Obai

💡 New here? Check the FAQ — covers when to start a new conversation, cost expectations, and which agent handles what.

Quick Demo

The Central Hub understands your intent, dispatches to the right specialists simultaneously (agents-as-tools pattern, not handoffs), and merges everything into one coherent answer.

Architecture

The Hub receives a query, runs input guardrails, then dispatches to multiple specialists in parallel (agents-as-tools pattern, not handoffs). Each agent calls its MCP server over streamable-http. Results flow back to the synthesizer. Opik (self-hosted) traces every span end-to-end and scores the final output. The Hub uses gpt-5.6-sol for routing and synthesis, the Strategy Agent uses gpt-5.1 for stronger backtest reasoning, and the remaining specialists use gpt-5-mini. The Research Agent adds deep qualitative analysis via Exa semantic search. The Prediction Markets Agent covers Polymarket with executable pricing, trade memos, wallet tracing, and setup-based backtesting. The Crypto Agent covers Coinbase spot markets with quotes, order books, OHLCV, and execution-grade spot backtests plus paper-ledger artifacts.

Why These Data Providers

FMP is the backbone -- it is not free, but a single subscription powers almost the entire system.

Prerequisites

• Python 3.12+
• uv -- install uv
• Docker + Docker Compose v2 -- Docker Engine (Linux) or Docker Desktop (macOS/Windows)

API Keys Required

No key needed: crypto-server (Coinbase Advanced Trade) and prediction-markets-server (Polymarket) use public market data only — no API key or account required.

Install

One-line install

curl -fsSL https://openbell.ai/install.sh | bash

Checks prerequisites, clones OBaI to ~/.local/share/obai, prompts for API keys, starts all services (including the web UI), and installs the obai CLI. Then chat with OBaI:

• Web UI (recommended): open http://127.0.0.1:8090 in your browser
• Terminal: run obai chat

Stop, restart, or upgrade later — the obai CLI now drives its own lifecycle, from any directory:

obai stop          # stop everything (Docker images and your data are preserved)
obai start         # bring it back up
obai restart       # stop, then start
obai upgrade       # pull the latest version and restart on it (prompts first; -y to skip)

obai upgrade fetches the latest release, re-pulls the versioned Docker images, and restarts the services and web UI automatically. The underlying ./setup.sh / ./teardown.sh scripts still work if you prefer running them from ~/.local/share/obai.

Install from source

git clone https://github.com/sixteen-dev/obai.git
cd obai

# Set your API keys (add to ~/.bashrc or ~/.zshrc for persistence)
export OPENAI_API_KEY=sk-proj-...
export FMP_API_KEY=...
export MASSIVE_API_KEY=...     # optional
export TAVILY_API_KEY=...      # optional
export EXA_API_KEY=...         # optional

./setup.sh         # one-shot setup: prereqs, Docker services, CLI, web UI

Then chat with OBaI:

• Web UI (recommended): open http://127.0.0.1:8090 in your browser
• Terminal: run obai chat

Stop, restart, or upgrade — use the obai CLI (or the ./teardown.sh / ./setup.sh scripts from the repo root):

obai stop          # stop everything (data preserved)
obai start         # start it back up
obai restart       # stop, then start
obai upgrade       # fast-forward your current branch and restart on it

Source checkouts are never reset. obai upgrade only fast-forwards your current branch when it is clean and strictly behind origin; if you have local commits or uncommitted changes it refuses and tells you what to do, so it will never clobber your work. (One-liner installs at ~/.local/share/obai track the release branch and upgrade turnkey.)

The setup script:

1. Checks prerequisites (Docker, Python 3.12+, uv, git)
2. Validates required API keys from your shell environment
3. Creates ~/.obai/ config directory with default preferences
4. Starts Opik tracing stack (self-hosted, Docker Compose)
5. Builds and starts all 10 MCP servers (Docker Compose)
6. Installs the obai CLI globally via uv tool install
7. Launches the Web UI (FastAPI on port 8090)
8. Configures Opik SDK for local tracing

Pinning a Version

OBaI uses GitHub Releases for versioned snapshots. To install a specific version:

git checkout v1.5.5
./setup.sh

To update to latest: obai upgrade (or git checkout main && git pull && ./setup.sh).

Running the System

Lifecycle is handled by the obai CLI — obai start to start, obai stop to stop (your data is preserved), obai restart to cycle, and obai upgrade to pull the latest version and restart. The ./setup.sh / ./teardown.sh scripts do the same thing and remain available. To check that all ten servers are healthy:

obai status

If a query fails with a connection error, run obai status, then obai start to bring anything back up.

The MCP servers run under the Docker Compose project obai (Opik under obai-opik). From the repo root:

docker compose -p obai ps                                           # list running servers
docker compose -p obai logs -f market-data-server                   # tail one server's logs
docker compose -p obai restart                                      # restart all MCP servers
docker compose -p obai up -d                                        # start just the MCP servers
docker compose -p obai-opik -f infra/opik/docker-compose.yml up -d  # start just Opik

CLI Usage

# Single query (streams response to stdout)
obai query "What is AAPL trading at?"

# JSON output (for piping to other tools)
obai query "AAPL fundamentals" --json

# Named session for multi-turn conversation
obai query "What is AAPL's P/E ratio?" --session research1
obai query "How does that compare to MSFT?" --session research1

# Interactive REPL
obai chat

# Check MCP server connectivity
obai status

MCP Servers

All servers use FastMCP with streamable-http transport, running inside Docker containers on a shared bridge network (obai-mcp-network).

Strategy Agent

The Strategy Agent is OBaI's quantitative researcher. Unlike other specialists that answer questions, the Strategy Agent builds, tests, and iterates on trading strategies autonomously.

How it works: You describe a hypothesis ("momentum strategy for AAPL and MSFT") and the agent:

1. Converts your idea into a structured strategy JSON (indicators, entry/exit rules, position sizing, risk management)
2. Runs a backtest via the backtest-server (Polars + polars-talib engine, DuckDB storage)
3. Analyzes results (Sharpe, Sortino, CAGR, max drawdown, win rate, profit factor)
4. Iterates 3-5 times — adding filters, tuning parameters, refining exits
5. Validates the final candidate on out-of-sample data (train/test split)
6. Returns a verdict (accept, paper_trade, needs_more_research, reject) with the executable strategy JSON

> Design a mean-reversion strategy for AAPL, MSFT, and GOOGL

Strategy Agent workflow:
  Iteration 1: RSI oversold baseline         → Sharpe 0.82
  Iteration 2: Add Bollinger Band filter     → Sharpe 1.14
  Iteration 3: Tighten stop-loss from 5%→3%  → Sharpe 1.21, drawdown -8.2%
  Iteration 4: Parameter sensitivity check   → stable across ±10% range
  Iteration 5: Full-period validation        → Sharpe 1.08 (minor degradation, acceptable)

  Verdict: paper_trade
  Final strategy JSON: { ... }

The agent uses gpt-5.1 by default (not gpt-5-mini like other specialists) because strategy design requires strong reasoning — metric interpretation, overfitting detection, and parameter sensitivity analysis.

Backtest server tools: run_strategy, get_job_status, get_supported_indicators, download_data, list_available_data, get_trade_log, compare_strategies, clear_cache

Web UI

OBaI ships a browser-based client with a dark glassmorphism interface:

• Real-time streaming via WebSocket
• Session management with persistent conversation history
• Live agent activity panel showing tool calls and specialist routing
• Portfolio preferences and Opik trace links in settings

obai web                  # Launch on http://127.0.0.1:8090
obai web --port 3000      # Custom port

The web UI is automatically started by setup.sh. It runs a single-process FastAPI/uvicorn server with minimal resource overhead — the heavy computation happens in the MCP servers (Docker) and the OpenAI API (remote).

TUI

OBaI includes a Textual-based Terminal UI with:

• Collapsible conversation history
• Hierarchical tool call display (see which agents were invoked)
• Streaming markdown responses
• Toggle-able debug panel

# From repo root
cd src/obai
uv run python -m clients.cli.tui

Observability & Evaluation

OBaI uses Opik (self-hosted, open source) for end-to-end tracing and evaluation. Every query generates a full trace you can inspect in the Opik UI at http://localhost:5173.

What Opik Shows You

Each trace captures the complete execution graph:

• Agent routing — which specialists the Hub dispatched to and why
• Tool calls — every MCP tool invoked (function name, arguments, response), nested under the agent that called it
• Timing — latency breakdown per agent and per tool call, so you can spot bottlenecks
• Token usage — input/output tokens per LLM call across the entire query
• Span hierarchy — Hub → Agent → MCP Tool, fully nested and expandable

Custom Evaluation Metrics

OBaI registers custom scorers with Opik that run on every traced query:

Running Evaluations

# From repo root
cd src/obai

# Trace a single query (inspect in Opik UI afterward)
uv run python -m evaluation query "What is AAPL trading at?" --verbose

# Run evaluation with all scorers
uv run python -m evaluation evaluate "What is AAPL trading at?"

# Run the full test suite (176 cases, categories: A/B/C/D/E/G/H)
uv run python -m evaluation evaluate --suite

# Fast mode — skip LLM judge, just faithfulness + completeness
uv run python -m evaluation evaluate --suite --no-builtin

# Export markdown report
uv run python -m evaluation evaluate --suite --report results.md

Opik Setup

Opik runs as a Docker Compose stack (ClickHouse + backend + frontend). The setup.sh script handles this automatically, or run it manually:

./infra/opik/setup-volumes.sh
docker compose -f infra/opik/docker-compose.yml up -d

Dashboard: http://localhost:5173 | Project: obai-eval

Configuration

Key environment variables (all have sensible defaults):

Per-agent model overrides are also available: MARKET_DATA_MODEL, FUNDAMENTALS_MODEL, EVENTS_NEWS_MODEL, OPTIONS_MODEL, SCREENER_MODEL, PORTFOLIO_MODEL, STRATEGY_MODEL, RESEARCH_MODEL, PREDICTION_MARKETS_MODEL.

User Preferences

OBaI stores personal preferences in ~/.obai/preferences.json. These persist across sessions and are used by agents to tailor responses and backtests to your profile.

Update via chat — just tell OBaI in conversation:

> Set my initial capital to 50000
> Change my risk tolerance to aggressive
> What are my current preferences?

The agents use get_preferences and set_preferences tools automatically.

Update manually — edit ~/.obai/preferences.json directly:

{
  "risk_tolerance": "moderate",
  "investment_horizon": "medium",
  "default_benchmark": "SPY",
  "initial_capital": 50000,
  "currency": "USD",
  "market": "US"
}

Project Structure

obai/
├── setup.sh                        # One-shot setup script
├── docker-compose.yml              # All 10 MCP servers
├── pyproject.toml                  # Monorepo dev tooling config
├── infra/
│   └── opik/                       # Opik tracing stack (Docker Compose)
├── src/
│   ├── fundamentals-server/        # MCP server — financials, ratios, vector search
│   ├── market-data-server/         # MCP server — prices, technicals
│   ├── events-news-server/         # MCP server — news, earnings, dividends
│   ├── options-server/             # MCP server — options chains, Greeks
│   ├── screening-server/           # MCP server — stock screening
│   ├── portfolio-server/           # MCP server — portfolio analysis, ETF holdings
│   ├── backtest-server/            # MCP server — strategy backtesting
│   ├── research-server/            # MCP server — qualitative research (Exa)
│   ├── prediction-markets-server/  # MCP server — Polymarket analysis (no API keys)
│   ├── crypto-server/              # MCP server — Coinbase spot crypto (no API keys)
│   └── obai/                       # Core application
│       ├── pyproject.toml          # OBaI package config
│       ├── core_agents/            # Agent definitions + orchestration
│       │   ├── central_hub_agent.py
│       │   ├── base_agent.py
│       │   ├── config.py
│       │   ├── guardrails.py
│       │   ├── prompts/            # Markdown prompt files
│       │   └── *_agent.py          # 10 specialist agents
│       ├── clients/
│       │   ├── cli/                # CLI + TUI clients
│       │   │   ├── chat.py         # Headless CLI (obai query/chat/status)
│       │   │   └── tui.py          # Textual TUI
│       │   └── web/                # Browser client
│       │       ├── server.py       # FastAPI + WebSocket server
│       │       └── static/         # SPA (HTML, CSS, JS)
│       └── evaluation/             # Eval framework
│           ├── cli.py              # Evaluation CLI
│           ├── eval_runner.py      # Test runner
│           ├── scorers/            # Faithfulness, completeness, LLM-judge
│           ├── metrics/            # Metric definitions
│           ├── test_cases/         # Predefined test queries
│           └── trace/              # Trace capture utilities
└── tests/                          # Monorepo-level tests

Development

# All commands run from repo root

# Lint and fix
uv run ruff check . --fix

# Format
uv run ruff format .

# Type check (strict mode)
uv run mypy src/ --strict

# Run tests
uv run pytest

Agent Skills

OBaI ships with agent skills that let any AI agent autonomously interact with the system:

OBaI Query Skill — Read-only financial research. The agent runs obai query commands directly, manages sessions, parses JSON responses, and presents answers. Ask any financial question and it routes to the right specialist automatically.

OBaI MCP Skill Suite — Direct-MCP alternative to the query skill for agents that support both skills and MCP (Claude Code, OpenClaw, etc.). Instead of going through the OBaI hub agent, the host agent itself plays the hub: the obai-hub skill routes intent and enforces grounding/synthesis rules, and ten specialist skills (obai-market-data, obai-fundamentals, obai-events-news, obai-options, obai-screening, obai-portfolio, obai-strategy, obai-research, obai-prediction-markets, obai-crypto) carry the curated specialist playbooks for each MCP server on its fixed port (8001–8010). Register the servers from skills/obai-hub/mcp-config.json. No OpenAI key needed — the host agent's model does the reasoning.

AutoTrader Skill — Autonomous paper trading bot on Alpaca. Combines OBaI analysis (read-only) with Alpaca execution (trades) to manage a stock portfolio. Evaluates strategy signals against deployed strategies, executes trades with built-in risk checks (position sizing, exposure limits, daily loss caps), and maintains a trading journal. Requires ALPACA_API_KEY and ALPACA_SECRET_KEY.

Roadmap

Done

• FastMCP servers with pure MCP protocol (streamable-http)
• Real-time market data integration (FMP API)
• Multi-agent orchestration with OpenAI Agent SDK (agents-as-tools)
• Self-hosted local infrastructure (Docker Compose, no cloud dependency)
• CLI client (obai query, obai chat, obai status)
• Textual TUI with streaming markdown and agent activity
• Tavily-powered AI news search
• Options server (Massive.com — chains, Greeks, IV, open interest)
• Backtest engine (Polars + polars-talib, train/test split)
• Strategy Agent with autonomous iteration loop
• Opik tracing and custom evaluation scorers
• Input guardrails for non-financial query filtering
• Qdrant vector search over financial education PDFs (shipped; disabled by default)
• Research server — deep qualitative analysis via Exa semantic search
• DuckDB storage for backtest OHLCV data (replaced Parquet-per-symbol)
• Intraday timeframes (5min, 15min, 1hr bars) for backtest engine and market data
• AutoTrader skill — autonomous paper trading on Alpaca with risk management

Next

• Options strategy analysis and backtesting
• Polymarket prediction market analysis (11 tools, executable pricing, trade memos, wallet tracing)
• Crypto market analysis
• Semantic caching via LangCache (Redis)
• Web client (FastAPI + WebSocket, dark glassmorphism UI)

License

Commons Clause + Apache 2.0. Free for personal and non-commercial use. See LICENSE for details.