@reicek/neataptic-ts 0.1.24 → 0.1.26

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

@@ -34,43 +34,53 @@ SNIP heuristic:
 
 ## architecture/network/prune/network.prune.utils.types.ts
 
-### PRUNING_METHOD_MAGNITUDE
+### ActivePruningConfig
 
-Pruning method identifier for absolute-weight ranking.
+Non-nullable pruning schedule configuration shape used by helpers.
 
-### PRUNING_METHOD_SNIP
+### DEFAULT_PRUNE_FREQUENCY
 
-Pruning method identifier for SNIP-like saliency ranking.
+Fallback prune cadence when schedule frequency is omitted or invalid.
 
-### MIN_REMAINING_CONNECTION_COUNT
+### MAX_EVOLUTIONARY_TARGET_SPARSITY
 
-Lower bound to ensure at least one connection remains after pruning.
+Safety cap below full sparsity to avoid degenerate zero-connection networks.
 
-### DEFAULT_PRUNE_FREQUENCY
+### MAX_PROGRESS_FRACTION
 
-Fallback prune cadence when schedule frequency is omitted or invalid.
+Maximum normalized schedule progress value.
 
 ### MIN_PROGRESS_FRACTION
 
 Minimum normalized schedule progress value.
 
-### MAX_PROGRESS_FRACTION
+### MIN_REMAINING_CONNECTION_COUNT
 
-Maximum normalized schedule progress value.
+Lower bound to ensure at least one connection remains after pruning.
 
-### MAX_EVOLUTIONARY_TARGET_SPARSITY
+### PRUNING_METHOD_MAGNITUDE
 
-Safety cap below full sparsity to avoid degenerate zero-connection networks.
+Pruning method identifier for absolute-weight ranking.
+
+### PRUNING_METHOD_SNIP
+
+Pruning method identifier for SNIP-like saliency ranking.
 
 ### REGROW_ATTEMPT_MULTIPLIER
 
 Retry multiplier to convert intended regrowth count into max attempts.
 
-### ActivePruningConfig
+## architecture/network/prune/network.prune.utils.ts
 
-Non-nullable pruning schedule configuration shape used by helpers.
+### getCurrentSparsity
 
-## architecture/network/prune/network.prune.utils.ts
+```ts
+getCurrentSparsity(): number
+```
+
+Current sparsity fraction relative to the training-time pruning baseline.
+
+Returns: Current sparsity in the [0,1] range when baseline is available.
 
 ### maybePrune
 
@@ -107,34 +117,22 @@ Parameters:
 
 Returns: Nothing.
 
-### getCurrentSparsity
-
-```ts
-getCurrentSparsity(): number
-```
-
-Current sparsity fraction relative to the training-time pruning baseline.
-
-Returns: Current sparsity in the [0,1] range when baseline is available.
-
 ## architecture/network/prune/network.prune.regrowth.utils.ts
 
-### maybeRunRegrowth
+### buildRegrowthCandidatePair
 
 ```ts
-maybeRunRegrowth(
+buildRegrowthCandidatePair(
   currentNetwork: default,
-  context: RegrowthPlanContext,
-): void
+): { sourceNode: default; targetNode: default; } | null
 ```
 
-Build and execute a regrowth plan when enabled.
+Build one random regrowth candidate pair if valid.
 
 Parameters:
-- `currentNetwork` - - Network to regrow.
-- `context` - - Inputs describing regrowth intent.
+- `currentNetwork` - - Network being regrown.
 
-Returns: Nothing.
+Returns: Candidate node pair or null when invalid.
 
 ### buildRegrowthPlan
 
@@ -151,6 +149,25 @@ Parameters:
 
 Returns: A plan when regrowth is meaningful; otherwise null.
 
+### connectionAlreadyExists
+
+```ts
+connectionAlreadyExists(
+  currentNetwork: default,
+  sourceNode: default,
+  targetNode: default,
+): boolean
+```
+
+Check whether a connection already exists.
+
+Parameters:
+- `currentNetwork` - - Network being regrown.
+- `sourceNode` - - Proposed source node.
+- `targetNode` - - Proposed target node.
+
+Returns: True when the edge already exists.
+
 ### executeRegrowthAttempts
 
 ```ts
@@ -166,57 +183,42 @@ Parameters:
 
 Returns: Nothing.
 
-### shouldContinueRegrowth
+### isInvalidRegrowthPair
 
 ```ts
-shouldContinueRegrowth(
+isInvalidRegrowthPair(
   currentNetwork: default,
-  desiredRemainingConnections: number,
-  attemptedRegrowthCount: number,
-  maxAttempts: number,
+  sourceNode: default,
+  targetNode: default,
 ): boolean
 ```
 
-Decide whether another regrowth attempt is allowed.
+Validate whether a candidate regrowth pair is acceptable.
 
 Parameters:
 - `currentNetwork` - - Network being regrown.
-- `desiredRemainingConnections` - - Target remaining connection count.
-- `attemptedRegrowthCount` - - Number of attempts already used.
-- `maxAttempts` - - Maximum attempts allowed.
+- `sourceNode` - - Proposed source node.
+- `targetNode` - - Proposed target node.
 
-Returns: True when another attempt should run.
+Returns: True when the pair must be rejected.
 
-### tryRegrowConnection
+### maybeRunRegrowth
 
 ```ts
-tryRegrowConnection(
+maybeRunRegrowth(
   currentNetwork: default,
+  context: RegrowthPlanContext,
 ): void
 ```
 
-Attempt one random valid connection addition.
+Build and execute a regrowth plan when enabled.
 
 Parameters:
-- `currentNetwork` - - Network being regrown.
+- `currentNetwork` - - Network to regrow.
+- `context` - - Inputs describing regrowth intent.
 
 Returns: Nothing.
 
-### buildRegrowthCandidatePair
-
-```ts
-buildRegrowthCandidatePair(
-  currentNetwork: default,
-): { sourceNode: default; targetNode: default; } | null
-```
-
-Build one random regrowth candidate pair if valid.
-
-Parameters:
-- `currentNetwork` - - Network being regrown.
-
-Returns: Candidate node pair or null when invalid.
-
 ### pickRandomNode
 
 ```ts
@@ -232,43 +234,41 @@ Parameters:
 
 Returns: Random node or undefined when the node list is empty.
 
-### isInvalidRegrowthPair
+### shouldContinueRegrowth
 
 ```ts
-isInvalidRegrowthPair(
+shouldContinueRegrowth(
   currentNetwork: default,
-  sourceNode: default,
-  targetNode: default,
+  desiredRemainingConnections: number,
+  attemptedRegrowthCount: number,
+  maxAttempts: number,
 ): boolean
 ```
 
-Validate whether a candidate regrowth pair is acceptable.
+Decide whether another regrowth attempt is allowed.
 
 Parameters:
 - `currentNetwork` - - Network being regrown.
-- `sourceNode` - - Proposed source node.
-- `targetNode` - - Proposed target node.
+- `desiredRemainingConnections` - - Target remaining connection count.
+- `attemptedRegrowthCount` - - Number of attempts already used.
+- `maxAttempts` - - Maximum attempts allowed.
 
-Returns: True when the pair must be rejected.
+Returns: True when another attempt should run.
 
-### connectionAlreadyExists
+### tryRegrowConnection
 
 ```ts
-connectionAlreadyExists(
+tryRegrowConnection(
   currentNetwork: default,
-  sourceNode: default,
-  targetNode: default,
-): boolean
+): void
 ```
 
-Check whether a connection already exists.
+Attempt one random valid connection addition.
 
 Parameters:
 - `currentNetwork` - - Network being regrown.
-- `sourceNode` - - Proposed source node.
-- `targetNode` - - Proposed target node.
 
-Returns: True when the edge already exists.
+Returns: Nothing.
 
 ### violatesAcyclicConstraint
 
@@ -291,52 +291,37 @@ Returns: True when acyclic ordering would be violated.
 
 ## architecture/network/prune/network.prune.schedule.utils.ts
 
-### getPruningConfig
-
-```ts
-getPruningConfig(
-  currentNetwork: default,
-): { start: number; end: number; frequency: number; targetSparsity: number; method: PruningMethod; regrowFraction: number; lastPruneIter?: number | undefined; } | undefined
-```
-
-Read the active pruning schedule from network internals.
-
-Parameters:
-- `currentNetwork` - - Network instance to inspect.
-
-Returns: Pruning configuration when enabled; otherwise undefined.
-
-### shouldRunScheduledPrune
+### alreadyPrunedThisIteration
 
 ```ts
-shouldRunScheduledPrune(
+alreadyPrunedThisIteration(
   currentIteration: number,
   currentPruningConfig: { start: number; end: number; frequency: number; targetSparsity: number; method: PruningMethod; regrowFraction: number; lastPruneIter?: number | undefined; },
 ): boolean
 ```
 
-Determine whether scheduled pruning should run at this iteration.
+Check whether this iteration was already pruned.
 
 Parameters:
-- `currentIteration` - - Training iteration being processed.
+- `currentIteration` - - Iteration to evaluate.
 - `currentPruningConfig` - - Active pruning schedule.
 
-Returns: True when pruning should execute now.
+Returns: True when pruning already happened for this iteration.
 
-### getInitialConnectionBaseline
+### buildPruneSelection
 
 ```ts
-getInitialConnectionBaseline(
-  currentNetwork: default,
-): number | undefined
+buildPruneSelection(
+  context: PruneSelectionContext,
+): PruneSelectionResult
 ```
 
-Read the scheduled-pruning baseline connection count.
+Build a connection removal selection from current ranking context.
 
 Parameters:
-- `currentNetwork` - - Network instance to inspect.
+- `context` - - Inputs for ranking and slicing removable connections.
 
-Returns: Baseline count when captured; otherwise undefined.
+Returns: Connections selected for pruning.
 
 ### buildScheduledTarget
 
@@ -355,118 +340,122 @@ Parameters:
 
 Returns: Desired remaining connections and current excess.
 
-### buildPruneSelection
+### calculateProgressFraction
 
 ```ts
-buildPruneSelection(
-  context: PruneSelectionContext,
-): PruneSelectionResult
+calculateProgressFraction(
+  currentIteration: number,
+  scheduleStart: number,
+  scheduleEnd: number,
+): number
 ```
 
-Build a connection removal selection from current ranking context.
+Compute clamped schedule progress in the [0,1] range.
 
 Parameters:
-- `context` - - Inputs for ranking and slicing removable connections.
+- `currentIteration` - - Iteration to evaluate.
+- `scheduleStart` - - Start iteration of schedule window.
+- `scheduleEnd` - - End iteration of schedule window.
 
-Returns: Connections selected for pruning.
+Returns: Clamped normalized progress.
 
-### disconnectConnections
+### calculateSnipSaliency
 
 ```ts
-disconnectConnections(
-  currentNetwork: default,
-  connectionsToDisconnect: default[],
-): void
+calculateSnipSaliency(
+  connection: default,
+): number
 ```
 
-Disconnect all selected connections from the network.
+Compute saliency for SNIP-like ranking.
 
 Parameters:
-- `currentNetwork` - - Network to mutate.
-- `connectionsToDisconnect` - - Connections to remove.
+- `connection` - - Connection to score.
 
-Returns: Nothing.
+Returns: Saliency value used for sorting.
 
-### resolvePruningMethod
+### clamp
 
 ```ts
-resolvePruningMethod(
-  method: PruningMethod | undefined,
-): PruningMethod
+clamp(
+  value: number,
+  minimum: number,
+  maximum: number,
+): number
 ```
 
-Normalize optional pruning method to a concrete value.
+Clamp a number into an inclusive range.
 
 Parameters:
-- `method` - - Optional configured pruning method.
+- `value` - - Raw value to clamp.
+- `minimum` - - Inclusive lower bound.
+- `maximum` - - Inclusive upper bound.
 
-Returns: Concrete pruning method.
+Returns: Clamped value.
 
-### markPruneIteration
+### disconnectConnections
 
 ```ts
-markPruneIteration(
-  currentPruningConfig: { start: number; end: number; frequency: number; targetSparsity: number; method: PruningMethod; regrowFraction: number; lastPruneIter?: number | undefined; },
-  currentIteration: number,
+disconnectConnections(
+  currentNetwork: default,
+  connectionsToDisconnect: default[],
 ): void
 ```
 
-Persist the iteration that last performed pruning.
+Disconnect all selected connections from the network.
 
 Parameters:
-- `currentPruningConfig` - - Active pruning configuration.
-- `currentIteration` - - Iteration to record.
+- `currentNetwork` - - Network to mutate.
+- `connectionsToDisconnect` - - Connections to remove.
 
 Returns: Nothing.
 
-### markTopologyDirty
+### getInitialConnectionBaseline
 
 ```ts
-markTopologyDirty(
+getInitialConnectionBaseline(
   currentNetwork: default,
-): void
+): number | undefined
 ```
 
-Mark topology cache as dirty after structural updates.
+Read the scheduled-pruning baseline connection count.
 
 Parameters:
-- `currentNetwork` - - Network with modified connectivity.
+- `currentNetwork` - - Network instance to inspect.
 
-Returns: Nothing.
+Returns: Baseline count when captured; otherwise undefined.
 
-### isOutsidePruningWindow
+### getPruningConfig
 
 ```ts
-isOutsidePruningWindow(
-  currentIteration: number,
-  currentPruningConfig: { start: number; end: number; frequency: number; targetSparsity: number; method: PruningMethod; regrowFraction: number; lastPruneIter?: number | undefined; },
-): boolean
+getPruningConfig(
+  currentNetwork: default,
+): { start: number; end: number; frequency: number; targetSparsity: number; method: PruningMethod; regrowFraction: number; lastPruneIter?: number | undefined; } | undefined
 ```
 
-Check whether an iteration is outside the pruning window.
+Read the active pruning schedule from network internals.
 
 Parameters:
-- `currentIteration` - - Iteration to evaluate.
-- `currentPruningConfig` - - Active pruning schedule.
+- `currentNetwork` - - Network instance to inspect.
 
-Returns: True when the iteration is out of range.
+Returns: Pruning configuration when enabled; otherwise undefined.
 
-### alreadyPrunedThisIteration
+### isOutsidePruningWindow
 
 ```ts
-alreadyPrunedThisIteration(
+isOutsidePruningWindow(
   currentIteration: number,
   currentPruningConfig: { start: number; end: number; frequency: number; targetSparsity: number; method: PruningMethod; regrowFraction: number; lastPruneIter?: number | undefined; },
 ): boolean
 ```
 
-Check whether this iteration was already pruned.
+Check whether an iteration is outside the pruning window.
 
 Parameters:
 - `currentIteration` - - Iteration to evaluate.
 - `currentPruningConfig` - - Active pruning schedule.
 
-Returns: True when pruning already happened for this iteration.
+Returns: True when the iteration is out of range.
 
 ### isScheduledPruningIteration
 
@@ -485,75 +474,69 @@ Parameters:
 
 Returns: True when this iteration matches the schedule cadence.
 
-### calculateProgressFraction
+### markPruneIteration
 
 ```ts
-calculateProgressFraction(
+markPruneIteration(
+  currentPruningConfig: { start: number; end: number; frequency: number; targetSparsity: number; method: PruningMethod; regrowFraction: number; lastPruneIter?: number | undefined; },
   currentIteration: number,
-  scheduleStart: number,
-  scheduleEnd: number,
-): number
+): void
 ```
 
-Compute clamped schedule progress in the [0,1] range.
+Persist the iteration that last performed pruning.
 
 Parameters:
-- `currentIteration` - - Iteration to evaluate.
-- `scheduleStart` - - Start iteration of schedule window.
-- `scheduleEnd` - - End iteration of schedule window.
+- `currentPruningConfig` - - Active pruning configuration.
+- `currentIteration` - - Iteration to record.
 
-Returns: Clamped normalized progress.
+Returns: Nothing.
 
-### clamp
+### markTopologyDirty
 
 ```ts
-clamp(
-  value: number,
-  minimum: number,
-  maximum: number,
-): number
+markTopologyDirty(
+  currentNetwork: default,
+): void
 ```
 
-Clamp a number into an inclusive range.
+Mark topology cache as dirty after structural updates.
 
 Parameters:
-- `value` - - Raw value to clamp.
-- `minimum` - - Inclusive lower bound.
-- `maximum` - - Inclusive upper bound.
+- `currentNetwork` - - Network with modified connectivity.
 
-Returns: Clamped value.
+Returns: Nothing.
 
-### rankConnectionsByRemovalPriority
+### rankConnectionsByMagnitude
 
 ```ts
-rankConnectionsByRemovalPriority(
+rankConnectionsByMagnitude(
   connections: default[],
-  method: PruningMethod,
 ): default[]
 ```
 
-Route ranking to the configured pruning heuristic.
+Rank connections by absolute weight magnitude.
 
 Parameters:
 - `connections` - - Candidate connections to rank.
-- `method` - - Ranking method to apply.
 
-Returns: Connections sorted by ascending removal priority.
+Returns: Connections sorted by ascending absolute weight.
 
-### rankConnectionsByMagnitude
+### rankConnectionsByRemovalPriority
 
 ```ts
-rankConnectionsByMagnitude(
+rankConnectionsByRemovalPriority(
   connections: default[],
+  method: PruningMethod,
 ): default[]
 ```
 
-Rank connections by absolute weight magnitude.
+Route ranking to the configured pruning heuristic.
 
 Parameters:
 - `connections` - - Candidate connections to rank.
+- `method` - - Ranking method to apply.
 
-Returns: Connections sorted by ascending absolute weight.
+Returns: Connections sorted by ascending removal priority.
 
 ### rankConnectionsBySnipSaliency
 
@@ -570,52 +553,54 @@ Parameters:
 
 Returns: Connections sorted by ascending saliency.
 
-### calculateSnipSaliency
+### resolveGradientMagnitude
 
 ```ts
-calculateSnipSaliency(
+resolveGradientMagnitude(
   connection: default,
 ): number
 ```
 
-Compute saliency for SNIP-like ranking.
+Resolve a stable gradient-magnitude proxy from connection delta statistics.
 
 Parameters:
-- `connection` - - Connection to score.
+- `connection` - - Connection containing accumulated delta history.
 
-Returns: Saliency value used for sorting.
+Returns: Absolute gradient magnitude proxy.
 
-### resolveGradientMagnitude
+### resolvePruningMethod
 
 ```ts
-resolveGradientMagnitude(
-  connection: default,
-): number
+resolvePruningMethod(
+  method: PruningMethod | undefined,
+): PruningMethod
 ```
 
-Resolve a stable gradient-magnitude proxy from connection delta statistics.
+Normalize optional pruning method to a concrete value.
 
 Parameters:
-- `connection` - - Connection containing accumulated delta history.
-
-Returns: Absolute gradient magnitude proxy.
+- `method` - - Optional configured pruning method.
 
-## architecture/network/prune/network.prune.sparsity.utils.ts
+Returns: Concrete pruning method.
 
-### readInitialSparsityBaseline
+### shouldRunScheduledPrune
 
 ```ts
-readInitialSparsityBaseline(
-  currentNetwork: default,
-): number | undefined
+shouldRunScheduledPrune(
+  currentIteration: number,
+  currentPruningConfig: { start: number; end: number; frequency: number; targetSparsity: number; method: PruningMethod; regrowFraction: number; lastPruneIter?: number | undefined; },
+): boolean
 ```
 
-Read baseline used for sparsity reporting.
+Determine whether scheduled pruning should run at this iteration.
 
 Parameters:
-- `currentNetwork` - - Network to inspect.
+- `currentIteration` - - Training iteration being processed.
+- `currentPruningConfig` - - Active pruning schedule.
 
-Returns: Baseline connection count when available.
+Returns: True when pruning should execute now.
+
+## architecture/network/prune/network.prune.sparsity.utils.ts
 
 ### calculateSparsityFromBaseline
 
@@ -634,37 +619,37 @@ Parameters:
 
 Returns: Sparsity ratio in [0,1] for valid baselines.
 
-## architecture/network/prune/network.prune.evolutionary.utils.ts
-
-### normalizeEvolutionaryTargetSparsity
+### readInitialSparsityBaseline
 
 ```ts
-normalizeEvolutionaryTargetSparsity(
-  rawTargetSparsity: number,
-): number
+readInitialSparsityBaseline(
+  currentNetwork: default,
+): number | undefined
 ```
 
-Clamp evolutionary target sparsity to safe operational bounds.
+Read baseline used for sparsity reporting.
 
 Parameters:
-- `rawTargetSparsity` - - Requested target sparsity.
+- `currentNetwork` - - Network to inspect.
 
-Returns: Normalized target sparsity.
+Returns: Baseline connection count when available.
 
-### getOrCaptureEvolutionaryBaseline
+## architecture/network/prune/network.prune.evolutionary.utils.ts
+
+### buildEvolutionaryPruneSelection
 
 ```ts
-getOrCaptureEvolutionaryBaseline(
-  currentNetwork: default,
-): number
+buildEvolutionaryPruneSelection(
+  context: PruneSelectionContext,
+): PruneSelectionResult
 ```
 
-Capture evolutionary baseline once and reuse it for subsequent pruning calls.
+Build evolutionary pruning connection selection.
 
 Parameters:
-- `currentNetwork` - - Network to inspect and possibly initialize.
+- `context` - - Inputs for ranking and slicing.
 
-Returns: Evolutionary baseline connection count.
+Returns: Connections selected for removal.
 
 ### buildEvolutionaryTarget
 
@@ -683,20 +668,20 @@ Parameters:
 
 Returns: Desired remaining and excess connection counts.
 
-### buildEvolutionaryPruneSelection
+### calculateEvolutionarySnipSaliency
 
 ```ts
-buildEvolutionaryPruneSelection(
-  context: PruneSelectionContext,
-): PruneSelectionResult
+calculateEvolutionarySnipSaliency(
+  connection: default,
+): number
 ```
 
-Build evolutionary pruning connection selection.
+Compute evolutionary SNIP-like saliency for one connection.
 
 Parameters:
-- `context` - - Inputs for ranking and slicing.
+- `connection` - - Connection to score.
 
-Returns: Connections selected for removal.
+Returns: Saliency score.
 
 ### disconnectEvolutionaryConnections
 
@@ -715,6 +700,21 @@ Parameters:
 
 Returns: Nothing.
 
+### getOrCaptureEvolutionaryBaseline
+
+```ts
+getOrCaptureEvolutionaryBaseline(
+  currentNetwork: default,
+): number
+```
+
+Capture evolutionary baseline once and reuse it for subsequent pruning calls.
+
+Parameters:
+- `currentNetwork` - - Network to inspect and possibly initialize.
+
+Returns: Evolutionary baseline connection count.
+
 ### markEvolutionaryTopologyDirty
 
 ```ts
@@ -730,6 +730,21 @@ Parameters:
 
 Returns: Nothing.
 
+### normalizeEvolutionaryTargetSparsity
+
+```ts
+normalizeEvolutionaryTargetSparsity(
+  rawTargetSparsity: number,
+): number
+```
+
+Clamp evolutionary target sparsity to safe operational bounds.
+
+Parameters:
+- `rawTargetSparsity` - - Requested target sparsity.
+
+Returns: Normalized target sparsity.
+
 ### rankEvolutionaryConnections
 
 ```ts
@@ -777,21 +792,6 @@ Parameters:
 
 Returns: Connections sorted by ascending saliency.
 
-### calculateEvolutionarySnipSaliency
-
-```ts
-calculateEvolutionarySnipSaliency(
-  connection: default,
-): number
-```
-
-Compute evolutionary SNIP-like saliency for one connection.
-
-Parameters:
-- `connection` - - Connection to score.
-
-Returns: Saliency score.
-
 ### resolveEvolutionaryGradientMagnitude
 
 ```ts