# utrechtuniversity/hta-genai architecture

> Architecture diagram of the GitHub repository utrechtuniversity/hta-genai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/utrechtuniversity/hta-genai
- Repository: https://github.com/utrechtuniversity/hta-genai

## Overview

This repository extracts structured HTA attributes from PDF documents with configurable LLMs, then optionally evaluates the results against ground truth. The main workflow is CLI configuration → PDF text extraction and schema-guided prompting → model response parsing and saved JSON → comparison and metrics. The graph follows the sampled runtime code; evaluation internals are only partially sampled, so uncertain evaluation substeps are not expanded.

Main entry points: [`run.py`](https://github.com/utrechtuniversity/hta-genai/blob/main/run.py) (Run workflow), [`hta/extraction/extract_hta_attributes.py`](https://github.com/utrechtuniversity/hta-genai/blob/main/hta/extraction/extract_hta_attributes.py) (Extraction runner), [`hta/evaluation/evaluate_results.py`](https://github.com/utrechtuniversity/hta-genai/blob/main/hta/evaluation/evaluate_results.py) (Result evaluator), [`hta/extraction/hta_extractor.py`](https://github.com/utrechtuniversity/hta-genai/blob/main/hta/extraction/hta_extractor.py) (Document extractor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Orchestration"]
  node_runner["Run workflow<br/>[run.py]"]
  node_config["Runtime config<br/>[config.yaml]"]
end

subgraph group_extraction["HTA Extraction"]
  node_extract_job["Extraction runner"]
  node_extractor["Document extractor<br/>[hta_extractor.py]"]
  node_prompt["Prompt template"]
  node_schema["Output schema<br/>[schema.json]"]
  node_results["Extraction results"]
end

subgraph group_models["LLM Integration"]
  node_llm_client["LLM client<br/>[llm_client.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_ground_truth["Ground truth"]
  node_evaluator["Result evaluator"]
  node_eval_outputs["Evaluation outputs"]
end

node_user(("Researcher"))
node_pdfs["HTA PDFs"]
node_llm_services{{"LLM providers"}}

node_user -->|"starts"| node_runner
node_runner -->|"loads"| node_config
node_runner -->|"runs extraction"| node_extract_job
node_extract_job -->|"reads"| node_config
node_extract_job -->|"discovers PDFs"| node_pdfs
node_extract_job -->|"processes each"| node_extractor
node_extractor -->|"loads"| node_prompt
node_extractor -->|"loads"| node_schema
node_extractor -->|"requests completion"| node_llm_client
node_llm_client -.->|"sends prompt"| node_llm_services
node_llm_services -.->|"returns response"| node_llm_client
node_extract_job -->|"appends JSON"| node_results
node_runner -->|"checks availability"| node_ground_truth
node_runner -->|"runs evaluation"| node_evaluator
node_evaluator -->|"reads results"| node_results
node_evaluator -->|"compares against"| node_ground_truth
node_evaluator -->|"reads descriptions"| node_schema
node_evaluator -.->|"requests comparison"| node_llm_client
node_runner -->|"writes comparisons and metrics"| node_eval_outputs

click node_runner "https://github.com/utrechtuniversity/hta-genai/blob/main/run.py"
click node_config "https://github.com/utrechtuniversity/hta-genai/blob/main/config/config.yaml"
click node_extract_job "https://github.com/utrechtuniversity/hta-genai/blob/main/hta/extraction/extract_hta_attributes.py"
click node_extractor "https://github.com/utrechtuniversity/hta-genai/blob/main/hta/extraction/hta_extractor.py"
click node_prompt "https://github.com/utrechtuniversity/hta-genai/blob/main/config/prompt_template.yaml"
click node_schema "https://github.com/utrechtuniversity/hta-genai/blob/main/config/schema.json"
click node_results "https://github.com/utrechtuniversity/hta-genai/tree/main/data/processed"
click node_llm_client "https://github.com/utrechtuniversity/hta-genai/blob/main/hta/llm_client.py"
click node_ground_truth "https://github.com/utrechtuniversity/hta-genai/tree/main/data/raw"
click node_evaluator "https://github.com/utrechtuniversity/hta-genai/blob/main/hta/evaluation/evaluate_results.py"
click node_eval_outputs "https://github.com/utrechtuniversity/hta-genai/tree/main/data/processed"

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_runner,node_config toneBlue
class node_extract_job,node_extractor,node_prompt,node_schema,node_results toneAmber
class node_llm_client toneMint
class node_ground_truth,node_evaluator,node_eval_outputs toneRose
class node_user,node_pdfs,node_llm_services toneIndigo
```

## Components

### Orchestration

- [Run workflow](https://github.com/utrechtuniversity/hta-genai/blob/main/run.py): `run.py`
- [Runtime config](https://github.com/utrechtuniversity/hta-genai/blob/main/config/config.yaml): `config/config.yaml`

### HTA Extraction

- [Extraction runner](https://github.com/utrechtuniversity/hta-genai/blob/main/hta/extraction/extract_hta_attributes.py): `hta/extraction/extract_hta_attributes.py`
- [Document extractor](https://github.com/utrechtuniversity/hta-genai/blob/main/hta/extraction/hta_extractor.py): `hta/extraction/hta_extractor.py`
- [Prompt template](https://github.com/utrechtuniversity/hta-genai/blob/main/config/prompt_template.yaml): `config/prompt_template.yaml`
- [Output schema](https://github.com/utrechtuniversity/hta-genai/blob/main/config/schema.json): `config/schema.json`
- [Extraction results](https://github.com/utrechtuniversity/hta-genai/tree/main/data/processed): `data/processed`

### LLM Integration

- [LLM client](https://github.com/utrechtuniversity/hta-genai/blob/main/hta/llm_client.py): `hta/llm_client.py`

### Evaluation

- [Ground truth](https://github.com/utrechtuniversity/hta-genai/tree/main/data/raw): `data/raw`
- [Result evaluator](https://github.com/utrechtuniversity/hta-genai/blob/main/hta/evaluation/evaluate_results.py): `hta/evaluation/evaluate_results.py`
- [Evaluation outputs](https://github.com/utrechtuniversity/hta-genai/tree/main/data/processed): `data/processed`

### Other components

- **Researcher**
- **HTA PDFs**
- **LLM providers**

## Connections

- Researcher → Run workflow: starts
- Run workflow → Runtime config: loads
- Run workflow → Extraction runner: runs extraction
- Extraction runner → Runtime config: reads
- Extraction runner → HTA PDFs: discovers PDFs
- Extraction runner → Document extractor: processes each
- Document extractor → Prompt template: loads
- Document extractor → Output schema: loads
- Document extractor → LLM client: requests completion
- LLM client → LLM providers: sends prompt
- LLM providers → LLM client: returns response
- Extraction runner → Extraction results: appends JSON
- Run workflow → Ground truth: checks availability
- Run workflow → Result evaluator: runs evaluation
- Result evaluator → Extraction results: reads results
- Result evaluator → Ground truth: compares against
- Result evaluator → Output schema: reads descriptions
- Result evaluator → LLM client: requests comparison
- Run workflow → Evaluation outputs: writes comparisons and metrics