Lead Generation

# Lead Generation

The lead generation system provides a reusable outreach pipeline that any Amble tenant can use to discover prospective business partners, enrich them with web research, and draft personalized outreach emails.

## Overview

The system uses three entity types, one global agent, and configurable views to manage the full outreach lifecycle:

1. **Discovery** — Find companies via web search, create prospect records
2. **Enrichment** — Research prospects, capture details and reputation
3. **Email Drafting** — Generate personalized outreach using business-type templates
4. **Human Review** — Review drafts, approve, and send

## Entity Types

### Business Type

Categories of businesses to target. Each business_type entity holds:

- **Description** — What this type of business does
- **Email templates** — Subject and body templates with placeholders (`{company_name}`, `{to_name}`, `{our_company}`, etc.)
- **Value proposition** — How your services relate to their business
- **Search queries** — Web search templates with `{city}`/`{state}` placeholders
- **Relevant services** — Which of your services matter most to them

### Prospect

A discovered company in the outreach pipeline. Key fields:

- **business_type_name** — Denormalized from connected business_type entity (enables kanban groupBy)
- **service_area** — Geographic area where the company operates
- **outreach_status** — Pipeline stage: discovered → enriched → email_drafted → email_sent → responded → converted
- **enrichment_notes** — AI-generated research summary
- **Connection to business_type** — Structured link for template lookups

### Outbound Email

An AI-drafted outreach email. Key fields:

- **subject/body_text** — Personalized from business_type templates + prospect enrichment
- **channel** — email, snail_mail, or phone
- **status** — draft → ready → sent → opened → replied → converted
- **Connection to prospect** — Links email to its target

## Lead Finder Agent

A global system agent (`is_system: true`) that works for any tenant by reading workspace context at runtime.

### How It Works

1. Reads workspace agent_context to understand the business, services, geography
2. Searches for business_type entities to get target categories
3. For each category × city combination, uses webSearch to find companies
4. Creates prospect entities linked to the appropriate business_type
5. Enriches prospects with web research (enrichment_notes)
6. Drafts outbound_email entities using business_type email templates

### Heartbeat Schedule

Runs weekdays at 8 AM and 1 PM ET. Focuses on enrichment and email drafting. Discovery is triggered by users via chat.

### Chat Suggestions

- "Discover all prospects for every business type in our target area"
- "Enrich the next batch of discovered prospects"
- "Draft outbound emails for enriched prospects"
- "What's the current pipeline status?"

## Views

Six views manage the pipeline:

| View | Type | Groups By |
|------|------|-----------|
| Outreach Pipeline | Kanban | outreach_status |
| By Business Type | Kanban | business_type_name |
| By Service Area | Kanban | service_area |
| All Companies | Data Table | — |
| Email Queue | Data Table | — |
| Email Pipeline | Kanban | email status |

## Setting Up for a New Tenant

1. **Create business_type entities** — Define the categories of businesses to target, with email templates personalized for your business
2. **Configure workspace agent_context** — Add your company description, services, geography, and value propositions
3. **Use Lead Finder agent** — Available in chat for all tenants. Say "Discover realtors in [your city]" to start

The agent reads your workspace context and business_type entities to customize its behavior — no code changes needed.

## Design Decisions

- **business_type as entity type (not enum)** — Extensible without code changes. Users add new categories by creating entities.
- **Denormalized business_type_name** — Kanban can't group by connection fields (reads entity.content only). Stored as string for groupBy, with connection for structured navigation.
- **Global agent** — One agent definition serves all tenants. Personalization via workspace context injected at runtime by `buildAgentSystemPrompt()`.
- **Email templates on business_type** — Each category has its own outreach messaging. Agent reads templates and personalizes with prospect-specific details.

## Related Modules

- [Agent System](/docs/features/agent-system) — Agent runtime, heartbeat, tool resolution
- [Entity System](/docs/features/entity-system) — Entity types, connections, extraction
- [View System](/docs/features/view-system) — Kanban, data tables, block-based layouts