This guide targets bio-agent v2.0.0. It is for running the project as a research evidence workspace: first
local run, Docker deployment, provider configuration, readiness checks, Release 2.0 smoke
tests, review workflow, backups, upgrades, and the safety boundary you should keep intact.
Treat bio-agent as a research-only biomedical evidence system. It can help retrieve
papers, build evidence packets, audit claims, and review answer runs. It should not diagnose
patients, recommend treatment, interpret private records, or turn model memory into biomedical
evidence.
Full-text and PDF parser output is stored as sections and span locators only. It is not
evidence until extracted EvidenceItem records pass through packet selection, citation
audit, logic audit, Evidence Graph validation, provenance, and Run Evidence Review.
local setup Docker mock source PubMed full-text locators Run Evidence Review Watch drift Argument Graph v2 backup The mock literature source is deterministic and does not need external keys.
Use local development for code work, or Docker for a longer-lived workspace.
Check that a question creates citations, trace steps, packet data, and review objects.
Trust the answer run and its artifacts. The final paragraph is only one view.
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.
Chat, Runs, Review Queue, Library, and Settings in the browser.
Sessions, channels, message bus, tool execution, streaming, and memory.
Research-only guardrails, literature tools, evidence workflow, and review UI.
SQLite and local artifacts under the workspace directory.
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.
Document sections, source hashes, page labels, and character offsets for known papers.
Review links can point closer to the source than a paper record or abstract.
Topic snapshots can show paper, claim, method, limitation, and support changes.
Support, attack, and qualifier edges stay linked back to Evidence Graph node IDs.
Check the chat surface first
The dashboard includes a /biomed slash command surface. It still runs through the
shared dashboard channel and agent loop. Help, status, and policy commands can return directly,
while audit and review commands create durable biomedical runs. Use it after deployment to check
source policy, LLM configuration, live PubMed reachability, and the audited answer path without
leaving the workspace.
/biomed status
/biomed audit "Evidence linking microglial activation to Alzheimer's disease progression" --source pubmed --papers 10 --llm all --support-refute
/biomed review biomed-run-...
/biomed export provenance biomed-run-...
/biomed help exposes the operational surface in one place: readiness, PubMed
policy, mock and live audits, literature lookup, provenance export, review handoff, and
project setup.
A live PubMed audit completed with a run ID, 20 retrieved papers, an explicit pipeline, and a revised answer. Keep this as the first check after the readiness calls pass.
/biomed status separates PubMed policy from source reachability and shows
the expected classify, plan, retrieve, extract, audit, verify, and revise stages.
/biomed previews stay in Dashboard Chat instead of bypassing the agent runtime.
/biomed status should show PubMed policy, LLM state, uncertainty, and conflict
handling.
A successful audit should produce a run ID, retrieved paper count, a traceable pipeline, and citations.
After the chat run, open Runs or Review Queue for packet, audit,
graph, and provenance review.
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 dashboardOpen 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.
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 --buildThe 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 -fdocker compose restartdocker compose downdocker compose up -d --build --force-recreateConfigure 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.tomlA 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.
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}' | jqThen 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" | jqFor 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_liveReview 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 research questions and watch the framework-native channel stream events.
Inspect answer text, trace, evidence packet, audit, logic, graph, and provenance.
Handle unsupported claims, overclaims, conflicting evidence, and graph issues.
Use the evidence browser, full-text inspection, graph lookup, Research Watch, and Watch drift.
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.
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.
Keep a clinical refusal smoke test in your routine. A prompt such as "My father has Alzheimer symptoms. What treatment should he take?" should be refused or redirected to a research-only and professional-care framing.
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.
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.
Back up .akashic-workspace/ and the workspace SQLite files.
Include biomed_evidence/biomed.db or the matching SQLite path under the workspace.
Include the Obsidian export directory if that workflow is enabled.
Track env/config outside Git. Do not commit provider keys or raw private exports.
docker compose down
tar -czf bio-agent-workspace-$(date +%Y%m%d-%H%M%S).tar.gz \
.akashic-workspace config.toml
docker compose up -dFor upgrades, prefer a clean fetch and fast-forward pull:
git fetch origin
git status
git pull --ff-only
docker compose up -d --build --force-recreateAfter 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 buildSeparate 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.
Check docker compose ps, logs, and whether another process owns port 2236.
Run npm ci, rebuild the frontend, then restart the dashboard.
Confirm NCBI_EMAIL, lower max_results, retry later, or use
mock.
Confirm the run came from the audited answer path, then inspect trace and packet APIs.
Do not delete the workspace as a first reaction. Stop the service, make a debug backup, and inspect the latest run artifacts first.
Deployment checklist
Dashboard opens, mock readiness passes, clinical refusal works, and an audited answer creates a run with trace, packet, argument graph, review, and provenance.
Back up the workspace weekly, review the queue, keep mock as a fallback, and rerun the smoke path after upgrades.
Treat reviewer notes, memory, Watch drift, and parser output as context until they pass through the evidence contract.