Fast-Path Context Enrichment

When queries take the SPECIFIC_PRODUCT_FAST_PATH, they bypass full LLM extraction for speed. However, they may still contain valuable demographic information that should be captured for better product recommendations.

Overview

The fast-path context enrichment module extracts demographics from queries that would otherwise skip LLM processing.

Problem Statement

Consider this query:

"Pusle 7-aastasele tüdrukule"
(Puzzle for a 7-year-old girl)

Before vs After Comparison

Timing Comparison

Summary:

• Without enrichment: Fast (110ms) but irrelevant results
• With enrichment: Fast (113ms) AND relevant results
• Full LLM: Slow (300ms) but relevant results

The 3ms enrichment overhead provides LLM-quality demographics at fast-path speed.

Implementation

Location

app/api/chat/orchestrators/context-orchestrator/helpers/fastpath-context.ts

Core Function

export function enrichFastPathContext(
  giftContext: GiftContext,
  userMessage: string,
  detection: SpecificProductDetection,
  detectOccasionFromText: OccasionDetector,
  debug: boolean = false
): void {
  // 1. Detect occasion from text
  const occasion = detectOccasionFromText(userMessage);
  if (occasion) {
    giftContext.occasion = occasion;
  }
  
  // 2. Extract demographics using deterministic patterns
  const demographics = extractDeterministicDemographics(userMessage, debug);
  if (demographics.extracted) {
    mergeDemographicsIntoContext(giftContext, demographics, { debug });
  }
  
  // 3. Apply occasion-based hints if applicable
  applyOccasionHints(giftContext, occasion, debug);
}

Extracted Fields

Field	Pattern Examples	Description
recipientAge	"7-aastasele", "50 year old"	Numeric age
recipientAgeRange	"7-9 aastasele"	Age range min/max
ageGroup	Derived from age	child/teen/adult/elderly
recipientGender	"tüdrukule", "for a boy"	male/female
recipient	"emale", "for mom"	Normalized relationship
occasion	"sünnipäevaks", "for birthday"	Detected occasion

Integration Points

1. Fast-Path Handler

// stages/handlers/specific-product-fast-path.ts
export async function handleSpecificProductFastPath({
  routingDecision,
  userMessage,
  detectOccasionFromText,
  debug
}: FastPathParams): Promise<{ giftContext: GiftContext; intentTime: number }> {
  
  // Build basic context from detection
  const giftContext = buildBasicFastPathContext(routingDecision);
  
  // Enrich with demographics
  enrichFastPathContext(
    giftContext,
    userMessage,
    routingDecision.specificProducts,
    detectOccasionFromText,
    debug
  );
  
  return { giftContext, intentTime: Date.now() };
}

2. Search Orchestrator

The enriched demographics flow through to the search orchestrator:

// Search uses demographics for filtering
if (giftContext.recipientAge && giftContext.recipientAge < 13) {
  // Filter for child-appropriate products
  searchParams.ageFilter = 'child';
}

if (giftContext.recipientGender) {
  // Consider gender-appropriate suggestions
  searchParams.genderHint = giftContext.recipientGender;
}

Examples

Example 1: Child Puzzle

Input: "Pusle 7-aastasele tüdrukule"

Fast-Path Detection:
  keywords: ["pusle"]
  categories: ["Pusled"]
  productType: "Puzzle"

Demographics Extraction:
  recipientAge: 7
  ageGroup: "child"
  ageBracket: "school_age"
  recipientGender: "female"
  recipient: "tütar"

Final Context:
{
  intent: "product_inquiry",
  productType: "Puzzle",
  categoryHints: ["Pusled"],
  recipientAge: 7,
  ageGroup: "child",
  recipientGender: "female",
  recipient: "tütar",
  meta: { route: "SPECIFIC_PRODUCT_FAST_PATH" }
}

Example 2: Gift Card with Occasion

Input: "Kinkekaart sünnipäevaks emale"

Fast-Path Detection:
  keywords: ["kinkekaart"]
  categories: ["Kinkekaardid"]
  productType: "Gift Card"

Demographics Extraction:
  recipient: "ema"
  recipientGender: "female" (inferred from "emale")

Occasion Detection:
  occasion: "birthday"

Final Context:
{
  intent: "product_inquiry",
  productType: "Gift Card",
  categoryHints: ["Kinkekaardid"],
  occasion: "birthday",
  recipient: "ema",
  recipientGender: "female",
  meta: { route: "SPECIFIC_PRODUCT_FAST_PATH" }
}

Example 3: Wrapping Paper (No Demographics)

Input: "Pakkepaber"

Fast-Path Detection:
  keywords: ["pakkepaber"]
  categories: ["Pakkepaberid"]
  productType: "Packaging"

Demographics Extraction:
  extracted: false (no demographic signals)

Final Context:
{
  intent: "product_inquiry",
  productType: "Packaging",
  categoryHints: ["Pakkepaberid"],
  meta: { route: "SPECIFIC_PRODUCT_FAST_PATH" }
}

Performance Impact

Metric	Without Enrichment	With Enrichment
Context construction	~5ms	~8ms
Search relevance	Basic	Personalized
Age-appropriate results	❌	✅
Gender-appropriate results	❌	✅

The 3ms overhead is negligible compared to the improved result relevance.

Related Documentation

• Deterministic Demographics - Pattern-based extraction
• Routing Pipeline - Fast-path routing decisions
• Context Extraction - Full LLM extraction