agentic-studio/network-poc/REQUIREMENTS.md

Agentic Office - Kipinä Hajautettu Verkkoprojekti

Tässä on kooste projektin vaatimuksista, työtehtävistä ja niiden nykytilanteesta. Tämä dokumentti on jatkuvasti päivittyvä kuvaus siitä, mitä tavoitellaan ja mitä on jo tehty.

🚀 Vaihe 1: Rust + Wasm Selain-Nodet (Selainpohjainen P2P)

Tavoitteet

• Madaltaa käyttäjän osallistumiskynnys "yhteen klikkaukseen".
• Selainkäyttäjien verkkolaitteen WebGPU:ta hyödyntävä asynkroninen Rust-solmu (Wasm).
• WebSocket-yhteys julkiseen Hubiin, joka jakelee matematiikka/AI-laskentaa eteenpäin Nodeille.

Tehtävät

• Rakenna axum-pohjainen Rust-reititin ja Hub Server (portti 3000)
• Luo Wasm-käännettävä Rust-kirjasto selaimen Node-agentteja varten
• Ota onnistuneesti käyttöön task-jono WebSocketin yli nodejen kanssa
• Pakkaa solmu yhteen helposti levitettävään muotoon (wasm-pack -> static/index.html)
• Tee yksinkertainen kuormalaskenta-algoritmi (Fibonacci) konseptin todentamiseksi
• Tallenna tulokset asynkronisesti käyttöjärjestelmään ja takaisin weppiin

---

🚀 Vaihe 2: Kipinä.studio taustajärjestelmä

Tavoitteet

• Luoda kunnollinen työjono (Job Queue).
• Sijoittaa Hub-palvelin julkisesti saatavuusosoitteeseen kipina.studio.

Tehtävät

• Tuotantopalvelimen käyttöönotto Docker-compose + Caddy TLS kautta (kipina.studio)
• Deploy-skripti (deploy.sh) + Discord-webhook-notifikaatio julkaisuista
• Admin-dashboard (/admin) Basic Auth -suojattuna, live-sessiot ja metriikat
• REST API (POST /api/v1/chat/completions) task_id-pohjaisella vastausten reitityksellä
• API timeout (120s) + selkeät virheilmoitukset (504 Gateway Timeout)
• IP-pohjainen rate limiting (max 4 yhteyttä/IP) + origin-validointi
• Turvamekanismin lisäys: Varmistetaan, ettei kukaan lähetä "falskeja" vastauksia nodeilta (PoW/challenge-response)
• SQLite-sessioseuranta (node_sessions + pair_results)

---

🚀 Vaihe 3 & 4: WebGPU ja Klusterin Statistiikka (VALMIS!)

Tavoitteet

• Korvata simppeli Fibonacci-luuppi aidoimmilla AI-tensoreilla ja laitekiihdytyksellä Burn-kirjastoa (WebGPU) apuna käyttäen.
• Valvoa ja suojella solmujen tehoa reaaliajassa.

Tehtävät

• Integroi burn-wgpu ja burn-core (v0.14.0) kääntymään Wasm-pakettiin
• Valmistele laskettavien tensoreiden välitys Hubilta laitteiston Metal/WebGPU -muistiin
• Koodaa Hubiin logiikka (Broadcast), joka yhdistää jokaisen solmun "4 GB" (oletuksena Mac-koneille) VRAM:in ja julkaisee summan Dashboardiin.
• Teollisuustason GPU "Duty Cycle" Throttling: JS Slider (25%-100%) jarruttaa raskaan WebGPU-ajon välitöntä syöttöä tauottaen laitteistoa ja suojellen käyttöjärjestelmää ylikuormittumukselta.

---

🚀 Vaihe 5: Aito Agentic Compute (Micro-LLM Tekstigeneraatio Verkossa)

Tavoitteet

• Korvata kokeellinen kymmenien tuhansien alkioiden pelkkä satunnais-matriisilaskenta (C=A*B) aidolla asynkronisella LLM-mallilla (esim. Llama-3 1B kvantisoituna / vastaava Transformer).
• Kyetä lataamaan selaimen IndexedDB:hen satojen megatavujen painot massivisena fetch-hakuna, kääntää ne WebGPU-puskureihin (Buffers) ja suorittaa tekstigeneraatiota etänä ohjattuna verkosta käsin WebSocketia myöden.

Tehtävät

• Refaktoroi Wasm-Noden (Burn.rs) paketti tuomaan Text-Tokenizerit (BPE, Qwen2.5-Coder) ja kielimallin arkkitehtuuri käyttöön
• Koodaa Nodeen logiikka hakea / kasata mallin painot välimuistista IndexedDB:hen (tokenizer.json + model weights)
• Hub uudistetaan generoimaan Text Prompts ja reitittämään työkuorman vapaalle solmulle (broadcast + task_id-matching)
• Kipinän käyttöliittymään Chat-ikkuna Hubin striimaamien tulossanojen tarkkailuun reaaliajassa (llm_chunk streaming)
• SmolLM 135M — täysi transformer (Burn), ~1.2 tok/s CPU
• Qwen2.5 0.5B — Candle-inferenssi, ChatML-muotoilu, ~0.4 tok/s CPU
• Qwen2.5-Coder 0.5B & 3B — koodigeneraatio, streaming-tokenit, task_id-tuki
• Phi-3 Mini — placeholder (liian suuri selaimelle, natiivisolmulle suunnitteilla)
• EN/FI tokenisaatiovertailu overhead-laskennalla
• Natiivisolmu (Rust + CUDA) — Qwen2.5 0.5B, ~50-100 tok/s RTX 4090, NVML GPU-metriikat

---

🚀 Vaihe 6: Agent Workspace & CLI (KÄYNNISSÄ)

Tavoitteet

• Interaktiivinen terminaalipohjainen käyttöliittymä kpn-komennoilla.
• Agenttitiimi (Koodari, Testaaja, Manageri) muokattavilla system prompteilla.
• Agenttien ketjutus: manageri analysoi → koodari toteuttaa → testaaja arvioi.

Tehtävät

• KPN-terminaali selaimeen (interaktiivinen komentorivi, komentohistoria)
• kpn run <malli> "<prompti>" — tehtävän lähetys REST API:n kautta
• kpn hello — tervehdyskomento
• kpn pipeline "<tehtävä>" — manageri → koodari → testaaja -ketjutus
• kpn status, kpn models, kpn clear, kpn help
• Agenttikortit (Koodari/Qwen-Coder, Testaaja/SmolLM, Manageri/KPN CLI)
• Muokattavat system promptit per agentti (localStorage-tallennus)
• Multi-select: yhteinen konteksti useammalle agentille
• Streaming-vastaukset terminaalissa (llm_chunk + vilkkuva kursori)
• URL-hash navigointi (#agents, #codelab, #network)
• SPA fallback (ServeDir + ServeFile)
• Agenttien välinen keskustelu (manageri ohjaa koodaria ja testaajaa dynaamisesti)
• Tehtävähistoria ja tulosten tallennus
• CLI-työkalu (kpn binary) lokaaliin käyttöön