jaakko
8f154a578c
Moniulotteinen pisteytys (0-100), portaittaiset vaikeustasot (CRUD → relaatiot → liiketoimintalogiikka → kehittyneet patternit), historiavertailu ja regressiotunnistus.
291 lines
12 KiB
Markdown
291 lines
12 KiB
Markdown
# 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:**
|
||
|
||
```python
|
||
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ää:**
|
||
```json
|
||
{
|
||
"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.
|