@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/trainer/trainer.types.ts

@@ -3,12 +3,22 @@ import type {
   FlappyRolloutOptions,
 } from '../flappyEvaluation';
 
-/** Network shape expected by the Flappy trainer. */
+/**
+ * Network shape expected by the Flappy trainer.
+ *
+ * The trainer only needs the evaluation-facing subset of a full network plus an
+ * optional score field used by staged ranking helpers.
+ */
 export interface FlappyTrainerNetwork extends FlappyNetworkLike {
   score?: number;
 }
 
-/** Local typed view for population-level fitness mode used by this trainer. */
+/**
+ * Local typed view for population-level fitness mode used by this trainer.
+ *
+ * This is intentionally narrower than the full `Neat` runtime API. The trainer
+ * documents only the methods and mutable options it actually depends on.
+ */
 export interface FlappyTrainerNeatController {
   generation: number;
   options: {
@@ -21,7 +31,13 @@ export interface FlappyTrainerNeatController {
   restoreRNGState(seed: number): void;
 }
 
-/** Compact generation report used for training logs. */
+/**
+ * Compact generation report used for training logs.
+ *
+ * The report is shaped for longitudinal monitoring rather than raw storage. It
+ * collects the distribution and best-run details needed to judge whether a
+ * generation improved robustly.
+ */
 export interface FlappyGenerationReport {
   generationIndex: number;
   difficultyScale: number;
@@ -41,13 +57,23 @@ export interface FlappyGenerationReport {
   bestFramesSurvived: number;
 }
 
-/** Trainer runtime state shared by orchestration helpers. */
+/**
+ * Trainer runtime state shared by orchestration helpers.
+ *
+ * Only mutable cross-step values live here: stop intent and the most recent
+ * generation report.
+ */
 export interface FlappyTrainerRuntimeState {
   shouldStop: boolean;
   latestGenerationReport?: FlappyGenerationReport;
 }
 
-/** Immutable trainer setup values. */
+/**
+ * Immutable trainer setup values.
+ *
+ * These values define the static training shape before runtime state and staged
+ * evaluation are attached.
+ */
 export interface FlappyTrainerSetup {
   inputSize: number;
   outputSize: number;
@@ -55,7 +81,13 @@ export interface FlappyTrainerSetup {
   elitismCount: number;
 }
 
-/** Generation-level rollout plans for staged evaluation. */
+/**
+ * Generation-level rollout plans for staged evaluation.
+ *
+ * Each generation resolves one plan that answers three questions: how strong is
+ * the current mutation schedule, which shared seeds belong to each stage, and
+ * what rollout budget each stage is allowed to spend.
+ */
 export interface FlappyGenerationEvaluationPlan {
   generationIndex: number;
   mutationRate: number;
@@ -69,7 +101,12 @@ export interface FlappyGenerationEvaluationPlan {
   reevaluationRolloutOptions: FlappyRolloutOptions;
 }
 
-/** Score carrier used for deterministic ordering helpers. */
+/**
+ * Score carrier used for deterministic ordering helpers.
+ *
+ * Wrapping a genome together with its score makes ranking utilities easier to
+ * write and keeps tie-breaking logic explicit.
+ */
 export interface ScoredGenomeEntry {
   genome: FlappyTrainerNetwork;
   score: number;

package/test/neat/neat.topology-intent.test.ts

@@ -0,0 +1,129 @@
+import Neat from '../../src/neat';
+import Network from '../../src/architecture/network';
+import * as methods from '../../src/methods/methods';
+
+type FastSlabPredicate = (training: boolean) => boolean;
+
+const getFastSlabPredicate = (network: Network): FastSlabPredicate => {
+  return Reflect.get(network, '_canUseFastSlab') as FastSlabPredicate;
+};
+
+describe('Neat topology intent', () => {
+  it('promotes fresh FFW populations to feed-forward intent', () => {
+    // Arrange
+    const neat = new Neat(2, 1, () => 0, {
+      popsize: 1,
+      mutation: methods.mutation.FFW,
+    });
+
+    // Act
+    const topologyIntent = neat.population[0].getTopologyIntent();
+
+    // Assert
+    expect(topologyIntent).toBe('feed-forward');
+  });
+
+  it('promotes nested FFW mutation wrappers to feed-forward intent', () => {
+    // Arrange
+    const neat = new Neat(2, 1, () => 0, {
+      popsize: 1,
+      mutation: [methods.mutation.FFW],
+    });
+
+    // Act
+    const topologyIntent = neat.population[0].getTopologyIntent();
+
+    // Assert
+    expect(topologyIntent).toBe('feed-forward');
+  });
+
+  it('restores fast slab eligibility for fresh FFW populations after activation prepares topology', () => {
+    // Arrange
+    const neat = new Neat(2, 1, () => 0, {
+      popsize: 1,
+      mutation: methods.mutation.FFW,
+    });
+    const genome = neat.population[0];
+    genome.activate([0, 0]);
+
+    // Act
+    const canUseFastSlab = getFastSlabPredicate(genome).call(genome, false);
+
+    // Assert
+    expect(canUseFastSlab).toBe(true);
+  });
+
+  it('promotes eligible seed networks to feed-forward intent when FFW is configured', () => {
+    // Arrange
+    const seedNetwork = new Network(2, 1);
+    const neat = new Neat(2, 1, () => 0, {
+      popsize: 1,
+      network: seedNetwork,
+      mutation: methods.mutation.FFW,
+    });
+
+    // Act
+    const topologyIntent = neat.population[0].getTopologyIntent();
+
+    // Assert
+    expect(topologyIntent).toBe('feed-forward');
+  });
+
+  it('does not promote recurrent seed networks to feed-forward intent', () => {
+    // Arrange
+    const seedNetwork = new Network(2, 1);
+    const outputNode = seedNetwork.nodes.find((node) => node.type === 'output');
+    if (!outputNode) {
+      throw new Error('Expected an output node for recurrent seed setup');
+    }
+    seedNetwork.connect(outputNode, outputNode, 1);
+    const neat = new Neat(2, 1, () => 0, {
+      popsize: 1,
+      network: seedNetwork,
+      mutation: methods.mutation.FFW,
+    });
+
+    // Act
+    const topologyIntent = neat.population[0].getTopologyIntent();
+
+    // Assert
+    expect(topologyIntent).toBe('unconstrained');
+  });
+
+  it('promotes fresh provenance genomes to feed-forward intent when FFW is configured', async () => {
+    // Arrange
+    const neat = new Neat(2, 1, () => 0, {
+      popsize: 2,
+      provenance: 1,
+      mutation: methods.mutation.FFW,
+    });
+
+    // Act
+    await neat.evolve();
+    const topologyIntent = neat.population[0].getTopologyIntent();
+
+    // Assert
+    expect(topologyIntent).toBe('feed-forward');
+  });
+
+  it('restores fast slab eligibility for fresh provenance genomes after activation prepares topology', async () => {
+    // Arrange
+    const neat = new Neat(2, 1, () => 0, {
+      popsize: 2,
+      provenance: 1,
+      mutation: methods.mutation.FFW,
+    });
+
+    // Act
+    await neat.evolve();
+    const provenanceGenome = neat.population[0];
+    provenanceGenome.activate([0, 0]);
+    const canUseFastSlab = getFastSlabPredicate(provenanceGenome).call(
+      provenanceGenome,
+      false,
+    );
+
+    // Assert
+    expect(canUseFastSlab).toBe(true);
+  });
+});

package/test/network/network.topology-intent.test.ts

@@ -0,0 +1,44 @@
+import { Architect, Network } from '../../src/neataptic';
+
+describe('Network topology intent', () => {
+  it('marks perceptron builders as feed-forward intent', () => {
+    const network = Architect.perceptron(3, 4, 1);
+
+    expect(network.getTopologyIntent()).toBe('feed-forward');
+  });
+
+  it('enables acyclic enforcement for perceptron builders', () => {
+    const network = Architect.perceptron(3, 4, 1);
+
+    expect(Reflect.get(network, '_enforceAcyclic')).toBe(true);
+  });
+
+  it('accepts feed-forward intent through the public constructor', () => {
+    const network = new Network(2, 1, { topologyIntent: 'feed-forward' });
+
+    expect(network.getTopologyIntent()).toBe('feed-forward');
+  });
+
+  it('serializes topology intent in JSON payloads', () => {
+    const network = Architect.perceptron(2, 3, 1);
+    const jsonPayload = network.toJSON() as { topologyIntent?: string };
+
+    expect(jsonPayload.topologyIntent).toBe('feed-forward');
+  });
+
+  it('restores topology intent during JSON deserialization', () => {
+    const network = Architect.perceptron(2, 3, 1);
+    const rebuiltNetwork = Network.fromJSON(
+      network.toJSON() as Record<string, unknown>,
+    );
+
+    expect(rebuiltNetwork.getTopologyIntent()).toBe('feed-forward');
+  });
+
+  it('keeps the legacy acyclic setter aligned with topology intent', () => {
+    const network = new Network(2, 1);
+    network.setEnforceAcyclic(true);
+
+    expect(network.getTopologyIntent()).toBe('feed-forward');
+  });
+});

package/test/examples/flappy_bird/browser-entry/browser-entry.utils.ts

@@ -1,12 +0,0 @@
-export * from './browser-entry.math.utils';
-export * from './browser-entry.host.utils';
-export * from './browser-entry.network-view.utils';
-export * from './browser-entry.observation.utils';
-export * from './browser-entry.playback.utils';
-export * from './browser-entry.spawn.utils';
-export * from './browser-entry.stats.utils';
-export * from './browser-entry.telemetry.utils';
-export * from './browser-entry.text-frame.utils';
-export * from './browser-entry.viewport.utils';
-export * from './browser-entry.visualization.utils';
-export * from './browser-entry.worker-channel.utils';

package/test/examples/flappy_bird/environment/environment.ts

@@ -1,7 +0,0 @@
-/**
- * Environment domain public entry.
- *
- * This compatibility façade re-exports the current environment implementation
- * while `flappyEnvironment.ts` is decomposed into focused environment modules.
- */
-export * from '../flappyEnvironment';

package/test/examples/flappy_bird/evaluation/evaluation.ts

@@ -1,7 +0,0 @@
-/**
- * Evaluation domain public entry.
- *
- * This compatibility façade re-exports the current evaluation implementation
- * while `flappyEvaluation.ts` is decomposed into focused evaluation modules.
- */
-export * from '../flappyEvaluation';

package/test/examples/flappy_bird/simulation-shared/simulation-shared.ts

@@ -1,15 +0,0 @@
-/**
- * Shared simulation public entry.
- *
- * This compatibility façade re-exports shared simulation utilities while
- * `flappy.simulation.shared.utils.ts` is decomposed into focused modules.
- */
-export * from './simulation-shared.constants';
-export * from './simulation-shared.control.utils';
-export * from './simulation-shared.difficulty.utils';
-export * from './simulation-shared.errors';
-export * from './simulation-shared.math.utils';
-export * from './simulation-shared.memory.utils';
-export * from './simulation-shared.observation.utils';
-export * from './simulation-shared.spawn.utils';
-export * from './simulation-shared.types';

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

@@ -1,78 +0,0 @@
-import { clampValue } from '../flappy.simulation.shared.utils';
-
-/**
- * Computes the arithmetic mean of numeric samples.
- *
- * @param values - Numeric samples.
- * @returns Arithmetic mean.
- */
-export function computeMean(values: readonly number[]): number {
-  if (values.length === 0) return 0;
-  return (
-    values.reduce(function accumulate(sumValue, currentValue): number {
-      return sumValue + currentValue;
-    }, 0) / values.length
-  );
-}
-
-/**
- * Computes population standard deviation from numeric samples.
- *
- * @param values - Numeric samples.
- * @param meanValue - Precomputed mean.
- * @returns Population standard deviation.
- */
-export function computePopulationStandardDeviation(
-  values: readonly number[],
-  meanValue: number,
-): number {
-  if (values.length === 0) return 0;
-
-  const variance =
-    values.reduce(function accumulateVariance(sumValue, currentValue): number {
-      const deltaFromMean = currentValue - meanValue;
-      return sumValue + deltaFromMean * deltaFromMean;
-    }, 0) / values.length;
-
-  return Math.sqrt(Math.max(0, variance));
-}
-
-/**
- * Computes an interpolated percentile value.
- *
- * @param values - Numeric samples.
- * @param percentile - Percentile in [0, 1].
- * @returns Interpolated percentile value.
- */
-export function computePercentile(
-  values: readonly number[],
-  percentile: number,
-): number {
-  if (values.length === 0) return Number.NaN;
-
-  const sortedValues = values.toSorted(compareNumbersAscending);
-
-  const clampedPercentile = clampValue(percentile, 0, 1);
-  const percentileIndex = clampedPercentile * (sortedValues.length - 1);
-  const lowerIndex = Math.floor(percentileIndex);
-  const upperIndex = Math.ceil(percentileIndex);
-  const interpolationWeight = percentileIndex - lowerIndex;
-
-  const lowerValue = sortedValues[lowerIndex] ?? sortedValues[0] ?? Number.NaN;
-  const upperValue = sortedValues[upperIndex] ?? lowerValue;
-  return lowerValue + (upperValue - lowerValue) * interpolationWeight;
-}
-
-/**
- * Numeric ascending comparator.
- *
- * @param leftValue - Left numeric value.
- * @param rightValue - Right numeric value.
- * @returns Ascending comparator delta.
- */
-export function compareNumbersAscending(
-  leftValue: number,
-  rightValue: number,
-): number {
-  return leftValue - rightValue;
-}