Skip to content

solvi.experimental.lora

A LoRA adapter on the decider for one question (experimental): solvi.experimental.lora.adapt_lora(part, examples), part.load_lora, solvi.experimental.lora.remove_lora(part).

Training on the CPU (device="cpu") creates no CUDA context, so it works beside a GPU that is busy or full.

An adapter belongs to a decision part (its name, on its model), not to the question's text: two parts asking the same task and options in one process — the folds of a cross-validation — each have their own, and a part never scores with another part's adapter (a SharedQuestionWarning names both parts once). The lora extra needs peft>=0.19; an older peft is refused before any training.

Versions of one part (the adapter loop, solvi.experimental.stream.lora_learner): swap(part, adapter, calibration) changes the adapter and its calibration (calibration(part): the thresholds, the guarantee, the conformal set, the adaptation) together under the part's version lock (version_lock(part), taken by each of the part's decisions) and the scorer's lock, so a decision of the part never sees an adapter without its own thresholds, and a decision on another question of the same model is not disturbed (the model's adapter slots are replaced, never changed in place) — except through a combination (Cascade, Vote, Route) over the part, which reads the part without its version lock and can pair one version's scores with the other's thresholds during a swap. adapt_lora and load_lora leave that window open (the adapter is on, the thresholds are cleared until act_guard runs). Swapping back is bit-exact (the part's and the model's fingerprints, the probabilities). stage(part, adapter) installs an adapter inactive, outside any slot; scoring(part, adapter) scores the part's question with it on the calling thread only. adapter_by_hash(folder, hash) finds an adapter file by the hash a decision recorded. Unmeasured beyond the tests.

Install on x86_64 macOS (Intel)

The last torch for x86_64 macOS is 2.2.2. transformers 5 and NumPy 2 do not run with it, and on Python 3.12 the transformers 4.x ModernBERT module calls torch.compile when it is imported, which Dynamo refuses there ("Dynamo is not supported on Python 3.12+"). A working set, reported by a user on an Intel Mac with Python 3.12:

pip install "torch==2.2.2" "numpy<2" "transformers==4.48.3" "peft>=0.19" "solvi[lora]"
export SOLVI_NO_COMPILE=1          # torch.compile becomes a no-op while the decider's encoder is imported and built

pip install "solvi[lora]" on that platform asks for transformers<5 and numpy<2 by itself (environment markers for x86_64 macOS only; other platforms are unchanged). SOLVI_NO_COMPILE=1 must be set before the decider is loaded (solvi.models.decider(..., backend="torch") / DecideModel.load); it also turns ModernBERT's compiled MLP off at run time. The ONNX backend (backend="onnx", solvi[onnx]) needs neither torch nor this setting.

LoRA adapters on the decider, one per question (experimental): solvi.experimental.lora.adapt_lora(part, examples).

When a question has a hundred labelled answers or more, a shift and a scale on the logits (part.fit) stop improving: they cannot change what the model reads in the input. A LoRA adapter can: low-rank updates (rank 8) of the encoder's attention and MLP weights in every layer, plus the last layer of the output head, trained on this question's examples with the rest of the checkpoint frozen. A gain over fit needs examples: at a few dozen try fit first (it takes milliseconds), and compare the two on held-out labels. The adapter is 3.2 MB (bf16); training on a CPU takes minutes (adapt_lora estimates compute from three warm unapplied updates after a discarded cold probe and says so before training), on a GPU seconds.

part = model.decision("team", "Which team?", "email", TEAMS)      # DecideModel.load(..., backend="torch")
from solvi.experimental.lora import adapt_lora, remove_lora
report = adapt_lora(part, labelled, holdout=300)                  # 300 of the examples calibrate act_guard
part.save_calibration("team.calib.json")                          # + team.calib.lora.safetensors beside it
...
remove_lora(part)                                                 # roll back

In 1.0 training and rolling back left the part (part.adapt_lora / part.remove_lora raise AttributeError naming these functions): a stable part does not import an experimental module. The part keeps an adapter slot — its LoRA adapter is a solvi Adapter (kind, fingerprint(), using(scorer), save(path)) — so part.save_lora / part.load_lora, the fingerprint, the trace and the calibration file work as before.

What changes and what does not:

  • The adapter is active only while this question is scored; every other question of the same model is scored by the checkpoint as it was (to the bit). Its hash is part of the part's fingerprint (and the model's), and every decision records it in extra["lora"], so a replay knows which weights answered.
  • Confidences after LoRA tend to be overconfident (more than after fit), so the escalation must be recalibrated on labels not used for training: holdout= runs act_guard on them. The question's earlier adaptation and thresholds are cleared: they were fitted on the model without the adapter.
  • Deterministic for a fixed seed on a CPU (the same examples, seed, torch version and thread count give the same adapter, and the same hash).
  • solvi-base-sized checkpoints only; for solvi-large or thousands of examples, tools/adapt_lora_gpu.py (in the solvi repository, not installed by pip) trains the same adapter on a GPU, and part.load_lora(path) loads it.

Needs the torch backend and peft: pip install "solvi[lora]".

LoraWarning

Bases: UserWarning

adapt_lora's notices: the time it will take, few examples, no held-out calibration.

LoraAdapter dataclass

LoraAdapter(tensors: dict, config: dict, info: dict = dict(), hash: str = '')

A trained adapter: its tensors (float32 on the CPU, values exact in bf16 — the file stores bf16), its config (rank, alpha, targets, the question) and what it was trained on (info). hash covers the config and the tensors.

describe

describe()

What the trace and the metadata show.

fingerprint

fingerprint()

The adapter's identity in the part's and the model's fingerprints: its hash.

using

using(scorer, active=True)

A context in which the scorer scores with this adapter active (active=False: with no adapter); one thread at a time.

provider_using

provider_using(scorer)

Suspend local adaptation for probes and restore even after scorer errors.

save

save(path)

Write the adapter (a .safetensors file with its config, the question and the checkpoint) → path.

load classmethod

load(path)

An adapter file written by save → the LoraAdapter (ValueError if it is not one, or its content does not match its hash). Into a part: solvi.experimental.lora.load(part, path) / part.load_lora(path).

check

check(part, allow_large=False)

Refuse what adapt_lora cannot adapt (ValueError / TypeError / ImportError with what to do instead).

remove

remove(part)

remove_lora (see there).

n_updates

n_updates(k, epochs, max_updates=400)

Updates of BS examples: epochs passes over k examples, at least 40 and at most max_updates.

train

train(part, rows, *, r=8, alpha=None, epochs=6, lr=0.0003, seed=0, device=None, max_updates=400, notify=None, updates=None, log=None)

Train an adapter on [(text, label)] (labels as part.spec.label gives them) → LoraAdapter. notify(estimate_seconds, updates, seconds_per_update, device) is called after warm unapplied probes are timed, before training (it may raise to refuse the training). updates: the number of updates (None: from epochs, between 40 and max_updates); log(u, updates, loss): called after every update (a heartbeat). Training on the CPU creates no CUDA context, so it works beside a GPU that is busy or full.

adapt

adapt(part, examples, *, r=8, epochs=6, holdout=None, seed=0, device=None, lr=0.0003, max_risk=0.1, signal='confidence', max_updates=400, allow_large=False)

adapt_lora (see there). allow_large: in-process training of a checkpoint larger than solvi-base (what tools/adapt_lora_gpu.py passes, on a GPU).

save

save(part, path)

part.save_lora (see there) → path.

read

read(path)

An adapter file → LoraAdapter (ValueError if it is not one, or its content does not match its hash; ImportError with what to install when safetensors or torch is missing).

load

load(part, path, strict=True, expect=None)

part.load_lora (see there); expect: the hash a calibration file names.

version_lock

version_lock(part)

The part's version lock (solvi.core.deciders.part.version_lock): each of the part's decisions holds it, and swap holds it while it changes the adapter and the thresholds together.

calibration

calibration(part)

What a version restores besides its adapter: the question's adaptation, the escalation thresholds, the guarantee, the conformal set, the thresholds per group and the part's signature (copies).

calibration_record

calibration_record(cal)

A calibration (see calibration) as plain data: what its fingerprint covers and its file holds.

calibration_fingerprint

calibration_fingerprint(cal)

The fingerprint of a calibration (see calibration).

stage

stage(part, ad)

Install ad on the part's scorer outside any slot, inactive (ahead of a swap, or to score it in shadow): the model's fingerprint and every question's answers are unchanged. From then on every question on the model is scored through the scorer's adapter switch, so the model's scoring is serialised by the scorer's lock. Idempotent.

unstage

unstage(part, ad)

Undo stage: the adapter leaves the scorer unless a slot holds it.

scoring

scoring(part, ad, *, adaptation=_OWN)

On this thread, score the part's question with adapter ad (None: with no adapter) in place of its own slot's — other threads, other questions and the fingerprints are unchanged. The adapter is staged first. adaptation: the question's adaptation to score with in place of the one the served version set (None: none; default: the served one) — a version's own calibration, so a version scores the same whichever version is served. Holds the part's version lock, so the part's own decisions wait (lock order: the part's, then the scorer's).

swap

swap(part, ad, cal, *, drop_old=True)

Make ad (None: no adapter) the part's adapter and cal (see calibration) its calibration in one step: under the part's version lock, then the scorer's lock, the slot, the cached logits and every threshold change together, so no decision of the part sees the adapter without its thresholds (the window adapt_lora / load_lora leave, in which the adapter is on and the thresholds are cleared). The adapter is installed inactive before the locks; the replaced one is uninstalled after them (drop_old) unless a slot holds it or it is staged. A decision in flight finishes with the old version. → {"from": the part's fingerprint before, "to": after, "old": the replaced adapter or None}.

adapter_by_hash

adapter_by_hash(where, hash)

The adapter with this hash among the .safetensors files of a folder (or one file) → LoraAdapter (its content verified against its hash); FileNotFoundError when none has it. What a replay resolves a decision's extra["lora"] with.

adapt_lora

adapt_lora(part, examples, *, r=8, epochs=6, holdout=None, seed=0, device=None, lr=0.0003, max_risk=0.1, signal='confidence', max_updates=400)

Experimental: train a small LoRA adapter on the decider's encoder for this question (part, a DecisionPart), from labelled examples [(input, correct)] — for solvi-base (the torch backend, pip install "solvi[lora]") and about 100 examples or more. Below that, try part.fit (and System.fit for questions without a model) first: they take milliseconds; the adapter can keep improving where fit levels off. Compare the two on held-out labels. (Was part.adapt_lora(examples, ...) before 1.0.)

Cost: minutes on a CPU; the time is estimated from warm unapplied updates and reported (a LoraWarning) before training. r: the adapter's rank (alpha = 2r); epochs: passes over the examples (updates of 8 examples, between 40 and max_updates); lr: the learning rate; seed: the adapter's initialization and the order of the examples — the same seed gives the same adapter on a CPU; device: None — the device the decider runs on.

After training the adapter is active for this question only (other questions of the same model are not affected), its hash is in the part's fingerprint and in every decision's extra["lora"], and the question's earlier adaptation (adapt / fit / teach) and escalation thresholds are cleared: they were fitted on the model without it. Confidences after LoRA are overconfident, so escalation must be recalibrated on labels NOT used for training: holdout — a list of [(input, correct)], a share of the examples (0.25) or a number of them split off (by the seed) — runs act_guard(holdout, risk, signal) after training and reports the held-out accuracy before and after; without one a LoraWarning says so (call act_guard yourself; a few hundred labels is typical). Refuses a decider that is not a torch encoder (ONNX: load it with backend="torch"; an LLM or a rule has no weights to adapt), one larger than solvi-base (use tools/adapt_lora_gpu.py on a GPU and part.load_lora), a combination (train the adapter on one of its parts, then calibrate the combination) and rank / number / span questions. Keep it with part.save_lora / part.load_lora or part.save_calibration (the adapter is written next to the calibration file); remove_lora rolls back. → {"adapter", "k", "updates", "seconds", "estimate_seconds", "size_mb", "device", "holdout": {"n", "accuracy_before", "accuracy_after", "act_guard"} or None, "cleared", "experimental": True}.

remove_lora

remove_lora(part)

Roll back adapt_lora / load_lora on part: the adapter is removed from the model (the question is answered by the checkpoint as before, to the bit) and the part's adaptation and escalation thresholds return to what they were before the first adapter in this process (after a load_lora: they are cleared — they were fitted with the adapter). → the removed adapter's hash, or None when there was none. A combination (Cascade / Vote / Route): every part's → [hash or None], in leaves order; its own threshold was fitted on the parts with their adapters: calibrate it again. (Was part.remove_lora() before 1.0.)