# firelex/jeff architecture

> Architecture diagram of the GitHub repository firelex/jeff, 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/firelex/jeff
- Repository: https://github.com/firelex/jeff

## Overview

Jeff is a local, fine-tuned decision model: a caller submits a situation and questions, and the serving API returns calibrated option probabilities and choices. The broader repository supports assembling and authoring training data, training checkpoints, evaluating them, and exercising decisions in games. The serving and game call paths are sampled; other subsystem links reflect README-described capabilities and module names, since their implementation excerpts were not provided.

Main entry points: [`src/jeff/server.py`](https://github.com/firelex/jeff/blob/main/src/jeff/server.py) (Decision API), [`src/jeff/games/__main__.py`](https://github.com/firelex/jeff/blob/main/src/jeff/games/__main__.py) (Game runner), [`src/jeff/model.py`](https://github.com/firelex/jeff/blob/main/src/jeff/model.py) (Decision model), [`src/jeff/train.py`](https://github.com/firelex/jeff/blob/main/src/jeff/train.py) (Fine-tuning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serve["Decision serving"]
  node_server["Decision API<br/>[server.py]"]
  node_checkpoint["Model checkpoint"]
  node_answer["Calibrated answers"]
end

subgraph group_model["Model runtime"]
  node_decision_model["Decision model<br/>[model.py]"]
  node_encoder["Input encoding<br/>[encoder.py]"]
  node_decoder["Model decoding<br/>[decoder.py]"]
end

subgraph group_training["Training data and models"]
  node_data["Public data prep<br/>[data.py]"]
  node_synthetic["Synthetic authoring<br/>[sft_synthetic.py]"]
  node_pipeline["Training schedule<br/>[sft_pipeline.py]"]
  node_trainer["Fine-tuning<br/>[train.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluate["Model evaluation<br/>[evaluate.py]"]
  node_jevbench["JevBench<br/>[jevbench.py]"]
  node_legalbench["LegalBench<br/>[legalbench.py]"]
  node_codecontests["CodeContests<br/>[codecontests.py]"]
end

subgraph group_games["Game experiments"]
  node_game_cli["Game runner<br/>[__main__.py]"]
  node_game_client["Game client<br/>[common.py]"]
  node_game["Game environments<br/>[frogger.py]"]
  node_pacman["Pac-Man<br/>[pacman.py]"]
  node_doom["Doom<br/>[doom.py]"]
end

node_caller(("API caller"))
node_external_author(("Open-model author"))

node_caller -->|"submits questions"| node_server
node_server -->|"calls prediction"| node_decision_model
node_server -->|"loads weights"| node_checkpoint
node_decision_model -->|"encodes input"| node_encoder
node_decision_model -->|"runs inference"| node_decoder
node_server -->|"returns probabilities"| node_answer
node_data -->|"prepares examples"| node_trainer
node_external_author -.->|"supplies generations"| node_synthetic
node_synthetic -->|"authors examples"| node_pipeline
node_pipeline -->|"schedules tranches"| node_trainer
node_trainer -->|"writes weights"| node_checkpoint
node_evaluate -->|"evaluates model"| node_checkpoint
node_jevbench -->|"benchmarks model"| node_checkpoint
node_legalbench -->|"benchmarks model"| node_checkpoint
node_codecontests -->|"benchmarks model"| node_checkpoint
node_game_cli -->|"runs episodes"| node_game
node_game_cli -->|"runs episodes"| node_pacman
node_game_cli -->|"runs episodes"| node_doom
node_game_cli -->|"selects player"| node_game_client
node_game_client -.->|"requests decisions"| node_server

click node_server "https://github.com/firelex/jeff/blob/main/src/jeff/server.py"
click node_decision_model "https://github.com/firelex/jeff/blob/main/src/jeff/model.py"
click node_encoder "https://github.com/firelex/jeff/blob/main/src/jeff/encoder.py"
click node_decoder "https://github.com/firelex/jeff/blob/main/src/jeff/decoder.py"
click node_data "https://github.com/firelex/jeff/blob/main/src/jeff/data.py"
click node_synthetic "https://github.com/firelex/jeff/blob/main/src/jeff/sft_synthetic.py"
click node_pipeline "https://github.com/firelex/jeff/blob/main/src/jeff/sft_pipeline.py"
click node_trainer "https://github.com/firelex/jeff/blob/main/src/jeff/train.py"
click node_evaluate "https://github.com/firelex/jeff/blob/main/src/jeff/evaluate.py"
click node_jevbench "https://github.com/firelex/jeff/blob/main/src/jeff/jevbench.py"
click node_legalbench "https://github.com/firelex/jeff/blob/main/src/jeff/legalbench.py"
click node_codecontests "https://github.com/firelex/jeff/blob/main/src/jeff/codecontests.py"
click node_game_cli "https://github.com/firelex/jeff/blob/main/src/jeff/games/__main__.py"
click node_game_client "https://github.com/firelex/jeff/blob/main/src/jeff/games/common.py"
click node_game "https://github.com/firelex/jeff/blob/main/src/jeff/games/frogger.py"
click node_pacman "https://github.com/firelex/jeff/blob/main/src/jeff/games/pacman.py"
click node_doom "https://github.com/firelex/jeff/blob/main/src/jeff/games/doom.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_server,node_checkpoint,node_answer toneBlue
class node_decision_model,node_encoder,node_decoder toneAmber
class node_data,node_synthetic,node_pipeline,node_trainer,node_caller toneMint
class node_evaluate,node_jevbench,node_legalbench,node_codecontests toneRose
class node_game_cli,node_game_client,node_game,node_pacman,node_doom,node_external_author toneIndigo
```

## Components

### Decision serving

- [Decision API](https://github.com/firelex/jeff/blob/main/src/jeff/server.py): `src/jeff/server.py`
- **Model checkpoint**
- **Calibrated answers**

### Model runtime

- [Decision model](https://github.com/firelex/jeff/blob/main/src/jeff/model.py): `src/jeff/model.py`
- [Input encoding](https://github.com/firelex/jeff/blob/main/src/jeff/encoder.py): `src/jeff/encoder.py`
- [Model decoding](https://github.com/firelex/jeff/blob/main/src/jeff/decoder.py): `src/jeff/decoder.py`

### Training data and models

- [Public data prep](https://github.com/firelex/jeff/blob/main/src/jeff/data.py): `src/jeff/data.py`
- [Synthetic authoring](https://github.com/firelex/jeff/blob/main/src/jeff/sft_synthetic.py): `src/jeff/sft_synthetic.py`
- [Training schedule](https://github.com/firelex/jeff/blob/main/src/jeff/sft_pipeline.py): `src/jeff/sft_pipeline.py`
- [Fine-tuning](https://github.com/firelex/jeff/blob/main/src/jeff/train.py): `src/jeff/train.py`

### Evaluation

- [Model evaluation](https://github.com/firelex/jeff/blob/main/src/jeff/evaluate.py): `src/jeff/evaluate.py`
- [JevBench](https://github.com/firelex/jeff/blob/main/src/jeff/jevbench.py): `src/jeff/jevbench.py`
- [LegalBench](https://github.com/firelex/jeff/blob/main/src/jeff/legalbench.py): `src/jeff/legalbench.py`
- [CodeContests](https://github.com/firelex/jeff/blob/main/src/jeff/codecontests.py): `src/jeff/codecontests.py`

### Game experiments

- [Game runner](https://github.com/firelex/jeff/blob/main/src/jeff/games/__main__.py): `src/jeff/games/__main__.py`
- [Game client](https://github.com/firelex/jeff/blob/main/src/jeff/games/common.py): `src/jeff/games/common.py`
- [Game environments](https://github.com/firelex/jeff/blob/main/src/jeff/games/frogger.py): `src/jeff/games/frogger.py`
- [Pac-Man](https://github.com/firelex/jeff/blob/main/src/jeff/games/pacman.py): `src/jeff/games/pacman.py`
- [Doom](https://github.com/firelex/jeff/blob/main/src/jeff/games/doom.py): `src/jeff/games/doom.py`

### Other components

- **API caller**
- **Open-model author**

## Connections

- API caller → Decision API: submits questions
- Decision API → Decision model: calls prediction
- Decision API → Model checkpoint: loads weights
- Decision model → Input encoding: encodes input
- Decision model → Model decoding: runs inference
- Decision API → Calibrated answers: returns probabilities
- Public data prep → Fine-tuning: prepares examples
- Open-model author → Synthetic authoring: supplies generations
- Synthetic authoring → Training schedule: authors examples
- Training schedule → Fine-tuning: schedules tranches
- Fine-tuning → Model checkpoint: writes weights
- Model evaluation → Model checkpoint: evaluates model
- JevBench → Model checkpoint: benchmarks model
- LegalBench → Model checkpoint: benchmarks model
- CodeContests → Model checkpoint: benchmarks model
- Game runner → Game environments: runs episodes
- Game runner → Pac-Man: runs episodes
- Game runner → Doom: runs episodes
- Game runner → Game client: selects player
- Game client → Decision API: requests decisions