Setup

Getting started

Install the Agentic Ontologist, inspect an ontology, and query it directly from the terminal.

Install

git clone https://github.com/lamng3/agentic-ontologist.git
cd agentic-ontologist
./setup.sh
source .venv/bin/activate

For a smaller installation, select only the provider integrations you need:

uv venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[openai,knowledge-graph,dev]"

Configure

cp .env.example .env

Set one model provider and any retrieval services required by your workflow.

Inspect an ontology

agonto inspect data/my-ontology.owl
agonto inspect data/my-ontology.ttl --json

inspect parses local OWL, RDF/XML, Turtle, N-Triples, TriG, TriX, or JSON-LD without loading an embedding or language model.

Search locally

agonto search data/my-ontology.owl \
  "water quality measurement" --top-k 8

This builds the concept graph and returns the most relevant ontology concepts. The first run may download the configured text embedding model.

Ask questions

# One question
agonto query data/my-ontology.owl \
  "Which concepts describe freshwater temperature?"

# Interactive terminal session
agonto chat data/my-ontology.owl

The ontology is parsed and embedded once per command, before the first question. Interactive mode reuses that graph for every question in the session. Add --refine to apply relation refinement first. Answers are plain sentences. Add --log to print the detailed run, or type log after an answer.

For a local model, set LLM_MODEL=ollama:llama3.1. Hosted models require the corresponding API key. The Ollama client is installed with the Agentic Ontologist.

search, query, and chat save concept embeddings under results/memory and load them on the next run. Delete that store with agonto memory clear data/my-ontology.owl. Pass --no-save-memory to skip writing it. Answers are cached separately under results/cache. The architecture page describes the hot, short-term, and long-term tiers and how eviction keeps each one inside its cap.

Run the evaluation pipeline

agonto run --ontology envo sweet --top_k 10 --eval_alignment
agonto run --ontology envo sweet --eval_alignment --refine

Catalog-based evaluation output is written under results/runs/.

Select retrieval backends

from agentic_ontologist.retrieval import create_vector_index, create_web_search

web = create_web_search("mediawiki")
index = create_vector_index("torch-exact", dimension=768)

Use static or dataset for deterministic offline work. Register project-specific web, ANN, DiskANN, or vector-database adapters through the same public retrieval API.

Optional Jev context selection is separate from retrieval. Install it with uv sync --extra jev, set JEV_API_KEY, and enable AGONTO_CONTEXT_HARNESS=jev. It starts in shadow mode and fails open to the original shortlist.

Route models and gate tools

Model routing and tool-risk gating use the same Jev key. They stay off until enabled, and they do not change which evidence the context harness selects.

uv sync --extra jev
export JEV_API_KEY=your_typesafe_api_key
export AGONTO_MODEL_ROUTING=jev
export AGONTO_ROUTE_LOCAL=ollama:phi3
export AGONTO_ROUTE_CAREFUL=deepseek-ai/DeepSeek-R1-Distill-Llama-70B
export AGONTO_TOOL_GATE=jev

The query and redacted tool arguments are sent to TypeSafe. Routing stores name, model_name, probabilities, confidence, and fail_open on the trace and emits model.routed. A blocked call sets the tool_execute step to blocked and emits tool.blocked.

Verify

python -m pytest -q
pre-commit run --all-files