How elementary-data/py-ai-datastream works
Project type and purpose
• This is a framework‐agnostic Python library (“ai_datastream”) implementing Vercel’s Data Stream Protocol for streaming AI chat responses.
• It provides two main integration points:
• Agent adapters (currently: LangGraph)
• API adapters (currently: FastAPI)
File structure
• Top-level:
• ai_datastream/ – core package
– agent/langgraph/ – LangGraph adapter: message_parser, stream_converter, streamer
– api/fastapi/ – FastAPI adapter: request/response types, streaming response class
– consts.py, messages.py, stream_parts.py, streamer.py – core protocol definitions and generic streamer
• Configuration files: pyproject.toml, pre-commit, CI workflow
• tests/ – unit tests for each adapter and core functionality
README for insights
• Confirms the two supported frameworks (agent: LangGraph; API: FastAPI)
• Shows usage pattern: FastAPI endpoint returns AiChatDataStreamAsyncResponse, wired to a LangGraphStreamer and an LLM model (e.g., ChatOpenAI) plus optional tools
• Emphasizes the “{type}:{data}” streaming protocol
A. Frontend Client
• React or any JS client using Vercel’s useChat hook (or custom consumer)
B. API Layer (FastAPI)
• FastAPI app receives HTTP POST → FastApiDataStreamRequest
• Returns AiChatDataStreamAsyncResponse (streaming HTTP response)
C. Streaming Engine (ai_datastream.core)
• Core streamer (streamer.py) orchestrates the protocol
• stream_parts.py defines framing (type markers)
• messages.py & consts.py define payload formats
D. Agent Adapter (LangGraph)
• LanggraphStreamer implements the IStreamer interface
• message_parser parses incoming graph state messages
• stream_converter translates Graph events into protocol messages
E. LLM & Tools
• ChatOpenAI or other LLM provider
• External “tools” invoked via protocol (toolCalls)
F. External Systems
• Vercel-style client UI (useChat hook), other web frameworks
Relationships & data flow
1. Client → HTTP POST → FastAPI endpoint
2. FastAPI → instantiates LanggraphStreamer with agent + prompt + messages
3. LanggraphStreamer subscribes to agent events (calls LLM, tools)
4. Agent events → processed by message_parser & stream_converter → yield protocol chunks
5. AiChatDataStreamAsyncResponse wraps generator to send chunks over HTTP as SSE/chunked response
6. Client receives “{type}:{data}” stream → reassembles chat UI
Architectural patterns & design principles
• Adapter pattern: separate “agent” and “api” adapters conform to generic streamer interface
• Streaming pipeline: generator-based, pluggable conversion steps
• Single-responsibility: core protocol logic lives in ai_datastream/streamer & stream_parts; adapters focus on framework glue