simulo 0.16.0__tar.gz → 0.17.0__tar.gz

{simulo-0.16.0/src/simulo.egg-info → simulo-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.16.0
+Version: 0.17.0
 Summary: Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause
@@ -15,17 +15,18 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.11,>=0.10
+Requires-Dist: simulo-interfaces<0.12,>=0.11
 Requires-Dist: mcap<2,>=1.3
 Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: usd-core<27,>=25.5
 Provides-Extra: assets
 Requires-Dist: usd-core<27,>=25.5; extra == "assets"
 Provides-Extra: dev
-Requires-Dist: black>=24.0; extra == "dev"
-Requires-Dist: isort>=5.13; extra == "dev"
-Requires-Dist: ruff>=0.5; extra == "dev"
-Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: black==26.5.1; extra == "dev"
+Requires-Dist: isort==8.0.1; extra == "dev"
+Requires-Dist: ruff==0.15.21; extra == "dev"
+Requires-Dist: mypy==2.3.0; extra == "dev"
+Requires-Dist: types-defusedxml==0.7.0.20260504; extra == "dev"
 Requires-Dist: pytest>=8.2; extra == "dev"
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: twine>=5.1; extra == "dev"

{simulo-0.16.0 → simulo-0.17.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.16.0"
+version = "0.17.0"
 description = "Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud."
 readme = "PYPI.md"
 requires-python = ">=3.11"
@@ -26,7 +26,7 @@ classifiers = [
 # mcap: used by `simulo recordings` to read back a downloaded recording and
 # verify it (message count) — MIT-licensed, deps only lz4+zstandard.
 dependencies = [
-    "simulo-interfaces>=0.10,<0.11",
+    "simulo-interfaces>=0.11,<0.12",
     "mcap>=1.3,<2",
     # Hardened XML parsing for URDF ingestion (USD Asset Catalogs, PR-12 fix
     # loop 2, security NIT): stdlib xml.etree.ElementTree relies on
@@ -54,7 +54,27 @@ dependencies = [
 # already installed unconditionally) but harmless — resolvers don't warn on
 # an extra whose contents are already satisfied by the base requirement.
 assets = ["usd-core>=25.5,<27"]
-dev = ["black>=24.0", "isort>=5.13", "ruff>=0.5", "mypy>=1.10", "pytest>=8.2", "build>=1.2", "twine>=5.1"]
+# black/isort/ruff/mypy pinned EXACT, not >=: see simulo-backend/pyproject.toml's
+# `dev` extra for the full rationale (2026-08-01 ruff 0.15.21->0.16.1 CI incident).
+# Keep in lockstep with `.github/workflows/simulo-ci.yml`'s `ruff`/`black`/`isort`/`mypy`
+# steps, which resolve their versions from THIS extra (`pip install -e ".[dev]"`).
+#
+# `types-defusedxml` is pinned EXACT for the same reason as the four tools above:
+# a stub package is a rule set, and a new typeshed release can tighten a
+# signature and turn a green tree red with no code change. `defusedxml` is a
+# declared RUNTIME dependency of this package (asset_package.py parses URDF with
+# it), so without the stubs mypy reported `Library stubs not installed` and —
+# worse — silently skipped type-checking every call into it.
+dev = [
+    "black==26.5.1",
+    "isort==8.0.1",
+    "ruff==0.15.21",
+    "mypy==2.3.0",
+    "types-defusedxml==0.7.0.20260504",
+    "pytest>=8.2",
+    "build>=1.2",
+    "twine>=5.1",
+]
 # `dev` carries build/twine but deliberately not commitizen; `release` below
 # adds commitizen for cutting version bumps without a second build/twine copy.
 release = ["commitizen>=3.27", "build>=1.2", "twine>=5.1"]
@@ -91,6 +111,17 @@ namespace_packages = true
 explicit_package_bases = true
 strict = true
 
+# `pxr` (the USD Python bindings, shipped by `usd-core`) is a C++-backed
+# extension module that publishes neither type stubs nor a `py.typed` marker,
+# so there is no more precise type available for it than the module object
+# itself. Suppressed at the module level — the same mechanism, and for the same
+# reason, as simulo-backend/pyproject.toml's skrl / onnxruntime overrides.
+# Scoped to `pxr` alone, so it cannot hide a real type error anywhere else:
+# `_load_pxr_usdutils` is the ONLY place this package imports it.
+[[tool.mypy.overrides]]
+module = ["pxr", "pxr.*"]
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "--import-mode=importlib"

simulo-0.17.0/src/simulo/__init__.py

@@ -0,0 +1,409 @@
+"""Simulo thin client — the user-facing, torch-free SDK surface.
+
+This is the ONE Simulo distribution that ships ``simulo/__init__.py``. The
+``extend_path`` call below unions every ``simulo/`` directory on ``sys.path`` into
+this package's ``__path__`` so the PEP 420 namespace portions shipped by sibling
+distributions (``simulo.core`` / ``simulo.backend`` / ``simulo.recording`` from
+``simulo-backend``; ``simulo.interfaces`` from ``simulo-interfaces``) resolve
+alongside the clean top-level ``simulo.App`` re-exported here.
+
+It MUST run before the re-exports below, because importing the thin client's
+internal ``App`` module pulls in ``simulo.interfaces`` (a sibling distribution).
+
+**The one-import rule.** Everything a user can legitimately need is reachable
+from ``import simulo``. ``simulo.interfaces`` is a packaging detail two
+distributions share so the thin client and the backend hold ONE definition
+instead of drifting copies — it is never a namespace a user types. A user who
+can write ``simulo.Physics.rigid(...)`` must not have to discover a second
+import to write ``except simulo.JobFailedError`` or
+``collision=simulo.Collision.enabled()``.
+
+The rule is enforced as a rule, not as a hand-kept list: the thin client's
+one-import-rule test derives the expected surface from
+``simulo.interfaces.__all__`` and ``simulo.interfaces.authoring.__all__`` and
+fails on any name that is not reachable here or explicitly declared in that
+test's exclusions table with a reason. A hand-maintained whitelist is only ever
+as current as the last person who remembered to edit it, and two names were
+missed that way before the rule replaced it.
+
+Three kinds of name live on ``simulo``:
+
+* **Platform** names — ``App / Runtime / Volume / Asset / Artifact /
+  ArtifactKind / callbacks`` — are **real, eager** attributes bound below.
+  They are always torch-free (``Artifact`` is the ``simulo-interfaces``
+  contract dataclass, ``ArtifactKind`` its wire-stable ``StrEnum``, both
+  re-exported).
+* **Contract vocabulary** — the shared error hierarchy (``SimuloError`` and its
+  subclasses), the ``NewType`` identifier aliases (``JobId``, ``ProjectId``, …),
+  and the authoring value types that are not already carried by the lazy
+  resolver (``Collision``, ``Transform``, the primitive shapes, the factory
+  return types, the markers, …) — are also **real, eager** attributes. They cost
+  nothing to bind: ``simulo.interfaces.authoring`` is a zero-dependency package
+  that the thin client's own learning resolver already imports at module scope,
+  so this adds no import and no dependency. Errors and IDs are likewise
+  stdlib-only (``NewType`` is the underlying ``str`` at runtime).
+* **Lazy, mode-aware** names — the learning names ``Task / Scene / Robot /
+  LearningEnv / RLTrainer / …`` plus the execution-time ``save_artifact`` and
+  ``run`` (the scenario execution loop) — are
+  resolved through the PEP 562 ``__getattr__`` below, which delegates to the
+  thin client's internal learning-name resolver. At submit (discovery mode) they resolve to
+  lean stand-ins so the user app imports without the heavy runtime; only the
+  backend runner (execution mode) resolves them to the real implementations.
+  Because the platform names are real attributes, ``__getattr__`` fires *only*
+  for the lazy names. The RELOCATED authoring value types (``Pose`` /
+  ``Material`` / ``Physics`` / ``Light`` / ``Terrain`` / ``World`` /
+  ``Entity`` / ``Visual`` / ``RecordConfig``) ride the same resolver but
+  resolve to their real, dependency-free ``simulo.interfaces.authoring``
+  class in BOTH modes — they need no heavy runtime, and exactly one
+  definition exists. (``Terrain`` is ground you generate; ``World`` is a
+  prebuilt place you bring, ``World.usd(...)``.)
+"""
+
+import pkgutil as _pkgutil
+from typing import TYPE_CHECKING
+
+__path__ = _pkgutil.extend_path(__path__, __name__)
+
+from simulo import callbacks
+from simulo._client.app import App
+from simulo._client.asset import Asset
+from simulo._client.learning import LEARNING_NAMES as _LEARNING_NAMES
+from simulo._client.learning import resolve as _resolve_learning
+from simulo._client.runtime import Runtime
+from simulo._client.volume import Volume
+
+# --- Contract vocabulary, re-exported under the one-import rule ---------------
+#
+# The shared error hierarchy and the identifier aliases. Both are stdlib-only:
+# the exceptions derive from ``Exception``, and every identifier is a
+# ``typing.NewType`` over ``str`` (zero runtime cost, distinct to a type
+# checker). A user catching a failed job writes ``except simulo.JobFailedError``,
+# never a second import.
+from simulo.interfaces import (
+    CheckpointId,
+    ContractViolationError,
+    Digest,
+    ImportResolutionError,
+    JobFailedError,
+    JobId,
+    OrganizationId,
+    PackageId,
+    ProjectId,
+    ResourceId,
+    ResourceNotFoundError,
+    ResourceUri,
+    ResumeIncompatibleError,
+    SimuloError,
+    TagId,
+    TrainedModelId,
+)
+
+# The authoring value types that the lazy resolver does NOT already carry.
+# Every one is a real, dependency-free class with exactly one definition, so —
+# unlike the learning names — there is nothing mode-aware about them and no
+# reason to defer: binding them eagerly is what makes ``simulo.Collision`` and
+# ``simulo.Transform`` exist at all.
+#
+# ``simulo.Asset`` (the thin client's registry HANDLE, imported above — the
+# name every shipped example and doc page uses) and
+# ``simulo.interfaces.authoring.Asset`` (the model-source spec) used to share
+# one name — two different user-facing
+# classes, both exposing ``.usd()`` / ``.urdf()``, so re-exporting the
+# authoring one here would have silently shadowed the handle users actually
+# want. #693 (owner decision) resolved the collision by renaming the
+# contract-side class to ``AssetSource``; with the names distinct, it is
+# re-exported here like every other concrete authoring type — no exclusion
+# needed any more.
+from simulo.interfaces.authoring import (
+    ArrowMarker,
+    AssetEntity,
+    AssetSource,
+    AxesMarker,
+    Collision,
+    Cone,
+    Cuboid,
+    Cylinder,
+    DeformableMaterial,
+    DeformablePhysics,
+    DistantLight,
+    DomeLight,
+    GroundPlane,
+    LightConfig,
+    PointMarker,
+    PrimitiveShape,
+    RigidPhysics,
+    RoughTerrain,
+    Sphere,
+    SphereMarker,
+    SubTerrainConfig,
+    SurfaceMaterial,
+    TerrainConfig,
+    Transform,
+    URDFAsset,
+    USDAsset,
+    USDWorld,
+    VisualMarkerBase,
+)
+from simulo.interfaces.platform import Artifact, ArtifactKind
+
+# Public surface = eager platform exports (real attributes; ``__getattr__`` never
+# fires for these) + the lazily-resolved learning names. Kept a static literal so
+# tooling recognises the re-exports; a test guards it against ``LEARNING_NAMES`` drift.
+__all__ = [
+    # platform (eager, real)
+    "App",
+    "Artifact",
+    "ArtifactKind",
+    "Runtime",
+    "Volume",
+    "Asset",
+    "callbacks",
+    # contract errors (eager, real) — the shared exception hierarchy
+    "SimuloError",
+    "ContractViolationError",
+    "ImportResolutionError",
+    "ResourceNotFoundError",
+    "ResumeIncompatibleError",
+    "JobFailedError",
+    # contract identifiers (eager, real) — NewType aliases over ``str``
+    "OrganizationId",
+    "ProjectId",
+    "PackageId",
+    "JobId",
+    "ResourceId",
+    "CheckpointId",
+    "TrainedModelId",
+    "TagId",
+    "ResourceUri",
+    "Digest",
+    # authoring value types (eager, real) — the rest of the vocabulary the
+    # lazy resolver below does not carry
+    "Collision",
+    "RigidPhysics",
+    "DeformableMaterial",
+    "DeformablePhysics",
+    "SurfaceMaterial",
+    "AssetSource",
+    "USDAsset",
+    "URDFAsset",
+    "LightConfig",
+    "DistantLight",
+    "DomeLight",
+    "TerrainConfig",
+    "GroundPlane",
+    "SubTerrainConfig",
+    "RoughTerrain",
+    "USDWorld",
+    "PrimitiveShape",
+    "Cone",
+    "Cuboid",
+    "Sphere",
+    "Cylinder",
+    "Transform",
+    "AssetEntity",
+    "VisualMarkerBase",
+    "AxesMarker",
+    "SphereMarker",
+    "ArrowMarker",
+    "PointMarker",
+    # lazy, mode-aware (the learning names + save_artifact)
+    "ActuatorGainsConfig",
+    "Camera",
+    "CameraSpawnConfig",
+    "ContactSensor",
+    "DifferentialIKController",
+    "Entity",
+    "ForceTorqueSensor",
+    "FrameTransformer",
+    "FrameTransformerTarget",
+    "GripperState",
+    "IMU",
+    "LearningEnv",
+    "Light",
+    "Material",
+    "ObservationComponent",
+    "ObservationSet",
+    "OperationalSpaceController",
+    "Physics",
+    "Player",
+    "Policy",
+    "Pose",
+    "RLPlayer",
+    "RLTrainer",
+    "RayCaster",
+    "RayPattern",
+    "RecordConfig",
+    "RewardComponent",
+    "RewardSet",
+    "Robot",
+    "Scenario",
+    "Scene",
+    "SensorOffset",
+    "Simulation",
+    "SurfaceGripperActuator",
+    "Task",
+    "Terrain",
+    "TerminationCondition",
+    "TerminationSet",
+    "Trainer",
+    "Visual",
+    "World",
+    "run",
+    "save_artifact",
+]
+
+
+def __getattr__(name: str) -> object:
+    """PEP 562 hook: lazily resolve the mode-aware learning names.
+
+    Fires only for attributes missing from the module dict — i.e. never for the
+    real platform exports above. Delegates the learning names to the thin
+    client's internal resolver (discovery stand-in vs. real
+    ``simulo.core`` class, by mode); everything else is a genuine ``AttributeError``.
+    """
+    if name in _LEARNING_NAMES:
+        return _resolve_learning(name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Expose only the public surface to ``dir(simulo)``.
+
+    That is ``__all__`` (eager platform exports + learning names) unioned with
+    :data:`LEARNING_NAMES`. Private module globals (``_pkgutil``,
+    ``_resolve_learning``, ``_LEARNING_NAMES``, the ``TYPE_CHECKING`` import, …)
+    are deliberately filtered out so tab-completion shows the user-facing API only.
+    """
+    return sorted(set(__all__) | set(_LEARNING_NAMES))
+
+
+if TYPE_CHECKING:
+    # Static aliases so a type checker sees the learning names with precise types
+    # (PEP 562 ``__getattr__`` would otherwise type them as ``Any``). The rule that
+    # this block MUST follow — and that the mypy positive test in
+    # ``tests/test_learning_typing.py`` locks — is:
+    #
+    # * **Subclassable** names (used as ``class X(simulo.Task)``) alias their
+    #   ``interfaces.runtime`` Protocol, so the subclass is checked against the
+    #   contract (e.g. ``TaskProtocol``).
+    # * **Instantiated mirror** names (used as ``simulo.LearningEnv(task=...)``,
+    #   ``simulo.RLTrainer(env=...)``, ``simulo.Robot(...)``,
+    #   ``simulo.RLPlayer(env=...)``) alias their typing FACADE in the thin
+    #   client's internal facades module — a Protocol alias would make mypy
+    #   reject instantiation ("Cannot instantiate protocol class"), and
+    #   ``Any`` (the pre-Wave-C4 rule) type-checked nothing. The facade
+    #   declares the contract surface plus the real constructor, so both the
+    #   call and every member access are checked against the real member set
+    #   and signature shape (name, kind, arity, presence of a default —
+    #   NOT the declared type; see the facades module docstring for the
+    #   known gap); facade fidelity to the contract AND to the concrete
+    #   worker class is pinned by the backend suite's conformance engine.
+    # * **Called mirror** name (``simulo.run(scenario_class, ...)`` — the one
+    #   non-learning, non-instantiated member of this kind): same problem as
+    #   an instantiated mirror one level down — with no override, ``run``
+    #   types as ``object`` (``__getattr__``'s declared return), and
+    #   ``object`` is not *callable* at all. It aliases a plain FUNCTION
+    #   facade (there is no Protocol for a bare function to alias against),
+    #   never registered in the backend's class-shaped conformance engine —
+    #   see the facades module docstring for where its drift guard lives
+    #   instead.
+    # * **Annotation-position mirror** names alias their contract Protocol:
+    #   ``Scene`` is ``SceneProtocol`` — measured across every shipped user
+    #   surface it appears only as ``def build(self, scene: simulo.Scene)``,
+    #   never instantiated, and the Protocol alias is what keeps that override
+    #   Liskov-compatible with the contract's ``scene: SceneProtocol``.
+    # * **Relocated value types** alias their real, dependency-free
+    #   ``simulo.interfaces.authoring`` class — precise field checking in both
+    #   modes, because only one definition exists.
+    #
+    # Engine authoring vocabulary (the one-import rule's second half —
+    # ``Camera`` and its sensor siblings, ``Simulation``, the controllers, the
+    # actuators, the ``*Set`` containers): only ``Camera`` gets an alias here. ``CameraProtocol`` exists
+    # in ``simulo.interfaces.authoring`` and ``Camera`` is instantiated
+    # (``simulo.Camera(width=640, ...)``, never subclassed), so it follows the
+    # "instantiated mirror -> facade" rule above exactly. The other 17 names
+    # have no TYPE_CHECKING alias, DELIBERATELY, per the rule's own "where none
+    # exists, do not invent one" corollary:
+    #   - ``CameraSpawnConfig`` / ``SensorOffset`` / ``RayPattern`` /
+    #     ``ActuatorGainsConfig`` / ``GripperState`` / ``Simulation`` have no
+    #     contract Protocol at all — nothing to alias against.
+    #   - ``ContactSensor`` / ``RayCaster`` / ``IMU`` / ``ForceTorqueSensor`` /
+    #     ``FrameTransformer`` conform only to the BASE ``SensorProtocol``
+    #     (path/update_period/enabled/debug_vis/name/update/reset) — it does not
+    #     declare their type-specific readers (``read_net_forces``,
+    #     ``read_hits``, ``read_linear_acceleration``, …), so aliasing them to
+    #     ``SensorProtocol`` would be a LOSSY, misleading type (mypy would flag
+    #     real shipped calls to those readers as errors) and aliasing to a
+    #     Protocol at all breaks instantiation ("Cannot instantiate protocol
+    #     class") — the same reason facades exist. Their own per-type contracts
+    #     are a later decision (``simulo.interfaces.authoring.sensor``'s own
+    #     docstring), not implied here.
+    #   - ``ObservationSet`` / ``RewardSet`` / ``TerminationSet`` /
+    #     ``DifferentialIKController`` / ``OperationalSpaceController`` /
+    #     ``SurfaceGripperActuator`` have no dedicated Protocol either.
+    #   Runtime resolution (the lazy resolver) is unaffected either way — these
+    #   fall back to ``__getattr__``'s ``-> object`` return type for a type
+    #   checker, same as any name with no static override.
+    from simulo._client.facades import Camera as Camera
+    from simulo._client.facades import LearningEnv as LearningEnv
+    from simulo._client.facades import RLPlayer as RLPlayer
+    from simulo._client.facades import RLTrainer as RLTrainer
+    from simulo._client.facades import Robot as Robot
+    from simulo.interfaces.authoring import SceneProtocol
+    from simulo.interfaces.runtime import (
+        ObservationComponentProtocol,
+        PlayerProtocol,
+        PolicyProtocol,
+        RewardComponentProtocol,
+        ScenarioProtocol,
+        TaskProtocol,
+        TerminationConditionProtocol,
+        TrainerProtocol,
+    )
+
+    # Subclassable names alias their Protocol so ``class X(simulo.Task)`` is checked
+    # against ``TaskProtocol``.
+    Task = TaskProtocol
+    Scenario = ScenarioProtocol
+    Policy = PolicyProtocol
+    Player = PlayerProtocol
+    Trainer = TrainerProtocol
+    ObservationComponent = ObservationComponentProtocol
+    RewardComponent = RewardComponentProtocol
+    TerminationCondition = TerminationConditionProtocol
+    # Annotation-position mirror name (see the rule above).
+    Scene = SceneProtocol
+    # ``save_artifact`` aliases its real execution-mode implementation (a
+    # torch-free thin-client function), so ``simulo.save_artifact("summary",
+    # path)`` type-checks with the precise signature instead of ``Any``.
+    from simulo._client.artifacts import save_artifact as save_artifact
+
+    # ``run`` (the scenario execution loop) aliases its typing FACADE — a
+    # plain FUNCTION facade, not a class one (there is no ``RunProtocol`` to
+    # alias against; ``run`` is not a contract method). Without this, ``run``
+    # falls back to ``__getattr__``'s ``-> object`` return type, and
+    # ``object`` is not callable: ``simulo.run(MyScenario, ...)`` in a freshly
+    # scaffolded app is a hard mypy error no ``--ignore-missing-imports`` can
+    # suppress. The facade's real target (``simulo.scenario.run``) lives in
+    # the ``simulo-backend`` distribution — outside this package's own
+    # ``MYPYPATH`` — but the facade itself is thin-client-resident code
+    # (``simulo/_client/facades.py``), exactly like ``Camera``'s facade for
+    # the same reason; see that module's docstring for the full rationale and
+    # where drift against the real function is caught (a live, unmocked
+    # signature comparison in ``simulo-backend``'s test suite, not mypy).
+    from simulo._client.facades import run as run
+
+    # RELOCATED authoring value types (Plan C — Waves C1, C2, then C4's
+    # ``RecordConfig``): the runtime object IS the real, dependency-free
+    # ``simulo.interfaces.authoring`` class in both
+    # modes, so these alias the real class — precise field/signature checking
+    # (e.g. mypy rejects ``simulo.Pose(xyz="nope")``) instead of ``Any``.
+    from simulo.interfaces.authoring import Entity as Entity
+    from simulo.interfaces.authoring import Light as Light
+    from simulo.interfaces.authoring import Material as Material
+    from simulo.interfaces.authoring import Physics as Physics
+    from simulo.interfaces.authoring import Pose as Pose
+    from simulo.interfaces.authoring import RecordConfig as RecordConfig
+    from simulo.interfaces.authoring import Terrain as Terrain
+    from simulo.interfaces.authoring import Visual as Visual
+    from simulo.interfaces.authoring import World as World

{simulo-0.16.0 → simulo-0.17.0}/src/simulo/_client/asset.py

@@ -23,8 +23,9 @@ The on-disk :attr:`path` only exists in **execution mode**:
 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.Asset`` (the single, dependency-free
-definition the backend consumes — relocated out of the backend in Plan C).
+``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
@@ -40,7 +41,7 @@ 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 Asset as _ModelSourceAsset
+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,
@@ -181,8 +182,8 @@ class Asset:
     @staticmethod
     def _model_asset(kind: str, path: str) -> Any:
         if current_mode() == EXECUTION:
-            # The model-source Asset is the dependency-free
-            # ``simulo.interfaces.authoring.asset.Asset`` (single definition,
+            # 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)

{simulo-0.16.0 → simulo-0.17.0}/src/simulo/_client/asset_api.py

@@ -574,9 +574,9 @@ def upload_archive(
     uploaded = 0
     for start in range(0, len(needed), _MAX_PART_NUMBERS_PER_BATCH):
         batch = needed[start : start + _MAX_PART_NUMBERS_PER_BATCH]
-        specs = {int(spec["part_number"]): spec for spec in client.presign_parts(version_id, batch)}
+        specs_by_number = {int(spec["part_number"]): spec for spec in client.presign_parts(version_id, batch)}
         for part_number in batch:
-            spec = specs.get(part_number)
+            spec = specs_by_number.get(part_number)
             if spec is None:
                 raise AssetApiError(f"The server did not presign part {part_number}.")
             chunk = _read_chunk(tar_path, part_number, part_size)

{simulo-0.16.0 → simulo-0.17.0}/src/simulo/_client/asset_package.py

@@ -66,6 +66,7 @@ import xml.etree.ElementTree as ET
 from dataclasses import dataclass, field
 from hashlib import sha256
 from pathlib import Path, PurePosixPath
+from types import ModuleType
 from typing import Callable, Iterable, Optional
 
 import defusedxml.ElementTree as DefusedET
@@ -132,7 +133,7 @@ class AssetsExtraMissingError(AssetPackageError):
 ASSETS_EXTRA_INSTALL_HINT = 'pip install "simulo[assets]"'
 
 
-def _load_pxr_usdutils():  # pragma: no cover - exercised via _extract_usd_references seam
+def _load_pxr_usdutils() -> ModuleType:  # pragma: no cover - exercised via _extract_usd_references seam
     """Import ``pxr.UsdUtils`` lazily — the ONLY place ``pxr`` is ever imported.
 
     Raises :class:`AssetsExtraMissingError` with the copyable install command
@@ -145,7 +146,11 @@ def _load_pxr_usdutils():  # pragma: no cover - exercised via _extract_usd_refer
             "Publishing or validating a USD package needs the USD inspection extra. "
             f"Install it with: {ASSETS_EXTRA_INSTALL_HINT}"
         ) from exc
-    return UsdUtils
+    # `pxr` publishes no stubs (see the mypy override in pyproject.toml), so
+    # `UsdUtils` arrives as Any. Bind through a typed local so this function
+    # hands its caller a real ModuleType instead of leaking Any across the seam.
+    usd_utils: ModuleType = UsdUtils
+    return usd_utils
 
 
 def _extract_usd_references(layer_path: Path) -> list[str]:
@@ -905,10 +910,21 @@ def _inspect_urdf(
             "declarations and re-run."
         ) from exc
 
+    # ElementTree types getroot() as Optional because a tree can be constructed
+    # empty; a tree returned by a SUCCESSFUL parse always has a root, so this
+    # branch is unreachable in practice. It is a real check rather than a cast
+    # so that if it ever were reached, it surfaces as the same clean
+    # publish-time error as every other URDF problem — never an AttributeError.
+    root_element = tree.getroot()
+    if root_element is None:  # pragma: no cover - unreachable after a successful parse
+        raise AssetPackageError(
+            f"{entry_rel} is not parseable as URDF XML: it has no root element. Fix the file and re-run."
+        )
+
     closure: dict[str, Path] = {entry_rel: entry_abs}
     reference_count = 0
     rewrites: list[tuple[ET.Element, str]] = []  # (element, new entry-relative filename)
-    for element in tree.getroot().iter():
+    for element in root_element.iter():
         if element.tag not in ("mesh", "texture"):
             continue
         ref = element.get("filename")
@@ -935,7 +951,7 @@ def _inspect_urdf(
     if reference_count > 0:
         for element, new_filename in rewrites:
             element.set("filename", new_filename)
-        entry_override_bytes = ET.tostring(tree.getroot(), encoding="utf-8", xml_declaration=True)
+        entry_override_bytes = ET.tostring(root_element, encoding="utf-8", xml_declaration=True)
 
     files = sorted(closure.items(), key=lambda item: item[0])
     return entry_rel, auto, files, reference_count, warnings, entry_override_bytes

{simulo-0.16.0 → simulo-0.17.0}/src/simulo/_client/asset_pins.py

@@ -20,7 +20,7 @@ The heavy logic (resolution, gating, rendering) lives here rather than in
 from __future__ import annotations
 
 import sys
-from typing import Dict, List, Optional, Sequence, TextIO
+from typing import Any, Dict, List, Mapping, Optional, Sequence, TextIO
 
 from simulo._client.runtime_display import display_runtime
 from simulo._client.submit_api import AssetPinError, SubmitApiClient
@@ -34,7 +34,7 @@ from simulo.interfaces.platform.asset_catalog import DEFAULT_ASSET_RUNTIME, Reso
 __all__ = ["DEFAULT_ASSET_RUNTIME", "collect_asset_refs", "resolve_and_pin_assets"]
 
 
-def collect_asset_refs(manifest: Dict) -> List[str]:
+def collect_asset_refs(manifest: Mapping[str, Any]) -> List[str]:
     """Return the de-duplicated registry-asset refs an app declared, in first-seen
     order.
 
@@ -85,7 +85,7 @@ def _resolved_publisher(canonical_ref: str) -> Optional[str]:
         return None
 
 
-def _render_resolved_block(refs: Sequence[str], resolved: Dict[str, ResolvedAssetPin]) -> str:
+def _render_resolved_block(refs: Sequence[str], resolved: Mapping[str, ResolvedAssetPin]) -> str:
     """The ``Resolved assets:`` block — the authored (short) ref →
     resolved version + short digest, columns aligned, in the order the refs were
     declared. When the ref OMITTED its publisher (the caller's own org), the