Skip to content

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 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.