agentic-studio/network-poc/SUPERAGENTS.md

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.