unitport 0.0.1__py3-none-any.whl

unitport/__init__.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+"""unitport — UnitPort local helper (headless daemon).
+
+Package-level constants shared across modules. Keep this import cheap: NO heavy
+third-party imports here (websockets etc. are imported lazily where used) so that
+``config`` / ``doctor`` / ``capabilities`` stay usable even in a broken env.
+
+Authoritative design: ``knowledges/local_helper_design.md`` (LH-D1…D6, C10/C11).
+"""
+
+__version__ = "0.0.1"
+
+# Wire / schema identifiers — must match the design doc and the cloud edge.
+CAPABILITIES_SCHEMA = "unitport.helper.capabilities@1"  # design §5
+PROTOCOL_VERSION = 1  # envelope { v, kind, id, verb, run_id?, payload, ts } §2
+
+# Cloud edge (Cloudflare Workers, design §11). Overridable via config.toml
+# [cloud].base_url or the UNITPORT_BASE_URL env var — never hard-required here.
+DEFAULT_BASE_URL = "https://svc.unitport.ai"
+
+__all__ = [
+    "__version__",
+    "CAPABILITIES_SCHEMA",
+    "PROTOCOL_VERSION",
+    "DEFAULT_BASE_URL",
+]

unitport/__main__.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""Enable ``python -m unitport`` (mirrors the ``unitport`` console script)."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

unitport/bundle.py

@@ -0,0 +1,152 @@
+# -*- coding: utf-8 -*-
+"""DispatchBundle model + materialization (contract C4 / design §8, LH-P4).
+
+A DispatchBundle is what the cloud sends via ``receive-bundle``. It is the
+complete, executable payload the compile chain produced
+(``web_export_chain_plan.md`` §6): env-cfg source + TrainingSpec + asset URI
+list + provenance + run_id. Large asset bodies never ride inside it — they are
+referenced by D2 URIs (``github://`` / ``helper://`` / ``storage://``) and
+resolved locally at materialize time.
+
+Wire shape (payload of the ``receive-bundle`` frame)::
+
+    {
+      "run_id":   "r-abc123",
+      "backend":  "isaac_lab" | "sb3_mujoco",
+      "provenance": { "owner_uid": "<uuid>", "canvas_project": "...", "signed_at": "..." },
+      "env_cfg":  { "file_name": "unitport_env_cfg.py", "source": "<python source>" },
+      "spec":     { "algorithm": "PPO"|"AMP_PPO", "max_iterations": 100, "seed": 1,
+                    "robot_sku": "...", "robot_family": "...",
+                    "resume_checkpoint": null | "helper://.../model_X.pt",
+                    "warm_start_actor": false },
+      "assets":   [ { "uri": "helper://<registered-path>", "dest": "assets/go2.xml" }, ... ]
+    }
+
+``materialize`` verifies provenance (own-canvas), lays out the run dir, writes
+the env-cfg + spec + metadata, and resolves ``helper://`` assets against the
+registered roots. It does NOT launch training (that is ``runner.start``).
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List
+
+from . import config as _config
+from . import security
+from .errors import VerbError
+
+VALID_BACKENDS = frozenset({"isaac_lab", "sb3_mujoco"})
+
+
+class MaterializedRun:
+    """Result of materializing a bundle — everything ``runner`` needs."""
+
+    def __init__(self, run_id: str, backend: str, run_dir: Path, config_file: Path, spec: Dict[str, Any]):
+        self.run_id = run_id
+        self.backend = backend
+        self.run_dir = run_dir
+        self.config_file = config_file  # compiled env-cfg .py
+        self.spec = spec
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "run_id": self.run_id,
+            "backend": self.backend,
+            "run_dir": str(self.run_dir),
+            "config_file": str(self.config_file),
+            "spec": self.spec,
+        }
+
+
+def _require(bundle: Dict[str, Any], key: str) -> Any:
+    if key not in bundle or bundle[key] in (None, ""):
+        raise VerbError(f"bundle missing required field: {key!r}")
+    return bundle[key]
+
+
+def run_root(cfg: Dict[str, Any], backend: str, run_id: str) -> Path:
+    ws = Path((cfg.get("workspace", {}) or {}).get("dir") or (_config.config_dir() / "workspace")).expanduser()
+    return ws / "training" / "runs" / backend / run_id
+
+
+def materialize(bundle: Dict[str, Any], paired_uid: str, cfg: Dict[str, Any] | None = None) -> MaterializedRun:
+    """Verify + lay down a bundle on disk. Fail loud on anything malformed or
+    provenance/asset-boundary violations (C11 §7)."""
+    cfg = cfg if cfg is not None else _config.load_config()
+
+    run_id = str(_require(bundle, "run_id"))
+    backend = str(_require(bundle, "backend"))
+    if backend not in VALID_BACKENDS:
+        raise VerbError(f"unknown backend {backend!r} (allowed: {sorted(VALID_BACKENDS)})")
+
+    provenance = bundle.get("provenance") or {}
+    security.assert_own_canvas(str(provenance.get("owner_uid") or ""), paired_uid)
+
+    env_cfg = _require(bundle, "env_cfg")
+    source = env_cfg.get("source")
+    if not source:
+        raise VerbError("bundle env_cfg.source is empty (helper consumes precompiled env-cfg, §8)")
+    file_name = env_cfg.get("file_name") or "unitport_env_cfg.py"
+
+    spec = dict(bundle.get("spec") or {})
+
+    run_dir = run_root(cfg, backend, run_id)
+    run_dir.mkdir(parents=True, exist_ok=True)
+
+    config_file = run_dir / file_name
+    config_file.write_text(source, encoding="utf-8")
+    (run_dir / "spec.json").write_text(json.dumps(spec, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    assets_resolved = _resolve_assets(bundle.get("assets") or [], run_dir, cfg)
+
+    (run_dir / "run.json").write_text(
+        json.dumps(
+            {
+                "run_id": run_id,
+                "backend": backend,
+                "owner_uid": paired_uid,
+                "config_file": str(config_file),
+                "assets": assets_resolved,
+                "materialized_at": _config.now_iso(),
+                "status": "materialized",
+            },
+            indent=2,
+            ensure_ascii=False,
+        ),
+        encoding="utf-8",
+    )
+    return MaterializedRun(run_id, backend, run_dir, config_file, spec)
+
+
+def _resolve_assets(assets: List[Dict[str, Any]], run_dir: Path, cfg: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Resolve each asset URI. ``helper://`` stays referenced by default (copied
+    into the run dir only if a ``dest`` is given). ``github://`` / ``storage://``
+    are declared-but-not-yet-fetched here (LH-P4 tail / needs network+storage);
+    they fail loud rather than silently skip."""
+    roots = (cfg.get("resource", {}) or {}).get("roots", []) or []
+    out: List[Dict[str, Any]] = []
+    for a in assets:
+        uri = a.get("uri") or ""
+        if uri.startswith("helper://"):
+            src = security.resolve_helper_uri(uri, roots)
+            entry = {"uri": uri, "resolved": str(src)}
+            dest = a.get("dest")
+            if dest:
+                dst = (run_dir / dest).resolve()
+                # dest must stay inside the run dir (no escape).
+                if run_dir.resolve() not in dst.parents and dst != run_dir.resolve():
+                    from .errors import SecurityError
+
+                    raise SecurityError(f"asset dest escapes run dir: {dest!r}")
+                dst.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(src, dst)
+                entry["copied_to"] = str(dst)
+            out.append(entry)
+        elif uri.startswith(("github://", "storage://")):
+            raise VerbError(f"asset scheme not yet materialized in this build: {uri!r} (LH-P4 tail)")
+        else:
+            raise VerbError(f"unknown asset URI scheme: {uri!r}")
+    return out

unitport/capabilities.py

@@ -0,0 +1,196 @@
+# -*- coding: utf-8 -*-
+"""Capability manifest (``report-capabilities`` verb, design §5).
+
+Probes the host for training engines + GPU and emits the
+``unitport.helper.capabilities@1`` payload the cloud uses to light up
+`BTN:helper` and gate which backends are dispatchable (no Isaac Lab → Isaac
+dispatch disabled, fail-loud rather than silent downgrade).
+
+Probing is intentionally **fail-soft**: a missing engine/command reports
+``installed: false`` (or an empty list), never raises. This is capability
+*discovery*, distinct from the §7 security red line (which is fail-loud).
+"""
+
+from __future__ import annotations
+
+import platform
+import re
+import shutil
+import subprocess
+import sys
+from typing import Any, Dict, List, Optional
+
+from . import CAPABILITIES_SCHEMA
+from . import config as _config
+
+# A probe importing a heavy engine could hang; keep every subprocess bounded.
+_PROBE_TIMEOUT = 20  # seconds
+_TOOL_TIMEOUT = 10
+
+
+def _run(cmd: List[str], timeout: int) -> Optional[str]:
+    """Run ``cmd``, return stripped stdout or None on any failure/timeout."""
+    try:
+        out = subprocess.run(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            timeout=timeout,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if out.returncode != 0:
+        return None
+    return (out.stdout or "").strip()
+
+
+def _probe_import(python_exe: str, module: str, version_expr: str) -> Dict[str, Any]:
+    """Probe ``module`` inside ``python_exe``; report installed + version.
+
+    Runs an isolated one-liner (``-I``) so we don't inherit our own site-packages
+    when probing a *different* interpreter. Fail-soft.
+    """
+    code = (
+        f"import importlib,sys\n"
+        f"try:\n"
+        f"    m=importlib.import_module({module!r})\n"
+        f"    print({version_expr})\n"
+        f"except Exception:\n"
+        f"    sys.exit(3)\n"
+    )
+    ver = _run([python_exe, "-I", "-c", code], _PROBE_TIMEOUT)
+    if ver is None:
+        return {"installed": False, "version": None}
+    return {"installed": True, "version": ver or "unknown"}
+
+
+# ---------------------------------------------------------------------------
+# Engines
+# ---------------------------------------------------------------------------
+def detect_isaac_lab(cfg: Dict[str, Any]) -> Dict[str, Any]:
+    """Isaac Lab lives behind its OWN interpreter (Isaac Sim's python), declared
+    via ``[installs.isaac_lab].python``. We report installed by path existence;
+    we do NOT import ``isaaclab`` here (it needs the Kit runtime and can hang) —
+    a deep version probe is deferred to `doctor`/training launch."""
+    entry = (cfg.get("installs", {}) or {}).get("isaac_lab", {}) or {}
+    py = entry.get("python")
+    if not py:
+        return {"installed": False, "version": None, "python": None}
+    from pathlib import Path
+
+    exists = Path(py).exists()
+    return {
+        "installed": bool(exists),
+        "version": None,  # deep probe deferred (Kit runtime); §5 note
+        "python": _config._norm_path(py) if py else None,
+        "python_exists": bool(exists),
+    }
+
+
+def detect_mujoco(cfg: Dict[str, Any]) -> Dict[str, Any]:
+    """MuJoCo (SB3 path) can run in the helper's own interpreter or a declared
+    one. Probe the declared interpreter if present, else ``sys.executable``."""
+    py = ((cfg.get("installs", {}) or {}).get("mujoco", {}) or {}).get("python") or sys.executable
+    return _probe_import(py, "mujoco", "getattr(m,'__version__','unknown')")
+
+
+def detect_sb3(cfg: Dict[str, Any]) -> Dict[str, Any]:
+    py = ((cfg.get("installs", {}) or {}).get("sb3", {}) or {}).get("python") or sys.executable
+    return _probe_import(py, "stable_baselines3", "getattr(m,'__version__','unknown')")
+
+
+def detect_conda_envs() -> List[str]:
+    if not shutil.which("conda"):
+        return []
+    out = _run(["conda", "env", "list", "--json"], _TOOL_TIMEOUT)
+    if not out:
+        return []
+    try:
+        import json
+
+        envs = json.loads(out).get("envs", [])
+    except Exception:
+        return []
+    names = []
+    for path in envs:
+        name = str(path).replace("\\", "/").rstrip("/").rsplit("/", 1)[-1]
+        if name:
+            names.append(name)
+    return names
+
+
+# ---------------------------------------------------------------------------
+# GPU (nvidia-smi)
+# ---------------------------------------------------------------------------
+def detect_gpu() -> Dict[str, Any]:
+    smi = shutil.which("nvidia-smi")
+    if not smi:
+        return {"nvidia_smi": []}
+    cuda = _detect_cuda_version(smi)
+    out = _run(
+        [
+            smi,
+            "--query-gpu=name,memory.total,driver_version",
+            "--format=csv,noheader,nounits",
+        ],
+        _TOOL_TIMEOUT,
+    )
+    gpus: List[Dict[str, Any]] = []
+    if out:
+        for line in out.splitlines():
+            parts = [p.strip() for p in line.split(",")]
+            if len(parts) < 3:
+                continue
+            name, mem, driver = parts[0], parts[1], parts[2]
+            try:
+                mem_mb = int(float(mem))
+            except ValueError:
+                mem_mb = None
+            gpus.append({"name": name, "mem_mb": mem_mb, "driver": driver, "cuda": cuda})
+    return {"nvidia_smi": gpus}
+
+
+def _detect_cuda_version(smi: str) -> Optional[str]:
+    banner = _run([smi], _TOOL_TIMEOUT)
+    if not banner:
+        return None
+    m = re.search(r"CUDA Version:\s*([0-9.]+)", banner)
+    return m.group(1) if m else None
+
+
+# ---------------------------------------------------------------------------
+# Manifest
+# ---------------------------------------------------------------------------
+def _os_name() -> str:
+    sysname = platform.system().lower()
+    if sysname.startswith("win"):
+        return "windows"
+    if sysname == "linux":
+        return "linux"
+    return sysname or "unknown"
+
+
+def build_manifest(cfg: Optional[Dict[str, Any]] = None, device_id: Optional[str] = None) -> Dict[str, Any]:
+    """Assemble the full capability manifest payload (design §5)."""
+    cfg = cfg if cfg is not None else _config.load_config()
+    device_id = device_id or _config.get_or_create_device_id()
+    return {
+        "schema": CAPABILITIES_SCHEMA,
+        "device_id": device_id,
+        "host": {
+            "os": _os_name(),
+            "arch": platform.machine() or "unknown",
+            "hostname": platform.node() or "unknown",
+        },
+        "engines": {
+            "isaac_lab": detect_isaac_lab(cfg),
+            "mujoco": detect_mujoco(cfg),
+            "sb3": detect_sb3(cfg),
+        },
+        "conda_envs": detect_conda_envs(),
+        "gpu": detect_gpu(),
+        "reported_at": _config.now_iso(),
+    }

unitport/cli.py

@@ -0,0 +1,196 @@
+# -*- coding: utf-8 -*-
+"""`unitport` command-line entrypoint (headless — design §10).
+
+Subcommands: login · up/serve · status · config · doctor · logout, plus a hidden
+`capabilities` for probing/debugging. There are deliberately NO pull/train/push
+subcommands — those are *remote* verbs driven from the canvas (C11 §4).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+# Windows console defaults to a legacy code page; force UTF-8 (img_generate.py style).
+try:  # pragma: no cover
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+except Exception:  # pragma: no cover
+    pass
+
+from . import __version__
+from . import capabilities as _caps
+from . import config as _config
+from . import doctor as _doctor
+from .errors import UnitportError
+
+
+# ---------------------------------------------------------------------------
+# Command handlers
+# ---------------------------------------------------------------------------
+def _cmd_login(args: argparse.Namespace) -> int:
+    from . import pairing  # lazy: pulls no heavy deps, but keep startup lean
+
+    pairing.login(base_url=args.base_url)
+    return 0
+
+
+def _cmd_up(args: argparse.Namespace) -> int:
+    from . import transport  # lazy: imports websockets only on connect
+
+    return transport.run(base_url=args.base_url)
+
+
+def _cmd_status(_args: argparse.Namespace) -> int:
+    cfg = _config.load_config()
+    tok = None
+    try:
+        tok = _config.load_token()
+    except UnitportError as exc:
+        print(f"  token: ERROR ({exc})")
+
+    isaac = (cfg.get("installs", {}) or {}).get("isaac_lab", {}) or {}
+    roots = (cfg.get("resource", {}) or {}).get("roots", []) or []
+
+    print(f"unitport v{__version__}")
+    print(f"  config dir : {_config.config_dir()}")
+    print(f"  cloud      : {_config.base_url(cfg)}")
+    print(f"  device_id  : {_config.get_or_create_device_id()}")
+    if tok:
+        print(f"  paired     : yes (uid={tok.get('uid')})")
+        print(f"  token exp  : {tok.get('expires_at', '?')}")
+    else:
+        print("  paired     : no  (run `unitport login`)")
+    print(f"  isaac py   : {isaac.get('python') or '(not set)'}")
+    print(f"  resource   : {len(roots)} root(s)")
+    return 0
+
+
+_ENGINE_FIELD_ACTIONS = {
+    "isaac-python": ("isaac_lab", "python"),
+    "isaac-launcher": ("isaac_lab", "launcher"),
+    "isaac-path": ("isaac_lab", "isaac_lab_path"),
+    "sb3-python": ("sb3_mujoco", "python"),
+    "sb3-launcher": ("sb3_mujoco", "launcher"),
+    "mujoco-python": ("mujoco", "python"),
+}
+
+
+def _cmd_config(args: argparse.Namespace) -> int:
+    action = args.config_action
+    if action == "show" or action is None:
+        print(json.dumps(_config.load_config(), indent=2, ensure_ascii=False))
+        return 0
+    if action in _ENGINE_FIELD_ACTIONS:
+        engine, field = _ENGINE_FIELD_ACTIONS[action]
+        _config.set_engine_field(engine, field, args.path)
+        print(f"  {engine}.{field} set: {args.path}")
+        return 0
+    if action == "workspace":
+        _config.set_workspace(args.path)
+        print(f"  workspace set: {args.path}")
+        return 0
+    if action == "add-root":
+        cfg = _config.add_resource_root(args.path)
+        roots = cfg["resource"]["roots"]
+        print(f"  resource roots ({len(roots)}): {', '.join(roots)}")
+        return 0
+    if action == "base-url":
+        _config.set_base_url(args.url)
+        print(f"  cloud base_url set: {args.url}")
+        return 0
+    print(f"unknown config action: {action}", file=sys.stderr)
+    return 2
+
+
+def _cmd_doctor(_args: argparse.Namespace) -> int:
+    return _doctor.run()
+
+
+def _cmd_capabilities(args: argparse.Namespace) -> int:
+    manifest = _caps.build_manifest()
+    print(json.dumps(manifest, indent=2, ensure_ascii=False))
+    return 0
+
+
+def _cmd_logout(_args: argparse.Namespace) -> int:
+    from . import pairing
+
+    pairing.logout()
+    print("  logged out (helper token cleared).")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="unitport",
+        description="UnitPort local helper — headless daemon (canvas is the remote control).",
+    )
+    p.add_argument("-V", "--version", action="version", version=f"unitport {__version__}")
+    sub = p.add_subparsers(dest="command")
+
+    sp = sub.add_parser("login", help="browser-approve device pairing (C10)")
+    sp.add_argument("--base-url", default=None, help="override cloud base URL")
+    sp.set_defaults(func=_cmd_login)
+
+    for name in ("up", "serve"):
+        sp = sub.add_parser(name, help="dial out to the relay and serve the fixed verb set")
+        sp.add_argument("--base-url", default=None, help="override cloud base URL")
+        sp.set_defaults(func=_cmd_up)
+
+    sp = sub.add_parser("status", help="connection / config / paired-account summary")
+    sp.set_defaults(func=_cmd_status)
+
+    sp = sub.add_parser("config", help="declare engine interpreters + resource roots")
+    csub = sp.add_subparsers(dest="config_action")
+    csub.add_parser("show", help="print effective config")
+    for act, helptext in (
+        ("isaac-python", "Isaac Sim venv python.exe"),
+        ("isaac-launcher", "path to il_train_launcher.py"),
+        ("isaac-path", "Isaac Lab root (subprocess cwd)"),
+        ("sb3-python", "SB3/MuJoCo python"),
+        ("sb3-launcher", "SB3 launcher script"),
+        ("mujoco-python", "MuJoCo probe python"),
+        ("workspace", "workspace root (Isaac: under PROJECTS_DIR)"),
+        ("add-root", "add a resource scan root"),
+    ):
+        cp = csub.add_parser(act, help=helptext)
+        cp.add_argument("path", help="filesystem path")
+    cp = csub.add_parser("base-url", help="set cloud base URL")
+    cp.add_argument("url", help="e.g. https://svc.unitport.ai")
+    sp.set_defaults(func=_cmd_config)
+
+    sp = sub.add_parser("doctor", help="fail-loud self-check")
+    sp.set_defaults(func=_cmd_doctor)
+
+    sp = sub.add_parser("capabilities", help="print the capability manifest (debug)")
+    sp.set_defaults(func=_cmd_capabilities)
+
+    sp = sub.add_parser("logout", help="clear the stored helper token")
+    sp.set_defaults(func=_cmd_logout)
+
+    return p
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return 0
+    try:
+        return int(args.func(args) or 0)
+    except UnitportError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\naborted.", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())