modeldispatcher-browser-agent 0.6.0

package/src/providers/gemini.ts

@@ -0,0 +1,95 @@
+/**
+ * Google Gemini — direct browser call, no SDK. The key travels in a header
+ * (`x-goog-api-key`) rather than the `?key=` query string: a URL ends up in
+ * proxy/server access logs and browser history, a header does not.
+ */
+
+import { consumeLines, describeHttpError, fetchWithRetry } from "../http.js";
+import type { ChatMessage, ProviderCallConfig, RequestOptions } from "../types.js";
+
+const DEFAULT_MAX_TOKENS = 1024;
+
+interface GeminiPart {
+  text: string;
+}
+interface GeminiContent {
+  role: "user" | "model";
+  parts: GeminiPart[];
+}
+
+function toContents(messages: readonly ChatMessage[]): GeminiContent[] {
+  return messages
+    .filter((m) => m.role !== "system")
+    .map((m) => ({ role: m.role === "assistant" ? "model" : "user", parts: [{ text: m.content }] }));
+}
+
+function systemInstructionOf(messages: readonly ChatMessage[], explicit?: string): string | undefined {
+  return explicit ?? messages.find((m) => m.role === "system")?.content;
+}
+
+function buildBody(messages: readonly ChatMessage[], options: RequestOptions) {
+  const system = systemInstructionOf(messages, options.systemInstruction);
+  return {
+    contents: toContents(messages),
+    generationConfig: {
+      maxOutputTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+      ...(options.jsonMode ? { responseMimeType: "application/json" } : {}),
+    },
+    ...(system ? { systemInstruction: { parts: [{ text: system }] } } : {}),
+  };
+}
+
+export async function completeGemini(
+  cfg: ProviderCallConfig,
+  messages: readonly ChatMessage[],
+  options: RequestOptions = {},
+): Promise<string> {
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(cfg.model)}:generateContent`;
+  const res = await fetchWithRetry(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "x-goog-api-key": cfg.apiKey },
+      body: JSON.stringify(buildBody(messages, options)),
+    },
+    options.signal,
+  );
+  if (!res.ok) throw new Error(await describeHttpError(res));
+  const data = await res.json();
+  return data.candidates?.[0]?.content?.parts?.[0]?.text ?? "";
+}
+
+export async function streamGemini(
+  cfg: ProviderCallConfig,
+  messages: readonly ChatMessage[],
+  onChunk: (fullTextSoFar: string) => void,
+  options: RequestOptions = {},
+): Promise<string> {
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(cfg.model)}:streamGenerateContent?alt=sse`;
+  const res = await fetchWithRetry(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "x-goog-api-key": cfg.apiKey },
+      body: JSON.stringify(buildBody(messages, options)),
+    },
+    options.signal,
+  );
+  if (!res.ok) throw new Error(await describeHttpError(res));
+
+  let full = "";
+  await consumeLines(res, (line) => {
+    if (!line.startsWith("data: ")) return;
+    const raw = line.slice(6).trim();
+    try {
+      const text = JSON.parse(raw).candidates?.[0]?.content?.parts?.[0]?.text;
+      if (text) {
+        full += text;
+        onChunk(full);
+      }
+    } catch {
+      // Skip a malformed/partial SSE frame — the next line may complete it.
+    }
+  });
+  return full;
+}

package/src/providers/ollama.ts

@@ -0,0 +1,81 @@
+/**
+ * Ollama — a local (or self-hosted) model server, no API key. Always uses
+ * `/api/chat` (message-list based) rather than switching between `/generate`
+ * and `/chat` per call shape — a single-turn prompt is just a one-message
+ * chat, so one code path covers both without the caller needing to know
+ * which Ollama endpoint that implies.
+ */
+
+import { consumeLines, fetchWithRetry, validateOllamaUrl } from "../http.js";
+import type { ChatMessage, ProviderCallConfig, RequestOptions } from "../types.js";
+
+const DEFAULT_MAX_TOKENS = 1024;
+
+function toApiMessages(messages: readonly ChatMessage[], systemInstruction?: string) {
+  const hasSystemTurn = messages.some((m) => m.role === "system");
+  const system = !hasSystemTurn && systemInstruction ? [{ role: "system", content: systemInstruction }] : [];
+  return [...system, ...messages.map((m) => ({ role: m.role, content: m.content }))];
+}
+
+function buildBody(cfg: ProviderCallConfig, messages: readonly ChatMessage[], options: RequestOptions, stream: boolean) {
+  return {
+    model: cfg.model,
+    messages: toApiMessages(messages, options.systemInstruction),
+    stream,
+    options: { num_predict: options.maxTokens ?? DEFAULT_MAX_TOKENS },
+  };
+}
+
+export async function completeOllama(
+  cfg: ProviderCallConfig,
+  messages: readonly ChatMessage[],
+  options: RequestOptions = {},
+): Promise<string> {
+  const baseUrl = validateOllamaUrl(cfg.ollamaUrl);
+  const res = await fetchWithRetry(
+    `${baseUrl}/api/chat`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(buildBody(cfg, messages, options, false)),
+    },
+    options.signal,
+  );
+  if (!res.ok) throw new Error(`Ollama error: HTTP ${res.status}. Is Ollama running?`);
+  const data = await res.json();
+  return data.message?.content ?? "";
+}
+
+export async function streamOllama(
+  cfg: ProviderCallConfig,
+  messages: readonly ChatMessage[],
+  onChunk: (fullTextSoFar: string) => void,
+  options: RequestOptions = {},
+): Promise<string> {
+  const baseUrl = validateOllamaUrl(cfg.ollamaUrl);
+  const res = await fetchWithRetry(
+    `${baseUrl}/api/chat`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(buildBody(cfg, messages, options, true)),
+    },
+    options.signal,
+  );
+  if (!res.ok) throw new Error(`Ollama error: HTTP ${res.status}. Is Ollama running?`);
+
+  let full = "";
+  await consumeLines(res, (line) => {
+    if (!line.trim()) return;
+    try {
+      const text = JSON.parse(line).message?.content;
+      if (text) {
+        full += text;
+        onChunk(full);
+      }
+    } catch {
+      // Skip a malformed/partial NDJSON line.
+    }
+  });
+  return full;
+}

package/src/providers/openaiCompatible.ts

@@ -0,0 +1,89 @@
+/**
+ * OpenAI and Groq — both speak the same chat-completions REST shape, direct
+ * from the browser, no SDK. Groq is just the same code pointed at its own
+ * base URL (matches how the Python core's GroqProvider relates to
+ * OpenAIProvider — same idea, browser side).
+ */
+
+import { consumeLines, describeHttpError, fetchWithRetry } from "../http.js";
+import type { ChatMessage, ProviderCallConfig, RequestOptions } from "../types.js";
+
+const DEFAULT_MAX_TOKENS = 1024;
+
+const BASE_URLS: Record<"openai" | "groq", string> = {
+  openai: "https://api.openai.com/v1/chat/completions",
+  groq: "https://api.groq.com/openai/v1/chat/completions",
+};
+
+function toApiMessages(messages: readonly ChatMessage[], systemInstruction?: string) {
+  const hasSystemTurn = messages.some((m) => m.role === "system");
+  const system = !hasSystemTurn && systemInstruction ? [{ role: "system", content: systemInstruction }] : [];
+  return [...system, ...messages.map((m) => ({ role: m.role, content: m.content }))];
+}
+
+function buildBody(cfg: ProviderCallConfig, messages: readonly ChatMessage[], options: RequestOptions, stream: boolean) {
+  return {
+    model: cfg.model,
+    max_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+    messages: toApiMessages(messages, options.systemInstruction),
+    ...(options.jsonMode ? { response_format: { type: "json_object" } } : {}),
+    ...(stream ? { stream: true } : {}),
+  };
+}
+
+async function request(
+  provider: "openai" | "groq",
+  cfg: ProviderCallConfig,
+  messages: readonly ChatMessage[],
+  options: RequestOptions,
+  stream: boolean,
+): Promise<Response> {
+  const res = await fetchWithRetry(
+    BASE_URLS[provider],
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.apiKey}` },
+      body: JSON.stringify(buildBody(cfg, messages, options, stream)),
+    },
+    options.signal,
+  );
+  if (!res.ok) throw new Error(await describeHttpError(res));
+  return res;
+}
+
+export async function completeOpenAICompatible(
+  provider: "openai" | "groq",
+  cfg: ProviderCallConfig,
+  messages: readonly ChatMessage[],
+  options: RequestOptions = {},
+): Promise<string> {
+  const res = await request(provider, cfg, messages, options, false);
+  const data = await res.json();
+  return data.choices?.[0]?.message?.content ?? "";
+}
+
+export async function streamOpenAICompatible(
+  provider: "openai" | "groq",
+  cfg: ProviderCallConfig,
+  messages: readonly ChatMessage[],
+  onChunk: (fullTextSoFar: string) => void,
+  options: RequestOptions = {},
+): Promise<string> {
+  const res = await request(provider, cfg, messages, options, true);
+  let full = "";
+  await consumeLines(res, (line) => {
+    if (!line.startsWith("data: ")) return;
+    const raw = line.slice(6).trim();
+    if (raw === "[DONE]") return;
+    try {
+      const delta = JSON.parse(raw).choices?.[0]?.delta?.content;
+      if (delta) {
+        full += delta;
+        onChunk(full);
+      }
+    } catch {
+      // Skip a malformed/partial SSE frame.
+    }
+  });
+  return full;
+}

package/src/registry.ts

@@ -0,0 +1,82 @@
+/**
+ * The provider registry — one canonical source for the metadata every app's
+ * settings screen was independently duplicating (name, default model, key
+ * placeholder, where to get a key).
+ */
+
+import type { ProviderId, ProviderInfo } from "./types.js";
+
+export const PROVIDERS: Record<ProviderId, ProviderInfo> = {
+  gemini: {
+    id: "gemini",
+    name: "Google Gemini",
+    free: false,
+    defaultModel: "gemini-2.0-flash",
+    placeholder: "AIza...",
+    infoUrl: "https://aistudio.google.com/app/apikey",
+    infoText: "Get a free key from Google AI Studio",
+  },
+  groq: {
+    id: "groq",
+    name: "Groq",
+    free: true,
+    defaultModel: "llama-3.1-8b-instant",
+    placeholder: "gsk_...",
+    infoUrl: "https://console.groq.com/keys",
+    infoText: "Get a free key from Groq Console",
+  },
+  ollama: {
+    id: "ollama",
+    name: "Ollama (local)",
+    free: true,
+    noKey: true,
+    defaultModel: "llama3.2",
+    placeholder: "http://localhost:11434",
+    infoUrl: "https://ollama.ai",
+    infoText: "Install Ollama on your machine",
+  },
+  anthropic: {
+    id: "anthropic",
+    name: "Anthropic Claude",
+    free: false,
+    defaultModel: "claude-haiku-4-5-20251001",
+    placeholder: "sk-ant-...",
+    infoUrl: "https://console.anthropic.com/settings/keys",
+    infoText: "Get a key from the Anthropic Console",
+  },
+  openai: {
+    id: "openai",
+    name: "OpenAI",
+    free: false,
+    defaultModel: "gpt-4o-mini",
+    placeholder: "sk-...",
+    infoUrl: "https://platform.openai.com/api-keys",
+    infoText: "Get a key from the OpenAI Platform",
+  },
+};
+
+export function isKnownProvider(id: string): id is ProviderId {
+  return Object.hasOwn(PROVIDERS, id);
+}
+
+/**
+ * A curated, hand-maintained shortlist of current models per vendor, for
+ * rendering a model `<select>` instead of a free-text field. Necessarily
+ * goes stale as vendors ship new models — update this list by hand when
+ * that happens; it isn't fetched from anywhere. `PROVIDERS[id].defaultModel`
+ * is always included (first) even if it's ever edited out of this list.
+ */
+export const MODEL_OPTIONS: Record<ProviderId, readonly string[]> = {
+  gemini: ["gemini-2.0-flash", "gemini-2.5-flash", "gemini-2.5-pro"],
+  groq: ["llama-3.1-8b-instant", "llama-3.3-70b-versatile", "openai/gpt-oss-120b"],
+  ollama: ["llama3.2", "llama3.1", "mistral", "qwen2.5"],
+  anthropic: ["claude-haiku-4-5-20251001", "claude-sonnet-4-5", "claude-opus-4-8"],
+  openai: ["gpt-4o-mini", "gpt-4o", "gpt-4.1-mini"],
+};
+
+/** `MODEL_OPTIONS[provider]` with `defaultModel` guaranteed present and first. */
+export function modelOptionsFor(provider: ProviderId): readonly string[] {
+  const options = MODEL_OPTIONS[provider];
+  const defaultModel = PROVIDERS[provider].defaultModel;
+  return options.includes(defaultModel) ? options : [defaultModel, ...options];
+}

package/src/types.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared vocabulary for the browser agent.
+ *
+ * Mirrors the split model-dispatcher's Python core uses: plain, dependency-free
+ * value types here, behaviour in `providers/*` and `agent.ts`.
+ */
+
+export type ProviderId = "gemini" | "openai" | "anthropic" | "groq" | "ollama";
+
+/** Static metadata about a provider — enough to render a settings picker. */
+export interface ProviderInfo {
+  readonly id: ProviderId;
+  readonly name: string;
+  /** Whether this provider has a genuinely free tier (not just "has a trial"). */
+  readonly free: boolean;
+  /** True for providers that need no API key at all (e.g. a local Ollama). */
+  readonly noKey?: boolean;
+  readonly defaultModel: string;
+  /** UI placeholder text for the key input (e.g. "sk-ant-..."). */
+  readonly placeholder: string;
+  readonly infoUrl: string;
+  readonly infoText: string;
+}
+
+/**
+ * One configured vendor: its model, and the key(s) pooled for it. More than
+ * one key is tried in order (e.g. a personal key and a team key) before
+ * this vendor is considered exhausted and the dispatcher moves to the next
+ * configured provider. Ignored for `provider: "ollama"`, which authenticates
+ * via `AgentConfig.ollamaUrl` instead of a key.
+ */
+export interface ProviderCredential {
+  readonly provider: ProviderId;
+  readonly model: string;
+  readonly apiKeys: readonly string[];
+}
+
+/**
+ * The full BYOK configuration: an ordered fallback list of vendors (each
+ * with its own pooled keys) to try in turn, plus Ollama's local server URL
+ * (shared across the whole config — there's only one local Ollama, not one
+ * per fallback slot). `dispatch`/`complete`/`streamComplete` walk this list
+ * candidate by candidate, mirroring the Python core's fallback chain.
+ */
+export interface AgentConfig {
+  readonly providers: readonly ProviderCredential[];
+  readonly ollamaUrl: string;
+}
+
+/**
+ * One concrete attempt: a specific vendor, model, and (for keyed vendors) a
+ * single already-resolved key — what an individual `providers/*` module
+ * needs to make one call. Distinct from `AgentConfig`, which holds the whole
+ * configured fallback list before the dispatch loop has picked a candidate.
+ */
+export interface ProviderCallConfig {
+  readonly provider: ProviderId;
+  readonly model: string;
+  readonly apiKey: string;
+  readonly ollamaUrl: string;
+}
+
+export type ChatRole = "system" | "user" | "assistant";
+
+export interface ChatMessage {
+  readonly role: ChatRole;
+  readonly content: string;
+}
+
+/** Options shared by both complete() and streamComplete()/streamChat(). */
+export interface RequestOptions {
+  /** System prompt / instruction, applied via each provider's native mechanism. */
+  systemInstruction?: string;
+  /** Request the provider's structured-JSON response mode where it has one
+   * (OpenAI-compatible providers only — Gemini's `responseMimeType` is
+   * always requested by callers that need it via a raw prompt instruction,
+   * Anthropic and Ollama have no such mode). */
+  jsonMode?: boolean;
+  maxTokens?: number;
+  /** Cancel the request (e.g. component unmount). Independent of, and
+   * merged with, the library's own request timeout. */
+  signal?: AbortSignal;
+}
+
+export interface StreamOptions extends RequestOptions {
+  /** Called with the *cumulative* text so far after every chunk, matching
+   * every existing app's streaming callback shape. */
+  onChunk: (fullTextSoFar: string) => void;
+}
+
+/** A free, public AI chat web product `openExternalChat` can hand a question
+ * off to — the no-API-key escape hatch, distinct from the `ProviderId`s above
+ * (which all require a BYOK credential). */
+export type ExternalChatProviderId = "chatgpt" | "claude" | "gemini" | "groq";
+
+/** Static metadata about one external chat provider. */
+export interface ExternalChatProviderInfo {
+  readonly id: ExternalChatProviderId;
+  readonly name: string;
+  /** Where `openExternalChat` sends the user when there's no known
+   * query-prefill parameter for this provider (or as the base URL the
+   * parameter is appended to). */
+  readonly homeUrl: string;
+  /** Build the deep-link URL for a given question, when this provider has a
+   * known (unofficial, reverse-engineered) prefill parameter. `null` when it
+   * doesn't — `openExternalChat` falls back to `homeUrl` plus the clipboard. */
+  readonly buildUrl: ((question: string) => string) | null;
+}