@reicek/neataptic-ts 0.1.24 → 0.1.26

package/src/neat/multiobjective/metrics/README.md

@@ -48,6 +48,49 @@ annotations.
 
 Returns: Compact metrics aligned with the current population order.
 
+### DEFAULT_MAX_PARETO_FRONTS
+
+Default number of Pareto fronts returned by accessors.
+
+Read helpers stay deliberately bounded by default so inspection callers get a
+useful frontier summary without accidentally materializing every tail front.
+
+### DEFAULT_PARETO_ARCHIVE_JSONL_MAX
+
+Default slice size when exporting Pareto archive as JSONL.
+
+Export uses a slightly larger default window than in-memory reads so offline
+tooling can inspect a broader recent history without requiring the full
+archive.
+
+### DEFAULT_PARETO_ARCHIVE_MAX_ENTRIES
+
+Default slice size when reading Pareto archive entries.
+
+This favors recent history, which is usually the most relevant window for
+telemetry panels or interactive inspection.
+
+### exportParetoArchiveJsonl
+
+```ts
+exportParetoArchiveJsonl(
+  archive: unknown[],
+  maxEntries: number,
+): string
+```
+
+Export a Pareto archive slice as JSON Lines.
+
+JSONL keeps each archived snapshot on its own line, which makes the output
+easy to stream, diff, or feed into external tooling without inventing another
+archive-specific export format.
+
+Parameters:
+- `archive` - - Archive collection ordered from oldest to newest.
+- `maxEntries` - - Maximum number of recent entries to export.
+
+Returns: Newline-delimited JSON for the selected archive window.
+
 ### reconstructParetoFronts
 
 ```ts
@@ -95,46 +138,3 @@ Parameters:
 - `maxEntries` - - Maximum number of recent entries to keep.
 
 Returns: A trailing slice containing at most `maxEntries` items.
-
-### exportParetoArchiveJsonl
-
-```ts
-exportParetoArchiveJsonl(
-  archive: unknown[],
-  maxEntries: number,
-): string
-```
-
-Export a Pareto archive slice as JSON Lines.
-
-JSONL keeps each archived snapshot on its own line, which makes the output
-easy to stream, diff, or feed into external tooling without inventing another
-archive-specific export format.
-
-Parameters:
-- `archive` - - Archive collection ordered from oldest to newest.
-- `maxEntries` - - Maximum number of recent entries to export.
-
-Returns: Newline-delimited JSON for the selected archive window.
-
-### DEFAULT_MAX_PARETO_FRONTS
-
-Default number of Pareto fronts returned by accessors.
-
-Read helpers stay deliberately bounded by default so inspection callers get a
-useful frontier summary without accidentally materializing every tail front.
-
-### DEFAULT_PARETO_ARCHIVE_MAX_ENTRIES
-
-Default slice size when reading Pareto archive entries.
-
-This favors recent history, which is usually the most relevant window for
-telemetry panels or interactive inspection.
-
-### DEFAULT_PARETO_ARCHIVE_JSONL_MAX
-
-Default slice size when exporting Pareto archive as JSONL.
-
-Export uses a slightly larger default window than in-memory reads so offline
-tooling can inspect a broader recent history without requiring the full
-archive.

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

@@ -33,37 +33,6 @@ flowchart TD
 
 ## neat/multiobjective/objectives/multiobjective.objectives.ts
 
-### readObjectiveValue
-
-```ts
-readObjectiveValue(
-  genomeItem: default,
-  descriptor: ObjectiveDescriptor,
-): number
-```
-
-Safely reads a single objective value for a given genome.
-
-This wraps the descriptor `accessor` in a `try/catch` so that a buggy
-objective function cannot crash multi-objective ranking.
-
-Notes:
-- If the accessor throws, this returns `0` (a neutral-ish fallback).
-- Callers should prefer to surface accessor errors during development;
-  this helper is intentionally defensive for long-running training loops.
-
-Parameters:
-- `genomeItem` - - Genome to evaluate.
-- `descriptor` - - Objective descriptor providing an accessor.
-
-Returns: Numeric objective value; `0` if the accessor throws.
-
-Example:
-
-```ts
-const score = readObjectiveValue(genome, { accessor: (g) => g.score ?? 0 });
-```
-
 ### buildGenomeValues
 
 ```ts
@@ -111,3 +80,34 @@ Parameters:
 - `descriptors` - - Objective descriptors (column schema).
 
 Returns: Objective values matrix.
+
+### readObjectiveValue
+
+```ts
+readObjectiveValue(
+  genomeItem: default,
+  descriptor: ObjectiveDescriptor,
+): number
+```
+
+Safely reads a single objective value for a given genome.
+
+This wraps the descriptor `accessor` in a `try/catch` so that a buggy
+objective function cannot crash multi-objective ranking.
+
+Notes:
+- If the accessor throws, this returns `0` (a neutral-ish fallback).
+- Callers should prefer to surface accessor errors during development;
+  this helper is intentionally defensive for long-running training loops.
+
+Parameters:
+- `genomeItem` - - Genome to evaluate.
+- `descriptor` - - Objective descriptor providing an accessor.
+
+Returns: Numeric objective value; `0` if the accessor throws.
+
+Example:
+
+```ts
+const score = readObjectiveValue(genome, { accessor: (g) => g.score ?? 0 });
+```

package/src/neat/multiobjective/shared/README.md

@@ -25,6 +25,33 @@ still run, but they would be reasoning about the wrong objectives or genomes.
 
 ## neat/multiobjective/shared/multiobjective.types.ts
 
+### NeatLikeWithMultiObjective
+
+Minimal Neat-like interface required by the multi-objective helpers.
+
+This host contract stays intentionally small so the multi-objective helpers
+can be reused without depending on the entire `Neat` controller surface.
+The boundary owns only two kinds of state:
+- objective-schema access for the start of the ranking pass,
+- optional Pareto-archive state for the end of the ranking pass.
+
+Everything else stays outside this interface on purpose. `objectives/`,
+`dominance/`, `fronts/`, and `crowding/` operate on prepared vectors,
+bookkeeping structures, and annotated genomes rather than reaching back into
+controller internals mid-pass.
+
+### NetworkWithMOAnnotations
+
+Extends a genome/network with multi-objective annotations.
+
+These properties are transient ranking metadata. They are attached after the
+multi-objective helpers compute fronts and crowding distances, then consumed
+by later selection or inspection code as a compact summary of where a genome
+landed on the current Pareto surface.
+
+Treat these fields as derived evidence, not durable genome state. A later
+ranking pass is free to recompute or overwrite them.
+
 ### ObjectiveDescriptor
 
 Describes how to evaluate one objective for one genome.
@@ -56,30 +83,3 @@ const objectives: ObjectiveDescriptor[] = [
   { accessor: (genome) => genome.cost ?? 0, direction: 'min' },
 ];
 ```
-
-### NeatLikeWithMultiObjective
-
-Minimal Neat-like interface required by the multi-objective helpers.
-
-This host contract stays intentionally small so the multi-objective helpers
-can be reused without depending on the entire `Neat` controller surface.
-The boundary owns only two kinds of state:
-- objective-schema access for the start of the ranking pass,
-- optional Pareto-archive state for the end of the ranking pass.
-
-Everything else stays outside this interface on purpose. `objectives/`,
-`dominance/`, `fronts/`, and `crowding/` operate on prepared vectors,
-bookkeeping structures, and annotated genomes rather than reaching back into
-controller internals mid-pass.
-
-### NetworkWithMOAnnotations
-
-Extends a genome/network with multi-objective annotations.
-
-These properties are transient ranking metadata. They are attached after the
-multi-objective helpers compute fronts and crowding distances, then consumed
-by later selection or inspection code as a compact summary of where a genome
-landed on the current Pareto surface.
-
-Treat these fields as derived evidence, not durable genome state. A later
-ranking pass is free to recompute or overwrite them.

package/src/neat/mutation/README.md

@@ -55,6 +55,76 @@ flowchart TD
 
 ## neat/mutation/mutation.ts
 
+### DEFAULT_CONNECTION_WEIGHT
+
+Default connection weight used when mutation must create a structural edge from scratch.
+
+This keeps bootstrap connections and split in-edges deterministic at the
+mutation boundary before later weight mutations or evaluation passes tune the
+value more precisely.
+
+### DEFAULT_GENE_ID
+
+Default gene id used when mutation needs a stable fallback for node metadata.
+
+The value is intentionally simple because it acts as compatibility padding,
+not as a semantic innovation marker.
+
+### DEFAULT_INNOVATION_ID
+
+Default innovation id used when a connection lacks recorded innovation metadata.
+
+This fallback prevents root mutation helpers from depending on missing ids
+while the real innovation-tracking paths decide whether to reuse or allocate
+new structural records.
+
+### ensureMinHiddenNodes
+
+```ts
+ensureMinHiddenNodes(
+  network: GenomeWithMetadata,
+  multiplierOverride: number | undefined,
+): Promise<void>
+```
+
+Ensure the network has a minimum number of hidden nodes and connectivity.
+
+This repair helper runs after structural edits when the controller wants to
+keep a mutated genome above a minimum hidden-capacity floor. It is less about
+exploration than about preserving a usable topology budget so later mutation,
+evaluation, and selection steps do not inherit a trivially underbuilt graph.
+
+The helper may add hidden nodes, wire missing edges, and rebuild cached
+connection structures, so callers should treat it as a topology-maintenance
+pass rather than a tiny invariant check.
+
+Parameters:
+- `network` - Genome whose hidden-node budget and connectivity should be repaired.
+- `multiplierOverride` - Optional override for the configured hidden-node multiplier.
+
+Returns: Promise that resolves after hidden-node and connectivity repairs have completed.
+
+### ensureNoDeadEnds
+
+```ts
+ensureNoDeadEnds(
+  network: GenomeWithMetadata,
+): void
+```
+
+Ensure there are no dead-end nodes (input/output isolation) in the network.
+
+Mutation can produce temporarily awkward graphs, especially after structural
+growth or pruning-like simplification. This repair pass reconnects stranded
+input, output, or hidden nodes so the genome remains a sensible candidate for
+later evaluation and does not carry obviously broken topology into the next
+controller stage.
+
+Parameters:
+- `network` - Genome whose endpoint and hidden-node connectivity should be repaired.
+
+Returns: Nothing. The network may gain repair connections in place.
+
 ### mutate
 
 ```ts
@@ -94,48 +164,6 @@ Example:
 neat.mutate();
 ```
 
-### mutateAddNodeReuse
-
-```ts
-mutateAddNodeReuse(
-  genome: GenomeWithMetadata,
-): Promise<void>
-```
-
-Split a randomly chosen enabled connection and insert a hidden node.
-
-This routine attempts to reuse a historical "node split" innovation record
-so that identical splits across different genomes share the same
-innovation ids. This preservation of innovation information is important
-for NEAT-style speciation and genome alignment.
-
-Use this helper when the controller wants a structural growth mutation that
-stays compatible with prior history. The important state change is not only
-the new hidden node inside one genome, but also the possible update to the
-controller's split-innovation table when this exact split has never been seen
-before.
-
-Method steps (high-level):
-- If the genome has no connections, connect an input to an output to
-  bootstrap connectivity.
-- Filter enabled connections and choose one at random.
-- Disconnect the chosen connection and either reuse an existing split
-  innovation record or create a new hidden node + two connecting
-  connections (in->new, new->out) assigning new innovation ids.
-- Insert the newly created node into the genome's node list at the
-  deterministic position to preserve ordering for downstream algorithms.
-
-Parameters:
-- `genome` - Genome to modify in place.
-
-Returns: Promise that resolves after the split has either reused an existing innovation record or created a new one.
-
-Example:
-
-```ts
-neat._mutateAddNodeReuse(genome);
-```
-
 ### mutateAddConnReuse
 
 ```ts
@@ -176,53 +204,48 @@ Parameters:
 
 Returns: Nothing. The genome may gain one new connection and the controller innovation map may be consulted or extended.
 
-### ensureMinHiddenNodes
+### mutateAddNodeReuse
 
 ```ts
-ensureMinHiddenNodes(
-  network: GenomeWithMetadata,
-  multiplierOverride: number | undefined,
+mutateAddNodeReuse(
+  genome: GenomeWithMetadata,
 ): Promise<void>
 ```
 
-Ensure the network has a minimum number of hidden nodes and connectivity.
+Split a randomly chosen enabled connection and insert a hidden node.
 
-This repair helper runs after structural edits when the controller wants to
-keep a mutated genome above a minimum hidden-capacity floor. It is less about
-exploration than about preserving a usable topology budget so later mutation,
-evaluation, and selection steps do not inherit a trivially underbuilt graph.
+This routine attempts to reuse a historical "node split" innovation record
+so that identical splits across different genomes share the same
+innovation ids. This preservation of innovation information is important
+for NEAT-style speciation and genome alignment.
 
-The helper may add hidden nodes, wire missing edges, and rebuild cached
-connection structures, so callers should treat it as a topology-maintenance
-pass rather than a tiny invariant check.
+Use this helper when the controller wants a structural growth mutation that
+stays compatible with prior history. The important state change is not only
+the new hidden node inside one genome, but also the possible update to the
+controller's split-innovation table when this exact split has never been seen
+before.
+
+Method steps (high-level):
+- If the genome has no connections, connect an input to an output to
+  bootstrap connectivity.
+- Filter enabled connections and choose one at random.
+- Disconnect the chosen connection and either reuse an existing split
+  innovation record or create a new hidden node + two connecting
+  connections (in->new, new->out) assigning new innovation ids.
+- Insert the newly created node into the genome's node list at the
+  deterministic position to preserve ordering for downstream algorithms.
 
 Parameters:
-- `network` - Genome whose hidden-node budget and connectivity should be repaired.
-- `multiplierOverride` - Optional override for the configured hidden-node multiplier.
+- `genome` - Genome to modify in place.
 
-Returns: Promise that resolves after hidden-node and connectivity repairs have completed.
+Returns: Promise that resolves after the split has either reused an existing innovation record or created a new one.
 
-### ensureNoDeadEnds
+Example:
 
 ```ts
-ensureNoDeadEnds(
-  network: GenomeWithMetadata,
-): void
+neat._mutateAddNodeReuse(genome);
 ```
 
-Ensure there are no dead-end nodes (input/output isolation) in the network.
-
-Mutation can produce temporarily awkward graphs, especially after structural
-growth or pruning-like simplification. This repair pass reconnects stranded
-input, output, or hidden nodes so the genome remains a sensible candidate for
-later evaluation and does not carry obviously broken topology into the next
-controller stage.
-
-Parameters:
-- `network` - Genome whose endpoint and hidden-node connectivity should be repaired.
-
-Returns: Nothing. The network may gain repair connections in place.
-
 ### selectMutationMethod
 
 ```ts
@@ -257,26 +280,3 @@ const method = await neat.selectMutationMethod(genome, false);
 // The result already reflects policy gates such as phased complexity and
 // structural limits, not just a random sample from the raw configured pool.
 ```
-
-### DEFAULT_CONNECTION_WEIGHT
-
-Default connection weight used when mutation must create a structural edge from scratch.
-
-This keeps bootstrap connections and split in-edges deterministic at the
-mutation boundary before later weight mutations or evaluation passes tune the
-value more precisely.
-
-### DEFAULT_GENE_ID
-
-Default gene id used when mutation needs a stable fallback for node metadata.
-
-The value is intentionally simple because it acts as compatibility padding,
-not as a semantic innovation marker.
-
-### DEFAULT_INNOVATION_ID
-
-Default innovation id used when a connection lacks recorded innovation metadata.
-
-This fallback prevents root mutation helpers from depending on missing ids
-while the real innovation-tracking paths decide whether to reuse or allocate
-new structural records.