@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -17,22 +17,9 @@ Notes:
 
 ## architecture/network/training/network.training.utils.types.ts
 
-### resolveEmaAlpha
-
-```ts
-resolveEmaAlpha(
-  smoothingWindow: number,
-  explicitAlpha: number | undefined,
-): number
-```
-
-Resolve default EMA alpha using a window length.
-
-Parameters:
-- `smoothingWindow` - - Window length for moving average operations.
-- `explicitAlpha` - - Optional user-provided alpha override.
+### ALLOWED_OPTIMIZERS
 
-Returns: A valid EMA alpha in the range (0, 1].
+Set of supported optimizer identifiers accepted by training options.
 
 ### buildMonitoredSmoothingConfig
 
@@ -55,14 +42,6 @@ Parameters:
 
 Returns: Normalized monitored smoothing configuration.
 
-### NetworkNode
-
-Local node shape alias used by training utility modules.
-
-### RegularizationArgument
-
-Regularization argument accepted by node-level propagation.
-
 ### CostDerivative
 
 ```ts
@@ -74,6 +53,14 @@ CostDerivative(
 
 Cost-derivative callback shape for output-node backpropagation.
 
+### GradientClipRuntimeConfig
+
+Runtime gradient clipping configuration normalized from training options.
+
+### NetworkNode
+
+Local node shape alias used by training utility modules.
+
 ### OutputNodeWithCostDerivative
 
 Extended output-node contract that supports custom cost derivatives.
@@ -82,19 +69,41 @@ Extended output-node contract that supports custom cost derivatives.
 
 Shared immutable context for network propagation helpers.
 
+### RegularizationArgument
+
+Regularization argument accepted by node-level propagation.
+
+### resolveEmaAlpha
+
+```ts
+resolveEmaAlpha(
+  smoothingWindow: number,
+  explicitAlpha: number | undefined,
+): number
+```
+
+Resolve default EMA alpha using a window length.
+
+Parameters:
+- `smoothingWindow` - - Window length for moving average operations.
+- `explicitAlpha` - - Optional user-provided alpha override.
+
+Returns: A valid EMA alpha in the range (0, 1].
+
 ### TrainingSample
 
 Training sample consumed by training set loops.
 
-### GradientClipRuntimeConfig
+## architecture/network/training/network.training.utils.ts
 
-Runtime gradient clipping configuration normalized from training options.
+### __trainingInternals
 
-### ALLOWED_OPTIMIZERS
+Test-only internal helper bundle.
 
-Set of supported optimizer identifiers accepted by training options.
+This is exported so unit tests can cover edge-cases in the smoothing logic without
+running full end-to-end training loops.
 
-## architecture/network/training/network.training.utils.ts
+Important: this is **not** considered stable public API. It may change between releases.
 
 ### applyGradientClippingImpl
 
@@ -113,91 +122,12 @@ Parameters:
 - `net` - - Network instance to update.
 - `cfg` - - Normalized clipping settings.
 
-### trainSetImpl
-
-```ts
-trainSetImpl(
-  net: default,
-  set: TrainingSample[],
-  batchSize: number,
-  accumulationSteps: number,
-  currentRate: number,
-  momentum: number,
-  regularization: RegularizationConfig,
-  costFunction: CostFunction | CostFunctionOrObject,
-  optimizer: OptimizerConfigBase | undefined,
-): number
-```
-
-Execute one full pass over dataset (epoch) with optional accumulation & adaptive optimizer.
-Returns mean cost across processed samples.
-
-This is the core "one epoch" primitive used by higher-level training orchestration.
-
-Parameters:
-- `net` - - Network instance receiving training updates.
-- `set` - - Training samples.
-- `batchSize` - - Mini-batch size (use 1 for pure SGD).
-- `accumulationSteps` - - Micro-batch accumulation steps.
-- `currentRate` - - Current learning rate (may be scheduled by caller).
-- `momentum` - - Momentum used by some optimizers (when applicable).
-- `regularization` - - Regularization configuration passed down to nodes.
-- `costFunction` - - Cost function selector (function or compatible object).
-- `optimizer` - - Optional optimizer configuration.
-
-Returns: Mean cost across the processed samples.
-
-### trainImpl
-
-```ts
-trainImpl(
-  net: default,
-  set: TrainingSample[],
-  options: TrainingOptions,
-): { error: number; iterations: number; time: number; }
-```
-
-High-level training orchestration with early stopping, smoothing & callbacks.
-
-This is the main entrypoint used by `Network.train(...)`-style APIs.
-
-Parameters:
-- `net` - - Network instance to train.
-- `set` - - Training dataset.
-- `options` - - Training options (stopping conditions, optimizer, hooks, etc.).
-
-Returns: Summary payload containing final error, iteration count, and elapsed time.
-
-Example:
-
-```ts
-const result = net.train(set, { iterations: 500, rate: 0.3 });
-console.log(result.error);
-```
-
-### propagate
-
-```ts
-propagate(
-  rate: number,
-  momentum: number,
-  update: boolean,
-  target: number[],
-  regularization: number,
-  costDerivative: CostDerivative | undefined,
-): void
-```
+### CheckpointConfig
 
-Propagate output and hidden errors backward through the network.
+Checkpoint callback configuration.
 
-Parameters:
-- `this` - Bound network instance.
-- `rate` - Learning rate.
-- `momentum` - Momentum factor.
-- `update` - Whether to apply updates immediately.
-- `target` - Output target values.
-- `regularization` - L2 regularization factor.
-- `costDerivative` - Optional output-node derivative override.
+Training can periodically call `save(...)` with a serialized network snapshot.
+You can persist these snapshots to disk, upload them, or keep them in-memory.
 
 ### clearState
 
@@ -210,13 +140,6 @@ Clear all node runtime traces and states.
 Parameters:
 - `this` - Bound network instance.
 
-### CheckpointConfig
-
-Checkpoint callback configuration.
-
-Training can periodically call `save(...)` with a serialized network snapshot.
-You can persist these snapshots to disk, upload them, or keep them in-memory.
-
 ### CostFunction
 
 ```ts
@@ -316,6 +239,30 @@ Notes:
 - Exact supported `type` values are validated by training utilities.
 - Unspecified fields fall back to sensible defaults per optimizer.
 
+### propagate
+
+```ts
+propagate(
+  rate: number,
+  momentum: number,
+  update: boolean,
+  target: number[],
+  regularization: number,
+  costDerivative: CostDerivative | undefined,
+): void
+```
+
+Propagate output and hidden errors backward through the network.
+
+Parameters:
+- `this` - Bound network instance.
+- `rate` - Learning rate.
+- `momentum` - Momentum factor.
+- `update` - Whether to apply updates immediately.
+- `target` - Output target values.
+- `regularization` - L2 regularization factor.
+- `costDerivative` - Optional output-node derivative override.
+
 ### ScheduleConfig
 
 Schedule callback configuration.
@@ -330,6 +277,34 @@ Serialized network payload used in checkpoint callbacks.
 This is intentionally loose: serialization formats evolve and may include nested
 structures. Treat this as an opaque snapshot blob.
 
+### trainImpl
+
+```ts
+trainImpl(
+  net: default,
+  set: TrainingSample[],
+  options: TrainingOptions,
+): { error: number; iterations: number; time: number; }
+```
+
+High-level training orchestration with early stopping, smoothing & callbacks.
+
+This is the main entrypoint used by `Network.train(...)`-style APIs.
+
+Parameters:
+- `net` - - Network instance to train.
+- `set` - - Training dataset.
+- `options` - - Training options (stopping conditions, optimizer, hooks, etc.).
+
+Returns: Summary payload containing final error, iteration count, and elapsed time.
+
+Example:
+
+```ts
+const result = net.train(set, { iterations: 500, rate: 0.3 });
+console.log(result.error);
+```
+
 ### TrainingOptions
 
 Public training options accepted by the high-level training orchestration.
@@ -355,14 +330,39 @@ Stopping conditions:
 - Provide at least one of `iterations` or `error`.
 - `earlyStopPatience` adds an additional "stop when no improvement" guard.
 
-### __trainingInternals
+### trainSetImpl
 
-Test-only internal helper bundle.
+```ts
+trainSetImpl(
+  net: default,
+  set: TrainingSample[],
+  batchSize: number,
+  accumulationSteps: number,
+  currentRate: number,
+  momentum: number,
+  regularization: RegularizationConfig,
+  costFunction: CostFunction | CostFunctionOrObject,
+  optimizer: OptimizerConfigBase | undefined,
+): number
+```
 
-This is exported so unit tests can cover edge-cases in the smoothing logic without
-running full end-to-end training loops.
+Execute one full pass over dataset (epoch) with optional accumulation & adaptive optimizer.
+Returns mean cost across processed samples.
 
-Important: this is **not** considered stable public API. It may change between releases.
+This is the core "one epoch" primitive used by higher-level training orchestration.
+
+Parameters:
+- `net` - - Network instance receiving training updates.
+- `set` - - Training samples.
+- `batchSize` - - Mini-batch size (use 1 for pure SGD).
+- `accumulationSteps` - - Micro-batch accumulation steps.
+- `currentRate` - - Current learning rate (may be scheduled by caller).
+- `momentum` - - Momentum used by some optimizers (when applicable).
+- `regularization` - - Regularization configuration passed down to nodes.
+- `costFunction` - - Cost function selector (function or compatible object).
+- `optimizer` - - Optional optimizer configuration.
+
+Returns: Mean cost across the processed samples.
 
 ## architecture/network/training/network.training.loop.utils.ts
 
@@ -399,29 +399,18 @@ Returns: Mean cost over processed samples.
 
 ## architecture/network/training/network.training.backprop.utils.ts
 
-### propagate
+### clearNodeState
 
 ```ts
-propagate(
-  rate: number,
-  momentum: number,
-  update: boolean,
-  target: number[],
-  regularization: number,
-  costDerivative: CostDerivative | undefined,
+clearNodeState(
+  node: default,
 ): void
 ```
 
-Propagate output and hidden errors backward through the network.
+Clear runtime state for a single node.
 
 Parameters:
-- `this` - Bound network instance.
-- `rate` - Learning rate.
-- `momentum` - Momentum factor.
-- `update` - Whether to apply updates immediately.
-- `target` - Output target values.
-- `regularization` - L2 regularization factor.
-- `costDerivative` - Optional output-node derivative override.
+- `node` - Node to clear.
 
 ### clearState
 
@@ -434,21 +423,6 @@ Clear all node runtime traces and states.
 Parameters:
 - `this` - Bound network instance.
 
-### validateTargetLength
-
-```ts
-validateTargetLength(
-  network: default,
-  target: number[],
-): void
-```
-
-Validate that target output count matches the network output width.
-
-Parameters:
-- `network` - Network instance receiving backpropagation.
-- `target` - Output target vector.
-
 ### createPropagationContext
 
 ```ts
@@ -474,65 +448,87 @@ Parameters:
 
 Returns: Immutable context consumed by propagation helpers.
 
-### propagateOutputLayer
+### getLastNodeIndex
 
 ```ts
-propagateOutputLayer(
-  context: PropagationContext,
-  target: number[],
-): void
+getLastNodeIndex(
+  network: default,
+): number
 ```
 
-Propagate all output nodes with explicit targets.
+Resolve the last node index in the network.
 
 Parameters:
-- `context` - Shared propagation context.
-- `target` - Output target vector.
+- `network` - Network instance.
 
-### propagateHiddenLayer
+Returns: Last valid node index.
+
+### getOutputLayerStartIndex
 
 ```ts
-propagateHiddenLayer(
-  context: PropagationContext,
+getOutputLayerStartIndex(
+  network: default,
+): number
+```
+
+Resolve the first index of the output layer.
+
+Parameters:
+- `network` - Network instance.
+
+Returns: Index at which output nodes begin.
+
+### propagate
+
+```ts
+propagate(
+  rate: number,
+  momentum: number,
+  update: boolean,
+  target: number[],
+  regularization: number,
+  costDerivative: CostDerivative | undefined,
 ): void
 ```
 
-Propagate all hidden nodes in reverse topological order.
+Propagate output and hidden errors backward through the network.
 
 Parameters:
-- `context` - Shared propagation context.
+- `this` - Bound network instance.
+- `rate` - Learning rate.
+- `momentum` - Momentum factor.
+- `update` - Whether to apply updates immediately.
+- `target` - Output target values.
+- `regularization` - L2 regularization factor.
+- `costDerivative` - Optional output-node derivative override.
 
-### propagateSingleOutputNode
+### propagateHiddenLayer
 
 ```ts
-propagateSingleOutputNode(
+propagateHiddenLayer(
   context: PropagationContext,
-  node: default,
-  targetValue: number,
 ): void
 ```
 
-Propagate a single output node with a target value.
+Propagate all hidden nodes in reverse topological order.
 
 Parameters:
 - `context` - Shared propagation context.
-- `node` - Output node to propagate.
-- `targetValue` - Expected output value for this node.
 
-### propagateSingleHiddenNode
+### propagateOutputLayer
 
 ```ts
-propagateSingleHiddenNode(
+propagateOutputLayer(
   context: PropagationContext,
-  node: default,
+  target: number[],
 ): void
 ```
 
-Propagate a single hidden node without a target value.
+Propagate all output nodes with explicit targets.
 
 Parameters:
 - `context` - Shared propagation context.
-- `node` - Hidden node to propagate.
+- `target` - Output target vector.
 
 ### propagateOutputNodeWithCostDerivative
 
@@ -553,48 +549,52 @@ Parameters:
 - `targetValue` - Expected output value for this node.
 - `costDerivative` - Cost derivative callback.
 
-### getOutputLayerStartIndex
+### propagateSingleHiddenNode
 
 ```ts
-getOutputLayerStartIndex(
-  network: default,
-): number
+propagateSingleHiddenNode(
+  context: PropagationContext,
+  node: default,
+): void
 ```
 
-Resolve the first index of the output layer.
+Propagate a single hidden node without a target value.
 
 Parameters:
-- `network` - Network instance.
-
-Returns: Index at which output nodes begin.
+- `context` - Shared propagation context.
+- `node` - Hidden node to propagate.
 
-### getLastNodeIndex
+### propagateSingleOutputNode
 
 ```ts
-getLastNodeIndex(
-  network: default,
-): number
+propagateSingleOutputNode(
+  context: PropagationContext,
+  node: default,
+  targetValue: number,
+): void
 ```
 
-Resolve the last node index in the network.
+Propagate a single output node with a target value.
 
 Parameters:
-- `network` - Network instance.
-
-Returns: Last valid node index.
+- `context` - Shared propagation context.
+- `node` - Output node to propagate.
+- `targetValue` - Expected output value for this node.
 
-### clearNodeState
+### validateTargetLength
 
 ```ts
-clearNodeState(
-  node: default,
+validateTargetLength(
+  network: default,
+  target: number[],
 ): void
 ```
 
-Clear runtime state for a single node.
+Validate that target output count matches the network output width.
 
 Parameters:
-- `node` - Node to clear.
+- `network` - Network instance receiving backpropagation.
+- `target` - Output target vector.
 
 ## architecture/network/training/network.training.finalize.utils.ts
 

package/src/architecture/node/README.md

@@ -18,11 +18,6 @@ Read this chapter in three passes:
 
 ## architecture/node/node.ts
 
-### NodeOptimizerProps
-
-Internal interface for accessing dynamic optimizer properties on Node instances.
-These properties are lazily allocated and not part of the main class definition.
-
 ### Node
 
 Node (Neuron)
@@ -38,6 +33,11 @@ Educational note: Traces (`eligibility` and `xtrace`) illustrate how recurrent c
 assignment works in algorithms like RTRL / policy gradients. They are updated only when
 using the traced activation path (`activate`) vs `noTraceActivate` (inference fast path).
 
+### NodeOptimizerProps
+
+Internal interface for accessing dynamic optimizer properties on Node instances.
+These properties are lazily allocated and not part of the main class definition.
+
 ### default
 
 #### _activateCore

package/src/architecture/nodePool/README.md

@@ -16,10 +16,6 @@ Read this chapter in three passes:
 
 ## architecture/nodePool/nodePool.ts
 
-### AcquireNodeOptions
-
-Options bag for acquiring a node.
-
 ### acquireNode
 
 ```ts
@@ -39,6 +35,20 @@ Parameters:
 
 Returns: A ready-to-use node instance.
 
+### AcquireNodeOptions
+
+Options bag for acquiring a node.
+
+### nodePoolStats
+
+```ts
+nodePoolStats(): { size: number; highWaterMark: number; reused: number; fresh: number; recycledRatio: number; }
+```
+
+Get current pool statistics for diagnostics and memory reporting.
+
+Returns: Pool size, reuse counters, and the long-run recycled ratio.
+
 ### releaseNode
 
 ```ts
@@ -57,16 +67,6 @@ Parameters:
 
 Returns: Nothing.
 
-### nodePoolStats
-
-```ts
-nodePoolStats(): { size: number; highWaterMark: number; reused: number; fresh: number; recycledRatio: number; }
-```
-
-Get current pool statistics for diagnostics and memory reporting.
-
-Returns: Pool size, reuse counters, and the long-run recycled ratio.
-
 ### resetNodePool
 
 ```ts