Skip to content

Commit 708bd71

Browse files
Labeeb2339Labeeb2339
committed
chore: add contributor and issue workflows
1 parent d37aead commit 708bd71

5 files changed

Lines changed: 325 additions & 0 deletions

File tree

‎.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.0.dev0 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.0.dev0 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

‎CHANGELOG.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
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.0.dev0] - Unreleased alpha
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 minor release and eager, single-device
16+
inference path.
17+
- Frozen MBPP calibration and development evaluation workflows with pinned
18+
dataset/model revisions, prepared token manifests, canonical evidence hashes,
19+
equal-byte baselines, and resumable per-task checkpoints.
20+
- Unit coverage for packing parity, byte accounting, cache integration, public
21+
data split discipline, and the supported Qwen3.5 factory path.
22+
23+
### Changed
24+
25+
- Scale-storage emulation now uses the declared physical FP16 or FP32 format;
26+
superseding diagnostic results retain the earlier record instead of rewriting
27+
it.
28+
- The Transformers dependency is constrained to `>=5.14.1,<5.15` while the
29+
package depends on that minor release's internal linear-attention cache
30+
contract.
31+
32+
### Known limitations
33+
34+
- The current Python path materializes one recurrent state while its layer
35+
executes. It does not establish faster inference, lower whole-model memory,
36+
or lower peak CUDA memory.
37+
- Full-model evidence is currently limited to the pinned
38+
`Qwen/Qwen3.5-0.8B-Base` revision and the environment described in
39+
[docs/compatibility.md](docs/compatibility.md).
40+
- The MBPP confirmation manifest is frozen, but this entry makes no held-out
41+
confirmation or generated-code-correctness claim.

‎CITATION.cff‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
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.0.dev0
8+
repository-code: "https://github.com/Labeeb2339/recurquant"
9+
url: "https://github.com/Labeeb2339/recurquant"
10+
license: Apache-2.0

‎CONTRIBUTING.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Contributing to RecurQuant
2+
3+
RecurQuant is an alpha research package with a deliberately narrow supported
4+
surface. Contributions are most useful when they include a small reproducer, a
5+
regression test, and an explicit statement of what the result does **not** show.
6+
7+
## Set up and check a change
8+
9+
The repository baseline is Python 3.11. On Windows, the same setup used by the
10+
project is:
11+
12+
```powershell
13+
uv venv --python 3.11 .venv
14+
uv pip install --python .venv\Scripts\python.exe -e ".[dev,eval]"
15+
.venv\Scripts\python.exe -m pytest
16+
.venv\Scripts\python.exe -m ruff check .
17+
```
18+
19+
On Linux or macOS, replace `.venv\Scripts\python.exe` with
20+
`.venv/bin/python` in the last three commands.
21+
22+
The full-model experiments are separate from the unit suite and download public
23+
model weights. Do not run them merely to validate a small code change. If a
24+
change affects Qwen3.5 integration, also run the smallest relevant smoke path
25+
documented in [compatibility and support](docs/compatibility.md), and report the
26+
exact model revision, device, dtype, attention implementation, and Transformers
27+
version.
28+
29+
Before submitting a change:
30+
31+
- add or update a focused test for changed behavior;
32+
- run the complete unit suite and Ruff command above;
33+
- keep generated evidence separate from hand-written interpretation; and
34+
- do not include access tokens, authentication files, private prompts,
35+
proprietary model data, or local machine secrets in code, logs, artifacts, or
36+
issues.
37+
38+
## Evidence and claim boundary
39+
40+
Use the terminology in [the project claim boundary](research/CLAIM_BOUNDARY.md).
41+
In particular:
42+
43+
- report packed **resident recurrent-state bytes** separately from model
44+
weights, attention KV caches, activations, allocator overhead, and the one
45+
state materialized during a layer call;
46+
- do not turn byte accounting into a speed, latency, peak-CUDA-memory, or
47+
whole-model-memory claim;
48+
- do not describe recurrent-state quantization itself as new, and do not call a
49+
result a breakthrough from a diagnostic trace or a development split;
50+
- attach the command, pinned revisions, environment, metric definition, and
51+
machine-readable artifact for a new numerical claim; and
52+
- preserve failed gates and negative results instead of silently replacing
53+
them.
54+
55+
The current supported package boundary is recorded in
56+
[docs/compatibility.md](docs/compatibility.md). A new model, Transformers minor
57+
release, execution backend, generation mode, or hardware target is unsupported
58+
until it has a regression test and clearly scoped full-model evidence.
59+
60+
## Keep pull requests reviewable
61+
62+
Keep each change to one testable behavior. In the description, state the
63+
problem, the exact verification commands, any new evidence file, and the claim
64+
boundary affected. Documentation-only corrections should identify the source
65+
artifact or code path that makes the replacement wording factual.

0 commit comments

Comments
 (0)