agentic-studio/kipina-codebench/golden-examples

Golden Examples — referenssitoteutukset

Kultaiset esimerkit ovat täydellisiä, testattuja FastAPI-projekteja joita LLM käyttää mallina koodigeneroinnissa. Malli näkee esimerkin ja tuottaa vastaavan rakenteen uudelle projektille.

Uuden esimerkin luominen

1. Luo hakemisto

mkdir golden-examples/shop

Nimeä hakemisto skenaarion mukaan (todo, blog, shop, booking...).

2. Luo 4 tiedostoa

Tiedosto	Sisältö
models.py	SQLAlchemy 2.0 -mallit (DeclarativeBase, Mapped, mapped_column)
schemas.py	Pydantic v2 -skeemat (ConfigDict, str | None -syntaksi)
main.py	FastAPI CRUD -endpointit (POST 201, GET, GET/:id 404, PUT, DELETE 204)
test_main.py	Pytest + TestClient, erillinen test.db, uniikki data per testi

3. Noudata konventioita

Python-versio: >=3.14

SQLAlchemy 2.0 (ei legacy):

# Oikein
class Base(DeclarativeBase):
    pass

class Todo(Base):
    id: Mapped[int] = mapped_column(primary_key=True, index=True)
    title: Mapped[str] = mapped_column(String(255))
    status: Mapped[str] = mapped_column(String(20), default="pending")

# Väärin
Base = declarative_base()
id = Column(Integer, primary_key=True)

Pydantic v2 (ei v1):

# Oikein
class TodoResponse(TodoCreate):
    id: int
    model_config = ConfigDict(from_attributes=True)

# Väärin
class Config:
    orm_mode = True

Tyypitys:

# Oikein
description: Mapped[str | None] = mapped_column(Text, default=None)

# Väärin
description: Mapped[Optional[str]]

Dokumentointi (zensical):

"""Tietokantamallit — SQLAlchemy 2.0, Mapped-tyypitys, SQLite."""

class Todo(Base):
    """Tehtävä — otsikko, kuvaus, deadline, prioriteetti ja status."""

Yksi rivi riittää. Kerro mitä asia ON, älä mitä se tekee. Katso DOCUMENTATION.md.

Testidata — uniikki ja kuvaava:

# Oikein
def test_create_todo():
    response = client.post("/todos/", json={"title": "Osta maitoa", "priority": 2})

def test_update_todo():
    created = client.post("/todos/", json={"title": "Vanha otsikko"}).json()

# Väärin — geneerinen data
def test_create_todo():
    response = client.post("/todos/", json={"title": "test", "priority": 1})

4. Testaa Docker-kontissa

rm -rf /tmp/golden-test && mkdir /tmp/golden-test
cp golden-examples/shop/*.py /tmp/golden-test/
docker run --rm -v /tmp/golden-test:/src:ro kipina-pytest

Kaikkien testien pitää mennä läpi. Ei varoituksia, ei deprecation-viestejä.

5. Vaikeustasot

Taso	Esimerkit	Haaste
1 — Perus-CRUD	todo/, users/, notes/	Yksi entiteetti
2 — Relaatiot	blog/, library/, school/	Foreign key, 2–3 entiteettiä
3 — Liiketoimintalogiikka	shop/, booking/	Custom endpointit, validointi

Aloita tasosta 1 ja etene. Tason 1 esimerkkien pitää olla yksinkertaisia — ne opettavat mallille perusrakenteen.

Miten esimerkit vaikuttavat

Benchmark lataa todo/-esimerkin ja syöttää sen LLM:lle osana koodingenerointipromptia:

REFERENCE IMPLEMENTATION (todo project — follow this exact structure):

=== models.py ===
<todo/models.py sisältö>

=== schemas.py ===
...

Malli näkee tarkan esimerkin ja tuottaa vastaavan rakenteen uudelle projektille. Mitä parempi esimerkki, sitä parempi tulos.