Platform Guide

Knowledge Graph

Schema packs are versioned, executable ontology contracts. Extraction is candidate-first and evidence-gated. Assertions are bitemporal and reversible. Nothing is asserted without a receipt.

Schema packs — contracts, not diagrams

A schema pack defines the entity and relation types the graph will accept and is enforced at write time. The spec is docs/SCHEMA_PACK_SYSTEM.md — the single source for pack structure, forking, migration, and compliance. Packs are how the platform guarantees that what is true in the graph has the shape the ontology said it would have.

pack_id: warranty.v2
version: 2.0.0
ontology: BFO/CCO
classes:
  - name: WarrantyClaim
    parent: cco:Stasis
    attributes:
      - reserve_amount: Money
      - failure_mode: ControlledVocab
relations:
  - claim --[caused_by]--> failure_mode

• Versioned — warranty.v1 → warranty.v2 is a migration, not a rename. The pack version gates which facts are valid.
• Executable — the pack compiles to DB constraints and validation logic. A hand-authored diagram that drifts from the DB is impossible.
• BFO/CCO-aligned — packs aligned to Basic Formal Ontology and Common Core Ontologies ship for programs that require that conformance — see LACE-GOV.
• Authored by hand, via the Build-with-AI Pack Architect, or programmatically.

Candidate-first, evidence-gated extraction

Facts enter as candidates carrying a pointer to the source document span they came from (document, block, and char offsets). They become assertions only after the evidence gate accepts them, and after human review where configured. Model confidence alone is not enough to add a fact to the graph.

One run, one terminal state, and a cost cap that actually stops the run.

POST /v1/kg/extractions
{ "dataset_id": "0141b...", "schema_pack_id": "warranty.v2", "budget_cap": "small" }
# → 202 { id, status:"running" }
GET /v1/kg/extractions/{id}  # poll to succeeded | failed | cancelled (single-run law)
GET /v1/kg/entities?pack=warranty.v2&query=warranty+reserves
# → entities + assertions + evidence_span_ids[] + conflict_sets[]

• Single-run law — one active run per (dataset, pack). A second POST while one is running returns 409.
• 202 → poll — launch shape is POST /v1/kg/extractions → 202, then GET /v1/kg/extractions/{id} to succeeded | failed | cancelled (see .agents/skills/lace-extraction-workflow).
• Cost cap — budget_cap: small | medium | large bounds LLM spend. The run fails cleanly at the cap instead of silently degrading.
• Pipeline underneath — extraction is a pipeline with checkpoints and DLQ, so it resumes from the last completed step on crash or restart.

Inside the pipeline, the system proposes candidates and then checks each one for evidence. Without a span, there is no assertion. This candidate-first approach replaced the earlier guess-then-filter pass.

Reversible identity resolution

Duplicate entities merge, and the merge is reversible. Because contributing records keep their identity (and the merge itself is ledgered as a fact with evidence), an incorrect merge is undone rather than reconstructed by hand. This matters the first time two genuinely different people share a name. Identity resolution clusters mentions of the same real-world entity, and splitting restores prior versions. Gazetteer grounding pins canonical forms. Proofs are in the repo as gazetteer-grounding-*.png.

Bitemporal assertions — corrections supersede, not erase

Every assertion carries valid time (when the fact was true in the world) and transaction time (when the system recorded it). Corrections create a new assertion that supersedes the prior one. History stays addressable. Point-in-time queries return what the organization actually knew on a given date — the question audits and holds turn on. Conflicts — overlapping valid-time assertions on the same relation — surface as conflict sets (conflict_sets[] in the query response), not as a silent winner. A human or a merge policy resolves the set.

Knowledge panels and citations

Query via POST /v1/kg/query or from an agent's KnowledgeCapability. Every result carries assertion_id + evidence_span_ids[] + security_labels for ACL checks. The frontend renders knowledge panels per entity: canonical attributes, relations, timeline, and the source spans that support each fact. Every claim is traceable to the document block and char offset that justified it. The same evidence spans power enterprise search and RAG citations.

Walkthrough — warranty reserves

1. Curate a dataset (alpenglow-ops) from uploads or a live connector.
2. Author or fork a pack — warranty.v2 with WarrantyClaim and caused_by.
3. Run extraction at small cap, poll to succeeded, inspect candidates and evidence coverage.
4. Review conflict sets (for example, two reserve amounts for the same claim in overlapping periods) and accept, supersede, or split.
5. Query via POST /v1/kg/query or from an agent's KnowledgeCapability — every result carries assertion_id + evidence_span_ids.

Platform surface: Knowledge Graph · See also Enterprise Search (three-leg RRF over the same evidence).