RAG System Overview

The Retrieval-Augmented Generation (RAG) system is the backbone of Kinetic Email's AI-powered email generation. It combines vector search with Claude AI to produce production-ready kinetic email HTML.

What is RAG?

Instead of relying solely on Claude's general knowledge, we augment each generation request with relevant code examples and best practices from our curated knowledge base. This dramatically improves output quality for kinetic email — a niche domain where general-purpose LLMs lack sufficient training data.

Architecture

User Prompt
    │
    ▼
┌────────────────────────────┐
│  Technique Extraction       │
│  Parse "Kinetic Features"   │
│  Map to: tabs, carousel,    │
│  survey, quiz, etc.         │
└─────────┬──────────────────┘
          │
    ┌─────▼─────┐
    │  Parallel  │
    │  Queries   │
    │            │
    ├────────────┤
    │            │
    ▼            ▼
┌────────┐  ┌────────────┐
│Query A │  │ Query B    │
│Filtered│  │ Unfiltered │
│topK=10 │  │ topK=15    │
│technique│  │ broad      │
│ match  │  │ search     │
└───┬────┘  └─────┬──────┘
    │             │
    └──────┬──────┘
           │
    ┌──────▼──────┐
    │ Merge &     │
    │ Deduplicate │
    └──────┬──────┘
           │
    ┌──────▼──────┐
    │ Re-rank     │
    │ Claude Haiku│
    │ Select 7    │
    └──────┬──────┘
           │
    ┌──────▼──────┐
    │ Build       │
    │ Context     │
    │ - CODE      │
    │ - KNOWLEDGE │
    └──────┬──────┘
           │
    ┌──────▼──────────────┐
    │ Claude Sonnet       │
    │ Generate HTML       │
    │ with RAG context    │
    └─────────────────────┘

Pipeline Steps

1. Technique Extraction

The extractTechniqueFromPrompt() function parses the user's prompt for a **Kinetic Features:** section and maps it to a known technique:

Detected Feature	Pinecone Filter
Tabbed, tabs	tabs
Carousel, slider	carousel
Survey, poll	survey
Quiz, trivia	quiz
Accordion, expand	accordion
Hamburger, menu	menu
Stepper, wizard	stepper
Toggle, switch	toggle
AMP	amp4email

2. Dual-Query Strategy

Two Pinecone queries run in parallel:

• Query A (Filtered): Uses the extracted technique as a $eq metadata filter. Returns the top 10 most relevant code examples specifically for that technique.
• Query B (Unfiltered): No technique filter. Returns the top 15 most relevant results across all techniques. Captures blog posts, general best practices, and edge case knowledge.

3. Merge & Deduplicate

Results from both queries are combined and deduplicated by content hash.

4. Re-ranking with Claude Haiku

Claude Haiku evaluates all merged results and selects the best 7, optimizing for:

• Relevance to the user's prompt
• Diversity — mix of HTML code examples and knowledge articles
• Quality thresholds — HTML examples must score ≥50%, blog articles must score ≥40%

5. Context Assembly

Selected results are organized into two sections injected into Claude's system prompt:

## CODE EXAMPLES
[Relevant HTML code snippets demonstrating the technique]

## KNOWLEDGE & BEST PRACTICES
[Blog articles, compatibility notes, anti-patterns]

6. Generation

Claude Sonnet generates the final email HTML using the full system prompt (kinetic email rules + RAG context + user prompt).

Knowledge Base

The RAG knowledge base contains two types of content:

HTML Code Examples

Production-tested kinetic email HTML demonstrating specific techniques. Each example is tagged with:

• Technique (tabs, carousel, survey, etc.)
• Complexity (beginner, intermediate, advanced)
• Purpose (ecommerce, newsletter, transactional)
• Best practice tags (responsive, accessible, outlook-compatible)

Blog/Knowledge Articles

The rag-blogs/ directory contains 16 curated articles covering:

1. Purpose & overview of kinetic email
2. The kinetic declaration pattern
3. HTML scaffold structure
4. Component-specific guides (tabs, survey/quiz, accordion, carousel, menu, stepper, hero headers)
5. Critical rules and anti-patterns
6. Style strategy (6 separate <style> blocks)
7. Email client compatibility
8. Tracking implementation
9. Variation matrix

Technique Semantics

When content is uploaded to Pinecone, rich structural descriptions are injected into the embedding text. This helps the vector search understand technique-specific patterns:

tabs: "Radio button inputs sharing the same 'name' attribute create mutually
       exclusive tab selections. Active state highlighting via :checked + label
       selectors. Content panels shown/hidden with :checked ~ .content selectors."

These semantic descriptions are maintained in api/admin/submit-content.js and api/admin/update-content.js.

Pinecone Setup

Two indexes with different embedding dimensions:

Index	Dimensions	Model
Primary	1536	text-embedding-3-small
Large	3072	text-embedding-3-large

Both indexes are updated simultaneously when content is submitted or modified.