{"id":28564264,"url":"https://github.com/amirlayegh/procurement-ai-assistant","last_synced_at":"2025-06-10T13:35:57.302Z","repository":{"id":297931175,"uuid":"995312246","full_name":"AmirLayegh/procurement-ai-assistant","owner":"AmirLayegh","description":"🏆 AI Procurement Assistant - Google Cloud Sweden Hackathon Winner. Natural language search for retail buyers using Superlinked semantic search.","archived":false,"fork":false,"pushed_at":"2025-06-08T11:40:57.000Z","size":1690,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-08T12:30:20.232Z","etag":null,"topics":["hackathon-winner","information-retrieval","large-language-models","procurement","semantic-search","vector-database"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AmirLayegh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-03T09:39:22.000Z","updated_at":"2025-06-08T11:41:00.000Z","dependencies_parsed_at":"2025-06-08T12:41:31.576Z","dependency_job_id":null,"html_url":"https://github.com/AmirLayegh/procurement-ai-assistant","commit_stats":null,"previous_names":["amirlayegh/procurement-ai-assistant"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmirLayegh%2Fprocurement-ai-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmirLayegh%2Fprocurement-ai-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmirLayegh%2Fprocurement-ai-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmirLayegh%2Fprocurement-ai-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AmirLayegh","download_url":"https://codeload.github.com/AmirLayegh/procurement-ai-assistant/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmirLayegh%2Fprocurement-ai-assistant/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259085469,"owners_count":22803207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hackathon-winner","information-retrieval","large-language-models","procurement","semantic-search","vector-database"],"created_at":"2025-06-10T13:35:55.634Z","updated_at":"2025-06-10T13:35:57.285Z","avatar_url":"https://github.com/AmirLayegh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛒 Procurement AI Assistant\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![Google Cloud](https://img.shields.io/badge/Google%20Cloud-Run-4285F4?logo=google-cloud)](https://cloud.google.com/run)\n[![Superlinked](https://img.shields.io/badge/Powered%20by-Superlinked-FF6B6B)](https://superlinked.com)\n\n\u003e **🏆 Firebase Studio Enterprise Vibe Coding Hackathon Winner 2025**  \n\u003e *Part of Google Cloud Sweden Region Launch*  \n\u003e Empowering retail buyers with AI-powered semantic search for intelligent procurement decisions.\n\n## 🎯 Overview\n\nProcurement 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.\n\n### ✨ Key Features\n\n- 🗣️ **Natural Language Search** - Query using plain English\n- ⚡ **Instant Results** - Sub-3-second response times\n- 📊 **Smart Analytics** - Supplier reliability, profit margins, return rates\n- 🎯 **Dual Purpose** - Serves both procurement and marketing teams\n- 🔍 **Vector Search** - Powered by advanced semantic understanding\n\n\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Frontend      │    │   Backend API    │    │  Vector DB      │\n│   (Firebase/    │    │                  │    │                 │\n     Streamlit)   │◄──►│   (Cloud Run)    │◄──►│    (Qdrant)     │\n│                 │    │   Superlinked    │    │                 │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n```\n\n### Tech Stack\n\n- **Backend**: Python 3.11, Superlinked Framework, FastAPI\n- **Frontend**: Next.js + TypeScript (Production) | Streamlit (Local Development)\n- **AI/ML**: OpenAI GPT-4, Sentence Transformers, Vector Search\n- **Database**: Qdrant Vector Database\n- **Infrastructure**: Google Cloud Run, Firebase Hosting\n- **Data**: Product catalog with enriched supplier metrics (Google Analytics 4 BigQuery dataset)\n\n## 📋 Prerequisites\n\n- Python 3.11+\n- Node.js 18+ (for production frontend)\n- Streamlit (for local development)\n- Google Cloud Platform account\n- OpenAI API key\n- Qdrant Cloud account (optional, uses in-memory by default)\n\n## 🛠️ Installation\n\n### Backend Setup\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/yourusername/procurement-ai-assistant.git\n   cd procurement-ai-assistant\n   ```\n\n2. **Install dependencies**\n   ```bash\n   pip install -r requirements.txt\n   # or with uv (recommended)\n   uv sync\n   ```\n\n3. **Configure environment variables**\n   ```bash\n   cp .env.example .env\n   # Edit .env with your API keys and configuration\n   ```\n\n4. **Start the server**\n   ```bash\n   # Development\n   make start-superlinked-server\n   \n   # Or directly\n   uv run python -m superlinked.server\n   ```\n\n### Quick Start with Streamlit (Local Development)\n\nFor rapid local development and testing:\n\n1. **Start the backend** (follow steps 1-4 above)\n\n2. **Run Streamlit frontend**\n   ```bash\n   streamlit run st_app/app.py\n   ```\n\n3. **Access the app**\n   - Streamlit UI: `http://localhost:8501`\n   - Backend API: `http://localhost:8080`\n\n### Production Frontend Setup (Next.js)\n\n1. **Navigate to frontend directory**\n   ```bash\n   cd frontend\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Configure environment**\n   ```bash\n   cp .env.local.example .env.local\n   # Add your backend API endpoint\n   ```\n\n4. **Start development server**\n   ```bash\n   npm run dev\n   ```\n\n## 🚀 Deployment\n\n### Deploy Backend to Google Cloud Run\n\n1. **Enable required APIs**\n   ```bash\n   gcloud services enable run.googleapis.com cloudbuild.googleapis.com\n   ```\n\n2. **Deploy using the provided script**\n   ```bash\n   chmod +x deploy.sh\n   ./deploy.sh\n   ```\n\n   Or manually:\n   ```bash\n   gcloud run deploy procurement-api \\\n     --source . \\\n     --platform managed \\\n     --region europe-north2 \\\n     --allow-unauthenticated \\\n     --memory 8Gi \\\n     --cpu 4 \\\n     --set-env-vars=\"ENVIRONMENT=production\"\n   ```\n\n### Deploy Frontend to Firebase\n\n1. **Install Firebase CLI**\n   ```bash\n   npm install -g firebase-tools\n   ```\n\n2. **Initialize and deploy**\n   ```bash\n   firebase init hosting\n   npm run build\n   firebase deploy\n   ```\n\n## 📊 Usage Examples\n\n### Basic Search Queries\n\n```bash\n# Cost-optimized products\ncurl -X POST \"https://your-api-url/api/v1/search/procurement_query\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"natural_query\": \"products with cost less than 5 dollars\", \"limit\": 5}'\n\n# High-margin, reliable suppliers\ncurl -X POST \"https://your-api-url/api/v1/search/procurement_query\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"natural_query\": \"dresses with low cost and high revenue\", \"limit\": 10}'\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `OPENAI_API_KEY` | OpenAI API key for natural language processing | Required |\n| `QDRANT_URL` | Qdrant vector database URL | `localhost:6333` |\n| `QDRANT_API_KEY` | Qdrant API key | Optional |\n| `DATA_PATH` | Path to product CSV data | `./data/csv/products_enriched.csv` |\n| `USE_QDRANT_VECTOR_DB` | Use Qdrant vs in-memory database | `false` |\n| `CHUNK_SIZE` | Data processing chunk size | `10` |\n\n### Data Schema\n\nThe system expects CSV data with the following columns:\n\n```csv\nproduct_id,name,category,brand,department,cost,retail_price,profit_margin_percent,\ntotal_orders,return_rate_percent,supplier_reliability_score,avg_sale_price,\ntotal_revenue,daily_sales_rate,days_since_creation,total_items_sold\n```\n\n## 🧪 Testing\n\n### Backend Tests\n\n```bash\n# Load test data\nmake load-data\n\n# Test basic search\nmake test-search\n\n# Test category-specific search\nmake test-category-search\n```\n\n### Streamlit Development\n\n```bash\n# Quick test with Streamlit interface\nstreamlit run streamlit_app.py\n```\n\n\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch \n3. Commit your changes \n4. Push to the branch\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **Superlinked** for the semantic search framework\n- **Google Cloud** for hosting infrastructure\n- **Codento** for organizing the hackathon\n\n\n\n\n\n---\n\n**Built with ❤️ by Amir**\n\n*Transform your procurement process from reactive to predictive with AI-powered intelligence.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famirlayegh%2Fprocurement-ai-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famirlayegh%2Fprocurement-ai-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famirlayegh%2Fprocurement-ai-assistant/lists"}