Production

Agentic B2B Lead Acquisition Engine

LeadForge AI

LeadForge AI automates end-to-end B2B sales development. It orchestrates a 4-phase asynchronous agent pipeline: Scout Agent (scraping), Enrichment Agent (contact mining), Auditor Agent (Lighthouse & social harvesting), and Copywriter Agent (Claude AI pitch generation) streaming live over Server-Sent Events (SSE).

GitHub Repository

Status

Production

Stack

Python, FastAPI, Playwright, Claude AI, Async SQLite, SSE Streaming

Throughput / Users

1,200+ Leads / Day

Performance

99.2% Uptime

System Architecture & Problem Statement

Core Problem Solved: Manual B2B lead generation requires hours of tedious web browsing, copying contact emails, manually checking website speed, and crafting individual outreach emails—resulting in slow outreach and low conversion rates.

Architecture Layers:

1FastAPI Async Backend: Controller layer with non-blocking event loops, custom SSE streaming routes, and REST endpoints.

24-Phase Multi-Agent Engine: ScoutAgent (Playwright browser automation), EnrichmentAgent (regex/DOM contact mining), AuditorAgent (PageSpeed API & SEO heuristics), and CopywriterAgent (Anthropic Claude 3.5 Sonnet API).

3Orchestrator Pipeline: 20-step execution state machine with automatic fallback error recovery, rate-limiting handlers, and queue dispatchers.

4Async SQLite Database (aiosqlite): Concurrent transaction store for leads, audit scores, generated email drafts, and outbound campaign status.

Key Product Features

Multi-Source Business Discovery (Justdial, Google Maps, Yelp via Playwright stealth)

Deep Contact Mining (Emails, Direct Phone, Social Links, Founder Names)

Automated PageSpeed & Mobile SEO Auditing Matrix

Lead Scoring & Tiering Matrix (A/B/C/D based on audit severity & revenue potential)

Claude AI Hyper-Personalized Pitch Generation (tailored pain points & performance fixes)

Real-Time Pipeline Execution Streaming via Server-Sent Events (SSE)

One-Click Automated Outreach via SMTP with custom HTML templates

Database Entity Schema & Relationships

Leads

Collection/Table

idattr

businessNameattr

websiteUrlattr

nicheattr

cityattr

tierScoreattr

statusattr

→ Has one AuditResult and many CopyDrafts

AuditResults

Collection/Table

leadIdattr

performanceScoreattr

seoScoreattr

mobileUsabilityattr

missingMetaattr

→ Belongs to Lead

CopyDrafts

Collection/Table

leadIdattr

subjectLineattr

emailBodyattr

painPointattr

sentAtattr

→ Belongs to Lead

API Specifications & Endpoints

POST/api/leads/discover

Triggers Playwright scout agents to find local businesses in a given city & niche.

GET/api/pipeline/stream/:sessionId

Real-time Server-Sent Events (SSE) endpoint streaming 20-step agent progress live.

POST/api/copy/generate

Invokes Claude 3.5 Sonnet to craft tailored outreach copy based on audit results.

POST/api/outreach/send

Dispatches personalized email via SMTP with delivery tracking.

Interactive Visual Screenshots & Previews

Pipeline Command Center Terminal

LIVE SIMULATION

[LEADFORGE-AI ENGINE v2.4]SSE STREAM ACTIVE

[04:02:11] ScoutAgent: Scraping 45 B2B leads in 'San Francisco' (Niche: SaaS)...

[04:02:14] EnrichmentAgent: Extracted 38 emails, 42 direct phone lines, 5 social links.

[04:02:18] AuditorAgent: Lighthouse PageSpeed score: 42/100 (LCP: 4.8s). Missing meta description.

[04:02:22] CopywriterAgent (Claude 3.5): Generated customized pitch hook. Tier A lead queued for outreach!

Real-time SSE streaming dashboard displaying live agent logs, active web scrapers, and lead enrichment steps.

Lead Intelligence & Audit Matrix

LIVE SIMULATION

Operational Metrics OverviewLive Telemetry

Total Throughput

1,240 / day

Avg Latency

18ms

Health Index

99.8%

Detailed audit breakdown showing PageSpeed scores, SEO deficiencies, contact details, and tier ranking.

🚀 Quick Start & Process to Run

STEP-BY-STEP REPRODUCIBLE SETUP

Prerequisites

Python 3.10+
Pip & Virtualenv
Playwright Chromium Browser
Anthropic API Key

Required Environment Variables (.env)

ANTHROPIC_API_KEY=sk-ant-...

PAGESPEED_API_KEY=AIzaSy...

SMTP_HOST=smtp.gmail.com

SMTP_PORT=587

SMTP_USER=user@domain.com

SMTP_PASS=app_password

Execution Steps:

1. Clone Repository & Create Virtual Environment

Initialize project codebase and activate isolated Python 3 environment.

$ git clone https://github.com/Dev-Nurul08/leadforge-ai.git && cd leadforge-ai && python -m venv venv && source venv/bin/activate

2. Install Python Dependencies & Playwright Browsers

Install FastAPI, Pydantic, aiosqlite, Anthropic SDK, and headless Chromium.

$ pip install -r requirements.txt && playwright install chromium

3. Configure Environment Credentials

Set ANTHROPIC_API_KEY, PageSpeed API key, and optional SMTP settings in .env file.

$ cp .env.example .env

4. Launch FastAPI Engine & Open Dashboard

Start Uvicorn server on http://localhost:8000 and view the agent control center.

$ python main.py

Engineering Challenges & Solutions

Challenge #1: Preventing anti-bot blocks when scraping business directories without relying on expensive proxy services.

Challenge #2: Streaming long-running multi-agent tasks (30s–2m) to the frontend interface without socket timeouts.

Key Lessons & Principles

Takeaway #1: Decoupling scraping, auditing, and LLM copy generation into distinct worker agents prevents single-point failure across external APIs.

Takeaway #2: Streaming granular progress logs builds user trust and makes multi-minute automated tasks feel instantaneous.