openchatbi: LangGraph v1, a sub-agent, and three roadmap items already shipped

jieba does not work on Python 3.12, so the segmenter changes silently

There is one version-dependent behaviour change in this project and it is worth knowing before you deploy it. For better Chinese text retrieval, the project uses jieba for word segmentation, and the documentation states plainly that jieba is not compatible with Python 3.12 or newer.

What happens on 3.12 and above is that the system falls back automatically to simple punctuation-based segmentation for Chinese text. The fallback is not an error and there is no warning described, it just produces different token boundaries.

That matters because segmentation feeds retrieval. The data catalog feature supports either vector-based or BM25-based retrieval, and the embedding model is itself listed as optional, so the retrieval path has three independent fallbacks stacked on top of each other: no embedding model means BM25 instead of vectors, Python 3.12 means punctuation segmentation instead of jieba, and a Chinese query is the case where the segmenter difference is most visible.

Nothing in the configuration exposes which segmenter is active. If you deploy on 3.11 and 3.13 with the same config you get different retrieval behaviour, and the only way to find out which one you have is to check the Python version.

v0.2.2 is the last version that does not need LangGraph v1

The agent runtime was upgraded to LangGraph v1 and the project now targets langgraph at 1.2.2 or newer. That upgrade also brought in the LangChain 1.x ecosystem and the compatibility changes that go with it.

The escape hatch is stated in one line: if you do not want to depend on LangGraph v1, use OpenChatBI v0.2.2 or an earlier release.

So v0.2.2 is a pinned escape hatch rather than an ordinary old release, and it is also described as a maintenance release for security and stability. That release name carries a typo in the security and stablity wording, which is the kind of thing you notice when the pinned version is one you have to reason about carefully.

The base dependency list is where the size of that upgrade shows. It pins langgraph at 1.2.2 or newer and langchain at 1.3.2 or newer, and then adds five further packages from the same ecosystem: langchain-openai, langchain-anthropic, langchain-community, langgraph-checkpoint-sqlite and langchain-mcp-adapters. Two more come from adjacent projects, deepagents for the analysis sub-agent and langmem for the memory layer.

The release history explains the sequence: v0.2.2 in March 2026 was the maintenance release, v0.3.0 in May 2026 was the LangGraph v1 upgrade, and v1.0.0b1 in July 2026 was the first beta of the data analysis agent.

All three roadmap items already ship in an initial form

The roadmap has three entries and every one of them describes something that already works. The anomaly detection algorithm, the root cause analysis algorithm and the data analysis agent are each marked as an initial version available, with the refinement toward production readiness described as actively ongoing.

That is unusual framing for a roadmap and it changes what the document is. It is not a list of what is coming, it is a list of what is shipped but not finished, which is a more useful thing to have if you are deciding whether to depend on it.

The three differ in how close they are. Anomaly detection is described as time series anomaly detection with an initial version available through the data analysis agent. Root cause analysis is described as multi-dimensional drill-down for anomaly investigation, with an initial Adtributor-based drill-down tool available. The data analysis agent entry names its own remaining work more concretely: robustness, data hand-off between tools, and overall quality.

Data hand-off is the item that reads as the real risk. An agent orchestrating five tools will fail in the seams between them rather than inside any one of them, and the roadmap says so.

Feature twelve is a sub-agent the main one delegates to

Twelve features are listed, and the twelfth is a different kind of thing from the other eleven. The first eleven are capabilities: natural language interaction, automatic SQL generation, data visualisation through plotly, data catalog management, time series forecasting, code execution, interactive problem solving, persistent memory, MCP support, knowledge base integration and a web interface.

The twelfth is an agent. It is a specialised sub-agent built on deepagents that the main agent delegates complex analysis to, and it orchestrates five things: text2sql, time series forecasting, anomaly detection, multi-dimensional drill-down using Adtributor, and Python execution.

The scope it covers is named too: trend forecasting, anomaly detection, anomaly root-cause drill-down, multi-metric correlation and business combination analysis.

Two design details are worth pulling out. It can optionally use a dedicated model, configured separately as analysis_llm, which means you can route expensive reasoning to a different model from the one handling the conversational turn. And the implementation is not hidden: the agent and the underlying anomaly detection and Adtributor algorithms are documented in a README inside the package, at openchatbi/analysis/README.md.

The delegation boundary is what makes this more than a prompt. The main agent is not asked to do forecasting or drill-down itself, so a complex question is routed rather than answered badly.

The template config points at gpt-5.5 with a temperature of 0.02

The configuration section gives a complete provider block, and it is worth reading as a set of decisions rather than as a placeholder:

# 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:

The temperature is 0.02 and max_tokens is 8192. A temperature that low is a deliberate choice for text2sql, where a creative model is a liability, and it pairs with the SQL result limit described further down.

The embedding model sits in the same provider block rather than in a separate section, and its absence has a stated consequence: without it you get BM25 retrieval instead of vector retrieval, and the memory tools will not work. That is two features degrading from one missing field.

The provider classes are LangChain classes named directly, ChatOpenAI for the chat model and OpenAIEmbeddings for the embeddings, so switching provider is a matter of pointing at a different LangChain class rather than at a different SDK.

The data warehouse block is configured separately and takes an organisation name, a dialect, a URI, a database name and an include_tables list, which means you can restrict which tables the catalog indexes rather than exposing an entire warehouse.

SQL results are capped at ten thousand rows unless you turn the cap off

Two settings guard against a text2sql query returning something the agent cannot hold. There is a switch to enable the limit and a number for the limit itself, defaulting to enabled and to ten thousand.

The reason given is both memory and context: the point is to avoid loading unbounded result sets into memory or into the agent context. Since the agent's context is the scarce resource rather than the machine's memory, a query that returns a million rows does not crash the process, it just silently consumes the conversation budget.

There is a third guard listed separately and described as optional and fail-closed, which is the right default for a tool generating SQL against a real warehouse. The description of that one is cut off in the page, so what it does on failure is not visible here.

Together the three are the difference between a demo and something you point at production. A result cap, a guard on the generated SQL, and an include_tables list are the three things standing between a natural language question and an unintended write.

The classifier stops at Python 3.11 while the code documents 3.12 behaviour

The package metadata declares requires-python as 3.11 up to but not including 4.0, so any 3.11 or newer interpreter is allowed.

The trove classifiers then list only Programming Language :: Python :: 3 and Programming Language :: Python :: 3.11. There is no 3.12 or 3.13 classifier, even though the segmentation note explicitly describes what happens on 3.12 and higher.

So the project supports 3.12 in the version constraint and in the prose, and does not declare it in the classifier. Anything that filters Python packages by trove classifier rather than by requires-python will show this as a 3.11 package.

The rest of the classifier block is wider than the language one. There are three intended audience values, developers, science and research, and end users on the desktop, and six topic values covering business intelligence, database work, information analysis, office and business, Python modules and AI.

The release version in the manifest is 1.0.0b1 and the trove status is Beta, which matches a project whose newest tag is a beta from July while commits have continued to the day this article was written.

Two evaluation directories, one Dockerfile, and three launch scripts

The repository root is twenty-one entries and several of them describe testing and deployment rather than the product.

There are two separate evaluation directories, baselines/ and evals/, which is a distinction the twelve features never mention. A baselines directory suggests recorded results to compare against and an evals directory suggests the harness that produces them, and having both at the root rather than inside the package means they are meant to be run from outside.

There is one Dockerfile and it is named Dockerfile.python-executor, which ties directly to the optional Docker prerequisite listed only for the docker executor mode. A Python code execution feature in a sandbox is the reason a container exists here.

Then there are three launch scripts at the root: run_cli.py, run_streamlit_ui.py and run_tests.py. The streamlit one is the demo entry point, and the example directory beside it holds the configuration templates, the SQL examples, table and column CSV files, a table info YAML file and a tracking_orders.sqlite database to experiment against.

Forecasting is not inside the package. There is a timeseries_forecasting directory at the top level, which is what the in-house forecasting models in feature five refer to, and it sits outside openchatbi/ alongside the source.

Editorial conclusion

Use this if you have a warehouse and a model key and want natural language querying with a real analysis path behind it, since the text2sql side has schema linking and a delegated agent rather than a single prompt. Skip it if you need production readiness today, because the anomaly detection, root cause analysis and data analysis agent are all described on the roadmap as initial versions still being refined. Before you deploy, set the result cap deliberately and read what the fail-closed SQL guard does, and check your Python version, since 3.12 silently changes Chinese segmentation while the classifier still claims 3.11.

Frequently asked questions

Official sources

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