Python: feat: Add ChatKit integration with a sample application (#1273)

* feat: Add ChatKit integration with a new frontend application - Created a new frontend application using React and Vite for the ChatKit integration. - Added essential files including package.json, vite.config.ts, and Tailwind CSS configuration. - Implemented core components: App, Home, ChatKitPanel, ThemeToggle, and hooks for color scheme management. - Established SQLite-based store implementation for ChatKit data persistence in store.py. - Integrated theme toggling functionality for light and dark modes. - Set up ESLint and TypeScript configurations for better development experience. * git ignore * fix mypy * add mising file * minimal frontend for chatkit sample * update ignore files * version * set python version lowerbound on chatkit * update project settings for chatkit * update setup * update setup * update setup * update setup * weather widget * add select city widget sample * remove widget helper * update chatkit to include file attachments and cover more thread item types * update readme with mermaid diagram * update diagram * update instructions * update chatkit dependency * fix converter imports * move to demos/ * move to demos/ -- rename references * support multiple session instead of using global variable in sample * support chunk streaming * fix tests * Update python/samples/demos/chatkit-integration/store.py Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com> * use local host --------- Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2025-11-04 18:11:40 -08:00
parent bbde248839
commit 0c862e97a6
33 changed files with 4972 additions and 2 deletions
@@ -0,0 +1,4 @@
+*.db
+*.db-shm
+*.db-wal
+uploads/
@@ -0,0 +1,268 @@
+# ChatKit Integration Sample with Weather Agent and Image Analysis
+
+This sample demonstrates how to integrate Microsoft Agent Framework with OpenAI ChatKit. It provides a complete implementation of a weather assistant with interactive widget visualization, image analysis, and file upload support.
+
+**Features:**
+
+- Weather information with interactive widgets
+- Image analysis using vision models
+- Current time queries
+- File upload with attachment storage
+- Chat interface with streaming responses
+- City selector widget with one-click weather
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph Frontend["React Frontend (ChatKit UI)"]
+        UI[ChatKit Components]
+        Upload[File Upload]
+    end
+
+    subgraph Backend["FastAPI Server"]
+        FastAPI[FastAPI Endpoints]
+
+        subgraph ChatKit["WeatherChatKitServer"]
+            Respond[respond method]
+            Action[action method]
+        end
+
+        subgraph Stores["Data & Storage Layer"]
+            SQLite[SQLiteStore<br/>Store Protocol]
+            AttStore[FileBasedAttachmentStore<br/>AttachmentStore Protocol]
+            DB[(SQLite DB<br/>chatkit_demo.db)]
+            Files[/uploads directory/]
+        end
+
+        subgraph Integration["Agent Framework Integration"]
+            Converter[ThreadItemConverter]
+            Streamer[stream_agent_response]
+            Agent[ChatAgent]
+        end
+
+        Widgets[Widget Rendering<br/>render_weather_widget<br/>render_city_selector_widget]
+    end
+
+    subgraph Azure["Azure AI"]
+        Foundry[GPT-5<br/>with Vision]
+    end
+
+    UI -->|HTTP POST /chatkit| FastAPI
+    Upload -->|HTTP POST /upload/id| FastAPI
+
+    FastAPI --> ChatKit
+
+    ChatKit -->|save/load threads| SQLite
+    ChatKit -->|save/load attachments| AttStore
+    ChatKit -->|convert messages| Converter
+
+    SQLite -.->|persist| DB
+    AttStore -.->|save files| Files
+    AttStore -.->|save metadata| SQLite
+
+    Converter -->|ChatMessage array| Agent
+    Agent -->|AgentRunResponseUpdate| Streamer
+    Streamer -->|ThreadStreamEvent| ChatKit
+
+    ChatKit --> Widgets
+    Widgets -->|WidgetItem| ChatKit
+
+    Agent <-->|Chat Completions API| Foundry
+
+    ChatKit -->|ThreadStreamEvent| FastAPI
+    FastAPI -->|SSE Stream| UI
+
+    style ChatKit fill:#e1f5ff
+    style Stores fill:#fff4e1
+    style Integration fill:#f0e1ff
+    style Azure fill:#e1ffe1
+```
+
+### Server Implementation
+
+The sample implements a ChatKit server using the `ChatKitServer` base class from the `chatkit` package:
+
+**Core Components:**
+
+- **`WeatherChatKitServer`**: Custom ChatKit server implementation that:
+
+  - Extends `ChatKitServer[dict[str, Any]]`
+  - Uses Agent Framework's `ChatAgent` with Azure OpenAI
+  - Converts ChatKit messages to Agent Framework format using `ThreadItemConverter`
+  - Streams responses back to ChatKit using `stream_agent_response`
+  - Creates and streams interactive widgets after agent responses
+
+- **`SQLiteStore`**: Data persistence layer that:
+
+  - Implements the `Store[dict[str, Any]]` protocol from ChatKit
+  - Persists threads, messages, and attachment metadata in SQLite
+  - Provides thread management and item history
+  - Stores attachment metadata for the upload lifecycle
+
+- **`FileBasedAttachmentStore`**: File storage implementation that:
+  - Implements the `AttachmentStore[dict[str, Any]]` protocol from ChatKit
+  - Stores uploaded files on the local filesystem (in `./uploads` directory)
+  - Generates upload URLs for two-phase file upload
+  - Saves attachment metadata to the data store for upload tracking
+  - Provides preview URLs for images
+
+**Key Integration Points:**
+
+```python
+# Converting ChatKit messages to Agent Framework
+converter = ThreadItemConverter(
+    attachment_data_fetcher=self._fetch_attachment_data
+)
+agent_messages = await converter.to_agent_input(user_message_item)
+
+# Running agent and streaming back to ChatKit
+async for event in stream_agent_response(
+    self.weather_agent.run_stream(agent_messages),
+    thread_id=thread.id,
+):
+    yield event
+
+# Streaming widgets
+widget = render_weather_widget(weather_data)
+async for event in stream_widget(thread_id=thread.id, widget=widget):
+    yield event
+```
+
+## Installation and Setup
+
+### Prerequisites
+
+- Python 3.10+
+- Node.js 18.18+ and npm 9+
+- Azure OpenAI service configured
+- Azure CLI for authentication (`az login`)
+
+### Backend Setup
+
+1. **Install Python packages:**
+
+```bash
+cd python/samples/demos/chatkit-integration
+pip install agent-framework-chatkit fastapi uvicorn azure-identity
+```
+
+2. **Configure Azure OpenAI:**
+
+```bash
+export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+export AZURE_OPENAI_API_VERSION="2024-06-01"
+export AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4o"
+```
+
+3. **Authenticate with Azure:**
+
+```bash
+az login
+```
+
+### Frontend Setup
+
+Install the Node.js dependencies:
+
+```bash
+cd frontend
+npm install
+```
+
+## How to Run
+
+### Start the Backend Server
+
+From the `chatkit-integration` directory:
+
+```bash
+python app.py
+```
+
+Or with auto-reload for development:
+
+```bash
+uvicorn app:app --host 127.0.0.1 --port 8001 --reload
+```
+
+The backend will start on `http://localhost:8001`
+
+### Start the Frontend Development Server
+
+In a new terminal, from the `frontend` directory:
+
+```bash
+npm run dev
+```
+
+The frontend will start on `http://localhost:5171`
+
+### Access the Application
+
+Open your browser and navigate to:
+
+```
+http://localhost:5171
+```
+
+You can now:
+
+- Ask about weather in any location (weather widgets display automatically)
+- Upload images for analysis using the attachment button
+- Get the current time
+- Ask to see available cities and click city buttons for instant weather
+
+### Project Structure
+
+```
+chatkit-integration/
+├── app.py                    # FastAPI backend with ChatKitServer implementation
+├── store.py                  # SQLiteStore implementation
+├── attachment_store.py       # FileBasedAttachmentStore implementation
+├── weather_widget.py         # Widget rendering functions
+├── chatkit_demo.db          # SQLite database (auto-created)
+├── uploads/                  # Uploaded files directory (auto-created)
+└── frontend/
+    ├── package.json
+    ├── vite.config.ts
+    ├── index.html
+    └── src/
+        ├── main.tsx
+        └── App.tsx           # ChatKit UI integration
+```
+
+### Configuration
+
+You can customize the application by editing constants at the top of `app.py`:
+
+```python
+# Server configuration
+SERVER_HOST = "127.0.0.1"  # Bind to localhost only for security (local dev)
+SERVER_PORT = 8001
+SERVER_BASE_URL = f"http://localhost:{SERVER_PORT}"
+
+# Database configuration
+DATABASE_PATH = "chatkit_demo.db"
+
+# File storage configuration
+UPLOADS_DIRECTORY = "./uploads"
+
+# User context
+DEFAULT_USER_ID = "demo_user"
+```
+
+### Sample Conversations
+
+Try these example queries:
+
+- "What's the weather like in Tokyo?"
+- "Show me available cities" (displays interactive city selector)
+- "What's the current time?"
+- Upload an image and ask "What do you see in this image?"
+
+## Learn More
+
+- [Agent Framework Documentation](https://aka.ms/agent-framework)
+- [ChatKit Documentation](https://platform.openai.com/docs/guides/chatkit)
+- [Azure OpenAI Documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/)
@@ -0,0 +1 @@
+# Copyright (c) Microsoft. All rights reserved.
@@ -0,0 +1,538 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+ChatKit Integration Sample with Weather Agent and Image Analysis
+
+This sample demonstrates how to integrate Microsoft Agent Framework with OpenAI ChatKit
+using a weather tool with widget visualization, image analysis, and Azure OpenAI. It shows
+a complete ChatKit server implementation using Agent Framework agents with proper FastAPI
+setup, interactive weather widgets, and vision capabilities for analyzing uploaded images.
+"""
+
+import logging
+from collections.abc import AsyncIterator, Callable
+from datetime import datetime, timezone
+from random import randint
+from typing import Annotated, Any
+
+import uvicorn
+from azure.identity import AzureCliCredential
+from fastapi import FastAPI, File, Request, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse, Response, StreamingResponse
+from pydantic import Field
+
+# ============================================================================
+# Configuration Constants
+# ============================================================================
+
+# Server configuration
+SERVER_HOST = "127.0.0.1"  # Bind to localhost only for security (local dev)
+SERVER_PORT = 8001
+SERVER_BASE_URL = f"http://localhost:{SERVER_PORT}"
+
+# Database configuration
+DATABASE_PATH = "chatkit_demo.db"
+
+# File storage configuration
+UPLOADS_DIRECTORY = "./uploads"
+
+# User context
+DEFAULT_USER_ID = "demo_user"
+
+# Logging configuration
+LOG_LEVEL = logging.INFO
+LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+LOG_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+# ============================================================================
+# Logging Setup
+# ============================================================================
+
+logging.basicConfig(
+    level=LOG_LEVEL,
+    format=LOG_FORMAT,
+    datefmt=LOG_DATE_FORMAT,
+)
+logger = logging.getLogger(__name__)
+
+# Agent Framework imports
+from agent_framework import AgentRunResponseUpdate, ChatAgent, ChatMessage, FunctionResultContent, Role
+from agent_framework.azure import AzureOpenAIChatClient
+
+# Agent Framework ChatKit integration
+from agent_framework_chatkit import ThreadItemConverter, stream_agent_response
+
+# Local imports
+from attachment_store import FileBasedAttachmentStore
+
+# ChatKit imports
+from chatkit.actions import Action
+from chatkit.server import ChatKitServer
+from chatkit.store import StoreItemType, default_generate_id
+from chatkit.types import (
+    ThreadItemDoneEvent,
+    ThreadMetadata,
+    ThreadStreamEvent,
+    UserMessageItem,
+    WidgetItem,
+)
+from chatkit.widgets import WidgetRoot
+from store import SQLiteStore
+from weather_widget import (
+    WeatherData,
+    city_selector_copy_text,
+    render_city_selector_widget,
+    render_weather_widget,
+    weather_widget_copy_text,
+)
+
+
+class WeatherResponse(str):
+    """A string response that also carries WeatherData for widget creation."""
+
+    def __new__(cls, text: str, weather_data: WeatherData):
+        instance = super().__new__(cls, text)
+        instance.weather_data = weather_data  # type: ignore
+        return instance
+
+
+async def stream_widget(
+    thread_id: str,
+    widget: WidgetRoot,
+    copy_text: str | None = None,
+    generate_id: Callable[[StoreItemType], str] = default_generate_id,
+) -> AsyncIterator[ThreadStreamEvent]:
+    """Stream a ChatKit widget as a ThreadStreamEvent.
+
+    This helper function creates a ChatKit widget item and yields it as a
+    ThreadItemDoneEvent that can be consumed by the ChatKit UI.
+
+    Args:
+        thread_id: The ChatKit thread ID for the conversation.
+        widget: The ChatKit widget to display.
+        copy_text: Optional text representation of the widget for copy/paste.
+        generate_id: Optional function to generate IDs for ChatKit items.
+
+    Yields:
+        ThreadStreamEvent: ChatKit event containing the widget.
+    """
+    item_id = generate_id("message")
+
+    widget_item = WidgetItem(
+        id=item_id,
+        thread_id=thread_id,
+        created_at=datetime.now(),
+        widget=widget,
+        copy_text=copy_text,
+    )
+
+    yield ThreadItemDoneEvent(type="thread.item.done", item=widget_item)
+
+
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location.
+
+    Returns a string description with embedded WeatherData for widget creation.
+    """
+    logger.info(f"Fetching weather for location: {location}")
+
+    conditions = ["sunny", "cloudy", "rainy", "stormy", "snowy", "foggy"]
+    temperature = randint(-5, 35)
+    condition = conditions[randint(0, len(conditions) - 1)]
+
+    # Add some realistic details
+    humidity = randint(30, 90)
+    wind_speed = randint(5, 25)
+
+    weather_data = WeatherData(
+        location=location,
+        condition=condition,
+        temperature=temperature,
+        humidity=humidity,
+        wind_speed=wind_speed,
+    )
+
+    logger.debug(f"Weather data generated: {condition}, {temperature}°C, {humidity}% humidity, {wind_speed} km/h wind")
+
+    # Return a WeatherResponse that is both a string (for the LLM) and carries structured data
+    text = (
+        f"Weather in {location}:\n"
+        f"• Condition: {condition.title()}\n"
+        f"• Temperature: {temperature}°C\n"
+        f"• Humidity: {humidity}%\n"
+        f"• Wind: {wind_speed} km/h"
+    )
+    return WeatherResponse(text, weather_data)
+
+
+def get_time() -> str:
+    """Get the current UTC time."""
+    current_time = datetime.now(timezone.utc)
+    logger.info("Getting current UTC time")
+    return f"Current UTC time: {current_time.strftime('%Y-%m-%d %H:%M:%S')} UTC"
+
+
+def show_city_selector() -> str:
+    """Show an interactive city selector widget to the user.
+
+    This function triggers the display of a widget that allows users
+    to select from popular cities to get weather information.
+
+    Returns a special marker string that will be detected to show the widget.
+    """
+    logger.info("Activating city selector widget")
+    return "__SHOW_CITY_SELECTOR__"
+
+
+class WeatherChatKitServer(ChatKitServer[dict[str, Any]]):
+    """ChatKit server implementation using Agent Framework.
+
+    This server integrates Agent Framework agents with ChatKit's server protocol,
+    providing weather information with interactive widgets and time queries through Azure OpenAI.
+    """
+
+    def __init__(self, data_store: SQLiteStore, attachment_store: FileBasedAttachmentStore):
+        super().__init__(data_store, attachment_store)
+
+        logger.info("Initializing WeatherChatKitServer")
+
+        # Create Agent Framework agent with Azure OpenAI
+        # For authentication, run `az login` command in terminal
+        try:
+            self.weather_agent = ChatAgent(
+                chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+                instructions=(
+                    "You are a helpful weather assistant with image analysis capabilities. "
+                    "You can provide weather information for any location, tell the current time, "
+                    "and analyze images that users upload. Be friendly and informative in your responses.\n\n"
+                    "If a user asks to see a list of cities or wants to choose from available cities, "
+                    "use the show_city_selector tool to display an interactive city selector.\n\n"
+                    "When users upload images, you will automatically receive them and can analyze their content. "
+                    "Describe what you see in detail and be helpful in answering questions about the images."
+                ),
+                tools=[get_weather, get_time, show_city_selector],
+            )
+            logger.info("Weather agent initialized successfully with Azure OpenAI")
+        except Exception as e:
+            logger.error(f"Failed to initialize weather agent: {e}")
+            raise
+
+        # Create ThreadItemConverter with attachment data fetcher
+        self.converter = ThreadItemConverter(
+            attachment_data_fetcher=self._fetch_attachment_data,
+        )
+
+        logger.info("WeatherChatKitServer initialized")
+
+    async def _fetch_attachment_data(self, attachment_id: str) -> bytes:
+        """Fetch attachment binary data for the converter.
+
+        Args:
+            attachment_id: The ID of the attachment to fetch.
+
+        Returns:
+            The binary data of the attachment.
+        """
+        return await attachment_store.read_attachment_bytes(attachment_id)
+
+    async def respond(
+        self,
+        thread: ThreadMetadata,
+        input_user_message: UserMessageItem | None,
+        context: dict[str, Any],
+    ) -> AsyncIterator[ThreadStreamEvent]:
+        """Handle incoming user messages and generate responses.
+
+        This method converts ChatKit messages to Agent Framework format using ThreadItemConverter,
+        runs the agent, converts the response back to ChatKit events using stream_agent_response,
+        and creates interactive weather widgets when weather data is queried.
+        """
+        from agent_framework import FunctionResultContent
+
+        if input_user_message is None:
+            logger.debug("Received None user message, skipping")
+            return
+
+        logger.info(f"Processing message for thread: {thread.id}")
+
+        try:
+            # Track weather data and city selector flag for this request
+            weather_data: WeatherData | None = None
+            show_city_selector = False
+
+            # Convert ChatKit user message to Agent Framework ChatMessage using ThreadItemConverter
+            agent_messages = await self.converter.to_agent_input(input_user_message)
+
+            if not agent_messages:
+                logger.warning("No messages after conversion")
+                return
+
+            logger.info(f"Running agent with {len(agent_messages)} message(s)")
+
+            # Run the Agent Framework agent with streaming
+            agent_stream = self.weather_agent.run_stream(agent_messages)
+
+            # Create an intercepting stream that extracts function results while passing through updates
+            async def intercept_stream() -> AsyncIterator[AgentRunResponseUpdate]:
+                nonlocal weather_data, show_city_selector
+                async for update in agent_stream:
+                    # Check for function results in the update
+                    if update.contents:
+                        for content in update.contents:
+                            if isinstance(content, FunctionResultContent):
+                                result = content.result
+
+                                # Check if it's a WeatherResponse (string subclass with weather_data attribute)
+                                if isinstance(result, str) and hasattr(result, "weather_data"):
+                                    extracted_data = getattr(result, "weather_data", None)
+                                    if isinstance(extracted_data, WeatherData):
+                                        weather_data = extracted_data
+                                        logger.info(f"Weather data extracted: {weather_data.location}")
+                                # Check if it's the city selector marker
+                                elif isinstance(result, str) and result == "__SHOW_CITY_SELECTOR__":
+                                    show_city_selector = True
+                                    logger.info("City selector flag detected")
+                    yield update
+
+            # Stream updates as ChatKit events with interception
+            async for event in stream_agent_response(
+                intercept_stream(),
+                thread_id=thread.id,
+            ):
+                yield event
+
+            # If weather data was collected during the tool call, create a widget
+            if weather_data is not None and isinstance(weather_data, WeatherData):
+                logger.info(f"Creating weather widget for location: {weather_data.location}")
+                # Create weather widget
+                widget = render_weather_widget(weather_data)
+                copy_text = weather_widget_copy_text(weather_data)
+
+                # Stream the widget
+                async for widget_event in stream_widget(thread_id=thread.id, widget=widget, copy_text=copy_text):
+                    yield widget_event
+                logger.debug("Weather widget streamed successfully")
+
+            # If city selector should be shown, create and stream that widget
+            if show_city_selector:
+                logger.info("Creating city selector widget")
+                # Create city selector widget
+                selector_widget = render_city_selector_widget()
+                selector_copy_text = city_selector_copy_text()
+
+                # Stream the widget
+                async for widget_event in stream_widget(
+                    thread_id=thread.id, widget=selector_widget, copy_text=selector_copy_text
+                ):
+                    yield widget_event
+                logger.debug("City selector widget streamed successfully")
+
+            logger.info(f"Completed processing message for thread: {thread.id}")
+
+        except Exception as e:
+            logger.error(f"Error processing message for thread {thread.id}: {e}", exc_info=True)
+
+    async def action(
+        self,
+        thread: ThreadMetadata,
+        action: Action[str, Any],
+        sender: WidgetItem | None,
+        context: dict[str, Any],
+    ) -> AsyncIterator[ThreadStreamEvent]:
+        """Handle widget actions from the frontend.
+
+        This method processes actions triggered by interactive widgets,
+        such as city selection from the city selector widget.
+        """
+
+        logger.info(f"Received action: {action.type} for thread: {thread.id}")
+
+        if action.type == "city_selected":
+            # Extract city information from the action payload
+            city_label = action.payload.get("city_label", "Unknown")
+
+            logger.info(f"City selected: {city_label}")
+            logger.debug(f"Action payload: {action.payload}")
+
+            # Track weather data for this request
+            weather_data: WeatherData | None = None
+
+            # Create an agent message asking about the weather
+            agent_messages = [ChatMessage(role=Role.USER, text=f"What's the weather in {city_label}?")]
+
+            logger.debug(f"Processing weather query: {agent_messages[0].text}")
+
+            # Run the Agent Framework agent with streaming
+            agent_stream = self.weather_agent.run_stream(agent_messages)
+
+            # Create an intercepting stream that extracts function results while passing through updates
+            async def intercept_stream() -> AsyncIterator[AgentRunResponseUpdate]:
+                nonlocal weather_data
+                async for update in agent_stream:
+                    # Check for function results in the update
+                    if update.contents:
+                        for content in update.contents:
+                            if isinstance(content, FunctionResultContent):
+                                result = content.result
+
+                                # Check if it's a WeatherResponse (string subclass with weather_data attribute)
+                                if isinstance(result, str) and hasattr(result, "weather_data"):
+                                    extracted_data = getattr(result, "weather_data", None)
+                                    if isinstance(extracted_data, WeatherData):
+                                        weather_data = extracted_data
+                                        logger.info(f"Weather data extracted: {weather_data.location}")
+                    yield update
+
+            # Stream updates as ChatKit events with interception
+            async for event in stream_agent_response(
+                intercept_stream(),
+                thread_id=thread.id,
+            ):
+                yield event
+
+            # If weather data was collected during the tool call, create a widget
+            if weather_data is not None and isinstance(weather_data, WeatherData):
+                logger.info(f"Creating weather widget for: {weather_data.location}")
+                # Create weather widget
+                widget = render_weather_widget(weather_data)
+                copy_text = weather_widget_copy_text(weather_data)
+
+                # Stream the widget
+                async for widget_event in stream_widget(thread_id=thread.id, widget=widget, copy_text=copy_text):
+                    yield widget_event
+                logger.debug("Weather widget created successfully from action")
+            else:
+                logger.warning("No weather data available to create widget after action")
+
+
+# FastAPI application setup
+app = FastAPI(
+    title="ChatKit Weather & Vision Agent",
+    description="Weather and image analysis assistant powered by Agent Framework and Azure OpenAI",
+    version="1.0.0",
+)
+
+# Add CORS middleware to allow frontend connections
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production, specify exact origins
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Initialize data store and ChatKit server
+logger.info("Initializing application components")
+data_store = SQLiteStore(db_path=DATABASE_PATH)
+attachment_store = FileBasedAttachmentStore(
+    uploads_dir=UPLOADS_DIRECTORY,
+    base_url=SERVER_BASE_URL,
+    data_store=data_store,
+)
+chatkit_server = WeatherChatKitServer(data_store, attachment_store)
+logger.info("Application initialization complete")
+
+
+@app.post("/chatkit")
+async def chatkit_endpoint(request: Request):
+    """Main ChatKit endpoint that handles all ChatKit requests.
+
+    This endpoint follows the ChatKit server protocol and handles both
+    streaming and non-streaming responses.
+    """
+    logger.debug(f"Received ChatKit request from {request.client}")
+    request_body = await request.body()
+
+    # Create context following the working examples pattern
+    context = {"request": request}
+
+    try:
+        # Process the request using ChatKit server
+        result = await chatkit_server.process(request_body, context)
+
+        # Return appropriate response type
+        if hasattr(result, "__aiter__"):  # StreamingResult
+            logger.debug("Returning streaming response")
+            return StreamingResponse(result, media_type="text/event-stream")  # type: ignore[arg-type]
+        # NonStreamingResult
+        logger.debug("Returning non-streaming response")
+        return Response(content=result.json, media_type="application/json")  # type: ignore[union-attr]
+    except Exception as e:
+        logger.error(f"Error processing ChatKit request: {e}", exc_info=True)
+        raise
+
+
+@app.post("/upload/{attachment_id}")
+async def upload_file(attachment_id: str, file: UploadFile = File(...)):
+    """Handle file upload for two-phase upload.
+
+    The client POSTs the file bytes here after creating the attachment
+    via the ChatKit attachments.create endpoint.
+    """
+    logger.info(f"Receiving file upload for attachment: {attachment_id}")
+
+    try:
+        # Read file contents
+        contents = await file.read()
+
+        # Save to disk
+        file_path = attachment_store.get_file_path(attachment_id)
+        file_path.write_bytes(contents)
+
+        logger.info(f"Saved {len(contents)} bytes to {file_path}")
+
+        # Load the attachment metadata from the data store
+        attachment = await data_store.load_attachment(attachment_id, {"user_id": DEFAULT_USER_ID})
+
+        # Clear the upload_url since upload is complete
+        attachment.upload_url = None
+
+        # Save the updated attachment back to the store
+        await data_store.save_attachment(attachment, {"user_id": DEFAULT_USER_ID})
+
+        # Return the attachment metadata as JSON
+        return JSONResponse(content=attachment.model_dump(mode="json"))
+
+    except Exception as e:
+        logger.error(f"Error uploading file for attachment {attachment_id}: {e}", exc_info=True)
+        return JSONResponse(status_code=500, content={"error": f"Failed to upload file: {str(e)}"})
+
+
+@app.get("/preview/{attachment_id}")
+async def preview_image(attachment_id: str):
+    """Serve image preview/thumbnail.
+
+    For simplicity, this serves the full image. In production, you should
+    generate and cache thumbnails.
+    """
+    logger.debug(f"Serving preview for attachment: {attachment_id}")
+
+    try:
+        file_path = attachment_store.get_file_path(attachment_id)
+
+        if not file_path.exists():
+            return JSONResponse(status_code=404, content={"error": "File not found"})
+
+        # Determine media type from file extension or attachment metadata
+        # For simplicity, we'll try to load from the store
+        try:
+            attachment = await data_store.load_attachment(attachment_id, {"user_id": DEFAULT_USER_ID})
+            media_type = attachment.mime_type
+        except Exception:
+            # Default to binary if we can't determine
+            media_type = "application/octet-stream"
+
+        return FileResponse(file_path, media_type=media_type)
+
+    except Exception as e:
+        logger.error(f"Error serving preview for attachment {attachment_id}: {e}", exc_info=True)
+        return JSONResponse(status_code=500, content={"error": str(e)})
+
+
+if __name__ == "__main__":
+    # Run the server
+    logger.info(f"Starting ChatKit Weather Agent server on {SERVER_HOST}:{SERVER_PORT}")
+    uvicorn.run(app, host=SERVER_HOST, port=SERVER_PORT, log_level="info")
@@ -0,0 +1,121 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""File-based AttachmentStore implementation for ChatKit.
+
+This module provides a simple AttachmentStore implementation that stores
+uploaded files on the local filesystem. In production, you should use
+cloud storage like S3, Azure Blob Storage, or Google Cloud Storage.
+"""
+
+from pathlib import Path
+from typing import Any, TYPE_CHECKING
+
+from chatkit.store import AttachmentStore
+from chatkit.types import Attachment, AttachmentCreateParams, FileAttachment, ImageAttachment
+from pydantic import AnyUrl
+
+if TYPE_CHECKING:
+    from store import SQLiteStore
+
+
+class FileBasedAttachmentStore(AttachmentStore[dict[str, Any]]):
+    """File-based AttachmentStore that stores files on local disk.
+
+    This implementation stores uploaded files in a local directory and provides
+    upload URLs that point to the FastAPI upload endpoint. It supports both
+    image and file attachments.
+
+    Features:
+    - Stores files in a local uploads directory
+    - Generates upload URLs for two-phase upload
+    - Generates preview URLs for images
+    - Proper cleanup on deletion
+
+    Note: This is for demonstration purposes. In production, use cloud storage
+    with signed URLs for better security and scalability.
+    """
+
+    def __init__(
+        self,
+        uploads_dir: str = "./uploads",
+        base_url: str = "http://localhost:8001",
+        data_store: "SQLiteStore | None" = None,
+    ):
+        """Initialize the file-based attachment store.
+
+        Args:
+            uploads_dir: Directory where uploaded files will be stored
+            base_url: Base URL for generating upload and preview URLs
+            data_store: Optional data store to persist attachment metadata
+        """
+        self.uploads_dir = Path(uploads_dir)
+        self.base_url = base_url.rstrip("/")
+        self.data_store = data_store
+        
+        # Create uploads directory if it doesn't exist
+        self.uploads_dir.mkdir(parents=True, exist_ok=True)
+
+    def get_file_path(self, attachment_id: str) -> Path:
+        """Get the filesystem path for an attachment."""
+        return self.uploads_dir / attachment_id
+
+    async def delete_attachment(self, attachment_id: str, context: dict[str, Any]) -> None:
+        """Delete an attachment and its file from disk."""
+        file_path = self.get_file_path(attachment_id)
+        if file_path.exists():
+            file_path.unlink()
+
+    async def create_attachment(
+        self, input: AttachmentCreateParams, context: dict[str, Any]
+    ) -> Attachment:
+        """Create an attachment with upload URL for two-phase upload.
+
+        This creates the attachment metadata and returns upload URLs that
+        the client will use to POST the actual file bytes.
+        """
+        # Generate unique ID for this attachment
+        attachment_id = self.generate_attachment_id(input.mime_type, context)
+        
+        # Generate upload URL that points to our FastAPI upload endpoint
+        upload_url = f"{self.base_url}/upload/{attachment_id}"
+
+        # Create appropriate attachment type based on MIME type
+        if input.mime_type.startswith("image/"):
+            # For images, also provide a preview URL
+            preview_url = f"{self.base_url}/preview/{attachment_id}"
+            
+            attachment = ImageAttachment(
+                id=attachment_id,
+                type="image",
+                mime_type=input.mime_type,
+                name=input.name,
+                upload_url=AnyUrl(upload_url),
+                preview_url=AnyUrl(preview_url),
+            )
+        else:
+            # For files, just provide upload URL
+            attachment = FileAttachment(
+                id=attachment_id,
+                type="file",
+                mime_type=input.mime_type,
+                name=input.name,
+                upload_url=AnyUrl(upload_url),
+            )
+
+        # Save attachment metadata to data store so it's available during upload
+        if self.data_store is not None:
+            await self.data_store.save_attachment(attachment, context)
+
+        return attachment
+
+    async def read_attachment_bytes(self, attachment_id: str) -> bytes:
+        """Read the raw bytes of an uploaded attachment.
+
+        This is used by the ThreadItemConverter to create base64-encoded
+        content for sending to the Agent Framework.
+        """
+        file_path = self.get_file_path(attachment_id)
+        if not file_path.exists():
+            raise FileNotFoundError(f"Attachment {attachment_id} not found on disk")
+        
+        return file_path.read_bytes()
@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ChatKit + Agent Framework Demo</title>
+    <script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+        height: 100vh;
+        display: flex;
+        flex-direction: column;
+      }
+
+      header {
+        padding: 1rem;
+        background: #f5f5f5;
+        border-bottom: 1px solid #ddd;
+      }
+
+      h1 {
+        font-size: 1.5rem;
+        margin-bottom: 0.5rem;
+      }
+
+      p {
+        color: #666;
+        font-size: 0.9rem;
+      }
+
+      #root {
+        flex: 1;
+        overflow: hidden;
+      }
+    </style>
+  </head>
+  <body>
+    <header>
+      <h1>ChatKit + Agent Framework Demo</h1>
+      <p>Simple weather assistant powered by Agent Framework and ChatKit</p>
+    </header>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
@@ -0,0 +1,27 @@
+{
+    "name": "chatkit-agent-framework-demo",
+    "version": "0.1.0",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build",
+        "preview": "vite preview"
+    },
+    "engines": {
+        "node": ">=18.18",
+        "npm": ">=9"
+    },
+    "dependencies": {
+        "@openai/chatkit-react": "^0",
+        "react": "^19.2.0",
+        "react-dom": "^19.2.0"
+    },
+    "devDependencies": {
+        "@types/react": "^19.2.0",
+        "@types/react-dom": "^19.2.0",
+        "@vitejs/plugin-react-swc": "^3.5.0",
+        "typescript": "^5.4.0",
+        "vite": "^7.1.9"
+    }
+}
@@ -0,0 +1,33 @@
+import { ChatKit, useChatKit } from "@openai/chatkit-react";
+
+const CHATKIT_API_URL = "/chatkit";
+const CHATKIT_API_DOMAIN_KEY =
+  import.meta.env.VITE_CHATKIT_API_DOMAIN_KEY ?? "domain_pk_localhost_dev";
+
+export default function App() {
+  const chatkit = useChatKit({
+    api: {
+      url: CHATKIT_API_URL,
+      domainKey: CHATKIT_API_DOMAIN_KEY,
+      uploadStrategy: { type: "two_phase" },
+    },
+    startScreen: {
+      greeting: "Hello! I'm your weather and image analysis assistant. Ask me about the weather in any location or upload images for me to analyze.",
+      prompts: [
+        { label: "Weather in New York", prompt: "What's the weather in New York?" },
+        { label: "Select City to Get Weather", prompt: "Show me the city selector for weather" },
+        { label: "Current Time", prompt: "What time is it?" },
+        { label: "Analyze an Image", prompt: "I'll upload an image for you to analyze" },
+      ],
+    },
+    composer: {
+      placeholder: "Ask about weather or upload an image...",
+      attachments: {
+        enabled: true,
+        accept: { "image/*": [".png", ".jpg", ".jpeg", ".gif", ".webp"] },
+      },
+    },
+  });
+
+  return <ChatKit control={chatkit.control} style={{ height: "100%" }} />;
+}
@@ -0,0 +1,15 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+
+const container = document.getElementById("root");
+
+if (!container) {
+  throw new Error("Root element with id 'root' not found");
+}
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}
@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["vite.config.ts"]
+}
@@ -0,0 +1,24 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react-swc";
+
+const backendTarget = process.env.BACKEND_URL ?? "http://127.0.0.1:8001";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: "0.0.0.0",
+    port: 5171,
+    proxy: {
+      "/chatkit": {
+        target: backendTarget,
+        changeOrigin: true,
+      },
+    },
+    // For production deployments, you need to add your public domains to this list
+    allowedHosts: [
+      // You can remove these examples added just to demonstrate how to configure the allowlist
+      ".ngrok.io",
+      ".trycloudflare.com",
+    ],
+  },
+});
@@ -0,0 +1,361 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""SQLite-based store implementation for ChatKit data persistence.
+
+This module provides a complete Store implementation using SQLite for data persistence.
+It includes proper thread safety, user isolation, and follows the ChatKit Store protocol.
+"""
+
+import sqlite3
+import uuid
+from typing import Any
+
+from chatkit.store import Store, NotFoundError
+from chatkit.types import (
+    Attachment,
+    Page,
+    ThreadItem,
+    ThreadMetadata,
+)
+from pydantic import BaseModel
+
+
+class ThreadData(BaseModel):
+    """Model for serializing thread data to SQLite."""
+    thread: ThreadMetadata
+
+
+class ItemData(BaseModel):
+    """Model for serializing thread item data to SQLite."""
+    item: ThreadItem
+
+
+class AttachmentData(BaseModel):
+    """Model for serializing attachment data to SQLite."""
+    attachment: Attachment
+
+
+class SQLiteStore(Store[dict[str, Any]]):
+    """SQLite-based store implementation for ChatKit data.
+
+    This implementation follows the pattern from the ChatKit Python tests
+    and provides persistent storage for threads, messages, and attachments.
+
+    Features:
+    - Thread-safe SQLite connections with WAL mode
+    - User isolation for multi-tenant support
+    - Proper error handling and transaction management
+    - Complete Store protocol implementation
+
+    Note: This is for demonstration purposes. In production, you should
+    implement proper error handling, connection pooling, and migration strategies.
+    """
+
+    def __init__(self, db_path: str | None = None):
+        self.db_path = db_path or "chatkit_demo.db"  # Use file-based DB for demo
+        self._create_tables()
+
+    def _create_connection(self):
+        # Enable thread safety and WAL mode for better concurrent access
+        conn = sqlite3.connect(self.db_path, check_same_thread=False)
+        conn.execute("PRAGMA journal_mode=WAL")
+        return conn
+
+    def _create_tables(self):
+        with self._create_connection() as conn:
+            # Create threads table
+            conn.execute(
+                """CREATE TABLE IF NOT EXISTS threads (
+                id TEXT PRIMARY KEY,
+                user_id TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                data TEXT NOT NULL
+                )"""
+            )
+
+            # Create items table
+            conn.execute(
+                """CREATE TABLE IF NOT EXISTS items (
+                id TEXT PRIMARY KEY,
+                thread_id TEXT NOT NULL,
+                user_id TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                data TEXT NOT NULL
+                )"""
+            )
+
+            # Create attachments table
+            conn.execute(
+                """CREATE TABLE IF NOT EXISTS attachments (
+                id TEXT PRIMARY KEY,
+                user_id TEXT NOT NULL,
+                data TEXT NOT NULL
+                )"""
+            )
+            conn.commit()
+
+    def generate_thread_id(self, context: dict[str, Any]) -> str:
+        return f"thr_{uuid.uuid4().hex[:8]}"
+
+    def generate_item_id(
+        self,
+        item_type: str,
+        thread: ThreadMetadata,
+        context: dict[str, Any],
+    ) -> str:
+        prefix_map = {
+            "message": "msg",
+            "tool_call": "tc",
+            "task": "tsk",
+            "workflow": "wf",
+            "attachment": "atc",
+        }
+        prefix = prefix_map.get(item_type, "itm")
+        return f"{prefix}_{uuid.uuid4().hex[:8]}"
+
+    async def load_thread(self, thread_id: str, context: dict[str, Any]) -> ThreadMetadata:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            cursor = conn.execute(
+                "SELECT data FROM threads WHERE id = ? AND user_id = ?",
+                (thread_id, user_id),
+            ).fetchone()
+
+            if cursor is None:
+                raise NotFoundError(f"Thread {thread_id} not found")
+
+            thread_data = ThreadData.model_validate_json(cursor[0])
+            return thread_data.thread
+
+    async def save_thread(self, thread: ThreadMetadata, context: dict[str, Any]) -> None:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            thread_data = ThreadData(thread=thread)
+
+            # Replace existing thread data
+            conn.execute(
+                "DELETE FROM threads WHERE id = ? AND user_id = ?",
+                (thread.id, user_id),
+            )
+            conn.execute(
+                "INSERT INTO threads (id, user_id, created_at, data) VALUES (?, ?, ?, ?)",
+                (
+                    thread.id,
+                    user_id,
+                    thread.created_at.isoformat(),
+                    thread_data.model_dump_json(),
+                ),
+            )
+            conn.commit()
+
+    async def load_thread_items(
+        self,
+        thread_id: str,
+        after: str | None,
+        limit: int,
+        order: str,
+        context: dict[str, Any],
+    ) -> Page[ThreadItem]:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            created_after: str | None = None
+            if after:
+                after_cursor = conn.execute(
+                    "SELECT created_at FROM items WHERE id = ? AND user_id = ?",
+                    (after, user_id),
+                ).fetchone()
+                if after_cursor is None:
+                    raise NotFoundError(f"Item {after} not found")
+                created_after = after_cursor[0]
+
+            query = """
+                SELECT data FROM items
+                WHERE thread_id = ? AND user_id = ?
+            """
+            params: list[Any] = [thread_id, user_id]
+
+            if created_after:
+                query += " AND created_at > ?" if order == "asc" else " AND created_at < ?"
+                params.append(created_after)
+
+            query += f" ORDER BY created_at {order} LIMIT ?"
+            params.append(limit + 1)
+
+            items_cursor = conn.execute(query, params).fetchall()
+            items = [
+                ItemData.model_validate_json(row[0]).item for row in items_cursor
+            ]
+
+            has_more = len(items) > limit
+            if has_more:
+                items = items[:limit]
+
+            return Page[ThreadItem](
+                data=items,
+                has_more=has_more,
+                after=items[-1].id if items else None
+            )
+
+    async def save_attachment(self, attachment: Attachment, context: dict[str, Any]) -> None:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            attachment_data = AttachmentData(attachment=attachment)
+            conn.execute(
+                "INSERT OR REPLACE INTO attachments (id, user_id, data) VALUES (?, ?, ?)",
+                (
+                    attachment.id,
+                    user_id,
+                    attachment_data.model_dump_json(),
+                ),
+            )
+            conn.commit()
+
+    async def load_attachment(self, attachment_id: str, context: dict[str, Any]) -> Attachment:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            cursor = conn.execute(
+                "SELECT data FROM attachments WHERE id = ? AND user_id = ?",
+                (attachment_id, user_id),
+            ).fetchone()
+
+            if cursor is None:
+                raise NotFoundError(f"Attachment {attachment_id} not found")
+
+            attachment_data = AttachmentData.model_validate_json(cursor[0])
+            return attachment_data.attachment
+
+    async def delete_attachment(self, attachment_id: str, context: dict[str, Any]) -> None:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            conn.execute(
+                "DELETE FROM attachments WHERE id = ? AND user_id = ?",
+                (attachment_id, user_id),
+            )
+            conn.commit()
+
+    async def load_threads(
+        self,
+        limit: int,
+        after: str | None,
+        order: str,
+        context: dict[str, Any],
+    ) -> Page[ThreadMetadata]:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            created_after: str | None = None
+            if after:
+                after_cursor = conn.execute(
+                    "SELECT created_at FROM threads WHERE id = ? AND user_id = ?",
+                    (after, user_id),
+                ).fetchone()
+                if after_cursor is None:
+                    raise NotFoundError(f"Thread {after} not found")
+                created_after = after_cursor[0]
+
+            query = "SELECT data FROM threads WHERE user_id = ?"
+            params: list[Any] = [user_id]
+
+            if created_after:
+                query += " AND created_at > ?" if order == "asc" else " AND created_at < ?"
+                params.append(created_after)
+
+            query += f" ORDER BY created_at {order} LIMIT ?"
+            params.append(limit + 1)
+
+            threads_cursor = conn.execute(query, params).fetchall()
+            threads = [
+                ThreadData.model_validate_json(row[0]).thread for row in threads_cursor
+            ]
+
+            has_more = len(threads) > limit
+            if has_more:
+                threads = threads[:limit]
+
+            return Page[ThreadMetadata](
+                data=threads,
+                has_more=has_more,
+                after=threads[-1].id if threads else None
+            )
+
+    async def add_thread_item(
+        self, thread_id: str, item: ThreadItem, context: dict[str, Any]
+    ) -> None:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            item_data = ItemData(item=item)
+            conn.execute(
+                "INSERT INTO items (id, thread_id, user_id, created_at, data) VALUES (?, ?, ?, ?, ?)",
+                (
+                    item.id,
+                    thread_id,
+                    user_id,
+                    item.created_at.isoformat(),
+                    item_data.model_dump_json(),
+                ),
+            )
+            conn.commit()
+
+    async def save_item(self, thread_id: str, item: ThreadItem, context: dict[str, Any]) -> None:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            item_data = ItemData(item=item)
+            conn.execute(
+                "UPDATE items SET data = ? WHERE id = ? AND thread_id = ? AND user_id = ?",
+                (
+                    item_data.model_dump_json(),
+                    item.id,
+                    thread_id,
+                    user_id,
+                ),
+            )
+            conn.commit()
+
+    async def load_item(self, thread_id: str, item_id: str, context: dict[str, Any]) -> ThreadItem:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            cursor = conn.execute(
+                "SELECT data FROM items WHERE id = ? AND thread_id = ? AND user_id = ?",
+                (item_id, thread_id, user_id),
+            ).fetchone()
+
+            if cursor is None:
+                raise NotFoundError(f"Item {item_id} not found in thread {thread_id}")
+
+            item_data = ItemData.model_validate_json(cursor[0])
+            return item_data.item
+
+    async def delete_thread(self, thread_id: str, context: dict[str, Any]) -> None:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            conn.execute(
+                "DELETE FROM threads WHERE id = ? AND user_id = ?",
+                (thread_id, user_id),
+            )
+            conn.execute(
+                "DELETE FROM items WHERE thread_id = ? AND user_id = ?",
+                (thread_id, user_id),
+            )
+            conn.commit()
+
+    async def delete_thread_item(
+        self, thread_id: str, item_id: str, context: dict[str, Any]
+    ) -> None:
+        user_id = context.get("user_id", "demo_user")
+
+        with self._create_connection() as conn:
+            conn.execute(
+                "DELETE FROM items WHERE id = ? AND thread_id = ? AND user_id = ?",
+                (item_id, thread_id, user_id),
+            )
+            conn.commit()
@@ -0,0 +1,437 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Weather widget rendering for ChatKit integration sample."""
+
+import base64
+from dataclasses import dataclass
+
+from chatkit.actions import ActionConfig
+from chatkit.widgets import Box, Button, Card, Col, Image, Row, Text, Title, WidgetRoot
+
+WEATHER_ICON_COLOR = "#1D4ED8"
+WEATHER_ICON_ACCENT = "#DBEAFE"
+
+# Popular cities for the selector
+POPULAR_CITIES = [
+    {"value": "seattle", "label": "Seattle, WA", "description": "Pacific Northwest"},
+    {"value": "new_york", "label": "New York, NY", "description": "East Coast"},
+    {"value": "san_francisco", "label": "San Francisco, CA", "description": "Bay Area"},
+    {"value": "chicago", "label": "Chicago, IL", "description": "Midwest"},
+    {"value": "miami", "label": "Miami, FL", "description": "Southeast"},
+    {"value": "austin", "label": "Austin, TX", "description": "Southwest"},
+    {"value": "boston", "label": "Boston, MA", "description": "New England"},
+    {"value": "denver", "label": "Denver, CO", "description": "Mountain West"},
+    {"value": "portland", "label": "Portland, OR", "description": "Pacific Northwest"},
+    {"value": "atlanta", "label": "Atlanta, GA", "description": "Southeast"},
+]
+
+# Mapping from city values to display names for weather queries
+CITY_VALUE_TO_NAME = {city["value"]: city["label"] for city in POPULAR_CITIES}
+
+
+
+def _sun_svg() -> str:
+    """Generate SVG for sunny weather icon."""
+    color = WEATHER_ICON_COLOR
+    accent = WEATHER_ICON_ACCENT
+    return (
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">'
+        f'<circle cx="32" cy="32" r="13" fill="{accent}" stroke="{color}" stroke-width="3"/>'
+        f'<g stroke="{color}" stroke-width="3" stroke-linecap="round">'
+        '<line x1="32" y1="8" x2="32" y2="16"/>'
+        '<line x1="32" y1="48" x2="32" y2="56"/>'
+        '<line x1="8" y1="32" x2="16" y2="32"/>'
+        '<line x1="48" y1="32" x2="56" y2="32"/>'
+        '<line x1="14.93" y1="14.93" x2="20.55" y2="20.55"/>'
+        '<line x1="43.45" y1="43.45" x2="49.07" y2="49.07"/>'
+        '<line x1="14.93" y1="49.07" x2="20.55" y2="43.45"/>'
+        '<line x1="43.45" y1="20.55" x2="49.07" y2="14.93"/>'
+        "</g>"
+        "</svg>"
+    )
+
+
+def _cloud_svg() -> str:
+    """Generate SVG for cloudy weather icon."""
+    color = WEATHER_ICON_COLOR
+    accent = WEATHER_ICON_ACCENT
+    return (
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">'
+        f'<path d="M22 46H44C50.075 46 55 41.075 55 35S50.075 24 44 24H42.7C41.2 16.2 34.7 10 26.5 10 18 10 11.6 16.1 11 24.3 6.5 25.6 3 29.8 3 35s4.925 11 11 11h8Z" '
+        f'fill="{accent}" stroke="{color}" stroke-width="3" stroke-linejoin="round"/>'
+        "</svg>"
+    )
+
+
+def _rain_svg() -> str:
+    """Generate SVG for rainy weather icon."""
+    color = WEATHER_ICON_COLOR
+    accent = WEATHER_ICON_ACCENT
+    return (
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">'
+        f'<path d="M22 40H44C50.075 40 55 35.075 55 29S50.075 18 44 18H42.7C41.2 10.2 34.7 4 26.5 4 18 4 11.6 10.1 11 18.3 6.5 19.6 3 23.8 3 29s4.925 11 11 11h8Z" '
+        f'fill="{accent}" stroke="{color}" stroke-width="3" stroke-linejoin="round"/>'
+        f'<g stroke="{color}" stroke-width="3" stroke-linecap="round">'
+        '<line x1="20" y1="48" x2="24" y2="56"/>'
+        '<line x1="30" y1="50" x2="34" y2="58"/>'
+        '<line x1="40" y1="48" x2="44" y2="56"/>'
+        "</g>"
+        "</svg>"
+    )
+
+
+def _storm_svg() -> str:
+    """Generate SVG for stormy weather icon."""
+    color = WEATHER_ICON_COLOR
+    accent = WEATHER_ICON_ACCENT
+    return (
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">'
+        f'<path d="M22 40H44C50.075 40 55 35.075 55 29S50.075 18 44 18H42.7C41.2 10.2 34.7 4 26.5 4 18 4 11.6 10.1 11 18.3 6.5 19.6 3 23.8 3 29s4.925 11 11 11h8Z" '
+        f'fill="{accent}" stroke="{color}" stroke-width="3" stroke-linejoin="round"/>'
+        f'<path d="M34 46L28 56H34L30 64L42 50H36L40 46Z" '
+        f'fill="{color}" stroke="{color}" stroke-width="2" stroke-linejoin="round"/>'
+        "</svg>"
+    )
+
+
+def _snow_svg() -> str:
+    """Generate SVG for snowy weather icon."""
+    color = WEATHER_ICON_COLOR
+    accent = WEATHER_ICON_ACCENT
+    return (
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">'
+        f'<path d="M22 40H44C50.075 40 55 35.075 55 29S50.075 18 44 18H42.7C41.2 10.2 34.7 4 26.5 4 18 4 11.6 10.1 11 18.3 6.5 19.6 3 23.8 3 29s4.925 11 11 11h8Z" '
+        f'fill="{accent}" stroke="{color}" stroke-width="3" stroke-linejoin="round"/>'
+        f'<g stroke="{color}" stroke-width="2" stroke-linecap="round">'
+        '<line x1="20" y1="48" x2="20" y2="56"/>'
+        '<line x1="17" y1="51" x2="23" y2="53"/>'
+        '<line x1="17" y1="53" x2="23" y2="51"/>'
+        '<line x1="36" y1="48" x2="36" y2="56"/>'
+        '<line x1="33" y1="51" x2="39" y2="53"/>'
+        '<line x1="33" y1="53" x2="39" y2="51"/>'
+        "</g>"
+        "</svg>"
+    )
+
+
+def _fog_svg() -> str:
+    """Generate SVG for foggy weather icon."""
+    color = WEATHER_ICON_COLOR
+    accent = WEATHER_ICON_ACCENT
+    return (
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">'
+        f'<path d="M22 40H44C50.075 40 55 35.075 55 29S50.075 18 44 18H42.7C41.2 10.2 34.7 4 26.5 4 18 4 11.6 10.1 11 18.3 6.5 19.6 3 23.8 3 29s4.925 11 11 11h8Z" '
+        f'fill="{accent}" stroke="{color}" stroke-width="3" stroke-linejoin="round"/>'
+        f'<g stroke="{color}" stroke-width="3" stroke-linecap="round">'
+        '<line x1="18" y1="50" x2="42" y2="50"/>'
+        '<line x1="24" y1="56" x2="48" y2="56"/>'
+        "</g>"
+        "</svg>"
+    )
+
+
+def _encode_svg(svg: str) -> str:
+    """Encode SVG as base64 data URI."""
+    encoded = base64.b64encode(svg.encode("utf-8")).decode("ascii")
+    return f"data:image/svg+xml;base64,{encoded}"
+
+
+# Weather condition to icon mapping
+WEATHER_ICONS = {
+    "sunny": _encode_svg(_sun_svg()),
+    "cloudy": _encode_svg(_cloud_svg()),
+    "rainy": _encode_svg(_rain_svg()),
+    "stormy": _encode_svg(_storm_svg()),
+    "snowy": _encode_svg(_snow_svg()),
+    "foggy": _encode_svg(_fog_svg()),
+}
+
+DEFAULT_WEATHER_ICON = _encode_svg(_cloud_svg())
+
+
+@dataclass
+class WeatherData:
+    """Weather data container."""
+
+    location: str
+    condition: str
+    temperature: int
+    humidity: int
+    wind_speed: int
+
+
+def render_weather_widget(data: WeatherData) -> WidgetRoot:
+    """Render a weather widget from weather data.
+
+    Args:
+        data: WeatherData containing weather information
+
+    Returns:
+        A ChatKit WidgetRoot (Card) displaying the weather information
+    """
+    # Get weather icon
+    weather_icon_src = WEATHER_ICONS.get(data.condition.lower(), DEFAULT_WEATHER_ICON)
+
+    # Build the widget
+    header = Box(
+        padding=5,
+        background="surface-tertiary",
+        children=[
+            Row(
+                justify="between",
+                align="center",
+                children=[
+                    Col(
+                        align="start",
+                        gap=1,
+                        children=[
+                            Text(
+                                value=data.location,
+                                size="lg",
+                                weight="semibold",
+                            ),
+                            Text(
+                                value="Current conditions",
+                                color="tertiary",
+                                size="xs",
+                            ),
+                        ],
+                    ),
+                    Box(
+                        padding=3,
+                        radius="full",
+                        background="blue-100",
+                        children=[
+                            Image(
+                                src=weather_icon_src,
+                                alt=data.condition,
+                                size=28,
+                                fit="contain",
+                            )
+                        ],
+                    ),
+                ],
+            ),
+            Row(
+                align="start",
+                gap=4,
+                children=[
+                    Title(
+                        value=f"{data.temperature}°C",
+                        size="lg",
+                        weight="semibold",
+                    ),
+                    Col(
+                        align="start",
+                        gap=1,
+                        children=[
+                            Text(
+                                value=data.condition.title(),
+                                color="secondary",
+                                size="sm",
+                                weight="medium",
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ],
+    )
+
+    # Details section
+    details = Box(
+        padding=5,
+        gap=4,
+        children=[
+            Text(value="Weather details", weight="semibold", size="sm"),
+            Row(
+                gap=3,
+                wrap="wrap",
+                children=[
+                    _detail_chip("Humidity", f"{data.humidity}%"),
+                    _detail_chip("Wind", f"{data.wind_speed} km/h"),
+                ],
+            ),
+        ],
+    )
+
+    return Card(
+        key="weather",
+        padding=0,
+        children=[header, details],
+    )
+
+
+def _detail_chip(label: str, value: str) -> Box:
+    """Create a detail chip widget component."""
+    return Box(
+        padding=3,
+        radius="xl",
+        background="surface-tertiary",
+        width=150,
+        minWidth=150,
+        maxWidth=150,
+        minHeight=80,
+        maxHeight=80,
+        flex="0 0 auto",
+        children=[
+            Col(
+                align="stretch",
+                gap=2,
+                children=[
+                    Text(value=label, size="xs", weight="medium", color="tertiary"),
+                    Row(
+                        justify="center",
+                        margin={"top": 2},
+                        children=[Text(value=value, weight="semibold", size="lg")],
+                    ),
+                ],
+            )
+        ],
+    )
+
+
+def weather_widget_copy_text(data: WeatherData) -> str:
+    """Generate plain text representation of weather data.
+
+    Args:
+        data: WeatherData containing weather information
+
+    Returns:
+        Plain text description for copy/paste functionality
+    """
+    return (
+        f"Weather in {data.location}:\n"
+        f"• Condition: {data.condition.title()}\n"
+        f"• Temperature: {data.temperature}°C\n"
+        f"• Humidity: {data.humidity}%\n"
+        f"• Wind: {data.wind_speed} km/h"
+    )
+
+
+def render_city_selector_widget() -> WidgetRoot:
+    """Render an interactive city selector widget.
+
+    This widget displays popular cities as a visual selection interface.
+    Users can click or ask about any city to get weather information.
+
+    Returns:
+        A ChatKit WidgetRoot (Card) with city selection display
+    """
+    # Create location icon SVG
+    location_icon = _encode_svg(
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">'
+        f'<path d="M32 8c-8.837 0-16 7.163-16 16 0 12 16 32 16 32s16-20 16-32c0-8.837-7.163-16-16-16z" '
+        f'fill="{WEATHER_ICON_ACCENT}" stroke="{WEATHER_ICON_COLOR}" stroke-width="3" stroke-linejoin="round"/>'
+        f'<circle cx="32" cy="24" r="6" fill="{WEATHER_ICON_COLOR}"/>'
+        "</svg>"
+    )
+
+    # Header section
+    header = Box(
+        padding=5,
+        background="surface-tertiary",
+        children=[
+            Row(
+                gap=3,
+                align="center",
+                children=[
+                    Box(
+                        padding=3,
+                        radius="full",
+                        background="blue-100",
+                        children=[
+                            Image(
+                                src=location_icon,
+                                alt="Location",
+                                size=28,
+                                fit="contain",
+                            )
+                        ],
+                    ),
+                    Col(
+                        align="start",
+                        gap=1,
+                        children=[
+                            Title(
+                                value="Popular Cities",
+                                size="md",
+                                weight="semibold",
+                            ),
+                            Text(
+                                value="Select a city or ask about any location",
+                                color="tertiary",
+                                size="xs",
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ],
+    )
+
+    # Create city chips in a grid layout
+    city_chips: list[Button] = []
+    for city in POPULAR_CITIES:
+        # Create a button that sends an action to query weather for the selected city
+        chip = Button(
+            label=city["label"],
+            variant="outline",
+            size="md",
+            onClickAction=ActionConfig(
+                type="city_selected",
+                payload={"city_value": city["value"], "city_label": city["label"]},
+                handler="server",  # Handle on server-side
+            ),
+        )
+        city_chips.append(chip)
+
+    # Arrange in rows of 3
+    city_rows: list[Row] = []
+    for i in range(0, len(city_chips), 3):
+        row_chips: list[Button] = city_chips[i : i + 3]
+        city_rows.append(
+            Row(
+                gap=3,
+                wrap="wrap",
+                justify="start",
+                children=list(row_chips),  # Convert to generic list
+            )
+        )
+
+    # Cities display section
+    cities_section = Box(
+        padding=5,
+        gap=3,
+        children=[
+            *city_rows,
+            Box(
+                padding=3,
+                radius="md",
+                background="blue-50",
+                children=[
+                    Text(
+                        value="💡 Click any city to get its weather, or ask about any other location!",
+                        size="xs",
+                        color="secondary",
+                    ),
+                ],
+            ),
+        ],
+    )
+
+    return Card(
+        key="city_selector",
+        padding=0,
+        children=[header, cities_section],
+    )
+
+
+def city_selector_copy_text() -> str:
+    """Generate plain text representation of city selector.
+
+    Returns:
+        Plain text description for copy/paste functionality
+    """
+    cities_list = "\n".join([f"• {city['label']}" for city in POPULAR_CITIES])
+    return f"Popular cities (click to get weather):\n{cities_list}\n\nYou can also ask about weather in any other location!"
				`@@ -0,0 +1 @@`
				`# Copyright (c) Microsoft. All rights reserved.`