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
¶
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.
fingerprint ¶
The adapter's identity in the part's and the model's fingerprints: its hash.
using ¶
A context in which the scorer scores with this adapter active (active=False: with no adapter); one thread at a time.
provider_using ¶
Suspend local adaptation for probes and restore even after scorer errors.
save ¶
Write the adapter (a .safetensors file with its config, the question and the checkpoint) → path.
load
classmethod
¶
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 ¶
Refuse what adapt_lora cannot adapt (ValueError / TypeError / ImportError with what to do instead).
n_updates ¶
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).
read ¶
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 ¶
part.load_lora (see there); expect: the hash a calibration file names.
version_lock ¶
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 ¶
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 ¶
A calibration (see calibration) as plain data: what its fingerprint covers and its file holds.
calibration_fingerprint ¶
The fingerprint of a calibration (see calibration).
stage ¶
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.
scoring ¶
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 ¶
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 ¶
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 ¶
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.)