# abdulbosidcoder/farmer architecture

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

- Interactive diagram: https://gitdiagram.com/abdulbosidcoder/farmer
- Repository: https://github.com/abdulbosidcoder/farmer

## Overview

Farmer is a Kaggriculture agent-training system: parameterized agents play self-play tournaments, receive fitness scores, and evolve across generations. The documented workflow promotes each generation’s champion to `avlod/`, admits it to `avlod/best/` only after a gate match, and carries an elite/mutated population forward. The graph follows README-described behavior; trainer internals were not sampled, so uncertain implementation-level links are omitted.

Main entry points: [`trainer/evolve.py`](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/trainer/evolve.py) (Evolution controller), [`trainer/common.py`](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/trainer/common.py) (Game utilities), [`avlod/population.json`](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/avlod/population.json) (Candidate population), [`agents/base/main.py`](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/agents/base/main.py) (Base agent template)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Training loop"]
  node_evolve["Evolution controller<br/>[evolve.py]"]
  node_common["Game utilities<br/>[common.py]"]
  node_population["Candidate population<br/>[population.json]"]
  node_fitness["Fitness scoring<br/>[evolve.py]"]
  node_selection["Selection and mutation<br/>[evolve.py]"]
end

subgraph group_agents["Agent strategies"]
  node_base["Base agent template<br/>[main.py]"]
  node_v8["V8 benchmark agent<br/>[main.py]"]
end

subgraph group_artifacts["Evolution artifacts"]
  node_champion["Generation champion"]
  node_best["Best gated agent<br/>[main.py]"]
  node_history["Progress history<br/>[history.csv]"]
end

subgraph group_runtime["Game runtime"]
  node_engine["Kaggriculture engine"]
end

node_operator(("Trainer operator"))
node_starter(("Starter opponent"))

node_operator -->|"starts training"| node_evolve
node_evolve -->|"loads or resumes"| node_population
node_evolve -->|"runs matches"| node_common
node_common -->|"plays games"| node_engine
node_evolve -->|"uses template"| node_base
node_evolve -.->|"benchmarks against"| node_v8
node_evolve -.->|"optionally challenges"| node_starter
node_evolve -->|"scores results"| node_fitness
node_fitness -->|"ranks candidates"| node_selection
node_selection -->|"forms next generation"| node_population
node_evolve -->|"saves champion"| node_champion
node_evolve -->|"gate-promotes winner"| node_best
node_evolve -->|"records progress"| node_history

click node_evolve "https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/trainer/evolve.py"
click node_common "https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/trainer/common.py"
click node_population "https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/avlod/population.json"
click node_fitness "https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/trainer/evolve.py"
click node_selection "https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/trainer/evolve.py"
click node_base "https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/agents/base/main.py"
click node_v8 "https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/agents/v8/main.py"
click node_champion "https://github.com/abdulbosidcoder/farmer/tree/claude/nice-babbage-k1tkdz/avlod"
click node_best "https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/avlod/best/main.py"
click node_history "https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/avlod/history.csv"

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_evolve,node_common,node_population,node_fitness,node_selection toneBlue
class node_base,node_v8 toneAmber
class node_champion,node_best,node_history toneMint
class node_engine toneRose
class node_operator,node_starter toneIndigo
```

## Components

### Training loop

- [Evolution controller](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/trainer/evolve.py): `trainer/evolve.py`
- [Game utilities](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/trainer/common.py): `trainer/common.py`
- [Candidate population](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/avlod/population.json): `avlod/population.json`
- [Fitness scoring](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/trainer/evolve.py): `trainer/evolve.py`
- [Selection and mutation](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/trainer/evolve.py): `trainer/evolve.py`

### Agent strategies

- [Base agent template](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/agents/base/main.py): `agents/base/main.py`
- [V8 benchmark agent](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/agents/v8/main.py): `agents/v8/main.py`

### Evolution artifacts

- [Generation champion](https://github.com/abdulbosidcoder/farmer/tree/claude/nice-babbage-k1tkdz/avlod): `avlod`
- [Best gated agent](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/avlod/best/main.py): `avlod/best/main.py`
- [Progress history](https://github.com/abdulbosidcoder/farmer/blob/claude/nice-babbage-k1tkdz/avlod/history.csv): `avlod/history.csv`

### Game runtime

- **Kaggriculture engine**

### Other components

- **Trainer operator**
- **Starter opponent**

## Connections

- Trainer operator → Evolution controller: starts training
- Evolution controller → Candidate population: loads or resumes
- Evolution controller → Game utilities: runs matches
- Game utilities → Kaggriculture engine: plays games
- Evolution controller → Base agent template: uses template
- Evolution controller → V8 benchmark agent: benchmarks against
- Evolution controller → Starter opponent: optionally challenges
- Evolution controller → Fitness scoring: scores results
- Fitness scoring → Selection and mutation: ranks candidates
- Selection and mutation → Candidate population: forms next generation
- Evolution controller → Generation champion: saves champion
- Evolution controller → Best gated agent: gate-promotes winner
- Evolution controller → Progress history: records progress