Skip to main content

Context Construction System Overview

The context construction system is a sophisticated multi-stage pipeline that transforms raw user messages into structured, semantically-rich gift contexts.

Key Characteristics​

  • Hybrid Architecture: Fast pattern-based classification + deep LLM semantic understanding
  • Multi-Stage Pipeline: 7-stage refinement from raw text to actionable context
  • Context-Aware: Maintains conversation state for pronoun resolution
  • Performance-Optimized: Parallel execution with <500ms total latency
  • Culturally-Aware: Estonian language support with morphology handling

Pipeline Stages​

7-Stage Pipeline​

Stage 0: Conversation State Retrieval​

  • Fetch stored context from Convex
  • Build conversation state (authors, categories, etc.)
  • Prepare for pronoun resolution

Stage 1: Fast Classifier​

Model: llama-4-scout-17b-16e-instruct
Duration: 100-200ms

  • Popular query patterns
  • Occasion/recipient/budget extraction
  • Confidence scoring
  • Fast-path for common queries

Stage 2: LLM Context Extraction​

Model: llama-4-scout-17b-16e-instruct
Duration: 300-500ms

  • Enhanced semantic prompt with conversation state
  • Structured JSON output
  • Pronoun resolution
  • Complex intent classification

Stage 3: Context Normalization​

  • Validate & sanitize fields
  • Language detection (pattern-based override)
  • Author name validation
  • Recipient/occasion normalization
  • Confidence scoring

Stage 4: Age Detection​

  • Pattern-based age keyword extraction
  • Age bracket mapping
  • Age group inference
  • Age range calculation
  • Deterministic (no LLM)

Stage 5: Hierarchical Refinement​

Triggered: confidence < 0.7
Duration: ~130ms

  • Step 1: Product type (12 options)
  • Step 2: Category (20-40 options)
  • Improves vague query handling

Stage 6: Constraint-Based Category Mapping​

  • Map constraints to specific categories
  • Enrich categoryHints
  • Handle book exclusions
  • Positive constraint mapping

Stage 7: Context Orchestration​

  • Apply refinement signals
  • Author workflow validation
  • Product inquiry resolution
  • Exclude list management
  • Taxonomy preservation for follow-ups

Core Context Structure​

interface GiftContext {
  // Intent
  intent: string;
  confidence: number;
  
  // Gift parameters
  occasion?: string;
  recipient?: string;
  recipientGender?: 'male' | 'female' | 'unisex';
  ageGroup?: 'child' | 'teen' | 'adult' | 'elderly';
  ageBracket?: AgeBracket;
  recipientAge?: number;
  
  // Budget
  budget?: {
    min?: number;
    max?: number;
    hint?: string;
  };
  
  // Taxonomy
  productType?: string;
  category?: string;
  categoryHints?: string[];
  productTypeHints?: string[];
  
  // Constraints
  constraints?: string[];
  bookLanguage?: 'et' | 'en';
  authorName?: string;
  isPopularQuery?: boolean;
  
  // Language
  language: 'et' | 'en' | 'mixed';
  
  // Metadata
  timestamp?: number;
  meta?: GiftContextMeta;
}

Performance Metrics​

StageDuration% of Total
Stage 0: State Retrieval~50ms10%
Stage 1: Fast Classifier100-200ms20-40%
Stage 2: LLM Extraction300-500ms60-80%
Stage 3: Normalization~10ms2%
Stage 4: Age Detection~2ms<1%
Stage 5: Hierarchical (optional)~130ms0-25%
Stage 6: Constraint Mapping~5ms<1%
Stage 7: Orchestration~30ms6%
Total<500ms100%

Key Innovations​

1. Hybrid LLM + Deterministic​

Rationale:

  • LLMs: Powerful but unreliable for structured output
  • Patterns: 100% accurate for known cases
  • Combined: Best of both worlds

2. Conversation State Injection​

Problem: Pronouns can't be resolved without context

Solution: Inject minimal conversation state to LLM:

VESTLUSE KONTEKST:
PEAMINE AUTOR: J.R.R. Tolkien

Result: "tema" → "J.R.R. Tolkien" (automatic resolution)

3. Two-Step Category Refinement​

Problem: 317 categories in one call = 7200ms latency

Solution:

  1. Product type (12 options) → 50ms
  2. Category within type (20-40) → 80ms
  3. Total: 130ms (98% faster)

Documentation Structure​

Detailed docs for each component: