@assistant-ui/mcp-docs-server 0.1.36 → 0.1.39

package/.docs/raw/docs/guides/speech.mdx

@@ -8,11 +8,13 @@ import { SpeechSample } from "@/components/docs/samples/speech";
 
 assistant-ui supports text-to-speech via the `SpeechSynthesisAdapter` interface. When a speech adapter is configured, users can trigger playback for any assistant message.
 
+Speech is the read-aloud mode: one message at a time, text to audio. For a live duplex conversation, see [Realtime Voice](/docs/guides/voice). For push-to-talk input into the composer, see [Dictation](/docs/guides/dictation).
+
 <SpeechSample />
 
 ## SpeechSynthesisAdapter
 
-The `SpeechSynthesisAdapter` interface has a single method:
+The adapter has a single method. The type lives in `@assistant-ui/core` and is re-exported from `@assistant-ui/react`:
 
 ```tsx
 import type { SpeechSynthesisAdapter } from "@assistant-ui/react";
@@ -22,26 +24,30 @@ type SpeechSynthesisAdapter = {
 };
 ```
 
-`speak` is called with the plain text of an assistant message and must return an `Utterance` object:
+`speak` receives the plain text of an assistant message and returns an `Utterance`:
 
 ```tsx
-type Utterance = {
-  status: SpeechSynthesisAdapter.Status;
-  cancel: () => void;
-  subscribe: (callback: () => void) => Unsubscribe;
-};
-
-type Status =
-  | { type: "starting" | "running" }
-  | { type: "ended"; reason: "finished" | "cancelled" | "error"; error?: unknown };
+namespace SpeechSynthesisAdapter {
+  type Status =
+    | { type: "starting" | "running" }
+    | {
+        type: "ended";
+        reason: "finished" | "cancelled" | "error";
+        error?: unknown;
+      };
+
+  type Utterance = {
+    status: Status;
+    cancel: () => void;
+    subscribe: (callback: () => void) => Unsubscribe;
+  };
+}
 ```
 
-Currently the following built-in adapter is available:
-
-- `WebSpeechSynthesisAdapter`: uses the browser's `Web Speech API` (`SpeechSynthesis`)
-
 ## WebSpeechSynthesisAdapter
 
+The built-in adapter uses the browser's Web Speech API (`SpeechSynthesis` / `SpeechSynthesisUtterance`):
+
 ```tsx
 import { WebSpeechSynthesisAdapter } from "@assistant-ui/react";
 
@@ -52,7 +58,9 @@ const runtime = useChatRuntime({
 });
 ```
 
-## UI
+When a speech adapter is provided, `capabilities.speech` is set to `true` automatically.
+
+## UI: ActionBarPrimitive.Speak
 
 The default action bar does not include a speech button. Add `ActionBarPrimitive.Speak` and `ActionBarPrimitive.StopSpeaking` to your assistant message action bar:
 
@@ -79,21 +87,17 @@ const AssistantActionBar = () => {
 };
 ```
 
-`ActionBarPrimitive.Speak` is automatically disabled when no speech adapter is configured.
+`ActionBarPrimitive.Speak` is disabled when no speech adapter is configured. While playback is active, `message.speech` holds the current speech state so the UI can switch to `StopSpeaking`.
 
-## Custom Adapters
+## Custom adapters
 
-Implement `SpeechSynthesisAdapter` to call any external TTS API:
+Implement `SpeechSynthesisAdapter` to call any external TTS provider. Fetch audio from your API, play it with `HTMLAudioElement`, and drive utterance status through `subscribe`:
 
 ```tsx title="lib/custom-tts-adapter.ts"
 import type { SpeechSynthesisAdapter } from "@assistant-ui/react";
 
 export class CustomTTSAdapter implements SpeechSynthesisAdapter {
-  private apiUrl: string;
-
-  constructor(options: { apiUrl: string }) {
-    this.apiUrl = options.apiUrl;
-  }
+  constructor(private apiUrl: string) {}
 
   speak(text: string): SpeechSynthesisAdapter.Utterance {
     const subscribers = new Set<() => void>();
@@ -104,7 +108,10 @@ export class CustomTTSAdapter implements SpeechSynthesisAdapter {
       for (const cb of subscribers) cb();
     };
 
-    const finish = (reason: "finished" | "cancelled" | "error", error?: unknown) => {
+    const finish = (
+      reason: "finished" | "cancelled" | "error",
+      error?: unknown,
+    ) => {
       if (status.type === "ended") return;
       status = { type: "ended", reason, error };
       notify();
@@ -117,17 +124,20 @@ export class CustomTTSAdapter implements SpeechSynthesisAdapter {
     })
       .then((res) => res.blob())
       .then((blob) => {
+        if (status.type === "ended") return;
         audio = new Audio(URL.createObjectURL(blob));
         status = { type: "running" };
         notify();
         audio.onended = () => finish("finished");
         audio.onerror = (e) => finish("error", e);
-        audio.play();
+        audio.play().catch((err) => finish("error", err));
       })
       .catch((err) => finish("error", err));
 
     return {
-      get status() { return status; },
+      get status() {
+        return status;
+      },
       cancel: () => {
         audio?.pause();
         finish("cancelled");
@@ -141,14 +151,22 @@ export class CustomTTSAdapter implements SpeechSynthesisAdapter {
 }
 ```
 
-Wire it up the same way as the built-in adapter:
+Wire it on the same `adapters.speech` slot as the built-in adapter:
 
 ```tsx
 import { CustomTTSAdapter } from "@/lib/custom-tts-adapter";
 
 const runtime = useChatRuntime({
   adapters: {
-    speech: new CustomTTSAdapter({ apiUrl: "/api/tts" }),
+    speech: new CustomTTSAdapter("/api/tts"),
   },
 });
 ```
+
+Use this shape for any provider TTS (OpenAI, ElevenLabs, cloud speech APIs, and so on). Keep the server route responsible for API keys; the adapter only needs a URL that returns audio bytes.
+
+## Related guides
+
+- [Realtime Voice](/docs/guides/voice): duplex voice sessions with `RealtimeVoiceAdapter`, `createVoiceSession`, and the voice UI component.
+- [Dictation](/docs/guides/dictation): speech-to-text into the composer with `DictationAdapter` and `ComposerPrimitive.Dictate`.
+- [Speech and Dictation API reference](/docs/api-reference/voice/speech-dictation): generated type docs.

package/.docs/raw/docs/guides/suggestions.mdx

@@ -163,6 +163,30 @@ const runtime = useLocalRuntime(myChatModel, {
 });
 ```
 
+For LLM-powered follow ups, use `createSuggestionAdapter`. It builds a deterministic transcript prompt from recent messages and calls your `complete` function. Forward the optional `signal` so in-flight generation can be cancelled when a new run starts.
+
+```tsx
+import { createSuggestionAdapter, useLocalRuntime } from "@assistant-ui/react";
+
+const suggestionAdapter = createSuggestionAdapter({
+  async complete({ prompt, signal }) {
+    const response = await fetch("/api/suggestions", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ prompt }),
+      signal,
+    });
+    const data: string[] = await response.json();
+    return data;
+  },
+  count: 3,
+});
+
+const runtime = useLocalRuntime(myChatModel, {
+  adapters: { suggestion: suggestionAdapter },
+});
+```
+
 ### External store runtime
 
 `useExternalStoreRuntime` exposes a `suggestions` field, so you can drive follow ups straight from your application state.
@@ -190,7 +214,52 @@ const [suggestions, setSuggestions] = useState<ThreadSuggestion[]>([]);
 const runtime = useChatRuntime({ suggestions });
 ```
 
-The local runtime clears its suggestions when a new run starts. External store and AI SDK runtimes keep whatever state you push, so you control the lifetime.
+They also accept the same `suggestion` adapter as the local runtime under `adapters`, so one adapter works across both runtimes. When set, the adapter owns `thread.suggestions` after each run settles, and any static `suggestions` option is ignored. Pair it with `createSuggestionAdapter` for built-in prompt construction:
+
+```tsx
+import { createSuggestionAdapter } from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+
+const runtime = useChatRuntime({
+  adapters: {
+    suggestion: createSuggestionAdapter({
+      async complete({ prompt, signal }) {
+        const response = await fetch("/api/suggestions", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ prompt }),
+          signal,
+        });
+        return response.json();
+      },
+    }),
+  },
+});
+```
+
+Example route that returns suggestion strings with the AI SDK:
+
+```ts
+// app/api/suggestions/route.ts
+import { generateObject } from "ai";
+import { z } from "zod";
+
+export async function POST(req: Request) {
+  const { prompt } = await req.json();
+
+  const { object } = await generateObject({
+    model: yourModel,
+    schema: z.object({
+      suggestions: z.array(z.string()).min(1).max(5),
+    }),
+    prompt,
+  });
+
+  return Response.json(object.suggestions);
+}
+```
+
+The local runtime clears its suggestions when a new run starts. External store runtimes keep whatever state you push, so you control the lifetime. With `adapters.suggestion` on the AI SDK runtime, suggestions clear on run start and regenerate after settle, matching the local runtime.
 
 ### Rendering runtime suggestions