@reicek/neataptic-ts 0.1.21 → 0.1.22

package/test/examples/flappy_bird/trainer/trainer.report.service.services.ts

@@ -0,0 +1,181 @@
+import {
+  evaluateFlappyFitnessAcrossSeeds,
+  rolloutEpisode,
+  type FlappyRolloutOptions,
+  type FlappySeedBatchEvaluation,
+} from '../flappyEvaluation';
+import {
+  FLAPPY_TRAINER_DUMMY_FLAP_OUTPUT,
+  FLAPPY_TRAINER_DUMMY_NETWORK_ID,
+  FLAPPY_TRAINER_DUMMY_NO_FLAP_OUTPUT,
+} from './trainer.constants';
+import type { FlappyTrainerNetwork } from './trainer.types';
+
+/**
+ * Aggregate and representative rollout resolved for the best genome.
+ *
+ * Keeping these values together lets the report facade stay focused on
+ * orchestration while this helper module owns cache fallback behavior.
+ */
+export interface ResolvedBestGenerationDetails {
+  bestAggregate: FlappySeedBatchEvaluation;
+  bestEpisode: ReturnType<typeof rolloutEpisode>;
+}
+
+/**
+ * Collects only finite scores from the current population.
+ *
+ * Unevaluated or invalid scores are intentionally skipped so percentile and
+ * standard deviation calculations operate on stable numeric inputs only.
+ *
+ * @param population - Current population.
+ * @returns Finite scores in population order.
+ * @example
+ * ```ts
+ * const scores = collectFiniteGenomeScores(population);
+ * ```
+ */
+export function collectFiniteGenomeScores(
+  population: readonly FlappyTrainerNetwork[],
+): number[] {
+  const finiteScores: number[] = [];
+
+  for (const genome of population) {
+    const genomeScore = genome.score ?? Number.NEGATIVE_INFINITY;
+    if (Number.isFinite(genomeScore)) {
+      finiteScores.push(genomeScore);
+    }
+  }
+
+  return finiteScores;
+}
+
+/**
+ * Resolves cached or fallback best-of-generation details for reporting.
+ *
+ * The report layer needs both aggregate seed statistics and one representative
+ * episode. This helper centralizes the fallback rules so the service facade can
+ * remain a thin orchestration layer.
+ *
+ * @param population - Current population.
+ * @param bestGenome - Genome selected as generation best.
+ * @param aggregateByGenome - Cached aggregate evaluations keyed by genome.
+ * @param fallbackSeeds - Seeds used when the aggregate must be recomputed.
+ * @param fallbackRolloutOptions - Rollout options for fallback evaluation.
+ * @returns Aggregate metrics and a representative best-genome episode.
+ * @example
+ * ```ts
+ * const { bestAggregate, bestEpisode } = resolveBestGenerationDetails(
+ *   population,
+ *   bestGenome,
+ *   aggregateByGenome,
+ *   reevaluationSeeds,
+ *   reevaluationRolloutOptions,
+ * );
+ * ```
+ */
+export function resolveBestGenerationDetails(
+  population: readonly FlappyTrainerNetwork[],
+  bestGenome: FlappyTrainerNetwork | undefined,
+  aggregateByGenome: ReadonlyMap<
+    FlappyTrainerNetwork,
+    FlappySeedBatchEvaluation
+  >,
+  fallbackSeeds: readonly number[],
+  fallbackRolloutOptions: FlappyRolloutOptions,
+): ResolvedBestGenerationDetails {
+  return {
+    bestAggregate: resolveBestAggregate(
+      population,
+      bestGenome,
+      aggregateByGenome,
+      fallbackSeeds,
+      fallbackRolloutOptions,
+    ),
+    bestEpisode: resolveBestEpisode(
+      population,
+      bestGenome,
+      fallbackSeeds,
+      fallbackRolloutOptions,
+    ),
+  };
+}
+
+function resolveBestAggregate(
+  population: readonly FlappyTrainerNetwork[],
+  bestGenome: FlappyTrainerNetwork | undefined,
+  aggregateByGenome: ReadonlyMap<
+    FlappyTrainerNetwork,
+    FlappySeedBatchEvaluation
+  >,
+  fallbackSeeds: readonly number[],
+  fallbackRolloutOptions: FlappyRolloutOptions,
+): FlappySeedBatchEvaluation {
+  const fallbackGenome = resolveFallbackGenome(population, bestGenome);
+  if (!fallbackGenome) {
+    return buildEmptySeedBatchEvaluation();
+  }
+
+  const cachedAggregate = aggregateByGenome.get(fallbackGenome);
+  if (cachedAggregate) {
+    return cachedAggregate;
+  }
+
+  return evaluateFlappyFitnessAcrossSeeds(
+    fallbackGenome,
+    fallbackSeeds,
+    fallbackRolloutOptions,
+  );
+}
+
+function resolveBestEpisode(
+  population: readonly FlappyTrainerNetwork[],
+  bestGenome: FlappyTrainerNetwork | undefined,
+  fallbackSeeds: readonly number[],
+  fallbackRolloutOptions: FlappyRolloutOptions,
+): ReturnType<typeof rolloutEpisode> {
+  const fallbackGenome = resolveFallbackGenome(population, bestGenome);
+  if (!fallbackGenome) {
+    return rolloutEpisode(resolveDummyNetwork(), fallbackRolloutOptions);
+  }
+
+  const episodeSeed = fallbackSeeds[0];
+  return rolloutEpisode(fallbackGenome, {
+    ...fallbackRolloutOptions,
+    seed: episodeSeed,
+  });
+}
+
+function resolveFallbackGenome(
+  population: readonly FlappyTrainerNetwork[],
+  bestGenome: FlappyTrainerNetwork | undefined,
+): FlappyTrainerNetwork | undefined {
+  return bestGenome ?? population[0];
+}
+
+function buildEmptySeedBatchEvaluation(): FlappySeedBatchEvaluation {
+  return {
+    seedCount: 0,
+    meanFitness: 0,
+    medianFitness: 0,
+    p90Fitness: 0,
+    fitnessStdDev: 0,
+    robustFitness: 0,
+    meanPipesPassed: 0,
+    meanFramesSurvived: 0,
+  };
+}
+
+function resolveDummyNetwork(): FlappyTrainerNetwork {
+  return {
+    activate: activateWithoutFlap,
+    _id: FLAPPY_TRAINER_DUMMY_NETWORK_ID,
+  };
+}
+
+function activateWithoutFlap(): number[] {
+  return [
+    FLAPPY_TRAINER_DUMMY_NO_FLAP_OUTPUT,
+    FLAPPY_TRAINER_DUMMY_FLAP_OUTPUT,
+  ];
+}

package/test/examples/flappy_bird/trainer/trainer.report.service.ts

@@ -0,0 +1,126 @@
+import {
+  rolloutEpisode,
+  type FlappySeedBatchEvaluation,
+} from '../flappyEvaluation';
+import {
+  FLAPPY_TRAINER_LOG_PARTS_DELIMITER,
+  FLAPPY_TRAINER_SCORE_MEDIAN_PERCENTILE,
+  FLAPPY_TRAINER_SCORE_P90_PERCENTILE,
+} from './trainer.constants';
+import type { FlappyMutationSchedule } from './trainer.evaluation-plan.utils';
+import {
+  collectFiniteGenomeScores,
+  resolveBestGenerationDetails,
+} from './trainer.report.service.services';
+import { buildGenerationLogParts } from './trainer.reporting.utils';
+import { resolveBestGenomeByScore } from './trainer.selection.utils';
+import {
+  computeMean,
+  computePercentile,
+  computePopulationStandardDeviation,
+} from '../flappy.simulation.shared.utils';
+import type {
+  FlappyGenerationEvaluationPlan,
+  FlappyGenerationReport,
+  FlappyTrainerNetwork,
+} from './trainer.types';
+
+/**
+ * Builds a compact report for the current generation.
+ *
+ * @param population - Current population.
+ * @param aggregateByGenome - Aggregate evaluation results keyed by genome.
+ * @param generationEvaluationPlan - Per-generation staged evaluation plan.
+ * @returns Aggregated generation report.
+ */
+export function buildGenerationReport(
+  population: readonly FlappyTrainerNetwork[],
+  aggregateByGenome: ReadonlyMap<
+    FlappyTrainerNetwork,
+    FlappySeedBatchEvaluation
+  >,
+  generationEvaluationPlan: FlappyGenerationEvaluationPlan,
+): FlappyGenerationReport {
+  // Step 1: Collect stable numeric inputs for distribution statistics.
+  const finalScores = collectFiniteGenomeScores(population);
+  const scoreMean = computeMean(finalScores);
+  const scoreStdDev = computePopulationStandardDeviation(
+    finalScores,
+    scoreMean,
+  );
+
+  // Step 2: Resolve best-genome derived metrics through the report helper boundary.
+  const bestGenome = resolveBestGenomeByScore(population);
+  const { bestAggregate, bestEpisode } = resolveBestGenerationDetails(
+    population,
+    bestGenome,
+    aggregateByGenome,
+    generationEvaluationPlan.reevaluationSeeds,
+    generationEvaluationPlan.reevaluationRolloutOptions,
+  );
+
+  // Step 3: Fold the resolved metrics into the compact generation report.
+  return {
+    generationIndex: generationEvaluationPlan.generationIndex,
+    difficultyScale: generationEvaluationPlan.difficultyScale,
+    mutationRate: generationEvaluationPlan.mutationRate,
+    mutationAmount: generationEvaluationPlan.mutationAmount,
+    quickSeedCount: generationEvaluationPlan.quickSeeds.length,
+    fullSeedCount: generationEvaluationPlan.fullSeeds.length,
+    reevaluationSeedCount: generationEvaluationPlan.reevaluationSeeds.length,
+    evaluatedPopulationSize: population.length,
+    scoreMean,
+    scoreMedian: computePercentile(
+      finalScores,
+      FLAPPY_TRAINER_SCORE_MEDIAN_PERCENTILE,
+    ),
+    scoreP90: computePercentile(
+      finalScores,
+      FLAPPY_TRAINER_SCORE_P90_PERCENTILE,
+    ),
+    scoreStdDev,
+    bestRobustFitness: bestGenome?.score ?? Number.NaN,
+    bestMeanFitness: bestAggregate.meanFitness,
+    bestPipesPassed: bestEpisode.pipesPassed,
+    bestFramesSurvived: bestEpisode.framesSurvived,
+  };
+}
+
+/**
+ * Emits one compact generation log line.
+ *
+ * @param generationLabel - Current generation label.
+ * @param mutationSchedule - Active mutation schedule.
+ * @param report - Optional aggregated generation report.
+ * @param fittestGenome - Fittest genome returned by the NEAT controller.
+ * @param fallbackEpisode - Fallback representative rollout episode.
+ * @returns Nothing.
+ */
+export function logGenerationSummary(
+  generationLabel: number,
+  mutationSchedule: FlappyMutationSchedule,
+  report: FlappyGenerationReport | undefined,
+  fittestGenome: FlappyTrainerNetwork,
+  fallbackEpisode: ReturnType<typeof rolloutEpisode>,
+): void {
+  const bestFitness =
+    report?.bestRobustFitness ??
+    (fittestGenome.score as number) ??
+    fallbackEpisode.fitness;
+  const bestPipesPassed =
+    report?.bestPipesPassed ?? fallbackEpisode.pipesPassed;
+  const bestFramesSurvived =
+    report?.bestFramesSurvived ?? fallbackEpisode.framesSurvived;
+
+  const logParts = buildGenerationLogParts(
+    generationLabel,
+    bestFitness,
+    bestPipesPassed,
+    bestFramesSurvived,
+    report,
+    mutationSchedule,
+  );
+
+  // eslint-disable-next-line no-console
+  console.log(logParts.join(FLAPPY_TRAINER_LOG_PARTS_DELIMITER));
+}

package/test/examples/flappy_bird/trainer/trainer.selection.utils.ts

@@ -0,0 +1,89 @@
+import type { FlappyTrainerNetwork, ScoredGenomeEntry } from './trainer.types';
+
+/**
+ * Returns top genomes ordered by current provisional score.
+ *
+ * @param population - Current trainer population.
+ * @param provisionalScoresByGenome - Optional map of staged provisional scores.
+ * @param targetCount - Maximum number of genomes to return.
+ * @returns Highest-scoring genomes in descending score order.
+ */
+export function selectTopGenomesByScore(
+  population: readonly FlappyTrainerNetwork[],
+  provisionalScoresByGenome: ReadonlyMap<FlappyTrainerNetwork, number>,
+  targetCount: number,
+): FlappyTrainerNetwork[] {
+  const scoredEntries = buildScoredGenomeEntries(
+    population,
+    provisionalScoresByGenome,
+  );
+
+  scoredEntries.sort(compareScoredGenomeEntriesDescending);
+
+  const selectedGenomes: FlappyTrainerNetwork[] = [];
+  const maximumSelectionCount = Math.max(
+    0,
+    Math.min(targetCount, scoredEntries.length),
+  );
+
+  let selectedIndex = 0;
+  while (selectedIndex < maximumSelectionCount) {
+    const scoredEntry = scoredEntries[selectedIndex];
+    if (scoredEntry) {
+      selectedGenomes.push(scoredEntry.genome);
+    }
+    selectedIndex += 1;
+  }
+
+  return selectedGenomes;
+}
+
+/**
+ * Resolves the best genome by current score.
+ *
+ * @param population - Current trainer population.
+ * @returns Highest-scoring genome or `undefined` when population is empty.
+ */
+export function resolveBestGenomeByScore(
+  population: readonly FlappyTrainerNetwork[],
+): FlappyTrainerNetwork | undefined {
+  const scoredGenomes = buildScoredGenomeEntries(population, undefined);
+  scoredGenomes.sort(compareScoredGenomeEntriesDescending);
+  return scoredGenomes[0]?.genome;
+}
+
+function buildScoredGenomeEntries(
+  population: readonly FlappyTrainerNetwork[],
+  provisionalScoresByGenome:
+    | ReadonlyMap<FlappyTrainerNetwork, number>
+    | undefined,
+): ScoredGenomeEntry[] {
+  const scoredEntries: ScoredGenomeEntry[] = [];
+
+  for (const genome of population) {
+    const score = resolveGenomeScore(genome, provisionalScoresByGenome);
+    scoredEntries.push({ genome, score });
+  }
+
+  return scoredEntries;
+}
+
+function resolveGenomeScore(
+  genome: FlappyTrainerNetwork,
+  provisionalScoresByGenome:
+    | ReadonlyMap<FlappyTrainerNetwork, number>
+    | undefined,
+): number {
+  if (provisionalScoresByGenome) {
+    return provisionalScoresByGenome.get(genome) ?? Number.NEGATIVE_INFINITY;
+  }
+
+  return genome.score ?? Number.NEGATIVE_INFINITY;
+}
+
+function compareScoredGenomeEntriesDescending(
+  leftEntry: ScoredGenomeEntry,
+  rightEntry: ScoredGenomeEntry,
+): number {
+  return rightEntry.score - leftEntry.score;
+}