AI Lead Qualification Engine

Production-ready FastAPI service for qualifying inbound leads using structured business signals, unstructured notes, optional LLM refinement, and CRM-ready outputs.

What this project does

This system receives raw inbound leads from forms, chatbots, CRMs, or automation tools and returns:

• a lead score from 0 to 100
• intent classification (high, medium, low)
• business priority label (urgent, normal, low) and priority class (p0, p1, p2)
• enrichment tags
• recommended next action
• an outreach-ready event payload for downstream automation

It is designed to look like a serious internal product, not a toy demo.

---

Architecture

Inbound lead (form / chatbot / CRM)
              |
              v
        FastAPI API Layer
              |
              +--> Enrichment Service
              |
              +--> Rules-based Scoring Engine
              |
              +--> Optional LLM Refinement
              |
              v
        Qualification Service
              |
              +--> Persist to DB (SQLite by default, Postgres-ready)
              |
              +--> Outreach Event Builder
              v
      CRM / automation / nurture workflows

Main modules

• lead_qualification_engine/api/routes: HTTP endpoints
• lead_qualification_engine/services/scoring.py: deterministic lead qualification logic
• lead_qualification_engine/services/llm.py: optional OpenAI-based refinement layer
• lead_qualification_engine/services/enrichment.py: metadata enrichment helpers
• lead_qualification_engine/services/qualification.py: orchestration and persistence
• lead_qualification_engine/models: database tables
• lead_qualification_engine/schemas: request / response models
• tests: API and scoring tests

---

Features

1. Lead scoring

The scoring engine uses:

• company size
• budget
• revenue
• timeline urgency
• source quality
• free-text buying intent signals

2. Intent classification

Maps leads into:

• high: route to sales immediately
• medium: nurture + discovery outreach
• low: low-touch nurture flow

3. Optional LLM refinement

If ENABLE_LLM=true and an API key is configured, the baseline result can be refined with an LLM for more nuanced reasoning.

4. Enrichment

Adds CRM-friendly metadata such as:

• email domain
• company tier
• source bucket

5. Outreach integration

Generates an event payload that can be sent to:

• n8n
• Zapier
• HubSpot workflows
• custom CRM automations

---

Tech stack

• API: FastAPI
• Validation: Pydantic v2
• DB: SQLAlchemy 2.0
• Storage default: SQLite
• Production DB ready: Postgres via DATABASE_URL
• LLM integration: OpenAI-compatible HTTP API
• Tests: Pytest
• Container/dev setup: Docker Compose

---

Project structure

ai-lead-qualification-engine/
├── lead_qualification_engine/
│   ├── api/routes/
│   ├── core/
│   ├── models/
│   ├── schemas/
│   ├── services/
│   └── main.py
├── tests/
├── .env.example
├── docker-compose.yml
├── requirements.txt
└── README.md

---

Quickstart

1. Clone and enter the repo

git clone <your-repo-url>
cd ai-lead-qualification-engine

2. Create environment

python -m venv .venv
source .venv/bin/activate   # macOS / Linux

3. Install dependencies

pip install -r requirements.txt

4. Create .env

cp .env.example .env

5. Start the API

uvicorn lead_qualification_engine.main:app --reload

Open:

• Swagger UI: http://127.0.0.1:8000/docs
• Health: http://127.0.0.1:8000/health

---

Example API request

POST /leads/qualify

{
  "full_name": "Jane Founder",
  "email": "jane@company.com",
  "company": "Acme Corp",
  "job_title": "CEO",
  "source": "website",
  "industry": "SaaS",
  "country": "United States",
  "company_size": 250,
  "annual_revenue": 2000000,
  "budget": 20000,
  "timeline_days": 10,
  "website": "https://company.com",
  "notes": "Budget approved. Need integration and a demo next week."
}

Example response

{
  "id": 1,
  "full_name": "Jane Founder",
  "email": "jane@company.com",
  "company": "Acme Corp",
  "job_title": "CEO",
  "source": "website",
  "industry": "SaaS",
  "country": "United States",
  "company_size": 250,
  "annual_revenue": 2000000.0,
  "budget": 20000.0,
  "timeline_days": 10,
  "website": "https://company.com/",
  "notes": "Budget approved. Need integration and a demo next week.",
  "score": 82,
  "intent": "high",
  "confidence": 0.96,
  "priority": "urgent",
  "priority_class": "p0",
  "recommended_action": "Route to sales immediately and trigger 15-minute follow-up.",
  "tags": ["high_budget", "priority_source", "saas", "united_states", "mid_market", "organic"],
  "needs_follow_up": true,
  "llm_reasoning": null,
  "created_at": "2026-04-16T15:30:00.000000"
}

---

Quick Demo

curl -X POST http://localhost:8000/leads/qualify \
-H "Content-Type: application/json" \
-d '{
  "name": "John Doe",
  "email": "john@example.com",
  "message": "Interested in pricing and demo",
  "source": "website"
}'

---

Output

{
  "score": 85,
  "intent": "high",
  "priority": "urgent",
  "recommended_action": "Follow up within 5 minutes"
}

---

Running tests

pytest -q

---