From a69e86f2bca97c545455a4fa6f75e2f57c90ca38 Mon Sep 17 00:00:00 2001 From: dahyeon Date: Fri, 3 Jul 2026 00:12:13 -0700 Subject: [PATCH] Add timeline vector metrics --- .../analysis-pipeline.service.spec.ts | 77 +- .../analysis/analysis-pipeline.service.ts | 43 +- .../analysis/analysis-read.service.spec.ts | 12 + .../modules/analysis/analysis-read.service.ts | 20 +- .../src/modules/analysis/analysis.module.ts | 2 + .../feature-extractor.service.spec.ts | 4 +- .../analysis/profile-builder.service.spec.ts | 23 +- .../analysis/profile-builder.service.ts | 24 +- .../analysis/timeline-metric.service.spec.ts | 342 ++++++++ .../analysis/timeline-metric.service.ts | 735 ++++++++++++++++++ apps/api/src/shared-contract.spec.ts | 89 ++- packages/shared/src/dto/analysis.dto.ts | 2 +- packages/shared/src/feature-registry.ts | 207 ++++- 13 files changed, 1543 insertions(+), 37 deletions(-) create mode 100644 apps/api/src/modules/analysis/timeline-metric.service.spec.ts create mode 100644 apps/api/src/modules/analysis/timeline-metric.service.ts diff --git a/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts b/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts index 6427bd6..e5e4a65 100644 --- a/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts +++ b/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts @@ -1,5 +1,5 @@ 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 { Account } from '../global/database/schemas'; 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 { ProfileBuilderService } from './profile-builder.service'; import { TimelineDerivedService } from './timeline-derived.service'; +import { TimelineMetricService } from './timeline-metric.service'; function createJobData(): UserAnalysisJobData { return { @@ -69,6 +70,15 @@ function createMatchPayload(matchId = 'KR_1') { kills: 10, 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: { 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 ProfileBuilderService(), new TimelineDerivedService(), + new TimelineMetricService(), ), updateAnalysisJob, updatePlayerMatchFeature, @@ -400,6 +411,20 @@ describe('AnalysisPipelineService', () => { 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 () => { const timeline = createTimelinePayloadWithFrames('KR_1', [ { @@ -440,12 +465,18 @@ describe('AnalysisPipelineService', () => { { timestamp: 900_000, events: [ + { + type: 'WARD_PLACED', + timestamp: 850_000, + creatorId: 1, + }, { type: 'ELITE_MONSTER_KILL', timestamp: 900_000, killerId: 4, killerTeamId: 100, monsterType: 'DRAGON', + assistingParticipantIds: [1], }, ], }, @@ -453,16 +484,39 @@ describe('AnalysisPipelineService', () => { const getMatchTimeline = jest .fn>, [string, string]>() .mockResolvedValue(timeline); - const { service, updatePlayerMatchFeature } = createPipelineHarness({ - getMatchTimeline, - }); + const { service, updatePlayerMatchFeature, updatePlayerProfile } = + createPipelineHarness({ + getMatchTimeline, + }); await service.processUserAnalysisJob(createJobData(), 'analysis-job-1'); const playerMatchFeatureSet = asRecord( 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(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({ 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 () => { diff --git a/apps/api/src/modules/analysis/analysis-pipeline.service.ts b/apps/api/src/modules/analysis/analysis-pipeline.service.ts index 2072d28..7b3ffd0 100644 --- a/apps/api/src/modules/analysis/analysis-pipeline.service.ts +++ b/apps/api/src/modules/analysis/analysis-pipeline.service.ts @@ -22,6 +22,7 @@ import type { import { FeatureExtractorService } from './feature-extractor.service'; import { ProfileBuilderService } from './profile-builder.service'; import { TimelineDerivedService } from './timeline-derived.service'; +import { TimelineMetricService } from './timeline-metric.service'; interface MatchRecord { matchId: string; @@ -48,6 +49,14 @@ function isRecordValue(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value); } +function isTimelinePayload(value: unknown): value is Record { + 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 { return typeof value === 'number' && Number.isFinite(value) ? value : fallback; } @@ -75,6 +84,7 @@ export class AnalysisPipelineService { private readonly featureExtractorService: FeatureExtractorService, private readonly profileBuilderService: ProfileBuilderService, private readonly timelineDerivedService: TimelineDerivedService, + private readonly timelineMetricService: TimelineMetricService, ) {} public async processUserAnalysisJob( @@ -311,7 +321,7 @@ export class AnalysisPipelineService { existingTimeline: unknown, regionalRoute: UserAnalysisJobData['regionalRoute'], ): Promise | undefined> { - if (isRecordValue(existingTimeline)) { + if (isTimelinePayload(existingTimeline)) { return existingTimeline; } @@ -320,6 +330,12 @@ export class AnalysisPipelineService { matchId, regionalRoute, ); + if (!isTimelinePayload(timeline)) { + this.logger.warn( + `Skipping malformed timeline for matchId="${this.safeLogText(matchId)}"`, + ); + return undefined; + } await this.storeRiotMatchTimeline(matchId, timeline); return timeline; } catch (error) { @@ -366,12 +382,29 @@ export class AnalysisPipelineService { ); if (feature.queueId !== queueId) continue; if (matchRecord.timeline) { - feature.derived = { - ...this.timelineDerivedService.buildDerivedData( - matchRecord.timeline, + const derived = this.timelineDerivedService.buildDerivedData( + matchRecord.timeline, + matchRecord.raw, + ); + const timelineMetrics = + this.timelineMetricService.extractTimelineMetrics( + feature, 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; } diff --git a/apps/api/src/modules/analysis/analysis-read.service.spec.ts b/apps/api/src/modules/analysis/analysis-read.service.spec.ts index 20b7685..c777c3d 100644 --- a/apps/api/src/modules/analysis/analysis-read.service.spec.ts +++ b/apps/api/src/modules/analysis/analysis-read.service.spec.ts @@ -131,7 +131,19 @@ describe('AnalysisReadService', () => { expect(profileFindOne).toHaveBeenCalledWith({ puuid: 'target-puuid', 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([ { metricId: 'deathsPerMin', value: 0.1 }, { metricId: 'kda', value: 0.8 }, diff --git a/apps/api/src/modules/analysis/analysis-read.service.ts b/apps/api/src/modules/analysis/analysis-read.service.ts index 71beeff..dec496c 100644 --- a/apps/api/src/modules/analysis/analysis-read.service.ts +++ b/apps/api/src/modules/analysis/analysis-read.service.ts @@ -1,5 +1,6 @@ import { Injectable, NotFoundException } from '@nestjs/common'; import { + FEATURE_SCHEMA_VERSION, METRICS, type AnalysisJobStatusDto, type MetricValueDto, @@ -90,11 +91,11 @@ export class AnalysisReadService { sampleGameCount: profile.sampleGameCount, championPool: profile.championPool, playstyle: Object.fromEntries( - METRICS.map((metric) => [ - metric.id, - this.clampMetricValue(profile.profile[metric.id]), + Object.entries(profile.profile).map(([metricId, value]) => [ + metricId, + this.clampMetricValue(value), ]), - ) as PlayerAnalysisDto['profile']['playstyle'], + ), featureSchemaVersion: profile.featureSchemaVersion, confidence: profile.confidence, }, @@ -118,7 +119,7 @@ export class AnalysisReadService { const playerProfileModel = await this.connectionService.getModel('playerProfile'); return playerProfileModel - .findOne({ puuid, queueId }) + .findOne({ puuid, queueId, featureSchemaVersion: FEATURE_SCHEMA_VERSION }) .lean() .exec(); } @@ -127,8 +128,13 @@ export class AnalysisReadService { profile: Record, direction: 'strength' | 'weakness', ): MetricValueDto[] { - return METRICS.map((metric) => { - const value = this.clampMetricValue(profile[metric.id]); + return METRICS.flatMap((metric) => { + const rawValue = profile[metric.id]; + if (typeof rawValue !== 'number' || !Number.isFinite(rawValue)) { + return []; + } + + const value = this.clampMetricValue(rawValue); return { metricId: metric.id, score: metric.direction === 'lowerIsBetter' ? 1 - value : value, diff --git a/apps/api/src/modules/analysis/analysis.module.ts b/apps/api/src/modules/analysis/analysis.module.ts index fdb1c15..3451370 100644 --- a/apps/api/src/modules/analysis/analysis.module.ts +++ b/apps/api/src/modules/analysis/analysis.module.ts @@ -19,6 +19,7 @@ import { createBullMqOptions } from './bullmq.config'; import { FeatureExtractorService } from './feature-extractor.service'; import { ProfileBuilderService } from './profile-builder.service'; import { TimelineDerivedService } from './timeline-derived.service'; +import { TimelineMetricService } from './timeline-metric.service'; @Module({ imports: [ @@ -50,6 +51,7 @@ import { TimelineDerivedService } from './timeline-derived.service'; FeatureExtractorService, ProfileBuilderService, TimelineDerivedService, + TimelineMetricService, ], controllers: [AnalysisController], exports: [AnalysisQueueService, AnalysisPipelineService], diff --git a/apps/api/src/modules/analysis/feature-extractor.service.spec.ts b/apps/api/src/modules/analysis/feature-extractor.service.spec.ts index 5e6703a..c9cd315 100644 --- a/apps/api/src/modules/analysis/feature-extractor.service.spec.ts +++ b/apps/api/src/modules/analysis/feature-extractor.service.spec.ts @@ -98,9 +98,9 @@ describe('FeatureExtractorService', () => { soloKills: 2, }); 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.confidence).toBe(1); }); diff --git a/apps/api/src/modules/analysis/profile-builder.service.spec.ts b/apps/api/src/modules/analysis/profile-builder.service.spec.ts index afa2e9e..6046750 100644 --- a/apps/api/src/modules/analysis/profile-builder.service.spec.ts +++ b/apps/api/src/modules/analysis/profile-builder.service.spec.ts @@ -35,7 +35,7 @@ function createFeature( featureSchemaVersion: FEATURE_SCHEMA_VERSION, normalizationMethod: 'registry-baseline', confidence: 1, - timelineProcessed: false, + timelineProcessed: true, ...overrides, }; } @@ -87,13 +87,16 @@ describe('ProfileBuilderService', () => { expect(profile.mainRole).toBe('MIDDLE'); 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( (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( - VECTOR_METRICS.map((metric) => profile.profile[metric.id]), + VECTOR_METRICS.map((metric) => profile.profile[metric.id] ?? 0), ); expect(profile.championPool).toEqual([ { championId: 103, games: 1, wins: 1 }, @@ -115,6 +118,20 @@ describe('ProfileBuilderService', () => { ).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', () => { const metrics: MetricDefinition[] = [ { diff --git a/apps/api/src/modules/analysis/profile-builder.service.ts b/apps/api/src/modules/analysis/profile-builder.service.ts index c1ae320..73beb2e 100644 --- a/apps/api/src/modules/analysis/profile-builder.service.ts +++ b/apps/api/src/modules/analysis/profile-builder.service.ts @@ -18,6 +18,7 @@ type ProfileSourceFeature = Pick< | 'normalized' | 'patch' | 'role' + | 'timelineProcessed' | 'win' >; @@ -37,7 +38,7 @@ function toFiniteMetricValue(value: number | undefined): number { function aggregateScalarMetric( features: readonly ProfileSourceFeature[], metricId: string, -): number { +): number | undefined { let weightedSum = 0; let confidenceSum = 0; @@ -52,7 +53,7 @@ function aggregateScalarMetric( } if (confidenceSum <= 0) { - return 0; + return undefined; } return weightedSum / confidenceSum; @@ -61,7 +62,7 @@ function aggregateScalarMetric( function aggregateRatioMetric( features: readonly ProfileSourceFeature[], metricId: string, -): number { +): number | undefined { const numeratorKey = `${metricId}Numerator`; const denominatorKey = `${metricId}Denominator`; const numerator = features.reduce( @@ -75,7 +76,7 @@ function aggregateRatioMetric( ); if (denominator <= 0) { - return 0; + return undefined; } return numerator / denominator; @@ -88,10 +89,13 @@ export function buildProfileMetricValues( const profile: Record = {}; for (const metric of metrics) { - profile[metric.id] = + const metricValue = metric.kind === 'ratio' ? aggregateRatioMetric(features, metric.id) : aggregateScalarMetric(features, metric.id); + if (metricValue !== undefined) { + profile[metric.id] = metricValue; + } } return profile; @@ -151,6 +155,11 @@ export class ProfileBuilderService { params.features.length / 5, 1, ); + const timelineCoverageMultiplier = + 0.7 + + 0.3 * + (params.features.filter((feature) => feature.timelineProcessed).length / + params.features.length); return { puuid: params.puuid, @@ -168,7 +177,10 @@ export class ProfileBuilderService { vector: VECTOR_METRICS.map((metric) => profile[metric.id] ?? 0), featureSchemaVersion: FEATURE_SCHEMA_VERSION, normalizationMethod: 'registry-baseline', - confidence: averageConfidence * sampleSizeConfidenceMultiplier, + confidence: + averageConfidence * + sampleSizeConfidenceMultiplier * + timelineCoverageMultiplier, patches: [ ...new Set(params.features.map((feature) => feature.patch)), ].sort(), diff --git a/apps/api/src/modules/analysis/timeline-metric.service.spec.ts b/apps/api/src/modules/analysis/timeline-metric.service.spec.ts new file mode 100644 index 0000000..9d35c32 --- /dev/null +++ b/apps/api/src/modules/analysis/timeline-metric.service.spec.ts @@ -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) { + 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, + ); + }); +}); diff --git a/apps/api/src/modules/analysis/timeline-metric.service.ts b/apps/api/src/modules/analysis/timeline-metric.service.ts new file mode 100644 index 0000000..f8be343 --- /dev/null +++ b/apps/api/src/modules/analysis/timeline-metric.service.ts @@ -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[]; + participantFrames: Map; +} + +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; + normalized: Record; + 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 { + if (typeof value === 'object' && value !== null && !Array.isArray(value)) { + return value as Record; + } + 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, +): 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): 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(); + 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, + participants: MatchParticipant[], +): 100 | 200 | undefined { + return ( + asTeamId(event.killerTeamId) ?? + participantTeamId(participants, asParticipantId(event.killerId)) + ); +} + +function eventInvolvesParticipant( + event: Record, + participantId: number, +): boolean { + return ( + asParticipantId(event.killerId) === participantId || + asParticipantIds(event.assistingParticipantIds).includes(participantId) || + victimDamageReceivedParticipantIds(event.victimDamageReceived).includes( + participantId, + ) + ); +} + +function isChampionKillBefore14(event: Record): boolean { + return ( + asString(event.type) === 'CHAMPION_KILL' && + (asNumber(event.timestamp) ?? Number.POSITIVE_INFINITY) < + FOURTEEN_MINUTES_MS + ); +} + +function isObjectiveMonsterEvent(event: Record): 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, + timeline: Record, + 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 = {}; + const normalized: Record = {}; + + 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, + ): TimelineMetricExtractionResult { + return { + features: {}, + normalized: {}, + vector: VECTOR_METRICS.map( + (metric) => existingNormalized[metric.id] ?? 0, + ), + }; + } + + private addScalarMetric( + context: TimelineMetricContext, + features: Record, + normalized: Record, + 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, + normalized: Record, + 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, + normalized: Record, + ): 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, + normalized: Record, + ): 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, + normalized: Record, + ): 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, + normalized: Record, + ): 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, + normalized: Record, + ): 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, + normalized: Record, + ): 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, + normalized: Record, + ): 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, + ); + } +} diff --git a/apps/api/src/shared-contract.spec.ts b/apps/api/src/shared-contract.spec.ts index 7591f74..d853300 100644 --- a/apps/api/src/shared-contract.spec.ts +++ b/apps/api/src/shared-contract.spec.ts @@ -25,24 +25,76 @@ const MVP_1_METRIC_IDS = [ 'objectiveParticipation', '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', () => { - it('defines MVP 1 vector metrics in the documented order', () => { - expect(FEATURE_SCHEMA_VERSION).toBe(1); - expect(METRICS.map((metric) => metric.id)).toEqual(MVP_1_METRIC_IDS); - expect(VECTOR_DIMENSION).toBe(12); + it('defines MVP 2 vector metrics in the documented order', () => { + expect(FEATURE_SCHEMA_VERSION).toBe(2); + expect(METRICS.map((metric) => metric.id)).toEqual(MVP_2_METRIC_IDS); + expect(VECTOR_DIMENSION).toBe(26); expect(METRICS.filter((metric) => metric.includeInVector)).toHaveLength( 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); expect(new Set(metricIds).size).toBe(metricIds.length); for (const metric of METRICS) { expect(metric.label).toBeTruthy(); - expect(metric.kind).toBe('scalar'); expect(metric.includeInVector).toBe(true); expect(metric.baseline).toBeDefined(); expect(Object.keys(metric.baseline ?? {}).sort()).toEqual([ @@ -63,6 +115,29 @@ describe('shared feature registry', () => { expect( METRICS.find((metric) => metric.id === 'deathsPerMin')?.direction, ).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', () => { @@ -127,7 +202,7 @@ describe('shared DTO contracts', () => { status: 'queued', }; 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']; const analysis: PlayerAnalysisDto = { account: { diff --git a/packages/shared/src/dto/analysis.dto.ts b/packages/shared/src/dto/analysis.dto.ts index 3f3167e..a973bcd 100644 --- a/packages/shared/src/dto/analysis.dto.ts +++ b/packages/shared/src/dto/analysis.dto.ts @@ -79,7 +79,7 @@ export interface PlayerProfileSummaryDto { queueId: number; sampleGameCount: number; championPool: ChampionPoolEntryDto[]; - playstyle: Record; + playstyle: Partial>; featureSchemaVersion: number; confidence: number; } diff --git a/packages/shared/src/feature-registry.ts b/packages/shared/src/feature-registry.ts index 7fdaa82..46d63f2 100644 --- a/packages/shared/src/feature-registry.ts +++ b/packages/shared/src/feature-registry.ts @@ -1,4 +1,4 @@ -export const FEATURE_SCHEMA_VERSION = 1; +export const FEATURE_SCHEMA_VERSION = 2; export type MetricDirection = 'higherIsBetter' | 'lowerIsBetter' | 'neutral'; export type Role = 'TOP' | 'JUNGLE' | 'MIDDLE' | 'BOTTOM' | 'UTILITY'; @@ -210,6 +210,211 @@ export const METRICS = [ 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[]; export type MetricId = (typeof METRICS)[number]['id'];