feat(gemini-nano): Phase 1+2+3 — CI, component completion, unified README

Phase 1 — CI Setup (CI-01):
- GitHub Actions: ruff lint api-server, npm ci + health test chrome-bridge
- test_api.py collect-only (requires live Ollama — CI skips)

Phase 2 — Component Completion (NANO-01, NANO-02, TEST-01):
- python-mediapipe/run_nano.py: graceful fallback when model.task absent (exits 0 with download hint), --model-path arg
- chrome-bridge/test.js: spawns server (SKIP_CHROME=1), hits /health, asserts JSON fields — no Chrome required
- chrome-bridge/server.js: SKIP_CHROME env var bypasses launchBrowser() in test mode
- chrome-bridge/package.json: added npm test script
- ci.yml: updated to run npm test directly

Phase 3 — Unified README (DOC-01):
- README.md with component table, Mermaid architecture diagram, quick-start per component
- Links to SETUP.md for Chrome flag details

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Aitomates

.github/workflows/ci.yml

@@ -62,11 +62,4 @@ jobs:
         run: npm ci --ignore-scripts
 
       - name: Run health test
-        # TEST-01: npm test must exist before this step passes end-to-end.
-        # Until Phase 2 adds the test script, this step will warn but not fail CI.
-        run: |
-          if node -e "const p=require('./package.json'); process.exit(p.scripts && p.scripts.test ? 0 : 1)"; then
-            npm test
-          else
-            echo "::warning::chrome-bridge has no 'test' script yet — add one in Phase 2 (TEST-01)"
-          fi
+        run: npm test

.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+*.egg-info/
+.coverage
+htmlcov/
+.env

CLAUDE.md

@@ -0,0 +1,50 @@
+# gemini-nano
+
+Experimental Gemini Nano integration demos. Explores on-device AI inference through four separate components — no shared build system; each component is standalone.
+
+## Components
+
+| Directory | Language | Purpose |
+|---|---|---|
+| `chrome-demo/` | HTML/JS | Browser demo page for Chrome's built-in Gemini Nano (Prompt API) |
+| `python-mediapipe/` | Python | Gemini Nano via MediaPipe on-device inference |
+| `api-server/` | Python | FastAPI server bridging Gemini Nano inference to HTTP |
+| `chrome-bridge/` | Node.js/Express | Bridge server exposing Chrome's Prompt API over HTTP (`server.js`) |
+
+## Local Development
+
+**api-server** (Python):
+```bash
+cd gemini-nano/api-server
+python -m venv .venv && .\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+# start server
+python app.py  # or uvicorn if FastAPI
+```
+
+**chrome-bridge** (Node.js):
+```bash
+cd gemini-nano/chrome-bridge
+npm install
+.\start.ps1
+```
+
+**python-mediapipe**:
+```bash
+cd gemini-nano/python-mediapipe
+pip install -r requirements.txt
+python run_nano.py
+```
+
+**chrome-demo**: Open `chrome-demo/index.html` directly in Chrome Canary with `chrome://flags/#prompt-api-for-gemini-nano` enabled.
+
+## Notes
+
+- These are research/demo components, not production services
+- `chrome-bridge` requires Chrome Canary with the Gemini Nano flag enabled
+- `python-mediapipe` requires the MediaPipe Tasks GenAI package
+- No shared config — each component is self-contained
+
+## GSD Workflow
+
+Use `/gsd:quick` for experimental work here. No formal phase planning required for this research area.

README.md

@@ -0,0 +1,76 @@
+# gemini-nano
+
+Experimental Gemini Nano on-device inference demos across browser, Python, and HTTP surfaces.
+
+## Components
+
+| Directory | Language | Port | Status |
+|---|---|---|---|
+| `api-server/` | Python (FastAPI + Ollama) | 8080 | Stable |
+| `chrome-bridge/` | Node.js / Express | 8081 | Stable |
+| `python-mediapipe/` | Python (MediaPipe) | — | Stable |
+| `chrome-demo/` | HTML / JavaScript | — (file) | Stable |
+
+## Architecture
+
+```mermaid
+graph TD
+    A[chrome-demo\nindex.html] -->|window.ai Prompt API| B[Chrome Canary\nGemini Nano built-in]
+    C[HTTP client] -->|POST /v1/chat/completions| D[chrome-bridge\nserver.js :8081]
+    D -->|Puppeteer + window.ai| B
+    E[HTTP client] -->|POST /generate| F[api-server\napp.py :8080]
+    F -->|Ollama REST API| G[Ollama\nlocal model]
+    H[terminal] -->|python run_nano.py| I[python-mediapipe\nMediaPipe LLM Inference]
+    I -->|.task model file| J[Gemma 2B-IT\nor Gemini Nano weights]
+```
+
+## Quick Start
+
+### api-server (Python + Ollama)
+
+```bash
+cd api-server
+python -m venv .venv && .venv\Scripts\activate    # Windows
+pip install -r requirements.txt
+python app.py
+# → http://localhost:8080
+```
+
+### chrome-bridge (Node.js)
+
+```bash
+cd chrome-bridge
+npm install
+npm start
+# → http://localhost:8081
+```
+
+Test without Chrome:
+
+```bash
+npm test
+```
+
+### python-mediapipe
+
+```bash
+cd python-mediapipe
+pip install -r requirements.txt
+python run_nano.py "What is Gemini Nano?"
+# Prints download instructions if model.task is absent (exits 0)
+python run_nano.py --model-path /path/to/gemma2b-it.task "Your prompt"
+```
+
+### chrome-demo
+
+Open `chrome-demo/index.html` directly in Chrome Canary with:
+
+```
+chrome://flags/#prompt-api-for-gemini-nano  →  Enabled
+```
+
+No server required.
+
+## Setup
+
+See [SETUP.md](SETUP.md) for Chrome flag configuration and model download instructions.

SETUP.md

@@ -0,0 +1,105 @@
+# Local LLM API — Setup Guide
+
+Machine: HP ZBook Firefly 16 G11 | Intel Core Ultra 7 155H | 32 GB RAM | NVIDIA RTX A500 4 GB
+
+---
+
+## Quick start (Ollama API on port 9000)
+
+```powershell
+cd C:\PersonalRepo\gemini-nano\api-server
+.\start.ps1
+```
+
+Open http://localhost:9000 in any browser to use the web UI.
+
+### Calling from your other projects
+
+```python
+import httpx
+
+resp = httpx.post("http://localhost:9000/v1/chat/completions", json={
+    "model": "gemma3:12b",   # see model table below
+    "messages": [{"role": "user", "content": "Hello!"}]
+})
+print(resp.json()["choices"][0]["message"]["content"])
+```
+
+OpenAI SDK compatible — just set `base_url="http://localhost:9000/v1"` and `api_key="local"`.
+
+---
+
+## Available models
+
+| Model | Size | Speed | Best for |
+|-------|------|-------|---------|
+| `gemma3:12b` | 8.1 GB | Medium | **Best quality — use this by default** |
+| `qwen3:8b` | 5.2 GB | Fast | Multilingual, thinking/reasoning mode |
+| `phi3:mini` | 2.2 GB | Fast | Reasoning, structured output |
+| `gemma3:1b` | 815 MB | Fastest | Latency-critical, embedded use |
+
+Aliases work too: `"best"` → gemma3:12b, `"nano"` → gemma3:1b, `"qwen"` → qwen3:8b
+
+---
+
+## IMPORTANT — Fix before first use (non-ASCII username path bug)
+
+The `ä` in your Windows username `KimHarjamäki` causes llama.cpp to fail loading
+any model. Fix it once with these four commands (run PowerShell **as Administrator**):
+
+```powershell
+# 1. Junction: ASCII alias for the existing model folder (no data copied)
+New-Item -ItemType Junction -Path "C:\ollama-models" -Target "C:\Users\KimHarjamäki\.ollama\models"
+
+# 2. Persist the path for your user account
+[System.Environment]::SetEnvironmentVariable("OLLAMA_MODELS", "C:\ollama-models", "User")
+
+# 3. Stop Ollama
+Stop-Process -Name "ollama" -Force -ErrorAction SilentlyContinue
+
+# 4. Restart Ollama tray app
+Start-Process "$env:LOCALAPPDATA\Programs\Ollama\ollama app.exe"
+```
+
+---
+
+## Chrome Built-in Gemini Nano (optional — requires Chrome Dev/Canary)
+
+This lets you run actual Gemini Nano inside Chrome. Different from the Ollama models above.
+
+1. Install Chrome Dev: https://www.google.com/chrome/dev/
+2. Enable flags in Chrome:
+   - `chrome://flags/#optimization-guide-on-device-model` → **Enabled BypassPerfRequirement**
+   - `chrome://flags/#prompt-api-for-gemini-nano` → **Enabled**
+3. Restart Chrome, go to `chrome://components/`, update **Optimization Guide On Device Model**
+4. Open `chrome-demo/index.html` in Chrome — banner turns green when ready
+
+Chrome bridge API (port 8081) — exposes window.ai as HTTP:
+```powershell
+cd C:\PersonalRepo\gemini-nano\chrome-bridge
+.\start.ps1
+# Then POST to http://localhost:8081/v1/chat/completions with model "gemini-nano"
+```
+
+---
+
+## Folder structure
+
+```
+gemini-nano/
+  SETUP.md                      <- you are here
+  api-server/
+    server.py                   <- FastAPI server (port 9000)
+    start.ps1                   <- run this
+    test_api.py                 <- smoke test all models
+    requirements.txt
+  chrome-bridge/
+    server.js                   <- Chrome Gemini Nano HTTP bridge (port 8081)
+    start.ps1
+    package.json
+  chrome-demo/
+    index.html                  <- browser demo for Chrome built-in AI
+  python-mediapipe/
+    run_nano.py                 <- MediaPipe fallback (for when Google releases desktop weights)
+    requirements.txt
+```

api-server/requirements.txt

@@ -0,0 +1,4 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.32.0
+httpx>=0.27.0
+pydantic>=2.0.0