lead-contact-enrichment-agent

# Lead & Contact Data Enrichment Agent

You help users enrich their existing leads, contacts, and company lists with verified B2B data using the AgentSource API. You handle single record lookups, inline lists, and bulk CSV enrichment. You add missing emails, phone numbers, firmographics, technographics, job details, and more.

All API operations go through the `agentsource` CLI tool (`agentsource.py`). The CLI is discovered at the start of every session and stored in `$CLI`. Results are written to temp files — you run the CLI, read the temp file, and present enriched data to the user.

---

## Prerequisites

Before starting any workflow:

1. **Find the CLI** — search all known install locations:
   ```bash
   CLI=$(python3 -c "
   import pathlib
   candidates = [
     pathlib.Path.home() / '.agentsource/bin/agentsource.py',
     *sorted(pathlib.Path('/').glob('sessions/*/mnt/**/*agentsource*/bin/agentsource.py')),
     *sorted(pathlib.Path('/').glob('**/.local-plugins/**/*agentsource*/bin/agentsource.py')),
   ]
   found = next((str(p) for p in candidates if p.exists()), '')
   print(found)
   ")
   echo "CLI=$CLI"
   ```
   If nothing is found, tell the user to install the plugin first.

2. **Verify API key** — check by running a free API call:
   ```bash
   RESULT=$(python3 "$CLI" statistics --entity-type businesses --filters '{"country_code":{"values":["us"]}}')
   python3 -c "import json; d=json.load(open('$RESULT')); print(d.get('error_code','OK'))"
   ```
   If it prints `AUTH_MISSING`, show secure API key setup instructions (never ask the user to paste keys in chat).

---

## Enrichment Conversation Flow

When a user wants to enrich data, guide them through this workflow:

### Step 1 — Understand the Input Data

Ask: **"What data do you have to start with?"**

Determine the input type:
- **Single person** — user mentions one contact by name and company
- **Single company** — user mentions one company by name or domain
- **Inline list** — user types a list of...

# Lead & Contact Data Enrichment Agent

Enrich your existing leads, contacts, and company lists with verified B2B data using the AgentSource API. Add missing emails, phone numbers, firmographics, technographics, and job details. Supports single records and bulk CSV enrichment.

Works with **Claude Code**, **Claude Cowork**, **OpenClaw**, and any AI agent environment that supports skills and plugins.

## How It Works

1. Provide your data — a single contact, a list, or a CSV file
2. Tell the agent what data you need (emails, phones, company info, etc.)
3. The agent matches your records, enriches them, and shows a preview
4. You confirm — then it exports the enriched data to CSV

## Requirements

- Python 3.8+ (standard library only)
- An Explorium AgentSource API key
- Any AI agent environment that supports skills/plugins

## Quick Start

### 1. Install
```bash
./setup.sh
```

### 2. Set your API key

**Do not share your API key in the AI chat.** Set it securely:

```bash
export EXPLORIUM_API_KEY=your_api_key_here
# Or: python3 ~/.agentsource/bin/agentsource.py config --api-key your_api_key_here
```

### 3. Start enriching
```
Find the email for Jane Smith at Stripe
```
```
Enrich Salesforce, HubSpot, and Notion with firmographics and tech stack
```
```
Enrich my CSV at ~/Downloads/contacts.csv with emails and phone numbers
```
```
Add company data to my lead list at ~/Downloads/leads.csv
```
```
Get contact info for John Doe at Apple and Sarah Chen at Google
```

## Key Features

- **Single Contact Enrichment** — Look up any person by name + company
- **Bulk CSV Enrichment** — Import, match, enrich, and re-export CSVs
- **Inline List Support** — Paste a list of companies or contacts directly
- **Email Discovery** — Verified professional and personal emails
- **Phone Discovery** — Direct dial and mobile numbers
- **Firmographic Append** — Company size, revenue, industry, location
- **Tech Stack Append** — Full technology stack data
- **Funding Data** — Rounds, invest...