livefold 0.1.0__tar.gz

livefold-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+.idea
+scripts/

livefold-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Danny
+
+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.

livefold-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: livefold
+Version: 0.1.0
+Summary: A primitive for online sequential aggregation in Python
+Project-URL: Source code, https://github.com/danielenricocahall/livefold
+Author: Daniel Cahall
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# livefold
+
+*live + fold — incremental folds over a mutable sequence.*
+
+[![Build Status](https://github.com/danielenricocahall/livefold/actions/workflows/ci.yaml/badge.svg)](https://github.com/danielenricocahall/livefold/actions/workflows/ci.yaml)
+[![Supported Versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://github.com/danielenricocahall/livefold/blob/main/pyproject.toml)
+[![license](https://img.shields.io/github/license/danielenricocahall/livefold.svg)](https://github.com/danielenricocahall/livefold/blob/main/LICENSE)
+
+> A primitive for online sequential aggregation in Python.
+> Maintain a mutable numeric sequence; query exact aggregates over any range
+> in **O(√n)**; plug in any associative reducer (any monoid).
+
+## When to reach for it
+
+| Need | Use |
+|---|---|
+| Immutable series, range aggregates | Prefix sums |
+| Frequent point updates, log-time queries | Segment tree / Fenwick tree |
+| Fixed-width rolling windows | `pandas.rolling()` / `polars.rolling()` |
+| **Mutable series, arbitrary range queries, multi-fold** | **livefold** |
+
+Common shapes: request latencies, sensor readings, trade prices, telemetry events.
+
+## Quickstart
+
+```bash
+pip install livefold
+```
+
+```python
+from livefold import LiveFold
+
+lf = LiveFold([1, 2, 3, 4, 5, 6], folds={"sum": sum, "max": max, "min": min})
+
+lf.append(7)
+lf.query(0, 5)
+# → {"sum": 21, "max": 6, "min": 1}
+
+# Mutate freely; aggregates stay current
+lf[2] = -1
+lf.query(2, 5)
+# → {"sum": 9, "max": 6, "min": -1}
+```
+
+## Performance
+
+![Query latency vs collection size](https://raw.githubusercontent.com/danielenricocahall/livefold/main/benchmarks/plots/query_latency.png)
+
+At n = 10⁷, `livefold`'s median range query is **69 µs vs naive Python's 29 ms** (~400× faster), and median append cost is **~2 µs across all n** while every other backend with a competitive query path (numpy, pandas) degrades linearly on *every* append. livefold's amortized append is O(√n) — boundary-crossing rebuilds are rare (~one per √n appends) but real — so the median characterizes typical streaming latency, not the rare rebuild spike.
+
+Full methodology, append benchmarks, comparison against four backends, and the reproduction script: [`benchmarks/`](https://github.com/danielenricocahall/livefold/tree/main/benchmarks).
+
+## Examples
+
+Two runnable Streamlit demos in [`examples/`](https://github.com/danielenricocahall/livefold/tree/main/examples):
+
+- **[`system_metrics/`](https://github.com/danielenricocahall/livefold/tree/main/examples/system_metrics)** — live `psutil`-driven CPU/memory dashboard with arbitrary-range aggregate queries. Runs entirely offline.
+- **[`crypto_ticks/`](https://github.com/danielenricocahall/livefold/tree/main/examples/crypto_ticks)** — synthetic BTC/USD tick stream with high/low/avg-price queries. Includes a drop-in recipe for real Binance ticks.
+
+
+## API
+
+```python
+LiveFold(data: Iterable, folds: dict[str, Callable])
+```
+
+| Member | Returns | Notes |
+|---|---|---|
+| `lf.append(x)` | `None` | Amortized O(√n); worst-case O(n) on perfect-square crossings |
+| `lf.query(left, right)` | `dict[str, Any]` | O(√n); inclusive bounds |
+| `lf.blocks` | `list[list]` | Underlying √n-sized blocks |
+| `lf.folded_values` | `dict[str, list]` | Per-fold, per-block aggregates |
+| `lf.insert / pop / extend / remove / sort / ...` | — | Standard `list` methods; blocks and folds updated in place |
+
+`LiveFold` subclasses `list`, so it's a drop-in for any code that expected a plain list — until you start calling `query`.
+
+## Time-indexed queries: `TimeIndexedLiveFold`
+
+For monotonic streams where you want to query by *time* instead of *index*, `TimeIndexedLiveFold` carries a parallel timestamp per element and exposes `query_time_range` — still O(√n).
+
+```python
+from livefold import TimeIndexedLiveFold
+
+lf = TimeIndexedLiveFold(
+    [1, 2, 3],
+    folds={"sum": sum, "max": max},
+    timestamps=[1.0, 2.0, 3.0],
+)
+lf.append(4, timestamp=4.0)
+lf.append(5, timestamp=5.0)
+
+lf.query_time_range(2.0, 4.0)
+# → {"sum": 9, "max": 4}
+```
+
+If you omit `timestamps` / `timestamp`, `time.time()` is used by default. The class is generic over the timestamp type — anything orderable works (`float`, `int`, `datetime`, ...). Pass explicit timestamps for any non-`float` type:
+
+```python
+from datetime import datetime
+from livefold import TimeIndexedLiveFold
+
+lf = TimeIndexedLiveFold[datetime](
+    [1, 2, 3],
+    folds={"sum": sum},
+    timestamps=[datetime(2025, 1, 1), datetime(2025, 6, 1), datetime(2026, 1, 1)],
+)
+lf.query_time_range(datetime(2025, 5, 1), datetime(2026, 6, 1))
+# → {"sum": 5}
+```
+
+`TimeIndexedLiveFold` is **append-only by design**. Operations that would break time ordering raise `MonotonicityError`:
+
+- `insert`, `sort`, `reverse` — would break the ordering invariant
+- slice `__setitem__`, slice `__delitem__` — would desync data and timestamps
+- `append` / `extend` with a timestamp earlier than the last stored one
+- `+` / `+=` with anything other than another `TimeIndexedLiveFold` (use `extend(values, timestamps=...)` instead)
+
+Integer indexing (`lf[i] = x`, `del lf[i]`), `pop`, `remove`, and `clear` work normally and keep the parallel timestamp list in sync. `+` and `+=` between two `TimeIndexedLiveFold` instances concatenate timestamps and re-check monotonicity.
+
+## How it works
+
+![Query animation](https://raw.githubusercontent.com/danielenricocahall/livefold/main/assets/query_animation.gif)
+
+`LiveFold` splits its underlying list into ⌊√n⌋ blocks of size √n, precomputes the configured folds for each block, and updates them incrementally on mutation. A `query(left, right)` walks at most two partial blocks plus the precomputed folds for whole-block spans in between — touching roughly 2√n elements per fold regardless of n. Mo's algorithm with mutability and a dict-shaped output.
+
+![Append re-block animation](https://raw.githubusercontent.com/danielenricocahall/livefold/main/assets/resize_animation.gif)
+
+`append` is **amortized O(√n)**. Most appends just push onto the last block at O(1), but each time `n` crosses a perfect square, `block_size = isqrt(n)` increments and the whole structure re-blocks — an O(n) cost. The gap between consecutive perfect squares is `2k + 1` (linear in `k = √n`, not geometric), so over `n` appends total rebuild work sums to Σ_{k=1}^{√n} O(k²) = O(n^(3/2)) — i.e. O(√n) per append amortized. Boundary crossings happen only ~once per √n appends, though, so the *median* append latency stays in the low µs range across all `n` (this is what the benchmarks show); the asymptotic only shows up in mean or total cost.
+
+`TimeIndexedLiveFold` layers a parallel monotonically non-decreasing timestamp list on top. `query_time_range(start, end)` calls `bisect_left`/`bisect_right` to map timestamps to indices in O(log n), then routes through the same √n-decomposed query path — so overall query cost stays O(√n).
+
+For the full derivation, complexity analysis, and other implementation details, see the [corresponding blog post](https://dannycahall.substack.com/p/square-root-decomposition-made-mutable).
+
+> *Note: the blog post predates the rebrand from `pysquagg` and uses the old singular `aggregator_function=` API. The math and structural choices are unchanged; only the package name and the `folds={"name": fn, ...}` dict shape have evolved.*
+
+## Fold contract
+
+A fold is a single-argument callable `fn(items) -> result` that:
+
+1. Accepts an **iterable** of elements (or, when called internally to combine block results, an iterable of prior fold results) and returns a single value.
+2. Is **associative**: `fn([fn([a, b]), fn([c, d])]) == fn([a, b, c, d])`. This lets `query` combine precomputed block-level folds with the partial folds at each end.
+3. Returns a value of the same shape it accepts as elements — i.e., feeding the result back through `fn` together with other results must work. `len` is a common-but-broken choice: it returns an `int` regardless of input shape, so `len([len(block_a), len(block_b)])` gives `2`, not the total element count.
+
+Examples that satisfy the contract: `sum`, `max`, `min`, `math.prod`, `math.gcd` (via `functools.reduce`), bitwise `or`/`and`/`xor`, `"".join`, and any mergeable sketch (t-digest, HyperLogLog, Count-Min, Welford) wrapped in a fold-shaped callable. Commutativity is *not* required — string concatenation, matrix multiplication, and other ordered monoids work too.
+
+## Constraints
+
+- **Not thread-safe.** Single-process, single-thread workloads only.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/danielenricocahall/livefold/blob/main/CONTRIBUTING.md).

livefold-0.1.0/README.md

@@ -0,0 +1,152 @@
+# livefold
+
+*live + fold — incremental folds over a mutable sequence.*
+
+[![Build Status](https://github.com/danielenricocahall/livefold/actions/workflows/ci.yaml/badge.svg)](https://github.com/danielenricocahall/livefold/actions/workflows/ci.yaml)
+[![Supported Versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://github.com/danielenricocahall/livefold/blob/main/pyproject.toml)
+[![license](https://img.shields.io/github/license/danielenricocahall/livefold.svg)](https://github.com/danielenricocahall/livefold/blob/main/LICENSE)
+
+> A primitive for online sequential aggregation in Python.
+> Maintain a mutable numeric sequence; query exact aggregates over any range
+> in **O(√n)**; plug in any associative reducer (any monoid).
+
+## When to reach for it
+
+| Need | Use |
+|---|---|
+| Immutable series, range aggregates | Prefix sums |
+| Frequent point updates, log-time queries | Segment tree / Fenwick tree |
+| Fixed-width rolling windows | `pandas.rolling()` / `polars.rolling()` |
+| **Mutable series, arbitrary range queries, multi-fold** | **livefold** |
+
+Common shapes: request latencies, sensor readings, trade prices, telemetry events.
+
+## Quickstart
+
+```bash
+pip install livefold
+```
+
+```python
+from livefold import LiveFold
+
+lf = LiveFold([1, 2, 3, 4, 5, 6], folds={"sum": sum, "max": max, "min": min})
+
+lf.append(7)
+lf.query(0, 5)
+# → {"sum": 21, "max": 6, "min": 1}
+
+# Mutate freely; aggregates stay current
+lf[2] = -1
+lf.query(2, 5)
+# → {"sum": 9, "max": 6, "min": -1}
+```
+
+## Performance
+
+![Query latency vs collection size](https://raw.githubusercontent.com/danielenricocahall/livefold/main/benchmarks/plots/query_latency.png)
+
+At n = 10⁷, `livefold`'s median range query is **69 µs vs naive Python's 29 ms** (~400× faster), and median append cost is **~2 µs across all n** while every other backend with a competitive query path (numpy, pandas) degrades linearly on *every* append. livefold's amortized append is O(√n) — boundary-crossing rebuilds are rare (~one per √n appends) but real — so the median characterizes typical streaming latency, not the rare rebuild spike.
+
+Full methodology, append benchmarks, comparison against four backends, and the reproduction script: [`benchmarks/`](https://github.com/danielenricocahall/livefold/tree/main/benchmarks).
+
+## Examples
+
+Two runnable Streamlit demos in [`examples/`](https://github.com/danielenricocahall/livefold/tree/main/examples):
+
+- **[`system_metrics/`](https://github.com/danielenricocahall/livefold/tree/main/examples/system_metrics)** — live `psutil`-driven CPU/memory dashboard with arbitrary-range aggregate queries. Runs entirely offline.
+- **[`crypto_ticks/`](https://github.com/danielenricocahall/livefold/tree/main/examples/crypto_ticks)** — synthetic BTC/USD tick stream with high/low/avg-price queries. Includes a drop-in recipe for real Binance ticks.
+
+
+## API
+
+```python
+LiveFold(data: Iterable, folds: dict[str, Callable])
+```
+
+| Member | Returns | Notes |
+|---|---|---|
+| `lf.append(x)` | `None` | Amortized O(√n); worst-case O(n) on perfect-square crossings |
+| `lf.query(left, right)` | `dict[str, Any]` | O(√n); inclusive bounds |
+| `lf.blocks` | `list[list]` | Underlying √n-sized blocks |
+| `lf.folded_values` | `dict[str, list]` | Per-fold, per-block aggregates |
+| `lf.insert / pop / extend / remove / sort / ...` | — | Standard `list` methods; blocks and folds updated in place |
+
+`LiveFold` subclasses `list`, so it's a drop-in for any code that expected a plain list — until you start calling `query`.
+
+## Time-indexed queries: `TimeIndexedLiveFold`
+
+For monotonic streams where you want to query by *time* instead of *index*, `TimeIndexedLiveFold` carries a parallel timestamp per element and exposes `query_time_range` — still O(√n).
+
+```python
+from livefold import TimeIndexedLiveFold
+
+lf = TimeIndexedLiveFold(
+    [1, 2, 3],
+    folds={"sum": sum, "max": max},
+    timestamps=[1.0, 2.0, 3.0],
+)
+lf.append(4, timestamp=4.0)
+lf.append(5, timestamp=5.0)
+
+lf.query_time_range(2.0, 4.0)
+# → {"sum": 9, "max": 4}
+```
+
+If you omit `timestamps` / `timestamp`, `time.time()` is used by default. The class is generic over the timestamp type — anything orderable works (`float`, `int`, `datetime`, ...). Pass explicit timestamps for any non-`float` type:
+
+```python
+from datetime import datetime
+from livefold import TimeIndexedLiveFold
+
+lf = TimeIndexedLiveFold[datetime](
+    [1, 2, 3],
+    folds={"sum": sum},
+    timestamps=[datetime(2025, 1, 1), datetime(2025, 6, 1), datetime(2026, 1, 1)],
+)
+lf.query_time_range(datetime(2025, 5, 1), datetime(2026, 6, 1))
+# → {"sum": 5}
+```
+
+`TimeIndexedLiveFold` is **append-only by design**. Operations that would break time ordering raise `MonotonicityError`:
+
+- `insert`, `sort`, `reverse` — would break the ordering invariant
+- slice `__setitem__`, slice `__delitem__` — would desync data and timestamps
+- `append` / `extend` with a timestamp earlier than the last stored one
+- `+` / `+=` with anything other than another `TimeIndexedLiveFold` (use `extend(values, timestamps=...)` instead)
+
+Integer indexing (`lf[i] = x`, `del lf[i]`), `pop`, `remove`, and `clear` work normally and keep the parallel timestamp list in sync. `+` and `+=` between two `TimeIndexedLiveFold` instances concatenate timestamps and re-check monotonicity.
+
+## How it works
+
+![Query animation](https://raw.githubusercontent.com/danielenricocahall/livefold/main/assets/query_animation.gif)
+
+`LiveFold` splits its underlying list into ⌊√n⌋ blocks of size √n, precomputes the configured folds for each block, and updates them incrementally on mutation. A `query(left, right)` walks at most two partial blocks plus the precomputed folds for whole-block spans in between — touching roughly 2√n elements per fold regardless of n. Mo's algorithm with mutability and a dict-shaped output.
+
+![Append re-block animation](https://raw.githubusercontent.com/danielenricocahall/livefold/main/assets/resize_animation.gif)
+
+`append` is **amortized O(√n)**. Most appends just push onto the last block at O(1), but each time `n` crosses a perfect square, `block_size = isqrt(n)` increments and the whole structure re-blocks — an O(n) cost. The gap between consecutive perfect squares is `2k + 1` (linear in `k = √n`, not geometric), so over `n` appends total rebuild work sums to Σ_{k=1}^{√n} O(k²) = O(n^(3/2)) — i.e. O(√n) per append amortized. Boundary crossings happen only ~once per √n appends, though, so the *median* append latency stays in the low µs range across all `n` (this is what the benchmarks show); the asymptotic only shows up in mean or total cost.
+
+`TimeIndexedLiveFold` layers a parallel monotonically non-decreasing timestamp list on top. `query_time_range(start, end)` calls `bisect_left`/`bisect_right` to map timestamps to indices in O(log n), then routes through the same √n-decomposed query path — so overall query cost stays O(√n).
+
+For the full derivation, complexity analysis, and other implementation details, see the [corresponding blog post](https://dannycahall.substack.com/p/square-root-decomposition-made-mutable).
+
+> *Note: the blog post predates the rebrand from `pysquagg` and uses the old singular `aggregator_function=` API. The math and structural choices are unchanged; only the package name and the `folds={"name": fn, ...}` dict shape have evolved.*
+
+## Fold contract
+
+A fold is a single-argument callable `fn(items) -> result` that:
+
+1. Accepts an **iterable** of elements (or, when called internally to combine block results, an iterable of prior fold results) and returns a single value.
+2. Is **associative**: `fn([fn([a, b]), fn([c, d])]) == fn([a, b, c, d])`. This lets `query` combine precomputed block-level folds with the partial folds at each end.
+3. Returns a value of the same shape it accepts as elements — i.e., feeding the result back through `fn` together with other results must work. `len` is a common-but-broken choice: it returns an `int` regardless of input shape, so `len([len(block_a), len(block_b)])` gives `2`, not the total element count.
+
+Examples that satisfy the contract: `sum`, `max`, `min`, `math.prod`, `math.gcd` (via `functools.reduce`), bitwise `or`/`and`/`xor`, `"".join`, and any mergeable sketch (t-digest, HyperLogLog, Count-Min, Welford) wrapped in a fold-shaped callable. Commutativity is *not* required — string concatenation, matrix multiplication, and other ordered monoids work too.
+
+## Constraints
+
+- **Not thread-safe.** Single-process, single-thread workloads only.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/danielenricocahall/livefold/blob/main/CONTRIBUTING.md).

livefold-0.1.0/assets/render_query_animation.py

@@ -0,0 +1,194 @@
+"""Render an animated GIF illustrating LiveFold's √n-decomposed query.
+
+Walks through `query(2, 7)` on a 9-element list with 3 blocks of size 3:
+   1. Idle state with precomputed per-block sums
+   2. Query is announced
+   3. Left partial block is scanned (1 element)
+   4. Middle whole block uses its precomputed fold (no scan)
+   5. Right partial block is scanned (2 elements)
+   6. Combined answer revealed
+
+Run with:  uv run --group bench python -m assets.render_query_animation
+Output: assets/query_animation.gif
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import matplotlib.patches as mpatches
+import matplotlib.pyplot as plt
+from matplotlib.animation import FuncAnimation, PillowWriter
+
+DATA = [3, 1, 4, 1, 5, 9, 2, 6, 5]
+BLOCK_SIZE = 3
+BLOCKS = [DATA[i : i + BLOCK_SIZE] for i in range(0, len(DATA), BLOCK_SIZE)]
+BLOCK_SUMS = [sum(b) for b in BLOCKS]
+
+QUERY_LEFT, QUERY_RIGHT = 2, 7  # inclusive
+
+IDLE_CELL = "#e5e7eb"
+PARTIAL = "#fbbf24"
+PRECOMPUTED = "#a78bfa"
+ANSWER = "#34d399"
+TEXT_DARK = "#111827"
+TEXT_MUTED = "#6b7280"
+
+NUM_PHASES = 6
+# Hold each phase by emitting one frame per phase + extra holds on the answer.
+# Total frames at fps=1 → seconds in the GIF.
+PHASE_DURATIONS = [1, 1, 1, 1, 1, 3]  # final answer holds for 3 seconds
+
+
+def phase_for_frame(frame: int) -> int:
+    cumulative = 0
+    for phase, duration in enumerate(PHASE_DURATIONS):
+        cumulative += duration
+        if frame < cumulative:
+            return phase
+    return NUM_PHASES - 1
+
+
+def draw(frame: int, ax) -> None:
+    phase = phase_for_frame(frame)
+    ax.clear()
+    ax.set_xlim(-0.6, 9.6)
+    ax.set_ylim(-2.6, 3.0)
+    ax.set_aspect("equal")
+    ax.axis("off")
+
+    title = "LiveFold(data, folds={'sum': sum})"
+    if phase >= 1:
+        title = "query(left=2, right=7) → ?"
+    if phase >= 5:
+        title = "query(left=2, right=7) → 27"
+    ax.text(
+        4.5,
+        2.55,
+        title,
+        ha="center",
+        va="center",
+        fontsize=14,
+        fontweight="bold",
+        color=TEXT_DARK,
+    )
+
+    for i, val in enumerate(DATA):
+        color = IDLE_CELL
+        if phase >= 2 and i == QUERY_LEFT:
+            color = PARTIAL
+        if phase >= 4 and QUERY_RIGHT - 1 <= i <= QUERY_RIGHT:
+            color = PARTIAL
+        ax.add_patch(
+            mpatches.FancyBboxPatch(
+                (i + 0.05, 1.05),
+                0.9,
+                0.9,
+                boxstyle="round,pad=0.02,rounding_size=0.08",
+                facecolor=color,
+                edgecolor="black",
+                linewidth=1.2,
+            )
+        )
+        ax.text(
+            i + 0.5,
+            1.5,
+            str(val),
+            ha="center",
+            va="center",
+            fontweight="bold",
+            fontsize=14,
+            color=TEXT_DARK,
+        )
+        ax.text(
+            i + 0.5,
+            2.15,
+            str(i),
+            ha="center",
+            va="center",
+            fontsize=9,
+            color=TEXT_MUTED,
+        )
+
+    for b_idx in range(len(BLOCKS)):
+        start_x = b_idx * BLOCK_SIZE + 0.05
+        end_x = start_x + BLOCK_SIZE - 0.1
+        ax.plot(
+            [start_x, start_x, end_x, end_x],
+            [0.95, 0.65, 0.65, 0.95],
+            color="#374151",
+            lw=1.5,
+        )
+
+        block_color = IDLE_CELL
+        if phase == 3 and b_idx == 1:
+            block_color = PRECOMPUTED
+        elif phase >= 4 and b_idx == 1:
+            block_color = PRECOMPUTED
+
+        label = f"sum = {BLOCK_SUMS[b_idx]}"
+        ax.text(
+            (start_x + end_x) / 2,
+            0.15,
+            label,
+            ha="center",
+            va="center",
+            fontsize=11,
+            fontweight="bold",
+            color=TEXT_DARK,
+            bbox=dict(
+                boxstyle="round,pad=0.4",
+                facecolor=block_color,
+                edgecolor="#374151",
+                linewidth=1.0,
+            ),
+        )
+
+    annotations: list[tuple[str, str]] = []
+    if phase >= 2:
+        annotations.append(("left partial → scan data[2] = 4", PARTIAL))
+    if phase >= 3:
+        annotations.append(("middle block → reuse precomputed sum = 15", PRECOMPUTED))
+    if phase >= 4:
+        annotations.append(("right partial → scan data[6:8] = 2 + 6 = 8", PARTIAL))
+    if phase >= 5:
+        annotations.append(("answer = 4 + 15 + 8 = 27", ANSWER))
+
+    for i, (text, color) in enumerate(annotations):
+        ax.text(
+            4.5,
+            -0.7 - i * 0.45,
+            text,
+            ha="center",
+            va="center",
+            fontsize=11,
+            color=TEXT_DARK,
+            bbox=dict(
+                boxstyle="round,pad=0.3",
+                facecolor=color,
+                edgecolor="none",
+                alpha=0.7,
+            ),
+        )
+
+
+def main() -> None:
+    fig, ax = plt.subplots(figsize=(10, 4.2), dpi=100)
+    fig.patch.set_facecolor("white")
+
+    total_frames = sum(PHASE_DURATIONS)
+    anim = FuncAnimation(
+        fig,
+        lambda f: draw(f, ax),
+        frames=total_frames,
+        interval=1000,
+        blit=False,
+    )
+
+    out = Path(__file__).parent / "query_animation.gif"
+    anim.save(out, writer=PillowWriter(fps=1))
+    print(f"Wrote {out}")
+
+
+if __name__ == "__main__":
+    main()