Nash Paints AI Assistant

A full-stack AI-powered paint consultation platform that helps users find the right Nash Paints products, get color recommendations, visualize paint applications, and chat with an AI consultant.

🎨 Features

Core Features

• AI Chat Consultant: Conversational AI assistant powered by GPT-4o mini that provides paint recommendations and answers questions
• Product Search: Semantic search using RAG (Retrieval-Augmented Generation) with ChromaDB for finding paint products
• Color Recommendation: AI-powered color extraction from uploaded images with matching Nash Paints product suggestions
• Virtual Repaint Preview: Generate visual previews of how paint colors would look on uploaded images
• Image Generation: DALL-E 3 integration for generating visual representations of paint applications
• Branch Locator: Find nearby Nash Paints branches with stock availability information
• Product Cards: Rich product displays with images, prices, and purchase links

Advanced Features

• Conversation Context: Maintains conversation history for contextual responses
• Image Context Tracking: References previous images when generating variations
• Streaming Responses: Real-time streaming chat responses for better UX
• Markdown Rendering: Formatted text display in chat messages
• Product Recommendations: Automatic product card display when products are mentioned

🛠️ Tech Stack

Backend

• Framework: FastAPI (Python)
• Database: PostgreSQL (production) / SQLite (development)
• ORM: SQLAlchemy
• Vector DB: ChromaDB for semantic search
• AI/ML:
  • OpenAI GPT-4o mini (chat)
  • OpenAI DALL-E 3 (image generation)
  • LangChain (RAG orchestration)
  • OpenAI Embeddings (vector search)
• Image Processing: Pillow (PIL)
• Other: Pydantic, python-dotenv

Frontend

• Framework: Next.js 15 (React)
• Language: TypeScript
• Styling: TailwindCSS 3.4
• UI Components: Custom components with shadcn/ui patterns
• Markdown: react-markdown with remark-gfm

📁 Project Structure

nashpaint1/
├── backend/
│   ├── app/
│   │   ├── config.py              # Application settings and environment variables
│   │   ├── db.py                  # Database connection and session management
│   │   ├── main.py                # FastAPI application entry point
│   │   ├── seed_data.py           # Database seeding script
│   │   ├── models/
│   │   │   ├── product.py         # Product data model
│   │   │   ├── branch.py          # Branch/location model
│   │   │   └── stock.py            # Stock inventory model
│   │   ├── routers/
│   │   │   ├── chat.py            # AI chat endpoint
│   │   │   ├── products.py        # Product search endpoint
│   │   │   ├── colors.py          # Color recommendation endpoint
│   │   │   ├── repaint.py         # Virtual repaint endpoint
│   │   │   └── upload.py           # Image upload endpoint
│   │   └── services/
│   │       ├── rag_service.py     # RAG and vector search service
│   │       ├── color_extractor.py # Color extraction from images
│   │       └── virtual_repaint.py # Image repainting service
│   ├── uploads/                    # Uploaded user images
│   ├── repaints/                   # Generated repaint previews
│   └── requirements.txt            # Python dependencies
├── frontend/
│   ├── app/
│   │   ├── layout.tsx              # Root layout with header
│   │   ├── page.tsx                # Home page
│   │   ├── chat/
│   │   │   └── page.tsx            # Chat interface
│   │   ├── products/
│   │   │   └── page.tsx            # Product search page
│   │   └── repaint/
│   │       └── page.tsx            # Virtual repaint page
│   ├── components/
│   │   ├── ChatMessageBubble.tsx  # Chat message component
│   │   ├── ProductCard.tsx         # Product display card
│   │   ├── ColorSwatch.tsx         # Color swatch component
│   │   ├── ImageUploader.tsx     # Image upload component
│   │   └── RepaintPreview.tsx      # Repaint preview component
│   ├── lib/
│   │   ├── api.ts                  # API client functions
│   │   └── utils.ts                # Utility functions
│   ├── assets/
│   │   └── icon-02-primary.png     # Nash Paints logo
│   └── package.json                # Node.js dependencies
└── README.md                        # This file

🚀 Getting Started

Prerequisites

• Python 3.12+
• Node.js 18+ and npm
• PostgreSQL (for production) or SQLite (for development)
• OpenAI API key (for AI features)

Backend Setup

1. Navigate to project root:

   cd /path/to/nashpaint1

2. Create virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r backend/requirements.txt

4. Create .env file in project root:

   # Database (use SQLite for development)
   DATABASE_URL=sqlite:///./nashpaints.db
   
   # For production PostgreSQL:
   # DATABASE_URL=postgresql+psycopg2://user:password@localhost:5432/nashpaints
   
   # OpenAI API (required for AI features)
   OPENAI_API_KEY=your_openai_api_key_here
   OPENAI_MODEL=gpt-4o-mini
   
   # Optional: HuggingFace token
   HF_API_TOKEN=your_hf_token_here

5. Seed the database:

   DATABASE_URL=sqlite:///./nashpaints.db python -m backend.app.seed_data

   This creates:

   • Sample products (Decorative, Industrial, Automotive, Woodline)
   • Dummy branch locations (Chitungwiza, Msasa, Graniteside)
   • Stock inventory data
   • ChromaDB vector index

6. Run the backend:

   uvicorn backend.app.main:app --reload --port 8000

   Backend will be available at http://localhost:8000

   • API docs: http://localhost:8000/docs
   • Health check: http://localhost:8000/health

Frontend Setup

1. Navigate to frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Create .env.local (optional, defaults to localhost:8000):

   NEXT_PUBLIC_API_BASE_URL=http://localhost:8000

4. Run the development server:

   npm run dev

   Frontend will be available at http://localhost:3000

📡 API Endpoints

Products

• POST /api/products/search - Search products using RAG + keyword search

  {
    "query": "interior matt white",
    "limit": 10
  }

Chat

• POST /api/chat - Stream chat responses with AI consultant

  {
    "message": "What paint should I use for my roof?",
    "history": [
      {"role": "user", "content": "...", "images": []},
      {"role": "assistant", "content": "...", "images": []}
    ]
  }

  Returns: Streaming text response with [PRODUCTS:...] and [IMAGE:...] markers

Colors

• POST /api/colors/recommend - Extract colors from image and recommend products

  {
    "image_path": "filename.jpg"
  }

Upload

• POST /api/upload/image - Upload image file Returns: {"url": "/static/uploads/filename.jpg"}

Repaint

• POST /api/repaint - Generate virtual repaint preview

  {
    "image_url": "/static/uploads/filename.jpg",
    "target_hex": "#E1251B"
  }

  Returns: {"repainted_image_url": "/static/repaints/repaint_xxx.jpg"}

🗄️ Database Schema

Products Table

- id (Integer, PK)
- name (String) - e.g., "Nash Decorative Interior Matt White"
- description (String, nullable)
- line (String) - Decorative, Industrial, Automotive, Woodline, Accessories
- type (String) - Acrylic, Enamel, 2K Urethane, etc.
- finish (String, nullable) - Matt, Silk, Gloss
- base (String, nullable) - Water-based, Solvent-based
- color_name (String, nullable)
- color_hex (String, nullable) - Hex color code
- image_url (String, nullable)
- coverage_m2_per_litre (Float, nullable)
- price (Float, nullable)
- purchase_link (String, nullable)

Branches Table

- id (Integer, PK)
- name (String) - e.g., "Nash Paints Chitungwiza Makoni"
- city (String) - e.g., "Harare"
- area (String, nullable) - e.g., "Chitungwiza"
- address (String, nullable)
- phone (String, nullable)
- latitude (String, nullable)
- longitude (String, nullable)

Stock Table

- id (Integer, PK)
- branch_id (Integer, FK -> branches.id)
- product_id (Integer, FK -> products.id)
- quantity_litres (Float) - Available stock in litres

⚙️ Configuration

Environment Variables

Variable	Description	Default
DATABASE_URL	Database connection string	postgresql+psycopg2://...
OPENAI_API_KEY	OpenAI API key for AI features	None
OPENAI_MODEL	OpenAI model to use	gpt-4o-mini
HF_API_TOKEN	HuggingFace API token (optional)	None
CHROMA_PERSIST_DIR	ChromaDB persistence directory	backend/chroma_data

CORS Configuration

Backend allows requests from:

• http://localhost:3000
• http://localhost:3001
• http://localhost:3002
• http://localhost:3003

Configure in backend/app/config.py if needed.

🔧 Development

Running in Development Mode

Backend:

uvicorn backend.app.main:app --reload --port 8000

Frontend:

cd frontend
npm run dev

Database Seeding

To reset and reseed the database:

rm -f nashpaints.db backend/nashpaints.db
DATABASE_URL=sqlite:///./nashpaints.db python -m backend.app.seed_data

Building for Production

Frontend:

cd frontend
npm run build
npm start

Backend:

# Use a production ASGI server like gunicorn with uvicorn workers
gunicorn backend.app.main:app -w 4 -k uvicorn.workers.UvicornWorker

🎯 Key Features Explained

RAG (Retrieval-Augmented Generation)

• Products are indexed in ChromaDB with embeddings
• User queries are embedded and matched against product descriptions
• Top matches are retrieved and passed to LLM for context-aware responses

Color Extraction

• Uses Pillow for image processing
• Quantizes images to extract dominant colors
• Matches extracted colors to Nash Paints product color_hex values

Virtual Repaint

• Applies color overlay effects to uploaded images
• Simulates paint application using image processing
• Saves results to backend/repaints/ directory

Conversation Context

• Maintains full conversation history
• Tracks generated images for reference
• Extracts product mentions from both user and assistant messages
• Automatically displays product cards when products are mentioned

Image Generation

• Detects image generation requests in chat
• Uses DALL-E 3 to create visual representations
• Maintains context from previous images when generating variations
• Includes product recommendations with generated images

🐛 Troubleshooting

Backend Issues

Import errors:

• Ensure virtual environment is activated
• Run pip install -r backend/requirements.txt

Database connection errors:

• Check DATABASE_URL in .env
• For SQLite, ensure write permissions in project directory
• For PostgreSQL, ensure database exists and credentials are correct

OpenAI API errors:

• Verify OPENAI_API_KEY is set in .env
• Check API key is valid and has credits

ChromaDB errors:

• Delete backend/chroma_data directory and re-run seed script
• Ensure write permissions for ChromaDB directory

Frontend Issues

Module not found:

• Run npm install in frontend/ directory
• Clear .next cache: rm -rf frontend/.next

API connection errors:

• Verify backend is running on port 8000
• Check NEXT_PUBLIC_API_BASE_URL in .env.local
• Check CORS settings in backend config

Build errors:

• Clear node_modules and reinstall: rm -rf node_modules && npm install
• Check Node.js version (requires 18+)

📝 License

This project is proprietary software for Nash Paints.

👥 Contributing

This is a private project. For contributions, contact the project maintainer.

🔮 Future Enhancements

• Real-time stock updates
• User authentication and saved projects
• Advanced image-to-image diffusion for repaints
• Multi-language support
• Mobile app
• Integration with Nash Paints e-commerce platform
• Advanced color matching algorithms
• Paint quantity calculator
• Project cost estimation

---

Built with ❤️ for Nash Paints