Files · Vertex AI Lead Intake for Amazon SP-API SMB Seller Acquisition

# Vertex AI Lead Intake for Amazon SP-API SMB Seller Acquisition
 
A conversational agent that qualifies prospective Amazon sellers, collects required documents, and registers them via SP-API — replacing static, high-drop-off registration forms.
 
## Problem
 
SMB sellers face significant friction when navigating Amazon's manual seller registration forms. Complex multi-page forms, unclear document requirements, and lack of guidance lead to 60%+ abandonment rates. This solution replaces static forms with a conversational AI agent that:
 
- Guides sellers through qualification with natural language
- Collects required business documents via chat
- Validates and repairs structured payloads automatically
- Registers sellers through Amazon's Selling Partner API
- Tracks costs with budget-aware LLM orchestration
 
## Setup
 
```bash
pnpm install
pnpm test            # vitest run with coverage
pnpm dev             # next dev (http://localhost:3000)
```
 
### Required environment variables
 
Copy `.env.example` to `.env` and fill in the values:
 
| Variable | Description | Links |
|----------|-------------|-------|
| `GOOGLE_CLOUD_PROJECT` | GCP project for Vertex AI | [Vertex AI setup](https://cloud.google.com/vertex-ai/docs/start/cloud-environment) |
| `GOOGLE_CLOUD_LOCATION` | GCP location (default: `us-central1`) | |
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to GCP service account JSON | |
| `AWS_REGION` | AWS region for IAM | [AWS IAM docs](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) |
| `AWS_ACCESS_KEY_ID` | AWS access key | |
| `AWS_SECRET_ACCESS_KEY` | AWS secret key | |
| `LWA_CLIENT_ID` | Login with Amazon client ID | [SP-API Developer Guide](https://developer-docs.amazon.com/sp-api/docs) |
| `LWA_CLIENT_SECRET` | Login with Amazon client secret | |
| `SP_API_REFRESH_TOKEN` | SP-API refresh token | |
| `LANGFUSE_PUBLIC_KEY` | Langfuse telemetry public key | [Langfuse](https://langfuse.com) |
| `LANGFUSE_SECRET_KEY` | Langfuse telemetry secret key | |
| `UNSTRUCTURED_API_KEY` | Unstructured.io API key | [Unstructured API](https://unstructured.io/api) |
| `BUDGET_PER_LEAD_USD` | Max cost per lead (default: 0.50) | |
| `BUDGET_DAILY_LIMIT_USD` | Daily budget cap (default: 10.00) | |
| `MODEL_ID` | Vertex AI model (default: `gemini-2.5-flash`) | |
 
## Architecture
 
```
User Chat → app/api/chat → IntakeMesh → LeadQualificationAgent → LeadBudgetTracker
                                              ↓
                                        LeadToRegistrationHandoff
                                              ↓
                                app/api/registration → SpApiClient → SP-API
                                              ↓
                                        BudgetTracker.recordSpend()
```
 
1. **Chat route** (`POST /api/chat`) — validates incoming messages with `IncomingRequestSchema`, dispatches to `IntakeMesh`
2. **Qualification agent** — uses Vertex AI Gemini to classify intent, qualify the lead, and decide routing confidence
3. **Budget check** — `LeadBudgetTracker` enforces per-lead and daily cost limits via `BudgetController`
4. **Handoff** — when confidence >= threshold, `LeadToRegistrationHandoff` initiates SP-API registration
5. **Registration route** (`POST /api/registration`) — validates and repairs payloads via `SpApiPayloadRepair`, calls SP-API
6. **Telemetry** — `TelemetryService` traces all LLM calls via Langfuse and records cost spans
 
## Package roles
 
### @reaatech packages
 
| Package | Role |
|---------|------|
| `@reaatech/agent-mesh` | Domain schemas (`IncomingRequestSchema`, `ContextPacketSchema`, `AgentResponseSchema`, `SessionRecordSchema`) and shared constants (`SERVICE_NAME`, `SERVICE_VERSION`, `CONFIDENCE`) |
| `@reaatech/agent-handoff` | Handoff protocol — `QualificationRouter` routes qualified leads to SP-API registration with retry, typed events, and configurable thresholds |
| `@reaatech/agent-budget-engine` | `BudgetController` with soft/hard caps per-lead and daily |
| `@reaatech/llm-cost-telemetry` | Cost calculation (`calculateCostFromTokens`) and `CostSpan` schema for telemetry records |
| `@reaatech/structured-repair-core` | LLM output repair via `repair`, `repairOutput`, `isValid`, `analyzeInput` — fixes markdown fences, type coercion, fuzzy key matching |
 
### Third-party packages
 
| Package | Role |
|---------|------|
| `@google-cloud/vertexai` | Gemini model access — `VertexAI` client for content generation, chat, streaming, and token counting |
| `@aws-sdk/client-iam` | `IAMClient` + `GetUserCommand` for validating AWS credentials before SP-API calls |
| `@assistant-ui/react` | Threaded chat UI primitives — `useLocalRuntime`, `ThreadPrimitive`, `ComposerPrimitive` |
| `@assistant-ui/react-markdown` | Markdown text primitive for rendering LLM responses inside chat bubbles |
| `react-markdown` | Markdown rendering via `Markdown` component with plugin support |
| `langfuse` | LLM observability — traces, generations, and cost tracking |
| `unstructured-client` | Document parsing — extracts business name, tax ID, and address from uploaded files |
| `next` | App Router framework with API routes and React Server Components |
| `zod` | Runtime validation — used by all `@reaatech/*` packages and route handlers |
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
  api/chat/route.ts   Conversational intake endpoint
  api/registration/   SP-API registration endpoint
  page.tsx            Chat UI with assistant-ui
src/                  Services, lib, adapters
  intake/             SpApiClient, LeadQualificationAgent, IntakeMesh, agent-handoff
  lib/                VertexAiClient, LeadBudgetTracker, TelemetryService, DocumentParser
  repair/             SpApiPayloadRepair with structured-repair-core
tests/                Vitest suite (mirrors src/)
packages/             API references for every dependency
```
 
## License
 
MIT — see [LICENSE](./LICENSE).