wm-mcp 0.3.0__tar.gz

wm_mcp-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.DS_Store

wm_mcp-0.3.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.3.0 — unreleased
+
+- **`surprise` streams.** Windows are decoded on the fly — bounded memory,
+  unbounded video length. Hour-long recordings scan without silent frame caps
+  (the old code quietly degraded a 10-minute video to ~0.4fps). Progress is
+  logged to stderr every 20 windows. Output now reports `n_windows`.
+- **Images as goals.** `embed_video` accepts still images (png/jpg/webp…),
+  treated as a static clip — so `predict(target_handle=...)` can answer "does
+  this video end up looking like this photo?"
+
+## 0.2.0 — unreleased
+
+- **Time-native everywhere.** `surprise` samples at a configurable `fps`
+  (default 8) so window spans are consistent regardless of source frame rate,
+  and every segment now carries `start_s`/`end_s` timestamps. `embed_video`
+  and `surprise` accept `start_s`/`end_s` to scan a slice of a long video.
+  `embed_video` reports the time span it embedded.
+- **Eager model preload.** `wm-mcp serve` starts loading weights in a
+  background thread at startup (disable with `--no-eager`), so an agent's
+  first tool call doesn't eat the full model load. Loading is lock-guarded.
+- Real encode/decode tests for the video loader (PyAV round-trip).
+
+## 0.1.0 — 2026-07-07
+
+- Initial probe. Three MCP tools (`embed_video`, `predict`, `surprise`) over
+  V-JEPA 2 ViT-L (fp16 on MPS/CUDA), server-side latent handles, localhost
+  HTTP API (`serve --http`), `warmup` command, live demo GIF.

wm_mcp-0.3.0/DEMO.md

@@ -0,0 +1,40 @@
+# Recording the launch GIF
+
+The GIF is one exchange: an LLM agent consulting a world model. Keep it under 30s.
+
+## Setup (once)
+
+```bash
+claude mcp add wm -- uvx wm-mcp serve
+# pre-warm so the GIF doesn't show a weight download:
+uvx wm-mcp embed sample.mp4
+```
+
+Use a clip with a clear event mid-video (something falls, a cut, a jump scare).
+Good sources: your own camera roll beats stock footage for authenticity.
+
+## The take
+
+Record the terminal (QuickTime screen recording, or `vhs` if installed; convert
+with `ffmpeg -i in.mov -vf "fps=12,scale=900:-1" out.gif`).
+
+1. Start `claude` in a clean directory.
+2. Type exactly: **"Where does this clip stop being predictable? ./sample.mp4"**
+3. Let it call `surprise`, wait for the answer, stop recording after the agent
+   summarizes the most surprising segment.
+
+## Caption for the README/post
+
+> An LLM agent consulting a video world model (V-JEPA 2) as a tool. The model
+> predicts each window's second half from its first; the spike is where reality
+> disagreed. Local, MIT, `uvx wm-mcp serve`.
+
+## Launch checklist
+
+- [ ] GIF at top of README
+- [ ] `git tag v0.1.0 && git push --tags` (publishes to PyPI via CI — set up PyPI
+      trusted publishing for the repo first)
+- [ ] Show HN: "Show HN: wm — run a world model locally, let any LLM agent call it"
+- [ ] r/LocalLLaMA post (angle: first local world-model runner with MCP)
+- [ ] MCP community/Discord (angle: first non-LLM model class behind MCP tools)
+- [ ] Note launch date; **day-14 verdict is binding** (see README kill criteria)

wm_mcp-0.3.0/LICENSE

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

wm_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: wm-mcp
+Version: 0.3.0
+Summary: Run a world model locally, and let any LLM agent call it as a tool. V-JEPA 2 as an MCP server.
+Project-URL: Homepage, https://github.com/rian-one/wm
+Project-URL: Issues, https://github.com/rian-one/wm/issues
+Author: Rian Herrmann
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,jepa,mcp,model-context-protocol,v-jepa,video,world-model
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: av>=12.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: huggingface-hub>=0.30
+Requires-Dist: mcp>=1.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: pillow>=10.0
+Requires-Dist: torch>=2.4
+Requires-Dist: torchvision>=0.19
+Requires-Dist: transformers>=4.53
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# wm
+
+**Run a world model locally, and let any LLM agent call it as a tool.**
+
+![An LLM agent consulting a video world model](demo.gif)
+
+*Live and unedited: Claude calls the `surprise` tool; V-JEPA 2 watches the clip and
+reports where its predictions broke (z=3.1 at frames 56–71 — the exact splice point
+of the test video). Wait time hidden, output verbatim.*
+
+LLMs can *describe* what happens when a cup gets knocked off a table. A world model
+can *watch* it happen and tell you, frame by frame, where reality stopped matching
+its prediction. `wm` puts Meta's [V-JEPA 2](https://huggingface.co/facebook/vjepa2-vitl-fpc64-256)
+(MIT-licensed, 0.3B params) behind an [MCP](https://modelcontextprotocol.io) server,
+so Claude, or any MCP client, can consult a video world model the way it consults a
+database.
+
+```
+uvx wm-mcp serve
+```
+
+That's the whole install. First run downloads PyTorch and ~1.2GB of model weights —
+**minutes of downloading, not a hang.**
+
+## The demo
+
+Ask your agent:
+
+> "Where does this clip stop being predictable? /path/to/video.mp4"
+
+The agent calls `surprise()`, the world model slides a window over the video,
+predicts each window's second half from its first, and reports the segment where
+its prediction failed hardest — z-scored per video, so scores mean something.
+
+## The three tools
+
+| Tool | What it does |
+|---|---|
+| `embed_video(source)` | Video → latent sequence, stored server-side under an opaque handle. |
+| `predict(handle, horizon_frames, target_handle?)` | Predict the trailing frames of a clip from its leading context (masked in-window prediction — horizon capped at clip length, this is not open-ended rollout). With `target_handle`, also returns cosine similarity between the prediction and a target embedding — goal-similarity scoring, computed server-side. |
+| `surprise(source, window, stride)` | Per-segment "how wrong was the model" scores + the most surprising segment. Anomaly spotting, event detection, "did anything unexpected happen." |
+
+Latents never cross the wire: tools exchange handle IDs, tensors stay in the server.
+
+## Setup with Claude Code
+
+```bash
+claude mcp add wm -- uvx wm-mcp serve
+```
+
+Then: *"embed this video and tell me how surprising the ending is"*.
+
+Also usable directly, no agent:
+
+```bash
+uvx wm-mcp surprise clip.mp4
+uvx wm-mcp embed clip.mp4
+uvx wm-mcp warmup     # pre-download weights so first real call is fast
+uvx wm-mcp info
+```
+
+## HTTP API (non-MCP consumers)
+
+The same three primitives over localhost HTTP — for scripts, notebooks, or
+anything that doesn't speak MCP:
+
+```bash
+uvx wm-mcp serve --http          # 127.0.0.1:8642
+curl -s localhost:8642/health
+curl -s -X POST localhost:8642/surprise -H 'content-type: application/json' \
+     -d '{"source": "clip.mp4"}'
+```
+
+Endpoints: `GET /health`, `GET /info`, `POST /embed`, `POST /predict`,
+`POST /surprise` — one-to-one with the MCP tools. Binds to localhost, no auth;
+don't expose it to the internet.
+
+## Hardware & honest numbers
+
+- Apple Silicon (MPS): ≥16GB unified memory. Measured on an M2 Pro / 16GB:
+  `surprise` on a 6s clip = **~18s end to end** (11 windows, fp16). A full
+  64-frame `embed_video` is the heavyweight case — expect minutes, not seconds.
+- NVIDIA: ≥8GB VRAM, substantially faster.
+- CPU works; it's just slow.
+- The model loads in fp16 on GPU devices (fp32 attention over 8k tokens will
+  swap a 16GB machine — we measured it, you don't want it).
+
+## What this is (and isn't)
+
+This is a **probe** — the smallest useful bridge between LLM agents and video world
+models, shipped to find out whether anyone wants that bridge. It is not a robotics
+stack, not a leaderboard, not a hosted service, and `predict` is honest about what
+V-JEPA 2's predictor actually does (masked latent prediction within a clip), not a
+marketing claim about simulating the future.
+
+Public kill criteria, decided before launch: if by day 14 this has under 200 stars
+AND under 10 substantive issues/PRs from strangers AND under 3 unprompted
+integrations — it gets archived with a public retro. If it resonates, the next step
+is a protocol, not a feature list.
+
+## License
+
+MIT. V-JEPA 2 weights are MIT-licensed by Meta FAIR.

wm_mcp-0.3.0/README.md

@@ -0,0 +1,103 @@
+# wm
+
+**Run a world model locally, and let any LLM agent call it as a tool.**
+
+![An LLM agent consulting a video world model](demo.gif)
+
+*Live and unedited: Claude calls the `surprise` tool; V-JEPA 2 watches the clip and
+reports where its predictions broke (z=3.1 at frames 56–71 — the exact splice point
+of the test video). Wait time hidden, output verbatim.*
+
+LLMs can *describe* what happens when a cup gets knocked off a table. A world model
+can *watch* it happen and tell you, frame by frame, where reality stopped matching
+its prediction. `wm` puts Meta's [V-JEPA 2](https://huggingface.co/facebook/vjepa2-vitl-fpc64-256)
+(MIT-licensed, 0.3B params) behind an [MCP](https://modelcontextprotocol.io) server,
+so Claude, or any MCP client, can consult a video world model the way it consults a
+database.
+
+```
+uvx wm-mcp serve
+```
+
+That's the whole install. First run downloads PyTorch and ~1.2GB of model weights —
+**minutes of downloading, not a hang.**
+
+## The demo
+
+Ask your agent:
+
+> "Where does this clip stop being predictable? /path/to/video.mp4"
+
+The agent calls `surprise()`, the world model slides a window over the video,
+predicts each window's second half from its first, and reports the segment where
+its prediction failed hardest — z-scored per video, so scores mean something.
+
+## The three tools
+
+| Tool | What it does |
+|---|---|
+| `embed_video(source)` | Video → latent sequence, stored server-side under an opaque handle. |
+| `predict(handle, horizon_frames, target_handle?)` | Predict the trailing frames of a clip from its leading context (masked in-window prediction — horizon capped at clip length, this is not open-ended rollout). With `target_handle`, also returns cosine similarity between the prediction and a target embedding — goal-similarity scoring, computed server-side. |
+| `surprise(source, window, stride)` | Per-segment "how wrong was the model" scores + the most surprising segment. Anomaly spotting, event detection, "did anything unexpected happen." |
+
+Latents never cross the wire: tools exchange handle IDs, tensors stay in the server.
+
+## Setup with Claude Code
+
+```bash
+claude mcp add wm -- uvx wm-mcp serve
+```
+
+Then: *"embed this video and tell me how surprising the ending is"*.
+
+Also usable directly, no agent:
+
+```bash
+uvx wm-mcp surprise clip.mp4
+uvx wm-mcp embed clip.mp4
+uvx wm-mcp warmup     # pre-download weights so first real call is fast
+uvx wm-mcp info
+```
+
+## HTTP API (non-MCP consumers)
+
+The same three primitives over localhost HTTP — for scripts, notebooks, or
+anything that doesn't speak MCP:
+
+```bash
+uvx wm-mcp serve --http          # 127.0.0.1:8642
+curl -s localhost:8642/health
+curl -s -X POST localhost:8642/surprise -H 'content-type: application/json' \
+     -d '{"source": "clip.mp4"}'
+```
+
+Endpoints: `GET /health`, `GET /info`, `POST /embed`, `POST /predict`,
+`POST /surprise` — one-to-one with the MCP tools. Binds to localhost, no auth;
+don't expose it to the internet.
+
+## Hardware & honest numbers
+
+- Apple Silicon (MPS): ≥16GB unified memory. Measured on an M2 Pro / 16GB:
+  `surprise` on a 6s clip = **~18s end to end** (11 windows, fp16). A full
+  64-frame `embed_video` is the heavyweight case — expect minutes, not seconds.
+- NVIDIA: ≥8GB VRAM, substantially faster.
+- CPU works; it's just slow.
+- The model loads in fp16 on GPU devices (fp32 attention over 8k tokens will
+  swap a 16GB machine — we measured it, you don't want it).
+
+## What this is (and isn't)
+
+This is a **probe** — the smallest useful bridge between LLM agents and video world
+models, shipped to find out whether anyone wants that bridge. It is not a robotics
+stack, not a leaderboard, not a hosted service, and `predict` is honest about what
+V-JEPA 2's predictor actually does (masked latent prediction within a clip), not a
+marketing claim about simulating the future.
+
+Public kill criteria, decided before launch: if by day 14 this has under 200 stars
+AND under 10 substantive issues/PRs from strangers AND under 3 unprompted
+integrations — it gets archived with a public retro. If it resonates, the next step
+is a protocol, not a feature list.
+
+## License
+
+MIT. V-JEPA 2 weights are MIT-licensed by Meta FAIR.

wm_mcp-0.3.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "wm-mcp"
+version = "0.3.0"
+description = "Run a world model locally, and let any LLM agent call it as a tool. V-JEPA 2 as an MCP server."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Rian Herrmann" }]
+keywords = ["world-model", "v-jepa", "jepa", "mcp", "model-context-protocol", "video", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=1.2",
+    "torch>=2.4",
+    "torchvision>=0.19",
+    "transformers>=4.53",
+    "numpy>=1.26",
+    "av>=12.0",
+    "pillow>=10.0",
+    "huggingface_hub>=0.30",
+    "fastapi>=0.110",
+    "uvicorn>=0.30",
+]
+
+[project.urls]
+Homepage = "https://github.com/rian-one/wm"
+Issues = "https://github.com/rian-one/wm/issues"
+
+[project.scripts]
+wm-mcp = "wm.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "httpx>=0.27"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wm"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["*.gif", "*.mp4", "*.png", "demo.tape", ".github"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wm_mcp-0.3.0/src/wm/__init__.py

@@ -0,0 +1,5 @@
+"""wm — run a world model locally, and let any LLM agent call it as a tool."""
+
+__version__ = "0.3.0"
+
+MODEL_ID = "facebook/vjepa2-vitl-fpc64-256"

wm_mcp-0.3.0/src/wm/backend.py

@@ -0,0 +1,132 @@
+"""V-JEPA 2 backend: encoder + masked-latent predictor.
+
+Semantics pinned to what the architecture actually does (transformers VJEPA2Model):
+- the encoder embeds a clip into N latent tokens (temporal-major: N = T' * S where
+  T' = frames / tubelet_size and S = spatial patches per tubelet);
+- the predictor fills in latents for *target* token positions given *context*
+  positions within the same clip. Future prediction = mask the trailing frames.
+  There is no arbitrary-horizon rollout; horizon is capped at the clip length.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from . import MODEL_ID
+
+
+def pick_device() -> str:
+    import torch
+
+    if torch.backends.mps.is_available():
+        return "mps"
+    if torch.cuda.is_available():
+        return "cuda"
+    return "cpu"
+
+
+class VJepa2Backend:
+    def __init__(self, model_id: str = MODEL_ID, device: str | None = None):
+        import threading
+
+        self.model_id = model_id
+        self.device = device or pick_device()
+        self._model = None
+        self._processor = None
+        self._load_lock = threading.Lock()
+
+    def _load(self):
+        # lock: eager background preload and a first tool call may race here
+        with self._load_lock:
+            if self._model is None:
+                import torch
+                from transformers import AutoModel, AutoVideoProcessor
+
+                self._processor = AutoVideoProcessor.from_pretrained(self.model_id)
+                # fp16 on GPU: fp32 attention over 8k tokens swaps a 16GB machine
+                # (measured 823s/clip); fp16 keeps activations in memory.
+                dtype = torch.float16 if self.device in ("mps", "cuda") else torch.float32
+                self._model = AutoModel.from_pretrained(
+                    self.model_id, attn_implementation="sdpa", dtype=dtype
+                )
+                self._model.to(self.device).eval()
+        return self._model, self._processor
+
+    def preload_async(self) -> None:
+        """Start loading weights in a daemon thread so the first call is fast."""
+        import threading
+
+        threading.Thread(target=self._load, daemon=True, name="wm-preload").start()
+
+    # -- layout ---------------------------------------------------------------
+
+    def layout(self, n_frames: int):
+        """(tokens_per_tubelet, tubelet_size, n_tubelets) for a clip of n_frames."""
+        model, _ = self._load()
+        cfg = model.config
+        spatial = (cfg.crop_size // cfg.patch_size) ** 2
+        tubelet = cfg.tubelet_size
+        return spatial, tubelet, max(1, n_frames // tubelet)
+
+    # -- ops ------------------------------------------------------------------
+
+    def preprocess(self, frames: np.ndarray):
+        """(T, H, W, C) uint8 -> pixel tensor on device, in the model's dtype."""
+        model, processor = self._load()
+        inputs = processor(frames, return_tensors="pt")
+        pixels = inputs["pixel_values_videos"].to(self.device)
+        return pixels.to(next(model.parameters()).dtype)
+
+    def encode(self, pixels) -> "object":
+        """Pixel tensor -> encoder latents (N, D) on CPU."""
+        import torch
+
+        model, _ = self._load()
+        with torch.inference_mode():
+            out = model(pixel_values_videos=pixels, skip_predictor=True)
+        return out.last_hidden_state[0].float().cpu()
+
+    def predict_masked(self, pixels, n_frames: int, horizon_frames: int):
+        """Predict latents for the trailing `horizon_frames` from the leading context.
+
+        Returns (predicted, actual): both (N_target, D) on CPU, where actual is the
+        encoder's real latents at the same target positions.
+        """
+        import torch
+
+        model, _ = self._load()
+        spatial, tubelet, n_tubelets = self.layout(n_frames)
+
+        horizon_tubelets = max(1, min(horizon_frames // tubelet, n_tubelets - 1))
+        ctx_tokens = (n_tubelets - horizon_tubelets) * spatial
+        total_tokens = n_tubelets * spatial
+
+        dev = pixels.device
+        context_mask = [torch.arange(0, ctx_tokens, device=dev).unsqueeze(0)]
+        target_mask = [torch.arange(ctx_tokens, total_tokens, device=dev).unsqueeze(0)]
+
+        with torch.inference_mode():
+            out = model(
+                pixel_values_videos=pixels,
+                context_mask=context_mask,
+                target_mask=target_mask,
+            )
+        predicted = out.predictor_output.last_hidden_state[0].float().cpu()
+        actual = out.predictor_output.target_hidden_state[0].float().cpu()
+        return predicted, actual
+
+
+_backend: VJepa2Backend | None = None
+
+
+def get_backend() -> VJepa2Backend:
+    global _backend
+    if _backend is None:
+        _backend = VJepa2Backend()
+    return _backend
+
+
+def set_backend(backend) -> None:
+    """Test seam: swap in a fake backend."""
+    global _backend
+    _backend = backend

wm_mcp-0.3.0/src/wm/cli.py

@@ -0,0 +1,108 @@
+"""CLI: `wm-mcp serve` (MCP over stdio) plus direct commands for demos and debugging."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import MODEL_ID, __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="wm-mcp",
+        description="Run a world model locally, and let any LLM agent call it as a tool.",
+    )
+    parser.add_argument("--version", action="version", version=f"wm-mcp {__version__} ({MODEL_ID})")
+    sub = parser.add_subparsers(dest="command")
+
+    p_serve = sub.add_parser("serve", help="start the MCP server (stdio), or HTTP with --http")
+    p_serve.add_argument("--http", action="store_true", help="serve a localhost HTTP API instead of MCP stdio")
+    p_serve.add_argument("--host", default="127.0.0.1")
+    p_serve.add_argument("--port", type=int, default=8642)
+    p_serve.add_argument(
+        "--no-eager",
+        action="store_true",
+        help="don't preload model weights in the background on startup",
+    )
+
+    sub.add_parser("warmup", help="download weights and load the model so first use is fast")
+
+    p_embed = sub.add_parser("embed", help="embed a video, print handle info as JSON")
+    p_embed.add_argument("source", help="video path or URL")
+
+    p_surprise = sub.add_parser("surprise", help="find where a video stops being predictable")
+    p_surprise.add_argument("source", help="video path or URL")
+    p_surprise.add_argument("--window", type=int, default=16)
+    p_surprise.add_argument("--stride", type=int, default=8)
+    p_surprise.add_argument("--fps", type=float, default=8.0, help="sampling rate (frames/sec)")
+    p_surprise.add_argument("--start", type=float, default=None, help="clip start (seconds)")
+    p_surprise.add_argument("--end", type=float, default=None, help="clip end (seconds)")
+
+    sub.add_parser("info", help="print device/model info as JSON")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "serve":
+        if not args.no_eager:
+            from .backend import get_backend
+
+            get_backend().preload_async()
+        if args.http:
+            from .http import serve_http
+
+            serve_http(host=args.host, port=args.port)
+        else:
+            from .server import serve
+
+            serve()
+        return 0
+
+    if args.command == "warmup":
+        import time
+
+        from .backend import get_backend
+
+        t0 = time.time()
+        backend = get_backend()
+        backend._load()
+        print(json.dumps({"device": backend.device, "model": MODEL_ID, "load_s": round(time.time() - t0, 1)}))
+        return 0
+
+    if args.command == "embed":
+        from . import service
+
+        print(json.dumps(service.embed_video(args.source), indent=2))
+        return 0
+
+    if args.command == "surprise":
+        from . import service
+
+        print(
+            json.dumps(
+                service.surprise(
+                    args.source,
+                    window=args.window,
+                    stride=args.stride,
+                    fps=args.fps,
+                    start_s=args.start,
+                    end_s=args.end,
+                ),
+                indent=2,
+            )
+        )
+        return 0
+
+    if args.command == "info":
+        from .backend import pick_device
+
+        print(json.dumps({"version": __version__, "model": MODEL_ID, "device": pick_device()}, indent=2))
+        return 0
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

wm_mcp-0.3.0/src/wm/handles.py

@@ -0,0 +1,49 @@
+"""Server-side latent store. Tools exchange opaque handle IDs, never tensors.
+
+Latents are multi-MB tensors; MCP transports JSON. Handles keep the tensors in
+process memory and give agents something cheap to pass around.
+"""
+
+from __future__ import annotations
+
+import secrets
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Any
+
+MAX_HANDLES = 32
+
+
+@dataclass
+class Entry:
+    latents: Any  # torch.Tensor (N, D) — mean-poolable latent sequence
+    pixels: Any = None  # processed pixel tensor, kept only when predict() may need it
+    meta: dict = field(default_factory=dict)
+
+
+class HandleStore:
+    def __init__(self, max_handles: int = MAX_HANDLES):
+        self._store: OrderedDict[str, Entry] = OrderedDict()
+        self._max = max_handles
+
+    def put(self, entry: Entry, prefix: str = "lat") -> str:
+        handle = f"{prefix}_{secrets.token_hex(4)}"
+        self._store[handle] = entry
+        while len(self._store) > self._max:
+            self._store.popitem(last=False)  # evict oldest
+        return handle
+
+    def get(self, handle: str) -> Entry:
+        if handle not in self._store:
+            raise KeyError(
+                f"unknown handle: {handle!r} (it may have been evicted; "
+                f"the store keeps the {self._max} most recent)"
+            )
+        self._store.move_to_end(handle)
+        return self._store[handle]
+
+    def __len__(self) -> int:
+        return len(self._store)
+
+
+STORE = HandleStore()