# ddidacus/loco-llm architecture

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

- Interactive diagram: https://gitdiagram.com/ddidacus/loco-llm
- Repository: https://github.com/ddidacus/loco-llm

## Overview

LoCo-LMs fine-tunes and evaluates language models with neuro-symbolic losses intended to improve factual and logical consistency. The main workflow is a user-supplied configuration and constraint choice entering `run.py`, which assembles the model, constraint manager, and trainer; training combines model belief probabilities with symbolic constraint loss, while evaluation scores consistency and related metrics. Data preparation supports BeliefBank and ConceptNet; README also documents EntailmentBank evaluation. The alternative-dataset scripts and some trainer wiring are not sampled, so their internal call paths are left unspecified.

Main entry points: [`run.py`](https://github.com/ddidacus/loco-llm/blob/main/run.py) (Run entry point), [`models/loco/trainer.py`](https://github.com/ddidacus/loco-llm/blob/main/models/loco/trainer.py) (Trainer), [`models/loco/model.py`](https://github.com/ddidacus/loco-llm/blob/main/models/loco/model.py) (QA language model), [`utils/eval.py`](https://github.com/ddidacus/loco-llm/blob/main/utils/eval.py) (Consistency metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run orchestration"]
  node_config["Experiment configs"]
  node_runner["Run entry point<br/>[run.py]"]
end

subgraph group_data["Fact and rule data"]
  node_beliefbank["BeliefBank data<br/>[beliefbank.py]"]
  node_conceptnet["ConceptNet data<br/>[conceptnet.py]"]
  node_dataset_core["Dataset primitives<br/>[dataset.py]"]
  node_conceptnet_extract["ConceptNet extraction<br/>[get_conceptnet.py]"]
end

subgraph group_training["Neuro-symbolic training"]
  node_model["QA language model<br/>[model.py]"]
  node_prompts["Prompt formats<br/>[prompts.py]"]
  node_trainer["Trainer<br/>[trainer.py]"]
  node_constraints["Constraint manager<br/>[constraints.py]"]
  node_training_utils["Training utilities<br/>[training.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_metrics["Consistency metrics<br/>[eval.py]"]
  node_entailment_eval["EntailmentBank evaluation"]
  node_beliefbank_eval["BeliefBank evaluation"]
end

node_user(("Experiment user"))
node_hf["Transformers model source"]
node_wandb["Weights &amp; Biases"]

node_user -->|"starts run"| node_runner
node_runner -->|"reads settings"| node_config
node_runner -->|"constructs model"| node_model
node_runner -->|"constructs manager"| node_constraints
node_runner -->|"starts task"| node_trainer
node_runner -.->|"logs run"| node_wandb
node_model -->|"loads model"| node_hf
node_model -->|"formats prompts"| node_prompts
node_trainer -->|"queries beliefs"| node_model
node_trainer -->|"computes loss"| node_constraints
node_trainer -->|"prepares data"| node_beliefbank
node_trainer -->|"scores results"| node_metrics
node_beliefbank -->|"uses samples"| node_dataset_core
node_conceptnet -->|"uses samples"| node_dataset_core
node_conceptnet_extract -.->|"supports extraction"| node_conceptnet
node_entailment_eval -.->|"evaluates consistency"| node_metrics
node_beliefbank_eval -.->|"evaluates consistency"| node_metrics

click node_config "https://github.com/ddidacus/loco-llm/tree/main/configs"
click node_runner "https://github.com/ddidacus/loco-llm/blob/main/run.py"
click node_beliefbank "https://github.com/ddidacus/loco-llm/blob/main/dataset/beliefbank.py"
click node_conceptnet "https://github.com/ddidacus/loco-llm/blob/main/dataset/conceptnet.py"
click node_dataset_core "https://github.com/ddidacus/loco-llm/blob/main/dataset/dataset.py"
click node_model "https://github.com/ddidacus/loco-llm/blob/main/models/loco/model.py"
click node_prompts "https://github.com/ddidacus/loco-llm/blob/main/models/loco/prompts.py"
click node_trainer "https://github.com/ddidacus/loco-llm/blob/main/models/loco/trainer.py"
click node_constraints "https://github.com/ddidacus/loco-llm/blob/main/utils/constraints.py"
click node_training_utils "https://github.com/ddidacus/loco-llm/blob/main/utils/training.py"
click node_metrics "https://github.com/ddidacus/loco-llm/blob/main/utils/eval.py"
click node_entailment_eval "https://github.com/ddidacus/loco-llm/blob/main/scripts/experiments/eval_entailmentbank.py"
click node_beliefbank_eval "https://github.com/ddidacus/loco-llm/blob/main/scripts/experiments/eval_beliefbank_binary.py"
click node_conceptnet_extract "https://github.com/ddidacus/loco-llm/blob/main/scripts/get_conceptnet.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_config,node_runner,node_user toneBlue
class node_beliefbank,node_conceptnet,node_dataset_core,node_conceptnet_extract toneAmber
class node_model,node_prompts,node_trainer,node_constraints,node_training_utils toneMint
class node_metrics,node_entailment_eval,node_beliefbank_eval toneRose
class node_hf,node_wandb toneIndigo
```

## Components

### Run orchestration

- [Experiment configs](https://github.com/ddidacus/loco-llm/tree/main/configs): `configs`
- [Run entry point](https://github.com/ddidacus/loco-llm/blob/main/run.py): `run.py`

### Fact and rule data

- [BeliefBank data](https://github.com/ddidacus/loco-llm/blob/main/dataset/beliefbank.py): `dataset/beliefbank.py`
- [ConceptNet data](https://github.com/ddidacus/loco-llm/blob/main/dataset/conceptnet.py): `dataset/conceptnet.py`
- [Dataset primitives](https://github.com/ddidacus/loco-llm/blob/main/dataset/dataset.py): `dataset/dataset.py`
- [ConceptNet extraction](https://github.com/ddidacus/loco-llm/blob/main/scripts/get_conceptnet.py): `scripts/get_conceptnet.py`

### Neuro-symbolic training

- [QA language model](https://github.com/ddidacus/loco-llm/blob/main/models/loco/model.py): `models/loco/model.py`
- [Prompt formats](https://github.com/ddidacus/loco-llm/blob/main/models/loco/prompts.py): `models/loco/prompts.py`
- [Trainer](https://github.com/ddidacus/loco-llm/blob/main/models/loco/trainer.py): `models/loco/trainer.py`
- [Constraint manager](https://github.com/ddidacus/loco-llm/blob/main/utils/constraints.py): `utils/constraints.py`
- [Training utilities](https://github.com/ddidacus/loco-llm/blob/main/utils/training.py): `utils/training.py`

### Evaluation

- [Consistency metrics](https://github.com/ddidacus/loco-llm/blob/main/utils/eval.py): `utils/eval.py`
- [EntailmentBank evaluation](https://github.com/ddidacus/loco-llm/blob/main/scripts/experiments/eval_entailmentbank.py): `scripts/experiments/eval_entailmentbank.py`
- [BeliefBank evaluation](https://github.com/ddidacus/loco-llm/blob/main/scripts/experiments/eval_beliefbank_binary.py): `scripts/experiments/eval_beliefbank_binary.py`

### Other components

- **Experiment user**
- **Transformers model source**
- **Weights & Biases**

## Connections

- Experiment user → Run entry point: starts run
- Run entry point → Experiment configs: reads settings
- Run entry point → QA language model: constructs model
- Run entry point → Constraint manager: constructs manager
- Run entry point → Trainer: starts task
- Run entry point → Weights & Biases: logs run
- QA language model → Transformers model source: loads model
- QA language model → Prompt formats: formats prompts
- Trainer → QA language model: queries beliefs
- Trainer → Constraint manager: computes loss
- Trainer → BeliefBank data: prepares data
- Trainer → Consistency metrics: scores results
- BeliefBank data → Dataset primitives: uses samples
- ConceptNet data → Dataset primitives: uses samples
- ConceptNet extraction → ConceptNet data: supports extraction
- EntailmentBank evaluation → Consistency metrics: evaluates consistency
- BeliefBank evaluation → Consistency metrics: evaluates consistency