loraport 0.1.3__py3-none-any.whl

loraport/__init__.py

@@ -0,0 +1,30 @@
+"""loraport: convert LoRA adapters between MLX (mlx-lm) and PEFT and verify dW."""
+
+from __future__ import annotations
+
+__version__ = "0.1.3"
+
+from .convert import ConvertResult, convert  # noqa: E402
+from .delta import Report, compare  # noqa: E402
+from .detect import load_adapter  # noqa: E402
+from .errors import AdapterFormatError, BaseConfigError, LoraportError, UnsupportedAdapterError  # noqa: E402
+from .formats.mlx import write_mlx as save_mlx  # noqa: E402
+from .formats.peft import write_peft as save_peft  # noqa: E402
+from .model import Adapter, LoraModule  # noqa: E402
+
+__all__ = [
+    "Adapter",
+    "AdapterFormatError",
+    "BaseConfigError",
+    "ConvertResult",
+    "LoraModule",
+    "LoraportError",
+    "Report",
+    "UnsupportedAdapterError",
+    "__version__",
+    "compare",
+    "convert",
+    "load_adapter",
+    "save_mlx",
+    "save_peft",
+]

loraport/basecfg.py

@@ -0,0 +1,92 @@
+"""Cross-check adapter tensor shapes against a base model ``config.json``."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import BaseConfigError
+from .model import Adapter, layer_of, terminal
+
+
+@dataclass(frozen=True)
+class BaseDims:
+    num_layers: int
+    hidden: int
+    intermediate: int | None
+    heads: int
+    kv_heads: int
+    head_dim: int
+
+    def expected(self, term: str) -> tuple[int, int] | None:
+        """Expected ``(in, out)`` of a well-known Llama-style projection, else None."""
+        q_out = self.heads * self.head_dim
+        kv_out = self.kv_heads * self.head_dim
+        table = {
+            "q_proj": (self.hidden, q_out),
+            "k_proj": (self.hidden, kv_out),
+            "v_proj": (self.hidden, kv_out),
+            "o_proj": (q_out, self.hidden),
+        }
+        if self.intermediate is not None:
+            table |= {
+                "gate_proj": (self.hidden, self.intermediate),
+                "up_proj": (self.hidden, self.intermediate),
+                "down_proj": (self.intermediate, self.hidden),
+            }
+        return table.get(term)
+
+
+def load_base_config(path: str | Path) -> BaseDims:
+    """Read ``config.json`` (a file, or a folder that contains it)."""
+    p = Path(path)
+    if p.is_dir():
+        p = p / "config.json"
+    try:
+        cfg = json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as e:
+        raise BaseConfigError(f"{p}: cannot read base model config ({e})") from e
+    if isinstance(cfg.get("text_config"), dict):  # multimodal wrappers
+        cfg = cfg["text_config"]
+    try:
+        hidden = int(cfg["hidden_size"])
+        heads = int(cfg["num_attention_heads"])
+        layers = int(cfg["num_hidden_layers"])
+    except (KeyError, TypeError, ValueError) as e:
+        raise BaseConfigError(
+            f"{p}: needs hidden_size, num_attention_heads and num_hidden_layers (missing or invalid: {e})"
+        ) from e
+    inter = cfg.get("intermediate_size")
+    return BaseDims(
+        layers,
+        hidden,
+        int(inter) if inter is not None else None,
+        heads,
+        int(cfg.get("num_key_value_heads") or heads),
+        int(cfg.get("head_dim") or hidden // heads),
+    )
+
+
+def check_adapter(adapter: Adapter, dims: BaseDims) -> list[str]:
+    """Return human-readable problems (empty list means consistent)."""
+    problems: list[str] = []
+    for name in sorted(adapter.modules):
+        mod = adapter.modules[name]
+        layer = layer_of(name)
+        if layer is not None and not 0 <= layer < dims.num_layers:
+            problems.append(
+                f"{name}: layer {layer} is outside the base model's range 0..{dims.num_layers - 1} "
+                f"(num_hidden_layers={dims.num_layers})"
+            )
+        exp = dims.expected(terminal(name))
+        if exp is None or not mod.consistent:
+            continue
+        r = mod.rank
+        want_a, want_b = (r, exp[0]), (exp[1], r)
+        if tuple(mod.A.shape) != want_a or tuple(mod.B.shape) != want_b:
+            problems.append(
+                f"{name}: expected A{want_a} B{want_b} for the base model, "
+                f"got A{tuple(mod.A.shape)} B{tuple(mod.B.shape)}"
+            )
+    return problems

loraport/cli.py

@@ -0,0 +1,158 @@
+"""Command line interface: inspect, convert, verify, demo.
+
+Exit codes: 0 success / verification passed, 1 verification failed or tensors
+were dropped, 2 invalid input or unsupported adapter.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .convert import convert, ensure_supported
+from .delta import compare
+from .detect import load_adapter
+from .errors import LoraportError, UnsupportedAdapterError
+from .render import adapter_summary, render_inspect, render_report
+from .sample import TRAP_NAMES, make_dora_adapter, make_mlx_adapter, make_trap, write_base_config
+
+
+def _cmd_inspect(args: argparse.Namespace) -> int:
+    adapter = load_adapter(args.path)
+    if args.json:
+        print(json.dumps(adapter_summary(adapter, str(args.path)), indent=2))
+    else:
+        print(render_inspect(adapter, str(args.path)))
+    return 0
+
+
+def _cmd_convert(args: argparse.Namespace) -> int:
+    res = convert(
+        args.src,
+        args.dst,
+        args.to,
+        base_config=args.base_config,
+        base_model_id=args.base_model_id,
+        verify=not args.no_verify,
+        rtol=args.rtol,
+        force=args.force,
+    )
+    print(f"wrote {args.to} adapter to {res.dst}")
+    for note in res.notes:
+        print(f"note: {note}")
+    if res.report is not None:
+        print(render_report(res.report, "source", "converted"))
+    else:
+        print("verification skipped (--no-verify)")
+        if res.dropped:
+            print(f"  source tensors that were NOT carried over ({len(res.dropped)}):")
+            for line in res.dropped[:12]:
+                print(f"    - {line}")
+    if res.ok:
+        print("next steps:")
+        for line in res.next_steps:
+            print(f"  {line}")
+        return 0
+    print("conversion is NOT safe to use: see the problems above", file=sys.stderr)
+    return 1
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    a, b = load_adapter(args.a), load_adapter(args.b)
+    ensure_supported(a)
+    ensure_supported(b)
+    report = compare(a, b, rtol=args.rtol)
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        print(render_report(report, str(args.a), str(args.b)))
+    return 0 if report.ok else 1
+
+
+def _headline(res_report) -> str:  # type: ignore[no-untyped-def]
+    return res_report.headline() if res_report is not None else "not verified"
+
+
+def _cmd_demo(args: argparse.Namespace) -> int:
+    out = Path(args.out)
+    print("loraport demo: synthetic practice adapters (mock), random numbers, not a trained model")
+    mlx_dir = make_mlx_adapter(out / "mlx")
+    base_cfg = write_base_config(out / "base")
+    print(f"1. made a practice MLX adapter in {mlx_dir} (rank 4, scale 20, last 2 of 4 blocks)")
+
+    # real conversion + real verification, both directions
+    to_peft = convert(mlx_dir, out / "peft", "peft", force=True, base_config=base_cfg)
+    print(f"2. MLX -> PEFT: {_headline(to_peft.report)}")
+    back = convert(out / "peft", out / "mlx_roundtrip", "mlx", force=True, base_config=base_cfg)
+    print(f"3. PEFT -> MLX: {_headline(back.report)}")
+
+    print("4. common mistakes, each compared with the original MLX adapter:")
+    reference = load_adapter(mlx_dir)
+    caught = 0
+    for kind in TRAP_NAMES:
+        rep = compare(reference, load_adapter(make_trap(kind, mlx_dir, out / "traps" / kind)))
+        caught += 0 if rep.ok else 1
+        print(f"   {kind:<18} {'caught' if not rep.ok else 'MISSED'}: {rep.headline()}")
+    print(f"{caught}/{len(TRAP_NAMES)} traps caught")
+    # extra folder for README section 5 (a DoRA adapter that convert must refuse); prints nothing
+    make_dora_adapter(mlx_dir, out / "dora")
+    return 0 if to_peft.ok and back.ok and caught == len(TRAP_NAMES) else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="loraport",
+        description="Convert LoRA adapters between MLX (mlx-lm) and PEFT and verify the weight delta.",
+    )
+    p.add_argument("--version", action="version", version=f"loraport {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    sp = sub.add_parser("inspect", help="show format, rank, scale and layers of an adapter folder")
+    sp.add_argument("path", type=Path)
+    sp.add_argument("--json", action="store_true", help="machine-readable output")
+    sp.set_defaults(func=_cmd_inspect)
+
+    sp = sub.add_parser("convert", help="convert an adapter to the other format and verify it")
+    sp.add_argument("src", type=Path)
+    sp.add_argument("dst", type=Path)
+    sp.add_argument("--to", choices=("peft", "mlx"), required=True)
+    sp.add_argument("--base-config", type=Path, help="base model config.json (or its folder) for shape/layer checks")
+    sp.add_argument("--base-model-id", help="hub id written into the output config (e.g. Qwen/Qwen2.5-1.5B-Instruct)")
+    sp.add_argument("--rtol", type=float, default=1e-5, help="max relative dW error (default 1e-5)")
+    sp.add_argument("--no-verify", action="store_true", help="skip the automatic verification")
+    sp.add_argument("--force", action="store_true", help="overwrite adapter files in dst")
+    sp.set_defaults(func=_cmd_convert)
+
+    sp = sub.add_parser("verify", help="compare the dW of two adapters (any formats)")
+    sp.add_argument("a", type=Path, help="reference adapter")
+    sp.add_argument("b", type=Path, help="adapter to check")
+    sp.add_argument("--rtol", type=float, default=1e-5)
+    sp.add_argument("--json", action="store_true")
+    sp.set_defaults(func=_cmd_verify)
+
+    sp = sub.add_parser("demo", help="run the whole flow on synthetic practice adapters (mock)")
+    sp.add_argument("--out", type=Path, default=Path("loraport-demo"))
+    sp.set_defaults(func=_cmd_demo)
+    return p
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return int(args.func(args))
+    except UnsupportedAdapterError as e:
+        print("error: refusing to convert an unsupported adapter:", file=sys.stderr)
+        for reason in e.reasons:
+            print(f"  - {reason}", file=sys.stderr)
+        return 2
+    except LoraportError as e:  # includes BaseConfigError, AdapterFormatError
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

loraport/convert.py

@@ -0,0 +1,126 @@
+"""Convert between MLX and PEFT adapter folders, then verify the result."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from .basecfg import check_adapter, load_base_config
+from .delta import Report, compare
+from .detect import load_adapter
+from .errors import AdapterFormatError, BaseConfigError, LoraportError, UnsupportedAdapterError
+from .formats.common import CONFIG_NAME
+from .formats.mlx import WEIGHTS_NAME as MLX_WEIGHTS
+from .formats.mlx import write_mlx
+from .formats.peft import WEIGHTS_NAME as PEFT_WEIGHTS
+from .formats.peft import write_peft
+from .model import Adapter
+
+Target = Literal["peft", "mlx"]
+
+
+@dataclass
+class ConvertResult:
+    dst: Path
+    adapter: Adapter  # the source adapter as read
+    report: Report | None  # None when verification was skipped
+    next_steps: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+    dropped: list[str] = field(default_factory=list)  # source tensors that did not make it into the output
+
+    @property
+    def ok(self) -> bool:
+        """True only if nothing was dropped and (when verified) the report passed."""
+        return not self.dropped and (self.report is None or self.report.ok)
+
+
+def ensure_supported(adapter: Adapter) -> None:
+    """Raise ``UnsupportedAdapterError`` if the adapter uses a feature we refuse to convert."""
+    if adapter.unsupported:
+        raise UnsupportedAdapterError(adapter.unsupported)
+
+
+def _validate(adapter: Adapter) -> None:
+    ensure_supported(adapter)
+    if not adapter.modules:
+        raise AdapterFormatError("no LoRA modules found in the adapter; nothing to convert")
+    bad = []
+    for name, mod in sorted(adapter.modules.items()):
+        if not mod.consistent:
+            bad.append(f"{name}: A{tuple(mod.A.shape)} and B{tuple(mod.B.shape)} do not share the rank dimension")
+        elif mod.rank != adapter.rank:
+            bad.append(f"{name}: tensor rank {mod.rank} differs from the configured rank {adapter.rank}")
+    if bad:
+        raise AdapterFormatError(
+            "inconsistent adapter, refusing to convert (was lora_A/lora_B transposed or the config edited?): "
+            + "; ".join(bad[:5])
+            + (f" (+{len(bad) - 5} more)" if len(bad) > 5 else "")
+        )
+
+
+def _next_steps(to: Target, dst: Path, base: str | None, num_layers_unknown: bool) -> list[str]:
+    base_ref = base or "<BASE_MODEL>"
+    if to == "peft":
+        return [
+            f"vLLM:      vllm serve {base_ref} --enable-lora --lora-modules my-adapter={dst}",
+            f"llama.cpp: python convert_lora_to_gguf.py --base <BASE_MODEL_DIR> --outfile adapter.gguf {dst}",
+        ]
+    steps = [f'mlx-lm:    mlx_lm.generate --model {base_ref} --adapter-path {dst} --prompt "Hello"']
+    if num_layers_unknown:
+        steps.append("num_layers=-1 was written (no --base-config); blocks without tensors keep dW=0.")
+    return steps
+
+
+def convert(
+    src: str | Path,
+    dst: str | Path,
+    to: Target,
+    *,
+    base_config: str | Path | None = None,
+    base_model_id: str | None = None,
+    verify: bool = True,
+    rtol: float = 1e-5,
+    force: bool = False,
+) -> ConvertResult:
+    """Convert the adapter in ``src`` to ``to`` ("peft" or "mlx") inside ``dst``.
+
+    Raises ``UnsupportedAdapterError`` / ``AdapterFormatError`` / ``BaseConfigError``
+    before writing anything.  Tensors the converter could not carry over are
+    never silent: they show up in ``ConvertResult.dropped`` and in the report.
+    """
+    if to not in ("peft", "mlx"):
+        raise LoraportError(f"unknown target format {to!r}; use 'peft' or 'mlx'")
+    adapter = load_adapter(src)
+    _validate(adapter)
+    if adapter.format == to:
+        raise AdapterFormatError(
+            f"{src} is already a {to} adapter; convert to the other format "
+            f"(--to {'mlx' if to == 'peft' else 'peft'}) or use `loraport verify`"
+        )
+    total_layers = None
+    if base_config is not None:
+        dims = load_base_config(base_config)
+        problems = check_adapter(adapter, dims)
+        if problems:
+            raise BaseConfigError(
+                "adapter does not fit the base model config:\n  " + "\n  ".join(problems), problems
+            )
+        total_layers = dims.num_layers
+
+    out = Path(dst)
+    if not force and any((out / n).exists() for n in (PEFT_WEIGHTS, MLX_WEIGHTS, CONFIG_NAME)):
+        raise LoraportError(f"{out} already contains adapter files; pass --force to overwrite them")
+
+    if to == "peft":
+        write_peft(adapter, out, base_model_id=base_model_id)
+    else:
+        write_mlx(adapter, out, total_layers=total_layers, base_model_id=base_model_id)
+
+    result_adapter = load_adapter(out)
+    dropped = list(adapter.key_issues)
+    report = compare(adapter, result_adapter, rtol=rtol) if verify else None
+    notes = list(adapter.warnings)
+    return ConvertResult(
+        out, adapter, report, _next_steps(to, out, base_model_id, to == "mlx" and total_layers is None), notes, dropped
+    )

loraport/delta.py

@@ -0,0 +1,129 @@
+"""Compare adapters by their weight delta dW = scale * B @ A without building dW.
+
+For ``U = [s1*B1, -s2*B2]`` (out x (r1+r2)) and ``V = [A1; A2]`` we have
+``dW1 - dW2 = U @ V`` and ``||U V||_F^2 = trace((U^T U)(V V^T))``, which only
+needs (r1+r2)-square matrices.  Everything runs in float64.  Squaring limits the
+precision floor of a relative error to about 1e-8, far below any real mistake.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+from .model import Adapter, LoraModule
+
+_TINY = 1e-30
+
+
+def _sq_norm(U: np.ndarray, V: np.ndarray) -> float:
+    gram_u = U.T @ U
+    gram_v = V @ V.T
+    return max(float(np.sum(gram_u * gram_v)), 0.0)  # both Gram matrices are symmetric
+
+
+def delta_norm(m: LoraModule) -> float:
+    """Frobenius norm of dW."""
+    A = m.A.astype(np.float64)
+    B = m.B.astype(np.float64)
+    return math.sqrt(_sq_norm(m.scale * B, A))
+
+
+def diff_norm(m1: LoraModule, m2: LoraModule) -> float:
+    """Frobenius norm of dW1 - dW2 (shapes must match)."""
+    U = np.concatenate([m1.scale * m1.B.astype(np.float64), -m2.scale * m2.B.astype(np.float64)], axis=1)
+    V = np.concatenate([m1.A.astype(np.float64), m2.A.astype(np.float64)], axis=0)
+    return math.sqrt(_sq_norm(U, V))
+
+
+def dense_delta(m: LoraModule) -> np.ndarray:
+    """Materialise dW (float64). Only for tests and small modules."""
+    return m.scale * (m.B.astype(np.float64) @ m.A.astype(np.float64))
+
+
+def _shapes(m: LoraModule) -> str:
+    return f"A{tuple(m.A.shape)} B{tuple(m.B.shape)}"
+
+
+@dataclass
+class Report:
+    """Result of comparing a reference adapter ``a`` with a candidate ``b``."""
+
+    ok: bool
+    rtol: float
+    n_reference: int
+    missing: list[str] = field(default_factory=list)  # in a, absent in b
+    extra: list[str] = field(default_factory=list)  # in b, absent in a
+    shape_mismatch: list[str] = field(default_factory=list)
+    key_issues: list[str] = field(default_factory=list)
+    per_module: dict[str, float] = field(default_factory=dict)  # relative dW error
+    worst_rel_err: float = 0.0
+    worst_module: str | None = None
+
+    @property
+    def bad_modules(self) -> list[str]:
+        return [n for n, e in self.per_module.items() if not e <= self.rtol]
+
+    def headline(self) -> str:
+        good = self.n_reference - len(self.missing) - len(self.shape_mismatch) - len(self.bad_modules)
+        if self.ok:
+            return f"PASS {self.n_reference}/{self.n_reference} modules, worst rel err {self.worst_rel_err:.1e}"
+        return (
+            f"FAIL {max(good, 0)}/{self.n_reference} modules match "
+            f"(missing {len(self.missing)}, extra {len(self.extra)}, shape mismatch {len(self.shape_mismatch)}, "
+            f"dW off {len(self.bad_modules)}, ignored/dropped tensors {len(self.key_issues)})"
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        def num(x: float) -> float | None:
+            return x if math.isfinite(x) else None
+
+        return {
+            "ok": self.ok,
+            "rtol": self.rtol,
+            "modules_in_reference": self.n_reference,
+            "missing": self.missing,
+            "extra": self.extra,
+            "shape_mismatch": self.shape_mismatch,
+            "key_issues": self.key_issues,
+            "bad_modules": self.bad_modules,
+            "worst_rel_err": num(self.worst_rel_err),
+            "worst_module": self.worst_module,
+            "per_module": {k: num(v) for k, v in self.per_module.items()},
+        }
+
+
+def compare(a: Adapter, b: Adapter, *, rtol: float = 1e-5) -> Report:
+    """Compare per-module dW of ``a`` (reference) and ``b``.
+
+    The report is ``ok`` only if no module is missing/extra, no shape differs,
+    no tensor was ignored or dropped on either side, and every relative error
+    ``||dW_a - dW_b|| / ||dW_a||`` is within ``rtol``.
+    """
+    missing = sorted(a.modules.keys() - b.modules.keys())
+    extra = sorted(b.modules.keys() - a.modules.keys())
+    shape_mismatch: list[str] = []
+    per_module: dict[str, float] = {}
+    for name in sorted(a.modules.keys() & b.modules.keys()):
+        ma, mb = a.modules[name], b.modules[name]
+        if not (ma.consistent and mb.consistent) or ma.A.shape != mb.A.shape or ma.B.shape != mb.B.shape:
+            shape_mismatch.append(f"{name}: {_shapes(ma)} vs {_shapes(mb)}")
+            continue
+        ref = delta_norm(ma)
+        diff = diff_norm(ma, mb)
+        if ref < _TINY:
+            per_module[name] = 0.0 if diff < _TINY else math.inf
+        else:
+            per_module[name] = diff / ref
+    issues = [f"a: {s}" for s in a.key_issues] + [f"b: {s}" for s in b.key_issues]
+    worst_module = max(per_module, key=lambda n: per_module[n], default=None)
+    worst = per_module[worst_module] if worst_module else 0.0
+    ok = (
+        len(a.modules) > 0
+        and not (missing or extra or shape_mismatch or issues)
+        and all(e <= rtol for e in per_module.values())
+    )
+    return Report(ok, rtol, len(a.modules), missing, extra, shape_mismatch, issues, per_module, worst, worst_module)

loraport/detect.py

@@ -0,0 +1,40 @@
+"""Decide whether a folder holds an MLX or a PEFT adapter and load it."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .errors import AdapterFormatError
+from .formats.mlx import WEIGHTS_NAME as MLX_WEIGHTS
+from .formats.mlx import read_mlx
+from .formats.peft import WEIGHTS_NAME as PEFT_WEIGHTS
+from .formats.peft import read_peft
+from .model import Adapter
+
+
+def detect_format(path: Path) -> str:
+    """Return ``"mlx"`` or ``"peft"`` based on the weight file name in ``path``."""
+    if not path.exists():
+        raise AdapterFormatError(f"{path}: no such directory (check the path)")
+    if not path.is_dir():
+        raise AdapterFormatError(f"{path}: not a directory (pass the adapter folder, not a file)")
+    has_mlx = (path / MLX_WEIGHTS).is_file()
+    has_peft = (path / PEFT_WEIGHTS).is_file()
+    if has_mlx and has_peft:
+        raise AdapterFormatError(
+            f"{path}: contains both {MLX_WEIGHTS} and {PEFT_WEIGHTS}; keep one adapter per folder"
+        )
+    if has_mlx:
+        return "mlx"
+    if has_peft:
+        return "peft"
+    raise AdapterFormatError(
+        f"{path}: no adapter found; expected {MLX_WEIGHTS} (mlx-lm) or {PEFT_WEIGHTS} (PEFT) "
+        "together with adapter_config.json"
+    )
+
+
+def load_adapter(path: str | Path) -> Adapter:
+    """Load an adapter folder in either format."""
+    p = Path(path)
+    return read_mlx(p) if detect_format(p) == "mlx" else read_peft(p)

loraport/errors.py

@@ -0,0 +1,29 @@
+"""Exceptions raised by loraport. The CLI maps every ``LoraportError`` to exit code 2."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+class LoraportError(Exception):
+    """Base class for all expected, user-fixable errors."""
+
+
+class AdapterFormatError(LoraportError):
+    """The folder is not a readable MLX or PEFT LoRA adapter (or cannot be written)."""
+
+
+class UnsupportedAdapterError(LoraportError):
+    """The adapter uses a feature loraport refuses to convert instead of silently breaking it."""
+
+    def __init__(self, reasons: Iterable[str]) -> None:
+        self.reasons: list[str] = list(reasons)
+        super().__init__("unsupported adapter: " + "; ".join(self.reasons))
+
+
+class BaseConfigError(LoraportError):
+    """The base model ``config.json`` is unreadable or disagrees with the adapter tensors."""
+
+    def __init__(self, message: str, problems: Iterable[str] = ()) -> None:
+        self.problems: list[str] = list(problems)
+        super().__init__(message)

loraport/formats/__init__.py

@@ -0,0 +1 @@
+"""Format readers and writers (``mlx``, ``peft``)."""

loraport/formats/common.py

@@ -0,0 +1,56 @@
+"""Helpers shared by the MLX and PEFT readers/writers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from ..errors import AdapterFormatError
+from ..model import LoraModule
+from ..st_io import SafetensorsFile
+
+CONFIG_NAME = "adapter_config.json"
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as e:
+        raise AdapterFormatError(f"{path}: file not found") from e
+    except (OSError, json.JSONDecodeError) as e:
+        raise AdapterFormatError(f"{path}: cannot parse JSON ({e})") from e
+    if not isinstance(data, dict):
+        raise AdapterFormatError(f"{path}: expected a JSON object")
+    return data
+
+
+def pair_modules(
+    st: SafetensorsFile,
+    a_keys: dict[str, str],
+    b_keys: dict[str, str],
+    scale: float,
+    transpose: bool,
+    issues: list[str],
+    a_leaf: str,
+    b_leaf: str,
+) -> dict[str, LoraModule]:
+    """Read A/B tensors that have a partner; report the ones that do not.
+
+    ``a_keys``/``b_keys`` map module name -> tensor key.  When ``transpose`` is
+    true the tensors are in MLX layout and are transposed to ``(r,in)``/``(out,r)``.
+    """
+    modules: dict[str, LoraModule] = {}
+    for name in sorted(a_keys.keys() - b_keys.keys()):
+        issues.append(f"{a_keys[name]}: no matching {b_leaf} tensor, module {name!r} is incomplete and was skipped")
+    for name in sorted(b_keys.keys() - a_keys.keys()):
+        issues.append(f"{b_keys[name]}: no matching {a_leaf} tensor, module {name!r} is incomplete and was skipped")
+    for name in sorted(a_keys.keys() & b_keys.keys()):
+        a = st.read(a_keys[name])
+        b = st.read(b_keys[name])
+        if transpose:
+            a, b = a.T, b.T
+        modules[name] = LoraModule(np.ascontiguousarray(a), np.ascontiguousarray(b), scale)
+    return modules