OTO
concepts · written for the site

From a document to the graph

The documentextracted to Markdown by oto ingest; no model
→
The reader: an agentreads it and writes the proposal: facts, classes, relations, the sentence for each; the agent's own model
→
The gatesmerge, check, apply by name: the vocabulary, the evidence, the supersession record; no model
→
The graph, compiledoto build into the store; every fact cites the document; no model
Only the reader interprets the text. For a real corpus the reader is an agent, and the engine gates what it proposes.

A document never enters the graph as text. Its facts do, one proposal at a time, and the document stays behind them as the thing they cite. Four steps, and only one of them interprets the text.

1. Ingest: the document becomes the corpus

oto ingest

claims the file, records its hash, and writes its text as build/documents/<slug>.md. Headings, tables and figures survive. The privacy scan blocks personal data. No model is involved: this is extraction, and it is reproducible.

2. A reader writes the proposal. This is the agent's job.

Someone reads the Markdown and writes proposals/<slug>.json: for each fact, an id, a class from the vocabulary, a summary in the document's words, and the sentence it came from as evidence, plus the relations between them.

For a real corpus, that reader is an agent. In Claude Code, the build-knowledge-base skill has the agent read each document, interview you about the vocabulary, write one proposal per document, and stop at the gates. The agent brings its own model. oto draft <slug> does the same for one document with a model the engine calls. A person does it by hand for a small corpus or a correction; the complete tutorial shows what the agent produces.

The engine never does this step. It does not read text for meaning and it does not invent a fact. Every fact in the graph was proposed by a named reader, with the sentence.

3. The gates turn the proposal into graph rows

oto curate add

merges the proposal into the candidate graph, filling status, as_of and sources from the proposal. A node that already exists with the same facts gains the document as a source. A node that exists with a different summary is refused: that is a supersession. oto curate check refuses a class or relation the vocabulary does not declare, a fact without evidence, an unrecorded overwrite, and personal data. oto curate apply --by promotes the candidate and writes the ledger.

The agent's proposal and a person's proposal pass the same gates. A model's mistake is caught the same way as a typo.

4. The build compiles the graph into the store

oto build

runs the compile stages on graph.json: the normalised graph, the derived facts, the ontology check, one retrieval card per node, and the SQLite store with every document's passages indexed. Neo4j and the static site are the same inputs loaded elsewhere. Only now does oto ingest complete archive the file, because the graph holds its facts.

What the query gives back

entity "Total loss settlement"

reads the node from the store. Its Sources line names the document by slug and its Evidence line quotes the sentence, so a reader can open the Markdown and check. The document is still on disk; a new version of it announces which facts need re-attestation.

So where is the model?

Step Who does it Model
ingest, survey the engine none
the proposal an agent following the build skill, oto draft, or a person the agent's own, or the one draft calls
the gates, apply, build the engine none
a query, a served tool the engine none
a question in your own words an agent using the tools the agent's own