blume 2.0.3 → 2.1.1

package/src/ai/ask.ts

@@ -34,6 +34,15 @@ export type AssistantProviderOptions = Record<
 /** The AI SDK provider package the OpenAI-compatible adapters install. */
 const OPENAI_COMPATIBLE_DEP = "@ai-sdk/openai-compatible";
 
+/**
+ * The AI SDK packages for the providers Blume calls directly: the package and
+ * the provider factory the route imports from it.
+ */
+const OPENAI_SDK = { factory: "createOpenAI", pkg: "@ai-sdk/openai" };
+const ANTHROPIC_SDK = { factory: "createAnthropic", pkg: "@ai-sdk/anthropic" };
+const GEMINI_SDK = { factory: "createGoogle", pkg: "@ai-sdk/google" };
+const GROK_SDK = { factory: "createXai", pkg: "@ai-sdk/xai" };
+
 // ---------------------------------------------------------------------------
 // Shared options
 // ---------------------------------------------------------------------------
@@ -69,7 +78,7 @@ const providerOptionsSchema = z.record(
 );
 
 /** The shared option schema, with the adapter's own key env var default. */
-const sharedOptions = (apiKeyEnv: string) => ({
+export const sharedOptions = (apiKeyEnv: string) => ({
   apiKeyEnv: z.string().min(1).default(apiKeyEnv),
   headers: z.record(z.string(), z.string()).optional(),
   providerOptions: providerOptionsSchema.optional(),
@@ -81,13 +90,21 @@ const reasoningOption = z.enum(assistantReasoningLevels).optional();
 // gateway()
 // ---------------------------------------------------------------------------
 
-const GATEWAY_API_KEY_ENV = "AI_GATEWAY_API_KEY";
+export const GATEWAY_API_KEY_ENV = "AI_GATEWAY_API_KEY";
 /** The model the gateway adapter uses when none is configured. */
 const DEFAULT_GATEWAY_MODEL = "openai/gpt-5.5";
 
 /** Options for {@link gateway}. */
 export interface AssistantGatewayOptions extends AssistantAdapterOptions {
-  /** A `provider/model` id routed by the gateway. Defaults to `openai/gpt-5.5`. */
+  /**
+   * Narration only: how the voice should sound, for speech models that take
+   * instructions ("Read calmly, like a teacher").
+   */
+  instructions?: string;
+  /**
+   * A `provider/model` id routed by the gateway. Defaults to `openai/gpt-5.5`
+   * for the assistant and `openai/tts-1-hd` for narration.
+   */
   model?: string;
   /**
    * How much the model reasons before answering. Sent as the AI SDK's
@@ -96,6 +113,8 @@ export interface AssistantGatewayOptions extends AssistantAdapterOptions {
    * offer the level you pick. Omitted keeps the model's default.
    */
   reasoning?: AssistantReasoning;
+  /** Narration only: the speech model's voice. Defaults to `alloy`. */
+  voice?: string;
 }
 
 const gatewayOptionsSchema = z.strictObject({
@@ -115,7 +134,8 @@ export const gatewayAdapterSchema = adapterDescriptorSchema(
 );
 
 /**
- * Route the assistant through the Vercel AI Gateway (the default). `model` is a
+ * Route the assistant through the Vercel AI Gateway (the default), or generate
+ * narration audio with one of its speech models. `model` is a
  * `provider/model` string; the key is `AI_GATEWAY_API_KEY`, or Vercel's OIDC
  * token when deployed there. Needs no provider SDK beyond the `ai` package
  * Blume ships.
@@ -129,6 +149,233 @@ export const gateway = (
   runtimeDeps: [],
 });
 
+// ---------------------------------------------------------------------------
+// openai()
+// ---------------------------------------------------------------------------
+
+const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
+
+/** Options for {@link openai}. */
+export interface AssistantOpenAIOptions extends AssistantAdapterOptions {
+  /**
+   * An OpenAI-compatible endpoint to call instead of OpenAI
+   * (`https://llm.internal.example.com/v1`): a self-hosted model or an
+   * internal gateway. The route then talks Chat Completions through
+   * `@ai-sdk/openai-compatible`, and the docs tools are off unless
+   * `ai.assistant.tools` turns them on, since the model may not call tools.
+   */
+  baseUrl?: string;
+  /** The model id (`gpt-5.5`). */
+  model: string;
+  /**
+   * The provider name the AI SDK reports, which a custom endpoint also reads
+   * its `providerOptions` under. Defaults to `openai`, or `openai-compatible`
+   * with a `baseUrl`.
+   */
+  name?: string;
+  /**
+   * How much the model reasons before answering, sent as `reasoning_effort`;
+   * with a `baseUrl`, the endpoint has to accept that parameter. Omitted
+   * keeps the model's default.
+   */
+  reasoning?: AssistantReasoning;
+}
+
+const openaiOptionsSchema = z.strictObject({
+  ...sharedOptions(OPENAI_API_KEY_ENV),
+  baseUrl: z.url().optional(),
+  model: z.string().min(1),
+  name: z.string().min(1).optional(),
+  reasoning: reasoningOption,
+});
+
+export type AssistantOpenAIAdapter = AdapterDescriptor<
+  "openai",
+  AssistantOpenAIOptions
+>;
+
+export const openaiAdapterSchema = adapterDescriptorSchema(
+  "openai",
+  openaiOptionsSchema
+);
+
+/**
+ * Route the assistant to OpenAI, or to any OpenAI-compatible endpoint with
+ * `baseUrl`. Reads `OPENAI_API_KEY` and needs `@ai-sdk/openai` installed; a
+ * custom endpoint needs `@ai-sdk/openai-compatible` instead, since most
+ * don't serve OpenAI's Responses API.
+ */
+export const openai = (
+  options: AssistantOpenAIOptions
+): AssistantOpenAIAdapter => ({
+  kind: "openai",
+  options,
+  requiredSecrets: [options.apiKeyEnv ?? OPENAI_API_KEY_ENV],
+  runtimeDeps: [options.baseUrl ? OPENAI_COMPATIBLE_DEP : OPENAI_SDK.pkg],
+});
+
+/**
+ * Options for the deprecated {@link openaiCompatible}: {@link openai}'s, with
+ * the endpoint and its key env var required.
+ *
+ * @deprecated Use {@link AssistantOpenAIOptions}.
+ */
+export interface AssistantOpenAICompatibleOptions extends AssistantOpenAIOptions {
+  apiKeyEnv: string;
+  baseUrl: string;
+}
+
+/** @deprecated Use {@link AssistantOpenAIAdapter}. */
+export type AssistantOpenAICompatibleAdapter = AssistantOpenAIAdapter;
+
+/**
+ * Route the assistant through an OpenAI-compatible endpoint.
+ *
+ * @deprecated Use `openai({ baseUrl, model, apiKeyEnv })`, which this calls.
+ */
+export const openaiCompatible = (
+  options: AssistantOpenAICompatibleOptions
+): AssistantOpenAIAdapter => openai(options);
+
+// ---------------------------------------------------------------------------
+// anthropic()
+// ---------------------------------------------------------------------------
+
+const ANTHROPIC_API_KEY_ENV = "ANTHROPIC_API_KEY";
+
+/** Options for {@link anthropic}. */
+export interface AssistantAnthropicOptions extends AssistantAdapterOptions {
+  /** The Claude model id (`claude-sonnet-5`). */
+  model: string;
+  /**
+   * How much the model reasons before answering. The Anthropic provider
+   * maps the level to the model's thinking: an effort on models with
+   * adaptive thinking, a thinking budget on older ones, and thinking off for
+   * `"none"`. Omitted keeps the model's default.
+   */
+  reasoning?: AssistantReasoning;
+}
+
+const anthropicOptionsSchema = z.strictObject({
+  ...sharedOptions(ANTHROPIC_API_KEY_ENV),
+  model: z.string().min(1),
+  reasoning: reasoningOption,
+});
+
+export type AssistantAnthropicAdapter = AdapterDescriptor<
+  "anthropic",
+  AssistantAnthropicOptions
+>;
+
+export const anthropicAdapterSchema = adapterDescriptorSchema(
+  "anthropic",
+  anthropicOptionsSchema
+);
+
+/**
+ * Route the assistant to Anthropic's Claude API. Reads `ANTHROPIC_API_KEY`
+ * and needs `@ai-sdk/anthropic` installed.
+ */
+export const anthropic = (
+  options: AssistantAnthropicOptions
+): AssistantAnthropicAdapter => ({
+  kind: "anthropic",
+  options,
+  requiredSecrets: [options.apiKeyEnv ?? ANTHROPIC_API_KEY_ENV],
+  runtimeDeps: [ANTHROPIC_SDK.pkg],
+});
+
+// ---------------------------------------------------------------------------
+// gemini()
+// ---------------------------------------------------------------------------
+
+const GEMINI_API_KEY_ENV = "GEMINI_API_KEY";
+
+/** Options for {@link gemini}. */
+export interface AssistantGeminiOptions extends AssistantAdapterOptions {
+  /** The Gemini model id (`gemini-3.5-flash`). */
+  model: string;
+  /**
+   * How much the model reasons before answering. The Google provider maps
+   * the level to the model's thinking level, or to a thinking budget on
+   * models that take one. Omitted keeps the model's default.
+   */
+  reasoning?: AssistantReasoning;
+}
+
+const geminiOptionsSchema = z.strictObject({
+  ...sharedOptions(GEMINI_API_KEY_ENV),
+  model: z.string().min(1),
+  reasoning: reasoningOption,
+});
+
+export type AssistantGeminiAdapter = AdapterDescriptor<
+  "gemini",
+  AssistantGeminiOptions
+>;
+
+export const geminiAdapterSchema = adapterDescriptorSchema(
+  "gemini",
+  geminiOptionsSchema
+);
+
+/**
+ * Route the assistant to Google's Gemini API. Reads `GEMINI_API_KEY` and
+ * needs `@ai-sdk/google` installed.
+ */
+export const gemini = (
+  options: AssistantGeminiOptions
+): AssistantGeminiAdapter => ({
+  kind: "gemini",
+  options,
+  requiredSecrets: [options.apiKeyEnv ?? GEMINI_API_KEY_ENV],
+  runtimeDeps: [GEMINI_SDK.pkg],
+});
+
+// ---------------------------------------------------------------------------
+// grok()
+// ---------------------------------------------------------------------------
+
+const GROK_API_KEY_ENV = "XAI_API_KEY";
+
+/** Options for {@link grok}. */
+export interface AssistantGrokOptions extends AssistantAdapterOptions {
+  /** The Grok model id (`grok-4.7`). */
+  model: string;
+  /**
+   * How much the model reasons before answering, sent as xAI's reasoning
+   * effort on the models that take one. Omitted keeps the model's default.
+   */
+  reasoning?: AssistantReasoning;
+}
+
+const grokOptionsSchema = z.strictObject({
+  ...sharedOptions(GROK_API_KEY_ENV),
+  model: z.string().min(1),
+  reasoning: reasoningOption,
+});
+
+export type AssistantGrokAdapter = AdapterDescriptor<
+  "grok",
+  AssistantGrokOptions
+>;
+
+export const grokAdapterSchema = adapterDescriptorSchema(
+  "grok",
+  grokOptionsSchema
+);
+
+/**
+ * Route the assistant to xAI's Grok models. Reads `XAI_API_KEY` and needs
+ * `@ai-sdk/xai` installed.
+ */
+export const grok = (options: AssistantGrokOptions): AssistantGrokAdapter => ({
+  kind: "grok",
+  options,
+  requiredSecrets: [options.apiKeyEnv ?? GROK_API_KEY_ENV],
+  runtimeDeps: [GROK_SDK.pkg],
+});
+
 // ---------------------------------------------------------------------------
 // openrouter()
 // ---------------------------------------------------------------------------
@@ -272,87 +519,39 @@ export const inkeep = (
   runtimeDeps: [OPENAI_COMPATIBLE_DEP],
 });
 
-// ---------------------------------------------------------------------------
-// openaiCompatible()
-// ---------------------------------------------------------------------------
-
-/** Options for {@link openaiCompatible}. */
-export interface AssistantOpenAICompatibleOptions extends AssistantAdapterOptions {
-  /** Name of the env var holding the endpoint's API key. */
-  apiKeyEnv: string;
-  /** The endpoint's base URL (`https://my-gateway.example.com/v1`). */
-  baseUrl: string;
-  /** The model id the endpoint serves. */
-  model: string;
-  /** The provider name the AI SDK reports. Defaults to `openai-compatible`. */
-  name?: string;
-  /**
-   * How much the model reasons before answering, sent in the request as
-   * `reasoning_effort`, so the endpoint has to accept that parameter.
-   * Omitted keeps the model's default.
-   */
-  reasoning?: AssistantReasoning;
-}
-
-const openaiCompatibleOptionsSchema = z.strictObject({
-  ...sharedOptions("API_KEY"),
-  // A generic endpoint has no preset, so the caller names the key env var.
-  apiKeyEnv: z.string().min(1),
-  baseUrl: z.url(),
-  model: z.string().min(1),
-  name: z.string().min(1).default("openai-compatible"),
-  reasoning: reasoningOption,
-});
-
-export type AssistantOpenAICompatibleAdapter = AdapterDescriptor<
-  "openai-compatible",
-  AssistantOpenAICompatibleOptions
->;
-
-export const openaiCompatibleAdapterSchema = adapterDescriptorSchema(
-  "openai-compatible",
-  openaiCompatibleOptionsSchema
-);
-
-/**
- * Route the assistant through any OpenAI-compatible endpoint: supply its `baseUrl`,
- * the `model` it serves, and the env var holding its key. Needs
- * `@ai-sdk/openai-compatible` installed.
- */
-export const openaiCompatible = (
-  options: AssistantOpenAICompatibleOptions
-): AssistantOpenAICompatibleAdapter => ({
-  kind: "openai-compatible",
-  options,
-  requiredSecrets: [options.apiKeyEnv],
-  runtimeDeps: [OPENAI_COMPATIBLE_DEP],
-});
-
 // ---------------------------------------------------------------------------
 // The `ai.assistant.provider` schema
 // ---------------------------------------------------------------------------
 
-/** Which backend answers the assistant: the value of `gateway()`, `openrouter()`, … */
+/** Which backend answers the assistant: the value of `gateway()`, `openai()`, … */
 export type AssistantAdapter =
   | AssistantGatewayAdapter
+  | AssistantOpenAIAdapter
+  | AssistantAnthropicAdapter
+  | AssistantGeminiAdapter
+  | AssistantGrokAdapter
   | AssistantOpenRouterAdapter
   | AssistantLlmGatewayAdapter
-  | AssistantInkeepAdapter
-  | AssistantOpenAICompatibleAdapter;
+  | AssistantInkeepAdapter;
 
 // ---------------------------------------------------------------------------
 // Blume 1 hints
 // ---------------------------------------------------------------------------
 
 /**
- * The 1.x `ai.ask.provider` names — also the adapters' `kind`s — each with the
- * `blume/ai` factory that replaced it.
+ * The adapters' `kind`s and the 1.x `ai.ask.provider` names, each with the
+ * `blume/ai` factory that takes its place.
  */
 const FACTORY_BY_PROVIDER = new Map([
+  ["anthropic", "anthropic"],
   ["gateway", "gateway"],
+  ["gemini", "gemini"],
+  ["grok", "grok"],
   ["inkeep", "inkeep"],
   ["llmgateway", "llmgateway"],
-  ["openai-compatible", "openaiCompatible"],
+  ["openai", "openai"],
+  // 1.x only: an OpenAI-compatible endpoint is `openai()` with a `baseUrl`.
+  ["openai-compatible", "openai"],
   ["openrouter", "openrouter"],
 ]);
 
@@ -417,7 +616,7 @@ const providerNotAdapterMessage = (issue: z.core.$ZodRawIssue): string => {
   const factory = name.success ? FACTORY_BY_PROVIDER.get(name.data) : undefined;
   return factory
     ? `ai.assistant.provider takes an adapter from "blume/ai", not a provider name: \`provider: ${factory}({ model })\`. The 1.x model, apiKeyEnv, baseUrl, headers, and reasoning fields move into the call.`
-    : 'ai.assistant.provider takes an adapter from "blume/ai": gateway(), openrouter(), llmgateway(), inkeep(), or openaiCompatible().';
+    : 'ai.assistant.provider takes an adapter from "blume/ai": openai(), anthropic(), gemini(), grok(), gateway(), openrouter(), llmgateway(), or inkeep().';
 };
 
 /**
@@ -429,10 +628,13 @@ export const assistantAdapterSchema = z.discriminatedUnion(
   "kind",
   [
     gatewayAdapterSchema,
+    openaiAdapterSchema,
+    anthropicAdapterSchema,
+    geminiAdapterSchema,
+    grokAdapterSchema,
     openrouterAdapterSchema,
     llmgatewayAdapterSchema,
     inkeepAdapterSchema,
-    openaiCompatibleAdapterSchema,
   ],
   {
     // A non-object (a 1.x provider name) fails before any discriminator is
@@ -485,6 +687,12 @@ export interface AskBackendTemplate {
 export interface AskBackend {
   /** Whether Blume grounds answers in the docs (Inkeep retrieves itself). */
   grounded: boolean;
+  /**
+   * Whether the docs tools are on when `ai.assistant.tools` is unset: yes for
+   * the hosted model catalogs, whose models call tools, and no for an
+   * OpenAI-compatible backend, which may be a local model that can't.
+   */
+  toolsByDefault: boolean;
   kind: AssistantAdapterKind;
   /** Human-readable adapter name for diagnostics ("AI Gateway"). */
   label: string;
@@ -562,6 +770,7 @@ const gatewayBackend = (
   apiKey: ${secretExpr(options.apiKeyEnv)},${headersLine(options.headers)}
 });\n`,
   },
+  toolsByDefault: true,
 });
 
 const openrouterBackend = (
@@ -589,6 +798,7 @@ const openrouterBackend = (
   apiKey: ${secretExpr(options.apiKeyEnv)},${headersLine(options.headers)}
 });\n`,
     },
+    toolsByDefault: true,
   };
 };
 
@@ -601,6 +811,7 @@ const openaiCompatibleBackend = (
   kind: AssistantAdapterKind,
   label: string,
   grounded: boolean,
+  toolsByDefault: boolean,
   options: {
     apiKeyEnv: string;
     baseUrl: string;
@@ -630,8 +841,66 @@ const openaiCompatibleBackend = (
   name: ${JSON.stringify(options.name)},
 });\n`,
   },
+  toolsByDefault,
+});
+
+/**
+ * The backend for a provider Blume calls directly, through that provider's
+ * own AI SDK package, which maps the top-level `reasoning` call option to the
+ * model's control itself. Their models all call tools.
+ */
+const directBackend = (
+  kind: AssistantAdapterKind,
+  label: string,
+  sdk: { factory: string; pkg: string },
+  options: {
+    apiKeyEnv: string;
+    headers?: Record<string, string>;
+    model: string;
+    name?: string;
+    providerOptions?: z.output<typeof providerOptionsSchema>;
+    reasoning?: AssistantReasoning;
+  }
+): AskBackend => ({
+  grounded: true,
+  kind,
+  label,
+  template: {
+    fields: callFields(options),
+    imports: [
+      'import { createTextStreamResponse, streamText, toTextStream } from "ai";',
+      `import { ${sdk.factory} } from ${JSON.stringify(sdk.pkg)};`,
+    ],
+    keyCheck: keyCheck(options.apiKeyEnv),
+    model: `provider(${JSON.stringify(options.model)})`,
+    setup: `\nconst provider = ${sdk.factory}({
+  apiKey: ${secretExpr(options.apiKeyEnv)},${headersLine(options.headers)}${
+    options.name ? `\n  name: ${JSON.stringify(options.name)},` : ""
+  }
+});\n`,
+  },
+  toolsByDefault: true,
 });
 
+/**
+ * `openai()`: OpenAI itself through its own SDK, or, with a `baseUrl`, a
+ * generic endpoint through the OpenAI-compatible provider — Chat Completions,
+ * which most such endpoints serve where the Responses API isn't — with the
+ * tools off by default, since a self-hosted model may not call them.
+ */
+const openaiBackend = (
+  options: z.output<typeof openaiOptionsSchema>
+): AskBackend => {
+  const { baseUrl } = options;
+  return baseUrl
+    ? openaiCompatibleBackend("openai", "OpenAI-compatible", true, false, {
+        ...options,
+        baseUrl,
+        name: options.name ?? "openai-compatible",
+      })
+    : directBackend("openai", "OpenAI", OPENAI_SDK, options);
+};
+
 /** Resolve a parsed `ai.assistant.provider` descriptor into its backend. */
 export const resolveAskBackend = (
   provider: AssistantAdapterConfig = assistantAdapterSchema.parse(
@@ -642,11 +911,25 @@ export const resolveAskBackend = (
     case "gateway": {
       return gatewayBackend(provider.options);
     }
+    case "anthropic": {
+      return directBackend(
+        "anthropic",
+        "Anthropic",
+        ANTHROPIC_SDK,
+        provider.options
+      );
+    }
+    case "gemini": {
+      return directBackend("gemini", "Gemini", GEMINI_SDK, provider.options);
+    }
+    case "grok": {
+      return directBackend("grok", "Grok", GROK_SDK, provider.options);
+    }
     case "openrouter": {
       return openrouterBackend(provider.options);
     }
     case "llmgateway": {
-      return openaiCompatibleBackend("llmgateway", "LLMGateway", true, {
+      return openaiCompatibleBackend("llmgateway", "LLMGateway", true, true, {
         ...provider.options,
         name: "llmgateway",
       });
@@ -654,18 +937,13 @@ export const resolveAskBackend = (
     case "inkeep": {
       // Inkeep answers from the content indexed in its dashboard, so injected
       // excerpts would conflict with its own retrieval.
-      return openaiCompatibleBackend("inkeep", "Inkeep", false, {
+      return openaiCompatibleBackend("inkeep", "Inkeep", false, false, {
         ...provider.options,
         name: "inkeep",
       });
     }
     default: {
-      return openaiCompatibleBackend(
-        "openai-compatible",
-        "OpenAI-compatible",
-        true,
-        provider.options
-      );
+      return openaiBackend(provider.options);
     }
   }
 };

package/src/ai/changelog-markdown.ts

@@ -1,4 +1,5 @@
 import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
+import { withChangelogIndexText } from "../core/changelog-index.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { absoluteUrl } from "../core/site-url.ts";
@@ -45,12 +46,16 @@ const rowLine = (project: BlumeProject, { date, page }: IndexRow): string => {
 
 export const buildChangelogIndexMarkdown = (project: BlumeProject): string => {
   const { i18n } = project.config;
-  const ui = i18n
-    ? resolveUIStrings(i18n.defaultLocale, {
-        defaultLocale: i18n.defaultLocale,
-        overrides: i18n.ui,
-      })
-    : EN_UI;
+  const ui = withChangelogIndexText(
+    project.config,
+    i18n
+      ? resolveUIStrings(i18n.defaultLocale, {
+          defaultLocale: i18n.defaultLocale,
+          overrides: i18n.ui,
+        })
+      : EN_UI,
+    i18n?.defaultLocale
+  );
   const rows: IndexRow[] = project.graph.pages
     .filter(
       (page) =>