OpenChatBI: a LangGraph text2sql agent with a separate analysis sub-agent

The gap OpenChatBI is aimed at: warehouse questions that are not single SQL statements

Most text2sql tooling stops at one query. You ask a question, the model writes SELECT, you get rows. OpenChatBI is built for the questions that arrive after that: why did this metric move, is this week's number anomalous, which dimension contributed the change. The README frames the project as a chat-based BI tool where the main agent can delegate to a specialized sub-agent that orchestrates text2sql, time series forecasting, anomaly detection, multi-dimensional drill-down via Adtributor, and Python execution. That delegation is the product thesis. The intended user is someone with warehouse credentials and an LLM API key who wants an analyst-facing chat surface, not a library author wiring up their own agent graph. Two sample UIs ship (Gradio and Streamlit), which tells you the project expects you to look at it in a browser rather than through a Python API.

Two agents, one graph: how the main agent and the analysis sub-agent divide work

The main agent handles conversation and schema-aware SQL generation. Retrieval over the data catalog is what feeds it: the README describes automatic discovery and indexing of table structures, with catalog storage backends supporting vector-based or BM25-based retrieval, plus business explanations for tables and columns that you maintain and that feed prompt optimization. The sub-agent is a different construction. It is built on deepagents, the LangChain project, and the README says the main agent delegates complex analysis to it. It can optionally use a dedicated analysis_llm, which is the practical lever if you want a stronger or cheaper model for the analysis path than for chat. The README points to openchatbi/analysis/README.md for the agent and the underlying anomaly detection and Adtributor algorithms, so the algorithmic detail lives in that file rather than the top-level one. Persistence sits on LangGraph checkpointing, covering conversation management and user characteristic memory, and the README notes memory tools do not work without an embedding model configured.

Configuring a warehouse, an LLM and a result limit in config.yaml

Installation is three paths: uv sync from a clone, pip install openchatbi, or uv sync --group dev for development. The demo copies example/config.yaml to openchatbi/config.yaml and substitutes your OpenAI key, then runs python run_streamlit_ui.py. For a real deployment you copy openchatbi/config.yaml.template instead. The config is YAML with a default_llm key naming the active provider, an llm_providers map whose entries carry a class string and a params block (the README's example uses langchain_openai.ChatOpenAI with model, temperature and max_tokens, and langchain_openai.OpenAIEmbeddings for the optional embedding_model), and a separate warehouse block. That warehouse block is where the project's scope becomes concrete: organization, dialect, and a data_warehouse_config with a uri, include_tables and database_name. The README example uses dialect: presto and a presto:// URI. Text2SQL results are limited by default, and the README says you can adjust or disable that limit in config.yaml, which matters because an unbounded result set goes straight into the agent context.

Where the README itself says the project is not finished

The roadmap is unusually direct. All three of its items are marked as initial versions being refined toward production readiness: the time series anomaly detection algorithm, the Adtributor-based multi-dimensional drill-down for root cause, and the data analysis agent's end-to-end orchestration, where the stated open problems are robustness, data hand-off between tools, and overall quality. Read that as the author's own assessment, not a reviewer's guess. The practical consequence is that the delegation path is the least settled part of the system. If your use case is question to SQL to a table or a plotly chart, you are on the mature path. If your use case is automated anomaly investigation feeding a report, you are on the path the author says is still being iterated. There is also a version boundary worth noting: v0.3.0 upgraded the runtime to LangGraph v1, the project targets langgraph>=1.2.2, and the README tells you to use v0.2.2 or earlier if you do not want that dependency. That is a clean escape hatch, but it also means older documentation and examples may not match the current graph.

Python 3.12 changes Chinese retrieval, and no embedding model changes memory

Two constraints deserve attention because both fail quietly. First, jieba is used for Chinese word segmentation for better Chinese text retrieval, and the README states it is not compatible with Python 3.12 or higher. On 3.12+, the system automatically falls back to simple punctuation-based segmentation. Nothing errors. Retrieval quality for Chinese content just drops. Second, the embedding_model section is optional, and without it the README says BM25 retrieval is used automatically and the memory tools will not work. So a deployment that skips embeddings still answers questions but loses persistent user memory, which is easy to miss until someone asks why the assistant forgot context between sessions. Neither constraint is a design flaw exactly, but both are the kind of thing that surfaces weeks after rollout rather than during setup.

What OpenChatBI does that a plain text2sql prompt does not

The honest comparison is with the common alternative: a single prompt that stuffs a schema dump into the context window and asks a general-purpose model for SQL. That approach has no catalog index, so schema linking is whatever the model can infer from the dump. It has no separate retrieval step, so BM25 or vector search over table and column descriptions is absent. It has no place to record business explanations for a column, and no mechanism to delegate an ambiguous question to a sub-agent that can run code or a forecasting model. OpenChatBI adds all four: catalog indexing with selectable retrieval backend, maintainable table and column explanations, an interactive mode where the agent asks the user for missing context, and the analysis sub-agent. The cost of those additions is configuration surface and a heavier dependency graph. A one-file script with an API key is still the better tool if your questions are simple, your schema is small, and you never need the agent to say it does not have enough information.

Licence, maintenance and what an upgrade actually costs

The repository is MIT licensed, which permits commercial use and modification with the licence and copyright notice retained. That is the permissive end of the spectrum, and it means the usual copyleft questions about linking or distribution do not arise here. This is not legal advice, and if you are embedding the tool in a product you should have counsel read the actual LICENSE file rather than this summary. On maintenance, the release cadence visible in the material runs from v0.2.2 in March 2026 through v0.3.0 in May and v1.0.0b1 in July, with the last push in August 2026. The v0.3.0 release notes describe a runtime upgrade to LangGraph v1, which is the upgrade that costs the most: it drags in the LangChain 1.x ecosystem, and the README's own guidance for teams that cannot take that dependency is to stay on v0.2.2 or earlier. Budget for that as a real migration decision rather than a patch bump, and note that v1.0.0b1 is a beta, so the analysis features it introduces are not covered by a stable release contract.

Editorial conclusion

Adopt OpenChatBI if you already run a warehouse that its dialect setting covers, you are comfortable pinning langgraph>=1.2.2 and the LangChain 1.x ecosystem, and you want catalog retrieval plus a delegating analysis agent rather than a single text2sql prompt. Do not adopt it if you need production-grade anomaly detection or root-cause output today: the roadmap lists the anomaly detection algorithm, the Adtributor drill-down and the analysis agent itself as all still being refined toward production readiness. Before committing, verify three things in a clone: that your dialect appears in the dialect config and your warehouse URI connects, whether you will configure an embedding_model (without it the README says vector retrieval and the memory tools do not work), and which Python version you are on, because jieba is not compatible with 3.12+ and Chinese segmentation silently degrades to punctuation splitting there.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. zhongyu09/openchatbi on GitHub