Research to Outreach is a monorepo that automates lead research and outreach by combining an AI research agent (powered by Anthropic) with a FastAPI backend and a React frontend. Given a search query, the system finds leads, enriches them with contact details and a research summary, and surfaces them in a dashboard for review and outreach.

┌─────────────────────────────────────────────────────────────────┐
│                         USER LAYER                              │
│  Slack Bot → Orchestrator → Research Agent → Strategy Agent    │
│  → Outreach Agent → Follow-up Agent                            │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                      DATA LAYER (Ghost DB)                      │
│  Master DB: jobs table                                          │
│  Per-Job DB: leads, strategy, email_log tables                 │
└─────────────────────────────────────────────────────────────────┘

• Location: agents/research/
• Purpose: Discovers and enriches leads using HasData + Gemini Flash
• Speed: ~2 seconds per lead (ultra-fast!)
• Cost: $0.002 per lead (200 leads FREE!)
• Input: job_id, query (e.g., "plumbing in Austin TX"), job_connection_string
• Output: Enriched leads in Ghost DB, job status → RESEARCH_COMPLETE
• Docs: See agents/research/README.md and agents/research/QUICKSTART.md

• Location: backend/
• Purpose: REST API for frontend, orchestrates agent pipeline
• Stack: FastAPI, asyncpg, Auth0

• Location: frontend/
• Purpose: Dashboard for viewing jobs and leads
• Stack: React, TypeScript, Vite

• Location: db/
• Schema: master_schema.sql (jobs), job_schema.sql (leads)

1. Install dependencies:

cd agents/research
pip install -r requirements.txt

2. Configure environment:

cp .env.example .env
# Edit .env with your API keys

3. Run test:

cd agents/research
python test_agent.py

See agents/research/QUICKSTART.md for detailed setup.

1. Clone the repository:

git clone <repo-url> && cd research-to-outreach

2. Copy the example env file:

cp .env.example .env
# Fill in your credentials

3. Start all services:

docker-compose up

Required in .env:

# Master Ghost DB
MASTER_DATABASE_URL=postgresql://ghost:***@<db>.ghost.build/postgres

# API Keys (both FREE tier available!)
HASDATA_API_KEY=your-api-key-here  # 200 leads FREE
GEMINI_API_KEY=AIzaSy...           # FREE tier
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=your-api-identifier

.
├── agents/
│   └── research/          # Research Agent (COMPLETE)
│       ├── agent.py       # Main orchestration
│       ├── search.py      # Google Maps API integration
│       ├── enrich.py      # Claude enrichment
│       ├── writer.py      # Ghost DB persistence
│       ├── test_agent.py  # Integration tests
│       └── README.md      # Full documentation
├── backend/
│   ├── main.py           # FastAPI app
│   ├── orchestrator.py   # Pipeline orchestration
│   └── auth.py           # Auth0 integration
├── frontend/
│   └── src/              # React app
├── db/
│   ├── master_schema.sql # Jobs table
│   ├── job_schema.sql    # Leads table
│   └── models.py         # Pydantic models
└── deploy/
    ├── Dockerfile.research
    └── truefoundry.yaml

• ✅ Research Agent: Complete and tested
• 🚧 Strategy Agent: TODO
• 🚧 Outreach Agent: TODO
• 🚧 Follow-up Agent: TODO
• 🚧 Orchestrator: Partial
• 🚧 Frontend: Partial

• Research Agent: agents/research/README.md
• Quick Start: agents/research/QUICKSTART.md
• Integration: agents/research/INTEGRATION.md

# Test Research Agent
cd agents/research
python test_agent.py

# Expected: 5 leads found, enriched, and saved to Ghost DB

See agents/research/INTEGRATION.md for TrueFoundry deployment instructions.

MIT