Files · Anthropic Document Pipeline for Klaviyo SMB Email Campaigns

# Anthropic Document Pipeline for Klaviyo SMB Email Campaigns
 
Generate personalized marketing email content from product feeds and customer segments using Anthropic Claude, and push directly to Klaviyo for SMB campaign execution.
 
## Problem
 
Small business marketers spend hours manually creating email campaigns, repurposing product data and customer segments across multiple channels without consistency.
 
## Architecture
 
```
Product Feed (JSON URL)
       │
       ▼
ProductFeedLoader ──► Document[] ──► chunkDocuments()
       │
       ▼
SegmentService ──► Customer Segments (Klaviyo API)
       │
       ├── BudgetService.checkCost() ──► allowed?
       ├── CacheService.getCached() ──► hit? → reuse
       │
       ▼
ContentGenerator ──► Anthropic Claude ──► raw JSON
       │
       ▼
ContentRepair ──► (structured-repair-core) ──► EmailContent
       │
       ├── CampaignService.createCampaign() ──► Klaviyo API
       ├── BudgetService.recordSpend()
       ├── CacheService.setCached()
       └── TelemetryService.traceLLMCall()
```
 
## REAA Packages
 
- **@reaatech/hybrid-rag** — Domain types (Document, Chunk) and schemas for product catalog representation
- **@reaatech/structured-repair-core** — Repairs malformed LLM JSON outputs into valid schema-conforming data
- **@reaatech/agent-budget-engine** — Enforces per-scope LLM spend limits with pre-flight checks and auto-downgrade
- **@reaatech/llm-cache** — Semantic and exact-match caching for LLM responses
- **@reaatech/prompt-version-control** — Versioned prompt template management client
- **@reaatech/llm-cost-telemetry** — CostSpan types and utilities for tracking LLM spend
 
## Third-party APIs
 
- **Klaviyo** (klaviyo-api) — Campaign creation, segment retrieval, profile management
- **Anthropic Claude** (@anthropic-ai/sdk) — Email content generation
- **VoyageAI** (voyageai) — Embeddings for semantic cache matching
- **Upstash Vector** (@upstash/vector) — Vector storage for cache
- **Langfuse** (langfuse) — LLM tracing and telemetry
 
## Setup
 
```bash
pnpm install
cp .env.example .env
# Edit .env with your API keys
```
 
### Environment Variables
 
| Variable | Description |
|----------|-------------|
| `ANTHROPIC_API_KEY` | Anthropic Claude API key |
| `KLAVIYO_API_KEY` | Klaviyo API key |
| `VOYAGE_API_KEY` | VoyageAI API key |
| `UPSTASH_VECTOR_URL` | Upstash Vector URL |
| `UPSTASH_VECTOR_TOKEN` | Upstash Vector token |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
| `LANGFUSE_HOST` | Langfuse host URL |
| `PVC_API_KEY` | Prompt Version Control API key |
| `PVC_BASE_URL` | Prompt Version Control base URL |
| `PRODUCT_FEED_URL` | URL to JSON product feed |
| `KLAVIYO_LIST_ID` | Default Klaviyo list ID |
| `BUDGET_DAILY_LIMIT` | Daily LLM spend cap in USD |
| `LLM_MODEL` | Claude model identifier |
 
## Usage
 
### Generate email content for a segment
 
```bash
curl -X POST http://localhost:3000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "productFeedUrl": "https://example.com/products.json",
    "segmentName": "VIP Customers",
    "campaignGoal": "Promote new arrivals",
    "tone": "professional"
  }'
```
 
### Run the full pipeline and create campaigns
 
```bash
curl -X POST http://localhost:3000/api/campaigns \
  -H "Content-Type: application/json" \
  -d '{
    "productFeedUrl": "https://example.com/products.json",
    "listId": "YOUR_LIST_ID",
    "campaignGoal": "Seasonal sale",
    "tone": "friendly"
  }'
```
 
## Testing
 
```bash
pnpm test
```
 
The test suite covers happy paths, error paths, and boundary cases for every module. Coverage is measured on runtime code (`src/**/*.ts`, `app/**/route.ts`) with a 90% threshold on all metrics.