Open History to see the last commit
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 },
73)
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
184)
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
196)
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 )
228)
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