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

README.md

271 lines6.7 KB

1# TanStack AI Python SDK
2​
3Python SDK for building AI applications with streaming, tool calling, and agentic workflows. Provides adapters for AI providers (Anthropic, OpenAI, etc.) and utilities for message formatting and SSE streaming.
4​
5## Features
6​
7- 🤖 **Agentic Workflows** - Automatic tool execution loops with customizable strategies
8- 🔧 **Tool Calling** - Define and execute tools with JSON Schema validation
9- 📡 **Streaming** - Full support for streaming chat completions
10- 🔌 **Multiple Adapters** - Support for Anthropic (Claude), with more providers coming soon
11- 🛡️ **Type Safety** - Comprehensive type hints using TypedDict and dataclasses
12- 📋 **Protocol Compliant** - Follows the TanStack AI StreamChunk protocol
13​
14## Installation
15​
16```bash
17pip install tanstack-ai anthropic
18```
19​
20Or install from source:
21​
22```bash
23cd packages/python/tanstack-ai
24pip install -e .
25```
26​
27## Quick Start
28​
29### Basic Chat
30​
31```python
32import asyncio
33from tanstack_ai import AnthropicAdapter, AIAdapterConfig, chat
34​
35async def main():
36 adapter = AnthropicAdapter(
37 AIAdapterConfig(api_key="your-api-key")
38 )
39​
40 async for chunk in chat(
41 adapter=adapter,
42 model="claude-3-5-sonnet-20241022",
43 messages=[{"role": "user", "content": "Hello!"}],
44 ):
45 if chunk["type"] == "content":
46 print(chunk["delta"], end="", flush=True)
47​
48asyncio.run(main())
49```
50​
51### Chat with Tools (Agentic Flow)
52​
53```python
54from tanstack_ai import chat, tool, max_iterations
55​
56# Define a tool
57weather_tool = tool(
58 name="get_weather",
59 description="Get the current weather for a location",
60 input_schema={
61 "type": "object",
62 "properties": {
63 "location": {"type": "string"},
64 "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
65 },
66 "required": ["location"],
67 },
68 execute=lambda args: {
69 "temperature": 72,
70 "conditions": "sunny",
71 "location": args["location"],
72 },
74​
75# Use the tool in chat
76async for chunk in chat(
77 adapter=adapter,
78 model="claude-3-5-sonnet-20241022",
79 messages=[
80 {"role": "user", "content": "What's the weather in San Francisco?"}
81 ],
82 tools=[weather_tool],
83 agent_loop_strategy=max_iterations(5),
84):
85 if chunk["type"] == "content":
86 print(chunk["delta"], end="", flush=True)
87 elif chunk["type"] == "tool_call":
88 print(f"\n[Calling: {chunk['toolCall']['function']['name']}]")
89```
90​
91See `example_usage.py` and `AGENTIC_FEATURES.md` for more examples.
92​
93## Usage
94​
95### StreamChunkConverter
96​
97Convert provider streaming events to TanStack AI StreamChunk format:
98​
99```python
100from tanstack_ai import StreamChunkConverter
101​
102converter = StreamChunkConverter(model="claude-3-haiku-20240307", provider="anthropic")
103​
104async for event in anthropic_stream:
105 chunks = await converter.convert_event(event)
106 for chunk in chunks:
107 # Process StreamChunk
108 pass
109```
110​
111### Message Formatters
112​
113Convert TanStack AI messages to provider formats:
114​
115```python
116from tanstack_ai import format_messages_for_anthropic, format_messages_for_openai
117​
118# Convert to Anthropic format
119system_message, anthropic_messages = format_messages_for_anthropic(messages)
120​
121# Convert to OpenAI format
122openai_messages = format_messages_for_openai(messages)
123```
124​
125### SSE Formatting Utilities
126​
127Format StreamChunk dictionaries as Server-Sent Events (SSE) for HTTP responses:
128​
129```python
130from tanstack_ai import format_sse_chunk, format_sse_done, format_sse_error
131​
132# Format a chunk
133sse_data = format_sse_chunk(chunk) # Returns "data: {...}\n\n"
134​
135# Format completion marker
136sse_done = format_sse_done() # Returns "data: [DONE]\n\n"
137​
138# Format an error
139sse_error = format_sse_error(exception) # Returns formatted error chunk
140```
141​
142Example usage in FastAPI:
143​
144```python
145async def generate_stream():
146 async for event in stream:
147 chunks = await converter.convert_event(event)
148 for chunk in chunks:
149 yield format_sse_chunk(chunk)
150 yield format_sse_done()
151```
152​
153## Core API
154​
155### chat()
156​
157Stream chat completions with automatic tool execution:
158​
159```python
160async for chunk in chat(
161 adapter=adapter, # AI adapter instance
162 model="model-name", # Model identifier
163 messages=[...], # Conversation messages
164 tools=[...], # Optional tools (auto-executed)
165 agent_loop_strategy=..., # Optional loop control strategy
166 options={...}, # Common options (temperature, etc.)
167 provider_options={...}, # Provider-specific options
168):
169 # Handle StreamChunk
170 pass
171```
172​
173### tool()
174​
175Define a tool with JSON Schema:
176​
177```python
178my_tool = tool(
179 name="tool_name",
180 description="What the tool does",
181 input_schema={...}, # JSON Schema for inputs
182 execute=lambda args: ..., # Function to execute
183 needs_approval=False, # Require user approval
185```
186​
187### Agent Loop Strategies
188​
189Control how the agent loop behaves:
190​
191```python
192from tanstack_ai import (
193 max_iterations, # Limit iterations
194 until_finish_reason, # Stop on specific reasons
195 combine_strategies, # Combine multiple strategies
197​
198# Max 10 iterations
199strategy = max_iterations(10)
200​
201# Stop on specific finish reasons
202strategy = until_finish_reason(["stop", "length"])
203​
204# Custom logic
205strategy = lambda state: len(state["messages"]) < 50
206​
207# Combine strategies
208strategy = combine_strategies([
209 max_iterations(10),
210 until_finish_reason(["stop"]),
211])
212```
213​
214## Adapters
215​
216### AnthropicAdapter
217​
218```python
219from tanstack_ai import AnthropicAdapter, AIAdapterConfig
220​
221adapter = AnthropicAdapter(
222 AIAdapterConfig(
223 api_key="your-api-key",
224 base_url=None, # Optional custom base URL
225 timeout=None, # Optional timeout
226 max_retries=None, # Optional max retries
227 )
229```
230​
231**Supported Models:**
232​
233- claude-3-5-sonnet-20241022
234- claude-3-5-sonnet-20240620
235- claude-3-5-haiku-20241022
236- claude-3-opus-20240229
237- claude-3-sonnet-20240229
238- claude-3-haiku-20240307
239​
240## StreamChunk Protocol
241​
242All streaming responses emit `StreamChunk` objects with these types:
243​
244- `content` - Text content being generated
245- `thinking` - Model's reasoning process (when supported)
246- `tool_call` - Model calling a tool
247- `tool_result` - Result from tool execution
248- `tool-input-available` - Tool inputs ready for client execution
249- `approval-requested` - Tool requires approval
250- `done` - Stream completion
251- `error` - Error occurred
252​
253See `docs/protocol/chunk-definitions.md` for detailed specifications.
254​
255## Supported Providers
256​
257- ✅ Anthropic (Claude models)
258- 🔄 OpenAI (coming soon)
259- 🔄 Gemini (coming soon)
260- 🔄 Ollama (coming soon)
261​
262## Examples
263​
264See these files for complete examples:
265​
266- `example_usage.py` - Basic usage examples
267- `AGENTIC_FEATURES.md` - Detailed documentation of agentic features
268​
269## License
270​
271MIT