Skip to content

README.md

Latest commit

 

History

History
114 lines (90 loc) · 5.32 KB

README.md

File metadata and controls

114 lines (90 loc) · 5.32 KB
Raw

🚀 Multi-Agent Lead Intelligence System

An AI-powered lead intelligence platform that automatically researches companies, extracts contact information, and generates personalized outreach messages using a multi-agent pipeline. Designed to effortlessly scale using asynchronous processing.

🏗 Architecture

┌─────────────────────────────────────────────────┐
│              React + Vite Frontend              │
│         (Pulse Intelligence UI Design)          │
└────────────────────┬────────────────────────────┘
                     │ Axios HTTP
┌────────────────────▼────────────────────────────┐
│              FastAPI Backend                     │
│                                                  │
│  ┌──────────┐  ┌──────────────┐  ┌───────────┐  │
│  │Researcher│→ │Contact Finder│→ │ Outreach  │  │
│  │  Agent   │  │    Agent     │  │  Writer   │  │
│  └──────────┘  └──────────────┘  └───────────┘  │
│       ↓              ↓                ↓          │
│   DuckDuckGo    7-Step Pipeline   Groq LLM      │
│   + Scraping    Snippet→Scrape→   (Llama 3.3)   │
│                 Score→LLM         Last Resort   │
└──────────────────────────────────────────────────┘

✨ Core Features

  • Researcher Agent 🕵️‍♂️ — intelligently searches the web, scrapes multiple highly-relevant sources, and builds deeply curated profiles via LLM.
  • Contact Finder Agent 📞 — Deterministic-first, 7-step pipeline that minimises LLM usage:
    1. Cache check — returns instantly if company was already processed
    2. DDG snippet regex — runs regex on search snippets immediately (no scraping needed for most companies)
    3. Link ranking — scores URLs by domain (justdial/indiamart = +5, wikipedia = -5) using urlparse().netloc to avoid false matches
    4. Targeted scraping — scrapes only the top 4 ranked links + runs regex
    5. Confidence scoring — every result scored (phone +5, email +5, directory source +3); best picked
    6. /contact page fallback — tries /contact, /contact-us, /about on the official domain if still incomplete
    7. LLM fallback — called ONCE only if all above steps fail
  • Outreach Writer Agent ✍️ — Generates engaging and natural WhatsApp-style outreach messages personalized to the extracted data.
  • Parallel Batch Processing ⚡ — Blazing fast ingestion of multiple companies concurrently mapped via asyncio.gather.
  • Excel Batch Upload 📊 — Directly upload .xlsx spreadsheets to process 10s-100s of companies seamlessly.
  • Pulse Intelligence UI 🎨 — A premium dashboard design with rounded glass forms, dynamic red-to-coral gradients, pill-shaped accents, expand/collapse cells, and loading pulse states.

🛠 Tech Stack

Layer Technologies
Frontend React, Vite, Axios, Lucide React, Premium CSS (Inter font)
Backend Python, FastAPI, Uvicorn, Asyncio
LLM & AI Groq API (llama-3.3-70b-versatile)
Scraping logic Requests, BeautifulSoup4, DuckDuckGo Search (ddgs)

🚀 Getting Started Locally

Backend Setup

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Create environment configuration
cp .env.example .env
# Important: Open .env and add your Groq API key (GROQ_API_KEY)

uvicorn main:app --reload

Frontend Setup

cd frontend
npm install

# Create environment configuration
cp .env.example .env

npm run dev

🌍 Environment Variables Setup

Backend (backend/.env)

GROQ_API_KEY=your_groq_api_key_here

Frontend (frontend/.env)

VITE_API_BASE_URL=http://localhost:8000

🔌 API Endpoints Reference

Method Endpoint Description
GET /health API health and system check
POST /process-company Triggers agents on a single company string point
POST /process-excel Triggers parallel agents on multiple companies from .xlsx upload

🚢 Deployment Guide

Deploying the Backend (Render / Railway)

  1. In Render, select New Web Service and upload this repository.
  2. Select the Root Directory as backend.
  3. Start command: uvicorn main:app --host 0.0.0.0 --port $PORT
  4. Make sure to add the GROQ_API_KEY to the service environment variables!
  5. Note the generated service URL (e.g. https://lead-intel.onrender.com).

Deploying the Frontend (Vercel)

  1. In Vercel, select Add New Project and connect the repository.
  2. Select the Root Directory as frontend.
  3. Under Environment Variables, add VITE_API_BASE_URL with the URL from your deployed backend above.
  4. Hit Deploy and the Pulse design system UI will compile!