OpenChatBI — Conversational BI Agent

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.

1. 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.
2. Business operations teams monitoring metric trends who need automated anomaly root-cause localization via Adtributor multi-dimensional drill-down.
3. 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.
4. 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.
5. Security-conscious deployments that need a fail-closed SQL guard, Docker-sandboxed code execution, audit logs, and HITL confidence gating.
6. Teams with accumulated approved SQL that want pattern memory and Golden SQL to feed high-quality examples into few-shot retrieval automatically.

What are this agent's strengths and limitations?

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:

1. Using uv (recommended):

git clone [email protected]:zhongyu09/openchatbi
uv sync

1. Using pip:

pip install openchatbi

1. For development:

uv sync --group dev

If 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?

1. 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).
2. 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).
3. Run the demo on the spider example dataset: python run_streamlit_ui.py.
4. 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"}})

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.