# ke-uniliv/idea2 architecture

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

- Interactive diagram: https://gitdiagram.com/ke-uniliv/idea2
- Repository: https://github.com/ke-uniliv/idea2

## Overview

IDEA2 supports ontology engineers and domain experts in extracting competency questions (CQs) from schemas or other source material, reviewing them in Notion, and iteratively refining rejected questions. The main runtime orchestrator is `idea2/runner.py`; generation, model access, evaluation, provenance export, and Notion review are distinct stages. The graph also includes documented persona/user-story input and ontology-testing uses. Some subsystem links are documented in the README rather than demonstrated by sampled calls; unsampled implementations are represented only where the README or source index supports them.

Main entry points: [`idea2/runner.py`](https://github.com/ke-uniliv/idea2/blob/main/idea2/runner.py) (Workflow runner), [`idea2/notion_utils.py`](https://github.com/ke-uniliv/idea2/blob/main/idea2/notion_utils.py) (Notion CQ operations), [`idea2/prompts.py`](https://github.com/ke-uniliv/idea2/blob/main/idea2/prompts.py) (Prompt design), [`idea2/cq_extraction.py`](https://github.com/ke-uniliv/idea2/blob/main/idea2/cq_extraction.py) (CQ extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow orchestration"]
  node_runner["Workflow runner<br/>[runner.py]"]
  node_schema_input["Schema input<br/>[schema2cq.py]"]
  node_personas["Persona stories"]
end

subgraph group_generation["CQ generation"]
  node_prompts["Prompt design<br/>[prompts.py]"]
  node_extraction["CQ extraction<br/>[cq_extraction.py]"]
  node_llm_api["LLM interface<br/>[interfaces.py]"]
  node_generation_config["Generation settings"]
end

subgraph group_review["Review and refinement"]
  node_reformulation["CQ reformulation<br/>[reformulate_cq.py]"]
  node_notion_api[("Notion workspace")]
  node_notion_ops["Notion CQ operations<br/>[notion_utils.py]"]
  node_linkage["CQ linkage<br/>[cq_linkage.py]"]
  node_metrics["Review metrics<br/>[notion_metrics.py]"]
end

subgraph group_data["Evaluation and provenance"]
  node_similarity["Similarity analysis<br/>[cq_measures.py]"]
  node_jsonld["CQ JSON-LD<br/>[cq_json_ld.py]"]
  node_exports["Exports<br/>[exports.py]"]
  node_constraints["Output constraints"]
  node_enrichment["Ontology enrichment"]
  node_evaluation["Iteration evaluation"]
end

node_engineer(("Ontology engineer"))
node_experts(("Domain experts"))
node_sources["Source documents"]

node_engineer -->|"starts workflow"| node_runner
node_sources -->|"provides input"| node_runner
node_runner -->|"loads schemas"| node_schema_input
node_runner -.->|"supports stories"| node_personas
node_runner -->|"runs extraction"| node_extraction
node_schema_input -->|"uses prompts"| node_prompts
node_extraction -->|"configures prompts"| node_prompts
node_extraction -->|"requests generation"| node_llm_api
node_llm_api -.->|"generates responses"| node_sources
node_runner -->|"runs refinement"| node_reformulation
node_reformulation -->|"queries feedback"| node_notion_api
node_reformulation -->|"uses prompts"| node_prompts
node_runner -->|"writes CQs"| node_notion_ops
node_notion_ops -->|"reads and writes"| node_notion_api
node_experts -->|"reviews CQs"| node_notion_api
node_runner -->|"links reformulations"| node_linkage
node_linkage -->|"updates relations"| node_notion_api
node_runner -->|"checks similarity"| node_similarity
node_runner -->|"exports provenance"| node_jsonld
node_jsonld -->|"reads iteration"| node_notion_ops
node_jsonld -->|"gets generation"| node_generation_config
node_runner -.->|"uses review metrics"| node_metrics
node_prompts -->|"imports metrics"| node_metrics
node_notion_ops -.->|"supports evaluation"| node_metrics
node_runner -.->|"offers exports"| node_exports
node_runner -.->|"applies constraints"| node_constraints
node_runner -.->|"supports ontology work"| node_enrichment
node_runner -.->|"evaluates iterations"| node_evaluation

click node_runner "https://github.com/ke-uniliv/idea2/blob/main/idea2/runner.py"
click node_schema_input "https://github.com/ke-uniliv/idea2/blob/main/idea2/schema2cq.py"
click node_personas "https://github.com/ke-uniliv/idea2/blob/main/idea2/personas_user_stories.py"
click node_prompts "https://github.com/ke-uniliv/idea2/blob/main/idea2/prompts.py"
click node_extraction "https://github.com/ke-uniliv/idea2/blob/main/idea2/cq_extraction.py"
click node_llm_api "https://github.com/ke-uniliv/idea2/blob/main/idea2/interfaces.py"
click node_generation_config "https://github.com/ke-uniliv/idea2/blob/main/idea2/generation_utils.py"
click node_reformulation "https://github.com/ke-uniliv/idea2/blob/main/idea2/reformulate_cq.py"
click node_notion_ops "https://github.com/ke-uniliv/idea2/blob/main/idea2/notion_utils.py"
click node_linkage "https://github.com/ke-uniliv/idea2/blob/main/idea2/cq_linkage.py"
click node_metrics "https://github.com/ke-uniliv/idea2/blob/main/idea2/notion_metrics.py"
click node_similarity "https://github.com/ke-uniliv/idea2/blob/main/idea2/cq_measures.py"
click node_jsonld "https://github.com/ke-uniliv/idea2/blob/main/idea2/cq_json_ld.py"
click node_exports "https://github.com/ke-uniliv/idea2/blob/main/idea2/exports.py"
click node_constraints "https://github.com/ke-uniliv/idea2/blob/main/idea2/output_constraints.py"
click node_enrichment "https://github.com/ke-uniliv/idea2/blob/main/idea2/ontology_enrichment.py"
click node_evaluation "https://github.com/ke-uniliv/idea2/blob/main/idea2/iteration_evaluation.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_runner,node_schema_input,node_personas toneBlue
class node_prompts,node_extraction,node_llm_api,node_generation_config toneAmber
class node_reformulation,node_notion_api,node_notion_ops,node_linkage,node_metrics toneMint
class node_similarity,node_jsonld,node_exports,node_constraints,node_enrichment,node_evaluation toneRose
class node_engineer,node_experts,node_sources toneIndigo
```

## Components

### Workflow orchestration

- [Workflow runner](https://github.com/ke-uniliv/idea2/blob/main/idea2/runner.py): `idea2/runner.py`
- [Schema input](https://github.com/ke-uniliv/idea2/blob/main/idea2/schema2cq.py): `idea2/schema2cq.py`
- [Persona stories](https://github.com/ke-uniliv/idea2/blob/main/idea2/personas_user_stories.py): `idea2/personas_user_stories.py`

### CQ generation

- [Prompt design](https://github.com/ke-uniliv/idea2/blob/main/idea2/prompts.py): `idea2/prompts.py`
- [CQ extraction](https://github.com/ke-uniliv/idea2/blob/main/idea2/cq_extraction.py): `idea2/cq_extraction.py`
- [LLM interface](https://github.com/ke-uniliv/idea2/blob/main/idea2/interfaces.py): `idea2/interfaces.py`
- [Generation settings](https://github.com/ke-uniliv/idea2/blob/main/idea2/generation_utils.py): `idea2/generation_utils.py`

### Review and refinement

- [CQ reformulation](https://github.com/ke-uniliv/idea2/blob/main/idea2/reformulate_cq.py): `idea2/reformulate_cq.py`
- **Notion workspace**
- [Notion CQ operations](https://github.com/ke-uniliv/idea2/blob/main/idea2/notion_utils.py): `idea2/notion_utils.py`
- [CQ linkage](https://github.com/ke-uniliv/idea2/blob/main/idea2/cq_linkage.py): `idea2/cq_linkage.py`
- [Review metrics](https://github.com/ke-uniliv/idea2/blob/main/idea2/notion_metrics.py): `idea2/notion_metrics.py`

### Evaluation and provenance

- [Similarity analysis](https://github.com/ke-uniliv/idea2/blob/main/idea2/cq_measures.py): `idea2/cq_measures.py`
- [CQ JSON-LD](https://github.com/ke-uniliv/idea2/blob/main/idea2/cq_json_ld.py): `idea2/cq_json_ld.py`
- [Exports](https://github.com/ke-uniliv/idea2/blob/main/idea2/exports.py): `idea2/exports.py`
- [Output constraints](https://github.com/ke-uniliv/idea2/blob/main/idea2/output_constraints.py): `idea2/output_constraints.py`
- [Ontology enrichment](https://github.com/ke-uniliv/idea2/blob/main/idea2/ontology_enrichment.py): `idea2/ontology_enrichment.py`
- [Iteration evaluation](https://github.com/ke-uniliv/idea2/blob/main/idea2/iteration_evaluation.py): `idea2/iteration_evaluation.py`

### Other components

- **Ontology engineer**
- **Domain experts**
- **Source documents**

## Connections

- Ontology engineer → Workflow runner: starts workflow (evidence: `README.md`)
- Source documents → Workflow runner: provides input (evidence: `README.md`)
- Workflow runner → Schema input: loads schemas (evidence: `idea2/runner.py`)
- Workflow runner → Persona stories: supports stories (evidence: `README.md`)
- Workflow runner → CQ extraction: runs extraction (evidence: `idea2/runner.py`)
- Schema input → Prompt design: uses prompts (evidence: `idea2/schema2cq.py`)
- CQ extraction → Prompt design: configures prompts (evidence: `idea2/cq_extraction.py`)
- CQ extraction → LLM interface: requests generation (evidence: `idea2/cq_extraction.py`)
- LLM interface → Source documents: generates responses
- Workflow runner → CQ reformulation: runs refinement (evidence: `idea2/runner.py`)
- CQ reformulation → Notion workspace: queries feedback (evidence: `idea2/reformulate_cq.py`)
- CQ reformulation → Prompt design: uses prompts (evidence: `idea2/reformulate_cq.py`)
- Workflow runner → Notion CQ operations: writes CQs (evidence: `idea2/runner.py`)
- Notion CQ operations → Notion workspace: reads and writes (evidence: `README.md`)
- Domain experts → Notion workspace: reviews CQs (evidence: `README.md`)
- Workflow runner → CQ linkage: links reformulations (evidence: `idea2/runner.py`)
- CQ linkage → Notion workspace: updates relations (evidence: `idea2/cq_linkage.py`)
- Workflow runner → Similarity analysis: checks similarity (evidence: `idea2/runner.py`)
- Workflow runner → CQ JSON-LD: exports provenance (evidence: `idea2/runner.py`)
- CQ JSON-LD → Notion CQ operations: reads iteration (evidence: `idea2/cq_json_ld.py`)
- CQ JSON-LD → Generation settings: gets generation (evidence: `idea2/cq_json_ld.py`)
- Workflow runner → Review metrics: uses review metrics
- Prompt design → Review metrics: imports metrics (evidence: `idea2/prompts.py`)
- Notion CQ operations → Review metrics: supports evaluation
- Workflow runner → Exports: offers exports
- Workflow runner → Output constraints: applies constraints
- Workflow runner → Ontology enrichment: supports ontology work
- Workflow runner → Iteration evaluation: evaluates iterations
