Release v1.0.0: stable API, merge/unmerge, CI hardening

Promote to production-stable v1.0.0 with a reduced public API surface
(21 symbols, internal ops moved to vlora.ops), VLoRAModel.merge()/unmerge()
for hook-free inference, project() quality warnings, PEP 561 py.typed,
and CI gates (ruff, mypy, 80% coverage floor). 225 tests pass at 89% coverage.

Author: tveseli

.github/workflows/ci.yml

@@ -7,11 +7,46 @@ on:
     branches: [main]
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Mypy
+        run: mypy src/vlora/
+
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.11", "3.13"]
+        python-version: ["3.9", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v4
@@ -24,5 +59,5 @@ jobs:
       - name: Install dependencies
         run: pip install -e ".[dev]"
 
-      - name: Run tests
-        run: pytest tests/ -v
+      - name: Run tests with coverage
+        run: pytest tests/ -v --cov=vlora --cov-report=term-missing --cov-fail-under=80

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.0.0] - 2026-04-11
+
+### Added
+- **`VLoRAModel.merge()` / `unmerge()`** — bake LoRA deltas into base model weights for hook-free inference. `is_merged` property tracks state. Errors on quantized base models.
+- **Quality warning in `project()`** — optional `warn_threshold` parameter warns when subspace coverage is low, suggesting `absorb()` to expand the basis.
+- **PEP 561 `py.typed` marker** — enables type checker support for downstream users.
+- **CI hardening** — ruff lint + format check, mypy type checking, pytest-cov with 80% coverage floor, Python 3.12 added to test matrix.
+- **Edge case and numerical precision tests** — rank-1 adapters, single-layer adapters, project→reconstruct roundtrip bounds, save→load serialization verification.
+
+### Changed
+- **API surface reduced** — low-level ops (`compute_svd`, `project_onto_subspace`, `gram_schmidt`, NF4 functions, `incremental_svd_update`, etc.) removed from top-level `vlora` namespace. Still accessible via `from vlora.ops import ...`.
+- **Development status** — classifier updated from "Alpha" to "Production/Stable".
+
+### Migration from 0.3.0
+Replace `from vlora import compute_svd` with `from vlora.ops import compute_svd` (and similarly for `project_onto_subspace`, `reconstruct_from_subspace`, `gram_schmidt`, `explained_variance_ratio`, `select_num_components`, `incremental_svd_update`, `NF4_QUANT_TABLE`, `nf4_quantize_dequantize`, `nf4_pack`, `nf4_unpack`). No other breaking changes.
+
 ## [0.3.0] - 2026-03-30
 
 ### Added

README.md

@@ -6,6 +6,12 @@
   <strong>Various LoRA adapters. One shared basis.</strong>
 </p>
 
+<p align="center">
+  <a href="https://github.com/vlora-dev/vlora/actions/workflows/ci.yml"><img src="https://github.com/vlora-dev/vlora/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/vlora-dev/"><img src="https://img.shields.io/pypi/v/vlora-dev" alt="PyPI"></a>
+  <a href="https://pypi.org/project/vlora-dev/"><img src="https://img.shields.io/pypi/pyversions/vlora-dev" alt="Python"></a>
+</p>
+
 Your adapters share more structure than you think. vLoRA finds the common basis and stores each adapter as a tiny coefficient vector — up to 122× compression at scale. Based on the [Share paper](https://arxiv.org/abs/2602.06043).
 
 ## Install
@@ -101,6 +107,19 @@ output = model(input_ids)
 print(model.available_tasks)  # ["task_0", "task_1", ...]
 ```
 
+### Merging into Base Weights
+
+For deployment with a single adapter, bake deltas directly into the base model — zero hook overhead:
+
+```python
+model = VLoRAModel(base_model, subspace)
+model.merge(task_id="task_0")  # deltas baked into weights
+output = model(input_ids)       # pure base model forward, no hooks
+
+model.unmerge()                 # restore original weights
+model.set_task("task_1")        # back to hook-based inference
+```
+
 ## QLoRA Support
 
 vLoRA has first-class support for [QLoRA](https://arxiv.org/abs/2305.14314) workflows. QLoRA compresses the **base model** (FP16 → 4-bit NF4), while vLoRA compresses the **adapter space** — these are orthogonal and stack multiplicatively.
@@ -445,6 +464,22 @@ subspace.save("updated_subspace/")
 }
 ```
 
+## Migrating from v0.x
+
+Low-level math operations have been moved from the top-level `vlora` namespace to `vlora.ops`:
+
+```python
+# Before (v0.x)
+from vlora import compute_svd, gram_schmidt, nf4_pack
+
+# After (v1.0)
+from vlora.ops import compute_svd, gram_schmidt, nf4_pack
+```
+
+Moved symbols: `compute_svd`, `project_onto_subspace`, `reconstruct_from_subspace`, `gram_schmidt`, `explained_variance_ratio`, `select_num_components`, `incremental_svd_update`, `NF4_QUANT_TABLE`, `nf4_quantize_dequantize`, `nf4_pack`, `nf4_unpack`.
+
+All other public APIs remain unchanged.
+
 ## License
 
 Apache 2.0

pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vlora-dev"
-version = "0.3.0"
+version = "1.0.0"
 description = "Various LoRA adapters. One shared basis. Up to 122x compression at scale."
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.9"
 authors = [{ name = "Tim Veseli" }]
 keywords = ["lora", "llm", "parameter-efficient", "fine-tuning", "subspace"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Science/Research",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
@@ -35,14 +35,18 @@ hf = ["transformers>=4.38", "huggingface-hub>=0.20"]
 docs = ["mkdocs-material>=9.5", "mkdocstrings[python]>=0.24"]
 dev = [
     "pytest>=7.0",
+    "pytest-cov>=4.0",
     "huggingface-hub>=0.20",
     "pre-commit>=3.0",
     "ruff>=0.8",
+    "mypy>=1.0",
 ]
 
 [project.urls]
-Homepage = "https://github.com/tveseli/vlora"
-Repository = "https://github.com/tveseli/vlora"
+Homepage = "https://github.com/vlora-dev/vlora"
+Repository = "https://github.com/vlora-dev/vlora"
+Changelog = "https://github.com/vlora-dev/vlora/blob/main/CHANGELOG.md"
+Issues = "https://github.com/vlora-dev/vlora/issues"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/vlora"]
@@ -56,9 +60,16 @@ line-length = 100
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "W"]
+ignore = ["E501", "E741", "E402"]
 
 [tool.mypy]
 python_version = "3.9"
 ignore_missing_imports = true
 warn_return_any = true
 check_untyped_defs = true
+follow_imports = "skip"
+exclude = ["build/", "dist/"]
+
+[[tool.mypy.overrides]]
+module = ["torch.*", "safetensors.*"]
+follow_imports = "skip"

src/vlora/__init__.py

@@ -5,35 +5,22 @@
 maintain one shared basis and per-task coefficient vectors.
 """
 
-__version__ = "0.3.0"
+__version__ = "1.0.0"
 
-from vlora.io import LoRAWeights, load_adapter, load_adapter_from_hub, save_adapter
-from vlora.ops import (
-    NF4_QUANT_TABLE,
-    compute_svd,
-    explained_variance_ratio,
-    gram_schmidt,
-    nf4_pack,
-    nf4_quantize_dequantize,
-    nf4_unpack,
-    project_onto_subspace,
-    reconstruct_from_subspace,
-    select_num_components,
-)
-from vlora.model import VLoRAModel
-from vlora.ops import incremental_svd_update
 from vlora.analysis import (
     adapter_diff,
     compute_similarity_matrix,
     find_clusters,
     find_outliers,
     subspace_coverage,
 )
+from vlora.io import LoRAWeights, load_adapter, load_adapter_from_hub, save_adapter
+from vlora.merge import dare_merge, task_arithmetic, ties_merge
+from vlora.model import VLoRAModel
 from vlora.pipeline import absorb_task, extract_adapter, init_subspace
 from vlora.router import TaskRouter
 from vlora.subspace import SharedSubspace, TaskProjection
 from vlora.training import SubspaceTrainer, orthogonal_init
-from vlora.merge import task_arithmetic, ties_merge, dare_merge
 
 __all__ = [
     # Core
@@ -48,18 +35,6 @@
     "init_subspace",
     "absorb_task",
     "extract_adapter",
-    # Ops
-    "compute_svd",
-    "project_onto_subspace",
-    "reconstruct_from_subspace",
-    "gram_schmidt",
-    "explained_variance_ratio",
-    "select_num_components",
-    # NF4 quantization (QLoRA-style)
-    "NF4_QUANT_TABLE",
-    "nf4_quantize_dequantize",
-    "nf4_pack",
-    "nf4_unpack",
     # Analysis
     "compute_similarity_matrix",
     "find_clusters",
@@ -73,8 +48,6 @@
     # Training
     "SubspaceTrainer",
     "orthogonal_init",
-    # Incremental
-    "incremental_svd_update",
     # Merging
     "task_arithmetic",
     "ties_merge",

src/vlora/analysis.py

@@ -2,14 +2,14 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 import torch
 from torch import Tensor
 
 from vlora.io import LoRAWeights
 from vlora.ops import project_onto_subspace
 
-from typing import TYPE_CHECKING
-
 if TYPE_CHECKING:
     from vlora.subspace import SharedSubspace
 

src/vlora/cli.py

@@ -9,7 +9,7 @@
 
 import click
 
-from vlora.io import LoRAWeights, load_adapter, save_adapter
+from vlora.io import load_adapter, save_adapter
 from vlora.ops import explained_variance_ratio
 from vlora.subspace import SharedSubspace
 
@@ -65,7 +65,7 @@ def info(subspace_path: str, as_json: bool):
     click.echo(f"  Tasks: {len(sub.tasks)}")
 
     if sub.tasks:
-        click.echo(f"\n  Task IDs:")
+        click.echo("\n  Task IDs:")
         for tid in sorted(sub.tasks.keys()):
             click.echo(f"    - {tid}")
 
@@ -102,7 +102,7 @@ def compress(adapter_dirs: tuple[str, ...], output: str, num_components: int | N
         task_ids.append(path.name)
         click.echo(f"    Loaded: {path.name}")
 
-    click.echo(f"  Building subspace...")
+    click.echo("  Building subspace...")
     sub = SharedSubspace.from_adapters(
         adapters,
         task_ids=task_ids,
@@ -210,7 +210,7 @@ def analyze(adapter_dirs: tuple[str, ...], threshold: float, as_json: bool):
     for n in names:
         click.echo(f"    Loaded: {n}")
 
-    click.echo(f"\n  Pairwise Cosine Similarity:")
+    click.echo("\n  Pairwise Cosine Similarity:")
     header = "  " + " " * 20 + "  ".join(f"{n[:8]:>8}" for n in names)
     click.echo(header)
     for i, name in enumerate(names):
@@ -242,7 +242,7 @@ def validate(subspace_path: str):
     import torch
 
     sub = SharedSubspace.load(subspace_path)
-    issues = {"errors": [], "warnings": []}
+    issues: dict[str, list[str]] = {"errors": [], "warnings": []}
 
     click.echo(f"\n  Validating: {subspace_path}")
     click.echo(f"  Tasks: {len(sub.tasks)}, Layers: {len(sub.layer_names)}, k={sub.num_components}")
@@ -298,7 +298,7 @@ def validate(subspace_path: str):
         for warn in issues["warnings"]:
             click.echo(f"    [WARN]  {warn}")
     if not issues["errors"] and not issues["warnings"]:
-        click.echo(f"\n  All checks passed.")
+        click.echo("\n  All checks passed.")
 
     click.echo()
 
@@ -347,7 +347,6 @@ def diff(subspace_path: str, task_a: str, task_b: str):
 @click.argument("subspace_path", type=click.Path(exists=True))
 def benchmark(subspace_path: str):
     """Benchmark subspace operations: reconstruct, project, absorb."""
-    import torch
 
     sub = SharedSubspace.load(subspace_path)
     task_ids = sorted(sub.tasks.keys())
@@ -418,11 +417,11 @@ def merge(adapter_dirs: tuple[str, ...], output: str, method: str, weights: str
 
     fn = MERGE_METHODS[method]
     if method == "ties":
-        merged = fn(adapters, density=density, weights=parsed_weights)
+        merged = fn(adapters, density=density, weights=parsed_weights)  # type: ignore[operator]
     elif method == "dare":
-        merged = fn(adapters, drop_rate=drop_rate, weights=parsed_weights, seed=seed)
+        merged = fn(adapters, drop_rate=drop_rate, weights=parsed_weights, seed=seed)  # type: ignore[operator]
     else:
-        merged = fn(adapters, weights=parsed_weights)
+        merged = fn(adapters, weights=parsed_weights)  # type: ignore[operator]
 
     save_adapter(merged, output)
     click.echo(f"  Merged adapter saved to: {output}")

src/vlora/integrations/huggingface.py

@@ -27,7 +27,6 @@
 import logging
 from typing import Any
 
-import torch
 import torch.nn as nn
 from torch import Tensor
 
@@ -101,6 +100,7 @@ def _make_differentiable_hook(self, layer_name: str):
             The reconstruction is differentiable — gradients flow from the
             loss through the hook back to the loadings parameters.
             """
+            assert self._trainer is not None
             params = self._trainer.params
             la = params[f"{layer_name}.loadings_a"]
             lb = params[f"{layer_name}.loadings_b"]

src/vlora/merge.py

@@ -13,7 +13,6 @@
 from __future__ import annotations
 
 import logging
-from typing import Literal
 
 import torch
 from torch import Tensor