Metadata-Version: 2.4
Name: spiralthink-core
Version: 0.9.0
Summary: Universal geometric compression with bit-exact reconstruction. Reference decoder (L0) and baseline encoder (L1).
Author: pfreig-art
License: Apache-2.0 AND CC-BY-4.0
Project-URL: Homepage, https://github.com/pfreig-art/spiralthink-core
Project-URL: Issues, https://github.com/pfreig-art/spiralthink-core/issues
Keywords: compression,kolmogorov,helix,spiral,bit-exact,reconstruction
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: ruff>=0.15; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"

# SpiralThink — Core

> **Universal geometric machine for sub-Kolmogorov effective compression and zero-error reconstruction.**

[![Status](https://img.shields.io/badge/status-preprint--v0.9-blueviolet)]() [![License](https://img.shields.io/badge/license-mixed-green)]() [![Private](https://img.shields.io/badge/repo-private-red)]()

---

## TL;DR

SpiralThink represents arbitrary data as trajectories on a parametric helical manifold $\mathcal{H}(r,\theta,z)$ generated by a short program $\pi$. We target the **algorithmic** lower bound $K(x)$ (Kolmogorov), not Shannon's $H(X)$. Reconstruction is **bit-exact** (zero-error) by design. Effective ratio $\rho = |x|/|\pi|$ diverges with chain length $n$.

| n | Raw bits | \|π\| | ρ |
|---|---|---|---|
| 10³ | 8 000 | 96 | 83× |
| 10⁶ | 8·10⁶ | 112 | 7.1·10⁴× |
| 10⁹ | 8·10⁹ | 128 | 6.25·10⁷× |
| 10¹² | 8·10¹² | 144 | 5.5·10¹⁰× |

---

## Repository layout

```
spiralthink-core/
├── paper/              # L0 · CC-BY 4.0 · preprint LaTeX + PDF
├── reference/          # L0 · CC-BY 4.0 · Python reference decoder
├── encoder/            # L1 · Apache-2.0 · baseline gradient encoder
├── spiralcore/         # L2 · PROPRIETARY · industrial encoder + GPU kernels
├── demo/               # shock-demo notebooks (numerical scaling §4)
├── docs/               # deployment manual
└── LICENSES/           # CC-BY-4.0, Apache-2.0, SpiralCore-EULA
```

---

## Mixed licensing model

| Layer | Path | License | Audience |
|---|---|---|---|
| **L0** Theory + reference decoder | `paper/`, `reference/` | CC-BY 4.0 | academia, open community |
| **L1** Baseline encoder | `encoder/` | Apache-2.0 | OSS contributors, integrators |
| **L2** Industrial encoder *SpiralCore™* | `spiralcore/` | Proprietary EULA | enterprise / unicorn moat |

---

## Core idea

$$\pi^\star = \arg\min_{\pi\,:\,U(\pi)=x} |\pi|, \qquad |\pi^\star| \approx K(x)$$

**Theorem 1 (Compression–Computation Tradeoff).**

$$|\pi| \cdot \log T_\pi \;\geq\; K(x) - O(1)$$

SpiralThink trades *space* for *deterministic recomputation*, never for accuracy.

## Zero-error architecture

```
Encoder ──π──▶ Decoder  U(π) = x
   ▲                       │
   └── hash(x) == hash(U(π)) ──┘
```

If hash mismatch → encoder appends residual patch $\delta$; total $|\pi|+|\delta| \ll |x|$ for structured data.

## Helical spring analogy

$U = \tfrac12 k\,\Delta x^2$. SpiralThink stores informational tension in $\pi$; uncoiling regenerates the chain — like a spring releases stored length without memorizing each coil.

## Universal passive storage

Substrate-agnostic: DNA, optical phase plates, magnetic domains, silicon. Exabyte archives → kilobyte inscriptions.

---

## Applications

1. LLM weights & KV-cache compression
2. Vector DB embeddings (RAM ↔ disk parity)
3. Cold archival (tape replacement)
4. Edge sub-MB foundation models

---

## Roadmap

- [x] Preprint v0.9 draft
- [x] Private repo bootstrap
- [ ] LaTeX compilation → arXiv
- [ ] Reference decoder (Python, NumPy)
- [ ] Baseline encoder (gradient search over $\pi$)
- [ ] Shock-demo notebook (§4 numerical examples)
- [ ] SpiralCore™ GPU kernel prototype
- [ ] Deployment manual v1

---

## Contact

Maintainer: **pfreig-art** · Palma / Maó, Illes Balears · 2026

*This repository is private. All rights reserved on L2 components. L0/L1 will be split into a public mirror at release time.*
