**Warning:** This project is in active development and in a very early stage. Breaking changes may occur at any time.
## Yet another AI chatbot
Conversations is an open-source AI chatbot designed to be simple, secure and privacy-friendly.
Why another AI chatbot? Because we want to be able to fully control our data and the way we interact with AI.
We want to have a very friendly end-user interface and code, and we want to be able to easily customize the
chatbot to our needs.
We leverage open-source projects such as [Vercel‘s AI SDK](https://ai-sdk.dev/) and [Pydantic AI](https://ai.pydantic.dev)
and only assemble them in a way that makes sense for us and allows us to focus on the product.
This assistant's purpose is also to be integrated into the "La Suite numΓ©rique" ecosystem of tools for public services.
Any help to improve the project is very welcome!
### Self-host
π Conversations is easy to install on your own servers
Available methods: Helm chart, soon Nix package
In the works: Docker Compose, soon YunoHost
## Getting started π§
### Test it
You can test Conversations on your browser by visiting this => TBD
### Run Conversations locally
> β οΈ The methods described below for running Conversations locally is **for testing purposes only**.
**Prerequisite**
Make sure you have a recent version of Docker and [Docker Compose](https://docs.docker.com/compose/install) installed on your laptop, then type:
```shellscript
$ docker -v
Docker version 20.10.2, build 2291f61
$ docker compose version
Docker Compose version v2.32.4
```
> β οΈ You may need to run the following commands with `sudo`, but this can be avoided by adding your user to the local `docker` group.
**Project bootstrap**
The easiest way to start working on the project is to use [GNU Make](https://www.gnu.org/software/make/):
```shellscript
$ make bootstrap FLUSH_ARGS='--no-input'
```
This command builds the `app-dev` and `frontend-dev` containers, installs dependencies, performs database migrations and compiles translations. It's a good idea to use this command each time you are pulling code from the project repository to avoid dependency-related or migration-related issues.
Your Docker services should now be up and running π
You can access the project by going to .
You will be prompted to log in. The default credentials are:
```
username: conversations
password: conversations
```
π Note that if you need to run them afterwards, you can use the eponymous Make rule:
```shellscript
$ make run
```
β οΈ For the frontend developer, it is often better to run the frontend in development mode locally.
To do so, install the frontend dependencies with the following command:
```shellscript
$ make frontend-development-install
```
And run the frontend locally in development mode with the following command:
```shellscript
$ make run-frontend-development
```
To start all the services, except the frontend container, you can use the following command:
```shellscript
$ make run-backend
```
**Setup a basic LLM call**
To be able to use Conversations, you need to configure at least one Large Language Model (LLM) provider.
You can do so by setting the appropriate environment variables in the `env.d/development/common` file:
```ini
AI_BASE_URL=http://host.docker.internal:12434/v1/
AI_MODEL=gemma3:4b
AI_API_KEY=XXX
```
for a local ollama, or by running a local LLM with docker-compose:
```shellscript
$ make create-compose-with-models
```
which will create a `compose.override.yml` file to start a local models `ai/smollm2`
which can be changed later by editing the `compose.override.yml` file.
You will need to call `make run` after changing the `env.d/development/common`
or `compose.override.yml` file.
You can find more information about configuring LLM providers in the [LLM Configuration](docs/llm-configuration.md) documentation.
**Adding content**
You can create a basic demo site by running this command:
```shellscript
$ make demo
```
Finally, you can check all available Make rules using this command:
```shellscript
$ make help
```
**Django admin**
You can access the Django admin site at:
.
You first need to create a superuser account:
```shellscript
$ make superuser
```
## Documentation π
Additional documentation is available in the `docs/` directory:
- [LLM Configuration](docs/llm-configuration.md) - Configure Large Language Models and providers
- [Attachments](docs/attachments.md) - How to use attachments in conversations
- [Tools for Agents](docs/tools.md) - Available tools and how to add new ones
- [Environment Variables](docs/env.md) - All available environment variables
- [Installation Guide](docs/installation.md) - Deploy on a Kubernetes cluster
- [Theming](docs/theming.md) - Customize the application appearance
- [Architecture](docs/architecture.md) - Technical architecture overview
## Licence π
This work is released under the MIT License (see [LICENSE](https://github.com/suitenumerique/conversations/blob/main/LICENSE)).
While Conversations is a public-driven initiative, our licence choice is an invitation for private sector actors to use, sell and contribute to the project.
## Contributing π
You can help us with translations on [Crowdin](https://crowdin.com/project/lasuite-conversations).
If you intend to make pull requests, see [CONTRIBUTING](https://github.com/suitenumerique/conversations/blob/main/CONTRIBUTING.md) for guidelines.
## Directory structure:
```markdown
docs
βββ bin - executable scripts or binaries that are used for various tasks, such as setup scripts, utility scripts, or custom commands.
βββ crowdin - for crowdin translations, a tool or service that helps manage translations for the project.
βββ docker - Dockerfiles and related configuration files used to build Docker images for the project. These images can be used for development, testing, or production environments.
βββ docs - documentation for the project, including user guides, API documentation, and other helpful resources.
βββ env.d/development - environment-specific configuration files for the development environment. These files might include environment variables, configuration settings, or other setup files needed for development.
βββ gitlint - configuration files for `gitlint`, a tool that enforces commit message guidelines to ensure consistency and quality in commit messages.
βββ src - main source code directory, containing the core application code, libraries, and modules of the project.
```
## Credits β€οΈ
### Stack
Conversations is built on top of [Django Rest Framework](https://www.django-rest-framework.org/), [Next.js](https://nextjs.org/), [Vercel‘s AI SDK](https://ai-sdk.dev/) and [Pydantic AI](https://ai.pydantic.dev). We thank the contributors of all these projects for their awesome work!
### Gov β€οΈ open source
