# ARC - Autonomous Recovery Controller

[![PyPI version](https://badge.fury.io/py/arc-training.svg)](https://badge.fury.io/py/arc-training)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

**A real-time fault-tolerance framework for neural network training.**

ARC monitors training signals — gradients, loss curvature, Fisher Information — to predict and recover from failures before they crash your run. It uses a Mamba-based state-space model with Evidential Deep Learning for uncertainty-aware failure prediction.

## Key Results

| Metric            | ARC v4.0                                                 |
| ----------------- | -------------------------------------------------------- |
| **Recovery Rate** | 100% on core failure types (NaN, Inf, explosion)         |
| **Overhead**      | ~35% (small models), higher on larger models             |
| **vs torchft**    | 3/3 vs 1/3 recoveries                                    |
| **Models Tested** | YOLOv11, DINOv2, Llama-Style, SD-UNet (up to 33M params) |

## Quick Start

### Installation

```bash
pip install arc-training
```

### Basic Usage

```python
from arc import Arc

# Wrap your model and optimizer
controller = Arc(model, optimizer)

# Training loop
for batch in dataloader:
    loss = model(batch)

    # ARC monitors, predicts, and recovers automatically
    action = controller.step(loss)

    if not action.rolled_back:
        loss.backward()
        optimizer.step()
```

### Lightning Integration

```python
from arc import ArcCallback

trainer = pl.Trainer(
    callbacks=[ArcCallback()]
)
```

## Configurations

| Config       | Overhead | Use Case                |
| ------------ | -------- | ----------------------- |
| **ARC Lite** | Lower    | Production training     |
| ARC Full     | Higher   | Debugging unstable runs |

## Failure Coverage

| Failure Type       | Detection | Recovery | Status         |
| ------------------ | --------- | -------- | -------------- |
| NaN/Inf Loss       | Yes       | Yes      | Validated      |
| Loss Explosion     | Yes       | Yes      | Validated      |
| Gradient Explosion | Yes       | Yes      | Validated      |
| OOM (all stages)   | Yes       | Yes      | Validated      |
| Accuracy Collapse  | Yes       | Partial  | Detection only |
| Mode Collapse      | Yes       | Partial  | Detection only |

## Benchmarks

```
Core Failure Recovery: 100% (NaN, Inf, explosion across all tests)
Modern Model Recovery: 5/8 induced failures recovered
torchft Comparison:    ARC 3/3 vs torchft 1/3
Models Tested:         YOLOv11, DINOv2-Small, Llama-Style, SD-UNet
```

## Links

- [Efficiency Report](ARC_EFFICIENCY_REPORT.md)

## Citation

```bibtex
@software{arc2026,
  title={ARC: Autonomous Recovery Controller for Neural Network Training},
  author={Kaushik, Aryan},
  year={2026},
  url={https://github.com/a-kaushik2209/ARC}
}
```

## License

AGPL-3.0 License - see [LICENSE](LICENSE) for details.

Copyright (c) 2026 Aryan Kaushik. All rights reserved.
