🛒 Procurement AI Assistant

🏆 Firebase Studio Enterprise Vibe Coding Hackathon Winner 2025
Part of Google Cloud Sweden Region Launch
Empowering retail buyers with AI-powered semantic search for intelligent procurement decisions.

🎯 Overview

Procurement AI Assistant transforms how retail buyers make purchasing decisions by providing instant, intelligent insights through natural language search. Instead of waiting days for engineering teams to provide data, buyers can now ask questions like "Show me sustainable dresses under $50 with reliable suppliers" and get actionable results in seconds.

✨ Key Features

• 🗣️ Natural Language Search - Query using plain English
• ⚡ Instant Results - Sub-3-second response times
• 📊 Smart Analytics - Supplier reliability, profit margins, return rates
• 🎯 Dual Purpose - Serves both procurement and marketing teams
• 🔍 Vector Search - Powered by advanced semantic understanding

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend API    │    │  Vector DB      │
│   (Firebase/    │    │                  │    │                 │
     Streamlit)   │◄──►│   (Cloud Run)    │◄──►│    (Qdrant)     │
│                 │    │   Superlinked    │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Tech Stack

• Backend: Python 3.11, Superlinked Framework, FastAPI
• Frontend: Next.js + TypeScript (Production) | Streamlit (Local Development)
• AI/ML: OpenAI GPT-4, Sentence Transformers, Vector Search
• Database: Qdrant Vector Database
• Infrastructure: Google Cloud Run, Firebase Hosting
• Data: Product catalog with enriched supplier metrics (Google Analytics 4 BigQuery dataset)

📋 Prerequisites

• Python 3.11+
• Node.js 18+ (for production frontend)
• Streamlit (for local development)
• Google Cloud Platform account
• OpenAI API key
• Qdrant Cloud account (optional, uses in-memory by default)

🛠️ Installation

Backend Setup

1. Clone the repository

   git clone https://github.com/yourusername/procurement-ai-assistant.git
   cd procurement-ai-assistant

2. Install dependencies

   pip install -r requirements.txt
   # or with uv (recommended)
   uv sync

3. Configure environment variables

   cp .env.example .env
   # Edit .env with your API keys and configuration

4. Start the server

   # Development
   make start-superlinked-server
   
   # Or directly
   uv run python -m superlinked.server

Quick Start with Streamlit (Local Development)

For rapid local development and testing:

1. Start the backend (follow steps 1-4 above)

2. Run Streamlit frontend

   streamlit run st_app/app.py

3. Access the app

   • Streamlit UI: http://localhost:8501
   • Backend API: http://localhost:8080

Production Frontend Setup (Next.js)

1. Navigate to frontend directory

   cd frontend

2. Install dependencies

   npm install

3. Configure environment

   cp .env.local.example .env.local
   # Add your backend API endpoint

4. Start development server

   npm run dev

🚀 Deployment

Deploy Backend to Google Cloud Run

1. Enable required APIs

   gcloud services enable run.googleapis.com cloudbuild.googleapis.com

2. Deploy using the provided script

   chmod +x deploy.sh
   ./deploy.sh

   Or manually:

   gcloud run deploy procurement-api \
     --source . \
     --platform managed \
     --region europe-north2 \
     --allow-unauthenticated \
     --memory 8Gi \
     --cpu 4 \
     --set-env-vars="ENVIRONMENT=production"

Deploy Frontend to Firebase

1. Install Firebase CLI

   npm install -g firebase-tools

2. Initialize and deploy

   firebase init hosting
   npm run build
   firebase deploy

📊 Usage Examples

Basic Search Queries

# Cost-optimized products
curl -X POST "https://your-api-url/api/v1/search/procurement_query" \
  -H "Content-Type: application/json" \
  -d '{"natural_query": "products with cost less than 5 dollars", "limit": 5}'

# High-margin, reliable suppliers
curl -X POST "https://your-api-url/api/v1/search/procurement_query" \
  -H "Content-Type: application/json" \
  -d '{"natural_query": "dresses with low cost and high revenue", "limit": 10}'

🔧 Configuration

Environment Variables

Data Schema

The system expects CSV data with the following columns:

product_id,name,category,brand,department,cost,retail_price,profit_margin_percent,
total_orders,return_rate_percent,supplier_reliability_score,avg_sale_price,
total_revenue,daily_sales_rate,days_since_creation,total_items_sold

🧪 Testing

Backend Tests

# Load test data
make load-data

# Test basic search
make test-search

# Test category-specific search
make test-category-search

Streamlit Development

# Quick test with Streamlit interface
streamlit run streamlit_app.py

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Superlinked for the semantic search framework
• Google Cloud for hosting infrastructure
• Codento for organizing the hackathon

Built with ❤️ by Amir

Transform your procurement process from reactive to predictive with AI-powered intelligence.