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), 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 uses seed ontologies (in Turtle .ttl format) to guide extraction. Provide yours in two ways:

1. Directory Seed: Set ONTOCAST_ONTOLOGY_DIRECTORY=/path/to/your/ontologies in your .env. 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 — 47 variables instead of 202, 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	Render/critic retry budget. At 1 the LLM critic never runs
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
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.