@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/evaluate/fitness/README.md

@@ -37,6 +37,29 @@ flowchart TD
 
 ## neat/evaluate/fitness/evaluate.fitness.ts
 
+### clearGenomeStateIfRequested
+
+```ts
+clearGenomeStateIfRequested(
+  controller: NeatControllerForEval,
+  evaluationOptions: { [key: string]: unknown; fitnessPopulation?: boolean | undefined; clear?: boolean | undefined; novelty?: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; } | undefined; entropySharingTuning?: { enabled?: boolean | undefined; targetEntropyVar?: number | undefined; adjustRate?: number | undefined; minSigma?: number | undefined; maxSigma?: number | undefined; } | undefined; entropyCompatTuning?: { enabled?: boolean | undefined; targetEntropy?: number | undefined; deadband?: number | undefined; adjustRate?: number | undefined; minThreshold?: number | undefined; maxThreshold?: number | undefined; } | undefined; autoDistanceCoeffTuning?: { enabled?: boolean | undefined; adjustRate?: number | undefined; minCoeff?: number | undefined; maxCoeff?: number | undefined; } | undefined; multiObjective?: { enabled?: boolean | undefined; autoEntropy?: boolean | undefined; dynamic?: { enabled?: boolean | undefined; } | undefined; } | undefined; speciation?: boolean | undefined; targetSpecies?: number | undefined; compatAdjust?: boolean | undefined; speciesAllocation?: { extendedHistory?: boolean | undefined; } | undefined; sharingSigma?: number | undefined; compatibilityThreshold?: number | undefined; excessCoeff?: number | undefined; disjointCoeff?: number | undefined; },
+  clearAction: (genome: GenomeForEvaluation) => void,
+): void
+```
+
+Clear cached genome state before evaluation when configured.
+
+Some evaluators expect each genome to start from a clean runtime state before
+scoring. This helper centralizes that policy so the two scoring modes do not
+each invent their own clearing rule. If clearing is disabled, the helper does
+nothing; if enabled, it applies the caller-provided clear action across the
+current population.
+
+Parameters:
+- `controller` - - NEAT controller instance for evaluation.
+- `evaluationOptions` - - Options object for the current evaluation pass.
+- `clearAction` - - Action that clears a genome's internal state.
+
 ### runFitnessEvaluation
 
 ```ts
@@ -65,26 +88,3 @@ Parameters:
 - `evaluationOptions` - - Options object for the current evaluation pass.
 
 Returns: Promise that resolves after fitness evaluation completes.
-
-### clearGenomeStateIfRequested
-
-```ts
-clearGenomeStateIfRequested(
-  controller: NeatControllerForEval,
-  evaluationOptions: { [key: string]: unknown; fitnessPopulation?: boolean | undefined; clear?: boolean | undefined; novelty?: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; } | undefined; entropySharingTuning?: { enabled?: boolean | undefined; targetEntropyVar?: number | undefined; adjustRate?: number | undefined; minSigma?: number | undefined; maxSigma?: number | undefined; } | undefined; entropyCompatTuning?: { enabled?: boolean | undefined; targetEntropy?: number | undefined; deadband?: number | undefined; adjustRate?: number | undefined; minThreshold?: number | undefined; maxThreshold?: number | undefined; } | undefined; autoDistanceCoeffTuning?: { enabled?: boolean | undefined; adjustRate?: number | undefined; minCoeff?: number | undefined; maxCoeff?: number | undefined; } | undefined; multiObjective?: { enabled?: boolean | undefined; autoEntropy?: boolean | undefined; dynamic?: { enabled?: boolean | undefined; } | undefined; } | undefined; speciation?: boolean | undefined; targetSpecies?: number | undefined; compatAdjust?: boolean | undefined; speciesAllocation?: { extendedHistory?: boolean | undefined; } | undefined; sharingSigma?: number | undefined; compatibilityThreshold?: number | undefined; excessCoeff?: number | undefined; disjointCoeff?: number | undefined; },
-  clearAction: (genome: GenomeForEvaluation) => void,
-): void
-```
-
-Clear cached genome state before evaluation when configured.
-
-Some evaluators expect each genome to start from a clean runtime state before
-scoring. This helper centralizes that policy so the two scoring modes do not
-each invent their own clearing rule. If clearing is disabled, the helper does
-nothing; if enabled, it applies the caller-provided clear action across the
-current population.
-
-Parameters:
-- `controller` - - NEAT controller instance for evaluation.
-- `evaluationOptions` - - Options object for the current evaluation pass.
-- `clearAction` - - Action that clears a genome's internal state.

package/src/neat/evaluate/novelty/README.md

@@ -49,77 +49,97 @@ flowchart TD
 
 ## neat/evaluate/novelty/evaluate.novelty.ts
 
-### runNoveltyBlendAndArchive
+### addGenomeToNoveltyArchive
 
 ```ts
-runNoveltyBlendAndArchive(
+addGenomeToNoveltyArchive(
   controller: NeatControllerForEval,
-  evaluationOptions: { [key: string]: unknown; fitnessPopulation?: boolean | undefined; clear?: boolean | undefined; novelty?: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; } | undefined; entropySharingTuning?: { enabled?: boolean | undefined; targetEntropyVar?: number | undefined; adjustRate?: number | undefined; minSigma?: number | undefined; maxSigma?: number | undefined; } | undefined; entropyCompatTuning?: { enabled?: boolean | undefined; targetEntropy?: number | undefined; deadband?: number | undefined; adjustRate?: number | undefined; minThreshold?: number | undefined; maxThreshold?: number | undefined; } | undefined; autoDistanceCoeffTuning?: { enabled?: boolean | undefined; adjustRate?: number | undefined; minCoeff?: number | undefined; maxCoeff?: number | undefined; } | undefined; multiObjective?: { enabled?: boolean | undefined; autoEntropy?: boolean | undefined; dynamic?: { enabled?: boolean | undefined; } | undefined; } | undefined; speciation?: boolean | undefined; targetSpecies?: number | undefined; compatAdjust?: boolean | undefined; speciesAllocation?: { extendedHistory?: boolean | undefined; } | undefined; sharingSigma?: number | undefined; compatibilityThreshold?: number | undefined; excessCoeff?: number | undefined; disjointCoeff?: number | undefined; },
+  descriptor: number[],
+  novelty: number,
+  noveltyOptions: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; },
 ): void
 ```
 
-Compute novelty, blend it into scores, and update the novelty archive.
-
-This is the controller-facing entrypoint for the novelty stage. It behaves
-like best-effort evidence enrichment after the core fitness path has run.
-If novelty is disabled or misconfigured, evaluation can safely continue with
-the base score evidence alone.
+Add a descriptor to the novelty archive when it exceeds the threshold.
 
-The helper preserves several important controller assumptions:
-- the current population order is left intact,
-- current species membership is left intact,
-- no objective-registration policy is changed here,
-- only novelty evidence, optional score blending, and archive state are
-  updated.
+The archive is intentionally bounded and selective. Threshold-based admission
+keeps it focused on descriptors that are genuinely unusual enough to be worth
+remembering, while the cap prevents novelty exploration from turning into an
+unbounded memory sink.
 
 Parameters:
 - `controller` - - NEAT controller instance for evaluation.
-- `evaluationOptions` - - Options object for the current evaluation pass.
+- `descriptor` - - Behavior descriptor for the current genome.
+- `novelty` - - Computed novelty score.
+- `noveltyOptions` - - Novelty configuration.
 
-Example:
+### applyNoveltyToPopulation
 
 ```ts
-runNoveltyBlendAndArchive(controller, controller.options);
-console.log(controller.population[0]?._novelty);
+applyNoveltyToPopulation(
+  controller: NeatControllerForEval,
+  descriptors: number[][],
+  distanceMatrix: number[][],
+  kNeighbors: number,
+  blendFactor: number,
+  noveltyOptions: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; },
+): void
 ```
 
-### getNoveltyNeighborCount
+Apply novelty scores and archive writes across the population.
+
+This helper is the fold stage of the novelty pipeline. It translates the
+descriptor-distance evidence into per-genome novelty annotations, then
+optionally blends that evidence into numeric scores and records sufficiently
+novel descriptors for future exploration pressure.
+
+Parameters:
+- `controller` - - NEAT controller instance for evaluation.
+- `descriptors` - - Descriptor vectors for each genome.
+- `distanceMatrix` - - Dense distance matrix.
+- `kNeighbors` - - Number of nearest neighbors to average.
+- `blendFactor` - - Novelty-vs-fitness blend factor.
+- `noveltyOptions` - - Novelty configuration.
+
+### blendNoveltyIntoScore
 
 ```ts
-getNoveltyNeighborCount(
-  noveltyOptions: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; },
-): number
+blendNoveltyIntoScore(
+  genome: GenomeForEvaluation,
+  novelty: number,
+  blendFactor: number,
+): void
 ```
 
-Resolve the number of nearest neighbors used for novelty scoring.
+Blend novelty into the genome score when the score already exists.
 
-Smaller neighbor counts make novelty more sensitive to local behavioral
-differences, while larger counts smooth that signal across a wider portion of
-the current population.
+This stage intentionally does not invent a base score when one is missing.
+Novelty acts as a companion signal to the existing evaluation path, not as a
+universal replacement for every scoring mode.
 
 Parameters:
-- `noveltyOptions` - - Novelty configuration.
-
-Returns: Neighbor count clamped to at least one.
+- `genome` - - Genome to update.
+- `novelty` - - Computed novelty value.
+- `blendFactor` - - Blend factor for novelty versus fitness.
 
-### getNoveltyBlendFactor
+### buildDistanceMatrix
 
 ```ts
-getNoveltyBlendFactor(
-  noveltyOptions: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; },
-): number
+buildDistanceMatrix(
+  descriptors: number[][],
+): number[][]
 ```
 
-Resolve the novelty-vs-fitness blend factor.
+Build the full pairwise distance matrix for the descriptor set.
 
-A factor of `0` keeps the existing fitness score unchanged. A factor of `1`
-makes novelty fully replace it when a numeric score exists. Values in between
-turn novelty into a partial exploratory bonus instead of a hard override.
+The matrix is dense and population-order aligned so later helpers can keep
+the scoring flow simple: each genome reads one row, drops its self-distance,
+and averages the nearest neighbors.
 
 Parameters:
-- `noveltyOptions` - - Novelty configuration.
+- `descriptors` - - Descriptor vectors for the current population.
 
-Returns: Blend factor used when a genome already has a numeric score.
+Returns: Dense distance matrix aligned with population order.
 
 ### buildNoveltyDescriptors
 
@@ -143,52 +163,29 @@ Parameters:
 
 Returns: Descriptor vectors aligned with population order.
 
-### buildDistanceMatrix
+### computeDescriptorDistance
 
 ```ts
-buildDistanceMatrix(
-  descriptors: number[][],
-): number[][]
+computeDescriptorDistance(
+  leftDescriptor: number[],
+  rightDescriptor: number[],
+  isSame: boolean,
+): number
 ```
 
-Build the full pairwise distance matrix for the descriptor set.
+Compute the Euclidean distance between two descriptors.
 
-The matrix is dense and population-order aligned so later helpers can keep
-the scoring flow simple: each genome reads one row, drops its self-distance,
-and averages the nearest neighbors.
+Distance is computed across the shared descriptor prefix so callers can keep
+using practical descriptor functions even when they occasionally emit vectors
+of uneven length. Self-distance is fixed at zero to keep later neighbor
+ranking deterministic.
 
 Parameters:
-- `descriptors` - - Descriptor vectors for the current population.
-
-Returns: Dense distance matrix aligned with population order.
-
-### applyNoveltyToPopulation
-
-```ts
-applyNoveltyToPopulation(
-  controller: NeatControllerForEval,
-  descriptors: number[][],
-  distanceMatrix: number[][],
-  kNeighbors: number,
-  blendFactor: number,
-  noveltyOptions: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; },
-): void
-```
-
-Apply novelty scores and archive writes across the population.
-
-This helper is the fold stage of the novelty pipeline. It translates the
-descriptor-distance evidence into per-genome novelty annotations, then
-optionally blends that evidence into numeric scores and records sufficiently
-novel descriptors for future exploration pressure.
+- `leftDescriptor` - - Left descriptor vector.
+- `rightDescriptor` - - Right descriptor vector.
+- `isSame` - - Whether both descriptors belong to the same genome index.
 
-Parameters:
-- `controller` - - NEAT controller instance for evaluation.
-- `descriptors` - - Descriptor vectors for each genome.
-- `distanceMatrix` - - Dense distance matrix.
-- `kNeighbors` - - Number of nearest neighbors to average.
-- `blendFactor` - - Novelty-vs-fitness blend factor.
-- `noveltyOptions` - - Novelty configuration.
+Returns: Euclidean distance across the shared prefix.
 
 ### computeNoveltyScore
 
@@ -211,71 +208,74 @@ Parameters:
 
 Returns: Novelty score for the genome.
 
-### blendNoveltyIntoScore
+### getNoveltyBlendFactor
 
 ```ts
-blendNoveltyIntoScore(
-  genome: GenomeForEvaluation,
-  novelty: number,
-  blendFactor: number,
-): void
+getNoveltyBlendFactor(
+  noveltyOptions: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; },
+): number
 ```
 
-Blend novelty into the genome score when the score already exists.
+Resolve the novelty-vs-fitness blend factor.
 
-This stage intentionally does not invent a base score when one is missing.
-Novelty acts as a companion signal to the existing evaluation path, not as a
-universal replacement for every scoring mode.
+A factor of `0` keeps the existing fitness score unchanged. A factor of `1`
+makes novelty fully replace it when a numeric score exists. Values in between
+turn novelty into a partial exploratory bonus instead of a hard override.
 
 Parameters:
-- `genome` - - Genome to update.
-- `novelty` - - Computed novelty value.
-- `blendFactor` - - Blend factor for novelty versus fitness.
+- `noveltyOptions` - - Novelty configuration.
 
-### addGenomeToNoveltyArchive
+Returns: Blend factor used when a genome already has a numeric score.
+
+### getNoveltyNeighborCount
 
 ```ts
-addGenomeToNoveltyArchive(
-  controller: NeatControllerForEval,
-  descriptor: number[],
-  novelty: number,
+getNoveltyNeighborCount(
   noveltyOptions: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; },
-): void
+): number
 ```
 
-Add a descriptor to the novelty archive when it exceeds the threshold.
+Resolve the number of nearest neighbors used for novelty scoring.
 
-The archive is intentionally bounded and selective. Threshold-based admission
-keeps it focused on descriptors that are genuinely unusual enough to be worth
-remembering, while the cap prevents novelty exploration from turning into an
-unbounded memory sink.
+Smaller neighbor counts make novelty more sensitive to local behavioral
+differences, while larger counts smooth that signal across a wider portion of
+the current population.
 
 Parameters:
-- `controller` - - NEAT controller instance for evaluation.
-- `descriptor` - - Behavior descriptor for the current genome.
-- `novelty` - - Computed novelty score.
 - `noveltyOptions` - - Novelty configuration.
 
-### computeDescriptorDistance
+Returns: Neighbor count clamped to at least one.
+
+### runNoveltyBlendAndArchive
 
 ```ts
-computeDescriptorDistance(
-  leftDescriptor: number[],
-  rightDescriptor: number[],
-  isSame: boolean,
-): number
+runNoveltyBlendAndArchive(
+  controller: NeatControllerForEval,
+  evaluationOptions: { [key: string]: unknown; fitnessPopulation?: boolean | undefined; clear?: boolean | undefined; novelty?: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; } | undefined; entropySharingTuning?: { enabled?: boolean | undefined; targetEntropyVar?: number | undefined; adjustRate?: number | undefined; minSigma?: number | undefined; maxSigma?: number | undefined; } | undefined; entropyCompatTuning?: { enabled?: boolean | undefined; targetEntropy?: number | undefined; deadband?: number | undefined; adjustRate?: number | undefined; minThreshold?: number | undefined; maxThreshold?: number | undefined; } | undefined; autoDistanceCoeffTuning?: { enabled?: boolean | undefined; adjustRate?: number | undefined; minCoeff?: number | undefined; maxCoeff?: number | undefined; } | undefined; multiObjective?: { enabled?: boolean | undefined; autoEntropy?: boolean | undefined; dynamic?: { enabled?: boolean | undefined; } | undefined; } | undefined; speciation?: boolean | undefined; targetSpecies?: number | undefined; compatAdjust?: boolean | undefined; speciesAllocation?: { extendedHistory?: boolean | undefined; } | undefined; sharingSigma?: number | undefined; compatibilityThreshold?: number | undefined; excessCoeff?: number | undefined; disjointCoeff?: number | undefined; },
+): void
 ```
 
-Compute the Euclidean distance between two descriptors.
+Compute novelty, blend it into scores, and update the novelty archive.
 
-Distance is computed across the shared descriptor prefix so callers can keep
-using practical descriptor functions even when they occasionally emit vectors
-of uneven length. Self-distance is fixed at zero to keep later neighbor
-ranking deterministic.
+This is the controller-facing entrypoint for the novelty stage. It behaves
+like best-effort evidence enrichment after the core fitness path has run.
+If novelty is disabled or misconfigured, evaluation can safely continue with
+the base score evidence alone.
+
+The helper preserves several important controller assumptions:
+- the current population order is left intact,
+- current species membership is left intact,
+- no objective-registration policy is changed here,
+- only novelty evidence, optional score blending, and archive state are
+  updated.
 
 Parameters:
-- `leftDescriptor` - - Left descriptor vector.
-- `rightDescriptor` - - Right descriptor vector.
-- `isSame` - - Whether both descriptors belong to the same genome index.
+- `controller` - - NEAT controller instance for evaluation.
+- `evaluationOptions` - - Options object for the current evaluation pass.
 
-Returns: Euclidean distance across the shared prefix.
+Example:
+
+```ts
+runNoveltyBlendAndArchive(controller, controller.options);
+console.log(controller.population[0]?._novelty);
+```

package/src/neat/evaluate/objectives/README.md

@@ -43,6 +43,23 @@ flowchart TD
 
 ## neat/evaluate/objectives/evaluate.objectives.ts
 
+### registerEntropyObjective
+
+```ts
+registerEntropyObjective(
+  controller: NeatControllerForEval,
+): void
+```
+
+Register the entropy objective and invalidate the cached objective list.
+
+Registering the objective is only half of the job. The cached objective list
+must also be invalidated so later ranking stages resolve the updated
+objective set instead of continuing to use stale ordering information.
+
+Parameters:
+- `controller` - - NEAT controller instance for evaluation.
+
 ### runAutoEntropyObjectiveInjection
 
 ```ts
@@ -93,20 +110,3 @@ Parameters:
 - `evaluationOptions` - - Options object for the current evaluation pass.
 
 Returns: True when entropy should be injected.
-
-### registerEntropyObjective
-
-```ts
-registerEntropyObjective(
-  controller: NeatControllerForEval,
-): void
-```
-
-Register the entropy objective and invalidate the cached objective list.
-
-Registering the objective is only half of the job. The cached objective list
-must also be invalidated so later ranking stages resolve the updated
-objective set instead of continuing to use stale ordering information.
-
-Parameters:
-- `controller` - - NEAT controller instance for evaluation.