# icamd/karpa architecture

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

- Interactive diagram: https://gitdiagram.com/icamd/karpa
- Repository: https://github.com/icamd/karpa

## Overview

KARPA takes KGQA questions and topic entities, asks an LLM to plan relevant relation paths, retrieves and ranks graph paths using either heuristic-value or pathfinding retrieval, then produces answers and evaluates predictions. The README documents both retrieval variants and automatic evaluation. Sampled code supports the main drivers’ LLM, graph-helper, and evaluation relationships; the detailed internal stages of unsampled code are represented at subsystem level rather than inferred. The repository also includes a separate CoT/IO prompting workflow.

Main entry points: [`KARPA/KARPA_H.py`](https://github.com/icamd/karpa/blob/main/KARPA/KARPA_H.py) (Heuristic Retrieval), [`KARPA/KARPA_D.py`](https://github.com/icamd/karpa/blob/main/KARPA/KARPA_D.py) (Pathfinding Retrieval), [`CoT/cot.py`](https://github.com/icamd/karpa/blob/main/CoT/cot.py) (CoT Runner), [`data`](https://github.com/icamd/karpa/tree/main/data) (QA Datasets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reasoning["KARPA Reasoning"]
  node_driver_h["Heuristic Retrieval<br/>[KARPA_H.py]"]
  node_driver_d["Pathfinding Retrieval<br/>[KARPA_D.py]"]
  node_relation_prompts["Relation Prompts<br/>[prompt_list.py]"]
end

subgraph group_kg["Knowledge Graph Access"]
  node_graph_helpers["Graph Helpers<br/>[freebase_func.py]"]
  node_query_client["Wikidata Client<br/>[client.py]"]
end

subgraph group_shared["Shared Services"]
  node_datasets["QA Datasets"]
  node_runtime_utils["Runtime Utilities<br/>[utils.py]"]
  node_evaluation["Prediction Evaluation"]
  node_prediction_files["Predictions"]
end

subgraph group_baseline["CoT Baseline"]
  node_cot_runner["CoT Runner<br/>[cot.py]"]
  node_cot_prompts["CoT/IO Prompts<br/>[prompt_list.py]"]
  node_cot_utils["CoT Utilities<br/>[utils.py]"]
end

node_user(("Questioner"))
node_kg_endpoint(("Freebase SPARQL"))
node_llm(("LLM Service"))

node_user -->|"submits question"| node_driver_h
node_user -->|"submits question"| node_driver_d
node_datasets -.->|"loads questions"| node_driver_h
node_datasets -.->|"loads questions"| node_driver_d
node_driver_h -->|"uses prompts"| node_relation_prompts
node_driver_d -->|"uses prompts"| node_relation_prompts
node_driver_h -->|"calls helpers"| node_graph_helpers
node_driver_d -->|"calls helpers"| node_graph_helpers
node_graph_helpers -->|"queries graph"| node_kg_endpoint
node_driver_h -->|"requests completions"| node_llm
node_driver_d -->|"requests completions"| node_llm
node_driver_h -->|"imports utilities"| node_runtime_utils
node_driver_d -->|"imports utilities"| node_runtime_utils
node_driver_h -->|"evaluates results"| node_evaluation
node_driver_d -->|"evaluates results"| node_evaluation
node_driver_h -->|"writes predictions"| node_prediction_files
node_driver_d -->|"writes predictions"| node_prediction_files
node_user -.->|"runs baseline"| node_cot_runner
node_cot_runner -->|"loads questions"| node_datasets
node_cot_runner -->|"selects prompts"| node_cot_prompts
node_cot_runner -->|"calls utilities"| node_cot_utils
node_cot_utils -->|"requests completion"| node_llm

click node_datasets "https://github.com/icamd/karpa/tree/main/data"
click node_driver_h "https://github.com/icamd/karpa/blob/main/KARPA/KARPA_H.py"
click node_driver_d "https://github.com/icamd/karpa/blob/main/KARPA/KARPA_D.py"
click node_relation_prompts "https://github.com/icamd/karpa/blob/main/KARPA/prompt_list.py"
click node_graph_helpers "https://github.com/icamd/karpa/blob/main/KARPA/freebase_func.py"
click node_query_client "https://github.com/icamd/karpa/blob/main/KARPA/client.py"
click node_runtime_utils "https://github.com/icamd/karpa/blob/main/KARPA/utils.py"
click node_evaluation "https://github.com/icamd/karpa/blob/main/KARPA/evaluate_results.py"
click node_prediction_files "https://github.com/icamd/karpa/tree/main/predictions"
click node_cot_runner "https://github.com/icamd/karpa/blob/main/CoT/cot.py"
click node_cot_prompts "https://github.com/icamd/karpa/blob/main/CoT/prompt_list.py"
click node_cot_utils "https://github.com/icamd/karpa/blob/main/CoT/utils.py"

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_driver_h,node_driver_d,node_relation_prompts toneBlue
class node_graph_helpers,node_query_client toneAmber
class node_datasets,node_runtime_utils,node_evaluation,node_prediction_files toneMint
class node_cot_runner,node_cot_prompts,node_cot_utils toneRose
class node_user,node_kg_endpoint,node_llm toneIndigo
```

## Components

### KARPA Reasoning

- [Heuristic Retrieval](https://github.com/icamd/karpa/blob/main/KARPA/KARPA_H.py): `KARPA/KARPA_H.py`
- [Pathfinding Retrieval](https://github.com/icamd/karpa/blob/main/KARPA/KARPA_D.py): `KARPA/KARPA_D.py`
- [Relation Prompts](https://github.com/icamd/karpa/blob/main/KARPA/prompt_list.py): `KARPA/prompt_list.py`

### Knowledge Graph Access

- [Graph Helpers](https://github.com/icamd/karpa/blob/main/KARPA/freebase_func.py): `KARPA/freebase_func.py`
- [Wikidata Client](https://github.com/icamd/karpa/blob/main/KARPA/client.py): `KARPA/client.py`

### Shared Services

- [QA Datasets](https://github.com/icamd/karpa/tree/main/data): `data`
- [Runtime Utilities](https://github.com/icamd/karpa/blob/main/KARPA/utils.py): `KARPA/utils.py`
- [Prediction Evaluation](https://github.com/icamd/karpa/blob/main/KARPA/evaluate_results.py): `KARPA/evaluate_results.py`
- [Predictions](https://github.com/icamd/karpa/tree/main/predictions): `predictions`

### CoT Baseline

- [CoT Runner](https://github.com/icamd/karpa/blob/main/CoT/cot.py): `CoT/cot.py`
- [CoT/IO Prompts](https://github.com/icamd/karpa/blob/main/CoT/prompt_list.py): `CoT/prompt_list.py`
- [CoT Utilities](https://github.com/icamd/karpa/blob/main/CoT/utils.py): `CoT/utils.py`

### Other components

- **Questioner**
- **Freebase SPARQL**
- **LLM Service**

## Connections

- Questioner → Heuristic Retrieval: submits question (evidence: `README.md`)
- Questioner → Pathfinding Retrieval: submits question (evidence: `README.md`)
- QA Datasets → Heuristic Retrieval: loads questions
- QA Datasets → Pathfinding Retrieval: loads questions
- Heuristic Retrieval → Relation Prompts: uses prompts (evidence: `KARPA/KARPA_H.py`)
- Pathfinding Retrieval → Relation Prompts: uses prompts (evidence: `KARPA/KARPA_D.py`)
- Heuristic Retrieval → Graph Helpers: calls helpers (evidence: `KARPA/KARPA_H.py`)
- Pathfinding Retrieval → Graph Helpers: calls helpers (evidence: `KARPA/KARPA_D.py`)
- Graph Helpers → Freebase SPARQL: queries graph (evidence: `KARPA/freebase_func.py`)
- Heuristic Retrieval → LLM Service: requests completions (evidence: `KARPA/KARPA_H.py`)
- Pathfinding Retrieval → LLM Service: requests completions (evidence: `KARPA/KARPA_D.py`)
- Heuristic Retrieval → Runtime Utilities: imports utilities (evidence: `KARPA/KARPA_H.py`)
- Pathfinding Retrieval → Runtime Utilities: imports utilities (evidence: `KARPA/KARPA_D.py`)
- Heuristic Retrieval → Prediction Evaluation: evaluates results (evidence: `KARPA/KARPA_H.py`)
- Pathfinding Retrieval → Prediction Evaluation: evaluates results (evidence: `KARPA/KARPA_D.py`)
- Heuristic Retrieval → Predictions: writes predictions (evidence: `README.md`)
- Pathfinding Retrieval → Predictions: writes predictions (evidence: `README.md`)
- Questioner → CoT Runner: runs baseline
- CoT Runner → QA Datasets: loads questions
- CoT Runner → CoT/IO Prompts: selects prompts (evidence: `CoT/cot.py`)
- CoT Runner → CoT Utilities: calls utilities (evidence: `CoT/cot.py`)
- CoT Utilities → LLM Service: requests completion (evidence: `CoT/utils.py`)
