envloop-cli 1.10.0__tar.gz → 1.12.0__tar.gz

{envloop_cli-1.10.0 → envloop_cli-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: envloop-cli
-Version: 1.10.0
+Version: 1.12.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

{envloop_cli-1.10.0 → envloop_cli-1.12.0}/envloop/cli.py

@@ -221,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")
@@ -609,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":

{envloop_cli-1.10.0 → envloop_cli-1.12.0}/envloop/client.py

@@ -582,11 +582,15 @@ class Jobs:
     def list(self, **kwargs):
         return self._server.list_jobs(**kwargs)
 
-    def logs(self, job_id, *, source='all', cursor=None, tail=None, limit=200):
-        """Read captured Job output, retaining pagination and collection metadata."""
+    def logs(self, job_id, *, source='all', cursor=None, tail=None, limit=200, process=None):
+        """Read captured Job output, retaining pagination and collection metadata.
+
+        ``process`` selects one recorded process, e.g. ``"trainer"`` for a Train Job's step metrics.
+        """
         from .job_logs import log_query
 
-        return self._server.get_job_logs(job_id, **log_query(source=source, cursor=cursor, tail=tail, limit=limit))
+        return self._server.get_job_logs(job_id, **log_query(source=source, cursor=cursor, tail=tail, limit=limit,
+                                                             process=process))
 
     def stop(self, job_id):
         return self._server.stop_job(job_id)

{envloop_cli-1.10.0 → envloop_cli-1.12.0}/envloop/job_logs.py

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

{envloop_cli-1.10.0 → envloop_cli-1.12.0}/envloop/train.py

@@ -52,11 +52,15 @@ class TrainJobs:
     def result(self, job_id: str) -> dict:
         return self._view(self.transport.request('GET', f'/v1/job/{quote(job_id, safe="")}/result'))
 
-    def logs(self, job_id: str, *, source="all", cursor=None, tail=None, limit=200) -> dict:
-        """Read a log page; cursors retain the server's source and capture metadata."""
+    def logs(self, job_id: str, *, source="all", cursor=None, tail=None, limit=200, process=None) -> dict:
+        """Read a log page; cursors retain the server's source and capture metadata.
+
+        ``process="trainer"`` reads only the trainer's step metric lines. Live step, loss and ETA
+        are ``status(job_id)["progress"]``.
+        """
         from .job_logs import log_query
 
-        query = urlencode(log_query(source=source, cursor=cursor, tail=tail, limit=limit))
+        query = urlencode(log_query(source=source, cursor=cursor, tail=tail, limit=limit, process=process))
         return self.transport.request("GET", f"/v1/job/{quote(job_id, safe='')}/logs?{query}")
 
     def stop(self, job_id: str) -> dict:

{envloop_cli-1.10.0 → envloop_cli-1.12.0}/envloop/train_log_cli.py

@@ -7,12 +7,19 @@ from collections import OrderedDict
 
 from .http import RemoteError
 from .terminal import color_enabled, compact_time, safe_text, status_text, style
+from .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).
+PROGRESS_POLL_SEC = 30
 
 
 def log_line(item, *, color=False):
     timestamp = compact_time(safe_text(item.get("at") or ""))
     level = safe_text(item.get("level") or "info")
     message = safe_text(item["content"])
+    # Captured lines keep their own line break; print adds one, so drop it rather than double-space.
+    if message.endswith("\n"):
+        message = message[:-1]
     if item.get("code"):
         diagnostic = safe_text(item["code"])
         if item.get("phase"):
@@ -47,6 +54,22 @@ def capture_summary(page):
     return "Log collection: " + "; ".join(details) if details else ""
 
 
+def show_progress(train, job_id, state):
+    """Print a Train Job's progress line to stderr when it changes; other Job types stop the polling."""
+    state["next"] = time.monotonic() + PROGRESS_POLL_SEC
+    try:
+        job = train.status(job_id)
+    except RemoteError:
+        return  # Progress is an observation; a failed read never interrupts the log stream.
+    if not isinstance(job, dict) or job.get("type") not in {None, "train"}:
+        state["enabled"] = False
+        return
+    line = progress_line(job_progress(job))
+    if line and line != state["line"]:
+        print(line, file=sys.stderr, flush=True)
+        state["line"] = line
+
+
 def read_logs(train, args):
     color = color_enabled()
     cursor = args.cursor
@@ -54,10 +77,12 @@ def read_logs(train, args):
     retries = 0
     previous_summary = None
     seen = OrderedDict()
+    progress = {"next": 0.0, "line": None, "enabled": args.follow and not args.json}
     try:
         while True:
             try:
-                page = train.logs(args.job_id, source=args.source, cursor=cursor, tail=tail, limit=args.limit)
+                page = train.logs(args.job_id, source=args.source, cursor=cursor, tail=tail, limit=args.limit,
+                                  **({"process": args.process} if getattr(args, "process", None) is not None else {}))
             except RemoteError as error:
                 transient = error.code == "NETWORK_ERROR" or error.status_code in {429, 500, 502, 503, 504}
                 if not args.follow or not transient or retries >= 3:
@@ -85,6 +110,8 @@ def read_logs(train, args):
             else:
                 for item in page["items"]:
                     print(log_line(item, color=color), flush=True)
+            if progress["enabled"] and time.monotonic() >= progress["next"]:
+                show_progress(train, args.job_id, progress)
             summary = capture_summary(page)
             if summary and summary != previous_summary:
                 print(summary, file=sys.stderr)

envloop_cli-1.12.0/envloop/train_progress.py

@@ -0,0 +1,51 @@
+"""One-line view of a Train Job's live ``training.progress``; reading never changes the Job."""
+
+import math
+
+from .terminal import compact_time, safe_text
+
+
+def _number(value):
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) else None
+
+
+def _duration(seconds):
+    seconds = int(round(seconds))
+    hours, rest = divmod(seconds, 3600)
+    minutes, seconds = divmod(rest, 60)
+    return f"{hours}h{minutes:02d}m" if hours else f"{minutes}m{seconds:02d}s" if minutes else f"{seconds}s"
+
+
+def job_progress(job):
+    """The ``training.progress`` mapping of a Job response, or None."""
+    training = job.get("training") if isinstance(job, dict) else None
+    progress = training.get("progress") if isinstance(training, dict) else None
+    return progress if isinstance(progress, dict) else None
+
+
+def progress_line(progress):
+    """``Training progress: step 32/66 (48.5%), loss 0.2118, lr 0.0001315, ETA 22m41s, updated ...``.
+
+    None until the platform has observed a step; a value never observed is omitted, not shown as zero.
+    """
+    if not isinstance(progress, dict) or _number(progress.get("step")) is None:
+        return None
+    step, total = _number(progress.get("step")), _number(progress.get("total_steps"))
+    part = f"step {step:g}/{total:g}" if total else f"step {step:g}"
+    percent = _number(progress.get("percent"))
+    parts = [part + (f" ({percent:g}%)" if percent is not None else "")]
+    loss = _number(progress.get("loss"))
+    if loss is not None:
+        logged = _number(progress.get("metrics_step"))
+        # The latest logged loss can belong to an earlier step than the step bar.
+        parts.append(f"loss {loss:.4g}" + (f" (step {logged:g})" if logged is not None and logged != step else ""))
+    for key, label in (("learning_rate", "lr"), ("grad_norm", "grad_norm")):
+        if _number(progress.get(key)) is not None:
+            parts.append(f"{label} {progress[key]:.4g}")
+    if _number(progress.get("tokens_seen")) is not None:
+        parts.append(f"tokens {int(progress['tokens_seen']):,}")
+    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']))}")
+    return "Training progress: " + ", ".join(parts)

{envloop_cli-1.10.0 → envloop_cli-1.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "envloop-cli"
-version = "1.10.0"
+version = "1.12.0"
 description = "EnvLoop CLI and Python SDK for jobs, training, checkpoints and inference"
 requires-python = ">=3.11"
 readme = "README.pypi.md"