Deploying bio-agent for reproducible evidence review

Scope

Confirm the deployment target

bio-agent is a research-only biomedical evidence agent. The system is useful for paper search, evidence extraction, citation audit, logic audit, Research Watch, and Run Evidence Review. It is not a medical advice service.

In a long-running setup, think of it as five layers: the browser dashboard, the shared agent framework, the biomedical plugin, local storage, and optional external providers such as PubMed or an OpenAI-compatible LLM. The default demo path works without those providers because it uses mock literature data.

Release 2.0

Include the Release 2.0 review features

Release 2.0 includes deterministic full-text and PDF ingestion for known papers, span locators, Watch graph drift, Argument Graph v2, and a Library workspace for source inspection. Deployments should verify those paths along with the chat and answer endpoints.

Local development

Run it locally when you want to inspect or change code

Use local setup for development, debugging, demos, and evaluation. You need Python 3.12, Node.js, npm, and uv. jq is optional, but it makes the smoke checks easier to read.

git clone https://github.com/andyzpb/bio-agent.git
cd bio-agent
uv venv
uv pip install -r requirements.txt
uv pip install -r requirements-dev.txt
npm ci
uv run python main.py setup
uv run python main.py init
uv run python main.py dashboard

The documented command is uv run python main.py dashboard. If the project already has a populated .venv, use the interpreter directly:

.venv/bin/python main.py dashboard

# or, when your shell already points at the project venv:
python main.py dashboard

Open the dashboard at:

http://127.0.0.1:2236

Start with the Biomedical Evidence workspace and keep the literature source on mock. That path is deterministic, so it is better for the first successful run than live PubMed.

Docker deployment

Use Docker when you want a persistent workspace

Docker is the cleaner choice for a longer-lived local or server instance. It keeps the app runtime stable and mounts the workspace so runs, papers, review decisions, and watch topics survive restarts.

git clone https://github.com/andyzpb/bio-agent.git
cd bio-agent
cp config.example.toml config.toml
docker compose up -d --build

The service listens at:

http://127.0.0.1:2236

The mount to protect is .akashic-workspace. Treat that directory as production data. It contains the runtime workspace and the biomedical evidence database.

docker compose logs -f

docker compose restart

docker compose down

docker compose up -d --build --force-recreate

Configuration

Configure providers after the mock path works

You can run the deterministic demo without a real LLM key or a PubMed key. Add live providers only after the dashboard opens and the mock workflow passes.

Start from the example config:

cp config.example.toml config.toml

A typical LLM block looks like this:

[llm]
provider = "deepseek"

[llm.main]
model = "deepseek-v4-pro"
api_key = "${DEEPSEEK_API_KEY}"
base_url = "https://api.deepseek.com/v1"

Common environment variables:

export DEEPSEEK_API_KEY="..."
export NCBI_EMAIL="you@example.com"
export NCBI_API_KEY="optional_ncbi_key"

Keep real keys out of Git. PubMed can run without a key, but NCBI_EMAIL is recommended and NCBI_API_KEY can improve rate-limit behavior.

Keep the runtime default on deepseek-v4-pro. For release or live smoke runs, deepseek-v4-flash is a practical cheaper model when you only need to verify the path.

Verification

Run the smallest useful smoke test

A shallow health check is not enough. For this project, a useful smoke test proves that the literature source works and that an audited answer can produce a run, citations, trace steps, packet data, and provenance.

First check the mock literature source:

curl -s -X POST "http://127.0.0.1:2236/api/biomed/literature/check" \
  -H "Content-Type: application/json" \
  -d '{"query":"microglia Alzheimer disease","source":"mock","max_results":3}' | jq

Then run one audited answer:

curl -s -X POST "http://127.0.0.1:2236/api/biomed/answer/audited" \
  -H "Content-Type: application/json" \
  -d '{"question":"What recent evidence links microglial activation to Alzheimer disease progression?","source":"mock","max_papers":5,"execute_support_refute":true}' \
  | jq '{
      run_id:.answer_result.run_id,
      citations:(.answer_result.citations | length),
      trace_steps:(.trace | length)
    }'

Save the returned run_id and inspect the artifacts:

RUN_ID="<answer run id>"

curl -s "http://127.0.0.1:2236/api/biomed/answer-runs/$RUN_ID/trace" \
  | jq '{run_id, steps:[.trace[] | {step,status}]}'

curl -s "http://127.0.0.1:2236/api/biomed/answer-runs/$RUN_ID/evidence-packet" | jq

curl -s "http://127.0.0.1:2236/api/biomed/answer-runs/$RUN_ID/provenance" \
  | jq '{ok, graph:.result.graph_id, entities:(.result.entities|length), activities:(.result.activities|length)}'

Release 2.0 adds a few extra endpoints worth checking when you are validating the full workspace. Set PAPER_ID and WATCH_ID from records created in the dashboard or API before running the full-text and drift calls.

curl -s "http://127.0.0.1:2236/api/biomed/answer-runs/$RUN_ID/argument-graph" | jq

curl -s -X POST "http://127.0.0.1:2236/api/biomed/papers/$PAPER_ID/full-text" \
  -H "Content-Type: application/json" \
  -d '{"source":"mock","content_type":"text/plain","content":"## Results\n...","overwrite":true}' | jq

curl -s "http://127.0.0.1:2236/api/biomed/watch/$WATCH_ID/drift" | jq

For a live PubMed release smoke, use a longer timeout. A 90 second run can fail while the stack is still healthy; 300 seconds gives the planner, retrieval, audit, and review path enough room.

.venv/bin/python -m eval.biomed_evidence.run_release_smoke \
  --source pubmed \
  --deepseek-model deepseek-v4-flash \
  --allow-planner-fallback \
  --timeout-seconds 300 \
  --output-dir /tmp/biomed_release_smoke_live

Daily operation

Review the run before you trust the answer

The dashboard is organized around a reviewer workflow. Chat is useful for starting and explaining work. For inspection, use Runs.

Ask one practical question during review: can every biomedical claim in this answer be traced back to retrieved papers, evidence spans, packet selection, and audit records? If the answer reads well but the trace is weak, trust the trace.

Safety boundary

Keep clinical requests out of the workflow

A deployed instance should refuse patient-specific diagnosis, treatment advice, dosage advice, prognosis, and private medical-record interpretation before retrieval, synthesis, export, or provenance work starts.

Evidence boundaries matter just as much. Project memory, reviewer notes, model drafts, Watch drift, Argument Graph advisory edges, and raw full-text parser output can guide review. They do not support biomedical claims unless they become evidence records and pass through the packet, audit, graph, provenance, and review path.

Backup and upgrade

Back up the workspace before you change the runtime

The main data directory is .akashic-workspace. Back it up with config.toml and any deployment-level environment variable records you keep outside Git.

docker compose down
tar -czf bio-agent-workspace-$(date +%Y%m%d-%H%M%S).tar.gz \
  .akashic-workspace config.toml
docker compose up -d

For upgrades, prefer a clean fetch and fast-forward pull:

git fetch origin
git status
git pull --ff-only
docker compose up -d --build --force-recreate

After any upgrade, rerun mock readiness, one audited answer, the latest run review, and the clinical refusal smoke. Developers should also run type checks, tests, eval, and the frontend build before using the deployment for release work.

.venv/bin/pyright --level error
.venv/bin/pyright --project pyrightconfig.tests.json --level error
.venv/bin/pytest -q tests/
.venv/bin/python -m eval.biomed_evidence.run_eval \
  --output /tmp/biomed_eval_release_2_0.json
npm run typecheck
npm run build

Troubleshooting

Separate app failures from provider failures

If the dashboard does not open, start with the process and logs. If PubMed looks unstable, run readiness first and then fall back to mock before blaming the evidence workflow.

Do not delete the workspace as a first reaction. Stop the service, make a debug backup, and inspect the latest run artifacts first.