Metadata-Version: 2.4
Name: tensor-spline
Version: 1.0.0
Summary: Compressed neural network layers — Eisenstein lattice splines and low-rank factorization
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0
Provides-Extra: mesh
Requires-Dist: plato-core>=0.1.0; extra == "mesh"

# tensor-spline

Compressed neural network layers — Eisenstein lattice splines and low-rank factorization.

## What's Novel

**SplineLinear**: Weights parameterized by control points on an Eisenstein (hexagonal) lattice, interpolated to create the full weight matrix. Built-in compression, regularization, and constraint-native structure.

**Key result**: drift-detect task hits 100% accuracy at 20× compression with SplineLinear.

## Install

```bash
pip install tensor-spline
```

Requires PyTorch ≥ 2.0.

## Quick Start

```python
import torch.nn as nn
from tensor_spline import SplineLinear, inject_spline, LowRankLinear, recommend_variant

# Option 1: Direct construction
layer = SplineLinear(512, 512, n_control_points=16)
# 262,144 params → 16 params (16,384:1 compression)

# Option 2: Inject into any model
model = nn.Sequential(nn.Linear(256, 128), nn.ReLU(), nn.Linear(128, 10))
inject_spline(model, n_control_points=16)

# Option 3: Low-rank for sharp classification tasks
layer = LowRankLinear(256, 128, rank=16)
# 32,768 params → 6,144 params (5.3× compression, 80% accuracy retention)

# Auto-select the right compression for your task
variant = recommend_variant("detect drift in sensor data")  # → "spline"
variant = recommend_variant("classify documents by topic")   # → "lowrank"
```

## Compression Strategies

| Method | Best For | Compression | Accuracy |
|--------|----------|-------------|----------|
| SplineLinear | Smooth/continuous tasks | 20-40× | 95-100% retention |
| LowRankLinear | Classification, sharp boundaries | 5-16× | 80% retention |
| HierarchicalSpline | Multi-scale continuous | 10-20× | Experimental |

## Honest Findings

SplineLinear achieves 100% accuracy at 20× compression on drift-detect (smooth task).
But only 31% on topic-classify (sharp boundaries) — IDW interpolation is too smooth for classification.
Use LowRankLinear for classification tasks instead.

**Use the right tool for the right task.**

## 3 Basis Functions (SplineLinear)

- `eisenstein` — Inverse distance weighting (default, best for smooth)
- `gaussian` — Gaussian RBF
- `bspline` — Cubic B-spline kernel

## Related

- **[plato-training](https://github.com/SuperInstance/plato-training)** — Micro model training (primary consumer of SplineLinear)
- **[eisenstein-embed](https://github.com/SuperInstance/eisenstein-embed)** — 5-layer semantic matching cascade (uses SplineLinear for 20× embedding quantization)
- **[eisenstein](https://github.com/SuperInstance/eisenstein)** — Eisenstein integer arithmetic (mathematical foundation)
- **[plato-types](https://github.com/SuperInstance/plato-types)** — Tile lifecycle and provenance
- **[ASSEMBLY-GUIDE](https://github.com/SuperInstance/plato-training/blob/master/ASSEMBLY-GUIDE.md)** — Full ecosystem assembly guide

## Mesh Protocol

tensor-spline supports the SuperInstance mesh protocol. When co-installed with [plato-core](https://github.com/SuperInstance/plato-core), compression capabilities auto-register with the shared registry.

```bash
pip install tensor-spline[mesh]
```

This enables:
- `spline-linear` and `low-rank` compressors discoverable via the mesh registry
- `inject`, `measure`, and `recommend` utilities available to other mesh services
- Entry-point based plugin loading (`superinstance.plugins`)

Works standalone without plato-core — graceful degradation via `try/except`.

## License

MIT
