`706aae7`

export: expose --adapter-mix-method (linear|svd); update CLI reference (audit-08 N4)

Authored by

espadonne 3 weeks ago

SHA: 706aae74eb2211d53fcd8ee44f7976c2a65de985
Parents: 7cb08b9
Tree: fde4826

4 changed files

Status	File	+	-
M	`docs/cli/reference.md`	2	1
M	`src/dlm/cli/commands.py`	25	1
M	`src/dlm/export/weighted_merge.py`	20	2
M	`tests/unit/cli/test_export_adapter_flag.py`	21	0

docs/cli/reference.mdmodified

  | `--draft TAG` | auto | Override the speculative-decoding draft model. |
  | `--no-draft` | false | Disable speculative decoding. Mutex with `--draft`. |
  | `--adapter NAME` | None | Export a single named adapter from `training.adapters`. Rejected on single-adapter documents. Mutex with `--adapter-mix`. |
 -| `--adapter-mix SPEC` | None | Weighted composition like `knowledge:1.0,tone:0.5`. Produces one Ollama model by merging the named adapters linearly at export time. LoRA-only; QLoRA sources require `--dequantize --merged`. Mutex with `--adapter`. |
 +| `--adapter-mix SPEC` | None | Weighted composition like `knowledge:1.0,tone:0.5`. Produces one Ollama model by merging the named adapters at export time. LoRA-only; QLoRA sources require `--dequantize --merged`. Mutex with `--adapter`. |
 +| `--adapter-mix-method` | `linear` | PEFT merge strategy: `linear` (default; fast weighted sum) or `svd` (higher fidelity, heavier compute). Only meaningful with `--adapter-mix`. |
  ### `dlm pack`

src/dlm/cli/commands.pymodified

              ),
          ),
      ] = None,
 +    adapter_mix_method: Annotated[
 +        str,
 +        typer.Option(
 +            "--adapter-mix-method",
 +            help=(
 +                "PEFT combination strategy for --adapter-mix. `linear` "
 +                "(default) sums LoRA deltas; `svd` recomposes via SVD "
 +                "(higher fidelity, heavier compute). Only meaningful "
 +                "with --adapter-mix."
 +            ),
 +        ),
 +    ] = "linear",
      verbose: Annotated[
          bool,
          typer.Option("--verbose", help="Log each subprocess command as it launches."),
                  "documents (this doc does not declare `training.adapters`)."
+             )
              raise typer.Exit(code=2)
 +        if adapter_mix_method not in ("linear", "svd"):
 +            console.print(
 +                f"[red]export:[/red] --adapter-mix-method must be "
 +                f"`linear` or `svd`, got {adapter_mix_method!r}."
 +            )
 +            raise typer.Exit(code=2)
          try:
              entries = parse_mix_spec(adapter_mix)
              validate_mix_against_declared(entries, set(adapters_declared))
          base_model = AutoModelForCausalLM.from_pretrained(
              str(cached.path), revision=spec.revision
+         )
 -        merged = build_weighted_merged(base_model, store, spec, entries_typed)
 +        merged = build_weighted_merged(
 +            base_model,
 +            store,
 +            spec,
 +            entries_typed,
 +            combination_type=adapter_mix_method,  # type: ignore[arg-type]
 +        )
          merge_dir = store.cache_dir_for(
              "_export_merged_" + "_".join(n for n, _ in mix_entries)
+         )

src/dlm/export/weighted_merge.pymodified

  import re
  from dataclasses import dataclass
 -from typing import TYPE_CHECKING, Any, Final
 +from typing import TYPE_CHECKING, Any, Final, Literal
  from dlm.export.errors import ExportError
+         )
 +CombinationType = Literal["linear", "svd"]
 +"""Allowed `add_weighted_adapter.combination_type` values (audit-08 N4).
++
 +- `linear` (default): weighted sum of LoRA deltas. Fast; exact for
 +  same-rank adapters; approximate for mixed ranks.
 +- `svd`: SVD-based recomposition. Higher fidelity across mixed ranks
 +  at meaningful compute cost.
++
 +PEFT exposes more (`cat`, `ties`, `dare_linear`, ...); we gate to the
 +two the project has tested end-to-end. Extending is a one-line
 +`Literal` bump once a new combination is validated.
 +"""
++
++
  def build_weighted_merged(  # pragma: no cover - heavy path
      base_model: Any,
      store: StorePath,
      spec: BaseModelSpec,  # noqa: ARG001  # reserved for future use
      entries: list[MixEntry],
 +    *,
 +    combination_type: CombinationType = "linear",
  ) -> Any:
      """Load each adapter, combine them via `add_weighted_adapter`.
      Returns a `PeftModel` with adapter `_export_merged` active. The
      caller writes the merged adapter to an ephemeral directory and
      hands it to the existing GGUF pipeline.
++
 +    `combination_type` controls PEFT's merge strategy (audit-08 N4).
      """
      from peft import PeftModel
          adapters=[e.name for e in entries],
          weights=[e.weight for e in entries],
          adapter_name=_MERGED_ADAPTER_NAME,
 -        combination_type="linear",
 +        combination_type=combination_type,
+     )
      model.set_adapter(_MERGED_ADAPTER_NAME)
      return model

tests/unit/cli/test_export_adapter_flag.pymodified

          text = _joined(result)
          assert "not declared" in text
          assert "ghost" in text
++
 +    def test_unknown_mix_method_rejected(self, tmp_path: Path) -> None:
 +        """Audit-08 N4: --adapter-mix-method accepts only linear|svd."""
 +        doc = _init_multi(tmp_path)
 +        runner = CliRunner()
 +        result = runner.invoke(
 +            app,
 +            [
 +                "--home",
 +                str(tmp_path / "home"),
 +                "export",
 +                str(doc),
 +                "--adapter-mix",
 +                "knowledge:1.0,tone:0.5",
 +                "--adapter-mix-method",
 +                "dare_linear",  # supported by PEFT but not exposed here
 +                "--skip-ollama",
 +            ],
 +        )
 +        assert result.exit_code == 2
 +        assert "linear` or `svd`" in _joined(result)