Metadata-Version: 2.4
Name: egora-rrl
Version: 0.2.1
Summary: Rotation-Retention Law — Knowledge loss is proportional to representational rotation in 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,egora,fine-tuning,knowledge-loss,lora,pytorch,representational-rotation,rotation-retention-law
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

# Rotation-Retention Law (EgoRA-RRL)

[![PyPI version](https://img.shields.io/pypi/v/egora-rrl)](https://pypi.org/project/egora-rrl/)
[![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 provides tools for the **Rotation-Retention Law**: the empirical finding that knowledge loss in fine-tuned language models is proportional to representational rotation.

$$\Delta M \propto \bar{\theta} = \mathbb{E}[\arccos(\cos\_\text{sim}(W_{\text{base}}, W_{\text{tuned}}))]$$

## Installation

```bash
pip install egora-rrl
```

This installs `egora` with diagnostics dependencies and re-exports the rotation analysis API.

## The Law

The Rotation-Retention Law states that benchmark performance change ($\Delta M$) after fine-tuning is proportional to the mean representational rotation ($\bar{\theta}$) across attention heads:

| Mean Rotation | Prediction | Interpretation |
|---------------|------------|----------------|
| $\bar{\theta} < 3°$ | ✅ Safe | Knowledge well preserved |
| $3° < \bar{\theta} < 5°$ | ⚠️ Warning | Check downstream benchmarks |
| $\bar{\theta} > 5°$ | ❌ Danger | Significant knowledge loss expected |

The proportionality constant $k \approx 0.68$ pp/degree was measured on 1B-parameter models.

## Quick Start

```python
from egora_rrl import (
    compute_head_geometry,
    rotation_retention_predict,
    classify_rotation_risk,
)

# Measure rotation
results = compute_head_geometry(base_model, tuned_model)
theta_bar = results['theta_bar_deg']

# Predict benchmark impact
predicted_delta = rotation_retention_predict(theta_bar)
risk = classify_rotation_risk(theta_bar)

print(f"Mean rotation: {theta_bar:.2f}°")
print(f"Predicted MMLU Δ: {predicted_delta:.2f} pp")
print(f"Risk level: {risk}")
```

## Learning Modes

Each attention head is classified into one of four learning modes based on rotation angle and magnitude ratio:

| Mode | Rotation | Magnitude | Interpretation |
|------|----------|-----------|----------------|
| **Preserved** | < 5° | ≈ 1.0 | Head unchanged, knowledge intact |
| **Additive** | < 5° | > 1.0 | New knowledge added without destroying old |
| **Substitutive** | > 5° | any | Old representations replaced with new |
| **Damaged** | > 5° | < 0.9 | Knowledge destroyed, capacity lost |

## Visualization

```python
from egora_rrl import plot_rotation_report

fig = plot_rotation_report(results)
fig.savefig("rrl_report.png", dpi=150)
```

## CLI

```bash
egora diagnose meta-llama/Llama-3.2-1B ./my-finetuned-model --plot
```

## Main Package

For the full EgoRA library (adapters, entropy governor, training), install:

```bash
pip install egora
```

## 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).
