Files · Databricks Lead Intake Agent for SMB Financial Advisors

# Databricks Lead Intake Agent for SMB Financial Advisors
 
Qualify, score, and route prospective client inquiries from web forms, email, or chat, automatically scheduling follow-up calls for high-value leads.
 
Independent financial advisors lose 40% of web inquiries due to slow response. Manual sorting of tire-kickers vs. serious prospects wastes billable hours, and no-shows plague calendared consultations.
 
## Architecture
 
```
Web Form / Email / Chat
        │
        ▼
  ┌─────────────────┐
  │ ConfidenceRouter │  ← @reaatech/confidence-router
  │  (classify lead  │
  │   quality/intent) │
  └────────┬────────┘
           │
      ┌────┴────┐
      │  ROUTE  │  (high confidence)
      │ CLARIFY │  (ambiguous)
      │ FALLBACK│  (low confidence)
      └────┬────┘
           │ (ROUTE path)
           ▼
  ┌─────────────────┐
  │ Databricks LLM  │  ← @databricks/sdk-experimental
  │ (extract        │
  │  structured     │
  │  profile)       │
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ StructuredRepair │  ← @reaatech/structured-repair-core
  │ (repair messy   │
  │  LLM output)    │
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ BudgetEngine    │  ← @reaatech/agent-budget-engine
  │ (per-lead cost  │
  │  caps)          │
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ SessionContinuity│  ← @reaatech/session-continuity
  │ (DynamoDB       │
  │  conversation   │
  │  context)       │
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ AgentHandoff    │  ← @reaatech/agent-handoff
  │ (route qualified│
  │  lead to        │
  │  scheduler)     │
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ HubSpot         │  ← @hubspot/api-client
  │ (create contact,│
  │  deal, task)    │
  └─────────────────┘
 
Observability: Langfuse spans throughout
```
 
## Prerequisites
 
- Node.js >= 22, pnpm >= 10
- A Databricks workspace with model serving endpoints
- A HubSpot private app access token
- A Langfuse account (self-hosted or cloud)
 
## Setup
 
```bash
pnpm install
cp .env.example .env
# Fill in your API keys and configuration
pnpm dev
```
 
## Environment Variables
 
| Variable | Description |
|---|---|
| `DATABRICKS_HOST` | Databricks workspace URL |
| `DATABRICKS_TOKEN` | Databricks personal access token |
| `HUBSPOT_ACCESS_TOKEN` | HubSpot private app access token |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
| `LANGFUSE_BASE_URL` | Langfuse base URL |
| `AWS_REGION` | AWS region for DynamoDB |
| `DYNAMODB_SESSIONS_TABLE` | DynamoDB table name for sessions |
| `LEAD_BUDGET_LIMIT_USD` | Per-lead budget cap in USD |
| `CONFIDENCE_ROUTE_THRESHOLD` | Confidence threshold for routing (0.0-1.0) |
| `CONFIDENCE_FALLBACK_THRESHOLD` | Confidence threshold for fallback (0.0-1.0) |
 
## API
 
### POST /api/lead
 
Submit a lead inquiry for processing.
 
**Request body:**
 
```json
{
  "message": "I have $500k to invest and want to schedule a call",
  "source": "web_form",
  "contactEmail": "investor@example.com",
  "contactName": "Jane Doe"
}
```
 
**Response (ROUTE):**
 
```json
{
  "leadId": "uuid",
  "decision": "ROUTE",
  "profile": {
    "name": "Jane Doe",
    "email": "investor@example.com",
    "estimatedAssets": 500000,
    "status": "qualified"
  },
  "schedulingResult": {
    "scheduled": true
  }
}
```
 
**Response (CLARIFY):**
 
```json
{
  "leadId": "uuid",
  "decision": "CLARIFY"
}
```
 
**Response (FALLBACK):**
 
```json
{
  "leadId": "uuid",
  "decision": "FALLBACK",
  "error": "Low confidence"
}
```
 
## Decision Tree
 
- **ROUTE**: confidence >= routeThreshold (default 0.8) — high-quality lead, proceed to extraction and scheduling
- **CLARIFY**: routeThreshold > confidence >= fallbackThreshold (default 0.3) — ambiguous, request more information
- **FALLBACK**: confidence < fallbackThreshold — low quality, log and discard
 
## Development
 
```bash
pnpm dev        # Start development server
pnpm typecheck  # Type-check the codebase
pnpm lint       # Lint with ESLint
pnpm test       # Run tests with coverage
```
 
## Packages
 
### REAA Packages
 
| Package | Version | Role |
|---|---|---|
| `@reaatech/confidence-router` | 0.1.1 | Classify lead quality and intent from free-text |
| `@reaatech/session-continuity` | 0.1.0 | Maintain conversation context across touchpoints |
| `@reaatech/structured-repair-core` | 1.0.0 | Extract contact details from messy LLM output |
| `@reaatech/agent-handoff` | 0.1.0 | Route qualified leads to scheduling sub-agent |
| `@reaatech/agent-budget-engine` | 0.1.1 | Enforce per-lead cost caps across LLM calls |
 
### Third-Party Packages
 
| Package | Version | Purpose |
|---|---|---|
| `@databricks/sdk-experimental` | 0.18.0 | Databricks model serving endpoint calls |
| `@hubspot/api-client` | 13.5.0 | HubSpot CRM contact/deal/engagement creation |
| `langfuse` | 3.38.20 | Observability via traces and spans |
| `zod` | 4.4.3 | Runtime schema validation |
| `p-retry` | 8.0.0 | Retry with exponential backoff |
| `@aws-sdk/client-dynamodb` | 3.1073.0 | DynamoDB session storage |
| `@supabase/supabase-js` | 2.108.2 | Available for additional data storage |
 
## License
 
MIT