tanstack-ai

What this skill does

## Overview

TanStack AI is a modular, provider-agnostic AI SDK with tree-shakeable adapters for OpenAI, Anthropic, Gemini, Ollama, and more. It provides streaming-first text generation, tool calling with approval workflows, structured output with Zod schemas, multimodal content support, and React hooks for chat/completion UIs.

**Core:** `@tanstack/ai`
**Vanilla Client:** `@tanstack/ai-client` (framework-agnostic)
**React:** `@tanstack/ai-react`
**Solid:** `@tanstack/ai-solid`
**Adapters:** `@tanstack/ai-openai`, `@tanstack/ai-anthropic`, `@tanstack/ai-gemini`, `@tanstack/ai-ollama`
**Languages:** TypeScript/JavaScript, PHP, Python
**Status:** Alpha

## Installation

```bash
npm install @tanstack/ai @tanstack/ai-react
# Or for framework-agnostic vanilla client:
npm install @tanstack/ai @tanstack/ai-client
# Provider adapters (install only what you need):
npm install @tanstack/ai-openai
npm install @tanstack/ai-anthropic
npm install @tanstack/ai-gemini
npm install @tanstack/ai-ollama
```

### PHP Installation

```bash
composer require tanstack/ai tanstack/ai-openai
```

### Python Installation

```bash
pip install tanstack-ai tanstack-ai-openai
```

## Core: generate()

```typescript
import { generate } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai/adapters'

const result = await generate({
  adapter: openaiText({ model: 'gpt-4o' }),
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain React hooks in 3 sentences.' },
  ],
})

// Streaming with async iteration
for await (const chunk of result) {
  process.stdout.write(chunk.text)
}
```

## Provider Adapters

```typescript
import { openaiText } from '@tanstack/ai-openai/adapters'
import { anthropicText } from '@tanstack/ai-anthropic/adapters'
import { geminiText } from '@tanstack/ai-gemini/adapters'
import { ollamaText } from '@tanstack/ai-ollama/adapters'

// OpenAI
const openai = openaiText({ model: 'gpt-4o' })

// Anthropic
const anthropic = anthropicText({ model: 'claude-sonnet-4-20250514' })

// Google Gemini
const gemini = geminiText({ model: 'gemini-pro' })

// Ollama (local)
const ollama = ollamaText({ model: 'llama3' })

// Runtime adapter switching
const adapter = process.env.AI_PROVIDER === 'anthropic' ? anthropic : openai
```

## React Hooks

### useChat

```tsx
import { useChat } from '@tanstack/ai-react'

function ChatUI() {
  const { messages, input, setInput, handleSubmit, isLoading } = useChat({
    adapter: openaiText({ model: 'gpt-4o' }),
  })

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          <strong>{msg.role}:</strong> {msg.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Type a message..."
        />
        <button type="submit" disabled={isLoading}>
          Send
        </button>
      </form>
    </div>
  )
}
```

### useCompletion

```tsx
import { useCompletion } from '@tanstack/ai-react'

function CompletionUI() {
  const { completion, input, setInput, handleSubmit, isLoading } = useCompletion({
    adapter: openaiText({ model: 'gpt-4o' }),
  })

  return (
    <div>
      <form onSubmit={handleSubmit}>
        <textarea
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Enter prompt..."
        />
        <button type="submit" disabled={isLoading}>Generate</button>
      </form>
      {completion && <div>{completion}</div>}
    </div>
  )
}
```

## Solid.js Hooks

```tsx
import { createChat } from '@tanstack/ai-solid'

function ChatUI() {
  const chat = createChat({
    adapter: openaiText({ model: 'gpt-4o' }),
  })

  return (
    <div>
      <For each={chat.messages()}>
        {(msg) => (
          <div>
            <strong>{msg.role}:</strong> {msg.content}
          </div>
        )}
      </For>
      <form onSubmit={chat.handleSubmit}>
        <input
          value={chat.input()}
          onInput={(e) => chat.setInput(e.target.value)}
          placeholder="Type a message..."
        />
        <button type="submit" disabled={chat.isLoading()}>
          Send
        </button>
      </form>
    </div>
  )
}
```

## Vanilla Client

For framework-agnostic usage without React or Solid:

```typescript
import { createAIClient } from '@tanstack/ai-client'
import { openaiText } from '@tanstack/ai-openai/adapters'

const client = createAIClient({
  adapter: openaiText({ model: 'gpt-4o' }),
})

// Subscribe to state changes
client.subscribe((state) => {
  console.log('Messages:', state.messages)
  console.log('Loading:', state.isLoading)
})

// Send a message
await client.send('Hello, world!')

// Clear conversation
client.clear()
```

## Streaming

### Streaming Strategies

```typescript
import { generate } from '@tanstack/ai'

// Default: stream chunks as they arrive
const result = await generate({
  adapter: openaiText({ model: 'gpt-4o' }),
  messages: [...],
  stream: true,
})

for await (const chunk of result) {
  // Process each chunk
  console.log(chunk.text)
}
```

Available streaming strategies:
- **Batch** - Collect all chunks before delivery
- **Punctuation** - Stream at sentence boundaries
- **WordBoundary** - Stream at word boundaries
- **Composite** - Combine multiple strategies

### Server-Sent Events (SSE)

```typescript
// Server-side SSE endpoint
import { createReplayStream } from '@tanstack/ai'

export async function handler(req: Request) {
  const stream = createReplayStream({
    adapter: openaiText({ model: 'gpt-4o' }),
    messages: await req.json(),
  })

  return new Response(stream, {
    headers: { 'Content-Type': 'text/event-stream' },
  })
}
```

## Structured Output

```typescript
import { generate } from '@tanstack/ai'
import { convertZodToJsonSchema } from '@tanstack/ai'
import { z } from 'zod'

const RecipeSchema = z.object({
  name: z.string(),
  ingredients: z.array(z.object({
    item: z.string(),
    amount: z.string(),
  })),
  steps: z.array(z.string()),
  cookTime: z.number(),
})

const result = await generate({
  adapter: openaiText({ model: 'gpt-4o' }),
  messages: [{ role: 'user', content: 'Give me a pasta recipe' }],
  schema: convertZodToJsonSchema(RecipeSchema),
})

// result is typed as z.infer<typeof RecipeSchema>
console.log(result.name, result.ingredients)
```

## Tool Calling

### Basic Tools

```typescript
import { generate } from '@tanstack/ai'

const result = await generate({
  adapter: openaiText({ model: 'gpt-4o' }),
  messages: [{ role: 'user', content: 'What is the weather in NYC?' }],
  tools: {
    getWeather: {
      description: 'Get weather for a location',
      parameters: z.object({
        location: z.string(),
        unit: z.enum(['celsius', 'fahrenheit']).optional(),
      }),
      execute: async ({ location, unit }) => {
        const data = await fetchWeather(location, unit)
        return data
      },
    },
  },
})
```

### Tool Calling with Approval Workflows

```typescript
import { ToolCallManager } from '@tanstack/ai'

const manager = new ToolCallManager({
  tools: {
    deleteUser: {
      description: 'Delete a user account',
      parameters: z.object({ userId: z.string() }),
      requiresApproval: true, // Requires human approval
      execute: async ({ userId }) => {
        await deleteUser(userId)
        return { success: true }
      },
    },
  },
  onApprovalRequired: async (toolCall) => {
    // Present to user for approval
    return await showApprovalDialog(toolCall)
  },
})
```

### Agentic Loop

```typescript
const result = await generate({
  adapter: openaiText({ model: 'gpt-4o' }),
  messages: [{ role: 'user', content: 'Research and summarize the topic' }],
  tools: { search, summarize, writeReport },
  maxIterations: 10, // Limit agent loop iterations
})
```

## Multimodal Content

```typescript
// Images
const result = await generate({
  adapter: openaiText({ model