tt-waypoint

Waypoint-1.5-1B (interactive world model) on Tenstorrent Blackhole via TTNN -- a from-scratch TTNN bring-up (nothing in tt-metal's models.tt_dit already covers this architecture), served through a stateful, session-based HTTP API behind a small ASGI server.

Runs on p150 (mesh P150).

Packaged and published with tt-model-manager as a v6 thin bundle (schema 6) -- a pip/venv-based install, not a container image.

Quickstart

tt-model pull  episod/tt-waypoint --with-weights
tt-model serve episod/tt-waypoint

pull --with-weights downloads this bundle (a small venv-install recipe: install.sh/run.sh + two wheels -- ttnn, torch and the base HTTP stack resolve from an index at install time) and the Overworld/Waypoint-1.5-1B weights, into your HF cache. serve starts the model's own HTTP server on port 20000 (or the next free port, if that one is busy); the first start compiles kernels for your device, which takes several minutes, and the server is ready when it logs Application startup complete.

tt-model pull episod/tt-waypoint --with-weights
tt-model serve episod/tt-waypoint

# Seed a session from a real starting image (base64-encoded PNG/JPEG):
curl -s localhost:20000/v1/sessions -H 'Content-Type: application/json' \
  -d "{\"image_b64\": \"$(base64 -w0 my_photo.png)\"}"
# -> {"session_id": "...", "frame_index": 1, "frame_b64": "..."}

# Step the session forward, steered by direction/zoom:
curl -s localhost:20000/v1/sessions/<session_id>/step \
  -H 'Content-Type: application/json' -d '{"direction": "forward", "zoom": 0.0}'

tt-model serve picks the host port itself (20000, or the next free one) -- the manifest's own port: field is not the seed for that choice (see container_cli.py's own comment on this), so don't assume a different value. Source, a local Gradio UI, and the bring-up log (every stage's hardware-verified numbers, every bug found and how -- including a real investigation into why generated-frame pixel correlation against a reference run looked catastrophic and turned out not to be, see BRINGUP_LOG.md): tsingletaryTT/tt-waypoint.

Provenance

The served-path code is split into two small wheels built for this bundle, both in wheels/:

wheel	what it is
waypoint_ttnn-0.1.0	this repo's served-path closure -- session.py, the ASGI app, and the tt/ model classes (bring-up scripts, tests, and docs are NOT included; see tsingletaryTT/tt-waypoint for those)
tt_waypoint_models_closure-0.78.0	the one tt-metal dependency this model has -- models/common/lightweightmodule.py, pinned to tt-metal v0.78.0