🇬🇧 English | 🇫🇷 Français
This repository is a technical presentation and documentation repository.
It does not contain downloadable source code or production files.
A complete project to build your own Flask-based conversational assistant, ready to run:
- locally (localhost)
- on shared hosting such as o2switch (Passenger / cPanel)
No external database, no hidden dependencies. You can use it as-is, modify it, or integrate it into another website or API.
This project provides a self-hosted conversational assistant built with Flask,
designed for developers and teams who want full control over their chatbot’s behavior and deployment.
The architecture prioritizes:
- a local knowledge base (JSON) as the primary source
- predictable behavior in professional environments
- optional AI integration (OpenAI)
- simple deployment without dependency on external SaaS platforms
flask_chatbot_advanced_2.0/
│
├── core/ → Chatbot logic and processing
├── interface/ → Frontend (chat UI and widget)
├── storage/ → Optional persistence layer
├── config/ → Environment and dependencies
├── deployment/ → Hosting and container setup
├── data/ → Example knowledge base
├── logs/ → Error tracking system
│
└── docs/
├── README_TECHNIQUE.md → Technical documentation and internal architecture
├── README.md → Main project documentation and guides
├── CUSTOMISATION.md → Bot customization (design, responses, OpenAI…)
└── INSTALL.md → Complete user guide
- Compatible with o2switch / Passenger (shared hosting)
- No database required (JSON-based operation)
- Readable, well-commented and easily customizable code
- CORS enabled: usable with websites or frontend interfaces
- Integrated logging system: errors automatically recorded in
/logs/
This chatbot is designed for:
- internal knowledge assistants
- support or documentation automation
- self-hosted AI assistants
- internal tools requiring controlled responses
- websites embedding a chatbot widget
The system can operate fully offline using a local knowledge base,
or optionally use OpenAI when extended responses are required.
When the chatbot is launched for the first time, some files are created automatically:
| File | Purpose |
|---|---|
| Persistence file | May be generated to store conversations if persistence is enabled |
logs/errors.log |
Created only when a server error occurs |
| Environment file | Must be created from the provided template to enable optional features |
| Mode | Description | Requires OpenAI Key |
|---|---|---|
| Local JSON (default) | Responses generated from the local knowledge base | No |
| OpenAI GPT (optional) | Uses OpenAI API when a key is provided | Yes |
The mode is automatically selected based on the presence of an API configuration in the environment.
No tokens are consumed if no key is provided.
The logs/ directory automatically records Flask server errors:
- automatic creation of log files when an error occurs
- automatic creation of the
logs/directory if missing - recording of date, error message and full traceback
This system works:
- in local mode
- with or without OpenAI
- in production (Passenger / shared hosting)
Palks Studio — Version 2.0 (Advanced Edition)
Compatible with Python 3.12+ and Flask 3.0+
© Palks Studio — see LICENSE.md