Create app.py

app.py

@@ -0,0 +1,1098 @@
+# app.py — CHR Compressed-Only Learning via Trading Card PNG (Investor Demo)
+# End-goal (Level 1): dataset -> compressed codes -> 2D "trading card" image
+# Training reads ONLY the trading card PNG pixels (no codes.bin used in training)
+
+import os
+# --- HF Spaces hardening: make OpenMP thread env vars valid integers ---
+def _set_int_env(name: str, value: int):
+    v = os.environ.get(name, "")
+    if not str(v).isdigit():
+        os.environ[name] = str(value)
+
+_set_int_env("OMP_NUM_THREADS", 1)
+_set_int_env("OPENBLAS_NUM_THREADS", 1)
+_set_int_env("MKL_NUM_THREADS", 1)
+_set_int_env("NUMEXPR_NUM_THREADS", 1)
+
+import io, re, json, math, struct, tempfile, traceback, hashlib, zlib
+from pathlib import Path
+from typing import List, Tuple, Dict, Optional
+
+import numpy as np
+import gradio as gr
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+import imageio.v2 as imageio
+from PIL import Image
+
+# -----------------------------
+# Optional DOCX support
+# -----------------------------
+_DOCX_OK = False
+try:
+    from docx import Document
+    _DOCX_OK = True
+except Exception:
+    _DOCX_OK = False
+
+# -----------------------------
+# Embeddings: sentence-transformers (preferred), fallback to hashing
+# -----------------------------
+from sklearn.feature_extraction.text import HashingVectorizer
+from sklearn.decomposition import PCA
+
+_ST_MODEL = None
+def _load_st_model():
+    global _ST_MODEL
+    if _ST_MODEL is not None:
+        return _ST_MODEL
+    try:
+        from sentence_transformers import SentenceTransformer
+        _ST_MODEL = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
+        return _ST_MODEL
+    except Exception:
+        return None
+
+def embed_texts(texts: List[str], prefer_sentence_transformer: bool = True) -> Tuple[np.ndarray, str]:
+    texts = [t if isinstance(t, str) else str(t) for t in texts]
+    if prefer_sentence_transformer:
+        model = _load_st_model()
+        if model is not None:
+            try:
+                vecs = model.encode(
+                    texts, batch_size=32, show_progress_bar=False,
+                    convert_to_numpy=True, normalize_embeddings=True
+                )
+                return vecs.astype(np.float32), "sentence-transformers/all-MiniLM-L6-v2"
+            except Exception:
+                pass
+
+    hv = HashingVectorizer(n_features=768, alternate_sign=False, norm=None)
+    X = hv.transform(texts)
+    vecs = X.toarray().astype(np.float32)
+    norms = np.linalg.norm(vecs, axis=1, keepdims=True) + 1e-9
+    vecs = vecs / norms
+    return vecs, "HashingVectorizer(768d) fallback"
+
+# -----------------------------
+# Text ingestion / splitting
+# -----------------------------
+def _basic_sentence_split(text: str) -> List[str]:
+    rough = re.split(r'[\n\r]+|(?<=[\.\!\?])\s+', text.strip())
+    out = []
+    for s in rough:
+        s = s.strip()
+        if s:
+            out.append(s)
+    return out
+
+def read_txt_bytes(b: bytes) -> str:
+    try:
+        return b.decode("utf-8")
+    except Exception:
+        return b.decode("latin-1", errors="ignore")
+
+def read_docx_bytes(b: bytes) -> List[str]:
+    if not _DOCX_OK:
+        raise RuntimeError("python-docx not installed in this Space.")
+    bio = io.BytesIO(b)
+    doc = Document(bio)
+    paras = [p.text.strip() for p in doc.paragraphs]
+    return [p for p in paras if p and not p.isspace()]
+
+def to_units(raw_text: str, mode: str) -> List[str]:
+    raw_text = raw_text.strip()
+    if not raw_text:
+        return []
+    if mode == "sentences":
+        return _basic_sentence_split(raw_text)
+    paras = [p.strip() for p in re.split(r"\n\s*\n+", raw_text) if p.strip()]
+    return paras
+
+# -----------------------------
+# Demo corpus (big enough to always train)
+# -----------------------------
+DEMO_CORPUS = """
+In the beginning, people stored knowledge in libraries, then in databases, and now in neural networks.
+Compression isn’t just saving space — it’s choosing what matters.
+A constellation is a pattern you can navigate.
+Entropy is a measure of surprise, and learning is surprise turning into structure.
+
+A system that learns from compressed data never needs the original.
+It doesn’t memorize pixels; it memorizes geometry.
+It doesn’t hoard text; it extracts signals.
+The question isn’t “Can it compress?” but “Can it learn after compressing?”
+
+Investors love seeing systems move.
+They love curves that fall.
+They love maps that cluster.
+They love a demo that feels alive.
+
+This demo builds a codec from your dataset,
+then trains a model exclusively on the codec’s trading card.
+No raw text is used during training.
+Only the trading card exists.
+
+We call the clusters constellations.
+We call the structure harvestable.
+We call the drop in entropy visible proof.
+"""
+
+# -----------------------------
+# CHR core
+# -----------------------------
+def softmax(x, axis=-1):
+    x = x - np.max(x, axis=axis, keepdims=True)
+    ex = np.exp(x)
+    return ex / (np.sum(ex, axis=axis, keepdims=True) + 1e-9)
+
+def global_range_entropy(p: np.ndarray) -> float:
+    m = p.mean(axis=0)
+    m_safe = np.clip(m, 1e-12, None)
+    return float(-(m_safe * np.log(m_safe)).sum())
+
+def soft_slab_entropy(z: np.ndarray, U: np.ndarray, bins: int = 8, tau: float = 5.0) -> float:
+    t = z @ U.T
+    K = U.shape[0]
+    Hs = []
+    for j in range(K):
+        tj = t[:, j]
+        tmin, tmax = float(tj.min()), float(tj.max())
+        if not np.isfinite(tmin) or not np.isfinite(tmax) or tmax - tmin < 1e-6:
+            Hs.append(0.0)
+            continue
+        centers = np.linspace(tmin, tmax, bins)
+        dist2 = (tj[:, None] - centers[None, :]) ** 2
+        weights = softmax(-tau * dist2, axis=1)
+        hist = weights.mean(axis=0)
+        hist = np.clip(hist, 1e-12, None)
+        H = float(-(hist * np.log(hist)).sum())
+        Hs.append(H)
+    return float(np.mean(Hs)) if Hs else 0.0
+
+def kmeans_plus_plus_init(z: np.ndarray, K: int, rng: np.random.RandomState) -> np.ndarray:
+    N, d = z.shape
+    inds = [rng.randint(0, N)]
+    centers = [z[inds[0]]]
+    cos0 = np.clip(z @ centers[0], -1.0, 1.0)
+    d2 = np.clip(1.0 - cos0, 1e-12, None)
+
+    for _ in range(1, K):
+        s = d2.sum()
+        if not np.isfinite(s) or s <= 0:
+            probs = np.full(N, 1.0 / N)
+        else:
+            probs = np.clip(d2 / s, 0.0, None)
+            probs = probs / (probs.sum() + 1e-12)
+        next_idx = rng.choice(N, p=probs)
+        inds.append(next_idx)
+        centers.append(z[next_idx])
+
+        cos_new = np.clip(z @ z[next_idx], -1.0, 1.0)
+        d2 = np.minimum(d2, np.clip(1.0 - cos_new, 1e-12, None))
+
+    U = np.stack(centers, axis=0)
+    U = U / (np.linalg.norm(U, axis=1, keepdims=True) + 1e-9)
+    return U
+
+def chr_optimize(z: np.ndarray, K: int = 8, iters: int = 30, beta: float = 12.0,
+                 bins: int = 8, tau: float = 5.0, seed: int = 42):
+    rng = np.random.RandomState(seed)
+    N, d = z.shape
+    U = kmeans_plus_plus_init(z, K, rng) if N >= K else np.pad(z, ((0, max(0, K - N)), (0, 0)), mode="wrap")[:K]
+    U = U / (np.linalg.norm(U, axis=1, keepdims=True) + 1e-9)
+
+    logits0 = beta * (z @ U.T)
+    p0 = softmax(logits0, axis=1)
+    Hg_traj = [global_range_entropy(p0)]
+    Hs_traj = [soft_slab_entropy(z, U, bins=bins, tau=tau)]
+
+    for _ in range(iters):
+        logits = beta * (z @ U.T)
+        p = softmax(logits, axis=1)
+        numer = p.T @ z
+        denom = p.sum(axis=0)[:, None] + 1e-9
+        U = numer / denom
+        U = U / (np.linalg.norm(U, axis=1, keepdims=True) + 1e-9)
+        Hg_traj.append(global_range_entropy(p))
+        Hs_traj.append(soft_slab_entropy(z, U, bins=bins, tau=tau))
+
+    logits = beta * (z @ U.T)
+    p = softmax(logits, axis=1)
+    return U, p, np.array(Hg_traj), np.array(Hs_traj)
+
+def compute_mhep(Hg_traj: np.ndarray, Hs_traj: np.ndarray, K: int, bins: int, w_g: float = 0.7, w_s: float = 0.3) -> float:
+    if len(Hg_traj) < 2 or len(Hs_traj) < 2:
+        return 0.0
+    maxHg = math.log(max(K, 2))
+    maxHs = math.log(max(bins, 2))
+    drop_g = max(0.0, float(Hg_traj[0] - Hg_traj[-1])) / (maxHg + 1e-9)
+    drop_s = max(0.0, float(Hs_traj[0] - Hs_traj[-1])) / (maxHs + 1e-9)
+    return float(np.clip(100.0 * (w_g * drop_g + w_s * drop_s), 0.0, 100.0))
+
+# -----------------------------
+# CHR → discrete "compressed" byte stream (codes.bin payload)
+# -----------------------------
+def make_radial_bins(radials: np.ndarray, B: int = 64) -> np.ndarray:
+    edges = np.quantile(radials, np.linspace(0, 1, B + 1))
+    for i in range(1, len(edges)):
+        if edges[i] <= edges[i - 1]:
+            edges[i] = edges[i - 1] + 1e-6
+    return edges.astype(np.float32)
+
+def quantize_radial(r: float, edges: np.ndarray) -> int:
+    b = np.searchsorted(edges, r, side="right") - 1
+    return int(np.clip(b, 0, len(edges) - 2))
+
+def pack_codes_to_bytes(labels: np.ndarray, bins: np.ndarray) -> bytes:
+    out = bytearray()
+    for c, b in zip(labels.tolist(), bins.tolist()):
+        out.append(int(c) & 0xFF)
+        out.append(int(b) & 0xFF)
+    return bytes(out)
+
+def save_codes_and_codec(code_bytes: bytes, codec: Dict, out_dir: str) -> Tuple[str, str]:
+    os.makedirs(out_dir, exist_ok=True)
+    bin_path = os.path.join(out_dir, "codes.bin")
+    meta_path = os.path.join(out_dir, "codec.json")
+    with open(bin_path, "wb") as f:
+        f.write(b"CHRC")
+        f.write(struct.pack("<I", 1))
+        f.write(code_bytes)
+    with open(meta_path, "w", encoding="utf-8") as f:
+        json.dump(codec, f, indent=2)
+    return bin_path, meta_path
+
+# -----------------------------
+# Trading Card layer (THE NEW PIECE)
+# -----------------------------
+CARD_MAGIC = b"TCAR"  # Trading Card magic
+CARD_VER = 1
+
+def _sha256_hex(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()
+
+def _crc32_u32(b: bytes) -> int:
+    return zlib.crc32(b) & 0xFFFFFFFF
+
+def pack_trading_card_payload(code_bytes: bytes, codec: Dict, title: str = "CHR Trading Card") -> bytes:
+    """
+    A self-contained binary payload that lives inside the card's pixels.
+
+    Layout:
+      magic(4) | ver(u32) | header_len(u32) | header_json | code_len(u32) | code_bytes
+    Header contains checksums for verification.
+    """
+    header = {
+        "title": title,
+        "codec": {
+            "backend": codec.get("backend"),
+            "K": codec.get("K"),
+            "radial_bins": codec.get("radial_bins"),
+            "iters": codec.get("iters"),
+            "beta": codec.get("beta"),
+            "slab_bins": codec.get("slab_bins"),
+            "tau": codec.get("tau"),
+            "seed": codec.get("seed"),
+        },
+        "units_count": codec.get("units_count"),
+        "bytes_per_unit": codec.get("bytes_per_unit"),
+        "code_len": int(len(code_bytes)),
+        "crc32": int(_crc32_u32(code_bytes)),
+        "sha256": _sha256_hex(code_bytes),
+    }
+    header_json = json.dumps(header, ensure_ascii=False).encode("utf-8")
+
+    blob = bytearray()
+    blob += CARD_MAGIC
+    blob += struct.pack("<I", CARD_VER)
+    blob += struct.pack("<I", len(header_json))
+    blob += header_json
+    blob += struct.pack("<I", len(code_bytes))
+    blob += code_bytes
+    return bytes(blob)
+
+def unpack_trading_card_payload(payload: bytes) -> Tuple[Dict, bytes]:
+    """
+    Returns (header_dict, code_bytes) after validating structure.
+    """
+    if len(payload) < 16:
+        raise ValueError("Card payload too small.")
+    if payload[:4] != CARD_MAGIC:
+        raise ValueError("Card magic not found.")
+    ver = struct.unpack("<I", payload[4:8])[0]
+    if ver != CARD_VER:
+        raise ValueError(f"Unsupported card version: {ver}")
+    hlen = struct.unpack("<I", payload[8:12])[0]
+    off = 12
+    header_json = payload[off:off+hlen]
+    off += hlen
+    header = json.loads(header_json.decode("utf-8"))
+    clen = struct.unpack("<I", payload[off:off+4])[0]
+    off += 4
+    code_bytes = payload[off:off+clen]
+    if len(code_bytes) != clen:
+        raise ValueError("Card payload truncated.")
+    return header, code_bytes
+
+def bytes_to_data_slab_image(payload: bytes, slab_w: int = 256) -> np.ndarray:
+    """
+    Convert payload bytes into a 2D slab (grayscale) image as uint8.
+    We pad to full rows.
+    """
+    arr = np.frombuffer(payload, dtype=np.uint8)
+    w = int(slab_w)
+    h = int(math.ceil(len(arr) / w))
+    pad = h*w - len(arr)
+    if pad > 0:
+        arr = np.concatenate([arr, np.zeros(pad, dtype=np.uint8)], axis=0)
+    slab = arr.reshape(h, w)
+    return slab
+
+def data_slab_image_to_bytes(slab: np.ndarray, orig_len: int) -> bytes:
+    flat = slab.astype(np.uint8).ravel()
+    return bytes(flat[:orig_len])
+
+def make_holo_front(U: np.ndarray, K: int, W: int, H: int, seed: int = 0) -> np.ndarray:
+    """
+    Create a holographic-looking RGB background from anchors U.
+    Deterministic and fast. This is "sizzle"; it doesn't contain the payload.
+    """
+    rng = np.random.RandomState(int(seed) + 123)
+    # pick a few anchor directions and random frequencies
+    d = U.shape[1]
+    n = min(K, 16)
+    idx = rng.choice(K, size=n, replace=K < n)
+    V = U[idx]  # [n, d]
+    # Create a coordinate grid
+    yy, xx = np.mgrid[0:H, 0:W].astype(np.float32)
+    xx = (xx / max(1, W-1) - 0.5) * 2.0
+    yy = (yy / max(1, H-1) - 0.5) * 2.0
+
+    # derive frequencies and phases from U
+    freqs = rng.uniform(2.0, 10.0, size=n).astype(np.float32)
+    phases = rng.uniform(0, 2*np.pi, size=n).astype(np.float32)
+
+    # 3 channels from different mixtures
+    out = np.zeros((H, W, 3), dtype=np.float32)
+    for c in range(3):
+        acc = np.zeros((H, W), dtype=np.float32)
+        for i in range(n):
+            a = float(V[i, (c*7) % d])
+            b = float(V[i, (c*11 + 3) % d])
+            acc += np.cos(freqs[i] * (a*xx + b*yy) + phases[i])
+        # normalize 0..1
+        acc = (acc - acc.min()) / (acc.max() - acc.min() + 1e-9)
+        out[..., c] = acc
+
+    # add a subtle radial vignette
+    rr = np.sqrt(xx*xx + yy*yy)
+    vignette = np.clip(1.1 - 0.35*rr, 0.6, 1.1)
+    out *= vignette[..., None]
+    out = np.clip(out, 0.0, 1.0)
+    return (out * 255.0).astype(np.uint8)
+
+def compose_trading_card(front_rgb: np.ndarray, slab_gray: np.ndarray, title: str, subtitle: str) -> np.ndarray:
+    """
+    Make a single card image:
+      - top: holo front with title/subtitle overlay
+      - bottom: data slab grid (this is where bytes live)
+    Output: RGB uint8 image.
+    """
+    Hf, Wf, _ = front_rgb.shape
+    slab_h, slab_w = slab_gray.shape
+
+    # Make slab into RGB
+    slab_rgb = np.stack([slab_gray]*3, axis=-1)
+
+    # Add a separator
+    sep = np.full((8, Wf, 3), 16, dtype=np.uint8)
+
+    # Resize slab to match card width (nearest)
+    if slab_w != Wf:
+        # simple nearest resize
+        slab_img = Image.fromarray(slab_gray, mode="L")
+        slab_img = slab_img.resize((Wf, slab_h), resample=Image.NEAREST)
+        slab_gray2 = np.array(slab_img, dtype=np.uint8)
+        slab_rgb = np.stack([slab_gray2]*3, axis=-1)
+
+    card = np.concatenate([front_rgb, sep, slab_rgb], axis=0)
+
+    # Overlay text on front using PIL (fast and dependency-light)
+    try:
+        pil = Image.fromarray(card, mode="RGB")
+        from PIL import ImageDraw, ImageFont
+        draw = ImageDraw.Draw(pil)
+        # default font
+        font1 = ImageFont.load_default()
+        font2 = ImageFont.load_default()
+
+        # Place title/subtitle
+        draw.rectangle([0, 0, Wf, 26], fill=(0, 0, 0))
+        draw.text((10, 6), title, fill=(255, 255, 255), font=font1)
+        draw.text((10, 34), subtitle, fill=(255, 255, 255), font=font2)
+
+        # Add a "foil" frame
+        draw.rectangle([4, 4, Wf-5, Hf-5], outline=(220, 220, 255), width=2)
+
+        card = np.array(pil, dtype=np.uint8)
+    except Exception:
+        pass
+
+    return card
+
+def save_png(arr: np.ndarray, path: str):
+    Image.fromarray(arr).save(path, format="PNG")
+
+def load_png(path: str) -> np.ndarray:
+    return np.array(Image.open(path).convert("RGB"), dtype=np.uint8)
+
+def extract_payload_from_card(card_rgb: np.ndarray, slab_top: int, slab_w: int, payload_len: int) -> bytes:
+    """
+    Extract bytes from the slab region (grayscale interpretation).
+    We read from the card's bottom data slab.
+    """
+    slab_rgb = card_rgb[slab_top:, :, :]
+    slab_gray = slab_rgb[..., 0].astype(np.uint8)  # stored grayscale replicated in RGB
+    # slab_gray already width==card width, we assume slab_w==card width
+    slab = slab_gray
+    return data_slab_image_to_bytes(slab, payload_len)
+
+# -----------------------------
+# Visuals (existing + card-specific)
+# -----------------------------
+def plot_entropy(Hg, Hs, out_path):
+    plt.figure(figsize=(6,4))
+    plt.plot(Hg, label="Global range entropy")
+    plt.plot(Hs, label="Slab entropy")
+    plt.xlabel("Iteration"); plt.ylabel("Entropy")
+    plt.title("Entropy drops during CHR compression")
+    plt.legend()
+    plt.tight_layout()
+    plt.savefig(out_path, dpi=150)
+    plt.close()
+
+def plot_constellation_map(z, U, labels, out_path):
+    if z.shape[1] > 2:
+        pca = PCA(n_components=2, random_state=0)
+        Z2 = pca.fit_transform(z)
+        U2 = pca.transform(U)
+    else:
+        Z2, U2 = z, U
+    plt.figure(figsize=(6,5))
+    plt.scatter(Z2[:,0], Z2[:,1], s=14, alpha=0.8, c=labels)
+    plt.scatter(U2[:,0], U2[:,1], marker="*", s=200)
+    plt.title("Constellation map (compressed geometry)")
+    plt.xlabel("PC1"); plt.ylabel("PC2")
+    plt.tight_layout()
+    plt.savefig(out_path, dpi=150)
+    plt.close()
+
+def plot_training_curves(losses, ppls, out_path):
+    plt.figure(figsize=(6,4))
+    plt.plot(losses, label="Loss")
+    plt.plot(ppls, label="Perplexity")
+    plt.xlabel("Checkpoint")
+    plt.title("Learning on trading card pixels")
+    plt.legend()
+    plt.tight_layout()
+    plt.savefig(out_path, dpi=150)
+    plt.close()
+
+def plot_rollout_tracks(seq_bytes: List[int], out_path, title="Rollout (byte tokens)"):
+    plt.figure(figsize=(8,3.6))
+    plt.plot(seq_bytes, label="Byte value")
+    plt.ylim(-2, 260)
+    plt.xlabel("Step"); plt.title(title)
+    plt.legend()
+    plt.tight_layout()
+    plt.savefig(out_path, dpi=150)
+    plt.close()
+
+def plot_before_after_tracks(before_bytes: List[int], after_bytes: List[int], out_path):
+    plt.figure(figsize=(10,4))
+    plt.subplot(1,2,1)
+    plt.plot(before_bytes, label="Byte value")
+    plt.title("BEFORE (untrained)")
+    plt.ylim(-2, 260)
+    plt.legend()
+
+    plt.subplot(1,2,2)
+    plt.plot(after_bytes, label="Byte value")
+    plt.title("AFTER (trained)")
+    plt.ylim(-2, 260)
+    plt.legend()
+
+    plt.suptitle("Rollout comparison (trained on card pixels)")
+    plt.tight_layout()
+    plt.savefig(out_path, dpi=150)
+    plt.close()
+
+def make_card_tilt_gif(card_rgb: np.ndarray, out_path: str, frames: int = 24, fps: int = 12):
+    """
+    Cheap holo tilt effect: shift color channels + brightness gradient over the front region.
+    This is pure sizzle and very fast.
+    """
+    H, W, _ = card_rgb.shape
+    frames = int(max(8, min(frames, 48)))
+    fps = int(max(6, min(fps, 24)))
+
+    imgs = []
+    for t in range(frames):
+        a = (t / frames) * 2*np.pi
+        dx = int(2 + 3*np.sin(a))
+        dy = int(2 + 3*np.cos(a))
+
+        img = card_rgb.copy().astype(np.int16)
+
+        # apply gentle "tilt" to the top half (front)
+        front_h = int(H * 0.45)
+        yy, xx = np.mgrid[0:front_h, 0:W]
+        grad = (0.85 + 0.15*np.sin(a + (xx / max(1, W-1))*2*np.pi)).astype(np.float32)
+
+        # channel shift
+        r = np.roll(img[:front_h, :, 0], shift=dx, axis=1)
+        g = np.roll(img[:front_h, :, 1], shift=dy, axis=0)
+        b = img[:front_h, :, 2]
+
+        img[:front_h, :, 0] = (r * grad).astype(np.int16)
+        img[:front_h, :, 1] = (g * grad).astype(np.int16)
+        img[:front_h, :, 2] = (b * grad).astype(np.int16)
+
+        img = np.clip(img, 0, 255).astype(np.uint8)
+        imgs.append(img)
+
+    imageio.mimsave(out_path, imgs, fps=fps)
+
+# -----------------------------
+# Training: byte-model reads ONLY the trading card PNG pixels
+# -----------------------------
+import torch
+import torch.nn as nn
+from torch.utils.data import Dataset, DataLoader
+
+class CardByteDataset(Dataset):
+    """
+    Produces next-byte prediction windows from the trading card's payload bytes.
+    Importantly, it reads from the CARD PNG (pixels) every time.
+    """
+    def __init__(self, card_png_path: str, payload_len: int, slab_top: int, block_size: int = 128):
+        self.card_png_path = card_png_path
+        self.payload_len = int(payload_len)
+        self.slab_top = int(slab_top)
+        self.block_size = int(block_size)
+
+        card = load_png(card_png_path)
+        slab_rgb = card[self.slab_top:, :, :]
+        slab_gray = slab_rgb[..., 0].astype(np.uint8)
+        flat = slab_gray.ravel()
+        self.bytes = torch.tensor(list(flat[:self.payload_len]), dtype=torch.long)
+
+    def __len__(self):
+        return max(0, len(self.bytes) - self.block_size - 1)
+
+    def __getitem__(self, idx):
+        x = self.bytes[idx:idx+self.block_size]
+        y = self.bytes[idx+1:idx+self.block_size+1]
+        return x, y
+
+class TinyByteTransformer(nn.Module):
+    """
+    FAST investor demo model: small and quick on CPU/GPU.
+    """
+    def __init__(self, vocab_size=256, d_model=128, n_layers=2, n_heads=4, block_size=128):
+        super().__init__()
+        self.tok = nn.Embedding(vocab_size, d_model)
+        self.pos = nn.Embedding(block_size, d_model)
+        enc_layer = nn.TransformerEncoderLayer(
+            d_model=d_model, nhead=n_heads, dim_feedforward=4*d_model,
+            dropout=0.1, batch_first=True
+        )
+        self.tr = nn.TransformerEncoder(enc_layer, num_layers=n_layers)
+        self.lm = nn.Linear(d_model, vocab_size)
+        self.block_size = int(block_size)
+
+    def forward(self, x):
+        B, T = x.shape
+        pos = torch.arange(T, device=x.device).unsqueeze(0).expand(B, T)
+        h = self.tok(x) + self.pos(pos)
+        mask = torch.triu(torch.ones(T, T, device=x.device), diagonal=1).bool()
+        h = self.tr(h, mask=mask)
+        return self.lm(h)
+
+@torch.no_grad()
+def sample_bytes(model, start: List[int], steps: int, device: str = "cpu", temperature: float = 1.0) -> List[int]:
+    model.eval()
+    seq = start[:]
+    steps = int(steps)
+    for _ in range(steps):
+        x = torch.tensor(seq[-model.block_size:], dtype=torch.long, device=device).unsqueeze(0)
+        logits = model(x)[0, -1] / max(1e-6, float(temperature))
+        probs = torch.softmax(logits, dim=-1)
+        nxt = int(torch.multinomial(probs, num_samples=1).item())
+        seq.append(nxt)
+    return seq
+
+def train_on_card_png(card_png_path: str,
+                      payload_len: int,
+                      slab_top: int,
+                      steps: int = 250,
+                      batch_size: int = 32,
+                      block_size: int = 128,
+                      lr: float = 5e-4,
+                      device: str = "cpu",
+                      log_every: int = 25):
+    ds = CardByteDataset(card_png_path, payload_len=payload_len, slab_top=slab_top, block_size=block_size)
+    n_windows = len(ds)
+    if n_windows <= 0:
+        raise RuntimeError(f"Card payload too small for block_size={block_size}. Reduce block_size or increase data.")
+
+    # avoid drop_last if small
+    drop_last = n_windows >= batch_size
+    dl = DataLoader(ds, batch_size=batch_size, shuffle=True, drop_last=drop_last)
+    it = iter(dl)
+
+    model = TinyByteTransformer(block_size=block_size).to(device)
+    opt = torch.optim.AdamW(model.parameters(), lr=lr)
+    loss_fn = nn.CrossEntropyLoss()
+
+    losses, ppls = [], []
+    steps = int(steps)
+    log_every = max(1, int(log_every))
+
+    model.train()
+    for step in range(1, steps+1):
+        try:
+            x, y = next(it)
+        except StopIteration:
+            it = iter(dl)
+            x, y = next(it)
+
+        x, y = x.to(device), y.to(device)
+        logits = model(x)
+        loss = loss_fn(logits.view(-1, 256), y.view(-1))
+
+        opt.zero_grad(set_to_none=True)
+        loss.backward()
+        torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0)
+        opt.step()
+
+        if step % log_every == 0:
+            l = float(loss.detach().cpu().item())
+            ppl = float(torch.exp(loss.detach()).cpu().item())
+            losses.append(l)
+            ppls.append(ppl)
+
+    return model, losses, ppls
+
+# -----------------------------
+# App state
+# -----------------------------
+STATE = {
+    "units": None,
+    "Z": None,
+    "U": None,
+    "labels": None,
+    "bins": None,
+    "bin_path": None,
+    "codec_path": None,
+    "codec": None,
+
+    "card_png_path": None,
+    "card_payload_len": None,
+    "card_slab_top": None,
+    "card_header": None,
+
+    "model": None,
+}
+
+def _bytes_from_upload(file_obj) -> Tuple[bytes, str]:
+    if file_obj is None:
+        return b"", ""
+    if isinstance(file_obj, str) and os.path.exists(file_obj):
+        return Path(file_obj).read_bytes(), os.path.basename(file_obj)
+    if hasattr(file_obj, "name") and os.path.exists(file_obj.name):
+        return Path(file_obj.name).read_bytes(), os.path.basename(file_obj.name)
+    return b"", "upload"
+
+# -----------------------------
+# Callbacks
+# -----------------------------
+def load_demo(units_mode: str):
+    raw = (DEMO_CORPUS.strip() + "\n\n") * 80
+    units = to_units(raw, units_mode)
+    units = [u.strip() for u in units if u.strip()]
+    STATE["units"] = units
+    return f"Loaded **{len(units)}** demo units (built-in corpus)."
+
+def ingest_file(file_obj, units_mode: str):
+    try:
+        b, name = _bytes_from_upload(file_obj)
+        if not b:
+            return "Upload a .txt or .docx file to begin."
+
+        if name.lower().endswith(".docx"):
+            paras = read_docx_bytes(b)
+            raw = "\n\n".join(paras)
+        else:
+            raw = read_txt_bytes(b)
+
+        units = to_units(raw, units_mode)
+        units = [u.strip() for u in units if u.strip()]
+        if len(units) > 5000:
+            units = units[:5000]
+
+        STATE["units"] = units
+        return f"Loaded **{len(units)}** units from **{name}**."
+    except Exception as e:
+        return f"Error ingesting file: {e}"
+
+def compress_and_make_card(K, iters, beta, slab_bins, tau, seed, radial_bins,
+                           card_width, front_height, title_text):
+    """
+    1) CHR compress
+    2) build codes.bin + codec.json
+    3) build trading card PNG that embeds a full self-contained payload
+    4) verify by extracting payload back from the PNG
+    """
+    try:
+        units = STATE.get("units")
+        if not units:
+            return "No units loaded. Upload or load demo corpus.", None, None, None, None, None, None
+
+        # --- CHR compression ---
+        Z, backend = embed_texts(units, prefer_sentence_transformer=True)
+        U, p, Hg, Hs = chr_optimize(
+            Z, K=int(K), iters=int(iters), beta=float(beta),
+            bins=int(slab_bins), tau=float(tau), seed=int(seed)
+        )
+        labels = p.argmax(axis=1).astype(np.int32)
+        proj = Z @ U.T
+        radials = proj[np.arange(len(units)), labels].astype(np.float32)
+
+        edges = make_radial_bins(radials, B=int(radial_bins))
+        bins_q = np.array([quantize_radial(float(radials[i]), edges) for i in range(len(units))], dtype=np.int32)
+
+        code_bytes = pack_codes_to_bytes(labels, bins_q)
+
+        # --- Save codes.bin + codec.json (for audit/download only) ---
+        out_dir = tempfile.mkdtemp()
+        codec = {
+            "backend": backend,
+            "K": int(K),
+            "radial_bins": int(radial_bins),
+            "iters": int(iters),
+            "beta": float(beta),
+            "slab_bins": int(slab_bins),
+            "tau": float(tau),
+            "seed": int(seed),
+            "U": U.tolist(),
+            "radial_edges": edges.tolist(),
+            "units_count": int(len(units)),
+            "bytes_per_unit": 2.0,
+            "total_bytes": int(len(code_bytes) + 8),
+        }
+        bin_path, codec_path = save_codes_and_codec(code_bytes, codec, out_dir)
+
+        # --- Build trading card payload ---
+        payload = pack_trading_card_payload(code_bytes=code_bytes, codec=codec, title=str(title_text).strip()[:120] or "CHR Trading Card")
+        payload_len = len(payload)
+
+        # --- Render data slab and holo front ---
+        card_w = int(card_width)
+        front_h = int(front_height)
+        slab = bytes_to_data_slab_image(payload, slab_w=card_w)  # grayscale slab holding payload
+        slab_h = slab.shape[0]
+        # front with same width
+        front = make_holo_front(np.array(U, dtype=np.float32), K=int(K), W=card_w, H=front_h, seed=int(seed))
+
+        mhep = compute_mhep(Hg, Hs, K=int(K), bins=int(slab_bins))
+
+        subtitle = f"Units={len(units)}  K={int(K)}  Bytes={payload_len}  CRC32={_crc32_u32(code_bytes):08x}"
+        card_rgb = compose_trading_card(front_rgb=front, slab_gray=slab, title=str(title_text).strip() or "CHR Trading Card", subtitle=subtitle)
+
+        # --- Save PNG ---
+        card_png_path = os.path.join(out_dir, "trading_card.png")
+        save_png(card_rgb, card_png_path)
+
+        # --- Determine slab top for extraction ---
+        sep_h = 8
+        slab_top = front_h + sep_h
+
+        # --- Verify by extracting payload back from PNG ---
+        card_loaded = load_png(card_png_path)
+        extracted = extract_payload_from_card(card_loaded, slab_top=slab_top, slab_w=card_w, payload_len=payload_len)
+        header2, code2 = unpack_trading_card_payload(extracted)
+
+        ok_crc = (_crc32_u32(code2) == int(header2["crc32"]))
+        ok_sha = (_sha256_hex(code2) == str(header2["sha256"]))
+        verified = (ok_crc and ok_sha and len(code2) == len(code_bytes))
+
+        # Save extra visuals
+        ent_plot = os.path.join(out_dir, "entropy.png")
+        map_plot = os.path.join(out_dir, "map.png")
+        plot_entropy(Hg, Hs, ent_plot)
+        plot_constellation_map(Z, U, labels, map_plot)
+
+        tilt_gif = os.path.join(out_dir, "card_tilt.gif")
+        # small tilt gif (fast)
+        make_card_tilt_gif(card_rgb, tilt_gif, frames=18, fps=12)
+
+        STATE.update({
+            "Z": Z, "U": U, "labels": labels, "bins": bins_q,
+            "bin_path": bin_path, "codec_path": codec_path, "codec": codec,
+            "card_png_path": card_png_path,
+            "card_payload_len": payload_len,
+            "card_slab_top": slab_top,
+            "card_header": header2,
+            "model": None
+        })
+
+        report = (
+            f"## Trading Card Generated\n"
+            f"- **Embedding backend:** `{backend}`\n"
+            f"- **Units:** **{len(units)}**\n"
+            f"- **Constellations (K):** **{int(K)}**\n"
+            f"- **Radial bins:** **{int(radial_bins)}**\n"
+            f"- **Card width:** **{card_w}px**\n"
+            f"- **Payload bytes inside card:** **{payload_len}**\n"
+            f"- **Code bytes (constellation+radial):** **{len(code_bytes)}**\n"
+            f"- **MHEP score:** **{mhep:.1f}%**\n"
+            f"\n### Integrity\n"
+            f"- CRC32 match: **{str(ok_crc)}**\n"
+            f"- SHA256 match: **{str(ok_sha)}**\n"
+            f"- **Verified:** {'✅ YES' if verified else '❌ NO'}\n"
+            f"\n### Investor-proof constraint\n"
+            f"Training can now read **only** the **PNG trading card pixels**."
+        )
+
+        header_json = json.dumps(header2, indent=2)
+
+        return report, ent_plot, map_plot, card_png_path, tilt_gif, bin_path, codec_path, header_json
+    except Exception as e:
+        return f"Error: {e}\n\n{traceback.format_exc()}", None, None, None, None, None, None, None
+
+def train_from_card(train_steps, batch_size, block_size, lr, log_every,
+                    temperature, rollout_steps, make_gif, gif_stride, gif_fps, gif_max_frames):
+    """
+    Train byte-level transformer on bytes extracted from the trading card PNG.
+    Training uses ONLY the PNG pixels.
+    """
+    try:
+        card_png_path = STATE.get("card_png_path")
+        payload_len = STATE.get("card_payload_len")
+        slab_top = STATE.get("card_slab_top")
+        header = STATE.get("card_header")
+
+        if not card_png_path or not os.path.exists(card_png_path) or payload_len is None or slab_top is None:
+            return "No trading card found. Generate a card first.", None, None, None, None
+
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+
+        # Re-load card and extract payload bytes (PNG pixels only)
+        card_rgb = load_png(card_png_path)
+        extracted = extract_payload_from_card(card_rgb, slab_top=slab_top, slab_w=card_rgb.shape[1], payload_len=int(payload_len))
+
+        # Parse payload and verify again (still only from pixels)
+        header2, code_bytes = unpack_trading_card_payload(extracted)
+        ok_crc = (_crc32_u32(code_bytes) == int(header2["crc32"]))
+        ok_sha = (_sha256_hex(code_bytes) == str(header2["sha256"]))
+        verified = (ok_crc and ok_sha)
+
+        # Auto-tune for speed + guarantee it runs
+        L = len(extracted)  # training bytes are the full payload
+        user_block = int(block_size)
+        user_bs = int(batch_size)
+
+        tuned_block = min(user_block, max(32, L // 10))
+        tuned_block = min(tuned_block, max(32, L - 2))
+        block_size = int(tuned_block)
+
+        n_windows = max(0, L - block_size - 1)
+        tuned_bs = min(user_bs, max(8, n_windows // 4)) if n_windows > 0 else 1
+        batch_size = int(max(1, tuned_bs))
+
+        # Start context for sampling: from the payload bytes (not codes.bin)
+        start = list(extracted[:block_size])
+
+        out_dir = os.path.dirname(card_png_path)
+
+        # BEFORE rollout (untrained)
+        untrained = TinyByteTransformer(block_size=block_size).to(device)
+        before_seq = sample_bytes(untrained, start=start, steps=int(rollout_steps), device=device, temperature=float(temperature))
+        before_plot = os.path.join(out_dir, "rollout_before.png")
+        plot_rollout_tracks(before_seq[-int(rollout_steps):], before_plot, title="BEFORE training (random)")
+
+        # Train
+        model, losses, ppls = train_on_card_png(
+            card_png_path=card_png_path,
+            payload_len=int(payload_len),
+            slab_top=int(slab_top),
+            steps=int(train_steps),
+            batch_size=batch_size,
+            block_size=block_size,
+            lr=float(lr),
+            device=device,
+            log_every=int(log_every),
+        )
+        STATE["model"] = model
+
+        train_plot = os.path.join(out_dir, "training.png")
+        plot_training_curves(losses, ppls, train_plot)
+
+        # AFTER rollout
+        after_seq = sample_bytes(model, start=start, steps=int(rollout_steps), device=device, temperature=float(temperature))
+        after_plot = os.path.join(out_dir, "rollout_after.png")
+        plot_rollout_tracks(after_seq[-int(rollout_steps):], after_plot, title="AFTER training (trained)")
+
+        # Compare
+        compare_plot = os.path.join(out_dir, "rollout_compare.png")
+        plot_before_after_tracks(before_seq[-int(rollout_steps):], after_seq[-int(rollout_steps):], compare_plot)
+
+        # Optional GIF (cap frames)
+        gif_path = None
+        if bool(make_gif):
+            gif_path = os.path.join(out_dir, "rollout.gif")
+            # Make a lightweight GIF using the byte track plot frames (fast)
+            # We'll render a few frames by progressively revealing the curve
+            seq = after_seq[-int(rollout_steps):]
+            stride = max(1, int(gif_stride))
+            fps = max(6, int(gif_fps))
+            max_frames = max(12, int(gif_max_frames))
+
+            frames = []
+            count = 0
+            for t in range(10, len(seq), stride):
+                fig = plt.figure(figsize=(7,3.6))
+                plt.plot(seq[:t], linewidth=2)
+                plt.ylim(-2, 260)
+                plt.title("AFTER training — rollout from trading card pixels")
+                plt.xlabel("Step"); plt.ylabel("Byte value")
+                plt.tight_layout()
+                buf = io.BytesIO()
+                plt.savefig(buf, format="png", dpi=140)
+                plt.close(fig)
+                buf.seek(0)
+                frames.append(imageio.imread(buf))
+                count += 1
+                if count >= max_frames:
+                    break
+            imageio.mimsave(gif_path, frames, fps=fps)
+
+        report = (
+            f"## Training Complete (PNG-only)\n"
+            f"- **Device:** `{device}`\n"
+            f"- **Integrity (from pixels):** {'✅ Verified' if verified else '❌ Not verified'}\n"
+            f"- **Payload bytes used for training:** **{L}**\n"
+            f"- **Auto block_size:** **{block_size}** (requested {user_block})\n"
+            f"- **Auto batch_size:** **{batch_size}** (requested {user_bs})\n"
+            f"- **Steps:** **{int(train_steps)}** (logged every {int(log_every)})\n"
+            f"- **Final logged loss:** **{losses[-1]:.4f}**\n"
+            f"- **Final logged perplexity:** **{ppls[-1]:.2f}**\n"
+            f"\n### What investors should notice\n"
+            f"Perplexity falls while training from **a single trading card image**."
+        )
+
+        metrics = {"loss": losses, "ppl": ppls}
+        return report, train_plot, compare_plot, gif_path, json.dumps(metrics, indent=2)
+    except Exception as e:
+        return f"Training error: {e}\n\n{traceback.format_exc()}", None, None, None, None
+
+# -----------------------------
+# Gradio UI
+# -----------------------------
+INTRO = """
+# Trading Card Learning (Level 1)
+**Pipeline:**
+1) Compress dataset → **constellation/radial codes**
+2) Pack codes into a **single PNG trading card**
+3) Train a tiny model using **only the PNG pixels**
+
+This is the “data becomes a trading card” end goal.
+"""
+
+with gr.Blocks(title="Trading Card Learning (CHR)") as demo:
+    gr.Markdown(INTRO)
+
+    with gr.Tab("1) Ingest"):
+        with gr.Row():
+            file_in = gr.File(label="Upload .txt or .docx", file_types=[".txt", ".docx"])
+            units_mode = gr.Radio(["paragraphs", "sentences"], value="sentences", label="Unit granularity")
+        with gr.Row():
+            ingest_btn = gr.Button("Load file", variant="primary")
+            demo_btn = gr.Button("Load built-in demo corpus", variant="secondary")
+        ingest_status = gr.Markdown("")
+        ingest_btn.click(ingest_file, inputs=[file_in, units_mode], outputs=[ingest_status])
+        demo_btn.click(load_demo, inputs=[units_mode], outputs=[ingest_status])
+
+    with gr.Tab("2) Compress → Trading Card"):
+        with gr.Row():
+            K = gr.Slider(2, 48, value=16, step=1, label="K (constellations)")
+            iters = gr.Slider(5, 120, value=35, step=1, label="CHR iterations")
+            beta = gr.Slider(2, 30, value=16, step=1, label="beta (assignment sharpness)")
+        with gr.Row():
+            slab_bins = gr.Slider(3, 16, value=8, step=1, label="slab bins (entropy measure)")
+            tau = gr.Slider(1, 20, value=5, step=1, label="tau (slab softness)")
+            radial_bins = gr.Slider(8, 256, value=64, step=8, label="radial bins (compression alphabet)")
+            seed = gr.Slider(0, 9999, value=42, step=1, label="seed")
+        with gr.Row():
+            card_width = gr.Slider(128, 512, value=256, step=32, label="Card width (pixels)")
+            front_height = gr.Slider(96, 320, value=160, step=16, label="Front (holo) height (pixels)")
+            title_text = gr.Textbox(value="CHR Trading Card", label="Card title")
+
+        compress_btn = gr.Button("Generate Trading Card PNG", variant="primary")
+        compress_report = gr.Markdown("")
+        with gr.Row():
+            ent_img = gr.Image(label="Entropy during compression", type="filepath")
+            map_img = gr.Image(label="Constellation map (PCA)", type="filepath")
+        with gr.Row():
+            card_img = gr.Image(label="Trading Card PNG (contains the data)", type="filepath")
+            card_tilt = gr.Image(label="Holo tilt (GIF)", type="filepath")
+        with gr.Row():
+            codes_bin = gr.File(label="codes.bin (audit only)")
+            codec_json = gr.File(label="codec.json (audit only)")
+        card_header = gr.Code(label="Trading card header (from pixels)", language="json")
+
+        compress_btn.click(
+            compress_and_make_card,
+            inputs=[K, iters, beta, slab_bins, tau, seed, radial_bins, card_width, front_height, title_text],
+            outputs=[compress_report, ent_img, map_img, card_img, card_tilt, codes_bin, codec_json, card_header]
+        )
+
+    with gr.Tab("3) Train from Trading Card"):
+        with gr.Row():
+            train_steps = gr.Slider(50, 2000, value=250, step=50, label="training steps (fast demo default)")
+            batch_size = gr.Slider(4, 128, value=32, step=4, label="batch size")
+            block_size = gr.Slider(32, 256, value=128, step=16, label="sequence length (bytes)")
+        with gr.Row():
+            lr = gr.Number(value=5e-4, label="learning rate")
+            log_every = gr.Slider(10, 200, value=25, step=5, label="log every (steps)")
+            temperature = gr.Slider(0.5, 2.0, value=1.0, step=0.05, label="rollout temperature")
+            rollout_steps = gr.Slider(40, 400, value=120, step=20, label="rollout steps (bytes)")
+        with gr.Row():
+            make_gif = gr.Checkbox(value=False, label="Generate rollout GIF (adds time)")
+            gif_stride = gr.Slider(1, 12, value=5, step=1, label="GIF stride (higher = faster)")
+            gif_fps = gr.Slider(6, 24, value=12, step=1, label="GIF FPS")
+            gif_max_frames = gr.Slider(12, 120, value=40, step=4, label="GIF max frames (cap)")
+
+        train_btn = gr.Button("Train from PNG pixels + generate visuals", variant="primary")
+        train_report = gr.Markdown("")
+        with gr.Row():
+            train_img = gr.Image(label="Loss + perplexity", type="filepath")
+            compare_img = gr.Image(label="BEFORE vs AFTER rollout", type="filepath")
+        gif_out = gr.Image(label="Rollout GIF (optional)", type="filepath")
+        metrics_json = gr.Code(label="Metrics (JSON)", language="json")
+
+        train_btn.click(
+            train_from_card,
+            inputs=[train_steps, batch_size, block_size, lr, log_every, temperature, rollout_steps,
+                    make_gif, gif_stride, gif_fps, gif_max_frames],
+            outputs=[train_report, train_img, compare_img, gif_out, metrics_json]
+        )
+
+if __name__ == "__main__":
+    # Disable SSR for stability / fewer asyncio warnings in Spaces
+    demo.launch(ssr_mode=False)