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¶

# 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 support is 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 the BIOT_KG_ID-selected graph — not yet wired to the served-KG selection (follow-up).
molecule-discovery is a placeholder.
panel tiers 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.