Search Orchestrator Paths

Once a query has been routed, the Search Orchestrator executes a path-specific search strategy. Each path is optimized for its use case, from ultra-fast commodity searches to comprehensive gift recommendation pipelines.

Overview

The Search Orchestrator is the execution engine that transforms routing decisions into actual product searches. It supports 5 distinct paths, each with different tradeoffs between speed, precision, and relevance.

Path Comparison Matrix

Path	Funnel	Rerank	Diversity	Latency	Use Case
Specific Product	❌	❌	❌	~150ms	Commodity items
Author	❌	❌	❌	~200ms	Books by author
Book Category	✅	✅	✅	~300ms	Genre searches
Clarification	N/A	N/A	N/A	~50ms	Invalid queries
Gift/Occasion	✅	✅	✅	~500ms	General gifts

1. Author Search Path

When It Activates

meta.route === 'AUTHOR_SEARCH_PATH' || intent === 'author_search'

Execution Flow

Key Characteristics

Precision over Relevance: Returns all books by the author rather than scoring by gift-worthiness.

No Funnel/Rerank: Assumes user wants comprehensive author catalog, not curated selection.

Limit: 50 matches from Convex, trimmed to 20 for display.

Performance: ~200ms average (just Convex + trim)

Implementation

Location: app/api/chat/orchestrators/search-orchestrator.ts:135-205

if (meta.route === 'AUTHOR_SEARCH_PATH' || intent === 'author_search') {
  const authorResults = await AuthorSearchService.searchByAuthor(
    authorName,
    { limit: 50 }
  );
  
  return {
    products: authorResults.slice(0, 20),
    metrics: { searchType: 'author_dedicated' }
  };
}

2. Book Category Path

When It Activates

meta.route === 'BOOK_CATEGORY_PATH'

Execution Flow

Key Characteristics

Category Fidelity: Preserves exact category without sanitization.

Precise Filters: Query rewriting injects csv_category filters directly.

Full Pipeline: Unlike Author path, this uses funnel/rerank for relevance.

Use Case: "Crime novels", "Science fiction books", etc.

Implementation

Location: app/api/chat/orchestrators/search-orchestrator.ts:213-232

if (context.meta?.route === 'BOOK_CATEGORY_PATH') {
  // Log and preserve supplied category
  logger.info('Book category path', {
    category: context.categoryHints[0]
  });
  
  // Query rewriting will inject exact csv_category filters
  // No additional sanitization needed
}

3. Specific Product Fast Path

When It Activates

meta.route === 'SPECIFIC_PRODUCT_FAST_PATH'

Execution Flow

Key Characteristics

Single Variation: Only one search query (not multiple variations).

Pre-filled Filters: Product type and category hint from detector.

Skip Everything: No funnel, no rerank, no diversity.

Latency Optimized: Dominated only by Convex search time.

Search Query Construction

Implementation

Location: app/api/chat/orchestrators/search-orchestrator.ts:238-349

if (context.meta?.route === 'SPECIFIC_PRODUCT_FAST_PATH') {
  const variation = {
    text: context.productType || 'gift',
    categoryFilter: context.categoryHints[0],
    productTypeFilter: context.productType,
    variationType: 'specific_product'
  };
  
  const searchResult = await ProductSearchService.searchMulti(
    [variation],
    { seed: 'deterministic' }
  );
  
  // Return immediately, no funnel/rerank
  return {
    products: searchResult.products.slice(0, 3),
    metrics: { fastPath: true }
  };
}

4. Clarification Path

When It Activates

meta.route === 'CLARIFICATION_PATH'

Execution Flow

Key Characteristics

Zero Search: No Convex calls, no processing.

Immediate Exit: Returns empty product set instantly.

Handler Responsibility: Handler triggers clarification messaging.

Metrics: Marks pipeline as "clarification_needed".

Implementation

Location: app/api/chat/orchestrators/search-orchestrator.ts:352-379

if (context.meta?.route === 'CLARIFICATION_PATH') {
  logger.warn('Clarification path: skipping search');
  
  return {
    products: [],
    metrics: {
      route: 'clarification',
      searchSkipped: true,
      durationMs: Date.now() - startTime
    },
    warnings: ['Query requires clarification']
  };
}

Handler Response

When the handler receives zero products from clarification path:

if (searchResult.products.length === 0 && 
    searchResult.metrics?.route === 'clarification') {
  return {
    type: 'clarification',
    message: 'What kind of gift are you looking for?',
    suggestions: ['Birthday gift', 'Anniversary', 'Just because']
  };
}

5. Gift/Occasion Path (Standard)

When It Activates

Default path when all other conditions fail (most common).

Execution Flow

Key Characteristics

Most Traffic: Handles majority of user requests.

Full Pipeline: Executes all phases (funnel, rerank, diversity).

Context-Aware: "Show more" detection preserves filters.

Multi-Query: Generates multiple search variations for coverage.

Show More Handling

Token Substitution

Before query rewriting, the orchestrator checks for show-more tokens:

Location: app/api/chat/orchestrators/search-orchestrator.ts:386-410

// Check for show-more tokens
if (isShowMoreRequest(userMessage)) {
  // Substitute "rohkem" with actual product type
  const persistentType = context.productType || 
                         previousContext?.productType || 
                         'gift';
  
  // Replace show-more tokens with meaningful search term
  userMessage = userMessage.replace(
    /rohkem|veel|more|another/gi,
    persistentType
  );
  
  // Preserve category and budget filters
  context.categoryHints = previousContext?.categoryHints || [];
  context.budget = previousContext?.budget;
}

Query Variations Generated

Each variation includes:

• Search text: Focus-specific query
• Category filter: From context hints
• Product type filter: From context
• Weight: Priority multiplier
• Variation type: For diagnostics

Full Pipeline Processing

After multi-query search returns 100-300 candidates:

See Finalist Selection Pipeline for complete details.

Path Selection Summary

Performance Characteristics

Latency Breakdown

Path	Routing	Search	Processing	Total
Specific Product	10ms	100ms	40ms	~150ms
Author	10ms	150ms	40ms	~200ms
Book Category	10ms	150ms	140ms	~300ms
Clarification	10ms	0ms	40ms	~50ms
Gift/Occasion	10ms	150ms	340ms	~500ms

Throughput Impact

Fast Paths (Specific Product, Author):

• Skip expensive processing
• Handle 2-3x more requests per second
• Ideal for commodity queries

Standard Path (Gift/Occasion):

• Full personalization
• More compute-intensive
• Worth the latency for complex queries

Configuration

Location: app/api/chat/orchestrators/search-orchestrator.config.ts

Path-Specific Settings

export const PATH_CONFIG = {
  AUTHOR_SEARCH: {
    maxResults: 50,
    trimTo: 20,
    skipFunnel: true,
    skipRerank: true,
    skipDiversity: true
  },
  
  SPECIFIC_PRODUCT: {
    singleVariation: true,
    skipFunnel: true,
    skipRerank: true,
    skipDiversity: true,
    maxResults: 3
  },
  
  BOOK_CATEGORY: {
    preserveCategory: true,
    skipSanitization: true,
    fullPipeline: true
  },
  
  GIFT_OCCASION: {
    multiQuery: true,
    fullPipeline: true,
    maxVariations: 5
  }
};

Key Takeaways

Path Optimization

Each path is optimized for its specific use case:

• Specific Product: Speed over personalization
• Author: Comprehensiveness over relevance
• Book Category: Precision over variety
• Gift/Occasion: Relevance and diversity

Processing Tradeoffs

Skip expensive phases when appropriate:

• Fast paths: No funnel/rerank/diversity
• Author path: No personalization
• Standard path: Full pipeline

Context Preservation

"Show more" handling maintains search context:

• Token substitution
• Filter preservation
• Seed randomization for variety

Routing Integrity

To change search behavior, you must update:

1. Detector that sets meta.route
2. Orchestrator path logic for that route
3. Configuration for path-specific settings

Changing only one causes mismatched expectations.

Related Documentation

• Query Routing & Detection - How routes are determined
• Multi-Query Retrieval - Search execution details
• Search Resilience & Fallbacks - Error handling
• Finalist Selection Pipeline - Complete pipeline

---

File References:

• Search Orchestrator: app/api/chat/orchestrators/search-orchestrator.ts
• Author Search: app/api/chat/services/author-search.ts
• Query Rewriting: app/api/chat/services/query-rewriting/index.ts
• Configuration: app/api/chat/orchestrators/search-orchestrator.config.ts