Metadata-Version: 2.4
Name: catalyst-brain
Version: 1.3.4
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
License-File: LICENSE
Summary: Catalyst Brain: O(1) Holographic Key-Value Cache, Quantum Attention, and Metacognitive Engine.
License-Expression: LicenseRef-Research-Eval
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

<div align="center">
  <h1>Catalyst Brain SDK</h1>
  <p><b>O(1) Holographic Memory, Grover-Amplified Attention, and Metacognitive Self-Improvement</b></p>
  <p>
    <a href="https://pypi.org/project/catalyst-brain/">
      <img src="https://img.shields.io/badge/PyPI-v1.3.4-blue" alt="PyPI">
    </a>
    <a href="https://pypi.org/project/catalyst-brain/">
      <img src="https://img.shields.io/badge/Python-3.9%2B-blue" alt="Python">
    </a>
    <img src="https://img.shields.io/badge/Rust-1.75+-orange" alt="Rust">
    <img src="https://img.shields.io/badge/SDK-Closed_Source-black" alt="Closed Source SDK">
    <img src="https://img.shields.io/badge/Pricing-Freemium-green" alt="Freemium">
    <img src="https://img.shields.io/badge/PyPI_Downloads-1.7k%2B_direct%20%2F%205k%2B_total-purple" alt="1.7k+ direct PyPI downloads and 5k+ total downloads">
  </p>
</div>

---

**catalyst-brain** is a closed-source, freemium Rust+PyO3 SDK providing
hyperdimensional computing (HDC) primitives for AI systems. It ships through
PyPI as a monetized SDK: free for research, evaluation, personal
experimentation, and benchmarking; commercial use requires a paid license.

PyPI Stats reports **1,700+ direct downloads** and **5,000+ total downloads
including mirrors** in the SDK's first month, so the documentation is written
for real users building with the package today.

Install from PyPI:

```bash
pip install --upgrade catalyst-brain
```

Then import the SDK:

```python
import catalyst_hdc as hdc

# Core HDC primitives
a = hdc.rand_bipolar(4096)
b = hdc.rand_bipolar(4096)
score = hdc.resonance(a, b)     # → ~0.5 for quasi-orthogonal vectors
bound = hdc.hdc_bind(a, b)      # XOR-like binding (self-inverse)
bundled = hdc.hdc_bundle(a, b)  # majority-vote superposition
shifted = hdc.hdc_permute(a, 3) # circular shift

# O(1) cognitive memory
from catalyst_hdc import PyHoloCPUScheduler
cpu = PyHoloCPUScheduler(dim=4096, quantum_capacity=8)
cpu.store_memory("user_pref_dark_mode")
assert cpu.recall("user_pref_dark_mode") == True
cpu.process_feedback(0.95)
print(cpu.feedback_strength())  # → 0.95
```

---

## Distribution Model

catalyst-brain is a product SDK, not an open-source project.

| Tier | Intended use | Notes |
|---|---|---|
| Free / evaluation | Research, learning, benchmarks, prototypes, non-commercial exploration | Available from PyPI |
| Commercial | Production systems, SaaS, hosted APIs, revenue-generating workflows | Requires a commercial license |
| Enterprise | Source access, private support, custom terms, deployment assistance | By agreement |

The public PyPI package is the supported distribution path. Redistribution,
production deployment, hosted API use, and derivative implementations of the
patented methods require commercial permission.

Contact: hello@strategic-innovations.ai

---

## User Commitment

The SDK is already being used by a growing base of early adopters. We treat
free-tier users as real users, not throwaway traffic.

- Keep `pip install catalyst-brain` as the primary onboarding path.
- Preserve documented import paths and method signatures across patch releases.
- Document breaking changes in `CHANGELOG.md` before users hit them.
- Ship Python type stubs with the wheel so IDEs and CI can catch mistakes early.
- Keep telemetry anonymous, opt-out, and free of user data, vectors, labels, or
  model outputs.
- Make commercial boundaries explicit so teams can prototype freely and upgrade
  before production, hosted API use, or revenue-generating deployment.

---

## SDK Reference

### Core HDC Primitives

Raw hypervector algebra. All other SDK classes are built on these.

| Function | Signature | Description |
|---|---|---|
| `rand_bipolar` | `(dim: int) → list[float]` | Random `{−1, +1}` hypervector |
| `resonance` | `(a, b) → float` | Cosine similarity normalized to [0, 1] |
| `hdc_bind` | `(a, b) → list[float]` | XOR-like binding (self-inverse: `bind(bind(a,b),b) == a`) |
| `hdc_bundle` | `(a, b) → list[float]` | Majority-vote superposition |
| `hdc_permute` | `(v, n) → list[float]` | Circular shift by `n` positions |
| `normalise_bipolar` | `(v) → list[float]` | Normalize to bipolar range |

```python
a = hdc.rand_bipolar(4096)
b = hdc.rand_bipolar(4096)

# Self-inverse binding (XOR)
assert hdc.resonance(a, b) > 0.4          # quasi-orthogonal
bound = hdc.hdc_bind(a, b)
recovered = hdc.hdc_bind(bound, b)
assert hdc.resonance(a, recovered) > 0.99  # a ⊕ (a ⊕ b) = b (bit-exact)

# Bundle N vectors using reduce
from functools import reduce
vectors = [hdc.rand_bipolar(4096) for _ in range(4)]
superposition = reduce(hdc.hdc_bundle, vectors)
```

---

### HoloCPU SDK — Cognitive Compute Engine

O(1) semantic memory with Grover-amplified attention routing.

```python
from catalyst_hdc import PyHoloCPUScheduler
import catalyst_hdc as hdc

cpu = PyHoloCPUScheduler(dim=4096, quantum_capacity=8)
```

#### Memory

```python
# Store and recall — O(1) regardless of how many memories exist
cpu.store_memory("user_preference_dark_mode")
cpu.store_memory("last_query")

assert cpu.recall("user_preference_dark_mode") == True
assert cpu.recall("nonexistent_key") == False

# Export entire cognitive state as a single 4096-float hypervector (16 KB constant)
state = cpu.export_holographic_state()
assert len(state) == 4096  # always 16 KB
```

#### Outcome Feedback

```python
# Signal quality of an inference result (0.0 = bad, 1.0 = perfect)
cpu.process_feedback(0.95)   # positive outcome
print(cpu.feedback_strength())  # → 0.95 (elevated from baseline 0.5)

cpu.process_feedback(0.1)    # negative outcome
print(cpu.feedback_strength())  # → drops toward baseline
```

#### Grover-Amplified Attention

```python
# quantum_grover_search takes a hypervector query + lists of key/value hypervectors
query = hdc.rand_bipolar(4096)
keys  = [hdc.rand_bipolar(4096) for _ in range(8)]
values = [hdc.rand_bipolar(4096) for _ in range(8)]

output = cpu.quantum_grover_search(query, keys, values)
# Returns a 4096-dim output vector from Grover-amplified routing
assert len(output) == 4096
```

#### Role Vectors

```python
# Generate orthogonal role hypervectors for structured binding
agent   = cpu.generate_role("agent")
user    = cpu.generate_role("user")
system  = cpu.generate_role("system")

# Use for structured message encoding: message = bind(content, agent_role)
```

#### API Reference

| Method | Signature | Description |
|---|---|---|
| `dimension()` | `→ int` | Hypervector dimensionality |
| `quantum_capacity()` | `→ int` | Qubit depth |
| `store_memory(key)` | `(str) → None` | Encode and store a semantic key |
| `recall(key)` | `(str) → bool` | O(1) key existence check |
| `export_holographic_state()` | `→ list[float]` | Full state as 4096 floats (16 KB) |
| `process_feedback(signal)` | `(float) → None` | Outcome feedback signal (0.0–1.0) |
| `feedback_strength()` | `→ float` | Current feedback strength |
| `quantum_grover_search(query, keys, values)` | `(Vec, list[Vec], list[Vec]) → list[float]` | Grover attention |
| `run_audit_integrity_check()` | `→ bool` | System health check |
| `generate_role(label)` | `(str) → list[float]` | Orthogonal role vector |

---

### HoloGen SDK — Geometric Hypervector Engine

Encode 3D geometry, materials, and photon states directly into hypervector space.

```python
from catalyst_hdc import PyHoloGenEngine

engine = PyHoloGenEngine(dim=10_000)
```

#### Pixel Geometry

```python
# Map screen coordinates to hypervector addresses
pixel_hv = engine.generate_pixel_geometry(64, 64)
# → list[int8], quasi-orthogonal per unique (x, y) pair

pixel_a = engine.generate_pixel_geometry(100, 200)
pixel_b = engine.generate_pixel_geometry(100, 201)  # adjacent pixel
# pixel_a and pixel_b are quasi-orthogonal — no hash collisions
```

#### Surface Materials

```python
# A metallic surface at position (10, 0, 5) facing upward
surface_hv = engine.generate_material_mapping(
    position=[10.0, 0.0, 5.0],  # [f32; 3]
    normal=[0.0, 1.0, 0.0],     # surface normal [f32; 3]
    material_id=42
)
```

#### Photon State

```python
# Form 1: encode photon color as a semantic hypervector
photon_hv = engine.generate_photon("blue")
# Supported: "violet"/"purple", "blue", "cyan", "green", "yellow",
# "amber"/"orange", "red", "white".

# Form 2: full geometric form
photon_hv = engine.generate_photon(
    [0.0, 5.0, 0.0],   # position [f32; 3]
    [1.0, 0.0, 0.0],   # direction [f32; 3]
    480.0,             # wavelength (nm)
)
```

#### BVH Nodes

```python
# encode_bvh_node(min_bounds, max_bounds, left_hv, right_hv)
# left_hv and right_hv must be bipolar hypervectors as list[int8]
# Convert: [int(x) for x in hdc.rand_bipolar(dim)]

left_hv  = [int(x) for x in hdc.rand_bipolar(4096)]
right_hv = [int(x) for x in hdc.rand_bipolar(4096)]

bvh_node = engine.encode_bvh_node(
    [0.0, -10.0, 0.0],   # min_bounds [f32; 3]
    [10.0, 10.0, 10.0],  # max_bounds [f32; 3]
    left_hv,
    right_hv,
)
```

#### Counterfactual Physics

```python
# Ask "what if this photon took a different path?"
# Inputs may be either bipolar i8 hypervectors or any object that stringifies
# (the latter is hashed deterministically into a hypervector of dim D).
actual_state = "jump→reward"
intervention = "crouch→reward"

alt_reality = engine.simulate_counterfactual(actual_state, intervention)
# Returns hypervector encoding hypothetical deviation (list[int8] of length D)
```

#### API Reference

| Method | Signature | Description |
|---|---|---|
| `structural_dimension()` | `→ int` | Hypervector dimensionality |
| `generate_pixel_geometry(x, y, frame_id=None)` | `(u32, u32, Optional[u64]) → list[int8]` | Pixel coords → HDC address. `frame_id` defaults to 0. |
| `generate_material_mapping(position, normal, material_id)` | `([f32;3], [f32;3], u32) → list[int8]` | Surface → HDC |
| `generate_photon(color)` | `(str) → list[int8]` | Color string → HDC. Also accepts `(position, direction, wavelength)` as the geometric form. |
| `encode_bvh_node(min_bounds, max_bounds, left_hv, right_hv)` | `([f32;3], [f32;3], Vec<i8>, Vec<i8>) → list[int8]` | BVH node |
| `simulate_counterfactual(state, intervention)` | `(Any, Any) → list[int8]` | Counterfactual physics. Args are either bipolar i8 vectors or any stringifiable object (hashed to a vector). |

---

### Metacognition & Self-Audit

Self-improvement loop: observe → recommend → apply → audit.

```python
from catalyst_hdc import PyMetacognition, PyOptimizer, PySelfAudit
import catalyst_hdc as hdc

meta = PyMetacognition(dim=4096)
```

#### Record Observations

```python
# Record inference outcomes with resonance, coherence, accuracy
hv = hdc.rand_bipolar(4096)
meta.record(res=0.85, coh=0.90, acc=0.75, context=hv, hash=12345)
meta.record(res=0.92, coh=0.88, acc=0.81, context=hv, hash=12346)
meta.record(res=0.61, coh=0.72, acc=0.55, context=hv, hash=12347)
```

#### Query State

```python
print(f"success_rate:  {meta.success_rate():.3f}")   # ratio of high-resonance successes
print(f"avg_resonance: {meta.avg_resonance():.3f}")  # mean resonance score
recs = meta.recommend()
# → [("momentum_increase", 0.05, "success rate > 80%, reinforce"), ...]
```

#### Apply Recommendations

```python
opt = PyOptimizer()
opt.apply("momentum_increase", 0.05, "success rate above 80%")
params = opt.get_params()
# → {"learning_rate": 0.6, "momentum": 0.5, "attention_weight": 0.55, "identity_lr": 0.01}
opt.rollback()  # revert last parameter change
```

#### Audit Integrity

```python
audit = PySelfAudit(dim=4096)
hv = hdc.rand_bipolar(4096)
score, passed, issues = audit.full_audit(hv)
# → score=1.0, passed=True, issues=[]
```

#### API Reference

| Class | Method | Signature | Description |
|---|---|---|---|
| `PyMetacognition` | `record(res, coh, acc, context, hash)` | `(float, float, float, Vec, u64)` | Log observation |
| `PyMetacognition` | `success_rate()` | `→ float` | Ratio of high-res successes |
| `PyMetacognition` | `avg_resonance()` | `→ float` | Mean resonance |
| `PyMetacognition` | `recommend()` | `→ list[tuple]` | Parameter recommendations |
| `PyOptimizer` | `apply(action, delta, reason)` | `(str, float, str)` | Apply parameter delta |
| `PyOptimizer` | `get_params()` | `→ dict` | Current parameters |
| `PyOptimizer` | `rollback()` | `→ None` | Revert last change |
| `PySelfAudit` | `full_audit(hv)` | `(Vec) → (float, bool, list)` | Integrity check |

---

### Quantum Attention Head

Drop-in replacement for standard softmax attention using Grover-amplified routing.

```python
from catalyst_hdc import PyQuantumAttentionHead
import catalyst_hdc as hdc

head = PyQuantumAttentionHead(dim=512, nqubits=40)

query  = hdc.rand_bipolar(512)
keys   = [hdc.rand_bipolar(512) for _ in range(10)]
values = [hdc.rand_bipolar(512) for _ in range(10)]

output = head.compute(query, keys, values)
# Returns 512-dim output vector
```

| Method | Signature | Description |
|---|---|---|
| `compute(query, keys, values)` | `(Vec, list[Vec], list[Vec]) → list[float]` | Grover attention |

> **Note:** `amplify()` does not exist as a standalone method. Grover amplification for large memory stores is implemented inside `PyHoloCPUScheduler.quantum_grover_search()`. `PyQuantumAttentionHead` is for fine-grained per-layer attention.

---

### HoloSwarm — Multi-Agent Spectral Synthesis

Superpose an arbitrary number of agents (Role ⊗ Policy ⊗ Skill) into a single hypervector and tune into any one of them at query time via iterative resonance decomposition.

```python
from catalyst_hdc import PyHoloSwarm
import catalyst_hdc as hdc

swarm = PyHoloSwarm(dim=4096)

# Register agents — each compound is permuted before bundling
# to de-correlate overlapping roles.
swarm.add_agent(
    role="planner",   r_hv=hdc.rand_bipolar(4096),
    policy="explore", p_hv=hdc.rand_bipolar(4096),
    skill="search",   s_hv=hdc.rand_bipolar(4096),
)
swarm.add_agent(
    role="executor",  r_hv=hdc.rand_bipolar(4096),
    policy="exploit", p_hv=hdc.rand_bipolar(4096),
    skill="tool_use", s_hv=hdc.rand_bipolar(4096),
)

# Decompose: given a role key, recover policy + skill via iterative unbinding
role, policy, skill, confidence = swarm.resonate(
    role_key="planner",
    p_guess=hdc.rand_bipolar(4096),
    s_guess=hdc.rand_bipolar(4096),
    max_iter=10,
)

# Probe which agents are active in a semantic sector
active = swarm.materialize(probe=hdc.rand_bipolar(4096), threshold=0.6)
# → [("planner", 0.73), ...]
```

| Method | Signature | Description |
|---|---|---|
| `add_agent(role, r_hv, policy, p_hv, skill, s_hv)` | `(str, Vec, str, Vec, str, Vec) → None` | Superpose Role ⊗ Policy ⊗ Skill into swarm |
| `add_paradox_trap(names, roles, keys)` | `(list[str], list[Vec], list[Vec]) → None` | Recursive causal-loop trap (HoloSec) |
| `resonate(role_key, p_guess, s_guess, max_iter)` | `→ tuple[str,str,str,float]` | Decompose swarm into (role, policy, skill, confidence) |
| `materialize(probe, threshold)` | `(Vec, float) → list[tuple[str,float]]` | Find agents resonating above threshold |
| `get_swarm_vector()` | `→ list[float]` | Raw composite hypervector |

---

### PyHKVC — Holographic Key-Value Cache

O(1) recency-unbiased KV cache using complex-domain phase accumulation. All entries contribute equal representational weight regardless of insertion order — no recency bias.

```python
from catalyst_hdc import PyHKVC

cache = PyHKVC(dim=1024)

# Store key-value pairs at sequence positions
cache.store("question:capital_france", "Paris", position=0)
cache.store("question:capital_japan",  "Tokyo", position=1)
cache.store("question:capital_uk",     "London", position=2)

# O(1) retrieval: HashMap lookup → phase-domain resonance
value, score = cache.query("question:capital_france")
# → ("Paris", 0.94)

print(cache.count())  # → 3
```

| Method | Signature | Description |
|---|---|---|
| `store(key, value, position)` | `(str, str, int) → None` | Insert key-value at position |
| `query(query_key)` | `(str) → tuple[str, float]` | Retrieve (value, confidence) |
| `count()` | `→ int` | Number of stored entries |
| `position_score(position)` | `(int) → float` | Recency-bias diagnostic (should be ≈constant) |
| `accumulator_magnitude()` | `→ list[float]` | Raw complex accumulator magnitudes |

---

### CausalMemory & MultiHopReasoner

Store causal relationships as hypervector triples and query them holographically.

```python
from catalyst_hdc import PyCausalMemory, PyMultiHopReasoner
import catalyst_hdc as hdc

# CausalMemory: cause → effect temporal chains
mem = PyCausalMemory(dim=4096)

t0 = hdc.rand_bipolar(4096)   # time-role HV
cause  = hdc.rand_bipolar(4096)
effect = hdc.rand_bipolar(4096)

mem.store(cause, effect, t0)

recovered_effect = mem.recall_effect(cause)   # → list[float] or None
recovered_causes = mem.recall_cause(effect)   # → list[list[float]]
by_time          = mem.recall_by_time(t0)     # → list[float] or None
```

```python
# MultiHopReasoner: traverse fact graphs up to N hops
reasoner = PyMultiHopReasoner(dim=4096)

f0 = reasoner.add_fact(hdc.rand_bipolar(4096))   # → index 0
f1 = reasoner.add_fact(hdc.rand_bipolar(4096))   # → index 1
reasoner.add_link(f0, f1)

query = hdc.rand_bipolar(4096)
results = reasoner.reason(query, hops=2)
# → [(fact_index, resonance_score), ...] sorted by resonance descending
```

| Class | Method | Description |
|---|---|---|
| `PyCausalMemory` | `store(cause, effect, time)` | Record a causal triple |
| `PyCausalMemory` | `recall_effect(cause)` | Retrieve effect for a cause |
| `PyCausalMemory` | `recall_cause(effect)` | Retrieve all causes for an effect |
| `PyCausalMemory` | `recall_by_time(time)` | Retrieve effect at a time |
| `PyMultiHopReasoner` | `add_fact(hv)` | Register a fact, returns index |
| `PyMultiHopReasoner` | `add_link(a, b)` | Undirected association between facts |
| `PyMultiHopReasoner` | `reason(query, hops)` | Multi-hop resonance query |

---

### Rain Protocol — Stateless Agent State Transfer

Rain v2 is a binary-first wire protocol for transferring HDC agent state between serverless invocations. Instead of a database or JSON tokens, agents exchange compact `.rain` binaries carrying their holographic world vector, causal edges, and Hebbian weights.

**Wire format (48-byte header + zlib payload):**
```
[RAIN 4B][version u16 BE][flags u16 BE][dim u32 BE][n_edges u32 BE][sha256 32B][compressed body]
```

```python
from catalyst_brain import RainPayload, rain_dumps, rain_loads
from catalyst_brain.rain import merge_digests, RainDigest, to_header, from_header
import catalyst_hdc as hdc

# Serialize agent state to .rain bytes
wv = hdc.rand_bipolar(10_000)
payload = RainPayload(
    agent_id="swarm-lead",
    dim=10_000,
    world_vector=wv,
)
blob = rain_dumps(payload)       # compact binary, SHA-256 verified
print(len(blob))                 # ≪ 100 KB even for 10k-dim vectors

# Round-trip
restored = rain_loads(blob)
assert restored.agent_id == "swarm-lead"
assert len(restored.world_vector) == 10_000
```

#### File I/O

```python
from catalyst_brain.rain import dump, load

dump(payload, "checkpoint.rain")
restored = load("checkpoint.rain")
```

#### HTTP Header Transfer

Pass agent state between serverless functions without a database:

```python
# Agent A — encode state into request header
header_value = to_header(payload)
# → base64 string, drop into X-Rain-State header

# Agent B — recover state on the other side
incoming = from_header(request.headers["X-Rain-State"])
resume_from(incoming.world_vector)
```

#### Holographic Digest Merge

Combine knowledge from N specialist agents into one vector without exposing underlying data:

```python
digest_a = RainDigest(agent_id="specialist-A", vector=hdc.rand_bipolar(4096))
digest_b = RainDigest(agent_id="specialist-B", vector=hdc.rand_bipolar(4096))

merged = merge_digests([digest_a, digest_b])
# → RainDigest with bundled (majority-vote) world vector
```

| Function | Signature | Description |
|---|---|---|
| `rain_dumps(payload)` | `(RainPayload) → bytes` | Serialize to .rain binary |
| `rain_loads(data)` | `(bytes) → RainPayload` | Deserialize from .rain binary |
| `dump(payload, path)` | `(RainPayload, str\|Path) → None` | Write .rain file |
| `load(path)` | `(str\|Path) → RainPayload` | Read .rain file |
| `to_header(payload)` | `(RainPayload) → str` | Base64 encode for X-Rain-State header |
| `from_header(value)` | `(str) → RainPayload` | Decode X-Rain-State header |
| `merge_digests(digests)` | `(list[RainDigest]) → RainDigest` | Algebraic knowledge merge |

---

### CatalystTokenKernel — Progressive Tool Discovery

Use CatalystTokenKernel to keep large tool schemas and execution output out of
the model context until the agent actually needs them. It is designed as a thin
kernel for MCP servers and coding agents that want paginated tool discovery,
schema-on-demand expansion, deferred code-execution status records, and Rain
state handoff.

```python
from catalyst_brain import CatalystTokenKernel, ToolSpec

kernel = CatalystTokenKernel(dim=4096)
kernel.register_tool(
    ToolSpec(
        name="sandbox.execute_python",
        description="Run Python code safely in a deferred sandbox task.",
        input_schema={
            "type": "object",
            "properties": {"code": {"type": "string"}},
            "required": ["code"],
        },
        tags=("code", "execution", "python", "sandbox"),
    )
)

# Progressive tools/list style page: no full schema in context.
page = kernel.list_tools(limit=10)
print(page.tools[0]["schema_ref"])

# Query-gated discovery: expand the schema only when dispatch is likely.
tool = kernel.discover("run python safely", limit=1, include_schema=True)[0]
print(tool["schema"]["properties"]["code"]["type"])

# Deferred code-execution state: compact status first, full output on fetch.
task = kernel.run_python_task("print('hello')")
result = kernel.fetch_task_result(task["task_id"])

# Rain snapshot for compact agent/session handoff.
snapshot = kernel.export_rain_snapshot(agent_id="coding-agent")
print(snapshot["estimated_reduction_ratio"])
```

| Class / Method | Description |
|---|---|
| `ToolSpec` | Verbose tool definition registered once |
| `CatalystTokenKernel.register_tool(spec)` | Stores a full descriptor in `PyHKVC` and returns a compact handle |
| `CatalystTokenKernel.list_tools(limit, cursor)` | Cursor-paginated compact tool manifest |
| `CatalystTokenKernel.discover(query, include_schema)` | Query-gated ranking with optional schema expansion |
| `CatalystTokenKernel.run_python_task(code)` | Constrained local Python execution with compact task status |
| `CatalystTokenKernel.create_code_execution_task(...)` | Compact deferred task status, with output stored outside context |
| `CatalystTokenKernel.fetch_task_result(task_id)` | Explicitly retrieve full code/stdout/stderr |
| `CatalystTokenKernel.export_rain_snapshot(agent_id)` | Export a Rain header for compact agent state transfer |

---

## Benchmarks

### Memory Footprint

Catalyst state is **constant** — it never grows with token count.

| Tokens | Standard FP16 KV-Cache | Catalyst HKVC | Reduction |
|---|---|---|---|
| 1,000 | 1,220.70 MB | **0.15 MB** | **8,000x** |
| 5,000 | 6,103.52 MB | **0.15 MB** | **40,000x** |
| 10,000 | 12,207.03 MB | **0.15 MB** | **80,000x** |

### Bit-Exact Recovery

Bind/unbind is **provably lossless** — XOR is its own inverse.

| Operation | Fidelity | Tested depth |
|---|---|---|
| BCV bind/unbind | **100.00% bit-exact** | 1,000 trials |
| Chained composition (depth 2–100) | **100.00% bit-exact** | 6 depths |
| HMK serialization | **100.00% bit-exact** | 100 trials |

### Multi-Item Superposition

Multi-item bundling maintains **98.4% constant bit accuracy** regardless of item count (up to ~7,213 items at D=10,000).

### Performance Benchmarks

All reproducible public-wheel benchmarks are maintained in the public
**[catalyst-brain-benchmarks](https://github.com/CrewRiz/catalyst-brain-benchmarks)**
repository:

```text
https://github.com/CrewRiz/catalyst-brain-benchmarks
```

The suite installs `catalyst-brain` from PyPI and uses only public SDK APIs, so
users can verify the published results without source access.

---

## Package Distribution

```bash
pip install catalyst-brain
python -c "import catalyst_hdc as hdc; print(len(hdc.rand_bipolar(4096)))"
```

Release wheels are built with the CPython stable ABI (`abi3-py39`) so one wheel
serves Python 3.9+ on the same platform. Each public release should include
platform wheels for the supported operating systems, the native `catalyst_hdc`
extension, the pure-Python `catalyst_brain` companion package, and type stubs.
The free-tier PyPI release is wheel-first; source distributions are reserved
for licensed source-access customers.

Source builds are not part of the public free tier. Licensed commercial and
enterprise customers can receive source access, private build instructions, or
deployment support under separate terms.

---

## Commercial Access

The public PyPI package is the free research and evaluation SDK. It is suitable
for learning, academic experiments, local prototypes, and benchmark
reproduction.

Production, enterprise, hosted API, revenue-generating, redistribution, resale,
or customer pilot use requires a written commercial license or pilot agreement.

For commercial access, enterprise evaluation, higher quotas, private support,
or source-access discussions, contact:

```text
hello@strategic-innovations.ai
```

The public SDK never relies on client-side checks as the commercial enforcement
boundary. Paid access, subscription status, tenant quotas, and API-key
authorization are enforced server-side in the managed Catalyst infrastructure.
Operational deployment details, payment-provider configuration, and secret
management are intentionally not part of the public PyPI documentation.

---

## Architecture

```
catalyst-brain wheel
├── catalyst_hdc        # Native Rust/PyO3 extension
│   ├── Core HDC        # bind/unbind, bundle, permute, resonance
│   ├── HoloCPU         # O(1) scheduler + Grover search
│   ├── HoloGen         # Geometric encoding facade
│   ├── Quantum Heads   # Quantum-inspired attention primitives
│   ├── HKVC            # Holographic key-value cache
│   └── MetaLearning    # Metacognition, SelfAudit, Optimizer, LearningLog
├── catalyst_brain      # Pure-Python companion package
│   ├── Rain Protocol   # Binary state transfer and digest merge
│   ├── Token Kernel    # Progressive tool discovery and compact task state
│   ├── Client          # Edge-worker HTTP wrapper
│   └── Telemetry       # Anonymous, opt-out SDK health events
├── catalyst_hdc.pyi    # Python type stubs (PEP 561)
└── py.typed            # PEP 561 marker
```

---

## Telemetry & Privacy

catalyst-brain collects anonymous usage data to help improve the SDK. No user data, vectors, labels, or model outputs are ever sent.

**What is collected** (all anonymous):
- SDK version, Python version, OS, CPU architecture
- A one-way hash of your machine's platform info (cannot be reversed)
- Which top-level feature was used and whether an exception occurred

**Opt-out** at any time:

```bash
export CATALYST_NO_TELEMETRY=1
```

Data is sent to a Cloudflare Worker endpoint over HTTPS in a background daemon thread and never blocks your code.

---

## License

**Closed-source freemium commercial SDK** — see LICENSE file for the free
research and evaluation grant.

| Use | Permitted? |
|---|---|
| Academic research | Free tier |
| Personal experimentation | Free tier |
| Benchmarking & evaluation | Free tier |
| Publishing results with attribution | Free tier |
| Production / commercial deployment | Commercial license required |
| SaaS / hosted API | Commercial license required |
| Redistribution or resale | Separate written permission required |
| Public source-code use | Not included in the free PyPI package |

**Patent:** U.S. Provisional Patent Application CATALYST-2026-001 covers holographic key-value caching, BlockCodeVector binding, resonant superposition memory, and Grover-amplified attention routing.

Contact: hello@strategic-innovations.ai

---

Copyright © 2026 Strategic Innovations AI. Built with Rust 🦀 + PyO3 🐍.

