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

README.md

491 lines11.0 KB

1# TanStack AI Examples
2​
3This directory contains comprehensive examples demonstrating TanStack AI across multiple languages and frameworks.
4​
5## Quick Start
6​
7Choose an example based on your use case:
8​
9- **Want a full-stack TypeScript app?** → [TanStack Chat (ts-react-chat)](#tanstack-chat-ts-react-chat)
10- **Need a vanilla JS frontend?** → [Vanilla Chat](#vanilla-chat)
11- **Building a Python backend?** → [Python FastAPI Server](#python-fastapi-server)
12- **Building a PHP backend?** → [PHP Slim Framework Server](#php-slim-framework-server)
13- **Multi-User TypeScript chat app?** → [Group Chat (ts-group-chat)](#group-chat-ts-group-chat)
14​
15## TypeScript Examples
16​
17### TanStack Chat (ts-react-chat)
18​
19A full-featured chat application built with the TanStack ecosystem.
20​
21**Tech Stack:**
22​
23- TanStack Start (full-stack React framework)
24- TanStack Router (type-safe routing)
25- TanStack Store (state management)
26- `@tanstack/ai` (AI backend)
27- `@tanstack/ai-react` (React hooks)
28- `@tanstack/ai-client` (headless client)
29​
30**Features:**
31​
32- ✅ Real-time streaming with OpenAI GPT-4o
33- ✅ Automatic tool execution loop
34- ✅ Rich markdown rendering
35- ✅ Conversation management
36- ✅ Modern UI with Tailwind CSS
37​
38**Getting Started:**
39​
40```bash
41cd examples/ts-react-chat
42pnpm install
43cp env.example .env
44# Edit .env and add your OPENAI_API_KEY
45pnpm start
46```
47​
48📖 [Full Documentation](ts-react-chat/README.md)
49​
50---
51​
52### Group Chat (ts-group-chat)
53​
54A real-time multi-user chat application with AI integration, demonstrating WebSocket-based communication and TanStack AI.
55​
56**Tech Stack:**
57​
58- TanStack Start (full-stack React framework)
59- TanStack Router (type-safe routing)
60- Cap'n Web RPC (bidirectional WebSocket RPC)
61- `@tanstack/ai` (AI backend)
62- `@tanstack/ai-anthropic` (Claude adapter)
63- `@tanstack/ai-client` (headless client)
64- `@tanstack/ai-react` (React hooks)
65​
66**Features:**
67​
68- ✅ Real-time multi-user chat with WebSocket
69- ✅ Online presence tracking
70- ✅ AI assistant (Claude) integration with queuing
71- ✅ Message broadcasting to all users
72- ✅ Modern chat UI (iMessage-style)
73- ✅ Username-based authentication (no registration)
74​
75**Getting Started:**
76​
77```bash
78cd examples/ts-group-chat
79pnpm install
80cp .env.example .env
81# Edit .env and add your ANTHROPIC_API_KEY
82pnpm dev
83```
84​
85Open `http://localhost:4000` in multiple browser tabs to test multi-user functionality.
86​
87**Key Concepts:**
88​
89- **WebSocket RPC**: Uses Cap'n Web RPC for type-safe bidirectional communication
90- **AI Queuing**: Claude requests are queued and processed sequentially
91- **Real-time Updates**: Messages and online users update in real-time
92- **Message Broadcasting**: Server broadcasts messages to all connected clients
93​
94📖 [Full Documentation](ts-group-chat/README.md)
95​
96---
97​
98### Vanilla Chat
99​
100A framework-free chat application using pure JavaScript and `@tanstack/ai-client`. Works with both PHP and Python backends.
101​
102**Tech Stack:**
103​
104- Vanilla JavaScript (no frameworks!)
105- `@tanstack/ai-client` (headless client)
106- Vite (dev server)
107- Compatible with PHP Slim or Python FastAPI backends
108​
109**Features:**
110​
111- ✅ Pure vanilla JavaScript
112- ✅ Real-time streaming messages
113- ✅ Beautiful, responsive UI
114- ✅ No framework dependencies
115- ✅ Works with multiple backend languages
116​
117**Getting Started:**
118​
119**Option 1: With Python Backend**
120​
121```bash
122# Start the Python backend first
123cd examples/python-fastapi
124python anthropic-server.py
125​
126# Then start the frontend
127cd examples/vanilla-chat
128pnpm install
129pnpm start
130```
131​
132**Option 2: With PHP Backend**
133​
134```bash
135# Start the PHP backend and UI together
136cd examples/php-slim
137pnpm install
138composer install
139cp env.example .env
140# Edit .env and add your ANTHROPIC_API_KEY
141pnpm start
142```
143​
144Open `http://localhost:3001` (UI) - connects to backend on port 8000
145​
146📖 [Full Documentation](vanilla-chat/README.md)
147​
148---
149​
150## Python Examples
151​
152### Python FastAPI Server
153​
154A FastAPI server that streams AI responses in Server-Sent Events (SSE) format, compatible with TanStack AI clients.
155​
156**Features:**
157​
158- ✅ FastAPI with SSE streaming
159- ✅ Converts Anthropic/OpenAI events to `StreamChunk` format
160- ✅ Compatible with `@tanstack/ai-client`
161- ✅ Tool call support
162- ✅ Type-safe with Pydantic
163​
164**Getting Started:**
165​
166```bash
167cd examples/python-fastapi
168​
169# Create virtual environment
170python3 -m venv venv
171source venv/bin/activate # On Windows: venv\Scripts\activate
172​
173# Install dependencies
174pip install -r requirements.txt
175​
176# Set up environment
177cp env.example .env
178# Edit .env and add your ANTHROPIC_API_KEY or OPENAI_API_KEY
179​
180# Run the server
181python anthropic-server.py # or openai-server.py
182```
183​
184**API Endpoints:**
185​
186- `POST /chat` - Stream chat responses in SSE format
187- `GET /health` - Health check
188​
189**Usage with TypeScript Client:**
190​
191```typescript
192import { ChatClient, fetchServerSentEvents } from '@tanstack/ai-client'
193​
194const client = new ChatClient({
195 connection: fetchServerSentEvents('http://localhost:8000/chat'),
196})
197​
198await client.sendMessage('Hello!')
199```
200​
201📖 [Full Documentation](python-fastapi/README.md)
202​
203---
204​
205## PHP Examples
206​
207### PHP Slim Framework Server
208​
209A PHP Slim Framework server that streams AI responses in SSE format, with support for both Anthropic and OpenAI.
210​
211**Features:**
212​
213- ✅ Slim Framework with SSE streaming
214- ✅ Converts Anthropic/OpenAI events to `StreamChunk` format
215- ✅ Compatible with `@tanstack/ai-client`
216- ✅ Tool call support
217- ✅ PHP 8.1+ with type safety
218​
219**Getting Started:**
220​
221```bash
222cd examples/php-slim
223​
224# Install dependencies
225composer install
226​
227# Set up environment
228cp env.example .env
229# Edit .env and add your ANTHROPIC_API_KEY and/or OPENAI_API_KEY
230​
231# Run the server
232composer start-anthropic # Runs on port 8000
233# or
234composer start-openai # Runs on port 8001
235```
236​
237**API Endpoints:**
238​
239- `POST /chat` - Stream chat responses in SSE format
240- `GET /health` - Health check
241​
242**Usage with TypeScript Client:**
243​
244```typescript
245import { ChatClient, fetchServerSentEvents } from '@tanstack/ai-client'
246​
247const client = new ChatClient({
248 connection: fetchServerSentEvents('http://localhost:8000/chat'),
249})
250​
251await client.sendMessage('Hello!')
252```
253​
254📖 [Full Documentation](php-slim/README.md)
255​
256---
257​
258## Architecture Patterns
259​
260### Full-Stack TypeScript
261​
262Use TanStack AI end-to-end in TypeScript:
263​
264```
265Frontend (React)
266 ↓ (useChat hook)
267@tanstack/ai-react
268 ↓ (ChatClient)
269@tanstack/ai-client
270 ↓ (SSE/HTTP)
271Backend (TanStack Start API Route)
272 ↓ (chat() function)
273@tanstack/ai
274 ↓ (adapter)
275AI Provider (OpenAI/Anthropic/etc.)
276```
277​
278**Example:** [TanStack Chat (ts-react-chat)](ts-react-chat/README.md)
279​
280### Multi-Language Backend
281​
282Use Python or PHP for the backend, TypeScript for the frontend:
283​
284```
285Frontend (Vanilla JS/React/Vue/etc.)
286 ↓ (ChatClient)
287@tanstack/ai-client
288 ↓ (SSE/HTTP)
289Backend (Python FastAPI or PHP Slim)
290 ↓ (tanstack-ai or tanstack/ai)
291Stream Conversion & Message Formatting
292 ↓ (provider SDK)
293AI Provider (OpenAI/Anthropic/etc.)
294```
295​
296**Examples:**
297​
298- [Python FastAPI](python-fastapi/README.md) + [Vanilla Chat](vanilla-chat/README.md)
299- [PHP Slim](php-slim/README.md) + [Vanilla Chat](vanilla-chat/README.md)
300- [PHP Slim](php-slim/README.md) + any frontend with `@tanstack/ai-client`
301​
302## Common Patterns
303​
304### Server-Sent Events (SSE) Streaming
305​
306All examples use SSE for real-time streaming:
307​
308**Backend (TypeScript):**
309​
310```typescript
311import { chat, toStreamResponse } from '@tanstack/ai'
312import { openaiText } from '@tanstack/ai-openai'
313​
314const stream = chat({
315 adapter: openaiText(),
316 model: 'gpt-4o',
317 messages,
318})
319​
320return toStreamResponse(stream)
321```
322​
323**Backend (Python):**
324​
325```python
326from tanstack_ai import StreamChunkConverter, format_sse_chunk
327​
328async for event in anthropic_stream:
329 chunks = await converter.convert_event(event)
330 for chunk in chunks:
331 yield format_sse_chunk(chunk)
332```
333​
334**Backend (PHP):**
335​
336```php
337use TanStack\AI\StreamChunkConverter;
338use TanStack\AI\SSEFormatter;
339​
340foreach ($anthropicStream as $event) {
341 $chunks = $converter->convertEvent($event);
342 foreach ($chunks as $chunk) {
343 echo SSEFormatter::formatChunk($chunk);
344 }
346```
347​
348**Frontend:**
349​
350```typescript
351import { ChatClient, fetchServerSentEvents } from '@tanstack/ai-client'
352​
353const client = new ChatClient({
354 connection: fetchServerSentEvents('/api/chat'),
355})
356```
357​
358### Automatic Tool Execution
359​
360The TypeScript backend (`@tanstack/ai`) automatically handles tool execution:
361​
362```typescript
363import { chat, toolDefinition } from '@tanstack/ai'
364import { z } from 'zod'
365​
366// Step 1: Define the tool schema
367const weatherToolDef = toolDefinition({
368 name: 'getWeather',
369 description: 'Get weather for a location',
370 inputSchema: z.object({
371 location: z.string().describe('The city and state, e.g. San Francisco, CA'),
372 }),
373 outputSchema: z.object({
374 temp: z.number(),
375 condition: z.string(),
376 }),
377})
378​
379// Step 2: Create server implementation
380const weatherTool = weatherToolDef.server(async ({ location }) => {
381 // This is called automatically by the SDK
382 return { temp: 72, condition: 'sunny' }
383})
384​
385const stream = chat({
386 adapter: openaiText(),
387 model: 'gpt-4o',
388 messages,
389 tools: [weatherTool], // SDK executes these automatically
390})
391```
392​
393Clients receive:
394​
395- `content` chunks - text from the model
396- `tool_call` chunks - when the model calls a tool
397- `tool_result` chunks - results from tool execution
398- `done` chunk - conversation complete
399​
400---
401​
402## Development Tips
403​
404### Running Multiple Examples
405​
406You can run backend and frontend examples together:
407​
408```bash
409# Option 1: Python backend + Vanilla Chat frontend
410# Terminal 1: Start Python backend
411cd examples/python-fastapi
412python anthropic-server.py
413​
414# Terminal 2: Start vanilla frontend
415cd examples/vanilla-chat
416pnpm start
417​
418# Option 2: PHP backend + Vanilla Chat frontend (runs together)
419cd examples/php-slim
420pnpm start # Starts both PHP server and vanilla-chat UI
421​
422# Option 3: Full-stack TypeScript
423cd examples/ts-react-chat
424pnpm start
425```
426​
427### Environment Variables
428​
429Each example has an `env.example` file. Copy it to `.env` and add your API keys:
430​
431```bash
432# TypeScript examples
433OPENAI_API_KEY=sk-...
434ANTHROPIC_API_KEY=sk-ant-...
435​
436# Python examples
437ANTHROPIC_API_KEY=sk-ant-...
438OPENAI_API_KEY=sk-...
439​
440# PHP examples
441ANTHROPIC_API_KEY=sk-ant-...
442OPENAI_API_KEY=sk-...
443```
444​
445### Building for Production
446​
447**TypeScript:**
448​
449```bash
450pnpm build
451```
452​
453**Python:**
454​
455```bash
456# Use a production ASGI server
457uvicorn anthropic-server:app --host 0.0.0.0 --port 8000
458```
459​
460**PHP:**
461​
462```bash
463# Use a production web server (Apache, Nginx, etc.)
464# See php-slim/README.md for deployment details
465```
466​
467---
468​
469## Contributing
470​
471When adding new examples:
472​
4731. **Create a README.md** with setup instructions
4742. **Add an env.example** file with required environment variables
4753. **Document the tech stack** and key features
4764. **Include usage examples** with code snippets
4775. **Update this README** to list your example
478​
479---
480​
481## Learn More
482​
483- 📖 [Main README](../README.md) - Project overview
484- 📖 [Documentation](../docs/) - Comprehensive guides
485- 📖 [TypeScript Packages](../packages/typescript/) - Core libraries
486- 📖 [Python Package](../packages/python/tanstack-ai/) - Python utilities
487- 📖 [PHP Package](../packages/php/tanstack-ai/) - PHP utilities
488​
489---
490​
491Built with ❤️ by the TanStack community