1"""Trial planner and executor for single-handoff experiments (Tracks A and B; one process; laptop).23A *condition* is a method + parameters + question-access regime. A *trial* is (condition, model pair, document, question).4Question-blind messages/caches are built once per (condition, document) and reused across that document's questions —5this is the reuse scenario, and the build cost is recorded on every trial as `doc_build_ms` with `reuse_count` = number of6questions that shared it. The runner is resumable: successful trial keys are skipped; failures are kept and retried once.7"""8from __future__ import annotations9import json, time, traceback, yaml, sys, os10from pathlib import Path11import numpy as np12import mlx.core as mx1314from .util import ROOT, read_json, write_json, sha256_json, sha256_text, utc_now, Timer, read_jsonl15from .records import new_record, write_record, trial_key16from .data.prepare import load_doc, load_key17from .scoring import score_synthetic, score_public18from .data.exec_tasks import run_hidden_tests19from .prompts import SYSTEM_RECEIVER, SYSTEM_RECEIVER_NOMSG, receiver_user_text, receiver_question_only20from .backends.mlx_backend import MLXModel, deep_copy_cache, memory_snapshot, reset_peak21from .cache.sparse import quantize_cache, cache_tensor_bytes, to_sparse_all22from .cache.selection import select_cache23from .cache.serialize import build_manifest, serialize_cache, deserialize_cache, codec_compress, codec_decompress24from .methods import text as TM2526FIDELITY = {"A0": "custom", "A1": "custom", "A2": "custom", "A3": "custom", "A4": "custom", "A5": "custom", "A6": "custom", "A7": "custom",27 "A8": "official", "B0": "custom", "B1": "custom", "B2": "custom", "B2b": "inspired", "B3": "inspired", "B4": "custom",28 "B5": "faithful_reimplementation", "B6": "faithful_reimplementation", "B9": "custom"}2930HARDWARE_ID = "laptop-m5max-48g"3132def _load_models(cfg):33 mcfg = yaml.safe_load(open(ROOT / "configs/models.yaml"))["models"]34 cache = {}35 def get(alias):36 if alias not in cache:37 cache[alias] = MLXModel(mcfg[alias]["repo"])38 return cache[alias]39 return get, mcfg4041def _select_items(cfg):42 man = read_json(ROOT / "data/manifests/splits.json")43 items = [it for it in man["items"] if it["split"] in cfg["splits"] and it["family"] in cfg["families"]]44 if cfg.get("lengths"):45 items = [it for it in items if it.get("target_tokens") is None or it["target_tokens"] in cfg["lengths"]]46 lim = cfg.get("limit_docs_per_family")47 if lim:48 out = []49 for fam in cfg["families"]:50 out += [it for it in items if it["family"] == fam][:lim]51 items = out52 return items5354def _cond_id(c: dict) -> str:55 parts = [c["method"]]56 for k in sorted(c):57 if k not in ("method", "access", "note"):58 parts.append(f"{k}={c[k]}")59 if "access" in c:60 parts.append(c["access"])61 return "|".join(parts)6263def plan(config_path: str, output: str) -> int:64 cfg = yaml.safe_load(open(config_path))65 items = _select_items(cfg)66 rows = []67 pairs = cfg["model_pairs"]68 for it in items:69 doc = load_doc(it["document_id"], it["family"])70 nq = len(doc["questions"]) if not cfg.get("max_questions_per_doc") else min(len(doc["questions"]), cfg["max_questions_per_doc"])71 for pair in pairs:72 for c in cfg["conditions"]:73 for seed in cfg.get("seeds", [0]):74 rows.append({"experiment_id": cfg["experiment_id"], "condition": _cond_id(c), "method": c["method"], "access": c.get("access", "none"),75 "sender": pair["sender"], "receiver": pair["receiver"], "family": it["family"], "document_id": it["document_id"],76 "split": it["split"], "target_tokens": it.get("target_tokens"), "n_questions": nq, "seed": seed, "expected_trials": nq})77 import csv78 Path(output).parent.mkdir(parents=True, exist_ok=True)79 with open(output, "w", newline="") as f:80 w = csv.DictWriter(f, fieldnames=list(rows[0].keys())); w.writeheader(); w.writerows(rows)81 tot = sum(r["expected_trials"] for r in rows)82 print(f"plan: {len(items)} documents, {len(cfg['conditions'])} conditions, {len(pairs)} model pairs -> {len(rows)} doc-conditions, {tot} trials -> {output}")83 return 08485# --------------------------------------------------------------------------------------------------------------------86class DocContext:87 """Per-document receiver state: tokenized prefix and dense cache (built lazily once)."""88 def __init__(self, receiver: MLXModel, doc_text: str, family: str):89 self.receiver = receiver; self.doc_text = doc_text; self.family = family90 self._dense = None; self.build_ms = None; self.prefix_ids = None; self.full_ids_fn = None91 self.sys = SYSTEM_RECEIVER92 def prefix_tokens(self):93 if self.prefix_ids is None:94 pre_txt = self.receiver.tokenizer.apply_chat_template([{"role": "system", "content": self.sys}, {"role": "user", "content": "Document:\n" + self.doc_text + "\n\n"}], add_generation_prompt=False, tokenize=False)95 self.prefix_ids = self.receiver.encode(pre_txt)96 return self.prefix_ids97 def split_ids(self, question: str):98 """Full chat tokens for (doc, question); returns (prefix_ids, query_ids) with prefix a true token prefix."""99 full = self.receiver.chat_prompt_tokens([{"role": "system", "content": self.sys}, {"role": "user", "content": receiver_user_text("Document", self.doc_text, question, self.family)}])100 pre = self.prefix_tokens()101 n = 0102 while n < min(len(pre), len(full)) and pre[n] == full[n]:103 n += 1104 return full[:n], full[n:]105 def dense_cache(self, prefix_ids):106 if self._dense is None or self._dense_len != len(prefix_ids):107 reset_peak()108 c, t = self.receiver.prefill(prefix_ids)109 self._dense = c; self._dense_len = len(prefix_ids); self.build_ms = t["prefill_ms"]; self.build_peak = int(mx.get_peak_memory())110 return self._dense111112def _score(family: str, pred: str, qkey: dict, key: dict) -> dict:113 if family == "exec":114 r = run_hidden_tests(pred, key["hidden_tests"])115 return {"correct": r["correct"], "pass_rate": r["pass_rate"], "error": r.get("error")}116 if family.startswith("public_"):117 return score_public(pred, [qkey["answer"]] + list(qkey.get("aliases", [])))118 return score_synthetic(pred, qkey)119120def run(config_path: str, resume: bool = False, limit: int | None = None, dry_run: bool = False) -> int:121 cfg = yaml.safe_load(open(config_path))122 res = yaml.safe_load(open(ROOT / "configs/resources.yaml"))123 protocol_hash = cfg.get("protocol_hash") or "unfrozen"124 config_hash = sha256_json(cfg)125 out_path = ROOT / "runs/raw" / f"{cfg['experiment_id']}.jsonl"126 done = set()127 if resume and out_path.exists():128 for r in read_jsonl(out_path):129 if r["status"] == "success":130 done.add(r["trial_id"])131 items = _select_items(cfg)132 get_model, mcfg = _load_models(cfg)133 gen_max = cfg.get("generation", {}).get("max_tokens", 48)134 n_done = n_run = n_fail = 0135 log_path = ROOT / "runs/logs" / f"{cfg['experiment_id']}.log"136 log_path.parent.mkdir(parents=True, exist_ok=True)137 def log(msg):138 line = f"{utc_now()} {msg}"139 print(line, flush=True)140 with open(log_path, "a") as f: f.write(line + "\n")141 log(f"run start experiment={cfg['experiment_id']} config_hash={config_hash[:12]} protocol={protocol_hash[:12]} items={len(items)} resume={resume} already_done={len(done)}")142 if dry_run:143 return plan(config_path, str(ROOT / "protocol" / f"{cfg['experiment_id']}_dryrun.csv"))144 t_start = time.time()145 for it in items:146 fam = it["family"]; doc = load_doc(it["document_id"], fam); key = load_key(it["document_id"], fam)147 qs = doc["questions"][: cfg.get("max_questions_per_doc") or None]148 qkeys = {q["question_id"]: q for q in key["questions"]}149 for pair in cfg["model_pairs"]:150 receiver = get_model(pair["receiver"]); sender = get_model(pair["sender"])151 dc = DocContext(receiver, doc["text"], fam)152 for cond in cfg["conditions"]:153 cid = _cond_id(cond); method = cond["method"]; access = cond.get("access", "none")154 if method.startswith("B"):155 access = cond.get("access", "blind")156 for seed in cfg.get("seeds", [0]):157 # trials for this (doc, cond, pair, seed)158 pending = []159 for q in qs:160 tk = trial_key(cfg["experiment_id"], it["document_id"], q["question_id"], method, {k: v for k, v in cond.items() if k != "method"},161 pair["sender"], pair["receiver"], access, protocol_hash, seed)162 if tk in done:163 n_done += 1; continue164 pending.append((q, tk))165 if not pending:166 continue167 if limit is not None and n_run >= limit:168 log(f"limit {limit} reached"); return 0169 # ---- build the question-blind message / cache once per document (reuse scenario)170 shared = None; shared_err = None171 if access in ("blind", "none"):172 try:173 shared = _build_message(method, cond, doc["text"], None, sender, receiver, dc, seed)174 except Exception as e:175 shared_err = e176 log(f"BUILD FAIL {cid} {it['document_id']}: {type(e).__name__}: {str(e)[:200]}")177 for q, tk in pending:178 rec = _run_one(cfg, cond, cid, method, access, pair, it, doc, q, qkeys.get(q["question_id"]), key, sender, receiver, dc, seed, tk, shared, shared_err, gen_max, protocol_hash, config_hash, len(pending))179 write_record(rec, out_path)180 n_run += 1181 if rec["status"] != "success": n_fail += 1182 sc = rec["task_scores"] or {}183 log(f"{cid:>40s} {it['document_id']:>28s} {q['question_id']:>14s} {rec['status']:>10s} corr={sc.get('correct', sc.get('f1'))} bytes={rec['serialized_payload_bytes']} ms={rec['total_wall_ms'] and round(rec['total_wall_ms'])} ans={json.dumps((rec['prediction_artifact'] or '')[:60])}")184 if limit is not None and n_run >= limit:185 log(f"limit {limit} reached"); return 0186 mx.clear_cache()187 log(f"run end: ran={n_run} skipped_done={n_done} failed={n_fail} elapsed_s={round(time.time()-t_start)}")188 return 0189190def _build_message(method, cond, doc_text, question, sender, receiver, dc: DocContext, seed):191 """Returns dict with message (Track A) or cache payload info (Track B); encode timings included."""192 t = Timer(); t.start("encode")193 out = {"method": method}194 if method == "A0":195 out["msg"] = TM.a0_no_message()196 elif method == "A1":197 out["msg"] = TM.a1_full(doc_text)198 elif method == "A2":199 out["msg"] = TM.a2_truncate(doc_text, cond["budget_tokens"], receiver.tokenizer)200 elif method == "A3":201 out["msg"] = TM.a3_extractive(doc_text, cond["budget_tokens"], receiver.tokenizer, question)202 elif method == "A4":203 out["msg"] = TM.a4_summary(doc_text, cond["budget_tokens"], sender, question)204 elif method == "A5":205 out["msg"] = TM.a5_structured(doc_text, cond["budget_tokens"], sender, question)206 elif method == "A6":207 out["msg"] = TM.a6_references(doc_text, cond["budget_tokens"], sender, question)208 elif method == "A7":209 out["msg"] = TM.a7_codec(doc_text, cond.get("codec", "zstd"))210 elif method == "A8":211 out["msg"] = TM.a8_llmlingua(doc_text, cond["budget_tokens"], receiver.tokenizer, question, device=cond.get("device", "mps"))212 elif method.startswith("B"):213 pre = dc.prefix_tokens()214 dense = dc.dense_cache(pre)215 out["doc_build_ms"] = dc.build_ms; out["doc_build_peak"] = dc.build_peak; out["prefix_tokens"] = len(pre)216 out["dense_bytes"] = cache_tensor_bytes(dense)217 t.start("compress")218 if method == "B0":219 c = to_sparse_all(deep_copy_cache(dense)); info = {}220 elif method == "B1":221 c = to_sparse_all(deep_copy_cache(dense)); info = {"serialize_roundtrip": True}222 elif method == "B2":223 c = quantize_cache(dense, cond["bits"], cond.get("group_size", 64)); info = {"bits": cond["bits"]}224 elif method in ("B3", "B4", "B5", "B6", "B9"):225 policy = {"B3": "sink_recent", "B4": "random", "B5": "attention", "B6": "pyramid", "B9": cond.get("policy", "sink_recent")}[method]226 window = None227 if policy in ("attention", "pyramid"):228 if question is not None:229 window = dc.split_ids(question)[1] # question-aware: the fresh query tokens are the observation window230 else:231 window = receiver.encode("\n\nSummarize the key facts, identifiers, amounts, dates and statuses of this document.") # question-blind generic instruction232 c, info = select_cache(receiver, dense, policy, cond["keep_frac"], window_token_ids=window, seed=seed, sinks=cond.get("sinks", 4), window_keep=cond.get("window_keep", 32))233 if method == "B9":234 c = quantize_cache(c, cond["bits"], cond.get("group_size", 64)); info["bits"] = cond["bits"]235 else:236 raise NotImplementedError(method)237 mx.eval([x for cc in c for x in (cc.keys if isinstance(cc.keys, tuple) else (cc.keys,))])238 mx.synchronize()239 t.stop("compress")240 t.start("serialize")241 man = build_manifest(receiver.info, pre, c, "doc", method, {k: v for k, v in cond.items() if k != "method"}, {"selection_info": {k: v for k, v in info.items() if k != "layer_budgets"}})242 payload = serialize_cache(c, man)243 t.stop("serialize")244 codec = cond.get("codec", "none")245 comp, comp_ms = codec_compress(payload, codec) if codec != "none" else (payload, 0.0)246 out.update({"cache": c, "payload": comp, "payload_bytes": len(comp), "raw_payload_bytes": len(payload), "cache_bytes": cache_tensor_bytes(c), "manifest": man,247 "compress_ms": t.spans.get("compress", 0.0), "serialize_ms": t.spans["serialize"] + comp_ms, "codec": codec, "select_info": info})248 else:249 raise NotImplementedError(method)250 t.stop("encode")251 out["encode_ms"] = t.spans["encode"]252 return out253254def _run_one(cfg, cond, cid, method, access, pair, it, doc, q, qkey, key, sender, receiver, dc, seed, tk, shared, shared_err, gen_max, protocol_hash, config_hash, reuse_count):255 fam = it["family"]256 rec = new_record(experiment_id=cfg["experiment_id"], trial_id=tk, run_group_id=cfg["experiment_id"] + ":" + cid, protocol_hash=protocol_hash, config_hash=config_hash,257 task_family=fam, document_id=it["document_id"], document_hash=it["document_hash"], question_id=q["question_id"], split=it["split"], cluster_id=it["cluster_id"],258 sender_model_revision=f"{sender.info.repo_id}@{sender.info.revision}", receiver_model_revision=f"{receiver.info.repo_id}@{receiver.info.revision}",259 tokenizer_hashes={"sender": sender.info.tokenizer_hash, "receiver": receiver.info.tokenizer_hash},260 backend_versions={"mlx": mx.__version__, "mlx_lm": receiver.info.mlx_lm_version}, hardware_id=HARDWARE_ID, device_state={"mlx_active_before": int(mx.get_active_memory())},261 weight_precision="bf16", method_id=method, implementation_fidelity=FIDELITY.get(method, "custom"),262 compression_config={k: v for k, v in cond.items() if k != "method"}, question_access=access, topology="single_handoff", handoff_index=1 if method != "A0" else 0,263 reuse_count=reuse_count if access in ("blind", "none") else 1, cache_hit=(access in ("blind", "none") and method.startswith("B")), cache_compatibility_hash=None,264 random_seed=seed, query_tokens=None, message_tokens=None, message_utf8_bytes=None, cache_tensor_bytes=None, serialized_payload_bytes=None,265 input_usage={}, output_usage={}, provider_cached_usage=None, process_memory=None, backend_memory=None, peak_prefill_memory=None, peak_decode_memory=None,266 mapper_memory=None, cost_with_source=None, prediction_artifact=None, evidence_artifact=None, reference_key_id=f"keys/{fam}/{it['document_id']}.json",267 task_scores=None, status="implementation_error", error_code=None, log_artifact=f"runs/logs/{cfg['experiment_id']}.log", payload_hash=None, output_hash=None)268 rec["source_tokens_sender"] = len(sender.encode(doc["text"])); rec["source_tokens_receiver"] = len(receiver.encode(doc["text"]))269 t_total0 = time.perf_counter()270 try:271 if shared_err is not None:272 raise shared_err273 built = shared if shared is not None else _build_message(method, cond, doc["text"], q["question"], sender, receiver, dc, seed)274 spans = {"encode_ms": built["encode_ms"]}275 reset_peak()276 if method.startswith("A"):277 msg = built["msg"]278 if method == "A6":279 material, rinfo = TM.a6_retrieve(msg, q["question"], cond.get("max_fetch_bytes", 2000), cond.get("max_lookups", 6))280 rec["fetched_bytes"] = rinfo["fetched_bytes"]; rec["evidence_artifact"] = rinfo281 else:282 material = msg.text283 if method == "A0":284 ids = receiver.chat_prompt_tokens([{"role": "system", "content": SYSTEM_RECEIVER_NOMSG}, {"role": "user", "content": receiver_question_only(q["question"], fam)}])285 else:286 ids = receiver.chat_prompt_tokens([{"role": "system", "content": SYSTEM_RECEIVER}, {"role": "user", "content": receiver_user_text(msg.material_label, material, q["question"], fam)}])287 spans["decode_payload_ms"] = msg.decode_ms288 g = receiver.generate_text(ids, max_tokens=gen_max)289 spans.update({"receiver_prefill_ms": g["prefill_ms"], "ttft_ms": g["ttft_ms"], "decode_ms": g["decode_ms"]})290 rec.update({"message_tokens": len(receiver.encode(material)), "message_utf8_bytes": msg.utf8_bytes, "serialized_payload_bytes": msg.payload_bytes,291 "side_information_bytes": msg.side_information_bytes, "query_tokens": len(ids), "input_usage": {"receiver_prompt_tokens": len(ids), **msg.sender_usage},292 "payload_hash": sha256_text(material)})293 if msg.meta: rec["compression_config"] = {**rec["compression_config"], "realized": {k: v for k, v in msg.meta.items() if k not in ("question_aware",)}}294 if method == "A5": rec["evidence_artifact"] = {"n_facts": msg.meta.get("n_facts"), "unresolved_quotes": msg.meta.get("unresolved_quotes"), "parse_ok": msg.meta.get("parse_ok")}295 else:296 pre, query_ids = dc.split_ids(q["question"])297 assert len(pre) == built["prefix_tokens"], "prefix mismatch"298 c = built["cache"]299 spans.update({"doc_prefill_ms": built["doc_build_ms"], "compress_ms": built["compress_ms"], "serialize_ms": built["serialize_ms"]})300 t = Timer(); t.start("load")301 if method == "B1" or cond.get("roundtrip", False):302 raw, dms = codec_decompress(built["payload"], built["codec"]) if built["codec"] != "none" else (built["payload"], 0.0)303 c_use, man = deserialize_cache(raw, receiver.info, built["manifest"]["prefix_token_hash"])304 rec["cache_compatibility_hash"] = man["prefix_token_hash"][:16]305 else:306 c_use = deep_copy_cache(c)307 t.stop("load"); spans["load_ms"] = t.spans["load"]308 g = receiver.generate_from_cache(c_use, query_ids, max_tokens=gen_max)309 spans.update({"receiver_prefill_ms": 0.0, "query_prefill_ms": g["query_prefill_ms"], "ttft_ms": g["ttft_ms"], "decode_ms": g["decode_ms"]})310 rec.update({"message_tokens": built["prefix_tokens"], "message_utf8_bytes": len(doc["text"].encode("utf-8")), "serialized_payload_bytes": built["payload_bytes"],311 "cache_tensor_bytes": built["cache_bytes"], "side_information_bytes": built["payload_bytes"] - built["cache_bytes"] if built["codec"] == "none" else None,312 "query_tokens": len(query_ids), "input_usage": {"receiver_prefix_tokens": built["prefix_tokens"], "dense_cache_bytes": built["dense_bytes"], "query_tokens": len(query_ids)},313 "payload_hash": sha256_text(str(len(built["payload"]))) , "peak_prefill_memory": built["doc_build_peak"]})314 rec["compression_config"] = {**rec["compression_config"], "realized": {k: v for k, v in built["select_info"].items() if k not in ("layer_budgets",)}}315 pred = g["text"]316 rec["prediction_artifact"] = pred; rec["output_hash"] = sha256_text(pred); rec["output_usage"] = {"output_tokens": g["output_tokens"]}317 rec["ttft_ms"] = spans["ttft_ms"]; rec["timing_spans"] = spans318 rec["total_wall_ms"] = (time.perf_counter() - t_total0) * 1000319 rec["peak_decode_memory"] = int(mx.get_peak_memory()); rec["backend_memory"] = memory_snapshot(); rec["process_memory"] = rec["backend_memory"]["process_rss_bytes"]320 if qkey is None:321 rec["status"] = "implementation_error"; rec["error_code"] = "missing_key"322 else:323 rec["task_scores"] = _score(fam, pred, qkey, key)324 rec["status"] = "success" if pred.strip() else "invalid_output"325 except Exception as e:326 rec["status"] = "oom" if "memory" in str(e).lower() else "implementation_error"327 rec["error_code"] = f"{type(e).__name__}: {str(e)[:300]}"328 rec["total_wall_ms"] = (time.perf_counter() - t_total0) * 1000329 traceback.print_exc()330 return rec331