Metadata-Version: 2.4
Name: aletheia-lora
Version: 0.1.2
Summary: Gradient-guided layer selection for efficient LoRA fine-tuning
Author-email: Abdulmalek Saket <abdulmalek@fenicebrand.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/aletheiaprotocol-ai/aletheia-lora
Project-URL: Repository, https://github.com/aletheiaprotocol-ai/aletheia-lora
Project-URL: Paper, https://arxiv.org/abs/2604.15351
Project-URL: DOI, https://doi.org/10.48550/arXiv.2604.15351
Project-URL: HuggingFace, https://huggingface.co/aletheiaprotocol/aletheia-lora
Project-URL: Issues, https://github.com/aletheiaprotocol-ai/aletheia-lora/issues
Keywords: lora,peft,fine-tuning,gradient,layer-selection,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: transformers>=4.36.0
Requires-Dist: peft>=0.7.0
Provides-Extra: eval
Requires-Dist: datasets>=2.14.0; extra == "eval"
Requires-Dist: human-eval; extra == "eval"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: ruff>=0.2.0; extra == "dev"
Dynamic: license-file

# Aletheia-LoRA

**Gradient-guided layer selection for efficient LoRA fine-tuning.**

[![arXiv](https://img.shields.io/badge/arXiv-2604.15351-b31b1b.svg)](https://arxiv.org/abs/2604.15351)
[![DOI](https://img.shields.io/badge/DOI-10.48550%2FarXiv.2604.15351-blue.svg)](https://doi.org/10.48550/arXiv.2604.15351)
[![Hugging Face](https://img.shields.io/badge/Hugging%20Face-Method%20Card-yellow.svg)](https://huggingface.co/aletheiaprotocol/aletheia-lora)
[![License](https://img.shields.io/badge/License-Apache--2.0-green.svg)](LICENSE)

Aletheia identifies the most informative transformer layers with a lightweight gradient probe, then applies LoRA adapters only to those layers. Across the finalized Research Line A evidence pack, this yields a **15-28% training speedup** with **bounded extra forgetting and broadly matched downstream behavior** across **14 successful models** from **8 architecture families** spanning **0.5B to 72B parameters**.

Paper: [Aletheia: Gradient-Guided Layer Selection for Efficient LoRA Fine-Tuning Across Architectures](https://arxiv.org/abs/2604.15351)

DOI: [10.48550/arXiv.2604.15351](https://doi.org/10.48550/arXiv.2604.15351)

Hugging Face card: [aletheiaprotocol/aletheia-lora](https://huggingface.co/aletheiaprotocol/aletheia-lora)

Evidence dataset: [aletheiaprotocol/aletheia-lora-evidence](https://huggingface.co/datasets/aletheiaprotocol/aletheia-lora-evidence)

## Installation

Until the package is published to PyPI, install it from source:

```bash
git clone https://github.com/aletheiaprotocol-ai/aletheia-lora.git
cd aletheia-lora
python -m pip install -e ".[dev]"
```

## Quick Start

```python
import torch
from aletheia_lora import gradient_probe, select_layers, apply_aletheia_lora
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import get_peft_model

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-3B", torch_dtype="auto")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-3B")

# 1. Measure per-layer importance with a short gradient probe.
layer_scores = gradient_probe(
    model=model,
    dataset=train_dataset,       # tokenized HF Dataset with input_ids + attention_mask
    num_layers=36,
    probe_batches=5,
    chunk_size=8,
)

# 2. Select the top 50% most informative layers.
selected_layers = select_layers(layer_scores, top_pct=50)

# 3. Apply LoRA only to the selected layers.
peft_config = apply_aletheia_lora(
    model=model,
    selected_layers=selected_layers,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
    r=16,
    lora_alpha=32,
)
model = get_peft_model(model, peft_config)
```

To use the paper-style asymmetric attention/MLP allocation:

```python
peft_config = apply_aletheia_lora(
    model=model,
    selected_layers=selected_layers,
    attention_r=16,
    mlp_r=64,
)
```

## Supported Claim

Use this wording:

> Aletheia provides a reproducible training-efficiency improvement over standard LoRA across multiple model families and scales, with bounded extra forgetting on downstream benchmarks.

This package supports that finished narrow claim. It does not claim:

- universal replacement for every LoRA setup
- better quality on every model and every metric
- compression better than quantization
- proof of the full Aletheia or NEXUS paradigm

## How It Works

1. **Gradient probe**: computes per-layer gradient norms on a small probe batch set with bounded memory usage.
2. **Layer selection**: ranks layers by gradient magnitude and keeps the top-k percent.
3. **Selective LoRA**: applies standard PEFT `LoraConfig` only to the selected layers.

## Evidence Summary

- **81 experiment rows** across 14 successful models and 8 architecture families
- **100% per-model speed win rate** in the main speed campaign
- **23.1% mean speedup** in the strongest frozen campaign
- **Bounded extra forgetting** on MMLU, GSM8K, and HumanEval under the narrow-claim framing
- **Scale range** from 0.5B to 72B parameters, including a MoE model

## Repository Contents

| Path | Purpose |
|------|---------|
| `src/aletheia_lora/` | Core library: probe, layer selection, and PEFT config builder |
| `examples/quick_start.py` | CPU-safe usage demo with simulated layer scores |
| `notebooks/quickstart_simulated_probe.ipynb` | Notebook version of the CPU-safe API demo |
| `tests/` | Unit tests for the public API |
| `.github/workflows/ci.yml` | Public CI for supported Python versions |
| `docs/` | PyPI, Papers with Code, arXiv v2, and evidence-bundle notes |
| `MODEL_CARD.md` | Human-readable method card |
| `huggingface/README.md` | Hugging Face Hub-ready card |
| `CITATION.cff` | GitHub citation metadata |

## Reproducibility

The full empirical record is described in the paper. A sanitized aggregate evidence companion is published at [aletheiaprotocol/aletheia-lora-evidence](https://huggingface.co/datasets/aletheiaprotocol/aletheia-lora-evidence). It contains aggregate metadata and final figures only; it excludes credentials, raw datasets, checkpoints, adapter weights, full gradient score dictionaries, and private cloud paths.

## Citation

```bibtex
@misc{saket2026aletheia,
  title={Aletheia: Gradient-Guided Layer Selection for Efficient LoRA Fine-Tuning Across Architectures},
  author={Saket, Abdulmalek},
  year={2026},
  eprint={2604.15351},
  archivePrefix={arXiv},
  primaryClass={cs.LG},
  doi={10.48550/arXiv.2604.15351},
  url={https://arxiv.org/abs/2604.15351}
}
```

## License

Apache 2.0
