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

envloop_experiment/job_cost.py

@@ -0,0 +1,41 @@
+"""One-line view of an Agent/Sandbox Job's ``cost`` and budget; reading never changes the Job."""
+
+import math
+from typing import Any
+
+
+def _usd(value: object) -> str:
+    if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value):
+        return "unknown"
+    if 0 < value < 0.01:
+        # Sub-cent amounts keep their significant digits down to one micro-USD (the platform's unit).
+        exact = f"{value:.6f}".rstrip("0")
+        return "$" + (exact if exact != "0." else f"{value:.1e}")
+    return f"${value:.2f}"
+
+
+def cost_line(job: Any) -> str | None:
+    """``Cost (estimate): $5.03 (model $4.12, sandbox $0.91) of a $5.00 budget; stopped: budget reached``.
+
+    None when the response has no ``cost`` block (Train and Inference Jobs, older platforms). An unknown
+    part is shown as unknown, never as zero.
+    """
+    cost = job.get("cost") if isinstance(job, dict) else None
+    if not isinstance(cost, dict):
+        return None
+    line = f"Cost (estimate): {_usd(cost.get('total_usd'))} (model {_usd(cost.get('model_usd'))}, " \
+           f"sandbox {_usd(cost.get('sandbox_usd'))})"
+    if cost.get("cap_usd") is not None:
+        line += f" of a {_usd(cost.get('cap_usd'))} budget"
+        if cost.get("unmetered") is True:
+            line += "; some usage has no price, so the budget cannot be enforced"
+        elif cost.get("budget_exceeded") is True:
+            line += "; stopped: budget reached"
+        else:
+            reserved = cost.get("reserved_usd")
+            line += f", {_usd(cost.get('remaining_usd'))} left"
+            if isinstance(reserved, (int, float)) and not isinstance(reserved, bool) and reserved > 0:
+                line += f" ({_usd(reserved)} reserved by running Trials)"
+    if cost.get("billing_mode") in {"off", "shadow"}:
+        line += f"; sandbox time not charged ({cost['billing_mode']} billing)"
+    return line

envloop_experiment/job_logs.py

@@ -0,0 +1,21 @@
+"""Selection shared by generic and training Job log views."""
+import re
+from typing import Any
+
+
+def log_query(*, source: str = 'all', cursor: str | None = None, tail: int | None = None, limit: int = 200, process: str | None = None) -> dict[str, Any]:
+    if source not in {'all', 'system', 'runtime'}:
+        raise ValueError('source must be all, system or runtime')
+    # One recorded process, for example ``trainer`` (the trainer's step metrics) or ``controller``.
+    if process is not None and (not isinstance(process, str) or not re.fullmatch(r'[A-Za-z0-9._:-]{1,128}', process)):
+        raise ValueError('process must be 1-128 letters, digits, ".", "_", ":" or "-"')
+    for name, value in (('limit', limit), ('tail', tail)):
+        if (name == 'limit' or value is not None) and (type(value) is not int or not 1 <= value <= 1000):
+            raise ValueError(f'{name} must be an integer from 1 to 1000')
+    if cursor is not None and (not isinstance(cursor, str) or not cursor):
+        raise ValueError('cursor must be a non-empty string')
+    if cursor is not None and tail is not None:
+        raise ValueError('cursor and tail are mutually exclusive')
+    return {key: value for key, value in {
+        'source': source, 'process': process, 'cursor': cursor, 'tail': tail, 'limit': limit,
+    }.items() if value is not None}

envloop_experiment/job_spec_cli.py

@@ -0,0 +1,146 @@
+"""Merge explicit Job CLI inputs into the public, type-specific request."""
+import argparse
+import json
+from collections.abc import Iterable, Mapping
+from copy import deepcopy
+from types import SimpleNamespace
+from typing import Any, cast
+
+from envloop_experiment.client import dataset_selector, runner_selector
+from envloop_experiment.train_runner_cli import SHORTCUT_FIELDS, runner_request
+
+
+class SpecFileError(ValueError):
+    """The input file is not a Job JSON object."""
+
+
+def spec_request(args: argparse.Namespace):
+    if args.trails is not None:
+        raise ValueError('--trails cannot be combined with --spec; the file defines its Trial list')
+    if args.type in {'agent', 'sandbox', 'inference'} and any(getattr(args, key) is not None for key in SHORTCUT_FIELDS):
+        raise ValueError('Train Runner shortcuts require --type train')
+    if args.type == 'inference':
+        if args.wait or args.timeout_sec is not None:
+            raise ValueError('Inference is a continuous service; --wait and --timeout-sec do not apply')
+        if args.runner is not None:
+            runner_selector(args.runner)
+    request = json.loads(args.spec.read_text(encoding='utf-8'))
+    if not isinstance(request, dict):
+        raise SpecFileError('Job spec must be a JSON object')
+    request = deepcopy(request)
+    kind = args.type or request.get('type', 'agent')
+    if kind not in {'agent', 'sandbox', 'train', 'inference'}:
+        raise ValueError('unsupported Job spec type')
+    args.type = kind
+    request['type'] = kind
+    if args.request_id is not None:
+        request['request_id'] = args.request_id
+    if args.trails is not None:
+        raise ValueError('--trails cannot be combined with --spec; the file defines its Trial list')
+    if args.dataset is not None and args.dataset_option is not None:
+        raise ValueError('provide only one positional dataset or --dataset')
+    def supplied(names: Iterable[str]):
+        return [name for name in names if getattr(args, name) is not None]
+    if kind in {'train', 'inference'}:
+        invalid = supplied(('dataset', 'dataset_option', 'source', 'task_id', 'split', 'revision',
+                            'job_id', 'tag', 'attempts', 'profile', 'delete_delay', 'max_cost_usd'))
+        if kind == 'inference':
+            invalid += supplied(('config', 'priority', 'seed', 'command', 'image', 'timeout_sec', *SHORTCUT_FIELDS))
+            if args.wait:
+                invalid.append('wait')
+        if invalid:
+            raise ValueError(f'--type {kind} does not support '+', '.join('--'+name.replace('_', '-') for name in invalid))
+        if kind == 'inference':
+            if args.runner is not None:
+                if not isinstance(request.get('spec'), dict):
+                    raise ValueError('Inference Job spec requires a spec object')
+                request['spec']['runner'] = runner_selector(args.runner)
+            return request
+        grouped = 'trials' in request or 'spec' in request
+        trials = request.get('trials', [{'spec': request.get('spec')}]) if grouped else [{'spec': request}]
+        if not isinstance(trials, list) or not trials or any(not isinstance(t, dict) or not isinstance(t.get('spec'), dict) for t in trials):
+            raise ValueError('Train Job spec requires non-empty trials with spec objects')
+        if args.priority is not None:
+            request['priority'] = args.priority
+        runner_fields = ('runner', 'command', 'image', 'timeout_sec', *SHORTCUT_FIELDS)
+        for trial in trials:
+            spec = trial['spec']
+            for field in ('seed', 'config'):
+                if getattr(args, field) is not None:
+                    spec[field] = getattr(args, field)
+            active_fields = runner_fields
+            values = vars(args).copy()
+            if not (args.runner or spec.get('runner')) and args.wait:
+                active_fields = tuple(field for field in runner_fields if field != 'timeout_sec')
+                values['timeout_sec'] = None
+            if supplied(active_fields):
+                values['runner'] = args.runner if args.runner is not None else spec.get('runner')
+                overlay = runner_request(cast(argparse.Namespace, SimpleNamespace(**values)))['trials'][0]['spec']
+                if 'resources' in overlay:
+                    overlay['resources'] = {**spec.get('resources', {}), **overlay['resources']}
+                spec.update(overlay)
+        return request
+    if supplied(SHORTCUT_FIELDS):
+        raise ValueError('Train Runner shortcuts require --type train')
+    if kind == 'sandbox' and supplied(('dataset', 'dataset_option', 'source', 'task_id', 'config', 'split', 'revision', 'seed')):
+        raise ValueError('Sandbox Jobs do not accept Dataset, Task or seed options')
+    if kind == 'agent' and args.image is not None:
+        raise ValueError('--image requires --type sandbox')
+    for field in ('job_id', 'tag', 'priority', 'attempts', 'command', 'image'):
+        if getattr(args, field) is not None:
+            request[field] = getattr(args, field)
+    if args.runner is not None:
+        if kind == 'sandbox':
+            from envloop_experiment.sandbox import sandbox_runner_selector
+            request['runner'] = sandbox_runner_selector(args.runner)
+        else:
+            request['runner'] = runner_selector(args.runner)
+    dataset = args.dataset if args.dataset is not None else args.dataset_option
+    if args.source is not None and dataset is not None:
+        raise ValueError('provide only one dataset or --source')
+    if args.source is not None or dataset is not None:
+        for key in ('dataset', 'dataset_ref', 'task', 'task_ref'):
+            request.pop(key, None)
+        if args.source is not None:
+            from envloop_experiment.client import load_task
+            request['task'] = load_task(args.source)
+        else:
+            request['dataset'] = dataset_selector(cast(Mapping[str, Any] | str, dataset))
+    selection = {key: getattr(args, key) for key in ('task_id', 'config', 'split', 'revision') if getattr(args, key) is not None}
+    if selection:
+        base = request.get('dataset', {})
+        if isinstance(base, str):
+            base = dataset_selector(base)
+        if not isinstance(base, dict) or 'task' in request or 'task_ref' in request or 'dataset_ref' in request:
+            raise ValueError('dataset selection options require a dataset selector')
+        request['dataset'] = {**base, **selection}
+    if args.profile is not None:
+        for key in ('profile_id', 'profile_name', 'profile_version', 'profile_ref'):
+            request.pop(key, None)
+        if request.get('runner') is not None:
+            request['profile_id'] = args.profile
+        else:
+            name, _, version = args.profile.partition('@')
+            request['profile_name'] = name
+            if version:
+                request['profile_version'] = version
+    if args.seed is not None:
+        if request.get('runner') is not None:
+            request['profile'] = {**request.get('profile', {}), 'seed': args.seed}
+        else:
+            request['seed'] = args.seed
+    execution = {}
+    if args.timeout_sec is not None:
+        if not args.timeout_sec.is_integer():
+            raise ValueError('--timeout-sec must be whole seconds')
+        execution['timeout_sec'] = int(args.timeout_sec)
+    if args.delete_delay is not None:
+        execution['delete_delay_sec'] = args.delete_delay
+    if execution:
+        request['execution'] = {**request.get('execution', {}), **execution}
+    if args.max_cost_usd is not None:
+        request['budget'] = {'max_cost_usd': args.max_cost_usd}
+    from envloop_experiment.runtime_params import merge_params
+    if 'params' in request or getattr(args, 'params', None) is not None:
+        request['params'] = merge_params(request.get('params', {}), getattr(args, 'params', None) or {})
+    return request

envloop_experiment/navigation_resources.py

@@ -0,0 +1,43 @@
+from typing import Any
+from urllib.parse import quote
+
+
+class InferenceResource:
+    def __init__(self, transport: Any, path: str):
+        self.transport, self.path = transport, path
+
+    def list(self):
+        return self.transport.request('GET', self.path)
+
+    def get(self, identifier: str):
+        return self.transport.request('GET', self.path + '/' + quote(identifier, safe=''))
+
+    def create(self, body: dict[str, Any]):
+        if not isinstance(body, dict):
+            raise ValueError('request must be an object')
+        return self.transport.request('POST', self.path, body)
+
+    def action(self, identifier: str, action: str):
+        if action not in {'events', 'wake', 'pause', 'resume', 'delete'}:
+            raise ValueError('unsupported endpoint action')
+        path = self.path + '/' + quote(identifier, safe='')
+        method = 'DELETE' if action == 'delete' else 'GET' if action == 'events' else 'POST'
+        return self.transport.request(method, path if action == 'delete' else path + '/' + action)
+
+
+class Inference:
+    def __init__(self, transport: Any):
+        self.profiles = InferenceResource(transport, '/v1/serving/profiles')
+        self.adapters = InferenceResource(transport, '/v1/adapters')
+        self.endpoints = InferenceResource(transport, '/v1/endpoints')
+
+
+class Dashboard:
+    def __init__(self, project: Any, jobs: Any, training: Any):
+        self.project, self.jobs, self.training = project, jobs, training
+
+    def get(self):
+        identity = self.project.transport.request('GET', '/v1/me')
+        project = identity.get('project') or {key: identity.get(key) for key in ('workspace_id', 'project_id')}
+        return {'project': project, 'jobs': self.jobs.list(limit=25, type='agent'),
+                'training': self.training.list(limit=25), 'coverage': 'first_page'}

envloop_experiment/resource_cli.py

@@ -0,0 +1,33 @@
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+from envloop.resource_cli import listing
+
+
+def add_job_resources(jobs: "argparse._SubParsersAction[argparse.ArgumentParser]"):
+    profiles = jobs.add_parser('serving-profile', help='Discover deployable serving profiles').add_subparsers(dest='resource_action', required=True)
+    listing(profiles, paged=False)
+    adapters = jobs.add_parser('adapter', help='Manage reusable inference adapters').add_subparsers(dest='resource_action', required=True)
+    listing(adapters, paged=False)
+    adapters.add_parser('get', help='Show an adapter').add_argument('identifier')
+    register = adapters.add_parser('register', help='Register an adapter using a JSON request')
+    register.add_argument('--file', type=Path, required=True)
+    delete = adapters.add_parser('delete', help='Delete an unreferenced adapter')
+    delete.add_argument('identifier')
+    from envloop.lifecycle_cli import wait_options
+    wait_options(delete)
+
+
+def run_job_resource(client: Any, args: argparse.Namespace):
+    resource = client.inference.profiles if args.action == 'serving-profile' else client.inference.adapters
+    action = args.resource_action
+    if action == 'list':
+        return resource.list()
+    if action == 'get':
+        return resource.get(args.identifier)
+    if action == 'register':
+        return resource.create(json.loads(args.file.read_text(encoding='utf-8')))
+    result = resource.action(args.identifier, 'delete')
+    return client.operations.wait(result['operation_id'], timeout=args.timeout_sec) if args.wait else result

envloop_experiment/resources.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Sequence
+from types import TracebackType
+from typing import Any
+from uuid import uuid4
+
+from envloop.http import RemoteError
+from envloop.resources import CleanupError, _id, _wait_options
+
+
+class Adapters:
+    def __init__(self, transport: Any, temporary_scope_id: str | None = None):
+        self.transport, self.temporary_scope_id = transport, temporary_scope_id
+
+    def list(self):
+        return self.transport.request("GET", "/v1/adapters")
+
+    def get(self, adapter_id: str):
+        return self.transport.request("GET", f"/v1/adapters/{_id(adapter_id)}")
+
+    def register(self, checkpoint: str, *, serving_profile: str, request_id: str | None = None):
+        body = {"request_id": request_id or str(uuid4()), "serving_profile": serving_profile,
+                "source": {"type": "train_checkpoint", "tinker_path": checkpoint}}
+        if self.temporary_scope_id:
+            body["temporary_scope_id"] = self.temporary_scope_id
+        return self.transport.request("POST", "/v1/adapters", body)
+
+    def delete(self, adapter_id: str):
+        return self.transport.request("DELETE", f"/v1/adapters/{_id(adapter_id)}")
+
+
+class Endpoints:
+    def __init__(self, transport: Any, temporary_scope_id: str | None = None):
+        self.transport, self.temporary_scope_id = transport, temporary_scope_id
+
+    def profiles(self):
+        return self.transport.request("GET", "/v1/serving/profiles")
+
+    def list(self):
+        return self.transport.request("GET", "/v1/endpoints")
+
+    def get(self, endpoint_id: str):
+        return self.transport.request("GET", f"/v1/endpoints/{_id(endpoint_id)}")
+
+    def create(self, *, name: str, serving_profile: str, adapters: Sequence[dict[str, str]], request_id: str | None = None, **options: Any):
+        body = {"request_id": request_id or str(uuid4()), "name": name, "serving_profile": serving_profile,
+                "adapters": adapters, "scaling": {"min_replicas": 0, "max_replicas": 1, "scale_to_zero_after_s": 300},
+                **options}
+        if self.temporary_scope_id:
+            body["temporary_scope_id"] = self.temporary_scope_id
+        return self.transport.request("POST", "/v1/endpoints", body)
+
+    def _action(self, endpoint_id: str, action: str):
+        return self.transport.request("POST", f"/v1/endpoints/{_id(endpoint_id)}/{action}", {})
+
+    def wake(self, endpoint_id: str):
+        return self._action(endpoint_id, "wake")
+
+    def pause(self, endpoint_id: str):
+        return self._action(endpoint_id, "pause")
+
+    def resume(self, endpoint_id: str):
+        return self._action(endpoint_id, "resume")
+
+    def delete(self, endpoint_id: str):
+        return self.transport.request("DELETE", f"/v1/endpoints/{_id(endpoint_id)}")
+
+    def wait(self, endpoint_id: str, *, timeout: float = 1800, poll_interval: float = 5):
+        _wait_options(timeout, poll_interval)
+        deadline = time.monotonic() + timeout
+        while True:
+            result = self.get(endpoint_id)
+            if result["status"] == "READY":
+                return result
+            if result["status"] in {"FAILED", "DELETED", "DELETING", "PAUSED", "SUSPENDED"}:
+                raise RemoteError("ENDPOINT_NOT_READY")
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(f"Endpoint {endpoint_id} did not become ready")
+            time.sleep(min(remaining, poll_interval))
+
+    def generate(self, model: str, prompt: str, *, job_id: str | None = None, **options: Any):
+        """Return the API completion; transient cold-start errors remain observable."""
+        if job_id is None:
+            raise ValueError('job_id is required; use the Job ID returned by endpoint creation')
+        return self.transport.request("POST", f"/v1/job/{_id(job_id)}/Inference/chat/completions", {
+            "model": model, "messages": [{"role": "user", "content": prompt}], **options,
+        })
+
+
+class TemporaryResources:
+    """Register on the server before work; wait for cleanup on every context exit.
+
+    The bounded server TTL survives a killed/disconnected process. Only resource
+    creation through this scope is enrolled; passing an existing ID never enrolls
+    it. Keep ``scope_id`` to retry cleanup after a client timeout.
+    """
+    cleanup_result: dict[str, Any] | None
+
+    def __init__(self, client: Any, *, ttl_seconds: int = 1800, request_id: str | None = None, cleanup_timeout: float = 600, poll_interval: float = 2):
+        if isinstance(ttl_seconds, bool) or not isinstance(ttl_seconds, int) or not 60 <= ttl_seconds <= 86400:
+            raise ValueError("ttl_seconds must be an integer between 60 and 86400")
+        _wait_options(cleanup_timeout, poll_interval)
+        self.client, self.ttl_seconds = client, ttl_seconds
+        self.request_id = request_id or str(uuid4())
+        self.cleanup_timeout, self.poll_interval = cleanup_timeout, poll_interval
+        self.scope_id, self.cleanup_result = None, None
+
+    def __enter__(self):
+        if self.scope_id is not None:
+            raise RuntimeError("A temporary scope can only be entered once")
+        scope = self.client._transport.request("POST", self.client.operations.project_path + "/temporary-resource-scopes",
+                                               {"request_id": self.request_id, "ttl_seconds": self.ttl_seconds})
+        self.scope_id = scope["scope_id"]
+        self.endpoints = Endpoints(self.client._transport, self.scope_id)
+        self.adapters = Adapters(self.client._transport, self.scope_id)
+        return self
+
+    @property
+    def path(self):
+        if self.scope_id is None:
+            raise RuntimeError("Enter the temporary resource scope before using it")
+        return self.client.operations.project_path + "/temporary-resource-scopes/" + _id(self.scope_id)
+
+    def get(self):
+        return self.client._transport.request("GET", self.path)
+
+    def retain(self, resources: list[dict[str, str]]):
+        return self.client._transport.request("POST", self.path + "/retain", {"resources": resources})
+
+    def cleanup(self):
+        self.cleanup_result = self.client._transport.request("DELETE", self.path)
+        try:
+            self.cleanup_result = self.client.operations.wait(self.cleanup_result["operation_id"],
+                                                              timeout=self.cleanup_timeout, poll_interval=self.poll_interval)
+        except CleanupError as error:
+            self.cleanup_result = error.operation
+            raise
+        return self.cleanup_result
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, traceback: TracebackType | None) -> bool:
+        try:
+            self.cleanup()
+        except BaseException as cleanup_error:
+            if exc is None:
+                raise
+            # Preserve both failures: the primary error is never silently replaced.
+            exc.add_note(f"Cleanup remains incomplete for scope {self.scope_id}; {type(cleanup_error).__name__}. Server TTL remains active.")
+            raise exc from cleanup_error
+        return False

envloop_experiment/runtime_params.py

@@ -0,0 +1,83 @@
+"""Literal highest-priority runtime parameters; no shell or environment expansion."""
+import argparse
+import json
+import re
+from collections.abc import Iterable, Sequence
+from copy import deepcopy
+from typing import Any
+
+# Keep aligned with the public server runtime-patch boundary, not resource selectors.
+PROTECTED = frozenset('PATH HOME SHELL ENV BASH_ENV PYTHONPATH PYTHONHOME NODE_OPTIONS EXECUTOR PROVIDER '
+    'RUNNER RUNNER_REF RUNNER_SOURCE REVISION SOURCE SOURCE_HASH SHA256 IMAGE DOCKER_IMAGE ENTRYPOINT COMMAND RUN_COMMAND '
+    'PROFILE PROFILE_ID PROFILE_NAME PROFILE_VERSION PROFILE_SHA256 PROFILE_REF DATASET DATASET_REF TASK TASK_REF '
+    'ACL TENANT TENANT_ID WORKSPACE_ID PROJECT_ID USER_ID BUDGET LIMITS QUOTA EXECUTION ENVIRONMENT'.split())
+PREFIXES = ('ENVLOOP_', 'ENVPLATFORM_', 'JOB_MASTER_', 'LD_', 'DYLD_')
+UNSAFE = {'__proto__', 'constructor', 'prototype'}
+MESSAGE = 'expected a runtime parameter JSON object or KEY=VALUE; invalid or protected parameter'
+
+
+def _check_json(value: Any, depth: int = 0) -> None:
+    if depth > 32 or isinstance(value, str) and '\x00' in value:
+        raise ValueError(MESSAGE)
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str) or key in UNSAFE:
+                raise ValueError(MESSAGE)
+            _check_json(item, depth + 1)
+    elif isinstance(value, list):
+        for item in value:
+            _check_json(item, depth + 1)
+    elif value is not None and type(value) not in (str, int, float, bool):
+        raise ValueError(MESSAGE)
+
+
+def validate_params(value: Any) -> dict[str, Any]:
+    try:
+        if not isinstance(value, dict):
+            raise ValueError
+        _check_json(value)
+        raw = json.dumps(value, ensure_ascii=False, allow_nan=False)
+        if len(raw.encode()) > 65536 or '\x00' in raw or any('\x00' in k for k in value):
+            raise ValueError
+        result: dict[str, Any] = {}
+        for key, item in value.items():
+            target = key.upper()
+            if (not re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]*', key, re.ASCII)
+                    or target in PROTECTED or target.startswith(PREFIXES) or target in result):
+                raise ValueError
+            result[target] = deepcopy(item)
+        return result
+    except (ValueError, TypeError, RecursionError, OverflowError):
+        raise ValueError(MESSAGE) from None
+
+
+def merge_params(base: Any, explicit: Any) -> dict[str, Any]:
+    return validate_params(validate_params(base) | validate_params(explicit))
+
+
+def _pairs(pairs: Iterable[tuple[str, Any]]) -> dict[str, Any]:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(MESSAGE)
+        result[key] = value
+    return result
+
+
+def parse_params(text: str) -> dict[str, Any]:
+    try:
+        if not text.lstrip().startswith(('{', '[', '"')) and '=' in text:
+            key, value = text.split('=', 1)
+            return validate_params({key: value})
+        return validate_params(json.loads(text, object_pairs_hook=_pairs))
+    except (ValueError, TypeError, RecursionError):
+        raise argparse.ArgumentTypeError(MESSAGE) from None
+
+
+class ParamsAction(argparse.Action):
+    def __call__(self, parser: argparse.ArgumentParser, namespace: argparse.Namespace,
+                 values: str | Sequence[Any] | None, option_string: str | None = None) -> None:
+        try:
+            setattr(namespace, self.dest, merge_params(getattr(namespace, self.dest, None) or {}, values))
+        except ValueError:
+            raise argparse.ArgumentError(self, MESSAGE) from None

envloop_experiment/sandbox.py

@@ -0,0 +1,28 @@
+"""Validate Sandbox Runner selections without resolving platform assets."""
+
+import re
+from typing import Any
+
+
+def validate_image(value: Any) -> str:
+    if (not isinstance(value, str) or len(value) > 512 or not re.fullmatch(
+            r'(?:[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*(?::[0-9]+)?/)*'
+            r'[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*'
+            r'(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(?:@sha256:[a-fA-F0-9]{64})?', value)):
+        raise ValueError('Sandbox image must be a Docker image name, optionally with a tag or sha256 digest')
+    return value
+
+
+def sandbox_runner_selector(value: Any) -> str:
+    if not isinstance(value, str) or not value or len(value) > 1024:
+        raise ValueError('Sandbox requires --runner NAME[@REVISION]')
+    prefix = 'envloop://runners/'
+    selector = value[len(prefix):] if value.startswith(prefix) else value
+    name, at, revision = selector.partition('@')
+    if not re.fullmatch(r'[a-z0-9][a-z0-9._-]*(?:/[a-z0-9][a-z0-9._-]*)?', name):
+        raise ValueError('Sandbox runner must be a short name or namespace/name[@REVISION]')
+    if at:
+        from envloop_experiment.client import runner_selector
+
+        runner_selector(f'{name if "/" in name else "envloop/" + name}@{revision}')
+    return selector

envloop_experiment/train.py

@@ -0,0 +1,93 @@
+"""Thin Train Job transport using the platform's unified Job contract."""
+import math
+import time
+from typing import Any
+from urllib.parse import quote, urlencode
+
+from envloop.client import INTERACTIVE_TRAINING_REMOVED as INTERACTIVE_TRAINING_REMOVED
+from envloop.http import RemoteError
+
+
+class TrainJobs:
+    def __init__(self, transport: Any):
+        self.transport = transport
+        from .http import configure_transport
+        configure_transport(self.transport)
+
+    def models(self) -> dict[str, Any]:
+        """Discover configured managed recipes; admission and GPU readiness remain separate."""
+        try:
+            return self.transport.request('GET', '/v1/job/training-models')
+        except RemoteError as error:
+            if error.status_code == 404:
+                raise RuntimeError(
+                    "This platform does not serve /v1/job/training-models; upgrade the platform to a "
+                    "version that matches this client (managed training discovery is unavailable).") from error
+            raise
+
+    @staticmethod
+    def _view(result: dict[str, Any]):
+        return {**(result.get('training') or {}), **result}
+
+    def submit(self, request: dict[str, Any]) -> dict[str, Any]:
+        """Submit one managed spec or ``{request_id, trials: [{name?, spec}, ...]}``.
+
+        Each Trial spec is an independent managed recipe or published Runner
+        (``{runner: "namespace/name@REVISION", resources?: {...}, ...}``).
+        Optional ``tags`` is a bounded string map for either recipe or Runner specs.
+        Runner ``command`` is the declared run_command parameter, never an
+        entrypoint override. Validation, defaults and execution selection belong
+        to the platform. The training view retains the server's complete response.
+        """
+        if not isinstance(request, dict) or request.get("type", "train") != "train":
+            raise ValueError("Train Job request must be a JSON object")
+        return self._view(self.transport.request("POST", "/v1/job", request | {"type": "train"}))
+
+    def status(self, job_id: str) -> dict[str, Any]:
+        return self._view(self.transport.request("GET", f"/v1/job/{quote(job_id, safe='')}") )
+
+    def result(self, job_id: str) -> dict[str, Any]:
+        return self._view(self.transport.request('GET', f'/v1/job/{quote(job_id, safe="")}/result'))
+
+    def logs(self, job_id: str, *, source: str = "all", cursor: str | None = None, tail: int | None = None, limit: int = 200, process: str | None = None) -> dict[str, Any]:
+        """Read a log page; cursors retain the server's source and capture metadata.
+
+        ``process="trainer"`` reads only the trainer's step metric lines. Live step, loss and ETA
+        are ``status(job_id)["progress"]``.
+        """
+        from envloop_experiment.job_logs import log_query
+
+        query = urlencode(log_query(source=source, cursor=cursor, tail=tail, limit=limit, process=process))
+        return self.transport.request("GET", f"/v1/job/{quote(job_id, safe='')}/logs?{query}")
+
+    def stop(self, job_id: str) -> dict[str, Any]:
+        return self._view(self.transport.request('POST', f'/v1/job/{quote(job_id, safe="")}/stop'))
+
+    def list(self, *, status: str | None = None, cursor: str | None = None, limit: int = 25) -> dict[str, Any]:
+        query = urlencode({key: value for key, value in {
+            "type": "train", "status": status, "cursor": cursor, "limit": limit,
+        }.items() if value is not None})
+        page = self.transport.request("GET", "/v1/job?" + query)
+        return {**page, "items": [self._view(item) for item in page["items"]]}
+
+    def checkpoints(self, *, train_job_id: str | None = None, job_id: str | None = None, run_id: str | None = None, cursor: str | None = None, limit: int = 25) -> dict[str, Any]:
+        query = urlencode({key: value for key, value in {
+            "train_job_id": train_job_id, "job_id": job_id, "run_id": run_id,
+            "cursor": cursor, "limit": limit,
+        }.items() if value is not None})
+        return self.transport.request("GET", "/v1/job/checkpoints?" + query)
+
+    def delete_checkpoint(self, checkpoint_id: str) -> dict[str, Any]:
+        return self.transport.request("DELETE", f"/v1/job/checkpoints/{quote(checkpoint_id, safe='')}")
+
+    def wait(self, job_id: str, *, timeout: float = 600) -> dict[str, Any]:
+        if not math.isfinite(timeout) or timeout < 0:
+            raise ValueError("timeout must be finite and non-negative")
+        deadline = time.monotonic() + timeout
+        while True:
+            result = self.status(job_id)
+            if result["status"] in {"SUCCEEDED", "FAILED", "CANCELLED", "completed", "succeeded", "failed", "cancelled"}:
+                return result
+            if time.monotonic() >= deadline:
+                raise TimeoutError("Train Job did not finish before timeout")
+            time.sleep(min(0.1, max(0, deadline - time.monotonic())))