README.md

metadata

title: Champ Chatbot Demo
emoji: 🤖
colorFrom: yellow
colorTo: gray
sdk: docker
pinned: false
app_port: 8000
python_version: '3.11'

MARVIN WebUI Demo

A lightweight chat interface powered by the MARVIN model, designed for easy deployment and testing. This project can run locally with Docker Compose or be deployed to platforms like Hugging Face Spaces.

Features

• Simple and fast chat interface
• Python backend with async endpoints
• Frontend served through a minimal web app
• Containerized so can start everything with a single command

Requirements

• Docker
• Docker Compose

Local Development

Start the database service

Before running the database service, make sure you .env file contains the following variables for local development:

USE_LOCAL_DDB=true
DYNAMODB_ENDPOINT=http://localhost:3000

To run the database service:

docker-compose -f docker-compose.dev.yml up -d

Start the backend and frontend service

From the project root:

docker compose up --build

Once everything is ready, open:

http://localhost:8000

Stopping the project

Use:

docker compose down

Rebuilding after code changes

Use:

docker compose up --build

Running without Docker

Before installing the dependencies, install uv:

pip install uv

uv is a python package manager similar to pip. However, it permits overriding package version conflicts. This allows installing packages that theorically incomptatible but are necessary to run the app.
After installing uv, create your virtual environment, then run:

uv pip install --no-cache-dir -r requirements.txt

---

Deployment on HuggingFace Spaces

A HuggingFace Space uses Git to store the code. It requires a YAML block at the beginning of the README.md file that defines metadata variables. Notably, this file specifies the app title (Champ Chatbot Demo), the SDK (docker), and the app port (8000).

Since docker is the selected SDK, the space builds the app using the Dockerfile at the project root.

Update code

To update the code in the space, click on + Contribute button in the upper-right corner of the Files page, then click Upload Files. Follow the instructions to commit/upload your local files to the space.

You could add the Git repo as a remote to your local Git repository, but it would add unnecessary complexity. HuggingFace is stricter than Gitlab concerning best Git practices. You would have to configure git-xet and delete the .env file and the binary file in rag_data from the Git history to be able to push your changes. The .env file has not been added to the space. The environment variables are stored in the settings page.

Unit testing

To run the tests, simply execute pytest at the project root. Make sure your virtual environment is activated and that dev dependencies are installed:

pip install -r requirements-dev.txt

Some tests are marked as resource_intensive. They take longer to run and might consume significant memory or CPU. To run them:

pytest -m resource_intensive

To run every test:

pytest -m ""

Code coverage

coverage is a Python library that measures code coverage. To use it, run:

coverage run -m pytest

To see a short summary of the results, run:

coverage report

For a more detailed presentation, run:

coverage html

To run pytest with additionnal arguments, you can run, for example:

coverage run -m pytest -m resource_intensive

Load testing

k6 is an open-source tool for performing load testing. Test cases are defined in JavaScript files and can be run using the command k6 run <filename>.js.

k6 installation

On Debian/Ubuntu:

sudo apt-get update
sudo apt-get install k6

On Windows:

winget install k6 --source winget

On Docker:

docker pull grafana/k6

For more options, see Install k6.

Test scenarios

The test cases are defined in the folder /tests/stress_tests/:

• chat_session.js simulates 150 users sending three messages to one specific model.
• file_upload.js simulates 150 users sending three PDF files.
• chat_session_with_file.js simulates 150 users sending one PDF file followed by three messages to one specific model.
• website_spike.js simulates 150 users connecting to the application home web page.

Chat session test scenario

The chat session scenario must be run by specifying the model type and the URL of the server. For example, the following command simulates 150 users making three requests at https://<username>-champ-chatbot.hf.space to the model champ:

k6 run chat_session.js -e MODEL_TYPE=champ -e URL=https://<username>-champ-chatbot.hf.space

The possible values for MODEL_TYPE are champ, google, and openai.

To find your HuggingFace Space backend URL, follow these steps:

1. Go to your space
2. Click on the three dots in the top right corner
3. Select Embed this Space
4. Look for the Direct URL in the code snippet.

Typically, the URL follows this format: https://<username>-<space-name>.hf.space.
To test locally, simply use http://localhost:8000

The file message_examples.txt contains 450 pediatric medical prompts (generated by Gemini and Sonnet). chat_session.js uses this file to simulate real user messages.

File upload test scenario

The file upload scenario must be run by specifying the file to send and the URL of the server. Each virtual user will upload the file 3 times to the server.

k6 run file_uploads.js -e FILE=my_pdf_file.pdf -e URL=https://<username>-champ-chatbot.hf.space

Make sure the file is at the same directory level as the test file.

Chat with file test scenario

The file upload scenario must be run by specifying the PDF file, the model type and the URL of the server. Each virtual user will upload the file once then send three messages to the server.

k6 run chat_session_with_file.js -e FILE=my_pdf_file.pdf -e MODEL_TYPE=champ -e URL=https://<username>-champ-chatbot.hf.space

The possible values for MODEL_TYPE are champ, google, and openai.

Make sure the file is at the same directory level as the test file.

Website spike test scenario

The website spike scenario must be run by specifying the website URL which is simply the HuggingFace Space URL:

k6 run website_spike.js -e URL=https://huggingface.co/spaces/<username>/champ-chatbot