Skip to main content

Query Routing & Detection

This guide explains how the system analyzes incoming user queries and routes them to the most appropriate search strategy, ensuring optimal performance and relevance.

Overview​

Every user query passes through a sophisticated routing system that determines which search path will deliver the best results. The routing is deterministic and prioritized, with fast paths for specific products and specialized paths for authors, books, and general gifts.

Routing Priority Order​

The routing system checks conditions in a specific order, with early matches taking precedence:

1. Specific Product Fast Path​

When it triggers: Keywords like "kinkekott" (gift bag), "pakkepaber" (wrapping paper), gift cards, puzzles, etc.

Why it's fast: Bypasses LLM context extraction entirely using deterministic keyword matching.

How It Works​

Keywords Detected:

  • Gift bags: "kinkekott", "kott", "bag"
  • Wrapping paper: "pakkepaber", "wrapping"
  • Gift cards: "kinkekaart", "gift card"
  • Puzzles: "pusle", "puzzle"
  • And many more...

Performance: This path skips funnel, reranking, and diversity phases for minimal latency.

2. Author Search Path​

When it triggers: Author name detected AND no gift keywords present.

Special logic: "kingitus emale Tolkienilt" (gift for mom from Tolkien) goes through the gift path, not author path, because gift keywords take precedence.

Examples:

  • ✅ "Tolkien" → Author path
  • ✅ "Books by J.K. Rowling" → Author path
  • ❌ "Gift for mom from Tolkien" → Gift path (gift keywords present)

3. Book Category Path​

When it triggers: User explicitly requested books + category maps to book product type.

Purpose: Preserves category fidelity for specific book searches while preventing gift flows from being forced into narrow book catalogs.

Examples:

  • ✅ "Crime novels" → Book category path
  • ✅ "Science fiction books" → Book category path
  • ❌ "Gift idea for book lover" → Gift path (gift intent)

4. Clarification Path​

When it triggers: Query is too short, nonsensical, or keyboard mashing.

Purpose: Avoid wasting resources on meaningless searches and guide users to provide better input.

Triggers:

  • Very short inputs: "a", "ok", "hi"
  • Non-words: "asdfgh", ";;;;;"
  • Too vague: Just whitespace or punctuation

5. Gift/Occasion Path (Default)​

When it triggers: All other conditions failed.

Purpose: Handles the majority of traffic with full LLM context extraction for nuanced understanding.

This path executes:

  • Full context extraction (occasion, recipient, budget, etc.)
  • Multi-query variations (occasion-focused, budget-focused, etc.)
  • Complete pipeline (funnel, rerank, diversity)

Show More Detection​

"Show more" requests are detected at multiple levels to maintain search context.

Phrases Detected:

  • Estonian: "näita rohkem", "veel", "rohkem"
  • English: "show more", "more", "another"
  • Context-aware: Short replies after showing products

Context-Level Detectors​

Specific Product Detector​

Maps keyword groups to taxonomy categories and product types for deterministic routing.

Implementation: app/api/chat/services/specific-product-detector.ts

// Example mapping
{
  keywords: ['kinkekott', 'kott', 'bag'],
  categoryHints: ['Kinkekotid ja -pakendid'],
  productType: 'gift_bags',
  route: 'SPECIFIC_PRODUCT_FAST_PATH'
}

Benefits:

  • Zero LLM latency for commodity items
  • Consistent categorization
  • Pre-filled context for downstream search

Book Category Detector​

Ensures category fidelity only when appropriate.

Implementation: app/api/chat/utils/book-query-detector.ts

Rules:

  1. User explicitly requested books
  2. Intent is NOT gift or author
  3. Category genuinely maps to book product type

Prevents: Gift flows from being locked into narrow book catalogs Preserves: "Crime novels" style searches with proper filters

Routing Configuration​

Location: app/api/chat/orchestrators/context-orchestrator/query-router.ts

Key Functions​

FunctionPurpose
determineQueryRoute()Main routing decision logic
detectSpecificProducts()Fast path detection
hasAuthorIntent()Author pattern matching
isShowMoreRequest()Show more detection
hasSpecificProductContext()Context preservation for show more

Decision Flow Summary​

Key Takeaways​

Deterministic & Prioritized​

Routing follows a strict priority order, ensuring consistent behavior:

  1. Specific products (fastest)
  2. Authors (when no gift keywords)
  3. Book categories (explicit requests)
  4. Clarification (invalid input)
  5. Gift/occasion (default)

Performance Optimized​

Different paths have different performance characteristics:

  • Specific Product: ~150ms (skip most processing)
  • Author: ~200ms (skip funnel/rerank)
  • Book Category: ~300ms (focused search)
  • Gift/Occasion: ~500ms (full pipeline)

Context Preservation​

"Show more" detection happens at multiple levels:

  • Query router detects phrases
  • Search orchestrator substitutes context
  • Memory system reuses previous products

Gift Keywords Win​

When both author and gift keywords are present, gift keywords take precedence to maintain proper gift recommendation flow.

File References:

  • Query Router: app/api/chat/orchestrators/context-orchestrator/query-router.ts
  • Specific Product Detector: app/api/chat/services/specific-product-detector.ts
  • Book Query Detector: app/api/chat/utils/book-query-detector.ts
  • Search Orchestrator: app/api/chat/orchestrators/search-orchestrator.ts