@xom11/whiteboard 0.24.2 → 0.25.0

package/README.md

@@ -63,7 +63,7 @@ export function ClassroomBoard() {
 
 ### AI dựng hình học 2D (opt-in)
 
-Textarea AI chỉ xuất hiện khi truyền `generateGeometryFigure`. Callback này chạy từ client nên phải gọi một server boundary của ứng dụng; không đưa `ANTHROPIC_API_KEY` vào component hoặc biến môi trường public.
+Textarea AI chỉ xuất hiện khi truyền `generateGeometryFigure`. Callback chạy từ client nên phải gọi server boundary của ứng dụng; không bao giờ đặt API key vào component / biến môi trường public.
 
 ```tsx
 'use client';
@@ -85,29 +85,102 @@ export function ClassroomBoard() {
 }
 ```
 
-Ví dụ route phía server trong Next.js:
+#### Provider backend (chọn 1)
+
+Từ phiên bản hỗ trợ multi-provider, có 2 lựa chọn:
+
+**A. Local Gemma 3 qua Ollama (mặc định, miễn phí, không cần API key)**
+
+Setup máy chạy server:
+
+```bash
+# macOS
+brew install ollama
+ollama serve                  # chạy nền cổng 11434
+
+# Chọn 1 trong 2 model:
+ollama pull gemma3:4b         # ~3.3GB Q4 — nhanh ~20s/đề, accuracy 75%
+ollama pull gemma3:12b        # ~8GB Q4  — chậm ~60s/đề, accuracy 92% (recommended cho production)
+
+# Linux
+curl -fsSL https://ollama.com/install.sh | sh
+ollama serve &
+ollama pull gemma3:12b
+```
+
+**Eval 12 đề THCS/lớp 10** (transpile success rate + dùng đúng primitive):
+
+| Model     | Transpile OK | Kind đúng | Refuse đúng | Avg latency |
+|-----------|--------------|-----------|-------------|-------------|
+| gemma3:4b  | 75%         | 63%       | 0/1         | 20s         |
+| gemma3:12b | 92%         | 88%       | 1/1         | 62s         |
+| Claude Opus 4.7 | ~100%  | ~100%     | 1/1         | ~5s (cost ~$0.01/đề) |
+
+Đề nghị: 12b cho production, 4b cho prototype/máy yếu, Anthropic cho accuracy tuyệt đối.
+
+Server-side route Next.js:
 
 ```ts
 import { generateFigure } from '@xom11/whiteboard/ai';
 
 export async function POST(request: Request) {
   const { problem } = await request.json();
-  const result = await generateFigure(problem, {
-    apiKey: process.env.ANTHROPIC_API_KEY ?? '',
-  });
+  // Default: provider=ollama, model=gemma3:4b, baseUrl=http://localhost:11434
+  const result = await generateFigure(problem);
   return Response.json(
-    result.ok
-      ? { ok: true, state: result.state }
-      : { ok: false, message: result.message },
+    result.ok ? { ok: true, state: result.state } : { ok: false, message: result.message },
   );
 }
 ```
 
-Trong repo package, chạy smoke/eval với API key chỉ ở local shell:
+Env override (optional):
+
+```bash
+WHITEBOARD_AI_PROVIDER=ollama          # default
+OLLAMA_BASE_URL=http://localhost:11434 # default
+OLLAMA_DEFAULT_MODEL=gemma3:12b        # default gemma3:4b; recommend gemma3:12b cho production
+```
+
+**B. Anthropic Claude (chính xác cao, tốn API cost)**
+
+```ts
+import { generateFigure } from '@xom11/whiteboard/ai';
+
+const result = await generateFigure(problem, {
+  apiKey: process.env.ANTHROPIC_API_KEY ?? '',
+});
+```
+
+Hoặc qua env:
+
+```bash
+WHITEBOARD_AI_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+**C. Provider tuỳ biến** (vd OpenAI, OpenRouter, vLLM): implement interface `AIProvider`:
+
+```ts
+import { generateFigure, type AIProvider } from '@xom11/whiteboard/ai';
+
+const customProvider: AIProvider = {
+  name: 'my-llm',
+  defaultModel: 'my-model',
+  async call(req) {
+    // req.systemPrompt, req.userPrompt, req.schema (JSON Schema cho envelope)
+    // ...
+    return { kind: 'json', data: envelopeObject };
+  },
+};
+
+const result = await generateFigure(problem, { provider: customProvider });
+```
+
+#### Smoke test local Ollama
 
 ```bash
-ANTHROPIC_API_KEY=... npm run ai:smoke
-ANTHROPIC_API_KEY=... npm run ai:eval -- --limit 5
+brew install ollama && ollama serve & ollama pull gemma3:4b
+OLLAMA_SMOKE=1 npx jest ollama.smoke
 ```
 
 ## Migration to v0.8.0 (geometry-3d redesign)