Add AutoPolicy 001 exact budget planner

.gitattributes

@@ -11,6 +11,7 @@ LICENSE text eol=lf
 
 # Preserve byte-level evidence identities on every checkout.
 research/results/experiment-001/** -text
-figures/figure-manifest.json -text
+research/results/autopolicy-001/** -text
+figures/*manifest.json -text
 figures/*.png -text
 requirements/verification-*.txt -text

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -13,7 +13,7 @@ body:
     attributes:
       label: Version or commit
       description: Provide the release version or Git commit SHA you tested.
-      placeholder: "0.1.2 or abc1234"
+      placeholder: "0.2.0 or abc1234"
     validations:
       required: true
 

.github/workflows/ci.yml

@@ -49,6 +49,11 @@ jobs:
           --inventory-only
           research/results/experiment-001
 
+      - name: Validate AutoPolicy evidence
+        run: >-
+          python scripts/validate_autopolicy_release.py
+          research/results/autopolicy-001
+
       - name: Run tests
         run: python -m pytest --basetemp .pytest-ci
 
@@ -58,4 +63,4 @@ jobs:
       - name: Smoke-test installed wheel
         run: >-
           python scripts/smoke_installed_distribution.py
-          dist/cliffquant-0.1.2-py3-none-any.whl
+          dist/cliffquant-0.2.0-py3-none-any.whl

CITATION.cff

@@ -5,15 +5,17 @@ type: software
 authors:
   - given-names: "Muhammad Labeeb Aryan"
     family-names: "bin Mohd Lokman"
-version: 0.1.2
+version: 0.2.0
 license: Apache-2.0
 repository-code: "https://github.com/Labeeb2339/cliffquant"
 url: "https://github.com/Labeeb2339/cliffquant"
 abstract: >-
   Exact minimax FP16 scale selection for a frozen multi-environment diagonal
-  quantization proxy, checked against exhaustive reference enumeration.
+  quantization proxy, plus exact logical-budget policy planning over recorded
+  mixed-precision candidates.
 keywords:
   - quantization
   - W4A16
   - model compression
+  - mixed precision
   - reproducible research

README.md

@@ -104,6 +104,54 @@ calibration environment separately, and optimizes the worst-environment scale
 objective exactly. The RecurQuant diagnostic is context for this decision, not
 part of CliffQuant's Experiment 001 evidence.
 
+## AutoPolicy 001: exact logical-budget planning
+
+AutoPolicy turns the frozen Experiment 001 measurements into an auditable
+mixed-precision plan. It records W4 CliffQuant, W8 AbsMax, and unquantized BF16
+source-reference candidates for all 150 target matrices. The published robust
+view selects one precision per transformer block and exactly minimizes the
+recorded worst-environment additive proxy under a logical target-payload
+budget.
+
+![AutoPolicy logical-byte frontier](figures/autopolicy-logical-byte-frontier.png)
+
+| Logical bits per target weight | W4 blocks | W8 blocks | BF16 blocks | Worst-environment proxy |
+|---:|---:|---:|---:|---:|
+| `4.125` | 24 | 0 | 0 | `1078.217405` |
+| `7.087` | 6 | 18 | 0 | `218.811198` |
+| `8.125` | 0 | 24 | 0 | `4.745117` |
+| `16.000` | 0 | 0 | 24 | `0.000000` |
+
+At the representative `440,721,408`-byte budget, the exact plan uses
+`440,303,616` logical bytes and selects 6 W4 plus 18 W8 blocks. The full
+150-matrix robust frontier was not tractable with the current exact dynamic
+program, so the robust publication view makes a transformer-block constraint
+explicit instead of hiding an approximation. Matrix-level exact planning
+remains available for the scalar `sum-groupwise-max` objective.
+
+AutoPolicy does not yet export or benchmark a runnable mixed-bit checkpoint.
+Its bytes are logical target payload, not checkpoint size or runtime memory,
+and its proxy values are not NLL or accuracy predictions.
+
+[Read the method](research/AUTOPOLICY_001_METHOD.md)
+|
+[Inspect the measured result](research/AUTOPOLICY_001_RESULT.md)
+|
+[Review the prior-art boundary](research/AUTOPOLICY_PRIOR_ART.md)
+|
+[Verify the portable evidence](research/results/autopolicy-001)
+
+From a repository checkout:
+
+```bash
+cliffquant autopolicy verify \
+  --candidates research/results/autopolicy-001/candidates.json
+
+cliffquant autopolicy verify \
+  --candidates research/results/autopolicy-001/candidates-transformer-blocks.json \
+  --plan research/results/autopolicy-001/plan-blocks-7bpp.json
+```
+
 ## Verification
 
 - `10,000 / 10,000` deterministic solver cases matched exhaustive FP16
@@ -202,7 +250,7 @@ python -m pytest
 python -m build
 ```
 
-Regenerate all three figures from the finalized proxy and NLL artifacts:
+Regenerate the three proxy/NLL figures from the finalized artifacts:
 
 ```bash
 python scripts/generate_figures.py \
@@ -215,6 +263,20 @@ The generator verifies the input checksum manifests before parsing results and
 writes its own provenance to
 [`figures/figure-manifest.json`](figures/figure-manifest.json).
 
+Regenerate the AutoPolicy frontier and its fourth figure from the checked-in
+transformer-block candidate table:
+
+```bash
+python scripts/generate_autopolicy_frontier.py \
+  --candidates research/results/autopolicy-001/candidates-transformer-blocks.json \
+  --output-json research/results/autopolicy-001/frontier.json \
+  --output-figure figures/autopolicy-logical-byte-frontier.png \
+  --output-manifest figures/autopolicy-logical-byte-frontier.manifest.json
+```
+
+That generator re-solves every recorded budget and writes a separate manifest
+binding the graph and frontier to the exact candidate table and generator.
+
 Validate the exact checked-in inventory on any supported development platform:
 
 ```bash

figures/autopolicy-logical-byte-frontier.manifest.json

@@ -0,0 +1 @@
+{"generator":{"file":"scripts/generate_autopolicy_frontier.py","matplotlib":"3.10.8","sha256":"835354cdb00d519e9f4ae2a1699398a5b77115474e2ad369d4586c571e4a68df"},"input":{"candidate_fingerprint_sha256":"5af77e3afec3ac75339da56c171ae9ab37939cfe8ab0e4b0b878f370862031ca","file":"../research/results/autopolicy-001/candidates-transformer-blocks.json","sha256":"248268b088e8f82aa2125fa254f0ada7d2d120943199322bcef4f95beb633b3b","size_bytes":41267},"outputs":{"figure":{"file":"autopolicy-logical-byte-frontier.png","height_px":1332,"sha256":"664a469e7c50150458685ca1b7c0380d15e2adad5e87371abbf9a3ff4b66b8cb","size_bytes":124523,"width_px":2052},"frontier":{"file":"../research/results/autopolicy-001/frontier.json","sha256":"147945284fc3794143af87dc7c92db5fd98aa25eabe8b7c42f950f877ee3d869","size_bytes":5466}},"schema":"cliffquant.autopolicy-figure-provenance.v1"}

pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cliffquant"
-version = "0.1.2"
-description = "Exact minimax FP16 scale selection for a multi-environment diagonal proxy"
+version = "0.2.0"
+description = "Exact multi-environment quantization scale and logical-budget policy research"
 readme = "README.md"
 requires-python = ">=3.11"
 license = "Apache-2.0"
@@ -21,6 +21,10 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
+autopolicy-experiment = [
+  "ml-dtypes>=0.5.1",
+  "safetensors>=0.8.0",
+]
 dev = [
   "build>=1.2",
   "packaging>=26.2",
@@ -31,6 +35,9 @@ figures = [
   "matplotlib==3.10.8",
 ]
 
+[project.scripts]
+cliffquant = "cliffquant.cli:main"
+
 [tool.setuptools.packages.find]
 where = ["src"]
 

research/AUTOPOLICY_001_METHOD.md

@@ -0,0 +1,129 @@
+# AutoPolicy 001 method
+
+## Purpose
+
+AutoPolicy 001 is a development measurement built from CliffQuant Experiment
+001. It asks a narrower question than a mixed-bit model benchmark:
+
+> Given a recorded W4, W8, and unquantized BF16 candidate for every frozen
+> target matrix, which discrete assignment minimizes a recorded
+> multi-environment reconstruction proxy under a logical target-payload budget?
+
+This is not a preregistered confirmation experiment. Its role is to validate the
+planner, artifact chain, byte model, and robust objective before any mixed-bit
+checkpoint is exported.
+
+## Frozen inputs
+
+- Base model: `Qwen/Qwen3.5-0.8B-Base` at revision
+  `dc7cdfe2ee4154fa7e30f5b51ca41bfa40174e68`.
+- The 150 language-tower matrices and 128-weight grouping already frozen by
+  Experiment 001.
+- The four separately normalized calibration environments already frozen by
+  Experiment 001: general, code, math, and multilingual.
+- The validated CliffQuant W4 scale run and its exact stored FP16 scales.
+
+The builder refuses model, calibration, module-inventory, or scale-run identity
+drift.
+
+## Candidate bank
+
+Each matrix receives exactly three choices:
+
+| Candidate | Codes | Stored scale | Distortion |
+|---|---:|---|---|
+| `w4_cliffquant` | signed INT4 | one FP16 scale per 128 weights | direct re-evaluation of the validated exact CliffQuant scales |
+| `w8_absmax` | signed INT8 | one FP16 scale per 128 weights | sign-aware no-clipping AbsMax target, rounded to the nearest positive finite FP16 scale |
+| `dense16` | unquantized BF16 source reference | none | zero reconstruction distortion by definition |
+
+W8 uses round-to-nearest, ties-to-even, followed by clipping to `[-128, 127]`.
+It is an AbsMax control, not an exact W8 scale optimizer.
+
+For every candidate, the builder records:
+
+- the sum of groupwise worst-environment normalized diagonal squared error; and
+- the module-level squared-error total for each environment separately.
+
+## Allocation granularity
+
+The measured candidate bank contains all 150 target matrices. AutoPolicy exposes
+two exact views over that table:
+
+- matrix-level allocation for the additive `sum-groupwise-max` scalar
+  objective; and
+- a 24-transformer-block view for the four-environment robust-minimax
+  objective, where all matrices in a selected block use the same candidate.
+
+The block view sums the recorded matrix distortions and logical bytes without
+changing them. It makes the exact multidimensional frontier tractable while
+keeping the precision choice deployable at a clear architecture boundary. The
+published AutoPolicy 001 frontier uses this block view. The full 150-matrix
+robust search remains available as a fail-closed research path, but it is not
+presented as the practical default.
+
+## Robust allocation objective
+
+For unit \(u\), candidate \(c\), environment \(e\), recorded distortion
+\(d_{u,c,e}\), and logical byte cost \(m_{u,c}\), the robust planner solves
+
+$$
+\min_x \max_e \sum_{u,c} d_{u,c,e}x_{u,c}
+$$
+
+subject to
+
+$$
+\sum_c x_{u,c}=1\quad\forall u,\qquad
+\sum_{u,c}m_{u,c}x_{u,c}\le B,\qquad
+x_{u,c}\in\{0,1\}.
+$$
+
+For the published robust frontier, \(u\) is a transformer block. The
+implementation keeps a componentwise byte/environment Pareto frontier. If the
+exact search exceeds its configured state, transition, or Pareto-comparison
+work limit, it aborts instead of silently returning an approximation. Objective
+ties prefer the lower sum over environments, then fewer bytes, then
+lexicographically smaller candidate IDs in sorted unit order.
+
+## Logical byte model
+
+For an integer candidate, the logical payload is:
+
+$$
+\left\lceil\frac{\text{weights}\times\text{bits}}{8}\right\rceil
++ 2\times\text{groups}.
+$$
+
+The unquantized BF16 source reference uses two bytes per target weight.
+
+The model deliberately excludes biases, zero buffers, `g_idx`, packing padding,
+non-target tensors, metadata, filesystem overhead, activations, KV cache, and
+runtime workspace. Therefore the budget is called **logical target-payload
+bytes**, not checkpoint size or runtime memory.
+
+## Verification gates
+
+- Every recomputed W4 group objective must match the validated stored objective
+  within a strict float64 numerical tolerance.
+- W8 vectorized results are tested against an independent scalar oracle.
+- Candidate JSON and every W8 array archive are content-addressed.
+- Candidate and plan JSON use strict duplicate-key rejection, finite-number
+  validation, canonical encoding, and self-fingerprints.
+- Plan verification reloads the exact candidate file and recomputes the exact
+  allocation.
+- Budgets below the all-W4 logical payload must fail closed.
+- The all-W4 and all-BF16 endpoints must select their respective uniform
+  policies.
+
+## Claim boundary
+
+AutoPolicy 001 can support only this claim:
+
+> At the selected allocation granularity, the solver returns the exact optimum
+> of the recorded discrete proxy table under the recorded logical-byte budget
+> when its exact frontier completes.
+
+It does not establish an optimum for NLL, accuracy, checkpoint size, runtime
+memory, latency, energy, or hardware throughput. It does not produce a runnable
+mixed-bit checkpoint. Those require a separate exporter and held-out
+confirmation.