# elementary-data/py-ai-datastream architecture

> Architecture diagram of the GitHub repository elementary-data/py-ai-datastream, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elementary-data/py-ai-datastream
- Repository: https://github.com/elementary-data/py-ai-datastream

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client"
        ClientUI["Client UI\n(useChat hook)"]:::client
    end

    subgraph "API Layer (FastAPI)"
        FastAPIApp["FastAPI App"]:::api
        FastApiRequest["FastApiDataStreamRequest"]:::api
        AsyncResponse["AiChatDataStreamAsyncResponse"]:::api
    end

    subgraph "Core Streaming Engine"
        CoreStreamer["CoreStreamer"]:::core
        StreamParts["StreamParts"]:::core
        Messages["Messages"]:::core
        Consts["Consts"]:::core
    end

    subgraph "Agent Adapter (LangGraph)"
        LangStreamer["LanggraphStreamer"]:::agent
        Parser["MessageParser"]:::agent
        Converter["StreamConverter"]:::agent
    end

    subgraph "LLM & Tools"
        LLM["ChatOpenAI"]:::external
        Tools["External Tools"]:::external
    end

    ClientUI -->|"POST /ai/chat {messages}"| FastAPIApp
    FastAPIApp -->|"uses request type"| FastApiRequest
    FastAPIApp -->|"returns response"| AsyncResponse
    FastAPIApp -->|"init streamer"| LangStreamer
    LangStreamer -->|"subscribe events"| LLM
    LLM -->|"toolCalls"| Tools
    LangStreamer -->|"LangGraph events"| Parser
    Parser --> Converter
    Converter --> CoreStreamer
    CoreStreamer --> StreamParts
    CoreStreamer --> Messages
    CoreStreamer --> Consts
    CoreStreamer -->|"type:data chunks"| AsyncResponse
    AsyncResponse -.->|"stream chunks"| ClientUI

    click FastApiRequest "https://github.com/elementary-data/py-ai-datastream/blob/main/ai_datastream/api/fastapi/types.py"
    click AsyncResponse "https://github.com/elementary-data/py-ai-datastream/blob/main/ai_datastream/api/fastapi/response.py"
    click CoreStreamer "https://github.com/elementary-data/py-ai-datastream/blob/main/ai_datastream/streamer.py"
    click StreamParts "https://github.com/elementary-data/py-ai-datastream/blob/main/ai_datastream/stream_parts.py"
    click Messages "https://github.com/elementary-data/py-ai-datastream/blob/main/ai_datastream/messages.py"
    click Consts "https://github.com/elementary-data/py-ai-datastream/blob/main/ai_datastream/consts.py"
    click Parser "https://github.com/elementary-data/py-ai-datastream/blob/main/ai_datastream/agent/langgraph/message_parser.py"
    click Converter "https://github.com/elementary-data/py-ai-datastream/blob/main/ai_datastream/agent/langgraph/stream_converter.py"
    click LangStreamer "https://github.com/elementary-data/py-ai-datastream/blob/main/ai_datastream/agent/langgraph/streamer.py"

    classDef client fill:#cccccc,stroke:#333,stroke-width:1px
    classDef api fill:#bae1ff,stroke:#333,stroke-width:1px
    classDef core fill:#b8e986,stroke:#333,stroke-width:1px
    classDef agent fill:#ffcc80,stroke:#333,stroke-width:1px
    classDef external fill:#d7bde2,stroke:#333,stroke-width:1px
```
