# Entropy-Adaptive State Quantization (EASQ)
A lightweight, dependency-free implementation of an adaptive state quantization engine. This module monitors the entropy (information density) of a data stream and dynamically adjusts the bit-depth of stored states.
## Concept
Traditional quantization uses a fixed bit-width (e.g., float32). EASQ proposes that "simple" or "redundant" states do not require high precision. By calculating the Shannon entropy of incoming data windows, the system automatically scales the quantization resolution.
- **High Entropy** (Chaos/Noise) -> High Precision (e.g., 8-12 bits)
- **Low Entropy** (Silence/Constancy) -> Low Precision (e.g., 1-2 bits)
## Requirements
- Python 3.8+
- Standard Library only (no `numpy` or `pandas`)
## Usage
```python
from entropy_adaptive_state_quantization import EASQProcessor
# Initialize with a precision range [min_bits, max_bits]
processor = EASQProcessor(min_bits=1, max_bits=12)
# Simulate a stream of data
data_stream = [0.1, 0.1, 0.1, 0.5, 0.9, 0.1, 1.0, 0.0]
for value in data_stream:
processor.add_sample(value)
if processor.is_window_full():
# Returns the compressed representation and metadata
result = processor.process_window()
print(f"Entropy: {result['entropy']:.2f} | Bits: {result['bits_used']}")
```
## Limitations
This implementation uses a histogram-based estimator for Shannon entropy. It is optimized for demonstration and does not currently implement GPU acceleration or persistent storage protocols.
<!-- ARES_AUTO_VERIFIED_SUMMARY:START -->
## Verified Project Notes
- Package import path: `entropy_adaptive_state_quantization`
- Entrypoint: `run_demo.py`
- Delivery mode: `prototype`
- Release tier: `prototype`
- Verification status: `PASS`
- Clean-room release gates: `NOT_RUN`
- Public exports: `EASQProcessor`
- Python files detected: `run_demo.py, entropy_adaptive_state_quantization/__init__.py, entropy_adaptive_state_quantization/core.py, entropy_adaptive_state_quantization/utils.py`
## Verification Commands
- `PASS` `"/home/corbybender/ares/.venv-linux/bin/python" -m py_compile "run_demo.py"`
- `PASS` `"/home/corbybender/ares/.venv-linux/bin/python" -m compileall "entropy_adaptive_state_quantization"`
- `PASS` `"/home/corbybender/ares/.venv-linux/bin/python" run_demo.py`
## Current Limits
- No additional consistency warnings were detected by the local audit.
<!-- ARES_AUTO_VERIFIED_SUMMARY:END -->
| Path | Bytes |
|---|---|
| __pycache__/run_demo.cpython-314.pyc | 2720 |
| DESIGN_BRIEF.md | 791 |
| entropy_adaptive_state_quantization/__init__.py | 255 |
| entropy_adaptive_state_quantization/__pycache__/__init__.cpython-314.pyc | 500 |
| entropy_adaptive_state_quantization/__pycache__/core.cpython-314.pyc | 6377 |
| entropy_adaptive_state_quantization/__pycache__/utils.cpython-314.pyc | 1464 |
| entropy_adaptive_state_quantization/core.py | 3895 |
| entropy_adaptive_state_quantization/utils.py | 784 |
| invention.json | 3123 |
| pyproject.toml | 430 |
| README.md | 2463 |
| run_demo.py | 2165 |
{
"id": "entropy-adaptive-state-quantization",
"title": "Entropy-Adaptive State Quantization",
"summary": "A Python implementation of a state management system that dynamically adjusts quantization precision based on the information entropy of the data stream. It reduces precision for low-entropy (redundant) states to save resources and increases precision for high-entropy (complex) states to maintain fidelity.",
"source": "student_autonomy",
"kind": "invention",
"path": "inventions/entropy-adaptive-state-quantization",
"delivery_mode": "prototype",
"release_tier": "prototype",
"release_verification_status": "not_run",
"created_at": "2026-03-29 07:56:16",
"updated_at": "2026-03-29 07:56:46",
"project_entrypoint": "run_demo.py",
"smoke_test_status": "passed",
"smoke_test_output": "--- Entropy-Adaptive State Quantization Demo --- Window | Entropy | Bits | Error (MSE) -------|---------|------|------------- 9 | 0.00 | 1 | 0.000000 19 | 0.00 | 1 | 0.000000 29 | 0.00 | 1 | 0.000000 39 | 2.65 | 12 | 0.000000 49 | 2.85 | 13 | 0.000000 59 | 2.17 | 10 | 0.000000 69 | 2.72 | 13 | 0.000000 79 | 2.45 | 12 | 0.000000 89 | 2.72 | 13 | 0.000000 99 | 2.32 | 11 | 0.000001 --- Summary --- Average Reconstruction Error: 0.000000 Demonstration complete. INVENTION_SMOKE_TEST: PASS",
"generated_files": 6,
"project_generated_at": "2026-03-29 07:56:44",
"source_exp_path": "experiments\\exp_self.20260308180140.015_20260308_180204",
"verification_status": "passed",
"verification_results": [
{
"command": "\"/home/corbybender/ares/.venv-linux/bin/python\" -m py_compile \"run_demo.py\"",
"passed": true,
"returncode": 0,
"timed_out": false,
"stdout_excerpt": "",
"stderr_excerpt": ""
},
{
"command": "\"/home/corbybender/ares/.venv-linux/bin/python\" -m compileall \"entropy_adaptive_state_quantization\"",
"passed": true,
"returncode": 0,
"timed_out": false,
"stdout_excerpt": "Listing 'entropy_adaptive_state_quantization'...",
"stderr_excerpt": ""
},
{
"command": "\"/home/corbybender/ares/.venv-linux/bin/python\" run_demo.py",
"passed": true,
"returncode": 0,
"timed_out": false,
"stdout_excerpt": "--- Entropy-Adaptive State Quantization Demo ---\nWindow | Entropy | Bits | Error (MSE)\n-------|---------|------|-------------\n 9 | 0.00 | 1 | 0.000000\n 19 | 0.00 | 1 | 0.000000\n 29 | 0.00 | 1 | 0.000000\n 39 | 2.65 | 12 | 0.000000\n 49 | 2.85 | 13 | 0.000000\n 59 | 2.17 | 10 | 0.000000\n 69 | 2.72 | 13 | 0.000000\n 79 | 2.45 | 12 | 0.000000\n 89 | 2.92 | 14 | 0.000000\n 99 | 2.25 | 11 | 0.000001\n\n--- Summary ---\nAverage Reconstruction Error: 0.000000\nDemonstration complete.\nINVENTION_SMOKE_TEST: PASS",
"stderr_excerpt": ""
}
],
"project_status": "built"
}