initium-deeplearning 0.1.0__tar.gz → 0.2.1__tar.gz

{initium_deeplearning-0.1.0 → initium_deeplearning-0.2.1}/.gitignore

@@ -216,3 +216,8 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# Experimental documents for context, not to be committed
+documents/*
+dnc-context/*
+tmp/*

{initium_deeplearning-0.1.0 → initium_deeplearning-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: initium-deeplearning
-Version: 0.1.0
+Version: 0.2.1
 Summary: Differentiable Neural Computer research framework with pluggable LSTM/Mamba/CfC controllers, MoE, split-graph and stochastic write heads.
 Project-URL: Homepage, https://github.com/samueleternity/initium
 Project-URL: Issues, https://github.com/samueleternity/initium/issues
@@ -47,6 +47,45 @@ The project studies how a neural controller can interact with a differentiable e
 
 These are research questions, not all established project claims. In particular, supported dataset interfaces do not imply that every modality has been trained and validated to the same standard as graph traversal.
 
+## Launch
+
+You can either fork/clone the repository and customize everything you need or you can use pip/pdm/uv for ready to use installation.
+
+Guide for pip usage:
+
+To install the whole framework: pip install initium-deeplearning
+
+For ANY mamba related operation you need: python -m initium.setup_wheels 
+
+Optionally you can try:
+pip install "initium-deeplearning[text]"
+pip install "initium-deeplearning[video]"
+pip install "initium-deeplearning[real-data]"
+
+To see all CLI optionality:
+initium-infer --help
+python initium.core_training --help
+
+Example usage:
+
+python -m initium.core_training 0.0 --controller lstm
+python -m initium.core_training 0.0 --split-graph --split-graph-variant mamba1 ...
+
+Inference runs need a checkpoint first. The built-in tool analyzes it and refuses unsupported task types or dimensions. Dataset preparation-only mode does not need a checkpoint.
+
+### Reusing prepared datasets
+
+Training and inference can save the processed dataset state so the raw source is not parsed or tokenized again. `--save DIRECTORY` writes to `DIRECTORY/<type>/<source> [prepared]/dataset.pkl`; `--load-prepared` accepts that prepared folder (or a save root containing exactly one prepared dataset of the requested type). When loading, `--dataset-link` is optional. Use `--prepare-only` with `--save` to prepare and save a dataset without starting a run:
+
+```bash
+python -m initium.core_training 0.0 --dataset-type text --dataset-link ./corpus.txt --save ./prepared --prepare-only
+python -m initium.core_training 0.0 --dataset-type text --load-prepared "./prepared/text/corpus [prepared]"
+initium-infer checkpoint.pt --dataset-type text --load-prepared "./prepared/text/corpus [prepared]"
+initium-infer --dataset-type text --dataset-link ./corpus.txt --save ./prepared --prepare-only
+```
+
+Prepared artifacts retain the resolved train/test pools or graph mappings, including the split used when they were created. They are Python pickle files and should only be loaded from sources you trust.
+
 ## High-level flow
 
 ```text
@@ -79,6 +118,25 @@ The training core delegates task construction and task-specific behavior to a da
 
 The DNC supplies a memory matrix and differentiable read/write interface. The memory can retain information beyond a controller's immediate hidden state. Content-based addressing, read heads, and temporal-link structures are part of the underlying DNC implementation. The temporal link matrix has quadratic cost in the number of memory cells, which motivates the project's link-matrix ablations and memory-size investigations.
 
+### Read/write mechanism roadmap
+
+The split-graph memory exposes independent read and write variants while retaining the DNC usage, allocation, write addressing, read modes, and temporal-link machinery:
+
+- `--dnc-read-variant cosine` is the DNC baseline. `relational-mlp` replaces cosine similarity with a learned score for each `(query, memory row)` pair. `relational-residual` adds a scaled learned pairwise score to cosine and zero-initializes its final layer, so it starts exactly at the DNC baseline. `--dnc-read-residual-scale` controls that correction's strength (default `1.0`). Track A logs the correction-to-cosine RMS ratio to show whether it contributes meaningfully. Write content addressing remains cosine-based for both learned readers.
+- `--dnc-write-variant learned` is the DNC baseline. `kanerva-closed-form` turns the existing write-value projection into an observation and applies a per-row online isotropic Gaussian posterior update. It does not import the Kanerva Machine's exchangeable episode objective or claim to reproduce its full generative model.
+- The variants compose, so the four baseline / Track A / Track B / combined cells are expressible through the same training and checkpoint pipeline. The closed-form writer uses a deterministic observation projection; the stochastic write head is not installed for that variant.
+- The graph curriculum emits ID, OOD, and OOD-offset metrics as before. Graph runs also write `run_<id>_relational_probe.csv`, with cosine top-1, selected read-head top-1, and held-out-composition accuracy. `data/graph_traversal/order_probe.py` supplies paired prefix-permutation helpers for the Q99 order-sensitivity evaluation.
+- Split-graph graph runs also write `run_<id>_track_a.csv` and `run_<id>_track_b.csv`. Track A records ID/OOD accuracy, relational stress and held-out-composition accuracy, ordinary-input read-score/cosine correlation, and read-content entropy/maximum weight. Track B records the Q99 order-sensitivity gate, ID/OOD posterior variance and write-update diagnostics, and training-window loss, gradient norm, AMP scale, and learning rate. These are experiment logs; no training or evaluation results are checked in.
+
+Use the selected split-graph baseline with either supported controller combiner:
+
+```bash
+python -m initium.core_training 0.0 --split-graph --split-graph-variant mamba1 --split-graph-combiner-mode controller --split-graph-combiner-variant cfc
+python -m initium.core_training 0.0 --split-graph --split-graph-variant mamba1 --split-graph-combiner-mode controller --split-graph-combiner-variant mamba+cfc
+```
+
+Add `--dnc-read-variant relational-mlp` to reproduce the original Track A reader, or `--dnc-read-variant relational-residual --dnc-read-residual-scale 1.0` to use the cosine-anchored Track A reader. Lower scales such as `0.5` are available for follow-up comparisons. Use `--dnc-write-variant kanerva-closed-form` for Track B. Add a reader and writer variant together only for the combined cell after each track is characterized. Dense temporal links remain the default. The short-run baseline reproduction gate and the Q99 paired-order evaluation are deliberate user-run experiment steps; no run results are assumed by this repository change.
+
 ### Controllers
 
 The training core exposes controller choices through its command-line interface and configuration:

{initium_deeplearning-0.1.0 → initium_deeplearning-0.2.1}/README.md

@@ -16,6 +16,45 @@ The project studies how a neural controller can interact with a differentiable e
 
 These are research questions, not all established project claims. In particular, supported dataset interfaces do not imply that every modality has been trained and validated to the same standard as graph traversal.
 
+## Launch
+
+You can either fork/clone the repository and customize everything you need or you can use pip/pdm/uv for ready to use installation.
+
+Guide for pip usage:
+
+To install the whole framework: pip install initium-deeplearning
+
+For ANY mamba related operation you need: python -m initium.setup_wheels 
+
+Optionally you can try:
+pip install "initium-deeplearning[text]"
+pip install "initium-deeplearning[video]"
+pip install "initium-deeplearning[real-data]"
+
+To see all CLI optionality:
+initium-infer --help
+python initium.core_training --help
+
+Example usage:
+
+python -m initium.core_training 0.0 --controller lstm
+python -m initium.core_training 0.0 --split-graph --split-graph-variant mamba1 ...
+
+Inference runs need a checkpoint first. The built-in tool analyzes it and refuses unsupported task types or dimensions. Dataset preparation-only mode does not need a checkpoint.
+
+### Reusing prepared datasets
+
+Training and inference can save the processed dataset state so the raw source is not parsed or tokenized again. `--save DIRECTORY` writes to `DIRECTORY/<type>/<source> [prepared]/dataset.pkl`; `--load-prepared` accepts that prepared folder (or a save root containing exactly one prepared dataset of the requested type). When loading, `--dataset-link` is optional. Use `--prepare-only` with `--save` to prepare and save a dataset without starting a run:
+
+```bash
+python -m initium.core_training 0.0 --dataset-type text --dataset-link ./corpus.txt --save ./prepared --prepare-only
+python -m initium.core_training 0.0 --dataset-type text --load-prepared "./prepared/text/corpus [prepared]"
+initium-infer checkpoint.pt --dataset-type text --load-prepared "./prepared/text/corpus [prepared]"
+initium-infer --dataset-type text --dataset-link ./corpus.txt --save ./prepared --prepare-only
+```
+
+Prepared artifacts retain the resolved train/test pools or graph mappings, including the split used when they were created. They are Python pickle files and should only be loaded from sources you trust.
+
 ## High-level flow
 
 ```text
@@ -48,6 +87,25 @@ The training core delegates task construction and task-specific behavior to a da
 
 The DNC supplies a memory matrix and differentiable read/write interface. The memory can retain information beyond a controller's immediate hidden state. Content-based addressing, read heads, and temporal-link structures are part of the underlying DNC implementation. The temporal link matrix has quadratic cost in the number of memory cells, which motivates the project's link-matrix ablations and memory-size investigations.
 
+### Read/write mechanism roadmap
+
+The split-graph memory exposes independent read and write variants while retaining the DNC usage, allocation, write addressing, read modes, and temporal-link machinery:
+
+- `--dnc-read-variant cosine` is the DNC baseline. `relational-mlp` replaces cosine similarity with a learned score for each `(query, memory row)` pair. `relational-residual` adds a scaled learned pairwise score to cosine and zero-initializes its final layer, so it starts exactly at the DNC baseline. `--dnc-read-residual-scale` controls that correction's strength (default `1.0`). Track A logs the correction-to-cosine RMS ratio to show whether it contributes meaningfully. Write content addressing remains cosine-based for both learned readers.
+- `--dnc-write-variant learned` is the DNC baseline. `kanerva-closed-form` turns the existing write-value projection into an observation and applies a per-row online isotropic Gaussian posterior update. It does not import the Kanerva Machine's exchangeable episode objective or claim to reproduce its full generative model.
+- The variants compose, so the four baseline / Track A / Track B / combined cells are expressible through the same training and checkpoint pipeline. The closed-form writer uses a deterministic observation projection; the stochastic write head is not installed for that variant.
+- The graph curriculum emits ID, OOD, and OOD-offset metrics as before. Graph runs also write `run_<id>_relational_probe.csv`, with cosine top-1, selected read-head top-1, and held-out-composition accuracy. `data/graph_traversal/order_probe.py` supplies paired prefix-permutation helpers for the Q99 order-sensitivity evaluation.
+- Split-graph graph runs also write `run_<id>_track_a.csv` and `run_<id>_track_b.csv`. Track A records ID/OOD accuracy, relational stress and held-out-composition accuracy, ordinary-input read-score/cosine correlation, and read-content entropy/maximum weight. Track B records the Q99 order-sensitivity gate, ID/OOD posterior variance and write-update diagnostics, and training-window loss, gradient norm, AMP scale, and learning rate. These are experiment logs; no training or evaluation results are checked in.
+
+Use the selected split-graph baseline with either supported controller combiner:
+
+```bash
+python -m initium.core_training 0.0 --split-graph --split-graph-variant mamba1 --split-graph-combiner-mode controller --split-graph-combiner-variant cfc
+python -m initium.core_training 0.0 --split-graph --split-graph-variant mamba1 --split-graph-combiner-mode controller --split-graph-combiner-variant mamba+cfc
+```
+
+Add `--dnc-read-variant relational-mlp` to reproduce the original Track A reader, or `--dnc-read-variant relational-residual --dnc-read-residual-scale 1.0` to use the cosine-anchored Track A reader. Lower scales such as `0.5` are available for follow-up comparisons. Use `--dnc-write-variant kanerva-closed-form` for Track B. Add a reader and writer variant together only for the combined cell after each track is characterized. Dense temporal links remain the default. The short-run baseline reproduction gate and the Q99 paired-order evaluation are deliberate user-run experiment steps; no run results are assumed by this repository change.
+
 ### Controllers
 
 The training core exposes controller choices through its command-line interface and configuration:

{initium_deeplearning-0.1.0 → initium_deeplearning-0.2.1}/pyproject.toml

@@ -38,6 +38,7 @@ real-data = ["initium-deeplearning[text,video]"]
 [project.scripts]
 initium-setup = "initium.setup_wheels:main"
 initium-infer = "initium.inference.run_inference:main"
+initium-kl-attribution = "initium.analysis.kl_attribution:main"
 
 [project.urls]
 Homepage = "https://github.com/samueleternity/initium"

{initium_deeplearning-0.1.0 → initium_deeplearning-0.2.1}/src/__init__.py

@@ -1,3 +1,3 @@
 """initium - modular Differentiable Neural Computer research framework."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"

initium_deeplearning-0.2.1/src/initium/__init__.py

@@ -0,0 +1,104 @@
+"""Initium's stable architecture API.
+
+Import mechanism-layer components from this package, for example::
+
+    from initium import SplitGraphDNC, MambaDNC, resize_memory
+
+Training and inference entry points remain in their existing modules
+(``initium.core_training`` and ``initium.inference``). Dataset encoders,
+``DigitCodec``, and task/curriculum implementations under ``initium.data``
+are intentionally internal: they describe replaceable representations, not
+the architecture contract. Exports are lazy so importing the package does
+not import a training CLI or optional model dependencies unnecessarily.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+__all__ = [
+    # DNC architectures
+    "SplitGraphDNC",
+    "MambaDNC",
+    # Controller mechanisms and compositions
+    "MambaControllerWrapper",
+    "Mamba2ControllerWrapper",
+    "Mamba3ControllerWrapper",
+    "CfCControllerWrapper",
+    "ChainedControllerWrapper",
+    "build_hybrid_controller",
+    # Routing and stochastic memory writes
+    "StochasticWriteHead",
+    "SwitchMoE",
+    "MoEBlock",
+    # Memory and checkpoint mechanics
+    "resize_memory",
+    "load_checkpoint",
+    "describe_checkpoint",
+    "load_model",
+    "LoadedModel",
+]
+
+_EXPORTS = {
+    "SplitGraphDNC": "initium.mamba_controller.split_graph_dnc",
+    "MambaDNC": "initium.mamba_controller.mamba_controller",
+    "MambaControllerWrapper": "initium.mamba_controller.mamba_controller",
+    "Mamba2ControllerWrapper": "initium.mamba_controller.mamba2_controller",
+    "Mamba3ControllerWrapper": "initium.mamba_controller.mamba3_controller",
+    "CfCControllerWrapper": "initium.LNN_controller.cfc_controller",
+    "ChainedControllerWrapper": "initium.LNN_controller.chained_controller",
+    "build_hybrid_controller": "initium.LNN_controller.hybrid_controller",
+    "StochasticWriteHead": "initium.memory_manipulation.stochastic_write_head_v2",
+    "SwitchMoE": "initium.MoE.moe_layer",
+    "MoEBlock": "initium.MoE.moe_layer",
+    "resize_memory": "initium.memory_manipulation.dynamic_memory_resize",
+    "load_checkpoint": "initium.inference.checkpoint_io",
+    "describe_checkpoint": "initium.inference.checkpoint_io",
+    "load_model": "initium.inference.model_loader",
+    "LoadedModel": "initium.inference.model_loader",
+}
+
+if TYPE_CHECKING:
+    from initium.inference.checkpoint_io import describe_checkpoint as describe_checkpoint
+    from initium.inference.checkpoint_io import load_checkpoint as load_checkpoint
+    from initium.inference.model_loader import LoadedModel as LoadedModel
+    from initium.inference.model_loader import load_model as load_model
+    from initium.LNN_controller.cfc_controller import CfCControllerWrapper as CfCControllerWrapper
+    from initium.LNN_controller.chained_controller import (
+        ChainedControllerWrapper as ChainedControllerWrapper,
+    )
+    from initium.LNN_controller.hybrid_controller import (
+        build_hybrid_controller as build_hybrid_controller,
+    )
+    from initium.mamba_controller.mamba2_controller import (
+        Mamba2ControllerWrapper as Mamba2ControllerWrapper,
+    )
+    from initium.mamba_controller.mamba3_controller import (
+        Mamba3ControllerWrapper as Mamba3ControllerWrapper,
+    )
+    from initium.mamba_controller.mamba_controller import (
+        MambaControllerWrapper as MambaControllerWrapper,
+    )
+    from initium.mamba_controller.mamba_controller import MambaDNC as MambaDNC
+    from initium.mamba_controller.split_graph_dnc import SplitGraphDNC as SplitGraphDNC
+    from initium.memory_manipulation.dynamic_memory_resize import resize_memory as resize_memory
+    from initium.memory_manipulation.stochastic_write_head_v2 import (
+        StochasticWriteHead as StochasticWriteHead,
+    )
+    from initium.MoE.moe_layer import MoEBlock as MoEBlock
+    from initium.MoE.moe_layer import SwitchMoE as SwitchMoE
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve only names explicitly listed in the stable public API."""
+    module_name = _EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(import_module(module_name), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

initium_deeplearning-0.2.1/src/initium/analysis/__init__.py

@@ -0,0 +1 @@
+"""Analysis helpers for matched Initium experiment runs."""

initium_deeplearning-0.2.1/src/initium/analysis/kl_attribution.py

@@ -0,0 +1,291 @@
+"""Matched-pair OGS/KL attribution report generator.
+
+Manifest example::
+
+    {"pairs": [{"seed": 1, "beta0_ogs": "...csv", "beta_ogs": "...csv",
+                "beta0_train": "...csv", "beta_train": "...csv"}]}
+
+Select the evaluation window before examining outcomes with --step-start and
+--step-end. Each run is averaged over that same inclusive step interval before
+the within-seed beta-minus-zero difference is computed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import math
+from pathlib import Path
+
+METRICS = (
+    "ogs",
+    "ood_acc",
+    "offset_normalized",
+    "memory_attributable_ood",
+    "ood_perfect_frac",
+)
+
+
+def _read_window(path, step_start, step_end, columns):
+    rows = []
+    with open(path, newline="", encoding="utf-8") as f:
+        for row in csv.DictReader(f):
+            step = int(float(row["step"]))
+            if step_start <= step <= step_end:
+                rows.append(
+                    {name: float(row[name]) for name in columns if row.get(name) not in (None, "")}
+                )
+    if not rows:
+        raise ValueError(f"{path}: no rows in preregistered step window {step_start}..{step_end}")
+    return {
+        name: sum(row[name] for row in rows if name in row) / sum(name in row for row in rows)
+        for name in columns
+        if any(name in row for row in rows)
+    }
+
+
+def _mean(values):
+    return sum(values) / len(values)
+
+
+def _sd(values):
+    return (
+        math.sqrt(sum((x - _mean(values)) ** 2 for x in values) / (len(values) - 1))
+        if len(values) > 1
+        else 0.0
+    )
+
+
+def _betacf(a, b, x):
+    qab, qap, qam = a + b, a + 1.0, a - 1.0
+    c, d = 1.0, 1.0 - qab * x / qap
+    d = 1e-300 if abs(d) < 1e-300 else 1.0 / d
+    h = d
+    for m in range(1, 201):
+        m2 = 2 * m
+        aa = m * (b - m) * x / ((qam + m2) * (a + m2))
+        d = 1.0 + aa * d
+        d = 1e-300 if abs(d) < 1e-300 else d
+        c = 1.0 + aa / c
+        c = 1e-300 if abs(c) < 1e-300 else c
+        d = 1.0 / d
+        h *= d * c
+        aa = -(a + m) * (qab + m) * x / ((a + m2) * (qap + m2))
+        d = 1.0 + aa * d
+        d = 1e-300 if abs(d) < 1e-300 else d
+        c = 1.0 + aa / c
+        c = 1e-300 if abs(c) < 1e-300 else c
+        d = 1.0 / d
+        delta = d * c
+        h *= delta
+        if abs(delta - 1.0) < 3e-14:
+            break
+    return h
+
+
+def _ibeta(a, b, x):
+    if x <= 0:
+        return 0.0
+    if x >= 1:
+        return 1.0
+    factor = math.exp(
+        math.lgamma(a + b) - math.lgamma(a) - math.lgamma(b) + a * math.log(x) + b * math.log1p(-x)
+    )
+    if x < (a + 1.0) / (a + b + 2.0):
+        return factor * _betacf(a, b, x) / a
+    return 1.0 - factor * _betacf(b, a, 1.0 - x) / b
+
+
+def _t_cdf(t, degrees):
+    x = degrees / (degrees + t * t)
+    tail = 0.5 * _ibeta(degrees / 2.0, 0.5, x)
+    return 1.0 - tail if t >= 0 else tail
+
+
+def _t_critical(degrees, confidence=0.95):
+    target = (1.0 + confidence) / 2.0
+    lo, hi = 0.0, 100.0
+    for _ in range(100):
+        mid = (lo + hi) / 2
+        if _t_cdf(mid, degrees) < target:
+            lo = mid
+        else:
+            hi = mid
+    return (lo + hi) / 2
+
+
+def _pearson(xs, ys):
+    if len(xs) < 2:
+        return float("nan")
+    mx, my = _mean(xs), _mean(ys)
+    xx = sum((x - mx) ** 2 for x in xs)
+    yy = sum((y - my) ** 2 for y in ys)
+    if xx == 0 or yy == 0:
+        return float("nan")
+    return sum((x - mx) * (y - my) for x, y in zip(xs, ys)) / math.sqrt(xx * yy)
+
+
+def _paired_report(deltas):
+    n = len(deltas)
+    mean = _mean(deltas)
+    sd = _sd(deltas)
+    se = sd / math.sqrt(n) if n else float("nan")
+    t_value = mean / se if se else (float("inf") if mean else 0.0)
+    p_value = 2.0 * (1.0 - _t_cdf(abs(t_value), n - 1)) if n > 1 else float("nan")
+    margin = _t_critical(n - 1) * se if n > 1 else float("nan")
+    return {
+        "n": n,
+        "mean_delta": mean,
+        "sd_delta": sd,
+        "paired_t": t_value,
+        "p_two_sided": p_value,
+        "ci95": [mean - margin, mean + margin],
+        "cohens_dz": mean / sd if sd else float("nan"),
+    }
+
+
+def _training_diagnostics(pair, step_start, step_end):
+    result = {}
+    for label in ("beta0_train", "beta_train"):
+        path = pair.get(label)
+        if not path:
+            continue
+        rows = _read_window(path, step_start, step_end, ("task_loss", "kl_mean", "kl_max"))
+        result[label] = rows
+    if "beta_train" in result:
+        kl_mean = result["beta_train"].get("kl_mean")
+        result["kl_collapse_flag"] = kl_mean is not None and abs(kl_mean) < 1e-5
+    if "beta0_train" in result and "beta_train" in result:
+        a = result["beta0_train"].get("task_loss")
+        b = result["beta_train"].get("task_loss")
+        result["task_loss_delta_beta_minus_zero"] = (
+            b - a if a is not None and b is not None else None
+        )
+        result["relative_task_loss_increase"] = (
+            (b - a) / max(abs(a), 1e-12) if a is not None and b is not None else None
+        )
+    return result
+
+
+def build_report(manifest, step_start, step_end):
+    if "comparisons" in manifest:
+        reports = []
+        for comparison in manifest["comparisons"]:
+            submanifest = {
+                "comparison": comparison.get("label", "unlabeled comparison"),
+                "pairs": comparison["pairs"],
+            }
+            reports.append(
+                {
+                    "task_family": comparison.get("task_family"),
+                    "architecture": comparison.get("architecture"),
+                    **build_report(submanifest, step_start, step_end),
+                }
+            )
+        directions = [
+            math.copysign(1, item["aggregate"]["ogs"]["mean_delta"])
+            for item in reports
+            if "ogs" in item.get("aggregate", {}) and item["aggregate"]["ogs"]["mean_delta"] != 0
+        ]
+        return {
+            "preregistered_step_window": [step_start, step_end],
+            "comparisons": reports,
+            "two_by_two_consistency": {
+                "ogs_effect_direction_consistent": len(directions) == len(reports)
+                and len(set(directions)) <= 1,
+                "criterion": "KL OGS effect sign should agree across the compared architectures and task families.",
+            },
+        }
+    pairs = manifest["pairs"]
+    if not pairs:
+        raise ValueError("manifest needs at least one matched seed pair")
+    columns = list(METRICS)
+    rows, diagnostics = [], []
+    for pair in pairs:
+        if (
+            pair.get("beta0_architecture") is not None
+            and pair.get("beta_architecture") is not None
+            and pair["beta0_architecture"] != pair["beta_architecture"]
+        ):
+            raise ValueError(f"seed {pair['seed']}: beta pair uses different architectures")
+        if (
+            pair.get("beta0_step_budget") is not None
+            and pair.get("beta_step_budget") is not None
+            and pair["beta0_step_budget"] != pair["beta_step_budget"]
+        ):
+            raise ValueError(f"seed {pair['seed']}: beta pair uses different step budgets")
+        anchor = _read_window(pair["beta0_ogs"], step_start, step_end, columns)
+        treatment = _read_window(pair["beta_ogs"], step_start, step_end, columns)
+        row = {"seed": pair["seed"]}
+        for metric in columns:
+            if metric in anchor and metric in treatment:
+                row[metric] = treatment[metric] - anchor[metric]
+        rows.append(row)
+        diagnostics.append(_training_diagnostics(pair, step_start, step_end))
+    stats = {
+        metric: _paired_report([r[metric] for r in rows if metric in r])
+        for metric in columns
+        if any(metric in r for r in rows)
+    }
+    anchor_ogs = [
+        _read_window(pair["beta0_ogs"], step_start, step_end, ("ogs",))["ogs"] for pair in pairs
+    ]
+    delta_ogs = [r.get("ogs", float("nan")) for r in rows]
+    mean_anchor = _mean(anchor_ogs)
+    regression_r = _pearson([v - mean_anchor for v in anchor_ogs], delta_ogs)
+    return {
+        "comparison": manifest.get("comparison", "beta effect"),
+        "preregistered_step_window": [step_start, step_end],
+        "pairing": "within-seed beta-minus-zero; same architecture and step window",
+        "n_seeds": len(pairs),
+        "minimum_n_8_met": len(pairs) >= 8,
+        "per_seed_deltas": rows,
+        "aggregate": stats,
+        "regression_to_mean": {
+            "corr_anchor_ogs_offset_vs_beta_delta": regression_r,
+            "possible_variance_dampening": math.isfinite(regression_r) and regression_r <= -0.5,
+        },
+        "training_diagnostics": diagnostics,
+        "no_collapse_and_no_cost_redistribution": {
+            "all_beta_runs_noncollapsed": all(
+                not d.get("kl_collapse_flag", False) for d in diagnostics
+            ),
+            "task_loss_deltas": [d.get("task_loss_delta_beta_minus_zero") for d in diagnostics],
+            "relative_task_loss_increases": [
+                d.get("relative_task_loss_increase") for d in diagnostics
+            ],
+            "possible_cost_redistribution": any(
+                d.get("relative_task_loss_increase") is not None
+                and d["relative_task_loss_increase"] >= 0.05
+                for d in diagnostics
+            ),
+            "interpretation": "Inspect task_loss and KL together; this report flags near-zero mean KL but does not infer causality.",
+        },
+    }
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("manifest", type=Path)
+    parser.add_argument(
+        "--step-start", type=int, required=True, help="inclusive preregistered lower step bound"
+    )
+    parser.add_argument(
+        "--step-end", type=int, required=True, help="inclusive preregistered upper step bound"
+    )
+    parser.add_argument("--output", type=Path, default=None)
+    args = parser.parse_args(argv)
+    if args.step_end < args.step_start:
+        parser.error("--step-end must be >= --step-start")
+    with args.manifest.open(encoding="utf-8") as f:
+        report = build_report(json.load(f), args.step_start, args.step_end)
+    rendered = json.dumps(report, indent=2, allow_nan=True)
+    if args.output:
+        args.output.write_text(rendered + "\n", encoding="utf-8")
+    print(rendered)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{initium_deeplearning-0.1.0 → initium_deeplearning-0.2.1}/src/initium/config/controller_config.py

@@ -67,6 +67,13 @@ SPLIT_GRAPH_COMBINER_MODE = "linear"  # "linear" (default) | "controller"
 SPLIT_GRAPH_COMBINER_VARIANT = "mamba1"
 SPLIT_GRAPH_COMBINER_NUM_BLOCKS = 1
 
+# DNC memory mechanism variants (only applied by the split-graph assembly).
+DNC_READ_VARIANT = "cosine"  # "cosine" | "relational-mlp" | "relational-residual"
+DNC_READ_RESIDUAL_SCALE = 1.0  # Gain applied before tanh for relational-residual.
+DNC_READ_RESIDUAL_MAX_RATIO = 0.5  # Maximum residual magnitude relative to cosine RMS.
+DNC_WRITE_VARIANT = "learned"  # "learned" | "kanerva-closed-form"
+DNC_WRITE_OBSERVATION_VARIANCE = 1.0  # fixed isotropic likelihood variance
+
 # ---- Option 1: link-matrix ablation/sparsification at fixed N -----------------
 LINK_MATRIX_MODE = "dense"  # "dense" | "ablated" | "sparse_topk"
 LINK_MATRIX_TOPK: int | None = None  # int, required only for "sparse_topk"