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:

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:

Release notes: CHANGELOG.md

Contributing

See Contributing. Issues and discussion: GitHub.

License

Apache License 2.0 — see LICENSE.