Metadata-Version: 2.4
Name: topological-coherence
Version: 0.2.1
Summary: Toroidal attention constraints for reducing LLM hallucination
Project-URL: Homepage, https://github.com/Paraxiom/topological-coherence
Project-URL: Documentation, https://paraxiom.org/presentations/coherence.html
Project-URL: Repository, https://github.com/Paraxiom/topological-coherence
Project-URL: Paper, https://doi.org/10.5281/zenodo.18187835
Author-email: Sylvain Cormier <sylvain@paraxiom.io>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: attention,coherence,hallucination,llm,logit-bias,machine-learning,tonnetz,topology,transformer
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: numpy>=1.21.0
Requires-Dist: torch>=2.0.0
Provides-Extra: demo
Requires-Dist: gradio>=4.0.0; extra == 'demo'
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: hf
Requires-Dist: transformers>=4.30.0; extra == 'hf'
Description-Content-Type: text/markdown

# Topological Coherence

**Toroidal attention constraints for reducing LLM hallucination**

*Sylvain Cormier | Paraxiom Research | 2026*

## Key Results (v2 — February 2026)

- **+2.8pp on Mistral 7B**, +2.1pp on Qwen 7B — TruthfulQA (817 samples, LLM-judged)
- **4/4 models improved** across 2 architectures and 3 parameter scales
- **Improvement scales with model capacity** — larger models benefit more
- **28x lower drift** than random sparsity (proves topology matters, not just compute reduction)
- Paper: [DOI: 10.5281/zenodo.18516477](https://doi.org/10.5281/zenodo.18516477)

## Installation

```bash
pip install topological-coherence

# With HuggingFace transformers support
pip install topological-coherence[hf]
```

## Quick Start: Toroidal Logit Bias

Drop-in logit processor for any HuggingFace model — no fine-tuning required:

```python
from topological_coherence import ToroidalLogitProcessor
from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("gpt2")
tokenizer = AutoTokenizer.from_pretrained("gpt2")

processor = ToroidalLogitProcessor(grid_size=12, radius=2.0, alpha=0.3)

inputs = tokenizer("The quantum nature of", return_tensors="pt")
outputs = model.generate(
    **inputs,
    logits_processor=[processor],
    max_new_tokens=100
)
print(tokenizer.decode(outputs[0]))
```

## Core API

### Tonnetz Geometry

```python
from topological_coherence import Tonnetz, distance_matrix

# Create a 12x12 torus topology
t = Tonnetz(grid_size=12)
t.distance(0, 5)        # L1 toroidal distance with wraparound
t.spectral_gap()         # First eigenvalue of the torus Laplacian

# Vectorized distance matrix (numpy, fast)
dm = distance_matrix(n_tokens=64, grid_size=12)  # (64, 64)
```

### Attention Masks (3 variants)

```python
from topological_coherence import ToroidalMask, sinkhorn_knopp

mask = ToroidalMask.hybrid(seq_len=64, radius=2.0, alpha=1.0)   # default
mask = ToroidalMask.hard_cutoff(seq_len=64, radius=2.0)          # binary
mask = ToroidalMask.soft_exponential(seq_len=64, alpha=1.0)      # smooth decay

tensor = mask.to_tensor()                     # torch.Tensor for attention
ds = sinkhorn_knopp(tensor, n_iters=50)       # project to doubly-stochastic
```

### Drift Measurement

```python
from topological_coherence import DriftMeter

meter = DriftMeter(threshold=2, grid_size=12)
meter.record(pred=5, target=8)
meter.record(pred=5, target=100)
print(f"Drift rate: {meter.rate():.3f}")
```

### Toroidal Attention (PyTorch)

```python
from topological_coherence import ToroidalAttention, TinyTransformer

# Drop-in attention replacement
attn = ToroidalAttention(d_model=64, n_heads=4, max_seq_len=64)

# Full demo transformer with swappable attention
model = TinyTransformer(
    vocab_size=144, d_model=64, n_heads=4,
    attention_type="toroidal"  # or "baseline", "random"
)
```

## Theory

Hallucination is a geometry problem. Unconstrained latent dynamics permit arbitrary drift through embedding space. Toroidal constraints provide a **constant spectral gap** that suppresses non-resonant modes:

```
λ₁ = 2 - 2cos(2π/N) = Θ(1)    for fixed grid size N
```

This bounds semantic drift without reducing model capacity.

**Hierarchy:** mHC (Birkhoff) ⊂ ERLHS (Hamiltonian) ⊂ Karmonic (Toroidal + Spectral)

## Links

- [Paper (Zenodo)](https://doi.org/10.5281/zenodo.18187835)
- [Toroidal Logit Bias Paper](https://doi.org/10.5281/zenodo.18516477)
- [Live Demo (HuggingFace)](https://huggingface.co/spaces/paraxiom-research/topological-coherence)
- [Source (GitHub)](https://github.com/Paraxiom/topological-coherence)
- [Rust Crate (crates.io)](https://crates.io/crates/topological-coherence)

## Citation

```bibtex
@misc{cormier2026topological,
  author = {Cormier, Sylvain},
  title = {Topological Constraints for Coherent Language Models},
  year = {2026},
  publisher = {Zenodo},
  doi = {10.5281/zenodo.18187835}
}
```

## License

Apache-2.0
