monarch-initiative/ontogpt

1. What this repository is

OntoGPT is a Python package for turning unstructured biomedical text into structured, ontology-grounded outputs using LLMs. The core product is a command-line extraction pipeline, with a small supporting web app and a large set of domain templates.

2. Primary entry points

The main runtime entry point is the CLI in src/ontogpt/cli.py. A minimal browser UI lives in src/ontogpt/webapp/main.py. Most users flow through the CLI, which selects a template/task, runs extraction, and writes outputs in one or more formats.

3. Template-driven extraction model

The src/ontogpt/templates/ directory is the conceptual center of the system. Each domain task has a paired .yaml and .py definition, covering things like drugs, phenotypes, reactions, recipes, GO terms, diseases, and environmental samples. These templates define the schema and extraction instructions that shape the LLM interaction and the structured result.

4. Prompt layer

Prompts are stored separately under src/ontogpt/prompts/ as Jinja2 templates. They encode task-specific instructions for extraction, reasoning, mapping, similarity, QA, and phenopacket generation. This separation makes prompt text a first-class architectural boundary distinct from template schemas and execution logic.

5. LLM and external model access

Model calls are abstracted through src/ontogpt/clients/, with llm_client.py as the generic adapter and openai_client.py as the provider-specific path. The README indicates the package now relies on LiteLLM semantics for provider support, so the external model boundary is “any LiteLLM-supported LLM provider” rather than OpenAI alone. There are also specialty clients for PubMed, Wikipedia, and HTML/soup-based retrieval, which extend the information source beyond the raw user text.

6. Ontology grounding and reasoning

The src/ontogpt/engines/ package holds the ontology-aware logic that grounds extracted text to controlled vocabulary terms and supports higher-level behaviors. Key subsystems include mapping, synonym resolution, topic classification, similarity, reasoner-based inference, and task-specific engines such as spires_engine.py, halo_engine.py, and pheno_engine.py. This is the architectural layer where text output is transformed into ontology-backed meaning.

7. Parsing, conversion, and object normalization

Once the LLM returns text, the src/ontogpt/utils/ package handles parsing and cleanup, including YAML/JSON wrappers and output parsing helpers. src/ontogpt/converters/ontology_converter.py and related code bridge between template instances, extracted objects, and ontology-oriented representations. This is the point where free-form model output becomes normalized structured data.

8. Output/export boundary

The src/ontogpt/io/ package is the main serialization layer. It exports results to YAML, JSON, CSV, Markdown, HTML, OWL, and RDF, and includes wrappers/utilities for templated or schema-aware output. This is an important architectural boundary because the same extracted object graph can be emitted for human review, tabular analysis, or ontology integration.

9. Web app architecture

The web app under src/ontogpt/webapp/ is intentionally minimal: an HTML form plus a results view backed by the same extraction pipeline as the CLI. It is not a separate product system; it is a thin presentation layer over the core package.

10. Evaluation subsystem

src/ontogpt/evaluation/ contains task-specific benchmarks and scripts for CTD, DrugMechDB, GO, HPOA, MAXO, IBD, and kidney-related examples. These evaluations use packaged datasets, gold standards, and task runners to measure extraction quality. Architecturally, this forms the validation boundary around the core extraction engines.

11. Ontex and domain extraction utilities

The src/ontogpt/ontex/ module appears to provide lower-level extraction support, likely for ontology-centric text extraction workflows. It sits adjacent to the engine layer and is used by task implementations that need more direct extraction mechanics.

12. Data and test assets

The repository includes extensive test fixtures under tests/input/ and golden outputs under tests/output/. These are not just unit-test aids; they document expected behavior across many templates, models, and export formats. The presence of sample OWL, YAML, pickle, TSV, and HTML outputs shows that the architecture is format-rich and pipeline-oriented.

13. Operational and packaging concerns

The project is packaged as a standard Python library with pyproject.toml, uv.lock, docs via MkDocs, and GitHub Actions for QC, docs deployment, and PyPI publishing. That means the architecture is designed for library distribution first, with CLI/web execution and reproducible evaluation as secondary operational modes.

14. Overall data flow

The common path is: user text or retrieved document → template selection → prompt assembly → LLM call through the client layer → parsed extraction → ontology grounding/reasoning → normalized object model → export to YAML/HTML/Markdown/OWL/RDF/CSV. External services enter at two points: model providers for generation and ontology/knowledge sources for grounding and retrieval.