lgf

# lgf — Lead Gen Factory

A CLI pipeline that takes a free-text ICP (Ideal Customer Profile) and returns
a scored, deduplicated list of B2B leads as both CSV and structured JSON.

## Prerequisites

Install lgf once (requires Python 3.12+):

```bash
# From the repo root
pip install -e .

# Or via pipx for isolated install
pipx install git+https://github.com/Catafal/lead-gen-factory.git
```

Verify installation:

```bash
lgf doctor
```

Required API keys (set in `~/.lgf/.env`):
- `TAVILY_API_KEY` — web search
- `OPENROUTER_API_KEY` — LLM scoring + extraction

---

## Core Command

```bash
lgf research --icp-text "<your ICP>" --json 2>/dev/null
```

The `--json` flag outputs a structured JSON envelope to stdout — perfect for
AI agents to capture and process without touching the filesystem.
All human-facing progress output goes to stderr (suppressed with `2>/dev/null`).

---

## Usage Patterns

### 1. Quick inline ICP (most common)

```bash
lgf research --icp-text "HR Directors at SaaS companies in Spain, 50-500 employees" --json 2>/dev/null
```

### 2. ICP from file (for complex profiles)

```bash
lgf research --icp icp_examples/skillia_spain.md --json 2>/dev/null
```

### 3. Narrow with a focus constraint

```bash
lgf research --icp-text "Tech companies in Madrid" --focus "only companies hiring L&D managers" --json 2>/dev/null
```

### 4. Filter by minimum ICP score

```bash
lgf research --icp-text "..." --min-score 8 --json 2>/dev/null
```

### 5. Dry-run — see search queries only (no crawling, no LLM calls)

```bash
lgf research --icp-text "..." --dry-run
```

### 6. Check current config

```bash
lgf config
```

---

## JSON Output Schema

When `--json` is used, the envelope printed to stdout has this structure:

```json
{
  "leads": [
    {
      "business": "Acme Corp",
      "first": "Ana",
      "last": "García",
      "email": "ana.garcia@acme.com",
      "linkedin": "https://linkedin.com/in/anagarcia",
      "website": "https://acme.com",
      "phone": null,...