# openbb-finance/openbb-ai architecture

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

- Interactive diagram: https://gitdiagram.com/openbb-finance/openbb-ai
- Repository: https://github.com/openbb-finance/openbb-ai

## Overview

##### Project type and purpose
- This is an SDK/library, not a standalone application. It supplies:
- `openbb_ai.models` – Pydantic schemas (e.g., `QueryRequest`, `Widget`, etc.)
- `openbb_ai.helpers` – SSE-message factories (`message_chunk`, `reasoning_step`, `get_widget_data`, `table`, `chart`, `cite`, `citations`)
- `openbb_ai.testing` – testing utilities
- It packages these for distribution (see `pyproject.toml`), validated by unit tests under `tests/`, and uses GitHub Actions for CI (lint, test, publish).

##### File structure
- Top level:
- `.github/workflows/` – CI pipelines
- `pyproject.toml` – build & dependency definitions
- `README.md` – usage, feature list, integration examples
- Core package: `openbb_ai/` containing:
- `models.py` – Pydantic data models (entrypoint: `QueryRequest`)
- `helpers.py` – functions producing SSE events
- `testing.py` – test helpers
- `tests/` – unit tests for helpers & models
- No “frontend” or “backend” directories—this is a library to be embedded in a user’s agent service (e.g., a FastAPI app).

##### Extract key architectural insights from the README
- Agents are stateless: each HTTP request carries full context in a `QueryRequest`.
- Streaming via SSE: the library returns SSE‐formatted messages to be proxied to OpenBB Workspace.
- External interactions:
- OpenBB Workspace (client) initiates requests and consumes SSE.
- (Optionally) LLM providers under the hood (not part of this SDK).
- Widget data calls – SSE messages trigger callbacks in the Workspace UI to fetch widget data.

##### Main components
a. Consumer Service (e.g., FastAPI Application)
– Receives HTTP requests with a JSON body validated against `QueryRequest`.
– Imports `openbb_ai.models` for request parsing and `openbb_ai.helpers` for SSE events.
– Contains the agent’s logic and LLM calls (external).
b. OpenBB_AI SDK
– Models layer (`models.py`)
– Helpers layer (`helpers.py`)
– Testing utilities (`testing.py`)
– Packaging & CI (GitHub Actions, `pyproject.toml`)
c. OpenBB Workspace (External Client)
– Sends requests to the consumer service
– Listens to Server-Sent Events (text/event-stream)
– Renders messages, tables, charts, citations, and issues widget-data callbacks
d. External LLM Service (Optional)
– The model endpoint used by the agent logic (GPT-type API, etc.)
e. Widget Data Endpoint (part of Workspace)
– Invoked via `get_widget_data` SSE messages

##### Architectural patterns & design principles
- Stateless micro‐API: each call self‐contained
- SSE streaming pattern for real‐time UI updates
- Strong typing & validation via Pydantic models
- Separation of concerns: models ↔ helpers ↔ consumer application
- CI/CD: automated linting, testing, publishing using GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Service Layer
    subgraph "Consumer Service" 
        direction TB
        HTTP["HTTP Endpoint\nPOST /query"]:::consumer
        AgentLogic["Agent Logic"]:::consumer
        LLMClient["LLM Client"]:::consumer
    end

    %% OpenBB SDK Library
    subgraph "OpenBB_AI SDK" 
        direction TB
        Models["Models Layer"]:::sdk
        Helpers["Helpers Layer"]:::sdk
        TestingUtils["Testing Utilities"]:::sdk
        PackageInit["Package Init"]:::sdk
    end

    %% Packaging & CI
    subgraph "Packaging & CI" 
        direction TB
        PyProject["pyproject.toml"]:::ci
        Readme["README.md"]:::ci
        LintCI["Lint Pipeline"]:::ci
        TestCI["Test Pipeline"]:::ci
        PublishCI["Publish Pipeline"]:::ci
    end

    %% External Systems
    subgraph "External Systems" 
        direction TB
        Workspace["OpenBB Workspace"]:::external
        LLMAPI["LLM API Service"]:::external
        WidgetAPI["Widget Data API"]:::external
    end

    %% Data Flows
    Workspace -->|"HTTP POST /query (QueryRequest JSON)"| HTTP
    HTTP -->|"Validate JSON"| Models
    HTTP -->|"Import helpers"| Helpers
    HTTP -->|"Invoke logic"| AgentLogic
    AgentLogic -->|"LLM API Call (streamed response)"| LLMClient
    LLMClient -->|"stream"| LLMAPI
    LLMAPI -->|"stream"| LLMClient
    LLMClient -->|"pass to helpers"| Helpers
    Helpers -->|"SSE: message_chunk, reasoning_step, table, chart, cite"| Workspace
    Helpers -->|"get_widget_data event"| Workspace
    Workspace -->|"Widget Data Callback"| WidgetAPI
    WidgetAPI -->|"JSON data"| HTTP
    HTTP -->|"SSE resume"| Helpers

    %% Click Events for SDK
    click Models "https://github.com/openbb-finance/openbb-ai/blob/main/openbb_ai/models.py"
    click Helpers "https://github.com/openbb-finance/openbb-ai/blob/main/openbb_ai/helpers.py"
    click TestingUtils "https://github.com/openbb-finance/openbb-ai/blob/main/openbb_ai/testing.py"
    click PackageInit "https://github.com/openbb-finance/openbb-ai/blob/main/openbb_ai/__init__.py"

    %% Click Events for Packaging & CI
    click PyProject "https://github.com/openbb-finance/openbb-ai/blob/main/pyproject.toml"
    click Readme "https://github.com/openbb-finance/openbb-ai/blob/main/README.md"
    click LintCI "https://github.com/openbb-finance/openbb-ai/blob/main/.github/workflows/lint.yml"
    click TestCI "https://github.com/openbb-finance/openbb-ai/blob/main/.github/workflows/test.yml"
    click PublishCI "https://github.com/openbb-finance/openbb-ai/blob/main/.github/workflows/publish.yml"

    %% Legend Styles
    classDef sdk fill:#cce5ff,stroke:#999,stroke-width:1px
    classDef consumer fill:#d4edda,stroke:#999,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#999,stroke-width:1px
    classDef ci fill:#f0f0f0,stroke:#999,stroke-width:1px
```
