blume 2.0.3 → 2.1.0

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/component-markdown.ts

@@ -1,6 +1,7 @@
 import { markdownTable } from "markdown-table";
 import { mdxToMdast } from "satteri";
 
+import { PARAM_LOCATIONS } from "../components/content/api-field.ts";
 import { parseYouTubeId } from "../components/content/youtube.ts";
 import type { ExampleLookup } from "../core/types.ts";
 import { MDX_FEATURES } from "../markdown/features.ts";
@@ -398,6 +399,18 @@ const tabs: ComponentMarkdown = ({ childComponents, children }) => {
     .join("\n\n");
 };
 
+/**
+ * A `<View>` block: its content under its view's name, so an agent reading
+ * the Markdown sees every view and which one each part belongs to.
+ */
+const view: ComponentMarkdown = ({ children, props }) => {
+  const title = isString(props.title) && props.title !== "" ? props.title : "";
+  if (!title) {
+    return children;
+  }
+  return children ? `**${title}**\n\n${children}` : `**${title}**`;
+};
+
 /** Escape the brackets that would end a link's text early. */
 const linkText = (value: string): string =>
   value.replaceAll(/[[\]]/gu, String.raw`\$&`);
@@ -420,6 +433,63 @@ const textProp = (value: EvaluatedValue): string => {
   return isNumber(value) ? String(value) : "";
 };
 
+/** Whether a flag prop is on: shorthand `true`, or the string `"true"`. */
+const flagOn = (value: EvaluatedValue): boolean =>
+  value === true || value === "true";
+
+/** A prop that holds one label or several. */
+const labelList = (value: EvaluatedValue): string[] =>
+  (Array.isArray(value) ? value : [value]).map(textProp).filter(Boolean);
+
+/**
+ * One `<ParamField>` or `<ResponseField>` as a list item: its labels, name,
+ * location, type, flags, and default on the first line, joined with middle
+ * dots, and its description indented under it, nested fields included. A
+ * field with no name, or a prop that wouldn't evaluate, declines.
+ */
+const apiField = (
+  { children, lossy, props }: ComponentMarkdownContext,
+  name: string,
+  location?: string
+): string | null => {
+  if (lossy || name === "") {
+    return null;
+  }
+  const value = props.default;
+  const head = [
+    ...labelList(props.pre),
+    `**${cellCode(name)}**`,
+    ...labelList(props.post),
+    location,
+    textProp(props.type) && cellCode(props.type),
+    flagOn(props.required) ? "required" : "",
+    flagOn(props.deprecated) ? "deprecated" : "",
+    value === undefined || value === null || value === ""
+      ? ""
+      : `default ${cellCode(isString(value) ? value : JSON.stringify(value))}`,
+  ].filter(Boolean);
+  const item = `- ${head.join(" · ")}`;
+  if (!children) {
+    return item;
+  }
+  const body = children
+    .split("\n")
+    .map((line) => (line === "" ? "" : `  ${line}`))
+    .join("\n");
+  return `${item}\n\n${body}`;
+};
+
+/** `<ParamField query="limit">`: named by its location attribute, else `name`. */
+const paramFieldMarkdown: ComponentMarkdown = (context) => {
+  const location = PARAM_LOCATIONS.find((key) => isString(context.props[key]));
+  return location
+    ? apiField(context, textProp(context.props[location]), location)
+    : apiField(context, textProp(context.props.name));
+};
+
+const responseFieldMarkdown: ComponentMarkdown = (context) =>
+  apiField(context, textProp(context.props.name));
+
 /**
  * A card is a link with a blurb, so that is what it becomes: the title as the
  * link text, the body under it, and the call to action last — the order the
@@ -822,7 +892,11 @@ const SERIALIZERS = {
   Icon: icon,
   Math: math,
   Panel: panel,
+  ParamField: paramFieldMarkdown,
   Prompt: prompt,
+  RequestExample: cardGroup,
+  ResponseExample: cardGroup,
+  ResponseField: responseFieldMarkdown,
   Steps: steps,
   Tabs: tabs,
   Tile: tile,
@@ -832,6 +906,7 @@ const SERIALIZERS = {
   "Tree.Folder": treeFolder,
   TypeTable: typeTable,
   Update: update,
+  View: view,
   YouTube: youtube,
 } satisfies Record<string, ComponentMarkdown>;
 

package/src/ai/cors.ts

@@ -61,6 +61,8 @@ export const preflightResponse = (
 
 /** The slice of Astro's `APIContext` the wrapped handler reads. */
 interface RequestContext {
+  /** The reader's address, which the route's rate limit keys on. */
+  readonly clientAddress?: string;
   request: Request;
 }