ai-chatbot-framework: a self-hosted Python bot builder with an admin dashboard

What ai-chatbot-framework solves, and for whom

Most chatbot stacks force a choice early: a hosted service with a monthly bill and a data-processing agreement, or a pile of Python scripts where the dialogue logic lives in code that only the original author understands. ai-chatbot-framework targets the second group and tries to remove the scripting. The README describes it as an "open-source, self-hosted, DIY Chatbot building platform built in Python" where you "create Natural Language conversational scenarios with no coding efforts whatsoever" through an admin UI.

The intended user is a developer or a small team that wants to own the deployment and still let a non-programmer edit conversation flows. Everything runs on your own infrastructure: the repository ships a Dockerfile, docker-compose.yml, docker-compose.dev.yml, docker-compose.llm.yml and a helm/ directory, so the deployment target can be a laptop, a single VM or a Kubernetes cluster. The licence is MIT, which places few restrictions on what you do with the code.

The trade-off is visible in the same README. Slack and WhatsApp via Twilio are marked "coming soon", so the channel list in practice is the web REST API and chat snippet plus Facebook Messenger. If your requirement is a bot inside an existing Slack workspace, this is not the tool for that job yet.

How the Python backend, MongoDB and Next.js admin fit together

The stack is split into two deployable pieces. The backend is Python with FastAPI and Pydantic, backed by MongoDB through the Motor async driver. The frontend is React and Next.js. The machine learning layer is scikit-learn, TensorFlow and Keras, with spaCy for word embeddings and python-crfsuite for sequence labelling, which is the usual pairing for entity extraction.

The docker-compose.yml file shows the runtime topology. A gateway service runs nginx:1.13.3-alpine and publishes port 8080, proxying to the backend and frontend. The backend container starts with a shell command that runs migrations first and then serves FastAPI on port 80 with the root path /api. MongoDB runs as mongo:4.2.20 with a named volume for data. The backend receives MONGODB_HOST as mongodb://mongodb:27017 and APPLICATION_ENV as Production.

That migration step matters. The repository has a manage.py at the top level and a migrations/ directory, so schema changes are applied at container start rather than baked into the image. The requirements.txt pins fastapi==0.115.7, motor==3.6.1, pymongo==4.9.2, scikit-learn==1.6.1, spacy==3.8.4, langchain==0.3.17 and langchain-openai==0.3.3, among roughly ninety other packages. The spaCy model is not pulled from PyPI: requirements.txt points en_core_web_md at a GitHub release wheel, so the first build needs network access to github.com.

On the understanding side, the README lists intent recognition and entity extraction as ML features, and zero-shot NLU using large language models as a separate option. Tool calling is described as API request fulfilment, and there is persistent memory and context management for multi-turn conversations. Knowledge base and FAQ answering with RAG is labelled "in development", so treat that as unfinished rather than available.

Installing ai-chatbot-framework with Docker Compose

The README points to docs/README.md for setup, and the repository root carries docker-compose.yml. The published images are alfredfrancis/ai-chatbot-framework_backend:latest and alfredfrancis/ai-chatbot-framework_frontend:latest, so a Compose run does not require a local build. From the repository root, the command is:

docker compose up -d

Compose starts four services: mongodb, backend, frontend and gateway. The backend container runs migrations before FastAPI starts, which is what the command list in docker-compose.yml shows. The gateway publishes port 8080 on the host, so the admin UI and API are reached through that port rather than by talking to the backend container directly.

docker compose ps

You should see the four services running and the mongodb volume mounted at /data. If the backend container exits, the migration step is the first place to look, since it runs before the server binds.

For a local build instead of the published images, docker-compose.dev.yml exists alongside the production file. The Dockerfile itself is based on python:3.12.7-slim, installs build-essential and python3-dev, then pip installs requirements.txt and exposes port 80. Because the spaCy model is fetched from a GitHub release URL, a build behind a restrictive proxy will fail at that line.

The first real use is a conversation flow: create an intent in the admin UI, attach training examples, add a response, and let the backend train the model. The examples/ directory holds order_status.json and restaurant_search.json, which are the closest thing to reference flows in the repository, along with client samples in examples/nodejs, examples/python and examples/ruby. Those client directories are the starting point for calling the bot over the REST API from your own application. The README does not document a required environment variable for an OpenAI key, so check docs/README.md before enabling the LLM path.

Where ai-chatbot-framework gets in your way

The largest constraint is release maturity. The newest release listed is v1.0.0-alpha.10 from 2025-02-03, and the two before it landed on consecutive days. An alpha version number on the only published line means the API surface and the migration set can change between tags, and the docker-compose.yml pulls :latest images rather than a pinned tag. Pinning to a specific image digest is the only way to make a deployment reproducible, and the Compose file as written does not do that.

Second, the channel story is narrower than the feature list implies. Facebook Messenger and the web snippet are the documented integrations; Slack and WhatsApp are explicitly "coming soon". A team that needs a Slack bot has to write that integration itself against the REST API.

Third, MongoDB 4.2.20 in the Compose file is an old server version. It is pinned in the repository, so it works, but it constrains any migration path you might want later and it is a separate upgrade project from the application itself.

Finally, the README claims you can build conversations "with no coding efforts whatsoever", but tool calling means HTTP endpoints you host and maintain, and the RAG knowledge base is still in development. The no-code promise covers dialogue authoring, not the integrations around it.

ai-chatbot-framework against Botpress

Botpress is the comparison that comes up in search, and the two differ in where the intelligence lives. Botpress is a TypeScript and Node.js platform with a visual flow editor and a plugin system, distributed as a managed cloud product with a self-hosted option. ai-chatbot-framework is Python and FastAPI with a MongoDB store, and its NLU is a scikit-learn and spaCy pipeline you train from the admin UI, with an optional LLM path through langchain-openai.

That difference decides most adoption questions. If your team writes Python and wants the intent model to be a local artefact you can inspect and retrain, this project is closer to that. If you want a large plugin marketplace and a company behind the hosted offering, Botpress is the more conventional choice. The licence also differs in kind: this project is MIT, which is permissive, while Botpress has changed its licensing over time, so check the current terms of whichever Botpress distribution you would use rather than relying on older summaries.

Neither is a drop-in replacement for the other. Migrating between them means rebuilding flows, not exporting them.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-08-26. The release history is thinner than the commit history: the most recent tagged release is v1.0.0-alpha.10 from 2025-02-03, roughly seven months before that last push. So code is moving on master while tagged releases lag, which is normal for an alpha project and awkward for anyone who wants to depend on versioned artefacts.

Upgrade cost comes from three places. The docker-compose.yml references :latest images, so an upgrade is implicit unless you pin digests. The backend runs python manage.py migrate on every container start, so a schema change applies the moment a new image is deployed, with no separate migration window. And requirements.txt pins exact versions of around ninety packages, including TensorFlow and Keras transitively, which makes a manual dependency bump a real task rather than a one-line change.

The MIT licence permits commercial use, modification and redistribution, and it comes with no warranty. It does not, by itself, settle anything about the data you put into the bot or the terms of the LLM provider you configure. If you enable the OpenAI path, your conversation content leaves your infrastructure for that provider, which is a separate decision from the framework's licence.

Editorial conclusion

Adopt it if you want a self-hosted bot builder you can read end to end: FastAPI, MongoDB, scikit-learn, spaCy and a Next.js admin UI, all MIT licensed. Skip it if you need a stable release, a managed service, or Slack and WhatsApp channels today, since the README lists those as coming soon. The releases page still shows v1.0.0-alpha.10, so before committing, verify that the docker-compose stack starts on your machine and that the intent and entity training pipeline runs against your own data.

Frequently asked questions

Official sources

1. alfredfrancis/ai-chatbot-framework on GitHub
2. Issues
3. License: MIT
4. README
5. Releases