# kurocaguama/kurosagol architecture

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

- Interactive diagram: https://gitdiagram.com/kurocaguama/kurosagol
- Repository: https://github.com/kurocaguama/kurosagol

## Overview

Kurosagol is a thesis-research toolkit for studying LLM logical reasoning and alignment. The principal workflow takes FOLIO natural-language premises through translation to first-order logic, logical inference, and retranslation; generated answers are assembled into preference datasets, used for DPO alignment, and evaluated against FOLIO with LogicSim-style metrics. The repository also contains ongoing baseline and alignment experiments. Some ongoing behavior is represented only by notebooks and artifact directories, so their internal call wiring is not inferred.

Main entry points: [`Ongoing`](https://github.com/kurocaguama/kurosagol/tree/main/Ongoing) (Ongoing experiments), [`Legacy/Kurosagol/create_pref_dataset.py`](https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/create_pref_dataset.py) (Preference generation), [`Legacy/Kurosagol/llm_testing.py`](https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/llm_testing.py) (Baseline evaluation), [`Legacy/Kurosagol/align.py`](https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/align.py) (Alignment runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Datasets and outputs"]
  node_folio[("FOLIO corpus")]
  node_preference["Preference datasets"]
  node_generated["Generated answers"]
  node_aligned_models["Aligned model outputs"]
end

subgraph group_generation["Reasoning generation"]
  node_ongoing_experiments["Ongoing experiments"]
  node_prompt_templates["Stage prompts<br/>[prompts.py]"]
  node_dataset_manager["Dataset generation<br/>[Kurosagol.py]"]
  node_legacy_generation["Preference generation"]
end

subgraph group_alignment["Preference and alignment"]
  node_dpo_trainer["DPO alignment<br/>[Kurosagol.py]"]
  node_alignment_driver["Alignment runner<br/>[align.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_baseline_eval["Baseline evaluation<br/>[llm_testing.py]"]
  node_evaluation_logic["LogicSim evaluation<br/>[logic_sim.py]"]
  node_logic_sim_plus["LogicSim+ metrics<br/>[logicsim.py]"]
  node_similarity["Text similarity<br/>[utils.py]"]
end

node_researcher(("Researcher"))
node_model_service{{"Language models"}}
node_hf_hub{{"Hugging Face Hub"}}

node_researcher -->|"runs stages"| node_legacy_generation
node_folio -->|"loads training data"| node_legacy_generation
node_legacy_generation -->|"creates manager"| node_dataset_manager
node_legacy_generation -->|"formats prompts"| node_prompt_templates
node_dataset_manager -->|"generates answers"| node_model_service
node_dataset_manager -->|"builds preference data"| node_preference
node_legacy_generation -->|"uploads datasets"| node_hf_hub
node_preference -->|"supplies training data"| node_alignment_driver
node_researcher -->|"runs alignment"| node_alignment_driver
node_alignment_driver -->|"trains model"| node_dpo_trainer
node_dpo_trainer -->|"loads base model"| node_model_service
node_alignment_driver -->|"publishes models"| node_hf_hub
node_researcher -->|"runs evaluation"| node_baseline_eval
node_baseline_eval -->|"reads validation split"| node_folio
node_baseline_eval -->|"generates stage answers"| node_model_service
node_baseline_eval -->|"publishes answer datasets"| node_hf_hub
node_researcher -->|"evaluates outputs"| node_evaluation_logic
node_evaluation_logic -->|"loads answer datasets"| node_hf_hub
node_evaluation_logic -->|"compares answers"| node_similarity
node_researcher -.->|"runs experiments"| node_ongoing_experiments
node_ongoing_experiments -.->|"uses stage prompts"| node_prompt_templates
node_ongoing_experiments -.->|"records results"| node_generated
node_ongoing_experiments -.->|"records alignment data"| node_aligned_models
node_ongoing_experiments -.->|"evaluates generations"| node_logic_sim_plus
node_logic_sim_plus -->|"compares FOLIO answers"| node_folio

click node_folio "https://github.com/kurocaguama/kurosagol/tree/main/FOLIO/FOLIO"
click node_preference "https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/create_pref_dataset.py"
click node_generated "https://github.com/kurocaguama/kurosagol/tree/main/Ongoing/alignment_results"
click node_aligned_models "https://github.com/kurocaguama/kurosagol/tree/main/Ongoing/alignment_datasets"
click node_ongoing_experiments "https://github.com/kurocaguama/kurosagol/tree/main/Ongoing"
click node_prompt_templates "https://github.com/kurocaguama/kurosagol/blob/main/Ongoing/prompts.py"
click node_dataset_manager "https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/Kurosagol.py"
click node_legacy_generation "https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/create_pref_dataset.py"
click node_dpo_trainer "https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/Kurosagol.py"
click node_alignment_driver "https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/align.py"
click node_baseline_eval "https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/llm_testing.py"
click node_evaluation_logic "https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/logic_sim.py"
click node_logic_sim_plus "https://github.com/kurocaguama/kurosagol/blob/main/Ongoing/logicsim.py"
click node_similarity "https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/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_folio,node_preference,node_generated,node_aligned_models toneBlue
class node_ongoing_experiments,node_prompt_templates,node_dataset_manager,node_legacy_generation toneAmber
class node_dpo_trainer,node_alignment_driver toneMint
class node_baseline_eval,node_evaluation_logic,node_logic_sim_plus,node_similarity toneRose
class node_researcher,node_model_service,node_hf_hub toneIndigo
```

## Components

### Datasets and outputs

- [FOLIO corpus](https://github.com/kurocaguama/kurosagol/tree/main/FOLIO/FOLIO): `FOLIO/FOLIO`
- [Preference datasets](https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/create_pref_dataset.py): `Legacy/Kurosagol/create_pref_dataset.py`
- [Generated answers](https://github.com/kurocaguama/kurosagol/tree/main/Ongoing/alignment_results): `Ongoing/alignment_results`
- [Aligned model outputs](https://github.com/kurocaguama/kurosagol/tree/main/Ongoing/alignment_datasets): `Ongoing/alignment_datasets`

### Reasoning generation

- [Ongoing experiments](https://github.com/kurocaguama/kurosagol/tree/main/Ongoing): `Ongoing`
- [Stage prompts](https://github.com/kurocaguama/kurosagol/blob/main/Ongoing/prompts.py): `Ongoing/prompts.py`
- [Dataset generation](https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/Kurosagol.py): `Legacy/Kurosagol/Kurosagol.py`
- [Preference generation](https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/create_pref_dataset.py): `Legacy/Kurosagol/create_pref_dataset.py`

### Preference and alignment

- [DPO alignment](https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/Kurosagol.py): `Legacy/Kurosagol/Kurosagol.py`
- [Alignment runner](https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/align.py): `Legacy/Kurosagol/align.py`

### Evaluation

- [Baseline evaluation](https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/llm_testing.py): `Legacy/Kurosagol/llm_testing.py`
- [LogicSim evaluation](https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/logic_sim.py): `Legacy/Kurosagol/logic_sim.py`
- [LogicSim+ metrics](https://github.com/kurocaguama/kurosagol/blob/main/Ongoing/logicsim.py): `Ongoing/logicsim.py`
- [Text similarity](https://github.com/kurocaguama/kurosagol/blob/main/Legacy/Kurosagol/utils.py): `Legacy/Kurosagol/utils.py`

### Other components

- **Researcher**
- **Language models**
- **Hugging Face Hub**

## Connections

- Researcher → Preference generation: runs stages
- FOLIO corpus → Preference generation: loads training data
- Preference generation → Dataset generation: creates manager
- Preference generation → Stage prompts: formats prompts
- Dataset generation → Language models: generates answers
- Dataset generation → Preference datasets: builds preference data
- Preference generation → Hugging Face Hub: uploads datasets
- Preference datasets → Alignment runner: supplies training data
- Researcher → Alignment runner: runs alignment
- Alignment runner → DPO alignment: trains model
- DPO alignment → Language models: loads base model
- Alignment runner → Hugging Face Hub: publishes models
- Researcher → Baseline evaluation: runs evaluation
- Baseline evaluation → FOLIO corpus: reads validation split
- Baseline evaluation → Language models: generates stage answers
- Baseline evaluation → Hugging Face Hub: publishes answer datasets
- Researcher → LogicSim evaluation: evaluates outputs
- LogicSim evaluation → Hugging Face Hub: loads answer datasets
- LogicSim evaluation → Text similarity: compares answers
- Researcher → Ongoing experiments: runs experiments
- Ongoing experiments → Stage prompts: uses stage prompts
- Ongoing experiments → Generated answers: records results
- Ongoing experiments → Aligned model outputs: records alignment data
- Ongoing experiments → LogicSim+ metrics: evaluates generations
- LogicSim+ metrics → FOLIO corpus: compares FOLIO answers