@kpritam/grimoire-output-docusaurus 0.1.8

package/templates/spellbook/src/components/SpellbookChat/streamProviders/ollama.ts

@@ -0,0 +1,44 @@
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+
+import { createCloudProvider } from "./createCloudProvider";
+
+const DEFAULT_BASE = "http://localhost:11434/v1";
+
+function normalizeBaseUrl(raw?: string): string {
+  const s = raw?.trim() || DEFAULT_BASE;
+  return s.replace(/\/+$/, "");
+}
+
+export const ollamaProvider = createCloudProvider({
+  id: "ollama",
+  displayName: "Ollama / compatible",
+  tagline: "Local server · Ollama / LM Studio / OpenAI-compatible",
+  models: [
+    { id: "llama3.2", label: "llama3.2" },
+    { id: "llama3.2:3b", label: "llama3.2:3b" },
+    { id: "qwen2.5:3b", label: "qwen2.5:3b" },
+    { id: "phi4:latest", label: "phi4:latest" },
+  ],
+  configFields: [
+    {
+      key: "baseUrl",
+      label: "OpenAI-compatible base URL",
+      placeholder: DEFAULT_BASE,
+      helpText:
+        "Ollama defaults to http://localhost:11434/v1. For browser access you must allow CORS on the server (e.g. OLLAMA_ORIGINS='https://yoursite.example' ollama serve).",
+      required: false,
+      secret: false,
+    },
+  ],
+  validateConfig: (cfg) => (!cfg.model?.trim() ? "Model name required" : null),
+  resolveModel: (cfg) => {
+    const baseURL = normalizeBaseUrl(cfg.baseUrl);
+    const ollama = createOpenAICompatible({
+      name: "ollama",
+      baseURL,
+      apiKey: "ollama",
+      includeUsage: true,
+    });
+    return ollama.chatModel(cfg.model);
+  },
+});

package/templates/spellbook/src/components/SpellbookChat/streamProviders/openai.ts

@@ -0,0 +1,34 @@
+import { createOpenAI } from "@ai-sdk/openai";
+
+import { createCloudProvider } from "./createCloudProvider";
+
+export const openaiProvider = createCloudProvider({
+  id: "openai",
+  displayName: "OpenAI",
+  tagline: "Cloud · BYOK · GPT-5 family",
+  models: [
+    { id: "gpt-5.5", label: "GPT-5.5", note: "flagship" },
+    { id: "gpt-5.4", label: "GPT-5.4" },
+    { id: "gpt-5.4-mini", label: "GPT-5.4 mini", note: "fast" },
+    { id: "gpt-5.4-nano", label: "GPT-5.4 nano", note: "budget" },
+    { id: "gpt-4o", label: "GPT-4o", note: "legacy" },
+    { id: "gpt-4o-mini", label: "GPT-4o mini" },
+    { id: "o3-mini", label: "o3-mini", note: "reasoning" },
+  ],
+  configFields: [
+    {
+      key: "apiKey",
+      label: "OpenAI API key",
+      placeholder: "sk-…",
+      helpText:
+        "Get one at platform.openai.com. Kept in this tab's memory only (cleared on refresh). Requests are made directly from the browser.",
+      required: true,
+      secret: true,
+    },
+  ],
+  validateConfig: (cfg) => (!cfg.apiKey?.trim() ? "API key required" : null),
+  resolveModel: (cfg) => {
+    const openai = createOpenAI({ apiKey: cfg.apiKey! });
+    return openai.chat(cfg.model);
+  },
+});

package/templates/spellbook/src/components/SpellbookChat/streamProviders/openaiRealtime.ts

@@ -0,0 +1,320 @@
+/**
+ * OpenAI Realtime API provider — text-mode streaming.
+ *
+ * Realtime's headline feature is bidirectional voice (audio in / audio
+ * out via WebRTC). This provider uses Realtime's WebSocket text mode so
+ * the regular text-chat panel can benefit from the API's persistent
+ * session model and lower per-turn latency. Voice integration is a
+ * future-work item and would replace the entire VoiceMode pipeline
+ * (browser STT + native TTS go away in favour of one WebRTC peer
+ * connection); see `voiceFsm.ts` for the FSM the future voice variant
+ * would dispatch into.
+ *
+ * Auth model:
+ *
+ *   Browsers MUST NOT hit the Realtime endpoint with a long-lived API
+ *   key. The user (or the docs site operator) needs to stand up a small
+ *   server endpoint that returns a short-lived `client_secret` minted
+ *   via OpenAI's REST API. The expected response shape is:
+ *
+ *     POST <tokenEndpoint>
+ *       → { client_secret: { value: "ek_…", expires_at: <unix ts> } }
+ *
+ *   We POST with no body (the endpoint can attach the model + voice it
+ *   wants behind the scenes). The endpoint should rate-limit and
+ *   authenticate its callers.
+ *
+ *   For prototyping, the user can paste a raw OpenAI API key in the
+ *   `apiKey` field instead — the provider will pass it as the
+ *   `Authorization: Bearer …` header. This is INSECURE for production
+ *   (anyone visiting the page sees the key in the network tab) but
+ *   matches the existing escape hatch we expose for direct Anthropic
+ *   browser access; the help text makes the trade-off explicit.
+ */
+
+import { mapFinishReason } from "./mapFinishReason";
+import type {
+  ProviderConfig,
+  StreamEvent,
+  StreamProvider,
+  StreamRequest,
+} from "./types";
+
+const REALTIME_WS = "wss://api.openai.com/v1/realtime";
+
+interface ClientSecretResponse {
+  readonly client_secret?: {
+    readonly value: string;
+    readonly expires_at?: number;
+  };
+}
+
+async function fetchEphemeralKey(endpoint: string): Promise<string> {
+  const res = await fetch(endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+  });
+  if (!res.ok) {
+    throw new Error(
+      `Token endpoint ${endpoint} returned ${res.status}. Configure it to mint OpenAI Realtime ephemeral keys.`,
+    );
+  }
+  const body = (await res.json()) as ClientSecretResponse;
+  const value = body.client_secret?.value;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(
+      "Token endpoint response missing `client_secret.value`. See OpenAI Realtime ephemeral keys docs.",
+    );
+  }
+  return value;
+}
+
+interface RealtimeServerEvent {
+  readonly type: string;
+  readonly response?: {
+    readonly status_details?: { readonly type?: string };
+    readonly usage?: {
+      readonly input_tokens?: number;
+      readonly output_tokens?: number;
+    };
+  };
+  readonly delta?: string;
+}
+
+/**
+ * Stream a text response using OpenAI's Realtime WebSocket. Yields
+ * `text-delta` events as `response.text.delta` server events arrive,
+ * then a single `finish` once `response.done` lands.
+ */
+async function* streamRealtimeText(
+  req: StreamRequest,
+  cfg: ProviderConfig,
+): AsyncIterable<StreamEvent> {
+  if (typeof WebSocket === "undefined") {
+    throw new Error(
+      "OpenAI Realtime requires a browser with WebSocket support.",
+    );
+  }
+
+  let token: string;
+  if (cfg.tokenEndpoint?.trim()) {
+    token = await fetchEphemeralKey(cfg.tokenEndpoint.trim());
+  } else if (cfg.apiKey?.trim()) {
+    token = cfg.apiKey.trim();
+  } else {
+    throw new Error(
+      "OpenAI Realtime needs either a token endpoint or an API key. Configure one in Settings → OpenAI Realtime.",
+    );
+  }
+
+  const url = `${REALTIME_WS}?model=${encodeURIComponent(cfg.model)}`;
+  const ws = new WebSocket(url, ["realtime", `openai-insecure-api-key.${token}`, "openai-beta.realtime-v1"]);
+
+  // Pipeline: events → channel queue → consumer.
+  const queue: StreamEvent[] = [];
+  let resolveNext: (() => void) | null = null;
+  let closed = false;
+  let error: Error | null = null;
+
+  const push = (ev: StreamEvent): void => {
+    queue.push(ev);
+    if (resolveNext) {
+      const r = resolveNext;
+      resolveNext = null;
+      r();
+    }
+  };
+
+  const finishWithError = (err: Error): void => {
+    error = err;
+    closed = true;
+    if (resolveNext) {
+      const r = resolveNext;
+      resolveNext = null;
+      r();
+    }
+  };
+
+  const onAbort = (): void => {
+    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+      try {
+        ws.close();
+      } catch {
+        // ignore
+      }
+    }
+    push({ type: "finish", finishReason: "abort" });
+    closed = true;
+  };
+
+  if (req.signal) {
+    if (req.signal.aborted) {
+      onAbort();
+      return;
+    }
+    req.signal.addEventListener("abort", onAbort, { once: true });
+  }
+
+  ws.addEventListener("open", () => {
+    // Configure the session for text-only mode. Modalities = ["text"]
+    // turns off audio entirely so we don't pay for streaming audio
+    // tokens we don't use.
+    ws.send(
+      JSON.stringify({
+        type: "session.update",
+        session: {
+          modalities: ["text"],
+          instructions: req.system,
+          temperature: req.temperature ?? 0.4,
+          max_response_output_tokens: req.maxTokens ?? 1024,
+        },
+      }),
+    );
+    // Stream the chat history as conversation items.
+    for (const m of req.messages) {
+      ws.send(
+        JSON.stringify({
+          type: "conversation.item.create",
+          item: {
+            type: "message",
+            role: m.role,
+            content: [{ type: "input_text", text: m.content }],
+          },
+        }),
+      );
+    }
+    ws.send(
+      JSON.stringify({
+        type: "response.create",
+        response: { modalities: ["text"] },
+      }),
+    );
+  });
+
+  ws.addEventListener("message", (ev: MessageEvent<string>) => {
+    let msg: RealtimeServerEvent;
+    try {
+      msg = JSON.parse(ev.data) as RealtimeServerEvent;
+    } catch {
+      return;
+    }
+    switch (msg.type) {
+      case "response.text.delta":
+      case "response.output_text.delta": {
+        const delta = msg.delta;
+        if (typeof delta === "string" && delta.length > 0) {
+          push({ type: "text-delta", text: delta });
+        }
+        return;
+      }
+      case "response.done": {
+        const usage = msg.response?.usage;
+        const stopType = msg.response?.status_details?.type;
+        push({
+          type: "finish",
+          finishReason: mapFinishReason(stopType),
+          inputTokens: usage?.input_tokens,
+          outputTokens: usage?.output_tokens,
+        });
+        try {
+          ws.close();
+        } catch {
+          // ignore
+        }
+        closed = true;
+        if (resolveNext) {
+          const r = resolveNext;
+          resolveNext = null;
+          r();
+        }
+        return;
+      }
+      case "error": {
+        finishWithError(
+          new Error(`OpenAI Realtime error: ${ev.data.slice(0, 280)}`),
+        );
+        return;
+      }
+      default:
+        return;
+    }
+  });
+
+  ws.addEventListener("error", () => {
+    finishWithError(new Error("OpenAI Realtime websocket error"));
+  });
+
+  ws.addEventListener("close", () => {
+    closed = true;
+    if (resolveNext) {
+      const r = resolveNext;
+      resolveNext = null;
+      r();
+    }
+  });
+
+  while (true) {
+    if (queue.length > 0) {
+      const ev = queue.shift()!;
+      yield ev;
+      if (ev.type === "finish") return;
+      continue;
+    }
+    if (error) throw error;
+    if (closed) return;
+    await new Promise<void>((resolve) => {
+      resolveNext = resolve;
+    });
+  }
+}
+
+export const openaiRealtimeProvider: StreamProvider = {
+  id: "openai-realtime",
+  displayName: "OpenAI Realtime (preview)",
+  tagline: "Cloud · WebSocket · text mode (voice integration coming)",
+  models: [
+    {
+      id: "gpt-realtime-preview",
+      label: "gpt-realtime-preview",
+      note: "voice/text",
+    },
+    {
+      id: "gpt-4o-realtime-preview",
+      label: "gpt-4o-realtime-preview",
+      note: "legacy",
+    },
+  ],
+  configFields: [
+    {
+      key: "tokenEndpoint",
+      label: "Ephemeral token endpoint",
+      placeholder: "https://your-backend.example/realtime-token",
+      helpText:
+        "URL of a small server endpoint that returns OpenAI Realtime client secrets. Recommended for production. See the file header in `streamProviders/openaiRealtime.ts` for the expected response shape.",
+      required: false,
+      secret: false,
+    },
+    {
+      key: "apiKey",
+      label: "OpenAI API key (insecure direct access)",
+      placeholder: "sk-…",
+      helpText:
+        "Prototyping only — the key is visible to anyone using this page. Prefer the token endpoint above for any deployment.",
+      required: false,
+      secret: true,
+    },
+  ],
+  validateConfig: (cfg) => {
+    if (!cfg.tokenEndpoint?.trim() && !cfg.apiKey?.trim()) {
+      return "Configure either a token endpoint or an API key";
+    }
+    if (
+      cfg.tokenEndpoint?.trim() &&
+      !/^https?:\/\//i.test(cfg.tokenEndpoint.trim())
+    ) {
+      return "Token endpoint must be an http(s) URL";
+    }
+    return null;
+  },
+  stream: (req, cfg) => streamRealtimeText(req, cfg),
+};

package/templates/spellbook/src/components/SpellbookChat/streamProviders/types.ts

@@ -0,0 +1,172 @@
+/**
+ * Multi-provider streaming contract for the in-browser documentation chat.
+ *
+ * All providers — cloud (Anthropic, OpenAI, Google, Ollama) and local
+ * (WebLLM via WebGPU) — implement this interface. The chat engine selects
+ * one at runtime based on user settings; secrets live in memory only
+ * (`secretStore.ts`), non-secret fields (provider id, chosen model,
+ * optional base URL) live in `localStorage` under `grimoire.chat.*`.
+ *
+ * Providers are loaded on-demand (dynamic `import()`) so the WebLLM runtime
+ * never enters the bundle of users who pick a cloud provider, and cloud
+ * SDKs never load for local-only users.
+ *
+ * DO NOT modify this file without coordinating with both ends:
+ *  - Provider impls live in `./anthropic.ts`, `./openai.ts`, `./google.ts`,
+ *    `./ollama.ts`, `./webllm.ts`.
+ *  - Consumer is `useChatEngine.ts`, which dispatches on `ProviderId`.
+ */
+
+export type ProviderId =
+  | "anthropic"
+  | "openai"
+  | "openai-realtime"
+  | "google"
+  | "ollama"
+  | "webllm";
+
+/**
+ * Auth + connection settings for a single provider.
+ *
+ * - `id`, `model`, `baseUrl` are read from `localStorage` under
+ *   `grimoire.chat.<id>.*` (see `STORAGE_KEYS`).
+ * - `apiKey` is read from the in-memory `secretStore` only. Cleared on
+ *   tab refresh — deliberate; do not persist.
+ */
+export interface ProviderConfig {
+  readonly id: ProviderId;
+  readonly model: string;
+  /** Cloud providers (anthropic, openai, google) — required. In-memory only. */
+  readonly apiKey?: string;
+  /** Ollama — defaults to `http://localhost:11434`. */
+  readonly baseUrl?: string;
+  /**
+   * OpenAI Realtime — URL of a server endpoint that mints ephemeral
+   * client_secrets via the OpenAI REST API. Browsers cannot safely use
+   * a long-lived API key against the Realtime endpoint, so the user
+   * must provide a small backend that returns `{ client_secret: { value, expires_at } }`
+   * on each call. See `streamProviders/openaiRealtime.ts` for the
+   * expected response shape.
+   */
+  readonly tokenEndpoint?: string;
+}
+
+/**
+ * Single user/assistant exchange in the rolling chat history. The system
+ * prompt + RAG context is passed separately via `StreamRequest.system`.
+ */
+export interface ChatTurn {
+  readonly role: "user" | "assistant";
+  readonly content: string;
+}
+
+export interface StreamRequest {
+  /** Concatenated system prompt: identity + persona + RAG context block. */
+  readonly system: string;
+  /** Multi-turn chat history. The current user question is the last entry. */
+  readonly messages: readonly ChatTurn[];
+  /** Soft cap on output tokens. Provider may clamp to its own limits. */
+  readonly maxTokens?: number;
+  /** Sampling temperature. Default 0.4 if omitted. */
+  readonly temperature?: number;
+  /** Cancel the in-flight request. */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * A streamed event from `StreamProvider.stream`. The async iterable yields
+ * zero-or-more `text-delta` events, then exactly one `finish` event.
+ */
+export type StreamEvent =
+  | { readonly type: "text-delta"; readonly text: string }
+  | {
+      readonly type: "finish";
+      readonly finishReason: "stop" | "length" | "tool-call" | "error" | "abort";
+      readonly inputTokens?: number;
+      readonly outputTokens?: number;
+    };
+
+/** Progress info for slow init steps (e.g. WebLLM model download). */
+export interface PreloadProgress {
+  readonly phase: string;
+  readonly message: string;
+  readonly loaded?: number;
+  readonly total?: number;
+  readonly fraction?: number;
+}
+
+/** A single configurable model option a provider exposes in the UI. */
+export interface ModelOption {
+  readonly id: string;
+  readonly label: string;
+  /** Optional hint shown next to the model name (e.g. "fast", "smart"). */
+  readonly note?: string;
+}
+
+/** Required config field schema (rendered in SettingsPanel per provider). */
+export interface ConfigField {
+  readonly key: "apiKey" | "baseUrl" | "tokenEndpoint";
+  readonly label: string;
+  readonly placeholder?: string;
+  readonly helpText?: string;
+  readonly required: boolean;
+  /** UI hint: should the value be masked (passwords)? */
+  readonly secret: boolean;
+}
+
+/** A single AI provider plugged into the chat engine. */
+export interface StreamProvider {
+  readonly id: ProviderId;
+  readonly displayName: string;
+  /** One-line tagline shown in the provider picker. */
+  readonly tagline: string;
+  /** Models the user can pick from. The first entry is the default. */
+  readonly models: readonly ModelOption[];
+  /** Config fields (api key, base URL, etc.) the SettingsPanel renders. */
+  readonly configFields: readonly ConfigField[];
+  /** Returns null if config is valid; otherwise a human-readable error. */
+  readonly validateConfig: (config: ProviderConfig) => string | null;
+  /** Optional warm-up (download model, open WS, etc.). Cloud providers may resolve immediately. */
+  readonly preload?: (
+    config: ProviderConfig,
+    onProgress?: (info: PreloadProgress) => void,
+  ) => Promise<void>;
+  /**
+   * Stream a chat completion. Yields text-delta events as tokens arrive,
+   * then exactly one finish event. Abort via `request.signal`.
+   */
+  readonly stream: (
+    request: StreamRequest,
+    config: ProviderConfig,
+  ) => AsyncIterable<StreamEvent>;
+}
+
+/**
+ * Provider registry: maps id to a lazy loader that returns the impl.
+ * Implementations live in sibling files and are imported on demand.
+ */
+export type ProviderRegistry = Readonly<
+  Record<ProviderId, () => Promise<StreamProvider>>
+>;
+
+/**
+ * Storage key helpers for non-secret preferences (provider id, model,
+ * base URL). API keys live in `secretStore.ts` — never in localStorage.
+ */
+export const STORAGE_KEYS = {
+  activeProvider: "grimoire.chat.provider",
+  field: (
+    id: ProviderId,
+    key: Exclude<ConfigField["key"], "apiKey"> | "model",
+  ): string => `grimoire.chat.${id}.${key}`,
+} as const;
+
+/** Default order shown in the provider picker dropdown. */
+export const PROVIDER_ORDER: readonly ProviderId[] = [
+  "anthropic",
+  "openai",
+  "openai-realtime",
+  "google",
+  "ollama",
+  "webllm",
+] as const;