Add mentor match ranking service

This commit is contained in:
dahyeon committed 2026-07-03 01:51:31 -07:00
1 parent 1df1cd54f8
commit 1db1d1d1d6
4 files changed
+580 -1

No files matched your search

@@ -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,
],
})
@@ -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[];
}
@@ -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<T>(value: T) {
return {
lean: jest.fn(() => ({
exec: jest.fn().mockResolvedValue(value),
})),
};
}
function createAggregateExec<T>(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<string, unknown> = {}) {
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();
});
});
@@ -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<string, number>;
vector: number[];
updatedAt: Date;
lastMatchAt?: Date;
tier?: string;
division?: string;
leaguePoints?: number;
}
interface MentorVectorSearchRecord extends Omit<MentorProfileRecord, 'vector'> {
score?: number;
}
@Injectable()
export class MentorMatchService {
constructor(private readonly connectionService: ConnectionService) {}
public async findMentorMatches(
puuid: string,
queueId: number,
requestedLimit = DEFAULT_MENTOR_MATCH_LIMIT,
): Promise<MentorMatchesResult> {
const playerProfileModel =
await this.connectionService.getModel('playerProfile');
const currentProfile = await playerProfileModel
.findOne({ puuid, queueId, featureSchemaVersion: FEATURE_SCHEMA_VERSION })
.lean<MentorProfileRecord>()
.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<MentorVectorSearchRecord>(
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<string, number>,
mentorProfile: Record<string, number>,
): 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<string, number>,
mentorProfile: Record<string, number>,
): 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<string, number>,
mentorProfile: Record<string, number>,
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));
}
}