ultragraph-1bit 0.1.0__tar.gz

ultragraph_1bit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Sync environment (incl. viz extra for matplotlib tests)
+        run: uv sync --extra viz --python ${{ matrix.python-version }}
+      - name: Lint (ruff)
+        run: uv run ruff check ultragraph tests examples assets
+      - name: Test (pytest)
+        run: uv run pytest

ultragraph_1bit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+# Publishes `ultragraph-1bit` via PyPI Trusted Publishing (OIDC) — no API token
+# stored in the repo. Fires when a GitHub Release is published, or manually.
+# One-time setup on PyPI: add a "pending" trusted publisher for project
+# `ultragraph-1bit`, owner `peterlodri-sec`, repo `ultra-graph`, workflow
+# `publish.yml` (no environment).
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

ultragraph_1bit-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.ug
+*.svg
+.venv/
+out/
+dist/

ultragraph_1bit-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project. Format follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-07-11
+
+The byte-graph that is a 1-bit (ternary) LLM.
+
+### Added
+- **Core** (`core.py`) — `Node`/`Edge`/`Tree`/`UltraEdge`/`UltraGraph`, the byte
+  buffers, the ad-hoc side store, and the dunder API (`node >> node` micro-edge,
+  `tree >> tree` ultra-edge, `len`/`iter`/`in`, `_repr_svg_`).
+- **Quantization** (`quant.py`) — ternary weights (absmean) + int8 activations
+  (absmax), with the small-`eps` / finite guards.
+- **Autograd** (`autograd.py`) — n-D reverse-mode tape: `+ - * / @`, `transpose`,
+  `swapaxes`, `reshape`, `relu`, `sqrt`, `sum`, `mean(axis)`, `softmax`,
+  `cross_entropy`; and `ternary_linear` with a straight-through estimator and
+  per-token int8 activation quantization.
+- **nn** (`nn.py`) — `linear_tree`, `mlp`, single-head `Attention`, batched
+  `MultiHeadAttention` (causal), `RMSNorm`, `LayerNorm`.
+- **Optimizers** (`optim.py`) — `SGD` and `Adam`, both with global-norm gradient
+  clipping; re-quantize the ternary buffers after each step.
+- **Visualization** (`viz.py`) — pure-SVG micro/macro/byte-heatmap views plus an
+  optional matplotlib backend (`[viz]` extra).
+- **I/O** (`io.py`) — byte-exact save/load.
+- **Examples** — `char_lm.py`, `transformer_lm.py`, `mini_gpt.py` (batched
+  multi-head transformer that memorizes a toy corpus), `render_viz.py`,
+  `make_figures.py`.
+- **Tests** — numeric-gradient checks for every op, an attention causality proof,
+  save/load byte-exactness, and end-to-end training; a dependency-free runner.
+- **Tooling & docs** — `ruff` (config in `pyproject.toml`), GitHub Actions CI
+  (`ruff` + `pytest` on Python 3.11–3.13), `CONTRIBUTING.md`, `CHANGELOG.md`, and
+  `docs/references.md` (an Erdős graph-theory reading list).
+
+[0.1.0]: https://github.com/peterlodri-sec/ultra-graph/releases/tag/v0.1.0

ultragraph_1bit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to ultragraph
+
+Thanks for poking at a byte-graph. It's a small, pure-Python (+ numpy) library, so
+the loop is short.
+
+## Setup
+
+Uses [uv](https://github.com/astral-sh/uv) and Python ≥ 3.11.
+
+```sh
+uv sync --extra viz     # core + dev (pytest, ruff) + matplotlib for viz tests
+```
+
+## The loop
+
+```sh
+just test        # pytest (or: uv run pytest)
+just test-fast   # dependency-free runner (stdlib + numpy only)
+uv run ruff check ultragraph tests examples assets   # lint
+just demo        # end-to-end ternary mini-GPT
+just viz         # render example graphs
+```
+
+CI (`.github/workflows/ci.yml`) runs `ruff check` + `pytest` on Python 3.11–3.13.
+Both must be green before merge.
+
+## Conventions
+
+- **Correctness first.** New autograd ops need a numeric-gradient test
+  (`tests/test_autograd.py` has the pattern: analytic backward vs central finite
+  differences). Quantized paths are checked against their unquantized surrogate
+  (that's what STE claims).
+- **The byte contract holds.** One node = one byte (`int8` activation), one edge =
+  one byte (ternary weight). Anything bigger than a byte lives in the ad-hoc side
+  store, not the hot buffers.
+- **Keep files focused.** Match the surrounding style: `ruff` config in
+  `pyproject.toml` (`select = F, E7, E9, I`); imports sorted.
+- **numpy is the only runtime dependency.** `matplotlib` is optional (`[viz]`
+  extra); the SVG backend stays stdlib-only.
+
+## Pull requests
+
+Small, focused PRs. Include tests. Run `ruff check` + `pytest` locally first. Say
+what you changed and why in the description.

ultragraph_1bit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Lodri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ultragraph_1bit-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: ultragraph-1bit
+Version: 0.1.0
+Summary: A pure-Python (+numpy) byte-graph that is a 1-bit (ternary) LLM: dunder API, autograd, ultra-edges, visualization.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.0
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# ultragraph
+
+[![CI](https://github.com/peterlodri-sec/ultra-graph/actions/workflows/ci.yml/badge.svg)](https://github.com/peterlodri-sec/ultra-graph/actions/workflows/ci.yml)
+[![python](https://img.shields.io/badge/python-3.11%2B-00d4ff)](pyproject.toml)
+[![license](https://img.shields.io/badge/license-MIT-b48bff)](LICENSE)
+
+A pure-Python (+ numpy) **byte-graph that is a 1-bit (ternary) LLM**.
+
+> **genesis** `251e6ea` · themed after [pocoo.vaked.dev](https://pocoo.vaked.dev)
+
+![ultragraph architecture — micro (node/edge, 1 byte each) → meso (tree) → macro (ultra-graph)](assets/architecture.png)
+
+Three levels:
+
+| level | unit | storage |
+|-------|------|---------|
+| micro | **node** / **edge** | **1 byte each** — `int8` activation / ternary weight `{-1,0,+1}` |
+| meso  | **tree** | a whole graph == one net/module (a Linear/MLP block) |
+| macro | **ultra-edge** (`===`) | typed wiring between trees → the **ultra-graph** = the model |
+
+Weights are ternary (BitNet b1.58 style); activations are int8. Full-precision
+"master" weights live in an ad-hoc side store during training; the byte buffers are
+the deployed state. Training uses a straight-through estimator (STE).
+
+## Illustrations
+
+Real outputs from a trained ternary mini-GPT — regenerate with `uv run python assets/make_figures.py`:
+
+| ultra-graph | causal attention | ternary weight bytes |
+|:---:|:---:|:---:|
+| ![architecture](assets/fig_architecture.png) | ![attention](assets/fig_attention.png) | ![weights](assets/fig_ternary_weights.png) |
+
+Left: the model as an **ultra-graph** — trees wired by ultra-edges (`===`), with residual skips.
+Middle: **real** causal self-attention weights (lower-triangular → no peeking at the future).
+Right: a trained query projection's weight bytes, each ∈ {−1, 0, +1}.
+
+## Install
+
+```sh
+pip install ultragraph-1bit    # then: import ultragraph
+# or from source (Python >=3.11):
+uv sync
+```
+
+## Dunder API
+
+`>>` is overloaded by operand type:
+
+```python
+import numpy as np
+from ultragraph import Tree, UltraGraph, Tensor, mlp, SGD
+
+# micro-edges inside a sparse tree
+g = Tree(4, "g")
+g[0] >> g[1]        # node >> node  -> micro-edge
+g[2] = 7            # set a node byte
+print(len(g), 2 in g, list(g))
+
+# ultra-edges between trees
+ug = UltraGraph()
+a = ug.add(Tree.dense(8, 16, "a"))
+b = ug.add(Tree.dense(16, 4, "b", act="none"))
+a >> b              # tree >> tree -> ultra-edge (plain)
+a.wire(b, "residual")
+```
+
+## Train a tiny ternary net
+
+```python
+ug = mlp([4, 16, 2])                 # dense ternary linear trees wired plain
+opt = SGD(ug, lr=0.3, momentum=0.9)
+x = Tensor(np.random.randn(32, 4).astype("float32"))
+for _ in range(300):
+    loss = ug.forward(x).cross_entropy(y)
+    opt.zero_grad(); loss.backward(); opt.step()   # step() re-quantizes weights
+```
+
+See `examples/char_lm.py` (MLP LM), `examples/transformer_lm.py` (single-head attention),
+and `examples/mini_gpt.py` (batched **multi-head** attention + **RMSNorm** + **Adam**) for
+end-to-end char-level ternary language models.
+
+```python
+from ultragraph import Embedding, MultiHeadAttention, RMSNorm, linear_tree, Adam
+# pre-norm transformer block over a [B, T, d_model] sequence:
+#   x = x + mha(norm1(x));  x = x + ff2(ff1(norm2(x)))
+```
+
+## Tasks
+
+```sh
+just test        # pytest
+just test-fast   # dependency-free runner (stdlib + numpy)
+just demo        # char-LM end-to-end
+just viz         # render example SVGs
+```
+
+## Layout
+
+```
+ultragraph/quant.py     ternary + int8 quantization, STE
+ultragraph/autograd.py  numpy autograd tape; ternary_linear (STE)
+ultragraph/core.py      Node/Edge/Tree/UltraEdge/UltraGraph + dunder API
+ultragraph/nn.py        linear_tree, mlp, Attention, MultiHeadAttention, RMSNorm, LayerNorm
+ultragraph/optim.py     SGD + Adam over fp32 masters (grad clip), re-quantize after step
+ultragraph/viz.py       pure-SVG + optional matplotlib (micro / macro / byte-heatmap)
+ultragraph/io.py        byte-exact save / load
+```
+
+Design spec: `docs/superpowers/specs/2026-07-10-ultragraph-design.md`.
+Graph-theory reading list (Erdős classics): [`docs/references.md`](docs/references.md).
+
+## Install from source
+
+```sh
+git clone https://github.com/peterlodri-sec/ultra-graph
+cd ultra-graph
+uv sync
+just test
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ultragraph_1bit-0.1.0/README.md

@@ -0,0 +1,123 @@
+# ultragraph
+
+[![CI](https://github.com/peterlodri-sec/ultra-graph/actions/workflows/ci.yml/badge.svg)](https://github.com/peterlodri-sec/ultra-graph/actions/workflows/ci.yml)
+[![python](https://img.shields.io/badge/python-3.11%2B-00d4ff)](pyproject.toml)
+[![license](https://img.shields.io/badge/license-MIT-b48bff)](LICENSE)
+
+A pure-Python (+ numpy) **byte-graph that is a 1-bit (ternary) LLM**.
+
+> **genesis** `251e6ea` · themed after [pocoo.vaked.dev](https://pocoo.vaked.dev)
+
+![ultragraph architecture — micro (node/edge, 1 byte each) → meso (tree) → macro (ultra-graph)](assets/architecture.png)
+
+Three levels:
+
+| level | unit | storage |
+|-------|------|---------|
+| micro | **node** / **edge** | **1 byte each** — `int8` activation / ternary weight `{-1,0,+1}` |
+| meso  | **tree** | a whole graph == one net/module (a Linear/MLP block) |
+| macro | **ultra-edge** (`===`) | typed wiring between trees → the **ultra-graph** = the model |
+
+Weights are ternary (BitNet b1.58 style); activations are int8. Full-precision
+"master" weights live in an ad-hoc side store during training; the byte buffers are
+the deployed state. Training uses a straight-through estimator (STE).
+
+## Illustrations
+
+Real outputs from a trained ternary mini-GPT — regenerate with `uv run python assets/make_figures.py`:
+
+| ultra-graph | causal attention | ternary weight bytes |
+|:---:|:---:|:---:|
+| ![architecture](assets/fig_architecture.png) | ![attention](assets/fig_attention.png) | ![weights](assets/fig_ternary_weights.png) |
+
+Left: the model as an **ultra-graph** — trees wired by ultra-edges (`===`), with residual skips.
+Middle: **real** causal self-attention weights (lower-triangular → no peeking at the future).
+Right: a trained query projection's weight bytes, each ∈ {−1, 0, +1}.
+
+## Install
+
+```sh
+pip install ultragraph-1bit    # then: import ultragraph
+# or from source (Python >=3.11):
+uv sync
+```
+
+## Dunder API
+
+`>>` is overloaded by operand type:
+
+```python
+import numpy as np
+from ultragraph import Tree, UltraGraph, Tensor, mlp, SGD
+
+# micro-edges inside a sparse tree
+g = Tree(4, "g")
+g[0] >> g[1]        # node >> node  -> micro-edge
+g[2] = 7            # set a node byte
+print(len(g), 2 in g, list(g))
+
+# ultra-edges between trees
+ug = UltraGraph()
+a = ug.add(Tree.dense(8, 16, "a"))
+b = ug.add(Tree.dense(16, 4, "b", act="none"))
+a >> b              # tree >> tree -> ultra-edge (plain)
+a.wire(b, "residual")
+```
+
+## Train a tiny ternary net
+
+```python
+ug = mlp([4, 16, 2])                 # dense ternary linear trees wired plain
+opt = SGD(ug, lr=0.3, momentum=0.9)
+x = Tensor(np.random.randn(32, 4).astype("float32"))
+for _ in range(300):
+    loss = ug.forward(x).cross_entropy(y)
+    opt.zero_grad(); loss.backward(); opt.step()   # step() re-quantizes weights
+```
+
+See `examples/char_lm.py` (MLP LM), `examples/transformer_lm.py` (single-head attention),
+and `examples/mini_gpt.py` (batched **multi-head** attention + **RMSNorm** + **Adam**) for
+end-to-end char-level ternary language models.
+
+```python
+from ultragraph import Embedding, MultiHeadAttention, RMSNorm, linear_tree, Adam
+# pre-norm transformer block over a [B, T, d_model] sequence:
+#   x = x + mha(norm1(x));  x = x + ff2(ff1(norm2(x)))
+```
+
+## Tasks
+
+```sh
+just test        # pytest
+just test-fast   # dependency-free runner (stdlib + numpy)
+just demo        # char-LM end-to-end
+just viz         # render example SVGs
+```
+
+## Layout
+
+```
+ultragraph/quant.py     ternary + int8 quantization, STE
+ultragraph/autograd.py  numpy autograd tape; ternary_linear (STE)
+ultragraph/core.py      Node/Edge/Tree/UltraEdge/UltraGraph + dunder API
+ultragraph/nn.py        linear_tree, mlp, Attention, MultiHeadAttention, RMSNorm, LayerNorm
+ultragraph/optim.py     SGD + Adam over fp32 masters (grad clip), re-quantize after step
+ultragraph/viz.py       pure-SVG + optional matplotlib (micro / macro / byte-heatmap)
+ultragraph/io.py        byte-exact save / load
+```
+
+Design spec: `docs/superpowers/specs/2026-07-10-ultragraph-design.md`.
+Graph-theory reading list (Erdős classics): [`docs/references.md`](docs/references.md).
+
+## Install from source
+
+```sh
+git clone https://github.com/peterlodri-sec/ultra-graph
+cd ultra-graph
+uv sync
+just test
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ultragraph_1bit-0.1.0/assets/make_figures.py

@@ -0,0 +1,201 @@
+"""Generate themed illustrations for the README from a REAL trained model.
+
+Palette matches pocoo.vaked.dev: deep navy background with cyan / green / purple
+accents. Figures are produced from an actual mini-GPT forward pass (ternary
+weights, causal attention matrix) plus an architecture diagram.
+
+Run: uv run python assets/make_figures.py
+"""
+from __future__ import annotations
+
+import math
+import os
+
+import matplotlib
+import numpy as np
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from matplotlib.colors import LinearSegmentedColormap
+from matplotlib.patches import FancyArrowPatch, FancyBboxPatch
+
+from ultragraph import Adam, Embedding, MultiHeadAttention, RMSNorm, Tensor, UltraGraph, linear_tree
+
+BG = "#070b16"
+PANEL = "#0b1120"
+CYAN = "#00d4ff"
+GREEN = "#00e660"
+PURPLE = "#b48bff"
+FG = "#c8d3e6"
+MUTED = "#4a5a80"
+
+OUT = os.path.join(os.path.dirname(__file__))
+
+# purple -> navy -> cyan, for ternary weights in {-1, 0, +1}
+TERNARY_CMAP = LinearSegmentedColormap.from_list("ug_ternary", [PURPLE, "#0e1730", CYAN])
+# navy -> cyan, sequential, for attention weights in [0, 1]
+ATTN_CMAP = LinearSegmentedColormap.from_list("ug_attn", ["#0a1024", "#0f5c78", CYAN])
+
+
+def _style(ax):
+    ax.set_facecolor(BG)
+    for s in ax.spines.values():
+        s.set_color(MUTED)
+    ax.tick_params(colors=FG, labelsize=8)
+    ax.xaxis.label.set_color(FG)
+    ax.yaxis.label.set_color(FG)
+    ax.title.set_color(FG)
+
+
+def _save(fig, name):
+    path = os.path.join(OUT, name)
+    fig.savefig(path, dpi=150, bbox_inches="tight", facecolor=BG)
+    plt.close(fig)
+    print("wrote", path)
+    return path
+
+
+def train_model():
+    np.random.seed(0)
+    text = "hello ultra graph world " * 4
+    chars = sorted(set(text))
+    stoi = {c: i for i, c in enumerate(chars)}
+    vocab = len(chars)
+    d_model, n_heads, T = 24, 4, 8
+    ids = np.array([stoi[c] for c in text], dtype=np.int64)
+    seqs = np.stack([ids[i : i + T + 1] for i in range(len(ids) - T)])
+    inputs, targets = seqs[:, :-1], seqs[:, 1:]
+    B = inputs.shape[0]
+
+    emb = Embedding(vocab, d_model, "emb")
+    n1 = RMSNorm(d_model, name="n1")
+    mha = MultiHeadAttention(d_model, n_heads, causal=True)
+    n2 = RMSNorm(d_model, name="n2")
+    ff1 = linear_tree(d_model, 4 * d_model, "ff1", act="relu")
+    ff2 = linear_tree(4 * d_model, d_model, "ff2", act="none")
+    unembed = linear_tree(d_model, vocab, "unembed", act="none")
+    model = UltraGraph("mini_gpt")
+    for m in (emb, n1, mha, n2):
+        model.register(m)
+    for t in (ff1, ff2, unembed):
+        model.add(t)
+    opt = Adam(model, lr=0.02, clip=1.0)
+
+    def forward(idx):
+        x = emb(idx.reshape(-1)).reshape(B, idx.shape[1], d_model)
+        x = x + mha(n1(x))
+        x = x + ff2.forward(ff1.forward(n2(x)))
+        return unembed.forward(x)
+
+    for _ in range(300):
+        loss = forward(inputs).cross_entropy(targets)
+        opt.zero_grad()
+        loss.backward()
+        opt.step()
+    return dict(mha=mha, n1=n1, emb=emb, inputs=inputs, T=T, d_model=d_model, n_heads=n_heads, B=B)
+
+
+def fig_ternary_weights(m):
+    """Real ternary weight matrix from the trained attention query projection."""
+    wq = m["mha"].wq.wq  # int8 {-1,0,1}, shape [d_model, d_model]
+    fig, ax = plt.subplots(figsize=(4.6, 4.2))
+    fig.patch.set_facecolor(BG)
+    im = ax.imshow(wq, cmap=TERNARY_CMAP, vmin=-1, vmax=1, interpolation="nearest")
+    _style(ax)
+    ax.set_title("ternary weight bytes  ·  W_q  ∈ {-1, 0, +1}", fontsize=10)
+    ax.set_xlabel("in")
+    ax.set_ylabel("out")
+    cb = fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04, ticks=[-1, 0, 1])
+    cb.ax.yaxis.set_tick_params(color=FG)
+    plt.setp(plt.getp(cb.ax.axes, "yticklabels"), color=FG)
+    return _save(fig, "fig_ternary_weights.png")
+
+
+def fig_attention(m):
+    """Real causal attention weights (head 0) from a forward pass."""
+    mha, n1, emb = m["mha"], m["n1"], m["emb"]
+    T, d, H = m["T"], m["d_model"], m["n_heads"]
+    dh = d // H
+    x = emb(m["inputs"][0]).reshape(1, T, d)
+    xn = n1(x)
+    q = mha.wq.forward(xn).reshape(1, T, H, dh).swapaxes(1, 2)
+    k = mha.wk.forward(xn).reshape(1, T, H, dh).swapaxes(1, 2)
+    scores = (q @ k.swapaxes(-1, -2)) * (1.0 / math.sqrt(dh))
+    mask = np.triu(np.full((T, T), -1e9, dtype=np.float32), k=1)
+    attn = (scores + Tensor(mask)).softmax(axis=-1).data[0, 0]  # [T, T]
+
+    fig, ax = plt.subplots(figsize=(4.6, 4.2))
+    fig.patch.set_facecolor(BG)
+    im = ax.imshow(attn, cmap=ATTN_CMAP, vmin=0, vmax=1, interpolation="nearest")
+    _style(ax)
+    ax.set_title("causal self-attention  ·  softmax(QKᵀ/√d)", fontsize=10)
+    ax.set_xlabel("key position")
+    ax.set_ylabel("query position")
+    cb = fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04)
+    cb.ax.yaxis.set_tick_params(color=FG)
+    plt.setp(plt.getp(cb.ax.axes, "yticklabels"), color=FG)
+    return _save(fig, "fig_attention.png")
+
+
+def fig_architecture():
+    """Ultra-graph view of the mini-GPT block: trees wired by ultra-edges."""
+    fig, ax = plt.subplots(figsize=(5.2, 6.4))
+    fig.patch.set_facecolor(BG)
+    ax.set_facecolor(BG)
+    ax.set_xlim(0, 10)
+    ax.set_ylim(0, 13)
+    ax.axis("off")
+
+    def box(y, label, color, sub=""):
+        b = FancyBboxPatch((2.6, y), 4.8, 1.0, boxstyle="round,pad=0.08,rounding_size=0.18",
+                           linewidth=1.6, edgecolor=color, facecolor=PANEL)
+        ax.add_patch(b)
+        ax.text(5.0, y + 0.62, label, ha="center", va="center", color=FG, fontsize=10, fontweight="bold")
+        if sub:
+            ax.text(5.0, y + 0.28, sub, ha="center", va="center", color=MUTED, fontsize=7.5)
+        return y
+
+    layers = [
+        (11.4, "Embedding", GREEN, "vocab → d_model"),
+        (9.6, "RMSNorm", PURPLE, ""),
+        (8.2, "MultiHeadAttention", CYAN, "ternary Q·K·V·O, causal"),
+        (6.4, "RMSNorm", PURPLE, ""),
+        (5.0, "MLP (ternary)", CYAN, "ff1 relu · ff2"),
+        (3.0, "Unembed", GREEN, "d_model → vocab"),
+    ]
+    for y, lab, col, sub in layers:
+        box(y, lab, col, sub)
+
+    def arrow(y0, y1, color=FG, curve=0.0, lw=1.4):
+        a = FancyArrowPatch((5.0, y0), (5.0, y1), connectionstyle=f"arc3,rad={curve}",
+                            arrowstyle="-|>", mutation_scale=12, color=color, lw=lw)
+        ax.add_patch(a)
+
+    arrow(11.4, 10.6)      # emb -> norm
+    arrow(9.6, 9.2)        # norm -> attn
+    arrow(8.2, 7.4)        # attn -> norm2
+    arrow(6.4, 6.0)        # norm2 -> mlp
+    arrow(5.0, 4.0)        # mlp -> unembed
+    # residual ultra-edges (curved, on the right)
+    for y0, y1, c in [(11.4, 8.2, CYAN), (8.2, 5.0, CYAN)]:
+        a = FancyArrowPatch((7.4, y0 + 0.5), (7.4, y1 + 0.5), connectionstyle="arc3,rad=-0.5",
+                            arrowstyle="-|>", mutation_scale=11, color=c, lw=1.2, linestyle=(0, (4, 2)))
+        ax.add_patch(a)
+        ax.text(9.0, (y0 + y1) / 2 + 0.5, "===", ha="center", va="center", color=c, fontsize=9, rotation=90)
+
+    ax.text(5.0, 12.5, "ultra-graph  ·  trees wired by ultra-edges (===)", ha="center",
+            color=FG, fontsize=11, fontweight="bold")
+    ax.text(5.0, 2.2, "every weight = 1 ternary byte  ·  every activation = 1 int8 byte",
+            ha="center", color=MUTED, fontsize=8)
+    return _save(fig, "fig_architecture.png")
+
+
+def main():
+    m = train_model()
+    fig_ternary_weights(m)
+    fig_attention(m)
+    fig_architecture()
+
+
+if __name__ == "__main__":
+    main()

ultragraph_1bit-0.1.0/docs/references.md

@@ -0,0 +1,34 @@
+# References — a graph theory reading list
+
+`ultragraph` is a byte-graph, so it owes a debt to graph theory. This is a short,
+opinionated reading list of Paul Erdős's most important graph-theory (and
+graph-theorist-adjacent combinatorics) publications — the classics every graph
+person eventually meets.
+
+Citation details were checked against the Wikipedia articles for the named
+theorems, the journals (Oxford Academic / Cambridge Core / Springer / AMS), and
+the Rényi Institute's Erdős archive. A few conjecture citations are flagged where
+a canonical volume/page could not be confirmed.
+
+### Foundational papers
+
+- **Erdős, P. & Szekeres, G. (1935).** "A combinatorial problem in geometry." *Compositio Mathematica*, 2, 463–470. [numdam](http://www.numdam.org/item/CM_1935__2__463_0/) — The Erdős–Szekeres theorem: any sequence longer than $(r-1)(s-1)$ has a monotone subsequence of length $r$ or $s$. A founding result of Ramsey theory (the "happy ending problem").
+- **Erdős, P. & Stone, A. H. (1946).** "On the structure of linear graphs." *Bulletin of the AMS*, 52(12), 1087–1091. [doi:10.1090/S0002-9904-1946-08715-7](https://doi.org/10.1090/S0002-9904-1946-08715-7) — The Erdős–Stone theorem fixes the asymptotic maximum edge count of graphs forbidding a fixed subgraph — the "fundamental theorem of extremal graph theory," generalizing Turán.
+- **Erdős, P. (1947).** "Some remarks on the theory of graphs." *Bulletin of the AMS*, 53(4), 292–294. [doi:10.1090/S0002-9904-1947-08785-1](https://doi.org/10.1090/S0002-9904-1947-08785-1) — The probabilistic lower bound $R(k,k) > 2^{k/2}$ for Ramsey numbers; launched the probabilistic method.
+- **Erdős, P. & Rényi, A. (1959).** "On random graphs. I." *Publicationes Mathematicae Debrecen*, 6, 290–297. [doi:10.5486/PMD.1959.6.3-4.12](https://doi.org/10.5486/PMD.1959.6.3-4.12) — Introduced the $G(n,m)$ random-graph model; founded the theory of random graphs.
+- **Erdős, P. & Rényi, A. (1960).** "On the evolution of random graphs." *Publ. Math. Inst. Hungar. Acad. Sci.*, 5, 17–61. [PDF](https://www.renyi.hu/~p_erdos/1960-10.pdf) (no DOI) — The phase-transition / giant-component paper; foundational for modern network science.
+- **Erdős, P. & Gallai, T. (1960).** "Gráfok előírt fokszámú pontokkal" [Graphs with vertices of prescribed degrees]. *Matematikai Lapok*, 11, 264–274. [PDF](https://www.renyi.hu/~p_erdos/1961-05.pdf) (no DOI) — The Erdős–Gallai theorem: the inequalities that decide when an integer sequence is *graphic* (a degree sequence of a simple graph).
+- **Erdős, P. (1959).** "Graph theory and probability." *Canadian Journal of Mathematics*, 11, 34–38. [doi:10.4153/CJM-1959-003-9](https://doi.org/10.4153/CJM-1959-003-9) — Graphs with simultaneously arbitrarily high girth *and* high chromatic number exist — a celebrated nonconstructive result.
+- **Erdős, P., Ko, C. & Rado, R. (1961).** "Intersection theorems for systems of finite sets." *Quarterly J. of Mathematics* (Oxford, 2nd Ser.), 12, 313–320. [doi:10.1093/qmath/12.1.313](https://doi.org/10.1093/qmath/12.1.313) — The Erdős–Ko–Rado theorem bounds the largest intersecting family of $k$-subsets; a cornerstone of extremal set theory.
+- **Erdős, P., Rényi, A. & Sós, V. T. (1966).** "On a problem of graph theory." *Studia Sci. Math. Hungar.*, 1, 215–235. [PDF](https://www.renyi.hu/~p_erdos/1966-06.pdf) (no DOI) — The friendship theorem: if every two vertices share exactly one common neighbour, the graph is a windmill.
+
+### Conjectures
+
+- **Erdős–Faber–Lovász** (1972; recorded in Erdős, P. (1981), "On the combinatorial problems which I would most like to see solved," *Combinatorica*, 1(1), 25–42, [doi:10.1007/BF02579174](https://doi.org/10.1007/BF02579174)). [wiki](https://en.wikipedia.org/wiki/Erd%C5%91s%E2%80%93Faber%E2%80%93Lov%C3%A1sz_conjecture) — The union of $k$ cliques of size $k$ pairwise sharing ≤1 vertex is $k$-colourable. Proved for all large $k$ in 2023 (Kang–Kelly–Kühn–Methuku–Osthus).
+- **Erdős–Sós** (posed ~1962; stated in Erdős, P. (1964), "Extremal problems in graph theory," in *Theory of Graphs and Its Applications* (Proc. Sympos. Smolenice 1963), Czechoslovak Acad. Sci., pp. 29–36; no DOI). [Erdős list](https://www.emis.de/classics/Erdos/extrram.htm) — Any graph with more than $(k-1)n/2$ edges contains every tree with $k$ edges. *(Exact page range as commonly cited; volume not viewed directly.)*
+- **Erdős–Hajnal** (Erdős, P. & Hajnal, A. (1977), "On spanned subgraphs of graphs," in *Contributions to Graph Theory and Its Applications*, Ilmenau, pp. 80–96; often cited via their (1989) "Ramsey-type theorems," *Discrete Applied Mathematics*, 25(1–2), 37–52). [wiki](https://en.wikipedia.org/wiki/Erd%C5%91s%E2%80%93Hajnal_conjecture) — Graphs omitting a fixed induced subgraph contain a clique or independent set of polynomial size $n^{c}$. Major open problem.
+- **Erdős–Gyárfás** (Erdős & Gyárfás, 1995). [wiki](https://en.wikipedia.org/wiki/Erd%C5%91s%E2%80%93Gy%C3%A1rf%C3%A1s_conjecture) · [West](http://dwest.web.illinois.edu/openp/2powcyc.html) — Every graph with minimum degree ≥ 3 has a cycle whose length is a power of two. *(Posed at a conference; no single origin paper — citation details unverified.)*
+
+---
+
+Compiled 2026-07-11; verify anything you plan to cite. `ultragraph` genesis `251e6ea`.