graphyco 0.1.0__tar.gz

graphyco-0.1.0/PKG-INFO

@@ -0,0 +1,494 @@
+Metadata-Version: 2.4
+Name: graphyco
+Version: 0.1.0
+Summary: Computational graph topology and dynamic gradient-flow monitoring for PyTorch
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: torch
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Provides-Extra: gui
+Requires-Dist: PySide6; extra == "gui"
+
+# Graphyco
+
+Computational graph topology and dynamic gradient-flow monitoring for PyTorch neural networks.
+
+Graphyco maps neural network architectures into a formal computational state graph:
+
+$$G_t = (V, E, X_t, A_t, G_t)$$
+
+- **$V$ (Operational Nodes):** Computational units (layers, functions, torch operators, input/output placeholders).
+- **$E$ (Directed Dependency Edges):** Directed dataflow dependencies classified as `operational`, `informational`, or `governance`.
+- **$X_t$ (Structural Invariants & Capacity):** Fixed-point graph metrics, structural capacity vectors, and domain constants.
+- **$A_t$ (Forward Activation Telemetry):** Forward tensor statistics (RMS, L1, L2, sparsity, mean, std) captured during execution.
+- **$G_t$ (Backward Gradient Telemetry):** Backward tensor statistics across activation gradients, parameter gradients, and edge-intercepted gradients.
+
+---
+
+## Architecture Overview
+
+```
+graphyco/
+├── src/
+│   └── graphyco/                  # Core Python package & library
+│       ├── core/                  # Deterministic graph primitives & invariant verification
+│       │   ├── primitives.py      # Node, Edge, CapacityVector, GraphState, checked arithmetic
+│       │   ├── graph.py           # Adjacency, density, degree metrics, DFS critical cycle detection
+│       │   ├── evaluation.py      # Coherence, topological bottlenecks, perturbation resilience
+│       │   └── invariants.py      # Seven enforced graph invariant validation rules
+│       ├── bridge/                # PyTorch model translation & execution orchestration
+│       │   ├── torch_bridge.py    # FX symbolic tracing, module fallback, parameter counting
+│       │   └── grad_bridge.py     # DynamicExecutionBridge, DynamicGraphState, LiveTrainingMonitor
+│       ├── observer/              # Observational runtime telemetry engine
+│       │   ├── grad_observer.py   # TensorStats, EdgeAutogradHook, FXGradObserver, ModuleGradObserver
+│       │   └── grad_eval.py       # Edge attenuation, dynamic bottleneck G_max, Types I-IV, temporal CV
+│       ├── visualizer/            # Query engine, REST API, CLI, and PySide6 Desktop GUI
+│       │   ├── app.py             # visualize(), extract_benchmark_json()
+│       │   ├── query.py           # QueryEngine, describe(), get_bottlenecks(), get_neighbors()
+│       │   ├── server.py          # AppServer HTTP daemon (/api/summary, /api/bottlenecks, etc.)
+│       │   ├── diagnostics.py     # LiveTrainingDiagnostics runtime monitor
+│       │   ├── gui.py             # VisualizerDesktopApp (PySide6 Qt GUI)
+│       │   └── __main__.py        # CLI runner (`python -m graphyco.visualizer`)
+│       └── tests/                 # Automated test suite (20 unit & integration tests)
+│           ├── test_dynamic_flow.py # Dynamic gradient flow unit tests (12 tests)
+│           ├── test_visualizer.py # Query engine & visualizer integration tests (8 tests)
+│           ├── test_torch_eval.py # Standalone architecture evaluation runner
+│           └── test_compare.py    # Comparative topology runner
+├── notebooks/                     # Interactive Jupyter notebooks
+│   ├── tutorials/                  # Step-by-step tutorial notebooks
+│   │   ├── 01_quickstart_and_model_evaluation.ipynb
+│   │   ├── 02_dynamic_gradient_monitoring.ipynb
+│   │   ├── 03_live_training_diagnostics.ipynb
+│   │   └── 04_query_engine_and_visualization.ipynb
+│   └── experiments/                # Empirical validation experiment notebooks
+│       ├── 01_static_topological_validation.ipynb
+│       ├── 02_dynamic_gradient_flow_validation.ipynb
+│       ├── 03_ablation_reachability_benchmark.ipynb
+│       ├── 04_model_initialization_and_export.ipynb
+│       └── 05_telemetry_query_and_analysis.ipynb
+├── validation/                     # Validation runners and benchmark data
+│   ├── validate_framework.py       # 6 controlled static topological validation protocols
+│   ├── validate_dynamic_flow.py    # 7 dynamic gradient-flow validation experiments (Q1–Q5)
+│   ├── canonical_benchmark.json    # Canonical 5-model benchmark data
+│   ├── dynamic_flow_benchmark.json # Dynamic flow gradient telemetry export
+│   ├── custom_model_benchmark.json # Custom architecture benchmark
+│   ├── dense_benchmark.json        # DenseNet benchmark
+│   ├── mlp_benchmark.json          # Sequential MLP benchmark
+│   └── resnet_benchmark.json       # ResNet Block benchmark
+├── pyproject.toml                  # Package configuration and CLI entrypoint
+├── research_understanding.md       # Mathematical research documentation
+└── README.md                       # Project documentation
+```
+
+---
+
+## Mathematical Specifications & Deterministic State Kernel
+
+### 1. Deterministic Fixed-Point Arithmetic
+
+All structural state metrics and invariant calculations are performed using 64-bit integer fixed-point arithmetic to guarantee bit-for-bit reproducibility:
+
+- **Fixed-Point Scale Factor:** $\text{SCALE} = 10{,}000$ (e.g., $1.0000 \to 10000$).
+- **Bounds:** Int64 integer range $[-2^{63}, 2^{63}-1]$.
+- **Checked Arithmetic:** Operations use `checked_add(a, b)` and `checked_mul(a, b)`, raising `OverflowError` if results cross bounds.
+- **Accumulator Guard:** Matrix multiplications and vector reductions employ an intermediate 128-bit accumulator (`safe_mul`) before dividing by `SCALE` to eliminate integer overflow during covariance operations:
+  $$\text{safe\_mul}(a, b) = \left\lfloor \frac{\text{int128}(a) \times \text{int128}(b)}{\text{SCALE}} \right\rfloor$$
+
+### 2. Resource Representation & Non-Negative Stress
+
+To avoid unconstrained algebraic cancellation, resources are defined as an ordered real pair in $\mathbb{R} \times \mathbb{R}_{\ge 0}$:
+
+$$R_v = (a_v, b_v)$$
+
+- $a_v \in \mathbb{R}$: Available operational capacity / activation baseline.
+- $b_v \in \mathbb{R}_{\ge 0}$: Accumulated structural stress, strictly non-negative ($\forall v \in V, b_v \ge 0$).
+- **Pathological State Condition:** A node is in a pathological state if and only if $b_v > 0$:
+  $$\text{pathological}(v) \iff b_v > 0$$
+- When $b_v$ exceeds a collapse threshold $\theta_{\text{collapse}}$, stress is redistributed via explicit governed operations, ensuring $\sum_{v} b_v$ is non-decreasing without an explicit discharge event.
+
+### 3. Seven Enforced Graph Invariants (`graphyco/core/invariants.py`)
+
+Validation function `validate_invariants(state: GraphState)` verifies that the graph satisfies all seven structural invariants:
+
+| Invariant | Rule Identifier | Formal Requirement |
+|---|---|---|
+| **INV-1** | `node_id_format` | Every node ID must match `^[a-zA-Z0-9_-]+$`. |
+| **INV-2** | `edge_integrity` | For every edge $e = (u, v)$, both $u \in V$ and $v \in V$. |
+| **INV-3** | `port_connectivity` | Every output port produced by a node must be consumed as an input port by $\ge 1$ node. |
+| **INV-4** | `node_uniqueness` | All node identifiers in $V$ must be distinct (no duplicates). |
+| **INV-5** | `graph_liveness` | The graph must contain at least one active node ($\exists v \in V: v.\text{active} = \text{True}$). |
+| **INV-6** | `attributes_nonempty` | Every node must contain $\ge 1$ descriptive attribute string. |
+| **INV-7** | `acyclic_critical_subgraph` | The critical operational subgraph $G_{\text{crit}} = (V, E_{\text{critical}})$ must be a Directed Acyclic Graph (DAG) with zero cycles. |
+
+Violation of any rule raises an explicit `InvariantViolationError(rule, detail)`.
+
+### 4. Dynamic State Transitions & Schur Complement Update
+
+When new operational nodes are introduced (e.g., dynamic splitting or expansion $V \to V+1$), the covariance matrix $\Sigma \in \mathbb{R}^{V \times V}$ expands to:
+
+$$\Sigma' = \begin{bmatrix} \Sigma & \mathbf{b} \\ \mathbf{b}^T & c \end{bmatrix}$$
+
+where $\mathbf{b} \in \mathbb{R}^V$ is the covariance between the new node and existing nodes, and $c \in \mathbb{R}$ is the node variance. The inverse $(\Sigma')^{-1}$ is computed in $O(V^2)$ rather than $O(V^3)$ via the Schur complement:
+
+$$(\Sigma')^{-1} = \begin{bmatrix} P + \frac{1}{S_{\text{safe}}} P \mathbf{b} \mathbf{b}^T P & -\frac{1}{S_{\text{safe}}} P \mathbf{b} \\ -\frac{1}{S_{\text{safe}}} \mathbf{b}^T P & \frac{1}{S_{\text{safe}}} \end{bmatrix}$$
+
+where $P = \Sigma^{-1}$ is the prior inverse, and $S_{\text{safe}}$ applies deterministic Tikhonov regularization against singularity:
+
+$$S_{\text{safe}} = \max\left(c - \mathbf{b}^T P \mathbf{b},\; \epsilon_{\min}\right)$$
+
+with $\epsilon_{\min} \in \text{DomainConstants}$.
+
+### 5. Transition Metrics: Gromov-Wasserstein vs. KL Divergence
+
+- **Topological Transitions (Variable Support):** When node splits, merges, or graph mutations alter the dimensionality of state space ($\mathcal{X}_N \to \mathcal{X}_{M}$), Kullback-Leibler divergence is undefined ($D_{\text{KL}} \to \infty$). Structural distance is computed via the Gromov-Wasserstein distance:
+  $$GW_p(\mu, \nu) = \left( \inf_{\gamma \in \Pi(\mu, \nu)} \iint |d_{\mathcal{X}}(x, x') - d_{\mathcal{Y}}(y, y')|^p \, d\gamma(x, y) \, d\gamma(x', y') \right)^{1/p}$$
+  To maintain temporal determinism, the Sinkhorn solver iteration count is bounded by a fixed invariant: $K_{\max} = \text{const} \in \text{DomainConstants}$.
+- **Parametric Transitions (Fixed Support):** For transformations preserving graph topology (e.g., capacity adjustments, weight updates, phase shifts), divergence is measured via standard discrete $D_{\text{KL}}$.
+
+### 6. Topological Observer Expressivity (Cycle Detection & GSN)
+
+Standard 1-Weisfeiler-Lehman (1-WL) graph isomorphism tests fail to detect cycles (e.g., cannot distinguish a 6-cycle from two disjoint 3-cycles). To preserve cycle sensitivity without the $O(V^k)$ memory explosion of $k$-WL ($k \ge 3$):
+- Cycles of length 3, 4, 5, and 6 are extracted deterministically via depth-first traversal during structural mutations.
+- The resulting counts form a static cycle feature vector $\mathbf{c}_v \in \mathbb{Z}^4$ attached directly to each node:
+  $$R_v = (a_v, b_v, \mathbf{c}_v)$$
+
+---
+
+## Static Topological Metrics (`graphyco/core/evaluation.py`)
+
+All metrics return scaled integer values ($\text{SCALE} = 10{,}000$):
+
+### 1. Graph Density ($D$)
+Ratio of directed edges present to maximum possible directed edges:
+$$D = \left\lfloor \frac{|E| \cdot \text{SCALE}}{|V|(|V|-1)} \right\rfloor$$
+
+### 2. Connectivity Coherence ($C$)
+Measures degree distribution uniformity across all nodes. Max variance $\text{MaxVar} = \frac{(N-1) \cdot \text{SCALE}^2}{N}$:
+$$C = \text{SCALE} - \left\lfloor \frac{\text{Var}(d)}{\text{MaxVar}} \cdot \text{SCALE} \right\rfloor, \quad C \in [0, \text{SCALE}]$$
+- $C = 10{,}000$ indicates identical degree distribution across all nodes (perfect balance).
+- Lower $C$ indicates concentrated hub architectures.
+
+### 3. Topological Bottleneck Ratio ($B$)
+Ratio of maximum node degree to mean node degree:
+$$B = \left\lfloor \frac{\max_i(d_i) \cdot \text{SCALE}}{\bar{d}} \right\rfloor$$
+- $B = 10{,}000$ ($1.0$) corresponds to perfectly uniform connectivity.
+- Elevated $B$ ($> 1.5$) identifies structural choke nodes.
+
+### 4. Perturbation Profile & Structural Perturbation Resilience ($R$)
+Local cascade cost per node $i$:
+$$\text{cost}_i = \max\left(1 + \left\lfloor \frac{d_i}{\text{SCALE}} \right\rfloor, 1\right) + \sum_{j \in \mathcal{N}(i)} \max\left(\left\lfloor \frac{d_j}{\text{SCALE}} \right\rfloor, 1\right)$$
+Structural perturbation resilience across graph order $N = |V|$:
+$$R = \left\lfloor \frac{N \cdot \text{SCALE}}{\sum_{i=1}^N \text{cost}_i} \right\rfloor$$
+
+### 5. Fan Balance & Dead Ratio
+- **Fan-in / Fan-out Imbalance:**
+  $$\text{imbalance}_i = \left\lfloor \frac{|\text{fan\_in}_i - \text{fan\_out}_i| \cdot \text{SCALE}}{\text{fan\_in}_i + \text{fan\_out}_i} \right\rfloor$$
+- **Dead Ratio:** Fraction of isolated nodes with zero incoming and outgoing edges:
+  $$\text{dead\_ratio} = \left\lfloor \frac{|V_{\text{isolated}}| \cdot \text{SCALE}}{|V|} \right\rfloor$$
+
+---
+
+## Dynamic Gradient-Flow Telemetry (`graphyco/observer/`)
+
+### 1. Tensor Statistics Engine (`TensorStats`)
+Computes observational metrics over detached float64 representations without modifying autograd computation:
+- **Element Count:** $N = \text{numel}(T)$
+- **Norms:** $L_1 = \sum |x_i|$, $L_2 = \sqrt{\sum x_i^2}$, $\text{RMS} = \frac{L_2}{\sqrt{N}}$
+- **Moments:** Mean $\mu$, Standard Deviation $\sigma$, Minimum, Maximum
+- **Sparsity & Health:** Zero-element fraction ($\frac{\sum \mathbb{I}[x_i = 0]}{N}$), Non-finite fraction ($\frac{\sum \mathbb{I}[\neg \text{isfinite}(x_i)]}{N}$)
+- **Fixed-point RMS:** $\text{round}(\text{RMS} \cdot \text{SCALE})$
+
+### 2. Edge Gradient Attenuation (`compute_gradient_attenuation`)
+For directed edge $e = (\text{source} \to \text{target})$:
+- **Forward Ratio:**
+  $$\alpha = \frac{\|g_{\text{source}}\|_2}{\|g_{\text{target}}\|_2 + \epsilon}$$
+- **Backward Ratio:**
+  $$\beta = \frac{\|g_{\text{target}}\|_2}{\|g_{\text{source}}\|_2 + \epsilon}$$
+- **Log Attenuation:**
+  $$\Delta = \ln\left(\frac{\|g_{\text{source}}\|_2 + \epsilon}{\|g_{\text{target}}\|_2 + \epsilon}\right)$$
+  - $\Delta < 0$: Gradient attenuates as it flows backward toward the input.
+  - $\Delta > 0$: Gradient amplifies along the backward path.
+
+### 3. Dynamic Gradient Bottleneck ($G_{\max}$)
+Concentration of backward gradient energy relative to uniform flow:
+$$q_i = \frac{g_i}{\frac{1}{|V|}\sum_{j \in V} g_j + \epsilon}, \quad G_{\max} = \max_{i \in V} q_i, \quad \text{choke\_node} = \arg\max_{i \in V} q_i$$
+where $g_i$ is the normalized gradient RMS of node $i$.
+
+### 4. Forward-Backward Alignment (`compute_forward_backward_alignment`)
+Quantifies relationship between activation magnitude $a_i = \text{RMS}(A_i)$ and gradient magnitude $g_i = \text{RMS}(G_i)$:
+- **Local Sensitivity Ratio:** $r_i = \frac{g_i}{a_i + \epsilon}$
+- **Spearman Rank Correlation:** $\rho_{AG} = \text{spearmanr}(\mathbf{a}, \mathbf{g})$
+- **Pearson Linear Correlation:** $r_{AG} = \text{pearsonr}(\mathbf{a}, \mathbf{g})$
+
+### 5. Four-Quadrant Structural-Functional Classification
+Nodes are partitioned by median splits on static topology perturbation score ($t_i$) and dynamic gradient RMS ($g_i$):
+
+| Quadrant | Structural Importance | Gradient Flux | Functional Role |
+|---|---|---|---|
+| **Type I** | High ($t_i \ge \tilde{t}$) | High ($g_i \ge \tilde{g}$) | **Dual Hub:** Central structural router carrying high computational signal. |
+| **Type II** | High ($t_i \ge \tilde{t}$) | Low ($g_i < \tilde{g}$) | **Structural Hub / Low Flux:** High connectivity but suppressed gradient flow. |
+| **Type III** | Low ($t_i < \tilde{t}$) | High ($g_i \ge \tilde{g}$) | **Dynamic Conduit:** Peripheral structure absorbing disproportionate gradient flux. |
+| **Type IV** | Low ($t_i < \tilde{t}$) | Low ($g_i < \tilde{g}$) | **Peripheral:** Low structural impact and low gradient activity. |
+
+### 6. Temporal Stability & Anomaly Detection
+Tracks node behavior across execution steps $t = 1, \dots, T$:
+- **Temporal Coefficient of Variation (CV):**
+  $$\text{CV}_i = \frac{\sigma_{g_i}}{|\mu_{g_i}| + \epsilon}$$
+- **Behavioral Classification:**
+  - `intermittent`: Zero-gradient fraction $> 0.30$.
+  - `unstable`: $\text{CV}_i > 0.50$.
+  - `consistently_strong`: $\mu_{g_i} \ge \text{median}(\boldsymbol{\mu}_g)$ with low variance.
+  - `consistently_weak`: $\mu_{g_i} < \text{median}(\boldsymbol{\mu}_g)$.
+- **Anomaly Detection:**
+  - **Vanishing Nodes:** $g_i < \tau_{\text{low}}$ (default absolute $10^{-6}$ or relative $0.01 \times \tilde{g}$).
+  - **Exploding Nodes:** $g_i > \tau_{\text{high}}$ (default absolute $100.0$ or relative $100.0 \times \tilde{g}$).
+
+---
+
+## Bridge Layer Architecture (`graphyco/bridge/`)
+
+### 1. PyTorch FX Tracing & Module Extraction (`torch_bridge.py`)
+- `trace_to_graph(model, concrete_args)`: Executes `torch.fx.symbolic_trace`, converting PyTorch FX IR nodes into `Node` primitives and dataflow arguments into directed `Edge` primitives.
+- `module_to_graph(model)`: Fallback recursive `nn.Module` inspector when symbolic tracing is unsupported (e.g., dynamic control flow, third-party C++ bindings).
+- `evaluate_model(model, mode="trace")`: Translates model and returns static topological metrics.
+
+### 2. Autograd Execution Bridge (`grad_bridge.py`)
+- `DynamicExecutionBridge`: Manages forward/backward execution, recording tensor stats on each step.
+  - Intercepts activation tensors via `FXGradObserver` or forward hooks.
+  - Intercepts backward gradients using `torch.nn.Module.register_full_backward_hook` and autograd hooks on edge tensors.
+  - Generates unified `DynamicGraphState` containing $G_t = (V, E, X_t, A_t, G_t)$.
+  - Supports export to structured JSON (`to_json()`) and CSV tables (`to_csv_nodes()`).
+- `LiveTrainingMonitor`: Non-invasive context manager for training loops:
+  ```python
+  monitor = LiveTrainingMonitor(model, log_interval=5)
+  with monitor.observe(step):
+      loss.backward()
+  ```
+
+---
+
+## Empirical Validation Benchmark Results
+
+### 1. Static Validation Suite (`validation/validate_framework.py`)
+
+Six controlled protocols executed across canonical architecture families:
+
+#### Protocol 1: Architectural Discriminability
+Evaluated on FX-traced operational graphs:
+
+| Architecture | Nodes ($|V|$) | Edges ($|E|$) | Density ($D$) | Coherence ($C$) | Bottleneck ($B$) | Resilience ($R$) |
+|---|---|---|---|---|---|---|
+| **Sequential MLP** | 9 | 8 | 0.1111 | 0.9970 | 1.1251 | 0.3600 |
+| **Feedforward CNN** | 9 | 8 | 0.1111 | 0.9970 | 1.1251 | 0.3600 |
+| **ResNet Block** | 8 | 9 | 0.1607 | 0.9956 | 1.5000 | 0.3333 |
+| **DenseNet Block** | 12 | 17 | 0.1287 | 0.9951 | 1.7653 | 0.2608 |
+| **U-Net Toy** | 14 | 14 | 0.0769 | 0.9985 | 1.5000 | 0.3333 |
+| **Self-Attention Toy** | 10 | 12 | 0.1333 | 0.9951 | 1.6673 | 0.2941 |
+
+*Key Result:* Sequential MLP and CNN produce identical topological metrics ($B=1.1251, R=0.3600$) due to identical sequential dependency structures. DenseNet exhibits maximum connectivity dispersion ($B=1.7653$), while Self-Attention exhibits highest concentration ($B=1.6673$).
+
+#### Protocol 2: Controlled Synthetic Confounder Isolation
+Fixed-size graphs with identical order $|V|=10$ and size $|E|=9$:
+
+| Topology Family | $|V|$ | $|E|$ | Density | Coherence | Bottleneck | Resilience |
+|---|---|---|---|---|---|---|
+| **Linear Chain** | 10 | 9 | 0.1000 | 0.9979 | 1.1115 | 0.3571 |
+| **Star (Single Hub)** | 10 | 9 | 0.1000 | 0.9210 | 5.0025 | 0.3448 |
+| **Binary Tree** | 10 | 9 | 0.1000 | 0.9896 | 1.6673 | 0.3571 |
+| **Bottleneck Funnel** | 10 | 9 | 0.1000 | 0.9814 | 2.2231 | 0.3571 |
+
+*Key Result:* Under identical $|V|$ and $|E|$, the Star topology yields maximum bottleneck ($5.0025$) and lowest coherence ($0.9210$), proving metrics measure connectivity geometry rather than node/edge counts.
+
+#### Protocol 3: Width-Scale Invariance
+Tested on 4-layer MLPs across parameter scales:
+- **Width 64 (13,130 parameters):** $|V|=9, |E|=8, B=1.1251, C=0.9970$.
+- **Width 512 (793,098 parameters):** $|V|=9, |E|=8, B=1.1251, C=0.9970$.
+*Key Result:* A $\sim 60\times$ increase in parameter volume yields identical topological metrics, proving decoupling of topology from parameter scale.
+
+#### Protocol 4: Metric Correlation & Non-Collinearity (Pearson $r$)
+
+| Metric | Density | Coherence | Bottleneck | Resilience |
+|---|---|---|---|---|
+| **Density** | $1.000$ | $-0.936$ | $0.328$ | $-0.389$ |
+| **Coherence** | $-0.936$ | $1.000$ | $-0.559$ | $0.666$ |
+| **Bottleneck** | $0.328$ | $-0.559$ | $1.000$ | $-0.928$ |
+| **Resilience** | $-0.389$ | $0.666$ | $-0.928$ | $1.000$ |
+
+#### Protocol 5: Systematic Perturbation Predictive Validity (Node Ablation)
+Evaluates whether topological perturbation scores predict empirical graph reachability collapse under single-node deletion:
+- **ResNet Block:** Spearman $\rho = 0.7555$ ($p = 0.0495$), Pearson $r = 0.7783$ ($p = 0.0392$).
+- **U-Net Toy:** Spearman $\rho = 0.4513$ ($p = 0.1216$), Pearson $r = 0.3284$ ($p = 0.2732$).
+
+#### Protocol 6: Asymptotic Graph Order Scaling ($N \in \{10, 25, 50, 100\}$)
+- **Linear Chain:** $B \to 1.0$ asymptotically ($1.1115 \to 1.0150$).
+- **Star Graph:** $B$ scales linearly with $\frac{N}{2}$ ($5.0025 \to 50.2512$).
+
+---
+
+### 2. Dynamic Flow Benchmark Suite (`validation/validate_dynamic_flow.py`)
+
+Seven dynamic protocols addressing core research questions Q1–Q5 across canonical models:
+
+#### Architecture-Level Dynamic Summary Table
+
+| Architecture | Density | Coherence | Bottleneck | Resilience | Act Flow (RMS) | Grad Flow (RMS) | $G_{\max}$ | $\rho(A, G)$ | Mean CV |
+|---|---|---|---|---|---|---|---|---|---|
+| **Sequential MLP** | 0.1111 | 0.9970 | 1.1251 | 0.3600 | 0.3011 | 0.0036 | 3.5114 | $-1.0000$ | 0.0409 |
+| **ResNet Block** | 0.1428 | 0.9956 | 1.5000 | 0.3333 | 0.6126 | 0.0045 | 2.8582 | $-0.2182$ | 0.0243 |
+| **DenseBlock** | 0.1287 | 0.9951 | 1.7653 | 0.2608 | 0.5014 | 0.0034 | 3.6713 | $-0.3825$ | 0.0220 |
+| **U-Net Toy** | 0.0769 | 0.9985 | 1.5000 | 0.3333 | 0.2512 | 0.0031 | 4.0313 | $-0.6784$ | 0.0534 |
+| **Self-Attention Toy** | 0.1333 | 0.9951 | 1.6673 | 0.2941 | 0.5895 | 0.0039 | 3.2122 | $+0.2997$ | 0.0365 |
+
+#### Findings for Core Research Questions (Q1–Q5)
+
+1. **Q1 (Structural vs. Functional Importance):**
+   Across all 53 evaluated nodes, Spearman correlation between static structural centrality and dynamic gradient magnitude is $\rho = -0.0583$ ($p = 0.678$). High structural connectivity does not guarantee high gradient flux. The empirical emergence of Type II nodes (high topology, low gradient) and Type III nodes (low topology, high gradient) confirms structural-functional divergence.
+2. **Q2 (Structural vs. Gradient Bottleneck):**
+   Static topological bottleneck $B$ identifies structural routing fan-in choke points (e.g., skip merges), whereas dynamic concentration $G_{\max}$ identifies computational signal concentration points (e.g., final linear projections `net_6`, `out`, `head`).
+3. **Q3 (Gradient Attenuation Across Paths):**
+   Edge log ratios ($\Delta$) reveal attenuation dynamics along skip paths. In ResNet Block, gradient ratio between parallel paths directly quantifies the signal fraction conveyed via skip vs. residual conv branches.
+4. **Q4 (Forward-Backward Alignment):**
+   Correlation between forward activation magnitude and backward gradient magnitude is negative or weak across standard models (MLP $\rho = -1.0000$, U-Net $\rho = -0.6784$, ResNet $\rho = -0.2182$, Self-Attention $\rho = +0.2997$), showing that activation scale is an unreliable proxy for gradient flux.
+5. **Q5 (Static Perturbation vs. Dynamic Stability):**
+   Static perturbation resilience correlates positively with reachability retention under ablation ($\rho = 0.1699$), verifying that topological fragility scores predict structural disconnection under node removal.
+
+---
+
+## Quickstart & Usage
+
+### 1. One-Line Model Profiling and Web Visualization
+
+```python
+import torch
+import torch.nn as nn
+from graphyco import visualize
+
+model = nn.Sequential(
+    nn.Linear(64, 128),
+    nn.ReLU(),
+    nn.Linear(128, 10)
+)
+x = torch.randn(8, 64)
+
+# Profiles 5 forward/backward steps, exports benchmark JSON, and starts local server
+app = visualize(model, inputs=x, steps=5, port=8000)
+```
+
+### 2. In-Memory Query Engine
+
+```python
+from graphyco import QueryEngine
+
+engine = QueryEngine("validation/dynamic_flow_benchmark.json")
+
+# Invariant and metric summary table
+summary_df = engine.describe()
+print(summary_df)
+
+# Side-by-side architecture comparison
+comparison_df = engine.describe(siblings=True)
+print(comparison_df)
+
+# Retrieve bottleneck choke points
+for b in engine.get_bottlenecks():
+    print(f"{b['architecture']}: G_max={b['gradient_bottleneck_gmax']:.2f} at node '{b['bottleneck_node']}'")
+```
+
+### 3. Non-Invasive Live Training Diagnostics
+
+```python
+import torch
+import torch.nn as nn
+from graphyco import LiveTrainingMonitor
+
+model = nn.Sequential(nn.Linear(64, 32), nn.ReLU(), nn.Linear(32, 10))
+optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
+criterion = nn.CrossEntropyLoss()
+
+monitor = LiveTrainingMonitor(model, log_interval=5)
+
+for step in range(20):
+    x = torch.randn(16, 64)
+    y = torch.randint(0, 10, (16,))
+
+    with monitor.observe(step):
+        optimizer.zero_grad()
+        loss = criterion(model(x), y)
+        loss.backward()
+        optimizer.step()
+
+    if monitor.has_new_data():
+        bneck = monitor.get_latest_bottleneck()
+        print(f"Step {step}: Choke Node = {bneck.get('bottleneck_node')} (G_max={bneck.get('max_concentration'):.2f})")
+```
+
+---
+
+## CLI Reference
+
+Execute commands via the package CLI entrypoint:
+
+```bash
+# Query all architectural bottlenecks from benchmark JSON
+python -m graphyco.visualizer --json validation/dynamic_flow_benchmark.json --query bottlenecks
+
+# Query invariant summary for a specific model architecture
+python -m graphyco.visualizer --json validation/dynamic_flow_benchmark.json --query summary --arch "ResNet Block"
+
+# Launch local HTTP REST server
+python -m graphyco.visualizer --json validation/dynamic_flow_benchmark.json --server --port 8080
+
+# Launch native PySide6 desktop GUI
+python -m graphyco.visualizer --json validation/dynamic_flow_benchmark.json --gui
+
+# Profile canonical model and export benchmark JSON
+python -m graphyco.visualizer --model resnet --steps 10 --export validation/resnet_benchmark.json
+```
+
+---
+
+## Verification & Test Execution
+
+Run the automated test suite (20 unit and integration tests):
+
+```bash
+pytest
+```
+
+Run standalone evaluation runners:
+
+```bash
+python src/graphyco/tests/test_torch_eval.py
+python src/graphyco/tests/test_compare.py
+```
+
+Run the 6 static topological validation protocols:
+
+```bash
+python validation/validate_framework.py
+```
+
+Run the 7 dynamic gradient-flow benchmark experiments:
+
+```bash
+python validation/validate_dynamic_flow.py
+```
+
+---
+
+## Interactive Notebook Catalog (`notebooks/`)
+
+### Tutorials (`notebooks/tutorials/`)
+- `01_quickstart_and_model_evaluation.ipynb`: FX graph tracing, invariant verification, and static metric computation.
+- `02_dynamic_gradient_monitoring.ipynb`: Dynamic telemetry extraction, edge attenuation calculations, and JSON export.
+- `03_live_training_diagnostics.ipynb`: Live training loop monitoring with real-time bottleneck detection.
+- `04_query_engine_and_visualization.ipynb`: Programmatic querying, REST API access, and dashboard integration.
+
+### Experiments (`notebooks/experiments/`)
+- `01_static_topological_validation.ipynb`: Interactive execution of Protocols 1–6 from `validate_framework.py`.
+- `02_dynamic_gradient_flow_validation.ipynb`: Interactive execution of Experiments A–G addressing Questions Q1–Q5.
+- `03_ablation_reachability_benchmark.ipynb`: BFS reachability simulation engine under node ablation.
+- `04_model_initialization_and_export.ipynb`: Multi-architecture telemetry generation and standalone export.
+- `05_telemetry_query_and_analysis.ipynb`: Offline query analysis and invariant cross-comparison.