envloop-cli 1.7.0__py3-none-any.whl → 1.12.0__py3-none-any.whl

envloop/agent_runs.py

@@ -1,7 +1,7 @@
 """Agent runs: a read-only view of Train Jobs grouped by their agent's run label.
 
 The platform stores no run object. Agents tag every Train Job they create with
-``user_metadata`` (the RSI loop: ``rsi_run``, ``rsi_round``, ``rsi_checkpoint``...);
+``tags`` (the RSI loop: ``rsi_run``, ``rsi_round``, ``rsi_checkpoint``...);
 this module pages through ``GET /v1/job`` and derives runs from those tags,
 using the same rules as the Console's agent runs page.
 """
@@ -34,7 +34,11 @@ class AgentRunError(RuntimeError):
 
 
 def _metadata(job) -> dict:
-    metadata = job.get("user_metadata")
+    metadata = job.get("tags")
+    if not isinstance(metadata, dict):
+        metadata = job.get("labels")
+    if not isinstance(metadata, dict):
+        metadata = job.get("user_metadata")
     return metadata if isinstance(metadata, dict) else {}
 
 
@@ -111,7 +115,7 @@ def _job_view(job) -> dict:
         "lora_rank": job.get("lora_rank"),
         "model_id": job.get("model_id"),
         "checkpoint": _checkpoint(job),
-        "user_metadata": metadata,
+        "tags": metadata,
     }
 
 

envloop/auth_cli.py

@@ -282,7 +282,7 @@ def run_auth(args, parser):
                 report["check"] = {401: "authentication_rejected", 403: "authorization_denied"}.get(
                     getattr(error, "status_code", None), safe_error_code(error))
                 _print(report, args.json)
-                print(format_error(error, args=args, program=parser.prog), file=sys.stderr)
+                print(format_error(error), file=sys.stderr)
                 return 1
     _print(report, getattr(args, "json", False))
     return 0

envloop/cli.py

@@ -39,6 +39,8 @@ class HelpArgumentParser(argparse.ArgumentParser):
     def __init__(self, *args, **kwargs):
         kwargs.setdefault('formatter_class', CommandHelpFormatter)
         super().__init__(*args, **kwargs)
+        self.add_argument("--no-color", action="store_true", default=argparse.SUPPRESS,
+                          help="Disable terminal highlighting")
         self.set_defaults(_help_parser=self)
         self._help_parser = self
 
@@ -61,9 +63,21 @@ class HelpArgumentParser(argparse.ArgumentParser):
     def error(self, message):
         if message.startswith("unrecognized arguments:"):
             message = "unrecognized arguments"
+        # argparse includes raw argument values in these diagnostics. Keep the
+        # option/type description while excluding values (which can be secrets).
+        if "invalid choice:" in message:
+            message = message.split("invalid choice:", 1)[0] + "invalid choice"
+        elif " value:" in message:
+            message = message.split(" value:", 1)[0] + " value"
+        elif message.startswith("ambiguous option:"):
+            message = "ambiguous option"
+        from .cli_errors import error_block
+
         command = self._help_parser
+        print(error_block("INVALID_ARGUMENT", message), file=sys.stderr)
+        print(file=sys.stderr)
         command.print_help(sys.stderr)
-        command.exit(2, f"\n{command.prog}: error: {message}\n")
+        command.exit(2)
 
 
 class CommandHelpFormatter(argparse.HelpFormatter):
@@ -133,10 +147,10 @@ def log_page_size(value):
 
 def runner_arguments(submit):
     submit.add_argument("--runner", metavar="NAME[@REVISION]",
-                        help="Agent/Train: namespace/name@REVISION; Sandbox: registered Runner name (for example base)")
-    submit.add_argument("--job-id", help="caller-selected Job ID")
-    submit.add_argument("--tag", help="run label")
-    submit.add_argument("--priority", type=int, help="waiting priority; larger values run first (default: 0)")
+                        help="Agent/Train/Inference: namespace/name@REVISION; Sandbox: registered Runner name (for example base)")
+    submit.add_argument("--job-id", help="Agent/Sandbox: caller-selected Job ID")
+    submit.add_argument("--tag", help="Agent/Sandbox: run label")
+    submit.add_argument("--priority", type=int, help="Agent/Sandbox/Train recipe: waiting priority; explicit value overrides spec (server default: 0)")
     submit.add_argument("--command", help="Agent/Sandbox: shell override; Train: declared run_command parameter passed to the published Runner entrypoint; preserves multiline text")
 
 
@@ -147,14 +161,14 @@ def parser():
         description="Manage Agent, Sandbox, Train and Inference Jobs and worker trials with EnvLoop.\nConfigure your connection with 'auth config'.",
     )
     cli._optionals.title = "Options"
-    cli.set_defaults(api_url=None, workspace_id=None)
+    cli.set_defaults(api_url=None, workspace_id=None, no_color=False)
     cli.add_argument("-V", "--version", action="version", version=f"%(prog)s {CLI_VERSION}", help="Display CLI version")
     groups = cli.add_subparsers(dest="group", title="Commands", prog=cli.prog, required=True)
     from .auth_cli import add_auth_commands
 
     jobs = groups.add_parser("job", help="Submit and manage Agent, Sandbox, Train and Inference Jobs").add_subparsers(dest="action", required=True)
     job_submit = jobs.add_parser("submit", help="Submit an Agent, Sandbox, Train or Inference Job", allow_abbrev=False)
-    job_submit.add_argument("--type", choices=("agent", "sandbox", "train", "inference"), default="agent", help="Job type (default: agent)")
+    job_submit.add_argument("--type", choices=("agent", "sandbox", "train", "inference"), default=None, help="Job type (default: spec type, otherwise agent)")
     job_submit.add_argument("--image", metavar="IMAGE", help="Sandbox image override (server default: python:3.11); Train Runner: public spelling of --docker")
     from .train_runner_cli import memory_mebibytes, positive_integer
 
@@ -166,7 +180,7 @@ def parser():
     for option in ('memory', 'disk', 'shm-size'):
         job_submit.add_argument('--' + option, type=memory_mebibytes, metavar="SIZE",
                                 help="Train Runner: per-Trial size in Mi/Gi/Ti (for example 64Gi)")
-    job_submit.add_argument("--file", type=Path, help="Managed Train or Inference Job JSON (spec or Train trials array; interactive training is unsupported)")
+    job_submit.add_argument("--spec", type=Path, metavar="REQUEST.json", help="Job specification JSON; explicit submission options override file values (except --trails)")
     job_submit.add_argument("--source", type=Path, help="two-file directory for a single-task Job")
     job_submit.add_argument("--task-id", help="select one task within the dataset")
     job_submit.add_argument(
@@ -175,17 +189,17 @@ def parser():
     )
     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")
-    job_submit.add_argument("--config", help="dataset subset; uses its declared default when omitted")
+    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("--revision", help="Git branch/tag/commit; must match the platform's pinned snapshot")
     runner_arguments(job_submit)
     job_submit.add_argument("--attempts", type=int)
-    job_submit.add_argument("--request-id")
+    job_submit.add_argument("--request-id", help="idempotency key; overrides request_id in --spec")
     job_submit.add_argument("--profile", type=profile_reference, metavar="NAME[@VERSION]",
-                            help="named runtime Profile; omitted version requires an explicit default")
+                            help="named runtime Profile; omitted version prefers default, then newest unarchived creation")
     job_submit.add_argument("--seed", type=int)
     job_submit.add_argument("--timeout-sec", type=wait_seconds,
-                            help="Agent/Sandbox or Train Runner execution timeout (whole seconds); Train --file wait timeout (default: 600)")
+                            help="Agent/Sandbox or Train Runner execution timeout (whole seconds); Train recipe --wait timeout (default: 600)")
     job_submit.add_argument("--delete-delay", 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")
@@ -207,6 +221,8 @@ def parser():
     train_log = jobs.add_parser("log", help="Read or follow Agent, Sandbox or Train Job logs")
     train_log.add_argument("job_id")
     train_log.add_argument("--source", choices=("all", "system", "runtime"), default="all")
+    train_log.add_argument("--process", metavar="NAME",
+                           help="Only one recorded process, e.g. trainer (a Train Job's step metrics)")
     position = train_log.add_mutually_exclusive_group()
     position.add_argument("--tail", type=log_page_size, help="Start with the last N records (default: 200)")
     position.add_argument("--cursor", help="Resume from a previously returned log cursor")
@@ -217,7 +233,7 @@ def parser():
     runs_list = runs.add_parser("list", help="List agent runs, most recently updated first")
     runs_list.add_argument("--json", action="store_true", help="Output the complete response as JSON (default: table)")
     runs_get = runs.add_parser("get", help="Show a run's rounds, Train Jobs and checkpoints")
-    runs_get.add_argument("run", metavar="RUN", help="run label: user_metadata.rsi_run or agent_run")
+    runs_get.add_argument("run", metavar="RUN", help="run tag: tags.rsi_run or agent_run")
     runs_get.add_argument("--json", action="store_true", help="Output the complete run as JSON (default: tables)")
     runs_start = runs.add_parser("start", help="Start a new RSI loop run (paid; needs training.run)")
     runs_start.add_argument("run", metavar="RUN", help="new run id: lower-case letters, digits and dashes")
@@ -233,6 +249,7 @@ def parser():
     runs_start.add_argument("--student-model", help="gateway student model of a dry run")
     runs_live = runs.add_parser("live", help="Show what a run does now; --follow streams new events")
     runs_live.add_argument("run", metavar="RUN")
+    runs_live.add_argument("--json", action="store_true", help="Output JSON; --follow emits complete frames as NDJSON")
     runs_live.add_argument("--since", type=int, help="only events after this cursor (the previous next_cursor)")
     runs_live.add_argument("--follow", action="store_true", help="poll and print new events until the run ends; Ctrl-C exits without stopping it")
     runs_steer = runs.add_parser("steer", help="Message the running operator now (needs training.run)")
@@ -273,7 +290,7 @@ def parser():
     update = profiles.add_parser("update", help="Edit an existing Profile by publishing a new immutable version")
     update.add_argument("name")
     update.add_argument("version", help="New version; existing versions cannot be overwritten")
-    update.add_argument("--from-version", help="Source version; omit to use the explicit default")
+    update.add_argument("--from-version", help="Source version; omit to use default, then newest unarchived creation")
     update.add_argument("--file", type=Path, required=True, help="TOML or JSON patch: merge params keys, replace supplied metadata; preserve omitted fields")
     update.add_argument("--runner", metavar="RUNNER", help="Bind a Runner revision; v1 requires a full commit; omit to preserve the source binding")
     update_secret = update.add_mutually_exclusive_group()
@@ -378,11 +395,24 @@ def resolve_cli_connection(api_url=None, workspace_id=None, project_id=None):
 
 
 def main(argv=None):
+    from .terminal import output_options
+
+    with output_options():
+        return _main(argv)
+
+
+def _main(argv=None):
     cli = parser()
     argv = sys.argv[1:] if argv is None else argv
     if not argv:
         cli.print_help()
         return 0
+    # Apply display options before validation, even if an earlier argument is invalid.
+    options = argv[:argv.index("--")] if "--" in argv else argv
+    if "--no-color" in options:
+        from .terminal import disable_color
+
+        disable_color()
     if any(value == "--api-key" or value.startswith("--api-key=") for value in argv):
         cli.error("API keys must be entered with auth config or supplied through ENVLOOP_API_KEY")
     args = cli.parse_args(argv)
@@ -397,22 +427,38 @@ def main(argv=None):
             from .cli_errors import format_error
             from .config import ConfigError
 
-            print(format_error(ConfigError('AUTH_INPUT_CANCELLED'), args=args, program=cli.prog), file=sys.stderr)
+            print(format_error(ConfigError('AUTH_INPUT_CANCELLED')), file=sys.stderr)
             return 1
         except Exception as exc:
             from .cli_errors import format_error
 
-            print(format_error(exc, args=args, program=cli.prog), file=sys.stderr)
+            print(format_error(exc), file=sys.stderr)
             return 1
     if args.group == "job" and args.action == "submit":
         from .train_runner_cli import SHORTCUT_FIELDS, runner_request
 
-        runner_mode = args.type == 'train' and args.file is None
-        if not runner_mode and any(getattr(args, key) is not None for key in SHORTCUT_FIELDS):
-            cli.error('Train Runner shortcuts require --type train --runner and cannot be combined with --file')
-        if args.type in {"train", "inference"}:
-            if args.file is None and not runner_mode:
-                cli.error(f"--type {args.type} requires --file REQUEST.json")
+        if args.spec is not None:
+            from .job_spec_cli import SpecFileError, spec_request
+
+            try:
+                args.job_request = spec_request(args)
+            except (OSError, UnicodeError, json.JSONDecodeError, SpecFileError) as exc:
+                from .cli_errors import format_error
+
+                print(format_error(exc), file=sys.stderr)
+                return 1
+            except (ValueError, TypeError) as exc:
+                cli.error(str(exc) if isinstance(exc, ValueError) else 'Unable to merge Job spec')
+        else:
+            args.type = args.type or 'agent'
+        runner_mode = args.type == 'train' and args.spec is None
+        if args.spec is None and not runner_mode and any(getattr(args, key) is not None for key in SHORTCUT_FIELDS):
+            cli.error('Train Runner shortcuts require --type train --runner and cannot be combined with --spec')
+        if args.spec is not None:
+            pass  # The merged request was validated above; the platform owns final admission.
+        elif args.type in {"train", "inference"}:
+            if args.spec is None and not runner_mode:
+                cli.error(f"--type {args.type} requires --spec REQUEST.json")
             if args.type == 'inference' and (args.wait or args.timeout_sec is not None):
                 cli.error('Inference is a continuous service; --wait and --timeout-sec do not apply')
             agent_fields = ("dataset", "dataset_option", "source", "task_id", "config", "split", "revision",
@@ -420,7 +466,7 @@ def main(argv=None):
             if not runner_mode:
                 agent_fields += ('runner', 'command', 'request_id', 'image')
             if any(getattr(args, key) is not None for key in agent_fields):
-                cli.error(f"--type {args.type} cannot be combined with Agent submission options or mixed --file/Runner input")
+                cli.error(f"--type {args.type} cannot be combined with Agent submission options or mixed --spec/Runner input")
             if runner_mode:
                 try:
                     args.train_request = runner_request(args)
@@ -430,8 +476,8 @@ def main(argv=None):
             from .sandbox import sandbox_runner_selector, validate_image
 
             if any(getattr(args, key) is not None for key in (
-                    'file', 'dataset', 'dataset_option', 'source', 'task_id', 'config', 'split', 'revision', 'seed')):
-                cli.error('--type sandbox accepts --runner without Dataset, Task, Train file or seed options')
+                    'spec', 'dataset', 'dataset_option', 'source', 'task_id', 'config', 'split', 'revision', 'seed')):
+                cli.error('--type sandbox accepts --runner without Dataset, Task, Job spec or seed options')
             try:
                 args.runner = sandbox_runner_selector(args.runner)
                 if args.image is not None:
@@ -443,8 +489,8 @@ def main(argv=None):
                     cli.error('Sandbox --timeout-sec must be whole seconds')
                 args.timeout_sec = int(args.timeout_sec)
         else:
-            if args.file is not None:
-                cli.error("--file requires --type train or inference")
+            if args.spec is not None:
+                cli.error("--spec requires --type train or inference")
             if args.image is not None:
                 cli.error('--image requires --type sandbox')
             if args.runner is not None:
@@ -526,17 +572,19 @@ def main(argv=None):
             elif args.group == "job":
                 if args.action == "submit":
                     if args.type == 'inference':
-                        result = client.jobs.submit_inference(json.loads(args.file.read_text(encoding='utf-8')))
+                        result = client.jobs.submit_inference(args.job_request)
                     elif args.type == "train":
-                        request = args.train_request if args.file is None else json.loads(args.file.read_text(encoding="utf-8"))
+                        request = args.train_request if args.spec is None else args.job_request
                         result = client.training_jobs.submit(request)
+                    elif args.spec is not None:
+                        result = client.jobs.submit_spec(args.job_request)
                     else:
                         result = client.jobs.submit(args.dataset, type=args.type, source=args.source, task_id=args.task_id,
                                                     attempts=args.attempts if args.attempts is not None else 1,
                                                     request_id=args.request_id, config=args.config, split=args.split,
                                                     revision=args.revision, **submission_options(args))
                     if args.wait:
-                        wait_options = {"timeout": args.timeout_sec} if args.type == "train" and args.file is not None and args.timeout_sec is not None else {}
+                        wait_options = {"timeout": args.timeout_sec} if args.type == "train" and args.spec is not None and args.timeout_sec is not None else {}
                         result = client.jobs.wait(result["job_id"], **wait_options)
                 elif args.action == 'event':
                     result = client.jobs.events(args.job_id)
@@ -563,6 +611,13 @@ def main(argv=None):
                     result = client.jobs.list(**options)
                 else:
                     result = getattr(client.jobs, 'status' if args.action == 'get' else args.action)(args.job_id)
+                    if args.action == 'get':
+                        from .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)
             elif args.group == "trail":
                 if args.action == "artifact":
                     if args.artifact_action == "download":
@@ -606,10 +661,10 @@ def main(argv=None):
 
         if isinstance(exc, CleanupError):
             print(json.dumps(operation_output(exc.operation), ensure_ascii=False))
-            print(format_error(exc, args=args, program=cli.prog), file=sys.stderr)
+            print(format_error(exc), file=sys.stderr)
             return 1
         # Do not emit arbitrary exception messages, file content or credentials.
-        print(format_error(exc, args=args, program=cli.prog), file=sys.stderr)
+        print(format_error(exc), file=sys.stderr)
         return 1