Skip to content

Commit 23f07cf

Browse files
Labeeb2339Labeeb2339
authored
Release packed RecurQuant cache with held-out MBPP confirmation (#1)
Publishes the physically packed recurrent-state cache, frozen public evaluation, independent verifier, and v0.2.0a1 release documentation.
2 parents 42d510a + f11f894 commit 23f07cf

57 files changed

Lines changed: 98764 additions & 189 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/ISSUE_TEMPLATE/qwen35_compatibility.yml‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
name: Qwen3.5 compatibility report
2+
description: Record a reproducible working, partial, or failing Qwen3.5 configuration.
3+
title: "[Qwen3.5] "
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
This form maps real compatibility; it does not certify output quality or production readiness. **Never paste access tokens, authentication files, private prompts, proprietary model data, or other secrets.** Use a short public or synthetic prompt.
9+
10+
- type: dropdown
11+
id: outcome
12+
attributes:
13+
label: Outcome
14+
options:
15+
- Works for the reported path
16+
- Partially works or gives incorrect behavior
17+
- Fails with an exception
18+
validations:
19+
required: true
20+
21+
- type: input
22+
id: recurquant_version
23+
attributes:
24+
label: RecurQuant version or commit
25+
placeholder: 0.2.0a1 or full commit hash
26+
validations:
27+
required: true
28+
29+
- type: input
30+
id: checkpoint
31+
attributes:
32+
label: Exact Qwen3.5 checkpoint and revision
33+
description: Include both the model ID and immutable revision hash.
34+
placeholder: Qwen/Qwen3.5-0.8B-Base @ dc7cdfe2ee4154fa7e30f5b51ca41bfa40174e68
35+
validations:
36+
required: true
37+
38+
- type: textarea
39+
id: environment
40+
attributes:
41+
label: Software and hardware
42+
placeholder: |
43+
OS: Windows 11
44+
Python: 3.11.x
45+
PyTorch: 2.x (include CUDA suffix)
46+
Transformers: 5.14.1
47+
Device: NVIDIA GPU model or CPU
48+
CUDA runtime and driver: version or not applicable
49+
render: shell
50+
validations:
51+
required: true
52+
53+
- type: textarea
54+
id: execution
55+
attributes:
56+
label: Execution configuration
57+
description: Report values even when the run succeeds.
58+
placeholder: |
59+
Dtype: bfloat16
60+
Attention implementation: eager
61+
Device map or placement: one CUDA device
62+
Batch size: 1
63+
Path: direct forward, greedy generation, beam search, etc.
64+
Prefill tokens: 32
65+
Decode or generated tokens: 32
66+
Cache: bits=4, group_size=128, rounding=nearest
67+
Layer overrides: none
68+
validations:
69+
required: true
70+
71+
- type: textarea
72+
id: reproducer
73+
attributes:
74+
label: Minimal public reproducer
75+
description: Use a public or synthetic prompt and include model loading, cache creation, and the failing or working call.
76+
render: python
77+
validations:
78+
required: true
79+
80+
- type: textarea
81+
id: result
82+
attributes:
83+
label: Result
84+
description: For a failure, include the complete traceback. For a working path, state exactly what completed; do not infer quality, speed, or memory improvements.
85+
render: shell
86+
validations:
87+
required: true
88+
89+
- type: textarea
90+
id: storage_summary
91+
attributes:
92+
label: Cache storage summary
93+
description: Paste `cache.storage_summary()` after at least one cache update when available.
94+
render: shell
95+
96+
- type: checkboxes
97+
id: disclosure
98+
attributes:
99+
label: Submission check
100+
options:
101+
- label: I used a public or synthetic prompt and removed secrets, access tokens, authentication files, private prompts, and proprietary data.
102+
required: true
103+
- label: I reported the exact checkpoint revision and did not turn a successful run into a quality, speed, peak-memory, or production-readiness claim.
104+
required: true

‎.github/ISSUE_TEMPLATE/reproducible_bug.yml‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
name: Reproducible bug
2+
description: Report a RecurQuant defect with enough detail to reproduce it.
3+
title: "[Bug] "
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for reducing the problem. **Do not include access tokens, authentication files, private prompts, proprietary model data, or other secrets.** Replace private inputs with a minimal public example before submitting.
9+
10+
- type: dropdown
11+
id: area
12+
attributes:
13+
label: Affected area
14+
options:
15+
- Packed cache integration
16+
- Quantization or byte accounting
17+
- Qwen3.5 factory or generation
18+
- CLI or packaging
19+
- Evaluation tooling
20+
- Other
21+
validations:
22+
required: true
23+
24+
- type: input
25+
id: recurquant_version
26+
attributes:
27+
label: RecurQuant version or commit
28+
description: Use `python -c "import recurquant; print(recurquant.__version__)"` or provide the full commit hash.
29+
placeholder: 0.2.0a1 or 0123456789abcdef...
30+
validations:
31+
required: true
32+
33+
- type: textarea
34+
id: environment
35+
attributes:
36+
label: Environment
37+
description: Include every line and replace only values that truly do not apply.
38+
placeholder: |
39+
OS: Windows 11
40+
Python: 3.11.x
41+
PyTorch: 2.x (include CUDA suffix)
42+
Transformers: 5.14.1
43+
Device: NVIDIA GPU model or CPU
44+
Dtype: bfloat16, float16, or float32
45+
Attention implementation: eager
46+
Batch size: 1
47+
Execution mode: direct forward, greedy generation, beam search, etc.
48+
validations:
49+
required: true
50+
51+
- type: textarea
52+
id: model
53+
attributes:
54+
label: Model and cache configuration
55+
description: Give the exact model ID, revision, cache bits, group size, rounding mode, and any layer overrides. Write `not applicable` for a model-independent bug.
56+
placeholder: |
57+
Model: Qwen/Qwen3.5-0.8B-Base
58+
Revision: dc7cdfe2ee4154fa7e30f5b51ca41bfa40174e68
59+
Cache: bits=4, group_size=128, rounding=nearest
60+
Layer overrides: none
61+
validations:
62+
required: true
63+
64+
- type: textarea
65+
id: reproducer
66+
attributes:
67+
label: Minimal reproducer
68+
description: Provide one self-contained example using public or synthetic input.
69+
render: python
70+
validations:
71+
required: true
72+
73+
- type: textarea
74+
id: observed
75+
attributes:
76+
label: Observed behavior and traceback
77+
description: Paste the complete traceback or exact incorrect output. Remove secrets and private paths where possible.
78+
render: shell
79+
validations:
80+
required: true
81+
82+
- type: textarea
83+
id: expected
84+
attributes:
85+
label: Expected behavior
86+
description: State the behavior you expected and why.
87+
validations:
88+
required: true
89+
90+
- type: textarea
91+
id: storage_summary
92+
attributes:
93+
label: Storage summary
94+
description: For packing or byte-accounting bugs, paste `cache.storage_summary()`. Otherwise write `not applicable`.
95+
render: shell
96+
97+
- type: checkboxes
98+
id: disclosure
99+
attributes:
100+
label: Submission check
101+
options:
102+
- label: I used a minimal public or synthetic input and removed secrets, access tokens, authentication files, private prompts, and proprietary data.
103+
required: true
104+
- label: I checked the current compatibility boundary and am not presenting an unsupported mode as validated.
105+
required: true

‎.github/workflows/ci.yml‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@ name: CI
22

33
on:
44
push:
5+
branches:
6+
- main
57
pull_request:
68

79
permissions:
@@ -13,15 +15,83 @@ jobs:
1315
timeout-minutes: 20
1416
steps:
1517
- uses: actions/checkout@v7.0.1
16-
- uses: actions/setup-python@v6
18+
- uses: actions/setup-python@v7.0.0
1719
with:
1820
python-version: "3.11"
1921
- uses: astral-sh/setup-uv@v9.0.0
2022
with:
2123
python-version: "3.11"
24+
version: "0.11.31"
2225
- name: Install
2326
run: uv pip install --system -e ".[dev]"
27+
- name: Verify frozen MBPP confirmation
28+
run: |
29+
recurquant verify-confirmation \
30+
evidence/mbpp-v02-confirmation.json \
31+
evidence/mbpp-v02-confirmation-manifest.json \
32+
--expect-artifact-sha256 70394c419298fc872cdd08e8aec12d17d5a56aa20f7d3c9f09fe8fdbf26c6ba9 \
33+
--expect-artifact-evidence-sha256 2a652df92f99fa81f785244d966829e909d31f200e5a1520b76e6b46fb45d3e0
2434
- name: Lint
2535
run: ruff check .
2636
- name: Test
2737
run: pytest
38+
- name: Check generated README assets
39+
run: python scripts/generate_readme_assets.py --check
40+
41+
package:
42+
name: Build wheel and sdist
43+
runs-on: ubuntu-latest
44+
timeout-minutes: 15
45+
steps:
46+
- uses: actions/checkout@v7.0.1
47+
- uses: actions/setup-python@v7.0.0
48+
with:
49+
python-version: "3.11"
50+
- uses: astral-sh/setup-uv@v9.0.0
51+
with:
52+
version: "0.11.31"
53+
- name: Build distributions
54+
run: uv build
55+
- name: Check distribution metadata
56+
run: uvx --from "twine==6.2.0" twine check --strict dist/*
57+
- uses: actions/upload-artifact@v7.0.1
58+
with:
59+
name: recurquant-dist
60+
path: dist/*
61+
if-no-files-found: error
62+
retention-days: 7
63+
64+
wheel-install:
65+
name: Wheel import / ${{ matrix.os }} / Python ${{ matrix.python-version }}
66+
needs: package
67+
runs-on: ${{ matrix.os }}
68+
timeout-minutes: 35
69+
strategy:
70+
fail-fast: false
71+
matrix:
72+
include:
73+
- os: ubuntu-latest
74+
python-version: "3.11"
75+
- os: ubuntu-latest
76+
python-version: "3.13"
77+
- os: windows-latest
78+
python-version: "3.11"
79+
steps:
80+
- uses: actions/setup-python@v7.0.0
81+
with:
82+
python-version: ${{ matrix.python-version }}
83+
- uses: actions/download-artifact@v8.0.1
84+
with:
85+
name: recurquant-dist
86+
path: dist
87+
- name: Install CPU PyTorch
88+
run: python -m pip install "torch>=2.7" --index-url https://download.pytorch.org/whl/cpu
89+
- name: Install the built wheel
90+
run: >-
91+
python -c "import pathlib, subprocess, sys;
92+
wheel = next(pathlib.Path('dist').glob('*.whl'));
93+
subprocess.check_call([sys.executable, '-m', 'pip', 'install', str(wheel)])"
94+
- name: Validate import and console entry point
95+
run: |
96+
python -c "import importlib.metadata as m, recurquant; assert m.version('recurquant') == recurquant.__version__ == '0.2.0a1'; print(recurquant.__version__)"
97+
recurquant demo --bits 4 --group-size 16

‎.gitleaks.toml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,11 @@ regexes = [
1111
'''"token_ids_sha256":\s*"[0-9a-f]{64}"''',
1212
'''"tokenizer_revision":\s*"[0-9a-f]{40}"''',
1313
]
14+
15+
[[allowlists]]
16+
description = "Prepared-manifest token ID digests"
17+
targetRules = ["generic-api-key"]
18+
regexTarget = "line"
19+
regexes = [
20+
'''"(?:code_token_ids_sha256|prompt_token_ids_sha256|token_manifest_sha256)"\s*:\s*"[0-9a-f]{64}"''',
21+
]

‎CHANGELOG.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Changelog
2+
3+
This file records user-visible package changes. RecurQuant is pre-release
4+
software, so compatibility can still change between development versions.
5+
6+
## [0.2.0a1] - 2026-07-22
7+
8+
### Added
9+
10+
- Physical INT4 nibble packing and INT8 payload storage for persistent Gated
11+
DeltaNet recurrent states, with grouped FP16 or FP32 scales.
12+
- `PackedRecurrentStateCache` for keeping recurrent states packed between layer
13+
calls, with opt-in evidence recording and exact resident-byte accounting.
14+
- A guarded Qwen3.5 cache factory, pinned Qwen3.5 quickstart, and compatibility
15+
checks for the tested Transformers release and eager, single-device
16+
inference path.
17+
- A reusable frozen v0.2 mixed-policy cache helper and an installed
18+
`recurquant qwen35` workflow shared with the source-tree quickstart. Uniform
19+
INT4 remains available only as an explicitly named stress baseline.
20+
- Machine-readable `recurquant qwen35 --json` output, a one-click Colab
21+
notebook, and a hash-anchored reproduction and extension guide.
22+
- Offline `recurquant verify-artifact` checks for strict JSON, whole-file
23+
SHA256 anchors, and canonical evidence hashes.
24+
- `recurquant verify-confirmation` independently checks the frozen MBPP
25+
manifest, artifact, quality gates, and optional raw checkpoint arrays. It
26+
distinguishes verified pass/fail outcomes from unanchored evidence.
27+
- Frozen MBPP calibration and development evaluation workflows with pinned
28+
dataset/model revisions, prepared token manifests, canonical evidence hashes,
29+
equal-byte baselines, and resumable per-task checkpoints.
30+
- Held-out confirmation evidence on all 500 frozen MBPP test tasks and 30,244
31+
teacher-forced reference-code tokens. The mixed layer-0 INT8 plus 17-layer
32+
INT4 layout reduced task-macro excess NLL by 72.75% relative to uniform INT4
33+
while using exactly 2,564,096 resident recurrent-state bytes; every
34+
preregistered quality gate passed.
35+
- A compressed release attachment containing the retained raw confirmation
36+
checkpoint for independent reconstruction of every reported gate.
37+
- Unit coverage for packing parity, byte accounting, cache integration, public
38+
data split discipline, and the supported Qwen3.5 factory path.
39+
40+
### Changed
41+
42+
- Scale-storage emulation now uses the declared physical FP16 or FP32 format;
43+
superseding diagnostic results retain the earlier record instead of rewriting
44+
it.
45+
- The Transformers dependency is pinned to exactly `5.14.1` while the alpha
46+
package depends on that release's internal linear-attention cache contract.
47+
- FP16 scale storage is identified as the evaluated default. FP32 scale storage
48+
remains supported for experiments but is not covered by full-model evidence.
49+
50+
### Fixed
51+
52+
- Beam-cache reordering now permutes packed INT4/INT8 payloads and scales
53+
directly instead of dequantizing and requantizing the recurrent state.
54+
55+
### Known limitations
56+
57+
- The current Python path materializes one recurrent state while its layer
58+
executes. It does not establish faster inference, lower whole-model memory,
59+
or lower peak CUDA memory.
60+
- Full-model evidence is currently limited to the pinned
61+
`Qwen/Qwen3.5-0.8B-Base` revision and the environment described in
62+
[docs/compatibility.md](docs/compatibility.md).
63+
- The held-out result is limited to teacher-forced likelihood on the pinned
64+
Qwen3.5 checkpoint and MBPP construction. It does not establish generated-code
65+
correctness, novelty, cross-model generality, or a breakthrough.

‎CITATION.cff‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
cff-version: 1.2.0
2+
message: "If you use RecurQuant, cite this software repository."
3+
title: RecurQuant
4+
type: software
5+
authors:
6+
- name: "Muhammad Labeeb Aryan"
7+
version: 0.2.0a1
8+
date-released: 2026-07-22
9+
repository-code: "https://github.com/Labeeb2339/recurquant"
10+
url: "https://github.com/Labeeb2339/recurquant"
11+
license: Apache-2.0

0 commit comments

Comments
 (0)