The Problem
Organizations need a reproducible way to turn unstructured documents into a searchable knowledge graph that records why a fact was added. Existing tools either pull raw triples or rely on hard‑coded schemas, leaving provenance and evidence buried.
What This Does
ontosmith turns a flat, human‑approved ontology into a governed graph. The pipeline (pipeline/) proposes candidate triples, runs them through the Jev decision model (pipeline/decisions.py), and writes only the judged facts to Neo4j (pipeline/neo4j_store.py). A lightweight web UI (app/) and a REST API (api/server.py) expose the graph for search and programmatic access. Example packs in packs/ (e.g., legal-contract) show how domain‑specific ontologies are packaged and validated via packs/conformance.schema.json.
How It Is Wired
Entry Points
api/server.py– starts a Flask app; routes like/buildand/querycallpipeline.batch_cli.run_batch.pipeline/__main__.py– CLI entry; delegates topipeline.batch_cli.main.
What This Code Touches Outside Itself
- Neo4j database (
pipeline/neo4j_store.pyuses theneo4jdriver). - Pack metadata (
packs/*.json). - Vector index via Neo4j’s native vector capability (no external service).
What Each File Is Responsible For
pipeline/configure.py– loads YAML config, sets global constants.pipeline/attribute_values.py– extracts typed attributes from documents.pipeline/decisions.py– applies Jev model to candidate triples.pipeline/ontology_builder.py– orchestrates proposal → decision → write.pipeline/graph_store.py– generic graph mutation helpers.pipeline/export_graph.py– serialises the built graph for backup or inspection.
Internal Call Graph (simplified)
api/server.py
└─ route /build → pipeline.batch_cli.run_batch
└─ batch_cli.run_batch
├─ pipeline.configure.load
├─ pipeline.ontology_builder.build
│ ├─ attribute_values.extract
│ ├─ decisions.evaluate
│ └─ graph_store.write_triple (neo4j_store)
└─ export_graph.export
The path from HTTP request to Neo4j write has four hops, all within the pipeline/ package. The decision step is the widest blast radius: any change to decisions.evaluate propagates to all builds.
Cycles & Hub pipeline/graph_store.py imports neo4j_store and vice‑versa for transaction handling, creating a small cycle that centralises all database interactions. Modifying Neo4j logic therefore requires touching both modules.
How To Use It
Setup
git clone https://github.com/moses-y/ontosmith
cd ontosmith
pip install -e .
A Neo4j 5.x Community instance must be running locally (default port 7687).
Configuration
- Create
pipeline/config.yamlor set environment variablesNEO4J_URI,NEO4J_USER,NEO4J_PASSWORD. - Pack configuration lives in
packs/legal-contract/pack.jsonand relatedprofile/*.json.
Running the Pipeline
python -m pipeline --config pipeline/config.yaml
This invokes pipeline/__main__.py, which calls pipeline.batch_cli.main and triggers a full build.
Starting the API
python -m api.server
Access the UI at http://localhost:5000 and query via GET /query?text=....
Real‑World Use
A legal team can drop a set of contract PDFs into packs/legal-contract/corpus/, run the pipeline, and immediately query the graph for parties, obligations, and dates. The API can be consumed by a compliance dashboard that visualises evidence spans via the evidence property stored with each triple.
Code Health & Issues
- Low – Dependencies declared in
pyproject.tomlwithout a lockfile, risking non‑reproducible builds. - Low – No Dockerfile or CI build matrix for Windows, limiting quick deployment on non‑Linux hosts.
The repository contains a full test suite (tests/), a LICENSE file, and basic CI via GitHub Actions (.github/workflows/ci.yml). No major static‑analysis findings were reported.
The Bottom Line
ontosmith offers a clear, ontology‑first build pipeline that writes traceable facts into Neo4j. It is well‑structured for developers familiar with Python, Flask, and Neo4j, but requires manual Neo4j management and a Linux environment. Suitable for data‑centric teams that need strict provenance and are comfortable maintaining a graph database.