ultracompress 0.1.0__tar.gz

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

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check src/ tests/
+
+      - name: Type check (mypy)
+        run: mypy src/ --ignore-missing-imports
+        continue-on-error: true
+
+      - name: Run tests
+        run: pytest tests/ -v --cov=ultracompress_cli --cov-report=term-missing
+
+      - name: Build package
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+
+      - name: Upload dist artifacts
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 30
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write  # for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish to PyPI via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

ultracompress-0.1.0/.github/workflows/security.yml

@@ -0,0 +1,45 @@
+name: Security
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  schedule:
+    - cron: "0 6 * * 1"  # Weekly Monday 6am UTC
+
+jobs:
+  security:
+    name: Security scans
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e "."
+          pip install bandit pip-audit safety
+
+      - name: Bandit (static security scan)
+        run: bandit -r src/ -ll
+        continue-on-error: true
+
+      - name: pip-audit (dependency CVEs)
+        run: pip-audit
+        continue-on-error: true
+
+      - name: Safety (dependency CVEs alternative)
+        run: safety check --json
+        continue-on-error: true
+
+      - name: Check for secrets (gitleaks)
+        uses: gitleaks/gitleaks-action@v2
+        continue-on-error: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

ultracompress-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual envs
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+.hypothesis/
+htmlcov/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Model downloads (can be huge)
+models/
+eval-results/
+*.safetensors
+*.pt
+*.bin

ultracompress-0.1.0/LICENSE

@@ -0,0 +1,33 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+------------------------------------------------------------------------------
+
+SCOPE OF THIS LICENSE
+
+The Apache-2.0 License above applies to the source code of this CLI
+(`ultracompress-cli`). It does NOT automatically grant any rights to the
+patent-pending compression methodologies described as "UltraCompress" or
+"Fractal Residual Recursion" or "Activation-Aware Row-Overlay Quantization",
+which are the subject of pending U.S. Provisional Patent Applications.
+
+Pre-compressed model artifacts distributed via the Hugging Face Hub are
+subject to separate license terms accompanying each artifact. The model
+weights themselves are governed by the upstream teacher model's license
+(e.g., Apache 2.0 for Qwen3, Llama Community License for Llama variants)
+plus any additional patent grant terms specific to this project.
+
+Copyright 2026 Missipssa Ounnar.

ultracompress-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: ultracompress
+Version: 0.1.0
+Summary: Extreme compression for large language models. Download pre-compressed models from Hugging Face Hub; self-compress support coming soon.
+Project-URL: Homepage, https://sipsalabs.com
+Project-URL: Documentation, https://github.com/mounnar/ultracompress-cli#readme
+Project-URL: Repository, https://github.com/mounnar/ultracompress-cli
+Project-URL: Issues, https://github.com/mounnar/ultracompress-cli/issues
+Author-email: Missipssa Ounnar <micipsa.ounner@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: compression,edge-ai,inference,llm,quantization,transformer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: huggingface-hub>=0.24.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: safetensors>=0.4.0
+Requires-Dist: tqdm>=4.66.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: torch
+Requires-Dist: torch>=2.0.0; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# UltraCompress
+
+> Extreme compression for large language models. Patent pending — USPTO 64/049,511 + 64/049,517
+
+[![PyPI](https://img.shields.io/pypi/v/ultracompress.svg)](https://pypi.org/project/ultracompress/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+
+Run large language models on less hardware.
+UltraCompress compresses modern transformer LLMs by **26–734×** with minimal quality loss. The underlying methods are patent pending; this CLI lets you **download pre-compressed reference models** and run them locally.
+
+## Install
+
+```bash
+pip install ultracompress
+```
+
+## Quickstart
+
+```bash
+# List pre-compressed models available on the official Hugging Face Hub
+uc list
+
+# Download a pre-compressed model (Qwen3-1.7B at 2.798 bpw, ~30% smaller than bnb-nf4)
+uc pull sipsalabs/qwen3-1.7b-uc2p79
+
+# Inspect what's in a compressed artifact
+uc info ./models/qwen3-1.7b-uc2p79
+
+# Benchmark the compressed model against the fp16 teacher
+uc eval ./models/qwen3-1.7b-uc2p79 --tasks hellaswag --limit 500
+```
+
+## What's available today (v0.1 — alpha)
+
+- `uc list` — browse pre-compressed models from our Hugging Face Hub collection.
+- `uc pull <model-id>` — download a pre-compressed model locally.
+- `uc info <path>` — inspect the compression metadata of an artifact.
+- `uc eval <path> --tasks <list>` — run downstream benchmarks via `lm-eval-harness` on the compressed model.
+
+## What's coming
+
+- `uc compress <hf-model-id> --bpw 2.8` — self-compression (private method, coming once patents clear).
+- `uc serve <path>` — inference server with OpenAI-compatible API.
+- `uc export --format gguf` — export to llama.cpp GGUF format.
+- `uc export --format coreml` — export to Apple CoreML for on-device inference.
+
+## Why UltraCompress
+
+On a 6-model × 8-method × 500-sample head-to-head benchmark:
+
+| Method | Bits per weight | Cohort median T1 retention | Catastrophic failures |
+|---|---:|---:|---:|
+| bitsandbytes int8 | 8.000 | 99.75% | 0/6 |
+| bitsandbytes nf4 | 4.000 | 98.31% | 0/6 |
+| HQQ 4-bit g64 | 4.500 | 97.72% | 0/6 |
+| **UltraCompress 2.8 bpw** | **2.798** | **95.63%** | **0/6** |
+| HQQ 3-bit g64 | 3.500 | 72.46% | 1/6 |
+| HQQ 2-bit g64 | 2.500 | 3.46% | 6/6 |
+
+UltraCompress is the only sub-3-bpw method on this cohort that produces zero catastrophic failures.
+
+## Patent status
+
+The UltraCompress compression methods are the subject of pending U.S. patent applications. Pre-compressed models are distributed under a separate licensing arrangement described in [LICENSE](LICENSE). The CLI code in this repository is Apache-2.0.
+
+## Citation
+
+```bibtex
+@misc{ounnar2026ultracompress,
+  title   = {UltraCompress: Extreme Compression for Large Language Models},
+  author  = {Missipssa Ounnar},
+  year    = {2026},
+  howpublished = {\url{https://mounnar.vercel.app}}
+}
+```
+
+## Author
+
+**Missipssa Ounnar** — [mounnar.vercel.app](https://mounnar.vercel.app) · [github.com/mounnar](https://github.com/mounnar)
+
+Built on a dual-RTX-5090 workstation I designed and assembled myself. Patent pending.

ultracompress-0.1.0/README.md

@@ -0,0 +1,82 @@
+# UltraCompress
+
+> Extreme compression for large language models. Patent pending — USPTO 64/049,511 + 64/049,517
+
+[![PyPI](https://img.shields.io/pypi/v/ultracompress.svg)](https://pypi.org/project/ultracompress/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+
+Run large language models on less hardware.
+UltraCompress compresses modern transformer LLMs by **26–734×** with minimal quality loss. The underlying methods are patent pending; this CLI lets you **download pre-compressed reference models** and run them locally.
+
+## Install
+
+```bash
+pip install ultracompress
+```
+
+## Quickstart
+
+```bash
+# List pre-compressed models available on the official Hugging Face Hub
+uc list
+
+# Download a pre-compressed model (Qwen3-1.7B at 2.798 bpw, ~30% smaller than bnb-nf4)
+uc pull sipsalabs/qwen3-1.7b-uc2p79
+
+# Inspect what's in a compressed artifact
+uc info ./models/qwen3-1.7b-uc2p79
+
+# Benchmark the compressed model against the fp16 teacher
+uc eval ./models/qwen3-1.7b-uc2p79 --tasks hellaswag --limit 500
+```
+
+## What's available today (v0.1 — alpha)
+
+- `uc list` — browse pre-compressed models from our Hugging Face Hub collection.
+- `uc pull <model-id>` — download a pre-compressed model locally.
+- `uc info <path>` — inspect the compression metadata of an artifact.
+- `uc eval <path> --tasks <list>` — run downstream benchmarks via `lm-eval-harness` on the compressed model.
+
+## What's coming
+
+- `uc compress <hf-model-id> --bpw 2.8` — self-compression (private method, coming once patents clear).
+- `uc serve <path>` — inference server with OpenAI-compatible API.
+- `uc export --format gguf` — export to llama.cpp GGUF format.
+- `uc export --format coreml` — export to Apple CoreML for on-device inference.
+
+## Why UltraCompress
+
+On a 6-model × 8-method × 500-sample head-to-head benchmark:
+
+| Method | Bits per weight | Cohort median T1 retention | Catastrophic failures |
+|---|---:|---:|---:|
+| bitsandbytes int8 | 8.000 | 99.75% | 0/6 |
+| bitsandbytes nf4 | 4.000 | 98.31% | 0/6 |
+| HQQ 4-bit g64 | 4.500 | 97.72% | 0/6 |
+| **UltraCompress 2.8 bpw** | **2.798** | **95.63%** | **0/6** |
+| HQQ 3-bit g64 | 3.500 | 72.46% | 1/6 |
+| HQQ 2-bit g64 | 2.500 | 3.46% | 6/6 |
+
+UltraCompress is the only sub-3-bpw method on this cohort that produces zero catastrophic failures.
+
+## Patent status
+
+The UltraCompress compression methods are the subject of pending U.S. patent applications. Pre-compressed models are distributed under a separate licensing arrangement described in [LICENSE](LICENSE). The CLI code in this repository is Apache-2.0.
+
+## Citation
+
+```bibtex
+@misc{ounnar2026ultracompress,
+  title   = {UltraCompress: Extreme Compression for Large Language Models},
+  author  = {Missipssa Ounnar},
+  year    = {2026},
+  howpublished = {\url{https://mounnar.vercel.app}}
+}
+```
+
+## Author
+
+**Missipssa Ounnar** — [mounnar.vercel.app](https://mounnar.vercel.app) · [github.com/mounnar](https://github.com/mounnar)
+
+Built on a dual-RTX-5090 workstation I designed and assembled myself. Patent pending.

ultracompress-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ultracompress"
+version = "0.1.0"
+description = "Extreme compression for large language models. Download pre-compressed models from Hugging Face Hub; self-compress support coming soon."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Missipssa Ounnar", email = "micipsa.ounner@gmail.com" }
+]
+keywords = ["llm", "compression", "quantization", "transformer", "inference", "edge-ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "huggingface_hub>=0.24.0",
+    "safetensors>=0.4.0",
+    "tqdm>=4.66.0",
+    "click>=8.1.0",
+    "rich>=13.0.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+torch = [
+    "torch>=2.0.0",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0",
+]
+
+[project.scripts]
+uc = "ultracompress_cli.__main__:main"
+ultracompress = "ultracompress_cli.__main__:main"
+
+[project.urls]
+Homepage = "https://sipsalabs.com"
+Documentation = "https://github.com/mounnar/ultracompress-cli#readme"
+Repository = "https://github.com/mounnar/ultracompress-cli"
+Issues = "https://github.com/mounnar/ultracompress-cli/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ultracompress_cli"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/ultracompress_cli" = "ultracompress_cli"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = ["E501"]

ultracompress-0.1.0/render_demo_video.py

@@ -0,0 +1,213 @@
+"""Render the `uc demo` output as a 1080p MP4 terminal-style screen recording.
+
+Approach: run `uc demo`, capture stdout in real time with timestamps, replay
+into a pyte virtual terminal at video framerate, render each frame as a PNG
+with monospace font on dark background, then stitch into MP4 with ffmpeg.
+
+Output: ~60 sec, 1920×1080, H.264, ready to upload to YC's demo video field.
+"""
+from __future__ import annotations
+import os, subprocess, time, threading, queue, shutil, tempfile, sys
+from pathlib import Path
+from PIL import Image, ImageDraw, ImageFont
+
+# ----- Config -----
+TERM_COLS = 110
+TERM_ROWS = 30
+W, H = 1920, 1080
+FPS = 30
+FONT_SIZE = 20
+PADDING = 40
+CHAR_W = 0  # auto
+LINE_H = 0  # auto
+BG = (12, 14, 18)
+FG = (220, 220, 220)
+DIM = (130, 130, 130)
+ACCENT = (102, 217, 239)  # cyan
+GREEN = (102, 217, 102)
+RED = (240, 100, 100)
+YELLOW = (240, 220, 102)
+WHITE = (245, 245, 245)
+BLACK = (12, 14, 18)
+
+# Pyte palette for ANSI 16-color
+PALETTE = {
+    'default': FG,
+    'black': (40, 44, 52),
+    'red': RED,
+    'green': GREEN,
+    'yellow': YELLOW,
+    'blue': (100, 149, 237),
+    'magenta': (199, 146, 234),
+    'cyan': ACCENT,
+    'white': WHITE,
+    'brown': (180, 140, 80),
+    'brightblack': (90, 96, 108),
+    'brightred': (250, 130, 130),
+    'brightgreen': (130, 240, 130),
+    'brightyellow': (250, 235, 130),
+    'brightblue': (130, 170, 250),
+    'brightmagenta': (220, 170, 250),
+    'brightcyan': (130, 230, 250),
+    'brightwhite': (255, 255, 255),
+}
+
+FFMPEG = r"C:\Users\scamd\AppData\Local\Microsoft\WinGet\Packages\Gyan.FFmpeg_Microsoft.Winget.Source_8wekyb3d8bbwe\ffmpeg-8.1-full_build\bin\ffmpeg.exe"
+
+# Try Cascadia Mono first, then Consolas as fallback
+FONT_CANDIDATES = [
+    "C:/Windows/Fonts/CascadiaMono.ttf",
+    "C:/Windows/Fonts/CascadiaCode.ttf",
+    "C:/Windows/Fonts/consola.ttf",
+    "C:/Windows/Fonts/cour.ttf",
+]
+FONT_BOLD_CANDIDATES = [
+    "C:/Windows/Fonts/CascadiaMonoBold.ttf",
+    "C:/Windows/Fonts/CascadiaCodeBold.ttf",
+    "C:/Windows/Fonts/consolab.ttf",
+    "C:/Windows/Fonts/courbd.ttf",
+]
+
+
+def find_font(candidates):
+    for p in candidates:
+        if Path(p).exists():
+            return p
+    raise FileNotFoundError(f"None of these fonts found: {candidates}")
+
+
+def capture_demo() -> list[tuple[float, bytes]]:
+    """Run `uc demo` and capture stdout with timestamps. Returns list of (ts, chunk)."""
+    print("Capturing uc demo output...")
+    env = os.environ.copy()
+    env["PYTHONIOENCODING"] = "utf-8"
+    env["TERM"] = "xterm-256color"
+    env["COLUMNS"] = str(TERM_COLS)
+    env["LINES"] = str(TERM_ROWS)
+    env["FORCE_COLOR"] = "1"  # rich auto-detection
+    env["COLORTERM"] = "truecolor"
+
+    proc = subprocess.Popen(
+        ["uc", "demo"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        env=env,
+        bufsize=0,
+    )
+
+    chunks = []
+    t0 = time.time()
+    while True:
+        chunk = proc.stdout.read(64)
+        if not chunk:
+            break
+        chunks.append((time.time() - t0, chunk))
+    proc.wait()
+    print(f"  captured {len(chunks)} chunks over {time.time() - t0:.1f}s")
+    return chunks
+
+
+def render_frames(chunks: list[tuple[float, bytes]], out_dir: Path, total_seconds: float | None = None):
+    """Replay chunks into pyte and render frames."""
+    import pyte
+
+    screen = pyte.Screen(TERM_COLS, TERM_ROWS)
+    stream = pyte.ByteStream(screen)
+
+    if total_seconds is None:
+        total_seconds = chunks[-1][0] + 1.5 if chunks else 5.0
+    n_frames = int(total_seconds * FPS) + 1
+
+    font_path = find_font(FONT_CANDIDATES)
+    bold_path = find_font(FONT_BOLD_CANDIDATES)
+    font = ImageFont.truetype(font_path, FONT_SIZE)
+    bold = ImageFont.truetype(bold_path, FONT_SIZE)
+
+    bbox = font.getbbox("M")
+    char_w = bbox[2] - bbox[0]
+    bbox = font.getbbox("Mg")
+    line_h = int((bbox[3] - bbox[1]) * 1.4) + 2
+
+    chunk_idx = 0
+    print(f"Rendering {n_frames} frames at {FPS} fps...")
+
+    for f in range(n_frames):
+        t = f / FPS
+        # Feed all chunks up to time t
+        while chunk_idx < len(chunks) and chunks[chunk_idx][0] <= t:
+            try:
+                stream.feed(chunks[chunk_idx][1])
+            except Exception:
+                pass
+            chunk_idx += 1
+
+        img = Image.new("RGB", (W, H), BG)
+        draw = ImageDraw.Draw(img)
+
+        # Draw header bar
+        draw.rectangle([0, 0, W, 36], fill=(28, 32, 40))
+        draw.ellipse([18, 12, 30, 24], fill=(255, 95, 86))
+        draw.ellipse([38, 12, 50, 24], fill=(255, 189, 46))
+        draw.ellipse([58, 12, 70, 24], fill=(39, 201, 63))
+        draw.text((W // 2 - 80, 8), "ultracompress demo", fill=DIM, font=font)
+
+        # Render each row
+        cursor = screen.cursor
+        for row_idx, line in enumerate(screen.display):
+            x = PADDING
+            y = PADDING + 36 + row_idx * line_h
+            row_data = screen.buffer[row_idx]
+            for col_idx in range(min(len(line), TERM_COLS)):
+                ch = line[col_idx] if col_idx < len(line) else " "
+                if ch == "\x00":
+                    ch = " "
+                ce = row_data.get(col_idx)
+                fg_name = ce.fg if ce else "default"
+                bgname = ce.bg if ce else "default"
+                bold_flag = ce.bold if ce else False
+                fg_color = PALETTE.get(fg_name, FG) if fg_name != "default" else FG
+                f_use = bold if bold_flag else font
+                if ch.strip():
+                    draw.text((x, y), ch, fill=fg_color, font=f_use)
+                x += char_w
+
+        # Save frame
+        img.save(out_dir / f"frame_{f:05d}.png", optimize=False, compress_level=1)
+        if f % 60 == 0:
+            print(f"  frame {f}/{n_frames} (t={t:.1f}s)")
+
+    return n_frames, total_seconds
+
+
+def main():
+    out_dir = Path(tempfile.mkdtemp(prefix="uc_demo_render_"))
+    try:
+        chunks = capture_demo()
+        if not chunks:
+            print("ERROR: no output captured")
+            sys.exit(1)
+        n_frames, total = render_frames(chunks, out_dir)
+        print(f"Rendered {n_frames} frames into {out_dir}")
+        # Stitch with ffmpeg
+        out_mp4 = Path(__file__).parent / "ultracompress_demo.mp4"
+        cmd = [
+            FFMPEG, "-y",
+            "-framerate", str(FPS),
+            "-i", str(out_dir / "frame_%05d.png"),
+            "-c:v", "libx264",
+            "-preset", "fast",
+            "-crf", "20",
+            "-pix_fmt", "yuv420p",
+            "-movflags", "+faststart",
+            str(out_mp4),
+        ]
+        print("Encoding MP4...")
+        subprocess.run(cmd, check=True)
+        size_mb = out_mp4.stat().st_size / 1024 / 1024
+        print(f"Wrote {out_mp4} ({size_mb:.1f} MB, {total:.1f}s)")
+    finally:
+        shutil.rmtree(out_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()