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 /build and /query call pipeline.batch_cli.run_batch.
  • pipeline/__main__.py – CLI entry; delegates to pipeline.batch_cli.main.

What This Code Touches Outside Itself

  • Neo4j database (pipeline/neo4j_store.py uses the neo4j driver).
  • 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.yaml or set environment variables NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD.
  • Pack configuration lives in packs/legal-contract/pack.json and related profile/*.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.toml without 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.