From 7221f5e92065d9eb5c4bc9ae07f43d53303e936f Mon Sep 17 00:00:00 2001 From: jaakko Date: Tue, 14 Apr 2026 07:14:17 +0300 Subject: [PATCH] SUPERAGENTS.md: itseoppivan koodausagentin arkkitehtuuri ja toteutussuunnitelma --- network-poc/SUPERAGENTS.md | 141 +++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 network-poc/SUPERAGENTS.md diff --git a/network-poc/SUPERAGENTS.md b/network-poc/SUPERAGENTS.md new file mode 100644 index 0000000..80c3981 --- /dev/null +++ b/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.