OTO
inside the engine · from ARCHITECTURE.md at v0.6.1

The lifecycle, and the code behind each step

Ingestoto ingest: the inbox becomes a corpus of dated sources
→
Surveyoto survey: what the documents talk about
→
Interviewthe vocabulary, the question each class answers
→
Curatefour gates: recap, contradictions, diff, apply by name
→
Buildthe compiler: refused if undeclared
→
Serveexplorer for people, tools for agents
→
Publisha query store, Neo4j, a static site
The life of a project. The three steps in indigo need a person's judgment; the skills carry them.
  oto init ──► oto ingest ──► (declare, author) ──► oto build ──► oto query / oto serve
  scaffold      intake/        model/  curate/        validate/     serve/
                                                      compile/
                                                      targets/
                                                      builder.py
                     ▲                                                     │
                     └────── oto feedback ◄──── oto bench ◄────────────────┘
                             bench/feedback.py  bench/
Step Command Code What it does
Create oto init, oto ontology, oto ontology export scaffold.py, model/ontologies.py Writes the identity config, a vocabulary, an empty or sample graph, and the directory tree. Nothing else is copied: the engine stays installed. export turns a project's accepted vocabulary into an ontology for the next project.
Ingest oto ingest, oto ingest complete, oto figures, oto survey intake/ A run claims the inbox into processing/, and each file becomes one Document of typed blocks through a registered extractor, is rendered to Markdown, given figure descriptions, scanned for personal data, and only then written to the corpus. Failures go to errors/<run>/ with the reason beside them. complete moves a run's files to archive/ once the graph holds their facts. survey maps the corpus, and survey --doc briefs one document for whoever drafts its proposal: its terms, and which already resolve to entities.
Declare oto ontology, oto ontology import, oto ontology model/ The vocabulary lives in ontology.config.json. It arrives from an ontology (a versioned, composable unit: see Ontologies below) or several merged, from a file (the Turtle Oto emits, CSV, JSON), from the documents via the interview, or by interview alone; oto status lists the four when none is declared. This package diffs it against the last accepted version, counts what a change breaks, checks domain and range conformance, proposes honest widenings, and reports who confirmed each class.
Capture oto capture capture.py What someone said in conversation becomes a dated, attributed source document in the inbox, with the statements in the speaker's words, and enters through the same ingest, drafting and gates as a file. The graph then cites it and the speaker is who to ask.
Draft oto draft draft.py Optional, behind the draft extra: a model drafts one document's proposal from the drafting rules, the vocabulary, the brief and the whole document, constrained to the proposal's JSON schema, streamed, with Anthropic's refusal fallback on. The file records which model drafted it and is dry-run merged so a person reads the same report any proposal gets. The one model call in Oto; nothing else imports it.
Author oto curate, oto vet curate/ Edits go into a candidate graph. curate add merges proposal files (one per document) into it by rule: new ids added, repeated facts gain a source, changed facts refused; --dry-run reports the same without writing. diff says what promoting it changes and refuses an overwrite with no supersession record. apply appends to the ledger what changed and why. assertions gives a spoken correction a citable id. vet finds citations to documents the corpus no longer holds.
Build oto build, oto clean, oto verify validate/preflight.py, builder.py, compile/, targets/ Pre-flight checks the authored inputs. The builder renames the previous output aside and runs four stages; on failure it restores the previous build.
Serve oto query, oto serve serve/engine.py, serve/store.py, serve/http.py Answers fourteen kg_* tools over JSON-RPC 2.0 on stdio, over HTTP (--http, the same messages on POST /rpc, one GET route per tool, /api/graph as the whole graph as data, and a view mounted at /), or one query per CLI call, from one store interface with two implementations: the SQLite build loaded into memory, the file released so a rebuild can swap it; or a self-hosted Neo4j, the production backend, a live connection checked at startup. The same queries through both must give the same text, and a test proves it. kg_overview is the map for a question that starts from no entity; the store carries the recent ledger so it can say what changed without reading a file. A synthesis over it is the query-knowledge skill's job, labelled and cited; readings worth keeping live as authored theme notes under notes/themes/.
Measure oto bench, oto bench add, oto feedback bench/ Runs a gold question set through the graph engine, a lexical baseline and an optional dense baseline. add appends a document's questions with their provenance; a reader's complaint about an answer can be promoted into the set.

Every command is one module under cli/, named after the command. oto status reads the project and names the next step in this order, which is how the playbooks route.