PaintMatch-AI

1. Introduction

This project is an Intelligent Assistant acting as a virtual expert on Suvinil paints. The objective is to help users choose the ideal product based on their needs and preferences by answering questions in natural language and generating visual simulations of the paint applied to an environment.

2. Key Features

• Complete RESTful API: Management of users and the paint catalog.
• Secure Authentication: Login system with JWT token-based authentication.
• AI Assistant (RAG): A chatbot utilizing Retrieval-Augmented Generation (RAG) to query a PostgreSQL database and provide accurate, contextual recommendations.
• Visual Generation with Gemini Imagen: An optional feature where the assistant can generate a realistic image of a room with the recommended color and paint type, if requested by the user.
• Interactive Documentation: Automatic API documentation generation with Swagger UI and ReDoc, provided by FastAPI.

3. How to Run the Project

Execute the following commands to validate:

Regenerate lockfile (if not already executed)

uv lock

Install dependencies

uv sync

Verify lint

uv run ruff check app/

Run tests

uv run pytest tests/ -v

With Docker and Docker Compose installed, you can spin up the entire application with a single main command.

Prerequisites

• Docker
• Docker Compose

Step-by-Step

1. Clone the Repository

git clone https://github.com/Brevex/PaintMatch-AI.git
cd PaintMatch-AI

2. Configure the Environment

# Copy the example file
cp .env.example .env

IMPORTANT

Remember to add a valid API key (GoogleAI only) and insert a strong password in the .env file.

3. Start the Application

make dev-build

4. Local Development with UV

This project uses uv for dependency management.

1. Install uv: See instructions

2. Install Dependencies:

   uv sync

3. Run Locally:

   uv run uvicorn app.main:app --reload

5. Access the API!

The application is 100% functional. You can access the interactive documentation in your browser:

http://localhost:8000/docs

4. How to Test the Application (Swagger UI /docs)

After running the application, you can test the entire user flow directly within the interactive documentation.

Step 1: Create a New User

• Go to the Users section and expand the endpoint POST /api/v1/users.
• Click on "Try it out".
• In the Request body, insert the new user data:

{
  "email": "test@user.com",
  "password": "Password123!",
  "full_name": "Test User"
}

• Click on "Execute". You should receive a 201 Created response.

Step 2: Authorize Access in Documentation

• Click the "Authorize" button at the top right of the page.
• Fill in the fields with the credentials you just created:

username: test@user.com
password: Password123!

• Click "Authorize" and close the window. The padlock icon should now appear closed.

Step 3: Test the AI Assistant

• Go to the Chat section and expand the endpoint POST /api/v1/chat.
• Click on "Try it out".
• In the request body, ask a question.

{
  "question": "What is the best paint for an external wall that is water and mold resistant? Show in an image how this paint would look on a house"
}

• Click on "Execute". The response will contain the assistant's recommendation and, in this specific case, an image_url with the visual simulation generated by Gemini.

IMPORTANT

To save resources, the system will only generate the image if explicitly requested.