diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..62793d0 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,86 @@ +# Publish workflow โ€” makes every future release one click. +# Author Saurabh (2026-09-24): no token stored = the PyPI trusted publisher +# flow sends an OIDC token per run. +# +# PyPI one-time setup (does NOT live in this repo): +# 1. Go to pypi.org/manage/project/spacepilot/settings/publishing +# 2. Add a pending publisher with: +# owner = motionvector-dev +# repo = spacepilot +# workflow = publish.yml +# environment = pypi (only if you gate by env; optional) +# 3. Done. This workflow NEVER stores a token. +# +# Tag a release (git tag v2.10.0 && git push origin v2.10.0) and this runs. + +name: publish + +on: + push: + tags: ['v*'] + workflow_dispatch: # manual trigger for emergency republish + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-python@v7 + with: + python-version: '3.11' + # Stale build guard โ€” the build/lib trap bit us on PR 167 (build/ from a + # pre-flatten tree shipped deleted modules into a fresh wheel). + - name: Clear stale build artifacts + run: rm -rf build/ dist/ -- *.egg-info + - name: Install build backend + run: python -m pip install --upgrade pip build + - name: Build sdist and wheel + run: python -m build + - name: Sanity โ€” version and no ghost modules in the wheel + run: | + python - <<'PY' + import importlib.metadata, zipfile, pathlib + whl = next(__import__('pathlib').Path('dist').glob('*.whl')) + z = zipfile.ZipFile(whl) + names = z.namelist() + ghosts = [n for n in names if 'pluto' in n or 'enhance_prompt' in n] + assert not ghosts, f"ghost modules in wheel: {ghosts}" + PY + - uses: actions/upload-artifact@v4 + with: + name: dist + path: dist/ + + publish: + needs: build + environment: pypi # matches the PyPI trusted-publisher environment, if configured + permissions: + id-token: write # OIDC for PyPI trusted publishing, no token stored + runs-on: ubuntu-latest + steps: + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist/ + - name: Publish to PyPI (trusted publisher) + uses: pypa/gh-action-pypi-publish@release/v1 + # No password/config. PyPI authenticates via the OIDC token. + # If you see 'Publisher verification failed' check the one-time + # PyPI settings at pypi.org/manage/project/spacepilot/settings/publishing + + release: + needs: publish + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/download-artifact@v4 # v4 is the current stable major + with: + name: dist + path: dist/ + - name: Create the GitHub release with the wheel attached + env: + GH_TOKEN: ${{ github.token }} + run: | + TAG="${GITHUB_REF_NAME}" + NOTES="RELEASE_NOTES_${TAG}.md" + gh release create "$TAG" --title "SpacePilot $TAG" --notes-file "$NOTES" dist/* diff --git a/README.md b/README.md index 174d2e7..48d0e24 100644 --- a/README.md +++ b/README.md @@ -1,243 +1,279 @@ # SpacePilot ๐Ÿš€ -**Status**: v2.8.0 Released on PyPI -**Verified**: 2026-09-20 via GitHub Release v2.8.0 and pytest test suite on main. -**Supersedes / Superseded by**: none - -> **"You decide what to run. SpacePilot decides how and where."** - -**SpacePilot** runs AI models on the machine in front of you and says honestly -what fits before you download it. One surface, every modality: text and chat, -embeddings, speech and transcription, image, and video. Text and embeddings -are the newest routes โ€” a pinned MLX route on Apple Silicon, an -OpenAI-compatible `/v1` surface โ€” added 2026-09-02 because AgentWorth and -SpaceBar need them; every route gets a fit verdict from the model registry and -a measurement written for every run. Work the machine cannot hold goes to a -rented box. A CLI, a FastMCP tool server and a zero-build web UI (`/create`, -`/cockpit`, `/studio`, `/oven.html`) are three windows onto one state. +[![PyPI](https://img.shields.io/badge/PyPI-spacepilot-2.9.0-blue)](https://pypi.org/project/spacepilot/) +[![Python](https://img.shields.io/badge/python-3.11%2B-informational)](https://pypi.org/project/spacepilot/) +[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE) +[![Tests](https://img.shields.io/badge/tests-1057%20passing-brightgreen)](.github/workflows/tests.yml) + +> **You decide what to run. SpacePilot decides how and where.** + +**SpacePilot** runs AI models on the machine in front of you and tells you +honestly what fits before you download it. One surface, every modality: text +and chat, embeddings, speech and transcription, and image โ€” with a per-run +measurement record for each. Work the machine cannot hold goes to a rented box +with the same honesty checks on both sides. A CLI, a FastMCP tool server, and +a zero-build web UI are three windows onto one state. + +Works today on Apple Silicon (Metal) and extends cleanly to CUDA and CPU. +The `/v1` surface is OpenAI-compatible, so anything that already speaks +`chat/completions` or `embeddings` can point at it. --- -## First run +## Why SpacePilot -The canonical install, upgrade, runtime, Qwen text, and MCP instructions live -in [`docs/LOCAL-SETUP.md`](docs/LOCAL-SETUP.md). +Two things this project does not do: -```bash -uv tool install spacepilot # Global installation from PyPI -spacepilot probe # what this machine can run -spacepilot models list # which models run here, with the fit verdict -spacepilot doctor # check environment and dependencies -``` +1. **It does not guess.** Every model card is either *flown* โ€” a real, dated + measurement on a named machine โ€” *on paper*, with the cited source โ€” or + *unflown*, which the registry names as a rule applied to a parameter + count. Most registries pretend the third category does not exist. This + one puts a number on it. +2. **It does not hide behind an API.** The `/v1` OpenAI-compatible surface + means other tools can use SpacePilot without learning a new format. The + heterogeneity it manages (local Lance/CUDA/CPU, rented spot, remote box) + is the point. + +The narrow waist that makes this useful: SpacePilot is a **decision layer +and orchestration layer** โ€” not a model, not a serving framework. It reads +your fleet, ranks what fits, and routes your work honestly. It never invents +a number. -What works today: +--- -- **Text** on Apple Silicon, via a pinned MLX-LM route (`spacepilot run text`, and `POST /v1/chat/completions`). -- **Embeddings** on the same MLX route, 1024-dim, `POST /v1/embeddings` โ€” in this PR. -- **Speech and transcription** via the API (`spacepilot serve`). -- **Image** on Apple Silicon, via mflux in its own conda env (`spacepilot runtimes check mflux` shows the route). +## What works today -The `/v1` surface, the shared fit verdict and the per-call measurement record -are specified in [`docs/design/INFERENCE-SURFACE.md`](docs/design/INFERENCE-SURFACE.md). +| surface | surface | route | +| --- | --- | --- | +| **Text** | Apple Silicon | `spacepilot run text`, pinned MLX-LM route | +| **Text (OpenAI-compatible)** | Any | `POST /v1/chat/completions` | +| **Embeddings** | Apple Silicon | `POST /v1/embeddings`, 1024-dim | +| **Speech (TTS)** | Any | In-process Kokoro-82M ONNX | +| **Transcription** | Any | whisper.cpp, measured, working | +| **Image** | Apple Silicon | mflux, own venv, subprocess-only | +| **Video** | โ€” | **Not yet** โ€” routes exist, refuse with 501. Mock test-pattern real render is gone. | -### Video +The `/v1` surface is specified in [`docs/design/INFERENCE-SURFACE.md`](docs/design/INFERENCE-SURFACE.md). -What does not: **video**. The engines and routes exist, but every render is a -mock โ€” an ffmpeg test pattern, not a real model run. +### Honest boundary -Video is a dock workload: it counts as real when it runs on a rented GPU end to -end. The generative cinema workstation is the longer-term aim, not a -description of what this repo does today. +Video here is real in name and honest in report: the engine routes exist as +specs, and the CLI tells you that. It is the longer-term aim, not a +description of this repo today. --- -## Architecture & Modular Components +## Install +```bash +uv tool install spacepilot # from PyPI โ€” the canonical install ``` -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ SpacePilot Modular Platform Topology โ”‚ -โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค -โ”‚ โ”‚ -โ”‚ 1. Compute Provider Modules (Pluggable Execution Runtimes) โ”‚ -โ”‚ โ”œโ”€โ”€ Local Host Driver: Apple Metal MPS / CUDA / CPU ($0.00 / Zero Cloud)โ”‚ -โ”‚ โ”œโ”€โ”€ Local Execution: Apple Metal MPS / CUDA / CPU โ”‚ -โ”‚ โ””โ”€โ”€ Hardware Probe: Auto-detects VRAM headroom & recommends models โ”‚ -โ”‚ โ”‚ -โ”‚ 2. Generative Model Modules (Polymorphic BaseVideoEngine Adapters) โ”‚ -โ”‚ โ”œโ”€โ”€ LTX-Video 2.5: spec only โ€” no inference runs, route refuses 501 โ”‚ -โ”‚ โ”œโ”€โ”€ Wan2.1 (1.3B & 14B): spec only โ€” no inference runs, route refuses โ”‚ -โ”‚ โ”œโ”€โ”€ HunyuanVideo: spec only โ€” no inference runs, route refuses โ”‚ -โ”‚ โ”œโ”€โ”€ Speech & VO: In-process Kokoro-82M ONNX with -16 LUFS sidechaining โ”‚ -โ”‚ โ””โ”€โ”€ Narrative: In-process GGUF screenplay deconstruction & 3D vectors โ”‚ -โ”‚ โ”‚ -โ”‚ 3. Agentic Protocol & Tool Modules โ”‚ -โ”‚ โ”œโ”€โ”€ FastMCP Tool Server (spacepilot/mcp_server.py): 17 tools for AI โ”‚ -โ”‚ โ”œโ”€โ”€ DocIR 2.0 Edit Protocol: Byte-exact, reversible patch operations โ”‚ -โ”‚ โ””โ”€โ”€ WebSocket PTY Bridge: Live interactive shell & worker streaming โ”‚ -โ”‚ โ”‚ -โ”‚ 4. UI Component Modules (Zero-Build Obsidian UI) โ”‚ -โ”‚ โ”œโ”€โ”€ Create Studio (/create): Camera Compass, Dual Keyframe, VO Ducking โ”‚ -โ”‚ โ”œโ”€โ”€ Cockpit (/cockpit): Live Host Telemetry, Model Hub โ”‚ -โ”‚ โ”œโ”€โ”€ Oven (/oven.html): Real-time 5-Lane ADLC Swarm Kanban Board โ”‚ -โ”‚ โ””โ”€โ”€ Director (/studio): Multi-track NLE timeline & asset inspector โ”‚ -โ”‚ โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -``` - ---- -## Setup & Secrets +Or with pip: ```bash -# Environment setup (venv or conda) -python -m venv .venv && source .venv/bin/activate -pip install -r requirements.txt +pip install spacepilot ``` -Configuration variables and provider API keys can be passed as standard environment variables or through any secrets manager (e.g., `.env` or Doppler): +Then: ```bash -export LOCAL_WORKER_TOKEN="your-token" # Required for gated worker endpoints -spacepilot studio +spacepilot probe # what this machine can run +spacepilot models list # which models run here, with the fit verdict +spacepilot doctor # check environment and dependencies ``` +No account, no API key, no port opened. Full setup guide: +[`docs/LOCAL-SETUP.md`](docs/LOCAL-SETUP.md). + --- -## Running the Studio +## Quickstart + +Start the combined web UI + API on localhost: ```bash -spacepilot studio # or: python spacepilot/web_api.py +spacepilot serve ``` -Serves the Web UI and API on: -* **Primary URL**: **`http://spacepilot.localhost:8088`** -* **Local Loopback**: **`http://localhost:8088`** (or `http://127.0.0.1:8088`) - -### Studio Pages: -* **Create Studio**: `http://spacepilot.localhost:8088/create` -* **Cockpit & Model Registry (legacy, vanilla JS)**: `http://spacepilot.localhost:8088/cockpit` - โ€” this is what `spacepilot/app.py` actually mounts and serves today. -* **Oven Swarm Kanban**: `http://spacepilot.localhost:8088/oven.html` -* **Director NLE**: `http://spacepilot.localhost:8088/studio` -* **Human documentation**: `http://spacepilot.localhost:8088/docs` -* **MCP Streamable HTTP v1**: `http://spacepilot.localhost:8088/mcp/v1/` -* **Cockpit v1 (React, `ui/`)**: not yet wired into `spacepilot/app.py`'s - static mount. Run separately as a Vite dev server โ€” - `http://127.0.0.1:5173/cockpit` under `mvec-local` (`docs/LOCAL-TEST.md`). - Whether it replaces the legacy cockpit above, and when, is still an open - product call. +Then open: + +- **Cockpit** โ€” `http://localhost:8088/cockpit` โ€” live hardware telemetry, + the model hub, and the save spot-billing path. +- **Create Studio** โ€” `http://localhost:8088/create` โ€” the create surface. +- **Developer docs** โ€” `http://localhost:8088/docs`. + +The Cockpit and other pages reflect whatever this machine actually is โ€” +including the honest "we don't know" state when a probe returns no answer. --- -## API Routes & Security Gate - -Every endpoint that spends compute or creates assets is gated by `X-SpacePilot-Token` (`require_token`). Read-only and telemetry routes stay open. - -| Route | Method | Auth | Purpose | -| :--- | :--- | :--- | :--- | -| `/api/generate` | `POST` | Yes | Video generation. No local execution path exists; refuses with a failed job status unless a remote GPU worker is running. | -| `/api/generate/multi-engine` | `POST` | Yes | Video generation across the three DiT engines. Refuses with 501 โ€” none of them run inference; the mock test-pattern render this route used to serve was removed. | -| `/api/audio/synthesize-local` | `POST` | Yes | In-process Kokoro TTS audio synthesis (-16 LUFS normalized). | -| `/api/audio/mix-ducked` | `POST` | Yes | Voiceover & background music dynamic sidechain ducking. | -| `/api/narrative/decompose-local` | `POST` | Yes | In-process GGUF screenplay deconstruction into 3D camera shots. | -| `/api/compute/models/download` | `POST` | Yes | Download model weights to `~/.cache/spacepilot/models/`. | -| `/api/gpu/launch` ยท `/terminate` | `POST` | Yes | Spot GPU infrastructure lifecycle management. | -| `/api/compute/local-profile` | `GET` | No | Hardware capability telemetry (backend, usable VRAM headroom). | -| `/api/compute/models/recommended` | `GET` | No | Curated model recommendations scored for host hardware. | -| `/api/engines` | `GET` | No | Complete catalogue of available video DiT engines. | -| `/healthz` | `GET` | No | Dependency-free process liveness check. | -| `/api/status` | `GET` | No | Live GPU worker and fleet status telemetry. | +## Your first run + +The CLI overlay of the first probe looks like the landing page's "fifteen +seconds, start to measured": it asks permission before reading anything, it +reports what it read, and it stays honest about gaps. + +```bash +spacepilot probe +``` + +What this returns on a given machine is a *records* entry in +`registry/measurements//`, timestamped, source-attributed, and +reusable. Nothing in that flow phones home. --- -## FastMCP Server Tools (`spacepilot/mcp_server.py`) +## Architecture at a glance -Native FastMCP tools exposed to Cursor, Claude Code, and Antigravity: +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ SpacePilot Platform Topology โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”‚ +โ”‚ 1. Compute Provider Modules (pluggable execution runtimes) โ”‚ +โ”‚ โ”œโ”€โ”€ Local Host Driver โ€” Apple Metal MPS / CUDA / CPU โ”‚ +โ”‚ โ”œโ”€โ”€ Hardware Probe โ€” auto-detects usable VRAM, names the source โ”‚ +โ”‚ โ””โ”€โ”€ Rented spots, docks, and managed APIs (cost-accounted) โ”‚ +โ”‚ โ”‚ +โ”‚ 2. Generative Model Modules โ”‚ +โ”‚ โ”œโ”€โ”€ LTX-Video 2.5, Wan2.1, HunyuanVideo โ€” spec only; routes โ”‚ +โ”‚ โ”‚ refuse 501 until real inference exists โ”‚ +โ”‚ โ”œโ”€โ”€ Speech & VO โ€” In-process Kokoro-82M ONNX โ”‚ +โ”‚ โ””โ”€โ”€ Narrative โ€” GGUF screenplay deconstruction โ”‚ +โ”‚ โ”‚ +โ”‚ 3. Agentic Protocol & Tool Modules โ”‚ +โ”‚ โ”œโ”€โ”€ FastMCP tool server (`spacepilot/mcp_server.py`) โ”‚ +โ”‚ โ”œโ”€โ”€ DocIR 2.0 Edit Protocol โ€” byte-exact reversible patches โ”‚ +โ”‚ โ””โ”€โ”€ WebSocket PTY bridge โ€” live shell & worker streaming โ”‚ +โ”‚ โ”‚ +โ”‚ 4. UI Component Modules (zero-build, no bundler) โ”‚ +โ”‚ โ”œโ”€โ”€ Create Studio `/create` โ”‚ +โ”‚ โ”œโ”€โ”€ Cockpit `/cockpit` โ”‚ +โ”‚ โ”œโ”€โ”€ Oven Swarm Kanban `/oven.html` โ”‚ +โ”‚ โ””โ”€โ”€ Director NLE `/studio` โ”‚ +โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` -* `spacepilot_probe_hardware`: Probes host GPU VRAM and compute headroom. -* `spacepilot_recommend_models`: Returns task-matched model catalog for current device. -* `spacepilot_decompose_storyboard`: Deconstructs screenplay into 3D camera vector scene beats. +### Where the code lives -The Studio process hosts the canonical loopback-only Streamable HTTP transport -at `/mcp/v1/`. The `spacepilot-mcp` command remains the stdio fallback for -clients that cannot use HTTP. +``` +spacepilot/ The package โ€” CLI, FastAPI app factory, drivers, + daemon, registry, measurement store +โ”œโ”€โ”€ drivers/ Per-runtime execution drivers โ€” MLX-LM (text), +โ”‚ mflux (image), whisper.cpp (transcribe), +โ”‚ Kokoro (speech), GGUF (narrative) +โ”œโ”€โ”€ api/routes/ 16 route modules; mutating routes go through +โ”‚ require_token; read-only stays open +โ”œโ”€โ”€ engines/ Video DiT engine specs โ€” none run inference yet +โ”œโ”€โ”€ web/ Zero-build UI actually served by app.py (ships +โ”‚ in the wheel โ€” a uv tool install used to 500) +โ”œโ”€โ”€ registry/ The model registry: variants, provenance, +โ”‚ measurements, systems +โ”‚ registry/models + systems + measurements +โ”œโ”€โ”€ docs/design/ The architecture and inference-surface docs +tests/ Pytest suite โ€” do not trust a hardcoded count + in any doc, check CI for the current number +landing/ The spacepilot.dev landing (deploys to Vercel) +native/SpaceBar/ macOS menu-bar app (Swift), separate cadence. + Moved to motionvector-dev/spacebar (carve-out + landed 2026-09-24); this directory will be + removed once the extraction settles. +``` --- -## Test Suite +## Configuration & secrets -Local pytest needs the project interpreter (see `AGENTS.md`, Interpreter) โ€” -`python3` on the primary dev machine resolves to base conda, which lacks -fastapi. CI on the self-hosted lenovo runner is the gate; the run on the -commit this README was last checked against passed -**771 tests, 4 skipped** (`gh run view ` on main for the current -number โ€” do not trust a hardcoded count here, it goes stale fast): +Environment variables are the interface, or any secrets manager. Never +commit secrets; `.env.example` is the reference of what a deployment needs. ```bash - -m pytest tests/ -v +export LOCAL_WORKER_TOKEN="your-token" # gated worker endpoints ``` -Covers: -- Polymorphic DiT engine adapters (LTX, Wan 1.3B/14B, HunyuanVideo). Mock renders only โ€” - every BaseVideoEngine path used to write an ffmpeg test pattern; the route that served - it now refuses with 501 instead, and no real video generation runs here yet. -- In-process Kokoro TTS and GGUF narrative drivers. -- Device capability probing and safety headroom calculations. -- FastMCP tool wrappers. -- REST API security token enforcement on all mutating routes. -- Frontend JavaScript syntax validation and HTML escaping. +--- + +## API & MCP + +### HTTP API + +Every endpoint that spends compute or creates assets is gated by +`X-SpacePilot-Token`. Read-only and telemetry routes stay open. + +Surfaces worth knowing: + +- `/v1/chat/completions` โ€” OpenAI-compatible chat +- `/v1/embeddings` โ€” embeddings +- `/api/compute/local-profile` โ€” hardware capability telemetry (usable VRAM with its source) +- `/api/compute/models/recommended` โ€” task-based fit verdicts for this machine +- `/healthz` โ€” dependency-free liveness +- `/docs` โ€” the developer portal + +### MCP + +`spacepilot-mcp` is a stdio MCP server for Cursor, Claude Code, and +Antigravity. The Studio process also hosts a loopback-only Streamable HTTP +transport at `/mcp/v1/`. --- -## Directory Layout +## Tests +```bash +python -m pytest tests/ -q ``` -spacepilot/ The package (flattened from spacepilot/pluto/, #101) -โ”œโ”€โ”€ cli.py CLI command router -โ”œโ”€โ”€ app.py FastAPI app factory โ€” mounts spacepilot/web/ as the frontend -โ”œโ”€โ”€ web_api.py Studio entry point (python -m spacepilot.web_api) -โ”œโ”€โ”€ mcp_server.py Native FastMCP tool server, 17 tools -โ”œโ”€โ”€ device_probe.py Cross-platform hardware profiler -โ”œโ”€โ”€ model_recommender.py Model catalog & dynamic fit scoring -โ”œโ”€โ”€ model_registry.py Registry loader โ€” variants, caveats, provenance -โ”œโ”€โ”€ measurements.py Measurement corpus (LOG) reader/writer -โ”œโ”€โ”€ substrate.py DirectLocal / DaemonClient wire-shaped dispatch -โ”œโ”€โ”€ local_workers.py Local in-process worker memory manager (LRU) -โ”œโ”€โ”€ engines/ Video DiT engine specs โ€” none run inference yet -โ”‚ โ”œโ”€โ”€ base.py BaseVideoEngine ABC & EngineSpec -โ”‚ โ”œโ”€โ”€ ltx_engine.py LTX-Video 2.5 (spec only) -โ”‚ โ”œโ”€โ”€ wan_engine.py Wan2.1 1.3B/14B (spec only) -โ”‚ โ”œโ”€โ”€ hunyuan_engine.py HunyuanVideo (spec only) -โ”‚ โ””โ”€โ”€ registry.py Engine lookup & fallback registry -โ”œโ”€โ”€ drivers/ In-process local execution drivers -โ”‚ โ”œโ”€โ”€ mflux_driver.py Image โ€” mflux, own conda env, subprocess-only -โ”‚ โ”œโ”€โ”€ mlx_lm_driver.py Text โ€” MLX-LM, the working `run text` route -โ”‚ โ”œโ”€โ”€ whisper_cpp_driver.py Transcribe โ€” measured, working -โ”‚ โ”œโ”€โ”€ kokoro_driver.py Speech (TTS) โ€” ONNX, working -โ”‚ โ”œโ”€โ”€ mlx_embed_driver.py Embeddings โ€” MLX, `/v1/embeddings` -โ”‚ โ””โ”€โ”€ gguf_driver.py GGUF screenplay deconstruction -โ”œโ”€โ”€ daemon/ Fleet daemon โ€” UDS + Tailscale peers, Ed25519, -โ”‚ signed LOG gossip (identity.py, fleet.py, log.py) -โ”œโ”€โ”€ storyboard_decomposer.py Screenplay-to-shot decomposition -โ”œโ”€โ”€ ltx_worker.py Remote PyTorch resident worker (EC2/Cloud) -โ”œโ”€โ”€ api/routes/ 16 route modules: assets, audio, billing, -โ”‚ checkpoints, compute, engines, generate, gpu, -โ”‚ health, inference, lora, measurements, recipes, -โ”‚ runtimes, storyboard, views -โ””โ”€โ”€ web/ Zero-build UI actually served by spacepilot/app.py. - โ”‚ Inside the package so it ships in the wheel โ€” a - โ”‚ `uv tool install` used to serve 500 on every page. - โ”œโ”€โ”€ index.html / app.js Director NLE & Asset matrix - โ”œโ”€โ”€ create.html / create.js Create Studio - โ”œโ”€โ”€ cockpit.html/cockpit.js Cockpit (legacy, vanilla JS โ€” currently what's live) - โ”œโ”€โ”€ oven.html Kanban board - โ””โ”€โ”€ app.css Design system -ui/ React 19 cockpit v1 / SpaceBar-web (landed #106/#107). - Not wired into spacepilot/app.py's static mount โ€” - run separately via Vite, see docs/LOCAL-TEST.md. -native/SpaceBar/ macOS menu-bar app (Swift), see docs/LOCAL-TEST.md -infra/ GPU startup scripts, IAM -tests/ Pytest suite โ€” 771 passed, 4 skipped on main as of - CI run 33631068854 (2026-09-02); re-check before citing -docs/ Architecture blueprints, plans, and research -``` + +Do not trust a hardcoded test count in any doc โ€” CI on the current `main` +is the number that counts. The suite covers the DiT engine specs (mock +renders only, honestly labelled), the working TTS/transcription/embedding +drivers, device probing, the `/v1` surface, and the FastMCP tools. + +--- + +## Roadmap + +Honest about what's in and what is not: + +- **Works now**: hardware probing with named sources, model fit verdicts, + compatibility across 88 variants, runtime installs that show what they + will move before they move it, speech locally, OpenAI-compatible `/v1`. +- **Not yet**: video on your own silicon, scheduling across more than one + ship at a time, a daemon that runs persistently outside the CLI. +- **Adjacent, separate package later**: SpaceBar (macOS menu bar app) ships + its own release. A CLI install should not pull in a macOS tray app. + +--- + +## Contributing + +Issues and PRs welcome. Two rules from [`AGENTS.md`](AGENTS.md) that keep +this honest: + +- **Execution over ceremony.** Skip bureaucratic process. Bias toward + working code with receipts. +- **Strict tests before implementation** on production paths: reproduce red + โ†’ fix green โ†’ refactor. Exploratory spikes are exempt until they land in + production paths. + +Run the tests locally before opening a PR. CI runs on a self-hosted lenovo +runner and is the gate. + +--- + +## License + +[Apache 2.0](LICENSE) โ€” same license as the registry's Apache-family model +weights so everything under this roof stays redistributable. + +--- + +## Links + +- **PyPI**: [`spacepilot`](https://pypi.org/project/spacepilot/) +- **Source**: [motionvector-dev/spacepilot](https://github.com/motionvector-dev/spacepilot) +- **Landing**: [spacepilot.dev](https://spacepilot.dev) +- **Docs portal**: [spacepilot.dev/docs](https://spacepilot.dev/docs) +- **Design paper**: [spacepilot.dev/paper](https://spacepilot.dev/paper) +- **Releases**: [motionvector-dev/spacepilot/releases](https://github.com/motionvector-dev/spacepilot/releases)