OntoCast

Agentic ontology-assisted extraction of RDF knowledge graphs from documents.

OntoCast turns unstructured text into queryable RDF: it co-evolves domain ontologies and fact graphs in a parallel map/reduce pipeline, with RDF 1.2 provenance, entity disambiguation across chunks, and optional vector-backed ontology retrieval. Run it as a REST service, a batch CLI, or embed the pipeline in your own LangChain / LangGraph agent.

Documentation: growgraph.github.io/ontocast

---

Why OntoCast

Most extractors dump triples and leave ontology drift to you. OntoCast treats schema and instance data as one loop: per-chunk render → critic → merge, with GraphUpdate patches (insert/delete) instead of regenerating whole graphs, SHACL validation with LLM-free autofix, and a light install so you can embed the core without pulling Docling, gRPC, or ONNX.

---

Features

• Parallel ontology + facts loops — concurrent per-unit render/critic with configurable workers
• GraphUpdate patches — token-efficient insert/delete ops, not full-graph regeneration
• Entity disambiguation — embedding + symbolic alignment across chunks
• RDF 1.2 provenance — quoted triples / provenance artifacts; optional strip_provenance
• Ontology context — catalog selection, vector retrieval (LanceDB or Qdrant), or a fixed ontology
• Facts validation — invariants, SHACL, and machine repairs without an extra LLM pass
• Stores — in-memory pyoxigraph by default; Fuseki for persistence; tenancy by tenant/project
• LLM caching — disk cache, in-flight limits, optional read-only / batch pre-warm
• Embeddable — ontocast_tools, run_unit_pipeline, or a LangGraph node

---

Install

Pick at least one LLM provider extra. Add server for the CLI and HTTP API:

uv add "ontocast[server,openai]"
# or: pip install "ontocast[server,openai]"

Common add-ons: doc-processing (PDF/DOCX), semantic-chunking (clustering-based chunk boundaries; pulls torch, a multi-GB download — without it chunking falls back to paragraph/sentence splits), lancedb or qdrant (ontology retrieval), shacl (shape validation).

uv add "ontocast[server,openai,doc-processing,lancedb,shacl]"

Full extras table: Installation.

---

Quick start

cp .env.example .env
# Set LLM_API_KEY (and LLM_PROVIDER / LLM_MODEL_NAME as needed)

ontocast serve
curl -X POST http://localhost:8999/process -F "file=@document.pdf"

Batch without a server:

ontocast process --input-path ./document.pdf --head-chunks 5 --output-dir ./out

Omit FUSEKI_URI for in-memory pyoxigraph. Details: Quick Start.

Supplying Your Ontologies

OntoCast can guide extraction with seed ontologies (in Turtle .ttl format), and can build them for you when you have none. Provide yours in two ways:

1. Directory Seed: Set ONTOCAST_ONTOLOGY_DIRECTORY=/path/to/your/ontologies in your environment, or pass --ontology-dir /path/to/your/ontologies for a single run. All .ttl files in that folder sync automatically on startup.
2. API Upload: Register schemas dynamically with the running server:

   curl -X POST "http://localhost:8999/ontologies?tenant=ontocast&project=test" -F "file=@my_ontology.ttl"

---

Configuration

Start from .env.example.minimal — the few dozen variables that decide what a run does, out of the full surface in .env.example, grouped by the decision they belong to. Then pick a playbook for what you are actually doing: evaluating, building an ontology, populating facts, scaling to a large catalog, or serving it.

The knobs that change what the pipeline does — as opposed to where it stores things:

Variable	Default	What it controls
RENDER_MODE	ontology_and_facts	Which halves run. ontology writes no facts; facts skips the ontology block and extracts only against the catalog you already have
ONTOLOGY_CONTEXT_MODE	selected_single_ontology	Where each unit's schema comes from: LLM catalog selection, vector retrieval, or one pinned ontology
LLM_GRAPH_FORMAT	jsonld	Wire encoding the LLM emits graphs in; turtle is the legacy alternative
MAX_VISITS_PER_NODE	1	Retries of a failed render. The critic's budget is FACTS_CRITIC_PASSES
PARALLEL_WORKERS	16	Concurrent content-unit workers
LLM_PROVIDER / LLM_MODEL_NAME / LLM_API_KEY	openai	Provider selection and credentials
ONTOCAST_ONTOLOGY_DIRECTORY	—	Seed ontologies synced on startup (CLI: --ontology-dir; empty string means none)
FUSEKI_URI	—	Triple store; unset means in-memory pyoxigraph

RENDER_MODE, ONTOLOGY_CONTEXT_MODE and LLM_GRAPH_FORMAT are also per-request parameters on /process. Full surface, including chunking, retrieval and validation: Configuration.

---

Embed in your agent

from langchain.agents import create_agent
from ontocast import Config, ToolBox, ontocast_tools

tools = await ToolBox.acreate(Config.in_memory())
await tools.initialize()

agent = create_agent(
    model,
    tools=[*ontocast_tools(tools)],
    prompt="Edit the ontology from the user's text.",
)

Also: run_unit_pipeline for a single passage, or make_ontocast_node inside your own LangGraph — see Embedding OntoCast.

---

Workflow

1. Convert → chunk prepare (segment, tag, filter, size)
2. Parallel ontology render → normalize → consolidate → structural check → critic
3. Parallel facts render → merge / disambiguate → validate (invariants, SHACL, autofix)
4. Serialize to the triple store; return Turtle from the API

Workflow guide · landscape: graph.lr.png · per-unit: ontology_loop, facts_loop

---

Documentation

Everything lives at growgraph.github.io/ontocast:

Installation · Quick Start	Getting started
Core Concepts · Workflow · Configuration	How it works
API · Embedding · Tenancy	Integrate
Ontology Context · Validation / SHACL · Triple Stores	Operate
API Reference	Python API

Release notes: CHANGELOG.md

---

Contributing

See Contributing. Issues and discussion: GitHub.

License

Apache License 2.0 — see LICENSE.