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).

Benchmark — kehityksen todentaminen

Ilman kunnollista pisteytystä ja historiaa ei voi todentaa kehitystä. Benchmark-järjestelmä tarvitsee kolme kerrosta: metriikat, vaikeustasot ja historiavertailu.

Metriikat

Yksittäinen "PASS/FAIL" ei riitä. Jokainen ajo pisteytetään moniulotteisesti:

Metriikka	Mitä mittaa	Pisteytys
Parsittavuus	Tuottiko malli kaikki 5 tiedostoa oikeilla markereilla?	0–5 (tiedostoa)
Syntaksi	Parsitaanko koodi virheettä?	0–4 (.py-tiedostot)
Importit	Ovatko kaikki importit resolvable?	0/1 per tiedosto
Testit	Pytest pass rate	passed / total (0.0–1.0)
Korjauskierrokset	Montako korjausta tarvittiin?	0 = paras, >2 = huono
Token-tehokkuus	Tokenia per läpäisty testi	pienempi = parempi
Nopeus	tok/s ja kokonaisaika	isompi tok/s = parempi
Varoitukset	Deprecation warnings, style issues	0 = paras

Kokonaispistemäärä (0–100):

score = (
    parsittavuus/5 * 15 +       # 15p: tiedostot syntyvät
    syntaksi/4 * 15 +            # 15p: koodi parsitaan
    testit * 40 +                # 40p: testit menevät läpi (tärkein)
    (1 - korjaukset/max) * 10 +  # 10p: ei tarvitse korjauksia
    tehokkuus_norm * 10 +        # 10p: vähän tokeneita per testi
    nopeus_norm * 10             # 10p: nopea generointi
)

Testien paino on 40% koska toimiva koodi on tärkein. Parsittavuus ja syntaksi ovat "pääsyvaatimuksia" — ilman niitä testejä ei voi edes ajaa.

Vaikeustasot

Kolme nykyistä skenaariota (todo, users, blog) ovat kaikki samaa tasoa. Kehityksen mittaamiseen tarvitaan portaikko:

Taso 1 — Perus-CRUD (nykyiset)

• Yksi entiteetti, ei relaatioita
• Esim. todo, users
• Odotettu tulos: 100% kaikilla kelvollisilla malleilla

Taso 2 — Relaatiot (nykyinen blog)

• 2–3 entiteettiä, foreign key -viittaukset
• Esim. blog (author → post), kirjasto (author → book)
• Haaste: relaatioiden oikea käsittely, cascade

Taso 3 — Liiketoimintalogiikka

• Validointisääntöjä, tilasiirtymiä, laskentaa
• Esim. verkkokauppa (tuote → tilaus → tilausrivi, varastosaldo, hintalaskenta)
• Haaste: pelkkä CRUD ei riitä, tarvitaan custom-endpointeja

Taso 4 — Kehittyneet patternit

• Autentikointi, middleware, taustatehtävät, WebSocket
• Esim. chat-sovellus (käyttäjä → huone → viesti, reaaliaikainen, online-status)
• Haaste: arkkitehtuuriosaamisesta, ei vain tietomallista

Skenaariot per taso:

SCENARIOS = [
    # Taso 1 — Perus-CRUD
    {"id": "todo",      "level": 1, "prompt": "Todo-sovellus: tehtävien hallinta, deadline, prioriteetti ja status"},
    {"id": "users",     "level": 1, "prompt": "REST API käyttäjähallinnalle SQLite-tietokannalla"},
    {"id": "notes",     "level": 1, "prompt": "Muistiinpanosovellus: otsikko, sisältö, tagit, luontipäivä"},

    # Taso 2 — Relaatiot
    {"id": "blog",      "level": 2, "prompt": "Blogi-API: kirjoittajat ja artikkelit, julkaisupäivämäärä ja status"},
    {"id": "library",   "level": 2, "prompt": "Kirjasto-API: kirjailijat, kirjat ja lainaukset, palautuspäivä ja sakko"},
    {"id": "school",    "level": 2, "prompt": "Kouluhallinto: opettajat, kurssit ja ilmoittautumiset, arvosanat"},

    # Taso 3 — Liiketoimintalogiikka
    {"id": "shop",      "level": 3, "prompt": "Verkkokauppa: tuotteet, tilaukset ja tilausrivit, varastosaldo vähenee tilauksessa, kokonaishinta lasketaan automaattisesti"},
    {"id": "booking",   "level": 3, "prompt": "Varausjärjestelmä: resurssit ja varaukset, päällekkäiset varaukset estetään, peruutus vapauttaa ajan"},
    {"id": "project",   "level": 3, "prompt": "Projektinhallinta: projektit, tehtävät ja kommentit, tehtävän status-siirtymät (todo→doing→done), projektin edistymisprosentti lasketaan tehtävistä"},
]

Historiavertailu

Tulokset tallennetaan aikasarjana jotta kehitys näkyy:

benchmark-history/
├── 2026-04-14_1200_v1.json    ← ensimmäinen ajo
├── 2026-04-14_1500_v2.json    ← prompti paranneltu
├── 2026-04-15_0900_v3.json    ← few-shot lisätty
└── latest.json                ← symlink uusimpaan

Jokainen tallennus sisältää:

{
    "version": "v3",
    "timestamp": "2026-04-15T09:00:00Z",
    "prompts_hash": "a3f2c1...",
    "results": [
        {
            "model": "qwen3-coder-next",
            "scenario": "todo",
            "level": 1,
            "score": 85,
            "metrics": {
                "parsability": 5,
                "syntax": 4,
                "tests_passed": 6,
                "tests_total": 6,
                "fix_rounds": 0,
                "tokens": 2100,
                "tok_per_sec": 72,
                "warnings": 0
            }
        }
    ],
    "summary": {
        "avg_score": 72,
        "pass_rate": 0.67,
        "by_level": {"1": 95, "2": 72, "3": 48}
    }
}

Kehitysraportti (automaattinen vertailu edelliseen):

╔═══════════════════════════════════════╗
║  Kehitysraportti v2 → v3             ║
╠═══════════════════════════════════════╣
║  Kokonaispistemäärä:  62 → 72 (+10)  ║
║  Pass rate:          44% → 67% (+23) ║
║  Taso 1:              80 → 95 (+15)  ║
║  Taso 2:              60 → 72 (+12)  ║
║  Taso 3:              45 → 48 (+3)   ║
║                                       ║
║  Parantunut:  pyproject-muoto ✓      ║
║  Parantunut:  import-ongelmat ✓      ║
║  Ennallaan:   liiketoimintalogiikka  ║
╚═══════════════════════════════════════╝

Regressiotunnistus

Jos promptimuutos parantaa yhtä skenaariota mutta rikkoo toisen, se pitää havaita:

• Jokaisella ajolla verrataan kaikkia skenaarioita edelliseen
• Jos mikä tahansa skenaario laskee >10 pistettä → varoitus
• Jos taso 1 (perus-CRUD) laskee → esto (perustason pitää aina toimia)

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.