Lead Scoring Pipeline

An end-to-end lead scoring and assignment demo pipeline built with FastAPI, scikit-learn, OR-Tools, and Streamlit.

Project Overview

This repository contains a synthetic lead scoring demo that can be wired into Salesforce via Apex triggers and scheduled export jobs.

Key features:

• Synthetic lead generation with a latent quality signal
• Gradient Boosting model training and inference
• Sales assignment optimizer with seniority routing and industry quotas
• Email reply intent scoring using a DeBERTa MNLI cross-encoder (cross-encoder/nli-deberta-v3-small)
• Streamlit dashboard for score inspection and assignment visualization
• Dockerized deployment for API, dashboard, and scheduler

Repository Structure

• app/ — FastAPI application and business logic
  • app/main.py — FastAPI entrypoint
  • app/api/routes/ — HTTP route handlers
  • app/services/ — score, optimization, and Salesforce mapping logic
  • app/email_intelligence/ — MNLI analysis loader and helpers
  • app/schemas/ — Pydantic request/response models
• config/optimizer.json — team roster, quotas, and assignment settings
• data/simulate.py — synthetic lead generator
• models/train.py — training script for models/lead_scorer.pkl
• jobs/scheduled_assignment.py — scheduled export workflow
• streamlit_app.py — Streamlit dashboard
• docker-compose.yml — API, dashboard, and scheduler services
• Dockerfile — single image for all services
• docker-entrypoint.sh — first-run bootstrap for data/model assets
• SALESFORCE_INTEGRATION.md — Salesforce setup and Apex integration guide
• output/ — generated assignment CSVs (ignored by git)

Getting Started

Local Python Setup

1. Create a virtual environment and install dependencies:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

2. Generate synthetic data:

python data/simulate.py

3. Train the lead scoring model:

python models/train.py

Run the API

uvicorn app.main:app --reload

Run the Streamlit Dashboard

streamlit run streamlit_app.py

Run Scheduled Assignment Export Manually

python jobs/scheduled_assignment.py

Docker

Build and start all services:

docker compose up --build

Run in detached mode:

docker compose up --build -d

Stop services:

docker compose down

Clean volumes and cache::

docker compose down -v

API Endpoints

• GET /health — health check
• POST /score/lead — score a single lead
• POST /score/batch — score multiple leads
• POST /score/optimize — assign leads to sales reps
• POST /ingest/score — ingest and score a Salesforce lead payload
• POST /ingest/score/batch — batch ingest and score leads
• POST /ingest/leads — ingest raw leads
• POST /email/analyze — analyze a prospect reply and blend MNLI intent score
• GET /email/benchmark — run the fixed MNLI benchmark suite
• POST /export/trigger — trigger assignment export
• GET /export/assignments — download assignment CSVs
• POST /simulation/verify — kick off a capped Monte Carlo simulation-verification run
• GET /simulation/verify/{run_id} — poll status / fetch the summary once done
• GET /model/metrics — AUC-ROC/PR, Brier, ECE pre/post calibration, confusion matrix, ROC curve
• GET /model/calibration — reliability-diagram data for the raw and calibrated model
• GET /model/feature-importance — impurity-based and permutation feature importances
• GET /model/uncertainty — Monte Carlo score distribution for a lead profile
• GET /figures/simulation/* — Monte Carlo simulation figures (conversion-rate histogram, latent-decile monotonicity, causal graph, MC dashboard, correlation heatmap)
• GET /figures/model/* — ROC/PR curves, calibration curve, feature-importance chart
• GET /figures/mnli/confusion-matrix — MNLI benchmark confusion matrix
• GET /figures/optimizer/* — assignment heatmap, constraint-cost comparison
• GET /reports/simulation-validation-table — Monte Carlo validation summary table
• GET /reports/email-score-update-cases — representative email score-movement cases
• GET /reports/optimizer-validation-table — per-salesperson assignment/quota/capacity table

Important Design Notes

• Synthetic data is intentionally generated from a latent quality variable.
• MNLI scoring is only used on lead replies, not cold leads.
• Reply score blending is always 0.6 * MNLI + 0.4 * model_score.
• leads.csv is the demo persistence layer; no database is used.
• Business logic is implemented in app/services/, not route handlers.
• Seniority routing is enforced by the optimizer and should not be changed without updating all routing logic.

Salesforce Integration

See SALESFORCE_INTEGRATION.md for step-by-step Salesforce setup, Apex trigger code, and integration details.

Notes

• output/ is gitignored and stores generated assignment exports.
• models/lead_scorer.pkl is produced by models/train.py.
• data/leads.csv is generated by data/simulate.py and updated by scoring workflows.