simulo 0.26.0__py3-none-any.whl

simulo/_client/asset.py

@@ -0,0 +1,331 @@
+"""``Asset`` — a read-only, registry-resolved mount (implements ``AssetProtocol``).
+
+A registry asset ref is ``[<publisher>/]<kind>/<name>[:v<N>]`` (e.g.
+``robot/so-arm-100:v3``, ``simulo/world/warehouse:v2``, or the unpinned
+``robot/forklift`` — resolved to an exact version **at submit**). The grammar
+is the ONE shared parser from ``simulo.interfaces.platform.asset_catalog`` — the
+CLI, the control plane, the worker, and the console all parse through it, so the
+grammar can never drift. This handle carries the parsed ``kind`` (``robot`` /
+``world`` / ``prop``), which enables **kind safety** (``Robot(asset=<world asset>)`` fails
+with a one-line explanation naming the mismatched kind).
+
+The on-disk :attr:`path` only exists in **execution mode**:
+
+* On a cloud worker (or a local ``run-package``), the runner exports
+  ``SIMULO_ASSET_<uri>`` pointing at the read-only mount; :attr:`path` returns it.
+* When no runner mount is present (a local run against the on-disk catalog cache),
+  :attr:`path` resolves the asset out of ``~/.simulo/assets/<org>/<kind>/<name>/v<N>/``
+  — the exact colon-free, NTFS-safe layout ``simulo asset get`` writes into — and,
+  when the asset has not been fetched, raises with the copyable
+  ``simulo asset get <ref>`` command to run.
+
+``Asset`` also unifies the *model-asset* spec surface: ``usd(path)`` / ``urdf(path)``
+name a robot/object source to load into a scene. In discovery (submit) these return
+an inert, torch-free :class:`_AssetSpec` so authoring a task is lean; only the
+backend runner (execution mode) resolves them to the real model-source
+``simulo.interfaces.authoring.asset.AssetSource`` (the single, dependency-free
+definition the backend consumes — relocated out of the backend in Plan C, renamed
+from ``Asset`` by owner decision to resolve the name collision with this very class).
+
+**Layer split.** This is the user-facing *handle* (``simulo.Asset``); the
+asset-catalog **wire** contract (ref grammar, routes, caps, wire dataclasses) lives
+in ``simulo.interfaces.platform.asset_catalog`` — this module consumes that
+module's :func:`parse_asset_ref` and stays decoupled from it otherwise.
+"""
+
+import contextlib
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterator, List, Optional, Tuple
+
+from simulo._client._mounts import asset_env_key
+from simulo._client.mode import EXECUTION, current_mode
+from simulo.interfaces.authoring import AssetSource as _ModelSourceAsset
+from simulo.interfaces.exceptions import ContractViolationError, ResourceNotFoundError
+from simulo.interfaces.platform.asset_catalog import (
+    GLOBAL_ASSET_PUBLISHER,
+    RESERVED_ASSET_PUBLISHERS,
+    ParsedAssetRef,
+    format_asset_ref,
+    parse_asset_ref,
+)
+
+# ---------------------------------------------------------------------------
+# Construction capture — every `Asset.from_registry(...)` handle constructed
+# while a capture scope is active is recorded here (the viewstream/seed
+# ambient-signal pattern in `app.py`, applied to CONSTRUCTION rather than a
+# submit flag). This is what lets an UNMOUNTED registry handle
+# (`forklift = simulo.Asset.from_registry(...)`, used only via
+# `Robot(asset=forklift)`, never passed to `App(mounts=...)`) still get
+# resolved and pinned: `simulo run` arms this scope BEFORE importing the app
+# file (so module-level constructions are seen) and keeps it armed through the
+# whole entrypoint invocation. `bundle.build_manifest` unions the captured
+# assets into the manifest's `resources` list alongside the App's own
+# `mounts=`-declared ones (authored-ref mount invariant — "Handle collection
+# is CONSTRUCTION-CAPTURE, not mount-only").
+# ---------------------------------------------------------------------------
+
+_CONSTRUCTION_CAPTURE: Optional[List["Asset"]] = None
+
+
+@contextlib.contextmanager
+def capture_constructed_assets() -> Iterator[List["Asset"]]:
+    """Collect every :class:`Asset` constructed in this scope (nestable; the
+    innermost active scope receives each construction)."""
+    global _CONSTRUCTION_CAPTURE
+    previous = _CONSTRUCTION_CAPTURE
+    captured: List["Asset"] = []
+    _CONSTRUCTION_CAPTURE = captured
+    try:
+        yield captured
+    finally:
+        _CONSTRUCTION_CAPTURE = previous
+
+
+def current_captured_assets() -> Tuple["Asset", ...]:
+    """Every :class:`Asset` constructed so far in the active capture scope, or
+    ``()`` when no scope is active (e.g. a direct ``JobFunction.spawn()`` call
+    outside ``simulo run`` — that path still resolves whatever the App's own
+    ``mounts=`` declares; construction-capture only ADDS coverage for
+    unmounted handles, it is never the sole source of truth)."""
+    if _CONSTRUCTION_CAPTURE is None:
+        return ()
+    return tuple(_CONSTRUCTION_CAPTURE)
+
+
+@dataclass(frozen=True)
+class _AssetSpec:
+    """Inert, torch-free model-asset spec produced in discovery mode.
+
+    Records the *kind* (``"usd"`` / ``"urdf"``) and source ``path`` a user named via
+    ``Asset.usd(...)`` / ``Asset.urdf(...)``. It is never used for computation at
+    submit — the real model-source asset is materialised on the worker.
+    """
+
+    kind: str
+    path: str
+
+
+def _parse_registry_ref(uri: str) -> ParsedAssetRef:
+    """Parse a registry ref through the shared grammar, re-raising as a
+    :class:`ContractViolationError` (the SDK's user-facing input-error type).
+
+    The wire grammar raises :class:`ValueError` with a user-language-first
+    message; the SDK surface speaks ``ContractViolationError``, so the message is
+    preserved and only the type is adapted — a bad ref reads the same whether it
+    reaches the user through the CLI resolver or this handle.
+    """
+    try:
+        return parse_asset_ref(uri)
+    except ValueError as exc:
+        raise ContractViolationError(str(exc)) from exc
+
+
+def _asset_cache_root() -> Path:
+    """The local catalog cache root — ``~/.simulo/assets`` (what ``simulo asset
+    get`` writes into). Reads ``$HOME`` via :meth:`Path.home` so test isolation
+    (a redirected ``HOME``) is honored in-process, exactly like the credentials
+    path."""
+    return Path.home() / ".simulo" / "assets"
+
+
+class Asset:
+    """A read-only, registry-resolved resource mounted into running jobs.
+
+    A registry ref is ``[<publisher>/]<kind>/<name>[:v<N>]`` (e.g.
+    ``simulo/robot/cartpole:v1``); :meth:`from_registry` names one, and :attr:`path`
+    resolves to its read-only mount inside a running job. ``Asset`` is also how a
+    task names USD/URDF model sources to load into a scene — :meth:`usd` /
+    :meth:`urdf`.
+
+    Raises:
+        ContractViolationError: if ``uri`` is not a valid
+            ``[<publisher>/]<kind>/<name>[:v<N>]`` ref.
+    """
+
+    def __init__(self, uri: str, *, read_only: bool = True) -> None:
+        self._ref = _parse_registry_ref(uri)
+        self._uri = uri
+        self._read_only = read_only
+        if _CONSTRUCTION_CAPTURE is not None:
+            _CONSTRUCTION_CAPTURE.append(self)
+
+    @classmethod
+    def from_registry(cls, uri: str, read_only: bool = True) -> "Asset":
+        """Get a handle to the registry asset at ``uri``.
+
+        ``uri`` is a catalog ref ``[<publisher>/]<kind>/<name>[:v<N>]`` — the
+        publisher defaults to your own org, ``simulo`` names the global catalog,
+        and an omitted ``:v<N>`` is resolved to the current latest **at submit**.
+        The handle is directly consumable wherever a model source is
+        accepted — ``Robot(asset=...)`` for a ``robot`` ref, ``scene.add(...)``
+        for a ``world`` ref.
+        """
+        return cls(uri, read_only=read_only)
+
+    @classmethod
+    def usd(cls, path: str) -> Any:
+        """Name a USD model source to load into a scene.
+
+        At submit time this returns an inert, torch-free spec object so authoring
+        stays lean; in the execution runtime it resolves to the real model asset. The return
+        type depends on mode, so it is typed ``Any``.
+        """
+        return cls._model_asset("usd", path)
+
+    @classmethod
+    def urdf(cls, path: str) -> Any:
+        """Name a URDF model source to load into a scene (see :meth:`usd`)."""
+        return cls._model_asset("urdf", path)
+
+    @staticmethod
+    def _model_asset(kind: str, path: str) -> Any:
+        if current_mode() == EXECUTION:
+            # The model-source AssetSource is the dependency-free
+            # ``simulo.interfaces.authoring.asset.AssetSource`` (single definition,
+            # relocated out of the backend in Plan C) — importable statically
+            # and torch-free, so no lazy import is needed any more.
+            factory = getattr(_ModelSourceAsset, kind)
+            return factory(path)
+        return _AssetSpec(kind=kind, path=path)
+
+    @property
+    def uri(self) -> str:
+        """The registry ref as authored (``[<publisher>/]<kind>/<name>[:v<N>]``)."""
+        return self._uri
+
+    @property
+    def kind(self) -> str:
+        """The ``<kind>`` segment of the ref — ``"robot"``, ``"world"``, or ``"prop"``."""
+        return self._ref.kind
+
+    @property
+    def name(self) -> str:
+        """The asset ``<name>`` slug."""
+        return self._ref.name
+
+    @property
+    def publisher(self) -> Optional[str]:
+        """The owning catalog publisher (``"simulo"`` = global, an org slug, or
+        ``None`` when omitted — the caller's own org)."""
+        return self._ref.publisher
+
+    @property
+    def version(self) -> Optional[int]:
+        """The pinned version number, or ``None`` for an unpinned ref (resolved at
+        submit)."""
+        return self._ref.version
+
+    @property
+    def is_read_only(self) -> bool:
+        """Whether this handle is read-only (registry assets always are)."""
+        return self._read_only
+
+    def read_only(self) -> "Asset":
+        """Return a read-only view of this asset (builder marker)."""
+        return Asset(self._uri, read_only=True)
+
+    def require_kind(self, expected: str) -> None:
+        """Fail with a one-line explanation if this asset's kind is not ``expected``.
+
+        The consumption-side half of **kind safety**: a ``robot`` context
+        (``Robot(asset=...)``) requires a ``robot`` asset, a ``world`` context a
+        ``world`` asset. ``simulo.core.Robot`` calls this (duck-typed) so
+        ``Robot(asset=simulo.Asset.from_registry("world/warehouse:v2"))`` fails
+        with a clear message rather than surfacing later as an opaque runtime
+        error. The kind is known from the ref itself, so the check is a cheap
+        string comparison — no catalog lookup.
+        """
+        if self._ref.kind == expected:
+            return
+        message = (
+            f"asset {self._uri!r} is a {self._ref.kind!r} asset, but a {expected!r} asset is required here — "
+            f"use a {expected}/... ref."
+        )
+        if expected == "robot":
+            # The common mix-up: a world handed to Robot(asset=...). Name the right
+            # consumption site so the fix is obvious.
+            message += " A world asset is added to the scene with scene.add(...), not built as a robot."
+        raise ContractViolationError(message)
+
+    @property
+    def path(self) -> str:
+        """Local read-only mount path — only meaningful inside a running job.
+
+        Resolution order, in execution mode:
+
+        1. ``SIMULO_ASSET_<uri>`` — the mount the execution environment
+           exported for this asset. When set, it is authoritative.
+        2. The on-disk catalog cache ``~/.simulo/assets/<org>/<kind>/<name>/v<N>/``
+           — the colon-free layout ``simulo asset get`` writes into. Used for a
+           local run with no runner-provided mount.
+
+        Raises outside execution mode, or — when neither a mount env var nor a
+        cached copy is present — with the exact ``simulo asset get <ref>`` command
+        to fetch it.
+        """
+        if current_mode() != EXECUTION:
+            raise ResourceNotFoundError(
+                f"Asset {self._uri!r}.path is only available inside a running job "
+                f"(SIMULO_MODE={EXECUTION!r}); it is not resolvable during packaging."
+            )
+        mount = os.environ.get(asset_env_key(self._uri))
+        if mount is not None:
+            return mount
+        cached = self._resolve_from_cache()
+        if cached is not None:
+            return str(cached)
+        raise ResourceNotFoundError(
+            f"Asset {self._uri!r} is not mounted and no local copy was found. Fetch it first:\n"
+            f"    simulo asset get {self._uri}"
+        )
+
+    def _resolve_from_cache(self) -> Optional[Path]:
+        """Find this asset in ``~/.simulo/assets/<org>/<kind>/<name>/v<N>/``, or ``None``.
+
+        **No silent cross-catalog fallback** (authored-ref mount invariant): an
+        explicit-publisher ref (``simulo`` for the global catalog, or an org slug)
+        resolves under that ONE catalog directory only. An omitted-publisher ref
+        means the caller's OWN org and NOTHING ELSE — every :data:`RESERVED_ASSET_PUBLISHERS`
+        directory (chief among them ``simulo``, the global catalog) is excluded from
+        its glob, so a cached global copy can never silently satisfy an own-org ref.
+        The caller's actual org slug is not resolvable client-side (saved
+        credentials carry only ``active_organization_id``, a UUID, never a slug),
+        so "not a reserved word" is the best available own-org filter.
+
+        Zero or ambiguous (``> 1``) matches resolve to ``None`` (the caller renders
+        the generic ``simulo asset get <ref>`` hint). The one exception: an
+        omitted-publisher ref with ZERO own-org matches but a cache hit under the
+        GLOBAL catalog raises directly here, naming the exact global ref — a
+        cross-catalog hit is real, useful information, not a plain miss.
+        """
+        root = _asset_cache_root()
+        version_glob = f"v{self._ref.version}" if self._ref.version is not None else "v*"
+
+        if self._ref.publisher is not None:
+            pattern = f"{self._ref.publisher}/{self._ref.kind}/{self._ref.name}/{version_glob}"
+            matches = sorted(p for p in root.glob(pattern) if p.is_dir())
+            return matches[0] if len(matches) == 1 else None
+
+        pattern = f"*/{self._ref.kind}/{self._ref.name}/{version_glob}"
+        all_matches = sorted(p for p in root.glob(pattern) if p.is_dir())
+        own_org_matches = [p for p in all_matches if p.relative_to(root).parts[0] not in RESERVED_ASSET_PUBLISHERS]
+        if len(own_org_matches) == 1:
+            return own_org_matches[0]
+        if not own_org_matches:
+            global_matches = [p for p in all_matches if p.relative_to(root).parts[0] == GLOBAL_ASSET_PUBLISHER]
+            if global_matches:
+                hint_ref = format_asset_ref(
+                    publisher=GLOBAL_ASSET_PUBLISHER,
+                    kind=self._ref.kind,
+                    name=self._ref.name,
+                    version=int(global_matches[0].name.removeprefix("v")),
+                )
+                raise ResourceNotFoundError(
+                    f"Asset {self._uri!r} has no local copy under your own org's cache, but the GLOBAL "
+                    f"catalog has one cached. Catalogs never fall back to each other silently — if you "
+                    f"meant the global asset, use its explicit ref:\n"
+                    f"    simulo asset get {hint_ref}"
+                )
+        return None  # zero, or ambiguous (>1), own-org matches