Metadata-Version: 2.4
Name: gradience
Version: 0.11.0
Summary: Spectral analysis of low-rank adaptation dynamics — measure rank evolution, detect phase transitions, and study training geometry
Author-email: John Nanney <johntnanney@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/johntnanney/gradience
Project-URL: Repository, https://github.com/johntnanney/gradience
Project-URL: Documentation, https://github.com/johntnanney/gradience#readme
Project-URL: Bug Tracker, https://github.com/johntnanney/gradience/issues
Keywords: lora,spectral-analysis,training-dynamics,low-rank-adaptation,fine-tuning,merge-audit,adapter-merge,compression,model-compression
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pyyaml>=6.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: packaging
Requires-Dist: rich>=10.0.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: torch>=2.0.0
Requires-Dist: safetensors>=0.4.0
Requires-Dist: typing_extensions>=4.0.0; python_version < "3.11"
Provides-Extra: bench
Requires-Dist: transformers<5,>=4.35.0; extra == "bench"
Requires-Dist: peft<1,>=0.7.0; extra == "bench"
Requires-Dist: datasets>=2.14.0; extra == "bench"
Requires-Dist: accelerate>=0.20.0; extra == "bench"
Requires-Dist: evaluate>=0.4.0; extra == "bench"
Requires-Dist: sentencepiece>=0.1.99; extra == "bench"
Requires-Dist: protobuf>=3.20.0; extra == "bench"
Requires-Dist: scikit-learn>=1.3.0; extra == "bench"
Requires-Dist: pandas>=2.0.0; extra == "bench"
Provides-Extra: hf
Requires-Dist: transformers<5,>=4.35.0; extra == "hf"
Requires-Dist: peft<1,>=0.7.0; extra == "hf"
Requires-Dist: sentencepiece>=0.1.99; extra == "hf"
Requires-Dist: protobuf>=3.20.0; extra == "hf"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.2.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: fast
Requires-Dist: hf_transfer>=0.1.4; extra == "fast"
Provides-Extra: all
Requires-Dist: gradience[bench,dev,fast,hf]; extra == "all"
Dynamic: license-file

# Gradience

**Spectral analysis of low-rank adaptation dynamics.**

Gradience is a research instrument for studying the geometry of LoRA fine-tuning.
It measures rank structure, energy concentration, and subspace alignment across
adapter layers — and provides reproducible, multi-seed experimental infrastructure
for validating spectral hypotheses.

## Quick Start

**Requires Python 3.10+**

```bash
pip install gradience

# Audit a LoRA adapter's spectral structure
gradience audit --peft-dir ./your-adapter --suggest-ranks

# Measure merge compatibility between two adapters
gradience merge-audit --adapter-a ./adapter_a --adapter-b ./adapter_b

# Run a full compression validation benchmark
gradience-bench --config bench_config.yaml
```

## What You Get

- **Spectral measurements** — Per-layer SVD analysis: stable rank, energy concentration, utilization ratios, rank waste quantification
- **Merge compatibility analysis** — Principal angles, directional agreement, and magnitude balance between adapter pairs, with per-layer geometric verdicts
- **Training telemetry** — Structured JSONL recording of spectral evolution across training steps
- **Reproducible benchmarking** — Multi-seed compression validation with statistical aggregation and tolerance-based safety policies
- **Publication-ready artifacts** — JSON data, Markdown reports, and aggregate statistics for tables and figures

## Install

```bash
pip install gradience                # Core (torch + safetensors + scipy)
pip install "gradience[hf]"          # + HuggingFace Trainer integration
pip install "gradience[bench]"       # + Full benchmark protocol with eval
pip install "gradience[all]"         # Everything
```

## Links

- **GitHub:** [github.com/johntnanney/gradience](https://github.com/johntnanney/gradience)
- **License:** Apache 2.0

## Citation

```bibtex
@software{gradience2026,
  title  = {Gradience: Spectral Analysis of Low-Rank Adaptation Dynamics},
  author = {Nanney, John T.},
  year   = {2026},
  url    = {https://github.com/johntnanney/gradience}
}
```
