agentic-studio/network-poc/BUILDING_BLOCKS.md

Kipinä Agentic Studio — Rakennuspalaset

Tämä dokumentti kuvaa projektin UI-komponentit, arkkitehtuuripatternit ja työnkulut niin, että vastaavan hajautetun AI-laskentaverkon ja agenttipohjaisen käyttöliittymän voi rakentaa alusta asti.

Yleiskuva

┌─────────────────────────────────────────────────────┐
│  Selain (käyttäjä)                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ Verkko-  │  │ Koodi-   │  │ Agents-näkymä     │  │
│  │ näkymä   │  │ labra    │  │ ┌───────────────┐ │  │
│  │          │  │          │  │ │ Terminaali    │ │  │
│  │ Stats    │  │ Editor   │  │ │ Tab-complete  │ │  │
│  │ Chat     │  │ Pipeline │  │ │ Dropdown      │ │  │
│  │ Tokenit  │  │ Tulokset │  │ │ Historia      │ │  │
│  └────┬─────┘  └────┬─────┘  │ └───────────────┘ │  │
│       │              │        └────────┬──────────┘  │
│       └──────────┬───┘                 │             │
│            UI WebSocket          HTTP API            │
│                  │              /api/v1/chat          │
│  ┌───────────────┴──────────────┐      │             │
│  │  Wasm Compute Node           │      │             │
│  │  (Candle + Burn)             │      │             │
│  │  ┌─────────┐ ┌────────────┐  │      │             │
│  │  │ RAM     │ │ IndexedDB  │  │      │             │
│  │  │ Cache   │ │ Cache      │  │      │             │
│  │  └─────────┘ └────────────┘  │      │             │
│  │  ┌─────────────────────────┐ │      │             │
│  │  │ Model Cache (QwenModel) │ │      │             │
│  │  └─────────────────────────┘ │      │             │
│  └──────────────┬───────────────┘      │             │
│                 │ WS                   │             │
└─────────────────┼──────────────────────┼─────────────┘
                  │                      │
         ┌────────┴──────────────────────┴──┐
         │  Hub (Axum + Tokio)              │
         │  ┌────────────┐ ┌─────────────┐  │
         │  │ Broadcast  │ │ Node        │  │
         │  │ Channel    │ │ Registry    │  │
         │  └────────────┘ └─────────────┘  │
         │  ┌────────────┐ ┌─────────────┐  │
         │  │ Busy-State │ │ Rate Limit  │  │
         │  │ Tracker    │ │ + Auth      │  │
         │  └────────────┘ └─────────────┘  │
         │  ┌─────────────────────────────┐ │
         │  │ SQLite (sessiot, tulokset)  │ │
         │  └─────────────────────────────┘ │
         └──────────────────────────────────┘

---

1. WebSocket-reaaliaikakommunikaatio

1.1 Hub ↔ Node broadcast-kanava

Tarkoitus: Jakaa tehtäviä ja vastaanottaa tuloksia kaikilta laskentasolmuilta.

Työnkulku:

1. Hub luo tokio::sync::broadcast::channel(100)
2. Jokainen solmu saa oman rx = stats_tx.subscribe()
3. Hub broadcastaa tehtävät: stats_tx.send(json)
4. Solmut suodattavat viestin tyypin ja selected_task:n perusteella

Viestityupit:

Tyyppi	Suunta	Sisältö
stats	Hub → kaikki	nodes, vram_gb, tasks
pair_task	Hub → tokenize-solmut	en, fi tekstiparit
llm_prompt	Hub → valittu solmu	prompt, model, task_id
llm_chunk	Solmu → Hub → UI	token (1 kerrallaan)
llm_done	Solmu → Hub → UI	response, tokens_generated, duration_ms
llm_error	Solmu → Hub → UI	error, task_id
task_routed	Hub → UI	status (routed/queued), node_id, message

Lagged-viestien käsittely:

match rx.recv().await {
    Ok(msg) => { /* käsittele */ }
    Err(broadcast::error::RecvError::Lagged(n)) => {
        // Ohitetaan vanhat viestit, ei katkaista yhteyttä
        continue;
    }
    Err(_) => break, // Kanava suljettu
}

1.2 Kohdennettu reititys (Direct Channel)

Tarkoitus: Lähetä tehtävä yhdelle tietylle solmulle broadcastin sijaan.

Työnkulku:

1. Jokainen solmu saa mpsc::unbounded_channel yhdistyessään
2. Hub tallentaa node_channels: HashMap<u64, UnboundedSender>
3. API-pyyntö → valitaan vapaa solmu → lähetetään suoraan kanavaan
4. Broadcast-kanavaa käytetään vain tuloksen välittämiseen UI:lle

let channels = state.node_channels.read().await;
if let Some(tx) = channels.get(&target_node_id) {
    tx.send(msg.to_string());
}

1.3 Busy-state ja työjono

Tarkoitus: Estä tehtävien reititys varatuille solmuille.

Rakenne:

• node_busy: HashSet<u64> — solmut joilla on aktiivinen tehtävä
• Asetetaan kun tehtävä reititetään, vapautetaan llm_done/llm_error:ssa
• Jos kaikki solmut varattuja → pollaa 500ms välein, max 30s

UI-palaute:

{"type": "task_routed", "status": "queued", "message": "Kaikki 2 solmua varattuja — odotetaan..."}
{"type": "task_routed", "status": "routed", "node_id": 3, "message": "Solmu #3 vapautui (2.5s jonossa)"}

---

2. Wasm-laskentasolmu

2.1 Elinkaari

init() → start_agent_node(ws_url, has_webgpu, device_info, task_id)
  │
  ├─ Avaa WebSocket hubiin
  ├─ Lähettää auth-viestin (laitetiedot, selected_task)
  ├─ Rekisteröityy onmessage-käsittelijä
  │    ├─ pair_task → tokenize
  │    ├─ llm_prompt → inference
  │    └─ ai_task → tensor matmul
  └─ Odottaa tehtäviä loopissa

Globaali tila (atominen, lukitsematon):

static GPU_LOAD_PERCENT: AtomicU32 = AtomicU32::new(50);
static LLM_BUSY: AtomicBool = AtomicBool::new(false);
static SELECTED_TASK: AtomicU32 = AtomicU32::new(0);

2.2 Kolmitasoinen cache

Pyyntö → [1] RAM-cache (thread_local HashMap)
            │ miss
            ▼
         [2] IndexedDB (selaimen pysyvä tallennus)
            │ miss
            ▼
         [3] Verkko (HuggingFace CDN, streaming + 5% progressi)
            │
            ▼
         Tallenna → IndexedDB → RAM-cache

Taso	Nopeus	Koko	Pysyvyys
RAM	~0ms	Rajaton	Sivulataus
IndexedDB	~50ms	~50GB	Pysyvä
Verkko	~10s/100MB	∞	—

Malliinstanssin cache (neljäs taso):

thread_local! {
    static MODEL_CACHE: RefCell<Option<CachedModel>> = RefCell::new(None);
}
// clear_kv_cache() promptien välillä — ei tarvitse rakentaa mallia uusiksi

2.3 Warmup-esilataus

Tarkoitus: Lataa malli valmiiksi ennen ensimmäistä oikeaa promptia.

// Lähetetään 1 tokenin warmup heti kun WS on auki
uiSocket.send(JSON.stringify({
    type: 'user_text',
    text: '{"prompt":"warmup","max_tokens":1}',
    task_type: 'qwen-coder'
}));

---

3. LLM-inferenssipipeline

3.1 Prompt-formaatti (ChatML + prefill)

<|im_start|>system
You are a coding assistant. Respond with ONLY code.<|im_end|>
<|im_start|>user
hello world in python<|im_end|>
<|im_start|>assistant
```                          ← PREFILL: pakottaa mallin aloittamaan koodilla

Prefill-tekniikka: Lisäämällä ``` assistantin vastauksen alkuun malli jatkaa suoraan koodilla eikä tuota "Sure! Here is..." -johdantoa. Säästää 10-20 tokenia per vastaus.

3.2 Sampling-parametrit

Parametri	Arvo	Tarkoitus
temperature	0.7	Pehmentää jakaumaa, vähentää toistoa
top_k	40	Rajaa valinnan 40 todennäköisimpään tokeniin
repetition_penalty	1.15	Rankaisee jo generoitujen tokenien uudelleenvalintaa
max_tokens	128	Oletusraja, JSON-promptilla konfiguroitavissa

Sampling-funktio (top-k + temperature + repetition penalty):

fn sample_top_k_with_penalty(logits, k, temperature, generated_tokens, penalty) -> u32 {
    // 1. Repetition penalty: vähennä aiempien tokenien logitteja
    // 2. Temperature scaling: jaa logitit temperaturella
    // 3. Top-k: ota k suurinta
    // 4. Softmax top-k:lle
    // 5. Satunnaisvalinta kumulatiivisella todennäköisyydellä (XorShift RNG)
}

3.3 Stop-sekvenssit

Generointi katkaistaan ja teksti trimmataan kun malli alkaa selittää:

let stop_patterns = ["\n###", "\nExplanation", "\nNote:", "\nOutput:", "\n```\n\n"];

3.4 Vastauksen siivous

Raakavastaus:     "Sure! Here is...\n```python\n# This is a simple program\nprint('hi')\n```"
                   │
strip_markdown:    "# This is a simple program\nprint('hi')"
                   │
strip_preamble:    "print('hi')"

Tunnistettavat selityskommentit: # This is, # simple, # program that, # here is, # the following, # below

3.5 Streaming

Jokainen generoitu token lähetetään heti llm_chunk-viestinä:

{"type": "llm_chunk", "token": "print", "prompt": "...", "model": "Qwen2.5-Coder", "task_id": "uuid"}

UI päivittää streaming-korttia reaaliaikaisesti appendaamalla tokeneita.

---

4. Terminaaliemulaattori

4.1 Rakenne

<div id="agent-hub-status">     <!-- Status-palkki (Hub + Laskenta) -->
<div id="agent-terminal">       <!-- Scrollaava tulosalue, max 100 riviä -->
<div>                            <!-- Input-rivi -->
    <span>$</span>
    <input id="term-input">
    <div id="term-dropdown">    <!-- Autocompletion-valikko -->
</div>

4.2 Komentojen käsittely

function termExec(cmd) {
    // Parsitaan: "kpn" + alikomento + argumentit
    // Tuetut: help, run, pipeline, load, status, models, hello, clear
    // Agenttinimi → malli-mapping: "coder" → "qwen-coder"
}

4.3 Tab-completion (kolmitasoinen)

const kpnCommands = {
    'kpn': ['help', 'run', 'pipeline', 'load', ...],
    'kpn run': ['coder', 'manager', 'qwen-coder', ...],
};
const kpnExamples = {
    'kpn run coder': ['"hello world in python"', ...],
};

Käyttö:

Näppäin	Toiminto
TAB	Täydennä seuraava sana tai avaa dropdown
Shift-TAB	Poista viimeinen sana (lainausmerkit kokonaisuutena)
↑ / ↓	Navigoi dropdownissa (tai komentohistoriassa)
Enter	Valitse dropdownista tai suorita komento
Esc	Sulje dropdown

4.4 Dropdown-valikko

function showDropdown(items, prefix) {
    // Luo div.term-dd-item per vaihtoehto
    // Positio: absolute, bottom: 100% (inputin yläpuolella)
    // Mouseenter → highlight, click → valinta
}

4.5 Komentohistoria

const termHistory = [];      // Kaikki ajetut komennot (viimeisin ensin)
let termHistIdx = -1;        // Nykyinen positio historiassa
// ArrowUp: termHistIdx++, ArrowDown: termHistIdx--

---

5. Status-palkit ja tilaindikaattorit

5.1 Hub-yhteyden tila

Tila	Väri	Teksti	Tooltip
Yhdistetään	🟡	"Yhdistetään..."	WebSocket-yhteys Kipinä Hubiin
Yhdistetty	🟢	"Yhdistetty"	Tehtävien jakelu aktiivinen
Katkennut	🔴	"Yhteys katkennut"	Tarkista verkko, lataa uudelleen

5.2 Laskentasolmun tila

Tila	Väri	Teksti	Nappi
Ei käynnissä	⚫	"—"	[Alusta laskentasolmu] sininen
Lataa	🟡	"Ladataan..."	[Peruuta] punainen
Valmis	🟢	"Qwen2.5-Coder"	[✓ Valmis] vihreä

5.3 Pipeline-tilakone (Codelab)

Step 1: WebAssembly-ytimen lataus     [◯ → ◷ → ✓]
Step 2: Tokenizer (7 MB)              [◯ → ◷ → ✓]
Step 3: Mallipainot (990 MB)           [◯ → ◷ 45% → ✓ cache]
Step 4: Mallin rakentaminen            [◯ → ◷ → ✓]
Step 5: Valmis generoimaan             [◯ → ✓]

Seuranta console.log-viesteistä:

if (msg.includes('[Coder]') && msg.includes('Malli ladattu')) {
    // Merkkaa kaikki vaiheet valmiiksi (myös cache-hitillä)
    setStep('step-wasm', 'done');
    setStep('step-tokenizer', 'done');
    setStep('step-model', 'done', 'cache');
    setStep('step-build', 'done');
    setStep('step-ready', 'done');
}

---

6. Tietoturva

6.1 XSS-suojaus

function esc(str) {
    return String(str).replace(/&/g,'&amp;').replace(/</g,'&lt;')
        .replace(/>/g,'&gt;').replace(/"/g,'&quot;');
}

Käyttöpaikat: Kaikki innerHTML-insertoinnit joissa on käyttäjä- tai backend-dataa.

6.2 System prompt -piilotus

function stripSystemPrompt(prompt) {
    const parts = prompt.split('\n\n');
    return parts[parts.length - 1] || prompt;
}

6.3 Viestityyppivalidointi (backend)

const ALLOWED_MSG_TYPES: &[&str] = &[
    "auth", "result", "pair_done", "llm_chunk", "llm_done",
    "llm_error", "download_progress", "user_text", "single_tokenize_done"
];

fn validate_message(text: &str) -> Result<Value, &'static str> {
    // 1. JSON-parsinta
    // 2. "type"-kenttä pakollinen
    // 3. Tyyppi sallittujen listalla
    // 4. Tyyppikohtainen validointi (esim. pair_done: token_count <= 10000)
}

6.4 Rate limiting

// Per-IP liukuva ikkuna: max 10 pyyntöä per 60s
let entry = limits.entry(addr.ip()).or_insert((now, 0));
if now.duration_since(entry.0).as_secs() >= 60 {
    *entry = (now, 1);
} else {
    entry.1 += 1;
    if entry.1 > 10 { return 429 Too Many Requests; }
}

6.5 Gamification-huijauksen esto

// Hub jakaa task_id:n → tallentaa pending_task_ids:hen
// Merkkejä jaetaan VAIN jos llm_done sisältää validin task_id:n
let valid_task = state.pending_task_ids.lock().unwrap().remove(tid);
if active_incentives && valid_task {
    *balance += 20;
}

---

7. Syntaksikorostus

7.1 Highlight.js-integraatio

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/styles/github-dark.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/highlight.min.js"></script>

function highlightCode(code) {
    if (typeof hljs !== 'undefined') {
        return hljs.highlightAuto(code).value;  // Automaattinen kielentunnistus
    }
    return esc(code);  // Fallback
}

Käyttöpaikat: Codelab-tulokset, agents-terminaalin vastaukset, network-chat.

---

8. Agenttien orkestrointi

8.1 Multi-agent pipeline

┌──────────┐     ┌──────────┐     ┌──────────┐
│ Manageri │ ──→ │ Koodari  │ ──→ │ Testaaja │
│ Analysoi │     │ Koodaa   │     │ Arvioi   │
│ tehtävä  │     │ ratkaisu │     │ koodi    │
└──────────┘     └──────────┘     └──────────┘

async function kpnPipeline(task) {
    const plan = await kpnRun('qwen-coder', `Analysoi: ${task}`);
    if (!plan) return;
    const code = await kpnRun('qwen-coder', `Koodaa: ${plan}`);
    if (!code) return;
    await kpnRun('smollm-135m', `Arvioi: ${code}`);
}

8.2 Agenttien promptien hallinta

const agentPrompts = {
    manager: { model: 'qwen-coder', prompt: 'Olet projektipäällikkö...' },
    coder:   { model: 'qwen-coder', prompt: 'Olet ohjelmistokehittäjä...' },
    // ...
};
// Tallennetaan localStorage:en per agentti
localStorage.setItem('kpn-agent-prompt-coder', customPrompt);

8.3 Yhteinen promptikonteksti

async function kpnRun(model, prompt) {
    const parts = [];
    if (sharedPrompt) parts.push(sharedPrompt);           // Kaikille yhteinen
    if (agent.prompt) parts.push(agent.prompt);            // Agenttikohtainen
    parts.push(prompt);                                     // Käyttäjän pyyntö
    const fullPrompt = parts.join('\n\n');
    // → HTTP POST /api/v1/chat/completions
}

---

9. Teknologiapino

Kerros	Teknologia	Tarkoitus
Frontend	Vanilla JS + HTML + CSS	Ei build-steppiä, toimii suoraan
Wasm	Rust + wasm-bindgen	Inferenssi selaimessa
LLM	Candle (Rust)	Transformer-inferenssi CPU:lla
Tensorit	Burn (Rust)	GPU-tensorilaskenta (WebGPU/NdArray)
Backend	Axum + Tokio (Rust)	Async WebSocket + HTTP -palvelin
Tietokanta	SQLite (rusqlite)	Sessiot ja tulokset
Cache	IndexedDB	Mallipainot selaimen pysyvässä muistissa
Korostus	Highlight.js (CDN)	Syntaksikorostus, automaattinen kielentunnistus
Tokenizer	HuggingFace tokenizers	BPE-tokenisaatio Wasmissa

---

10. Jatkokehitysideoita

Näiden rakennuspalasten pohjalta voi rakentaa:

• Oma chat-UI: WebSocket + streaming + syntaksikorostus
• Hajautettu laskentaverkko: Hub + node-rekisteri + busy-state + työjono
• Selain-LLM: Wasm + Candle + IndexedDB-cache + warmup
• Agenttipohjainen työnkulku: Pipeline + prompt-orkestrointi + reititys
• Terminaaliemulasttori: Input + historia + tab-completion + dropdown
• Reaaliaikadashboard: WebSocket broadcast + tilaindikaattorit + metriikat