# ThRetNet Reference v1.3

This repository is the correctness-oriented, platform-independent PyTorch
reference for **ThRetNet Quantum CPA v1.3**. It contains the model architecture,
state equations, chronological-cut execution, checkpoint compatibility, and
focused scientific invariants without a training service, dataset, experiment
harness, or platform-specific execution dependency.

The reference stores parameters and performs model math in IEEE FP32. It uses
ordinary PyTorch operations and defaults to CPU. Any PyTorch device that supports
the required operations may be selected through `ThRetNetConfig.device`.

## Installation

From the unpacked release directory:

```bash
python -m pip install .
```

PyTorch must already be available or installable for the target platform.

## Minimal use

```python
import torch

from thretnet_reference import ThRetNetConfig, ThRetNetCPAQuantumV13

config = ThRetNetConfig(
    vocab_size=12098,
    regular_vocab_size=12096,
    eor_token=12096,
    class_count=32,
    device="cpu",
)
model = ThRetNetCPAQuantumV13(config)

# A scored row contains prompt, reasoning, and finalization regions separated
# by two consumed EOR tokens. The final EOR terminates generation and is not
# consumed by the model.
tokens = torch.tensor([[1, 2, 12096, 3, 12096, 4]], dtype=torch.long)
logits = model.forward_scored(tokens, prompt_length=2)
```

`forward`, `forward_scored`, and `recurrent_reference` are differentiable.
`prefill` and `step` provide recurrent inference with fixed-size memory state.

## Checkpoints

The portable model preserves the v1.3 parameter and buffer keys used by the
training implementation. A raw state dictionary or a training checkpoint with
its state dictionary under `model` can be loaded with:

```python
from thretnet_reference import load_checkpoint

model = load_checkpoint("checkpoint.pt", config=config)
```

Checkpoint deserialization uses PyTorch's restricted weights-only loader by
default. Set `trust_pickle=True` only for a checkpoint whose complete provenance
is trusted.

## Contents

- `ARCHITECTURE.md` specifies the model and its phase/memory behavior.
- `src/thretnet_reference` contains only portable PyTorch code.
- `tests` contains geometry, retention, generation, checkpoint, and source-parity
  invariants.
- `artifacts/dgx-spark-gb10-sm121` is an isolated source snapshot of the
  device-resident FP32 training kernel specialized for NVIDIA DGX Spark. It is
  not imported or built by the portable package.
- `MANIFEST.sha256` records the release content hashes.

## Scope

This is a reference implementation, not a throughput claim. The portable path
prioritizes transparent equations and testability. The supplemental Spark
artifact records one optimized realization of the same v1.3 parameter contract.

## License

The complete release is dedicated to the public domain under CC0 1.0 Universal.
See `LICENSE`.