lineage-ml 0.2.0__py3-none-any.whl

lineage/__init__.py

@@ -0,0 +1,41 @@
+"""lineage - git for a model that keeps learning.
+
+    from lineage import Lineage, gate, diff
+
+    L = Lineage.init("my-notes", base="Qwen/Qwen3-0.6B")   # a frozen base, no lives, an empty present, a seed
+    L.learn_many(paragraphs)                                 # one step per text: the text's loss + a return toward the model's earlier selves
+    res = gate(L)                                            # six readings of the present against the lives before it; res["ok"]
+    life = L.fold("week one", gate=res)                      # a commit: life 1, frozen, with the gate's verdict recorded
+    print(L.log())                                           # the lives
+    print(diff(L, 0, 1)["words_up"])                         # what life 1 learned, in words
+
+The API:
+    Lineage.init(path, base, rank, alpha, targets, policy, quant, device, truncate_layers, seed, chat)
+    Lineage.open(path, device, truncate_layers, present)
+    L.learn(text, kind, weight, source) -> record | None       L.learn_many(texts, kind, source, on_step) -> summary
+    L.fold(name, gate, force, probes) -> life                   L.discard(life=False) -> record
+    L.adopt(src, name, gate, force) -> life                     a life learned elsewhere (another lineage's selves/gNNN) taken in as the next self, verbatim, with its provenance; L.donor_of(src)
+    L.stash()  L.log()  L.status()  L.stream()  L.learned_texts()  L.generate(prompt)  L.life_dir(k)  L.self_dir(k)
+    gate(L, candidate="present" | "last" | k | "gNNN" | dir, probes, wide, questions, policy) -> record (format_gate)
+    diff(L, a, b, probes=None, top, n) -> record (format_diff)
+    compact(adapter_dirs, out, rank=0 | R, energy) -> record    (lives 1..K: compact([L.life_dir(k) for k in range(1, K + 1)], out))
+    replay(from_lineage, out, policy, fold_every, device, against=None) -> Lineage   (against: L.meta["replay"] holds the comparison)
+    bisect(path, margin=None, cls=None) -> record (format_bisect)   which life moved a reading, from the records alone (no model)
+    serve(L, port=8765, learn=False) -> counts                     a local HTTP server: POST /say, POST /learn, GET /status, until shutdown
+    tune(path, texts, weights, n_learn, n_hold) -> record (format_tune)   the return's weight read on your own texts, on a scratch copy; apply_weight(path, w)
+    default_weight_for(n_params) -> float                          the weight init starts a base with, by its size (1.0 to 10B parameters, 0.3 above)
+    LineageError: a refusal the lineage makes on purpose; the message says why and nothing was changed.
+"""
+from .core import DEFAULT_BASE, DEFAULT_POLICY, PACKAGE_VERSION, Lineage, LineageError, LineageWarning
+from .gate import format_gate, gate
+from .diff import diff, format_diff
+from .compact import compact
+from .replay import replay, replay_onto
+from .bisect import bisect, format_bisect
+from .serve import serve
+from .tune import tune, format_tune, apply_weight, default_weight_for
+
+__version__ = PACKAGE_VERSION
+__all__ = ["Lineage", "LineageError", "LineageWarning", "DEFAULT_POLICY", "DEFAULT_BASE", "gate", "format_gate", "diff",
+           "format_diff", "compact", "replay", "replay_onto", "bisect", "format_bisect", "serve", "tune", "format_tune", "apply_weight",
+           "default_weight_for", "__version__"]

lineage/__main__.py

@@ -0,0 +1,4 @@
+"""`python -m lineage`: the command line where the `lineage` script is not on PATH."""
+from .cli import main
+
+raise SystemExit(main())

lineage/bisect.py

@@ -0,0 +1,171 @@
+"""Bisect: which life moved a reading. Read from the records alone, without the model.
+
+Every selves/gKKK/gate.json that holds a reading of life k (the reading it was folded on, or one taken afterwards with
+`bisect --read`) gives, per class, the parent's mean margin and the candidate's, in both forms (raw, and pmi, the
+prior-subtracted); their difference is what that life's fold moved, in nats, signed. It also gives the rent that life
+paid (G-5: ln of the held-out perplexity, candidate over parent) and the loops it added over the parent's replies (G-6).
+Per class, the path root -> life 1 -> ... -> the last life is the parent's mean at life 1 followed by every life's
+candidate mean, and the life that moved the class most is the largest |move|. A life without a reading is `unread`: its
+move is not known; its standing is still on the path when the next life's gate read it as the parent. `--read` gates an
+unread life now (lives 1..k-1 against lives 1..k, the reading it would have been kept on) and writes the record beside
+the adapter, marked `read_after_fold`; the fold's own verdict in lineage.json stays what it was.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Optional
+
+from .core import LineageError, read_policy, utc_now
+
+FORMS = ("raw", "pmi")
+
+
+def life_record(path: str, k: int) -> Optional[dict]:
+    """selves/gKKK/gate.json when it holds a reading of life k (its classes), else None (missing, unreadable, a fold with
+    the gate SKIPPED, or a record of another life)."""
+    p = os.path.join(path, "selves", f"g{k:03d}", "gate.json")
+    if not os.path.exists(p):
+        return None
+    try:
+        with open(p, encoding="utf-8") as f:
+            rec = json.load(f)
+    except (OSError, ValueError):
+        return None
+    if not isinstance(rec, dict) or not rec.get("classes") or rec.get("life") not in (None, k):
+        return None
+    return rec
+
+
+def write_reading(lineage, k: int, rec: dict) -> str:
+    """A reading of life k taken after its fold (`gate(lineage, k)`), written to selves/gKKK/gate.json beside the adapter:
+    the record with `life`, the fold's time and verdict (`folded`, `fold_verdict`, from lineage.json) and `read_after_fold`
+    (when). Returns the record's posix path. A SKIPPED stub the fold wrote is replaced; a reading already there is too."""
+    life = lineage.meta["lives"][k - 1]
+    d = lineage.self_dir(life); os.makedirs(d, exist_ok=True)
+    out = {**rec, "life": k, "folded": life.get("time"), "fold_verdict": life.get("gate", "SKIPPED"), "read_after_fold": utc_now()}
+    p = os.path.join(d, "gate.json"); tmp = p + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(out, f, indent=1)
+    os.replace(tmp, p)
+    return f"selves/g{k:03d}/gate.json"
+
+
+def bisect(path: str, margin: Optional[str] = None, cls: Optional[str] = None) -> dict:
+    """The record: `lives` (one per life: `k`, `name`, `gate` as the fold recorded it, `read`, and when read `verdict`,
+    `read_after_fold`, `rent`, `loops_added`, `loops`, `moves` {class: candidate - parent} in the chosen form, `moves_raw`
+    and `moves_pmi` in both, and the probe set), `classes` ({class: `path` [{life, mean}] from the root, `moves` {k: move},
+    `moves_raw`, `moves_pmi`, `moved_most` {life, name, move, other: the same life's move in the other form}, `net` (the
+    last life's mean less the root's, when both are known)}), `unread` (the lives without a reading), `margin` (`raw` or
+    `pmi`; None takes `gate.margin` from policy.json), `other` (the other form), `same_probes` (every reading read one
+    probe file). The two forms can disagree in sign on a life: the raw move includes the change in the model's taste for
+    the opener phrases themselves, the prior-subtracted move is net of it; both are given so the disagreement shows. `cls`
+    keeps one class; a class not in any record is a LineageError, as is a lineage with no lives."""
+    p = os.path.join(path, "lineage.json")
+    if not os.path.exists(p):
+        raise LineageError(f"{os.path.abspath(path)} is not a lineage (no lineage.json): run lineage init first")
+    with open(p, encoding="utf-8") as f:
+        meta = json.load(f)
+    pol = read_policy(path, meta)
+    if margin is None:
+        margin, margin_from = pol["gate"]["margin"], "policy.json"
+    else:
+        margin_from = "given"
+    if margin not in FORMS:
+        raise LineageError(f"margin must be raw or pmi, not {margin!r}")
+    other = "pmi" if margin == "raw" else "raw"
+    lives = meta.get("lives") or []
+    if not lives:
+        raise LineageError("no lives to bisect: fold first (a reading belongs to a life)")
+    recs = {life["k"]: life_record(path, life["k"]) for life in lives}
+    classes: list[str] = []
+    for rec in recs.values():
+        for c in (rec or {}).get("classes", {}):
+            if c not in classes:
+                classes.append(c)
+    if cls is not None:
+        if cls not in classes:
+            have = ", ".join(classes) if classes else "no class has been read"
+            raise LineageError(f"class {cls!r} is not in any reading of this lineage ({have})")
+        classes = [cls]
+    rows, shas = [], []
+    for life in lives:
+        k, rec = life["k"], recs[life["k"]]
+        row = {"k": k, "name": life.get("name"), "gate": life.get("gate", "SKIPPED"), "read": rec is not None}
+        if rec is not None:
+            g5, g6 = rec.get("checks", {}).get("G-5 the rent", {}), rec.get("checks", {}).get("G-6 no loop", {})
+            both = {f: {c: rec["classes"][c][f"{f}_candidate"] - rec["classes"][c][f"{f}_parent"] for c in classes if c in rec["classes"]}
+                    for f in FORMS}
+            row.update({"verdict": rec.get("verdict"), "read_after_fold": rec.get("read_after_fold"),
+                        "rent": g5.get("value"), "loops_added": g6.get("value"), "loops": g6.get("loops"),
+                        "moves": both[margin], "moves_raw": both["raw"], "moves_pmi": both["pmi"],
+                        "probes": {x: (rec.get("probes") or {}).get(x) for x in ("set", "sha256", "n")}})
+            shas.append(row["probes"]["sha256"])
+        rows.append(row)
+    out_classes = {}
+    for c in classes:
+        path_means = []
+        for i, life in enumerate(lives):
+            k, rec = life["k"], recs[life["k"]]
+            if i == 0:                                                 # the root: the parent of life 1
+                path_means.append({"life": 0, "mean": rec["classes"][c][f"{margin}_parent"] if rec and c in rec["classes"] else None})
+            after = recs.get(lives[i + 1]["k"]) if i + 1 < len(lives) else None
+            if rec and c in rec["classes"]:
+                m = rec["classes"][c][f"{margin}_candidate"]
+            elif after and c in after["classes"]:                      # unread, but the next gate read this stack as its parent
+                m = after["classes"][c][f"{margin}_parent"]
+            else:
+                m = None
+            path_means.append({"life": k, "mean": m})
+        moves = {r["k"]: r["moves"][c] for r in rows if r["read"] and c in r["moves"]}
+        in_form = {f: {r["k"]: r[f"moves_{f}"][c] for r in rows if r["read"] and c in r[f"moves_{f}"]} for f in FORMS}
+        most = max(moves, key=lambda k: (abs(moves[k]), -k)) if moves else None
+        root, last = path_means[0]["mean"], path_means[-1]["mean"]
+        out_classes[c] = {"path": path_means, "moves": moves, "moves_raw": in_form["raw"], "moves_pmi": in_form["pmi"],
+                          "moved_most": ({"life": most, "name": lives[most - 1].get("name"), "move": moves[most], "other": in_form[other][most]}
+                                         if most else None),
+                          "net": (last - root) if root is not None and last is not None else None}
+    return {"base": meta["base"], "rank": meta.get("rank"), "margin": margin, "margin_from": margin_from, "other": other, "class_filter": cls,
+            "lives": rows, "classes": out_classes, "unread": [r["k"] for r in rows if not r["read"]],
+            "same_probes": len(set(shas)) <= 1}
+
+
+def _mean(m: Optional[float]) -> str:
+    return f"{m:+.2f}" if m is not None else "?"
+
+
+FORM_WORD = {"raw": "raw", "pmi": "prior-subtracted"}
+
+
+def format_bisect(res: dict) -> str:
+    """The header, one line per life (the fold's verdict, and the reading's own when it was read after the fold, the rent,
+    the loops added, every class's move), one line per class (the path from the root, the life that moved it most with
+    its move in both forms, the net), and the notes."""
+    n, unread = len(res["lives"]), res["unread"]
+    lines = [f"{res['base']} (rank {res['rank']}); {n} {'life' if n == 1 else 'lives'}, {n - len(unread)} read"
+             + (f", {len(unread)} unread" if unread else "") + f"; margin {res['margin']} ({res['margin_from']})"]
+    w = max(len(r["name"] or "") for r in res["lives"]) + 2
+    for r in res["lives"]:
+        head = f"  life {r['k']:>2} {(chr(34) + (r['name'] or '') + chr(34)):<{w}} gate {r['gate']:<13}"
+        if not r["read"]:
+            lines.append(head + " unread"); continue
+        after = f"  (read after the fold: {r.get('verdict') or '?'})" if r.get("read_after_fold") else ""
+        rent = f"{r['rent']:+.3f}" if isinstance(r.get("rent"), (int, float)) else "?"
+        loops = r["loops_added"] if r.get("loops_added") is not None else "?"
+        moves = ", ".join(f"{c} {m:+.2f}" for c, m in r["moves"].items()) or "(no class)"
+        lines.append(f"{head} rent {rent}  loops added {loops}  moved: {moves}{after}")
+    cw = max((len(c) for c in res["classes"]), default=0) + 2
+    for c, v in res["classes"].items():
+        path = " -> ".join(("root " if e["life"] == 0 else f"{e['life']} ") + _mean(e["mean"]) for e in v["path"])
+        most = v["moved_most"]
+        who = (f"life {most['life']} moved it most ({most['move']:+.2f} nats {FORM_WORD[res['margin']]}; "
+               f"{FORM_WORD[res['other']]} {most['other']:+.2f})") if most else "no life read"
+        net = f"net {v['net']:+.2f}" if v["net"] is not None else "net unknown (a life unread)"
+        lines.append(f"  {c:<{cw}} {who}; {net}   {path}")
+    lines.append(f"  a move is the candidate's mean margin less the parent's on that life's gate reading, in nats ({FORM_WORD[res['margin']]}; "
+                 f"the {FORM_WORD[res['other']]} form beside it is net of the model's taste for the opener phrases themselves, and the two can "
+                 "disagree); the path is each life's own standing"
+                 + (" (an unread life's, where its successor's gate read it as the parent)" if unread else ""))
+    if not res["same_probes"]:
+        lines.append("  note: the readings did not all read one probe file: the moves are each on their own set, and the path is not one reading")
+    return "\n".join(lines)

lineage/body.py

@@ -0,0 +1,417 @@
+"""The body: a frozen base, a stack of frozen selves (LoRA adapters, one per life), and a trainable present on top.
+
+Nothing is ever merged into the base. The model at life k is the base with selves 1..k on; the root is the base alone.
+"""
+from __future__ import annotations
+
+import glob
+import os
+from contextlib import contextmanager
+from typing import Iterable, Optional
+
+import torch
+import torch.nn.functional as F
+
+STANDARD_TARGETS = ["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]
+
+
+def pick_device(device: Optional[str] = None) -> torch.device:
+    if device:
+        return torch.device(device)
+    if torch.cuda.device_count() > 0:                        # the count honours CUDA_VISIBLE_DEVICES where is_available() may not
+        return torch.device("cuda")
+    if getattr(torch.backends, "mps", None) is not None and torch.backends.mps.is_available():
+        return torch.device("mps")
+    return torch.device("cpu")
+
+
+def load_model(base: str, device: torch.device, dtype: Optional[torch.dtype] = None, quant: Optional[str] = None,
+               truncate_layers: Optional[int] = None, revision: Optional[str] = None):
+    """The base weights and the tokenizer, at `revision` when the lineage pinned one. bf16 on CUDA, fp32 elsewhere;
+    `quant="nf4"` loads 4-bit through bitsandbytes."""
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+    rev = {"revision": revision} if revision else {}
+    tok = AutoTokenizer.from_pretrained(base, **rev)
+    if tok.pad_token is None and tok.eos_token is not None:
+        tok.pad_token = tok.eos_token
+    if quant == "nf4":
+        from transformers import BitsAndBytesConfig
+        from peft import prepare_model_for_kbit_training
+        qc = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4", bnb_4bit_compute_dtype=torch.bfloat16,
+                                bnb_4bit_use_double_quant=True)
+        model = AutoModelForCausalLM.from_pretrained(base, quantization_config=qc, torch_dtype=torch.bfloat16,
+                                                     device_map={"": device.index or 0}, **rev)
+        model = prepare_model_for_kbit_training(model, use_gradient_checkpointing=False)
+    else:
+        if dtype is None:
+            dtype = torch.bfloat16 if device.type == "cuda" else torch.float32
+        model = AutoModelForCausalLM.from_pretrained(base, torch_dtype=dtype, **rev).to(device)
+    if truncate_layers:                                        # tests: a few layers of a real model, not a random one
+        layers = _find_layers(model)
+        if layers is not None:
+            del layers[truncate_layers:]
+            model.config.num_hidden_layers = truncate_layers
+    return tok, model
+
+
+def _find_layers(model):
+    for name in ("model.layers", "transformer.h", "model.decoder.layers", "gpt_neox.layers"):
+        obj = model
+        try:
+            for part in name.split("."):
+                obj = getattr(obj, part)
+            return obj
+        except AttributeError:
+            continue
+    return None
+
+
+def default_targets(model) -> list | str:
+    names = {n.split(".")[-1] for n, _ in model.named_modules()}
+    found = [t for t in STANDARD_TARGETS if t in names]
+    return found if len(found) >= 4 else "all-linear"
+
+
+def lora_config(rank: int, alpha: float, targets):
+    from peft import LoraConfig
+    return LoraConfig(r=rank, lora_alpha=alpha, lora_dropout=0.0, bias="none", task_type="CAUSAL_LM", target_modules=targets)
+
+
+def adapter_dir(path: str) -> str:
+    """An adapter directory: the directory itself (a self saved flat, a compacted adapter, any peft adapter), or its
+    `present/` subfolder when the adapter sits there (a stash, or a self folded before 0.2)."""
+    d = os.path.join(path, "present"); return d if os.path.exists(os.path.join(d, "adapter_config.json")) else path
+
+
+def is_base_model(base: str, tok) -> bool:
+    """A base (pre-trained only) model: no chat template, or an id that ends in `-Base`/`base`. Such a model is read as raw
+    text: its template tokens are untrained and a templated prompt reads degenerate margins and replies."""
+    name = os.path.basename(base.rstrip("/\\")).lower()
+    return not getattr(tok, "chat_template", None) or name.endswith("base")
+
+
+def set_active(model, names: Iterable[str], trainable: Iterable[str] = ("present",)) -> None:
+    """Turn on exactly the adapters in `names` on every LoRA layer, and make only those in `trainable` trainable.
+    (peft's set_adapter flips requires_grad as a side effect, so the freeze is re-applied here.) Every name must be an
+    adapter the body carries, once: peft silently skips an unknown name in the forward and applies a repeated one twice."""
+    from peft.tuners.lora import LoraLayer
+    names = list(names); trainable = list(trainable)
+    known = getattr(model, "peft_config", None)
+    if known is None:
+        if names:
+            raise ValueError(f"the model carries no adapters, so none of {names} can be turned on")
+        return
+    bad = [n for n in names if n not in known]
+    if bad or len(set(names)) != len(names):
+        raise ValueError(f"adapters {bad or 'repeated in ' + str(names)} are not on this model; it has {sorted(known)}")
+    for m in model.modules():
+        if isinstance(m, LoraLayer):
+            m.set_adapter(names)
+    for n, p in model.named_parameters():
+        if "lora_" in n:
+            p.requires_grad_(any(f".{t}." in n for t in trainable))
+
+
+class Body:
+    """A base with selves g001..g00k frozen and a trainable `present` on top. `chat` says whether prompts go through the
+    tokenizer's chat template (None: yes when there is one and the base is not a base model). `seed` seeds torch at the
+    birth of the present, after the selves are loaded (their loads consume the RNG), so the present's LoRA A is a
+    function of the seed alone."""
+
+    def __init__(self, base: str, selves: list[str], rank: int, alpha: float, targets=None, device=None, dtype=None,
+                 quant=None, truncate_layers=None, present: bool = True, revision: Optional[str] = None, chat: Optional[bool] = None,
+                 seed: Optional[int] = None):
+        self.device = pick_device(device)
+        self.base, self.revision = base, revision
+        self.tok, model = load_model(base, self.device, dtype, quant, truncate_layers, revision)
+        self.chat = (not is_base_model(base, self.tok)) if chat is None else bool(chat)
+        from peft import PeftModel, get_peft_model
+        self.targets = targets or default_targets(model)
+        self.rank, self.alpha = rank, alpha
+        cfg = self.lora_config()
+        self.selves: list[str] = []
+        if selves:
+            model = PeftModel.from_pretrained(model, selves[0], adapter_name="g001", is_trainable=False)
+            self.model = model; self.selves.append("g001"); self.load_weights("g001", selves[0])
+            for i, path in enumerate(selves[1:], start=2):
+                self.selves.append(self.load_self(path, f"g{i:03d}"))
+            if present:
+                if seed is not None:
+                    torch.manual_seed(seed)
+                self._born_present(cfg)
+        else:
+            if present and seed is not None:
+                torch.manual_seed(seed)
+            model = get_peft_model(model, cfg, adapter_name="present") if present else model
+        self.model = model
+        self.has_present = present
+        self.activate()
+
+    def lora_config(self):
+        return lora_config(self.rank, self.alpha, self.targets)
+
+    # ----- which selves speak
+    def activate(self) -> None:
+        if self.has_present:
+            set_active(self.model, self.selves + ["present"], trainable=["present"])
+        elif self.selves:
+            set_active(self.model, self.selves, trainable=[])
+
+    @contextmanager
+    def root(self):
+        """The base alone, every adapter off (a model that carries none is already the root); the body is restored after."""
+        try:
+            if hasattr(self.model, "disable_adapter"):
+                with self.model.disable_adapter():
+                    yield
+            else:
+                yield
+        finally:
+            self.activate()
+
+    @contextmanager
+    def using(self, names: Optional[Iterable[str]]):
+        """Read with exactly these adapters on (None or an empty list: the root); the body is restored after."""
+        names = list(names) if names is not None else []
+        if not names:
+            with self.root():
+                yield
+            return
+        try:
+            set_active(self.model, names, trainable=[]); yield
+        finally:
+            self.activate()
+
+    def present_params(self):
+        return [p for n, p in self.model.named_parameters() if ".present." in n]
+
+    # ----- the adapters' plumbing
+    def _born_present(self, cfg) -> None:
+        """A fresh present on top, in fp32 whatever the base's dtype (peft's add_adapter leaves it in the base's, where an
+        lr of 1e-4 is below bf16's resolution; its get_peft_model path upcasts, so the first life already had this)."""
+        self.model.add_adapter("present", cfg)
+        for p in self.present_params():
+            p.data = p.data.float()
+
+    def load_weights(self, name: str, path: str) -> None:
+        """Copy an adapter file's tensors into the adapter `name` exactly (peft's load rounds the file to the base's dtype
+        before upcasting), and refuse a file that does not fit the body (a self from a differently shaped base)."""
+        from peft import set_peft_model_state_dict
+        from safetensors.torch import load_file
+        path = adapter_dir(path)
+        files = glob.glob(os.path.join(path, "*.safetensors"))
+        if not files:
+            raise FileNotFoundError(f"no adapter weights under {path}")
+        res = set_peft_model_state_dict(self.model, load_file(files[0]), adapter_name=name)
+        missing = [k for k in res.missing_keys if f".{name}." in k]
+        if missing or res.unexpected_keys:
+            raise ValueError(f"{path} does not fit the model ({len(missing)} tensors missing, {len(res.unexpected_keys)} unexpected): "
+                             "a different base, or one truncated to a different number of layers")
+
+    def load_self(self, path: str, name: str) -> str:
+        """Load a saved adapter as the frozen adapter `name`, exactly, without turning it on. Returns the name."""
+        self.model.load_adapter(adapter_dir(path), adapter_name=name, is_trainable=False)
+        self.load_weights(name, path)
+        return name
+
+    def count_tokens(self, text: str) -> int:
+        return len(self.tok(text).input_ids)
+
+    def encode(self, text: str, max_len: int = 384) -> torch.Tensor:
+        return self.tok(text, return_tensors="pt", truncation=True, max_length=max_len).input_ids.to(self.device)
+
+    @torch.no_grad()
+    def dist(self, ids: torch.Tensor, selves: Optional[list[str]] = "stack") -> torch.Tensor:
+        """A self's next-token distribution on `ids`: `selves=None` the root (every adapter off); `"stack"` every frozen
+        self (the parent); a list of adapter names; `"all"` the frozen selves and the present."""
+        self.model.eval()
+        names = None if selves is None else (self.selves if selves == "stack" else (self.selves + ["present"] if selves == "all" else list(selves)))
+        try:
+            with self.using(names):
+                t = self.model(ids).logits.float()
+        finally:
+            self.model.train()
+        return F.softmax(t, dim=-1)
+
+    @torch.no_grad()
+    def token_logps(self, text: str, max_len: int = 384):
+        """The log-probability of each actual next token under the model as it is (every self and the present on)."""
+        ids = self.encode(text, max_len)
+        self.model.eval()
+        lp = F.log_softmax(self.model(ids).logits.float(), dim=-1)[0, :-1]
+        self.model.train()
+        tgt = ids[0, 1:]
+        return tgt.tolist(), lp.gather(-1, tgt.unsqueeze(-1)).squeeze(-1).tolist()
+
+    @torch.no_grad()
+    def perplexity(self, texts: Iterable[str], max_len: int = 384) -> float:
+        self.model.eval()
+        tot, n = 0.0, 0
+        for t in texts:
+            ids = self.encode(t, max_len)
+            if ids.shape[1] < 2:
+                continue
+            out = self.model(ids, labels=ids)
+            tot += out.loss.item() * (ids.shape[1] - 1); n += ids.shape[1] - 1
+        self.model.train()
+        return float(torch.exp(torch.tensor(tot / max(n, 1))))
+
+    @torch.no_grad()
+    def generate(self, prompt: str, max_new: int = 200, temperature: float = 0.7, top_p: float = 0.9, chat: Optional[bool] = None) -> str:
+        self.model.eval()
+        ids = self.prompt_ids(prompt, chat)
+        # greedy decoding passes None for the sampling knobs so a base's own generation_config (Qwen3 ships temperature 0.6,
+        # top_p 0.95, top_k 20) does not make transformers warn three times in the middle of a gate's quiet minutes
+        sample = ({"do_sample": True, "temperature": temperature, "top_p": top_p} if temperature > 0
+                  else {"do_sample": False, "temperature": None, "top_p": None, "top_k": None})
+        out = self.model.generate(input_ids=ids, attention_mask=torch.ones_like(ids), max_new_tokens=max_new,
+                                  pad_token_id=self.tok.pad_token_id, **sample)
+        self.model.train()
+        return self.tok.decode(out[0, ids.shape[1]:], skip_special_tokens=True).strip()
+
+    def chat_ids(self, messages: list, chat: Optional[bool] = None) -> torch.Tensor:
+        """A conversation (OpenAI-style messages: role system/user/assistant, content) as the model expects it: through the chat template
+        when the body reads chat, else as plain 'Role: content' lines ending in 'Assistant:' so a reply starts on its own line."""
+        chat = self.chat if chat is None else chat
+        msgs = [{"role": str(m.get("role", "user")), "content": str(m.get("content", ""))} for m in messages]
+        if chat and getattr(self.tok, "chat_template", None):
+            kw = {"add_generation_prompt": True, "return_tensors": "pt"}
+            try:
+                ids = self.tok.apply_chat_template(msgs, enable_thinking=False, **kw)
+            except TypeError:
+                ids = self.tok.apply_chat_template(msgs, **kw)
+            if not torch.is_tensor(ids):
+                ids = ids["input_ids"]
+            return ids.to(self.device)
+        text = "".join(f"{m['role'].capitalize()}: {m['content'].strip()}\n" for m in msgs) + "Assistant:"
+        return self.tok(text, return_tensors="pt").input_ids.to(self.device)
+
+    def _eos_ids(self) -> set:
+        """Every id the base ends a reply with (a chat template's end-of-turn beside the tokenizer's eos)."""
+        ids = set()
+        for src in (getattr(self.model.generation_config, "eos_token_id", None), self.tok.eos_token_id):
+            if isinstance(src, int):
+                ids.add(src)
+            elif isinstance(src, (list, tuple)):
+                ids.update(int(x) for x in src)
+        return ids
+
+    def _generate_kw(self, ids: torch.Tensor, max_new: int, temperature: float, top_p: float, stop: Optional[list]) -> dict:
+        sample = ({"do_sample": True, "temperature": temperature, "top_p": top_p} if temperature > 0
+                  else {"do_sample": False, "temperature": None, "top_p": None, "top_k": None})
+        kw = {"input_ids": ids, "attention_mask": torch.ones_like(ids), "max_new_tokens": max_new, "pad_token_id": self.tok.pad_token_id, **sample}
+        if stop:
+            kw.update(stop_strings=list(stop), tokenizer=self.tok)    # generation halts at the first stop string (the string itself is in the text)
+        return kw
+
+    def _ended(self, new: torch.Tensor, max_new: int) -> bool:
+        """Whether the reply ended by itself (an end token, or fewer tokens than allowed) rather than at the cap."""
+        return int(new.shape[0]) < max_new or (new.shape[0] > 0 and int(new[-1]) in self._eos_ids())
+
+    @torch.no_grad()
+    def generate_chat(self, messages: list, max_new: int = 200, temperature: float = 0.7, top_p: float = 0.9, chat: Optional[bool] = None,
+                      stop: Optional[list] = None) -> tuple:
+        """One reply to a conversation; returns (reply, prompt_tokens, completion_tokens, ended), `ended` False when the reply hit `max_new`.
+        `stop`: strings at which generation halts (the reply is returned up to and including the one met; the caller cuts it)."""
+        self.model.eval()
+        ids = self.chat_ids(messages, chat)
+        kw = self._generate_kw(ids, max_new, temperature, top_p, stop)
+        try:
+            out = self.model.generate(**kw)
+        except TypeError:                                              # a transformers without stop_strings: generate the cap, the caller cuts
+            kw.pop("stop_strings", None); kw.pop("tokenizer", None)
+            out = self.model.generate(**kw)
+        self.model.train()
+        new = out[0, ids.shape[1]:]
+        return self.tok.decode(new, skip_special_tokens=True).strip(), int(ids.shape[1]), int(new.shape[0]), self._ended(new, max_new)
+
+    def stream_chat(self, messages: list, result: dict, max_new: int = 200, temperature: float = 0.7, top_p: float = 0.9,
+                    chat: Optional[bool] = None, stop: Optional[list] = None):
+        """`generate_chat` as a generator of text pieces, as the tokens come (transformers' TextIteratorStreamer, the generation in a
+        thread). When the generator is exhausted `result` holds reply, prompt_tokens, completion_tokens and ended, as `generate_chat` returns them."""
+        import threading
+        from transformers import TextIteratorStreamer
+        self.model.eval()
+        ids = self.chat_ids(messages, chat)
+        kw = self._generate_kw(ids, max_new, temperature, top_p, stop)
+        streamer = TextIteratorStreamer(self.tok, skip_prompt=True, skip_special_tokens=True, timeout=600.0)
+        kw["streamer"] = streamer
+        held: list = []
+
+        def work():
+            with torch.no_grad():
+                try:
+                    held.append(self.model.generate(**kw))
+                except TypeError:
+                    kw.pop("stop_strings", None); kw.pop("tokenizer", None)
+                    held.append(self.model.generate(**kw))
+                except BaseException as e:                             # the streamer's end() is never reached: release the reader
+                    held.append(e); streamer.end()
+        t = threading.Thread(target=work, daemon=True)
+        t.start()
+        pieces = []
+        try:
+            for piece in streamer:
+                if piece:
+                    pieces.append(piece)
+                    yield piece
+        finally:
+            t.join(timeout=600.0)
+            self.model.train()
+        if held and isinstance(held[0], BaseException):
+            raise held[0]
+        out = held[0]
+        new = out[0, ids.shape[1]:]
+        result.update(reply="".join(pieces).strip(), prompt_tokens=int(ids.shape[1]), completion_tokens=int(new.shape[0]), ended=self._ended(new, max_new))
+
+    def prompt_ids(self, prompt: str, chat: Optional[bool] = None, system: Optional[str] = None) -> torch.Tensor:
+        """A prompt as the model expects it: through the chat template when the body reads chat (`chat` overrides), else
+        the raw text ending in a newline, so a reply or a scored opener starts a new line as it would under a template."""
+        chat = self.chat if chat is None else chat
+        if chat and getattr(self.tok, "chat_template", None):
+            msgs = ([{"role": "system", "content": system}] if system else []) + [{"role": "user", "content": prompt}]
+            kw = {"add_generation_prompt": True, "return_tensors": "pt"}
+            try:
+                ids = self.tok.apply_chat_template(msgs, enable_thinking=False, **kw)
+            except TypeError:
+                ids = self.tok.apply_chat_template(msgs, **kw)
+            if not torch.is_tensor(ids):
+                ids = ids["input_ids"]
+            return ids.to(self.device)
+        text = (system.rstrip() + "\n\n" if system else "") + prompt.rstrip() + "\n"
+        return self.tok(text, return_tensors="pt").input_ids.to(self.device)
+
+    def save_present(self, path: str) -> str:
+        os.makedirs(path, exist_ok=True)
+        self.model.save_pretrained(path, selected_adapters=["present"])
+        return os.path.join(path, "present")
+
+    def finish_fold(self, name: str) -> None:
+        """After `load_self(saved, name)`: the loaded adapter joins the stack as the newest self, the present is dropped and a
+        fresh one is born on top. Seed torch before calling when the fresh present should be reproducible."""
+        self._drop_present()
+        self.selves.append(name)
+        self.activate()
+
+    def fold_present(self, saved_dir: str) -> str:
+        """The present becomes the next frozen self, exactly; a fresh present is born on top. Returns the new self's name."""
+        name = self.load_self(saved_dir, f"g{len(self.selves) + 1:03d}")
+        self.finish_fold(name)
+        return name
+
+    def reset_present(self) -> None:
+        """Drop the present's weights and begin a fresh one (a discard). Seed torch before calling for reproducibility."""
+        self._drop_present()
+        self.activate()
+
+    def _drop_present(self) -> None:
+        """Delete the present (turned off first, so peft does not warn) and bear a fresh one."""
+        set_active(self.model, self.selves, trainable=[])
+        self.model.delete_adapter("present")
+        self._born_present(self.lora_config())
+
+    def drop_self(self, name: str) -> None:
+        """Take the newest self off the model (a discarded life); the present stays."""
+        if not self.selves or self.selves[-1] != name:
+            raise ValueError(f"{name} is not the newest self ({self.selves[-1:] or 'none'})")
+        self.model.delete_adapter(name); self.selves.pop(); self.activate()