simulo 0.14.0__tar.gz → 0.16.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.14.0
+Version: 0.16.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,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.7,>=0.6
+Requires-Dist: simulo-interfaces<0.11,>=0.10
 Requires-Dist: mcap<2,>=1.3
 Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: usd-core<27,>=25.5
@@ -83,7 +83,7 @@ def hello(name: str = "world", repeat: int = 3) -> dict:
     return {"greeting": f"hello, {name}", "repeat": repeat}
 
 
-@app.local_entrypoint
+@app.entrypoint
 def main(name: str = "world", repeat: int = 3) -> None:
     handle = hello.spawn(name=name, repeat=repeat)
     print(f"Submitted job: {handle.job_name}")

{simulo-0.14.0 → simulo-0.16.0}/PYPI.md

@@ -47,7 +47,7 @@ def hello(name: str = "world", repeat: int = 3) -> dict:
     return {"greeting": f"hello, {name}", "repeat": repeat}
 
 
-@app.local_entrypoint
+@app.entrypoint
 def main(name: str = "world", repeat: int = 3) -> None:
     handle = hello.spawn(name=name, repeat=repeat)
     print(f"Submitted job: {handle.job_name}")

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.14.0"
+version = "0.16.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.6,<0.7",
+    "simulo-interfaces>=0.10,<0.11",
     "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
@@ -100,18 +100,43 @@ markers = [
     "requires_execution_backend: end-to-end test that needs a live execution backend in the loop; skipped in CPU/unit runs",
 ]
 
+# --- Formatters / linters --------------------------------------------------
+# `tests/fixtures/wire_stability/` holds byte-frozen snapshots of real shipped
+# apps. `test_manifest_wire_stability.py` pins their archive digests, so those
+# bytes are INPUT to a gate, not source to be maintained: a formatter version
+# bump that reformats one silently moves every golden and reds the gate with a
+# message blaming the client. Every tool that rewrites files in `tests/` must
+# therefore skip that directory.
+#
+# Each tool needs a SECOND setting to honour the skip when a path is passed
+# EXPLICITLY (`black tests/fixtures/wire_stability/cartpole/app.py`) rather than
+# discovered from a directory — the explicit form is what a changed-files lint
+# invocation or an editor-on-save uses, so plain excludes alone are a false
+# sense of safety (measured: all three tools reformatted the file anyway):
+#   black -> `force-exclude` (not `extend-exclude`)
+#   isort -> `filter_files = true` (and a `*/`-anchored glob)
+#   ruff  -> `force-exclude = true`
+# The source digests are additionally pinned in `_FIXTURE_SOURCE_SHA256`
+# (`tests/test_manifest_wire_stability.py`) as the backstop for any mutation
+# these excludes do not cover.
+
 [tool.isort]
 profile = "black"
 line_length = 120
 known_first_party = ["simulo"]
+extend_skip_glob = ["*/tests/fixtures/wire_stability/*"]
+filter_files = true
 
 [tool.ruff]
 line-length = 120
 src = ["src"]
+extend-exclude = ["tests/fixtures/wire_stability"]
+force-exclude = true
 
 [tool.black]
 line-length = 120
 target-version = ["py311"]
+force-exclude = "tests/fixtures/wire_stability/"
 
 # --- Commitizen ------------------------------------------------------------
 # `cz bump` creates the version-bump commit + tag locally; CI publishes to

simulo-0.16.0/src/simulo/__init__.py

@@ -0,0 +1,188 @@
+"""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).
+
+Two 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).
+* **Lazy, mode-aware** names — the learning names ``Task / Scene / Robot /
+  LearningEnv / RLTrainer / …`` plus the execution-time ``save_artifact`` — 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
+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",
+    # lazy, mode-aware (the learning names + save_artifact)
+    "Entity",
+    "LearningEnv",
+    "Light",
+    "Material",
+    "ObservationComponent",
+    "Physics",
+    "Player",
+    "Policy",
+    "Pose",
+    "RLPlayer",
+    "RLTrainer",
+    "RecordConfig",
+    "RewardComponent",
+    "Robot",
+    "Scenario",
+    "Scene",
+    "Task",
+    "Terrain",
+    "TerminationCondition",
+    "Trainer",
+    "Visual",
+    "World",
+    "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.
+    # * **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.
+    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
+
+    # 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/src/simulo/_client/_entrypoint.py

@@ -0,0 +1,313 @@
+"""Map ``simulo run`` command-line arguments onto a function's signature.
+
+Two submit paths share this module's introspection, pointed at different
+targets:
+
+* **The entrypoint path** — ``simulo run app.py`` maps ``--flag value``
+  arguments onto the registered ``@app.entrypoint``'s parameters and
+  invokes it; the entrypoint's own ``spawn()`` calls end at exactly one
+  submit (:func:`run_entrypoint` / :func:`parse_args`). (A direct ``python
+  app.py`` never reaches this module: :meth:`App.entrypoint` prints the
+  exact equivalent ``simulo run`` command to stderr and exits 2.)
+* **The no-entrypoint path** — with no ``@app.entrypoint`` declared, the
+  CLI maps the same ``--flag value`` arguments directly onto the chosen
+  ``@app.job``'s own signature (:func:`parse_explicit_args`) and spawns it.
+  Only EXPLICITLY-passed flags are returned there: a defaulted-but-unpassed
+  parameter must stay out of the submitted ``args`` so an upgraded client
+  submits the byte-identical package (same ``canonical_args`` → same
+  ``package_id``) for the no-flags case it always produced ``args={}`` for.
+
+An argument parser is built from the target's signature: each parameter
+``foo_bar`` becomes ``--foo-bar`` (dash for underscore), coerced from the
+parameter's default type, then its annotation. A parameter without a default is
+required. This keeps authoring frictionless — ``def main(num_envs: int = 4096)``
+just works as ``--num-envs 4096`` — with no argparse boilerplate in the app file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import inspect
+import types
+import typing
+from typing import Any, Callable, Collection, Mapping, Optional, Sequence
+
+_STR_TO_TYPE: Mapping[str, type] = {"int": int, "float": float, "bool": bool, "str": str}
+
+_SKIP_KINDS = (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
+
+#: The only types a ``--flag value`` string can be conclusively coerced to.
+_SCALAR_TYPES: tuple[type, ...] = (int, float, bool, str)
+
+#: Sentinel default for :func:`parse_explicit_args`'s parser: a parameter whose
+#: parsed value is still this object was never passed on the command line, so it
+#: is omitted from the returned kwargs (the job body applies its own default at
+#: execution). ``None`` cannot play this role — it is a legitimate flag value.
+_UNSET: Any = object()
+
+
+def _param_type(param: inspect.Parameter) -> type:
+    """Best-effort scalar type for a parameter: default's type, then annotation.
+
+    A concrete (non-``None``) default is the most reliable signal — ``= 4096``
+    means ``int``. Otherwise fall back to the annotation (a real type, or a PEP
+    563 string like ``"int"``). Defaults to ``str`` when nothing is conclusive.
+    """
+    default = param.default
+    if default is not inspect.Parameter.empty and default is not None:
+        return type(default)
+    ann = param.annotation
+    if isinstance(ann, type):
+        return ann
+    if isinstance(ann, str):
+        return _STR_TO_TYPE.get(ann, str)
+    return str
+
+
+def _str_to_bool(raw: str) -> bool:
+    """Parse a CLI ``--flag value`` boolean (``true``/``1``/``yes`` → ``True``)."""
+    lowered = raw.strip().lower()
+    if lowered in ("true", "1", "yes", "y", "on"):
+        return True
+    if lowered in ("false", "0", "no", "n", "off"):
+        return False
+    raise argparse.ArgumentTypeError(f"expected a boolean (true/false), got {raw!r}")
+
+
+def flag_for_param(name: str) -> str:
+    """The ``--flag`` a signature parameter ``name`` maps to (dash for underscore)."""
+    return "--" + name.replace("_", "-")
+
+
+def mappable_params(fn: Callable[..., object]) -> list[tuple[str, inspect.Parameter]]:
+    """The parameters :func:`build_parser` maps to ``--flags``.
+
+    ``VAR_POSITIONAL`` (``*args``) and ``VAR_KEYWORD`` (``**kwargs``) are
+    skipped, exactly as ``build_parser`` skips them — signature guards must use
+    the same filter, or a harmless ``def train(**job)`` would be rejected for a
+    flag it never gets.
+    """
+    return [(name, param) for name, param in inspect.signature(fn).parameters.items() if param.kind not in _SKIP_KINDS]
+
+
+def _strip_optional_annotation(ann: Any) -> Any:
+    """Unwrap ``Optional[X]`` / ``X | None`` / ``Union[X, None]`` to ``X``.
+
+    Handles both representations of each spelling: under ``from __future__
+    import annotations`` (which every shipped scaffold enables) an annotation
+    is a STRING like ``"int | None"``, ``"Optional[int]"``, or
+    ``"Union[int, None]"``; without it, a typing object (whose ``Optional``
+    and ``Union`` spellings are the same object, handled by ``get_origin``).
+    All are common, deliberate ways to declare "this scalar, or unset" — the
+    wrapper must not hide the scalar, and no SPELLING may work in one
+    representation and fail in the other. Anything that is not exactly "one
+    type or None" is returned unchanged.
+    """
+    if isinstance(ann, str):
+        text = ann.strip()
+        if text.startswith("typing."):
+            text = text[len("typing.") :]
+        if text.startswith("Optional[") and text.endswith("]"):
+            return text[len("Optional[") : -1].strip()
+        if text.startswith("Union[") and text.endswith("]"):
+            # Naive comma split is safe here: a nested generic like
+            # "Union[dict[str, int], None]" yields 3 parts and falls through
+            # unchanged — its inner type is not a scalar anyway.
+            parts = [part.strip() for part in text[len("Union[") : -1].split(",")]
+            non_none = [part for part in parts if part != "None"]
+            if len(parts) == 2 and len(non_none) == 1:
+                return non_none[0]
+            return ann
+        if "|" in text:
+            parts = [part.strip() for part in text.split("|")]
+            non_none = [part for part in parts if part != "None"]
+            if len(parts) == 2 and len(non_none) == 1:
+                return non_none[0]
+        return ann
+    origin = typing.get_origin(ann)
+    if origin is typing.Union or origin is types.UnionType:
+        args = [arg for arg in typing.get_args(ann) if arg is not type(None)]
+        if len(args) == 1:
+            return args[0]
+    return ann
+
+
+def conclusive_param_type(param: inspect.Parameter) -> Optional[type]:
+    """The scalar type a ``--flag`` value is conclusively coerced to, or ``None``.
+
+    Unlike :func:`_param_type` — whose ``str`` FALLBACK is fine for an
+    entrypoint (the entrypoint body runs client-side and can fix things up) —
+    the no-entrypoint job path submits the coerced value straight into the
+    job's ``args``, so a guess is a silent wrong submission: ``tags: list = []``
+    would coerce ``--tags release`` through ``list("release")`` into
+    ``["r", "e", "l", ...]``, and a ``Path``/``set``/enum value would crash
+    ``json.dumps`` at manifest time. ``None`` here means "reject at submit".
+
+    Conclusive: a non-``None`` scalar default (its type), or an ``int`` /
+    ``float`` / ``bool`` / ``str`` annotation — real type, PEP 563 string, or
+    either wrapped in ``Optional[...]`` / ``| None``. An unannotated parameter
+    stays ``str`` (the documented text fallback, unchanged from the entrypoint
+    convention).
+    """
+    default = param.default
+    if default is not inspect.Parameter.empty and default is not None:
+        return type(default) if type(default) in _SCALAR_TYPES else None
+    ann = param.annotation
+    if ann is inspect.Parameter.empty:
+        return str
+    ann = _strip_optional_annotation(ann)
+    if isinstance(ann, type) and ann in _SCALAR_TYPES:
+        return ann
+    if isinstance(ann, str) and ann in _STR_TO_TYPE:
+        return _STR_TO_TYPE[ann]
+    return None
+
+
+def unmappable_params(fn: Callable[..., object]) -> list[tuple[str, str, str, bool]]:
+    """``(name, kind, why, has_default)`` for parameters the CLI cannot map.
+
+    ``kind`` is ``"positional-only"`` (the worker executes ``fn(**args)``, so a
+    keyword can never reach it) or ``"type"`` (no conclusive scalar coercion —
+    see :func:`conclusive_param_type`).
+
+    ``has_default`` is the caller's rejection policy input: without a default
+    the parameter is required-but-unmappable — the submit can never succeed, so
+    it is rejected always. WITH a default the defaults-only submit works today
+    (``fn(**{})`` never touches the parameter), so callers reject only when a
+    flag actually targets it — a blanket rejection would break submits that
+    work on shipped 0.14.x clients.
+    """
+    result: list[tuple[str, str, str, bool]] = []
+    for name, param in mappable_params(fn):
+        has_default = param.default is not inspect.Parameter.empty
+        if param.kind is inspect.Parameter.POSITIONAL_ONLY:
+            result.append((name, "positional-only", "declared positional-only (before a '/')", has_default))
+            continue
+        if conclusive_param_type(param) is not None:
+            continue
+        if param.default is not inspect.Parameter.empty and param.default is not None:
+            why = f"default {param.default!r} of non-scalar type {type(param.default).__name__}"
+        elif param.annotation is not inspect.Parameter.empty:
+            why = f"annotation {param.annotation!r} is not a scalar type"
+        else:  # pragma: no cover - unreachable: no annotation + no default resolves to str
+            why = "no usable type"
+        result.append((name, "type", why, has_default))
+    return result
+
+
+def build_parser(
+    fn: Callable[..., object],
+    *,
+    sentinel_defaults: bool = False,
+    prog: Optional[str] = None,
+    exclude: Collection[str] = (),
+) -> argparse.ArgumentParser:
+    """Build an ``argparse`` parser from a function's signature.
+
+    With ``sentinel_defaults=False`` (the entrypoint path — behavior unchanged),
+    a defaulted parameter's parser default is the signature's own default, so
+    ``parse_args`` yields EVERY parameter, and values coerce via
+    :func:`_param_type` (``str`` fallback included). With
+    ``sentinel_defaults=True`` (the no-entrypoint job path), defaulted
+    parameters default to the private ``_UNSET`` sentinel instead — so
+    :func:`parse_explicit_args` can tell an explicitly-passed flag from an
+    untouched default — and values coerce via :func:`conclusive_param_type`
+    (callers must have rejected inconclusive signatures first). ``prog`` names
+    the parser in ``-h`` output (e.g. ``"simulo run app.py"``); default is the
+    function's own name, as before.
+
+    ``exclude`` drops the named parameters from the parser entirely — the
+    no-entrypoint path passes its DEFERRED unmappable-but-defaulted parameters
+    here (see :func:`unmappable_params`), so a flag targeting one — even via
+    an argparse abbreviation the caller's exact-token scan cannot see — fails
+    at submit as an unrecognized argument rather than being mis-parsed.
+    """
+    sig = inspect.signature(fn)
+    doc = (inspect.getdoc(fn) or "").strip().splitlines()
+    parser = argparse.ArgumentParser(
+        prog=prog if prog is not None else getattr(fn, "__name__", "entrypoint"),
+        description=doc[0] if doc else None,
+    )
+    for name, param in sig.parameters.items():
+        if param.kind in _SKIP_KINDS or name in exclude:
+            continue
+        flag = flag_for_param(name)
+        required = param.default is inspect.Parameter.empty
+        if required:
+            default = None
+        elif sentinel_defaults:
+            default = _UNSET
+        else:
+            default = param.default
+        if sentinel_defaults:
+            resolved = conclusive_param_type(param)
+            typ = resolved if resolved is not None else _param_type(param)
+        else:
+            typ = _param_type(param)
+        if typ is bool:
+            parser.add_argument(
+                flag,
+                dest=name,
+                type=_str_to_bool,
+                required=required,
+                default=default,
+                metavar="BOOL",
+            )
+        else:
+            parser.add_argument(
+                flag,
+                dest=name,
+                type=typ,
+                required=required,
+                default=default,
+            )
+    return parser
+
+
+def parse_args(fn: Callable[..., object], argv: Sequence[str]) -> dict[str, Any]:
+    """Parse ``argv`` against ``fn``'s signature into a keyword-argument dict."""
+    parser = build_parser(fn)
+    namespace = parser.parse_args(list(argv))
+    sig = inspect.signature(fn)
+    kwargs: dict[str, Any] = {}
+    for name, param in sig.parameters.items():
+        if param.kind in _SKIP_KINDS:
+            continue
+        kwargs[name] = getattr(namespace, name)
+    return kwargs
+
+
+def parse_explicit_args(
+    fn: Callable[..., object],
+    argv: Sequence[str],
+    *,
+    prog: Optional[str] = None,
+    exclude: Collection[str] = (),
+) -> dict[str, Any]:
+    """Parse ``argv`` against ``fn``'s signature; return ONLY explicitly-passed kwargs.
+
+    The no-entrypoint submit path maps CLI flags onto a ``@app.job``'s own
+    signature with this: a parameter the user did not pass stays OUT of the
+    returned dict (the job body applies its own default on the worker), so the
+    no-flags case still submits ``args={}`` — exactly what pre-mapping clients
+    always submitted — and ``package_id`` is unchanged across the upgrade.
+    A parameter without a default is required, exactly as on the entrypoint
+    path. ``exclude`` names parameters left out of the parser and the result
+    (the deferred unmappable-but-defaulted ones — see :func:`build_parser`).
+    """
+    parser = build_parser(fn, sentinel_defaults=True, prog=prog, exclude=exclude)
+    namespace = parser.parse_args(list(argv))
+    sig = inspect.signature(fn)
+    kwargs: dict[str, Any] = {}
+    for name, param in sig.parameters.items():
+        if param.kind in _SKIP_KINDS or name in exclude:
+            continue
+        value = getattr(namespace, name)
+        if value is not _UNSET:
+            kwargs[name] = value
+    return kwargs
+
+
+def run_entrypoint(fn: Callable[..., object], argv: Sequence[str]) -> object:
+    """Parse ``argv`` for ``fn`` and invoke it (the single submit happens inside)."""
+    return fn(**parse_args(fn, argv))

{simulo-0.14.0 → simulo-0.16.0}/src/simulo/_client/_runner.py

@@ -10,9 +10,9 @@ Two submit modes now share this one handle type:
 * **Cloud submit** (credentials present, or ``SIMULO_API_URL``/``SIMULO_ENV``
   set): ``spawn`` has already uploaded the package and created a job on the
   control plane, so the handle carries the SERVER-assigned ``job_id`` plus the
-  base URL/token to observe it. ``.get()`` polls
-  :class:`~simulo._client.jobs_api.JobsApiClient` to a terminal status and
-  returns the result on success, or raises :class:`JobFailedError` (with a
+  base URL/token to observe it. ``.get()`` polls the jobs API client to a
+  terminal status and returns the result on success, or raises
+  :class:`JobFailedError` (with a
   ``simulo logs <id>`` hint) on failure/cancellation.
 
 The thin client keeps **no** import of and no ``find_spec`` dependency on