README.md

# 🤖 AI Client Acquisition System

> Enterprise-grade, hyper-intelligent lead discovery, profiling, and scoring pipeline.  
> Built with production AI engineering practices — not n8n-style hype.

[![Phase](https://img.shields.io/badge/Phase-1%20Finding-blue)]()
[![Models](https://img.shields.io/badge/AI-MiniMax%20M2.7%20%2B%20LLaMA-green)]()
[![Cost](https://img.shields.io/badge/LLM%20Cost-%240%2Fday-brightgreen)]()
[![Trigger.dev](https://img.shields.io/badge/Orchestration-Trigger.dev-purple)]()

---

## What This System Does

Automatically discovers, qualifies, and profiles potential clients for an AI automation agency.

```
Every day at 9 AM PKT:
  1. Pick next territory (city × industry) → 27 cities, auto-rotation
  2. Search Google for companies → Serper API
  3. Scrape each website → Playwright (headless)
  4. Detect pain signals → "no chatbot", "phone booking only", etc.
  5. Gate 2: Skip if < 2 pain signals
  6. Find decision-maker emails → Hunter.io + Pattern Generation + SMTP
  7. Verify emails → 7-layer verification (FREE)
  8. Find personal LinkedIn + social profiles
  9. AI profiling → MiniMax M2.7 (chain-of-thought reasoning)
  10. Deterministic scoring → 100-point scale, zero hallucination
  11. Alert on Slack → hot leads (85+) instant, daily digest for all
```

## Architecture

```
┌─────────────────────────────────────────────────────┐
│ CRON: daily-lead-discovery (4 AM UTC = 9 AM PKT)   │
│   → Territory Manager → Google Search → Queue       │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼ (max 3 concurrent)
┌─────────────────────────────────────────────────────┐
│ TASK: process-company                               │
│   → Scrape → Pain Signals → Gate 2                  │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│ TASK: enrich-and-profile                            │
│   → Hunter → Pattern Gen → SMTP → LinkedIn         │
│   → Python AI Service → Save → Slack Alert          │
└─────────────────────────────────────────────────────┘
```

## Model Chain (All FREE on NVIDIA NIM)

| Priority | Model | Parameters | Use Case |
|----------|-------|-----------|----------|
| 1st | MiniMax M2.7 | ~100B+ | Profiling, scoring, complex reasoning |
| 2nd | LLaMA 3.3 70B | 70B | Reliable fallback |
| 3rd | LLaMA 3.1 8B | 8B | Email classification, simple tasks |
| 4th | Deterministic | — | Zero hallucination fallback |

**Single API key. Single endpoint. $0/day.**

## Scoring System (100 points, fully deterministic)

```
Company Fit:      25 pts   (industry + size match)
AI Readiness:     20 pts   (tech stack + AI jobs)
Service Match:    20 pts   (pain signals → our services)
Decision Maker:   20 pts   (verified email + LinkedIn + authority)
Timing:           15 pts   (growth signals + active website)

Tiers: hot (85+) | warm (70-84) | nurture (50-69) | archive (<50)
```

## Tech Stack

| Layer | Technology | Purpose |
|-------|-----------|---------|
| Orchestration | Trigger.dev | CRON, task chaining, retry, queuing |
| Database | Supabase (PostgreSQL) | Data storage, config, state |
| LLM | NVIDIA NIM (MiniMax + LLaMA) | AI profiling & analysis |
| Web Scraping | Playwright | Headless browser |
| Email | Hunter.io + SMTP | Finding & verification |
| Notifications | Slack Bot | Alerts, commands, digest |
| AI Service | Python FastAPI | Profiling, scoring, hallucination guard |
| Language | TypeScript + Python | Core logic |

## Project Structure

```
src/
├── discovery/                    # Phase 1: Finding pipeline
│   ├── lib/                      # Core logic
│   │   ├── contact-enricher.ts   # 6-step email pipeline
│   │   ├── email-classifier.ts   # Tier 1/2/3 classification
│   │   ├── email-verifier.ts     # 7-layer verification
│   │   ├── email-pattern-generator.ts  # FREE Snov replacement
│   │   ├── linkedin-person-finder.ts   # Personal LinkedIn
│   │   ├── social-finder.ts      # Instagram, Facebook, Twitter
│   │   ├── pain-signal-detector.ts     # Heuristic + LLM
│   │   ├── territory-manager.ts  # City×industry grid
│   │   └── web-scraper.ts        # Playwright scraper
│   ├── providers/                # External APIs
│   │   ├── hunter.ts             # Hunter.io integration
│   │   ├── serper.ts             # Google search
│   │   └── reoon.ts              # Email verification
│   └── trigger-tasks/            # Trigger.dev tasks
│       ├── auto-discovery.ts     # 5 chained tasks
│       └── manual-discovery.ts   # Slack-triggered runs
├── profiling/                    # AI profiling service
│   └── python-service/           # FastAPI
│       ├── main.py               # /profile endpoint
│       ├── profiler.py           # Chain-of-thought profiling
│       ├── scorer.py             # Signal extraction + deterministic math
│       ├── hallucination_guard.py # Evidence-based cross-check
│       ├── nvidia_client.py      # Multi-model LLM client
│       └── config.py             # Settings
├── shared/                       # Shared utilities
│   ├── config/env.ts             # Environment validation (Zod)
│   ├── llm/nvidia-client.ts      # Multi-model LLM (MiniMax primary)
│   ├── llm/prompts.ts            # Production prompts
│   ├── llm/grounding.ts          # Evidence-based verification
│   ├── observability/tracer.ts   # Trace IDs + token tracking
│   ├── pipeline/checkpoint.ts    # Crash recovery
│   ├── supabase/client.ts        # DB client
│   └── utils/                    # Retry, rate limiter, logger
└── slack/                        # Slack integration
    ├── slack-service.ts          # 3-layer delivery
    └── slack-commands.ts         # /discover, /leads, /status, etc.
```

## Quick Start

See [Setup Guide](docs/setup-guide.md) for detailed instructions.

```bash
# 1. Clone
git clone https://github.com/iDevBuddy/ai-client-acquisition.git
cd ai-client-acquisition

# 2. Install
npm install
cd src/profiling/python-service && pip install -r requirements.txt && cd ../../..

# 3. Configure
cp .env.example .env
# Fill in your API keys (see docs/setup-guide.md)

# 4. Database
# Run supabase/migrations/*.sql on your Supabase project

# 5. Run
npm run trigger:dev          # Start Trigger.dev (task orchestration)
cd src/profiling/python-service && python main.py  # Start AI service
```

## API Keys Required

| Service | Cost | What It Does |
|---------|------|-------------|
| NVIDIA NIM | FREE | AI models (MiniMax + LLaMA) |
| Serper.dev | FREE (2500/mo) | Google search |
| Hunter.io | FREE (25/mo) | Email finding |
| Reoon | FREE (20/day) | Email verification |
| Supabase | FREE | Database |
| Slack | FREE | Notifications |
| Trigger.dev | FREE (50K runs/mo) | Job orchestration |

**Total cost: $0/month**

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

Private — All rights reserved.