methodlm 1.0.1__py3-none-any.whl

methodlm_gui.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""MethodLM desktop GUI -- a local quantum console. No cloud, no framework.
+
+  python methodlm_gui.py            # opens http://127.0.0.1:8777 in your browser
+
+Serves methodlm_gui.html (the quantum front-end) wrapped in an HTML skeleton, plus a
+tiny JSON API the page talks to when it detects the backend:
+  GET  /api/ping                 -> {ok:true}         (page flips to 'live' mode)
+  POST /api/describe {path,...}  -> validate() result (columns, candidates, suggestions)
+  POST /api/run {path,target}    -> runs the real investigation, returns the ledger text
+The same HTML runs standalone as an Artifact (no backend -> simulation mode).
+"""
+import json, os, threading, webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+HTML = os.path.join(HERE, "methodlm_gui.html")
+PORT = 8777
+
+SKELETON = ("<!doctype html><html lang='en'><head><meta charset='utf-8'>"
+            "<meta name='viewport' content='width=device-width,initial-scale=1'>"
+            "<style>html,body{margin:0;background:#0a0603}</style></head><body>{body}</body></html>")
+
+
+def _read_html():
+    with open(HTML, encoding="utf-8") as f:
+        return SKELETON.replace("{body}", f.read())
+
+
+class H(BaseHTTPRequestHandler):
+    def _send(self, code, body, ctype="application/json"):
+        b = body.encode("utf-8") if isinstance(body, str) else body
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(b)))
+        self.end_headers()
+        self.wfile.write(b)
+
+    def log_message(self, *a):  # quiet
+        pass
+
+    def do_GET(self):
+        if self.path in ("/", "/index.html"):
+            self._send(200, _read_html(), "text/html; charset=utf-8")
+        elif self.path == "/api/ping":
+            self._send(200, json.dumps({"ok": True}))
+        else:
+            self._send(404, json.dumps({"error": "not found"}))
+
+    def _body(self):
+        n = int(self.headers.get("Content-Length", 0))
+        return json.loads(self.rfile.read(n) or b"{}")
+
+    def do_POST(self):
+        try:
+            data = self._body()
+        except Exception as e:
+            return self._send(400, json.dumps({"error": f"bad json: {e}"}))
+        if self.path == "/api/describe":
+            from methodlm_io import validate
+            r = validate(data.get("path", ""), data.get("target"),
+                         table=data.get("table"), query=data.get("query"))
+            self._send(200, json.dumps(r))
+        elif self.path == "/api/run":
+            self._send(200, json.dumps(self._run(data)))
+        elif self.path == "/api/race":
+            self._send(200, json.dumps(self._run(data, race=True)))
+        else:
+            self._send(404, json.dumps({"error": "not found"}))
+
+    def _run(self, data, race=False):
+        import methodlm as M
+        from methodlm_io import load_any, featurize, format_report
+        path, target = data.get("path", ""), data.get("target", "")
+        raw, notes = load_any(path, table=data.get("table"), query=data.get("query"))
+        tbl, rep = featurize(raw, target)
+        report = format_report(notes, rep, target)
+        cols = [c for c in tbl if c != target]
+        q = (f"Investigate what actually drives {target} in this dataset "
+             f"(columns: {', '.join(cols[:12])}). Do not trust raw correlations.")
+        name = os.path.splitext(os.path.basename(path))[0]
+        res = M.investigate(name, tbl, target, q, False, ingest_report=report)
+        with open(os.path.join(HERE, f"ledger_{name}.txt"), encoding="utf-8") as f:
+            out = {"ledger": f.read(), "verdict": res["verdict"],
+                   "tested": res["nrun"], "prereg": res["pre"], "gate": res["gate"]}
+        if race:
+            out["vanilla"] = M.vanilla_answer(q)
+        return out
+
+
+def main():
+    srv = ThreadingHTTPServer(("127.0.0.1", PORT), H)
+    url = f"http://127.0.0.1:{PORT}"
+    print(f"MethodLM quantum console -> {url}  (Ctrl+C to stop)")
+    threading.Timer(0.6, lambda: webbrowser.open(url)).start()
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        print("\nstopped.")
+
+
+if __name__ == "__main__":
+    main()

methodlm_io.py

@@ -0,0 +1,246 @@
+"""MethodLM ingestion -- convert many data formats into the canonical table
+(numeric columns + a target) that both halves of MethodLM need, and REPORT every
+transformation so the ledger shows exactly what was done to the data.
+
+load_any(path)         -> (raw column dict, load notes)   dispatch on extension
+featurize(cols,target) -> (numeric column dict, report)   coerce mixed -> numeric
+
+Supported now: .csv .tsv .txt, .json, .jsonl/.ndjson, .parquet/.pq, .db/.sqlite,
+.npz, .xlsx (needs openpyxl). Featurizer handles: numeric, boolean, datetime ->
+date parts, numeric-looking strings, binary + low-card categoricals (one-hot),
+and DROPS free text / high-cardinality columns (stated, with the count).
+
+BOUNDARY (honest): MethodLM asks "what drives the target?" -- it needs columns and a
+target. A lone image, raw audio, or a free-text document is not that until something
+featurizes it into columns with a target. This layer does the tabular conversions;
+it does not pretend a single unlabeled blob is a causal question.
+"""
+import os, re, sqlite3, warnings
+import numpy as np
+
+SUPPORTED_EXT = {".csv", ".tsv", ".txt", ".json", ".jsonl", ".ndjson", ".parquet",
+                 ".pq", ".db", ".sqlite", ".sqlite3", ".npz", ".xlsx", ".xls"}
+IMG_EXT = {".png", ".jpg", ".jpeg", ".bmp", ".gif", ".webp"}
+TXT_EXT = {".txt", ".md", ".log"}
+
+_DATEISH = re.compile(r"\d{4}[-/]\d{1,2}[-/]\d{1,2}|\d{1,2}:\d{2}")
+
+def _looks_datelike(series):
+    sample = series.dropna().astype(str).head(20)
+    return len(sample) > 0 and (sample.str.contains(_DATEISH).mean() > 0.7)
+
+
+def load_any(path, table=None, query=None):
+    ext = os.path.splitext(path)[1].lower()
+    notes = []
+    import pandas as pd
+    if ext in (".csv", ".txt"):
+        df = pd.read_csv(path, sep=None, engine="python")
+    elif ext == ".tsv":
+        df = pd.read_csv(path, sep="\t")
+    elif ext == ".json":
+        df = pd.read_json(path)
+    elif ext in (".jsonl", ".ndjson"):
+        df = pd.read_json(path, lines=True)
+    elif ext in (".parquet", ".pq"):
+        df = pd.read_parquet(path)
+    elif ext in (".xlsx", ".xls"):
+        try:
+            df = pd.read_excel(path)
+        except ImportError:
+            raise SystemExit("Excel support needs:  pip install openpyxl")
+    elif ext in (".db", ".sqlite", ".sqlite3"):
+        con = sqlite3.connect(path)
+        if query:
+            df = pd.read_sql_query(query, con)
+        else:
+            if not table:
+                tabs = pd.read_sql_query(
+                    "SELECT name FROM sqlite_master WHERE type='table'", con)["name"].tolist()
+                if not tabs:
+                    raise SystemExit("no tables in sqlite file")
+                table = tabs[0]
+                notes.append(f"sqlite: auto-selected table '{table}' (of {tabs})")
+            df = pd.read_sql_query(f"SELECT * FROM {table}", con)
+        con.close()
+    elif ext == ".npz":
+        z = np.load(path)
+        df = pd.DataFrame({k: z[k].ravel() for k in z.files})
+        notes.append(f"npz arrays -> columns {list(z.files)}")
+    else:
+        raise SystemExit(f"unsupported extension '{ext}'. Convert to CSV/JSON/Parquet/SQLite.")
+    return {c: df[c].to_numpy() for c in df.columns}, notes
+
+
+def featurize(cols, target):
+    import pandas as pd
+    num, rep = {}, {"kept": [], "encoded": [], "derived": [], "dropped": []}
+
+    def add(name, series):
+        v = pd.to_numeric(series, errors="coerce")
+        num[name] = v.fillna(v.mean()).astype(float).to_numpy()
+
+    for name, arr in cols.items():
+        if name == target:
+            continue
+        s = pd.Series(arr)
+        if pd.api.types.is_bool_dtype(s):
+            num[name] = s.astype(float).to_numpy(); rep["encoded"].append(f"{name}: bool->0/1"); continue
+        if pd.api.types.is_numeric_dtype(s):
+            add(name, s); rep["kept"].append(name); continue
+        co = pd.to_numeric(s, errors="coerce")
+        if co.notna().mean() > 0.9:
+            add(name, s); rep["kept"].append(name); continue
+        if _looks_datelike(s):
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                dt = pd.to_datetime(s, errors="coerce")
+            if dt.notna().mean() > 0.8:
+                made = []
+                for part, vals in [("year", dt.dt.year), ("month", dt.dt.month),
+                                   ("dow", dt.dt.dayofweek), ("hour", dt.dt.hour)]:
+                    if vals.nunique(dropna=True) > 1:
+                        num[f"{name}_{part}"] = vals.fillna(vals.median()).astype(float).to_numpy()
+                        made.append(part)
+                rep["derived"].append(f"{name}: datetime -> {made}"); continue
+        nun = s.nunique(dropna=True)
+        if nun == 2:
+            cats = sorted(map(str, s.dropna().unique()))
+            num[name] = (s.astype(str) == cats[-1]).astype(float).to_numpy()
+            rep["encoded"].append(f"{name}: binary {cats}"); continue
+        if 2 < nun <= 10:
+            for c in sorted(map(str, s.dropna().unique())):
+                num[f"{name}={c}"] = (s.astype(str) == c).astype(float).to_numpy()
+            rep["encoded"].append(f"{name}: one-hot ({nun} levels)"); continue
+        rep["dropped"].append(f"{name}: {nun} categories / free text")
+
+    # target
+    ts = pd.Series(cols[target])
+    ct = pd.to_numeric(ts, errors="coerce")
+    if ct.notna().mean() > 0.9:
+        num[target] = ct.fillna(ct.mean()).astype(float).to_numpy()
+    elif ts.nunique(dropna=True) == 2:
+        cats = sorted(map(str, ts.dropna().unique()))
+        num[target] = (ts.astype(str) == cats[-1]).astype(float).to_numpy()
+        rep["encoded"].append(f"TARGET {target}: binary {cats} -> {cats[-1]}=1")
+    else:
+        raise SystemExit(f"target '{target}' is neither numeric nor binary -- "
+                         f"MethodLM needs a target it can pose 'what drives it' about "
+                         f"({ts.nunique()} distinct values found).")
+
+    n = min(len(v) for v in num.values())
+    return {k: v[:n] for k, v in num.items()}, rep
+
+
+def describe(path, table=None, query=None):
+    """Cheap column census for validation / GUI dropdowns -- names, inferred kinds,
+    row count, and which columns can serve as a target."""
+    import pandas as pd
+    raw, notes = load_any(path, table=table, query=query)
+    cols, n = [], 0
+    for name, arr in raw.items():
+        s = pd.Series(arr); n = max(n, len(s))
+        if pd.api.types.is_bool_dtype(s):
+            kind = "boolean"
+        elif pd.api.types.is_numeric_dtype(s):
+            kind = "numeric"
+        elif pd.to_numeric(s, errors="coerce").notna().mean() > 0.9:
+            kind = "numeric-text"
+        elif _looks_datelike(s):
+            kind = "datetime"
+        else:
+            nun = int(s.nunique(dropna=True))
+            kind = "binary" if nun == 2 else ("categorical" if nun <= 10 else f"text({nun})")
+        cols.append({"name": name, "kind": kind})
+    cands = [c["name"] for c in cols if c["kind"] in ("numeric", "numeric-text", "boolean", "binary")]
+    return {"columns": cols, "n_rows": n, "notes": notes, "target_candidates": cands}
+
+
+def validate(path, target=None, table=None, query=None):
+    """Return {ok, errors, suggestions, info} -- so a caller can reject bad input and
+    show the user exactly what IS valid instead of a stack trace."""
+    import os, difflib
+    out = {"ok": False, "errors": [], "suggestions": [], "info": None}
+    if not os.path.exists(path):
+        out["errors"].append(f"file not found: {path}")
+        return out
+    ext = os.path.splitext(path)[1].lower()
+    if os.path.isfile(path) and ext not in SUPPORTED_EXT:
+        out["errors"].append(f"unsupported format '{ext}'")
+        out["suggestions"] = ["convert to .csv, .json, .parquet, or .sqlite",
+                              "or use --folder for a labelled folder of files"]
+        return out
+    try:
+        info = describe(path, table, query)
+    except SystemExit as e:
+        out["errors"].append(str(e)); return out
+    except Exception as e:
+        out["errors"].append(f"could not read file: {e}"); return out
+    out["info"] = info
+    cols = [c["name"] for c in info["columns"]]
+    if not target:
+        out["errors"].append("choose a target column")
+        out["suggestions"] = info["target_candidates"][:8]
+        return out
+    if target not in cols:
+        near = difflib.get_close_matches(target, cols, n=5, cutoff=0.3)
+        out["errors"].append(f"target '{target}' is not a column")
+        out["suggestions"] = near or info["target_candidates"][:8]
+        return out
+    if target not in info["target_candidates"]:
+        out["errors"].append(f"target '{target}' is text/high-cardinality; MethodLM needs "
+                             f"a numeric or binary target")
+        out["suggestions"] = info["target_candidates"][:8]
+        return out
+    out["ok"] = True
+    return out
+
+
+def load_folder(root, label="__dir__"):
+    """A labelled folder of files -> a feature table. Text files become lexical features,
+    images become basic pixel-statistic features; the label is the parent folder name
+    (so root/spam/*.txt vs root/ham/*.txt gives label=spam/ham). The honest bridge from
+    non-tabular files to MethodLM's 'columns + target' question."""
+    import glob
+    import numpy as np
+    rows = []
+    for path in glob.glob(os.path.join(root, "**", "*"), recursive=True):
+        if not os.path.isfile(path):
+            continue
+        ext = os.path.splitext(path)[1].lower()
+        lab = os.path.basename(os.path.dirname(path)) if label == "__dir__" else label
+        if ext in TXT_EXT:
+            t = open(path, encoding="utf-8", errors="ignore").read()
+            w = t.split()
+            rows.append({"n_chars": len(t), "n_words": len(w),
+                         "avg_word_len": float(np.mean([len(x) for x in w])) if w else 0.0,
+                         "digit_share": sum(c.isdigit() for c in t) / max(len(t), 1),
+                         "upper_share": sum(c.isupper() for c in t) / max(len(t), 1),
+                         "label": lab})
+        elif ext in IMG_EXT:
+            from PIL import Image
+            im = Image.open(path).convert("RGB")
+            a = np.asarray(im, dtype=float) / 255.0
+            rows.append({"width": im.width, "height": im.height,
+                         "aspect": im.width / max(im.height, 1),
+                         "r_mean": float(a[..., 0].mean()), "g_mean": float(a[..., 1].mean()),
+                         "b_mean": float(a[..., 2].mean()), "brightness": float(a.mean()),
+                         "contrast": float(a.std()), "label": lab})
+    if not rows:
+        raise SystemExit(f"no .txt/.md or image files found under {root}")
+    keys = rows[0].keys()
+    return {k: np.array([r.get(k, np.nan) for r in rows], dtype=object if k == "label" else float)
+            for k in keys}, [f"folder {root}: {len(rows)} files -> {len(keys)-1} features + label"]
+
+
+def format_report(notes, rep, target):
+    lines = []
+    for nt in notes:
+        lines.append(f"  {nt}")
+    if rep["kept"]:
+        lines.append(f"  kept numeric ({len(rep['kept'])}): {', '.join(rep['kept'])}")
+    for k in ("encoded", "derived", "dropped"):
+        for item in rep[k]:
+            lines.append(f"  {k}: {item}")
+    lines.append(f"  target: {target}")
+    return "\n".join(lines)

methodlm_models.py

@@ -0,0 +1,294 @@
+"""Model backends for MethodLM -- the discipline is the product, not the model.
+
+The enforced protocol (pre-registration, tools, honest ledger, ternary second witness)
+is identical no matter which model generates the text. A backend only has to turn
+(system, messages) into a reply string. Swap the backend, keep the method.
+
+  local  : Qwen-3B via llama-completion.exe   -- private, offline, free (default)
+  claude : Anthropic API (Claude Opus 4.8)    -- frontier reasoning; needs
+           `pip install anthropic` + credentials (ANTHROPIC_API_KEY or `ant auth login`)
+
+messages is a list of {"role": "user"|"assistant", "content": str}, first turn user.
+"""
+import os
+import subprocess
+
+
+class LocalLlama:
+    kind = "local"
+    label = "local Qwen-3B (offline)"
+
+    def __init__(self, llama, gguf, threads=8, ctx=None):
+        # ctx=3072 was the original default and is too small for multi-candidate panels:
+        # investigate()'s transcript grows by one ADJUST exchange (~500-1000 chars) per
+        # candidate column, and a 7-8 column panel fills 3072 tokens of prompt by turn 8-9
+        # -- with 0 tokens left for the response, llama-completion.exe returns an EMPTY
+        # completion (not a syntax error), which investigate()'s no-progress guard reads as
+        # 3 consecutive unrecognized-tool turns and kills the run with no FINAL. Verified
+        # directly: the qwen3b.gguf here reports n_ctx_train up to 32768 when -c is left at
+        # its own default, so 3072 was an artificial cap, not a model limit. Override via
+        # METHODLM_LOCAL_CTX if a given panel is even larger; 8192 gives headroom for a
+        # ~10-candidate panel (ADJUST + one REFUTE re-check per candidate) at the same
+        # threads/batch settings.
+        if ctx is None:
+            ctx = int(os.environ.get("METHODLM_LOCAL_CTX", "8192"))
+        self.llama, self.gguf, self.threads, self.ctx = llama, gguf, threads, ctx
+        self.label = f"local {os.path.splitext(os.path.basename(gguf))[0]} (gguf)"
+
+    def generate(self, system, messages, max_tokens=230, temp=0.3):
+        parts = [f"<|im_start|>system\n{system}<|im_end|>"]
+        for m in messages:
+            parts.append(f"<|im_start|>{m['role']}\n{m['content']}<|im_end|>")
+        parts.append("<|im_start|>assistant\n")
+        prompt = "\n".join(parts)
+        p = subprocess.run([self.llama, "-m", self.gguf, "-p", prompt, "-n", str(max_tokens),
+                            "-t", str(self.threads), "-c", str(self.ctx), "--special",
+                            "-no-cnv", "--temp", str(temp)],
+                           capture_output=True, text=True, encoding="utf-8", errors="replace")
+        return p.stdout.split("<|im_start|>assistant\n")[-1].split("<|im_end|>")[0].strip()
+
+
+class ClaudeAPI:
+    kind = "claude"
+
+    def __init__(self, model="claude-opus-4-8"):
+        try:
+            import anthropic
+        except ImportError:
+            raise SystemExit("claude backend needs the SDK:  pip install anthropic")
+        self.model = model
+        self.label = f"Claude ({model})"
+        try:
+            self._client = anthropic.Anthropic()          # resolves key/profile from env
+            self._client.models.list(limit=1)             # validate credentials up front
+        except Exception as e:
+            raise SystemExit(f"Claude unavailable (need ANTHROPIC_API_KEY): {str(e)[:70]}")
+
+    def generate(self, system, messages, max_tokens=230, temp=None):
+        # Opus 4.8: system is separate; temperature/thinking omitted (rejected on 4.8).
+        resp = self._client.messages.create(
+            model=self.model, max_tokens=max(max_tokens, 512), system=system,
+            messages=[{"role": m["role"], "content": m["content"]} for m in messages])
+        return "".join(b.text for b in resp.content if b.type == "text").strip()
+
+
+class OllamaModel:
+    """A local model served by Ollama (http://localhost:11434) -- unlike LocalLlama, no
+    separate binary/GGUF path management: whatever's already been `ollama pull`ed just
+    works, GPU-accelerated where the model fits in VRAM, transparently CPU-offloaded for
+    the layers that don't. Uses /api/chat (not /api/generate) since the harness's tool
+    loop needs real multi-turn system+messages semantics, not a single flat prompt."""
+    kind = "ollama"
+
+    def __init__(self, model, url=None):
+        import urllib.request
+        self._urllib = urllib.request
+        self.model = model
+        self.url = url or os.environ.get("OLLAMA_URL", "http://localhost:11434/api/chat")
+        self.label = f"local {model} (ollama)"
+
+    def generate(self, system, messages, max_tokens=230, temp=0.3):
+        import json
+        payload = {
+            "model": self.model,
+            "messages": [{"role": "system", "content": system}] + list(messages),
+            "stream": False,
+            "options": {"temperature": temp, "num_predict": max_tokens},
+        }
+        body = json.dumps(payload).encode("utf-8")
+        req = self._urllib.Request(self.url, data=body, headers={"Content-Type": "application/json"})
+        with self._urllib.urlopen(req, timeout=600) as resp:
+            return json.loads(resp.read())["message"]["content"].strip()
+
+
+class HFModel:
+    """A local Hugging Face causal LM (torch) -- e.g. the method-baked Qwen-0.5B."""
+    kind = "hf"
+
+    def __init__(self, path, label=None):
+        import torch
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+        self._torch = torch
+        self.tok = AutoTokenizer.from_pretrained(path)
+        self.model = AutoModelForCausalLM.from_pretrained(path, dtype=torch.float32).eval()
+        self.label = label or f"HF ({os.path.basename(str(path))})"
+
+    def generate(self, system, messages, max_tokens=230, temp=0.0):
+        chat = [{"role": "system", "content": system}] + list(messages)
+        enc = self.tok.apply_chat_template(chat, add_generation_prompt=True,
+                                           return_tensors="pt", return_dict=True)
+        with self._torch.no_grad():
+            out = self.model.generate(**enc, max_new_tokens=max_tokens, do_sample=False)
+        return self.tok.decode(out[0][enc["input_ids"].shape[1]:], skip_special_tokens=True).strip()
+
+
+class ContrastiveQwenHF:
+    """Contrastive-decoding backend: a real strong/weak Qwen2.5-Instruct pair
+    (default 1.5B strong vs 0.5B weak, same family/tokenizer -- Qwen2.5-0.5B-
+    Instruct and Qwen2.5-1.5B-Instruct), amplified via
+    structured_attention.contrastive_next_token_logits (Li et al. 2022:
+    amplified = strong + alpha*(strong - weak), masked to the strong model's
+    own plausible tokens). Same idea as LocalLlama/HFModel above -- turn
+    (system, messages) into a reply string -- so it drops straight into the
+    backend-selection slot; the method (PREREGISTER/tools/ledger) doesn't
+    change, only which model proposes each turn's tool call and verdict.
+
+    Built from, and reuses, the already-tested amplification primitive from
+    golden-attention/demo_contrastive_qwen.py -- this class adds a real
+    KV-cache (past_key_values reused across steps for BOTH models) instead
+    of that demo's recompute-the-whole-sequence-every-token loop, because
+    investigate() calls generate() repeatedly on a growing multi-turn
+    transcript (up to 24 turns) -- without a cache that loop is quadratic in
+    generated length per call and compounds across turns; with it, each new
+    token is one incremental forward pass per model, same as any normal
+    HF .generate() call.
+
+    Needs `pip install transformers` plus the (editable, not on PyPI)
+    structured-attention package -- tries a plain `import structured_attention`
+    first (already pip-installed editable in this checkout's environment);
+    if that fails, falls back to METHODLM_STRUCTURED_ATTENTION pointing at a
+    checkout of https://github.com/gbranaa4-hue/structured-attention, same
+    optional-path-override pattern as METHODLM_TRITKIT."""
+    kind = "contrastive"
+
+    def __init__(self, weak_name=None, strong_name=None, alpha=None, beta=None):
+        import torch
+        try:
+            from structured_attention import contrastive_next_token_logits
+        except ImportError:
+            sa_path = os.environ.get("METHODLM_STRUCTURED_ATTENTION")
+            if not sa_path:
+                raise SystemExit(
+                    "contrastive backend needs structured_attention: "
+                    "pip install -e /path/to/structured-attention, or set "
+                    "METHODLM_STRUCTURED_ATTENTION=/path/to/structured-attention")
+            import sys
+            sys.path.insert(0, sa_path)
+            try:
+                from structured_attention import contrastive_next_token_logits
+            except ImportError as e:
+                raise SystemExit(f"contrastive backend: structured_attention still "
+                                  f"not importable from {sa_path}: {e}")
+        try:
+            from transformers import AutoModelForCausalLM, AutoTokenizer
+        except ImportError:
+            raise SystemExit("contrastive backend needs the SDK:  pip install transformers")
+
+        self._torch = torch
+        self._amplify = contrastive_next_token_logits
+        self.weak_name = weak_name or os.environ.get("METHODLM_CD_WEAK", "Qwen/Qwen2.5-0.5B-Instruct")
+        self.strong_name = strong_name or os.environ.get("METHODLM_CD_STRONG", "Qwen/Qwen2.5-1.5B-Instruct")
+        self.alpha = alpha if alpha is not None else float(os.environ.get("METHODLM_CD_ALPHA", "1.0"))
+        self.beta = beta if beta is not None else float(os.environ.get("METHODLM_CD_BETA", "0.1"))
+        self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        dtype = torch.bfloat16 if self.device == "cuda" else torch.float32
+
+        self.tok = AutoTokenizer.from_pretrained(self.strong_name)
+        self.weak = AutoModelForCausalLM.from_pretrained(self.weak_name, dtype=dtype).to(self.device).eval()
+        self.strong = AutoModelForCausalLM.from_pretrained(self.strong_name, dtype=dtype).to(self.device).eval()
+        eos_cfg = getattr(self.strong.generation_config, "eos_token_id", None)
+        self.eos_ids = set(eos_cfg) if isinstance(eos_cfg, (list, tuple, set)) else \
+            ({eos_cfg} if eos_cfg is not None else {self.tok.eos_token_id})
+        self.label = (f"contrastive {self.strong_name.split('/')[-1]} vs "
+                       f"{self.weak_name.split('/')[-1]} (alpha={self.alpha}, {self.device})")
+
+    def _sample(self, logits, temp, top_k):
+        torch = self._torch
+        if temp is None or temp <= 1e-6:
+            return logits.argmax(dim=-1, keepdim=True)
+        logits = logits / temp
+        finite = torch.isfinite(logits).sum(dim=-1, keepdim=True).item()
+        k = max(1, min(top_k, finite))
+        v, _ = torch.topk(logits, k)
+        logits = logits.masked_fill(logits < v[:, [-1]], float("-inf"))
+        probs = torch.softmax(logits, dim=-1)
+        return torch.multinomial(probs, 1)
+
+    def generate(self, system, messages, max_tokens=230, temp=0.3, top_k=40):
+        torch = self._torch
+        chat = [{"role": "system", "content": system}] + list(messages)
+        # tokenize=False then a separate tok(...) call, not apply_chat_template's own
+        # return_tensors="pt" -- that path returned a BatchEncoding instead of a plain
+        # tensor against this checkout's transformers version (5.12.1); same two-step
+        # route the already-tested demo_contrastive_qwen.py uses.
+        text = self.tok.apply_chat_template(chat, tokenize=False, add_generation_prompt=True)
+        input_ids = self.tok(text, return_tensors="pt").input_ids.to(self.device)
+        with torch.no_grad():
+            s_out = self.strong(input_ids, use_cache=True)
+            w_out = self.weak(input_ids, use_cache=True)
+            s_past, w_past = s_out.past_key_values, w_out.past_key_values
+            generated = []
+            for _ in range(max_tokens):
+                s_logits = s_out.logits[:, -1, :].float()
+                w_logits = w_out.logits[:, -1, :].float()
+                amplified = self._amplify(s_logits, w_logits, alpha=self.alpha, plausibility_beta=self.beta)
+                next_tok = self._sample(amplified, temp, top_k)
+                tok_id = int(next_tok.item())
+                if tok_id in self.eos_ids:
+                    break
+                generated.append(tok_id)
+                s_out = self.strong(next_tok, past_key_values=s_past, use_cache=True)
+                w_out = self.weak(next_tok, past_key_values=w_past, use_cache=True)
+                s_past, w_past = s_out.past_key_values, w_out.past_key_values
+        text = self.tok.decode(generated, skip_special_tokens=True).strip()
+        # Real problem, found running this against investigate()'s multi-turn loop (up to 24
+        # turns, transcript growing every turn): each generate() call re-prefills the WHOLE
+        # growing conversation from scratch (no cache persists across separate calls, by
+        # design -- investigate() calls generate() fresh each turn), and PyTorch's CUDA
+        # caching allocator doesn't return freed blocks to the driver between calls. On an
+        # 8GB card this compounded turn over turn -- watched it go from ~1GB free after load
+        # to ~100MB free by turn ~13 of a single item, 100% GPU util but barely progressing
+        # (allocator thrashing/fragmentation, not real compute). del the local references and
+        # empty_cache() explicitly once per turn so the freed blocks actually go back; small,
+        # fixed per-turn cost, but keeps a multi-turn run from starving itself out by the time
+        # a panel has many candidate columns.
+        del s_out, w_out, s_past, w_past, input_ids
+        if self.device == "cuda":
+            torch.cuda.empty_cache()
+        return text
+
+
+def get_model(name, here):
+    name = (name or "local").lower()
+    # The real llama-completion.exe + DLLs + GGUF files are a multi-GB local build, not
+    # something to duplicate into every checkout that imports methodlm.py -- optional override
+    # for when they live somewhere other than next to this file (e.g. mesh_rag_server.py imports
+    # methodlm.py from the canonical repo, but the actual binary/GGUFs only exist in llama_demo).
+    # Defaults to `here` (unchanged behavior) if unset.
+    bin_dir = os.environ.get("METHODLM_LOCAL_BIN_DIR", here)
+    llama = os.path.join(bin_dir, "bin", "llama-completion.exe")
+    if name in ("local", "qwen", "llama", "qwen3b", "3b"):
+        return LocalLlama(llama, os.path.join(bin_dir, "qwen3b.gguf"))
+    if name in ("qwen05b", "qwen0.5b", "0.5b", "small"):
+        return LocalLlama(llama, os.path.join(bin_dir, "qwen.gguf"))
+    if name in ("baked", "method-baked", "baked05b"):
+        # Same "the real weights live in llama_demo, not next to this file" situation as
+        # the llama.cpp binary/GGUFs above -- reuse the same bin_dir override rather than
+        # inventing a second env var for the same real problem.
+        return HFModel(os.path.join(bin_dir, "method_baked_v2"), "method-baked Qwen-0.5B")
+    # Any already-`ollama pull`ed model, GPU-accelerated with automatic CPU offload for
+    # what doesn't fit in VRAM -- no separate binary/GGUF path management like LocalLlama.
+    # "ollama:<tag>" is the general form; a couple of real, currently-installed models get
+    # short aliases since they're the ones actually used for the harness benchmark.
+    ollama_aliases = {"qwen7b": "qwen2.5-coder:7b", "qwen2.5-coder-7b": "qwen2.5-coder:7b",
+                       "qwen14b": "qwen2.5-coder:14b", "qwen2.5-coder-14b": "qwen2.5-coder:14b",
+                       # official Microsoft BitNet b1.58 2B-4T -- real ternary {-1,0,+1}
+                       # weights (not the 4-bit-quantized-down-to-"1-bit"-branding kind), pulled
+                       # via hf.co/microsoft/bitnet-b1.58-2B-4T-gguf since the locally-downloaded
+                       # bitnet.gguf used a since-removed llama.cpp quant type (TYPE_IQ4_NL_4_4)
+                       # and can no longer be loaded by any current build.
+                       "bitnet": "hf.co/microsoft/bitnet-b1.58-2B-4T-gguf"}
+    if name in ollama_aliases:
+        return OllamaModel(ollama_aliases[name])
+    if name.startswith("ollama:"):
+        return OllamaModel(name.split(":", 1)[1])
+    if name in ("contrastive", "cd", "contrastive-qwen", "cdqwen"):
+        # real 1.5B-vs-0.5B Qwen2.5-Instruct pair, amplified via
+        # structured_attention.contrastive_next_token_logits -- see
+        # ContrastiveQwenHF's docstring above for the full rationale.
+        return ContrastiveQwenHF()
+    frontier = {"claude": "claude-opus-4-8", "opus": "claude-opus-4-8",
+                "sonnet": "claude-sonnet-5", "haiku": "claude-haiku-4-5", "api": "claude-opus-4-8"}
+    if name in frontier:
+        return ClaudeAPI(frontier[name])
+    raise SystemExit(f"unknown model backend '{name}' -- use: qwen3b|qwen05b|baked|qwen7b|qwen14b|ollama:<tag>|contrastive|opus|sonnet|haiku")

rescore.py

@@ -0,0 +1,17 @@
+"""Re-score a saved benchmark audit JSON with the CURRENT judge (no API spend)."""
+import json, sys
+from collections import Counter
+from benchmark_models import judge
+
+path = sys.argv[1] if len(sys.argv) > 1 else "benchmark_models_audit.json"
+d = json.load(open(path, encoding="utf-8"))
+models = dict.fromkeys(r["model"] for r in d)
+for model in models:
+    for cond in ("plain", "harness"):
+        rows = [r for r in d if r["model"] == model and r["cond"] == cond]
+        if not rows:
+            continue
+        t = Counter(judge(r["verdict"], r["cause"], r["decoy"], r["conf"]) for r in rows)
+        n = len(rows)
+        print(f"{model:>22} | {cond:>7} | CAUSE {t['cause']}/{n} | DECOY {t['decoy']}/{n} | "
+              f"conf {t['conf']}/{n} | wrong {t['wrong']}/{n} | reject {t['reject']}/{n} | hedge {t['hedge']}/{n}")