docs/USAGE_ATOMIC.md

# Using Cosmos from code

Every path below was run before being written here. Paths are relative to the repository
root, and they are the paths that actually exist — an earlier version of this file
referenced `cosmos_best.pt` at the root and a `cosmos_model` module, and neither is where
it said.

---

## Load a checkpoint and read its provenance

```python
import torch

ck = torch.load("weights/phos.pt", map_location="cpu", weights_only=False)

print(ck["arch"])              # PHOS-dyn12-phi-QuantumBorn
print(f'{ck["total_steps"]:,}')# 2,800
print(ck["best_val_loss"])     # 0.6984356045722961
print(ck["quantum_source"])    # ibm_real_shots
print(ck["quantum_draws"])     # 400000
print(len(ck["vocab_list"]))   # 162
```

Every checkpoint carries its own lineage. Nothing here needs a config file to be trusted.

| file | params | what it is |
|---|---|---|
| `weights/phos.pt` | 1,153,804 | **the flagship.** dyn12 on the φ scaffold, still growing |
| `weights/spark_cst.pt` | 1,924,488 | the 54D Hebbian kernel model |
| `weights/cosmos_born.pt` | 1,842,432 | the original quantum-born char transformer |
| `weights/cosmos_best.pt` | — | earlier lineage, tiktoken BPE, no quantum birth |

---

## Build the model and generate

The classes are in `architecture/`, not a package you have to install:

```python
import sys; sys.path.insert(0, "architecture")
import torch, cosmos_state_ladder as L

ck = torch.load("weights/phos.pt", map_location="cpu", weights_only=False)
vocab = ck["vocab_list"]
m = L.Ladder(vocab=len(vocab), rung=ck["rung"], ffn=ck["ffn"])
m.load_state_dict(ck["model"], strict=False)
m.eval()

stoi = {c: i for i, c in enumerate(vocab)}
idx = torch.tensor([[stoi.get(c, 0) for c in "the woods"]])
for _ in range(60):
    logits = m(idx[:, -128:])
    logits = logits[0] if isinstance(logits, tuple) else logits
    nxt = int(torch.multinomial(torch.softmax(logits[0, -1] / 0.8, -1), 1))
    idx = torch.cat([idx, torch.tensor([[nxt]])], 1)
print("".join(vocab[i] for i in idx[0].tolist()))
```

`strict=False` is deliberate: checkpoints from different rungs carry different state
tensors, and a mismatch should be visible rather than fatal.

---

## Serve it over HTTP instead

```bash
python serving/cosmos_serve.py 11501
```

Ollama-compatible, so existing clients work unchanged:

```python
import requests
r = requests.post("http://127.0.0.1:11501/api/chat", json={
    "model": "cosmos-phos",
    "messages": [{"role": "user", "content": "hello"}],
    "stream": False,
    "options": {"num_predict": 200},
})
print(r.json()["message"]["content"])
```

**Serve on CPU.** Measured 2026-08-02 on a GTX 1650 Ti with a working CUDA torch:

```
phos n=200   GPU 14.25s   CPU 10.44s
cst  n=200   GPU 10.32s   CPU  3.76s     CPU 2.7x faster
```

Generation is one forward pass per character, strictly sequential, so at 1–2M parameters
there is no batch to amortise kernel-launch overhead over and the card spends its time
dispatching. **Training the same models is 7–25× faster on that GPU** — same hardware,
opposite answer, because a training step is one large batched forward+backward.
`COSMOS_SERVE_DEVICE=cuda` forces the card if your models are much larger.

---

## Keep training it on your own text

```bash
python architecture/phos_grow.py --status
python architecture/phos_grow.py
```

It warm-starts from the checkpoint **and its optimiser state**, appends new vocabulary
without moving existing indices, and refuses to train if its preflight cannot prove the
mechanism is live — a refusal is recorded in `phos_lineage.jsonl` rather than silently
skipped. Five mechanisms in this project's history ran clean and did nothing; that guard
is why.

---

## Verify any of this yourself

```bash
python benchmarks/verify_quantum_engine.py    # shot conservation, weight-birth vs theory
python benchmarks/causality_probe.py          # Ω cannot see the future (random seed each run)
python kit_health.py                          # every part: PRESENT -> LOADS -> ANSWERS
```

`causality_probe.py` draws a fresh random seed every run, so your execution is independent
evidence rather than a replay of someone else's. Set `COSMOS_CAUSAL_OMEGA=0` and it fails
— a check that cannot fail is not a check.