Metadata-Version: 2.4
Name: egora-diagnostics
Version: 0.2.1
Summary: EgoRA Diagnostics — Rotation geometry analysis and visualization for fine-tuned language models. Companion package for egora.
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: PyPI (main package), https://pypi.org/project/egora/
Author-email: Mark Dillerop <mark@dillerop.com>
License: AGPL-3.0-or-later
Keywords: deep-learning,diagnostics,egora,fine-tuning,knowledge-preservation,pytorch,rotation-geometry
Classifier: Development Status :: 4 - Beta
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: egora[diagnostics]>=0.2.0
Description-Content-Type: text/markdown

# EgoRA Diagnostics

[![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)

**Companion package for [egora](https://pypi.org/project/egora/).**

This package installs `egora` with diagnostics dependencies (matplotlib, scipy) and re-exports the diagnostics API for convenience.

## Installation

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

This is equivalent to:

```bash
pip install "egora[diagnostics]"
```

## What You Get

- **Rotation Geometry Analysis**: `compute_head_geometry()` — per-head rotation angles, learning mode classification
- **Interhead Diversity**: `compute_interhead_diversity()` — similarity matrix across attention heads
- **Publication-Quality Plots**: `plot_rotation_report()` — combined 4-panel report figure
- **CLI Tool**: `egora diagnose base_model tuned_model --plot`

## Quick Start

```python
from egora_diagnostics import (
    compute_head_geometry,
    compute_interhead_diversity,
    save_geometry,
    plot_rotation_report,
    plot_rotation_heatmap,
    plot_layer_profile,
    plot_mode_distribution,
)

# Analyze rotation between base and fine-tuned model
results = compute_head_geometry(base_model, tuned_model)
print(f"Mean rotation: {results['theta_bar_deg']:.2f}°")

# Generate report
fig = plot_rotation_report(results)
fig.savefig("rotation_report.png", dpi=150)
```

## Main Package

For the full EgoRA library (adapters, entropy governor, PEFT compatibility), install the main package:

```bash
pip install egora
```

See [github.com/ArsSocratica/EgoRA](https://github.com/ArsSocratica/EgoRA) for full documentation.

## Citation

```bibtex
@article{dillerop2026rotation,
  title={The Rotation-Retention Law: Knowledge Loss Is Proportional to 
         Representational Rotation in Fine-Tuned Language Models.
         With EgoRA: Entropy-Governed Orthogonality Regularization 
         for Adaptation},
  author={Dillerop, Mark},
  year={2026},
  note={Preprint}
}
```

## License

AGPL-3.0-or-later with Academic Additional Permission.
See [LICENSE-ACADEMIC](https://github.com/ArsSocratica/EgoRA/blob/main/LICENSE-ACADEMIC).
