Skip to content

Embedding OntoCast in your agent

OntoCast is a library as well as a server. This page shows how to call the extraction pipeline, the ontology tools and the triple store from your own LangChain agent or LangGraph workflow.

There are three ways in, in increasing order of how much of OntoCast you take on:

You want to Use
Give an agent tools to read and edit ontologies ontocast_tools
Extract from one passage of text run_unit_pipeline
Run the whole document pipeline inside your graph make_ontocast_node

Install the core with one LLM provider extra, for example pip install "ontocast[openai,documents]". The documents extra is needed by everything that extracts, including run_unit_pipeline; Installation lists the others.

Construct a ToolBox

ToolBox owns every stateful tool: the LLM client, the triple store, the ontology catalog and the vector store. Build it once, at startup, and reuse it:

from ontocast import Config, ToolBox

async with await ToolBox.acreate(Config.in_memory()) as tools:
    await tools.initialize()
    ...
# Backend connections (Fuseki, Qdrant) are closed here.

Use ToolBox.acreate, not ToolBox(config), from async code: the plain constructor sets up the LLM provider through asyncio.run, which fails inside a running event loop. initialize() loads the ontology catalog and the SHACL shapes. Without async with, call await tools.aclose() when you are done.

Config.in_memory() uses the in-memory triple store, a full SPARQL engine, and turns vector retrieval off, so nothing external is needed. Every other setting still comes from the environment. For a deployment, build Config() and point it at Fuseki; see Triple stores.

Tools for any agent

ontocast_tools(tools) returns LangChain tools any agent can call:

from langchain.agents import create_agent
from ontocast import ontocast_tools

agent = create_agent(model, tools=ontocast_tools(tools))
Tool Offered Does
ontocast_list_ontologies by default List every ontology with its IRI, title and version
ontocast_get_ontology by default Fetch one ontology as Turtle
ontocast_search_ontology_terms by default, with a vector store Find classes and properties by meaning
ontocast_retrieve_ontology_context by default, with a vector store Retrieve the part of the ontology relevant to a text
ontocast_sparql_select by default Read-only SELECT or ASK, returned as JSON rows
ontocast_sparql_construct by default Read-only CONSTRUCT or DESCRIBE, returned as Turtle
ontocast_chunk_text by default, with documents Split a document into parts
ontocast_extract by default, with documents Run extraction over a passage, as one part
ontocast_apply_graph_update mutating=True Apply an insert/delete patch
ontocast_ingest_ontology_ttl mutating=True Register a new ontology
ontocast_delete_ontology mutating=True Delete an ontology from the triple store and the vector store
ontocast_convert_document named in include Convert a file on the host to text
ontocast_align_entities named in include Match equivalent entities across graphs

Every tool is a coroutine: agents must call ainvoke, and invoke raises NotImplementedError.

Tools whose backend is missing are left out

A tool whose backend is missing is not returned at all, because an agent handed a tool that always fails keeps retrying it. The list you get therefore depends on your install and configuration. To see why a tool is missing:

from ontocast import ontocast_tool_diagnostics

for name, reason in ontocast_tool_diagnostics(tools).items():
    print(f"{name}: {reason}")
ontocast_search_ontology_terms: no vector store is configured (set QDRANT_URI or LANCEDB_ENABLED)
ontocast_chunk_text: requires docling-core; install with pip install "ontocast[documents]"

ontocast_tool_names(tools) returns the names ontocast_tools would build, without building them.

Choosing tools

ontocast_tools(tools, include=["ontocast_sparql_select", "ontocast_get_ontology"])
ontocast_tools(tools, exclude=["ontocast_extract"])
ontocast_tools(tools, mutating=True, max_chars=50_000)

The write tools need mutating=True because each changes stored state for good: ontocast_delete_ontology drops every stored version of an ontology and its vectors, from one IRI the model chose. It leaves your seed directory alone, so an ontology that is still there returns at the next start. The SPARQL tools refuse INSERT, DELETE, DROP, CLEAR and the other update keywords; writes go through ontocast_apply_graph_update, which parses the patch and, with ONTOLOGY_MAX_TRIPLES set, refuses one that would grow the graph past it.

max_chars bounds each tool's result. A result cut to fit is marked as cut, so the model does not read truncated Turtle as a complete graph.

The two search tools need a vector store, and Config.in_memory() has none. Without one, each part is shown one ontology from the catalog, which is a complete extraction path; vector retrieval exists to combine terms from several ontologies. To add the embedded LanceDB store (lancedb extra) to an in-memory configuration:

from ontocast.onto.enum import OntologyContextMode

config = Config.in_memory()
config.tool_config.lancedb.enabled = True
# Embed through the API, no local model.
config.tool_config.embedding.provider = "openai"
config.tool_config.embedding.model_name = "text-embedding-3-small"
config.tool_config.embedding.dimension = 1536
config.server.ontology_context_mode = (
    OntologyContextMode.SELECTED_VECTOR_SEARCH_ONTOLOGY
)

tools = await ToolBox.acreate(config)
await tools.initialize()

initialize() builds the index when the configured mode, or the ontology_context_mode passed to it, is vector retrieval; for extraction, set the same mode on the AgentState (ontology_context_mode). For a Qdrant server, install the qdrant extra and set QDRANT_URI. The default embedding provider runs a local model and needs sentence-transformers (in doc-processing). Choosing ontology context explains the trade-offs.

Extract from one passage

run_unit_pipeline is the lightest way to run extraction: a plain coroutine, pydantic in and out, with no LangGraph graph and so no recursion limit to set. Each loop inside it is bounded by the critic and retry budgets.

from ontocast import AgentState, InputDocument, run_unit_pipeline
from ontocast.onto.enum import RenderMode

state = AgentState(
    input_document=InputDocument(filename="note.txt", data=text.encode()),
    render_mode=RenderMode.ONTOLOGY_AND_FACTS,
    facts_user_instruction="Extract every measurement with its unit.",
)
ontology_result, facts_result = await run_unit_pipeline(state, tools)

It treats the whole input as one part (content unit). It skips chunking, section tagging, bibliography routing, summarization, ontology normalization, entity disambiguation and the validation gate, and ignores max_chunks, target_sections and summarize_sections. For a whole document, use the graph.

The pipeline as a LangGraph node

The pipeline's state type has no reducer channels and every node returns the whole state, so you cannot add the compiled graph to your StateGraph directly unless your state has the same keys. make_ontocast_node maps between the two states explicitly:

from langgraph.graph import StateGraph
from ontocast import make_ontocast_node, text_in_turtle_out

to_state, from_state = text_in_turtle_out()

builder = StateGraph(MyState)
builder.add_node(
    "extract",
    make_ontocast_node(tools, to_agent_state=to_state, from_agent_state=from_state),
)

text_in_turtle_out() reads a string from your state's input key and writes back ontology_ttl and facts_ttl; pass text_key, ontology_key and facts_key to use your own names, or write the two mapping functions yourself.

The document graph runs the same number of steps for any document, because parts are processed inside its nodes rather than as graph steps. The node runs it under its own recursion limit, or the recursion_limit you pass; a recursion_limit set in your RunnableConfig takes precedence over both.

The node compiles the graph once, when you create it, and merges your RunnableConfig into its own, so callbacks and tracing metadata reach the inner run.

Building the graph yourself

from ontocast import build_agent_graph, create_agent_graph

compiled = create_agent_graph(tools, checkpointer=saver, name="ontocast")
builder = build_agent_graph(tools)  # uncompiled, to add your own nodes

create_agent_graph takes optional checkpointer, store and name. Set name when you embed the graph as a subgraph; otherwise it appears as LangGraph in traces.

Limit a run's tokens

A RunMeter counts tokens while a run is in progress, across all of its content units, and stops the run at a limit. Bind it around the run:

from ontocast import BudgetExceededError, RunMeter, use_run_meter

meter = RunMeter(
    token_caps={"input": 400_000, "output": 60_000},
    on_usage=report_progress,  # receives meter.snapshot()
    min_interval_s=5.0,
)
try:
    with use_run_meter(meter):
        async for chunk in workflow.astream(state, stream_mode="values"):
            final = chunk
except BudgetExceededError as exc:
    report_usage(exc.snapshot)
else:
    report_usage(meter.snapshot())
  • Usage is kept per model as TokenTotals. input, cache_read, cache_write, output and reasoning count provider calls, as the provider reports them: cache_read and cache_write are included in input, and reasoning in output. replayed_input and replayed_output count answers replayed from the LLM response cache, for which no provider call is made.
  • token_caps limits counts summed over models, keyed by field name.
  • limit is your own policy: a function given a copy of the counts per model before each provider call, returning a reason to stop or None. The meter holds no prices; a caller that budgets in money prices the counts here:
def within_budget(usage):
    spent = sum(price(model, totals) for model, totals in usage.items())
    return f"spent {spent:.2f}" if spent >= budget else None


meter = RunMeter(limit=within_budget)
  • The limit is checked before each provider call. Once a cap is reached or limit returns a reason, the next call is not sent, and the run raises BudgetExceededError with the meter's snapshot once its parallel units have finished. Calls already in flight complete and are recorded, so the final usage can go over the limit by what those calls used.
  • on_usage is called with a snapshot at most once every min_interval_s seconds, and once more when the use_run_meter block exits.

When no meter is bound, ontocast process, the /process and /process_unit routes, and make_ontocast_node apply MAX_INPUT_TOKENS_PER_DOCUMENT and MAX_OUTPUT_TOKENS_PER_DOCUMENT to each document. On the routes, that document's result is a 422 with error_code budget_exceeded; ontocast process records the document as failed and goes on to the next one. A meter you bind yourself replaces these settings.

Several tenants in one process

A ToolBox serves one partition of the stores. To serve another:

scoped = await tools.for_scope("acme", "reports")

Each scope has its own triple store connection, ontology catalog and vector store, over its own copy of the configuration, so scopes cannot see each other's data. The LLM client and its cache, the converter, the chunker and the embedding model are shared. At most MAX_TENANCY_SCOPES scopes stay open; the least recently used is closed first. await tools.aclose() closes them all. Tenancy explains how partitions are named.