# Kipinä Agent Builder — Suunnitelma

Käyttäjä voi rakentaa omia agentteja "hahmolomakkeella": valitsee avatarin, roolin, kielimallin ja muokkaa prompteja. Agentit tallentuvat localStorageen ja ovat käytettävissä pipelineissa.

## Nykytila

```js
// Kovakoodattu agentPrompts-objekti
const agentPrompts = {
    manager: { name: 'Manageri', model: 'qwen2.5-coder:7b', default: '...' },
    coder:   { name: 'Koodari', model: 'qwen2.5-coder:7b', default: '...' },
    tofuist: { name: 'Tofuist', model: 'qwen2.5-coder:7b', docs: '/docs/tofu-cheatsheet.md', default: '...' },
    // ...
};
```

**Ongelma:** Uuden agentin lisääminen vaatii koodimuutoksen index.html:ään.

## Tavoite

```
┌─────────────────────────────────────────────────────┐
│  Agent Builder -lomake                              │
│                                                     │
│  ┌─────────┐  Nimi: [Tofuist          ]             │
│  │ 🦎      │  Rooli: [IaC / Infra    ▼]            │
│  │ avatar  │  Malli: [qwen2.5-coder:7b ▼]          │
│  └─────────┘  Docs:  [/docs/tofu-cheatsheet.md]    │
│                                                     │
│  System Prompt:                                     │
│  ┌─────────────────────────────────────────────┐    │
│  │ You are an OpenTofu/Terraform IaC specialist│    │
│  │ ...                                         │    │
│  └─────────────────────────────────────────────┘    │
│                                                     │
│  LLM-parametrit:                                    │
│  Temperature: [0.7]  Top-k: [40]  Max tokens: [512]│
│                                                     │
│  [💾 Tallenna]  [🗑️ Poista]  [📤 Export JSON]       │
└─────────────────────────────────────────────────────┘
```

## Building Blocks

### 1. Agenttiskeema

```js
{
    id: 'tofuist',                          // uniikki tunniste
    name: 'Tofuist',                        // näyttönimi
    avatar: '/avatars/gecko_notext.png',     // avatar-kuvan polku
    role: 'iac',                             // rooli-template
    model: 'qwen2.5-coder:7b',             // eksakti Ollama-mallinimi
    color: '#e3a336',                        // teemaväri UI:ssa
    docs: '/docs/tofu-cheatsheet.md',        // valinnainen referenssidokumentti
    prompt: 'You are an OpenTofu...',        // system prompt
    params: {                                // LLM-parametrit
        temperature: 0.7,
        top_k: 40,
        max_tokens: 512,
        repetition_penalty: 1.15
    }
}
```

### 2. Rooli-templatet (alasvetovalikko)

Valmiit pohjat jotka tuovat oletuspromptit ja parametrit:

| Rooli | Oletusprompt | Parametrit |
|-------|-------------|------------|
| Koodari | "Kirjoita selkeää, testattavaa koodia" | temp 0.7, max 512 |
| QA / Testaus | "Kirjoita testejä, etsi virheitä" | temp 0.4, max 512 |
| DevOps | "Dockerfile, Compose, CI/CD" | temp 0.5, max 512 |
| DevSecOps | "Tietoturva-auditointi, OWASP" | temp 0.3, max 512 |
| Arkkitehti | "Järjestelmäsuunnittelu, rajapinnat" | temp 0.6, max 512 |
| IaC / Infra | "OpenTofu/Terraform HCL-koodi" | temp 0.5, max 512 |
| Data | "Tietokannat, SQL, datamallit" | temp 0.5, max 512 |
| Manageri | "Tehtävien jako ja koordinointi" | temp 0.8, max 200 |
| Kirjoittaja | "Dokumentaatio, README, ohjeet" | temp 0.8, max 512 |
| Vapaa | (tyhjä, käyttäjä kirjoittaa) | temp 0.7, max 512 |

### 3. Malli-valitsin

Lista saatavilla olevista malleista — haetaan dynaamisesti:

```
Hub-kysely: GET /api/models → palauttaa yhdistettyjen solmujen mallit

Tai staattinen lista:
- qwen2.5-coder:7b    (oletus, natiivi GPU)
- qwen2.5-coder:1.5b  (kevyt)
- qwen2.5-coder:0.5b  (selain Wasm)
- deepseek-r1          (reasoning)
- llama3.2:3b          (yleiskäyttö)
```

Pitkän aikavälin tavoite: hub ilmoittaa WebSocketin kautta mitkä mallit ovat saatavilla.

### 4. Avatar-valitsin

Valmiit avatarit + mahdollisuus ladata oma:

| Hahmo | Tiedosto | Eläin |
|-------|----------|-------|
| Asiakas | kettu_notext.png | Kettu |
| Manageri | karhunpentu.png | Karhunpentu |
| Koodari | kipina_notext.png | Salamanteri |
| Data | pesukarhu_notext.png | Pesukarhu |
| QA | susi_notext.png | Pikkususi |
| DevOps | laiskiainen_notext.png | Laiskiainen |
| Tarkkailija | aikuinen_susi.png | Aikuinen susi |
| Tofuist | gecko_notext.png | Gecko/Lisko |
| Arkkitehti | ??? | (tulossa) |
| DevSecOps | ??? | (tulossa) |

### 5. Docs-kenttä (referenssidokumentti)

Agentti voi viitata ulkoiseen dokumenttiin joka ladataan promptiin:

```
docs: '/docs/tofu-cheatsheet.md'  →  haetaan fetch():llä, cachetetaan _docsCache-kenttään
```

**Toiminta:**
1. Ensimmäisellä `kpnRun`-kutsulla ladataan docs-URL
2. Sisältö cachetetaan `agent._docsCache`-kenttään
3. Liitetään promptiin: `"Reference:\n" + docsContent`
4. Ei ladata uudelleen saman session aikana

**Rajoitukset:**
- Max ~3000 tokenia (~10 KB) — pidempi docs tiivistetään
- Vain tekstitiedostot (.md, .txt)

### 6. Tallennus (localStorage)

```js
// Tallennusavain
'kpn-custom-agents' → JSON.stringify([ agentSkeema1, agentSkeema2, ... ])

// Ladattaessa
const customAgents = JSON.parse(localStorage.getItem('kpn-custom-agents') || '[]');
const defaultAgents = { manager: {...}, coder: {...}, ... };
const agentPrompts = { ...defaultAgents };
for (const agent of customAgents) {
    agentPrompts[agent.id] = agent;
}
```

**Oletusagentit** (manager, coder, tester, qa, data) ovat aina mukana — niitä ei voi poistaa, mutta prompteja voi muokata.

**Käyttäjäagentit** (tofuist, arkkitehti, devsecops, ...) tallentuvat localStorageen ja latautuvat käynnistyksessä.

### 7. Export / Import

```js
// Export — JSON-tiedosto
const blob = new Blob([JSON.stringify(agent, null, 2)], { type: 'application/json' });
// → agent-tofuist.json

// Import — tiedoston valinta tai drag & drop
// Validoidaan skeema, lisätään agentPrompts-objektiin
```

Mahdollistaa agenttien jakamisen tiimin kesken.

## Toteutusvaiheet

### Vaihe 1: Hahmolomake UI
- Avatar-grid valitsin
- Rooli-template alasvetovalikko (täyttää oletuspromptit)
- Malli-valitsin
- System prompt -tekstikenttä
- LLM-parametrit (temperature, top-k, max_tokens)
- Tallenna/Poista-napit

### Vaihe 2: Dynaaminen agenttirekisteri
- `agentPrompts` ladataan localStoragesta
- Oletusagentit + käyttäjän agentit yhdistetään
- Avatar-kortit renderöidään dynaamisesti (ei HTML:ssä)
- Värimapit generoidaan agenttiskeemasta

### Vaihe 3: Pipeline käyttää dynaamisia agentteja
- Pipeline-vaiheet viittaavat agentin id:hen (ei kovakoodattuun nimeen)
- Käyttäjä voi valita mitkä agentit osallistuvat pipelineen
- Tofuist voi korvata DevOpsin IaC-projekteissa

### Vaihe 4: Mallirekisteri (hub-integraatio)
- Hub tarjoaa `/api/models`-endpointin
- Saatavilla olevat mallit näkyvät valitsimessa reaaliajassa
- Solmun liittyessä/poistuessa mallit päivittyvät

## Arkkitehtuurikaavio

```
┌──────────────────────────────────────────────────┐
│  Agent Builder UI                                │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
│  │ Avatar   │ │ Rooli    │ │ Malli-valitsin   │  │
│  │ Grid     │ │ Template │ │ (hub/staattinen) │  │
│  └────┬─────┘ └────┬─────┘ └────────┬─────────┘  │
│       └─────────────┼───────────────┘             │
│                     ▼                             │
│  ┌──────────────────────────────────────────────┐ │
│  │  Agent Schema  { id, name, avatar, model,   │ │
│  │                  role, color, docs, prompt,  │ │
│  │                  params }                    │ │
│  └──────────────────┬───────────────────────────┘ │
│                     │                             │
│       ┌─────────────┼─────────────┐               │
│       ▼             ▼             ▼               │
│  localStorage   Org Chart    Pipeline             │
│  (persist)      (render)     (execute)            │
└──────────────────────────────────────────────────┘
```