OpenChatBI

OpenChatBI is an open source, chat-based intelligent BI tool powered by large language models, designed to help users query, analyze, and visualize data through natural language conversations. Built on LangGraph and LangChain ecosystem, it provides chat agents and workflows that support natural language to SQL conversion and streamlined data analysis.

Join the Slack channel to discuss: Invitation Link To Join

Core Features

1. Natural Language Interaction: Get data analysis results by asking questions in natural language
2. Automatic SQL Generation: Convert natural language queries into SQL statements using advanced text2sql workflows with schema linking and well organized prompt engineering
3. Data Visualization: Generate intuitive data visualizations (via plotly)
4. Data Catalog Management: Automatically discovers and indexes database table structures, supports flexible catalog storage backends with vector-based or BM25-based retrieval, and easily maintains business explanations for tables and columns as well as optimizes Prompts.
5. Time Series Forecasting: In-house forecasting models, accessed through the data analysis agent (see feature 12)
6. Code Execution: Execute Python code for data analysis and visualization
7. Interactive Problem-Solving: Proactively ask users for more context when information is incomplete
8. Persistent Memory: Conversation management and user characteristic memory based on LangGraph checkpointing
9. MCP Support: Integration with MCP tools by configuration
10. Knowledge Base Integration: Answer complex questions by combining catalog based knowledge retrival and external knowledge base retrival (via MCP tools)
11. Web UI Interface: Provide 2 sample UI: simple and streaming web interfaces using Gradio and Streamlit, easy to integrate with other web applications
12. Data Analysis Agent: A specialized sub-agent (built on deepagents) that the main agent delegates complex analysis to. It orchestrates text2sql, time series forecasting, anomaly detection, multi-dimensional drill-down (Adtributor) and Python execution to cover trend forecasting, anomaly detection, anomaly root-cause drill-down, multi-metric correlation and business combination analysis. Optionally uses a dedicated analysis_llm. See openchatbi/analysis/README.md for the agent and the underlying anomaly detection / Adtributor algorithms.

Roadmap

1. Anomaly Detection Algorithm: Time series anomaly detection — initial version available via the data analysis agent; actively being refined toward production readiness.
2. Root Cause Analysis Algorithm: Multi-dimensional drill-down for anomaly investigation — initial Adtributor-based drill-down tool available; actively being refined toward production readiness.
3. Data Analysis Agent: End-to-end analysis orchestration — initial version available; iterating on robustness, data hand-off between tools, and overall quality to reach production readiness.

Getting started

Installation & Setup

Prerequisites

• Python 3.11 or higher
• Access to a supported LLM provider (OpenAI, Anthropic, etc.)
• Data Warehouse (Database) credentials (like Presto, PostgreSQL, MySQL, etc.)
• (Optional) Embedding model for vector-based retrieval - if not available, BM25-based retrieval will be used
• (Optional) Docker - required only for docker executor mode

Note on Chinese Text Segmentation: For better Chinese text retrieval, jieba is used for word segmentation. However, jieba is not compatible with Python 3.12+. On Python 3.12 and higher, the system automatically falls back to simple punctuation-based segmentation for Chinese text.

LangGraph Version Compatibility

OpenChatBI has upgraded its agent runtime to LangGraph v1 and currently targets langgraph>=1.2.2. 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.

Installation

1. Using uv (recommended):

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

2. Using pip:

pip install openchatbi

3. For development:

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

Optional: If you want to use pysqlite3 (newer SQLite builds), you can install it manually. If build fails, install SQLite first:

On macOS, try to install sqlite using Homebrew:

brew install sqlite
brew info sqlite
export LDFLAGS="-L/opt/homebrew/opt/sqlite/lib"
export CPPFLAGS="-I/opt/homebrew/opt/sqlite/include"

On Amazon Linux / RHEL / CentOS:

sudo yum install sqlite-devel

On Ubuntu / Debian:

sudo apt-get update
sudo apt-get install libsqlite3-dev

Run Demo

Run demo using example dataset from spider dataset. You need to provide "YOUR OPENAI API KEY" or change config to use other LLM providers.

Note: The demo example includes embedding model configuration. If you want to run without an embedding model, you can remove the embedding_model section in the config - BM25 retrieval will be used automatically.

cp example/config.yaml openchatbi/config.yaml
sed -i 's/YOUR_API_KEY_HERE/[YOUR OPENAI API KEY]/g' openchatbi/config.yaml
python run_streamlit_ui.py

Configuration

1. Create configuration file

Copy the configuration template:

cp openchatbi/config.yaml.template openchatbi/config.yaml

Or create an empty YAML file.

2. Configure your LLMs:

# Select which provider to use
default_llm: openai

# Define one or more providers
llm_providers:
  openai:
    default_llm:
      class: langchain_openai.ChatOpenAI
      params:
        api_key: YOUR_API_KEY_HERE
        model: gpt-5.5
        temperature: 0.02
        max_tokens: 8192

    # Optional: Embedding model for vector-based retrieval and memory tools
    # If not configured, BM25-based retrieval will be used, and the memory tools will not work
    embedding_model:
      class: langchain_openai.OpenAIEmbeddings
      params:
        api_key: YOUR_API_KEY_HERE
        model: text-embedding-3-large
        chunk_size: 1024

3. Configure your data warehouse:

organization: Your Company
dialect: presto
data_warehouse_config:
  uri: "presto://user@host:8080/catalog/schema"
  include_tables:
    - your_table_name
  database_name: "catalog.schema"

4. Configure SQL result limit:

Text2SQL query results are limited by default to avoid loading unbounded result sets into memory or the agent context. You can adjust the limit or disable it in config.yaml:

enable_sql_result_limit: true
sql_result_limit: 10000

5. Optionally enable the fail-closed Text2SQL SQL guard:

The application-layer SQL guard keeps its backward-compatible fail-open behavior by default after known dangerous patterns are rejected. Deployments that prefer stricter enforcement can opt in to the read-only allowlist:

enable_fail_closed_sql_guard: true

When enabled, only SELECT and WITH ... SELECT query shapes are allowed to reach the data warehouse. This regex-based guard is an interim defense-in-depth control and can reject valid dialect-specific read-only SQL. Always connect OpenChatBI with a read-only, non-superuser warehouse account; the guard does not replace database permissions. Parser-based validation of a single read-only statement is the planned hardening direction.

Running the Application

1. Invoking LangGraph:

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"}})

# System-generated SQL
SELECT date, SUM(clicks)/SUM(impression) AS ctr
FROM ad_performance
WHERE date >= CURRENT_DATE - 7 DAYS
GROUP BY date
ORDER BY date;

2. Sample Web UI:

Streamlit based UI:

streamlit run sample_ui streamlit_ui.py

Run Gradio based UI:

python sample_ui/streaming_ui.py

3. Command Line Interface (CLI):

export CONFIG_FILE=YOUR_CONFIG_FILE_PATH
python run_cli.py

Configuration Instructions

The configuration template is provided at config.yaml.template. Key configuration sections include:

Basic Settings

• organization: Organization name (e.g., "Your Company")
• dialect: Database dialect (e.g., "presto")
• bi_config_file: Path to BI configuration file (e.g., "example/bi.yaml")

Catalog Store Configuration

• `cata