AutoFlow: a Graph RAG knowledge base on TiDB Serverless, read before you deploy

The gap AutoFlow fills: documentation search that answers instead of linking

A documentation site with a keyword search box returns links. The reader still has to open three pages, reconcile version differences, and assemble an answer. AutoFlow's stated goal is the other shape: a Perplexity-style conversational search page where the answer is synthesised and the sources are shown alongside it. The README describes a built-in website crawler that navigates official and documentation sites, using sitemap URL scraping to cover a doc set without hand-listing every page. That crawler is the ingestion front door, and it tells you who the project is aimed at. If your knowledge lives in a sitemap-driven documentation site, the onboarding path is short. If it lives in PDFs, ticket systems, or a wiki with no sitemap, the crawler is not the tool you need and you are looking at a different integration problem. The second audience is product teams who want that search experience embedded in their own site rather than hosted separately. The README gives an embeddable JavaScript snippet as a feature: you copy the snippet, paste it into your site, and the conversational window typically sits in the bottom right corner. Both audiences get the same backend. The difference is only whether the UI is the hosted page or the widget.

How the pipeline is assembled: TiDB for storage, LlamaIndex for retrieval, DSPy for the model layer

The tech stack list is unusually explicit about division of labour, and it is the most useful part of the README. TiDB is described as the database for chat history, vectors, JSON and analytics. That single sentence is the architectural claim: one system holds the conversation log, the embedding index, structured metadata, and the query workload used to inspect both. LlamaIndex is the RAG framework, so chunking, indexing and retrieval orchestration come from that project rather than from AutoFlow's own code. DSPy sits above it as, in the README's phrasing, the framework for programming rather than prompting foundation models. That is a meaningful split. DSPy means the prompt logic is expressed as modules that can be compiled or tuned against a metric, not as a string template you edit by hand. The practical consequence is that changing retrieval behaviour may mean changing a DSPy program and recompiling, not editing a prompt file. The frontend is Next.js with Tailwind CSS and shadcn/ui components, which explains the widget: a Next.js app and an embeddable snippet can share the same component tree. The graph part of graph RAG is not spelled out in the README beyond the topic tags, which include knowledge-graph and graphrag. The repository does not, in the supplied material, document the entity and relation extraction step, the graph schema, or how graph traversal is combined with vector similarity at query time. Treat that as the largest documentation gap and read the source before you assume a particular retrieval design.

Getting it running: Docker Compose, four cores, eight gigabytes

The README points to one deployment path: Deploy with Docker Compose, with a stated requirement of 4 CPU cores and 8 GB RAM. That is the concrete sizing figure the project gives, and it is worth reading as a floor for the application containers rather than a total budget for a production corpus. The repository publishes two images, tidbai/backend and tidbai/frontend, which the README surfaces as Docker Hub badges; a Compose file that pulls these is what the deployment guide describes. TiDB itself is the dependency you have to resolve before the stack is useful. The README links TiDB Cloud Serverless with a utm_source of tidb.ai, and the project description names TiDB Serverless Vector Storage as the vector store. So the expected configuration is a hosted TiDB Serverless instance rather than a self-managed TiDB cluster, which removes the operational burden of running TiDB but adds a network dependency and an account to provision. The README does not, in the material provided, list the environment variable names, the connection string format, or the embedding provider configuration. Those live in the deployment docs at autoflow.tidb.ai, and you should read them before sizing anything. The warning banner adds a forward-looking note: the maintainers say the next move is to make it a Python package, with `pip install autoflow-ai` given as the intended shape. That is a plan, not a current capability.

The early-stage warning is load-bearing, not boilerplate

The README opens with a warning block: Autoflow is still in the early stages of development, and the maintainers are actively working on it. Release history backs that up. The most recent release listed is 0.4.0, dated 2025-01-03, preceded by 0.4.0rc1 on 2024-12-31 and v0.3.0 on 2024-12-09. A release candidate two days before the final tag, and a minor version bump roughly three weeks before that, is a fast cadence at the zero-dot-something stage. For an operator, the practical risk is not that the code is bad. It is that the interfaces move. If you build an integration against the backend API, or fork the frontend, or write a custom ingestion step that feeds the same tables, you are building on a surface the maintainers have not declared stable. The versioning itself is inconsistent: 0.4.0 and 0.4.0rc1 carry no v prefix while v0.3.0 does. That is a small thing, but it is the kind of small thing that makes tag-based pinning in a Docker Compose file fiddly, and it is a signal about how much attention the release process has received relative to the features. Pin to a digest rather than a tag if you deploy this.

Where AutoFlow is the wrong tool

The clearest failure mode is scope mismatch on ingestion. The crawler is described as working from sitemaps. Point it at a site with a partial or stale sitemap and coverage is partial or stale, and nothing in the README suggests a fallback crawler that follows links heuristically. A second case is the team that wants a library, not an application. The README's own roadmap says the Python package is a future move, which means today you are deploying a Next.js frontend and a backend service. If your requirement is to call a retrieval function from inside an existing Python service, AutoFlow gives you a service to talk to over HTTP, not an import. A third case is the team without a TiDB footprint. The stack is built around TiDB holding vectors, JSON, chat history and analytics together. If you already run Postgres and have no appetite for a second database, adopting AutoFlow means adopting TiDB as a dependency of a documentation search feature. That is a large commitment for a small feature, and the README does not present a supported alternative vector backend. Finally, the graph RAG claim is the part with the least documentation. If your evaluation hinges on entity extraction quality or multi-hop retrieval, the supplied material does not let you assess it, and you should not adopt on the strength of the topic tags alone.

The realistic alternative: a plain vector store and a retrieval library you own

The obvious comparison is not another product but a smaller stack: pgvector on Postgres with LlamaIndex, which AutoFlow already uses, driving your own retrieval endpoint. The difference is in what you get and what you give up. AutoFlow ships the conversational UI, the crawler, the widget snippet and an admin surface for documents, so the work you skip is frontend and ingestion plumbing. The work you take on is operating a Next.js app, a backend service and a TiDB instance, plus tracking a project at 0.4.0. A pgvector setup gives you none of the UI and all of the control: the schema is yours, the retrieval code is yours, and there is no graph layer to reason about. The second comparison is a managed RAG service. Those remove the deployment entirely but remove the data locality too, which is the reason a team picks a self-hosted tool in the first place. AutoFlow's position is between the two: more out-of-the-box than pgvector, more under your control than a hosted service, and tied to TiDB in a way neither of the others is. The DSPy dependency is the detail that most distinguishes it from a hand-rolled pgvector pipeline. If you want to tune retrieval against a metric rather than by prompt editing, that is a real advantage. If you want to read the retrieval logic and change one line, DSPy indirection works against you.

Maintenance, licensing and what to verify before you commit

AutoFlow is Apache-2.0, and the README links the licence file at the repository root. Apache-2.0 is permissive and includes an explicit patent grant, which matters if you embed the widget in a commercial product. It also means you can fork and modify without a copyleft obligation on your changes. What the licence does not cover is the surrounding dependencies and services. TiDB Cloud Serverless is a hosted product with its own terms and its own pricing, and the README's links carry utm parameters pointing at PingCAP's commercial pages, which tells you the hosted database is the intended production path. LlamaIndex and DSPy carry their own licences. None of that is legal advice; read the terms of the services you actually enable. On maintenance cost, the material supports a few concrete observations. The project is not archived and the last push is recent relative to the 0.4.0 release, so it is being worked on. The stated next move is packaging, which likely means interface churn before it means stability. The README directs questions to GitHub Discussions and Discord rather than to a documented support contract, so your maintenance plan is community-shaped. The versioning inconsistency between 0.4.0 and v0.3.0 means you should pin image digests, not tags, and re-read the deployment guide at autoflow.tidb.ai on each upgrade rather than assuming environment variables are stable across minor versions.

Editorial conclusion

Adopt AutoFlow if you want a self-hosted conversational search layer over documentation you control, you are comfortable running a Next.js frontend plus FastAPI backend plus TiDB, and you accept the project's own early-stage warning. Do not adopt it if you need a stable API contract, a Python-installable library, or a RAG stack you can debug without a graph database in the loop. Before committing, verify three things: that the deploy-with-docker guide's 4 CPU core and 8 GB RAM sizing matches your corpus, that your embedding model choice is configurable in the deployment you run, and that the 0.4.0 release, dated 2025-01-03, still corresponds to the main branch you intend to pin.

Official sources

1. License: Apache-2.0
2. pingcap/autoflow on GitHub
3. Project website
4. README
5. Releases