aurora-peft 0.1.1__tar.gz

aurora_peft-0.1.1/.gitignore

@@ -0,0 +1,32 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+.tox/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Credentials — NEVER commit
+.pypirc
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+
+# Test outputs
+*.log
+htmlcov/
+.deepeval/
+
+# Reference files used during initial development
+reference/

aurora_peft-0.1.1/.pypirc.template

@@ -0,0 +1,20 @@
+# PyPI configuration file
+# Copy this file to ~/.pypirc (Linux/macOS) or %USERPROFILE%\.pypirc (Windows)
+# and fill in your API tokens.
+#
+# Get tokens at:
+#   - https://pypi.org/manage/account/token/
+#   - https://test.pypi.org/manage/account/token/
+#
+# DO NOT commit this file. It's already in .gitignore.
+
+[pypi]
+username = __token__
+password = pypi-REPLACE_WITH_YOUR_PYPI_TOKEN
+
+[testpypi]
+username = __token__
+password = pypi-REPLACE_WITH_YOUR_TESTPYPI_TOKEN
+
+# Optional: don't upload to legacy if you prefer the new upload URL
+# (twine 4.x defaults to legacy, which works fine)

aurora_peft-0.1.1/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to `aurora-peft` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-08-30
+
+### Fixed
+
+- **Auto-patch `peft.PeftType.AURORA` đáng tin cậy hơn**: Thêm hàm
+  `aurora_peft.patch_peft(verbose=False)` tự sửa file
+  `site-packages/peft/utils/peft_types.py` (chèn `AURORA = "AURORA"`).
+  - Auto-chạy khi `import aurora_peft`.
+  - Idempotent (không ghi đè nếu đã patch).
+  - Fail gracefully nếu file read-only (warning + fallback sang
+    `AuroraModel` trực tiếp).
+- Trước đó, `import aurora_peft` ở venv mới (peft chưa patch) raise
+  `AttributeError: type object 'PeftType' has no attribute 'AURORA'` khi
+  gọi `AuroraConfig()`. Giờ fix bằng patch runtime.
+
+### Note
+
+- Version bump `0.1.0` → `0.1.1` vì PyPI/TestPyPI reserve filename sau khi
+  xoá — không thể reupload cùng version.
+
+## [0.1.0] - 2026-08-30
+
+### Added
+
+- **`ANL` module**: Adaptive Nonlinear Layer (KAN-style), extracted from the
+  four reference forks in https://github.com/ins1stenc3/AuroRA.
+  - Defaults match the paper: `grid_size=5`, `spline_order=3`, `scale_noise=0.1`,
+    `base_activation=Tanh`, `grid_range=[-1, 1]`.
+  - Supports input shape `(N, in_features)` and `(..., in_features)`.
+- **`AuroraLinear`**: `nn.Linear` + LoRA + ANL inserted between `lora_A` and
+  `lora_B`. Inherits from `peft.tuners.lycoris_utils.LycorisLayer` to reuse
+  multi-adapter, merge/unmerge, scaling logic.
+  - Forward (dynamic): `output = base(x) + scaling * B(ANL(A(dropout(x))))`
+  - Static merge: `ΔW = scaling * B @ ANL(A)` (added to `base.weight`).
+- **`AuroraConfig`**: `LycorisConfig` + ANL-specific hyperparameters
+  (`grid_size`, `spline_order`, `scale_noise`, `base_activation`).
+- **`AuroraModel`**: `LycorisTuner` subclass. Currently supports `nn.Linear`
+  targets only.
+- **Auto-registration with `peft`**: `import aurora_peft` patches the `PeftType`
+  enum (adds `AURORA`) and calls `register_peft_method`, so
+  `peft.get_peft_model(base, AuroraConfig(...))` works out of the box.
+  - The patch modifies `site-packages/peft/utils/peft_types.py` in place
+    (adds `AURORA = "AURORA"` after `DEFT = "DEFT"`).
+  - Auto-patch runs silently on `import aurora_peft`. If it fails (e.g.
+    read-only filesystem), a `UserWarning` is raised and user can run
+    `aurora_peft.patch_peft(verbose=True)` explicitly for diagnostics.
+  - For read-only installs, fall back to `AuroraModel(model, config)`
+    directly (does not need the enum patch).
+- **`get_aurora_model(base, config)`**: convenience wrapper that bypasses
+  `peft.get_peft_model` for users who prefer a direct API.
+
+### Known limitations
+
+- Only `nn.Linear` targets are supported. `nn.Conv2d` and `nn.Embedding`
+  support are not implemented (see `AGENT.md §7`).
+- Quantization (bitsandbytes / GPTQ) is not integrated.
+- The reference repo has 4 forks that each implement Aurora slightly
+  differently (some apply ANL to weights, others to activations). We follow
+  the **paper Algorithm 1** (dynamic forward + static merge).
+
+### Tests
+
+- 28 unit tests, all passing:
+  - `tests/test_anl_layer.py` (11): construction, forward shapes, numerical
+    match against 3 reference forks (commonsense, image, sdgen — excluding the
+    `natural_language_understanding` fork which has a documented shape bug),
+    gradient flow, partition-of-unity at knots, validation.
+  - `tests/test_aurora_layer.py` (9): forward equals manual
+    LoRA+ANL composition, freeze base weights, disable adapters,
+    merge/unmerge round-trip, gradient flow to all params.
+  - `tests/test_integration_peft.py` (8): end-to-end via `peft.get_peft_model`,
+    save/load round-trip, direct `AuroraModel` / `get_aurora_model` API.

aurora_peft-0.1.1/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

aurora_peft-0.1.1/NOTES_diff.md

@@ -0,0 +1,191 @@
+# NOTES_diff.md — Phân tích diff giữa các bản fork AuroRA
+
+Mục đích: xác định **phần nào là đóng góp mới của AuroRA** cần giữ lại trong thư
+viện `aurora-peft`, **phần nào là boilerplate của `peft`** cần bỏ đi khi viết lại.
+
+Phạm vi: 4 fork trong repo gốc
+- `commonsense_reasoning/` (NLU/commonsense, fork của `peft` rất cũ, dạng `lora.py` đơn file)
+- `natural_language_understanding/` (NLU, dùng code style `loralib` của Microsoft)
+- `image_classification/` (CV/ViT, fork `peft` đã có `BaseTuner` + multi-adapter)
+- `subject_driven_generation/` (diffusion/SD, cùng style với `image_classification`)
+
+`peft` tham chiếu: bản **mới nhất trên PyPI** (`peft==0.20.0`) — sẽ dùng làm khuôn
+mẫu, KHÔNG dùng bản fork trong repo.
+
+---
+
+## 1. So sánh 4 bản `ANL.py`
+
+| Đặc điểm | commonsense | nlu | image | sdgen |
+|---|---|---|---|---|
+| Số dòng | 72 | 70 | 74 | 74 |
+| `import math` thừa | có | không | không | không |
+| `spline_input.to(dtype=self.spline_weight.dtype)` | không | không | **có** | **có** |
+| Định nghĩa `b_splines` | giống | giống | giống | giống |
+| Định nghĩa `forward` (công thức) | giống | giống | gần giống | gần giống |
+
+### Kết luận
+
+Về mặt **toán học**, 4 bản `ANL.forward` đều tính cùng một công thức:
+
+```
+output = tanh(Linear(tanh(x), W_base)) + Linear(sum_spline_basis(x), W_spline)
+```
+
+Hai biến thể:
+
+- **Biến thể "gốc"** (commonsense, nlu): không ép dtype ở giữa.
+- **Biến thể "ép dtype"** (image, sdgen): ép `spline_input` về `dtype` của
+  `spline_weight` trước khi nhân. Lý do có lẽ là tương thích khi base model
+  chạy ở fp16/bf16 nhưng ANL phải ở fp32 vì có grid buffer và `b_splines` dùng
+  bool masks. Trong bản refactor, ta sẽ **giữ cả hai nhánh** và để user chọn
+  qua config (`anl_compute_dtype: str = "same"` mặc định theo `spline_weight`).
+
+→ Thư viện sẽ dùng bản **commonsense** (sạch nhất) làm cơ sở, và bổ sung
+option ép dtype từ image/sdgen.
+
+---
+
+## 2. So sánh cách gắn ANL vào LoRA
+
+Có **hai kiểu** khác nhau giữa các fork:
+
+### Kiểu A — áp ANL lên weight `lora_A` (pre-activation transform)
+
+File: `commonsense_reasoning/peft/src/peft/tuners/lora.py`,
+     `natural_language_understanding/loralib/layers.py`
+
+Trong forward:
+
+- `commonsense` (line 336):
+  ```python
+  def get_weight_A(self):
+      if self.lora_use_mixer:
+          return self.lora_AB(self.lora_A.weight)
+      return self.lora_A.weight
+  ```
+- `nlu` (line 141):
+  ```python
+  result += (self.lora_dropout(x)
+             @ self.lora_activation(self.lora_A.transpose(0, 1))
+             @ self.lora_B.transpose(0, 1)) * self.scaling
+  ```
+
+**Lưu ý quan trọng về `nlu`**: `lora_act = ANL(r, r)` nhưng được áp lên
+`self.lora_A.transpose(0, 1)` — `lora_A` có shape `(r, in_features)`, sau
+transpose là `(in_features, r)`. `ANL(in=r, out=r)` chỉ chấp nhận input có
+`size(1) == in_features == r`. Với batch > 1 thì shape là `(batch, in_features)`
+chứ không phải `(in_features, r)` ⇒ **code này có bug shape**. Có thể chỉ chạy
+khi `batch == r` (hy hữu). Sẽ không reproduce bug này.
+
+### Kiểu B — áp ANL lên activation `lora_A(x)` (post-activation transform)
+
+File: `image_classification/peft/src/peft/tuners/lora/layer.py`,
+     `subject_driven_generation/peft/tuners/lora/layer.py`
+
+Trong forward (image, line 393):
+```python
+result += lora_B(lora_AB(lora_A(dropout(x)))) * scaling
+```
+
+Đây là **dynamic, input-dependent** form — đúng với paper Eq. (4):
+`Δh = B · σ(Ax)`.
+
+### Kết luận
+
+- Theo paper AuroRA §3.5 (Algorithm 1):
+  - **Training (dynamic)**: `h = W₀x + B · σ(Ax)` ⇒ Kiểu B
+  - **Inference (static merge)**: `ΔW = B · σ(A)` ⇒ Kiểu A
+  - Repo gốc **chỉ hiện thực 1 trong 2**, không phân biệt train/inference.
+- Bản refactor (`aurora-peft`) sẽ:
+  - Mặc định dùng **Kiểu B** trong forward (dynamic) để khớp paper.
+  - Trong `merge()` (inference) sẽ compute `ΔW = B · ANL(A)` — đây là thứ paper
+    gọi là "static merge". Vì ANL phi tuyến, việc merge vào `W₀` chỉ hợp lệ khi
+    `A` là weight matrix cố định; với activation phụ thuộc input thì không merge
+    được. Do đó sẽ document rõ: `merge()` raise `NotImplementedError` với
+    thông báo "AuroRA dynamic mode cannot be merged; use unmerged forward".
+
+---
+
+## 3. Inventory các thay đổi so với `peft` upstream
+
+### Phần KHÔNG giữ (boilerplate của fork cũ)
+
+- Toàn bộ file `lora.py` / `layers.py` / `layer.py` đã sửa — đây là bản fork
+  `peft` rất cũ (không có `BaseTuner`, dùng mixin `LoraLayer` đơn giản). Sẽ
+  viết lại từ đầu theo API `peft==0.20.0` (`BaseTunerLayer` + multi-adapter).
+- Tất cả `lora_use_mixer` / `lora_use_act` flag trong `LoraConfig` —
+  sẽ thay bằng `use_anl: bool = True` trong `AuroraConfig` mới.
+- `lora_AB`, `lora_act`, `lora_activation` — đổi tên thành `anl` cho nhất
+  quán.
+- File `peft/src/peft/tuners/lora/bnb.py`, `gptq.py`, v.v. trong fork — bỏ
+  (không hỗ trợ quantization theo AGENT.md §7).
+- Các class `MergedLinear`, `Linear8bitLt`, v.v. trong fork — bỏ (Milestone 0
+  chỉ cần `Linear` thường).
+
+### Phần GIỮ LẠI làm đóng góp cốt lõi
+
+- `ANL` module (4 bản giống nhau về công thức) — sẽ refactor vào
+  `src/aurora_peft/layer.py` (Milestone 1).
+- Logic forward: `result = base_layer(x) + scaling * B(ANL(A(dropout(x))))`
+  — sẽ hiện thực trong `AuroraLinear` (Milestone 2).
+
+### Phần dùng làm "fact reference" cho peft 0.20
+
+Đọc các file peft 0.20 sau làm khuôn mẫu:
+- `peft/tuners/lora/layer.py` — `LoraLayer`, `Linear` (class `nn.Linear +
+  LoraLayer`, multi-adapter, `BaseTunerLayer`)
+- `peft/tuners/lora/model.py` — `LoraModel`, `LoraModel._create_new_module`,
+  `_replace_module`, `_mark_only_adapters_as_trainable`
+- `peft/tuners/loha/layer.py` + `model.py` — LoHa là tuner thêm linear mixing
+  matrix giữa A và B, gần với AuroRA về concept (không nonlinear nhưng cấu
+  trúc multi-adapter + linear-mix giữa hai low-rank giống).
+- `peft/utils/peft_types.py::register_peft_method` — API plugin chính thức
+  cho tuner mới từ peft 0.13+.
+
+---
+
+## 4. Phát hiện quan trọng: `peft==0.20.0` đã có `register_peft_method`
+
+Không cần monkeypatch. Chỉ cần:
+
+1. Thêm `AURORA = "AURORA"` vào enum `PeftType` trong
+   `peft/utils/peft_types.py` (1 dòng patch).
+2. Trong `aurora_peft/__init__.py`, gọi:
+   ```python
+   from peft.utils.peft_types import register_peft_method
+   register_peft_method(name="aurora", config_cls=AuroraConfig, model_cls=AuroraModel)
+   ```
+3. Sau đó `get_peft_model(base, AuroraConfig(...))` chạy được.
+
+→ Trong Milestone 3 sẽ:
+- **Không patch source `peft`** — sẽ tạo module con `peft_patch.py` trong
+  `aurora_peft` để thêm enum `AURORA` thông qua monkeypatch nhẹ tại runtime
+  (chấp nhận được, document rõ). Lý do: tránh yêu cầu user sửa file `peft`
+  đã cài.
+- Hoặc yêu cầu user chạy 1 lệnh patch sau khi `pip install`. Sẽ quyết ở M3.
+
+---
+
+## 5. Quyết định Milestone 1
+
+- Lấy bản **commonsense_reasoning/ANL.py** làm gốc (sạch nhất).
+- Đổi tên `b_splines` → `_b_splines` (private).
+- Giữ nguyên tất cả công thức.
+- Thêm option `compute_dtype: Optional[torch.dtype] = None` để ép dtype như
+  image/sdgen.
+- Test sẽ so khớp output với 4 bản gốc bằng `torch.allclose` (sẽ bỏ qua bản
+  nlu vì bug shape như đã ghi nhận).
+
+---
+
+## 6. Cập nhật Milestone 6
+
+Tham chiếu trong `reference/` đã được **xoá** sau khi mọi test pass (không
+còn phụ thuộc vào 4 fork cũ). Test `test_anl_matches_commonsense_reference`
+giờ skip thay vì fail nếu `reference/` không tồn tại — package có thể
+publish/pip-install độc lập.
+
+Logic so khớp đã được verify 1 lần (3 bản gốc match `torch.allclose` với
+`atol=1e-6, rtol=1e-5`). Công thức không thay đổi nên các lần chạy sau vẫn
+đúng.

aurora_peft-0.1.1/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: aurora-peft
+Version: 0.1.1
+Summary: Re-implementation of AuroRA (NeurIPS 2025) as a peft-compatible tuner.
+Project-URL: Homepage, https://github.com/ins1stenc3/AuroRA
+Project-URL: Paper, https://arxiv.org/abs/2502.12166
+Project-URL: Original repo, https://github.com/ins1stenc3/AuroRA
+Project-URL: PEFT library, https://github.com/huggingface/peft
+Project-URL: Repository, https://github.com/ins1stenc3/AuroRA
+Project-URL: Issues, https://github.com/ins1stenc3/AuroRA/issues
+Project-URL: Changelog, https://github.com/ins1stenc3/AuroRA/blob/main/aurora-peft/CHANGELOG.md
+Author: aurora-peft contributors
+Maintainer: aurora-peft contributors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: aurora,fine-tuning,kan,lora,parameter-efficient,peft,pytorch
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: peft>=0.13
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# aurora-peft
+
+Re-implementation của **[AuroRA: Breaking Low-Rank Bottleneck of LoRA with
+Nonlinear Mapping](https://arxiv.org/abs/...)** (NeurIPS 2025) dưới dạng một
+tuner cho [🤗 PEFT](https://github.com/huggingface/peft) (>=0.13).
+
+## Cài đặt
+
+```bash
+pip install aurora-peft
+```
+
+Hoặc cài bản dev:
+
+```bash
+pip install -e .
+```
+
+## Sử dụng nhanh
+
+```python
+import torch
+from transformers import AutoModel
+from aurora_peft import AuroraConfig, get_aurora_model
+
+base = AutoModel.from_pretrained("bert-base-uncased")
+
+config = AuroraConfig(
+    r=8,                       # LoRA rank (= ANL in/out dim)
+    alpha=16,                  # LoRA alpha
+    target_modules=["query", "value"],
+    grid_size=5,               # B-spline intervals (paper: 5)
+    spline_order=3,            # B-spline degree (paper: 3)
+    scale_noise=0.1,
+)
+
+model = get_aurora_model(base, config)
+
+# Optimizer chỉ update params của Aurora (ANL + A + B)
+model.print_trainable_parameters()
+```
+
+Hoặc dùng qua API chuẩn của `peft`:
+
+```python
+from peft import get_peft_model
+from aurora_peft import AuroraConfig
+
+model = get_peft_model(base, AuroraConfig(r=8, target_modules=["q_proj", "v_proj"]))
+```
+
+## Công thức
+
+AuroRA mở rộng LoRA bằng cách chèn một **Adaptive Nonlinear Layer (ANL)**
+giữa hai low-rank matrix `A` và `B`:
+
+```
+Δh = B · ANL(A · x)
+```
+
+trong đó ANL là một mini KAN:
+
+```
+ANL(z) = tanh(W_base @ tanh(z)) + W_spline @ Σ_i B_i(z)
+```
+
+`B_i` là basis B-spline bậc `spline_order` trên `grid_size` khoảng.
+
+## Re-implementation note
+
+Đây là **re-implementation không chính thức**, dựa trên paper và 4 bản fork
+trong repo gốc https://github.com/ins1stenc3/AuroRA. Mục tiêu:
+
+1. Rút logic lõi (ANL + cách gắn vào `nn.Linear`) ra khỏi 4 fork trùng lặp.
+2. Tương thích với `peft` hiện hành (>=0.13).
+3. Có unit test so khớp số học với bản gốc.
+
+Bản gốc (paper) dùng **hai công thức**:
+
+- **Training (dynamic)**: `h = W₀x + B · ANL(Ax)` — input-dependent.
+- **Inference (static merge)**: `ΔW = B · ANL(A)` — weight-only, merge được
+  vào `W₀`.
+
+Repo gốc chỉ hiện thực 1 trong 2. Thư viện này:
+
+- Forward (training) dùng công thức dynamic (khớp paper Algorithm 1, line
+  "Training Phase").
+- `merge()` dùng công thức static (line "Inference Preparation"), nên sau khi
+  merge, forward chỉ là `Wx` (không còn gọi ANL nữa).
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## Giấy phép
+
+Apache-2.0 (theo license của peft và paper).