@tanstack/cta-framework-react-cra 0.43.1 → 0.44.0

package/examples/tanchat/assets/src/hooks/useTTS.ts

@@ -0,0 +1,78 @@
+import { useCallback, useRef, useState } from 'react'
+
+/**
+ * Hook for text-to-speech playback via the TTS API.
+ */
+export function useTTS() {
+  const [playingId, setPlayingId] = useState<string | null>(null)
+  const audioRef = useRef<HTMLAudioElement | null>(null)
+
+  const speak = useCallback(async (text: string, id: string) => {
+    // Stop any currently playing audio
+    if (audioRef.current) {
+      audioRef.current.pause()
+      audioRef.current = null
+    }
+
+    setPlayingId(id)
+
+    try {
+      const response = await fetch('/demo/api/tts', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          text,
+          voice: 'nova',
+          model: 'tts-1',
+          format: 'mp3',
+        }),
+      })
+
+      if (!response.ok) {
+        const errorData = await response.json()
+        throw new Error(errorData.error || 'TTS failed')
+      }
+
+      const result = await response.json()
+
+      // Convert base64 to audio and play
+      const audioData = atob(result.audio)
+      const bytes = new Uint8Array(audioData.length)
+      for (let i = 0; i < audioData.length; i++) {
+        bytes[i] = audioData.charCodeAt(i)
+      }
+      const blob = new Blob([bytes], { type: result.contentType })
+      const url = URL.createObjectURL(blob)
+
+      const audio = new Audio(url)
+      audioRef.current = audio
+
+      audio.onended = () => {
+        URL.revokeObjectURL(url)
+        setPlayingId(null)
+        audioRef.current = null
+      }
+
+      audio.onerror = () => {
+        URL.revokeObjectURL(url)
+        setPlayingId(null)
+        audioRef.current = null
+      }
+
+      await audio.play()
+    } catch (error) {
+      console.error('TTS error:', error)
+      setPlayingId(null)
+    }
+  }, [])
+
+  const stop = useCallback(() => {
+    if (audioRef.current) {
+      audioRef.current.pause()
+      audioRef.current = null
+    }
+    setPlayingId(null)
+  }, [])
+
+  return { playingId, speak, stop }
+}

package/examples/tanchat/assets/src/lib/model-selection.ts

@@ -0,0 +1,78 @@
+export type Provider = 'openai' | 'anthropic' | 'gemini' | 'ollama'
+
+export interface ModelOption {
+  provider: Provider
+  model: string
+  label: string
+}
+
+export const MODEL_OPTIONS: Array<ModelOption> = [
+  // OpenAI models
+  { provider: 'openai', model: 'gpt-4o', label: 'OpenAI - GPT-4o' },
+  { provider: 'openai', model: 'gpt-4o-mini', label: 'OpenAI - GPT-4o Mini' },
+
+  // Anthropic models
+  {
+    provider: 'anthropic',
+    model: 'claude-haiku-4-5',
+    label: 'Anthropic - Claude Haiku 4.5',
+  },
+  {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-5-20250929',
+    label: 'Anthropic - Claude Sonnet 4.5',
+  },
+
+  // Gemini models
+  {
+    provider: 'gemini',
+    model: 'gemini-2.0-flash-exp',
+    label: 'Gemini - 2.0 Flash',
+  },
+
+  // Ollama models
+  { provider: 'ollama', model: 'mistral:7b', label: 'Ollama - Mistral 7B' },
+]
+
+const STORAGE_KEY = 'tanstack-ai-model-preference'
+
+export function getStoredModelPreference(): ModelOption | null {
+  if (typeof window === 'undefined') return null
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY)
+    if (stored) {
+      const parsed = JSON.parse(stored)
+      // Validate that the stored option still exists in MODEL_OPTIONS
+      const found = MODEL_OPTIONS.find(
+        (o) => o.provider === parsed.provider && o.model === parsed.model,
+      )
+      if (found) return found
+    }
+  } catch {
+    // Ignore storage errors
+  }
+  return null
+}
+
+export function setStoredModelPreference(option: ModelOption): void {
+  if (typeof window === 'undefined') return
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(option))
+  } catch {
+    // Ignore storage errors
+  }
+}
+
+export function getDefaultModelOption(): ModelOption {
+  return getStoredModelPreference() || MODEL_OPTIONS[0]
+}
+
+export function getModelOptionsForProvider(provider: Provider): ModelOption[] {
+  return MODEL_OPTIONS.filter((o) => o.provider === provider)
+}
+
+export function getAvailableModelOptions(
+  availableProviders: Provider[],
+): ModelOption[] {
+  return MODEL_OPTIONS.filter((o) => availableProviders.includes(o.provider))
+}

package/examples/tanchat/assets/src/lib/vendor-capabilities.ts

@@ -0,0 +1,55 @@
+import type { Provider } from './model-selection'
+
+export interface VendorCapabilities {
+  chat: boolean
+  structured: boolean
+  image: boolean
+  transcription: boolean
+  tts: boolean
+}
+
+export const VENDOR_CAPABILITIES: Record<Provider, VendorCapabilities> = {
+  openai: {
+    chat: true,
+    structured: true,
+    image: true,
+    transcription: true,
+    tts: true,
+  },
+  anthropic: {
+    chat: true,
+    structured: true,
+    image: false,
+    transcription: false,
+    tts: false,
+  },
+  gemini: {
+    chat: true,
+    structured: true,
+    image: false,
+    transcription: false,
+    tts: false,
+  },
+  ollama: {
+    chat: true,
+    structured: true,
+    image: false,
+    transcription: false,
+    tts: false,
+  },
+}
+
+export function hasCapability(
+  provider: Provider,
+  capability: keyof VendorCapabilities,
+): boolean {
+  return VENDOR_CAPABILITIES[provider]?.[capability] ?? false
+}
+
+export function getProvidersWithCapability(
+  capability: keyof VendorCapabilities,
+): Provider[] {
+  return (Object.keys(VENDOR_CAPABILITIES) as Provider[]).filter(
+    (provider) => VENDOR_CAPABILITIES[provider][capability],
+  )
+}

package/examples/tanchat/assets/src/routes/demo/api.available-providers.ts

@@ -0,0 +1,35 @@
+import { createFileRoute } from '@tanstack/react-router'
+import type { Provider } from '@/lib/model-selection'
+
+export const Route = createFileRoute('/demo/api/available-providers')({
+  server: {
+    handlers: {
+      GET: async () => {
+        const available: Provider[] = []
+
+        if (process.env.OPENAI_API_KEY) {
+          available.push('openai')
+        }
+        if (process.env.ANTHROPIC_API_KEY) {
+          available.push('anthropic')
+        }
+        if (process.env.GEMINI_API_KEY) {
+          available.push('gemini')
+        }
+        // Ollama is always available (local, no key needed)
+        available.push('ollama')
+
+        return new Response(
+          JSON.stringify({
+            providers: available,
+            hasOpenAI: available.includes('openai'),
+          }),
+          {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        )
+      },
+    },
+  },
+})

package/examples/tanchat/assets/src/routes/demo/api.image.ts

@@ -0,0 +1,74 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { generateImage, createImageOptions } from '@tanstack/ai'
+import { openaiImage } from '@tanstack/ai-openai'
+
+export const Route = createFileRoute('/demo/api/image')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const body = await request.json()
+        const { prompt, numberOfImages = 1, size = '1024x1024' } = body
+        const data = body.data || {}
+        const model: string = data.model || body.model || 'gpt-image-1'
+
+        if (!prompt || prompt.trim().length === 0) {
+          return new Response(
+            JSON.stringify({
+              error: 'Prompt is required',
+            }),
+            {
+              status: 400,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          )
+        }
+
+        if (!process.env.OPENAI_API_KEY) {
+          return new Response(
+            JSON.stringify({
+              error: 'OPENAI_API_KEY is not configured',
+            }),
+            {
+              status: 500,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          )
+        }
+
+        try {
+          const options = createImageOptions({
+            adapter: openaiImage((model || 'gpt-image-1') as any),
+          })
+
+          const result = await generateImage({
+            ...options,
+            prompt,
+            numberOfImages,
+            size,
+          })
+
+          return new Response(
+            JSON.stringify({
+              images: result.images,
+              model,
+            }),
+            {
+              status: 200,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          )
+        } catch (error: any) {
+          return new Response(
+            JSON.stringify({
+              error: error.message || 'An error occurred',
+            }),
+            {
+              status: 500,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          )
+        }
+      },
+    },
+  },
+})

package/examples/tanchat/assets/src/routes/demo/api.structured.ts

@@ -0,0 +1,168 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { chat, createChatOptions } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { geminiText } from "@tanstack/ai-gemini";
+import { openaiText } from "@tanstack/ai-openai";
+import { ollamaText } from "@tanstack/ai-ollama";
+import { z } from "zod";
+
+import type { Provider } from "@/lib/model-selection";
+
+// Schema for structured recipe output
+const RecipeSchema = z.object({
+  name: z.string().describe("The name of the recipe"),
+  description: z.string().describe("A brief description of the dish"),
+  prepTime: z.string().describe('Preparation time (e.g., "15 minutes")'),
+  cookTime: z.string().describe('Cooking time (e.g., "30 minutes")'),
+  servings: z.number().describe("Number of servings"),
+  difficulty: z.enum(["easy", "medium", "hard"]).describe("Difficulty level"),
+  ingredients: z
+    .array(
+      z.object({
+        item: z.string().describe("Ingredient name"),
+        amount: z.string().describe('Amount needed (e.g., "2 cups")'),
+        notes: z.string().optional().describe("Optional preparation notes"),
+      })
+    )
+    .describe("List of ingredients"),
+  instructions: z
+    .array(z.string())
+    .describe("Step-by-step cooking instructions"),
+  tips: z.array(z.string()).optional().describe("Optional cooking tips"),
+  nutritionPerServing: z
+    .object({
+      calories: z.number().optional(),
+      protein: z.string().optional(),
+      carbs: z.string().optional(),
+      fat: z.string().optional(),
+    })
+    .optional()
+    .describe("Nutritional information per serving"),
+});
+
+export type Recipe = z.infer<typeof RecipeSchema>;
+
+export const Route = createFileRoute("/demo/api/structured")({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const body = await request.json();
+        const { recipeName, mode = "structured" } = body;
+        const data = body.data || {};
+        const provider: Provider = data.provider || body.provider || "openai";
+        const model: string = data.model || body.model || "gpt-4o";
+
+        if (!recipeName || recipeName.trim().length === 0) {
+          return new Response(
+            JSON.stringify({
+              error: "Recipe name is required",
+            }),
+            {
+              status: 400,
+              headers: { "Content-Type": "application/json" },
+            }
+          );
+        }
+
+        try {
+          // Pre-define typed adapter configurations
+          const adapterConfig = {
+            anthropic: () =>
+              createChatOptions({
+                adapter: anthropicText(
+                  (model || "claude-sonnet-4-5-20250929") as any
+                ),
+              }),
+            gemini: () =>
+              createChatOptions({
+                adapter: geminiText((model || "gemini-2.0-flash-exp") as any),
+              }),
+            ollama: () =>
+              createChatOptions({
+                adapter: ollamaText((model || "mistral:7b") as any),
+              }),
+            openai: () =>
+              createChatOptions({
+                adapter: openaiText((model || "gpt-4o") as any),
+              }),
+          };
+
+          const options = adapterConfig[provider]();
+
+          if (mode === "structured") {
+            // Structured output mode - returns validated object
+            const result = await chat({
+              ...options,
+              messages: [
+                {
+                  role: "user",
+                  content: `Generate a complete recipe for: ${recipeName}. Include all ingredients with amounts, step-by-step instructions, prep/cook times, and difficulty level.`,
+                },
+              ],
+              outputSchema: RecipeSchema,
+            } as any);
+
+            return new Response(
+              JSON.stringify({
+                mode: "structured",
+                recipe: result,
+                provider,
+                model,
+              }),
+              {
+                status: 200,
+                headers: { "Content-Type": "application/json" },
+              }
+            );
+          } else {
+            // One-shot markdown mode - returns text
+            const markdown = await chat({
+              ...options,
+              stream: false,
+              messages: [
+                {
+                  role: "user",
+                  content: `Generate a complete recipe for: ${recipeName}.
+
+Format the recipe in beautiful markdown with:
+- A title with the recipe name
+- A brief description
+- Prep time, cook time, and servings
+- Ingredients list with amounts
+- Numbered step-by-step instructions
+- Optional tips section
+- Nutritional info if applicable
+
+Make it detailed and easy to follow.`,
+                },
+              ],
+            } as any);
+
+            return new Response(
+              JSON.stringify({
+                mode: "oneshot",
+                markdown,
+                provider,
+                model,
+              }),
+              {
+                status: 200,
+                headers: { "Content-Type": "application/json" },
+              }
+            );
+          }
+        } catch (error: any) {
+          return new Response(
+            JSON.stringify({
+              error: error.message || "An error occurred",
+            }),
+            {
+              status: 500,
+              headers: { "Content-Type": "application/json" },
+            }
+          );
+        }
+      },
+    },
+  },
+});

package/examples/tanchat/assets/src/routes/demo/api.tanchat.ts

@@ -0,0 +1,89 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { chat, maxIterations, toStreamResponse } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { openaiText } from "@tanstack/ai-openai";
+import { geminiText } from "@tanstack/ai-gemini";
+import { ollamaText } from "@tanstack/ai-ollama";
+
+import { getGuitars, recommendGuitarToolDef } from "@/lib/example.guitar-tools";
+import type { Provider } from "@/lib/model-selection";
+
+const SYSTEM_PROMPT = `You are a helpful assistant for a store that sells guitars.
+
+CRITICAL INSTRUCTIONS - YOU MUST FOLLOW THIS EXACT WORKFLOW:
+
+When a user asks for a guitar recommendation:
+1. FIRST: Use the getGuitars tool (no parameters needed)
+2. SECOND: Use the recommendGuitar tool with the ID of the guitar you want to recommend
+3. NEVER write a recommendation directly - ALWAYS use the recommendGuitar tool
+
+IMPORTANT:
+- The recommendGuitar tool will display the guitar in a special, appealing format
+- You MUST use recommendGuitar for ANY guitar recommendation
+- ONLY recommend guitars from our inventory (use getGuitars first)
+- The recommendGuitar tool has a buy button - this is how customers purchase
+- Do NOT describe the guitar yourself - let the recommendGuitar tool do it
+`;
+
+export const Route = createFileRoute("/demo/api/tanchat")({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        // Capture request signal before reading body (it may be aborted after body is consumed)
+        const requestSignal = request.signal;
+
+        // If request is already aborted, return early
+        if (requestSignal.aborted) {
+          return new Response(null, { status: 499 }); // 499 = Client Closed Request
+        }
+
+        const abortController = new AbortController();
+
+        try {
+          const body = await request.json();
+          const { messages } = body;
+          const data = body.data || {};
+          const provider: Provider = data.provider || "anthropic";
+          const model: string = data.model || "claude-haiku-4-5";
+
+          // Adapter factory pattern for multi-vendor support
+          const adapterConfig = {
+            anthropic: () =>
+              anthropicText((model || "claude-haiku-4-5") as any),
+            openai: () => openaiText((model || "gpt-4o") as any),
+            gemini: () => geminiText((model || "gemini-2.0-flash-exp") as any),
+            ollama: () => ollamaText((model || "mistral:7b") as any),
+          };
+
+          const adapter = adapterConfig[provider]();
+
+          const stream = chat({
+            adapter,
+            tools: [
+              getGuitars, // Server tool
+              recommendGuitarToolDef, // No server execute - client will handle
+            ],
+            systemPrompts: [SYSTEM_PROMPT],
+            agentLoopStrategy: maxIterations(5),
+            messages,
+            abortController,
+          });
+
+          return toStreamResponse(stream, { abortController });
+        } catch (error: any) {
+          // If request was aborted, return early (don't send error response)
+          if (error.name === "AbortError" || abortController.signal.aborted) {
+            return new Response(null, { status: 499 }); // 499 = Client Closed Request
+          }
+          return new Response(
+            JSON.stringify({ error: "Failed to process chat request" }),
+            {
+              status: 500,
+              headers: { "Content-Type": "application/json" },
+            }
+          );
+        }
+      },
+    },
+  },
+});

package/examples/tanchat/assets/src/routes/demo/api.transcription.ts

@@ -0,0 +1,89 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { generateTranscription } from "@tanstack/ai";
+import { openaiTranscription } from "@tanstack/ai-openai";
+
+export const Route = createFileRoute("/demo/api/transcription")({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const formData = await request.formData();
+        const audioFile = formData.get("audio") as File | null;
+        const audioBase64 = formData.get("audioBase64") as string | null;
+        const model = (formData.get("model") as string) || "whisper-1";
+        const language = formData.get("language") as string | null;
+        const responseFormat = formData.get("responseFormat") as string | null;
+
+        if (!audioFile && !audioBase64) {
+          return new Response(
+            JSON.stringify({
+              error: "Audio file or base64 data is required",
+            }),
+            {
+              status: 400,
+              headers: { "Content-Type": "application/json" },
+            }
+          );
+        }
+
+        if (!process.env.OPENAI_API_KEY) {
+          return new Response(
+            JSON.stringify({
+              error: "OPENAI_API_KEY is not configured",
+            }),
+            {
+              status: 500,
+              headers: { "Content-Type": "application/json" },
+            }
+          );
+        }
+
+        try {
+          const adapter = openaiTranscription(model as any);
+
+          // Prepare audio data
+          let audioData: string | File;
+          if (audioFile) {
+            audioData = audioFile;
+          } else if (audioBase64) {
+            audioData = audioBase64;
+          } else {
+            throw new Error("No audio data provided");
+          }
+
+          const result = await generateTranscription({
+            adapter,
+            audio: audioData,
+            language: language || undefined,
+            responseFormat: (responseFormat as any) || "verbose_json",
+          });
+
+          return new Response(
+            JSON.stringify({
+              id: result.id,
+              model: result.model,
+              text: result.text,
+              language: result.language,
+              duration: result.duration,
+              segments: result.segments,
+              words: result.words,
+            }),
+            {
+              status: 200,
+              headers: { "Content-Type": "application/json" },
+            }
+          );
+        } catch (error: any) {
+          return new Response(
+            JSON.stringify({
+              error: error.message || "An error occurred",
+            }),
+            {
+              status: 500,
+              headers: { "Content-Type": "application/json" },
+            }
+          );
+        }
+      },
+    },
+  },
+});