Skip to content

R13 — ppl_headroom terminology disambiguation (autoscan-side annotation) #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
synapticode-ai merged 1 commit into from
Jun 4, 2026
Merged

R13 — ppl_headroom terminology disambiguation (autoscan-side annotation) #22

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 36 additions & 3 deletions src/terncore/autoscan.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,10 @@
CACHE_SCHEMA_VERSION = "autoscan_cache/2.0"

DEFAULT_BLOCK_SIZE = 10
# Autoscan-internal per-layer scan-time gate: maximum PPL degradation
# allowed per added layer-block during perplexity-gated layer-eligibility
# scanning. NOT the R7-A/R8 v1.1 outcome metric of the same name — see
# auto_scan() docstring for terminology distinction. R13.
DEFAULT_PPL_HEADROOM = 0.20

# Projection types ordered by empirical quantization tolerance (most -> least).
Expand Down Expand Up @@ -386,7 +390,20 @@ def auto_scan(
Args:
model_id: HuggingFace model ID or local path.
threshold: Ternary quantization threshold.
ppl_headroom: Maximum allowed PPL increase as a fraction (0.20 = 20%).
ppl_headroom: Maximum allowed PPL degradation as a fraction (0.20 = 20%),
applied as a per-layer scan-time GATE during the sweep:
adding a layer-block is accepted only if cumulative PPL
degradation stays under this threshold.

NOTE: this is autoscan's *internal* (autoscan-internal) sense of `ppl_headroom`
— a scan-time gate on per-layer additions. DISTINCT from
the R7-A v1.0 WikiText-2 PPL methodology / R8 v1.1
weight-compression PPL headroom diagnostic outcome metric
of the same name (`ppl_headroom = (ppl_ternary - ppl_fp16)
/ ppl_fp16`), which is a measured *result* of compression
rather than a *gate* during scanning. The two are
conceptually related but not interchangeable. See R13
(docs/backlog.md) for terminology disambiguation tracking.
block_size: Number of layers to add per sweep step.
use_cache: If True, return cached result when available.
device: Explicit device for HF model load + scan. ``None``
Expand Down Expand Up @@ -629,7 +646,20 @@ def streaming_scan(
Args:
model_id: Local path to a sharded safetensors model directory.
threshold: Ternary quantisation threshold.
ppl_headroom: Maximum allowed PPL increase as a fraction.
ppl_headroom: Maximum allowed PPL degradation as a fraction (0.20 = 20%),
applied as a per-layer scan-time GATE during the sweep:
adding a layer-block is accepted only if cumulative PPL
degradation stays under this threshold.

NOTE: this is autoscan's *internal* (autoscan-internal) sense of `ppl_headroom`
— a scan-time gate on per-layer additions. DISTINCT from
the R7-A v1.0 WikiText-2 PPL methodology / R8 v1.1
weight-compression PPL headroom diagnostic outcome metric
of the same name (`ppl_headroom = (ppl_ternary - ppl_fp16)
/ ppl_fp16`), which is a measured *result* of compression
rather than a *gate* during scanning. The two are
conceptually related but not interchangeable. See R13
(docs/backlog.md) for terminology disambiguation tracking.
use_cache: Return cached result if available.
baseline_ppl: Pre-computed baseline PPL (skips Pass 1 if given).

Expand Down Expand Up @@ -856,7 +886,10 @@ def main():
)
parser.add_argument(
"--ppl-headroom", type=float, default=DEFAULT_PPL_HEADROOM,
help=f"Maximum allowed PPL increase as a fraction (default: {DEFAULT_PPL_HEADROOM})",
help="PPL headroom threshold for autoscan per-layer scan-time gate "
"(max PPL degradation per layer-block; default 0.20). "
"Autoscan-internal sense — distinct from R7-A/R8 v1.1 outcome metric. "
"R13.",
)
parser.add_argument(
"--block-size", type=int, default=DEFAULT_BLOCK_SIZE,
Expand Down