@reicek/neataptic-ts 0.1.26 → 0.1.27

package/src/architecture/network/gating/network.gating.utils.ts

@@ -1,3 +1,46 @@
+/**
+ * Connection-gating utilities and gate-aware repair helpers for network edits.
+ *
+ * Gating is the lightweight way to let one node decide how strongly another
+ * connection should matter right now. That makes this chapter about more than
+ * a simple `gate()` setter. It also owns the awkward structural case where a
+ * hidden node is removed and the network tries to preserve useful gated
+ * behavior by reconnecting predecessor and successor nodes, then reassigning
+ * preserved gaters onto the new bridge connections.
+ *
+ * The split inside this folder follows those two jobs. `gate.utils` keeps
+ * ordinary gate and ungate bookkeeping small and predictable. `remove.utils`
+ * handles the more invasive bridge-repair flow used during gate-aware hidden
+ * node removal. The shared types file only carries temporary collections used
+ * during that repair work; it is not the right chapter intro.
+ *
+ * ```mermaid
+ * flowchart LR
+ *   Gater[Gater node activation] --> Modulate[Modulate connection gain]
+ *   Modulate --> Target[Target node input sum]
+ *   Remove[Remove hidden node] --> Bridge[Create bridge connections]
+ *   Bridge --> Preserve[Reassign preserved gaters]
+ * ```
+ *
+ * A useful mental model is that gating changes when a connection is
+ * influential, while bridge repair tries to preserve where information can
+ * still travel after topology surgery. Keeping both concerns together makes
+ * the public surface easier to learn because callers usually encounter them in
+ * the same network-editing workflows.
+ *
+ * Example: attach a hidden node as a gater for one connection.
+ *
+ * ```ts
+ * network.gate(hiddenNode, connection);
+ * ```
+ *
+ * Example: later remove that modulation and return the connection to static
+ * weighting.
+ *
+ * ```ts
+ * network.ungate(connection);
+ * ```
+ */
 import type Network from '../../network/network';
 import Node from '../../node';
 import Connection from '../../connection';

package/src/architecture/network/genetic/README.md

@@ -1,52 +1,59 @@
 # architecture/network/genetic
 
-Canonical threshold used for random binary parent/gene choice.
-
-## architecture/network/genetic/network.genetic.utils.types.ts
-
-### DEFAULT_REENABLE_PROBABILITY
-
-Default probability for re-enabling disabled genes during crossover.
-
-### FIRST_INDEX
-
-First element index used when reading newly created connections.
+Network-level crossover boundary for recombining two compatible parent
+graphs into one offspring.
+
+This chapter is the genetic shelf of `architecture/network/`: the place
+where structure is inherited rather than mutated from scratch. It answers a
+practical question that shows up during neuroevolution and testing alike: if
+two networks already expose the same input and output contract, how should a
+child network mix their node and connection genes without losing a runnable
+topology?
+
+The helpers below split that answer into setup, selection, and
+materialization. Setup decides how large the offspring can be and which
+parent has inheritance priority. Selection chooses overlapping and disjoint
+genes. Materialization turns the chosen genes back into a concrete `Network`
+instance and restores gating when the chosen gater still exists. That keeps
+the public `crossOver()` surface compact while the README can still teach the
+full inheritance flow.
+
+```mermaid
+flowchart LR
+  ParentA[Parent A] --> Context[Build crossover context]
+  ParentB[Parent B] --> Context
+  Context --> Nodes[Assign offspring nodes]
+  Nodes --> Genes[Choose connection genes]
+  Genes --> Offspring[Materialize offspring network]
+```
 
-### NO_GATER_INDEX
+This is inspired by NEAT-style crossover, but it stays intentionally
+pragmatic. Innovation identity is derived from endpoint indices, node
+alignment depends on current ordering, and the goal is a predictable,
+inspectable operator for this repo's runtime rather than a full historical
+innovation tracker.
 
-Sentinel index representing that no gater node is assigned.
+For compact background reading on the wider idea, see Wikipedia
+contributors,
+[Crossover (genetic algorithm)](https://en.wikipedia.org/wiki/Crossover_(genetic_algorithm)).
+The implementation here specializes that idea to graph-shaped neural
+networks with gating and disabled genes.
 
-### PARENT_COMPATIBILITY_ERROR_MESSAGE
+Example: create one offspring using ordinary fitness-biased inheritance.
 
-Shared compatibility error message for crossover parent validation.
-
-### RANDOM_BINARY_SELECTION_THRESHOLD
-
-Canonical threshold used for random binary parent/gene choice.
+```ts
+const child = crossOver(parentA, parentB);
+```
 
-### RandomGenerator
+Example: force symmetric inheritance when you want experimentation rather
+than fitter-parent bias.
 
 ```ts
-RandomGenerator(): number
+const exploratoryChild = crossOver(parentA, parentB, true);
 ```
 
-Shared random generator signature for genetic operators.
-
 ## architecture/network/genetic/network.genetic.utils.ts
 
-Genetic operator: NEAT‑style crossover (legacy merge operator removed).
-
-This module now focuses solely on producing recombinant offspring via {@link crossOver}.
-The previous experimental `Network.merge` flow has been removed to reduce maintenance
-surface area and avoid implying a misleading sequential-composition guarantee.
-
-Design notes:
-- The implementation favors deterministic, inspectable orchestration at the top level.
-- Gene-selection details are delegated to setup/materialization helpers so the public
-  crossover API stays compact and predictable.
-- The resulting offspring preserves the same input/output interface as both parents,
-  which keeps downstream evaluation and training pipelines compatible.
-
 ### crossOver
 
 ```ts
@@ -1004,3 +1011,35 @@ Parameters:
 - `traversalContext` - - Traversal context.
 
 Returns: Endpoint context or undefined.
+
+## architecture/network/genetic/network.genetic.utils.types.ts
+
+Canonical threshold used for random binary parent/gene choice.
+
+### DEFAULT_REENABLE_PROBABILITY
+
+Default probability for re-enabling disabled genes during crossover.
+
+### FIRST_INDEX
+
+First element index used when reading newly created connections.
+
+### NO_GATER_INDEX
+
+Sentinel index representing that no gater node is assigned.
+
+### PARENT_COMPATIBILITY_ERROR_MESSAGE
+
+Shared compatibility error message for crossover parent validation.
+
+### RANDOM_BINARY_SELECTION_THRESHOLD
+
+Canonical threshold used for random binary parent/gene choice.
+
+### RandomGenerator
+
+```ts
+RandomGenerator(): number
+```
+
+Shared random generator signature for genetic operators.

package/src/architecture/network/genetic/docs.order.json

@@ -0,0 +1,10 @@
+{
+  "introFile": "network.genetic.utils.ts",
+  "fileOrder": [
+    "network.genetic.utils.ts",
+    "network.genetic.setup.utils.ts",
+    "network.genetic.selection.utils.ts",
+    "network.genetic.materialize.utils.ts",
+    "network.genetic.utils.types.ts"
+  ]
+}

package/src/architecture/network/genetic/network.genetic.utils.ts

@@ -1,3 +1,56 @@
+/**
+ * Network-level crossover boundary for recombining two compatible parent
+ * graphs into one offspring.
+ *
+ * This chapter is the genetic shelf of `architecture/network/`: the place
+ * where structure is inherited rather than mutated from scratch. It answers a
+ * practical question that shows up during neuroevolution and testing alike: if
+ * two networks already expose the same input and output contract, how should a
+ * child network mix their node and connection genes without losing a runnable
+ * topology?
+ *
+ * The helpers below split that answer into setup, selection, and
+ * materialization. Setup decides how large the offspring can be and which
+ * parent has inheritance priority. Selection chooses overlapping and disjoint
+ * genes. Materialization turns the chosen genes back into a concrete `Network`
+ * instance and restores gating when the chosen gater still exists. That keeps
+ * the public `crossOver()` surface compact while the README can still teach the
+ * full inheritance flow.
+ *
+ * ```mermaid
+ * flowchart LR
+ *   ParentA[Parent A] --> Context[Build crossover context]
+ *   ParentB[Parent B] --> Context
+ *   Context --> Nodes[Assign offspring nodes]
+ *   Nodes --> Genes[Choose connection genes]
+ *   Genes --> Offspring[Materialize offspring network]
+ * ```
+ *
+ * This is inspired by NEAT-style crossover, but it stays intentionally
+ * pragmatic. Innovation identity is derived from endpoint indices, node
+ * alignment depends on current ordering, and the goal is a predictable,
+ * inspectable operator for this repo's runtime rather than a full historical
+ * innovation tracker.
+ *
+ * For compact background reading on the wider idea, see Wikipedia
+ * contributors,
+ * [Crossover (genetic algorithm)](https://en.wikipedia.org/wiki/Crossover_(genetic_algorithm)).
+ * The implementation here specializes that idea to graph-shaped neural
+ * networks with gating and disabled genes.
+ *
+ * Example: create one offspring using ordinary fitness-biased inheritance.
+ *
+ * ```ts
+ * const child = crossOver(parentA, parentB);
+ * ```
+ *
+ * Example: force symmetric inheritance when you want experimentation rather
+ * than fitter-parent bias.
+ *
+ * ```ts
+ * const exploratoryChild = crossOver(parentA, parentB, true);
+ * ```
+ */
 import type Network from '../../network/network';
 import { materializeOffspringConnections } from './network.genetic.materialize.utils';
 import {
@@ -7,23 +60,6 @@ import {
   createNodeBuildContext,
 } from './network.genetic.setup.utils';
 
-/**
- * Genetic operator: NEAT‑style crossover (legacy merge operator removed).
- *
- * This module now focuses solely on producing recombinant offspring via {@link crossOver}.
- * The previous experimental `Network.merge` flow has been removed to reduce maintenance
- * surface area and avoid implying a misleading sequential-composition guarantee.
- *
- * Design notes:
- * - The implementation favors deterministic, inspectable orchestration at the top level.
- * - Gene-selection details are delegated to setup/materialization helpers so the public
- *   crossover API stays compact and predictable.
- * - The resulting offspring preserves the same input/output interface as both parents,
- *   which keeps downstream evaluation and training pipelines compatible.
- *
- * @module network.genetic
- */
-
 /**
  * NEAT-inspired crossover between two parent networks producing a single offspring.
  *

package/src/architecture/network/network.ts

@@ -1,20 +1,91 @@
 /**
  * Core network chapter for the architecture surface.
  *
- * This folder now owns the public `Network` class that readers and callers use
- * to build, activate, evolve, serialize, and export graph-shaped neural
- * systems. The surrounding helper chapters keep activation, training,
- * topology, pruning, ONNX, and slab execution policy focused, while this file
- * preserves the orchestration story that ties those responsibilities into one
- * runtime boundary.
+ * This folder owns the public `Network` class: the boundary where a graph stops
+ * being only nodes and connections and starts behaving like one runnable,
+ * mutable, trainable system. Higher-level NEAT code can mutate or score a
+ * network, but this chapter is where the graph itself learns how to activate,
+ * accept structural edits, preserve deterministic state, serialize, and cross
+ * the ONNX boundary.
  *
- * Read this chapter in three passes:
+ * That boundary matters because the same instance has to serve several jobs
+ * without changing shape. A caller may want ordinary inference, training-aware
+ * forward passes, topology edits, reproducible stochastic behavior, sparse
+ * pruning, or a portable checkpoint. Keeping those responsibilities under one
+ * facade makes the public API readable while the helper chapters keep each
+ * policy cluster narrow enough to teach.
  *
- * 1. start here to understand the public `Network` contract and why it sits
- *    above nodes, layers, and connections,
- * 2. continue into the helper chapters when you want one subsystem in detail,
- * 3. return here when you need to see how the public API composes those
- *    subsystem policies back into one runtime object.
+ * A useful mental model is to read `network/` as four cooperating shelves.
+ * `bootstrap/` explains one-time construction policy. `activate/`, `runtime/`,
+ * and `training/` explain how a graph is stepped and regularized once it is
+ * alive. `connect/`, `mutate/`, `remove/`, `prune/`, and `topology/` explain
+ * graph surgery. `serialize/`, `standalone/`, `onnx/`, and `stats/` explain
+ * portability, inspection, and reporting.
+ *
+ * The performance story is equally important. This chapter deliberately hides
+ * storage details until they matter. Callers should be able to ask for
+ * `activate()` or `train()` without first understanding slab packing, pooled
+ * activation arrays, or cache invalidation. The helper folders then expose how
+ * the same graph can switch between object traversal and denser typed-array
+ * paths without changing the surface contract.
+ *
+ * ```mermaid
+ * flowchart LR
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Build[bootstrap and topology intent]:::base --> NetworkClass[Network facade]:::accent
+ *   NetworkClass --> Execute[activate runtime and training]:::base
+ *   Execute --> Edit[connect mutate prune remove]:::base
+ *   Edit --> Persist[serialize standalone and ONNX]:::base
+ * ```
+ *
+ * ```mermaid
+ * flowchart TD
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   NetworkChapter[network chapter]:::accent --> Bootstrap[bootstrap/ one-time setup]:::base
+ *   NetworkChapter --> Activate[activate/ forward-pass policy]:::base
+ *   NetworkChapter --> Runtime[runtime/ training-time controls]:::base
+ *   NetworkChapter --> Structure[connect mutate topology prune]:::base
+ *   NetworkChapter --> Interop[serialize standalone onnx stats]:::base
+ * ```
+ *
+ * For background on the execution-order side of this chapter, see Wikipedia
+ * contributors, [Topological sorting](https://en.wikipedia.org/wiki/Topological_sorting).
+ * Feed-forward network execution, acyclic guards, and some of the helper
+ * policies in this folder all depend on the same scheduling idea even when the
+ * public API keeps that detail out of the caller's way.
+ *
+ * Example: create a compact layered network and use the ordinary activation
+ * surface.
+ *
+ * ```ts
+ * const network = Network.createMLP(2, [4], 1);
+ * const outputValues = network.activate([0, 1]);
+ * ```
+ *
+ * Example: checkpoint one network, then restore it for another run.
+ *
+ * ```ts
+ * const network = new Network(2, 1, { seed: 7 });
+ * const saved = network.toJSON();
+ * const restored = Network.fromJSON(saved);
+ * const replayed = restored.activate([1, 0]);
+ * ```
+ *
+ * Practical reading order:
+ *
+ * 1. Start here for the public `Network` facade and the cross-chapter map.
+ * 2. Continue into `bootstrap/` when the constructor contract is the next
+ *    question.
+ * 3. Continue into `activate/`, `runtime/`, and `training/` for execution and
+ *    learning policy.
+ * 4. Continue into `connect/`, `mutate/`, `remove/`, `prune/`, and `topology/`
+ *    for structural editing.
+ * 5. Finish in `serialize/`, `standalone/`, `onnx/`, and `stats/` for
+ *    portability, derived reports, and export flows.
  */
 
 import Node from '../node/node';
@@ -114,42 +185,16 @@ import type {
 } from './network.types';
 
 /**
- * Network (Evolvable / Trainable Graph)
- * =====================================
- * Represents a directed neural computation graph used both as a NEAT genome
- * phenotype and (optionally) as a gradientΓÇætrainable model. The class binds
- * together specialized modules (topology, pruning, serialization, slab packing)
- * to keep the core surface approachable for learners.
- *
- * Educational Highlights:
- *  - Structural Mutation: functions like `addNodeBetween()` and evolutionary
- *    helpers (in higher-level `Neat`) mutate topology to explore architectures.
- *  - Fast Execution Paths: a StructureΓÇæofΓÇæArrays (SoA) slab (`rebuildConnectionSlab`)
- *    packs connection data into typed arrays to improve cache locality.
- *  - Memory Optimization: node pooling & typed array pooling demonstrate how
- *    allocation patterns affect performance and GC pressure.
- *  - Determinism: RNG snapshot/restore methods allow reproducible experiments.
- *  - Hybrid Workflows: dropout, stochastic depth, weight noise and mixed precision
- *    illustrate gradientΓÇæera regularization applied to evolved topologies.
- *
- * Typical Usage:
- * ```ts
- * const net = new Network(4, 2);           // create network
- * const out = net.activate([0.1,0.3,0.2,0.9]);
- * net.addNodeBetween();                    // structural mutation
- * const slab = net.getConnectionSlab(); // inspect packed arrays
- * const clone = net.clone();               // deep copy
- * ```
+ * Public graph runtime that combines execution, editing, and portability.
  *
- * Performance Guidance:
- *  - Invoke `activate()` normally; the class autoΓÇæselects slab vs object path.
- *  - Batch structural mutations then call `rebuildConnectionSlab(true)` if you
- *    need an immediate fastΓÇæpath (it is invoked lazily otherwise).
- *  - Keep input array length exactly equal to `input`; mismatches throw early.
+ * `Network` is the instance callers reach for when one directed graph should be
+ * activated immediately, mutated structurally, regularized during training, or
+ * shipped across a checkpoint or export boundary without changing types.
  *
- * Serialization:
- *  - `toJSON()` / `fromJSON()` support experiment checkpointing.
- *  - ONNX export (`exportToONNX`) enables interoperability with other tools.
+ * Read the class as an orchestration facade over the helper chapters in this
+ * folder. The public methods stay on the instance so older imports and examples
+ * remain stable, while the heavier activation, topology, deterministic, and
+ * interoperability policies live in narrower modules below this surface.
  */
 import type { NetworkView } from '../../utils/memory';