Add metric baseline computation service

This commit is contained in:
dahyeon committed 2026-07-03 01:15:20 -07:00
1 parent d18e36e962
commit 3ef86b0b66
3 files changed
+437

No files matched your search

@@ -18,6 +18,7 @@ import { AnalysisPipelineService } from './analysis-pipeline.service';
import { AnalysisProcessor } from './analysis.processor'; import { AnalysisProcessor } from './analysis.processor';
import { createBullMqOptions } from './bullmq.config'; import { createBullMqOptions } from './bullmq.config';
import { FeatureExtractorService } from './feature-extractor.service'; import { FeatureExtractorService } from './feature-extractor.service';
import { MetricBaselineService } from './metric-baseline.service';
import { ProfileBuilderService } from './profile-builder.service'; import { ProfileBuilderService } from './profile-builder.service';
import { SeedCollectionProcessor } from './seed-collection.processor'; import { SeedCollectionProcessor } from './seed-collection.processor';
import { SeedCollectionService } from './seed-collection.service'; import { SeedCollectionService } from './seed-collection.service';
@@ -56,6 +57,7 @@ import { TimelineMetricService } from './timeline-metric.service';
AnalysisProcessor, AnalysisProcessor,
SeedCollectionProcessor, SeedCollectionProcessor,
FeatureExtractorService, FeatureExtractorService,
MetricBaselineService,
ProfileBuilderService, ProfileBuilderService,
SeedCollectionService, SeedCollectionService,
TimelineDerivedService, TimelineDerivedService,
@@ -65,6 +67,7 @@ import { TimelineMetricService } from './timeline-metric.service';
exports: [ exports: [
AnalysisQueueService, AnalysisQueueService,
AnalysisPipelineService, AnalysisPipelineService,
MetricBaselineService,
SeedCollectionService, SeedCollectionService,
], ],
}) })
@@ -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<T> {
exec: jest.Mock<Promise<T>, []>;
}
type AcknowledgedUpdate = { acknowledged: boolean };
type AggregateMock = jest.Mock<ExecQuery<PlayerMatchFeature[]>, [unknown[]]>;
type UpdateOneMock = jest.Mock<
ExecQuery<AcknowledgedUpdate>,
[Record<string, unknown>, Record<string, unknown>, Record<string, unknown>?]
>;
function asRecord(value: unknown): Record<string, unknown> {
if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
return value as Record<string, unknown>;
}
return {};
}
function execResolved<T>(value: T): ExecQuery<T> {
return { exec: jest.fn<Promise<T>, []>().mockResolvedValue(value) };
}
function createStoredFeature(
overrides: Partial<PlayerMatchFeature> = {},
): 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<ExecQuery<PlayerMatchFeature[]>, [unknown[]]>()
.mockReturnValue(execResolved(seedFeatures));
const updateOne: UpdateOneMock = jest
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
.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<ExecQuery<PlayerMatchFeature[]>, [unknown[]]>()
.mockReturnValue(execResolved(seedFeatures));
const updateOne: UpdateOneMock = jest
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
.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'],
},
},
});
});
});
@@ -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<MetricBaselineComputationResult> {
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<BaselineFeatureSample[]> {
const playerMatchFeatureModel =
await this.connectionService.getModel('playerMatchFeature');
return playerMatchFeatureModel
.aggregate<BaselineFeatureSample>(this.baselineAggregation(cohort, patch))
.exec();
}
private baselineAggregation(
cohort: BaselineCohort,
patch: string,
): PipelineStage[] {
const matchStage: Record<string, unknown> = {
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
role: {
$in: [...ROLES],
},
...(patch === 'ALL' ? {} : { patch }),
};
const accountMatchStage: Record<string, unknown> = {
'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<string, number[]> {
const metricValuesByKey = new Map<string, number[]>();
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;
}
}