{"id":50530709,"url":"https://github.com/addy1997/procurement-agent","last_synced_at":"2026-06-03T13:02:12.225Z","repository":{"id":355261397,"uuid":"1227376973","full_name":"addy1997/procurement-agent","owner":"addy1997","description":"Agentic AI Hackathon","archived":false,"fork":false,"pushed_at":"2026-05-02T17:16:43.000Z","size":1593,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T18:31:54.042Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/addy1997.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-02T15:45:45.000Z","updated_at":"2026-05-02T17:16:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/addy1997/procurement-agent","commit_stats":null,"previous_names":["addy1997/procurement-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/addy1997/procurement-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/addy1997%2Fprocurement-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/addy1997%2Fprocurement-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/addy1997%2Fprocurement-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/addy1997%2Fprocurement-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/addy1997","download_url":"https://codeload.github.com/addy1997/procurement-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/addy1997%2Fprocurement-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33865655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2026-06-03T13:02:11.218Z","updated_at":"2026-06-03T13:02:12.217Z","avatar_url":"https://github.com/addy1997.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Procurement-Supervisor Agent\n\nA serverless AI-driven procurement orchestration system deployed on AWS Lambda (Python 3.12). A multi-agent supervisor routes incoming procurement requests to specialised sub-agents for supplier discovery, compliance validation, inventory synchronisation, and contract negotiation.\n\n## Architecture\n\n![System Architecture](https://github.com/addy1997/procurement-agent/blob/main/docs/System_Architecture.png)\n\nThe system operates across two layers:\n\n| Layer | Components |\n|---|---|\n| **Serverless AI Orchestration** | API Gateway → AWS Lambda (Procurement-Supervisor Agent) → Amazon S3 deployment |\n| **Enterprise-Grade Data Processing** | Compliance-Validator, Inventory-Orchestrator, Contract-Supervisor sub-agents |\n\n### Procurement-Supervisor Agent internals\n\n| Module | Responsibility |\n|---|---|\n| Intent Analysis (LLM) | Parses raw procurement queries into structured intents |\n| Task Delegation | Decides which sub-agent acts next |\n| Sub-Agent Routing | Dispatches work and collects results |\n| Data Synthesis | NumPy + Pydantic normalisation and ranking |\n| Error Handling | Centralised retry and failure capture |\n| Multi-Agent Orchestrator | Feedback loop that runs until the goal is reached |\n\n### Sub-agents\n\n| Agent | Responsibility |\n|---|---|\n| **Laptop-Finder Agent** | Discovers suppliers matching hardware specifications via MongoDB vector search |\n| **Compliance-Validator Agent** | Verifies vendor certifications and safety compliance using Groq LLM |\n| **Inventory-Orchestrator Agent** | Synchronises stock levels across internal ERP systems |\n| **Contract-Supervisor Agent** | Manages RFQ scheduling and negotiation workflows |\n\n## Repository Structure\n\n```\nprocurement-agent/\n├── main.py                              # Lambda entry point (LangGraph workflow)\n├── requirements.txt\n├── .env                                 # Local secrets (never committed)\n│\n├── agents/                              # All agent classes\n│   ├── __init__.py\n│   ├── supervisor.py                    # Procurement-Supervisor (orchestrator)\n│   ├── laptop_finder.py                 # Laptop-Finder Agent\n│   ├── compliance_validator.py          # Compliance-Validator Agent\n│   ├── inventory_orchestrator.py        # Inventory-Orchestrator Agent\n│   ├── contract_supervisor.py           # Contract-Supervisor Agent\n│   └── registry.py                      # Seeds agent registry in MongoDB\n│\n├── core/                                # Supervisor internals\n│   ├── intent_analysis.py               # LLM-based intent parsing\n│   ├── task_delegation.py               # Next-agent decision logic\n│   ├── data_synthesis.py                # NumPy/Pydantic ranking\n│   ├── error_handling.py                # Centralised error capture\n│   └── orchestrator.py                  # Multi-agent feedback loop\n│\n├── integrations/                        # External system connectors (aiohttp)\n│   ├── supplier_api.py                  # External Supplier APIs\n│   ├── erp_connector.py                 # Internal DBs / ERP Systems\n│   ├── compliance_db.py                 # Compliance Databases\n│   └── logistics_api.py                 # 3rd-Party Logistics\n│\n├── llm/\n│   └── groq_client.py                   # Groq LLM wrapper with conversation memory\n│\n├── config/\n│   └── config_manager.py                # AWS SSM Parameter Store / env-var loader\n│\n├── scripts/                             # Offline utilities (not deployed to Lambda)\n│   ├── seed_data.py\n│   ├── bulk_seed.py\n│   ├── create_embeddings.py\n│   ├── experience_collections_seed.py\n│   ├── check_setup.py\n│   ├── check_voyage_ai_setup.py\n│   └── aws_check.py\n│\n├── tests/\n│   └── test_search.py\n│\n├── infra/                               # Deployment tooling\n│   ├── build_lambda.py\n│   └── zip.py\n│\n└── docs/\n    └── architecture.png                 # System architecture diagram\n```\n\n## Tech Stack\n\n| Concern | Technology |\n|---|---|\n| Runtime | Python 3.12 / AWS Lambda |\n| Orchestration | LangGraph |\n| LLM | Groq (`llama-3.3-70b-versatile`) |\n| Embeddings | Voyage AI (`voyage-3`) |\n| Vector store | MongoDB Atlas (vector search indexes) |\n| HTTP (async) | aiohttp |\n| Data processing | NumPy, Pydantic |\n| Cloud infra | AWS Lambda, S3, API Gateway, SSM Parameter Store |\n| AWS SDK | Boto3 |\n\n## Setup\n\n### Prerequisites\n\n- Python 3.12\n- AWS account with Lambda, S3, API Gateway, and SSM Parameter Store access\n- [Groq API key](https://console.groq.com/)\n- [Voyage AI API key](https://www.voyageai.com/)\n- MongoDB Atlas instance with vector search enabled\n\n### Install dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n### Install git hooks (one-time, after cloning)\n\n```bash\nbash scripts/setup_hooks.sh\n```\n\nThis installs a pre-commit hook that blocks accidental commits of `.env` files and `venv/` directories.\n\n### Get your API keys\n\nYou need accounts and API keys from three services before running anything locally. The project does **not** ship any keys — you must supply your own.\n\n| Service | Where to get your key | Used for |\n|---|---|---|\n| **Groq** | [console.groq.com](https://console.groq.com/) → API Keys | LLM inference (free tier available) |\n| **Voyage AI** | [dashboard.voyageai.com](https://dashboard.voyageai.com/) → API Keys | Text embeddings (free tier: 200M tokens) |\n| **MongoDB Atlas** | [cloud.mongodb.com](https://cloud.mongodb.com/) → Database → Connect | Vector store + task persistence (free M0 cluster available) |\n\n\u003e **Voyage AI free tier note:** the free plan allows 3 requests per minute. The supervisor already inserts a 22-second cooldown between embedding calls to stay within this limit. If you upgrade to a paid plan you can reduce or remove those sleeps in `agents/supervisor.py`.\n\n### Create your `.env` file\n\nCreate a file named `.env` in the project root (it is git-ignored and will never be committed):\n\n```bash\ncp .env.example .env   # if .env.example exists, or create from scratch:\ntouch .env\n```\n\nThen open `.env` and fill in your keys:\n\n```dotenv\n# .env — never commit this file\n\n# Groq (https://console.groq.com/keys)\nGROQ_API_KEY=gsk_...\n\n# Voyage AI (https://dashboard.voyageai.com/api-keys)\nVOYAGE_API_KEY=pa-...\n\n# MongoDB Atlas connection string\n# Format: mongodb+srv://\u003cuser\u003e:\u003cpassword\u003e@\u003ccluster\u003e.mongodb.net/?appName=\u003capp\u003e\nMONGODB_URI=mongodb+srv://username:password@cluster0.xxxxx.mongodb.net/?appName=Cluster0\n\n# Optional — only needed for integrations/erp_connector.py\nERP_ENDPOINTS=https://erp1.example.com,https://erp2.example.com\n\n# Optional — only needed for integrations/supplier_api.py\nSUPPLIER_API_URL=https://api.supplier-directory.example.com\nSUPPLIER_API_KEY=\n\n# Optional — only needed for integrations/compliance_db.py\nCOMPLIANCE_DB_URL=https://compliance.example.com\nCOMPLIANCE_DB_KEY=\n\n# Optional — only needed for integrations/logistics_api.py\nLOGISTICS_API_URL=https://logistics.example.com\nLOGISTICS_API_KEY=\n```\n\nThe application loads this file automatically via `python-dotenv`. On AWS Lambda, set these as Lambda environment variables or store them in SSM Parameter Store — `config/config_manager.py` checks environment variables first, then falls back to SSM.\n\n### Seed the database\n\n```bash\npython scripts/seed_data.py               # seed supplier records\npython scripts/create_embeddings.py       # generate vector embeddings\npython agents/registry.py                 # register sub-agents in MongoDB\n```\n\n### Deploy to AWS Lambda\n\n```bash\npython infra/build_lambda.py\n```\n\nThe script packages the source into `procurbot_final.zip`, uploads it to the configured S3 bucket, and updates the Lambda function via the S3 URI.\n\n## Running Locally\n\n### 1. Clone the repository\n\n```bash\ngit clone https://github.com/addy1997/procurement-agent.git\ncd procurement-agent\n```\n\n### 2. Create and activate a virtual environment\n\n```bash\npython3 -m venv venv\n\n# macOS / Linux\nsource venv/bin/activate\n\n# Windows\nvenv\\Scripts\\activate\n```\n\n### 3. Install dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n### 4. Install git hooks (one-time)\n\n```bash\nbash scripts/setup_hooks.sh\n```\n\n### 5. Create your `.env` file\n\n```bash\ncp .env.example .env\n```\n\nOpen `.env` and fill in your Groq API key, Voyage AI API key, and MongoDB URI (see [Get your API keys](#get-your-api-keys) below).\n\n### 6. Seed the database (first run only)\n\nThis populates MongoDB with supplier records, generates vector embeddings, and registers the sub-agents. You need a working `.env` before running these.\n\n```bash\npython scripts/seed_data.py               # insert supplier records\npython scripts/create_embeddings.py       # generate and store embeddings\npython agents/registry.py                 # register sub-agents in MongoDB\n```\n\n### 7. Run the agent\n\n**Full pipeline** (Laptop-Finder → Compliance-Validator → synthesis):\n\n```bash\npython agents/supervisor.py\n```\n\n**Interactive chatbot** (single-turn RAG over the supplier database):\n\n```bash\npython llm/groq_client.py\n```\n\nType your query at the `You:` prompt. Type `exit` to quit.\n\n**Simulate a Lambda invocation** locally:\n\n```bash\npython -c \"\nfrom agents.supervisor import lambda_handler\nimport json\nresult = lambda_handler({'query': 'Find laptop suppliers in London'}, None)\nprint(json.loads(result['body'])['recommendation'])\n\"\n```\n\n### Rate limits on the free tier\n\nVoyage AI's free plan allows **3 requests per minute**. The supervisor inserts a 22-second cooldown between embedding calls automatically — expect each full pipeline run to take about 45–60 seconds.\n\n---\n\n## Usage\n\nInvoke via API Gateway or directly as a Lambda test event:\n\n```json\n{\n  \"query\": \"Find suppliers for industrial laptops under £40,000 with ISO 9001 certification\"\n}\n```\n\nThe supervisor routes the request through the sub-agent pipeline and returns:\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"recommendation\": \"Based on compliance validation and supplier discovery...\"\n  }\n}\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faddy1997%2Fprocurement-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faddy1997%2Fprocurement-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faddy1997%2Fprocurement-agent/lists"}