LeadIQ is a supplier-discovery and ranking platform for industrial sourcing workflows. The project combines a FastAPI backend, a LangGraph-style orchestration layer, PostgreSQL with pgvector, a lightweight ML ranker, and a Next.js interface to turn natural-language procurement requests into ranked supplier recommendations.
The system is designed to address a common industrial sourcing problem: procurement teams express a need in plain language, but supplier data is noisy, fragmented, and inconsistent. LeadIQ tackles that by:
- extracting structured requirements from free-form text,
- searching a supplier database semantically and by filter criteria,
- ranking candidates with a heuristic and ML-assisted score,
- explaining the recommendation in plain English,
- capturing human feedback to improve the ranking model over time.
This makes the project a good portfolio example for RAG-style retrieval, agentic orchestration, vector search, and feedback-driven ML.
The core repository is working in the current environment, but there is an important distinction between verified infrastructure and live benchmark metrics:
- Verified: the database connection succeeds on port 5433.
- Verified: the synthetic supplier generation path succeeds.
- Verified: the benchmark query generation path succeeds.
- Verified: the app bootstrap and evaluation entry-point run through the project code.
- Not yet verified: final live benchmark metric numbers from the Gemini-backed evaluation run, because the provider is currently rate-limited and returns quota exhaustion errors.
This means the product story is strong and the pipeline is real, but any final metric table should be treated as illustrative until a non-rate-limited provider or offline evaluation mode is used.
flowchart LR
A[User / Buyer Request] --> B[Next.js Frontend]
B --> C[FastAPI API]
C --> D[Agent Pipeline]
D --> E[LLM Requirement Extraction]
E --> F[Supplier Search]
F --> G[PostgreSQL + pgvector]
G --> H[Heuristic + ML Ranking]
H --> I[Recommendation + Explanation]
I --> J[Frontend Results]
J --> K[User Feedback]
K --> L[Feedback Store]
L --> M[Celery Retraining Task]
M --> N[Updated Ranker Model]
N --> O[Benchmark Evaluation]
O --> P[Metrics Dashboard]
The learning loop is implemented across the app API, the agent graph, and the reusable ranker:
User query
↓
Search / rank suppliers
↓
User marks relevant or irrelevant suppliers
↓
Feedback saved in the database
↓
Retraining task builds supervised training data
↓
Logistic model is updated
↓
Evaluation compares the new ranking against the previous one
- API feedback collection: backend/app/api/routes.py
- Agent orchestration: backend/app/agents/graph.py
- Ranking logic: backend/app/ml/ranker.py
- Retraining task: backend/app/tasks/celery_app.py
- A supplier ranking is converted into labeled training examples.
- Relevant and irrelevant choices are added to the ranking signal.
- The logistic-regression model can be retrained from those examples.
- The project has the right architecture for a realistic closed-loop learning system, even though the live benchmark numbers are currently blocked by external LLM quotas.
The repository currently includes the following implemented pieces:
- FastAPI backend with search, feedback, metrics, health, and evaluation endpoints
- SQLAlchemy async models for suppliers, query logs, feedback, benchmark queries, and evaluation runs
- PostgreSQL + pgvector retrieval layer for supplier search
- LangGraph-style orchestration flow for extract → search → rank → recommend
- LLM-backed requirement extraction and recommendation with Gemini and OpenAI support
- Local fallback mode when external LLM providers are unavailable or rate-limited
- Heuristic ranking plus optional logistic-regression ranking model
- Celery retraining and evaluation tasks
- Docker Compose orchestration for database, Redis, backend, worker, and frontend
- Next.js UI for supplier search and metrics
- Synthetic data generation scripts for suppliers and benchmark queries
- Backend: Python, FastAPI, SQLAlchemy, Celery
- Database: PostgreSQL, pgvector
- AI / LLM: LangChain, OpenAI, Gemini
- Agent workflow: LangGraph-style pipeline implemented in Python
- ML: scikit-learn, joblib, numpy
- Frontend: Next.js, React, TypeScript
- Infrastructure: Docker Compose, Redis
LeadIQ/
├── backend/
│ ├── app/
│ │ ├── agents/
│ │ ├── api/
│ │ ├── config.py
│ │ ├── database.py
│ │ ├── main.py
│ │ ├── ml/
│ │ ├── models/
│ │ ├── services/
│ │ ├── tasks/
│ │ └── utils/
│ ├── ml_models/
│ ├── scripts/
│ ├── requirements.txt
│ ├── run_eval.py
│ └── tests/
├── frontend/
│ ├── app/
│ └── package.json
├── .github/
│ └── workflows/
├── docker-compose.yml
├── README.md
├── .env
├── .env.example
├── .gitignore
└── LICENSE
- Docker and Docker Compose
- Python 3.11+
- A valid Gemini API key or OpenAI API key if using external LLM providers
- Optional: a local or offline mode configuration if you want the project to run without live model quota
The app reads environment variables from the project root .env file. Relevant values include:
OPENAI_API_KEY=
GEMINI_API_KEY=
LLM_PROVIDER=gemini
LLM_MODEL=gemini-3.6-flash
LLM_FALLBACK_MODEL=gemini-3.6-flash
LLM_TIMEOUT_SECONDS=30
DATABASE_URL=postgresql+asyncpg://leadiq:leadiq_secret@localhost:5433/leadiq
DATABASE_URL_SYNC=postgresql://leadiq:leadiq_secret@localhost:5433/leadiq
REDIS_URL=redis://localhost:6379/0The Docker Compose setup passes these settings into the backend and worker. The local port is set to 5433 to avoid a Windows PostgreSQL conflict on port 5432.
Create or update the root .env file and set the provider values required for your setup.
docker compose up -d postgres redisdocker compose up -d backend celery_worker frontend- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API docs: http://localhost:8000/docs
- Metrics endpoint: http://localhost:8000/metrics docker compose up -d backend celery_worker frontend
### 4) Access the app
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API docs: http://localhost:8000/docs
- Metrics endpoint: http://localhost:8000/metrics
## API endpoints
The following routes are implemented in the backend:
## API endpoints
The following routes are implemented in the backend:
| Method | Endpoint | Purpose |
|---|---|---|
| POST | `/api/v1/search` | Run the supplier-search pipeline for a natural-language query |
| POST | `/api/v1/feedback` | Record user feedback for a ranked supplier |
| POST | `/api/v1/feedback/retrain` | Trigger the retraining path for the ranking model |
| GET | `/api/v1/metrics` | Return evaluation and feedback summary metrics |
| POST | `/api/v1/evaluate` | Run the benchmark evaluation workflow |
| GET | `/api/v1/health` | Check DB and Redis health |
| Method | Endpoint | Purpose |
|---|---|---|
| POST | `/api/v1/search` | Run the supplier-search pipeline for a natural-language query |
| POST | `/api/v1/feedback` | Record user feedback for a ranked supplier |
| POST | `/api/v1/feedback/retrain` | Trigger the retraining path for the ranking model |
| GET | `/api/v1/metrics` | Return evaluation and feedback summary metrics |
| POST | `/api/v1/evaluate` | Run the benchmark evaluation workflow |
| GET | `/api/v1/health` | Check DB and Redis health |
| GET | `/metrics` | Prometheus metrics |
## Evaluation and benchmark notes
This project includes a benchmark workflow for supplier ranking and retrieval. The synthetic dataset and benchmark-generation scripts have been verified in this environment, but the final live benchmark run remains blocked by provider quota exhaustion from the Gemini API.
The repository therefore demonstrates the full evaluation architecture, data-generation flow, and retraining loop without claiming final benchmark numbers from a successful live run.
## Demo guidance
The local UI can be used for a live product walkthrough, but it is not a reliable source of final benchmark metrics. The demo is best used to show the user flow, the extracted requirements, and the ranked supplier output rather than to claim measured quality numbers.
## Data and evaluation
The project includes scripts to generate synthetic supplier data and benchmark queries:
- `backend/scripts/generate_suppliers.py`
- `backend/scripts/generate_benchmarks.py`
- `backend/scripts/train_initial_ranker.py`
The benchmark workflow is built to support a real evaluation loop, but the actual live results must be regenerated under a configured provider without quota exhaustion before they are suitable for final portfolio reporting.
The evaluation workflow computes values such as:
- Recall@5
- Precision@5
- MRR
- NDCG@5
- Extraction field accuracy
- Tool success rate
- Latency and failure rate
## Known notes
- The app has a rule-based fallback for extraction/recommendation when the LLM is unavailable.
- LLM model names can change over time depending on the provider; the project therefore supports configuration via environment variables.
- The app is structured as a working implementation and demo platform rather than a fully production-hardened deployment.