EasyPizzy - Smart Quick-Commerce Ordering Assistant

An AI-powered grocery ordering assistant that helps users describe their needs in natural language and receive optimized grocery orders from quick-commerce providers (Swiggy Instamart, Blinkit, Zepto) based on budget, health goals, and nutritional requirements.

🚀 Quick Start

Prerequisites

• Python 3.8+
• Node.js 16+
• npm or yarn

Backend Setup

1. Navigate to backend directory:

cd backend

2. Create virtual environment:

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

3. Install dependencies:

pip install -r requirements.txt

4. Add GEMINI_API_KEY (required for AI product search):

# Create .env in backend/ or set environment variable
export GEMINI_API_KEY=your_gemini_api_key_here
# Or add to a .env file (never commit .env - it's in .gitignore)

5. Run the server:

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

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

Frontend Setup

1. Navigate to frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Start development server:

npm run dev

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

📁 Project Structure

hackthon/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── main.py         # FastAPI app
│   │   ├── routes/         # API endpoints
│   │   ├── services/       # Business logic
│   │   ├── models/         # Pydantic models
│   │   └── utils/          # Utility functions
│   └── requirements.txt
├── frontend/                # React frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── services/       # API services
│   │   └── App.jsx         # Main app
│   └── package.json
└── README.md

🎯 Features

• Natural Language Input: Describe your grocery needs in plain English
• AI Constraint Extraction: Automatically extracts budget, health goals, and dietary preferences
• Smart Product Recommendations: Filters products based on constraints and pincode availability
• Real-time Budget Tracking: Visual budget tracker with warnings
• Nutrition Summary: Track protein, calories, carbs, and fats
• Cart Management: Add, remove, and adjust quantities
• Order Summary: Review order with provider breakdown
• Payment Integration: Generate payment links (mock for demo)

🔄 User Flow

1. Landing Page: Enter pincode
2. Input Screen: Describe needs in natural language
3. Constraint Visualization: Review and adjust extracted constraints
4. Product Recommendations: Browse and add products to cart
5. Order Summary: Review order details
6. Checkout: Proceed to payment
7. Confirmation: Order confirmed

🛠️ Technology Stack

Backend

• FastAPI - Modern Python web framework
• Pydantic - Data validation
• OpenAI (optional) - AI constraint extraction

Frontend

• React 18 - UI library
• React Router - Navigation
• Axios - HTTP client
• Vite - Build tool

📝 API Endpoints

• POST /api/v1/pincode/validate - Validate pincode
• POST /api/v1/ai/extract-constraints - Extract constraints from natural language
• POST /api/v1/products/recommend - Get product recommendations
• POST /api/v1/cart/validate - Validate cart
• POST /api/v1/order/summary - Generate order summary
• POST /api/v1/payment/generate-link - Generate payment link

See EasyPizzy_API_Specification.md for detailed API documentation.

🎨 Design Documents

• EasyPizzy_Design_Document.md - Complete UI/UX and system design
• EasyPizzy_API_Specification.md - Detailed API schemas
• EasyPizzy_Implementation_Roadmap.md - Development checklist

🧪 Testing

Backend

cd backend
uvicorn app.main:app --reload
# Visit http://localhost:8000/docs for interactive API docs

Frontend

cd frontend
npm run dev
# Visit http://localhost:3000

📦 Product Data & Index Setup

Product data and the search index are not committed (they're large and in .gitignore). You need to set them up before AI product search works:

1. Add product CSV files to ai-agent/data/:

   • Place CSV files with product data (e.g. atta.csv, meats.csv, protein.csv, fruit & veg.csv)
   • Format: multi-provider columns (zepto_*, blinkit.*, swiggy-instamart.*, etc.) or standard format with Source, Product Name, Category, etc.

2. Build the search index (required before first use):

cd ai-agent
python -m venv .venv  # if not already done
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install google-generativeai
python -m product_agent build --data-dir data

• This creates ai-agent/.index/products.db from the CSV files.
• Run again whenever you add or update product data.

Scaling: The system can be extended by adding more CSV data, integrating live provider APIs, or scraping product catalogs. More data = more pincodes and better coverage.

📍 Supported Pincodes

Currently supported pincodes (Delhi, Mumbai, Bangalore, Kolkata):

Pincode	City	State
110001	Delhi	Delhi
110002	Delhi	Delhi
400001	Mumbai	Maharashtra
560001	Bangalore	Karnataka
700001	Kolkata	West Bengal

These can be scaled by updating backend/app/utils/pincode_validator.py and adding more product data for new regions.

🔧 Configuration

Backend

• GEMINI_API_KEY (required): For AI-powered product search, intent parsing, and ranking. Get one at Google AI Studio.
• OPENAI_API_KEY in .env for AI constraint extraction (optional; default uses rule-based extraction)

Frontend

• API base URL is set in src/services/api.js
• Default: http://localhost:8000/api/v1

🚧 Hackathon MVP Scope

Implemented:

• ✅ Pincode validation
• ✅ Natural language input
• ✅ Constraint extraction (rule-based)
• ✅ Product recommendations
• ✅ Cart management
• ✅ Order summary
• ✅ Payment link generation (mock)

Future Enhancements:

• Real-time inventory sync
• Multiple provider order splitting
• User accounts and order history
• Recipe-based ordering
• Voice input support

📄 License

This project is created for hackathon purposes.

👥 Team

Built for hackathon - EasyPizzy Team

---

Happy Coding! 🎉