API reference

agentic_ontologist.workspace

OntologyWorkspace

High-level interface for loading one local ontology, retrieving concepts, and asking ontology-grounded questions.

OntologyWorkspace(
    path: str | Path,
    *,
    format: str | None = None,
    refine: bool = False,
)

from agentic_ontologist.workspace import OntologyWorkspace

workspace = OntologyWorkspace("ontology.owl", refine=True)
matches = workspace.search("freshwater temperature", top_k=8)
answer = workspace.ask("Which concepts describe freshwater temperature?")

After the exact question hash misses, a checksum of three-word shingles on each remembered answer can name the last concept on that path and skip retrieval. The overlap must be at least 0.75 and lead the next answer by 0.15. A single misspelled word can still match. A question with fewer than 4 shingles continues into the Harness. signature.py

OWL/RDF pathNatural languageCached graph View source →

agentic_ontologist.parser

Parser

Format-selecting facade over RDF, JSON, and relation-text adapters.

Parser(
    filepath: str | Path,
    config_path: str | Path | None = None,
    name: str | None = None,
    version: str | None = None,
    *,
    config: ParserConfig | None = None,
    format: str | InputFormat | None = None,
)

from agentic_ontologist.parser import Parser

ontology = Parser("domain.ttl", name="domain", version="1.0").to_ontology()
triples = Parser("domain.owl").extract_triples()

Parser source → Format definitions →

agentic_ontologist.algorithms.graph

Graph data model

from agentic_ontologist.algorithms.graph import ConceptGraph
from agentic_ontologist.parser import Parser

ontology = Parser("domain.owl").to_ontology()
graph = ConceptGraph(nodes=[], edges=[])
graph.build_from_ontology(ontology)
graph.compute_all_embeddings(alpha=0.5)
neighbors = graph.nearest_nodes("material fatigue", k=10)

agentic_ontologist.algorithms.refinement

Ontology refinement

from agentic_ontologist.algorithms.refinement import (
    GraphUpdate,
    OfflineGraphRefiner,
    OnlineOntologyRefiner,
)

offline = OfflineGraphRefiner(concept_similar=my_semantic_predicate)
collapsed = offline.refine(graph)

online = OnlineOntologyRefiner(
    concept_similar=my_semantic_predicate,
    confidence_threshold=8.5,
)
result = online.refine(collapsed, [GraphUpdate(source, target, confidence=9.2)])
print(result.applied_updates, result.deferred_updates)

agentic_ontologist.embeddings

Embeddings and vector indexes

Built in: torch-exact. ANN, DiskANN, and vector-database backends are supported as adapters but are not bundled implementations.

from agentic_ontologist.retrieval import create_vector_index, register_vector_index

index = create_vector_index("torch-exact", dimension=768)
index.add(ids, vectors, metadata)
results = index.search(query_vector, k=10)

agentic_ontologist.retrieval

Retrieval providers

from agentic_ontologist.retrieval import (
    create_web_search,
    describe_web_search,
    register_web_search,
)

provider = create_web_search("mediawiki", lang="en", project="wikipedia")
print(describe_web_search("mediawiki"))
count = provider.search_count("ontology matching")

Retrieval source → Plugin example →

Harness

One small model answers typed questions about the current question and the last few turns of this chat. The call is SGLang POST /v1/systemone at http://127.0.0.1:30000 (AGONTO_HARNESS_URL). An empty value keeps the Ollama router, ollama:phi3. A local policy reads those answers and chooses replay or retrieve. The choice list stays at 26 options, including retrieve. The reasoner is the only model that writes the answer, and it stays the chat model.

Replay happens when the choice names a cached question, or when same-intent is at least 0.8, the score is “Same question,” and one cached question is the nearest choice. A failed call falls open to retrieve. A follow-up hangs under the previous question when the continuation probability is at least 0.8. A new topic hangs from a virtual root. Under each question the trie records the route, the ontology concept ids, and the answer. That trie is this chat only. The answer cache stays the memory shared across chats.

Jev model routing (AGONTO_MODEL_ROUTING=jev) and the Jev context harness (AGONTO_CONTEXT_HARNESS=jev) stay optional extras. They are separate from this call.

Context harness

Retrieval remains responsible for recall. The harness decides which retrieved concepts, neighbors, and web passages enter the prompt.

from agentic_ontologist.retrieval import JevContextHarness

harness = JevContextHarness(shadow=True, min_relevance=0.2)
answer = workspace.ask(question, harness=harness)
print(workspace.last_context_selection.metrics())

Jev is optional: uv sync --extra jev and JEV_API_KEY. Query text, concept labels, and web snippets are sent to TypeSafe. If the key is missing or Jev fails, the harness fails open and returns the original shortlist.

agentic_ontologist.agents

Agent runtime

from agentic_ontologist.agents import Agent, JevModelRouter, ToolRiskGate

agent = Agent(
    llm,
    model_router=JevModelRouter(),
    tool_gate=ToolRiskGate(threshold=0.5),
    save_local=True,
)
response = agent.invoke("Find the closest ontology concept.")
run = agent.invoke("Explain the match.", return_trace=True)

Model routing

create_model_router() returns a router when AGONTO_MODEL_ROUTING=jev. It asks one choice question, then Agent.invoke uses the selected model for that run.

The model_route step and the llm_invoke step store name, model_name, probabilities, confidence, fail_open, and error. The same payload is emitted as model.routed for Ontology-of-Thought. If Jev is unavailable, the run fails open to the current model.

Tool-risk gating

create_tool_gate() returns a gate when AGONTO_TOOL_GATE=jev. It runs after tool.parsed and before tool execution. The default gated tools are search_term_context and search_knowledge_graph. Override them with AGONTO_GATED_TOOLS. ontology_term_info is not gated.

Jev returns the probability that the call is unsafe. A value at or above AGONTO_TOOL_RISK_THRESHOLD (default 0.5) becomes the tool result:

{"blocked": true, "tool_name": "search_term_context", "reason": "...", "risk": 0.92}

The tool function is not called. The tool_execute step status is blocked, and Ontology-of-Thought receives tool.blocked. Arguments are passed through redact before the request. Query text and those redacted arguments are still sent to TypeSafe. When the gate is enabled and Jev cannot decide, that gated call fails closed. A disabled gate leaves every tool call unchanged.

agentic_ontologist.validation

Validation

agentic_ontologist.prompting

Prompt construction

OntologyEquivalencePromptBuilder(
    config: PromptConfig | None = None,
).build(source: object, target: object) -> str

from agentic_ontologist.prompting import (
    OntologyEquivalencePromptBuilder,
    parse_equivalence_answer,
)

prompt = OntologyEquivalencePromptBuilder().build(source, target)
decision = parse_equivalence_answer(model.invoke(prompt).content)

View source →

agentic_ontologist.uq

Uncertainty quantification

from agentic_ontologist.uq import AgreementConfidenceScorer

scorer = AgreementConfidenceScorer(llm=llm, num_responses=5)
answer, confidence, scores = scorer.score_prompt(prompt)

View source →