diff --git a/network-poc/frontend/public/GUIDE.md b/network-poc/frontend/public/GUIDE.md index 6ae8c96..078fe9a 100644 --- a/network-poc/frontend/public/GUIDE.md +++ b/network-poc/frontend/public/GUIDE.md @@ -230,6 +230,144 @@ mitä luokkia importata. --- +## Rakennuspalaset vs. vapaa generointi + +Kielimalli voi generoida koodia kahdella perustavanlaatuisesti eri tavalla. +Ymmärtäminen milloin kumpikin toimii on avain luotettavaan koodigenerointi-pipelineen. + +### Tapa 1: Vapaa generointi (naivi) + +LLM generoi jokaisen tiedoston tyhjästä. Prompti kuvaa mitä halutaan, +malli tuottaa koko tiedoston — importeista lähtien. + +```mermaid +flowchart LR + P["Prompti"] --> LLM1["LLM: models.py"] + LLM1 --> V1{"Validointi"} + V1 -->|virhe| LLM1 + V1 -->|ok| LLM2["LLM: schemas.py"] + LLM2 --> V2{"Validointi"} + V2 -->|virhe| LLM2 + V2 -->|ok| LLM3["LLM: main.py"] + LLM3 --> V3{"..."} + + style V1 fill:#1a1e2e,stroke:#f85149,color:#c9d1d9 + style V2 fill:#1a1e2e,stroke:#f85149,color:#c9d1d9 + style V3 fill:#1a1e2e,stroke:#f85149,color:#c9d1d9 +``` + +**Ongelma:** Pieni malli (0.5B–7B) tekee toistuvia rakenteellisia virheitä: + +| Virhe | Esiintymistiheys | Selitys | +|-------|:---:|------| +| Puuttuva import | ~60% | `from datetime import date` unohtuu | +| SQLite `connect_args` | ~80% | Malli ei muista SQLite-erityisyyttä | +| Väärä Enum-käyttö | ~50% | Sekoittaa `sqlalchemy.Enum` ja `enum.Enum` | +| Poetry pyproject.toml:ssa | ~40% | Malli suosii Poetryä vaikka ohje sanoo uv | +| Testit kopioivat koko appin | ~70% | Malli ei osaa importata, luo uudet reitit | + +Retry-loopilla (virhe → uusi yritys virheviestin kanssa) osa korjautuu, +mutta **sama malli toistaa samoja virheitä** koska ne johtuvat harjoitusdatasta. +7 tiedoston projekti vaatii 7–14 LLM-kutsua ja 80–120 sekuntia. + +### Tapa 2: Rakennuspalaset (template pipeline) + +LLM:ltä pyydetään **vain JSON-speksi** — entiteetit, kentät ja tyypit. +Koodi kootaan mekaanisesti valmiista pohjista joiden rakenne on todistettavasti +oikein. + +```mermaid +flowchart LR + P["Projektin kuvaus"] --> LLM["LLM: JSON-speksi"] + LLM --> S["{ entities: [...] }"] + S --> T1["Template: models.py"] + S --> T2["Template: schemas.py"] + S --> T3["Template: main.py"] + S --> T4["Template: test_main.py"] + S --> T5["Template: Dockerfile"] + T1 & T2 & T3 & T4 & T5 --> D["Docker build + pytest"] + + style LLM fill:#1a1e2e,stroke:#d29922,color:#c9d1d9 + style S fill:#1a1e2e,stroke:#3fb950,color:#c9d1d9 + style D fill:#1a1e2e,stroke:#58a6ff,color:#c9d1d9 +``` + +**Idea:** Malli on hyvä päättämään *mitä* (entiteetit, kentät), mutta huono +muistamaan *miten* (importit, engine setup, testikonfiguraatio). Annetaan +mallin tehdä se missä se on hyvä, ja hoidetaan loput mekaanisesti. + +### LLM:n ainoa tehtävä + +Malli tuottaa JSON-rakenteen kuten: + +```json +{ + "project_name": "todo-app", + "entities": [ + { + "name": "Todo", + "table_name": "todos", + "fields": [ + {"name": "title", "sa_type": "String(255)", "py_type": "str", "nullable": false}, + {"name": "due_date", "sa_type": "Date", "py_type": "date | None", "nullable": true}, + {"name": "status", "sa_type": "String(20)", "py_type": "str", "default": "pending"} + ] + } + ], + "extra_imports": ["from datetime import date"] +} +``` + +Tämä on yksinkertainen tehtävä jossa pienikin malli onnistuu luotettavasti: +entiteettien tunnistus projektin kuvauksesta ja kenttätyyppien valinta. + +### Template täyttää loput + +Jokainen template on kuin madlib — aukot täytetään speksin datalla: + +**models.py template (yksinkertaistettu):** +```python +from sqlalchemy import create_engine, Column, Integer, {sa_types} +# ... aina samat importit, engine setup, SessionLocal ... + +class {entity.name}(Base): + __tablename__ = "{entity.table_name}" + id = Column(Integer, primary_key=True, index=True) + {field.name} = Column({field.sa_type}, nullable={field.nullable}) + # ... jokainen kenttä speksistä ... +``` + +Tulos: importit ovat aina oikein, `connect_args` on aina mukana, +testit importoivat aina `main.py`:stä eivätkä kopioi sitä. + +### Vertailu: mittaustulokset + +| | Vapaa generointi | Rakennuspalaset | +|---|:---:|:---:| +| LLM-kutsuja | 7–14 | **1** | +| Aika | 80–120s | **~20s** | +| Syntaksi OK | ~70% | **100%** | +| Docker build | vaihteleva | **100%** | +| Pytest läpi | 0% | **100%** | +| API toimii | ~30% | **100%** | + +### Milloin kumpikin toimii + +**Rakennuspalaset** kun: +- Projektin rakenne on tunnettu (FastAPI + SQLAlchemy CRUD) +- Laatu ja luotettavuus ovat tärkeitä +- Malli on pieni (0.5B–7B) + +**Vapaa generointi** kun: +- Projektin rakenne on epätavallinen +- Tarvitaan custom-logiikkaa jota template ei kata +- Malli on riittävän iso (>70B tai pilvi-API) + +Paras lopputulos syntyy yhdistelmällä: **rakennuspalaset perusrakenteelle, +vapaa generointi business-logiikalle**. + +--- + ## Laadun parantaminen ### 1. Isompi malli (suurin vaikutus) diff --git a/network-poc/frontend/src/components/AgentBar.astro b/network-poc/frontend/src/components/AgentBar.astro index 39c39fe..599592d 100644 --- a/network-poc/frontend/src/components/AgentBar.astro +++ b/network-poc/frontend/src/components/AgentBar.astro @@ -1,37 +1,37 @@ - +
- -
+ +
+
- Lisää + Add
- +