How openbb-finance/openbb-ai works
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