Skip to content

OntoCast OntoCast logo

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

Python PyPI version PyPI Downloads License pre-commit DOI

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.

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]"

See Installation for the full extras table.

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 Guide.

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 — see Render Mode
ONTOLOGY_CONTEXT_MODE selected_single_ontology Where each unit's schema comes from: LLM catalog selection, vector retrieval, or one pinned ontology — see Ontology Context
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 System.

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

Workflow diagram

  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

Browse the complete documentation using the sidebar or start with these core guides:
Installation · Quick Start Getting started
Core Concepts · Workflow Guide · Configuration System How it works
API Endpoints · Embedding OntoCast · Tenancy Integrate
Ontology Context · Validation / SHACL · Triple Stores Operate
API Reference Python API

Release notes: CHANGELOG

Contributing

We welcome contributions! See the Contributing Guide for guidelines, and feel free to open issues or discussions on GitHub.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.