envloop-cli-experiment 1.23.0__py3-none-any.whl

envloop_experiment/client.py

@@ -0,0 +1,471 @@
+import math
+import time
+import tomllib
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any, BinaryIO, Protocol, cast
+from uuid import uuid4
+
+from envloop.downloads import ArtifactError, artifact_path, download_file
+from envloop.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+class TaskService(Protocol):
+    def list_trials(self, **kwargs: Any) -> dict[str, Any]: ...
+    def get_task_run(self, trial_id: str) -> dict[str, Any]: ...
+    def get_trial_detail(self, trial_id: str) -> dict[str, Any]: ...
+    def get_trial_training(self, trial_id: str) -> dict[str, Any]: ...
+    def list_trial_metrics(self, trial_id: str, **kwargs: Any) -> dict[str, Any]: ...
+    def list_trial_checkpoints(self, trial_id: str, **kwargs: Any) -> dict[str, Any]: ...
+    def get_task_result(self, trial_id: str) -> dict[str, Any]: ...
+    def get_task_snapshot(self, trial_id: str) -> dict[str, Any]: ...
+    def stop_task(self, trial_id: str) -> dict[str, Any]: ...
+    def list_trial_artifacts(self, trial_id: str, **kwargs: Any) -> dict[str, Any]: ...
+    def open_trial_artifact(self, trial_id: str, artifact_id: str) -> BinaryIO: ...
+
+
+def load_task(source: str | Path | Mapping[str, Any]) -> dict[str, Any]:
+    """Read a two-file UTF-8 runner, with legacy task.toml compatibility."""
+    if isinstance(source, Mapping):
+        return dict(source)
+    directory = Path(source)
+    runner_config, legacy_config = directory / "runner.toml", directory / "task.toml"
+    if (runner_config.exists() or runner_config.is_symlink()) and (
+        legacy_config.exists() or legacy_config.is_symlink()
+    ):
+        raise ValueError("runner.toml and task.toml cannot coexist")
+    config_path = (
+        runner_config if runner_config.exists() or runner_config.is_symlink()
+        else legacy_config
+    )
+    if config_path.is_symlink() or not config_path.is_file():
+        raise ValueError(f"missing regular runner.toml or task.toml: {directory}")
+    config = config_path.read_text(encoding="utf-8")
+    execution = tomllib.loads(config).get("execution", {})
+    if not isinstance(execution, dict):
+        raise ValueError("[execution] must be a table")
+    entry = execution.get("entrypoint")
+    if entry not in {"main.py", "main.sh"}:
+        raise ValueError("entrypoint must be main.py or main.sh")
+    path = directory / entry
+    if path.is_symlink() or not path.is_file():
+        raise ValueError(f"missing regular entrypoint: {entry}")
+    names = {p.name for p in directory.iterdir() if p.is_file() or p.is_symlink()}
+    if names != {config_path.name, entry}:
+        raise ValueError(
+            "runner directory must contain exactly its config and entrypoint"
+        )
+    return {config_path.name: config, entry: path.read_text(encoding="utf-8")}
+
+
+def validate_command(command: str) -> str:
+    """Preserve shell text while rejecting malformed or oversized overrides."""
+    if not isinstance(command, str) or not command.strip() or "\x00" in command:
+        raise ValueError("command must be non-empty UTF-8 shell text without NUL")
+    try:
+        encoded = command.encode("utf-8")
+    except UnicodeEncodeError as exc:
+        raise ValueError("command must be valid UTF-8 shell text") from exc
+    if len(encoded) > 65536:
+        raise ValueError("command must not exceed 65536 UTF-8 bytes")
+    return command
+
+
+def dataset_selector(dataset: str | Mapping[str, Any], **selection: Any) -> dict[str, Any]:
+    """Package a catalog selection; the platform resolves and freezes it."""
+    if isinstance(dataset, str):
+        name, version = dataset, None
+        if "@" in dataset:
+            name, version = dataset.rsplit("@", 1)
+        if (not name.strip() or name != name.strip()
+                or (version is not None and (not version.strip() or version != version.strip()))):
+            raise ValueError("dataset must be a non-empty name or name@version")
+        selector = {"name": name}
+        if version is not None:
+            selector["version"] = version
+    elif isinstance(dataset, Mapping):
+        selector = dict(dataset)
+    else:
+        raise ValueError("dataset must be a name or selector")
+    for key, value in selection.items():
+        if value is not None:
+            if key in selector and selector[key] != value:
+                raise ValueError(f"conflicting dataset selection: {key}")
+            selector[key] = value
+    return selector
+
+
+class Tasks:
+    def __init__(self, server: TaskService) -> None:
+        self._server = server
+        from .http import configure_transport
+        configure_transport(self._server)
+
+    def list(self, **kwargs: Any) -> dict[str, Any]:
+        """List Agent and Train Trials; filter by ``type`` and/or ``job_id``."""
+        return self._server.list_trials(**kwargs)
+
+    def snapshot(self, trial_id: str) -> dict[str, Any]:
+        return self._server.get_task_snapshot(trial_id)
+
+    def status(self, trial_id: str) -> dict[str, Any]:
+        return self._server.get_task_run(trial_id)
+
+    def detail(self, trial_id: str) -> dict[str, Any]:
+        """Read common identity and the server's type-specific detail."""
+        return self._server.get_trial_detail(trial_id)
+
+    def training(self, trial_id: str) -> dict[str, Any]:
+        """Read the training extension of a Train Trial."""
+        return self._server.get_trial_training(trial_id)
+
+    def metrics(self, trial_id: str, **kwargs: Any) -> dict[str, Any]:
+        """Read one page of metrics belonging to this Trial."""
+        return self._server.list_trial_metrics(trial_id, **kwargs)
+
+    def checkpoints(self, trial_id: str, **kwargs: Any) -> dict[str, Any]:
+        """Read one page of checkpoints belonging to this Trial."""
+        return self._server.list_trial_checkpoints(trial_id, **kwargs)
+
+    def result(self, trial_id: str) -> dict[str, Any]:
+        return self._server.get_task_result(trial_id)
+
+    def stop(self, trial_id: str) -> dict[str, Any]:
+        return self._server.stop_task(trial_id)
+
+    def artifacts(self, trial_id: str, **kwargs: Any) -> dict[str, Any]:
+        """One page of the Trial's artifact listing (``cursor`` / ``limit``)."""
+        return self._server.list_trial_artifacts(trial_id, **kwargs)
+
+
+
+
+    def _all_artifacts(self, trial_id: str):
+        items, cursor = cast(list[dict[str, Any]], []), None
+        while True:
+            page = self.artifacts(trial_id, cursor=cursor, limit=100)
+            items.extend(page["items"])
+            cursor = page.get("next_cursor")
+            if cursor is None:
+                return items
+
+
+    def download_artifact(self, trial_id: str, artifact: str | Mapping[str, Any], dest: str | Path) -> dict[str, Any]:
+        """Download a listed Trial artifact, verifying its size, digest and path."""
+        item = artifact if isinstance(artifact, Mapping) else next(
+            (entry for entry in self._all_artifacts(trial_id) if entry.get('artifact_id') == artifact), None)
+        if item is None:
+            raise ArtifactError('ARTIFACT_NOT_FOUND')
+        return download_file(lambda: self._server.open_trial_artifact(trial_id, item['artifact_id']), item, dest)
+
+    def download_artifacts(self, trial_id: str, dest: str | Path) -> dict[str, Any]:
+        """Download every uploaded artifact of a Trial below ``dest``.
+
+        All names are checked before any file is written. Artifacts that are not
+        ``uploaded`` (pending, failed or deleted) are reported in ``skipped``.
+        """
+        root = Path(dest)
+        items = self._all_artifacts(trial_id)
+        for item in items:
+            artifact_path(root, item.get("name"))
+        downloaded, skipped = cast(list[dict[str, Any]], []), cast(list[dict[str, Any]], [])
+        for item in items:
+            if item.get("upload_state") == "uploaded" and item.get("artifact_id"):
+                downloaded.append(self.download_artifact(trial_id, item, root))
+            else:
+                skipped.append({"artifact_id": item.get("artifact_id"), "name": item["name"],
+                                "upload_state": item.get("upload_state")})
+        return {"trial_id": trial_id, "directory": str(root), "downloaded": downloaded, "skipped": skipped}
+
+
+    def wait(
+        self, trial_id: str, *, timeout: float = 30, poll_interval: float = 0.05
+    ) -> dict[str, Any]:
+        if not math.isfinite(timeout) or timeout < 0:
+            raise ValueError("timeout must be finite and non-negative")
+        if not math.isfinite(poll_interval) or poll_interval <= 0:
+            raise ValueError("poll_interval must be finite and positive")
+        logger.info("task.wait_started trial_id=%s timeout_sec=%s", trial_id, timeout)
+        deadline = time.monotonic() + timeout
+        previous_status = None
+        while True:
+            trial = self.status(trial_id)
+            if trial["status"] != previous_status:
+                logger.debug(
+                    "task.status_changed trial_id=%s status=%s",
+                    trial_id,
+                    trial["status"],
+                )
+                previous_status = trial["status"]
+            if trial["status"] in {"succeeded", "failed", "cancelled"}:
+                logger.info(
+                    "task.wait_finished trial_id=%s status=%s",
+                    trial_id,
+                    trial["status"],
+                )
+                return trial
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                logger.warning(
+                    "task.wait_timed_out trial_id=%s timeout_sec=%s", trial_id, timeout
+                )
+                raise TimeoutError(f"trial {trial_id} did not finish within {timeout}s")
+            time.sleep(min(poll_interval, remaining))
+
+
+def runner_selector(value: str):
+    """Require an explicit, portable revision; resolution belongs to the API."""
+    if not isinstance(value, str):
+        raise ValueError("runner requires name@revision")
+    name, separator, revision = value.partition("@")
+    if (not separator or not name or "/" not in name or not revision
+            or value != value.strip() or any(char.isspace() for char in value)
+            or revision in {"HEAD", "FETCH_HEAD", "ORIG_HEAD", "MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD"}
+            or revision.startswith("-") or ".." in revision or revision == "@" or "@{" in revision
+            or any(char in revision for char in "~^:{}?*[\\")):
+        raise ValueError("runner requires name@revision with an explicit commit, tag or branch")
+    return value
+
+
+def job_budget(max_cost_usd: float):
+    """The public ``budget`` of an Agent/Sandbox Job: a USD cap from 0.000001 (one micro-USD) to 100000."""
+    if (type(max_cost_usd) not in (int, float) or not math.isfinite(max_cost_usd)
+            or not 0.000001 <= max_cost_usd <= 100_000):
+        raise ValueError("max_cost_usd must be a USD amount from 0.000001 to 100000")
+    return {"max_cost_usd": max_cost_usd}
+
+
+class Jobs:
+    def __init__(self, server: Any):
+        self._server = server
+        from .http import configure_transport
+        configure_transport(self._server)
+
+    def submit(self, dataset: str | Mapping[str, Any] | None = None, *, source: Any = None,
+               task_ref: Mapping[str, Any] | None = None, task_id: str | None = None,
+               request_id: str | None = None, attempts: int = 1, namespace: str | None = None,
+               config: str | None = None, split: str | None = None, revision: str | None = None,
+               runner: str | None = None,
+               profile_id: str | None = None, job_id: str | None = None, tag: str | None = None,
+               queue_id: str = "default",
+               priority: int = 0, command: str | None = None, source_train_job_id: str | None = None,
+               source_train_trial_id: str | None = None,
+               type: str = 'agent', image: str | None = None, params: Mapping[str, Any] | None = None,
+               max_cost_usd: float | None = None, **options: Any):
+        """Submit an Agent Job or a Sandbox Job using a registered Runner.
+
+        A source Trial requires its Train Job ID. The API verifies source type,
+        ownership and project scope, and resolves any legacy Train Job alias.
+        ``max_cost_usd`` caps the Job's model plus sandbox spend; the Job stops with
+        ``error=BUDGET_EXCEEDED`` when it is reached and its result reports ``cost``.
+        """
+        if type not in {'agent', 'sandbox'}:
+            raise ValueError('Jobs.submit type must be agent or sandbox; use training_jobs.submit for train')
+        if image is not None and type != 'sandbox':
+            raise ValueError('image requires a Sandbox Job')
+        for field, value in (("source_train_job_id", source_train_job_id),
+                             ("source_train_trial_id", source_train_trial_id)):
+            if value is not None and (not isinstance(value, str) or not value.strip()):
+                raise ValueError(f"{field} must be a non-empty string")
+        if source_train_trial_id is not None and source_train_job_id is None:
+            raise ValueError("source_train_trial_id requires source_train_job_id")
+        if request_id is not None and (not isinstance(request_id, str) or not request_id.strip() or len(request_id) > 128):
+            raise ValueError("request_id must be a non-empty string of at most 128 characters")
+        if params is not None:
+            from envloop_experiment.runtime_params import validate_params
+            options['params'] = validate_params(params)
+        if max_cost_usd is not None:
+            options['budget'] = job_budget(max_cost_usd)
+        if type == 'sandbox':
+            from envloop.http import validate_public_execution
+            from envloop_experiment.sandbox import (
+                sandbox_runner_selector,
+                validate_image,
+            )
+
+            if any(value is not None for value in (dataset, source, task_ref, task_id, namespace,
+                   config, split, revision, source_train_job_id, source_train_trial_id)):
+                raise ValueError('Sandbox Jobs accept a Runner without Dataset, Task or training-source options')
+            if any(key in options for key in ('seed', 'profile_name', 'profile_version')):
+                raise ValueError('Sandbox profiles must use profile_id with a registered Runner')
+            if any(key in options for key in ('executor', 'provider')):
+                raise ValueError('execution backend is configured by the server')
+            body = {'type': 'sandbox', 'runner': sandbox_runner_selector(runner),
+                    'request_id': request_id if request_id is not None else str(uuid4()),
+                    'attempts': attempts, 'queue_id': queue_id, 'priority': priority, **options}
+            for key, value in dict(profile_id=profile_id, job_id=job_id, tag=tag).items():
+                if value is not None:
+                    body[key] = value
+            if command is not None:
+                body['command'] = validate_command(command)
+            if image is not None:
+                body['image'] = validate_image(image)
+            validate_public_execution(body)
+            return self._server.submit_job(body)
+        profile_only = all(value is None for value in (dataset, source, task_ref)) and (profile_id is not None or options.get("profile_name") is not None)
+        if sum(value is not None for value in (dataset, source, task_ref)) != 1 and not profile_only:
+            raise ValueError("provide exactly one dataset, source or task_ref")
+        if dataset is None and not profile_only and (runner is not None or any(value is not None for value in (task_id, namespace, config, split, revision))):
+            raise ValueError("dataset selection options require a dataset")
+        if runner is not None:
+            runner = runner_selector(runner)
+        if command is not None:
+            options["command"] = validate_command(command)
+        selection = {key: value for key, value in dict(task_id=task_id, namespace=namespace, config=config,
+                                                      split=split, revision=revision).items() if value is not None}
+        if profile_only:
+            source = {"dataset": selection} if selection else {}
+        elif source is not None:
+            source = {"task": load_task(source)}
+        elif task_ref is not None:
+            source = {"task_ref": dict(task_ref)}
+        elif isinstance(dataset, str):
+            source = {"dataset": dataset_selector(dataset, **selection)}
+        elif isinstance(dataset, Mapping):
+            if "kind" not in dataset:
+                source = {"dataset": dataset_selector(dataset, **selection)}
+            elif selection:
+                raise ValueError("selection options require a dataset name; fixed references already freeze members")
+            else:
+                source = {"dataset_ref": dict(dataset)}
+        else:
+            raise ValueError("dataset must be a fixed reference, name or name@version")
+        for key, value in dict(runner=runner, profile_id=profile_id,
+                               job_id=job_id, tag=tag, source_train_job_id=source_train_job_id,
+                               source_train_trial_id=source_train_trial_id).items():
+            if value is not None:
+                options[key] = value
+        # Omit new defaults on legacy submissions to retain older API compatibility.
+        if runner is not None or queue_id != "default":
+            options["queue_id"] = queue_id
+        if runner is not None or priority != 0:
+            options["priority"] = priority
+        # Resolve on the platform after its request_id check, so a retry retains
+        # its first frozen snapshot even when the source/default has changed.
+        logger.info("job.submitting attempts=%s", attempts)
+        job = self._server.submit_job({"request_id": request_id if request_id is not None else str(uuid4()),
+                                       **source, "attempts": attempts, **options})
+        logger.info("job.submitted job_id=%s", job["job_id"])
+        return job
+
+    def submit_spec(self, body: dict[str, Any], *, params: Mapping[str, Any] | None = None):
+        """Submit an Agent/Sandbox JSON request without dropping declared fields."""
+        if not isinstance(body, dict) or body.get('type', 'agent') not in {'agent', 'sandbox'}:
+            raise ValueError('submit_spec requires an Agent or Sandbox Job object')
+        from envloop_experiment.runtime_params import merge_params
+        if 'params' in body or params is not None:
+            body = {**body, 'params': merge_params(body.get('params', {}), params or {})}
+        request_id = body.get('request_id', str(uuid4()))
+        if not isinstance(request_id, str) or not request_id.strip() or len(request_id) > 128:
+            raise ValueError('request_id must be a non-empty string of at most 128 characters')
+        return self._server.submit_job({'request_id': request_id, **body})
+
+    def regrade(self, *, job_id: str | None = None, trial_ids: Sequence[str] | None = None,
+                reward_set: dict[str, Any] | None = None, runner_ref: str | None = None,
+                runner: str | None = None, budget: dict[str, Any] | None = None,
+                request_id: str | None = None):
+        """Re-run only the verifier of sealed compose Trials, optionally with a reward set version.
+
+        ``job_id`` regrades every sealed Trial of an Agent Job; ``trial_ids`` names Trials that must all be
+        eligible. ``reward_set`` is ``{"uri", "manifest_sha256"}``; ``None`` uses each Task's own tests.
+        Source Trials are never changed: every new score is a new Trial in the returned regrade Job.
+        ``runner`` (``NAME@REVISION|branch|tag``) or ``runner_ref`` selects a Runner Revision that declares
+        regrade support; Trials sealed before that capability existed need one. The default ``request_id`` is
+        derived from the request, so retrying the same regrade is idempotent; pass a new one to run it again.
+        """
+        if (job_id is None) == (trial_ids is None):
+            raise ValueError('regrade needs exactly one of job_id or trial_ids')
+        if trial_ids is not None and (not isinstance(trial_ids, (list, tuple)) or not 1 <= len(trial_ids) <= 1000
+                                      or any(not isinstance(item, str) or not item for item in trial_ids)):
+            raise ValueError('trial_ids must name 1 to 1000 Trials')
+        if reward_set is not None and (not isinstance(reward_set, dict) or set(reward_set) != {'uri', 'manifest_sha256'}):
+            raise ValueError('reward_set must be {"uri": ..., "manifest_sha256": ...}')
+        if runner is not None and runner_ref is not None:
+            raise ValueError('give either runner or runner_ref, not both')
+        if runner is not None and (not isinstance(runner, str) or '@' not in runner):
+            raise ValueError('runner must be NAME@REVISION, branch or tag')
+        source = {'job_id': job_id} if job_id is not None else {'trial_ids': list(cast(Sequence[str], trial_ids))}
+        if request_id is None:
+            import hashlib
+            import json
+            identity = json.dumps({'source': source, 'reward_set': reward_set, 'runner': runner,
+                                   'runner_ref': runner_ref, 'budget': budget}, sort_keys=True, separators=(',', ':'))
+            request_id = 'regrade-' + hashlib.sha256(identity.encode()).hexdigest()[:32]
+        if not isinstance(request_id, str) or not request_id.strip() or len(request_id) > 128:
+            raise ValueError('request_id must be a non-empty string of at most 128 characters')
+        body = {'type': 'regrade', 'request_id': request_id, 'source': source, 'reward_set': reward_set}
+        for key, value in (('runner_ref', runner_ref), ('runner', runner), ('budget', budget)):
+            if value is not None:
+                body[key] = value
+        return self._server.submit_job(body)
+
+    def submit_inference(self, body: dict[str, Any]):
+        """Submit a continuous inference deployment, identified by its Job ID."""
+        from envloop_experiment.inference import validate_submission
+        validate_submission(body)
+        return self._server.submit_job({'request_id': str(uuid4()), **body, 'type': 'inference'})
+
+    def pause(self, job_id: str):
+        return self._server.job_action(job_id, 'pause')
+
+    def resume(self, job_id: str):
+        return self._server.job_action(job_id, 'resume')
+
+    def wake(self, job_id: str):
+        return self._server.job_action(job_id, 'wake')
+
+    def events(self, job_id: str):
+        return self._server.job_events(job_id)
+
+    def status(self, job_id: str):
+        return self._server.get_job(job_id)
+
+    def result(self, job_id: str):
+        return self._server.get_job_result(job_id)
+
+    def list(self, **kwargs: Any):
+        return self._server.list_jobs(**kwargs)
+
+    def logs(self, job_id: str, *, source: str = 'all', cursor: str | None = None, tail: int | None = None,
+             limit: int = 200, process: str | None = None):
+        """Read captured Job output, retaining pagination and collection metadata.
+
+        ``process`` selects one recorded process, e.g. ``"trainer"`` for a Train Job's step metrics.
+        """
+        from envloop_experiment.job_logs import log_query
+
+        return self._server.get_job_logs(job_id, **log_query(source=source, cursor=cursor, tail=tail, limit=limit,
+                                                             process=process))
+
+    def stop(self, job_id: str):
+        return self._server.stop_job(job_id)
+
+    def wait(self, job_id: str, *, timeout: float = 600, poll_interval: float = .1, max_poll_interval: float = 5):
+        """Poll until terminal; the interval grows 1.5x per poll up to ``max_poll_interval``.
+
+        Jobs that run for tens of minutes (large-model training) would otherwise
+        issue ten status requests a second for the whole wait.
+        """
+        if not math.isfinite(timeout) or timeout < 0:
+            raise ValueError("timeout must be finite and non-negative")
+        if not math.isfinite(poll_interval) or poll_interval <= 0:
+            raise ValueError("poll_interval must be finite and positive")
+        if not math.isfinite(max_poll_interval) or max_poll_interval <= 0:
+            raise ValueError("max_poll_interval must be finite and positive")
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.status(job_id)
+            if job["status"] in {"completed", "failed", "cancelled"}:
+                return job
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError("job did not reach a terminal state")
+            time.sleep(min(poll_interval, remaining))
+            poll_interval = max(poll_interval, min(poll_interval * 1.5, max_poll_interval))
+
+
+
+
+class RpcService(TaskService, Protocol):
+    """Transport-independent execution service contract."""

envloop_experiment/decision.py

@@ -0,0 +1,20 @@
+"""Thin Job-bound decision transport. Business logic stays in approved plugins."""
+from typing import Any
+from urllib.parse import quote
+
+
+class DecisionClient:
+    def __init__(self, transport: Any):
+        self.transport = transport
+
+    @staticmethod
+    def validate(job_id: str, model: str, payload: dict[str, Any]):
+        if (not isinstance(job_id, str) or not job_id.strip()
+                or not isinstance(model, str) or not model.strip()
+                or not isinstance(payload, dict) or 'model' in payload):
+            raise ValueError('decision requires job_id, model and a payload object without model')
+
+    def evaluate(self, job_id: str, *, model: str, payload: dict[str, Any]):
+        self.validate(job_id, model, payload)
+        return self.transport.request('POST', f'/v1/job/{quote(job_id, safe="")}/Inference/decision',
+                                      {'model': model, **payload})

envloop_experiment/http.py

@@ -0,0 +1,142 @@
+import shlex
+from collections.abc import Callable
+from http.client import HTTPException, InvalidURL
+from typing import Any, cast
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode
+from urllib.request import Request
+
+from envloop.http import (
+    REDIRECT_STATUSES,
+    Download,
+    RemoteError,
+    transport_error,
+    validate_public_execution,
+)
+
+
+class Endpoints:
+    request: Callable[..., Any]
+    base: str
+    headers: dict[str, str]
+    opener: Any
+    timeout: float
+    remote_error: Callable[[HTTPError], BaseException]
+
+    def submit_job(self, body: dict[str, Any]):
+        validate_public_execution(body)
+        if 'params' in body:
+            from envloop_experiment.runtime_params import validate_params
+            body = {**body, 'params': validate_params(body['params'])}
+        configure_transport(self)
+        return self.request("POST", "/v1/job", body)
+
+
+    def get_job(self, job_id: str):
+        return self.request("GET", f"/v1/job/{quote(job_id, safe='')}")
+
+
+    def get_job_result(self, job_id: str):
+        return self.request("GET", f"/v1/job/{quote(job_id, safe='')}/result")
+
+
+    def get_job_logs(self, job_id: str, **kwargs: Any):
+        return self.request("GET", f"/v1/job/{quote(job_id, safe='')}/logs?" + urlencode(kwargs))
+
+
+    def list_jobs(self, **kwargs: Any):
+        return self.request("GET", "/v1/job?" + urlencode({key: value for key, value in kwargs.items() if value is not None}))
+
+
+    def job_action(self, job_id: str, action: str):
+        return self.request('POST', f"/v1/job/{quote(job_id, safe='')}/{action}", {})
+
+
+    def job_events(self, job_id: str):
+        return self.request('GET', f"/v1/job/{quote(job_id, safe='')}/events")
+
+
+    def stop_job(self, job_id: str):
+        return self.request("POST", f"/v1/job/{quote(job_id, safe='')}/stop")
+
+
+    def list_trials(self, **kwargs: Any):
+        return self.request("GET", "/v1/trials?" + urlencode({key: value for key, value in kwargs.items() if value is not None}))
+
+
+    def get_task_run(self, trial_id: str):
+        return self.request("GET", f"/v1/trials/{quote(trial_id, safe='')}")
+
+
+    def get_trial_detail(self, trial_id: str):
+        return self.request("GET", f"/v1/trials/{quote(trial_id, safe='')}/detail")
+
+
+    def get_trial_training(self, trial_id: str):
+        return self.request("GET", f"/v1/trials/{quote(trial_id, safe='')}/training")
+
+
+    def list_trial_metrics(self, trial_id: str, **kwargs: Any):
+        query = urlencode({key: value for key, value in kwargs.items() if value is not None})
+        return self.request("GET", f"/v1/trials/{quote(trial_id, safe='')}/metrics?{query}")
+
+
+    def list_trial_checkpoints(self, trial_id: str, **kwargs: Any):
+        query = urlencode({key: value for key, value in kwargs.items() if value is not None})
+        return self.request("GET", f"/v1/trials/{quote(trial_id, safe='')}/checkpoints?{query}")
+
+
+    def get_task_result(self, trial_id: str):
+        return self.request("GET", f"/v1/trials/{quote(trial_id, safe='')}/result")
+
+
+    def get_task_snapshot(self, trial_id: str):
+        return self.request("GET", f"/v1/trials/{quote(trial_id, safe='')}/snapshot")
+
+
+    def stop_task(self, trial_id: str):
+        return self.request("POST", f"/v1/trials/{quote(trial_id, safe='')}/stop")
+
+
+    def list_trial_artifacts(self, trial_id: str, **kwargs: Any):
+        return self.request("GET", f"/v1/trials/{quote(trial_id, safe='')}/artifacts?"
+                            + urlencode({key: value for key, value in kwargs.items() if value is not None}))
+
+
+    def open_trial_artifact(self, trial_id: str, artifact_id: str):
+        """Open an artifact through APIServer; storage redirects are refused."""
+        url = self.base + f"/v1/trials/{quote(trial_id, safe='')}/artifacts/{quote(artifact_id, safe='')}/content"
+        headers = {key: value for key, value in self.headers.items() if key != "Content-Type"}
+        try:
+            try:
+                return Download(self.opener.open(Request(url, headers=headers), timeout=self.timeout))
+            except HTTPError as error:
+                if error.code in REDIRECT_STATUSES:
+                    error.close()
+                    raise RemoteError('DATA_REDIRECT_REJECTED', error.code) from None
+                raise self.remote_error(error) from None
+        except (URLError, TimeoutError, OSError, InvalidURL, HTTPException, ValueError) as error:
+            raise transport_error(error) from None
+
+
+
+
+def configure_transport(transport: Any):
+    from envloop.http import HttpService
+    if isinstance(transport, HttpService):
+        cast(Any, transport)._request_policy = request_policy
+
+
+def request_policy(self: Any, method: str, path: str, body: Any, headers: Any):
+    from envloop import http as base_http
+    if method != 'POST' or path != '/v1/job':
+        return self._send(method, path, body, headers, self.timeout)
+    try:
+        return self._send(method, path, body, headers, max(self.timeout, getattr(base_http, "SUBMIT_TIMEOUT_SEC", 120)))
+    except RemoteError as error:
+        submission = body.get("request_id") if isinstance(body, dict) else None
+        if error.status_code is None and isinstance(submission, str) and 0 < len(submission) <= 128 and submission.isprintable():
+            cast(Any, error).submission_request_id = submission
+            error.hint = (f"The platform may already have created this Job. Retry with --request-id {shlex.quote(submission)} "
+                          "to reuse this submission instead of creating a duplicate.")
+        raise

envloop_experiment/inference.py

@@ -0,0 +1,36 @@
+"""Public inference intent validation; resolution and admission remain server owned."""
+import re
+from typing import Any
+
+_FIELDS = {'name', 'runner', 'inputs', 'serving_profile', 'hardware', 'weights_format',
+           'scaling', 'temporary_scope_id', 'profile'}
+
+
+def validate_submission(body: Any):
+    if (not isinstance(body, dict) or set(body) - {'type', 'request_id', 'spec'}
+            or body.get('type', 'inference') != 'inference'):
+        raise ValueError('inference submission requires spec and request_id')
+    spec = body.get('spec')
+    if not isinstance(spec, dict):
+        raise ValueError('inference submission requires a spec object')
+    if 'request_id' in body and (not isinstance(body['request_id'], str)
+            or not body['request_id'].strip() or len(body['request_id']) > 128):
+        raise ValueError('request_id must be a non-empty string of at most 128 characters')
+    if any(key in spec for key in ('provider', 'executor', 'resolved_runner', 'runtime')):
+        raise ValueError('execution configuration and Runner resolution are owned by the server')
+    if 'runner' not in spec:
+        return  # Explicit legacy compatibility: existing adapter specs still reach the API.
+    if set(spec) - _FIELDS:
+        raise ValueError('fixed-input inference cannot mix legacy or runtime fields')
+    runner = spec['runner']
+    if (not isinstance(runner, str)
+            or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*@[^\s@]+', runner)):
+        raise ValueError('runner requires namespace/name@revision')
+    if any(not isinstance(spec.get(key), str) or not spec[key].strip()
+           for key in ('name', 'serving_profile')):
+        raise ValueError('fixed-input inference requires name and serving_profile')
+    inputs = spec.get('inputs', {})
+    if (not isinstance(inputs, dict) or set(inputs) - {'checkpoint'}
+            or 'checkpoint' in inputs and (not isinstance(inputs['checkpoint'], str)
+            or not inputs['checkpoint'].startswith('envloop://') or not inputs['checkpoint'][10:])):
+        raise ValueError('inputs accepts one Checkpoint ANS URI')