# OntoSmith

> An ontology-driven knowledge-graph builder: design the ontology first (schema, definitions, boundary examples — approved by a human, shipped as a versioned, hash-pinned pack), then build the graph under it with a pipeline that separates proposing from judging. Models propose candidates; deterministic gates and a fitted decision model (Jev, a pinned component) decide what is written. Every triple carries its evidence span and provenance; every operating point is adopted through a pre-registered measurement gate. The built graph lives in Neo4j — one store whose native vector index and full-text search power its serving: sentence-level evidence search by default through `ontosmith search` — a direct sentence index, the graph's evidence pool, and a beam traversal channel — hybrid retrieval (vector + lexical + graph) through a sample API and a minimal demo app, and the same retrieval for AI callers through an MCP server (`ontosmith mcp`, five read-only tools). MIT-licensed; the quality record — scores with scope, method, and failure anatomy, failures included — is published in the project whitepaper and is reproducible from the shipped adjudication appendix.
>
> Scope, stated plainly: the schema is a flat extraction contract — an inventory of entity and relation types with definitions and boundary examples, drafted or imported, approved by a human, judged per type by the decision model. A pack's declarations are where precision is enforced; the shipped open-domain pack additionally passes undeclared surface relations through as-is, folding only the surfaces it declares, so arbitrary text yields a graph while declared domains stay exact. Extraction runs in passes when the pack declares them: extra framing passes, and a residual pass that re-reads each excerpt against the facts already extracted and asks only for what is not yet covered — the shipped open-domain pack declares the residual pass. It is not a formal ontology: no class hierarchy, no inheritance, no logical axioms — OntoSmith is not an OWL ontology editor and runs no inference over the graph. The flatness is deliberate (per-type decisions are what make quality measurable); the job is turning a document corpus into a governed, evidence-carrying graph for search and agents.

## Product

- [README](README.md): what OntoSmith is, the no-key first steps, the six-step loop, the packs, and the command map
- [Whitepaper](docs/whitepaper.md): the long-form technical report and the canonical quality record (§5) — system, method, measured scores with intervals, failure anatomy, gate adoptions and rejections, cost accounting, limitations
- [Connections](docs/connections.md): the connection layer — seats, the reference profile (default preset), recommended models, the custom-binding contract, and `ontosmith configure`, the wizard (with its template twin) that declares bindings
- [Serving](docs/serving.md): the one graph in Neo4j, `ontosmith search`, the sample API, the demo app, and the MCP server
- [Hands-on guide](docs/hands-on.md): the whole loop in four tracks over your own documents — the quickstart build, the same build under an ontology domain pack, drafting your own pack with the ontology builder, and importing a public ontology (FIBO over CUAD) through the same builder gates
- [Hands-on appendix](docs/hands-on-appendix.md): the appendix track — reproduce the reference build: the flagship loop (profile → counted projection → gold audit → capped live run → corrected scoring) replayed against shipped artifacts and a fetched dataset subset
- [CLI reference](docs/cli-reference.md): every `ontosmith` command and its options, refreshed by hand from the live `--help` surface — the file says so in its own header
- [Pack design](docs/PACK_DESIGN.md): the pack-format contract — what a pack is, its files, and the rules it is loaded, versioned, and measured under
- [Adjudication contract](docs/ADJUDICATION.md): the standing specification for machine adjudication in the quality records, including the six seam rulings

## Quality records and evidence

- [Benchmarks index](benchmarks/README.md): the claim-level index — every published number with its scope, the harness that produces it, and its readout
- [Re-DocRED record (pointer)](benchmarks/redocred.md): the flagship build's scope, replay path, and the failure-anatomy data block the chart renderer parses
- [BioRED & CUAD records (pointer)](benchmarks/biored-cuad.md): the supporting records' scope and where their data lives (pack conformance entries CR-1…CR-7, CC-1…CC-4)
- [Adjudication appendix](benchmarks/appendix/README.md): the flagship record's samples, key files, and verdicts — machine judgments, labeled as such — plus the raw census scores; a replay recomputes every headline from these files alone
- [Reproduce](reproduce/README.md): every headline figure mapped to the command that recomputes it — or marked as record data when a figure is not reader-recomputable

## Examples

- [Examples index](examples/README.md): the walkthrough map — recorded reference artefact, demo corpus, and the replay/fetch demo tooling

## Project

- [Changelog](CHANGELOG.md): notable changes per release, Keep-a-Changelog format
- [Contributing](CONTRIBUTING.md): how to contribute, the test and lint gates, and the clean-room discipline
- [Security policy](SECURITY.md): how to report a vulnerability (GitHub private reporting)
- [Notice](NOTICE): third-party terms — Re-DocRED (MIT; Wikipedia-derived text under CC BY-SA), CUAD (CC BY 4.0, fetch-only), BioRED source terms, Project Gutenberg (public domain)
- [License](LICENSE): MIT — Copyright (c) 2026 Dongbum Lee