diff --git a/apps/api/src/modules/analysis/analysis.module.ts b/apps/api/src/modules/analysis/analysis.module.ts index 071f5d6..34f89ad 100644 --- a/apps/api/src/modules/analysis/analysis.module.ts +++ b/apps/api/src/modules/analysis/analysis.module.ts @@ -20,6 +20,7 @@ import { createBullMqOptions } from './bullmq.config'; import { FeatureExtractorService } from './feature-extractor.service'; import { MetricBaselineService } from './metric-baseline.service'; import { MetricNormalizationService } from './metric-normalization.service'; +import { MentorMatchService } from './mentor-match.service'; import { ProfileBuilderService } from './profile-builder.service'; import { SeedCollectionProcessor } from './seed-collection.processor'; import { SeedCollectionService } from './seed-collection.service'; @@ -60,6 +61,7 @@ import { TimelineMetricService } from './timeline-metric.service'; FeatureExtractorService, MetricBaselineService, MetricNormalizationService, + MentorMatchService, ProfileBuilderService, SeedCollectionService, TimelineDerivedService, @@ -71,6 +73,7 @@ import { TimelineMetricService } from './timeline-metric.service'; AnalysisPipelineService, MetricBaselineService, MetricNormalizationService, + MentorMatchService, SeedCollectionService, ], }) diff --git a/apps/api/src/modules/analysis/analysis.types.ts b/apps/api/src/modules/analysis/analysis.types.ts index 05b8dc7..3a84395 100644 --- a/apps/api/src/modules/analysis/analysis.types.ts +++ b/apps/api/src/modules/analysis/analysis.types.ts @@ -1,4 +1,4 @@ -import type { Role } from '@persona-lenz/shared'; +import type { MetricId, Role } from '@persona-lenz/shared'; import type { BaselineCohort, LaneOpponentRef, @@ -96,3 +96,44 @@ export interface BuiltPlayerProfile { division?: string; leaguePoints?: number; } + +export interface MentorChampionPoolEntry { + championId: number; + games: number; + wins: number; +} + +export interface SimilarMentorMetric { + metricId: MetricId; + currentValue: number; + mentorValue: number; + absoluteGap: number; +} + +export interface GapMentorMetric { + metricId: MetricId; + currentValue: number; + mentorValue: number; + mentorAdvantage: number; +} + +export interface MentorMatch { + puuid: string; + similarityScore: number; + finalScore: number; + tier?: string; + division?: string; + leaguePoints?: number; + mainRole: Role; + mainChampions: MentorChampionPoolEntry[]; + sampleGameCount: number; + similarMetrics: SimilarMentorMetric[]; + gapMetrics: GapMentorMetric[]; +} + +export interface MentorMatchesResult { + puuid: string; + queueId: number; + profileUpdatedAt: Date; + matches: MentorMatch[]; +} diff --git a/apps/api/src/modules/analysis/mentor-match.service.spec.ts b/apps/api/src/modules/analysis/mentor-match.service.spec.ts new file mode 100644 index 0000000..c80a922 --- /dev/null +++ b/apps/api/src/modules/analysis/mentor-match.service.spec.ts @@ -0,0 +1,218 @@ +import { FEATURE_SCHEMA_VERSION, VECTOR_DIMENSION } from '@persona-lenz/shared'; +import type { ConnectionService } from '../global/database/connection.service'; +import { MentorMatchService } from './mentor-match.service'; + +function createLeanExec(value: T) { + return { + lean: jest.fn(() => ({ + exec: jest.fn().mockResolvedValue(value), + })), + }; +} + +function createAggregateExec(value: T) { + return { + exec: jest.fn().mockResolvedValue(value), + }; +} + +function createVector(fillValue = 0.5): number[] { + return Array.from({ length: VECTOR_DIMENSION }, () => fillValue); +} + +function createProfile(overrides: Record = {}) { + return { + puuid: 'target-puuid', + queueId: 420, + mainRole: 'MIDDLE', + sampleGameCount: 35, + championPool: [ + { championId: 103, games: 8, wins: 5 }, + { championId: 84, games: 6, wins: 4 }, + { championId: 7, games: 5, wins: 2 }, + ], + profile: { + kda: 0.3, + killParticipation: 0.5, + goldPerMin: 0.5, + csPerMin: 0.5, + deathsPerMin: 0.7, + }, + vector: createVector(), + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + updatedAt: new Date('2026-07-02T00:00:00.000Z'), + lastMatchAt: new Date('2026-07-02T00:00:00.000Z'), + tier: 'DIAMOND', + isSeed: false, + ...overrides, + }; +} + +describe('MentorMatchService', () => { + beforeEach(() => { + jest.useFakeTimers().setSystemTime(new Date('2026-07-03T00:00:00.000Z')); + }); + + afterEach(() => { + jest.useRealTimers(); + }); + + it('queries high-tier seed profiles with Atlas Vector Search and reranks candidates', async () => { + const currentProfile = createProfile(); + const findOne = jest.fn(() => createLeanExec(currentProfile)); + const aggregate = jest.fn(() => + createAggregateExec([ + createProfile({ + puuid: 'mentor-low-style-better-context', + championPool: [ + { championId: 103, games: 12, wins: 8 }, + { championId: 84, games: 5, wins: 4 }, + { championId: 777, games: 5, wins: 3 }, + ], + profile: { + kda: 0.9, + killParticipation: 0.49, + goldPerMin: 0.8, + csPerMin: 0.51, + deathsPerMin: 0.2, + }, + sampleGameCount: 20, + tier: 'CHALLENGER', + leaguePoints: 900, + lastMatchAt: new Date('2026-07-03T00:00:00.000Z'), + score: 0.8, + }), + createProfile({ + puuid: 'mentor-high-style-weaker-context', + championPool: [{ championId: 222, games: 30, wins: 20 }], + profile: { + kda: 0.4, + killParticipation: 0.52, + goldPerMin: 0.55, + csPerMin: 0.7, + deathsPerMin: 0.6, + }, + sampleGameCount: 30, + tier: 'MASTER', + lastMatchAt: new Date('2026-06-19T00:00:00.000Z'), + score: 0.9, + }), + ]), + ); + const service = new MentorMatchService({ + getModel: jest.fn().mockResolvedValue({ findOne, aggregate }), + } as unknown as ConnectionService); + + const result = await service.findMentorMatches('target-puuid', 420, 2); + + expect(findOne).toHaveBeenCalledWith({ + puuid: 'target-puuid', + queueId: 420, + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + }); + expect(aggregate).toHaveBeenCalledWith([ + { + $vectorSearch: { + index: 'player_profile_vector_index', + path: 'vector', + queryVector: currentProfile.vector, + numCandidates: 200, + limit: 50, + filter: { + mainRole: 'MIDDLE', + queueId: 420, + tier: { $in: ['MASTER', 'GRANDMASTER', 'CHALLENGER'] }, + isSeed: true, + sampleGameCount: { $gte: 20 }, + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + }, + }, + }, + { $match: { puuid: { $ne: 'target-puuid' } } }, + { + $project: { + puuid: 1, + queueId: 1, + mainRole: 1, + sampleGameCount: 1, + championPool: 1, + profile: 1, + updatedAt: 1, + lastMatchAt: 1, + tier: 1, + division: 1, + leaguePoints: 1, + score: { $meta: 'vectorSearchScore' }, + }, + }, + ]); + expect(result.profileUpdatedAt).toEqual( + new Date('2026-07-02T00:00:00.000Z'), + ); + expect(result.matches.map((match) => match.puuid)).toEqual([ + 'mentor-low-style-better-context', + 'mentor-high-style-weaker-context', + ]); + expect(result.matches[0].finalScore).toBeGreaterThan( + result.matches[1].finalScore, + ); + expect(result.matches[0].mainChampions).toEqual([ + { championId: 103, games: 12, wins: 8 }, + { championId: 84, games: 5, wins: 4 }, + { championId: 777, games: 5, wins: 3 }, + ]); + expect(result.matches[0].similarMetrics).toEqual([ + { + metricId: 'killParticipation', + currentValue: 0.5, + mentorValue: 0.49, + absoluteGap: 0.01, + }, + { + metricId: 'csPerMin', + currentValue: 0.5, + mentorValue: 0.51, + absoluteGap: 0.01, + }, + { + metricId: 'goldPerMin', + currentValue: 0.5, + mentorValue: 0.8, + absoluteGap: 0.3, + }, + ]); + expect(result.matches[0].gapMetrics).toEqual([ + { + metricId: 'kda', + currentValue: 0.3, + mentorValue: 0.9, + mentorAdvantage: 0.6, + }, + { + metricId: 'deathsPerMin', + currentValue: 0.7, + mentorValue: 0.2, + mentorAdvantage: 0.5, + }, + { + metricId: 'goldPerMin', + currentValue: 0.5, + mentorValue: 0.8, + mentorAdvantage: 0.3, + }, + ]); + }); + + it('throws when the player profile has not been built yet', async () => { + const findOne = jest.fn(() => createLeanExec(null)); + const aggregate = jest.fn(); + const service = new MentorMatchService({ + getModel: jest.fn().mockResolvedValue({ findOne, aggregate }), + } as unknown as ConnectionService); + + await expect( + service.findMentorMatches('missing-puuid', 420), + ).rejects.toThrow('Player profile not found.'); + expect(aggregate).not.toHaveBeenCalled(); + }); +}); diff --git a/apps/api/src/modules/analysis/mentor-match.service.ts b/apps/api/src/modules/analysis/mentor-match.service.ts new file mode 100644 index 0000000..48477dd --- /dev/null +++ b/apps/api/src/modules/analysis/mentor-match.service.ts @@ -0,0 +1,317 @@ +import { Injectable, NotFoundException } from '@nestjs/common'; +import { + FEATURE_SCHEMA_VERSION, + METRICS, + VECTOR_DIMENSION, + type MetricDefinition, + type Role, +} from '@persona-lenz/shared'; +import type { PipelineStage } from 'mongoose'; +import { ConnectionService } from '../global/database/connection.service'; +import type { + GapMentorMetric, + MentorChampionPoolEntry, + MentorMatch, + MentorMatchesResult, + SimilarMentorMetric, +} from './analysis.types'; + +const MENTOR_VECTOR_SEARCH_INDEX_NAME = 'player_profile_vector_index'; +const MENTOR_VECTOR_SEARCH_NUM_CANDIDATES = 200; +const MENTOR_VECTOR_SEARCH_LIMIT = 50; +const DEFAULT_MENTOR_MATCH_LIMIT = 10; +const MINIMUM_MENTOR_SAMPLE_GAME_COUNT = 20; +const LOW_SAMPLE_GAME_COUNT_THRESHOLD = 30; +const LOW_SAMPLE_PENALTY = 0.1; +const RECENCY_HALF_LIFE_MS = 14 * 24 * 60 * 60 * 1000; +const HIGH_TIER_MENTOR_TIERS = ['MASTER', 'GRANDMASTER', 'CHALLENGER']; + +interface MentorProfileRecord { + puuid: string; + queueId: number; + mainRole: Role; + sampleGameCount: number; + championPool: MentorChampionPoolEntry[]; + profile: Record; + vector: number[]; + updatedAt: Date; + lastMatchAt?: Date; + tier?: string; + division?: string; + leaguePoints?: number; +} + +interface MentorVectorSearchRecord extends Omit { + score?: number; +} + +@Injectable() +export class MentorMatchService { + constructor(private readonly connectionService: ConnectionService) {} + + public async findMentorMatches( + puuid: string, + queueId: number, + requestedLimit = DEFAULT_MENTOR_MATCH_LIMIT, + ): Promise { + const playerProfileModel = + await this.connectionService.getModel('playerProfile'); + const currentProfile = await playerProfileModel + .findOne({ puuid, queueId, featureSchemaVersion: FEATURE_SCHEMA_VERSION }) + .lean() + .exec(); + + if (!currentProfile) { + throw new NotFoundException('Player profile not found.'); + } + + if (currentProfile.vector.length !== VECTOR_DIMENSION) { + return { + puuid, + queueId, + profileUpdatedAt: currentProfile.updatedAt, + matches: [], + }; + } + + const candidates = await playerProfileModel + .aggregate( + this.createMentorCandidatePipeline(currentProfile, puuid, queueId), + ) + .exec(); + + return { + puuid, + queueId, + profileUpdatedAt: currentProfile.updatedAt, + matches: candidates + .map((candidate) => this.toMentorMatch(currentProfile, candidate)) + .sort((left, right) => right.finalScore - left.finalScore) + .slice(0, this.normalizeLimit(requestedLimit)), + }; + } + + private createMentorCandidatePipeline( + currentProfile: MentorProfileRecord, + puuid: string, + queueId: number, + ): PipelineStage[] { + return [ + { + $vectorSearch: { + index: MENTOR_VECTOR_SEARCH_INDEX_NAME, + path: 'vector', + queryVector: currentProfile.vector, + numCandidates: MENTOR_VECTOR_SEARCH_NUM_CANDIDATES, + limit: MENTOR_VECTOR_SEARCH_LIMIT, + filter: { + mainRole: currentProfile.mainRole, + queueId, + tier: { $in: HIGH_TIER_MENTOR_TIERS }, + isSeed: true, + sampleGameCount: { $gte: MINIMUM_MENTOR_SAMPLE_GAME_COUNT }, + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + }, + }, + }, + { $match: { puuid: { $ne: puuid } } }, + { + $project: { + puuid: 1, + queueId: 1, + mainRole: 1, + sampleGameCount: 1, + championPool: 1, + profile: 1, + updatedAt: 1, + lastMatchAt: 1, + tier: 1, + division: 1, + leaguePoints: 1, + score: { $meta: 'vectorSearchScore' }, + }, + }, + ]; + } + + private toMentorMatch( + currentProfile: MentorProfileRecord, + mentorProfile: MentorVectorSearchRecord, + ): MentorMatch { + const similarityScore = this.clamp01(mentorProfile.score ?? 0); + + return { + puuid: mentorProfile.puuid, + similarityScore, + finalScore: this.calculateFinalScore( + currentProfile, + mentorProfile, + similarityScore, + ), + tier: mentorProfile.tier, + division: mentorProfile.division, + leaguePoints: mentorProfile.leaguePoints, + mainRole: mentorProfile.mainRole, + mainChampions: mentorProfile.championPool.slice(0, 3), + sampleGameCount: mentorProfile.sampleGameCount, + similarMetrics: this.resolveSimilarMetrics( + currentProfile.profile, + mentorProfile.profile, + ), + gapMetrics: this.resolveGapMetrics( + currentProfile.profile, + mentorProfile.profile, + ), + }; + } + + private calculateFinalScore( + currentProfile: MentorProfileRecord, + mentorProfile: MentorVectorSearchRecord, + similarityScore: number, + ): number { + const championPoolSimilarity = this.calculateChampionPoolSimilarity( + currentProfile.championPool, + mentorProfile.championPool, + ); + const recencyScore = this.calculateRecencyScore(mentorProfile.lastMatchAt); + const tierScore = this.resolveTierScore(mentorProfile.tier); + const lowSamplePenalty = + mentorProfile.sampleGameCount < LOW_SAMPLE_GAME_COUNT_THRESHOLD + ? LOW_SAMPLE_PENALTY + : 0; + + return this.clamp01( + 0.6 * similarityScore + + 0.2 * championPoolSimilarity + + 0.12 * recencyScore + + 0.08 * tierScore - + lowSamplePenalty, + ); + } + + private calculateChampionPoolSimilarity( + currentChampionPool: MentorChampionPoolEntry[], + mentorChampionPool: MentorChampionPoolEntry[], + ): number { + const currentChampionIds = new Set( + currentChampionPool.slice(0, 5).map((entry) => entry.championId), + ); + const mentorChampionIds = new Set( + mentorChampionPool.slice(0, 5).map((entry) => entry.championId), + ); + const unionChampionIds = new Set([ + ...currentChampionIds, + ...mentorChampionIds, + ]); + if (unionChampionIds.size === 0) return 0; + + let sharedChampionCount = 0; + currentChampionIds.forEach((championId) => { + if (mentorChampionIds.has(championId)) sharedChampionCount += 1; + }); + + return sharedChampionCount / unionChampionIds.size; + } + + private calculateRecencyScore(lastMatchAt: Date | undefined): number { + if (!lastMatchAt) return 0; + const ageMs = Date.now() - lastMatchAt.getTime(); + if (ageMs <= 0) return 1; + return this.clamp01(Math.pow(0.5, ageMs / RECENCY_HALF_LIFE_MS)); + } + + private resolveTierScore(tier: string | undefined): number { + if (tier === 'CHALLENGER') return 1; + if (tier === 'GRANDMASTER') return 0.8; + if (tier === 'MASTER') return 0.6; + return 0; + } + + private resolveSimilarMetrics( + currentProfile: Record, + mentorProfile: Record, + ): SimilarMentorMetric[] { + return METRICS.flatMap((metric) => { + const comparison = this.createMetricValues( + currentProfile, + mentorProfile, + metric, + ); + if (!comparison) return []; + + return { + metricId: metric.id, + currentValue: comparison.currentValue, + mentorValue: comparison.mentorValue, + absoluteGap: this.roundMetricGap( + Math.abs(comparison.mentorValue - comparison.currentValue), + ), + }; + }) + .sort((left, right) => left.absoluteGap - right.absoluteGap) + .slice(0, 3); + } + + private resolveGapMetrics( + currentProfile: Record, + mentorProfile: Record, + ): GapMentorMetric[] { + return METRICS.flatMap((metric) => { + const comparison = this.createMetricValues( + currentProfile, + mentorProfile, + metric, + ); + if (!comparison) return []; + + const rawMentorAdvantage = + metric.direction === 'lowerIsBetter' + ? comparison.currentValue - comparison.mentorValue + : comparison.mentorValue - comparison.currentValue; + if (rawMentorAdvantage <= 0) return []; + + return { + metricId: metric.id, + currentValue: comparison.currentValue, + mentorValue: comparison.mentorValue, + mentorAdvantage: this.roundMetricGap(rawMentorAdvantage), + }; + }) + .sort((left, right) => right.mentorAdvantage - left.mentorAdvantage) + .slice(0, 3); + } + + private createMetricValues( + currentProfile: Record, + mentorProfile: Record, + metric: MetricDefinition, + ): { currentValue: number; mentorValue: number } | null { + const currentValue = currentProfile[metric.id]; + const mentorValue = mentorProfile[metric.id]; + if (!Number.isFinite(currentValue) || !Number.isFinite(mentorValue)) { + return null; + } + + return { + currentValue: this.clamp01(currentValue), + mentorValue: this.clamp01(mentorValue), + }; + } + + private normalizeLimit(requestedLimit: number): number { + if (!Number.isInteger(requestedLimit) || requestedLimit < 1) { + return DEFAULT_MENTOR_MATCH_LIMIT; + } + return Math.min(requestedLimit, DEFAULT_MENTOR_MATCH_LIMIT); + } + + private roundMetricGap(value: number): number { + return Math.round(value * 1_000_000) / 1_000_000; + } + + private clamp01(value: number): number { + if (!Number.isFinite(value)) return 0; + return Math.max(0, Math.min(1, value)); + } +}