Add timeline vector metrics

This commit is contained in:
dahyeon committed 2026-07-03 00:12:13 -07:00
1 parent 77ba93b94a
commit a69e86f2bc
13 files changed
+1543 -37

No files matched your search

@@ -1,5 +1,5 @@
import { Logger } from '@nestjs/common'; import { Logger } from '@nestjs/common';
import { FEATURE_SCHEMA_VERSION } from '@persona-lenz/shared'; import { FEATURE_SCHEMA_VERSION, VECTOR_METRICS } from '@persona-lenz/shared';
import type { ConnectionService } from '../global/database/connection.service'; import type { ConnectionService } from '../global/database/connection.service';
import type { Account } from '../global/database/schemas'; import type { Account } from '../global/database/schemas';
import { RiotNotFoundError, type RiotApiClient } from '../riot/riot-api.client'; import { RiotNotFoundError, type RiotApiClient } from '../riot/riot-api.client';
@@ -8,6 +8,7 @@ import { FeatureExtractorService } from './feature-extractor.service';
import { AnalysisPipelineService } from './analysis-pipeline.service'; import { AnalysisPipelineService } from './analysis-pipeline.service';
import { ProfileBuilderService } from './profile-builder.service'; import { ProfileBuilderService } from './profile-builder.service';
import { TimelineDerivedService } from './timeline-derived.service'; import { TimelineDerivedService } from './timeline-derived.service';
import { TimelineMetricService } from './timeline-metric.service';
function createJobData(): UserAnalysisJobData { function createJobData(): UserAnalysisJobData {
return { return {
@@ -69,6 +70,15 @@ function createMatchPayload(matchId = 'KR_1') {
kills: 10, kills: 10,
totalDamageDealtToChampions: 30_000, totalDamageDealtToChampions: 30_000,
}, },
{
participantId: 6,
puuid: 'enemy-puuid',
teamId: 200,
teamPosition: 'MIDDLE',
championId: 134,
kills: 4,
totalDamageDealtToChampions: 16_000,
},
], ],
}, },
}; };
@@ -85,7 +95,7 @@ function createTimelinePayload(
}, },
info: { info: {
frameInterval: 60_000, frameInterval: 60_000,
frames: events.length > 0 ? [{ timestamp: 0, events }] : [], frames: [{ timestamp: 0, events, participantFrames: {} }],
}, },
}; };
} }
@@ -281,6 +291,7 @@ function createPipelineHarness(options: PipelineHarnessOptions = {}) {
new FeatureExtractorService(), new FeatureExtractorService(),
new ProfileBuilderService(), new ProfileBuilderService(),
new TimelineDerivedService(), new TimelineDerivedService(),
new TimelineMetricService(),
), ),
updateAnalysisJob, updateAnalysisJob,
updatePlayerMatchFeature, updatePlayerMatchFeature,
@@ -400,6 +411,20 @@ describe('AnalysisPipelineService', () => {
expect(timelineSet.timelineFetchedAt).toBeInstanceOf(Date); expect(timelineSet.timelineFetchedAt).toBeInstanceOf(Date);
}); });
it('refetches cached timeline data when it is malformed', async () => {
const { getMatchTimeline, service, updateRiotMatch } =
createPipelineHarness({
existingMatchRaw: createMatchPayload(),
existingTimeline: {},
});
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
expect(getMatchTimeline).toHaveBeenCalledWith('KR_1', 'asia');
const timelineSet = findTimelineSet(updateRiotMatch);
expect(timelineSet.timeline).toEqual(createTimelinePayload());
});
it('stores derived timeline data when a timeline is available', async () => { it('stores derived timeline data when a timeline is available', async () => {
const timeline = createTimelinePayloadWithFrames('KR_1', [ const timeline = createTimelinePayloadWithFrames('KR_1', [
{ {
@@ -440,12 +465,18 @@ describe('AnalysisPipelineService', () => {
{ {
timestamp: 900_000, timestamp: 900_000,
events: [ events: [
{
type: 'WARD_PLACED',
timestamp: 850_000,
creatorId: 1,
},
{ {
type: 'ELITE_MONSTER_KILL', type: 'ELITE_MONSTER_KILL',
timestamp: 900_000, timestamp: 900_000,
killerId: 4, killerId: 4,
killerTeamId: 100, killerTeamId: 100,
monsterType: 'DRAGON', monsterType: 'DRAGON',
assistingParticipantIds: [1],
}, },
], ],
}, },
@@ -453,16 +484,39 @@ describe('AnalysisPipelineService', () => {
const getMatchTimeline = jest const getMatchTimeline = jest
.fn<Promise<Record<string, unknown>>, [string, string]>() .fn<Promise<Record<string, unknown>>, [string, string]>()
.mockResolvedValue(timeline); .mockResolvedValue(timeline);
const { service, updatePlayerMatchFeature } = createPipelineHarness({ const { service, updatePlayerMatchFeature, updatePlayerProfile } =
getMatchTimeline, createPipelineHarness({
}); getMatchTimeline,
});
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1'); await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
const playerMatchFeatureSet = asRecord( const playerMatchFeatureSet = asRecord(
asRecord(updatePlayerMatchFeature.mock.calls[0][1]).$set, asRecord(updatePlayerMatchFeature.mock.calls[0][1]).$set,
); );
const playerMatchFeatureSetFeatures = asRecord(
playerMatchFeatureSet.features,
);
const playerMatchFeatureSetNormalized = asRecord(
playerMatchFeatureSet.normalized,
);
const playerMatchFeatureSetVector =
playerMatchFeatureSet.vector as number[];
expect(playerMatchFeatureSet.timelineProcessed).toBe(true); expect(playerMatchFeatureSet.timelineProcessed).toBe(true);
expect(playerMatchFeatureSetFeatures).toMatchObject({
objectivePreWardRateNumerator: 1,
objectivePreWardRateDenominator: 1,
eliteObjectiveParticipationRateNumerator: 1,
eliteObjectiveParticipationRateDenominator: 1,
});
expect(playerMatchFeatureSetNormalized.objectivePreWardRate).toBe(1);
expect(
playerMatchFeatureSetVector[
VECTOR_METRICS.findIndex(
(metric) => metric.id === 'objectivePreWardRate',
)
],
).toBe(1);
expect(playerMatchFeatureSet.derived).toEqual({ expect(playerMatchFeatureSet.derived).toEqual({
fightClusters: [ fightClusters: [
{ {
@@ -524,6 +578,19 @@ describe('AnalysisPipelineService', () => {
}, },
], ],
}); });
const playerProfileSet = asRecord(
asRecord(updatePlayerProfile.mock.calls[0][1]).$set,
);
const playerProfileSetProfile = asRecord(playerProfileSet.profile);
const playerProfileSetVector = playerProfileSet.vector as number[];
expect(playerProfileSetProfile.objectivePreWardRate).toBe(1);
expect(
playerProfileSetVector[
VECTOR_METRICS.findIndex(
(metric) => metric.id === 'objectivePreWardRate',
)
],
).toBe(1);
}); });
it('continues raw match analysis when timeline fetch fails', async () => { it('continues raw match analysis when timeline fetch fails', async () => {
@@ -22,6 +22,7 @@ import type {
import { FeatureExtractorService } from './feature-extractor.service'; import { FeatureExtractorService } from './feature-extractor.service';
import { ProfileBuilderService } from './profile-builder.service'; import { ProfileBuilderService } from './profile-builder.service';
import { TimelineDerivedService } from './timeline-derived.service'; import { TimelineDerivedService } from './timeline-derived.service';
import { TimelineMetricService } from './timeline-metric.service';
interface MatchRecord { interface MatchRecord {
matchId: string; matchId: string;
@@ -48,6 +49,14 @@ function isRecordValue(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value); return typeof value === 'object' && value !== null && !Array.isArray(value);
} }
function isTimelinePayload(value: unknown): value is Record<string, unknown> {
if (!isRecordValue(value)) {
return false;
}
const info = asRecord(value.info);
return Array.isArray(info.frames) && info.frames.length > 0;
}
function asNumber(value: unknown, fallback = 0): number { function asNumber(value: unknown, fallback = 0): number {
return typeof value === 'number' && Number.isFinite(value) ? value : fallback; return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
} }
@@ -75,6 +84,7 @@ export class AnalysisPipelineService {
private readonly featureExtractorService: FeatureExtractorService, private readonly featureExtractorService: FeatureExtractorService,
private readonly profileBuilderService: ProfileBuilderService, private readonly profileBuilderService: ProfileBuilderService,
private readonly timelineDerivedService: TimelineDerivedService, private readonly timelineDerivedService: TimelineDerivedService,
private readonly timelineMetricService: TimelineMetricService,
) {} ) {}
public async processUserAnalysisJob( public async processUserAnalysisJob(
@@ -311,7 +321,7 @@ export class AnalysisPipelineService {
existingTimeline: unknown, existingTimeline: unknown,
regionalRoute: UserAnalysisJobData['regionalRoute'], regionalRoute: UserAnalysisJobData['regionalRoute'],
): Promise<Record<string, unknown> | undefined> { ): Promise<Record<string, unknown> | undefined> {
if (isRecordValue(existingTimeline)) { if (isTimelinePayload(existingTimeline)) {
return existingTimeline; return existingTimeline;
} }
@@ -320,6 +330,12 @@ export class AnalysisPipelineService {
matchId, matchId,
regionalRoute, regionalRoute,
); );
if (!isTimelinePayload(timeline)) {
this.logger.warn(
`Skipping malformed timeline for matchId="${this.safeLogText(matchId)}"`,
);
return undefined;
}
await this.storeRiotMatchTimeline(matchId, timeline); await this.storeRiotMatchTimeline(matchId, timeline);
return timeline; return timeline;
} catch (error) { } catch (error) {
@@ -366,12 +382,29 @@ export class AnalysisPipelineService {
); );
if (feature.queueId !== queueId) continue; if (feature.queueId !== queueId) continue;
if (matchRecord.timeline) { if (matchRecord.timeline) {
feature.derived = { const derived = this.timelineDerivedService.buildDerivedData(
...this.timelineDerivedService.buildDerivedData( matchRecord.timeline,
matchRecord.timeline, matchRecord.raw,
);
const timelineMetrics =
this.timelineMetricService.extractTimelineMetrics(
feature,
matchRecord.raw, matchRecord.raw,
), matchRecord.timeline,
derived,
);
feature.derived = {
...derived,
}; };
feature.features = {
...feature.features,
...timelineMetrics.features,
};
feature.normalized = {
...feature.normalized,
...timelineMetrics.normalized,
};
feature.vector = timelineMetrics.vector;
feature.timelineProcessed = true; feature.timelineProcessed = true;
} }
@@ -131,7 +131,19 @@ describe('AnalysisReadService', () => {
expect(profileFindOne).toHaveBeenCalledWith({ expect(profileFindOne).toHaveBeenCalledWith({
puuid: 'target-puuid', puuid: 'target-puuid',
queueId: 420, queueId: 420,
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
}); });
expect(analysis.profile.playstyle.kda).toBe(0.8);
expect(analysis.profile.playstyle.goldDiffAt10).toBeUndefined();
expect(analysis.profile.playstyle.objectivePreWardRate).toBeUndefined();
expect(
analysis.strengths.some((metric) => metric.metricId === 'goldDiffAt10'),
).toBe(false);
expect(
analysis.weaknesses.some(
(metric) => metric.metricId === 'deathWithShutdownBountyGivenRate',
),
).toBe(false);
expect(analysis.strengths).toEqual([ expect(analysis.strengths).toEqual([
{ metricId: 'deathsPerMin', value: 0.1 }, { metricId: 'deathsPerMin', value: 0.1 },
{ metricId: 'kda', value: 0.8 }, { metricId: 'kda', value: 0.8 },
@@ -1,5 +1,6 @@
import { Injectable, NotFoundException } from '@nestjs/common'; import { Injectable, NotFoundException } from '@nestjs/common';
import { import {
FEATURE_SCHEMA_VERSION,
METRICS, METRICS,
type AnalysisJobStatusDto, type AnalysisJobStatusDto,
type MetricValueDto, type MetricValueDto,
@@ -90,11 +91,11 @@ export class AnalysisReadService {
sampleGameCount: profile.sampleGameCount, sampleGameCount: profile.sampleGameCount,
championPool: profile.championPool, championPool: profile.championPool,
playstyle: Object.fromEntries( playstyle: Object.fromEntries(
METRICS.map((metric) => [ Object.entries(profile.profile).map(([metricId, value]) => [
metric.id, metricId,
this.clampMetricValue(profile.profile[metric.id]), this.clampMetricValue(value),
]), ]),
) as PlayerAnalysisDto['profile']['playstyle'], ),
featureSchemaVersion: profile.featureSchemaVersion, featureSchemaVersion: profile.featureSchemaVersion,
confidence: profile.confidence, confidence: profile.confidence,
}, },
@@ -118,7 +119,7 @@ export class AnalysisReadService {
const playerProfileModel = const playerProfileModel =
await this.connectionService.getModel('playerProfile'); await this.connectionService.getModel('playerProfile');
return playerProfileModel return playerProfileModel
.findOne({ puuid, queueId }) .findOne({ puuid, queueId, featureSchemaVersion: FEATURE_SCHEMA_VERSION })
.lean<PlayerProfileRecord>() .lean<PlayerProfileRecord>()
.exec(); .exec();
} }
@@ -127,8 +128,13 @@ export class AnalysisReadService {
profile: Record<string, number>, profile: Record<string, number>,
direction: 'strength' | 'weakness', direction: 'strength' | 'weakness',
): MetricValueDto[] { ): MetricValueDto[] {
return METRICS.map((metric) => { return METRICS.flatMap((metric) => {
const value = this.clampMetricValue(profile[metric.id]); const rawValue = profile[metric.id];
if (typeof rawValue !== 'number' || !Number.isFinite(rawValue)) {
return [];
}
const value = this.clampMetricValue(rawValue);
return { return {
metricId: metric.id, metricId: metric.id,
score: metric.direction === 'lowerIsBetter' ? 1 - value : value, score: metric.direction === 'lowerIsBetter' ? 1 - value : value,
@@ -19,6 +19,7 @@ import { createBullMqOptions } from './bullmq.config';
import { FeatureExtractorService } from './feature-extractor.service'; import { FeatureExtractorService } from './feature-extractor.service';
import { ProfileBuilderService } from './profile-builder.service'; import { ProfileBuilderService } from './profile-builder.service';
import { TimelineDerivedService } from './timeline-derived.service'; import { TimelineDerivedService } from './timeline-derived.service';
import { TimelineMetricService } from './timeline-metric.service';
@Module({ @Module({
imports: [ imports: [
@@ -50,6 +51,7 @@ import { TimelineDerivedService } from './timeline-derived.service';
FeatureExtractorService, FeatureExtractorService,
ProfileBuilderService, ProfileBuilderService,
TimelineDerivedService, TimelineDerivedService,
TimelineMetricService,
], ],
controllers: [AnalysisController], controllers: [AnalysisController],
exports: [AnalysisQueueService, AnalysisPipelineService], exports: [AnalysisQueueService, AnalysisPipelineService],
@@ -98,9 +98,9 @@ describe('FeatureExtractorService', () => {
soloKills: 2, soloKills: 2,
}); });
expect(feature.vector).toEqual( expect(feature.vector).toEqual(
VECTOR_METRICS.map((metric) => feature.normalized[metric.id]), VECTOR_METRICS.map((metric) => feature.normalized[metric.id] ?? 0),
); );
expect(feature.vector).toHaveLength(12); expect(feature.vector).toHaveLength(VECTOR_METRICS.length);
expect(feature.featureSchemaVersion).toBe(FEATURE_SCHEMA_VERSION); expect(feature.featureSchemaVersion).toBe(FEATURE_SCHEMA_VERSION);
expect(feature.confidence).toBe(1); expect(feature.confidence).toBe(1);
}); });
@@ -35,7 +35,7 @@ function createFeature(
featureSchemaVersion: FEATURE_SCHEMA_VERSION, featureSchemaVersion: FEATURE_SCHEMA_VERSION,
normalizationMethod: 'registry-baseline', normalizationMethod: 'registry-baseline',
confidence: 1, confidence: 1,
timelineProcessed: false, timelineProcessed: true,
...overrides, ...overrides,
}; };
} }
@@ -87,13 +87,16 @@ describe('ProfileBuilderService', () => {
expect(profile.mainRole).toBe('MIDDLE'); expect(profile.mainRole).toBe('MIDDLE');
expect(profile.sampleGameCount).toBe(2); expect(profile.sampleGameCount).toBe(2);
for (const metric of METRICS) { for (const metric of METRICS.filter((metric) => metric.kind === 'scalar')) {
expect(profile.profile[metric.id]).toBeCloseTo( expect(profile.profile[metric.id]).toBeCloseTo(
(firstNormalized[metric.id] + secondNormalized[metric.id] * 0.5) / 1.5, (firstNormalized[metric.id] + secondNormalized[metric.id] * 0.5) / 1.5,
); );
} }
for (const metric of METRICS.filter((metric) => metric.kind === 'ratio')) {
expect(profile.profile[metric.id]).toBeUndefined();
}
expect(profile.vector).toEqual( expect(profile.vector).toEqual(
VECTOR_METRICS.map((metric) => profile.profile[metric.id]), VECTOR_METRICS.map((metric) => profile.profile[metric.id] ?? 0),
); );
expect(profile.championPool).toEqual([ expect(profile.championPool).toEqual([
{ championId: 103, games: 1, wins: 1 }, { championId: 103, games: 1, wins: 1 },
@@ -115,6 +118,20 @@ describe('ProfileBuilderService', () => {
).toThrow('Cannot build a profile without match features.'); ).toThrow('Cannot build a profile without match features.');
}); });
it('discounts profile confidence when timeline metrics are missing', () => {
const profile = service.buildProfile({
features: [
createFeature({ timelineProcessed: true }),
createFeature({ matchId: 'KR_2', timelineProcessed: false }),
],
isSeed: false,
puuid: 'target-puuid',
queueId: 420,
});
expect(profile.confidence).toBeCloseTo(0.34);
});
it('aggregates ratio metrics from raw numerator and denominator counts', () => { it('aggregates ratio metrics from raw numerator and denominator counts', () => {
const metrics: MetricDefinition[] = [ const metrics: MetricDefinition[] = [
{ {
@@ -18,6 +18,7 @@ type ProfileSourceFeature = Pick<
| 'normalized' | 'normalized'
| 'patch' | 'patch'
| 'role' | 'role'
| 'timelineProcessed'
| 'win' | 'win'
>; >;
@@ -37,7 +38,7 @@ function toFiniteMetricValue(value: number | undefined): number {
function aggregateScalarMetric( function aggregateScalarMetric(
features: readonly ProfileSourceFeature[], features: readonly ProfileSourceFeature[],
metricId: string, metricId: string,
): number { ): number | undefined {
let weightedSum = 0; let weightedSum = 0;
let confidenceSum = 0; let confidenceSum = 0;
@@ -52,7 +53,7 @@ function aggregateScalarMetric(
} }
if (confidenceSum <= 0) { if (confidenceSum <= 0) {
return 0; return undefined;
} }
return weightedSum / confidenceSum; return weightedSum / confidenceSum;
@@ -61,7 +62,7 @@ function aggregateScalarMetric(
function aggregateRatioMetric( function aggregateRatioMetric(
features: readonly ProfileSourceFeature[], features: readonly ProfileSourceFeature[],
metricId: string, metricId: string,
): number { ): number | undefined {
const numeratorKey = `${metricId}Numerator`; const numeratorKey = `${metricId}Numerator`;
const denominatorKey = `${metricId}Denominator`; const denominatorKey = `${metricId}Denominator`;
const numerator = features.reduce( const numerator = features.reduce(
@@ -75,7 +76,7 @@ function aggregateRatioMetric(
); );
if (denominator <= 0) { if (denominator <= 0) {
return 0; return undefined;
} }
return numerator / denominator; return numerator / denominator;
@@ -88,10 +89,13 @@ export function buildProfileMetricValues(
const profile: Record<string, number> = {}; const profile: Record<string, number> = {};
for (const metric of metrics) { for (const metric of metrics) {
profile[metric.id] = const metricValue =
metric.kind === 'ratio' metric.kind === 'ratio'
? aggregateRatioMetric(features, metric.id) ? aggregateRatioMetric(features, metric.id)
: aggregateScalarMetric(features, metric.id); : aggregateScalarMetric(features, metric.id);
if (metricValue !== undefined) {
profile[metric.id] = metricValue;
}
} }
return profile; return profile;
@@ -151,6 +155,11 @@ export class ProfileBuilderService {
params.features.length / 5, params.features.length / 5,
1, 1,
); );
const timelineCoverageMultiplier =
0.7 +
0.3 *
(params.features.filter((feature) => feature.timelineProcessed).length /
params.features.length);
return { return {
puuid: params.puuid, puuid: params.puuid,
@@ -168,7 +177,10 @@ export class ProfileBuilderService {
vector: VECTOR_METRICS.map((metric) => profile[metric.id] ?? 0), vector: VECTOR_METRICS.map((metric) => profile[metric.id] ?? 0),
featureSchemaVersion: FEATURE_SCHEMA_VERSION, featureSchemaVersion: FEATURE_SCHEMA_VERSION,
normalizationMethod: 'registry-baseline', normalizationMethod: 'registry-baseline',
confidence: averageConfidence * sampleSizeConfidenceMultiplier, confidence:
averageConfidence *
sampleSizeConfidenceMultiplier *
timelineCoverageMultiplier,
patches: [ patches: [
...new Set(params.features.map((feature) => feature.patch)), ...new Set(params.features.map((feature) => feature.patch)),
].sort(), ].sort(),
@@ -0,0 +1,342 @@
import { VECTOR_METRICS } from '@persona-lenz/shared';
import type { ExtractedPlayerMatchFeature } from './analysis.types';
import { TimelineMetricService } from './timeline-metric.service';
function createBaseFeature(): ExtractedPlayerMatchFeature {
return {
matchId: 'KR_1',
puuid: 'target-puuid',
queueId: 420,
role: 'MIDDLE',
championId: 103,
gameCreation: 1_700_000_000_000,
gameDurationSec: 1_800,
win: true,
patch: '26.13',
features: {
kda: 3,
},
normalized: {
kda: 0.5,
},
vector: [],
featureSchemaVersion: 2,
normalizationMethod: 'registry-baseline',
confidence: 1,
timelineProcessed: false,
laneOpponent: {
puuid: 'enemy-mid-puuid',
championId: 134,
},
};
}
function createRawMatch() {
return {
metadata: {
matchId: 'KR_1',
},
info: {
participants: [
{
participantId: 1,
puuid: 'target-puuid',
teamId: 100,
teamPosition: 'MIDDLE',
},
{
participantId: 2,
puuid: 'ally-jungle-puuid',
teamId: 100,
teamPosition: 'JUNGLE',
},
{
participantId: 3,
puuid: 'ally-top-puuid',
teamId: 100,
teamPosition: 'TOP',
},
{
participantId: 6,
puuid: 'enemy-mid-puuid',
teamId: 200,
teamPosition: 'MIDDLE',
},
{
participantId: 7,
puuid: 'enemy-jungle-puuid',
teamId: 200,
teamPosition: 'JUNGLE',
},
],
},
};
}
function participantFrame(overrides: Record<string, unknown>) {
return {
jungleMinionsKilled: 0,
minionsKilled: 0,
position: { x: 0, y: 0 },
timeEnemySpentControlled: 0,
totalGold: 0,
xp: 0,
...overrides,
};
}
function createTimeline() {
return {
info: {
frames: [
{
timestamp: 8 * 60_000,
events: [],
participantFrames: {
'1': participantFrame({ position: { x: 4_000, y: 4_000 } }),
'2': participantFrame({ position: { x: 5_000, y: 4_000 } }),
'3': participantFrame({ position: { x: 10_000, y: 4_000 } }),
},
},
{
timestamp: 10 * 60_000,
events: [
{
type: 'CHAMPION_KILL',
timestamp: 100_000,
killerId: 1,
victimId: 6,
assistingParticipantIds: [2],
},
{
type: 'CHAMPION_KILL',
timestamp: 200_000,
killerId: 2,
victimId: 7,
assistingParticipantIds: [1],
},
{
type: 'CHAMPION_KILL',
timestamp: 300_000,
killerId: 2,
victimId: 7,
assistingParticipantIds: null,
victimDamageReceived: [{ participantId: 1 }],
},
{
type: 'CHAMPION_KILL',
timestamp: 400_000,
killerId: 6,
victimId: 1,
assistingParticipantIds: [],
},
{
type: 'WARD_PLACED',
timestamp: 500_000,
creatorId: 1,
},
],
participantFrames: {
'1': participantFrame({
jungleMinionsKilled: 5,
minionsKilled: 75,
position: { x: 4_000, y: 4_000 },
timeEnemySpentControlled: 10_000,
totalGold: 4_000,
xp: 5_000,
}),
'2': participantFrame({ position: { x: 4_800, y: 4_000 } }),
'3': participantFrame({ position: { x: 9_000, y: 4_000 } }),
'6': participantFrame({
jungleMinionsKilled: 0,
minionsKilled: 70,
totalGold: 3_500,
xp: 4_500,
}),
},
},
{
timestamp: 14 * 60_000,
events: [
{
type: 'WARD_PLACED',
timestamp: 830_000,
creatorId: 1,
},
],
participantFrames: {
'1': participantFrame({
position: { x: 4_000, y: 4_000 },
timeEnemySpentControlled: 30_000,
totalGold: 6_000,
}),
'2': participantFrame({ position: { x: 5_500, y: 4_000 } }),
'3': participantFrame({ position: { x: 11_000, y: 4_000 } }),
'6': participantFrame({
totalGold: 6_200,
}),
},
},
{
timestamp: 15 * 60_000,
events: [
{
type: 'WARD_PLACED',
timestamp: 850_000,
creatorId: 1,
},
{
type: 'ELITE_MONSTER_KILL',
timestamp: 900_000,
killerId: 2,
killerTeamId: 100,
monsterType: 'DRAGON',
assistingParticipantIds: [1],
},
],
participantFrames: {},
},
{
timestamp: 20 * 60_000,
events: [],
participantFrames: {
'1': participantFrame({
position: { x: 4_000, y: 4_000 },
timeEnemySpentControlled: 60_000,
}),
'2': participantFrame({ position: { x: 7_000, y: 4_000 } }),
'3': participantFrame({ position: { x: 12_000, y: 4_000 } }),
},
},
{
timestamp: 30 * 60_000,
events: [],
participantFrames: {
'1': participantFrame({
timeEnemySpentControlled: 90_000,
}),
},
},
],
},
};
}
describe('TimelineMetricService', () => {
const service = new TimelineMetricService();
it('extracts timeline vector metrics and ratio counts', () => {
const feature = createBaseFeature();
const result = service.extractTimelineMetrics(
feature,
createRawMatch(),
createTimeline(),
{
advantageEvents: [],
deathEvents: [
{
t: 400_000,
victimParticipantId: 1,
x: 4_000,
y: 4_000,
zone: 'middleLane',
shutdownBountyGiven: 300,
nearestAllyDistanceApprox: 1_500,
},
{
t: 1_000_000,
victimParticipantId: 1,
x: 4_000,
y: 4_000,
zone: 'middleLane',
shutdownBountyGiven: 0,
nearestAllyDistanceApprox: 1_500,
},
],
fightClusters: [
{
startTimeMs: 100_000,
endTimeMs: 130_000,
killCount: 3,
participantIds: [1, 2, 6, 7],
openerParticipantIds: [1],
cleanupParticipantIds: [2],
isTeamfight: true,
},
{
startTimeMs: 600_000,
endTimeMs: 640_000,
killCount: 3,
participantIds: [1, 2, 6, 7],
openerParticipantIds: [2],
cleanupParticipantIds: [1],
isTeamfight: true,
},
],
objectiveWindows: [
{
objectiveTimeMs: 900_000,
startTimeMs: 780_000,
endTimeMs: 930_000,
killerParticipantId: 2,
killerTeamId: 100,
monsterType: 'DRAGON',
},
],
roamFrames: [],
},
);
expect(result.features).toMatchObject({
goldDiffAt10: 500,
goldDiffAt14: -200,
csDiffAt10: 10,
xpDiffAt10: 500,
deathsBefore14: 1,
killParticipationBefore14: 1,
earlyWardsPerMin: 2 / 14,
objectivePreWardRateNumerator: 1,
objectivePreWardRateDenominator: 1,
eliteObjectiveParticipationRateNumerator: 1,
eliteObjectiveParticipationRateDenominator: 1,
teamfightFirstEngagementParticipationRateNumerator: 1,
teamfightFirstEngagementParticipationRateDenominator: 2,
teamfightCleanupKillParticipationRateNumerator: 1,
teamfightCleanupKillParticipationRateDenominator: 2,
deathWithShutdownBountyGivenRateNumerator: 1,
deathWithShutdownBountyGivenRateDenominator: 2,
ccTimePerMinute: 3,
});
expect(result.features.isolationTendency).toBeCloseTo(
(1_000 + 800 + 1_500 + 3_000) / 4,
);
expect(result.normalized.objectivePreWardRate).toBe(1);
expect(result.normalized.eliteObjectiveParticipationRate).toBe(1);
expect(result.normalized.teamfightFirstEngagementParticipationRate).toBe(
0.5,
);
expect(result.vector).toHaveLength(VECTOR_METRICS.length);
expect(
result.vector[
VECTOR_METRICS.findIndex((metric) => metric.id === 'goldDiffAt10')
],
).toBeCloseTo(result.normalized.goldDiffAt10);
expect(
result.vector[
VECTOR_METRICS.findIndex(
(metric) => metric.id === 'objectivePreWardRate',
)
],
).toBe(1);
expect(
result.vector[
VECTOR_METRICS.findIndex(
(metric) => metric.id === 'deathWithShutdownBountyGivenRate',
)
],
).toBe(0.5);
expect(result.vector[VECTOR_METRICS.length - 1]).toBe(
result.normalized.ccTimePerMinute,
);
});
});
@@ -0,0 +1,735 @@
import {
METRICS,
VECTOR_METRICS,
type MetricDefinition,
type Role,
} from '@persona-lenz/shared';
import { Injectable } from '@nestjs/common';
import type { ExtractedPlayerMatchFeature } from './analysis.types';
import type {
TimelineDeathEvent,
TimelineDerivedData,
TimelineFightCluster,
TimelineObjectiveWindow,
} from './timeline-derived.service';
interface TimelinePosition {
x: number;
y: number;
}
interface MatchParticipant {
participantId: number;
puuid?: string;
teamId?: 100 | 200;
teamPosition?: string;
}
interface TimelineParticipantFrame {
participantId: number;
position?: TimelinePosition;
totalGold?: number;
xp?: number;
minionsKilled?: number;
jungleMinionsKilled?: number;
timeEnemySpentControlled?: number;
}
interface TimelineFrame {
timestamp: number;
events: Record<string, unknown>[];
participantFrames: Map<number, TimelineParticipantFrame>;
}
interface TimelineMetricContext {
allyParticipantIds: number[];
derived: TimelineDerivedData;
feature: ExtractedPlayerMatchFeature;
frames: TimelineFrame[];
gameMinutes: number;
laneOpponentParticipantId?: number;
participantId: number;
participants: MatchParticipant[];
teamId: 100 | 200;
}
export interface TimelineMetricExtractionResult {
features: Record<string, number>;
normalized: Record<string, number>;
vector: number[];
}
const TEN_MINUTES_MS = 10 * 60_000;
const FOURTEEN_MINUTES_MS = 14 * 60_000;
const TWENTY_MINUTES_MS = 20 * 60_000;
const FRAME_MATCH_TOLERANCE_MS = 30_000;
const OBJECTIVE_PRE_WARD_WINDOW_MS = 60_000;
const OBJECTIVE_MONSTER_TYPES = new Set([
'DRAGON',
'RIFTHERALD',
'BARON_NASHOR',
]);
function asRecord(value: unknown): Record<string, unknown> {
if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
return value as Record<string, unknown>;
}
return {};
}
function asArray(value: unknown): unknown[] {
return Array.isArray(value) ? value : [];
}
function asNumber(value: unknown): number | undefined {
return typeof value === 'number' && Number.isFinite(value)
? value
: undefined;
}
function asString(value: unknown): string | undefined {
return typeof value === 'string' ? value : undefined;
}
function asParticipantId(value: unknown): number | undefined {
const participantId = asNumber(value);
return participantId !== undefined && participantId > 0
? participantId
: undefined;
}
function asTeamId(value: unknown): 100 | 200 | undefined {
const teamId = asNumber(value);
return teamId === 100 || teamId === 200 ? teamId : undefined;
}
function asParticipantIds(value: unknown): number[] {
return asArray(value).flatMap((item) => {
const participantId = asParticipantId(item);
return participantId === undefined ? [] : [participantId];
});
}
function victimDamageReceivedParticipantIds(value: unknown): number[] {
return asArray(value).flatMap((item) => {
const participantId = asParticipantId(asRecord(item).participantId);
return participantId === undefined ? [] : [participantId];
});
}
function parsePosition(value: unknown): TimelinePosition | undefined {
const position = asRecord(value);
const x = asNumber(position.x);
const y = asNumber(position.y);
if (x === undefined || y === undefined) {
return undefined;
}
return { x, y };
}
function parseParticipants(
rawMatch: Record<string, unknown>,
): MatchParticipant[] {
const info = asRecord(rawMatch.info);
return asArray(info.participants)
.map(asRecord)
.flatMap((participant) => {
const participantId = asParticipantId(participant.participantId);
if (participantId === undefined) {
return [];
}
return [
{
participantId,
puuid: asString(participant.puuid),
teamId: asTeamId(participant.teamId),
teamPosition: asString(participant.teamPosition),
},
];
});
}
function parseFrames(timeline: Record<string, unknown>): TimelineFrame[] {
const info = asRecord(timeline.info);
return asArray(info.frames)
.map(asRecord)
.flatMap((frame) => {
const timestamp = asNumber(frame.timestamp);
if (timestamp === undefined) {
return [];
}
const participantFrames = new Map<number, TimelineParticipantFrame>();
for (const [participantIdValue, participantFrameValue] of Object.entries(
asRecord(frame.participantFrames),
)) {
const participantId = asParticipantId(Number(participantIdValue));
if (participantId === undefined) {
continue;
}
const participantFrame = asRecord(participantFrameValue);
participantFrames.set(participantId, {
participantId,
position: parsePosition(participantFrame.position),
totalGold: asNumber(participantFrame.totalGold),
xp: asNumber(participantFrame.xp),
minionsKilled: asNumber(participantFrame.minionsKilled),
jungleMinionsKilled: asNumber(participantFrame.jungleMinionsKilled),
timeEnemySpentControlled: asNumber(
participantFrame.timeEnemySpentControlled,
),
});
}
return [
{
timestamp,
events: asArray(frame.events).map(asRecord),
participantFrames,
},
];
})
.sort((left, right) => left.timestamp - right.timestamp);
}
function normalizeMetric(
metric: MetricDefinition,
role: Role,
rawValue: number,
): number {
const baseline = metric.baseline?.[role];
if (!baseline) {
return Math.max(0, Math.min(1, rawValue));
}
return Math.max(
0,
Math.min(1, (rawValue - baseline.min) / (baseline.max - baseline.min)),
);
}
function normalizationRole(role: ExtractedPlayerMatchFeature['role']): Role {
return role === 'UNKNOWN' ? 'MIDDLE' : role;
}
function findMetric(metricId: string): MetricDefinition | undefined {
return METRICS.find((metric) => metric.id === metricId);
}
function findClosestFrame(
frames: TimelineFrame[],
timestampMs: number,
): TimelineFrame | undefined {
let selected: TimelineFrame | undefined;
let selectedDistance = Number.POSITIVE_INFINITY;
for (const frame of frames) {
const distanceMs = Math.abs(frame.timestamp - timestampMs);
if (distanceMs < selectedDistance) {
selected = frame;
selectedDistance = distanceMs;
}
}
return selectedDistance <= FRAME_MATCH_TOLERANCE_MS ? selected : undefined;
}
function participantTeamId(
participants: MatchParticipant[],
participantId: number | undefined,
): 100 | 200 | undefined {
if (participantId === undefined) {
return undefined;
}
return participants.find(
(participant) => participant.participantId === participantId,
)?.teamId;
}
function eventTeamId(
event: Record<string, unknown>,
participants: MatchParticipant[],
): 100 | 200 | undefined {
return (
asTeamId(event.killerTeamId) ??
participantTeamId(participants, asParticipantId(event.killerId))
);
}
function eventInvolvesParticipant(
event: Record<string, unknown>,
participantId: number,
): boolean {
return (
asParticipantId(event.killerId) === participantId ||
asParticipantIds(event.assistingParticipantIds).includes(participantId) ||
victimDamageReceivedParticipantIds(event.victimDamageReceived).includes(
participantId,
)
);
}
function isChampionKillBefore14(event: Record<string, unknown>): boolean {
return (
asString(event.type) === 'CHAMPION_KILL' &&
(asNumber(event.timestamp) ?? Number.POSITIVE_INFINITY) <
FOURTEEN_MINUTES_MS
);
}
function isObjectiveMonsterEvent(event: Record<string, unknown>): boolean {
return (
asString(event.type) === 'ELITE_MONSTER_KILL' &&
OBJECTIVE_MONSTER_TYPES.has(asString(event.monsterType) ?? '')
);
}
function distance(left: TimelinePosition, right: TimelinePosition): number {
return Math.hypot(left.x - right.x, left.y - right.y);
}
function csAt(frame: TimelineParticipantFrame | undefined): number | undefined {
if (!frame) {
return undefined;
}
return (frame.minionsKilled ?? 0) + (frame.jungleMinionsKilled ?? 0);
}
function objectiveWindowTeamId(
window: TimelineObjectiveWindow,
participants: MatchParticipant[],
): 100 | 200 | undefined {
return (
asTeamId(window.killerTeamId) ??
participantTeamId(participants, window.killerParticipantId)
);
}
function scoreParticipantDeath(event: TimelineDeathEvent): number {
return event.shutdownBountyGiven > 0 ? 1 : 0;
}
function finalParticipantFrame(
frames: TimelineFrame[],
participantId: number,
): TimelineParticipantFrame | undefined {
for (let index = frames.length - 1; index >= 0; index -= 1) {
const frame = frames[index].participantFrames.get(participantId);
if (frame) {
return frame;
}
}
return undefined;
}
@Injectable()
export class TimelineMetricService {
public extractTimelineMetrics(
feature: ExtractedPlayerMatchFeature,
rawMatch: Record<string, unknown>,
timeline: Record<string, unknown>,
derived: TimelineDerivedData,
): TimelineMetricExtractionResult {
const participants = parseParticipants(rawMatch);
const participant = participants.find(
(candidate) => candidate.puuid === feature.puuid,
);
if (!participant?.participantId || !participant.teamId) {
return this.emptyResult(feature.normalized);
}
const context: TimelineMetricContext = {
allyParticipantIds: participants
.filter(
(candidate) =>
candidate.teamId === participant.teamId &&
candidate.participantId !== participant.participantId,
)
.map((candidate) => candidate.participantId),
derived,
feature,
frames: parseFrames(timeline),
gameMinutes: Math.max(feature.gameDurationSec / 60, 1),
laneOpponentParticipantId: feature.laneOpponent
? participants.find(
(candidate) => candidate.puuid === feature.laneOpponent?.puuid,
)?.participantId
: undefined,
participantId: participant.participantId,
participants,
teamId: participant.teamId,
};
const features: Record<string, number> = {};
const normalized: Record<string, number> = {};
this.addEarlyLaneMetrics(context, features, normalized);
this.addEarlyEventMetrics(context, features, normalized);
this.addObjectiveMetrics(context, features, normalized);
this.addIsolationMetric(context, features, normalized);
this.addTeamfightMetrics(context, features, normalized);
this.addDeathRiskMetric(context, features, normalized);
this.addCrowdControlMetric(context, features, normalized);
const mergedNormalized = { ...feature.normalized, ...normalized };
return {
features,
normalized,
vector: VECTOR_METRICS.map((metric) => mergedNormalized[metric.id] ?? 0),
};
}
private emptyResult(
existingNormalized: Record<string, number>,
): TimelineMetricExtractionResult {
return {
features: {},
normalized: {},
vector: VECTOR_METRICS.map(
(metric) => existingNormalized[metric.id] ?? 0,
),
};
}
private addScalarMetric(
context: TimelineMetricContext,
features: Record<string, number>,
normalized: Record<string, number>,
metricId: string,
rawValue: number | undefined,
): void {
if (rawValue === undefined || !Number.isFinite(rawValue)) {
return;
}
const metric = findMetric(metricId);
if (!metric) {
return;
}
features[metricId] = rawValue;
normalized[metricId] = normalizeMetric(
metric,
normalizationRole(context.feature.role),
rawValue,
);
}
private addRatioMetric(
context: TimelineMetricContext,
features: Record<string, number>,
normalized: Record<string, number>,
metricId: string,
numerator: number,
denominator: number,
): void {
features[`${metricId}Numerator`] = numerator;
features[`${metricId}Denominator`] = denominator;
if (denominator <= 0) {
return;
}
const metric = findMetric(metricId);
if (!metric) {
return;
}
normalized[metricId] = normalizeMetric(
metric,
normalizationRole(context.feature.role),
numerator / denominator,
);
}
private addEarlyLaneMetrics(
context: TimelineMetricContext,
features: Record<string, number>,
normalized: Record<string, number>,
): void {
if (!context.laneOpponentParticipantId) {
return;
}
const frameAt10 = findClosestFrame(context.frames, TEN_MINUTES_MS);
const participantAt10 = frameAt10?.participantFrames.get(
context.participantId,
);
const opponentAt10 = frameAt10?.participantFrames.get(
context.laneOpponentParticipantId,
);
const frameAt14 = findClosestFrame(context.frames, FOURTEEN_MINUTES_MS);
const participantAt14 = frameAt14?.participantFrames.get(
context.participantId,
);
const opponentAt14 = frameAt14?.participantFrames.get(
context.laneOpponentParticipantId,
);
const playerCsAt10 = csAt(participantAt10);
const opponentCsAt10 = csAt(opponentAt10);
this.addScalarMetric(
context,
features,
normalized,
'goldDiffAt10',
participantAt10?.totalGold !== undefined &&
opponentAt10?.totalGold !== undefined
? participantAt10.totalGold - opponentAt10.totalGold
: undefined,
);
this.addScalarMetric(
context,
features,
normalized,
'goldDiffAt14',
participantAt14?.totalGold !== undefined &&
opponentAt14?.totalGold !== undefined
? participantAt14.totalGold - opponentAt14.totalGold
: undefined,
);
this.addScalarMetric(
context,
features,
normalized,
'csDiffAt10',
playerCsAt10 !== undefined && opponentCsAt10 !== undefined
? playerCsAt10 - opponentCsAt10
: undefined,
);
this.addScalarMetric(
context,
features,
normalized,
'xpDiffAt10',
participantAt10?.xp !== undefined && opponentAt10?.xp !== undefined
? participantAt10.xp - opponentAt10.xp
: undefined,
);
}
private addEarlyEventMetrics(
context: TimelineMetricContext,
features: Record<string, number>,
normalized: Record<string, number>,
): void {
const earlyKillEvents = context.frames
.flatMap((frame) => frame.events)
.filter(isChampionKillBefore14);
const teamEarlyKillEvents = earlyKillEvents.filter(
(event) => eventTeamId(event, context.participants) === context.teamId,
);
const earlyKillParticipationCount = teamEarlyKillEvents.filter((event) =>
eventInvolvesParticipant(event, context.participantId),
).length;
const deathsBefore14 = earlyKillEvents.filter(
(event) => asParticipantId(event.victimId) === context.participantId,
).length;
const earlyWardCount = context.frames
.flatMap((frame) => frame.events)
.filter(
(event) =>
asString(event.type) === 'WARD_PLACED' &&
(asNumber(event.timestamp) ?? Number.POSITIVE_INFINITY) <
FOURTEEN_MINUTES_MS &&
asParticipantId(event.creatorId) === context.participantId,
).length;
this.addScalarMetric(
context,
features,
normalized,
'deathsBefore14',
deathsBefore14,
);
this.addScalarMetric(
context,
features,
normalized,
'killParticipationBefore14',
teamEarlyKillEvents.length > 0
? earlyKillParticipationCount / teamEarlyKillEvents.length
: undefined,
);
this.addScalarMetric(
context,
features,
normalized,
'earlyWardsPerMin',
earlyWardCount / 14,
);
}
private addObjectiveMetrics(
context: TimelineMetricContext,
features: Record<string, number>,
normalized: Record<string, number>,
): void {
const events = context.frames.flatMap((frame) => frame.events);
const wardEvents = events.filter(
(event) =>
asString(event.type) === 'WARD_PLACED' &&
asParticipantId(event.creatorId) === context.participantId,
);
const ownObjectiveWindows = context.derived.objectiveWindows.filter(
(window) =>
objectiveWindowTeamId(window, context.participants) === context.teamId,
);
const objectivePreWardCount = ownObjectiveWindows.filter((window) =>
wardEvents.some((event) => {
const timestamp = asNumber(event.timestamp);
return (
timestamp !== undefined &&
timestamp >= window.objectiveTimeMs - OBJECTIVE_PRE_WARD_WINDOW_MS &&
timestamp <= window.objectiveTimeMs
);
}),
).length;
const ownEliteObjectiveEvents = events.filter(
(event) =>
isObjectiveMonsterEvent(event) &&
eventTeamId(event, context.participants) === context.teamId,
);
const eliteObjectiveParticipationCount = ownEliteObjectiveEvents.filter(
(event) => eventInvolvesParticipant(event, context.participantId),
).length;
this.addRatioMetric(
context,
features,
normalized,
'objectivePreWardRate',
objectivePreWardCount,
ownObjectiveWindows.length,
);
this.addRatioMetric(
context,
features,
normalized,
'eliteObjectiveParticipationRate',
eliteObjectiveParticipationCount,
ownEliteObjectiveEvents.length,
);
}
private addIsolationMetric(
context: TimelineMetricContext,
features: Record<string, number>,
normalized: Record<string, number>,
): void {
const nearestDistances = context.frames.flatMap((frame) => {
if (frame.timestamp < 8 * 60_000 || frame.timestamp > TWENTY_MINUTES_MS) {
return [];
}
const participantPosition = frame.participantFrames.get(
context.participantId,
)?.position;
if (!participantPosition) {
return [];
}
const allyDistances = context.allyParticipantIds.flatMap((allyId) => {
const allyPosition = frame.participantFrames.get(allyId)?.position;
return allyPosition
? [distance(participantPosition, allyPosition)]
: [];
});
if (allyDistances.length === 0) {
return [];
}
return [Math.min(...allyDistances)];
});
this.addScalarMetric(
context,
features,
normalized,
'isolationTendency',
nearestDistances.length > 0
? nearestDistances.reduce((sum, value) => sum + value, 0) /
nearestDistances.length
: undefined,
);
}
private addTeamfightMetrics(
context: TimelineMetricContext,
features: Record<string, number>,
normalized: Record<string, number>,
): void {
const teamfights = context.derived.fightClusters.filter(
(cluster: TimelineFightCluster) => cluster.isTeamfight,
);
const firstEngagementCount = teamfights.filter((cluster) =>
cluster.openerParticipantIds.includes(context.participantId),
).length;
const cleanupCount = teamfights.filter((cluster) =>
cluster.cleanupParticipantIds.includes(context.participantId),
).length;
this.addRatioMetric(
context,
features,
normalized,
'teamfightFirstEngagementParticipationRate',
firstEngagementCount,
teamfights.length,
);
this.addRatioMetric(
context,
features,
normalized,
'teamfightCleanupKillParticipationRate',
cleanupCount,
teamfights.length,
);
}
private addDeathRiskMetric(
context: TimelineMetricContext,
features: Record<string, number>,
normalized: Record<string, number>,
): void {
const ownDeaths = context.derived.deathEvents.filter(
(event) => event.victimParticipantId === context.participantId,
);
const shutdownDeaths = ownDeaths.reduce(
(sum, event) => sum + scoreParticipantDeath(event),
0,
);
this.addRatioMetric(
context,
features,
normalized,
'deathWithShutdownBountyGivenRate',
shutdownDeaths,
ownDeaths.length,
);
}
private addCrowdControlMetric(
context: TimelineMetricContext,
features: Record<string, number>,
normalized: Record<string, number>,
): void {
const finalFrame = finalParticipantFrame(
context.frames,
context.participantId,
);
const controlledMs = finalFrame?.timeEnemySpentControlled;
this.addScalarMetric(
context,
features,
normalized,
'ccTimePerMinute',
controlledMs === undefined
? undefined
: controlledMs / 1_000 / context.gameMinutes,
);
}
}
+82 -7
View File
@@ -25,24 +25,76 @@ const MVP_1_METRIC_IDS = [
'objectiveParticipation', 'objectiveParticipation',
'soloKills', 'soloKills',
]; ];
const MVP_2_TIMELINE_METRIC_IDS = [
'goldDiffAt10',
'goldDiffAt14',
'csDiffAt10',
'xpDiffAt10',
'deathsBefore14',
'killParticipationBefore14',
'earlyWardsPerMin',
'objectivePreWardRate',
'eliteObjectiveParticipationRate',
'isolationTendency',
'teamfightFirstEngagementParticipationRate',
'teamfightCleanupKillParticipationRate',
'deathWithShutdownBountyGivenRate',
'ccTimePerMinute',
];
const MVP_2_METRIC_IDS = [...MVP_1_METRIC_IDS, ...MVP_2_TIMELINE_METRIC_IDS];
const MVP_2_TIMELINE_METRIC_CONTRACTS = [
{ id: 'goldDiffAt10', kind: 'scalar', direction: 'higherIsBetter' },
{ id: 'goldDiffAt14', kind: 'scalar', direction: 'higherIsBetter' },
{ id: 'csDiffAt10', kind: 'scalar', direction: 'higherIsBetter' },
{ id: 'xpDiffAt10', kind: 'scalar', direction: 'higherIsBetter' },
{ id: 'deathsBefore14', kind: 'scalar', direction: 'lowerIsBetter' },
{
id: 'killParticipationBefore14',
kind: 'scalar',
direction: 'higherIsBetter',
},
{ id: 'earlyWardsPerMin', kind: 'scalar', direction: 'higherIsBetter' },
{ id: 'objectivePreWardRate', kind: 'ratio', direction: 'higherIsBetter' },
{
id: 'eliteObjectiveParticipationRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{ id: 'isolationTendency', kind: 'scalar', direction: 'lowerIsBetter' },
{
id: 'teamfightFirstEngagementParticipationRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'teamfightCleanupKillParticipationRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'deathWithShutdownBountyGivenRate',
kind: 'ratio',
direction: 'lowerIsBetter',
},
{ id: 'ccTimePerMinute', kind: 'scalar', direction: 'higherIsBetter' },
] as const;
describe('shared feature registry', () => { describe('shared feature registry', () => {
it('defines MVP 1 vector metrics in the documented order', () => { it('defines MVP 2 vector metrics in the documented order', () => {
expect(FEATURE_SCHEMA_VERSION).toBe(1); expect(FEATURE_SCHEMA_VERSION).toBe(2);
expect(METRICS.map((metric) => metric.id)).toEqual(MVP_1_METRIC_IDS); expect(METRICS.map((metric) => metric.id)).toEqual(MVP_2_METRIC_IDS);
expect(VECTOR_DIMENSION).toBe(12); expect(VECTOR_DIMENSION).toBe(26);
expect(METRICS.filter((metric) => metric.includeInVector)).toHaveLength( expect(METRICS.filter((metric) => metric.includeInVector)).toHaveLength(
VECTOR_DIMENSION, VECTOR_DIMENSION,
); );
}); });
it('keeps metric ids unique and every MVP 1 metric normalizable by role', () => { it('keeps metric ids unique and every vector metric normalizable by role', () => {
const metricIds = METRICS.map((metric) => metric.id); const metricIds = METRICS.map((metric) => metric.id);
expect(new Set(metricIds).size).toBe(metricIds.length); expect(new Set(metricIds).size).toBe(metricIds.length);
for (const metric of METRICS) { for (const metric of METRICS) {
expect(metric.label).toBeTruthy(); expect(metric.label).toBeTruthy();
expect(metric.kind).toBe('scalar');
expect(metric.includeInVector).toBe(true); expect(metric.includeInVector).toBe(true);
expect(metric.baseline).toBeDefined(); expect(metric.baseline).toBeDefined();
expect(Object.keys(metric.baseline ?? {}).sort()).toEqual([ expect(Object.keys(metric.baseline ?? {}).sort()).toEqual([
@@ -63,6 +115,29 @@ describe('shared feature registry', () => {
expect( expect(
METRICS.find((metric) => metric.id === 'deathsPerMin')?.direction, METRICS.find((metric) => metric.id === 'deathsPerMin')?.direction,
).toBe('lowerIsBetter'); ).toBe('lowerIsBetter');
expect(
METRICS.find((metric) => metric.id === 'deathWithShutdownBountyGivenRate')
?.direction,
).toBe('lowerIsBetter');
});
it('defines MVP 2 timeline metric aggregation contracts', () => {
expect(
MVP_2_TIMELINE_METRIC_IDS.map((metricId) => {
const metric = METRICS.find((candidate) => candidate.id === metricId);
return {
id: metric?.id,
kind: metric?.kind,
direction: metric?.direction,
includeInVector: metric?.includeInVector,
};
}),
).toEqual(
MVP_2_TIMELINE_METRIC_CONTRACTS.map((metric) => ({
...metric,
includeInVector: true,
})),
);
}); });
it('defines shared advantage event weights for timeline-derived metrics', () => { it('defines shared advantage event weights for timeline-derived metrics', () => {
@@ -127,7 +202,7 @@ describe('shared DTO contracts', () => {
status: 'queued', status: 'queued',
}; };
const playstyle = Object.fromEntries( const playstyle = Object.fromEntries(
MVP_1_METRIC_IDS.map((metricId) => [metricId, 0.5]), MVP_2_METRIC_IDS.map((metricId) => [metricId, 0.5]),
) as PlayerAnalysisDto['profile']['playstyle']; ) as PlayerAnalysisDto['profile']['playstyle'];
const analysis: PlayerAnalysisDto = { const analysis: PlayerAnalysisDto = {
account: { account: {
+1 -1
View File
@@ -79,7 +79,7 @@ export interface PlayerProfileSummaryDto {
queueId: number; queueId: number;
sampleGameCount: number; sampleGameCount: number;
championPool: ChampionPoolEntryDto[]; championPool: ChampionPoolEntryDto[];
playstyle: Record<MetricId, number>; playstyle: Partial<Record<MetricId, number>>;
featureSchemaVersion: number; featureSchemaVersion: number;
confidence: number; confidence: number;
} }
+206 -1
View File
@@ -1,4 +1,4 @@
export const FEATURE_SCHEMA_VERSION = 1; export const FEATURE_SCHEMA_VERSION = 2;
export type MetricDirection = 'higherIsBetter' | 'lowerIsBetter' | 'neutral'; export type MetricDirection = 'higherIsBetter' | 'lowerIsBetter' | 'neutral';
export type Role = 'TOP' | 'JUNGLE' | 'MIDDLE' | 'BOTTOM' | 'UTILITY'; export type Role = 'TOP' | 'JUNGLE' | 'MIDDLE' | 'BOTTOM' | 'UTILITY';
@@ -210,6 +210,211 @@ export const METRICS = [
UTILITY: { min: 0, max: 1.5 }, UTILITY: { min: 0, max: 1.5 },
}), }),
}, },
{
id: 'goldDiffAt10',
label: '10분 골드 차이',
direction: 'higherIsBetter',
kind: 'scalar',
includeInVector: true,
// TODO: MVP 3에서 인구 percentile baseline으로 교체.
baseline: allRoles({
TOP: { min: -3_000, max: 3_000 },
JUNGLE: { min: -3_000, max: 3_000 },
MIDDLE: { min: -3_000, max: 3_000 },
BOTTOM: { min: -3_000, max: 3_000 },
UTILITY: { min: -2_000, max: 2_000 },
}),
},
{
id: 'goldDiffAt14',
label: '14분 골드 차이',
direction: 'higherIsBetter',
kind: 'scalar',
includeInVector: true,
// TODO: MVP 3에서 인구 percentile baseline으로 교체.
baseline: allRoles({
TOP: { min: -4_000, max: 4_000 },
JUNGLE: { min: -4_000, max: 4_000 },
MIDDLE: { min: -4_000, max: 4_000 },
BOTTOM: { min: -4_000, max: 4_000 },
UTILITY: { min: -2_500, max: 2_500 },
}),
},
{
id: 'csDiffAt10',
label: '10분 CS 차이',
direction: 'higherIsBetter',
kind: 'scalar',
includeInVector: true,
// TODO: MVP 3에서 인구 percentile baseline으로 교체.
baseline: allRoles({
TOP: { min: -60, max: 60 },
JUNGLE: { min: -50, max: 50 },
MIDDLE: { min: -60, max: 60 },
BOTTOM: { min: -60, max: 60 },
UTILITY: { min: -20, max: 20 },
}),
},
{
id: 'xpDiffAt10',
label: '10분 경험치 차이',
direction: 'higherIsBetter',
kind: 'scalar',
includeInVector: true,
// TODO: MVP 3에서 인구 percentile baseline으로 교체.
baseline: allRoles({
TOP: { min: -2_000, max: 2_000 },
JUNGLE: { min: -2_000, max: 2_000 },
MIDDLE: { min: -2_000, max: 2_000 },
BOTTOM: { min: -2_000, max: 2_000 },
UTILITY: { min: -1_500, max: 1_500 },
}),
},
{
id: 'deathsBefore14',
label: '14분 전 사망',
direction: 'lowerIsBetter',
kind: 'scalar',
includeInVector: true,
// TODO: MVP 3에서 인구 percentile baseline으로 교체.
baseline: allRoles({
TOP: { min: 0, max: 6 },
JUNGLE: { min: 0, max: 5 },
MIDDLE: { min: 0, max: 6 },
BOTTOM: { min: 0, max: 6 },
UTILITY: { min: 0, max: 7 },
}),
},
{
id: 'killParticipationBefore14',
label: '14분 전 킬 관여율',
direction: 'higherIsBetter',
kind: 'scalar',
includeInVector: true,
// TODO: MVP 3에서 인구 percentile baseline으로 교체.
baseline: allRoles({
TOP: { min: 0, max: 1 },
JUNGLE: { min: 0, max: 1 },
MIDDLE: { min: 0, max: 1 },
BOTTOM: { min: 0, max: 1 },
UTILITY: { min: 0, max: 1 },
}),
},
{
id: 'earlyWardsPerMin',
label: '초반 분당 와드',
direction: 'higherIsBetter',
kind: 'scalar',
includeInVector: true,
// TODO: MVP 3에서 인구 percentile baseline으로 교체.
baseline: allRoles({
TOP: { min: 0, max: 1 },
JUNGLE: { min: 0, max: 1.2 },
MIDDLE: { min: 0, max: 1 },
BOTTOM: { min: 0, max: 1 },
UTILITY: { min: 0, max: 2 },
}),
},
{
id: 'objectivePreWardRate',
label: '오브젝트 전 와드율',
direction: 'higherIsBetter',
kind: 'ratio',
includeInVector: true,
baseline: allRoles({
TOP: { min: 0, max: 1 },
JUNGLE: { min: 0, max: 1 },
MIDDLE: { min: 0, max: 1 },
BOTTOM: { min: 0, max: 1 },
UTILITY: { min: 0, max: 1 },
}),
},
{
id: 'eliteObjectiveParticipationRate',
label: '에픽 오브젝트 관여율',
direction: 'higherIsBetter',
kind: 'ratio',
includeInVector: true,
baseline: allRoles({
TOP: { min: 0, max: 1 },
JUNGLE: { min: 0, max: 1 },
MIDDLE: { min: 0, max: 1 },
BOTTOM: { min: 0, max: 1 },
UTILITY: { min: 0, max: 1 },
}),
},
{
id: 'isolationTendency',
label: '고립 성향',
direction: 'lowerIsBetter',
kind: 'scalar',
includeInVector: true,
// TODO: MVP 3에서 인구 percentile baseline으로 교체.
baseline: allRoles({
TOP: { min: 0, max: 8_000 },
JUNGLE: { min: 0, max: 8_000 },
MIDDLE: { min: 0, max: 8_000 },
BOTTOM: { min: 0, max: 8_000 },
UTILITY: { min: 0, max: 8_000 },
}),
},
{
id: 'teamfightFirstEngagementParticipationRate',
label: '한타 첫 교전 관여율',
direction: 'higherIsBetter',
kind: 'ratio',
includeInVector: true,
baseline: allRoles({
TOP: { min: 0, max: 1 },
JUNGLE: { min: 0, max: 1 },
MIDDLE: { min: 0, max: 1 },
BOTTOM: { min: 0, max: 1 },
UTILITY: { min: 0, max: 1 },
}),
},
{
id: 'teamfightCleanupKillParticipationRate',
label: '한타 마무리 관여율',
direction: 'higherIsBetter',
kind: 'ratio',
includeInVector: true,
baseline: allRoles({
TOP: { min: 0, max: 1 },
JUNGLE: { min: 0, max: 1 },
MIDDLE: { min: 0, max: 1 },
BOTTOM: { min: 0, max: 1 },
UTILITY: { min: 0, max: 1 },
}),
},
{
id: 'deathWithShutdownBountyGivenRate',
label: '현상금 사망률',
direction: 'lowerIsBetter',
kind: 'ratio',
includeInVector: true,
baseline: allRoles({
TOP: { min: 0, max: 1 },
JUNGLE: { min: 0, max: 1 },
MIDDLE: { min: 0, max: 1 },
BOTTOM: { min: 0, max: 1 },
UTILITY: { min: 0, max: 1 },
}),
},
{
id: 'ccTimePerMinute',
label: '분당 군중제어 시간',
direction: 'higherIsBetter',
kind: 'scalar',
includeInVector: true,
// TODO: MVP 3에서 인구 percentile baseline으로 교체.
baseline: allRoles({
TOP: { min: 0, max: 10 },
JUNGLE: { min: 0, max: 12 },
MIDDLE: { min: 0, max: 10 },
BOTTOM: { min: 0, max: 8 },
UTILITY: { min: 0, max: 15 },
}),
},
] as const satisfies readonly MetricDefinition[]; ] as const satisfies readonly MetricDefinition[];
export type MetricId = (typeof METRICS)[number]['id']; export type MetricId = (typeof METRICS)[number]['id'];