ComparisonGenerationService Deep Dive

Overview

The ComparisonGenerationService generates AI-powered comparison pages between pairs of work items. It supports both automatic pair selection (picking the next best un-compared pair) and manual pair specification. The pipeline researches items via web search, generates structured comparison data with dimension-by-dimension scoring, and produces a full markdown article -- all committed to the work's data repository.

Architecture

The comparison system is split into a service layer and a set of pure functions for pair selection, research, and content generation. This design enables thorough unit testing of the core logic without service dependencies.

ComparisonGenerationService (NestJS service)
        |
        +-- Pair Selection Layer (pure functions)
        |       +-- selectNextPair()
        |       +-- findManualPair()
        |       +-- countRemainingPairs()
        |       +-- buildPairKey()
        |
        +-- Research Layer (pure function + injected deps)
        |       +-- researchPair()
        |       +-- buildSearchQueries()
        |
        +-- Generation Layer (pure function + injected deps)
        |       +-- generateComparison()
        |           +-- AI structured data (askJson)
        |           +-- AI markdown article (askText)
        |           +-- AI extended analysis (askText, optional)
        |
        +-- Persistence Layer
                +-- DataRepository.writeComparison()
                +-- DataRepository.writeComparisonMarkdown()
                +-- Git add/commit/push

API Reference

Methods

`generateNextComparison(workId, userId)`

Automatically selects and generates the next comparison pair.

Parameter	Type	Description
`workId`	`string`	The work ID
`userId`	`string`	The requesting user's ID

Returns: Promise<ComparisonResult>

interface ComparisonResult {
	status: 'success' | 'skipped' | 'error';
	slug?: string;
	message: string;
}

`generateManualComparison(workId, userId, itemASlug, itemBSlug)`

Generates a comparison for two specifically chosen items.

Returns: Promise<ComparisonResult>

`getRemainingCount(workId, userId)`

Counts how many un-generated comparison pairs remain.

Returns: Promise<number>

`listComparisons(workId, userId)`

Lists all existing comparisons for a work.

Returns: Promise<ComparisonData[]>

`getComparison(workId, userId, slug)`

Retrieves a single comparison by slug, including markdown content and optional extended analysis.

Returns: Promise<{ comparison: ComparisonData | null; markdown?: string; extendedAnalysisMarkdown?: string }>

`deleteComparison(workId, userId, slug)`

Deletes a comparison by slug, updates the comparison state, and pushes the changes.

Returns: Promise<ComparisonResult>

Implementation Details

Pair Selection Algorithm

The selectNextPair() function implements a category-aware, priority-sorted pair selection:

Group items by category -- items are grouped by their primary category
Filter by minimum size -- categories with fewer items than min_items_for_comparison (default: 3) are skipped
Sort by priority -- within each category, items are sorted: featured first, then by order, then alphabetically
Generate all pairs -- all combinatorial pairs within a category are generated
Skip existing -- pairs already in generated_pairs are filtered out
Return first match -- the first un-generated pair is returned

Canonical Pair Keys

Pair keys are order-independent. buildPairKey('vercel', 'netlify') and buildPairKey('netlify', 'vercel') both produce "netlify--vercel". This prevents duplicate comparisons regardless of argument order.

Research Pipeline

The researchPair() function:

Generates up to 4 search queries per pair (e.g., "Vercel vs Netlify", compare Vercel and Netlify)
Executes up to 3 queries via the search facade
Deduplicates results by URL
Extracts content from up to 5 top results
Trims each extraction to 2,000 characters to control token costs
Falls back to search snippets when extraction fails