Langchain-Chatchat pins Python below 3.12, declares no dependencies, and has not been pushed since 2025-11-10

Python below 3.12 and one excluded patch release, both on a single line

The only entry under dependencies in pyproject.toml is the interpreter itself, and it is a constrained one: python = ">=3.8.1,<3.12,!=3.9.7". Two separate restrictions are packed into that string. The upper bound is 3.12, so a machine on 3.12 or anything newer is outside the range the project declares for itself, and one specific patch, 3.9.7, is excluded by name rather than by a range.

A named exclusion is unusual enough to be worth understanding rather than working around. It means somebody hit a problem specific to that build rather than to the 3.9 series, and the fix in the project was to refuse the interpreter instead of to work around it. That is the right call, and it also means the pin encodes history you cannot read from the code.

The consequence for deployment is that a current base image is a problem before your code is. Most container images built today ship a Python well past 3.12, so the first thing you meet is a constraint violation on a project that has not been pushed to since 2025-11-10. Choose the interpreter deliberately rather than inheriting it from the image you already use, and if you must run 3.12, that is a fork of the constraint rather than a configuration change.

pyproject.toml declares no dependencies, so the real set lives in libs/

Open the dependency table and there is one line in it, the Python constraint. No langchain, no FastAPI, no Streamlit, no embedding library, despite the project describing itself as built on langchain with a service exposed through FastAPI and an interface built on Streamlit. The top-level entries explain why: a libs/ directory, a .gitmodules file, and a poetry.toml next to pyproject.toml. The runtime dependency set is not in the file a packaging tool reads.

The README offers three routes into a running instance, and that is where the real instructions live: a pip installation route, a source installation and development route, and a Docker route. The development route points at docs/contributing/README_dev.md for contributors. So a reader is expected to assemble the environment from a guide rather than from the project metadata, which is the opposite of how a modern Python package is normally consumed.

Two things follow. First, you cannot create a working environment from pyproject.toml alone, and any tooling that tries will produce something that installs cleanly and does not run. Second, no lock file appears among the top-level entries next to pyproject.toml, so the exact versions of whatever the install step pulls are not pinned in the repository. For a project whose whole premise is reproducible offline deployment, that gap is the first thing to close on your side.

The primary package index is the Tsinghua mirror, not PyPI

The last block of pyproject.toml declares a poetry source named tsinghua, with the url https://pypi.tuna.tsinghua.edu.cn/simple/ and priority set to primary. A source with primary priority is consulted ahead of the defaults, so this line decides where dependencies are resolved from for everyone who installs the project.

The choice is sensible for the audience the project was built for, a Chinese knowledge base scenario with open source models, where the mirror is fast and reachable. It is also a supply chain decision that is one line long and easy to miss. A network that cannot reach that host either fails to resolve or falls back, and an organisation with an allowlist of package indexes now has one more entry to approve. Nothing in the file marks the mirror as optional or as a fallback for one region.

The consequence is worth stating plainly: before you audit anything else in this project, know that its default resolution path is a third-party index rather than the canonical one. If your policy is to install from an internal proxy, you override that source deliberately and record the override, because the alternative is that the override lives in someone's pip configuration and nobody reviewing the deployment can see it.

The repository records Apache-2.0 and pyproject.toml records MIT

Two files in this project name a licence and they do not agree. GitHub records the repository as Apache-2.0. The pyproject.toml metadata sets license = "MIT". The LICENSE file sits at the top level of the tree, and neither of the other two files is a copy of it.

There is a detail in pyproject.toml that decides how much the conflict matters. It sets package-mode = false, which means the project is not built or published as a distributable package. The name field reads Chatchat, the version field reads 0.3.0, and the readme field points at README.md, all of it is package metadata for something that is never packaged. A licence field in a file whose packaging is switched off is a leftover rather than a distribution statement.

So the practical reading is that LICENSE is the authority and the pyproject field is noise, which is the opposite of the normal order. For a project you install from source, that distinction rarely matters. For anyone who forks it, vendors it into an internal image, or contributes back, it matters immediately, and the description of this project as Apache-2.0 in repository metadata is the string most tools will show you without checking the file it came from.

Four ways to call a tool, and the model decides which row you are in

The most useful table in the README is the one that maps model capability to how a tool gets invoked, because it shows that the Agent switch is not binary. Enabling Agent and choosing several tools lets the model call the tools itself, and the README says this suits ChatGLM3, Qwen or an online API with Agent capability. Enabling Agent with a single tool narrows it: the model only parses the tool arguments, which the README offers for models whose tool selection is mediocre and for cases where you want to pick the function yourself. Turning Agent off and choosing one tool means you fill the parameters in by hand, for models with no Agent capability at all. No tool and an uploaded image is the image path, recommended for a multimodal model such as qwen-vl-chat.

Read as a whole, that is a degradation ladder rather than a feature list. The same integration, say a Wolfram or an arXiv lookup, works in all four rows, and what changes is who decides to call it. The README says the 0.3.x Agent work was optimised for ChatGLM3 and Qwen, and the same table marks Agent as unstable in 0.2.x.

The consequence is that switching models can silently change the shape of your interface. A model that cannot call functions does not produce an error; it produces a form, and a team that evaluated the Agent experience on one model and deployed on another will find the tools still there and the conversation gone.

FastChat has no function call row and Ollama has no embedding, so the server picks your features

The supported serving frameworks are Xinference, LocalAI, Ollama and FastChat, and all four are listed as aligned to the OpenAI API interface, which is why the project's model access layer can be uniform. The rows below that are where the differences sit, and they decide what you can build.

The model types row lists LLM, Embedding, Rerank, Text-to-Image, Vision and Audio for Xinference and LocalAI. Ollama's row lists LLM, Text-to-Image and Vision. FastChat's row lists LLM and Vision. The Function Call row carries a check for Xinference, LocalAI and Ollama, and a slash for FastChat.

That gives you two hard constraints before you write any configuration. If the Agent features matter, FastChat is out. If your knowledge base needs an embedding model served by the same process, Ollama cannot supply it and you run a second server, because a RAG setup needs both the chat model and the encoder. The acceleration engine row narrows the choices further, with mlx listed only for Xinference, GGUF and GGML for Ollama, and vLLM for FastChat.

So picking a serving framework is picking a feature set, and the cost of that choice is a second process or a missing capability. Decide it against the features you will use rather than against the framework you already run.

The retrieval chain has no rerank stage, and no training step at all

The README describes the pipeline in one long line, and the order is the design. Load the file, read the text, split the text, vectorise the text, vectorise the question, match the most similar top k vectors, put the matched text into the prompt as context alongside the question, then send it to the model to generate the answer. Eight steps, one numeric parameter, one generation call.

What is missing is as informative as what is there. There is no reranking stage between the vector match and the prompt, so the text that reaches the model is the top k by vector similarity and nothing refines the order. There is no query rewriting, no hybrid scoring in this description and no answer verification step. The README also states plainly that the project involves no fine-tuning and no training, while noting that fine-tuning or training could be used to improve results.

So the project's own account of how to improve it points outside the project, at a model you train yourself. One table does show retrieval widening: the 0.2.x to 0.3.x comparison moves file chat from vector retrieval only to a unified File RAG capability with BM25 and KNN among the methods. If retrieval quality is your problem, that change is where the project answers it, and the top k parameter is where you tune what you get.

The last push was 2025-11-10, the newest tag is v0.3.1, and the version field says 0.3.0

Three version identities coexist in this repository and none of them agree. The version field in pyproject.toml reads 0.3.0. The newest tag is v0.3.1, released 2024-07-12, after v0.3.0 on 2024-06-20 and v0.2.10 on 2024-01-25. And the repository's last push was on 2025-11-10, more than a year after that tag and after every release in the list, which means the default branch is ahead of anything published.

That gap is the central fact about adopting this now. The code you would get by following the quick start is not the code in the newest release, and neither is a clean, documented upgrade path, because the version field you would record in your own inventory says 0.3.0 while your source is months of unreleased commits past v0.3.1.

The images have their own lag. The README says the Docker image will be updated in the near future, a sentence with no date attached, and separately notes that the code in the AutoDL image has been updated to the v0.3.0 version. So a docker/ directory exists in the tree while the README describes the image as pending. The honest approach is to treat master as a fork you own: pin the commit you tested, freeze the dependency set yourself, and assume you are maintaining the deployment rather than consuming it.

Editorial conclusion

Adopt Langchain-Chatchat if you need a Chinese-language knowledge base assistant that runs entirely on open source models and you already operate a model server, since the project expects you to start one yourself and point the config at it. Do not adopt it for a new deployment without reading the staleness first, and do not rely on the Agent tools with a model that cannot call functions. Verify first by checking whether the Python you have is inside the declared range, then by resolving the dependency set from libs/ rather than from pyproject.toml, which declares none.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes