Metadata-Version: 2.4
Name: egora-diagnostics
Version: 0.3.0
Summary: Rotation-Retention Law analysis, knowledge mapping, and gradient alignment diagnostics for fine-tuned neural networks. Companion to the egora package.
Project-URL: Homepage, https://github.com/ArsSocratica/EgoRA
Project-URL: Documentation, https://github.com/ArsSocratica/EgoRA#readme
Project-URL: Repository, https://github.com/ArsSocratica/EgoRA
Project-URL: Issues, https://github.com/ArsSocratica/EgoRA/issues
Author-email: Mark Dillerop <mark@dillerop.com>
License: AGPL-3.0-or-later
License-File: LICENSE
License-File: LICENSE-ACADEMIC
License-File: NOTICE
Keywords: alignment,deep-learning,diagnostics,egora,fine-tuning,interpretability,knowledge-map,pytorch,rotation,transformer
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: egora>=0.1.0
Requires-Dist: numpy>=1.21
Requires-Dist: torch>=2.0
Provides-Extra: all
Requires-Dist: datasets>=2.0; extra == 'all'
Requires-Dist: matplotlib>=3.5; extra == 'all'
Requires-Dist: scipy>=1.7; extra == 'all'
Provides-Extra: datasets
Requires-Dist: datasets>=2.0; extra == 'datasets'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: plots
Requires-Dist: matplotlib>=3.5; extra == 'plots'
Requires-Dist: scipy>=1.7; extra == 'plots'
Description-Content-Type: text/markdown

# EgoRA Diagnostics — Rotation-Retention Law & Knowledge Mapping

[![PyPI version](https://img.shields.io/pypi/v/egora-diagnostics)](https://pypi.org/project/egora-diagnostics/)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

Advanced diagnostic tools for analyzing fine-tuned neural networks. Companion package to [`egora`](https://pypi.org/project/egora/).

## Installation

```bash
pip install egora-diagnostics
```

With plotting and dataset support:

```bash
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

```python
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.

```python
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.

```python
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`](https://pypi.org/project/egora-diagnostics/) |
| 💻 **GitHub** | [ArsSocratica/EgoRA](https://github.com/ArsSocratica/EgoRA) |
| 📄 **Paper** | [arXiv:2602.05192](https://arxiv.org/abs/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](https://github.com/ArsSocratica/EgoRA/blob/main/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**: mark@dillerop.com
