# Kipinä Agentic Network — Hajautettu AI-laskentaverkko

Kipinä Agentic Network on hajautettu tekoälylaskentaverkko, jossa selaimet ja natiivit solmut tarjoavat GPU-laskentatehoa yhteiseen käyttöön. Hub-palvelin koordinoi tehtäviä ja solmut suorittavat ne WebGPU:lla tai CPU:lla.

## Miten se toimii

```
┌──────────┐     WebSocket     ┌──────────┐     WebSocket     ┌──────────────┐
│  Selain  │◄─────────────────►│   Hub    │◄─────────────────►│ Natiivi-node │
│  (Wasm)  │  tehtävät/tulokset│ (Axum)   │  tehtävät/tulokset│   (Rust)     │
│  WebGPU  │                   │ :3000    │                   │ NVML/sysinfo │
└──────────┘                   └──────────┘                   └──────────────┘
     │                              │
     └── CPU fallback (NdArray)     └── Dashboard + statistiikat
         jos WebGPU ei tuettu
```

**Hub** jakaa tehtäviä (tokenisointiparit, LLM-promptit, kooditehtävät) 10 sekunnin välein. Solmut käsittelevät vain valitsemansa tehtävätyypin mukaisia viestejä.

## Kolme tapaa osallistua verkkoon

### 1. Selainsolmu — Laskentaverkko
- Avaa `http://localhost:3000` | `https://kipina.studio` ja valitse tehtävä:
  - **Tokenisointivertailu** — EN/FI-kieliparien BPE-tokenisointitehokkuus (~7 MB lataus)
  - **SmolLM 135M** — kevyt LLM-inferenssi (~269 MB, ~1.2 tok/s)
  - **Qwen2.5 0.5B** — tehokkaampi LLM (~990 MB, ~0.4 tok/s)
  - **Phi-3 Mini 3.8B** — vain native-nodella
- WebGPU tunnistetaan automaattisesti, CPU-fallback jos ei tuettu
- Mallit ja tokenizerit cachetetaan IndexedDB:hen

### 2. Selainsolmu — Koodilaboratorio
- Erillinen välilehti: **Qwen2.5-Coder** koodigenerointi
- Valittavissa **0.5B** (nopea) tai **3B** (laadukas, 6.2 GB lataus)
- Oma promptti: kirjoita Python-ohjelmointitehtävä ja paina "Generate"
- Syntaksikorostettu koodivastaus

### 3. Natiivi-node (Rust + CUDA/CPU)
- Qwen2.5-0.5B-Instruct inferenssi CUDA:lla (~50-100 tok/s RTX 4090) tai CPU:lla (~11 tok/s)
- Kerää nvidia-smi-tason laitteistotiedot: GPU-nimi, VRAM, lämpötila, kuormitus
- Lataa mallin automaattisesti HuggingFace Hubista (~990 MB, cachetetaan)

## Käynnistys

### Docker Compose (suositeltu)

```bash
# Hub + selainsolmu
docker compose up

# Hub + selainsolmu + natiivi-node (vaatii nvidia-container-toolkit)
docker compose --profile native up
```

Dashboard avautuu osoitteessa http://localhost:3000 | https://kipina.studio

### Ilman Dockeria

```bash
# 1. Rakenna Wasm-paketti (vaatii wasm-pack)
cd node && wasm-pack build --target web --out-dir ../static/pkg && cd ..

# 2. Käynnistä hub (terminaali 1)
cargo run -p hub

# 3. Avaa selain: http://localhost:3000 | https://kipina.studio

# 4. Valinnainen: natiivi-node LLM-inferenssillä (terminaali 2)
# Lataa Qwen2.5-0.5B automaattisesti HuggingFacesta (~990 MB, cachetetaan)
# Release-moodissa ~11 tok/s CPU:lla (32 ydintä)
CARGO_TARGET_DIR=target-native HUB_URL=ws://localhost:3000/ws ALLOCATED_GB=4 cargo run --release -p native-node


# Tai yhdistä tuotantopalvelimeen:
CARGO_TARGET_DIR=target-native HUB_URL=wss://kipina.studio/ws ALLOCATED_GB=4 cargo run --release -p native-node
```

### CUDA-tuki

CUDA on oletuksena päällä native-nodessa. Vaatii `nvidia-cuda-toolkit`:n:

```bash
# Asenna (Ubuntu/Pop!_OS)
sudo apt install nvidia-cuda-toolkit

# Tarkista
nvcc --version

# Aja — tunnistaa CUDA:n automaattisesti, fallback CPU:lle
CARGO_TARGET_DIR=target-native HUB_URL=ws://localhost:3000/ws cargo run --release -p native-node

# Tuotantoon
CARGO_TARGET_DIR=target-native HUB_URL=wss://kipina.studio/ws cargo run --release -p native-node
```

Jos CUDA:a ei ole, poista feature: `candle-core = { version = "0.8" }` (ilman `features = ["cuda"]`).

## WebGPU-asetukset selaimessa

WebGPU ei ole oletuksena päällä kaikissa selaimissa. Jos "Liity laskentaverkkoon" -nappi käynnistää CPU-fallbackin vaikka koneessa on näytönohjain:

**Chrome / Brave (Linux APT/DEB):**
```bash
google-chrome --enable-unsafe-webgpu --enable-features=Vulkan --ignore-gpu-blocklist --use-angle=vulkan --ozone-platform=x11 https://kipina.studio

brave-browser --enable-unsafe-webgpu --enable-features=Vulkan --ignore-gpu-blocklist --use-angle=vulkan --ozone-platform=x11 https://kipina.studio
```

**Chrome / Brave (Linux Flatpak):**
```bash
flatpak run com.google.Chrome --enable-unsafe-webgpu --enable-features=Vulkan --ignore-gpu-blocklist --use-angle=vulkan --ozone-platform=x11 https://kipina.studio

flatpak run com.brave.Browser --enable-unsafe-webgpu --enable-features=Vulkan --ignore-gpu-blocklist --use-angle=vulkan --ozone-platform=x11 https://kipina.studio
```

**Chrome / Brave (Windows / Mac):**
1. Avaa `chrome://flags`
2. Ota käyttöön "WebGPU" ja "Vulkan"
3. Käynnistä selain uudelleen

**Firefox:** `about:config` → `dom.webgpu.enabled` = `true`

**Safari:** Develop → Feature Flags → WebGPU

## Projektin rakenne

```
network-poc/
├── hub/                  # Keskuspalvelin (Rust + Axum)
│   └── src/
│       ├── main.rs       #   WebSocket-reititin, tehtävien jakelu, admin HTML, Basic Auth
│       └── db.rs         #   SQLite: node_sessions, pair_results
├── node/                 # Selainsolmu (Rust → Wasm)
│   └── src/
│       ├── lib.rs         #   Wasm-entrypoint, tehtävävalinta, WS-handler
│       ├── storage.rs     #   IndexedDB-välimuisti
│       ├── sampling.rs    #   Top-k sampling (EOS-penaltti)
│       ├── smollm.rs      #   SmolLM 135M inferenssi
│       ├── qwen.rs        #   Qwen2.5 0.5B inferenssi
│       ├── qwen_coder.rs  #   Qwen2.5-Coder 0.5B/3B koodigenerointi
│       └── phi3.rs        #   Phi-3 placeholder
├── native-node/          # Natiivi-solmu (Rust + CUDA)
│   └── src/
│       ├── main.rs       #   GPU-tunnistus, WS-yhteys, tehtäväkäsittely
│       └── inference.rs  #   Qwen2.5-0.5B Candle-inferenssi (CUDA/CPU)
├── static/
│   ├── index.html        # Dashboard + Koodilaboratorio
│   └── pkg/              # Wasm-build (generoidaan)
├── deploy.sh             # Lokaali build → palvelimelle
├── docker-compose.yml    # Kehitys
├── docker-compose.prod.yml # Tuotanto (Caddy + Hub)
├── docker-compose.client.yml # Client-nodejen Docker
├── Dockerfile.prod       # Tuotanto-image (cache mount)
└── Caddyfile.prod        # TLS + reverse proxy
```

## Ympäristömuuttujat

| Muuttuja | Oletus | Kuvaus |
|---|---|---|
| `HUB_URL` | `ws://hub:3000/ws` | Hub-palvelimen WebSocket-osoite (native-node) |
| `ALLOCATED_GB` | `4` | Solmun varaama muisti verkosta (GB) |
| `ADMIN_PASSWORD` | `kipina` | Admin-sivun ja API:n salasana (Basic Auth) |
| `DATABASE_PATH` | `nodes.db` | SQLite-tietokannan polku |
| `STATIC_DIR` | `../static` | Staattisten tiedostojen kansio |

## Admin-sivu

`https://kipina.studio/admin` (Basic Auth, salasana: `ADMIN_PASSWORD`)

Sisältää:
- Node-sessiot: IP, laitetiedot, GPU, WebGPU-tuki, tehtävätyyppi, uptime
- Tokenisointitulokset: EN/FI-vertailut, ylikustannus-%
- Yhteenvetotilastot: sessiot, WebGPU vs CPU, keskiarvot

## Projektin tila

Toimivat ominaisuudet:
- Tokenisointivertailu (EN/FI, BPE, top-k sampling)
- SmolLM 135M inferenssi selaimessa (Candle + Wasm)
- Qwen2.5 0.5B inferenssi selaimessa (Candle + Wasm)
- Qwen2.5-Coder 0.5B/3B koodigenerointi (Koodilaboratorio-välilehti)
- Native node + CUDA (RTX 4090: ~50-100 tok/s)
- Admin-dashboard + SQLite + Basic Auth
- Deploy-skripti (lokaali build → palvelin)
- WebGPU + CPU fallback, GPU-tunnistus (NVIDIA/AMD/Apple)