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    │
    └──────┬──────┘
           │
    ┌──────▼──────────────┐
    │ Filter by           │
    │ contentFocus        │
    │ (kinetic/amp/general)│
    └──────┬──────────────┘
           │
    ┌──────▼──────┐
    │ Build       │
    │ Context     │
    │ - CODE      │
    │ - KNOWLEDGE │
    └──────┬──────┘
           │
    ┌──────▼──────────────┐
    │ Blueprint           │
    │ (Haiku generates    │
    │  copy + design      │
    │  tokens)            │
    └──────┬──────────────┘
           │
    ┌──────▼──────────────┐
    │ Parallel Generation │
    │ ┌─────┐  ┌───────┐  │
    │ │Kine-│  │ AMP   │  │
    │ │tic  │  │4Email │  │
    │ │Sonn-│  │Sonnet │  │
    │ │et   │  │       │  │
    │ └─────┘  └───────┘  │
    └─────────────────────┘

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. Content Focus Filtering

After re-ranking, blog results are filtered by contentFocus to ensure the right knowledge reaches the right build:

Build Type	Blog Content Included
Kinetic	`contentFocus: 'kinetic'` + `contentFocus: 'general'`
AMP	`contentFocus: 'amp'` + `contentFocus: 'general'`

Blogs without a contentFocus value default to general and appear in both builds. HTML code examples always go to kinetic builds; AMP code examples always go to AMP builds.

6. Context Assembly

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

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

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

7. Blueprint Generation

Before code generation, Claude Haiku generates a structural blueprint containing:

Finalized copy — headlines, body text, CTAs used verbatim in all builds
Design system — color palette, typography, spacing, and button styles
Structure — section layout, interactive config, fallback strategy

The blueprint is the single source of truth for both kinetic and AMP builds, ensuring textual and visual parity.

8. Parallel Generation

Claude Sonnet generates kinetic HTML and (optionally) AMP4Email HTML in parallel, both referencing the same blueprint for consistent copy, colors, fonts, backgrounds, and button styling.

Knowledge Base

The RAG knowledge base contains three types of content:

HTML Code Examples (`type: 'html'`)

Production-tested kinetic CSS email HTML demonstrating specific techniques. Used only in kinetic builds. Each example is tagged with:

Technique (tabs, carousel, survey, etc.)
Complexity (beginner, intermediate, advanced)
Purpose (ecommerce, newsletter, transactional)
Example type (positive or negative/anti-pattern)
Best practice tags (responsive, accessible, outlook-compatible)

AMP Code Examples (`type: 'amp'`)

Production-tested AMP4Email HTML demonstrating AMP components. Used only in AMP builds. Each example is tagged with:

Technique (tabs, accordion, carousel, survey, toggle, hybrid, static)
Complexity (beginner, intermediate, advanced)
HTML type (complete template or component module)

Blog/Knowledge Articles (`type: 'blog'`)

Educational articles covering kinetic email best practices and techniques. Each article is tagged with:

Content Focus — kinetic (kinetic builds only), amp (AMP builds only), or general (both builds)
Blog Topic (kinetic-techniques, email-best-practices, case-studies, tutorials)
Learning Level (beginner, intermediate, advanced)
Techniques Covered (which kinetic techniques the article discusses)
Key Takeaways (summary used for embedding generation)

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

Purpose & overview of kinetic email
The kinetic declaration pattern
HTML scaffold structure
Component-specific guides (tabs, survey/quiz, accordion, carousel, menu, stepper, hero headers)
Critical rules and anti-patterns
Style strategy (6 separate <style> blocks)
Email client compatibility
Tracking implementation
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.

What is RAG?​

Architecture​

Pipeline Steps​

1. Technique Extraction​

2. Dual-Query Strategy​

3. Merge & Deduplicate​

4. Re-ranking with Claude Haiku​

5. Content Focus Filtering​

6. Context Assembly​

7. Blueprint Generation​

8. Parallel Generation​

Knowledge Base​

HTML Code Examples (type: 'html')​

AMP Code Examples (type: 'amp')​

Blog/Knowledge Articles (type: 'blog')​

Technique Semantics​

Pinecone Setup​