diff --git a/network-poc/frontend/public/GUIDE.md b/network-poc/frontend/public/GUIDE.md index 078fe9a..7eace9a 100644 --- a/network-poc/frontend/public/GUIDE.md +++ b/network-poc/frontend/public/GUIDE.md @@ -321,35 +321,79 @@ Malli tuottaa JSON-rakenteen kuten: Tämä on yksinkertainen tehtävä jossa pienikin malli onnistuu luotettavasti: entiteettien tunnistus projektin kuvauksesta ja kenttätyyppien valinta. +Speksi sisältää myös **relaatiot** entiteettien välillä: + +```json +{ + "entities": [ + {"name": "Author", "table_name": "authors", "fields": [...]}, + {"name": "Book", "table_name": "books", "fields": [ + {"name": "title", "sa_type": "String(255)", "py_type": "str", "nullable": false}, + {"name": "author_id", "sa_type": "Integer", "py_type": "int", "nullable": false} + ]} + ], + "relationships": [ + {"from": "Book", "field": "author_id", "to": "Author", "type": "many-to-one"} + ] +} +``` + +Templateit generoivat relaatioista automaattisesti: +- `ForeignKey('authors.id')` models.py:hin +- `relationship("Book", back_populates="author")` molempiin suuntiin +- `BookDetail`-schema jossa author-data mukana +- `GET /authors/{id}/books/` nested endpoint +- FK-validointi: 404 jos parent-entiteettiä ei ole + +### Architect-agentti: speksin laatu ratkaisee + +Arkkitehti on **kriittisin agentti** koko pipelinessa. Jos speksi on hyvä +(oikeat entiteetit, kentät, relaatiot), kaikki muu seuraa automaattisesti. +Jos speksi on huono, templateitkaan eivät pelasta. + +Arkkitehtia ohjataan: +1. **Chain-of-thought**: "Mieti ensin entiteetit, sitten kentät, sitten relaatiot" +2. **Domain-esimerkit**: Todo, verkkokauppa, blogi — malli näkee miltä hyvä speksi näyttää +3. **Anti-patternit**: "Ei turhia ID-kenttiä, ei Enumeita, ei suomenkielisiä nimiä koodissa" +4. **Relaatiosäännöt**: "Jokainen `_id`-kenttä tarvitsee vastaavan relationship-merkinnän" + +Isompi malli (tai API) tässä yhdessä kohdassa parantaa kaikkien projektien laatua +koska speksi on ainoa paikka jossa LLM:n ymmärrys vaikuttaa. + ### 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} +from sqlalchemy import create_engine, Column, Integer, {sa_types}, ForeignKey +from sqlalchemy.orm import sessionmaker, relationship # ... 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ä ... + # FK-kentät: ForeignKey + relationship automaattisesti + {fk_field} = Column(Integer, ForeignKey('{parent_table}.id')) + {parent_lower} = relationship("{Parent}", back_populates="{children}") ``` Tulos: importit ovat aina oikein, `connect_args` on aina mukana, -testit importoivat aina `main.py`:stä eivätkä kopioi sitä. +relaatiot generoituvat oikein, testit importoivat `main.py`:stä eivätkä kopioi sitä. ### Vertailu: mittaustulokset | | Vapaa generointi | Rakennuspalaset | |---|:---:|:---:| -| LLM-kutsuja | 7–14 | **1** | -| Aika | 80–120s | **~20s** | +| LLM-kutsuja | 7–14 | **3** (speksi + requirements + README) | +| Aika | 80–120s | **~25s** | | Syntaksi OK | ~70% | **100%** | | Docker build | vaihteleva | **100%** | | Pytest läpi | 0% | **100%** | | API toimii | ~30% | **100%** | +| Relaatiot (FK) | ei koskaan | **100%** | +| Nested endpointit | ei koskaan | **automaattisesti** | ### Milloin kumpikin toimii