robovast-client 2.1.0__tar.gz

robovast_client-2.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.1
+Name: robovast-client
+Version: 2.1.0
+Summary: Talk to a RoboVAST service: upload projects, launch campaigns, wait for them, fetch results.
+License: Apache-2.0
+Author: Frederik Pasch
+Author-email: fred-labs@mailbox.org
+Requires-Python: >=3.12,<3.14
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: click (>=8.1,<9.0)
+Requires-Dist: pydantic (>=2.12,<3.0)
+Requires-Dist: requests (>=2.31,<3.0)
+Description-Content-Type: text/markdown
+
+# robovast-client
+
+Talk to a running [RoboVAST](https://github.com/cps-test-lab/robovast) service — upload a
+project, launch a campaign, wait for it, fetch the results — without installing RoboVAST.
+
+```bash
+pip install robovast-client
+vast login https://robovast.example.org
+```
+
+## What it is for
+
+RoboVAST runs simulation campaigns: a scenario, a sweep of configurations, repeated runs,
+recorded provenance. That work happens **on the service**, on a Docker host or a
+Kubernetes cluster. If you are the person *driving* it rather than the person *hosting*
+it, this is all you need.
+
+The full `robovast` distribution pulls in a simulator stack, an array library and a
+dataframe library — 88 packages, around 290 MB — because it can execute campaigns itself.
+This one is three dependencies (`pydantic`, `click`, `requests`) and about 30 MB, because
+it only talks to something that can.
+
+> **Not yet on PyPI.** Install it from a checkout with `pip install src/robovast_client`.
+
+## What you get
+
+`vast` grows commands as capability is installed; with only the client, it is:
+
+| Command | Does |
+|---|---|
+| `vast login <url>` / `vast logout` | store or forget the service credentials |
+| **`vast workspace run`** | **launch a campaign** — pushes the project and starts it; `--wait-and-download` blocks and fetches the results |
+| `vast campaign stop/stop-job/log` | stop a campaign, kill one wedged job, read its infrastructure log |
+| `vast workspace init/update/list/delete` | push a project directory to the service |
+| `vast files get/put` | move a single file by address |
+| `vast image build/wait/status/log` | have the service build a project's derived images |
+| `vast campaign wait <campaign-id>` | block until a campaign is genuinely over |
+| `vast doctor` | check the login, the service and your PATH |
+
+`vast cluster` and `vast service` are partly here on purpose: a subcommand exists exactly
+when something that can perform it is installed. The verbs above only drive a service, so
+they are complete here. `vast cluster setup/cleanup/jobs-cleanup/monitor` and `vast service
+upgrade/token` need a kubeconfig and come with `robovast-cluster`. So `vast cluster --help`
+lists `store-cleanup` and not `setup` — nothing is stubbed and nothing fails on use.
+
+Both groups spanning two distributions is the design: a group is named after the **object**
+it acts on, not after what you installed.
+
+There is no ambient project. Every command names its own input, and a campaign runs a
+*workspace's* project — `vast workspace run <workspace> [vast]`.
+
+An LLM agent reaches the same service through its MCP endpoint, which needs nothing
+installed at all. `vast login` prints the `claude mcp add` line that registers it. The
+control verbs are deliberately on both sides; each side additionally owns what only it can
+do — bulk bytes and long waits here, results queries and diff-based authoring there.
+
+## Waiting for a campaign
+
+A campaign can run for days, so nothing blocks a request on one. `vast campaign wait` polls
+the service and exits when the campaign is genuinely finished — past postprocessing, not
+merely past its last run:
+
+```bash
+vast campaign wait basic-nav-2026-08-16-101500
+```
+
+Its **exit code is the answer**: `0` finished, `1` failed, `2` you interrupted the wait,
+and a distinct code for "no such campaign" so a typo cannot be mistaken for a failed run.
+Run it as the whole command — chaining anything after it makes the shell report the
+wrapper's status instead, which turns a failed campaign into a reported success.
+
+## What it is not
+
+No simulator, no Kubernetes client, no Docker, no MuJoCo, no ROS. It cannot execute a
+campaign or build an image itself, only ask a service to. If you need to *run* campaigns on your own machine,
+install `robovast`; to host them on a cluster, add `robovast-cluster`.
+
+## Licence
+
+Apache-2.0.
+

robovast_client-2.1.0/README.md

@@ -0,0 +1,80 @@
+# robovast-client
+
+Talk to a running [RoboVAST](https://github.com/cps-test-lab/robovast) service — upload a
+project, launch a campaign, wait for it, fetch the results — without installing RoboVAST.
+
+```bash
+pip install robovast-client
+vast login https://robovast.example.org
+```
+
+## What it is for
+
+RoboVAST runs simulation campaigns: a scenario, a sweep of configurations, repeated runs,
+recorded provenance. That work happens **on the service**, on a Docker host or a
+Kubernetes cluster. If you are the person *driving* it rather than the person *hosting*
+it, this is all you need.
+
+The full `robovast` distribution pulls in a simulator stack, an array library and a
+dataframe library — 88 packages, around 290 MB — because it can execute campaigns itself.
+This one is three dependencies (`pydantic`, `click`, `requests`) and about 30 MB, because
+it only talks to something that can.
+
+> **Not yet on PyPI.** Install it from a checkout with `pip install src/robovast_client`.
+
+## What you get
+
+`vast` grows commands as capability is installed; with only the client, it is:
+
+| Command | Does |
+|---|---|
+| `vast login <url>` / `vast logout` | store or forget the service credentials |
+| **`vast workspace run`** | **launch a campaign** — pushes the project and starts it; `--wait-and-download` blocks and fetches the results |
+| `vast campaign stop/stop-job/log` | stop a campaign, kill one wedged job, read its infrastructure log |
+| `vast workspace init/update/list/delete` | push a project directory to the service |
+| `vast files get/put` | move a single file by address |
+| `vast image build/wait/status/log` | have the service build a project's derived images |
+| `vast campaign wait <campaign-id>` | block until a campaign is genuinely over |
+| `vast doctor` | check the login, the service and your PATH |
+
+`vast cluster` and `vast service` are partly here on purpose: a subcommand exists exactly
+when something that can perform it is installed. The verbs above only drive a service, so
+they are complete here. `vast cluster setup/cleanup/jobs-cleanup/monitor` and `vast service
+upgrade/token` need a kubeconfig and come with `robovast-cluster`. So `vast cluster --help`
+lists `store-cleanup` and not `setup` — nothing is stubbed and nothing fails on use.
+
+Both groups spanning two distributions is the design: a group is named after the **object**
+it acts on, not after what you installed.
+
+There is no ambient project. Every command names its own input, and a campaign runs a
+*workspace's* project — `vast workspace run <workspace> [vast]`.
+
+An LLM agent reaches the same service through its MCP endpoint, which needs nothing
+installed at all. `vast login` prints the `claude mcp add` line that registers it. The
+control verbs are deliberately on both sides; each side additionally owns what only it can
+do — bulk bytes and long waits here, results queries and diff-based authoring there.
+
+## Waiting for a campaign
+
+A campaign can run for days, so nothing blocks a request on one. `vast campaign wait` polls
+the service and exits when the campaign is genuinely finished — past postprocessing, not
+merely past its last run:
+
+```bash
+vast campaign wait basic-nav-2026-08-16-101500
+```
+
+Its **exit code is the answer**: `0` finished, `1` failed, `2` you interrupted the wait,
+and a distinct code for "no such campaign" so a typo cannot be mistaken for a failed run.
+Run it as the whole command — chaining anything after it makes the shell report the
+wrapper's status instead, which turns a failed campaign into a reported success.
+
+## What it is not
+
+No simulator, no Kubernetes client, no Docker, no MuJoCo, no ROS. It cannot execute a
+campaign or build an image itself, only ask a service to. If you need to *run* campaigns on your own machine,
+install `robovast`; to host them on a cluster, add `robovast-cluster`.
+
+## Licence
+
+Apache-2.0.

robovast_client-2.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[tool.poetry]
+name = "robovast-client"
+version = "2.1.0"
+description = "Talk to a RoboVAST service: upload projects, launch campaigns, wait for them, fetch results."
+authors = ["Frederik Pasch <fred-labs@mailbox.org>"]
+license = "Apache-2.0"
+readme = "README.md"
+# Ships into the `robovast` namespace rather than a name of its own, so no import path
+# changes: `robovast/`, `robovast/service/` and `robovast/execution/` carry no
+# `__init__.py` in any distribution, which makes them PEP 420 namespace packages and lets
+# the trees merge. `robovast/client/` is a regular package because only this
+# distribution ever provides it.
+packages = [{include = "robovast"}]
+
+[tool.poetry.dependencies]
+python = ">=3.12,<3.14"
+# The whole point of this distribution. `pip install robovast` pulls 88 distributions and
+# ~290 MB -- pandas and numpy alone are 152 MB of it -- to run four HTTP verbs. These
+# three are ~30 MB, and nothing here may add a fourth without a reason that survives
+# "could the service do this instead?".
+#
+# Deliberately NOT depending on `robovast`. The dependency runs the other way: robovast is
+# built on this, and an edge back would be a cycle.
+pydantic = "^2.12"
+click = "^8.1"
+requests = "^2.31"
+
+# The `vast` command itself. It lives here because every audience has one: the core, the
+# execution lanes and the operator commands all attach their verbs to this group through
+# `robovast.cli_plugins`.
+[tool.poetry.scripts]
+vast = "robovast.client.cli:main"
+
+# The groups are named after what they act on, and each ships wherever its verbs can run.
+# `campaign` and `container` only ever drive a service, so they are wholly the client's.
+# `service` and `cluster` span two distributions on purpose: the group is defined by its
+# object, not by what you installed, so `service restart` (a URL and a token) is here while
+# `service upgrade` (an API server) attaches from robovast-cluster.
+#
+# Verbs defined in the same module as their group stay ordinary `@group.command()`s rather
+# than entry points: metadata is for crossing distributions, and a distribution's own verbs
+# must not vanish on a pyproject edit that was not followed by a reinstall.
+[tool.poetry.plugins."robovast.cli_plugins"]
+campaign = "robovast.client.campaign_cli:campaign"
+service = "robovast.client.service_cli:service"
+cluster = "robovast.client.cluster_cli:cluster"
+container = "robovast.client.container_cli:container"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

robovast_client-2.1.0/robovast/client/__init__.py

@@ -0,0 +1,17 @@
+# Copyright (C) 2026 Frederik Pasch
+# SPDX-License-Identifier: Apache-2.0
+
+"""What a client needs to talk to a robovast-service, and nothing else.
+
+These modules were under :mod:`robovast.common`, which cannot host them once the client
+ships as its own distribution: ``common/__init__.py`` carries the lazy re-export map, so
+the package is a regular one and its contents cannot be split across two distributions.
+``robovast.client`` is a package of its own for exactly that reason.
+
+The rule for what belongs here is the install it has to survive in: ``pydantic``,
+``click`` and ``requests``, with no simulator, no Kubernetes client and no array library.
+Anything reaching further belongs in the core.
+
+Deliberately kept empty of re-exports. The parent it came from cost 528 modules to touch
+because its ``__init__`` imported eagerly; repeating that here would undo the point.
+"""

robovast_client-2.1.0/robovast/client/app_version.py

@@ -0,0 +1,65 @@
+# Copyright (C) 2026 Frederik Pasch
+# SPDX-License-Identifier: Apache-2.0
+
+"""The version of the code *this process is running*.
+
+Lives here rather than beside the in-process service because both sides of the version
+handshake need it: the HTTP client reports its own version, the service reports the one it
+loaded. Keeping it in ``local_transport`` meant a client could not ask "what am I running?"
+without importing the whole in-process server.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+
+def running_version() -> str:
+    """The running code's version: git revision if available, else package metadata.
+
+    The preference is the point. A service is long-lived and loads its code once, so a
+    client needs to tell "the fix I just made is loaded" from "this process predates it".
+    The packaged version alone cannot — it stays ``2.0.0`` across every edit.
+
+    Never raises. The git-revision path needs ``robovast.common.execution``, which a
+    client-only install does not have, so the import is inside the ``try`` with everything
+    else: a version string is diagnostic, and failing to produce one must not break the
+    handshake it is part of.
+
+    The distributions are tried in order of how much they say about the running code:
+    ``robovast`` when it is installed, then ``robovast-client``, which is installed in
+    *every* case and so is the last answer that is still a fact. ``0.0.0+unknown`` remains
+    only for a source tree with no metadata at all — reported by a perfectly good
+    client-only install, it would read as a broken install rather than a small one.
+    """
+    try:
+        from robovast.common.execution import \
+            get_app_version  # pylint: disable=import-outside-toplevel
+        return get_app_version()
+    except Exception:  # noqa: BLE001 - version reporting must never break the handshake
+        for dist in ("robovast", "robovast-client"):
+            try:
+                return _pkg_version(dist)
+            except PackageNotFoundError:
+                continue
+        return "0.0.0+unknown"  # a source tree with no metadata
+
+
+def running_revision() -> str:
+    """The running code's git revision, or ``""`` when it cannot be determined.
+
+    The strict half of :func:`running_version`, and the reason both exist: a *version* is
+    allowed to fall back to package metadata, because "which robovast am I?" always has an
+    answer worth printing. A *revision* is not, because the only question it is asked is
+    "is this the same code as over there?" -- and a semver that stays ``2.0.0`` across every
+    edit answers that with a confident wrong yes.
+
+    ``""`` therefore means "no comparison is possible here", which a caller can act on by
+    saying so. Two cases produce it and neither is an error: a client-only install (no
+    ``robovast.common.execution`` to ask) and a non-git install of the full package.
+    """
+    try:
+        from robovast.common.execution import \
+            code_revision  # pylint: disable=import-outside-toplevel
+        return code_revision()
+    except Exception:  # noqa: BLE001 - a diagnostic must not raise; "" is the honest answer
+        return ""