clausius 0.1.0__py3-none-any.whl

clausius/__init__.py

@@ -0,0 +1,35 @@
+"""clausius — did the thing you changed break your model?
+
+Named for Rudolf Clausius, who coined the word *entropy* in 1865 — building it
+from the Greek `trope` (transformation) and shaping it deliberately to echo
+"energy", so the two would sound like the related quantities they are. Entropy
+is the signal this library reads.
+
+    from clausius import capture, compare
+
+    ref  = capture("mlx-community/gemma-4-e4b-it-4bit", prompts, tag="v1")
+    cand = capture("mlx-community/gemma-4-e4b-it-4bit", prompts, tag="v2",
+                   adapter="./my-lora")
+    print(compare(ref, cand))
+    # REGRESSION  (max d_z = +0.782, threshold 0.3, one-sided)
+
+`prompts` are your own, unlabeled. No gold answers and no judge model: the
+comparison is between the model's own per-token entropy distributions on
+identical inputs.
+
+See `core` for why each default is what it is — every one of them is a measured
+result rather than a taste, and FINDINGS.md has the evidence.
+"""
+from .core import (BOOTSTRAP_RESAMPLES, BOOTSTRAP_SEED, CAP_LADDER,
+                   DEFAULT_SIGNAL, DEFAULT_THRESHOLD, MIN_PAIRED_ITEMS,
+                   SIGNALS, Capture, Result, TruncationCurve, aggregate,
+                   bootstrap_ci, capture, compare, top_movers,
+                   truncation_curve)
+
+__all__ = ['capture', 'compare', 'Capture', 'Result', 'aggregate',
+           'truncation_curve', 'TruncationCurve', 'top_movers',
+           'bootstrap_ci',
+           'SIGNALS', 'DEFAULT_SIGNAL', 'DEFAULT_THRESHOLD',
+           'MIN_PAIRED_ITEMS', 'CAP_LADDER',
+           'BOOTSTRAP_RESAMPLES', 'BOOTSTRAP_SEED']
+__version__ = '0.1.0'

clausius/cli.py

@@ -0,0 +1,161 @@
+"""Command line for clausius. Exits non-zero on a regression, for CI.
+
+    clausius capture --model M --prompts p.jsonl --out ref.json
+    clausius capture --model M --prompts p.jsonl --out cand.json --adapter ./lora
+    clausius compare ref.json cand.json
+"""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .core import (DEFAULT_SIGNAL, DEFAULT_THRESHOLD, SIGNALS, capture,
+                   compare, top_movers, truncation_curve)
+
+
+def read_prompts(path):
+    """One prompt per line: JSONL with a "prompt" field, or plain text.
+
+    Both are accepted because the realistic source is a sample of production
+    traffic, which is usually a log rather than a curated dataset.
+    """
+    lines = [l for l in Path(path).read_text().splitlines() if l.strip()]
+    out = []
+    for line in lines:
+        if line.lstrip().startswith('{'):
+            d = json.loads(line)
+            out.append(d.get('prompt') or d.get('text') or d.get('input'))
+        else:
+            out.append(line)
+    missing = [i for i, p in enumerate(out) if not p]
+    if missing:
+        raise SystemExit(
+            f"{len(missing)} line(s) had no prompt field (first: line "
+            f"{missing[0] + 1}); expected JSONL with 'prompt'/'text'/'input', "
+            f"or plain text")
+    return out
+
+
+def _clip(text, width=160):
+    """One line, bounded — a terminal diagnostic, not a transcript dump."""
+    flat = ' '.join((text or '').split())
+    return flat[:width] + ('…' if len(flat) > width else '')
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog='clausius', description=__doc__.split('\n')[0],
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest='cmd', required=True)
+
+    c = sub.add_parser('capture', help='record one configuration')
+    c.add_argument('--model', required=True, help='path or HF id')
+    c.add_argument('--prompts', required=True, help='JSONL or plain text')
+    c.add_argument('--out', required=True)
+    c.add_argument('--tag', default=None)
+    c.add_argument('--adapter', default=None, help='LoRA adapter path')
+    c.add_argument('--max-tokens', type=int, default=512,
+                   help='generation cap. Capture at the most generous cap you '
+                        'can afford: truncated items are dropped at compare '
+                        'time, and a capture can be re-analyzed at any TIGHTER '
+                        'cap but never at a looser one — the lengths of '
+                        'truncated items are not recoverable.')
+    c.add_argument('--limit', type=int, default=None,
+                   help='use only the first N prompts (default: all of them). '
+                        'Sampling is rarely worth it: a full capture at a '
+                        'generous --max-tokens is itself the reference, while '
+                        'a sampled probe is thrown away. Use it on prompt sets '
+                        'large enough that a wrong cap is expensive.')
+    c.add_argument('--raw', action='store_true',
+                   help="do not apply the model's chat template. For base "
+                        "models; on an instruct model this causes runaway "
+                        "generation and a truncation-dominated capture.")
+
+    d = sub.add_parser('compare', help='paired comparison of two captures')
+    d.add_argument('reference')
+    d.add_argument('candidate')
+    d.add_argument('--signal', default=DEFAULT_SIGNAL, choices=SIGNALS)
+    d.add_argument('--threshold', type=float, default=DEFAULT_THRESHOLD)
+    d.add_argument('--two-sided', action='store_true',
+                   help='also flag entropy DECREASES. Known false positive: a '
+                        'pure confidence change with zero accuracy impact will '
+                        'trip it.')
+    d.add_argument('--keep-truncated', action='store_true',
+                   help='do not drop items that hit the token cap. Dilutes the '
+                        'effect and lets generation length leak in.')
+    d.add_argument('--show', type=int, default=0, metavar='N',
+                   help='also print the N items whose entropy moved most, '
+                        'with the text both configs produced. The verdict '
+                        'says something broke; this says what.')
+    d.add_argument('--json', action='store_true')
+
+    a = ap.parse_args(argv)
+
+    if a.cmd == 'capture':
+        prompts = read_prompts(a.prompts)
+        if a.limit:
+            prompts = prompts[:a.limit]
+        print(f"  {len(prompts)} prompts · {a.model}"
+              + (f" + {a.adapter}" if a.adapter else ""), file=sys.stderr)
+
+        def tick(i, n):
+            if i % 25 == 0 or i == n:
+                print(f"  {i}/{n}", file=sys.stderr, flush=True)
+
+        cap = capture(a.model, prompts, tag=a.tag or Path(a.out).stem,
+                      max_tokens=a.max_tokens, adapter=a.adapter,
+                      chat=False if a.raw else None, progress=tick)
+        # save before any verdict on the run: the capture cost real GPU time and
+        # is still re-analyzable (compare --keep-truncated) even when doomed for
+        # the default path.
+        print(f"  → {cap.save(a.out)}", file=sys.stderr)
+
+        curve = truncation_curve(cap)
+        print(f"  truncation at this and every tighter cap:", file=sys.stderr)
+        print(str(curve), file=sys.stderr)
+        if not curve.usable:
+            # A candidate can only truncate more items, so this comparison is
+            # already impossible. Say so now rather than after a second capture.
+            print(f"\n  ERROR: only {curve.survivors} of {curve.n_items} items "
+                  f"survive at --max-tokens {curve.cap_used}, and compare needs "
+                  f"{curve.floor}.\n"
+                  f"  A candidate capture can only truncate MORE items, so this "
+                  f"comparison cannot succeed.\n"
+                  f"  Re-capture with a larger --max-tokens (the cap is not "
+                  f"recoverable after the fact), or compare --keep-truncated to "
+                  f"accept a diluted effect.", file=sys.stderr)
+            return 2
+        return 0
+
+    r = compare(a.reference, a.candidate, signal=a.signal,
+                threshold=a.threshold, one_sided=not a.two_sided,
+                drop_truncated=not a.keep_truncated)
+    if a.json:
+        print(json.dumps({'verdict': r.verdict, 'flagged': r.flagged,
+                          'signal': r.signal, 'effect': round(r.effect, 4),
+                          'threshold': r.threshold, 'one_sided': r.one_sided,
+                          'n_compared': r.n_compared,
+                          'n_dropped_truncated': r.n_dropped_truncated,
+                          'ci': [round(v, 4) for v in r.ci],
+                          'detail': {k: round(v, 4)
+                                     for k, v in r.detail.items()}}, indent=1))
+    else:
+        print(r)
+        if a.show:
+            movers = top_movers(a.reference, a.candidate, n=a.show,
+                                signal=a.signal,
+                                drop_truncated=not a.keep_truncated)
+            print(f"\n  {len(movers)} largest movers by {a.signal}:")
+            for m in movers:
+                print(f"\n  item {m['i']}  \u0394{a.signal} {m['delta']:+.2f}"
+                      f"  ({m['ref']:.2f} -> {m['cand']:.2f})")
+                if m['prompt']:
+                    print(f"    prompt: {_clip(m['prompt'])}")
+                print(f"    ref   : {_clip(m['ref_text'])}")
+                print(f"    cand  : {_clip(m['cand_text'])}")
+    # non-zero on regression so a CI step fails without extra glue
+    return 1 if r.flagged else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

clausius/core.py

@@ -0,0 +1,525 @@
+"""Label-free detection of deployment regressions.
+
+You changed something — quantization, offload capacity, top-k, a LoRA
+checkpoint, an inference backend — and you need to know whether it degraded the
+model. Measuring that normally needs a labeled eval set for your actual task,
+which most teams do not have.
+
+This compares the model's own **per-token entropy** before and after, paired on
+the same unlabeled prompts. No gold answers, no judge model, no eval set. The
+signal is a byproduct of a forward pass you are already running.
+
+Validated against five unrelated damage mechanisms whose true damage was
+measured independently — quantization, expert zeroing, top-k reduction, expert
+substitution and LoRA fine-tuning — on two architectures. See FINDINGS.md (F8,
+F9, F11, F13).
+
+The design decisions below are not defaults chosen by taste. Each one is a
+result:
+
+THRESHOLD 0.3. Thirteen configurations known to be harmless — offload capacity
+    changes of up to 8x, a mixed-precision scheme, across two models and two
+    tasks — produce |d_z| <= 0.10. 0.3 is ~3x that null. An earlier eyeballed
+    0.5 was ~5x the null and missed real regressions, including one costing 39
+    accuracy points.
+
+ONE-SIDED BY DEFAULT. Every damaged configuration measured raises entropy. The
+    only configurations that LOWER it are ones with provably zero damage —
+    scaling logits leaves greedy output bit-identical while collapsing entropy,
+    and a two-sided test flags it. So the default flags increases only. Damage
+    that made a model MORE confident would be invisible; three mechanisms were
+    deliberately constructed to produce that and none did, but it is not
+    excluded. `two_sided=True` trades that for a known false positive.
+
+PAIRED, SAME PROMPTS. Item-to-item variance in base entropy dwarfs the effect of
+    a config change, so unpaired comparison is hopeless. Mismatched prompt sets
+    are rejected rather than silently compared.
+
+TRUNCATED ITEMS EXCLUDED. Items that hit the token cap dilute the signal across
+    hundreds of low-information tokens — excluding them roughly doubled the
+    measured effect — and dropping them stops the detector riding on generation
+    length, which is a property of the cap you chose rather than of the model.
+
+    This note used to say that a damaged model rambles into the cap. The
+    measurements do not support it. At cap 512 a *healthy* 4-bit checkpoint
+    truncated 47/60 items while a destroyed 2-bit one truncated 3; two LoRA
+    fine-tunes truncated 22 and 33 of 50 on held-out domains where their own
+    base truncated none. Rambling tracks how far off-distribution a prompt is,
+    not how damaged the model is. The filter is right; the reason was wrong.
+
+    It carries a cost on heterogeneous traffic. The items it drops are the
+    long-output ones, and F11 measures those as the family most sensitive to
+    compression — validating on short factual recall understates damage to
+    structured generation by ~14x. So on a mixed prompt set the filter biases
+    what survives toward the least sensitive items. Set a cap generous enough
+    that truncation is rare rather than routine, and read `n_dropped_truncated`
+    as a statement about which prompts were measured, not only how many.
+
+NO SINGLE AGGREGATION WINS. `max` is monotone in damage where `p90` inverts on
+    long-output tasks; `p90` gives a larger effect on some others. Every verdict
+    agrees under both across all five mechanisms, so all are reported and the
+    flag is not sensitive to the choice.
+"""
+from __future__ import annotations
+
+import json
+import time
+import warnings
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+
+SIGNALS = ('max', 'p90', 'mean', 'mean_top10', 'first', 'gen_len')
+DEFAULT_SIGNAL = 'max'
+DEFAULT_THRESHOLD = 0.3
+
+# Below this many paired items the effect size is noise. `compare` refuses;
+# `capture` reports how far a run is from it while the model is still loaded.
+MIN_PAIRED_ITEMS = 20
+
+# Caps a truncation curve is reported at. Only the entries at or under the cap
+# a capture actually used are answerable — see `truncation_curve`.
+CAP_LADDER = (256, 512, 768, 1024, 1536, 2048, 3072, 4096, 6144, 8192)
+
+# Bootstrap settings for the reported interval. Seeded by default: a CI gate
+# whose output changes between runs on identical inputs is not a gate.
+BOOTSTRAP_RESAMPLES = 2000
+BOOTSTRAP_SEED = 0
+
+
+def aggregate(entropy: np.ndarray, n_prompt: int) -> dict:
+    """Every aggregation of a per-token entropy sequence, over generated tokens.
+
+    `n_prompt` is clamped: a configuration can be damaged badly enough to
+    generate nothing at all (top-k <= 2 on one model does exactly this), and an
+    unguarded index into an empty generated span raises rather than recording
+    the observation. An immediate stop is a data point about the damage.
+    """
+    n_p = min(n_prompt, len(entropy))
+    gen = entropy[n_p - 1:] if n_p >= 1 else entropy
+    if len(gen) == 0:
+        gen = entropy[-1:] if len(entropy) else np.array([0.0])
+    return {
+        'first': float(gen[0]),
+        'mean': float(np.mean(gen)),
+        'max': float(np.max(gen)),
+        'p90': float(np.percentile(gen, 90)),
+        'mean_top10': float(np.mean(np.sort(gen)[-max(1, len(gen) // 10):])),
+        'gen_len': float(len(gen)),
+    }
+
+
+@dataclass
+class Capture:
+    """One configuration's behavior on a prompt set."""
+    model: str
+    tag: str
+    prompts: list = field(default_factory=list)
+    rows: list = field(default_factory=list)
+    meta: dict = field(default_factory=dict)
+
+    def save(self, path) -> Path:
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(json.dumps({'model': self.model, 'tag': self.tag,
+                                 'prompts': self.prompts, 'rows': self.rows,
+                                 'meta': self.meta}))
+        return p
+
+    @classmethod
+    def load(cls, path) -> "Capture":
+        d = json.loads(Path(path).read_text())
+        return cls(model=d['model'], tag=d['tag'], prompts=d.get('prompts', []),
+                   rows=d['rows'], meta=d.get('meta', {}))
+
+
+@dataclass
+class Result:
+    """The verdict, and everything needed to disbelieve it."""
+    flagged: bool
+    effect: float
+    signal: str
+    threshold: float
+    one_sided: bool
+    n_compared: int
+    n_dropped_truncated: int
+    detail: dict
+    ci: tuple = (float('nan'), float('nan'))
+
+    @property
+    def verdict(self) -> str:
+        return 'REGRESSION' if self.flagged else 'clean'
+
+    def __str__(self) -> str:
+        span = ("" if any(np.isnan(v) for v in self.ci)
+                else f" [95% CI {self.ci[0]:+.2f}, {self.ci[1]:+.2f}]")
+        lines = [f"{self.verdict}  ({self.signal} d_z = {self.effect:+.3f}"
+                 f"{span}, "
+                 f"threshold {self.threshold}, "
+                 f"{'one' if self.one_sided else 'two'}-sided)",
+                 f"  compared {self.n_compared} paired items"
+                 + (f", dropped {self.n_dropped_truncated} truncated"
+                    if self.n_dropped_truncated else ""),
+                 "  all signals: " + "  ".join(
+                     f"{k} {v:+.2f}" for k, v in self.detail.items())]
+        return "\n".join(lines)
+
+
+@dataclass
+class TruncationCurve:
+    """What every tighter generation cap would have cost, from one capture.
+
+    The point of reporting this at capture time is that the answer is already
+    in hand and the alternative is finding out at compare time, after a second
+    capture has also been paid for.
+    """
+    cap_used: int
+    n_items: int
+    n_censored: int
+    rows: list
+    floor: int = MIN_PAIRED_ITEMS
+
+    @property
+    def survivors(self) -> int:
+        """Items that would survive truncation filtering at the cap used."""
+        return self.n_items - self.n_censored
+
+    @property
+    def usable(self) -> bool:
+        """Whether a paired comparison against this capture can succeed.
+
+        A candidate can only ever truncate MORE items, never fewer, so a
+        reference already under the floor is a comparison that cannot be run.
+        """
+        return self.survivors >= self.floor
+
+    def as_dict(self) -> dict:
+        """JSON-serializable form, for storing on a Capture's meta."""
+        return {'cap_used': self.cap_used, 'n_items': self.n_items,
+                'n_censored': self.n_censored, 'survivors': self.survivors,
+                'usable': self.usable, 'floor': self.floor, 'rows': self.rows}
+
+    def __str__(self) -> str:
+        lines = []
+        for r in self.rows:
+            mark = "  <- this run" if r['cap'] == self.cap_used else ""
+            warn = ("  below compare's floor of %d" % self.floor
+                    if r['survivors'] < self.floor else "")
+            lines.append(f"    cap {r['cap']:>5}: {r['truncated']:>3} truncated, "
+                         f"{r['survivors']:>3} survive{warn}{mark}")
+        if self.n_censored:
+            lines.append(
+                f"    {self.n_censored} item(s) reached the {self.cap_used} cap; "
+                f"their true lengths are unknown, so this table cannot be "
+                f"extended above it")
+        return "\n".join(lines)
+
+
+def truncation_curve(capture, caps=CAP_LADDER, floor=MIN_PAIRED_ITEMS):
+    """Truncation counts this capture would have shown at tighter caps.
+
+    Exact downward, silent upward. Every item that finished has its true
+    generated length recorded, so the count at any cap at or under the one used
+    is not an estimate — it is what would have happened. Items that hit the cap
+    have no recorded true length, so no cap above it is answerable at all and
+    none is reported; extrapolating there would be inventing data.
+
+    Accepts a `Capture` or a path to a saved one.
+    """
+    cap = capture if isinstance(capture, Capture) else Capture.load(capture)
+    cap_used = cap.meta.get('max_tokens')
+    if not cap_used:
+        raise ValueError(
+            "capture has no max_tokens in meta; the curve is defined relative "
+            "to the cap that was used and cannot be computed without it")
+    lengths = [r['ent']['gen_len'] for r in cap.rows]
+    n = len(lengths)
+    # matches capture()'s own truncation test: n_gen >= max_tokens - 2
+    counted = sorted({c for c in caps if c <= cap_used} | {int(cap_used)})
+    rows = [{'cap': c,
+             'truncated': sum(1 for x in lengths if x >= c - 2),
+             'survivors': sum(1 for x in lengths if x < c - 2)}
+            for c in counted]
+    censored = sum(1 for x in lengths if x >= cap_used - 2)
+    return TruncationCurve(cap_used=int(cap_used), n_items=n,
+                           n_censored=censored, rows=rows, floor=floor)
+
+
+def apply_chat_template(tokenizer, prompt, chat=None):
+    """Wrap a prompt in the model's chat format, if it has one.
+
+    Defaults to ON for any tokenizer that declares a template. Feeding a raw
+    completion-style prompt to an instruct-tuned model puts it off-distribution:
+    it rambles instead of answering, and the run comes back truncation-dominated
+    — 19 of 25 items hit a 256-token cap in the first end-to-end test of this
+    library. Truncated items are dropped, so the comparison then rests on
+    whatever few happened to terminate.
+
+    `chat=False` is the escape hatch for base models and for deliberately
+    measuring raw-completion behavior.
+    """
+    if chat is False:
+        return prompt
+    tmpl = getattr(tokenizer, 'chat_template', None)
+    if chat is None and not tmpl:
+        return prompt
+    msg = [{'role': 'user', 'content': prompt}]
+    try:
+        return tokenizer.apply_chat_template(msg, add_generation_prompt=True,
+                                             tokenize=False)
+    except Exception:
+        return prompt
+
+
+
+def _backend_mlx():
+    try:
+        import mlx.core as mx
+        from mlx_lm import generate as _generate, load as _load
+    except ImportError as e:
+        raise ImportError(
+            "capture needs mlx-lm, which runs on Apple Silicon only:\n"
+            "    pip install 'clausius[mlx]'\n"
+            "There is no other capture backend in this release. One was built\n"
+            "and measured, and is not shipped because its threshold has never\n"
+            "been calibrated — see EXPERIMENT.md.\n"
+            "compare, aggregate and truncation_curve are pure numpy and run "
+            "anywhere, so captures made elsewhere can be analyzed here.") from e
+
+    def load(model, adapter):
+        return _load(model, adapter_path=adapter) if adapter else _load(model)
+
+    def run(model_obj, tok, rendered, max_tokens):
+        text = _generate(model_obj, tok, prompt=rendered,
+                         max_tokens=max_tokens, verbose=False)
+        ids = tok.encode(rendered + text)
+        n_prompt = len(tok.encode(rendered))
+        logits = model_obj(mx.array([ids])[:, :-1]).astype(mx.float32)
+        logp = logits - mx.logsumexp(logits, axis=-1, keepdims=True)
+        ent = np.asarray((-mx.sum(mx.exp(logp) * logp, axis=-1))[0].tolist())
+        del logits, logp
+        return text, n_prompt, len(ids) - n_prompt, ent
+
+    return load, run
+
+
+
+def capture(model, prompts, tag='run', max_tokens=512, adapter=None,
+            chat=None, model_obj=None, tokenizer=None,
+            progress=None) -> Capture:
+    """Run `prompts` through a model configuration and record its entropy.
+
+    `model` is a path or HF id. Pass `model_obj`/`tokenizer` instead to reuse an
+    already-loaded model, or to measure a configuration this library has no way
+    to construct itself — a patched runtime, a custom cache, an offload wrapper.
+    That is the intended extension point: clausius does not manage
+    configurations, it compares whatever two runs you hand it.
+
+    Arguments are checked before the runtime is imported, so a caller wiring up
+    that extension point finds out on any machine rather than only on a Mac.
+
+    The runtime is recorded on the capture. A torch backend exists on the
+    `feat/torch-backend` branch and is NOT shipped — see EXPERIMENT.md for the
+    decision and FINDINGS F15 for the measurement behind it.
+    """
+    if model_obj is None and model is None:
+        raise ValueError(
+            "capture needs either `model` (a path or HF id) or a preloaded "
+            "`model_obj` plus `tokenizer`")
+    if model_obj is not None and tokenizer is None:
+        raise ValueError(
+            "`model_obj` was given without `tokenizer`; capture needs both — "
+            "the tokenizer renders the chat template and counts prompt tokens, "
+            "which is what separates prompt positions from generated ones")
+
+    load, run = _backend_mlx()
+
+    if model_obj is None:
+        model_obj, tokenizer = load(model, adapter)
+    rows, t0 = [], time.time()
+    for i, prompt in enumerate(prompts):
+        rendered = apply_chat_template(tokenizer, prompt, chat)
+        # teacher-forced pass over prompt+completion: entropy at the positions
+        # where the model actually committed, not at whatever it would have
+        # produced under a different sampler
+        text, n_prompt, n_gen, ent = run(model_obj, tokenizer, rendered,
+                                         max_tokens)
+        rows.append({'ent': aggregate(ent, n_prompt),
+                     'truncated': n_gen >= max_tokens - 2,
+                     'empty_gen': n_gen <= 0,
+                     'text': text[:2000]})
+        if progress:
+            progress(i + 1, len(prompts))
+    # A capture is read back weeks later, so it has to say what produced it. With
+    # a preloaded model there is no path to record, and str(None) — which this
+    # used to write — is worse than useless as provenance.
+    origin = str(model) if model is not None else \
+        f'<preloaded {type(model_obj).__name__}>'
+    cap = Capture(model=origin, tag=tag, prompts=list(prompts), rows=rows,
+                  meta={'max_tokens': max_tokens, 'adapter': adapter,
+                        'chat': chat, 'backend': 'mlx',
+                        'truncated': sum(r['truncated'] for r in rows),
+                        'seconds': round(time.time() - t0, 1)})
+
+    # The curve travels with the capture, so a caller who never touches the CLI
+    # still has it — including after a save/load round trip weeks later.
+    curve = truncation_curve(cap)
+    cap.meta['truncation'] = curve.as_dict()
+    if not curve.usable:
+        # A warning rather than a raise: the capture is real, it cost GPU time,
+        # and `compare(drop_truncated=False)` can still use it. But silence here
+        # is what let a doomed pair reach compare twice during development, and
+        # the Python API is the documented path for offload wrappers and patched
+        # runtimes — the callers least likely to be watching a terminal.
+        warnings.warn(
+            f"only {curve.survivors} of {curve.n_items} items survive at "
+            f"max_tokens={curve.cap_used}, and compare() needs {curve.floor}. "
+            f"A candidate capture can only truncate more, so this comparison "
+            f"cannot succeed. Re-capture with a larger max_tokens (the cap is "
+            f"not recoverable after the fact), or pass drop_truncated=False.",
+            stacklevel=2)
+    return cap
+
+
+def _pair(reference, candidate, drop_truncated):
+    """Load, validate, and return (ref, cand, kept indices).
+
+    Shared by `compare` and `top_movers` so the two can never disagree about
+    which items count — a diagnostic that explained items the verdict had
+    already discarded would be worse than none.
+    """
+    ref = reference if isinstance(reference, Capture) else Capture.load(reference)
+    cand = candidate if isinstance(candidate, Capture) else Capture.load(candidate)
+
+    if len(ref.rows) != len(cand.rows):
+        raise ValueError(
+            f"captures have different lengths ({len(ref.rows)} vs "
+            f"{len(cand.rows)}); a paired comparison needs the same items")
+    if ref.prompts and cand.prompts and ref.prompts != cand.prompts:
+        raise ValueError(
+            "captures used different prompts; pairing them would compare two "
+            "datasets rather than two configurations")
+
+    rb, cb = ref.meta.get('backend'), cand.meta.get('backend')
+    if rb and cb and rb != cb:
+        # Not an error: "did switching inference backend break the model" is a
+        # real question, and this is how you would ask it. But the 0.3 threshold
+        # was calibrated within a runtime, where kernel-level differences cancel
+        # in the paired difference. Across runtimes they do not, and no benign
+        # backend swap has been measured to establish that null.
+        warnings.warn(
+            f"comparing a {rb} capture against a {cb} one. The threshold is "
+            f"calibrated within a single runtime; across runtimes a benign "
+            f"difference in numerics or tokenisation is not distinguishable "
+            f"from damage, and that null has not been measured.", stacklevel=2)
+
+    keep = [i for i in range(len(ref.rows))
+            if not (drop_truncated and (ref.rows[i].get('truncated')
+                                        or cand.rows[i].get('truncated')))]
+    if len(keep) < MIN_PAIRED_ITEMS:
+        raise ValueError(
+            f"only {len(keep)} items survive truncation filtering; the effect "
+            f"size would be noise. Raise max_tokens or pass "
+            f"drop_truncated=False.")
+    return ref, cand, keep
+
+
+def bootstrap_ci(deltas, resamples=BOOTSTRAP_RESAMPLES, seed=BOOTSTRAP_SEED,
+                 level=95.0):
+    """Interval for d_z under resampling the PROMPTS.
+
+    Seeded, and deliberately so. Everything else about a capture is
+    deterministic — a capture at 1536 predicted 47/60 truncations at 512 and a
+    separate run at 512 produced exactly 47 — and a CI gate whose JSON output
+    changes between runs on identical inputs is not a gate.
+
+    WHAT IT COVERS: how much d_z would move if you had drawn a different sample
+    of prompts. That is the question behind "are 60 prompts enough?".
+
+    WHAT IT DOES NOT COVER: the benign-configuration variation the ±0.10 null
+    measures. Those are different sources of uncertainty. A tight interval
+    around +0.15 means *this prompt set reliably reads +0.15*, NOT that the
+    change is safe — the verdict against the threshold is what says that, and
+    the threshold is calibrated against benign configs rather than against
+    prompt resampling.
+    """
+    d = np.asarray(deltas, dtype=float)
+    if len(d) < 2:
+        return (float('nan'), float('nan'))
+    rng = np.random.default_rng(seed)
+    draws = d[rng.integers(0, len(d), (resamples, len(d)))]
+    dz = draws.mean(axis=1) / (draws.std(axis=1, ddof=1) + 1e-12)
+    tail = (100.0 - level) / 2.0
+    lo, hi = np.percentile(dz, [tail, 100.0 - tail])
+    return float(lo), float(hi)
+
+
+def compare(reference, candidate, signal=DEFAULT_SIGNAL,
+            threshold=DEFAULT_THRESHOLD, one_sided=True,
+            drop_truncated=True, resamples=BOOTSTRAP_RESAMPLES,
+            seed=BOOTSTRAP_SEED) -> Result:
+    """Paired entropy comparison. Returns a Result; raises on mismatched inputs.
+
+    Accepts `Capture` objects or paths to saved ones.
+
+    The reported interval is descriptive only — `flagged` is the threshold test
+    and nothing else, because that threshold is what 13 benign configurations
+    calibrated. Turning the verdict into a significance test would replace a
+    measured decision rule with an unmeasured one.
+    """
+    if signal not in SIGNALS:
+        raise ValueError(f"unknown signal {signal!r}; choose from {SIGNALS}")
+    ref, cand, keep = _pair(reference, candidate, drop_truncated)
+    dropped = len(ref.rows) - len(keep)
+
+    detail, chosen = {}, None
+    for s in SIGNALS:
+        x = np.array([ref.rows[i]['ent'][s] for i in keep])
+        y = np.array([cand.rows[i]['ent'][s] for i in keep])
+        ok = np.isfinite(x) & np.isfinite(y)
+        d = y[ok] - x[ok]
+        detail[s] = float(d.mean() / (d.std(ddof=1) + 1e-12))
+        if s == signal:
+            chosen = d
+
+    effect = detail[signal]
+    flagged = effect > threshold if one_sided else abs(effect) > threshold
+    return Result(flagged=flagged, effect=effect, signal=signal,
+                  threshold=threshold, one_sided=one_sided,
+                  n_compared=len(keep), n_dropped_truncated=dropped,
+                  detail=detail,
+                  ci=bootstrap_ci(chosen, resamples=resamples, seed=seed))
+
+
+def top_movers(reference, candidate, n=5, signal=DEFAULT_SIGNAL,
+               drop_truncated=True):
+    """The items whose entropy moved most, with the text from both configs.
+
+    `compare` answers "did something break". This answers "show me", which is
+    the next question every time and the one the aggregate cannot address:
+    d_z is ordinal rather than proportional (FINDINGS F14d), so the per-item
+    view is how a reader forms their own judgment of severity.
+
+    Everything needed is already recorded — no second capture, no model.
+    """
+    if signal not in SIGNALS:
+        raise ValueError(f"unknown signal {signal!r}; choose from {SIGNALS}")
+    ref, cand, keep = _pair(reference, candidate, drop_truncated)
+    rows = []
+    for i in keep:
+        a = ref.rows[i]['ent'][signal]
+        b = cand.rows[i]['ent'][signal]
+        if not (np.isfinite(a) and np.isfinite(b)):
+            continue
+        rows.append({
+            'i': i,
+            'delta': float(b - a),
+            'ref': float(a),
+            'cand': float(b),
+            'prompt': ref.prompts[i] if i < len(ref.prompts) else '',
+            'ref_text': ref.rows[i].get('text', ''),
+            'cand_text': cand.rows[i].get('text', ''),
+        })
+    rows.sort(key=lambda r: r['delta'], reverse=True)
+    return rows[:n]

clausius-0.1.0.dist-info/METADATA

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: clausius
+Version: 0.1.0
+Summary: Detect whether a deployment change degraded your model — without a labeled eval set
+Project-URL: Homepage, https://github.com/beatakouchnir/clausius
+Project-URL: Findings, https://github.com/beatakouchnir/clausius/blob/main/FINDINGS.md
+Project-URL: Issues, https://github.com/beatakouchnir/clausius/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: llm,mixture-of-experts,mlx,quantization,regression-testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: mlx
+Requires-Dist: mlx-lm>=0.20; extra == 'mlx'
+Description-Content-Type: text/markdown
+
+# clausius — did the thing you changed break your model?
+
+Two questions, both answered on consumer hardware (M5 Max, 128 GB), across five
+model families:
+
+1. **What is the best model you can actually run in the memory you have?**
+2. **If you change anything — config, quantization, fine-tune — how would you
+   know it broke the model, without a labeled eval set?**
+
+## What's new here
+
+- **Accuracy measured across MoE offload configurations at all** — four surveyed
+  implementations report none. It inverts the default advice: at matched memory,
+  aggressive quantization costs **73 points** of instruction adherence where
+  exact expert offload costs **1.0**.
+- **Label-free regression detection, checked against independently measured
+  damage.** Predictive entropy is well studied; using it to detect that *a
+  deployment change broke the model* — validated against five unrelated damage
+  mechanisms whose true cost was measured separately — appears not to be. It
+  flagged a −2.2pp quantization regression on **60 unlabeled prompts**, where
+  paired McNemar on gold labels needed **n=878** to reach p<0.05 (F14).
+- **The corpus is committed, so the tables below rebuild on a laptop** — no
+  model, no accelerator, two commands. Negatives included: eight controlled
+  failures where the interesting signal lost to a simpler one, and seven places
+  where a result did not survive its own check and the record says so.
+
+**Scope, up front.** Capturing needs Apple Silicon (`mlx-lm`). Everything else —
+`compare`, the analysis, and re-deriving every table below from the committed
+corpus — is pure numpy and runs anywhere, with no model downloads:
+
+```bash
+git clone https://github.com/beatakouchnir/clausius && cd clausius
+pip install ".[dev]" && pytest -q                  # 36 tests, no accelerator
+python -m knowledge.quantladder analyze            # rebuilds F14's ladder from records
+python -m knowledge.frontier report                # rebuilds the 3-axis Pareto frontier
+```
+
+That is the fastest way to check whether the numbers here are real.
+
+---
+
+*Named for Rudolf Clausius, who coined the word **entropy** in 1865 — from the
+Greek `trope`, transformation, shaped to echo "energy" so the two would sound
+like the related quantities they are. Entropy is the signal this tool reads.*
+
+## Quickstart
+
+```bash
+pip install "clausius[mlx] @ git+https://github.com/beatakouchnir/clausius"
+```
+
+Take 60 prompts of your own — production traffic is ideal, and **no labels are
+needed** — or start with the 60 in [`examples/prompts.jsonl`](https://github.com/beatakouchnir/clausius/blob/main/examples/prompts.jsonl).
+Capture the configuration you trust, capture the one you changed, compare:
+
+```bash
+clausius capture --model ./gemma-26b-a4b-4bit --prompts examples/prompts.jsonl \
+    --out ref.json  --max-tokens 1536
+clausius capture --model ./gemma-26b-a4b-2bit --prompts examples/prompts.jsonl \
+    --out cand.json --max-tokens 1536
+clausius compare ref.json cand.json --show 3
+```
+
+```
+REGRESSION  (max d_z = +5.922, threshold 0.3, one-sided)
+  compared 20 paired items, dropped 5 truncated
+  all signals: max +5.92  p90 +11.64  mean +10.43  mean_top10 +9.00  first +2.80  gen_len +10.55
+```
+
+That is a real run, on 25 unlabeled prompts. The two checkpoints differ only in
+quantization; the 2-bit one independently measures **73 points lower** on
+instruction adherence. `compare` exits non-zero on a regression, so it drops
+into CI without glue.
+
+**→ [USAGE.md](https://github.com/beatakouchnir/clausius/blob/main/USAGE.md) is the operating manual**: choosing prompts, setting
+the token cap, reading `d_z` and its interval, calibrating your own null, and
+running it as a CI gate. Start there after your first run.
+
+**Every default is a measured result, not a preference** — the 0.3 threshold
+comes from 13 configurations known to be harmless, the one-sided test from a
+construction that fools a two-sided one, the truncation filter from an effect
+that doubles once you apply it. `src/clausius/core.py` states each one and
+[FINDINGS.md](https://github.com/beatakouchnir/clausius/blob/main/FINDINGS.md) has the evidence.
+
+> **Status.** `clausius` is installable and tested (36 tests, no accelerator
+> required). The `knowledge/` research package that produced the findings is
+> *not* packaged — it needs local model checkpoints and an external artifact
+> store, and is kept for reproducibility rather than reuse.
+
+---
+
+## What was measured
+
+Full evidence, positives *and* negatives, in
+[FINDINGS.md](https://github.com/beatakouchnir/clausius/blob/main/FINDINGS.md) —
+which opens with a prior-art accounting stating which parts independently
+re-derive published work and which appear to be new. The headline results:
+
+| | result | where |
+|---|---|---|
+| **Offload beats downsizing** | an offloaded 35B at **3.40 GB** scores **0.9447** on gsm8k, against a natively-fitting 4B at 3.91 GB scoring 0.8426. Same ordering on popqa (+13.9pp) and mmlu_pro (+20.9pp). The whole cost is latency. | F3–F6 |
+| **The lossy shortcut is dominated** | *dropping* non-resident experts instead of fetching them costs **91% of gsm8k accuracy** at 50% residency, while being slower. | F6 |
+| **Label-free detection works** | validated against five unrelated damage mechanisms whose true damage was measured independently. Benign controls stay clean: a 3.3× memory reduction changes ~25% of generations textually and moves no signal. | F8 |
+| **It is more sensitive than labels** | the −2.2pp regression above: flagged on 60 unlabeled prompts, where labels needed n=878. | F14 |
+| **Forgetting is detectable too** | move the reference and it becomes a training monitor: LoRA checkpoints on a held-out domain read d_z +0.74 to +0.84 at −16 to −26pp accuracy. | F9 |
+| **Short benchmarks understate damage ~14×** | factual QA loses 1.5pp where structured generation loses 18–21pp under the same quantization — the axis agents live on. | F11 |
+| **Routing carries a fact-level address** | ablate the experts a fact routes to and that fact degrades far more than a paraphrase, a same-relation fact, or a random control. Two architectures. A **mechanism** result, not a product. | R9–R10 |
+
+### What it does not do
+
+- **Sensitivity is the weaker half.** Specificity is 13/13; a −5.7pp config is
+  missed at any threshold that preserves that record.
+- **Confidence-increasing damage would be invisible** to a one-sided detector.
+  Three mechanisms were built to produce it and none did, but it is not excluded.
+- **d_z is ordinal, not proportional.** 3-bit loses 25× more accuracy than 4-bit
+  and reads 2× the d_z. "Something moved, and roughly how hard" is supportable;
+  "you lost k accuracy points" is not.
+- Needs logits and a reference config; it cannot score a config in isolation.
+- **The threshold is calibrated on one stack.** On a different framework, device
+  or quantizer, measure your own null first —
+  [USAGE.md](https://github.com/beatakouchnir/clausius/blob/main/USAGE.md#calibrating-your-own-null) has the recipe.
+
+### Scope: local models, GPU capture
+
+**Local and self-hosted only, deliberately.** Anthropic exposes no logprobs at
+all, Gemini's are missing on current frontier models, and OpenAI caps
+`top_logprobs` at 20 — *truncated* entropy, a different quantity. Hosted-API
+support and cascade routing are recorded as **don't-build** decisions in
+[EXPERIMENT.md](https://github.com/beatakouchnir/clausius/blob/main/EXPERIMENT.md).
+
+**Capture targets a GPU**: Apple Silicon via MLX in this release, CUDA next,
+CPU never — measured here, 7B decode runs 6.7 tok/s on CPU against 22 on the
+same machine's GPU, the gap widens with size, and the 26B MoE behind the
+findings is impractical there. Two terms that are often conflated:
+
+| | | |
+|---|---|---|
+| **framework** | mlx, PyTorch | which library runs the forward pass |
+| **device** | cuda, mps, cpu | which hardware PyTorch dispatches to |
+
+Nothing about the *method* needs Apple Silicon, and a working PyTorch framework
+backend exists on the `feat/torch-backend` branch — **deliberately not
+shipped**. It was measured on mps and cpu (F15, F15c), so the framework path is
+exercised; what has never been calibrated is the **cuda device** and the
+CUDA-native quantizers (bitsandbytes, GPTQ, AWQ). Shipping a runtime whose
+threshold is uncalibrated on the device most users would run would contradict
+the claim this package makes about its defaults. The bar it must clear is in
+[EXPERIMENT.md](https://github.com/beatakouchnir/clausius/blob/main/EXPERIMENT.md).
+
+## Claim taxonomy — keep these separate
+
+Two halves making **different kinds of claim**. Conflating them would overstate
+one and undersell the other.
+
+| half | signal | claim type | validated by | breadth |
+|---|---|---|---|---|
+| **online** | predictive entropy | *"this answer is likely wrong"*, *"this change broke the model"* — a **correctness** claim | Stages A–D, F8–F9 | 5 models, 6 task configs, 5 damage mechanisms |
+| **offline** | routing ablation | *"this came from stored fact X"* — a **mechanism** claim | R3, R9, R9c, R10 | 2 architectures, probe-style |
+
+**Entropy is mechanism-blind** — it reports that the model was uncertain, not
+*how* the answer was produced. So *"flag the answers the model was least sure
+of"* is defensible and *"our telemetry tells you how the answer was generated"*
+is not. **Neither half claims to improve accuracy.**
+
+## What did not work
+
+Eight controlled negatives where routing lost to a simpler signal — usually
+reading the prompt text, or predictive entropy. The structural reason: routing
+is downstream of the residual stream *and* the prompt, so it is bounded by
+both. Part II of
+[FINDINGS.md](https://github.com/beatakouchnir/clausius/blob/main/FINDINGS.md)
+records them so they are not re-run.
+
+## Seven corrections worth reading
+
+The record keeps its own failures, because they were load-bearing:
+
+- **A planned 16-50 GPU-hour sweep was canceled after reading the
+  implementation.** `policy='exact'` fetches missing experts before computing —
+  it would have measured a guaranteed flat line.
+- **A confident mechanistic hypothesis died with its own bug fix.** A tidy
+  shared-expert explanation for a gemma-vs-qwen top-k split evaporated when a
+  ranking error was corrected — `argpartition` guarantees membership, not order.
+- **An instrumentation bug meant a whole axis was never measured.**
+  `mx.get_peak_memory()` captured the model load before the cache freed it, so
+  every configuration reported identical memory.
+- **A published-looking result was a scoring artifact.** The RAG conditional
+  claim read −0.431 in the predicted direction until the scorer accepted any
+  gold alias; it then read +0.066, the wrong direction. Recorded as open.
+- **A rationale in the shipped code was wrong for three runs running.** The
+  truncation filter was justified by "a damaged model rambles into the token
+  cap" — but a *healthy* 4-bit truncated 47/60 items at cap 512 where a
+  destroyed 2-bit truncated 3, and two LoRA fine-tunes truncated 22 and 33 of 50
+  where their base truncated none. Rambling tracks off-distribution, not damage.
+  The filter was right; the reason was not (F14b).
+- **A calibration claim was falsified by the next measurement.** A widened null
+  (+0.172) was attributed to the reference being unquantized; the same pair
+  reads −0.062 on gsm8k. It was the prompt set. Superseded, not overwritten
+  (F14c).
+- **An assumption made the exact error the finding warns against.** F14 assumed
+  3-bit "sits between two measured points in damage" — right about the ordering,
+  badly wrong about the distance: −56.6pp, a broken deployment, at only 2x
+  4-bit's d_z. Kept visible as a worked example of ordinal-not-proportional
+  (F14d).
+
+Two method rules came out of them, applied throughout:
+
+> **Read a knob's implementation before scoping a sweep over it.**
+> **A wiring control must be able to fail on the assumption it protects.**
+
+The second has teeth: a top-k no-op control passed 16/16 while the ranking
+assumption beneath it was wrong, because keeping every position is
+order-independent.
+
+## Prior art
+
+Applied, not ours: MoE expert offloading with an LRU cache
+([Mixtral-offloading](https://arxiv.org/pdf/2312.17238)), speculative expert
+prefetch ([HOBBIT](https://arxiv.org/pdf/2411.01433), ExpertFlow, CommitMoE),
+predictive entropy, McNemar, Belady, Pareto dominance.
+
+What appears new: **accuracy measured across MoE offload configurations at
+all** (four surveyed implementations report none); exact offload being
+**capacity-non-reproducible but fixed-capacity deterministic**, which
+invalidates output-diffing as a validation method; **prefill admitting *optimal*
+caching**, since a layer's routing for the whole prompt yields the access
+sequence before any fetch; and **label-free config-regression detection
+validated against independently-known damage**.
+
+---
+
+## Repository layout
+
+| path | what | needs |
+|---|---|---|
+| `src/clausius/` | **the tool** — capture, compare, CLI | numpy; mlx-lm only to capture |
+| `tests/` | 36 tests, none load a model; CI installs the built wheel | numpy |
+| `records/` | **the measurement corpus** — the evidence behind FINDINGS.md, ~10 MB | — |
+| `knowledge/` | the research package that produced the findings | local checkpoints, external artifact store (`CLAUSIUS_ARTIFACTS`) |
+| `USAGE.md` | **the operating manual** — prompts, caps, reading the output, CI | — |
+| `FINDINGS.md` | the full experimental record, positives and negatives | — |
+| `EXPERIMENT.md` | designs, scope decisions, what was deliberately not built, and ten hard-won operational cautions | — |
+
+The split is deliberate: the detector **needs no labels and no benchmark harness
+to be used** — scoring exists only to *validate* it, which is what `knowledge/`
+does ([its README](https://github.com/beatakouchnir/clausius/blob/main/knowledge/README.md)
+documents every module and how to obtain the datasets). Analysis is stdlib/numpy
+and loads no model, deliberately: MLX uses unified memory, so pinning to
+`mx.cpu` isolates nothing — the axis that matters is loads-a-model vs doesn't.

clausius-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+clausius/__init__.py,sha256=8XKGqXK1DwmUvtxrSF5J9aJnouvqJhxAvSp_3DtRHbw,1626
+clausius/cli.py,sha256=rEJpTc57zazFl1Q0fUoUQ5XZzvr16wUFiwrKv9OBAWE,7746
+clausius/core.py,sha256=66N8xueflZ1OZerW3D61F_TAXwro7kHlDt3cCC8dbl4,23856
+clausius-0.1.0.dist-info/METADATA,sha256=hfSDOSEJy-FrISe-8lTT3rq1zxcN-yrVkYSzQVB3pFs,15137
+clausius-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+clausius-0.1.0.dist-info/entry_points.txt,sha256=dto1HDzy4DcWnjfIYSqB910JhQ1YZPfC5nsaa7Ap44Y,47
+clausius-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+clausius-0.1.0.dist-info/licenses/NOTICE,sha256=qpb5JCIil1U0hEYkPohegpD72KwIEChof5UBX75dzfg,2492
+clausius-0.1.0.dist-info/RECORD,,

clausius-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

clausius-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clausius = clausius.cli:main

clausius-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

clausius-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,48 @@
+clausius
+Copyright 2026 Beata Kouchnir
+
+This product includes software developed for measuring the effect of
+deployment-time changes on language models.
+
+The research package (`knowledge/`) vendors code under `knowledge/_vendor/`,
+copied from the author's other work rather than depended on, so that this
+repository is self-contained. It carries the same license as the rest.
+
+--------------------------------------------------------------------------
+DATASETS
+
+The measurement corpus under `records/` holds results DERIVED from the public
+evaluation datasets below — accuracy, entropy and per-item scores. No dataset
+is bundled: `knowledge/` fetches each one from the Hugging Face Hub at run
+time, so reproducing an experiment means obtaining the data from its original
+source under that source's own terms.
+
+    GSM8K            openai/gsm8k                              MIT
+    MMLU-Pro         TIGER-Lab/MMLU-Pro                        MIT
+    PopQA            akariasai/popqa                           no license declared
+    HumanEval+       evalplus/humanevalplus                    Apache-2.0
+    IFEval           google/IFEval                             Apache-2.0
+    GPQA             Idavidrein/gpqa                           CC BY 4.0, gated
+    AA-Omniscience   ArtificialAnalysis/AA-Omniscience-Public  Apache-2.0
+    HLE              cais/hle                                  MIT, gated
+
+Two files redistribute source items verbatim, under the MIT terms above:
+
+    records/quantladder/prompts.gsm8k100.jsonl   100 GSM8K questions
+    records/quantladder/prompts.gsm8k200.jsonl   200 GSM8K questions
+
+and the gold answers for those items are stored alongside the model's
+predictions in `records/quantladder/acc.*.json`. They are included so that the
+same-item comparison in FINDINGS F14c can be checked exactly rather than
+approximately.
+
+GPQA is treated differently, at its authors' request: they ask that the
+dataset not be posted in plain text online, to keep it out of future training
+corpora. No GPQA question, answer option or gold answer appears anywhere in
+this repository, and the model's generated answer text was removed from
+`records/stage_a.gpqa*.json` for the same reason. What remains is derived
+measurement — correctness, entropy, and the domain label.
+
+IFEval scoring uses Google Research's `instruction_following_eval` registry
+(Apache-2.0), which is NOT bundled here. Where it is absent the scorer returns
+no verdict for that item rather than guessing.