# Superagentti — itseoppiva koodausjärjestelmä

Visio: järjestelmä joka **oppii joka iteraatiolla** ja kehittyy lopulta superagentiksi ohjelmointitehtäviin.

## Miksi tämä on realistista

Benchmark-järjestelmä (`model-benchmark.mjs`) tarjoaa jo valmiin **fitness-funktion**: pytest-tulokset antavat yksiselitteisen signaalin (6/6 vs 0/6). Se on itseoppivan järjestelmän vaikein osa — ja se on valmis.

Puuttuvat palaset ovat analysoija ja promptin evoluutio.

## Arkkitehtuuri

```
    ┌──────────────┐
    │  Benchmark   │ ← nykyinen model-benchmark.mjs
    │  (suorita)   │
    └──────┬───────┘
           │ results.json + _pytest.txt + _code_raw.txt
           ▼
    ┌──────────────┐
    │  Analysoija  │ ← luokittele virheet automaattisesti
    │              │   "pyproject: poetry vs pep621"
    │              │   "testi kutsuu olematonta endpointia"
    └──────┬───────┘
           │ virheluokat + korjausohjeet
           ▼
    ┌──────────────┐
    │  Promptin    │ ← muokkaa prompteja tulosten perusteella
    │  evoluutio   │   lisää sääntöjä, few-shot-esimerkkejä
    └──────┬───────┘
           │ parannetut promptit
           ▼
    ┌──────────────┐
    │  Benchmark   │ ← aja uudestaan parannetuilla prompteilla
    │  (uusinta)   │
    └──────────────┘
         ↻ toista kunnes 100%
```

## Toteutustasot

### Taso 1 — Virhepohjainen promptin korjaus

Helpoin ja nopein toteuttaa. Pytest-virheistä tunnistetaan virheluokka ja lisätään sääntö promptiin automaattisesti.

**Esimerkki:**
- Benchmark tuottaa: `pyproject.toml` käyttää Poetry-muotoa
- Analysoija tunnistaa: `[tool.poetry]` → virheluokka `wrong-pyproject-format`
- Evoluutio lisää promptiin: `"pyproject.toml MUST use PEP 621 [project] format, NOT [tool.poetry]"`
- Seuraava ajo onnistuu

**Virheluokkia** (havaittu ensimmäisistä ajoista):
| Virheluokka | Kuvaus | Promptikorjaus |
|-------------|--------|----------------|
| `wrong-pyproject-format` | Poetry-muoto PEP 621:n sijaan | Lisää sääntö: "use [project], not [tool.poetry]" |
| `missing-endpoint-test` | Testi kutsuu endpointia jota ei ole | Lisää sääntö: "only test endpoints defined in main.py" |
| `missing-import` | Puuttuva import | Korjaussilmukan asia (taso 4) |
| `unique-constraint` | Testi ei käsittele duplikaatteja | Lisää sääntö: "use unique test data per test" |

### Taso 2 — Few-shot oppiminen

Onnistuneet generoinnit talteen "kultaisiksi esimerkeiksi" joita syötetään tuleviin prompteihin.

**Miten toimii:**
1. Benchmark-ajo tuottaa 100% PASS -tuloksen (esim. blog-skenaario)
2. Generoidut tiedostot tallennetaan `golden-examples/blog/` -hakemistoon
3. Seuraavissa ajoissa CODE_SYSTEM-promptiin liitetään: "Tässä on toimiva blog-projekti, generoi vastaava todo-projektille"
4. Malli näkee konkreettisesti mitä odotetaan

**Etu:** Laatu nousee nopeasti koska malli saa tarkan esimerkin odotetusta rakenteesta — tiedostomarkerit, importit, pyproject-muoto.

### Taso 3 — Monimalliorkesteri

Eri malli eri vaiheeseen. Benchmark-data kertoo mikä malli on missä paras.

**Esimerkki:**
| Vaihe | Paras malli | Perustelu |
|-------|-------------|-----------|
| Vaatimukset | qwen3:30b | Nopea, hyvä suomenkielinen ymmärrys |
| JSON-speksi | gemma4:31b | Tarkka strukturoitu output |
| Koodigenerointi | qwen3-coder-next | Suunniteltu koodaukseen |
| Korjaus | devstral:24b | Hyvä virheiden analysointi |

**Kahden GPU:n hyödyntäminen:** Vaiheita voi ajaa rinnakkain eri malleilla eri GPU:illa. Esim. speksi GPU1:llä samalla kun edellinen koodi validoidaan GPU2:lla.

### Taso 4 — Itsekorjaava agenttilooppi

Nykyinen korjaussilmukka (max 2 kierrosta) käyttää staattista validaattoria. Taso 4 syöttää **oikean pytest-virheviestin** mallille.

**Nykyinen (rajoitettu):**
```
validaattori → "ISSUE: relatiivinen import" → LLM korjaa → aja uudestaan
```

**Taso 4 (itsekorjaava):**
```
pytest → "IntegrityError: UNIQUE constraint failed" → LLM analysoi → korjaa → pytest → ✓
```

**Iteraatiolooppi:**
1. Aja pytest
2. Jos virheitä: syötä virheilmoitus + koodi mallille
3. Malli korjaa koodin
4. Aja pytest uudestaan
5. Toista kunnes PASS tai max N kierrosta

Tämä on lähellä sitä miten Claude Code ja Cursor toimivat sisäisesti.

### Taso 5 — Promptin evoluutio (geneettinen)

Automaattinen promptien optimointi geneettisellä algoritmilla.

**Algoritmi:**
1. Generoi N promptivarianttia (mutaatiot: lisää sääntö, poista sääntö, muokkaa sanamuotoa)
2. Aja benchmark jokaisella variantilla
3. Pisteytä: `fitness = testsPassed / testsTotal`
4. Valitse parhaat (top-K)
5. Risteytä ja mutaatioi uusia variantteja
6. Toista

**Mutaatio-operaatiot:**
- `add_rule`: Lisää uusi sääntö promptiin (peräisin virheanalyysistä)
- `remove_rule`: Poista sääntö joka ei vaikuta tuloksiin
- `rephrase`: Muotoile sääntö uudelleen (esim. "MUST" → "ALWAYS", esimerkin lisäys)
- `reorder`: Vaihda sääntöjen järjestystä (promptin alku painottuu enemmän)

## Superagentti syntyy kun

Yhdistetään kaikki tasot: järjestelmä **valitsee parhaan mallin tehtävään** (taso 3), **käyttää opittuja prompteja** (taso 2), **korjaa virheensä itse** (taso 4), ja **parantaa promptejaan joka kierroksella** (taso 5).

## Toteutusjärjestys

```
Taso 1  ██████████  ← aloita tästä (päivä)
Taso 4  ████████    ← seuraavaksi (päivä)
Taso 2  ██████      ← golden examples (päivä)
Taso 3  ████        ← monimalli (2-3 päivää)
Taso 5  ██          ← evoluutio (viikko)
```

Taso 1 antaa suurimman hyödyn nopeimmin. Taso 4 (itsekorjaava looppi) on toiseksi tärkein koska se moninkertaistaa onnistumisprosentin. Taso 5 on pitkän aikavälin investointi.