chore: import upstream snapshot with attribution

python/assistant-ui-sync-server-api/README.md

@@ -0,0 +1,224 @@
+# assistant-ui Sync Server API
+
+A Python client library for interacting with assistant-ui sync server backends, providing the same API structure as the JavaScript/TypeScript `useChatRuntime`.
+
+## Installation
+
+```bash
+pip install assistant-ui-sync-server-api
+```
+
+Or using uv:
+
+```bash
+uv add assistant-ui-sync-server-api
+```
+
+## Usage
+
+### Basic Example
+
+```python
+import asyncio
+from assistant_ui import AssistantClient
+
+# Create a client
+client = AssistantClient(base_url="https://api.example.com")
+
+# Create messages
+messages = [
+    {
+        "role": "user",
+        "content": [{"type": "text", "text": "Hello, how are you?"}]
+    }
+]
+
+# Send a chat request to a specific thread
+async def main():
+    thread = client.threads("thread-123")
+    response = await thread.chat(
+        messages=messages,
+        system="You are a helpful assistant."
+    )
+    print(response.json())
+    await client.close()
+
+asyncio.run(main())
+```
+
+### Using Context Managers
+
+```python
+# Async context manager
+async with AssistantClient(base_url="https://api.example.com") as client:
+    thread = client.threads("thread-123")
+    response = await thread.chat(messages=messages)
+
+# Sync context manager
+with AssistantClient(base_url="https://api.example.com") as client:
+    thread = client.threads("thread-123")
+    response = thread.chat_sync(messages=messages)
+```
+
+### Authentication
+
+```python
+# Static headers
+client = AssistantClient(
+    base_url="https://api.example.com",
+    headers={"Authorization": "Bearer your-token"}
+)
+
+# Dynamic headers (async)
+async def get_auth_headers():
+    token = await fetch_token()
+    return {"Authorization": f"Bearer {token}"}
+
+client = AssistantClient(
+    base_url="https://api.example.com",
+    headers=get_auth_headers
+)
+```
+
+### Using Tools
+
+```python
+tools = {
+    "get_weather": {
+        "description": "Get the current weather for a location",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "location": {"type": "string"},
+                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
+            },
+            "required": ["location"]
+        }
+    }
+}
+
+thread = client.threads("thread-123")
+response = await thread.chat(
+    messages=messages,
+    tools=tools
+)
+```
+
+### Canceling Operations
+
+```python
+thread = client.threads("thread-123")
+
+# Start a long-running chat
+chat_task = asyncio.create_task(thread.chat(messages=messages))
+
+# Cancel it
+await thread.cancel()
+chat_task.cancel()
+```
+
+### Message Types
+
+The package supports various message types matching the assistant-ui format:
+
+```python
+from assistant_ui.types import Message
+
+# Text message
+text_message: Message = {
+    "role": "user",
+    "content": [{"type": "text", "text": "Hello!"}]
+}
+
+# Image message
+image_message: Message = {
+    "role": "user",
+    "content": [
+        {"type": "text", "text": "What's in this image?"},
+        {"type": "image", "image": "https://example.com/image.jpg"}
+    ]
+}
+
+# File message
+file_message: Message = {
+    "role": "user",
+    "content": [
+        {"type": "file", "data": "https://example.com/file.pdf", "mimeType": "application/pdf"}
+    ]
+}
+
+# Assistant message with tool calls
+assistant_message: Message = {
+    "role": "assistant",
+    "content": [
+        {"type": "text", "text": "I'll help you with that."},
+        {
+            "type": "tool-call",
+            "toolCallId": "call-123",
+            "toolName": "get_weather",
+            "args": {"location": "San Francisco"}
+        }
+    ]
+}
+
+# Tool result message
+tool_message: Message = {
+    "role": "tool",
+    "content": [
+        {
+            "type": "tool-result",
+            "toolCallId": "call-123",
+            "toolName": "get_weather",
+            "result": {"temperature": 72, "condition": "sunny"},
+            "isError": False
+        }
+    ]
+}
+```
+
+## API Reference
+
+### `AssistantClient`
+
+Main client for interacting with assistant-ui backends.
+
+**Constructor:**
+
+```python
+AssistantClient(
+    base_url: str,
+    headers: Optional[Dict[str, str] | Callable] = None,
+    timeout: Optional[float] = None,
+    **kwargs
+)
+```
+
+**Methods:**
+
+- `threads(thread_id: str) -> ThreadClient`: Get a ThreadClient for a specific thread
+- `close()`: Close the async client
+- `close_sync()`: Close the sync client
+
+### `ThreadClient`
+
+Client for interacting with a specific thread.
+
+**Methods:**
+
+- `chat(messages, system=None, tools=None, **kwargs)`: Send an async chat request
+- `chat_sync(messages, system=None, tools=None, **kwargs)`: Send a sync chat request
+- `cancel()`: Cancel the current async operation
+- `cancel_sync()`: Cancel the current sync operation
+
+## Type Definitions
+
+The package includes TypedDict definitions for all message types and configuration options, providing full type hints for better IDE support and type checking.
+
+## Development
+
+This package is part of the assistant-ui monorepo. To contribute:
+
+1. Clone the main repository
+2. Navigate to `python/assistant-ui`
+3. Install dependencies with `uv sync`
+4. Run tests with `uv run pytest`