AI Home Decor Agent 🏠✨

An AI-powered home decoration assistant that analyzes room photos and generates curated product recommendations matching your aesthetic and budget.

Overview

Upload room photos, describe your desired aesthetic (e.g., "Industrial-minimalist" or "Mid-century modern with warm woods"), set a budget, and get 20 perfectly curated home decor items with direct purchase links in ~10 seconds.

Key Features

• Smart Image Analysis: Uses Google Gemini to analyze room photos and understand spatial context
• Aesthetic Intelligence: Interprets free-text aesthetic descriptions to match your style
• Budget-Aware Curation: Ensures all recommendations fit within your specified budget
• Multi-Source Search: Leverages Perplexity AI and Pinterest for comprehensive product discovery
• Quality Validation: Built-in quality control to verify links, prices, and aesthetic matching
• Iterative Refinement: Up to 4 AI loops to optimize results and fill gaps

Technical Architecture

Backend Structure

backend/
├── config.py                          # Environment & API key management
├── server.py                          # Flask routes & middleware
├── orchestrator.py                    # Main AI processing pipeline
├── mcp.py                             # Model Control Protocol interface
└── apis/                              # Modular API services
    ├── gemini/
    │   ├── gemini_client.py           # Image analysis & tag generation
    │   └── mcp_interface.py           # MCP integration layer
    ├── perplexity/
    │   ├── perplexity_client.py       # Product search & web scraping
    │   └── mcp_interface.py           # MCP integration layer
    ├── pinterest/
    │   ├── pinterest_client.py        # Visual inspiration & discovery
    │   └── mcp_interface.py           # MCP integration layer
    └── quality_control/
        ├── quality_checker.py         # Result validation & filtering
        └── mcp_interface.py           # MCP integration layer

Processing Pipeline

1. Image Upload & Analysis - Gemini processes room photos and aesthetic description
2. Tag Generation - AI generates relevant product categories (plants, lighting, wall art, etc.)
3. Product Search - Perplexity and Pinterest search for matching products
4. Quality Control - Validates links, checks prices, filters by aesthetic match
5. Iterative Refinement - Loops up to 4 times to reach 20 quality items
6. Result Curation - Returns final grid of products with thumbnails and purchase links

Setup Instructions

Prerequisites

You need API keys for at least one of these services:

• Google Gemini API (required for image analysis)
• Perplexity AI API (required for product search)
• Pinterest API (optional, for visual discovery)

Installation

1. Clone the repository

   git clone <repository-url>
   cd fractal

2. Set up Python environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt

3. Configure environment variables

   cp .env.example .env
   # Edit .env and add your API keys:
   # GEMINI_API_KEY=your_gemini_api_key_here
   # PERPLEXITY_API_KEY=your_perplexity_api_key_here
   # PINTEREST_API_KEY=your_pinterest_api_key_here (optional)

4. Run the application

   cd backend
   python server.py

5. Access the web interface Open your browser to http://localhost:5000

Task Master Integration

This project is also set up with Task Master AI for development workflow management.

To use Task Master:

1. Add your API keys to .env
2. Enable taskmaster-ai in Cursor MCP settings
3. In Cursor chat: Initialize taskmaster-ai in my project
4. In Cursor chat: Can you parse my PRD at scripts/prd.txt?

Usage

Basic Workflow

1. Upload Images: Select 1-5 room photos (JPEG/PNG, ≥720×720px, max 5MB each)
2. Describe Aesthetic: Enter a style description like "Scandinavian minimalist" or "Bohemian with earth tones"
3. Set Budget: Enter your total budget in USD (must be > 0)
4. Generate: Click "Generate" and wait ~10 seconds for AI processing
5. Browse Results: View 20 curated items with images, prices, and "Buy" links

API Endpoints

• GET / - Main web interface
• POST /api/generate - Process images and generate recommendations

  {
    "images": ["base64_encoded_image_1", "base64_encoded_image_2"],
    "aesthetic": "Industrial-minimalist with warm metals",
    "budget": 300
  }

• GET /health - Health check endpoint

Expected Response Format

{
  "items": [
    {
      "url": "https://store.example.com/product/123",
      "title": "Industrial Metal Floor Lamp",
      "price": 89.99,
      "category": "lighting",
      "thumbnail": "https://images.example.com/thumb.jpg"
    }
  ],
  "total_items": 20,
  "iterations_used": 2,
  "warnings": []
}

API Service Details

Gemini Integration

• Purpose: Image analysis and semantic tag generation
• Capabilities: Room understanding, style interpretation, budget-aware refinement
• Rate Limits: Managed automatically with backoff strategies

Perplexity Integration

• Purpose: Product search and price extraction
• Capabilities: Web scraping, product discovery, link validation
• Search Strategy: Optimized queries like "buy {tag} under ${budget} online"

Pinterest Integration

• Purpose: Visual inspiration and aesthetic matching
• Capabilities: Pin search, shopping link extraction, visual similarity
• Content Filtering: Home decor focused, budget-appropriate

Quality Control

• Link Validation: Verifies product URLs are accessible
• Price Verification: Ensures prices are within budget constraints
• Aesthetic Matching: Scores items against the specified style
• Duplicate Detection: Removes similar items from different sources

Development

Project Structure

fractal/
├── README.md                           # This file
├── requirements.txt                    # Python dependencies
├── .env.example                        # Environment variables template
├── .gitignore                          # Git ignore rules
├── .cursorignore                       # Cursor AI ignore rules
├── backend/                            # Main application backend
├── frontend/                           # Web UI (future React app)
├── scripts/                            # Task Master & documentation
│   ├── prd.txt                        # Product Requirements Document  
│   └── example_prd.txt                # PRD template
├── tests/                              # Unit tests
└── venv/                              # Python virtual environment

Running Tests

cd backend
python -m pytest tests/ -v

Development Workflow

1. Use Task Master AI for task management and development planning
2. Follow the modular architecture - each API service is independent
3. Update MCP interfaces when adding new capabilities
4. Add tests for new features in the tests/ directory
5. Update documentation for API changes

Adding New API Services

1. Create new folder in backend/apis/your_service/
2. Implement your_service_client.py with core functionality
3. Create mcp_interface.py to define MCP integration
4. Update backend/mcp.py to register the new service
5. Add configuration in backend/config.py
6. Write tests in tests/test_your_service.py

Performance & Constraints

• Response Time: ~10-15 seconds for complete processing
• Image Limits: Up to 5 images, max 5MB each, min 720×720px
• Budget Range: $1 - $10,000 USD
• Result Count: Targets exactly 20 items, minimum 10
• API Rate Limits: Automatically managed with exponential backoff

Troubleshooting

Common Issues

• "No results found": Try broader aesthetic terms or increase budget
• "API service unavailable": Check API keys in .env file
• Slow responses: Some iterations may take longer due to web scraping
• Invalid links: Quality control catches most issues, but some may slip through

Error Codes

• 400: Invalid input (missing images, budget, or aesthetic)
• 401: Missing or invalid API keys
• 429: Rate limit exceeded, try again later
• 500: Internal processing error

Debug Mode

Set DEBUG=True in .env for detailed logging and error traces.

Future Enhancements

• Category Balancing: Force exactly 5 items per category (plants, lights, wall art, accents)
• Visual Similarity: Compare product thumbnails to room photos using image embeddings
• User Personalization: Save preferences and improve recommendations over time
• Mobile App: React Native wrapper for mobile experience
• Social Features: Share and favorite product collections
• Advanced Filtering: Price ranges, brand preferences, shipping options

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Task Master AI for development workflow management
• Google Gemini for image analysis capabilities
• Perplexity AI for intelligent product search
• Pinterest for visual inspiration and discovery