# Sparse Associative State Injection (SASI)
## Overview
Sparse Associative State Injection (SASI) is a technique for managing state in high-dimensional vector spaces. By maintaining a sparse representation of state, we can inject associative context into a running process with minimal interference to the existing state structure.
This package provides a pure-Python, dependency-free implementation of the SASI mechanism.
## Installation
No external dependencies are required. Python 3.8+ is recommended.
```bash
pip install -e .
```
## Usage
The core concept involves creating a sparse state context and injecting signals into it.
```python
import random
from sparse_associative_state_injection_sasi import VectorFactory, SASIContext
# 1. Initialize the context and Factory
factory = VectorFactory(dimensions=128)
ctx = SASIContext(dimensions=128, sparsity=0.1)
# 2. Create associative memory patterns
key_a = factory.create_sparse_vector(label="key_a")
val_a = factory.create_sparse_vector(label="val_a")
ctx.associate(key_a, val_a)
# 3. Inject state based on a query signal
query = factory.create_dense_vector(seed=42)
result = ctx.inject(query)
print(f"Active nodes: {sum(1 for x in result if x > 0)}")
```
## Implementation Details
* **Sparse Pruning**: The system enforces sparsity by only retaining the top-k activation magnitudes after each injection step. This mimics the biological principle of inhibition of return.
* **Associative Retrieval**: State is not just added; it is retrieved based on the cosine similarity of the input signal to stored keys.
* **Limitations**: This implementation uses Python lists and standard math libraries. It is intended for algorithmic demonstration and small-scale local processing. It is not optimized for GPU or large-scale matrix operations found in deep learning frameworks.
<!-- ARES_AUTO_VERIFIED_SUMMARY:START -->
## Verified Project Notes
- Package import path: `sparse_associative_state_injection_sasi`
- Entrypoint: `run_demo.py`
- Delivery mode: `prototype`
- Release tier: `prototype`
- Verification status: `PASS`
- Clean-room release gates: `NOT_RUN`
- Public exports: `SASIContext, VectorFactory, cosine_similarity, sparsify_vector`
- Python files detected: `run_demo.py, sparse_associative_state_injection_sasi/__init__.py, sparse_associative_state_injection_sasi/core.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 "sparse_associative_state_injection_sasi"`
- `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 | 4123 |
| DESIGN_BRIEF.md | 809 |
| invention.json | 3149 |
| pyproject.toml | 569 |
| README.md | 2790 |
| run_demo.py | 2644 |
| sparse_associative_state_injection_sasi/__init__.py | 362 |
| sparse_associative_state_injection_sasi/__pycache__/__init__.cpython-314.pyc | 550 |
| sparse_associative_state_injection_sasi/__pycache__/core.cpython-314.pyc | 9023 |
| sparse_associative_state_injection_sasi/core.py | 4924 |
{
"id": "sparse-associative-state-injection-sasi",
"title": "Sparse Associative State Injection (SASI)",
"summary": "A lightweight, dependency-free Python implementation of a sparse state machine. SASI allows for the injection of high-dimensional sparse vectors into a persistent state context, utilizing associative memory retrieval to update state based on similarity rather than direct address.",
"source": "student_autonomy",
"kind": "invention",
"path": "inventions/sparse-associative-state-injection-sasi",
"delivery_mode": "prototype",
"release_tier": "prototype",
"release_verification_status": "not_run",
"created_at": "2026-03-29 07:54:42",
"updated_at": "2026-03-29 07:55:14",
"project_entrypoint": "run_demo.py",
"smoke_test_status": "passed",
"smoke_test_output": "--- SASI (Sparse Associative State Injection) Demo --- Initializing Local AI Tooling... Config: Dimensions=256, Sparsity=0.05 1. Generating Sparse Concepts (Memory Initialization)... Key Vector: Active=25, Mag=4.7765 Val Vector: Active=25, Mag=4.7282 2. Binding Key -> Value in Associative Memory... 3. Injecting Noise Signal... State after Noise: Active=12, Mag=3.3804 4. Injecting 'Key' Signal (Triggering Association)... State after Key: Active=12, Mag=3.9741 State Change: 3.3804 -> 3.9741 SUCCES",
"generated_files": 5,
"project_generated_at": "2026-03-29 07:55:12",
"source_exp_path": "experiments\\exp_self.20260308175629.013_20260308_175701",
"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 \"sparse_associative_state_injection_sasi\"",
"passed": true,
"returncode": 0,
"timed_out": false,
"stdout_excerpt": "Listing 'sparse_associative_state_injection_sasi'...",
"stderr_excerpt": ""
},
{
"command": "\"/home/corbybender/ares/.venv-linux/bin/python\" run_demo.py",
"passed": true,
"returncode": 0,
"timed_out": false,
"stdout_excerpt": "--- SASI (Sparse Associative State Injection) Demo ---\nInitializing Local AI Tooling...\nConfig: Dimensions=256, Sparsity=0.05\n\n1. Generating Sparse Concepts (Memory Initialization)...\n Key Vector: Active=25, Mag=4.6617\n Val Vector: Active=25, Mag=4.8055\n\n2. Binding Key -> Value in Associative Memory...\n\n3. Injecting Noise Signal...\n State after Noise: Active=12, Mag=3.3804\n\n4. Injecting 'Key' Signal (Triggering Association)...\n State after Key: Active=12, Mag=3.9804\n\nState Change: 3.3804 -> 3.9804\nSUCCESS: Associative injection resulted in state enrichment.\n\n--- Demo Complete ---\nINVENTION_SMOKE_TEST: PASS",
"stderr_excerpt": ""
}
],
"project_status": "built"
}