envloop-cli 1.28.0__py3-none-any.whl → 1.30.0__py3-none-any.whl

envloop/_optional.py

@@ -30,7 +30,7 @@ FEATURE_COMMANDS = {
 
 MODULES: dict[str, str] = {
     **dict.fromkeys('data data_publications data_upload data_cli profile_updates recipes'.split(), 'data'),
-    **dict.fromkeys('train train_progress train_runner_cli train_log_cli job_logs job_cost inference decision sandbox runtime_params job_spec_cli training'.split(), 'experiment'),
+    **dict.fromkeys('train train_progress train_metrics_cli train_runner_cli train_log_cli job_logs job_cost inference decision sandbox runtime_params job_spec_cli training'.split(), 'experiment'),
     **dict.fromkeys('agent_runs rsi_cli'.split(), 'rsi-loop'),
 }
 CLIENTS = {

envloop/auth_cli.py

@@ -20,6 +20,9 @@ def add_auth_commands(groups: "argparse._SubParsersAction[argparse.ArgumentParse
     login.add_argument("--no-browser", action="store_true", help="Print the login link without opening a browser")
     login.add_argument("--timeout-seconds", type=int, choices=range(1, 601), metavar="SECONDS", default=300,
                        help="Wait up to 1–600 seconds (default: 300)")
+    login.add_argument("--read-only", action="store_true",
+                       help="Issue a read-only key, for example for CI that only reads results. "
+                            "Without it the key follows your project role")
     configure = commands.add_parser("config", help="Save Base URL and API key for CLI and SDK")
     configure.add_argument("--no-check", action="store_true", help="Save without API verification (offline; key remains unverified)")
     actions = configure.add_subparsers(dest="config_action")

envloop/auth_login.py

@@ -76,7 +76,8 @@ def login(args: argparse.Namespace, store: Any) -> int:
     def digest(value: str) -> str:
         return hashlib.sha256(value.encode()).hexdigest()
     response = _request(url, 'start', {'key_hash': digest(key), 'poll_hash': digest(poll_token),
-                                    'code_hash': digest(code)}, min(5, args.timeout_seconds))
+                                    'code_hash': digest(code), **({'read_only': True} if args.read_only else {})},
+                        min(5, args.timeout_seconds))
     identifier, uri = _verification_url(url, response)
     interval, expires = response.get('interval'), response.get('expires_in')
     if (isinstance(interval, bool) or not isinstance(interval, (int, float)) or not 0 < interval <= 10 or
@@ -88,6 +89,8 @@ def login(args: argparse.Namespace, store: Any) -> int:
     try:
         print(f'Base URL: {url}\nConfirmation code: {code}\nOpen: {uri}', flush=True)
         print('Sign in with Clerk, enter this code, and authorize your workspace/project.', flush=True)
+        print('The key will be read only.' if args.read_only else
+              'The key follows your project role. The page lists its permissions before you authorize.', flush=True)
         if not args.no_browser:
             try:
                 opened = webbrowser.open(uri, new=1)

envloop/cli_errors.py

@@ -27,10 +27,10 @@ def _register(codes: str, message: str) -> None:
         _MESSAGES[code] = message
 
 
-_register("DATA_SCOPE_REQUIRED", "Configure a project key with explicit Data read permission, plus Data write for publication and upload management.")
+_register("DATA_ACCESS_REQUIRED", "This key lacks the permission named above on the Dataset, Runner, Profile, Checkpoint or Trial artifact. Run el auth login to issue a new key that follows your project role: every role can read, and Developer or Admin can also write and delete (create, update, delete, upload, runner register). A key from el auth login --read-only cannot write; log in again without --read-only. Or give a key Read or Edit on that page in the Console under CONFIGURE > API Keys. Existing keys never gain permissions.")
 _register("DATA_NATIVE_INCOMPLETE DATA_NATIVE_UNAVAILABLE", "Native catalog registration is incomplete. Retry the same input after the platform is ready.")
 _register("DATA_DEPENDENCIES_ACTIVE DATA_DEPENDENCIES_UNKNOWN DATA_DEPENDENCIES_CHANGED DATA_DELETE_CONFLICT", "Retirement requires a complete, current dependency check. Resolve active or unknown dependencies, then retry the same resource.")
-_register("DATA_PUBLICATION_INVALID", "Check the immutable ANS URI, native manifest and exact file sizes and SHA-256 values.")
+_register("DATA_PUBLICATION_INVALID", "Check the immutable ANS URI, native manifest and exact file sizes and SHA-256 values. A record Dataset source is https://github.com/OWNER/REPO or https://huggingface.co/datasets/ORG/NAME with the full commit, not a branch or tag.")
 _register("DATA_PIN_CONFLICT DATA_REVISION_REQUIRED", "Publish a new immutable revision; existing and revoked references cannot be overwritten.")
 _register("DATA_QUOTA_EXCEEDED DATA_QUOTA_UNCONFIGURED", "Ask a project administrator to configure publication storage quota. Revoking publications does not free retained content.")
 _register("DATA_UPLOAD_CONFLICT DATA_UPLOAD_INCOMPLETE DATA_UPLOAD_RATE_LIMITED", "Inspect the upload with data upload get; resume matching parts or explicitly abort it.")
@@ -182,7 +182,7 @@ TASK_REQUEST_CONFLICT TEMPORARY_DEPENDENCY_REQUIRES_RETAIN TEMPORARY_RESOURCE_RE
 TEMPORARY_SCOPE_CONFLICT TEMPORARY_SCOPE_EXPIRED TRIAL_IDEMPOTENCY_CONFLICT TRIAL_VERSION_CONFLICT USAGE_EVENT_CONFLICT
 PROFILE_CORRUPT ADAPTER_STORAGE_UNAVAILABLE INSUFFICIENT_BALANCE METHOD_NOT_ALLOWED REQUEST_TOO_LARGE
 BATCH_POLICY_NOT_APPROVED BATCH_PROVIDER_UNAVAILABLE CHECKPOINT_ACCESS_DENIED CHECKPOINT_DOWNLOAD_UNAVAILABLE
-CHECKPOINT_MANAGEMENT_UNAVAILABLE CHECKPOINT_MANAGEMENT_UNSUPPORTED CHECKPOINT_NOT_DURABLE CHECKPOINT_RUN_REQUIRED
+CHECKPOINT_MANAGEMENT_UNAVAILABLE CHECKPOINT_MANAGEMENT_UNSUPPORTED CHECKPOINT_NOT_DURABLE CHECKPOINT_TRIAL_REQUIRED
 CHECKPOINT_SIGNER_UNAVAILABLE INVALID_CHECKPOINT_CURSOR INVALID_CHECKPOINT_TTL INVALID_CHECKPOINT_VISIBILITY
 INVALID_EXECUTION_CONFIG INVALID_METRICS_RANGE INVALID_TRAIN_JOB_CURSOR INVALID_TRAIN_JOB_LIST_LIMIT
 INVALID_TRAIN_JOB_METADATA INVALID_TRAIN_JOB_SPEC INVALID_TRAIN_JOB_STATUS LOG_RETENTION_EXPIRED
@@ -329,7 +329,11 @@ def upload_recovery(error: BaseException) -> str:
     if isinstance(upload_id, str) and re.fullmatch(r'upload_[a-f0-9]{32}', upload_id):
         lines.extend([f'  Upload retained: {upload_id}', f'  Inspect with: el data upload get {upload_id}'])
     generated = getattr(error, 'generated_idempotency_key', None)
-    if isinstance(generated, str) and re.fullmatch(r'[a-f0-9]{32}', generated):
+    # A definite refusal (permission, validation, not found) fails the same way again; offer the key only
+    # when the outcome is unknown or retryable.
+    status = getattr(error, 'status_code', None)
+    retryable = not isinstance(status, int) or status >= 500 or status in {408, 429}
+    if retryable and isinstance(generated, str) and re.fullmatch(r'[a-f0-9]{32}', generated):
         lines.append(f'  Retry the same input with --idempotency-key {generated}')
     return '\n'.join(lines)
 

envloop/cli_output.py

@@ -38,7 +38,8 @@ def table(headers: Sequence[object], rows: Sequence[Sequence[object]]) -> str:
 
 
 def timestamp(value: object) -> str:
-    return compact_time(value, local=True)
+    """Table and summary times: UTC to seconds, labelled; --json keeps the original value."""
+    return compact_time(value, utc=True)
 
 
 def next_page(args: argparse.Namespace, cursor: object, program: str) -> str:

envloop/lifecycle_cli.py

@@ -18,7 +18,9 @@ def add_management_commands(settings: "argparse._SubParsersAction[argparse.Argum
         if action == 'wait':
             command.add_argument('--timeout-seconds', type=float, default=600)
     cleanup = settings.add_parser('cleanup', help='Clean an explicit set of Project resource IDs')
-    cleanup.add_argument('--file', type=Path, required=True, help='JSON array of resource kind and ID objects')
+    cleanup.add_argument('--file', type=Path, required=True,
+                         help='JSON array of {"kind": KIND, "id": ID} objects; KIND is job (a Train Job), endpoint, adapter '
+                              'or checkpoint, for example [{"kind": "job", "id": "job_..."}]')
     cleanup.add_argument('--request-id', required=True)
     wait_options(cleanup)
     scopes = settings.add_parser('resource-scope', help='Manage temporary resources with server TTL').add_subparsers(dest='scope_action', required=True)

envloop/terminal.py

@@ -6,7 +6,7 @@ import sys
 import unicodedata
 from contextlib import contextmanager
 from contextvars import ContextVar
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any, TextIO
 
 _NO_COLOR = ContextVar("envloop_cli_no_color", default=False)
@@ -47,15 +47,18 @@ def status_text(text: str) -> str:
     return style(text, code) if code else text
 
 
-def compact_time(value: Any, *, local: bool = False) -> Any:
-    """Render aware times to seconds; preserve unknown or timezone-free values."""
+def compact_time(value: Any, *, utc: bool = False) -> Any:
+    """Render aware times to seconds; preserve unknown or timezone-free values.
+
+    ``utc`` converts to UTC and labels it, so a table read on any machine means the same instant.
+    """
     if not isinstance(value, str):
         return value
     try:
         parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
         if parsed.tzinfo is not None:
-            if local:
-                parsed = parsed.astimezone()
+            if utc:
+                return parsed.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
             return parsed.strftime("%Y-%m-%d %H:%M:%S")
     except ValueError:
         pass

{envloop_cli-1.28.0.dist-info → envloop_cli-1.30.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: envloop-cli
-Version: 1.28.0
+Version: 1.30.0
 Summary: EnvLoop CLI and Python SDK for jobs, training, checkpoints and inference
 Project-URL: Homepage, https://envloop.ai
 Project-URL: Documentation, https://docs.envloop.ai
@@ -249,7 +249,7 @@ The platform starts the published Revision’s `main.sh` / `main.py` using the R
 CLI output uses compact timestamps and highlights statuses and log levels by default on terminals.
 Use `el --no-color job list` or append `--no-color` to a command to disable highlighting, including errors.
 `NO_COLOR=1`, `TERM=dumb`, pipes, and redirected output also disable colors. JSON preserves original values.
-List times use the local timezone; Job logs retain the recorded timezone, with full precision and offsets available through `--json`.
+List and table times are UTC with a `UTC` label; Job logs retain the recorded timezone and mark lines collected only after the Job ended with `(backfilled)`. Full precision, offsets and the `backfilled` field are available through `--json`.
 `el job run live RUN --follow --json` emits complete response frames as NDJSON; Ctrl-C stops reading without stopping the Run.
 
 ## Job-bound decision plugins
@@ -283,7 +283,7 @@ download a complete registered ANS object directory through EnvHub. Datasets req
 authorization the SDK uses GET URLs valid for up to five minutes, verifies file size/SHA-256,
 and installs the directory atomically. Matching platform support is required.
 
-A compatible server and an explicitly granted project Key with `envloop:data:read` are required; writes additionally need `envloop:data:write`. Default and older Keys do not gain these permissions. The current login selects the base URL, workspace and project; there is no `--env` flag. After configuring the Key using `el auth config`:
+A compatible server is required. Data uses the permission of the resource it touches: read (for example `datasets.read`) to query and download, write to publish and upload, delete to retire; a key from `el auth login` follows your project role. The current login selects the base URL, workspace and project; there is no `--env` flag. After configuring the Key using `el auth config`:
 
 ```bash
 el data list --type dataset --json

{envloop_cli-1.28.0.dist-info → envloop_cli-1.30.0.dist-info}/RECORD

@@ -1,55 +1,56 @@
 envloop/__init__.py,sha256=tX06Gh2EmufRr0J_3YKtjDeNrJ30auR3y3BJ3N3FHJY,421
-envloop/_optional.py,sha256=r9vtIbeDSneOQWZZRDdKVOCzkWBpjLbkFkKbGOolqqg,8963
-envloop/auth_cli.py,sha256=Ve7G9AHNsO-zvWNrUgcKiVCTgXKvHYRHjnnhoeTstmE,15448
-envloop/auth_login.py,sha256=PBdgIO_GJ6nMVisWdbGBW1NL2gMV73t1Fao4q3aWvLs,6973
+envloop/_optional.py,sha256=d2Ebq9g0JTKjiq3fuGobG4XjXc6MCogZ5X7uXQDaqak,8981
+envloop/auth_cli.py,sha256=Yjwy1eLyrKfGPOA2vx6q5ZyMyrCNuUh5Xkn7d9-4IvM,15681
+envloop/auth_login.py,sha256=uOqPHqgzi0Y5eDMiZJH-EI_HxY55F9bRr8CoBb8OHfk,7231
 envloop/auth_workspace.py,sha256=g92Dok4eSp6P-Du5qkwzZG4JDeSrdYTXJbn5WCzCFMo,14927
 envloop/cli.py,sha256=Vafivql1JBrlIrfJOD-XAw6AevQKIasmvDHmcazIzqo,15010
-envloop/cli_errors.py,sha256=pMV-V3VSAb_55KmWukkPG5LRNmS11pHxPh1kq_8tqR8,30787
-envloop/cli_output.py,sha256=KtD1TZ947ZGnyi4NUWASZ69xyOwrDykklHGudpmYuA4,5933
+envloop/cli_errors.py,sha256=tPqZFFjW-XMvIq4Vxzbn1D5LbIM6BMHKRkl4nKleeS8,31622
+envloop/cli_output.py,sha256=UkcEMqxpzMUSYaxTQMJR1WQ8nqsoq-piPNyPrCMR5dQ,6025
 envloop/client.py,sha256=TdTUhHwtK0FL6xzIz4moaNdIPlC-TkisPvU4zNPnaTA,3270
 envloop/config.py,sha256=1Wr2lNdNNZzsQDPNGsk-TsnEUvDqOtocy9TgUpmOZO0,22494
 envloop/downloads.py,sha256=ktL-hz9HWPGNuQX_N5RmLyt16qbooArljW9z80XYmTo,3253
 envloop/http.py,sha256=2mu5yIgQDESC0y2LvdE53d7fPfSzT0oXVjlY25qwGkY,16479
-envloop/lifecycle_cli.py,sha256=eKK0mP1yXBmmuEpzafNPRoSQjyluGIxcSYGPfr07Rr0,3179
+envloop/lifecycle_cli.py,sha256=AiiNK7fueIw2Y5HP-OcIKMDUjIXZrUZiFASHfRNkk5Q,3349
 envloop/navigation_resources.py,sha256=3PeZiYtXHXPMwuCLRdw1mUnZDTDJUYthUhsiJkHtI_g,10378
 envloop/profile_secrets.py,sha256=5QpHRV_Gy1MxObR62SX4nNblqk7gWqQZNtzy6wZNV0s,6325
 envloop/resource_cli.py,sha256=JUMpptd3VvCas0D3cdS5p8_iHVCkiaiIqqGLeFdCnws,13371
 envloop/resources.py,sha256=V5nDuM8QgE52V9slSj2ywmhZqwgMKFosm4o5naFaEJo,3025
-envloop/terminal.py,sha256=kuvcOrFUxdgyNO9nEXabZzVJuX9QS0MhWZXhr3mrUWo,2617
+envloop/terminal.py,sha256=AtScg4nUo6wMQO7LNCnypUV9wWB62baBXO7YGpA3jV8,2771
 envloop/utils/__init__.py,sha256=huB3qPQuKNr3JxfH3Ys09YWFtHiDamCHFsBa4epANgQ,25
 envloop/utils/logging.py,sha256=rXN0qyxhfGEq4vWXxjwfaczPPZf_7atnOkkBTgNNRPc,1017
 envloop_data/__init__.py,sha256=nKDGmzFNAQv2mq16YijiI3Q-gDL_smNyZD-AQaqoz7Y,68
 envloop_data/cli.py,sha256=5J_pS5jf65gyaRpE2EV4jDfDUZ1oEsK0iHAmhJlk-oU,9023
-envloop_data/cli_output.py,sha256=oPMBa_CQoMF9a6xnqzxlEUvxNs6g_xIDAKbZC2IhkdY,4271
-envloop_data/client.py,sha256=mw2RlyGOWD1EK0qzq0BiBAGcetxBk7LO23tpCZq9SoQ,12515
-envloop_data/data.py,sha256=OxixzVuNwY21GW_KiCWx9qu_HK3QKWyHsF9Jyd8xjNE,27541
-envloop_data/data_cli.py,sha256=BoJyoCwHyaobxbqtBs8TS0CmsBMexlbEvofMfxjzC9g,13437
-envloop_data/data_publications.py,sha256=CigperPxG5-V8pDJqHc26SerbElrZEgpAqwifEGPxtA,6865
-envloop_data/data_upload.py,sha256=lQdxGbxnO2Zlxe9QWe1-rTyxAyNjc9aSD0BqC4mbiKU,14270
+envloop_data/cli_output.py,sha256=3ZuAXJiXs1wVxIthHMpRgn-VVC4PatSUAWZDCgldrhQ,4414
+envloop_data/client.py,sha256=M1NxvQiiNWq3CByW7AehEOfpkfBrC7ysSDAPkeccCaA,12515
+envloop_data/data.py,sha256=VWmdQbOlXOaQZdPqcTQLk0Di0HeMSLARxAfntwh2RWo,27610
+envloop_data/data_cli.py,sha256=NtJ-Bpw2fnSOCWy3bsgdUMLKUc8z1wrB1NqiOvHMsSw,13623
+envloop_data/data_publications.py,sha256=_Z64X9CCHz1c2AhtcbRIQuROiJ2jTLw6dA3nn1PyHek,6885
+envloop_data/data_upload.py,sha256=b9hf-MwWHtrZW-9U9WyxJxX89SRsEHXCPcSQIy6SVMM,14270
 envloop_data/http.py,sha256=adbMFCUsS1YYanzdCoqM4HIgIOxjgXoHKOkxSwUuvW4,6726
-envloop_data/navigation_resources.py,sha256=TB505mMv1yoG4V-QAohKHXAYCu7njVe3p-luOvpN1DM,12283
+envloop_data/navigation_resources.py,sha256=V3JtSXYqXk1e0ke1nEdBHcZtUHNqHu9mJd4BfN9y4zg,12553
 envloop_data/profile_updates.py,sha256=FB3Huf0AIlqg6CUC0TcrEeWCF5GH1Z6iJN5Wkq8KcYg,3126
 envloop_data/recipes.py,sha256=JH0bvM0LCH_iN4p4ONfTSF53eSHAVLUQNFLueOx07UA,1301
-envloop_data/resource_cli.py,sha256=0539WCdc4lGUd3ZlgKyCxF4Nk6jIX5ck3338nCDodcc,7129
+envloop_data/resource_cli.py,sha256=E1CW0Toe_uw07WEV2B6ZkbUWc4w7Md5Hv7bboUGGxZI,7230
 envloop_data/runner_packages.py,sha256=Xi50hZbdoew9DJ8iYQevMo2jv3qgR3iT50wtV04rFfQ,3424
 envloop_experiment/__init__.py,sha256=nKDGmzFNAQv2mq16YijiI3Q-gDL_smNyZD-AQaqoz7Y,68
-envloop_experiment/cli.py,sha256=0RfMAGanAL_vd2J2kwSVieNeF0FCZfwWYYujFZGJrg0,28655
+envloop_experiment/cli.py,sha256=Tc1irMierk-_6Yl8cyJc_xVPelE21X7bjacK8fDaJlM,31119
 envloop_experiment/cli_output.py,sha256=-FojsqOMIIQuOnfhk2AaqMtwUz5skoWvLeNASm8An6Y,2689
 envloop_experiment/client.py,sha256=VKKqI9IDazxaN7-coP48DvXcz6SqjZ8ScM4O6plBNWI,25122
 envloop_experiment/decision.py,sha256=HJTj-jSJJ5kcxQQzFXwrA9IICWXA6zSNBFL9EbbrxqI,918
 envloop_experiment/http.py,sha256=A_PHWVr7PV4eiP30lXmOITiljXf6GEIYGkJlr1KFz-Q,6110
 envloop_experiment/inference.py,sha256=74MZDs0lqqqNwgdvj58rs-D3emDj4iHv1W-copc5PYA,2134
-envloop_experiment/job_cost.py,sha256=KUaFTn0mg1yF8EvqQxlm131G_4YpsnCe1dM_QT4tHjg,1920
+envloop_experiment/job_cost.py,sha256=gZB69-pdsJM4wManw44AIS9T3ZtsxxQTqrJs-cHjwJU,2214
 envloop_experiment/job_logs.py,sha256=RLipbj89e5hQdBeXtszsxSYYw7By1hscwSTGFQzQ3Qw,1340
-envloop_experiment/job_spec_cli.py,sha256=0IaQv_nR93WVYYx3Lba-HbqMN-WCLrzseChEKcXdkxA,7981
+envloop_experiment/job_spec_cli.py,sha256=qyt0hZMAVqOCoRSzEuO2mQ8f8ro5cLiY5eRdAWGQbOM,9753
 envloop_experiment/navigation_resources.py,sha256=xoI4VFmd0dzviKvzndwKAoWdfbaL_f50cnXRxPkfoo4,1832
 envloop_experiment/resource_cli.py,sha256=MCFWHl4iCNe1UiGyHcvMM67LOHQ7MZl3joFtftQwqLk,2083
 envloop_experiment/resources.py,sha256=4guXzssv7XhYkn8ESH-79DIMWUyKDIg70uOa-KoNvp0,7236
 envloop_experiment/runtime_params.py,sha256=ITF6hDuhfdChnWo3e8NW27WxEoNoCuOTww-Hz60zqQU,3608
 envloop_experiment/sandbox.py,sha256=sTpAWbcs2jAPfb7gILK4MTJSmcpSeZG3anFkLA5TgdQ,1274
-envloop_experiment/train.py,sha256=fb6Sqdyo15ynq-vKeUbnyRTfkG5anVu3Ewt152g0fK8,5110
-envloop_experiment/train_log_cli.py,sha256=quOgnUqjE647YhsO44C_zp778ndarmJ2Wr1ANCL45Ck,6368
-envloop_experiment/train_progress.py,sha256=Cln8NPWfmSH9Mnlml-78dOXqwZTqWVeJ8ArDWFAQv-A,2536
+envloop_experiment/train.py,sha256=S0nkTjfbXJnDL1uxPeOIcfHF3Zxc3jqO6O2_UcNjcr0,5472
+envloop_experiment/train_log_cli.py,sha256=jCu7c0DGzy0La8tigJVDjuQHROaw6kfclU64QYsRVj0,6622
+envloop_experiment/train_metrics_cli.py,sha256=AXq5UPf_Xa4RCxAwZNvz8VZKghN1k3dhxbAXXxMmLlY,6522
+envloop_experiment/train_progress.py,sha256=XrF6g1XNtGReuIfFdfXTvD4XwvS-bDcFZNHzTCCfYa0,2546
 envloop_experiment/train_runner_cli.py,sha256=OiHv7Dp2VPoQVmFR0vgJoAd5Ni0uQvtCyNf5Lk4AFfc,3154
 envloop_experiment/training/__init__.py,sha256=IEQWbCHe-zZ2e7JQxOrFOdYlSQxMfOceCZUf_KeszBk,221
 envloop_rsi_loop/__init__.py,sha256=nKDGmzFNAQv2mq16YijiI3Q-gDL_smNyZD-AQaqoz7Y,68
@@ -57,7 +58,7 @@ envloop_rsi_loop/agent_runs.py,sha256=GrXSfnQ8MchA9i8UI3LWJiTninpI0PeTm0hgz2TJ0N
 envloop_rsi_loop/cli.py,sha256=Kqearg20Mvfyj62r2mibVdWEMo1NHjthgvS-Tl7SC-A,3047
 envloop_rsi_loop/cli_output.py,sha256=GxM4UiL4NzzSyjRrikai6ROW-1WPjFtwrIfpnE8GZ4U,3173
 envloop_rsi_loop/rsi_cli.py,sha256=e9XHeIPwMz1dZ6NhK3UIETCdy7LbIWgFosF1FnKVUQk,2580
-envloop_cli-1.28.0.dist-info/METADATA,sha256=ouQWXHdlfU-i6Hgn-D9jnh5nmwkEl7jw5HlDaPt4nVY,15656
-envloop_cli-1.28.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
-envloop_cli-1.28.0.dist-info/entry_points.txt,sha256=8aXOpgtVk4GndhChA4XNecShkb1w0xGHBHrKla78ofI,67
-envloop_cli-1.28.0.dist-info/RECORD,,
+envloop_cli-1.30.0.dist-info/METADATA,sha256=ku-cMRnCnhzCW4sa4kW-wFyyhH__GtXzdUI6qTEHe7A,15810
+envloop_cli-1.30.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+envloop_cli-1.30.0.dist-info/entry_points.txt,sha256=8aXOpgtVk4GndhChA4XNecShkb1w0xGHBHrKla78ofI,67
+envloop_cli-1.30.0.dist-info/RECORD,,

envloop_data/cli_output.py

@@ -38,9 +38,10 @@ def list_layout(items: list[dict[str, Any]], args: argparse.Namespace) -> tuple[
         render = dataset_row
         empty = 'No datasets found.'
     elif args.group == 'checkpoint':
-        headers = ('CHECKPOINT ID', 'TYPE', 'MODEL', 'JOB ID', 'URI')
-        render = lambda item: (item.get('checkpoint_id'), item.get('checkpoint_type'), item.get('base_model'),
-                               item.get('job_id'), item.get('uri'))
+        # The checkpoint ID is the resource_id (cp_…); the save name (adapter-final) repeats across Jobs.
+        headers = ('CHECKPOINT ID', 'NAME', 'TYPE', 'MODEL', 'JOB ID', 'URI')
+        render = lambda item: (item.get('resource_id'), item.get('checkpoint_id'), item.get('checkpoint_type'),
+                               item.get('base_model'), item.get('job_id'), item.get('uri'))
         empty = 'No checkpoints found.'
     elif args.group == "profile" and args.name is None:
         headers = ("NAME", "VERSIONS", "DEFAULT", "UPDATED AT")
@@ -64,7 +65,7 @@ def pagination(command: list[str], args: argparse.Namespace, cursor: object) ->
     command.extend(['--limit', str(args.limit), '--cursor=' + str(cursor)])
     fields = {'dataset': ('type', 'query'),
               'data': ('type', 'ref', 'job_id', 'trial_id'),
-              'checkpoint': ('job_id', 'run_id'), 'profile': ('name',)}
+              'checkpoint': ('job_id', 'trial_id'), 'profile': ('name',)}
     for field in fields.get(args.group, ()):
         if getattr(args, field, None) is not None:
             if field == 'query':

envloop_data/client.py

@@ -194,7 +194,7 @@ class Runners:
                  source_ref_kind: str = 'branch', dry_run: bool = False):
         """Publish a Runner package directory as the immutable revision NAME@REVISION.
 
-        This is `client.data.create(kind='runner', ...)` with the native manifest built
+        This is `client.data.create(type='runner', ...)` with the native manifest built
         from `directory` (runner.toml plus its main.py or main.sh entrypoint): the
         platform stores the bytes, derives the package and index SHA-256, creates the
         Runner asset on first use and registers the revision. `revision` is the full
@@ -219,7 +219,7 @@ class Runners:
             raise RemoteError('RUNNER_SOURCE_REF_INVALID')
         name, manifest, files, executables = runner_package(directory, name=name, executables=executables)
         ref = f'envloop://runners/{name}@{revision}'
-        publication = Data(self._server).create(kind='runner', ref=ref, manifest=manifest, files=files,
+        publication = Data(self._server).create(type='runner', ref=ref, manifest=manifest, files=files,
                                                 executables=executables, dry_run=dry_run)
         if dry_run:
             return publication

envloop_data/data.py

@@ -114,10 +114,10 @@ class Data:
             raise ValueError('limit must be between 1 and 100')
         return path + '?' + urlencode({key: value for key, value in params.items() if value is not None})
 
-    def list(self, *, kind: Literal['dataset', 'artifact', 'checkpoint', 'runner', 'recipe'], ref: str | None = None, job_id: str | None = None, trial_id: str | None = None, limit: int = 25, cursor: str | None = None) -> dict[str, Any]:
-        if kind not in ('dataset', 'artifact', 'checkpoint', 'runner', 'recipe') or (kind != 'artifact' and (job_id or trial_id)):
-            raise ValueError('select a Data kind and appropriate owner filters')
-        return self.transport.request('GET', self._query(self._path(), kind=kind, ref=ref, job_id=job_id, trial_id=trial_id, limit=limit, cursor=cursor))
+    def list(self, *, type: Literal['dataset', 'artifact', 'checkpoint', 'runner', 'recipe'], ref: str | None = None, job_id: str | None = None, trial_id: str | None = None, limit: int = 25, cursor: str | None = None) -> dict[str, Any]:
+        if type not in ('dataset', 'artifact', 'checkpoint', 'runner', 'recipe') or (type != 'artifact' and (job_id or trial_id)):
+            raise ValueError('select a Data type and appropriate owner filters')
+        return self.transport.request('GET', self._query(self._path(), type=type, ref=ref, job_id=job_id, trial_id=trial_id, limit=limit, cursor=cursor))
 
     def get(self, data_id: str) -> dict[str, Any]:
         return self.transport.request('GET', self._path(data_id))
@@ -131,16 +131,16 @@ class Data:
         from envhub.ans.proto import ANSError, DatasetRef, InvalidManifest, parse_uri
 
         reference = parse_uri(uri)
-        kinds = {'datasets':'dataset', 'artifacts':'artifact', 'model':'checkpoint',
+        data_types = {'datasets':'dataset', 'artifacts':'artifact', 'model':'checkpoint',
                  'runners':'runner', 'recipes':'recipe'}
-        if reference.kind not in kinds or reference.uri != uri:
+        if reference.kind not in data_types or reference.uri != uri:
             raise ValueError('select a complete resource ANS URI')
         if isinstance(reference, DatasetRef) and (not isinstance(split, str) or not split):
             raise ValueError('Dataset download requires a split')
         if not isinstance(reference, DatasetRef) and split is not None:
             raise ValueError('split is only supported for Dataset')
         endpoint = self._path() + '/download'
-        parameters = {'kind': kinds[reference.kind], 'ref': uri, 'split': split}
+        parameters = {'type': data_types[reference.kind], 'ref': uri, 'split': split}
         plan = self.transport.request('GET', self._query(endpoint, **parameters))
         from envhub.ans.client import validate_download_plan
         try:
@@ -179,36 +179,36 @@ class Data:
         return {'ref': uri, 'split': split, 'content_digest': plan['content_digest'],
                 'directory': str(target), 'verified': True}
 
-    def create(self, *, kind: str, ref: str | None = None, manifest: dict[str, Any] | None = None, files: dict[str, Any] | None = None, model: str | None = None, revision: str | None = None,
+    def create(self, *, type: str, ref: str | None = None, manifest: dict[str, Any] | None = None, files: dict[str, Any] | None = None, model: str | None = None, revision: str | None = None,
                executables: Sequence[str] = (), dry_run: bool = False, idempotency_key: str | None = None):
         """Register native content or frozen public-HF metadata in this project."""
         from envloop_data.data_publications import hf_source
 
-        source = hf_source(kind, model, revision, ref=ref, manifest=manifest, files=files,
+        source = hf_source(type, model, revision, ref=ref, manifest=manifest, files=files,
                            executables=executables, dry_run=dry_run)
         if source is not None:
             result = self.transport.request('POST', self._path(), source)
-            return result if dry_run else self._native_result(result, kind)
-        return self._publish(kind, ref, manifest, files, dry_run,
+            return result if dry_run else self._native_result(result, type)
+        return self._publish(type, ref, manifest, files, dry_run,
                              executables=executables, idempotency_key=idempotency_key)
 
     def update(self, data_id: str, *, ref: str | None = None, manifest: dict[str, Any] | None = None, files: dict[str, Any] | None = None, model: str | None = None, revision: str | None = None,
-               executables: Sequence[str] = (), kind: str | None = None, dry_run: bool = False, idempotency_key: str | None = None):
+               executables: Sequence[str] = (), type: str | None = None, dry_run: bool = False, idempotency_key: str | None = None):
         """Publish a new revision of the same asset, preserving its previous revision."""
         from envloop_data.data_publications import hf_source
 
-        source = hf_source('checkpoint' if kind is None else kind, model, revision, ref=ref, manifest=manifest, files=files,
+        source = hf_source('checkpoint' if type is None else type, model, revision, ref=ref, manifest=manifest, files=files,
                            executables=executables, dry_run=dry_run)
         resource = self.get(data_id)
-        if kind is not None and kind != resource['kind']:
-            raise ValueError('update must preserve the publication kind')
+        if type is not None and type != resource['type']:
+            raise ValueError('update must preserve the publication type')
         if source is not None:
-            if (resource['kind'] != 'checkpoint' or resource.get('metadata_only') is not True
+            if (resource['type'] != 'checkpoint' or resource.get('metadata_only') is not True
                     or resource.get('name') != model or not resource.get('model_uri')):
                 raise ValueError('HF update must preserve the native model identity')
             result = self.transport.request('POST', self._path(data_id) + '/revisions', source)
-            return result if dry_run else self._native_result(result, resource['kind'])
-        return self._publish(resource['kind'], ref, manifest, files, dry_run,
+            return result if dry_run else self._native_result(result, resource['type'])
+        return self._publish(resource['type'], ref, manifest, files, dry_run,
                              parent_id=data_id, executables=executables, idempotency_key=idempotency_key)
 
     def delete(self, data_id: str, *, dry_run: bool = False):
@@ -217,9 +217,9 @@ class Data:
         return self.transport.request('DELETE', self._path(data_id) + ('?dry_run=true' if dry_run else ''))
 
     @staticmethod
-    def _native_result(result: Any, kind: str):
+    def _native_result(result: Any, data_type: str):
         resource = result.get('resource', result) if isinstance(result, dict) else None
-        if (isinstance(resource, dict) and resource.get('kind') == kind
+        if (isinstance(resource, dict) and resource.get('type') == data_type
                 and resource.get('native_registered') is True and resource.get('native_ready') is True
                 and isinstance(resource.get('data_id', resource.get('id')), str)
                 and re.fullmatch(r'ans_[A-Za-z0-9_-]+', resource.get('data_id', resource.get('id')))):
@@ -231,37 +231,37 @@ class Data:
                 error.staging_id = staging
         raise error
 
-    def _publish(self, kind: str, ref: str | None, manifest: dict[str, Any] | None, files: dict[str, Any] | None, dry_run: bool, *, parent_id: str | None = None, executables: Sequence[str] = (), idempotency_key: str | None = None):
+    def _publish(self, data_type: str, ref: str | None, manifest: dict[str, Any] | None, files: dict[str, Any] | None, dry_run: bool, *, parent_id: str | None = None, executables: Sequence[str] = (), idempotency_key: str | None = None):
         from envloop_data.data_publications import (
             INLINE_BYTES,
-            KINDS,
+            TYPES,
             executable_files,
             prepare,
         )
 
-        if kind not in KINDS or not isinstance(ref, str) or not ref or type(dry_run) is not bool:
-            raise ValueError('select a publication kind, immutable ANS ref and boolean dry_run')
-        executables = executable_files(kind, manifest, executables)
+        if data_type not in TYPES or not isinstance(ref, str) or not ref or type(dry_run) is not bool:
+            raise ValueError('select a publication type, immutable ANS ref and boolean dry_run')
+        executables = executable_files(data_type, manifest, executables)
         with prepare(manifest, files) as (manifest, entries, payload, total, digest):
             if total <= INLINE_BYTES and len(entries) <= 100:
                 encoded = {entry['path']: base64.b64encode(payload.read(cast(int, entry['size']))).decode() for entry in entries}
-                body: dict[str, Any] = {'kind': kind, 'ref': ref, 'manifest': manifest, 'files': encoded, 'dry_run': dry_run}
+                body: dict[str, Any] = {'type': data_type, 'ref': ref, 'manifest': manifest, 'files': encoded, 'dry_run': dry_run}
                 if executables:
                     body['executables'] = executables
                 path = self._path(parent_id) + '/revisions' if parent_id else self._path()
                 result = self.transport.request('POST', path, body)
-                return result if dry_run else self._native_result(result, kind)
+                return result if dry_run else self._native_result(result, data_type)
             request_key = uuid4().hex if idempotency_key is None else idempotency_key
             identifier = None
             try:
-                upload = self.create_upload(kind=kind, ref=ref, manifest=manifest, payload_sha256=digest,
+                upload = self.create_upload(type=data_type, ref=ref, manifest=manifest, payload_sha256=digest,
                                             idempotency_key=request_key, parent_id=parent_id,
                                             executables=executables, dry_run=dry_run)
                 if dry_run:
                     return upload
                 identifier = upload.get('upload_id')
                 if upload.get('state') == 'committed':
-                    return self._native_result(upload, kind)
+                    return self._native_result(upload, data_type)
                 identifier = upload['upload_id']
                 part_bytes = upload['limits']['part_bytes']
                 if type(part_bytes) is not int or not 0 < part_bytes <= INLINE_BYTES:
@@ -278,7 +278,7 @@ class Data:
                         self.upload_part(identifier, number, chunk)
                 if existing:
                     raise RemoteError('DATA_UPLOAD_CONFLICT')
-                return self._native_result(self.complete_upload(identifier), kind)
+                return self._native_result(self.complete_upload(identifier), data_type)
             except BaseException as error:
                 # Keep server state recoverable; do not silently abort another
                 # process's resumable upload or lose its reservation identifier.
@@ -289,16 +289,16 @@ class Data:
                     cast(Any, error).upload_id = identifier
                 raise
 
-    def create_upload(self, *, kind: str, ref: str | None, manifest: dict[str, Any] | None, payload_sha256: str, idempotency_key: str, parent_id: str | None = None,
+    def create_upload(self, *, type: str, ref: str | None, manifest: dict[str, Any] | None, payload_sha256: str, idempotency_key: str, parent_id: str | None = None,
                       executables: Sequence[str] = (), dry_run: bool = False):
-        from envloop_data.data_publications import KINDS, executable_files
+        from envloop_data.data_publications import TYPES, executable_files
 
-        if (kind not in KINDS or not isinstance(ref, str) or not ref or type(dry_run) is not bool
+        if (type not in TYPES or not isinstance(ref, str) or not ref or not isinstance(dry_run, bool)
                 or not isinstance(payload_sha256, str) or not re.fullmatch(r'[a-f0-9]{64}', payload_sha256)
                 or not isinstance(idempotency_key, str) or not re.fullmatch(r'[A-Za-z0-9_.:-]{1,128}', idempotency_key)):
             raise ValueError('invalid upload metadata or idempotency key')
-        executables = executable_files(kind, manifest, executables)
-        body: dict[str, Any] = dict(kind=kind, ref=ref, manifest=manifest, payload_sha256=payload_sha256, dry_run=dry_run)
+        executables = executable_files(type, manifest, executables)
+        body: dict[str, Any] = dict(type=type, ref=ref, manifest=manifest, payload_sha256=payload_sha256, dry_run=dry_run)
         if executables:
             body['executables'] = executables
         if parent_id is not None:

envloop_data/data_cli.py

@@ -10,7 +10,7 @@ from typing import Any
 
 from envloop_data.data_publications import (
     INLINE_BYTES,
-    KINDS,
+    TYPES,
     open_file,
     prepare,
     storage_files,
@@ -20,7 +20,7 @@ from envloop_data.data_publications import (
 def add_commands(groups: "argparse._SubParsersAction[argparse.ArgumentParser]", listing: Callable[[Any], argparse.ArgumentParser]):
     data = groups.add_parser('data', help='Manage Project ANS resources and verified downloads').add_subparsers(dest='action', required=True)
     command = listing(data)
-    command.add_argument('--type', required=True, choices=[*KINDS, 'artifact'])
+    command.add_argument('--type', required=True, choices=[*TYPES, 'artifact'])
     for option in ('ref', 'job-id', 'trial-id'):
         command.add_argument('--' + option)
     for action in ('get', 'files'):
@@ -33,7 +33,7 @@ def add_commands(groups: "argparse._SubParsersAction[argparse.ArgumentParser]",
             command.set_defaults(_list_view=True)
     for action in ('create', 'update'):
         command = data.add_parser(action, help='Register native content or HF metadata' if action == 'create' else 'Register a new immutable revision')
-        command.add_argument('--type', required=action == 'create', choices=KINDS)
+        command.add_argument('--type', required=action == 'create', choices=TYPES)
         if action == 'update':
             command.add_argument('data_id', metavar='DATA_ID')
         publication_arguments(command, source=True)
@@ -51,7 +51,7 @@ def add_commands(groups: "argparse._SubParsersAction[argparse.ArgumentParser]",
     command.add_argument('--json', action='store_true')
     uploads = data.add_parser('upload', help='Explicit resumable upload lifecycle').add_subparsers(dest='upload_action', required=True)
     command = uploads.add_parser('create', help='Verify local input and reserve a multipart upload')
-    command.add_argument('--type', choices=KINDS, required=True)
+    command.add_argument('--type', choices=TYPES, required=True)
     publication_arguments(command)
     command.add_argument('--idempotency-key', required=True)
     command.add_argument('--parent-id', help='Existing publication when creating a new revision')
@@ -83,15 +83,19 @@ def add_commands(groups: "argparse._SubParsersAction[argparse.ArgumentParser]",
     command.add_argument('--json', action='store_true')
 
 
+MANIFEST_HELP = ('Native JSON content manifest; a record Dataset source.repository is https://github.com/OWNER/REPO '
+                 'or https://huggingface.co/datasets/ORG/NAME, with source.commit the full commit')
+
+
 def publication_arguments(command: argparse.ArgumentParser, *, source: bool = False):
     command.add_argument('--ref', required=not source, help='Exact immutable ANS URI')
     if source:
         inputs = command.add_mutually_exclusive_group(required=True)
-        inputs.add_argument('--manifest', type=Path, help='Native JSON content manifest')
+        inputs.add_argument('--manifest', type=Path, help=MANIFEST_HELP)
         inputs.add_argument('--model', help='Public Hugging Face model namespace/name; metadata only')
         command.add_argument('--revision', help='Explicit HF source ref; the server freezes its full commit')
     else:
-        command.add_argument('--manifest', type=Path, required=True, help='Native JSON content manifest')
+        command.add_argument('--manifest', type=Path, required=True, help=MANIFEST_HELP)
     command.add_argument('--directory', type=Path, required=not source, help='Directory containing exactly the declared files')
     command.add_argument('--executable', action='append', dest='executables', default=[],
                          help='Declared Runner file that must be executable; repeat for each path')
@@ -128,7 +132,7 @@ def publication_input(args: argparse.Namespace):
 
 def execute(data: Any, args: argparse.Namespace):
     if args.action == 'list':
-        return data.list(kind=args.type, ref=args.ref, job_id=args.job_id, trial_id=args.trial_id, limit=args.limit, cursor=args.cursor)
+        return data.list(type=args.type, ref=args.ref, job_id=args.job_id, trial_id=args.trial_id, limit=args.limit, cursor=args.cursor)
     if args.action == 'get':
         return {'resource': data.get(args.data_id), 'files': data.files(args.data_id, limit=args.limit, cursor=args.cursor)}
     if args.action == 'files':
@@ -148,8 +152,8 @@ def execute(data: Any, args: argparse.Namespace):
             manifest, files = publication_input(args)
             options.update(ref=args.ref, manifest=manifest, files=files, executables=args.executables)
         if args.action == 'create':
-            return data.create(kind=args.type, **options)
-        return data.update(args.data_id, kind=args.type, **options)
+            return data.create(type=args.type, **options)
+        return data.update(args.data_id, type=args.type, **options)
     if args.action == 'register':
         return register(data, args)
     if args.action == 'registration':
@@ -160,7 +164,7 @@ def execute(data: Any, args: argparse.Namespace):
         if args.upload_action == 'create':
             manifest, files = publication_input(args)
             with prepare(manifest, files) as (manifest, _, _, _, digest):
-                return data.create_upload(kind=args.type, ref=args.ref, manifest=manifest, payload_sha256=digest,
+                return data.create_upload(type=args.type, ref=args.ref, manifest=manifest, payload_sha256=digest,
                                           idempotency_key=args.idempotency_key, parent_id=args.parent_id,
                                           executables=args.executables, dry_run=args.dry_run)
         if args.upload_action == 'part':

envloop_data/data_publications.py

@@ -11,7 +11,7 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import Any
 
-KINDS = ('dataset', 'checkpoint', 'runner', 'recipe')
+TYPES = ('dataset', 'checkpoint', 'runner', 'recipe')
 INLINE_BYTES = 8 * 1024 * 1024
 MAX_FILE = 512 * 1024 * 1024
 MAX_TOTAL = 1024 * 1024 * 1024
@@ -50,23 +50,23 @@ def storage_files(manifest: dict[str, Any]) -> list[dict[str, Any]]:
     return sorted(projected, key=lambda item: item['path'])
 
 
-def executable_files(kind: str, manifest: Any, executables: Sequence[str]) -> list[str]:
+def executable_files(data_type: str, manifest: Any, executables: Sequence[str]) -> list[str]:
     """Explicit Runner inventory; do not modify its immutable native manifest."""
     if not isinstance(executables, (tuple, list)):
         raise ValueError('executables must be a sequence of declared Runner paths')
     entries = storage_files(manifest)
     paths = {entry['path'] for entry in entries}
     if (any(not isinstance(path, str) or path not in paths for path in executables)
-            or len(set(executables)) != len(executables) or executables and kind != 'runner'):
+            or len(set(executables)) != len(executables) or executables and data_type != 'runner'):
         raise ValueError('executables must select distinct declared Runner files')
     return sorted(executables)
 
 
-def hf_source(kind: str, model: str | None, revision: str | None, *, ref: Any, manifest: Any, files: Any, executables: Any,
+def hf_source(data_type: str, model: str | None, revision: str | None, *, ref: Any, manifest: Any, files: Any, executables: Any,
               dry_run: bool):
     if model is None and revision is None:
         return None
-    if (kind != 'checkpoint' or ref is not None or manifest is not None or files is not None
+    if (data_type != 'checkpoint' or ref is not None or manifest is not None or files is not None
             or executables or type(dry_run) is not bool
             or not isinstance(model, str) or len(model) > 193
             or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._-]{0,95}/[A-Za-z0-9][A-Za-z0-9._-]{0,95}', model)
@@ -74,7 +74,7 @@ def hf_source(kind: str, model: str | None, revision: str | None, *, ref: Any, m
             or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._/-]*', revision) or '..' in revision
             or any(part in ('', '.') for part in revision.split('/'))):
         raise ValueError('HF metadata requires checkpoint model and explicit revision, without content inputs')
-    return {'kind': 'checkpoint', 'source': {'type': 'hf', 'model': model, 'revision': revision}, 'dry_run': dry_run}
+    return {'type': 'checkpoint', 'source': {'type': 'hf', 'model': model, 'revision': revision}, 'dry_run': dry_run}
 
 
 @contextmanager

envloop_data/data_upload.py

@@ -234,7 +234,7 @@ class Registrations:
             if identity.get('name') != dataset or identity.get('version') != version:
                 raise _invalid(f'dataset.toml declares {identity.get("name")}@{identity.get("version")}, not {dataset}@{version}')
             size, sha256 = _digest(bundle)
-            body = {'kind': 'dataset', 'ref': f'envloop://datasets/{dataset}@{version}', 'payload_sha256': sha256,
+            body = {'type': 'dataset', 'ref': f'envloop://datasets/{dataset}@{version}', 'payload_sha256': sha256,
                     'manifest': {'schema': 'envhub.artifact/v1', 'kind': 'file', 'metadata': BUNDLE,
                                  'files': [{'path': name, 'size': size, 'sha256': sha256}]}}
             workspace, project = self.data._scope()

envloop_data/navigation_resources.py

@@ -62,7 +62,7 @@ class Datasets:
 
 
 def _checkpoint_matches(checkpoint: str, item: dict[str, Any]) -> bool:
-    if checkpoint in {item.get('checkpoint_id'), item.get('uri'), item.get('model_uri')}:
+    if checkpoint in {item.get('resource_id'), item.get('checkpoint_id'), item.get('uri'), item.get('model_uri')}:
         return True
     parsed = urlsplit(checkpoint)
     if parsed.scheme not in {'envloop', 'tinker'} or parsed.query or parsed.fragment:
@@ -133,13 +133,13 @@ class Checkpoints:
     def delete(self, checkpoint_id: str) -> Any:
         return self.transport.request('DELETE', f"/v1/checkpoints/{quote(checkpoint_id, safe='')}")
 
-    def download(self, checkpoint: str, directory: str | Path, *, job_id: str | None = None, run_id: str | None = None) -> dict[str, Any]:
+    def download(self, checkpoint: str, directory: str | Path, *, job_id: str | None = None, trial_id: str | None = None) -> dict[str, Any]:
         from pathlib import Path
 
         directory = Path(directory)
         matches, cursor, seen = cast(list[dict[str, Any]], []), None, set()
         while True:
-            page = self.list(job_id=job_id, run_id=run_id, cursor=cursor, limit=100)
+            page = self.list(job_id=job_id, trial_id=trial_id, cursor=cursor, limit=100)
             for item in page['items']:
                 if _checkpoint_matches(checkpoint, item):
                     matches.append(item)
@@ -166,14 +166,16 @@ class Checkpoints:
         if urlsplit(item.get('uri', '')).scheme == 'mock' and item.get('validation_mode') == 'mock':
             return self._download_archive(item, files, directory)
         transport = self.transport
+        # The checkpoint ID (resource_id) and a uri are both accepted; sign with the reference the caller gave.
+        reference = {'resource_id': checkpoint} if checkpoint == item.get('resource_id') else {'uri': checkpoint}
 
         class Content:
             urls: dict[str, Any] | None = None
 
             def refresh(self) -> None:
                 # Keep the original authorized identity and file hashes across refreshes.
-                signed = transport.request('GET', query('/v1/checkpoints/download', uri=checkpoint,
-                                                        job_id=item['job_id'], run_id=run_id))
+                signed = transport.request('GET', query('/v1/checkpoints/download', **reference,
+                                                        job_id=item['job_id'], trial_id=item.get('trial_id')))
                 urls = signed.get('urls', {})
                 if (set(names) != set(urls)
                         or signed.get('checkpoint_id', item['checkpoint_id']) != item['checkpoint_id']):

envloop_data/resource_cli.py

@@ -33,8 +33,8 @@ def add_resource_commands(groups: "argparse._SubParsersAction[argparse.ArgumentP
         'immutable Runner revision NAME@REVISION. The platform stores the bytes, computes the package and index '
         'SHA-256, creates the Runner on first use and registers the revision; identical retries are idempotent and '
         'changed content for an existing revision is refused. This is el data create --type runner with the native '
-        'manifest built for you; use that command to publish an existing manifest. The key needs envloop:data:write '
-        'and runners.write, and publish permission on a Runner owned by another Project.')
+        'manifest built for you; use that command to publish an existing manifest. The key needs runners.write '
+        '(el auth login issues it to a Developer or Admin), and publish permission on a Runner owned by another Project.')
     register.add_argument('directory', metavar='DIRECTORY', type=Path, help='Runner package directory; every file in it is published')
     register.add_argument('--revision', required=True, help='Full 40- or 64-character source commit, for example $(git rev-parse HEAD)')
     register.add_argument('--name', help='NAMESPACE/NAME; must equal [runner] name in runner.toml (default: that name)')
@@ -47,12 +47,12 @@ def add_resource_commands(groups: "argparse._SubParsersAction[argparse.ArgumentP
     checkpoints = groups.add_parser('checkpoint', help='List and download saved training Checkpoints').add_subparsers(dest='action', required=True)
     command = listing(checkpoints)
     command.add_argument('--job-id', help='Only Checkpoints of this Train Job')
-    command.add_argument('--run-id', help='Only Checkpoints of this training run label')
+    command.add_argument('--trial-id', help='Only Checkpoints of this Trial')
     download = checkpoints.add_parser('download', help='Download files and verify their sizes and SHA-256 hashes')
-    download.add_argument('checkpoint', metavar='CHECKPOINT', help='Checkpoint ID or uri from `checkpoint list`')
+    download.add_argument('checkpoint', metavar='CHECKPOINT', help='Checkpoint ID (cp_…) or uri from `checkpoint list`')
     download.add_argument('directory', metavar='DIRECTORY', type=Path)
     download.add_argument('--job-id')
-    download.add_argument('--run-id')
+    download.add_argument('--trial-id')
     from envloop.lifecycle_cli import wait_options
     delete = checkpoints.add_parser('delete', help='Remove an unreferenced Checkpoint and stored files')
     delete.add_argument('identifier', metavar='CHECKPOINT_ID')
@@ -83,14 +83,15 @@ def execute(args: argparse.Namespace, client: Any):
             result = client.checkpoints.delete(args.identifier)
             return client.operations.wait(result['operation_id'], timeout=args.timeout_seconds) if args.wait else result
         if action == 'download':
-            return client.checkpoints.download(args.checkpoint, args.directory, job_id=args.job_id, run_id=args.run_id)
-        return client.checkpoints.list(job_id=args.job_id, run_id=args.run_id,
+            return client.checkpoints.download(args.checkpoint, args.directory, job_id=args.job_id, trial_id=args.trial_id)
+        return client.checkpoints.list(job_id=args.job_id, trial_id=args.trial_id,
                                        cursor=args.cursor, limit=args.limit)
 
 
-RUNNER_WRITE_HINT = ('Registering a Runner revision needs a project key with Data write (envloop:data:write) and '
-                     'Runners write (runners.write), and publish or admin permission when another project owns the '
-                     'Runner. Existing keys keep their original capabilities; issue a new key with these permissions.')
+RUNNER_WRITE_HINT = ('Registering a Runner revision needs a project key with Runners write (runners.write), and '
+                     'publish or admin permission when another project owns the Runner. Existing keys keep their '
+                     'original capabilities; run el auth login without --read-only (Developer or Admin role) to issue '
+                     'a new key with it.')
 
 
 def register_runner(client: Any, args: argparse.Namespace):
@@ -102,7 +103,7 @@ def register_runner(client: Any, args: argparse.Namespace):
                                          executables=args.executables, source_ref=args.source_ref,
                                          source_ref_kind=args.source_ref_kind, dry_run=args.dry_run)
     except RemoteError as error:
-        if error.code == 'ACCESS_DENIED' and not error.hint:
+        if error.code in {'ACCESS_DENIED', 'DATA_ACCESS_REQUIRED'} and not error.hint:
             error.hint = RUNNER_WRITE_HINT
         raise
     if not args.dry_run:

envloop_experiment/cli.py

@@ -5,6 +5,9 @@ import sys
 from pathlib import Path
 from typing import Any
 
+# Single-resource reads and actions print the response as JSON already; scripts may still pass --json.
+JSON_DEFAULT_HELP = "Output the complete response as JSON (the default; accepted for consistency with list commands)"
+
 
 def dataset_reference(value: str):
     name, separator, version = value.rpartition("@")
@@ -125,9 +128,11 @@ def add_commands(groups: "argparse._SubParsersAction[argparse.ArgumentParser]"):
         help="Dataset name; optional author version (legacy positional form)",
     )
     job_submit.add_argument("--dataset", dest="dataset_option", type=dataset_reference, metavar="NAME[@VERSION]",
-                            help="Dataset name; default selection uses the platform's pinned snapshot")
+                            help="Agent: Dataset name; default selection uses the platform's pinned snapshot. "
+                                 "Train recipe (--spec): record Dataset NAMESPACE/NAME@VERSION read in place of records")
     job_submit.add_argument("--config", help="Agent: Dataset subset; Train recipe: named preset; omitted preserves spec or server default")
-    job_submit.add_argument("--split", help="one complete split name; omitted selects all splits")
+    job_submit.add_argument("--split", help="Agent: one complete split name, omitted selects all splits; "
+                                            "Train recipe: the record Dataset split to train on (required with --dataset)")
     job_submit.add_argument("--revision", help="Git branch/tag/commit; must match the platform's pinned snapshot")
     runner_arguments(job_submit)
     job_submit.add_argument("--attempts", type=int)
@@ -141,8 +146,8 @@ def add_commands(groups: "argparse._SubParsersAction[argparse.ArgumentParser]"):
     job_submit.add_argument("--timeout-seconds", type=wait_seconds,
                             help="Agent/Sandbox or Train Runner execution timeout (whole seconds); Train recipe --wait timeout (default: 600)")
     job_submit.add_argument("--max-cost-usd", type=max_cost_usd, metavar="USD",
-                            help="Agent/Sandbox: Job spend cap in USD (model calls plus Sandbox time); the Job stops "
-                                 "with error BUDGET_EXCEEDED once it is reached")
+                            help="Agent/Sandbox: Job spend cap in USD (model calls plus Sandbox time); Train recipe "
+                                 "--spec: cap on the GPU time of all Trials. Work stops with error BUDGET_EXCEEDED")
     job_submit.add_argument("--delete-delay-seconds", type=nonnegative_seconds, metavar="SECONDS",
                             help="keep each Sandbox (E2B or Fly) after completion for SECONDS (default: 0); cancellation/timeout delete immediately")
     job_submit.add_argument("--wait", action="store_true")
@@ -153,6 +158,8 @@ def add_commands(groups: "argparse._SubParsersAction[argparse.ArgumentParser]"):
         if action == 'event':
             command.add_argument('--json', action='store_true')
             command.set_defaults(_list_view=True)
+        else:
+            command.add_argument("--json", action="store_true", help=JSON_DEFAULT_HELP)
     regrade = jobs.add_parser("regrade", help="Re-run only the verifier of sealed compose Trials, optionally with a reward set",
                               allow_abbrev=False)
     regrade_source = regrade.add_mutually_exclusive_group(required=True)
@@ -197,6 +204,12 @@ def add_commands(groups: "argparse._SubParsersAction[argparse.ArgumentParser]"):
     train_log.add_argument("--limit", type=log_page_size, default=200, help="Maximum records per page (default: 200)")
     train_log.add_argument("--follow", action="store_true", help="Drain pages and poll until collection ends; Ctrl-C exits without stopping the Job")
     train_log.add_argument("--json", action="store_true", help="Output the complete page as JSON; --follow emits one page per line (NDJSON)")
+    train_metrics = jobs.add_parser("metrics", help="Read or follow a Train Job's per-step metrics")
+    train_metrics.add_argument("job_id", metavar="JOB_ID")
+    train_metrics.add_argument("--follow", action="store_true",
+                               help="Print new steps until the Job ends; Ctrl-C exits without stopping the Job")
+    train_metrics.add_argument("--json", action="store_true",
+                               help="Output the complete response as JSON; --follow emits one step per line (NDJSON)")
     from envloop._optional import available
     if available('rsi-loop'):
         from envloop_rsi_loop.cli import add_commands as add_runs
@@ -210,7 +223,9 @@ def add_commands(groups: "argparse._SubParsersAction[argparse.ArgumentParser]"):
     snapshot = tasks.add_parser("snapshot")
     snapshot.add_argument("trial_id", metavar="TRIAL_ID")
     for action in ("get", "stop", "result"):
-        tasks.add_parser(action).add_argument("trial_id", metavar="TRIAL_ID")
+        command = tasks.add_parser(action)
+        command.add_argument("trial_id", metavar="TRIAL_ID")
+        command.add_argument("--json", action="store_true", help=JSON_DEFAULT_HELP)
     listing.add_argument("--json", action="store_true", help="Output the complete response as JSON")
     artifacts = tasks.add_parser("artifact", help="List or download a Trial's artifacts").add_subparsers(dest="artifact_action", required=True)
     artifact_list = artifacts.add_parser("list", help="List one page of artifacts")
@@ -409,6 +424,12 @@ def execute_job(args: argparse.Namespace, client: Any, cli: argparse.ArgumentPar
         from envloop_experiment.train_log_cli import read_logs
 
         raise CommandExit(read_logs(client.jobs, args))
+    elif args.action == "metrics":
+        from envloop_experiment.train_metrics_cli import read_metrics
+
+        result = read_metrics(client.training_jobs, args)
+        if result is None:
+            raise CommandExit(0)
     elif args.action == "run" and args.run_action in {"start", "live", "steer", "stop"}:
         from envloop_rsi_loop.rsi_cli import run_rsi
 
@@ -426,12 +447,13 @@ def execute_job(args: argparse.Namespace, client: Any, cli: argparse.ArgumentPar
     else:
         result = getattr(client.jobs, 'status' if args.action == 'get' else args.action)(args.job_id)
         if args.action == 'get':
+            from envloop_experiment.train_metrics_cli import availability_line
             from envloop_experiment.train_progress import job_progress, progress_line
 
             # The JSON on stdout is unchanged; a Train Job's live progress is a readable stderr line.
-            line = progress_line(job_progress(result))
-            if line:
-                print(line, file=sys.stderr)
+            for line in (progress_line(job_progress(result)), availability_line(result)):
+                if line:
+                    print(line, file=sys.stderr)
         if args.action in {'get', 'result'}:
             from envloop_experiment.job_cost import cost_line
 
@@ -441,10 +463,27 @@ def execute_job(args: argparse.Namespace, client: Any, cli: argparse.ArgumentPar
                 print(line, file=sys.stderr)
             from envloop.cli_errors import failure_lines
 
-            for line in failure_lines(result):
+            for line in failure_lines(train_trials(client, result)):
                 print(line, file=sys.stderr)
     return result
 
+
+def train_trials(client: Any, result: Any):
+    """The failed Trials of a failed Train Job as a members view; any other Job is returned unchanged.
+
+    A Train Job lists only its Trial IDs, so their codes come from one Trial list read. A failed read
+    keeps the Job output and exit status: the failure lines are a convenience, not the result.
+    """
+    if not isinstance(result, dict) or result.get('type') != 'train' or result.get('status') != 'failed':
+        return result
+    from envloop.http import RemoteError
+    try:
+        page = client.trials.list(type='train', job_id=result.get('job_id'), limit=100)
+    except (RemoteError, OSError):
+        return result
+    attempts = [trial for trial in page.get('items') or [] if isinstance(trial, dict)] if isinstance(page, dict) else []
+    return {'members': [{'attempts': attempts}]}
+
 def execute_trial(args: argparse.Namespace, client: Any, cli: argparse.ArgumentParser):
     if args.action == "artifact":
         if args.artifact_action == "download":

envloop_experiment/job_cost.py

@@ -1,4 +1,4 @@
-"""One-line view of an Agent/Sandbox Job's ``cost`` and budget; reading never changes the Job."""
+"""One-line view of a Job's ``cost`` and budget; reading never changes the Job."""
 
 import math
 from typing import Any
@@ -17,18 +17,21 @@ def _usd(value: object) -> str:
 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.
+    A budgeted Train Job reports GPU time instead: ``Cost (estimate): $6.79 (GPU) of a $10.00 budget, $3.21 left``.
+    None when the response has no ``cost`` block (Inference Jobs, Train Jobs without a budget, 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'))})"
+    train = "gpu_usd" in cost
+    line = f"Cost (estimate): {_usd(cost.get('total_usd'))} " + (
+        "(GPU)" if train else f"(model {_usd(cost.get('model_usd'))}, sandbox {_usd(cost.get('sandbox_usd'))})")
     if cost.get("max_cost_usd") is not None:
         line += f" of a {_usd(cost.get('max_cost_usd'))} budget"
         if cost.get("unmetered") is True:
-            line += "; some usage has no price, so the budget cannot be enforced"
+            line += ("; the GPUs have no price, so the budget cannot be enforced" if train
+                     else "; some usage has no price, so the budget cannot be enforced")
         elif cost.get("budget_exceeded") is True:
             line += "; stopped: budget reached"
         else:
@@ -37,5 +40,5 @@ def cost_line(job: Any) -> str | None:
             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)"
+        line += f"; {'GPU' if train else 'sandbox'} time not charged ({cost['billing_mode']} billing)"
     return line

envloop_experiment/job_spec_cli.py

@@ -14,6 +14,30 @@ class SpecFileError(ValueError):
     """The input file is not a Job JSON object."""
 
 
+def train_dataset(spec: dict[str, Any], dataset: str | None, split: str | None) -> dict[str, Any]:
+    """A Train spec's record Dataset selector: NAME@VERSION and --split replace or complete the file's."""
+    if 'runner' in spec:
+        raise ValueError('--dataset and --split select recipe training data; a Runner Train spec takes no records')
+    if 'records' in spec:
+        raise ValueError('--dataset replaces inline records; remove records from the Train spec')
+    current = spec.get('dataset', {})
+    if not isinstance(current, dict):
+        raise ValueError('Train spec dataset must be an object')
+    selector = dict(current)
+    if dataset is not None:
+        name, separator, version = dataset.rpartition('@')
+        if not separator:
+            raise ValueError('Train --dataset needs an exact NAMESPACE/NAME@VERSION')
+        if (name, version) != (current.get('name'), current.get('version')):
+            selector.pop('manifest_sha256', None)  # a pin belongs to the version it was read from
+        selector.update(name=name, version=version)
+    if split is not None:
+        selector['split'] = split
+    if not {'name', 'version', 'split'} <= set(selector):
+        raise ValueError('Train --dataset needs NAMESPACE/NAME@VERSION and --split')
+    return selector
+
+
 def spec_request(args: argparse.Namespace):
     if args.trials is not None:
         raise ValueError('--trials cannot be combined with --spec; the file defines its Trial list')
@@ -42,10 +66,11 @@ def spec_request(args: argparse.Namespace):
     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_seconds', 'max_cost_usd'))
+        invalid = supplied(('source', 'task_id', 'revision',
+                            'job_id', 'tag', 'attempts', 'profile', 'delete_delay_seconds'))
         if kind == 'inference':
-            invalid += supplied(('config', 'priority', 'seed', 'command', 'image', 'timeout_seconds', *SHORTCUT_FIELDS))
+            invalid += supplied(('dataset', 'dataset_option', 'split', 'config', 'priority', 'seed', 'command', 'image',
+                                 'timeout_seconds', 'max_cost_usd', *SHORTCUT_FIELDS))
             if args.wait:
                 invalid.append('wait')
         if invalid:
@@ -62,12 +87,18 @@ def spec_request(args: argparse.Namespace):
             raise ValueError('Train Job spec requires non-empty trials with spec objects')
         if args.priority is not None:
             request['priority'] = args.priority
+        if args.max_cost_usd is not None:
+            # One cap on the GPU time of all the Job's Trials; the platform refuses it where it cannot enforce it.
+            request['budget'] = {'max_cost_usd': args.max_cost_usd}
         runner_fields = ('runner', 'command', 'image', 'timeout_seconds', *SHORTCUT_FIELDS)
+        dataset = args.dataset if args.dataset is not None else args.dataset_option
         for trial in trials:
             spec = trial['spec']
             for field in ('seed', 'config'):
                 if getattr(args, field) is not None:
                     spec[field] = getattr(args, field)
+            if dataset is not None or args.split is not None:
+                spec['dataset'] = train_dataset(spec, dataset, args.split)
             active_fields = runner_fields
             values = vars(args).copy()
             if not (args.runner or spec.get('runner')) and args.wait:

envloop_experiment/train.py

@@ -62,6 +62,11 @@ class TrainJobs:
         query = urlencode(log_query(source=source, cursor=cursor, tail=tail, limit=limit, process=process))
         return self.transport.request("GET", f"/v1/jobs/{quote(job_id, safe='')}/logs?{query}")
 
+    def metrics(self, job_id: str) -> dict[str, Any]:
+        """Recorded training metrics; ``loss.per_step`` holds one point per step the trainer reported
+        (loss, learning_rate, grad_norm, epoch, tokens_seen, seconds_per_step, observation time ``at``)."""
+        return self.transport.request("GET", f"/v1/jobs/{quote(job_id, safe='')}/metrics")
+
     def stop(self, job_id: str) -> dict[str, Any]:
         return self._view(self.transport.request('POST', f'/v1/jobs/{quote(job_id, safe="")}/stop'))
 
@@ -72,9 +77,9 @@ class TrainJobs:
         page = self.transport.request("GET", "/v1/jobs?" + query)
         return {**page, "items": [self._view(item) for item in page["items"]]}
 
-    def checkpoints(self, *, job_id: str | None = None, run_id: str | None = None, cursor: str | None = None, limit: int = 25) -> dict[str, Any]:
+    def checkpoints(self, *, job_id: str | None = None, trial_id: str | None = None, cursor: str | None = None, limit: int = 25) -> dict[str, Any]:
         query = urlencode({key: value for key, value in {
-            "job_id": job_id, "run_id": run_id,
+            "job_id": job_id, "trial_id": trial_id,
             "cursor": cursor, "limit": limit,
         }.items() if value is not None})
         return self.transport.request("GET", "/v1/checkpoints?" + query)

envloop_experiment/train_log_cli.py

@@ -12,7 +12,7 @@ from envloop.http import TRANSIENT_CODES, RemoteError
 from envloop.terminal import color_enabled, compact_time, safe_text, status_text, style
 from envloop_experiment.train_progress import job_progress, progress_line
 
-# While following a Train Job, re-read its progress at most this often (the platform observes it about every 30 s).
+# While following a Train Job, re-read its progress at most this often (the platform observes it about every 10 s).
 PROGRESS_POLL_SEC = 30
 # Consecutive transient failures `job log --follow` retries before it exits with the error.
 FOLLOW_RETRIES = 3
@@ -30,10 +30,13 @@ def log_line(item: dict[str, Any], *, color: bool = False):
         if item.get("phase"):
             diagnostic += f"; phase={safe_text(item['phase'])}"
         message = f"[{diagnostic}] {message}"
+    # The line had no write time and was read after the Job ended: its time is when it was collected.
+    backfilled = "(backfilled)" if item.get("backfilled") is True else ""
     if color:
         timestamp = style(timestamp, "2") if timestamp else ""
+        backfilled = style(backfilled, "2") if backfilled else ""
         level = status_text(level)
-    prefix = " ".join(part for part in (timestamp, level) if part)
+    prefix = " ".join(part for part in (timestamp, backfilled, level) if part)
     return f"{prefix} {message}"
 
 

envloop_experiment/train_metrics_cli.py

@@ -0,0 +1,146 @@
+"""Per-step Train Job metrics as a table or JSON; reading never changes the remote Job."""
+
+import argparse
+import json
+import math
+import re
+import sys
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from envloop.cli_output import display, table
+from envloop.http import TRANSIENT_CODES, RemoteError
+
+# The platform records new steps about every 10 s.
+POLL_SEC = 10
+# After the Job ends, its last steps are recorded by one final read on the platform.
+FINAL_READ_DELAY_SEC = 5
+FOLLOW_RETRIES = 3
+TERMINAL = {"completed", "succeeded", "failed", "cancelled", "SUCCEEDED", "FAILED", "CANCELLED"}
+HEADERS = ("STEP", "LOSS", "LEARNING RATE", "GRAD NORM", "EPOCH", "TOKENS", "SECONDS/STEP", "OBSERVED AT")
+# Column widths of --follow, which prints rows before later ones are known.
+WIDTHS = (6, 10, 13, 10, 8, 12, 12, 23)
+
+
+def _number(value: Any) -> float | None:
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) else None
+
+
+def job_steps(metrics: Any) -> list[dict[str, Any]]:
+    """``loss.per_step`` of a metrics response: one point per recorded step."""
+    loss = metrics.get("loss") if isinstance(metrics, dict) else None
+    points = loss.get("per_step") if isinstance(loss, dict) else None
+    return [point for point in points if isinstance(point, dict) and _number(point.get("step")) is not None] \
+        if isinstance(points, list) else []
+
+
+def _value(value: Any, spec: str) -> str | None:
+    number = _number(value)
+    return None if number is None else format(int(number) if spec == "d" else number, spec)
+
+
+def _observed(value: Any) -> str | None:
+    """``at`` is Unix time; like every table time it is shown in UTC, labelled (--json keeps the number)."""
+    number = _number(value)
+    return None if number is None else datetime.fromtimestamp(number, timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+def step_row(point: dict[str, Any], *, model: bool = False) -> tuple[object, ...]:
+    row = (_value(point.get("step"), "d"), _value(point.get("loss"), ".6g"),
+           _value(point.get("learning_rate"), ".4g"), _value(point.get("grad_norm"), ".4g"),
+           _value(point.get("epoch"), ".4g"), _value(point.get("tokens_seen"), "d"),
+           _value(point.get("seconds_per_step"), ".3g"), _observed(point.get("at")))
+    return (point.get("model_id"), *row) if model else row
+
+
+def _fixed(cells: tuple[object, ...]) -> str:
+    return "  ".join(display(cell).ljust(width) for cell, width in zip(cells, WIDTHS)).rstrip()
+
+
+def _read(read: Any, args: argparse.Namespace, retries: list[int]) -> Any:
+    """One read; ``--follow`` retries transient failures and names each retry."""
+    while True:
+        try:
+            value = read()
+        except RemoteError as error:
+            transient = error.code in TRANSIENT_CODES or error.status_code in {429, 500, 502, 503, 504}
+            if not args.follow or not transient or retries[0] >= FOLLOW_RETRIES:
+                raise
+            retries[0] += 1
+            delay = error.retry_after if error.retry_after is not None else 2
+            code = error.code if re.fullmatch(r"[A-Z0-9_]{1,128}", error.code) else "HTTP_ERROR"
+            status = f", HTTP {error.status_code}" if isinstance(error.status_code, int) else ""
+            print(f"Metrics read failed ({code}{status}); retry {retries[0]}/{FOLLOW_RETRIES} in {delay:g}s.",
+                  file=sys.stderr, flush=True)
+            time.sleep(delay)
+            continue
+        retries[0] = 0
+        return value
+
+
+def read_metrics(train: Any, args: argparse.Namespace) -> Any:
+    """``job metrics``: the response for ``--json``; otherwise prints and returns None."""
+    if not args.follow:
+        metrics = train.metrics(args.job_id)
+        if args.json:
+            return metrics
+        steps = job_steps(metrics)
+        if not steps:
+            print("No step metrics recorded yet." if not metrics.get("available") else "No step metrics.",
+                  file=sys.stderr)
+            return None
+        models = len({point.get("model_id") for point in steps}) > 1
+        print(table(("MODEL", *HEADERS) if models else HEADERS, [step_row(point, model=models) for point in steps]))
+        return None
+    return follow(train, args)
+
+
+def follow(train: Any, args: argparse.Namespace) -> None:
+    seen: set[tuple[Any, Any]] = set()
+    retries = [0]
+    header = False
+    model = None  # the Trials of a group Job run one after another; each starts with its model
+    final = False
+    try:
+        while True:
+            job = _read(lambda: train.status(args.job_id), args, retries)
+            metrics = _read(lambda: train.metrics(args.job_id), args, retries)
+            for point in job_steps(metrics):
+                identity = (point.get("model_id"), point.get("step"))
+                if identity in seen:
+                    continue
+                seen.add(identity)
+                if args.json:
+                    # One step per line; JSON escaping keeps control sequences out of the terminal.
+                    print(json.dumps(point, ensure_ascii=True), flush=True)
+                    continue
+                if isinstance(point.get("model_id"), str) and point["model_id"] != model:
+                    model = point["model_id"]
+                    print(f"Model {display(model)}", flush=True)
+                    header = False
+                if not header:
+                    print(_fixed(HEADERS), flush=True)
+                    header = True
+                print(_fixed(step_row(point)), flush=True)
+            if final:
+                return None
+            if isinstance(job, dict) and job.get("status") in TERMINAL:
+                final = True  # one more read picks up the steps recorded when the Job ended
+                time.sleep(FINAL_READ_DELAY_SEC)
+                continue
+            time.sleep(POLL_SEC)
+    except KeyboardInterrupt:
+        from envloop._optional import CommandExit
+
+        raise CommandExit(130) from None
+
+
+def availability_line(job: Any) -> str | None:
+    """``Step metrics: ...`` for a Train Job response; None for other Jobs."""
+    training = job.get("training") if isinstance(job, dict) else None
+    if not isinstance(training, dict) or not isinstance(training.get("metrics_available"), bool):
+        return None
+    if training["metrics_available"]:
+        return f"Step metrics: available; read them with: el job metrics {display(job.get('job_id'))}"
+    return "Step metrics: not recorded yet"

envloop_experiment/train_progress.py

@@ -48,5 +48,5 @@ def progress_line(progress: dict[str, Any] | None) -> str | None:
     if _number(progress.get("eta_seconds")) is not None:
         parts.append(f"ETA {_duration(progress['eta_seconds'])}")
     if isinstance(progress.get("updated_at"), str):
-        parts.append(f"updated {safe_text(compact_time(progress['updated_at']))}")
+        parts.append(f"updated {safe_text(compact_time(progress['updated_at'], utc=True))}")
     return "Training progress: " + ", ".join(parts)