egora-diagnostics 0.3.0

Rotation-Retention Law analysis, knowledge mapping, and gradient alignment diagnostics for fine-tuned neural networks. Companion to the egora package.

EgoRA Diagnostics — Rotation-Retention Law & Knowledge Mapping

Advanced diagnostic tools for analyzing fine-tuned neural networks. Companion package to egora.

Installation

pip install egora-diagnostics

With plotting and dataset support:

pip install egora-diagnostics[all]

Modules

1. Threshold Analysis (Rotation-Retention Law)

Tests the empirical law $\Delta M \propto \bar{\theta}$:

• Dimensionality-aware critical threshold: $\theta_{\text{crit}} = \arcsin(1/\sqrt{d_{\text{head}}})$
• Golden ratio $k$-check
• Phase transition detection
• Cross-architecture validation

from egora import compute_head_geometry
from egora_diagnostics import run_threshold_analysis

geo = compute_head_geometry(base_model, tuned_model)
results = run_threshold_analysis(
    geo, model_name="llama_8b",
    mmlu_base=63.42, mmlu_after=62.86,
    output_dir="analysis/",
)

2. Knowledge Map

Logit lens, attention probing, and Knowledge Concentration Index (KCI) to locate where knowledge lives in the model.

from egora_diagnostics import run_knowledge_map

summary = run_knowledge_map(model, tokenizer, output_dir="analysis/")

3. Alignment Landscape

Per-head gradient alignment between fine-tuning and capability-preservation directions. Identifies critical heads.

from egora_diagnostics import run_alignment_landscape

landscape = run_alignment_landscape(
    model, tokenizer,
    finetune_data=ft_loader,
    capability_data=cap_loader,
)

Resources

	Link
📦 PyPI	pip install egora-diagnostics
💻 GitHub	ArsSocratica/EgoRA
📄 Paper	arXiv:2602.05192

License

This software is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), with an Additional Permission for Academic Use pursuant to AGPL Section 7.

• Academic use: Free, no copyleft obligations, citation required. See LICENSE-ACADEMIC.
• Commercial use: Requires both a software license and a patent license.

Patent Notice

The methods implemented in this software are covered by U.S. Provisional Patent Application No. 64/024,742, filed April 1, 2026, by Mark Dillerop.

Contact: [e-mail]