# Kipinä Agentic Studio — Promptit

Kaikki järjestelmässä käytetyt promptit. Jokainen on dokumentoitu eksaktisti
niin kuin se lähetetään mallille, muuttujat merkitty `${...}`-syntaksilla.

---

## 1. Inferenssin system prompt (Wasm + natiivi)

**Sijainti:** `node/src/qwen_coder.rs` rivi 256, `native-node/src/inference.rs` rivi 127
**Malli:** Qwen2.5-Coder-0.5B/3B
**ChatML-rooli:** `<|im_start|>system`

```
You are a coding assistant. Respond with ONLY code. No explanations, no markdown, no comments unless asked.
```

**Tarkoitus:** Pakottaa malli tuottamaan pelkkää koodia ilman selityksiä.
**Prefill:** Assistantin vastaus alkaa ` ``` ` joka ohjaa mallin koodiblokkiin.

---

## 2. Agenttikohtaiset system promptit (frontend)

**Sijainti:** `static/index.html` rivit 1136-1144
**Tallennus:** localStorage (`kpn-agent-prompt-{key}`)
**ChatML-rooli:** Liitetään `<|im_start|>user` -blokkiin osaksi promptia

### 2.1 Manageri (manager)
```
Olet projektipäällikkö. Jaa tehtävät osiin, priorisoi ja koordinoi tiimin työtä.
```
**Malli:** qwen-coder

### 2.2 Koodari (coder)
```
Olet kokenut ohjelmistokehittäjä. Kirjoita selkeää, testattavaa koodia ja vastaa aina koodilla.
```
**Malli:** qwen-coder

### 2.3 Data-agentti (data)
```
Olet tietokanta-asiantuntija. Vastaat skeemojen suunnittelusta, SQL-kyselyiden optimoinnista ja datamalleista.
```
**Malli:** qwen-coder

### 2.4 QA (qa)
```
Olet laadunvarmistaja (QA). Kirjoitat testejä, etsit virheitä ja varmistat, että kaikki reunatapaukset on huomioitu.
```
**Malli:** smollm-135m

### 2.5 DevOps / Testaaja (tester)
```
Olet DevOps-insinööri. Vastaat koodin julkaisuputkista, serveri-infrastruktuurista ja ympäristön suorituskyvystä.
```
**Malli:** smollm-135m

### 2.6 Tarkkailija (observer)
```
Olet ohjelmistoprojektin riippumaton valvoja. Sinulla on täysi pääsy kaikkiin projektin tietoihin ja muiden agenttien keskusteluihin. Valvo tiimin (Manageri, Koodari, Data, QA, DevOps) toimintaa asiantuntijana kokonaisuutena ja huomauta välittömästi visio- tai turvallisuusriskeistä.
```
**Malli:** deepseek-r1

### 2.7 Asiakas (client)
```
Kirjoita tähän asiakkaan toiveet ja projektin vaatimukset. Orkestraattori (Manageri) purkaa ja delegoi nämä työt asiantuntijoille.
```
**Malli:** user-input (ei LLM:ää, käyttäjän teksti)

---

## 3. Projekti-pipeline (`kpn project`)

### 3.1 Vaihe 1: Managerin tiedostojako

**Konteksti:** Käyttäjä on antanut projektin kuvauksen.
**Tavoite:** Pilkotaan projekti yksittäisiksi tiedostoiksi oikeassa riippuvuusjärjestyksessä.

```
List the source files needed for this project. One file per line, format:
filename.py: what this file contains

Rules:
- Max 4 files
- Only .py, .toml, .json, .html files
- No directories, no paths, just filenames
- List dependencies first, then main app (e.g. models.py before main.py)
- Use pyproject.toml for dependencies (not requirements.txt)

Project: ${task}
```

**Odotettu vastausformaatti:**
```
models.py: SQLAlchemy User model and database setup
main.py: FastAPI app with CRUD endpoints
pyproject.toml: project dependencies
```

**Parsintasäännöt:**
- Rivi voi olla `filename.ext: kuvaus` tai pelkkä `filename.ext`
- Tiedostonimessä ei saa olla `/`, välilyöntejä tai polkuja
- Päättyy tiedostopäätteeseen (`/\.\w{1,5}$/`)
- Numerot, `-`, `*` ja `` ` `` strippataan rivin alusta
- Max 40 merkin tiedostonimi

### 3.2 Vaihe 2: Koodarin tiedostogenerointi (per tiedosto)

**Konteksti:** Managerin tiedostolista on parsittu. Jokaiselle tiedostolle generoidaan koodi erikseen. Aiemmin generoidut tiedostot annetaan kontekstina.

**Perusmuoto:**
```
${context}Project: ${task}
Write ONLY the file "${filename}"${description ? ': ' + description : ''}.
Use the exact libraries mentioned in the project description. Write correct, working code.
```

**`${context}` (kun aiempia tiedostoja on generoitu):**
```
Already written files:
--- models.py ---
from sqlalchemy import ...
...

--- main.py ---
from fastapi import ...
...

```

**Erikoistapaus: pyproject.toml**

Koska 0.5B-malli ei tunne uv/pyproject.toml-formaattia, annetaan eksplisiittinen esimerkki:
```
${context}Project: ${task}
Write ONLY the file "pyproject.toml": ${description}.
Use this exact format:
[project]
name = "projectname"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["fastapi", "uvicorn"]

[project.scripts]
start = "uvicorn main:app --reload"
Use the exact libraries mentioned in the project description. Write correct, working code.
```

**Erikoistapaus: requirements.txt (fallback)**
```
...
List one dependency per line. No version pins unless necessary.
...
```

### 3.3 Vaihe 2 (fallback): Yhtenä kokonaisuutena

Jos managerin vastaus ei tuota parsittavaa tiedostolistaa:
```
Project: ${task}
Files: ${managerin_vastaus}

Write all the code for this project. Use the exact libraries mentioned in the project description. Use pyproject.toml for dependencies (not requirements.txt).
```

### 3.4 Vaihe 3: Testerin arviointi

**Konteksti:** Kaikki generoidut tiedostot yhdistettynä.

```
Review this project. List bugs or issues. Be brief.
If the code is correct, say "LGTM".

--- models.py ---
from sqlalchemy import ...

--- main.py ---
from fastapi import ...
```

**Odotettu vastaus:** Bugilista tai `LGTM`.
**Trigger korjausluuppiin:** Jos vastaus EI sisällä "lgtm" tai "looks good" (case-insensitive).

### 3.5 Vaihe 4: Koodarin korjaukset (ehdollinen)

Ajetaan vain jos testeri löysi ongelmia.

```
Fix the issues found in the review.
Review feedback: ${review}

Current code:
--- models.py ---
...

--- main.py ---
...

Write the corrected code.
```

### 3.6 Vaihe 5: Testerin uudelleenarviointi (ehdollinen)

```
Review the corrected code briefly:
${fixedCode}
```

---

## 4. Yksinkertainen pipeline (`kpn pipeline`)

### 4.1 Manageri
```
Analyse this task briefly and write a technical spec for a coder:
${task}
```

### 4.2 Koodari
```
${managerin_vastaus}

Write the code.
```

### 4.3 Testaaja
```
Review briefly:
${koodarin_vastaus}
```

---

## 5. Yksittäiset komennot

### 5.1 `kpn run <malli> "<prompti>"`

Promptin koostaminen `kpnRun`-funktiossa:
```
${sharedPrompt}        ← Kaikille agenteille yhteinen (jos asetettu)

${agentPrompt}         ← Valitun agentin system prompt (jos löytyy)

${käyttäjän_prompti}   ← Käyttäjän kirjoittama teksti
```

Osat yhdistetään `\n\n`-erottimella ja lähetetään `<|im_start|>user`-blokkiin.

### 5.2 `kpn hello`

Kiinteä prompti SmolLM-135M -mallille:
```
Tervehdi käyttäjää iloisesti ja lyhyesti suomeksi. Ole innostunut ja energinen! Vastaa yhdellä lauseella.
```

### 5.3 Warmup (automaattinen)

Lähetetään automaattisesti kun laskentasolmu käynnistyy. Triggeröi mallin latauksen ilman näkyvää tulosta.
```json
{"prompt": "warmup", "max_tokens": 1}
```

---

## 6. Stop-sekvenssit (inferenssi)

**Sijainti:** `node/src/qwen_coder.rs` rivi 345, `native-node/src/inference.rs` rivi 210

Generointi katkaistaan ja teksti trimmataan kun malli tuottaa minkä tahansa näistä:

| Sekvenssi | Tarkoitus |
|-----------|-----------|
| `\n###` | Markdown-otsikko (selitysosio alkaa) |
| `\nExplanation` | Selitysosio |
| `\nNote:` | Huomautus |
| `\nOutput:` | Esimerkkitulostus |
| `` \n```\n\n `` | Koodiblokin loppu + tyhjä rivi |
| `\n// Example` | Esimerkkikoodi (C/Rust/JS) |
| `\n// example` | Sama pienellä |
| `\n# Example` | Esimerkkikoodi (Python/Ruby) |
| `\n# example` | Sama pienellä |

---

## 7. Vastauksen siivous (post-processing)

**Sijainti:** `strip_markdown_wrapper()` molemmissa inferenssimoduuleissa

### 7.1 Kielitunnisteen poisto

Jos ensimmäinen rivi on tunnettu kielitunniste, se poistetaan.
Tunnistetut: `python`, `py`, `rust`, `rs`, `javascript`, `js`, `typescript`, `ts`,
`java`, `kotlin`, `scala`, `go`, `ruby`, `rb`, `php`, `swift`,
`c`, `cpp`, `c++`, `c#`, `csharp`, `r`, `sql`, `bash`, `sh`, `zsh`,
`html`, `css`, `json`, `yaml`, `yml`, `toml`, `xml`, `markdown`, `md`,
`lua`, `perl`, `dart`, `elixir`, `haskell`, `hs`, `ocaml`, `zig`,
`plaintext`, `text`, `txt`

### 7.2 Sulkevan ` ``` ` poisto

Poistetaan VAIN jos ` ``` ` on omalla rivillään tiedoston lopussa
(edeltävä merkki on rivinvaihto tai alku).

### 7.3 Johdantolauseiden poisto

Ensimmäinen rivi poistetaan jos se alkaa (case-insensitive):
`Sure!`, `Here is`, `Here's`, `Certainly!`, `Below is`

### 7.4 Selityskommenttien poisto

Alun `# `-alkuiset rivit poistetaan jos ne sisältävät (case-insensitive):
`this is`, `simple`, `program that`, `here is`, `the following`, `below`

Shebang (`#!`) säilytetään.

---

## 8. Promptin kulku mallille (ChatML)

Lopullinen viesti mallille koostetaan näin:

```
<|im_start|>system
You are a coding assistant. Respond with ONLY code. No explanations, no markdown, no comments unless asked.<|im_end|>
<|im_start|>user
${sharedPrompt}

${agentPrompt}

${käyttäjän/pipelinen prompti}<|im_end|>
<|im_start|>assistant
```
```

**Huomio:** ` ``` ` assistantin alussa on prefill — se on osa syötettä eikä mallin tuottamaa. Malli jatkaa suoraan koodilla.

---

## 9. Sampling-parametrit

| Parametri | Arvo | Kuvaus |
|-----------|------|--------|
| `temperature` | 0.7 | Jakaumaa pehmentävä kerroin |
| `top_k` | 40 | Valinnan rajoitus 40 todennäköisimpään tokeniin |
| `repetition_penalty` | 1.15 | Aiemmin generoitujen tokenien rankaisu |
| `max_tokens` | 512 (oletus) | Konfiguroitavissa JSON-promptilla |
| `eos_token` | 151645 | Qwen2.5:n päätöstokeni |