ontos

A subset of Enclave — the knowledge-graph layer of Enclave's sovereign AI company brain.

What Ontos is

Ontos is an in-VPC knowledge-graph runtime. It:

1. Extracts typed entities and typed relationships from an enterprise's data (documents, communications, systems of record).
2. Persists them as immutable, bitemporally-valid, provenance-tagged facts.
3. Serves them to LLM agents through a Model Context Protocol (MCP) interface, with permission-aware graph traversal.
4. Emits a compliance-grade audit record for every query.

Ontos is the "relationships" half of Enclave's company brain. Where the retrieval substrate answers what a document says, Ontos answers how things connect — who owns what, what depends on what, what changed when, and what the source-of-truth was on a given date.

Every fact carries provenance. Every query is audit-ready. Every deployment runs inside the customer's VPC.

Where Ontos sits in the Enclave family

Status

0.1.0 (first public release) — the runtime works end-to-end: ingest a directory of text files via ontos ingest, query it via ontos query "..." or the ask MCP tool, verify the audit chain via ontos audit verify. See CHANGELOG.md for what shipped in this release and docs/design/ for the per-milestone architecture notes.

Install

# From PyPI
pip install enclave-ontos

# Or via uv
uv add enclave-ontos

The PyPI distribution name is enclave-ontos; the import name stays ontos (same shape as pip install PyYAML → import yaml).

Container image on GHCR (multi-platform amd64):

docker pull ghcr.io/enclave-labs-inc/ontos:0.1.0
# or the moving tag
docker pull ghcr.io/enclave-labs-inc/ontos:latest

Quickstart

# From an installed release
ontos serve

# From a clone (dev)
uv sync --extra dev
uv run ontos serve

Then point any MCP-speaking client (Claude Code, Cursor, Codex, Gemini CLI) at the streamable-HTTP endpoint printed on start.

The CLI also ships ontos ingest <dir>, ontos query "<question>", and ontos audit verify — see CHANGELOG.md for what's in each release and RELEASING.md for the release process.

PDF ingest (0.3.0+)

ontos ingest reads .txt, .md, and .pdf files from a directory. PDFs route through LlamaCloud's hosted vision API via the [llama] extra:

pip install 'enclave-ontos[llama]'
export LLAMA_CLOUD_API_KEY=llx-...
ontos ingest \
    --source-dir ./corpus \
    --ontology ./starter.yaml \
    --pdf-backend llamaparse

Two backends ship:

• --pdf-backend pypdf (install [pdf]) — sovereign in-VPC parsing via local pypdf. Zero network calls. Works on PDFs with an embedded text layer (typical office / finance / legal filings). Pick this when sovereignty matters.
• --pdf-backend llamaparse (install [llama]) — BRIDGE, document bytes leave the customer VPC on their way to api.cloud.llamaindex.ai. Handles scanned / image-based PDFs via LlamaCloud's hosted vision API. Pick this only when the content actually needs vision — your pypdf run tells you so by failing with "PypdfConnector got zero characters from X. The PDF is likely image-based; use --pdf-backend llamaparse ...".

Pure .txt/.md ingest requires no flag and no extra.

Anthropic (Claude) backend

Ollama is the default, in-VPC LLM. To extract and plan with Claude instead:

pip install 'enclave-ontos[anthropic]'
export ANTHROPIC_API_KEY=sk-ant-...
ontos ingest --source-dir ./corpus --ontology ./starter.yaml --llm-backend anthropic
ontos query "Who works at Acme?" --ontology ./starter.yaml --llm-backend anthropic

--anthropic-model picks the model (default claude-opus-5). This is a BRIDGE backend: prompts and document text go to api.anthropic.com, so don't use it for in-VPC regulated deployments.

Ollama timeouts (0.3.0+)

First-time model loads can take 30–60s. If ontos ingest or ontos query times out, warm the model via ollama run <model> first, or raise the per-request timeout with --ollama-timeout 180 (or higher for long documents).

Storage selection and dev-store persistence (0.3.0+)

By default the CLI persists dev-store facts to ~/.ontos/dev-store.pkl, so ontos ingest ... followed by ontos query ... works out of the box without an external database. The existing --storage-path PATH and ONTOS_STORAGE_PATH options remain supported; pass --storage-path "" for ephemeral in-memory storage.

For an invocation-wide override, pass --storage before the subcommand:

# Ephemeral in-memory NetworkX store
ontos --storage networkx:// query "Who works at Acme?" --ontology ./starter.yaml

# Persisted NetworkX dev store
ontos --storage networkx:///tmp/scratch.pkl ingest --source-dir ./corpus --ontology ./starter.yaml

# Neo4j
ontos --storage neo4j://db.internal:7687/neo4j query "Who works at Acme?" --ontology ./starter.yaml

Supported storage URLs are:

• networkx:// — ephemeral in-memory dev store.
• networkx:///path/to/file.pkl — persisted NetworkX dev store.
• neo4j://host:port/database — Neo4j.
• neo4j+ssc://host:port/database and bolt+s://host:port/database — Neo4j TLS schemes.

CLI storage settings win over storage environment settings; values omitted from a Neo4j URL, such as the username or password, are filled from NEO4J_USER / NEO4J_PASSWORD. Credentials embedded in the URL are supported for compatibility but discouraged because URLs can leak through shell history or process listings. Prefer a dedicated password environment variable:

export ONTOS_NEO4J_PASSWORD='...'
ontos \
  --storage neo4j://neo4j@db.internal:7687/neo4j \
  --storage-password-env ONTOS_NEO4J_PASSWORD \
  query "Who works at Acme?" --ontology ./starter.yaml

--storage and command-level --storage-path are mutually exclusive. Production deployments may continue using ONTOS_STORAGE_BACKEND=neo4j plus the existing NEO4J_* environment variables; the CLI flag is an in-process override and does not mutate those environment settings. The NetworkX pickle remains Python-version-specific, single-process, and is not a wire format.

Snapshot MCP (0.5.0+)

Serve the MCP tool surface over a frozen graph export instead of the live store:

ontos serve --snapshot ~/snapshots/graph-2026-10-07.pkl --port 7788

Boots a read-only MCP server bound to the pickle. All existing read tools (search, traverse, explain, provenance, audit_lookup, ask) work unchanged; a new snapshot_info tool reports a content-hash id, the file's mtime, format, and the ontology stamp from #34 so orchestrators can disambiguate across sources. Mutually exclusive with --storage-path. Honors as_of, ACL filtering, and the Article-12 audit chain exactly as live-serve does — snapshot_info is itself audited, and intentionally reports no fact count or filesystem path.

Today's snapshot format is an ONTOS-NX-STORE-V2 Python pickle (.pkl / .pickle). The loader's magic-header check is a format check (rejects non-Ontos files), not a safety mitigation — a crafted pickle with the right prefix still runs on load, so only load snapshots from trusted sources. Text-based safe-to-load formats (JSON-LD, GraphML, Cypher) land with issue #32.

Design pillars

1. Every fact carries provenance — (source_id, extractor_version, confidence, t_valid, t_invalid) on every triple.
2. Every query carries an audit record — EU AI Act Article 12: ≥12 fields per AI-influenced decision, ≥6 mo retention, per-user attribution.
3. Permission-aware traversal at the executor — paths crossing forbidden nodes pruned during traversal, not after. Zero node-existence leakage.
4. Bitemporal correctness — as_of on every read; contradictions close old validity windows.
5. Planner/executor split — LLM writes typed plans over the ontology; deterministic executor runs multi-hop retrieval.
6. Sovereign by architecture — nothing leaves the customer VPC. Deployable air-gapped.

MCP tools (v0)

• search(query, as_of?, k?, agent_identity) — semantic + graph retrieval
• traverse(start, relation, depth, as_of?, agent_identity) — permission-aware multi-hop
• explain(entity_id, as_of?, agent_identity) — entity dossier with sources
• provenance(fact_id) — full provenance chain for one fact
• audit(query_id) — Article-12 audit record for a prior query
• as_of(query, timestamp, agent_identity) — historical query for regulatory review

Layout

ontos/
├── runtime/     # FastMCP server + tool surface
├── planner/     # NL → typed plan over ontology
├── executor/    # multi-hop + PPR + pruning + authz-aware traversal
├── extraction/  # LlamaIndex/LangChain wrappers today; migrates to enclave-scribe once Scribe passes benchmarks
├── ontology/    # LinkML / YAML schemas
├── storage/     # backend-agnostic (Neo4j / NetworkX / Neptune)
├── authz/       # OpenFGA / SpiceDB
├── audit/       # Article-12 audit emitter
└── ingest/      # source connectors

Contributing

Ontos is open-source and we actively want outside contributors. Start with:

• CONTRIBUTING.md — dev setup, coding standards, the non-negotiable invariants, and the PR process.
• CODE_OF_CONDUCT.md — Contributor Covenant v2.1.
• SECURITY.md — how to report a vulnerability (do not open a public issue for security bugs).
• GitHub Issues for bugs and feature proposals; GitHub Discussions for questions and design conversations.

License

Apache-2.0.