OpenChatBI — Conversational BI Agent
An open-source chat-based BI tool powered by LLMs that lets users query, analyze, and visualize warehouse data through natural language — no SQL required.
- Source repo
- zhongyu09/openchatbi
- Stars
- ★ 671
- Last updated
- 2d ago
- License
- MIT
- Primary language
- Python
- FA score
- 66/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Data analysts who want to query Presto/PostgreSQL/MySQL warehouses in natural language and get back SQL, result tables, and charts without writing queries by hand.
- Not a fit if
- Users without warehouse credentials or a ready dataset
- Teams needing production-ready anomaly detection and root-cause analysis
- Source review
- 66/100 · Some gaps
What does this agent do, and when should you use it?
OpenChatBI is an open-source, chat-based business intelligence tool built on LangGraph v1 and the LangChain ecosystem, providing agent graphs and workflows for natural-language data analysis. Its multi-stage Text2SQL pipeline (information extraction, table selection, schema linking, SQL generation, execution, scoring, and an optional confidence gate) turns user questions into executed SQL, with Plotly-based visualization on top. Beyond text2sql, it ships a data analysis sub-agent built on deepagents that orchestrates time series forecasting, anomaly detection, and Adtributor multi-dimensional drill-down root cause analysis, plus sandboxed Python code execution. The system includes a data catalog with file-system or SQLAlchemy database backends and vector or BM25 retrieval, persistent conversation memory, MCP tool integration, and sample Streamlit/Gradio UIs with a FastAPI async API. An optional agent harness adds audit logging, Langfuse tracing, HITL confidence gating, SQL error recovery, learned SQL memory, and an evaluation toolchain — all off by default. Licensed under MIT, it requires Python 3.11+, an LLM provider API key, and data warehouse credentials.
OpenChatBI accepts natural-language questions and processes them through the LangGraph graph returned by get_default_graph(): an llm_node dispatches tools including text2sql, data_analysis, run_python_code, search_knowledge, show_schema, memory_tools, and mcp_tools, proactively asking the user for context via an AskHuman tool when information is incomplete. The Text2SQL graph runs information_extraction, table_selection, generate_sql, execute_sql, score_sql, and generate_visualization steps, with an optional confidence gate that pauses low-confidence SQL for user approval. The data catalog automatically discovers and indexes warehouse table structures, supplying business semantics for tables/columns and derived metric formulas to schema linking; the data analysis sub-agent orchestrates text2sql, time series forecasting (via a separate forecasting service), anomaly detection, Adtributor drill-down, and Python execution. Outputs include system-generated SQL, query results, and Plotly charts, delivered through Streamlit/Gradio UIs, a CLI (run_cli.py), or the FastAPI async API.
- Data analysts who want to query Presto/PostgreSQL/MySQL warehouses in natural language and get back SQL, result tables, and charts without writing queries by hand.
- Business operations teams monitoring metric trends who need automated anomaly root-cause localization via Adtributor multi-dimensional drill-down.
- Data platform teams building a catalog-driven Text2SQL capability, maintaining table/column business descriptions, SQL rules, and derived metrics to improve generation quality over time.
- Engineering teams embedding conversational BI into their own web apps, reusing the Streamlit/Gradio samples or the FastAPI interface in sample_api/async_api.py.
- Security-conscious deployments that need a fail-closed SQL guard, Docker-sandboxed code execution, audit logs, and HITL confidence gating.
- Teams with accumulated approved SQL that want pattern memory and Golden SQL to feed high-quality examples into few-shot retrieval automatically.
How do you install or deploy this agent?
Prerequisites: Python 3.11+ (note jieba is incompatible with 3.12+, which falls back to punctuation-based Chinese segmentation), an LLM provider API key, and data warehouse credentials; Docker and an embedding model are optional (BM25 retrieval is used automatically without embeddings). Installation:
- Using uv (recommended):
git clone [email protected]:zhongyu09/openchatbi
uv sync- Using pip:
pip install openchatbi- For development:
uv sync --group devIf you don't want LangGraph v1, use OpenChatBI v0.2.2 or earlier. Install drivers as needed: pip install openchatbi[mysql], [postgresql], [azure-openai], [google-vertex-ai], [bedrock], [huggingface], [deepseek], or [ollama].
How do you use this agent?
- Create a config: cp openchatbi/config.yaml.template openchatbi/config.yaml, or use the example (cp example/config.yaml openchatbi/config.yaml) and substitute your key (sed -i 's/YOUR_API_KEY_HERE/[YOUR OPENAI API KEY]/g' openchatbi/config.yaml).
- In config.yaml, configure default_llm and llm_providers (e.g., langchain_openai.ChatOpenAI), optional embedding_model and text2sql_llm, plus data_warehouse_config (uri, include_tables, database_name).
- Run the demo on the spider example dataset: python run_streamlit_ui.py.
- Invoke programmatically:
export CONFIG_FILE=YOUR_CONFIG_FILE_PATH
from openchatbi import get_default_graph
graph = get_default_graph()
graph.invoke({"messages": [{"role": "user", "content": "Show me ctr trends for the past 7 days"}]}, config={"configurable": {"thread_id": "1"}})- Alternatively use the CLI (python run_cli.py), Streamlit UI (streamlit run sample_ui/streamlit_ui.py), or Gradio UI (python sample_ui/streaming_ui.py). For time series forecasting, build and run the separate timeseries_forecasting service (./build_and_run.sh) and set timeseries_forecasting_service_url in the config.
What are this agent's strengths and limitations?
- Text2SQL is a multi-stage workflow (information extraction, table selection, schema linking, generation, execution, scoring) backed by a maintainable data catalog with table/column semantics, SQL rules, and derived metrics — not a single-shot prompt.
- Differentiated analytics built in: a deepagents-based data analysis sub-agent orchestrates time series forecasting, anomaly detection, and Adtributor root-cause drill-down, going beyond simple question-answering.
- Strong engineering posture: HITL confidence gating, a fail-closed SQL guard, Docker-sandboxed code execution, audit logging, Langfuse tracing, RunLedger deterministic replay evals, and an LLM-as-Judge evaluation flow.
- Highly pluggable: multi-provider LLM support via LangChain, automatic vector/BM25 retrieval fallback, and catalog storage switchable between file system and SQLAlchemy databases with a migration script.
- Non-trivial runtime requirements: Python 3.11+, an LLM API key, warehouse credentials, and a separately deployed Dockerized forecasting service for time series features.
- jieba Chinese segmentation is unavailable on Python 3.12+, degrading to punctuation-based segmentation that may hurt Chinese text retrieval quality.
- Anomaly detection, root cause analysis, and the data analysis agent are initial versions; the roadmap explicitly states they are still being refined toward production readiness.
- Advanced harness features (confidence gate, learned memory, Golden SQL, observability) are all off by default and must be enabled individually in config.yaml; the regex-based SQL guard is an interim control, and the README advises always connecting with a read-only, non-superuser warehouse account.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| OpenChatBI — Conversational BI Agent This agent | 66 · Some gaps | Library / SDKFree + model costs | ★ 671 | 2d ago | Python | OpenAI API · Claude API |
| PyOD 3: Agentic Anomaly Detection Library | 52 · Major gaps | Library / SDKFree | ★ 10k | 11d ago | Python | Codex · Claude Code |
| Nixtla TimeGPT-1 | Insufficient evidence | Library / SDKFree + model costs | ★ 4k | 2d ago | Jupyter Notebook | — |
| DATAGEN Research Assistant | 44 · Major gaps | CLIFree + model costs | ★ 1.8k | 21d ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Least privilege: SQL result row limits by default, opt-in fail-closed SQL guard, read-only account advice — good, minus one because the guard is regex-based and fail-open by default. User confirmation: HITL confidence gate (approve/reject/edit) exists but is off by default. Data flow transparency: architecture diagrams and explicit separation of catalog DB vs warehouse config are clear. Sensitive data: audit log masks SQL literals by default, but handling of warehouse credentials in config.yaml is not thoroughly documented. Dependency security: sensible version ranges but no lockfile audit or dependency scanning evidence. External effects: three code-executor tiers (local/RestrictedPython/Docker) exist, but the default mode and its isolation strength are not confirmed in evidence — notable deduction. Rollback: no migration rollback or state rollback documented. Source attribution: MIT license and named author (Yu Zhong), but unverified publisher and no third-party attribution notices.
Self-consistency: README and pyproject (1.0.0b1, LangGraph v1 requirement, jieba/Py3.12 incompatibility) align, though README contains a typo ('sample_ui streamlit_ui.py'). Dependency availability: explicit version floors, optional extras, and a BM25 fallback degradation path are well handled. Failure messages: SQL error classification with recovery strategies and retry budgets is described, but concrete error text and user-visible messages are not shown in evidence.
Audience and scenarios: developer/analyst/end-user classifiers, multiple LLM providers and dialects, CLI/API/two UIs — full marks. Capability boundaries: roadmap honestly marks sub-agent features as 'initial version toward production readiness', but boundaries rely mainly on self-declaration. Trigger precision: agent and text2sql graphs show routing/interrupt logic, but no evidence of tool-selection precision tests. Environment fit: Python 3.11+, multi-OS install instructions, jieba degradation — adequate; Docker optional.
Information architecture: file-level project tree — full marks. Install notes: uv/pip/dev paths, optional SQLite build guidance, extras documented. Naming stability: 1.0.0b1 beta; API in flux (LangGraph v1 upgrade requires downgrade to v0.2.2). Examples and FAQ: demo config, melted-data tests, evals flow, but no FAQ section. Known limitations: jieba 3.12+ incompatibility, guard false-rejection risk, candid roadmap — full marks. License: full MIT text present. Versioning/changelog: no CHANGELOG evidence, version number only — clear deduction. Maintenance responsibility: single maintainer, no governance or contributor agreement evidence, publisher unverified.
Output usability: plotly visualization, show_schema, save_report tools and streaming UIs adequately described. Marginal value: catalog management, confidence gate, golden SQL and Adtributor form a differentiated bundle vs. hand-rolling LangChain, but most are optional switches and self-rated beta. Cost benefit: token/cost metrics, optional dedicated analysis_llm, selectable executors; no measured cost data.
Claim traceability: most README claims map to file paths (analysis/README, evals/judge/README, migrate.py) and the structure tree. Cross-source corroboration: pyproject deps/versions/extras match README; tests corroborate Adtributor and agent-graph claims — however core safety claims (audit, confidence gate, golden SQL) lack corresponding tests in evidence. Fact/inference separation: roadmap explicitly distinguishes 'initial version' from 'production readiness' — honest and full marks.
- The SQL guard is fail-open by default and regex-based; it may miss dangerous patterns or reject valid dialect SQL — always connect with a read-only, non-superuser warehouse account.
- The default code-execution mode is not confirmed in evidence; explicitly configure the Docker executor in production rather than local execution.
- Safety/quality features (HITL confidence gate, audit log, golden SQL) are off by default and must be explicitly enabled in config.yaml before deployment.
- Documentation of warehouse credential handling in config.yaml is insufficient — watch for credential leakage.
- Single-maintainer beta (1.0.0b1) with no changelog; breaking changes like the LangGraph v1 upgrade require your own evaluation. This is a static review with no executed verification.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
OpenChatBI v1.0.0b1 OpenChatBI 1.0.0 Beta 1(v1.0.0b1) is the first beta release toward 1.0, introducing a much stronger agent foundation for data analysis workflows. This release adds the new Data Analysis Agent, anomaly detection, and Adtributor root-cause analysis, while also improving agent observability, human-in-the-loop behavior, memory, and evaluation infrastructure. The release also expands SQL evaluation capabilities, adds a SQLAlchemy-backed catalog store, improves judge scripts and evaluation cases, resolves mypy type issues, and introduces optional extras for LLM providers. …View on GitHub ↗ -
v0.3.0 0.3.0 - Upgrade agent runtime to LangGraph v1
Release notes excerpt
OpenChatBI has upgraded its agent runtime to LangGraph v1 and currently targets langgraph==1.1.10. This upgrade also brings in the LangChain 1.x ecosystem and related compatibility changes. If you do not want to depend on LangGraph v1, please use OpenChatBI v0.2.2 or an earlier release. Highlights: 1. Upgrade langgraph to v1(1.1.10) 2. Add SQL safety validation before Text2SQL execution 3. Text2SQL graph enhancement Full Changelog: https://github.com/zhongyu09/openchatbi/compare/v0.2.2...v0.3.0View on GitHub ↗ -
v0.2.2 0.2.2 - Maintenance release for security and stablity
Release notes excerpt
What's Changed * feat: implement multi-provider support for LLM configuration and usage by @OrMullerHahitti in https://github.com/zhongyu09/openchatbi/pull/6 * Add optional RunLedger replay suite by @ZackMitchell910 in https://github.com/zhongyu09/openchatbi/pull/8 * Add cache validation in create_vector_db by @zhongyu09 in https://github.com/zhongyu09/openchatbi/pull/9 * fix: restrict file formats in save_report tool to enhance security by @zhongyu09 in https://github.com/zhongyu09/openchatbi/pull/12 New Contributors …View on GitHub ↗