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.

5. AI Usage in Development

As requested in the challenge, AI was used as a strategic tool during development.

• Main Tool: Gemini (Google)
• How it was Used: Gemini acted as a pair programmer, helping to accelerate development, debug errors, and refine the architecture.
• Reason for Choice: Among LLM models, Gemini stands out for its enormous context window, which favors cohesive responses suitable for extensive tasks (such as programming).

Examples of Prompts Used

• Stack Choice: "I will develop a chatbot for Suvinil paint recommendations and their possible applications. The language adopted will be Python 3.13. The database used will be PostgreSQL. The LLM used will be OpenAI's chatGPT. We will use RAG to search for information in a PostgreSQL database and provide accurate and contextual recommendations. Your job is to provide me with a list of pros and cons of using Django, FastAPI, and Flask frameworks for the backend implementation of this project."
• Improvement Suggestions: "This provisional implementation makes multiple SQL queries for each question. Use RAG + agent to perform relevant searches locally via the vector database. Apply a regex to recognize a universal URL pattern instead of a fixed text susceptible to failure."
• Script Generation: "Use the pandas and sqlalchemy libraries to read a CSV file and load the read data into a database. The CSV data must be organized into a dataframe. Read the database to ensure duplicates are not exported and are properly ignored. Create a Paint type object and add it to the database session."
• Test Creation: "Create a script that simulates the process of creating and reading users and paints directly in the database to ensure that crud and security functions operate as expected. The script must create and save users in the database. Use assert to confirm if the user data created in the database is identical to the input data. If an assert verification fails, the script must immediately throw an error indicating the test failed. Verify if the hash was applied to the password before saving to the database and ensure the original password corresponds to the saved hash. In the end, the script will remove the data inserted into the database."