SUPERAGENTS.md: itseoppivan koodausagentin arkkitehtuuri ja toteutussuunnitelma

network-poc/SUPERAGENTS.md

@@ -0,0 +1,141 @@
+# 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.