@xom11/whiteboard 0.24.1 → 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';
+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)

package/dist/ai.d.mts

@@ -0,0 +1,472 @@
+import { b as State, D as DslInputT, a as AiFigureUiResult } from './types-DWRyCa2m.mjs';
+import { z } from 'zod';
+import 'react';
+import '@excalidraw/excalidraw/element/types';
+
+type TranspileErrorCode = 'SCHEMA' | 'DUPLICATE_NAME' | 'UNKNOWN_REF' | 'KIND_MISMATCH' | 'CYCLE';
+interface TranspileError {
+    code: TranspileErrorCode;
+    message: string;
+    path?: string[];
+    hint?: string;
+}
+
+interface ProviderTokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /** Anthropic prompt caching — local provider để 0. */
+    cacheReadTokens?: number;
+    /** Anthropic prompt caching — local provider để 0. */
+    cacheCreationTokens?: number;
+}
+interface ProviderRequest {
+    systemPrompt: string;
+    userPrompt: string;
+    /**
+     * JSON Schema mà provider phải honor để constrain output. Anthropic → wrap
+     * thành tool input_schema. Ollama → pass thẳng vào `format` (v0.5+).
+     */
+    schema: Record<string, unknown>;
+    /** Provider-specific model id (vd "gemma3:4b", "claude-opus-4-7"). */
+    model: string;
+    /** Token cap cho response. */
+    maxTokens: number;
+    signal?: AbortSignal;
+}
+type ProviderOutput = {
+    kind: 'json';
+    data: unknown;
+    usage?: ProviderTokenUsage;
+} | {
+    kind: 'error';
+    message: string;
+    status?: number;
+};
+interface AIProvider {
+    /** Tên định danh ("anthropic", "ollama", ...). */
+    readonly name: string;
+    /** Default model id khi caller không truyền. */
+    readonly defaultModel: string;
+    call(req: ProviderRequest): Promise<ProviderOutput>;
+}
+
+interface AnthropicProviderOptions {
+    apiKey: string;
+    /** Cache system prompt qua Anthropic prompt-caching (mặc định bật). */
+    enableCaching?: boolean;
+}
+declare class AnthropicProvider implements AIProvider {
+    private readonly opts;
+    readonly name = "anthropic";
+    readonly defaultModel = "claude-opus-4-7";
+    constructor(opts: AnthropicProviderOptions);
+    call(req: ProviderRequest): Promise<ProviderOutput>;
+}
+
+interface OllamaProviderOptions {
+    /** Endpoint base URL, default http://localhost:11434. */
+    baseUrl?: string;
+    /** Default model id nếu request không truyền. */
+    defaultModel?: string;
+    /** Custom fetch impl (dùng cho test mock). */
+    fetchImpl?: typeof fetch;
+}
+declare class OllamaProvider implements AIProvider {
+    readonly name = "ollama";
+    readonly defaultModel: string;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(opts?: OllamaProviderOptions);
+    private resolveFetch;
+    call(req: ProviderRequest): Promise<ProviderOutput>;
+}
+
+interface SelectProviderOptions {
+    /** Provider instance dùng trực tiếp (override mọi env). */
+    provider?: AIProvider;
+    /** Anthropic API key. Khi truyền → auto chọn AnthropicProvider. */
+    apiKey?: string;
+    /** Anthropic prompt-caching, default true (chỉ áp dụng provider Anthropic). */
+    enableCaching?: boolean;
+    /** Ollama endpoint override. */
+    ollamaBaseUrl?: string;
+    /** Ollama model override (vd "gemma3:1b"). */
+    ollamaDefaultModel?: string;
+    /** Test env: env vars getter (default process.env). */
+    env?: Record<string, string | undefined>;
+}
+declare function selectProvider(opts?: SelectProviderOptions): AIProvider;
+
+interface GenerateOptions extends SelectProviderOptions {
+    /** Model id override (provider-specific). Mặc định: provider.defaultModel. */
+    model?: string;
+    maxTokens?: number;
+    signal?: AbortSignal;
+}
+interface TokenUsage$1 {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+}
+type GenerateResult = {
+    ok: true;
+    state: State;
+    dsl: DslInputT;
+    usage: TokenUsage$1;
+    provider: string;
+} | {
+    ok: false;
+    reason: 'refused';
+    message: string;
+    usage?: TokenUsage$1;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'parse_error';
+    message: string;
+    raw?: unknown;
+    usage?: TokenUsage$1;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'transpile_error';
+    message: string;
+    errors: TranspileError[];
+    dsl: unknown;
+    usage?: TokenUsage$1;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'api_error';
+    message: string;
+    status?: number;
+    provider?: string;
+};
+declare function generateFigure(problem: string, opts?: GenerateOptions): Promise<GenerateResult>;
+
+interface HandleGenerateFigureInput {
+    /** Đề bài tiếng Việt từ teacher. */
+    problem: string;
+}
+interface HandleGenerateFigureOptions extends GenerateOptions {
+    /**
+     * Optional telemetry hook. Gọi cho MỖI attempt với envelope nội bộ trước
+     * khi map sang AiFigureUiResult — consumer dùng để log usage/cost/error.
+     * Không throw từ logger — sẽ swallow để không vỡ response.
+     *
+     * @param result GenerateResult của attempt
+     * @param attempt 1-indexed (1 = lần đầu, 2 = retry, ...)
+     */
+    onResult?: (result: GenerateResult, attempt: number) => void;
+    /**
+     * Số attempt tối đa khi nhận `transpile_error`. Default 2 (1 retry).
+     * AI stochastic → lần 2 thường khá hơn. Min 1, max 5.
+     */
+    maxAttempts?: number;
+}
+/**
+ * Gọi AI orchestrator và trả về kết quả ở dạng `AiFigureUiResult` mà
+ * `<Whiteboard generateGeometryFigure>` chấp nhận trực tiếp.
+ *
+ * Auto-retry: chỉ retry khi `transpile_error` (DSL không hợp lệ — model
+ * stochastic có cơ hội emit khá hơn lần 2). KHÔNG retry `refused` (AI cố ý
+ * từ chối), `parse_error` (envelope sai schema — chắc chắn sai mọi lần),
+ * hay `api_error` (network / config — không liên quan model).
+ *
+ * Mapping:
+ *   - ok=true             → { ok: true, state }
+ *   - refused             → { ok: false, message: <message AI gửi> }
+ *   - parse_error         → { ok: false, message: 'AI trả JSON không hợp lệ…' }
+ *   - transpile_error     → { ok: false, message: 'AI tạo hình không hợp lệ…' }
+ *   - api_error           → { ok: false, message: <message gốc> }
+ *
+ * Server-side caller giữ `GenerateResult` đầy đủ qua `onResult` callback cho
+ * mục đích telemetry/logging.
+ */
+declare function handleGenerateFigure(input: HandleGenerateFigureInput, opts?: HandleGenerateFigureOptions): Promise<AiFigureUiResult>;
+
+declare const FigureEnvelopeZ: z.ZodEffects<z.ZodObject<{
+    decision: z.ZodEnum<["build", "refuse"]>;
+    figure: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        points: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, ...z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>[]]>, "many">;
+        shapes: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, ...z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>[]]>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    }, {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    decision: "build" | "refuse";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    } | undefined;
+}, {
+    decision: "build" | "refuse";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    } | undefined;
+}>, {
+    decision: "build" | "refuse";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    } | undefined;
+}, {
+    decision: "build" | "refuse";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    } | undefined;
+}>;
+type FigureEnvelopeT = z.infer<typeof FigureEnvelopeZ>;
+declare function envelopeJsonSchema(): Record<string, unknown>;
+/** Helper: ép envelope build hợp lệ về DslInputT (sau khi đã validate). */
+declare function envelopeBuildDsl(env: FigureEnvelopeT): DslInputT;
+
+interface GenerateDeltaOptions extends SelectProviderOptions {
+    model?: string;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    maxAttempts?: number;
+}
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+}
+type GenerateDeltaResult = {
+    ok: true;
+    state: State;
+    mergedDsl: DslInputT;
+    mode: 'add' | 'replace';
+    usage: TokenUsage;
+    provider: string;
+} | {
+    ok: false;
+    reason: 'refused';
+    message: string;
+    usage?: TokenUsage;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'parse_error';
+    message: string;
+    raw?: unknown;
+    usage?: TokenUsage;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'transpile_error';
+    message: string;
+    errors: TranspileError[];
+    dsl: unknown;
+    usage?: TokenUsage;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'name_collision';
+    message: string;
+    collisions: string[];
+    errors: TranspileError[];
+    dsl: unknown;
+    usage?: TokenUsage;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'unresolved_ref';
+    message: string;
+    refs: string[];
+    errors: TranspileError[];
+    dsl: unknown;
+    usage?: TokenUsage;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'api_error';
+    message: string;
+    status?: number;
+    provider?: string;
+};
+interface GenerateFigureDeltaInput {
+    problem: string;
+    currentDsl: DslInputT;
+}
+declare function generateFigureDelta(input: GenerateFigureDeltaInput, opts?: GenerateDeltaOptions): Promise<GenerateDeltaResult>;
+
+interface HandleGenerateFigureDeltaInput {
+    problem: string;
+    currentDsl: DslInputT;
+}
+interface HandleGenerateFigureDeltaOptions extends GenerateDeltaOptions {
+    onResult?: (result: GenerateDeltaResult, attempt: number) => void;
+    maxAttempts?: number;
+}
+declare function handleGenerateFigureDelta(input: HandleGenerateFigureDeltaInput, opts?: HandleGenerateFigureDeltaOptions): Promise<AiFigureUiResult>;
+
+declare const FigureRefineEnvelopeZ: z.ZodEffects<z.ZodObject<{
+    decision: z.ZodEnum<["add", "replace", "refuse"]>;
+    figure: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        points: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, ...z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>[]]>, "many">;
+        shapes: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, ...z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>[]]>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    }, {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    decision: "refuse" | "add" | "replace";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    } | undefined;
+}, {
+    decision: "refuse" | "add" | "replace";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    } | undefined;
+}>, {
+    decision: "refuse" | "add" | "replace";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    } | undefined;
+}, {
+    decision: "refuse" | "add" | "replace";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    } | undefined;
+}>;
+type FigureRefineEnvelopeT = z.infer<typeof FigureRefineEnvelopeZ>;
+declare function refineEnvelopeJsonSchema(): Record<string, unknown>;
+
+export { type AIProvider, AnthropicProvider, type FigureEnvelopeT, FigureEnvelopeZ, type FigureRefineEnvelopeT, FigureRefineEnvelopeZ, type GenerateDeltaOptions, type GenerateDeltaResult, type GenerateFigureDeltaInput, type GenerateOptions, type GenerateResult, type HandleGenerateFigureDeltaInput, type HandleGenerateFigureDeltaOptions, type HandleGenerateFigureInput, type HandleGenerateFigureOptions, OllamaProvider, type ProviderOutput, type ProviderRequest, type ProviderTokenUsage, type SelectProviderOptions, type TokenUsage$1 as TokenUsage, envelopeBuildDsl, envelopeJsonSchema, generateFigure, generateFigureDelta, handleGenerateFigure, handleGenerateFigureDelta, refineEnvelopeJsonSchema, selectProvider };