Using the biot CLI with the Graffold KG¶
The biot CLI is the supported interface to the Graffold knowledge graph: a
composable command-line tool where each command is a discovery step, and any
command that consults the KG does so through a stable API (/v1/atlas/*) served
over Graffold's Parquet knowledge graphs. The KG backend is swappable without
changing any command.
1. Serve a knowledge graph¶
Choose where the KG runs (one protocol, three backends)¶
Every consumer (the biot CLI, the query agent) talks to the KG through one
GraphBackend protocol, so the same commands work regardless of where the
graph physically runs — you pick the backend:
| Backend | What it is | Who runs it |
|---|---|---|
duckdb |
local Parquet, query-only | you (self-host) |
falkordb |
local Docker / self-hosted graph | you (self-host) |
remote |
the hosted graffold KG over /v1/kg/* |
the paid remote |
Select it with get_backend("remote", kg_id="etec") (or GRAPH_BACKEND=remote).
The remote backend is read-only — it satisfies query_entities /
get_neighbors / health_check; ingest always goes through the ingest API
(graffold-ingest deploy), never a backend write. So a customer can self-host
duckdb/falkordb, or query the hosted box, without changing a line of consumer
code.
Run the serving API¶
# serves KGs under ~/.graffold/parquet/<kg_id>/
ATLAS_DEFAULT_KG=<kg_id> uv run uvicorn biot_api.main:app --port 8000
# override the parquet root with PARQUET_DIR=<path> if needed
2. Point the CLI at the KG (env contract)¶
export BIOT_KG_URL=http://localhost:8000 # the served API
export BIOT_KG_ID=<kg_id> # which graph to query
# optional: BIOT_KG_ENABLED=false to no-op the KG; BIOT_KG_TIMEOUT=30
KG calls degrade gracefully: if the API is unreachable or disabled, commands proceed ungrounded rather than failing.
3. Pick an LLM (for the reasoning steps)¶
--service on any LLM-using command. Supported: bedrock (AWS, model-agnostic
Converse — e.g. --model-id deepseek.v3.2), anthropic, openai,
openrouter, ollama, bedrock-llama, claude-code. Bedrock uses the
machine's AWS session (SSO) — no API key in the CLI.
4. The workflow¶
biot intake brief "<free-form problem/TPP>" --problem-id <id> \
--service bedrock --model-id deepseek.v3.2 -o brief.md
# free-form input -> validated brief.md (schema-checked)
biot pathfinder map brief.md --kg --service bedrock -o disease-map.md
# brief -> disease map; --kg grounds it in prior KG knowledge
biot target-identification propose disease-map.md --disease "<name>" \
--kg --service bedrock -o targets.md
# candidates ranked by KG grounding: VALIDATED / REJECTED(killed) /
# NOVEL, and each flagged if CONTESTED (KG holds opposing claims)
biot target-identification check "TargetA,TargetB" --kg
# quick per-target KG verdict lookup (validated/rejected/novel)
biot panel review <any-doc> --tier <local|single|frontier>
# adversarial multi-model review; exits 1 if no usable critique
biot knowledge-graph {ingest|query|search|neighbors|stats}
# build/query the KG directly (see Known limits)
5. What the KG adds (measured, honest)¶
- Reliability — deterministic verdicts: the model flips validated/killed ~25% across identical queries; the KG returns the same verdict every time.
- Speed / cost — grounded lookup ~1.8× faster and ~5.7× fewer tokens than live literature research (paid once at ingestion, reused per query).
- Traceability — per-edge provenance (
evidence_ref). - Contradiction detection (the differentiator) — surfaces targets the KG
holds opposing claims about (e.g. ACTIVATES vs INHIBITS across papers) with
per-side source counts — a contested-claim risk flag the model can't
reproduce. Exposed at
/v1/kg/contradictions. - Corroboration —
≥2-source supportis a proven non-random, predictive proxy (5–11% per corpus, higher on topically-coherent sources) — a ranking/confidence signal, not a standalone correctness score.
See the KG Value Study for the measured evidence and the Source Comparison Study for the per-source corroboration numbers.
6. Known limits (honest)¶
- Contradiction/corroboration volume scales with corpus richness (full-text > abstracts).
- Free-text target names may not join to KG entity IDs without a normalization layer; the KG-native flow (query what the KG knows for the disease) is the robust path today.
biot knowledge-graph {stats,search}read Graffold's default parquet dir, not theBIOT_KG_ID-selected graph — not yet wired to the served-KG selection (follow-up).molecule-discoveryis a placeholder.paneltiers are ollama/openrouter only (no bedrock tier yet).
Legacy: Atlas pipeline¶
The Atlas pipeline consumed the KG via the same /v1/atlas/* endpoints and
remains a valid caller, but the biot CLI above is the supported interface. The
Atlas integration and benchmark pages are preserved for history under
Integration → Legacy and Ingestion & Enrichment; they are not the
primary path.