From 3ef86b0b66b8876d0f650c6aab99a9407a5302ac Mon Sep 17 00:00:00 2001 From: dahyeon Date: Fri, 3 Jul 2026 01:15:20 -0700 Subject: [PATCH] Add metric baseline computation service --- .../src/modules/analysis/analysis.module.ts | 3 + .../analysis/metric-baseline.service.spec.ts | 218 ++++++++++++++++++ .../analysis/metric-baseline.service.ts | 216 +++++++++++++++++ 3 files changed, 437 insertions(+) create mode 100644 apps/api/src/modules/analysis/metric-baseline.service.spec.ts create mode 100644 apps/api/src/modules/analysis/metric-baseline.service.ts diff --git a/apps/api/src/modules/analysis/analysis.module.ts b/apps/api/src/modules/analysis/analysis.module.ts index eff2f8d..3f06305 100644 --- a/apps/api/src/modules/analysis/analysis.module.ts +++ b/apps/api/src/modules/analysis/analysis.module.ts @@ -18,6 +18,7 @@ import { AnalysisPipelineService } from './analysis-pipeline.service'; import { AnalysisProcessor } from './analysis.processor'; import { createBullMqOptions } from './bullmq.config'; import { FeatureExtractorService } from './feature-extractor.service'; +import { MetricBaselineService } from './metric-baseline.service'; import { ProfileBuilderService } from './profile-builder.service'; import { SeedCollectionProcessor } from './seed-collection.processor'; import { SeedCollectionService } from './seed-collection.service'; @@ -56,6 +57,7 @@ import { TimelineMetricService } from './timeline-metric.service'; AnalysisProcessor, SeedCollectionProcessor, FeatureExtractorService, + MetricBaselineService, ProfileBuilderService, SeedCollectionService, TimelineDerivedService, @@ -65,6 +67,7 @@ import { TimelineMetricService } from './timeline-metric.service'; exports: [ AnalysisQueueService, AnalysisPipelineService, + MetricBaselineService, SeedCollectionService, ], }) diff --git a/apps/api/src/modules/analysis/metric-baseline.service.spec.ts b/apps/api/src/modules/analysis/metric-baseline.service.spec.ts new file mode 100644 index 0000000..c0899e4 --- /dev/null +++ b/apps/api/src/modules/analysis/metric-baseline.service.spec.ts @@ -0,0 +1,218 @@ +import { FEATURE_SCHEMA_VERSION } from '@persona-lenz/shared'; +import type { ConnectionService } from '../global/database/connection.service'; +import type { PlayerMatchFeature } from '../global/database/schemas'; +import { MetricBaselineService } from './metric-baseline.service'; + +interface ExecQuery { + exec: jest.Mock, []>; +} + +type AcknowledgedUpdate = { acknowledged: boolean }; +type AggregateMock = jest.Mock, [unknown[]]>; +type UpdateOneMock = jest.Mock< + ExecQuery, + [Record, Record, Record?] +>; + +function asRecord(value: unknown): Record { + if (typeof value === 'object' && value !== null && !Array.isArray(value)) { + return value as Record; + } + return {}; +} + +function execResolved(value: T): ExecQuery { + return { exec: jest.fn, []>().mockResolvedValue(value) }; +} + +function createStoredFeature( + overrides: Partial = {}, +): PlayerMatchFeature { + return { + createdAt: new Date('2026-07-01T00:00:00.000Z'), + updatedAt: new Date('2026-07-01T00:00:00.000Z'), + matchId: 'KR_1', + puuid: 'seed-puuid', + queueId: 420, + role: 'MIDDLE', + championId: 103, + gameCreation: 1_700_000_000_000, + gameDurationSec: 1_800, + win: true, + patch: '26.13', + features: { + csPerMin: 8, + kda: 3, + }, + normalized: {}, + vector: [], + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + normalizationMethod: 'registry-baseline', + confidence: 1, + timelineProcessed: true, + ...overrides, + }; +} + +describe('MetricBaselineService', () => { + it('computes p5-p95 breakpoints from seed raw feature values', async () => { + const seedFeatures = [10, 20, 30, 40, 50].map((kda, index) => + createStoredFeature({ + matchId: `KR_${index + 1}`, + features: { + kda, + }, + }), + ); + const aggregate: AggregateMock = jest + .fn, [unknown[]]>() + .mockReturnValue(execResolved(seedFeatures)); + const updateOne: UpdateOneMock = jest + .fn, Parameters>() + .mockReturnValue(execResolved({ acknowledged: true })); + const connectionService = { + getModel: jest.fn((modelKey: string) => + Promise.resolve( + modelKey === 'playerMatchFeature' + ? { aggregate } + : { + updateOne, + }, + ), + ), + } as unknown as ConnectionService; + const service = new MetricBaselineService(connectionService); + const computedAt = new Date('2026-07-03T12:00:00.000Z'); + + const result = await service.computeMetricBaselines({ + cohort: 'MASTER_PLUS', + computedAt, + patch: 'ALL', + }); + + expect(result).toEqual({ + baselinesWritten: 1, + cohort: 'MASTER_PLUS', + computedAt, + patch: 'ALL', + samplesRead: 5, + }); + const aggregatePipeline = aggregate.mock.calls[0]?.[0]; + expect(aggregatePipeline).toContainEqual({ + $match: { + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + role: { + $in: ['TOP', 'JUNGLE', 'MIDDLE', 'BOTTOM', 'UTILITY'], + }, + }, + }); + expect(aggregatePipeline).toContainEqual({ + $lookup: { + as: 'account', + foreignField: 'puuid', + from: 'account', + localField: 'puuid', + }, + }); + expect(updateOne).toHaveBeenCalledTimes(1); + const [, update, options] = updateOne.mock.calls[0]; + const updateSet = asRecord(asRecord(update).$set); + expect(updateSet).toMatchObject({ + cohort: 'MASTER_PLUS', + computedAt, + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + metricId: 'kda', + patch: 'ALL', + role: 'MIDDLE', + sampleCount: 5, + }); + const breakpoints = updateSet.percentileBreakpoints; + expect(Array.isArray(breakpoints)).toBe(true); + const numericBreakpoints = (breakpoints as unknown[]).filter( + (value): value is number => typeof value === 'number', + ); + expect(numericBreakpoints).toHaveLength(19); + expect(numericBreakpoints[0]).toBe(12); + expect(numericBreakpoints[9]).toBe(30); + expect(numericBreakpoints[18]).toBe(48); + expect(options).toEqual({ upsert: true }); + }); + + it('groups baseline values by metric and role and skips unknown roles', async () => { + const seedFeatures = [ + createStoredFeature({ + role: 'MIDDLE', + features: { + csPerMin: 8, + kda: 3, + }, + }), + createStoredFeature({ + matchId: 'KR_2', + role: 'MIDDLE', + features: { + csPerMin: 9, + kda: 5, + }, + }), + createStoredFeature({ + matchId: 'KR_3', + role: 'TOP', + features: { + kda: 2, + }, + }), + createStoredFeature({ + matchId: 'KR_4', + role: 'UNKNOWN', + features: { + kda: 99, + }, + }), + ]; + const aggregate: AggregateMock = jest + .fn, [unknown[]]>() + .mockReturnValue(execResolved(seedFeatures)); + const updateOne: UpdateOneMock = jest + .fn, Parameters>() + .mockReturnValue(execResolved({ acknowledged: true })); + const connectionService = { + getModel: jest.fn((modelKey: string) => + Promise.resolve( + modelKey === 'playerMatchFeature' + ? { aggregate } + : { + updateOne, + }, + ), + ), + } as unknown as ConnectionService; + const service = new MetricBaselineService(connectionService); + + await service.computeMetricBaselines({ + cohort: 'MASTER_PLUS', + patch: '26.13', + }); + + const writtenBaselines = updateOne.mock.calls.map(([filter]) => filter); + expect(writtenBaselines).toEqual( + expect.arrayContaining([ + expect.objectContaining({ metricId: 'kda', role: 'MIDDLE' }), + expect.objectContaining({ metricId: 'csPerMin', role: 'MIDDLE' }), + expect.objectContaining({ metricId: 'kda', role: 'TOP' }), + ]), + ); + expect(writtenBaselines).not.toContainEqual( + expect.objectContaining({ role: 'UNKNOWN' }), + ); + expect(aggregate.mock.calls[0]?.[0]).toContainEqual({ + $match: { + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + patch: '26.13', + role: { + $in: ['TOP', 'JUNGLE', 'MIDDLE', 'BOTTOM', 'UTILITY'], + }, + }, + }); + }); +}); diff --git a/apps/api/src/modules/analysis/metric-baseline.service.ts b/apps/api/src/modules/analysis/metric-baseline.service.ts new file mode 100644 index 0000000..b22294f --- /dev/null +++ b/apps/api/src/modules/analysis/metric-baseline.service.ts @@ -0,0 +1,216 @@ +import { Injectable } from '@nestjs/common'; +import { FEATURE_SCHEMA_VERSION, METRICS, ROLES } from '@persona-lenz/shared'; +import type { PipelineStage } from 'mongoose'; +import { ConnectionService } from '../global/database/connection.service'; +import type { + BaselineCohort, + PlayerMatchFeature, + TeamPosition, +} from '../global/database/schemas'; +import { DEFAULT_SEED_COLLECTION_QUEUE_TYPE } from './analysis.constants'; + +export interface MetricBaselineComputationOptions { + cohort?: BaselineCohort; + computedAt?: Date; + patch?: string; +} + +export interface MetricBaselineComputationResult { + baselinesWritten: number; + cohort: BaselineCohort; + computedAt: Date; + patch: string; + samplesRead: number; +} + +type BaselineFeatureSample = Pick< + PlayerMatchFeature, + 'features' | 'patch' | 'role' +>; + +const BASELINE_PERCENTILES = Array.from( + { length: 19 }, + (_, index) => (index + 1) * 0.05, +); +const MASTER_PLUS_TIERS = ['MASTER', 'GRANDMASTER', 'CHALLENGER']; + +function isTeamPosition(value: unknown): value is TeamPosition { + return typeof value === 'string' && ROLES.includes(value as TeamPosition); +} + +function finiteNumber(value: unknown): number | undefined { + return typeof value === 'number' && Number.isFinite(value) + ? value + : undefined; +} + +function baselineKey(metricId: string, role: TeamPosition): string { + return `${metricId}\u0000${role}`; +} + +function percentile(sortedValues: number[], percentileRank: number): number { + if (sortedValues.length === 0) { + return 0; + } + if (sortedValues.length === 1) { + return sortedValues[0] ?? 0; + } + + const rankIndex = (sortedValues.length - 1) * percentileRank; + const lowerIndex = Math.floor(rankIndex); + const upperIndex = Math.ceil(rankIndex); + const lowerValue = sortedValues[lowerIndex] ?? 0; + const upperValue = sortedValues[upperIndex] ?? lowerValue; + return lowerValue + (upperValue - lowerValue) * (rankIndex - lowerIndex); +} + +@Injectable() +export class MetricBaselineService { + constructor(private readonly connectionService: ConnectionService) {} + + public async computeMetricBaselines( + options: MetricBaselineComputationOptions = {}, + ): Promise { + const cohort = options.cohort ?? 'MASTER_PLUS'; + const computedAt = options.computedAt ?? new Date(); + const patch = options.patch ?? 'ALL'; + const samples = await this.findBaselineFeatureSamples(cohort, patch); + const groupedMetricValues = this.groupMetricValues(samples); + const metricBaselineModel = + await this.connectionService.getModel('metricBaseline'); + + let baselinesWritten = 0; + for (const [key, values] of groupedMetricValues.entries()) { + const [metricId, role] = key.split('\u0000') as [string, TeamPosition]; + const sortedValues = [...values].sort((left, right) => left - right); + const percentileBreakpoints = BASELINE_PERCENTILES.map((percentileRank) => + percentile(sortedValues, percentileRank), + ); + + await metricBaselineModel + .updateOne( + { + metricId, + role, + cohort, + patch, + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + }, + { + $set: { + metricId, + role, + cohort, + patch, + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + sampleCount: sortedValues.length, + percentileBreakpoints, + computedAt, + }, + }, + { upsert: true }, + ) + .exec(); + baselinesWritten += 1; + } + + return { + baselinesWritten, + cohort, + computedAt, + patch, + samplesRead: samples.length, + }; + } + + private async findBaselineFeatureSamples( + cohort: BaselineCohort, + patch: string, + ): Promise { + const playerMatchFeatureModel = + await this.connectionService.getModel('playerMatchFeature'); + return playerMatchFeatureModel + .aggregate(this.baselineAggregation(cohort, patch)) + .exec(); + } + + private baselineAggregation( + cohort: BaselineCohort, + patch: string, + ): PipelineStage[] { + const matchStage: Record = { + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + role: { + $in: [...ROLES], + }, + ...(patch === 'ALL' ? {} : { patch }), + }; + const accountMatchStage: Record = { + 'account.isSeed': true, + ...(cohort === 'MASTER_PLUS' + ? { + 'account.tiers': { + $elemMatch: { + queueType: DEFAULT_SEED_COLLECTION_QUEUE_TYPE, + tier: { + $in: MASTER_PLUS_TIERS, + }, + }, + }, + } + : {}), + }; + + return [ + { + $match: matchStage, + }, + { + $lookup: { + from: 'account', + localField: 'puuid', + foreignField: 'puuid', + as: 'account', + }, + }, + { + $unwind: '$account', + }, + { + $match: accountMatchStage, + }, + { + $project: { + features: 1, + patch: 1, + role: 1, + }, + }, + ]; + } + + private groupMetricValues( + samples: BaselineFeatureSample[], + ): Map { + const metricValuesByKey = new Map(); + for (const sample of samples) { + if (!isTeamPosition(sample.role)) { + continue; + } + + for (const metric of METRICS) { + const value = finiteNumber(sample.features[metric.id]); + if (value === undefined) { + continue; + } + + const key = baselineKey(metric.id, sample.role); + const values = metricValuesByKey.get(key) ?? []; + values.push(value); + metricValuesByKey.set(key, values); + } + } + + return metricValuesByKey; + } +}