Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

ai.md

347 lines8.2 KB

1---
2title: "@tanstack/ai"
3id: tanstack-ai-api
4order: 1
5---
6​
7The core AI library for TanStack AI.
8​
9## Installation
10​
11```bash
12npm install @tanstack/ai
13```
14​
15## `chat(options)`
16​
17Creates a streaming chat response.
18​
19```typescript
20import { chat } from "@tanstack/ai";
21import { openaiText } from "@tanstack/ai-openai";
22​
23const stream = chat({
24 adapter: openaiText("gpt-4o"),
25 messages: [{ role: "user", content: "Hello!" }],
26 tools: [myTool],
27 systemPrompts: ["You are a helpful assistant"],
28 agentLoopStrategy: maxIterations(20),
29});
30```
31​
32### Parameters
33​
34- `adapter` - An AI adapter instance with model (e.g., `openaiText('gpt-4o')`, `anthropicText('claude-sonnet-4-5')`)
35- `messages` - Array of chat messages
36- `tools?` - Array of tools for function calling
37- `systemPrompts?` - System prompts to prepend to messages
38- `agentLoopStrategy?` - Strategy for agent loops (default: `maxIterations(5)`)
39- `abortController?` - AbortController for cancellation
40- `modelOptions?` - Model-specific options (renamed from `providerOptions`)
41​
42### Returns
43​
44An async iterable of `StreamChunk`.
45​
46## `summarize(options)`
47​
48Creates a text summarization.
49​
50```typescript
51import { summarize } from "@tanstack/ai";
52import { openaiSummarize } from "@tanstack/ai-openai";
53​
54const result = await summarize({
55 adapter: openaiSummarize("gpt-4o"),
56 text: "Long text to summarize...",
57 maxLength: 100,
58 style: "concise",
59});
60```
61​
62### Parameters
63​
64- `adapter` - An AI adapter instance with model
65- `text` - Text to summarize
66- `maxLength?` - Maximum length of summary
67- `style?` - Summary style ("concise" | "detailed")
68- `modelOptions?` - Model-specific options
69​
70### Returns
71​
72A `SummarizationResult` with the summary text.
73​
74## `toolDefinition(config)`
75​
76Creates an isomorphic tool definition that can be instantiated for server or client execution.
77​
78```typescript
79import { toolDefinition } from "@tanstack/ai";
80import { z } from "zod";
81​
82const myToolDef = toolDefinition({
83 name: "my_tool",
84 description: "Tool description",
85 inputSchema: z.object({
86 param: z.string(),
87 }),
88 outputSchema: z.object({
89 result: z.string(),
90 }),
91 needsApproval: false, // Optional
92});
93​
94// Or create client implementation
95const myClientTool = myToolDef.client(async ({ param }) => {
96 // Client-side implementation
97 return { result: "..." };
98});
99​
100// Use directly in chat() (server-side, no execute)
101chat({
102 adapter: openaiText("gpt-4o"),
103 tools: [myToolDef],
104 messages: [{ role: "user", content: "..." }],
105});
106​
107// Or create server implementation
108const myServerTool = myToolDef.server(async ({ param }) => {
109 // Server-side implementation
110 return { result: "..." };
111});
112​
113// Use directly in chat() (server-side, no execute)
114chat({
115 adapter: openaiText("gpt-4o"),
116 tools: [myServerTool],
117 messages: [{ role: "user", content: "..." }],
118});
119```
120​
121### Parameters
122​
123- `name` - Tool name (must be unique)
124- `description` - Tool description for the model
125- `inputSchema` - Zod schema for input validation
126- `outputSchema?` - Zod schema for output validation
127- `needsApproval?` - Whether tool requires user approval
128- `metadata?` - Additional metadata
129​
130### Returns
131​
132A `ToolDefinition` object with `.server()` and `.client()` methods for creating concrete implementations.
133​
134## `toServerSentEventsStream(stream, abortController?)`
135​
136Converts a stream to a ReadableStream in Server-Sent Events format.
137​
138```typescript
139import { chat, toServerSentEventsStream } from "@tanstack/ai";
140import { openaiText } from "@tanstack/ai-openai";
141​
142const stream = chat({
143 adapter: openaiText("gpt-4o"),
144 messages: [...],
145});
146const readableStream = toServerSentEventsStream(stream);
147```
148​
149### Parameters
150​
151- `stream` - Async iterable of `StreamChunk`
152- `abortController?` - Optional AbortController to abort when stream is cancelled
153​
154### Returns
155​
156A `ReadableStream<Uint8Array>` in Server-Sent Events format. Each chunk is:
157- Prefixed with `"data: "`
158- Followed by `"\n\n"`
159- Stream ends with `"data: [DONE]\n\n"`
160​
161## `toStreamResponse(stream, init?)`
162​
163Converts a stream to an HTTP Response with proper SSE headers.
164​
165```typescript
166import { chat, toStreamResponse } from "@tanstack/ai";
167import { openaiText } from "@tanstack/ai-openai";
168​
169const stream = chat({
170 adapter: openaiText("gpt-4o"),
171 messages: [...],
172});
173return toStreamResponse(stream);
174```
175​
176### Parameters
177​
178- `stream` - Async iterable of `StreamChunk`
179- `init?` - Optional ResponseInit options (including `abortController`)
180​
181### Returns
182​
183A `Response` object suitable for HTTP endpoints with SSE headers (`Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`).
184​
185## `maxIterations(count)`
186​
187Creates an agent loop strategy that limits iterations.
188​
189```typescript
190import { chat, maxIterations } from "@tanstack/ai";
191import { openaiText } from "@tanstack/ai-openai";
192​
193const stream = chat({
194 adapter: openaiText("gpt-4o"),
195 messages: [...],
196 agentLoopStrategy: maxIterations(20),
197});
198```
199​
200### Parameters
201​
202- `count` - Maximum number of tool execution iterations
203​
204### Returns
205​
206An `AgentLoopStrategy` object.
207​
208## Types
209​
210### `ModelMessage`
211​
212```typescript
213interface ModelMessage {
214 role: "user" | "assistant" | "system" | "tool";
215 content: string;
216 toolCallId?: string;
218```
219​
220### `StreamChunk`
221​
222```typescript
223type StreamChunk =
224 | ContentStreamChunk
225 | ThinkingStreamChunk
226 | ToolCallStreamChunk
227 | ToolResultStreamChunk
228 | DoneStreamChunk
229 | ErrorStreamChunk;
230​
231interface ThinkingStreamChunk {
232 type: "thinking";
233 id: string;
234 model: string;
235 timestamp: number;
236 delta?: string; // Incremental thinking token
237 content: string; // Accumulated thinking content
239```
240​
241Stream chunks represent different types of data in the stream:
242​
243- **Content chunks** - Text content being generated
244- **Thinking chunks** - Model's reasoning process (when supported by the model)
245- **Tool call chunks** - When the model calls a tool
246- **Tool result chunks** - Results from tool execution
247- **Done chunks** - Stream completion
248- **Error chunks** - Stream errors
249​
250### `Tool`
251​
252```typescript
253interface Tool {
254 type: "function";
255 function: {
256 name: string;
257 description: string;
258 parameters: Record<string, any>;
259 };
260 execute?: (args: any) => Promise<any> | any;
261 needsApproval?: boolean;
263```
264​
265## Usage Examples
266​
267```typescript
268import { chat, summarize, generateImage } from "@tanstack/ai";
269import {
270 openaiText,
271 openaiSummarize,
272 openaiImage,
273} from "@tanstack/ai-openai";
274​
275// --- Streaming chat
276const stream = chat({
277 adapter: openaiText("gpt-4o"),
278 messages: [{ role: "user", content: "Hello!" }],
279});
280​
281// --- One-shot chat response (stream: false)
282const response = await chat({
283 adapter: openaiText("gpt-4o"),
284 messages: [{ role: "user", content: "What's the capital of France?" }],
285 stream: false, // Returns a Promise<string> instead of AsyncIterable
286});
287​
288// --- Structured response with outputSchema
289import { z } from "zod";
290const parsed = await chat({
291 adapter: openaiText("gpt-4o"),
292 messages: [{ role: "user", content: "Summarize this text in JSON with keys 'summary' and 'keywords': ... " }],
293 outputSchema: z.object({
294 summary: z.string(),
295 keywords: z.array(z.string()),
296 }),
297});
298​
299// --- Structured response with tools
300import { toolDefinition } from "@tanstack/ai";
301const weatherTool = toolDefinition({
302 name: "getWeather",
303 description: "Get the current weather for a city",
304 inputSchema: z.object({
305 city: z.string().describe("City name"),
306 }),
307}).server(async ({ city }) => {
308 // Implementation that fetches weather info
309 return JSON.stringify({ temperature: 72, condition: "Sunny" });
310});
311​
312const toolResult = await chat({
313 adapter: openaiText("gpt-4o"),
314 messages: [
315 { role: "user", content: "What's the weather in Paris?" }
316 ],
317 tools: [weatherTool],
318 outputSchema: z.object({
319 answer: z.string(),
320 weather: z.object({
321 temperature: z.number(),
322 condition: z.string(),
323 }),
324 }),
325});
326​
327// --- Summarization
328const summary = await summarize({
329 adapter: openaiSummarize("gpt-4o"),
330 text: "Long text to summarize...",
331 maxLength: 100,
332});
333​
334// --- Image generation
335const image = await generateImage({
336 adapter: openaiImage("dall-e-3"),
337 prompt: "A futuristic city skyline at sunset",
338 numberOfImages: 1,
339 size: "1024x1024",
340});
341```
342​
343## Next Steps
344​
345- [Getting Started](../getting-started/quick-start) - Learn the basics
346- [Tools Guide](../guides/tools) - Learn about tools
347- [Adapters](../adapters/openai) - Explore adapter options