simhub 0.1.0__py3-none-any.whl

simhub/__init__.py

@@ -0,0 +1,239 @@
+"""simhub: define an environment, a policy and a task in Python; run them anywhere.
+
+Two things ship from this package and they are built from one source tree.
+
+**The library** -- what you import. Three small protocols (an environment, a
+policy, a task), one episode loop, one recorder, and a client that launches
+batches of the same thing on hosted GPUs::
+
+    import simhub
+
+    @simhub.environment("warehouse-pick")
+    def build(cell_seed: int = 7) -> simhub.Env:
+        from .mjcf import build_mjcf              # heavy imports inside
+        return PickEnv(build_mjcf(cell_seed))
+
+    @simhub.policy("scripted")
+    def scripted(env):
+        from .policies import ScriptedPick
+        return ScriptedPick(env)
+
+    simhub.run("warehouse-pick", "scripted", out="out/one")   # here, now
+
+    sh = simhub.connect()
+    batch = sh.project("./warehouse_pick").launch(
+        env="warehouse-pick",
+        policies=["scripted", "groot-ft"],
+        seeds=range(32),
+        task=simhub.Task(placed="eq:1", collisions="eq:0"),
+        record=simhub.Record(cameras=["hero", "wrist"], video="hero"),
+    )
+    batch.wait(); batch.report().table()
+
+**The server** -- the artifact store, job queue and workers under
+``simhub.api``, ``simhub.worker`` and ``simhub.adapters``. Never published;
+installed from source in this repository.
+
+Both live here so that ``protocol.py`` -- the thing most likely to drift --
+exists exactly once. The two distributions must never be installed into the
+same virtual environment; they provide the same import path.
+
+Everything below is imported lazily. Importing ``simhub`` in an API container
+must not cost numpy, and importing it in a notebook must not cost FastAPI.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+__version__ = "0.1.0"
+
+if TYPE_CHECKING:  # pragma: no cover - names for a type checker, bound lazily below
+    from simhub.batch import Batch as Batch
+    from simhub.checks import CheckReport as CheckReport
+    from simhub.checks import check as check
+    from simhub.client import Client as Client
+    from simhub.client import SimhubError as SimhubError
+    from simhub.client import connect as connect
+    from simhub.env import Env as Env
+    from simhub.env import Obs as Obs
+    from simhub.env import StepInfo as StepInfo
+    from simhub.env import environment as environment
+    from simhub.env import make_env as make_env
+    from simhub.named_assets import NamedAsset as NamedAsset
+    from simhub.named_assets import asset as asset
+    from simhub.policies import Policy as Policy
+    from simhub.policies import make_policy as make_policy
+    from simhub.policies import policy as policy
+    from simhub.project import Project as Project
+    from simhub.recording import Recorder as Recorder
+    from simhub.recording import VideoWriter as VideoWriter
+    from simhub.report import Report as Report
+    from simhub.rollout import Record as Record
+    from simhub.rollout import RolloutResult as RolloutResult
+    from simhub.scorer import BestOfK as BestOfK
+    from simhub.scorer import MeanMetric as MeanMetric
+    from simhub.scorer import StageProgress as StageProgress
+    from simhub.scorer import SuccessRate as SuccessRate
+    from simhub.session import Session as Session
+    from simhub.spec import ArraySpec as ArraySpec
+    from simhub.spec import CameraSpec as CameraSpec
+    from simhub.spec import EnvSpec as EnvSpec
+    from simhub.spec import MetricSpec as MetricSpec
+    from simhub.spec import PolicySpec as PolicySpec
+    from simhub.suite import Episode as Episode
+    from simhub.suite import Eval as Eval
+    from simhub.suite import Suite as Suite
+    from simhub.task import Conditions as Conditions
+    from simhub.task import Score as Score
+    from simhub.task import Stages as Stages
+    from simhub.task import Task as Task
+
+#: name -> the module it lives in. A table rather than a chain of try/imports
+#: so that ``dir(simhub)`` is honest and a typo names the attribute rather
+#: than failing somewhere inside an import.
+#:
+#: **No name here may also be a submodule of this package**, and that is a hard
+#: rule rather than a style: importing ``simhub.policies`` makes the import
+#: system set ``simhub.policies`` on this module, which would shadow a lazy
+#: export of the same name -- so ``simhub.policy`` would be the decorator until
+#: something imported the module and the module afterwards. That is why the
+#: decorators live in ``policies.py`` rather than ``policy.py``, the scene check
+#: in ``checks.py``, and the object resolver in ``objects.py``.
+#:
+#: ``rollout`` is the one that kept its module name and therefore is *not*
+#: exported: ``simhub.rollout`` is the module, and :func:`simhub.run` is the
+#: one-episode call.
+_EXPORTS = {
+    "asset": "simhub.named_assets",
+    "NamedAsset": "simhub.named_assets",
+    "ArraySpec": "simhub.spec",
+    "CameraSpec": "simhub.spec",
+    "EnvSpec": "simhub.spec",
+    "MetricSpec": "simhub.spec",
+    "PolicySpec": "simhub.spec",
+    "Env": "simhub.env",
+    "Obs": "simhub.env",
+    "StepInfo": "simhub.env",
+    "environment": "simhub.env",
+    "make_env": "simhub.env",
+    "Policy": "simhub.policies",
+    "policy": "simhub.policies",
+    "make_policy": "simhub.policies",
+    "Task": "simhub.task",
+    "Conditions": "simhub.task",
+    "Stages": "simhub.task",
+    "Score": "simhub.task",
+    "Verdict": "simhub.task",
+    "Record": "simhub.rollout",
+    "RolloutResult": "simhub.rollout",
+    "Recorder": "simhub.recording",
+    "VideoWriter": "simhub.recording",
+    "annotate_frame": "simhub.recording",
+    "read_trajectory": "simhub.recording",
+    "Emitter": "simhub.emit",
+    "Environment": "simhub.base",
+    "PolicyBase": "simhub.base",
+    "MujocoEnvironment": "simhub.base",
+    "ScriptedPolicy": "simhub.base",
+    "manifest": "simhub.single",
+    "loaded": "simhub.registry",
+    "Project": "simhub.project",
+    "Client": "simhub.client",
+    "SimhubError": "simhub.client",
+    "connect": "simhub.client",
+    "Session": "simhub.session",
+    "Batch": "simhub.batch",
+    "Suite": "simhub.suite",
+    "Episode": "simhub.suite",
+    "Eval": "simhub.suite",
+    "Report": "simhub.report",
+    "SuccessRate": "simhub.scorer",
+    "MeanMetric": "simhub.scorer",
+    "StageProgress": "simhub.scorer",
+    "BestOfK": "simhub.scorer",
+    "AirTransport": "simhub.particulate",
+    "CoatingParameters": "simhub.particulate",
+    "ExtractionContact": "simhub.particulate",
+    "ParticleClass": "simhub.particulate",
+    "WetCoating": "simhub.particulate",
+    "CleaningTool": "simhub.cleaning",
+    "SurfaceContamination": "simhub.cleaning",
+    "render_cycles": "simhub.replay",
+    "check": "simhub.checks",
+    "CheckReport": "simhub.checks",
+    "assets": "simhub.objects",
+    "weights": "simhub.objects",
+    "check_access": "simhub.objects",
+}
+
+__all__ = [*sorted(_EXPORTS), "run", "__version__"]
+
+
+def __getattr__(name: str) -> Any:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module 'simhub' has no attribute {name!r}")
+    import importlib
+
+    return getattr(importlib.import_module(module), name)
+
+
+def __dir__():
+    return sorted(__all__)
+
+
+def run(
+    env: str,
+    policy: str = "simhub:hold",
+    *,
+    seed: int = 0,
+    out: Any = None,
+    task: Any = None,
+    record: Any = None,
+    max_steps: Any = None,
+    env_kwargs: Any = None,
+    policy_kwargs: Any = None,
+    prompt: Any = None,
+):
+    """One episode, in this interpreter, writing the hosted output layout.
+
+    A development affordance, and saying so plainly matters: anybody can step
+    MuJoCo in a Python loop for free, so a library whose pitch is "we wrap your
+    loop" has no reason to exist. What this is for is the debug cycle -- a
+    ``NameError`` should cost a second, not a round trip -- and for one
+    property that is worth more than it looks.
+
+    **The laptop predicts the cluster.** This is the same
+    :func:`~simhub.rollout.rollout` the container calls, writing the same
+    files, so a local result and a hosted result are the same artifacts read by
+    the same report code. A test asserts they stay identical for a fixed seed;
+    the moment they diverge, iterating locally stops being worth anything.
+
+    What it is *not* is the product. A 3-billion-parameter policy on a real
+    GPU, sixty episodes at once, photorealistic rendering, a fine-tune on what
+    you recorded, and a number with a content digest behind it are all the
+    hosted path, and none of them fits here.
+    """
+    from pathlib import Path
+
+    from simhub.env import make_env
+    from simhub.policies import make_policy
+    from simhub.rollout import Record, rollout
+
+    instance = make_env(env, **(env_kwargs or {}))
+    if prompt:
+        import dataclasses
+
+        instance.spec = dataclasses.replace(instance.spec, prompt=prompt)
+    controller = make_policy(policy, instance, **(policy_kwargs or {}))
+    return rollout(
+        instance,
+        controller,
+        seed=seed,
+        out=Path(out) if out is not None else None,
+        task=task,
+        record=record or Record(),
+        max_steps=max_steps,
+        policy_name=policy,
+    )

simhub/asset_cli.py

@@ -0,0 +1,58 @@
+"""Authenticated CLI for named environment assets, shared by both installs."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Optional, Sequence
+
+from simhub.client import Client, SimhubError
+from simhub.named_assets import AssetError, fetch
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = argparse.ArgumentParser(prog="simhub asset", description=__doc__)
+    parser.add_argument("--url", help="API URL (default: SIMHUB_API_URL)")
+    commands = parser.add_subparsers(dest="command", required=True)
+    upload = commands.add_parser("upload", help="Upload a named URDF and its meshes, or a mesh")
+    upload.add_argument("source")
+    upload.add_argument("--env", required=True, help="hosted environment name; created if absent")
+    upload.add_argument("--name", required=True, help="asset name within the environment")
+    upload.add_argument("--root", help="allowed dependency root (default: source directory)")
+    upload.add_argument("--package", action="append", default=[], metavar="NAME=PATH",
+                        help="resolve a ROS package:// prefix; repeat for multiple packages")
+    upload.add_argument("--message", default="")
+    listing = commands.add_parser("list", help="List the latest revision of each named asset")
+    listing.add_argument("--env", required=True)
+    listing.add_argument("--version", default="latest")
+    get = commands.add_parser("get", help="Download and verify an asset and its dependencies")
+    get.add_argument("reference", help="environment/name[@version]")
+    get.add_argument("--out", required=True)
+    args = parser.parse_args(argv)
+    try:
+        with Client(url=args.url) as client:
+            if args.command == "upload":
+                packages = {}
+                for item in args.package:
+                    key, separator, path = item.partition("=")
+                    if not separator or not key or not path or key in packages:
+                        raise AssetError("each --package must be a unique NAME=PATH")
+                    packages[key] = path
+                result = client.upload_asset(
+                    args.source, environment=args.env, name=args.name, root=args.root,
+                    packages=packages, message=args.message,
+                )
+            elif args.command == "list":
+                result = client.named_assets(args.env, args.version)
+            else:
+                resolved = fetch(client, args.reference, into=args.out)
+                result = {"path": str(resolved.path), "digest": resolved.digest}
+        print(json.dumps(result, indent=2))
+        return 0
+    except (AssetError, SimhubError, OSError, ValueError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())