# monarch-initiative/ontogpt architecture

> Architecture diagram of the GitHub repository monarch-initiative/ontogpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monarch-initiative/ontogpt
- Repository: https://github.com/monarch-initiative/ontogpt

## Overview

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.

Main entry points: [`src/ontogpt/engines`](https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/engines) (Engines), [`src/ontogpt/cli.py`](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/cli.py) (CLI), [`src/ontogpt/clients/llm_client.py`](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/clients/llm_client.py) (LLM adapter), [`src/ontogpt/io`](https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/io) (Exporters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core pipeline"]
  node_llm_clients[("LLM clients<br/>provider adapters")]
  node_llm_client["LLM adapter<br/>client core<br/>[llm_client.py]"]
  node_openai_client["OpenAI path<br/>provider client<br/>[openai_client.py]"]
  node_retrieval_clients[("Retrieval clients<br/>source adapters<br/>[pubmed_client.py]")]
end

subgraph group_interfaces["Entry points"]
  node_cli["CLI<br/>entry point<br/>[cli.py]"]
  node_webapp["Web app<br/>presentation<br/>[main.py]"]
end

subgraph group_modeling["Task definitions"]
  node_templates["Templates<br/>task schemas"]
  node_prompts["Prompts<br/>prompt library"]
end

subgraph group_grounding["Ontology grounding"]
  node_engines{{"Engines<br/>grounding logic"}}
  node_mapping_engine["Mapping<br/>[mapping_engine.py]"]
  node_reasoner_engine["Reasoner<br/>inference<br/>[reasoner_engine.py]"]
  node_synonym_engine["Synonyms<br/>lexical grounding<br/>[synonym_engine.py]"]
  node_ontology_converter["Ontology converter<br/>normalization"]
  node_parsing_utils["Parsing utils<br/>output parsing"]
  node_ontex["Ontex<br/>extraction support<br/>[extractor.py]"]
  node_utils["Utilities<br/>helpers"]
end

subgraph group_outputs["Output and validation"]
  node_exporters[("Exporters<br/>serialization")]
  node_evaluation{{"Evaluation<br/>benchmarks"}}
end

node_cli -->|"selects task"| node_templates
node_cli -->|"assembles prompt"| node_prompts
node_cli -->|"calls model"| node_llm_client
node_webapp -.->|"reuses pipeline"| node_cli
node_templates -->|"guides prompt"| node_prompts
node_llm_clients -->|"includes"| node_llm_client
node_llm_clients -->|"includes"| node_openai_client
node_llm_clients -->|"includes"| node_retrieval_clients
node_llm_client -->|"feeds text"| node_engines
node_retrieval_clients -->|"adds evidence"| node_engines
node_engines -->|"maps terms"| node_mapping_engine
node_engines -->|"infers"| node_reasoner_engine
node_engines -->|"resolves names"| node_synonym_engine
node_engines -->|"supports extraction"| node_ontex
node_engines -->|"normalizes"| node_ontology_converter
node_ontology_converter -->|"cleans output"| node_parsing_utils
node_parsing_utils -->|"prepares records"| node_exporters
node_engines -->|"exports results"| node_exporters
node_evaluation -->|"benchmarks tasks"| node_templates
node_evaluation -->|"measures grounding"| node_engines
node_evaluation -.->|"checks formats"| node_exporters
node_utils -->|"supports"| node_llm_client
node_utils -->|"supports"| node_exporters

click node_cli "https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/cli.py"
click node_webapp "https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/webapp/main.py"
click node_templates "https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/templates"
click node_prompts "https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/prompts"
click node_llm_clients "https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/clients"
click node_llm_client "https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/clients/llm_client.py"
click node_openai_client "https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/clients/openai_client.py"
click node_retrieval_clients "https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/clients/pubmed_client.py"
click node_engines "https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/engines"
click node_mapping_engine "https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/engines/mapping_engine.py"
click node_reasoner_engine "https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/engines/reasoner_engine.py"
click node_synonym_engine "https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/engines/synonym_engine.py"
click node_ontology_converter "https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/converters/ontology_converter.py"
click node_parsing_utils "https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/utils"
click node_exporters "https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/io"
click node_evaluation "https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/evaluation"
click node_ontex "https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/ontex/extractor.py"
click node_utils "https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/utils"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_llm_clients,node_llm_client,node_openai_client,node_retrieval_clients toneBlue
class node_cli,node_webapp toneAmber
class node_templates,node_prompts toneMint
class node_engines,node_mapping_engine,node_reasoner_engine,node_synonym_engine,node_ontology_converter,node_parsing_utils,node_ontex,node_utils toneRose
class node_exporters,node_evaluation toneIndigo
```

## Components

### Core pipeline

Main extraction flow from CLI through templates, LLM calls, grounding, normalization, and export.

- [LLM clients](https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/clients): provider adapters · Model access layer abstracted across LiteLLM-supported providers and specialty retrieval clients. · `src/ontogpt/clients`
- [LLM adapter](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/clients/llm_client.py): client core · Generic LLM client abstraction used by extraction tasks. · `src/ontogpt/clients/llm_client.py`
- [OpenAI path](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/clients/openai_client.py): provider client · Provider-specific client implementation. · `src/ontogpt/clients/openai_client.py`
- [Retrieval clients](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/clients/pubmed_client.py): source adapters · Specialty clients for PubMed, Wikipedia, and HTML/soup-based retrieval. · `src/ontogpt/clients/pubmed_client.py`

### Entry points

User-facing ways to run the package.

- [CLI](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/cli.py): entry point · Main command-line entry point for extraction workflows. · `src/ontogpt/cli.py`
- [Web app](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/webapp/main.py): presentation · Minimal browser UI over the same extraction pipeline. · `src/ontogpt/webapp/main.py`

### Task definitions

Templates and prompts that define extraction behavior.

- [Templates](https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/templates): task schemas · Domain-specific YAML/Python task definitions that shape extraction. · `src/ontogpt/templates`
- [Prompts](https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/prompts): prompt library · Jinja2 prompt templates for extraction, reasoning, mapping, QA, and similarity. · `src/ontogpt/prompts`

### Ontology grounding

Engines and converters that map free text to ontology-backed structures.

- [Engines](https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/engines): grounding logic · Ontology-aware extraction, mapping, reasoning, synonym, topic, and similarity components. · `src/ontogpt/engines`
- [Mapping](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/engines/mapping_engine.py): ontology mapping · Maps extracted mentions to controlled vocabulary terms. · `src/ontogpt/engines/mapping_engine.py`
- [Reasoner](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/engines/reasoner_engine.py): inference · Supports rule- and reasoner-based inference over extracted content. · `src/ontogpt/engines/reasoner_engine.py`
- [Synonyms](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/engines/synonym_engine.py): lexical grounding · Resolves synonym and naming variation during grounding. · `src/ontogpt/engines/synonym_engine.py`
- [Ontology converter](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/converters/ontology_converter.py): normalization · Bridges template instances, extracted objects, and ontology-oriented representations. · `src/ontogpt/converters/ontology_converter.py`
- [Parsing utils](https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/utils): output parsing · Cleanup and parsing helpers for YAML/JSON-like model outputs. · `src/ontogpt/utils`
- [Ontex](https://github.com/monarch-initiative/ontogpt/blob/main/src/ontogpt/ontex/extractor.py): extraction support · Lower-level ontology-centric extraction support used by some tasks. · `src/ontogpt/ontex/extractor.py`
- [Utilities](https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/utils): helpers · Shared helpers for model use, multilingual handling, parsing, and document utilities. · `src/ontogpt/utils`

### Output and validation

Serialization and evaluation boundaries around the core system.

- [Exporters](https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/io): serialization · Writes extracted results to YAML, JSON, CSV, Markdown, HTML, OWL, and RDF. · `src/ontogpt/io`
- [Evaluation](https://github.com/monarch-initiative/ontogpt/tree/main/src/ontogpt/evaluation): benchmarks · Task-specific benchmarks and runners for CTD, DrugMechDB, GO, HPOA, MAXO, IBD, and kidney examples. · `src/ontogpt/evaluation`

## Connections

- CLI → Templates: selects task · CLI chooses a template-driven extraction task.
- CLI → Prompts: assembles prompt · CLI-driven runs load prompt text for task execution.
- CLI → LLM adapter: calls model · CLI flows invoke the LLM abstraction for generation.
- Web app → CLI: reuses pipeline · Web UI is a thin front end over the same extraction machinery.
- Templates → Prompts: guides prompt · Template definitions and prompts jointly shape task behavior.
- LLM clients → LLM adapter: includes · Generic adapter sits inside the broader client layer.
- LLM clients → OpenAI path: includes · Provider-specific path within the client layer.
- LLM clients → Retrieval clients: includes · Retrieval and source clients extend the model boundary.
- LLM adapter → Engines: feeds text · Model output is handed into ontology-aware engines.
- Retrieval clients → Engines: adds evidence · Retrieved context can supplement grounding and extraction.
- Engines → Mapping: maps terms · Core engine layer includes ontology mapping.
- Engines → Reasoner: infers · Core engine layer includes reasoning/inference.
- Engines → Synonyms: resolves names · Core engine layer includes synonym handling.
- Engines → Ontex: supports extraction · Some task implementations use lower-level ontology extraction support.
- Engines → Ontology converter: normalizes · Engine outputs are converted into structured ontology-oriented objects.
- Ontology converter → Parsing utils: cleans output · Conversion relies on parsing and cleanup helpers.
- Parsing utils → Exporters: prepares records · Parsed normalized objects are handed to serialization/export.
- Engines → Exporters: exports results · Structured output is emitted in multiple downstream formats.
- Evaluation → Templates: benchmarks tasks · Evaluation suites exercise specific template-driven tasks.
- Evaluation → Engines: measures grounding · Benchmarks validate ontology grounding and task performance.
- Evaluation → Exporters: checks formats · Golden outputs cover multiple serialization targets.
- Utilities → LLM adapter: supports · Utility code supports model interaction and output handling.
- Utilities → Exporters: supports · Shared helpers are reused by output and file handling code.