Upload README.md with huggingface_hub

7933a5f verified about 15 hours ago

5.32 kB

license: mit
language:
  - code
library_name: sphere-attention
tags:
  - poisson-attention
  - hypersphere
  - code-generation
  - long-context
  - sparse-attention
  - research
datasets:
  - codeparrot/codeparrot-clean

POET-51M-certified

51M-parameter POET trained with a key-clustering regularizer, so its sparse-attention certificates are informative rather than merely sound.

Results

Trained with an auxiliary key-clustering loss (per-head EMA codebook; each key pulled toward its nearest centroid, λ=0.1) to induce the geodesic cap concentration the certificates rely on.

	unregularized POET	this model (λ=0.1)
paired ppl vs GPT-2 baseline	−2.9%	−2.7% (z = −64)
median certificate ε @ 29% budget	0.60 (vacuous)	0.119
p90 certificate ε	~0.99	0.89
sparse quality @ 29% budget	+1.4% ppl	+0.5% ppl

For ~0.25% perplexity, the median query now carries a proof that it retained ≥88% of its attention mass under a 29% key budget.

The certificate is a trustworthy risk signal: certified ε ranks queries by their true attention error with Spearman ρ = 0.88. Using it to gate — fall back to exact attention whenever ε > τ — bounds the tail by construction:

τ	suffix ppl vs dense	fallback rate	keys/query
0.20	1.0001x	62.5%	71% of dense
0.50	1.0009x	51.0%	60% of dense

i.e. dense-quality output, ~35% of attention saved, worst-case certified error ≤ τ. This is the checkpoint to use if you care about bounded sparse attention rather than best raw perplexity.

Recipe: seq 512, lr 6e-4, --cluster-reg 0.1, 60k steps, selective weight decay, EMA 0.999.

What POET is

POET (POisson attEntion Transformer) replaces softmax attention with the closed-form spherical Poisson kernel. Queries and keys are L2-retracted onto the unit hypersphere and scored by

P_r(<q,k>) = (1 - r^2) / (1 - 2 r <q,k> + r^2)^(d/2)

with a learnable per-head radius r (resolution, replacing temperature), rotary positions (rotations are isometries of the sphere), and a QUEST-style query-norm sharpness term. Equivalently, each attention weight is the harmonic measure of where a random walk started at the query's interior point first exits the sphere at that key.

Because keys live on a sphere, attention admits a geodesic cap decomposition that supports budgeted sparse attention with closed-form per-query error certificates.

Architecture is otherwise a standard pre-LN transformer (GELU MLP, tied embeddings, GPT-2 BPE). Custom code — not transformers-compatible.

Usage

pip install git+https://github.com/Grayblock-AI/spherical-attention

import torch, tiktoken
from sphere_attention.hub import load_poet

model = load_poet("Grayblock-AI/POET-51M-certified")
enc = tiktoken.get_encoding("gpt2")
ids = torch.tensor([enc.encode_ordinary("def quicksort(arr):")])
out = model.generate(ids, max_new_tokens=64, top_k=20)
print(enc.decode(out[0].tolist()))

Training data

codeparrot/codeparrot-clean (permissively licensed Python), GPT-2 BPE. The long-context variants use repository-grouped packing: files from the same repo are packed contiguously so long sequences contain genuine cross-file structure (imports, call sites, definitions).

Limitations

Research checkpoint, small scale. Not instruction-tuned; a raw next-token model. Python only.
Trained on ~983M tokens, which is under compute-optimal for the larger sizes — absolute perplexities are compressed, though all comparisons in the results are matched arm-for-arm.
Exact long-range identifier retrieval is near-zero at these model sizes (for POET and all baselines) — a capacity limit, not architecture.
Sparse-attention certificates are sound (coverage 1.0) but conservative in the tail; see POET-51M-certified for the regularized variant and the gating mechanism that bounds the tail operationally.
Poisson attention has no fused kernel yet, so wall-clock is ~2x a flash-attention baseline at equal FLOPs.

Citation

@misc{poet2026,
  title  = {POET: Poisson Attention Transformers with Certified Sparsity on the Hypersphere},
  author = {Jerge, Michael},
  year   = {2026},
  url    = {https://github.com/Grayblock-AI/spherical-attention}
}

Config

{
  "model": "sphere-ff",
  "dim": 512,
  "depth": 8,
  "heads": 8,
  "seq_len": 512,
  "batch_size": 32,
  "steps": 60000,
  "warmup": 1000,
  "lr": 0.0006,
  "solver_iters": 4,
  "solver_tol": 0.001,
  "eval_every": 1000,
  "seed": 0,
  "grad_accum": 2,
  "no_bf16": false,
  "r_init": 0.7,
  "logit_scale": 10.0,
  "tag": "clufull1",
  "save_checkpoint": true,
  "checkpoint_every": 0,
  "s3_prefix": "",
  "data_dir": "data1b",
  "wandb": false,
  "wandb_project": "spherical-attention",
  "wandb_entity": null,
  "cloudwatch": false,
  "cloudwatch_region": "us-east-2",
  "resume": "",
  "ngpt": true,
  "selective_wd": true,
  "grad_steps": 1,
  "ema": 0.999,
  "cluster_reg": 0.1,
  "abort_divergence": 1.5
}

Grayblock-AI
/

POET-51M-certified