hugpy-wrapper 0.1.0__py3-none-any.whl

fitevict/__init__.py

@@ -0,0 +1,34 @@
+"""fitevict — a pure, deterministic evict-to-fit / placement allocator.
+
+Clean-room: NO hugpy import. The core (`types`, `evict`, `plan`) is stdlib-only
+and reads nothing live — every fact arrives in a frozen record captured once by
+the caller, so identical records produce byte-identical plans. The `host` seam
+(`EngineHost` / `drive`) and the `adapters` package hold the impure edges that
+wrap a real inference engine (llama.cpp first).
+"""
+from __future__ import annotations
+
+from .evict import evict_order, plan_eviction, sort_key
+from .host import DriveResult, EngineHost, drive
+from .plan import plan_fit
+from .types import (
+    ACTIONS, FAILURE_KINDS, RAM, VRAM, DeviceBudget, Eviction, EvictionPlan,
+    FitFailure, FitPlan, HostBudget, LoadRequest, ModelFootprint, Offload,
+    Policy, Resident, canonical_key, key_equivalent,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # types
+    "VRAM", "RAM", "ACTIONS", "FAILURE_KINDS", "canonical_key", "key_equivalent",
+    "DeviceBudget", "HostBudget", "ModelFootprint", "Resident", "LoadRequest",
+    "Policy", "Eviction", "EvictionPlan", "FitFailure", "Offload", "FitPlan",
+    # evict
+    "sort_key", "plan_eviction", "evict_order",
+    # plan
+    "plan_fit",
+    # host
+    "EngineHost", "DriveResult", "drive",
+]

fitevict/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Engine adapters — the impure geometry/pricing edges. llama.cpp first."""
+from __future__ import annotations
+
+from .llama_cpp import gguf_footprint
+
+__all__ = ["gguf_footprint"]

fitevict/adapters/db.py

@@ -0,0 +1,487 @@
+"""Call-log writer for the fitevict engine — Postgres `inference_engine.call_log`.
+
+GLUE (new code, not lifted): one row per call, UPSERT by request_id, fail-open.
+Stores RAW values only; derived values come from `call_log_derived`. Timestamps
+are passed as epoch floats and written to `timestamptz` via to_timestamp().
+
+Connects as the `hugpy` OS user the way the task specifies — psql is owned by
+hugpy, so the engine shells UPSERTs through `sudo -u hugpy psql -d inference_engine`
+when it cannot open a direct psycopg connection. A direct psycopg connection is
+tried first (dsn from HUGPY_CALLLOG_DSN) and used when available.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any, Dict, Optional
+
+_COLS = (
+    "request_id", "model_name", "received_at", "dispatched_at",
+    "weights_staged_at", "weights_loaded_at", "inference_started_at",
+    "inference_ended_at", "responded_at", "worker", "context_length",
+    "total_layers", "n_gpu_layers", "n_cpu_moe", "kv_cache_bytes",
+    "non_expert_bytes", "expert_bytes", "quantization", "is_moe",
+    "load_in_4bit", "alloc_mode", "prefer_gpu", "prefer_ram",
+    "prompt_tokens", "completion_tokens", "decode_tokens", "task",
+    "caller", "callee", "request_params", "responder", "recipient",
+    "response_meta", "from_ip", "to_ip", "endpoint", "model_path",
+    "mmproj_path", "model_bytes", "llama_port", "llama_argv", "forwarded_at",
+    "request_body", "forwarded_body", "response_body", "plan_verdict",
+    "plan_note", "predicted_need_bytes", "free_vram_before",
+    "free_vram_after_load", "measured_vram_after_load",
+    "bytes_freed_by_eviction", "evicted_keys", "http_status", "error",
+    "layers_ram", "gpu_slices", "attention", "process_bytes_after_call",
+)
+_TS_COLS = {"received_at", "dispatched_at", "weights_staged_at",
+            "weights_loaded_at", "inference_started_at", "inference_ended_at",
+            "responded_at", "forwarded_at"}
+_JSON_COLS = {"request_params", "response_meta", "request_body",
+              "forwarded_body", "response_body", "gpu_slices", "attention"}
+_ARRAY_COLS = {"llama_argv", "evicted_keys"}
+
+
+def _text(v: Any) -> str:
+    return "'" + str(v).replace("'", "''") + "'"
+
+
+def _sql_literal(col: str, val: Any) -> str:
+    if val is None:
+        return "NULL"
+    if col in _TS_COLS:
+        return f"to_timestamp({float(val)})"
+    if col in _JSON_COLS:
+        js = json.dumps(val, default=str)
+        return "'" + js.replace("'", "''") + "'::jsonb"
+    if col in _ARRAY_COLS:
+        return "ARRAY[" + ", ".join(_text(v) for v in val) + "]::text[]"
+    if isinstance(val, bool):
+        return "TRUE" if val else "FALSE"
+    if isinstance(val, (int, float)):
+        return repr(val)
+    return _text(val)
+
+
+def upsert(row: Dict[str, Any]) -> Optional[int]:
+    """UPSERT one call_log row by request_id. Returns the row id, or None on a
+    failure that was swallowed fail-open (the call still happened)."""
+    cols = [c for c in _COLS if c in row]
+    vals = [_sql_literal(c, row.get(c)) for c in cols]
+    set_clause = ", ".join(f"{c}=EXCLUDED.{c}" for c in cols if c != "request_id")
+    sql = (
+        f"INSERT INTO call_log ({', '.join(cols)}) VALUES ({', '.join(vals)}) "
+        f"ON CONFLICT (request_id) DO UPDATE SET {set_clause} RETURNING id;"
+    )
+    try:
+        out = subprocess.run(
+            ["sudo", "-u", "hugpy", "psql", "-d", "inference_engine", "-tA",
+             "-c", sql],
+            capture_output=True, text=True, timeout=30)
+        if out.returncode != 0:
+            raise RuntimeError(out.stderr.strip() or "psql nonzero exit")
+        txt = out.stdout.strip().splitlines()
+        return int(txt[0]) if txt and txt[0].strip().isdigit() else None
+    except Exception as exc:  # noqa: BLE001 — fail-open; never lose the call
+        print(f"[call_log] UPSERT failed (fail-open): {exc}")
+        return None
+
+
+# ── residents: the box's live llama-server seats (written at every edge) ──────
+_RES_COLS = (
+    ("key", "text"), ("pid", "int"), ("port", "int"), ("state", "text"),
+    ("alive", "boolean"), ("healthy", "boolean"), ("busy", "boolean"),
+    ("loading", "boolean"), ("load_error", "text"), ("vram_bytes", "bigint"),
+    ("ram_bytes", "bigint"), ("device", "int"), ("n_gpu_layers", "int"),
+    ("total_layers", "int"), ("n_cpu_moe", "int"), ("ctx", "int"),
+    ("is_moe", "boolean"), ("quant", "text"), ("model_file", "text"),
+    ("endpoint", "text"), ("resident_since", "float8"),
+    ("weights_loaded_at", "float8"), ("last_used", "float8"), ("calls", "int"),
+    ("engine", "text"),
+)
+_RES_TS = {"resident_since", "weights_loaded_at", "last_used"}
+
+
+def write_residents(worker: str, rows: "list[dict]") -> bool:
+    """Replace this box's residents with ``rows`` in one statement: upsert every
+    seat, delete the seats no longer present (evicted). Fail-open."""
+    snap = [{c: r.get(c) for c, _ in _RES_COLS} for r in rows]
+    js = json.dumps(snap, default=str).replace("'", "''")
+    w = _text(worker)
+    rec = ", ".join(f"{c} {t}" for c, t in _RES_COLS)
+    sel = ", ".join((f"to_timestamp(s.{c})" if c in _RES_TS else f"s.{c}")
+                    for c, _ in _RES_COLS)
+    cols = ", ".join(c for c, _ in _RES_COLS)
+    upd = ", ".join(f"{c}=EXCLUDED.{c}" for c, _ in _RES_COLS if c != "key")
+    sql = (
+        f"WITH s AS (SELECT * FROM jsonb_to_recordset('{js}'::jsonb) AS x({rec})), "
+        f"gone AS (DELETE FROM residents WHERE worker={w} "
+        f"AND key NOT IN (SELECT key FROM s)) "
+        f"INSERT INTO residents (worker, {cols}, observed_at) "
+        f"SELECT {w}, {sel}, now() FROM s "
+        f"ON CONFLICT (worker, key) DO UPDATE SET {upd}, observed_at=now();"
+    )
+    try:
+        out = subprocess.run(
+            ["sudo", "-u", "hugpy", "psql", "-d", "inference_engine", "-tA",
+             "-c", sql],
+            capture_output=True, text=True, timeout=10)
+        if out.returncode != 0:
+            raise RuntimeError(out.stderr.strip() or "psql nonzero exit")
+        return True
+    except Exception as exc:  # noqa: BLE001 — fail-open; serving never waits on this
+        print(f"[residents] write failed (fail-open): {exc}")
+        return False
+
+
+
+# ── models: the box's GGUF catalog (the wrapper's discovery is the source) ───
+def write_models(worker: str, rows: "list[dict]") -> bool:
+    """Replace this box's catalog with ``rows`` ({key, path, model_dir, quant,
+    bytes, files}) in one statement; keys gone from disk are deleted. Fail-open."""
+    js = json.dumps(rows, default=str).replace("'", "''")
+    w = _text(worker)
+    sql = (
+        f"WITH s AS (SELECT * FROM jsonb_to_recordset('{js}'::jsonb) AS x("
+        "key text, path text, model_dir text, quant text, bytes bigint, files jsonb, engine text)), "
+        f"gone AS (DELETE FROM models WHERE worker={w} AND key NOT IN (SELECT key FROM s)) "
+        "INSERT INTO models (worker, key, path, model_dir, quant, bytes, files, engine, seen_at) "
+        f"SELECT {w}, key, path, model_dir, quant, bytes, files, COALESCE(engine, 'gguf'), now() FROM s "
+        "ON CONFLICT (worker, key) DO UPDATE SET path=EXCLUDED.path, engine=EXCLUDED.engine, "
+        "model_dir=EXCLUDED.model_dir, quant=EXCLUDED.quant, bytes=EXCLUDED.bytes, "
+        "files=EXCLUDED.files, seen_at=now();"
+    )
+    try:
+        out = subprocess.run(
+            ["sudo", "-u", "hugpy", "psql", "-d", "inference_engine", "-tA", "-c", sql],
+            capture_output=True, text=True, timeout=15)
+        if out.returncode != 0:
+            raise RuntimeError(out.stderr.strip() or "psql nonzero exit")
+        return True
+    except Exception as exc:  # noqa: BLE001
+        print(f"[models] catalog write failed (fail-open): {exc}")
+        return False
+
+
+# ── the pair's knobs (model_workers.user_settings) — the DB is the contract ──
+def pair_knobs(worker: str, key: str) -> dict:
+    """The (worker, model) pair's operator knobs from the hugpy DB; {} when the
+    pair has none or the DB is unreachable (the call then runs at defaults)."""
+    w, k = _text(worker), _text(key)
+    sql = (
+        "SELECT coalesce(mw.user_settings, '{}'::jsonb)::text FROM model_workers mw "
+        "JOIN models m ON m.id = mw.model_id "
+        "WHERE mw.worker_id = (SELECT worker_id FROM hugpy_worker_heartbeat "
+        f"WHERE name = {w} ORDER BY ts DESC LIMIT 1) "
+        f"AND (m.name = {k} OR m.name LIKE '%~' || {k} OR {k} LIKE '%~' || m.name) "
+        "ORDER BY (m.name = " + k + ") DESC LIMIT 1;"
+    )
+    try:
+        out = subprocess.run(["sudo", "-u", "hugpy", "psql", "-d", "hugpy", "-tA", "-c", sql],
+                             capture_output=True, text=True, timeout=10)
+        if out.returncode != 0:
+            raise RuntimeError(out.stderr.strip() or "psql nonzero exit")
+        txt = out.stdout.strip()
+        return json.loads(txt) if txt else {}
+    except Exception as exc:  # noqa: BLE001
+        print(f"[knobs] read failed for {key}: {exc}")
+        return {}
+
+
+def static_keys(worker: str) -> "Optional[set]":
+    """The worker's 🔒static models from the DB pair rows
+    (model_workers.user_settings.residency = 'static'). Static = never evicted
+    once loaded (operator 2026-10-03). None when the DB is unreachable."""
+    w = _text(worker)
+    sql = (
+        "SELECT coalesce(json_agg(m.name), '[]')::text FROM model_workers mw "
+        "JOIN models m ON m.id = mw.model_id "
+        "WHERE mw.worker_id = (SELECT worker_id FROM hugpy_worker_heartbeat "
+        f"WHERE name = {w} ORDER BY ts DESC LIMIT 1) "
+        "AND mw.user_settings->>'residency' = 'static';"
+    )
+    try:
+        txt = _psql_hugpy(sql)
+        return set(json.loads(txt or "[]"))
+    except Exception as exc:  # noqa: BLE001
+        print(f"[static] read failed: {exc}")
+        return None
+
+
+def _psql_hugpy(sql: str) -> str:
+    out = subprocess.run(["sudo", "-u", "hugpy", "psql", "-d", "hugpy", "-tA", "-c", sql],
+                         capture_output=True, text=True, timeout=15)
+    if out.returncode != 0:
+        raise RuntimeError(out.stderr.strip() or "psql nonzero exit")
+    return out.stdout.strip()
+
+
+# ── exact sizing: llama.cpp projections + measured CUDA context + transformers loads ──
+def _ie(sql: str) -> str:
+    out = subprocess.run(["sudo", "-u", "hugpy", "psql", "-d", "inference_engine", "-tA", "-c", sql],
+                         capture_output=True, text=True, timeout=15)
+    if out.returncode != 0:
+        raise RuntimeError(out.stderr.strip() or "psql nonzero exit")
+    return out.stdout.strip()
+
+
+def _lit(v):
+    return "NULL" if v is None else (repr(int(v)) if isinstance(v, (int, float)) and not isinstance(v, bool) else _text(v))
+
+
+def get_projection(worker, file, ctx, ngl, ncm, kv):
+    try:
+        txt = _ie("SELECT row_to_json(p)::text FROM gguf_projection p WHERE worker=%s AND file=%s AND ctx=%d "
+                  "AND n_gpu_layers=%d AND n_cpu_moe=%d AND kv_type=%s"
+                  % (_text(worker), _text(file), int(ctx), int(ngl), int(ncm), _text(kv)))
+        return json.loads(txt) if txt else None
+    except Exception as exc:  # noqa: BLE001
+        print(f"[proj] read failed: {exc}")
+        return None
+
+
+def put_projection(worker, file, ctx, ngl, ncm, kv, p):
+    cols = ("dev_model", "dev_context", "dev_compute", "dev_self", "host_model", "host_context", "host_compute",
+            "host_repack")
+    try:
+        _ie("INSERT INTO gguf_projection (worker, file, ctx, n_gpu_layers, n_cpu_moe, kv_type, %s) VALUES (%s, %s, %d, %d, %d, %s, %s) "
+            "ON CONFLICT (worker, file, ctx, n_gpu_layers, n_cpu_moe, kv_type) DO UPDATE SET %s, at=now()"
+            % (", ".join(cols), _text(worker), _text(file), int(ctx), int(ngl), int(ncm), _text(kv),
+               ", ".join(_lit(p.get(c)) for c in cols), ", ".join(f"{c}=EXCLUDED.{c}" for c in cols)))
+    except Exception as exc:  # noqa: BLE001
+        print(f"[proj] write failed: {exc}")
+
+
+def get_cuda_context(worker, device):
+    try:
+        txt = _ie("SELECT bytes FROM cuda_context WHERE worker=%s AND device=%s" % (_text(worker), _text(device)))
+        return int(txt) if txt else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def put_cuda_context(worker, device, nbytes):
+    try:
+        _ie("INSERT INTO cuda_context (worker, device, bytes) VALUES (%s, %s, %d) ON CONFLICT (worker, device) "
+            "DO UPDATE SET bytes=EXCLUDED.bytes, samples=cuda_context.samples+1, at=now()"
+            % (_text(worker), _text(device), int(nbytes)))
+    except Exception as exc:  # noqa: BLE001
+        print(f"[cuda_ctx] write failed: {exc}")
+
+
+def get_tf_measure(worker, key, bnb4, ctx):
+    try:
+        where = "" if ctx is None else " AND ctx=%d" % int(ctx)
+        txt = _ie("SELECT row_to_json(t)::text FROM tf_measure t WHERE worker=%s AND key=%s AND bnb4=%s%s "
+                  "ORDER BY at DESC LIMIT 1" % (_text(worker), _text(key), "true" if bnb4 else "false", where))
+        return json.loads(txt) if txt else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def put_tf_measure(worker, key, bnb4, ctx, tensor_bytes=None, load_bytes=None, peak_bytes=None):
+    try:
+        _ie("INSERT INTO tf_measure (worker, key, bnb4, ctx, tensor_bytes, load_bytes, peak_bytes) VALUES (%s, %s, %s, %d, %s, %s, %s) "
+            "ON CONFLICT (worker, key, bnb4, ctx) DO UPDATE SET "
+            "tensor_bytes=COALESCE(EXCLUDED.tensor_bytes, tf_measure.tensor_bytes), "
+            "load_bytes=COALESCE(EXCLUDED.load_bytes, tf_measure.load_bytes), "
+            "peak_bytes=GREATEST(COALESCE(EXCLUDED.peak_bytes, 0), COALESCE(tf_measure.peak_bytes, 0)), at=now()"
+            % (_text(worker), _text(key), "true" if bnb4 else "false", int(ctx),
+               _lit(tensor_bytes), _lit(load_bytes), _lit(peak_bytes)))
+    except Exception as exc:  # noqa: BLE001
+        print(f"[tf_measure] write failed: {exc}")
+
+
+def put_measured(worker, file, ctx, ngl, ncm, kv, process_bytes, context_bytes):
+    """G5/G3: the NVML-measured process bytes of a real load of this exact
+    configuration, and the context derived from its load-log buffers."""
+    try:
+        _ie("INSERT INTO gguf_projection (worker, file, ctx, n_gpu_layers, n_cpu_moe, kv_type, measured_process, measured_context, measured_at) "
+            "VALUES (%s, %s, %d, %d, %d, %s, %s, %s, now()) ON CONFLICT (worker, file, ctx, n_gpu_layers, n_cpu_moe, kv_type) "
+            "DO UPDATE SET measured_process=EXCLUDED.measured_process, measured_context=EXCLUDED.measured_context, measured_at=now()"
+            % (_text(worker), _text(file), int(ctx), int(ngl), int(ncm), _text(kv), _lit(process_bytes), _lit(context_bytes)))
+    except Exception as exc:  # noqa: BLE001
+        print(f"[measured] write failed: {exc}")
+
+
+def put_eviction(row: dict) -> None:
+    """One unload, timed and measured in bytes (inference_engine.evictions)."""
+    cols = ("worker", "key", "engine", "request_id", "reason", "pid", "process_bytes", "free_before", "free_after")
+    ts = ("started_at", "exited_at", "released_at")
+    vals = [_lit(row.get(c)) for c in cols] + [("to_timestamp(%r)" % float(row[t])) if row.get(t) else "NULL" for t in ts]
+    try:
+        _ie("INSERT INTO evictions (%s) VALUES (%s)" % (", ".join(cols + ts), ", ".join(vals)))
+    except Exception as exc:  # noqa: BLE001
+        print(f"[eviction] write failed: {exc}")
+
+
+def get_full_ctx(worker, file, ctx, ngl, ncm, kv):
+    """G8/A: the stored full-context measurement for this configuration (or None)."""
+    try:
+        txt = _ie("SELECT full_ctx_process FROM gguf_projection WHERE worker=%s AND file=%s AND ctx=%d "
+                  "AND n_gpu_layers=%d AND n_cpu_moe=%d AND kv_type=%s"
+                  % (_text(worker), _text(file), int(ctx), int(ngl), int(ncm), _text(kv)))
+        return int(txt) if txt else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def put_full_ctx(worker, file, ctx, ngl, ncm, kv, process_bytes, tokens, prefill_s, request_id):
+    """G8/A: NVML process bytes after a prompt that fills the whole context."""
+    try:
+        _ie("INSERT INTO gguf_projection (worker, file, ctx, n_gpu_layers, n_cpu_moe, kv_type, full_ctx_process, "
+            "full_ctx_tokens, full_ctx_prefill_s, full_ctx_request_id, full_ctx_at) VALUES (%s, %s, %d, %d, %d, %s, %d, %d, %r, %s, now()) "
+            "ON CONFLICT (worker, file, ctx, n_gpu_layers, n_cpu_moe, kv_type) DO UPDATE SET "
+            "full_ctx_process=EXCLUDED.full_ctx_process, full_ctx_tokens=EXCLUDED.full_ctx_tokens, "
+            "full_ctx_prefill_s=EXCLUDED.full_ctx_prefill_s, full_ctx_request_id=EXCLUDED.full_ctx_request_id, full_ctx_at=now()"
+            % (_text(worker), _text(file), int(ctx), int(ngl), int(ncm), _text(kv), int(process_bytes),
+               int(tokens), float(prefill_s), _text(request_id)))
+    except Exception as exc:  # noqa: BLE001
+        print(f"[g8] write failed: {exc}")
+
+
+def ctx_choice(key: str, file: str) -> dict:
+    """The context facts for (model, quant file) from the hugpy DB: the per-tick
+    KV ladder (model_quant_facts.kv_cost.ticks) and the history default
+    (model_default_ctx: smallest tick covering the model's largest real use).
+    {} when unknown."""
+    import re as _re
+    logical = _re.sub(r"-\d{5}-of-\d{5}\.gguf$", ".gguf", file or "")   # split GGUF: the DB keys the logical name
+    k, f = _text(key), "(%s, %s)" % (_text(file), _text(logical))
+    sql = ("SELECT json_build_object('ticks', fq.kv_cost->'ticks', 'default_ctx', d.default_ctx, "
+           "'default_tick', d.default_tick, 'need_tokens', d.need_tokens, 'basis', d.basis)::text "
+           "FROM model_quant_facts fq JOIN models m ON m.id = fq.model_id "
+           "LEFT JOIN model_default_ctx d ON d.model_id = fq.model_id AND d.file = fq.file "
+           f"WHERE fq.file IN {f} AND (m.name = {k} OR m.name LIKE '%~' || {k} OR {k} LIKE '%~' || m.name) "
+           f"ORDER BY (m.name = {k}) DESC LIMIT 1;")
+    try:
+        txt = _psql_hugpy(sql)
+        return json.loads(txt) if txt else {}
+    except Exception as exc:  # noqa: BLE001
+        print(f"[ctx] read failed for {key}: {exc}")
+        return {}
+
+
+def serving_growth(worker, file, ctx, ngl, ncm, kv):
+    """G8 for a configuration: (bytes, source). The configuration's own measured
+    growth (test-fire full-context fill, else the largest seen in real calls);
+    before any measurement of it, the LARGEST G8 measured on this card (the G3
+    precedent: the card's measured value, labelled as a pre-measurement bound)."""
+    try:
+        txt = _ie(
+            "SELECT json_build_object("
+            " 'own', (SELECT serving_growth FROM gguf_projection WHERE worker=%s AND file=%s AND ctx=%d "
+            "         AND n_gpu_layers=%d AND n_cpu_moe=%d AND kv_type=%s),"
+            " 'observed', (SELECT max_growth_observed FROM serving_growth_observed WHERE worker=%s "
+            "         AND regexp_replace(model_path, '.*/', '')=%s AND ctx=%d AND n_gpu_layers=%d AND n_cpu_moe=%d),"
+            " 'card', greatest((SELECT max(serving_growth) FROM gguf_projection WHERE worker=%s),"
+            "                  (SELECT max(max_growth_observed) FROM serving_growth_observed WHERE worker=%s)))::text"
+            % (_text(worker), _text(file), int(ctx), int(ngl), int(ncm), _text(kv),
+               _text(worker), _text(file), int(ctx), int(ngl), int(ncm), _text(worker), _text(worker)))
+        d = json.loads(txt) if txt else {}
+    except Exception as exc:  # noqa: BLE001
+        print(f"[g8] read failed: {exc}")
+        return 0, "unmeasured"
+    own = max([v for v in (d.get("own"), d.get("observed")) if v is not None] or [None]) \
+        if (d.get("own") is not None or d.get("observed") is not None) else None
+    if own is not None:
+        return int(own), "measured (this configuration)"
+    if d.get("card") is not None:
+        return int(d["card"]), "card max (pre-measurement bound)"
+    return 0, "unmeasured"
+
+
+def put_kv_structure(worker, file, st: dict, slots, ctx, log_path):
+    try:
+        _ie("INSERT INTO kv_structure (worker, file, kv_type, k_cell_bytes, v_cell_bytes, kv_layers, kv_seqs, rs_bytes, "
+            "rs_cells, rs_layers, slots, source_ctx, source_log, at) VALUES (%s, %s, %s, %d, %d, %d, %s, %d, %d, %d, %s, %d, %s, now()) "
+            "ON CONFLICT (worker, file, kv_type) DO UPDATE SET k_cell_bytes=EXCLUDED.k_cell_bytes, v_cell_bytes=EXCLUDED.v_cell_bytes, "
+            "kv_layers=EXCLUDED.kv_layers, kv_seqs=EXCLUDED.kv_seqs, rs_bytes=EXCLUDED.rs_bytes, rs_cells=EXCLUDED.rs_cells, "
+            "rs_layers=EXCLUDED.rs_layers, slots=EXCLUDED.slots, source_ctx=EXCLUDED.source_ctx, source_log=EXCLUDED.source_log, at=now()"
+            % (_text(worker), _text(file), _text(st["kv_type"]), st["k_cell_bytes"], st["v_cell_bytes"], st["kv_layers"],
+               _text(st["kv_seqs"]), st["rs_bytes"], st["rs_cells"], st["rs_layers"], _lit(slots), int(ctx), _text(log_path)))
+    except Exception as exc:  # noqa: BLE001
+        print(f"[kv_structure] write failed: {exc}")
+
+
+def get_kv_structure(worker, file, kv_type="f16"):
+    """The measured f16 structure (other KV types derive exactly from it)."""
+    try:
+        txt = _ie("SELECT row_to_json(k)::text FROM kv_structure k WHERE worker=%s AND file=%s AND kv_type='f16'"
+                  % (_text(worker), _text(file)))
+        return json.loads(txt) if txt else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def rewrite_ticks(file: str, st: dict) -> None:
+    """Replace the quant's DB KV ticks (hugpy.model_quant_facts.kv_cost.ticks)
+    with K2 device bytes from the measured structure; keeps each tick's ctx.
+    q8_0 / q4_0 cells are 17/32 and 9/32 of f16 (34 and 18 bytes per 32
+    elements); the recurrent state is f32 in every KV type."""
+    from .. import sizing as _S
+    import re as _re
+    file = _re.sub(r"-\d{5}-of-\d{5}\.gguf$", ".gguf", file or "")   # the DB keys split GGUFs by logical name
+    kv = st["k_cell_bytes"] + st["v_cell_bytes"]
+    rs = int(st.get("rs_bytes") or 0)
+    try:
+        cur = _psql_hugpy("SELECT kv_cost->'ticks' FROM model_quant_facts WHERE file = %s LIMIT 1" % _text(file))
+        ticks = json.loads(cur) if cur else None
+        if not ticks:
+            return
+        new = {}
+        for k, t in ticks.items():
+            c = int(t["ctx"])
+            rsb = _S.page(rs) if rs else 0
+            new[k] = {"ctx": c, "f16": _S.page(c * kv) + rsb,
+                      "q8_0": _S.page(c * kv * 17 // 32) + rsb, "q4_0": _S.page(c * kv * 9 // 32) + rsb}
+        js = json.dumps(new).replace("'", "''")
+        _psql_hugpy("UPDATE model_quant_facts SET kv_cost = kv_cost || jsonb_build_object('ticks', '%s'::jsonb, "
+                    "'basis', 'llama.cpp load log (K2, measured)', 'bytes_per_token', %d, 'fixed_bytes', %d) "
+                    "WHERE file = %s" % (js, kv, rs, _text(file)))
+    except Exception as exc:  # noqa: BLE001
+        print(f"[ticks] rewrite failed for {file}: {exc}")
+
+
+def put_measured_host(worker, file, ctx, ngl, ncm, kv, anon, filebytes):
+    """R1: RssAnon / RssFile of a real RAM (or partial) load of this config."""
+    try:
+        _ie("INSERT INTO gguf_projection (worker, file, ctx, n_gpu_layers, n_cpu_moe, kv_type, measured_host_anon, "
+            "measured_host_file, measured_host_at) VALUES (%s, %s, %d, %d, %d, %s, %d, %d, now()) "
+            "ON CONFLICT (worker, file, ctx, n_gpu_layers, n_cpu_moe, kv_type) DO UPDATE SET "
+            "measured_host_anon=EXCLUDED.measured_host_anon, measured_host_file=EXCLUDED.measured_host_file, measured_host_at=now()"
+            % (_text(worker), _text(file), int(ctx), int(ngl), int(ncm), _text(kv), int(anon), int(filebytes)))
+    except Exception as exc:  # noqa: BLE001
+        print(f"[host] write failed: {exc}")
+
+
+def get_measured_host(worker, file, ctx, ngl, ncm, kv):
+    try:
+        txt = _ie("SELECT json_build_object('anon', measured_host_anon, 'file', measured_host_file)::text FROM gguf_projection "
+                  "WHERE worker=%s AND file=%s AND ctx=%d AND n_gpu_layers=%d AND n_cpu_moe=%d AND kv_type=%s"
+                  % (_text(worker), _text(file), int(ctx), int(ngl), int(ncm), _text(kv)))
+        return json.loads(txt) if txt else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def pair_facts(worker: str, key: str, file: str) -> dict:
+    """Every FACT for (worker, model, quant) — hugpy.pair_facts(), the single
+    input of sizing.decide() (central uses the same function)."""
+    try:
+        txt = _psql_hugpy("SELECT pair_facts(%s, %s, %s)::text" % (_text(worker), _text(key), _text(file)))
+        return json.loads(txt) if txt else {}
+    except Exception as exc:  # noqa: BLE001
+        print(f"[facts] read failed for {key}: {exc}")
+        return {}
+
+
+def put_tf_structure(worker, key, model_dir, tensor_bytes, tensor_bytes_bnb4, geometry):
+    """T1 facts for a transformers model (safetensors headers + config geometry)."""
+    try:
+        _ie("INSERT INTO tf_structure (worker, key, model_dir, tensor_bytes, tensor_bytes_bnb4, geometry, at) "
+            "VALUES (%s, %s, %s, %s, %s, %s::jsonb, now()) ON CONFLICT (worker, key) DO UPDATE SET "
+            "model_dir=EXCLUDED.model_dir, tensor_bytes=EXCLUDED.tensor_bytes, tensor_bytes_bnb4=EXCLUDED.tensor_bytes_bnb4, "
+            "geometry=EXCLUDED.geometry, at=now()"
+            % (_text(worker), _text(key), _text(model_dir), _lit(tensor_bytes), _lit(tensor_bytes_bnb4),
+               _text(json.dumps(geometry or {}))))
+    except Exception as exc:  # noqa: BLE001
+        print(f"[tf_structure] write failed: {exc}")