From 762066102aae9fb915070e82701b221901bc0371 Mon Sep 17 00:00:00 2001 From: Jaakko Vanhala Date: Mon, 6 Apr 2026 07:53:01 +0300 Subject: [PATCH] =?UTF-8?q?PROMPTS.md:=20kaikki=20j=C3=A4rjestelm=C3=A4n?= =?UTF-8?q?=20promptit=20dokumentoitu=20eksaktisti?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Kattaa kaikki 9 osa-aluetta: 1. Inferenssin system prompt (ChatML) 2. Agenttikohtaiset system promptit (7 agenttia) 3. Projekti-pipeline promptit (5 vaihetta + erikoistapaukset) 4. Yksinkertaisen pipelinen promptit 5. Yksittäiset komennot (run, hello, warmup) 6. Stop-sekvenssit (10 kpl) 7. Vastauksen siivous (4 vaihetta) 8. ChatML-promptin koostaminen (prefill-tekniikka) 9. Sampling-parametrit Jokainen prompti on eksaktissa muodossaan muuttujamerkinnöillä. Parsintasäännöt ja erikoistapaukset (pyproject.toml, requirements.txt) dokumentoitu yksityiskohtaisesti. Co-Authored-By: Claude Opus 4.6 (1M context) --- network-poc/PROMPTS.md | 348 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 network-poc/PROMPTS.md diff --git a/network-poc/PROMPTS.md b/network-poc/PROMPTS.md new file mode 100644 index 0000000..e70b2c4 --- /dev/null +++ b/network-poc/PROMPTS.md @@ -0,0 +1,348 @@ +# 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 ""` + +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 |