Metadata-Version: 2.4
Name: muscore-compress
Version: 0.1.0
Summary: Cut LLM context token costs: MusCoRe colour-frequency serialisation for structured state. Verified reduction vs JSON, on-chain sealed protocol (cert df9822d8).
Author-email: "J!ll!qu!d (Angus McGregor)" <gussstos@gmail.com>
License: Proprietary - Free for evaluation, paid licence for production use
Project-URL: Homepage, https://github.com/Ember-Circle-Coin/Cinder-Awareness
Project-URL: Certificate, https://explorer.scoredetect.com/certificate/df9822d8-8951-4f3f-b557-2647588c40e4
Keywords: llm,tokens,compression,serialisation,ai-agents,context-window,muscore
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# muscore-compress

**Cut your AI agent's context bill. Verified, sealed, reproducible.**

Every agent framework passes structured state through model context as JSON —
and pays for every token of it, every call, every loop. `muscore-compress`
re-serialises that state into the MusCoRe™ symbol protocol: same meaning,
a fraction of the tokens.

```bash
pip install muscore-compress
```

```python
from muscore_compress import encode, decode, benchmark

state = {"step": 14, "goal": "civic-lookup", "history": [...]}
stream = encode(state)          # dense MusCoRe symbols
restored = decode(stream)       # lossless — always
benchmark(state)                # run the numbers on YOUR payload
```

## The numbers

<!-- RELEASE GATE: this table must be filled from an actual
     `python -m muscore_compress.benchmark` run on the sealed codec.
     Placeholder numbers = no release. Numbers follow code. -->

| Metric | Raw JSON | Gzipped JSON | MusCoRe |
|---|---|---|---|
| Bytes | _run benchmark_ | _run benchmark_ | _run benchmark_ |
| LLM tokens (tiktoken cl100k) | _run benchmark_ | n/a (binary) | _run benchmark_ |

Historical verified figures for the sealed protocol: ~92% byte reduction vs
raw JSON, 45–61% vs gzipped JSON. Token benchmark: reproduce it yourself —
`python -m muscore_compress.benchmark` prints the full table on a sample
agent-state payload, or call `benchmark(your_payload)` on your own data.

**A note on gzip:** gzip wins raw byte counts on large payloads — but gzip
output is binary and cannot ride inside a text context window. MusCoRe
streams are text-native: they go straight into the prompt. The comparison
that costs you money is *tokens in context*, and that is the number this
package attacks.

## Why the seal matters

The MusCoRe protocol was sealed on-chain November 2025 — Skale mainnet,
block 35752169, [cert df9822d8](https://explorer.scoredetect.com/certificate/df9822d8-8951-4f3f-b557-2647588c40e4).
The alphabet cannot drift. What your agents encode today decodes
identically in ten years, and no dependency update can silently change
the wire format underneath you. No other serialisation format offers a
cryptographically frozen vocabulary.

Demonstrated in public: a blind AI-to-AI exchange (Claude → human courier
→ Grok) with self-verifying parity, on the open X timeline, July 2026.

## Licence

Free for evaluation and benchmarking. Production use: **$49 per project**
— [gumroad.com/YOUR-LINK](https://gumroad.com). Includes the full protocol
spec and the sealed alphabet reference.

Support the wider build: [patreon.com/c/NoitallionDispatch](https://patreon.com/c/NoitallionDispatch)

## Verify everything

Run the tests: `pytest tests/` — the round-trip suite gates every release.
Run the benchmark on your own payloads before paying a cent.

Check me, not trust me. Ahoeaaa.

*Gussstron Foundation · Cape Town, South Africa*
