envloop-cli 0.1.0__py3-none-any.whl

el_cli/__init__.py

@@ -0,0 +1 @@
+"""Standalone EnvLoop command-line client."""

el_cli/cli.py

@@ -0,0 +1,257 @@
+"""el: local Profile and Task operations built entirely on the SDK."""
+
+import argparse
+import json
+import os
+import shlex
+import sys
+from pathlib import Path
+
+from . import train
+from .client import Client
+
+
+class HelpArgumentParser(argparse.ArgumentParser):
+    """Show full command help for syntax and usage errors."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.set_defaults(_help_parser=self)
+        self._help_parser = self
+
+    def parse_known_args(self, args=None, namespace=None):
+        self._help_parser = self
+        parsed, remaining = super().parse_known_args(args, namespace)
+        # Subparsers propagate their defaults; keep the deepest selected command
+        # for unknown arguments and usage checks performed after parsing.
+        self._help_parser = parsed._help_parser
+        return parsed, remaining
+
+    def error(self, message):
+        command = self._help_parser
+        command.print_help(sys.stderr)
+        command.exit(2, f"\n{command.prog}: error: {message}\n")
+
+
+def dataset_reference(value):
+    name, separator, version = value.rpartition("@")
+    if (not value.strip() or (separator and (not name.strip() or not version.strip()))):
+        raise argparse.ArgumentTypeError(
+            "expected name or name@version with a non-empty name and version "
+            "(e.g. org/dataset@1.0)"
+        )
+    return value
+
+
+def submit_arguments(submit):
+    submit.add_argument("source", type=Path)
+    submit.add_argument(
+        "--profile", help="name@version, or name with an explicit default; latest is literal",
+    )
+    submit.add_argument("--profile-sha256", help="Expected canonical ProfileSpec SHA-256")
+    submit.add_argument("--request-id")
+    submit.add_argument("--seed", type=int)
+    submit.add_argument("--timeout-sec", type=int)
+    submit.add_argument("--executor", choices=["local", "docker", "sandbox"])
+    submit.add_argument("--provider", choices=["e2b", "e2b-local"])
+    submit.add_argument("--wait", action="store_true")
+
+
+def parser():
+    cli = HelpArgumentParser(prog="el")
+    cli.add_argument("--repository-root", type=Path)
+    cli.add_argument("--repository-commit")
+    cli.add_argument("--work-dir", type=Path)
+    cli.add_argument("--api-url", default=os.environ.get("ENVLOOP_BASE_URL", os.environ.get("ENVPLATFORM_API_URL")), help="HTTPS apiserver or loopback URL; defaults to ENVLOOP_BASE_URL; Bearer key from ENVLOOP_API_KEY")
+    cli.add_argument("--workspace-id", default=os.environ.get("ENVLOOP_WORKSPACE_ID"), help="Optional workspace override; defaults to the user's authorized workspace")
+    groups = cli.add_subparsers(dest="group", required=True)
+    train.register(groups)
+    profiles = groups.add_parser("profile").add_subparsers(dest="action", required=True)
+    profiles.add_parser("init")
+    put = profiles.add_parser("put")
+    put.add_argument("name")
+    put.add_argument("version")
+    put.add_argument("--file", type=Path, required=True, help="ProfileSpec JSON file")
+    get = profiles.add_parser("get")
+    get.add_argument("name")
+    get.add_argument("--version")
+    listing = profiles.add_parser("list")
+    listing.add_argument("--name")
+    listing.add_argument("--include-archived", action="store_true")
+    listing.add_argument("--limit", type=int, default=50)
+    listing.add_argument("--cursor")
+    default = profiles.add_parser("set-default")
+    default.add_argument("name")
+    default.add_argument("version")
+    default.add_argument("--expected-version", help="Omit only when no default exists")
+    for command in ("archive", "export"):
+        item = profiles.add_parser(command)
+        item.add_argument("name")
+        item.add_argument("version")
+    tasks = groups.add_parser("task").add_subparsers(dest="action", required=True)
+    submit = tasks.add_parser("submit")
+    submit_arguments(submit)
+    submissions = groups.add_parser("submit").add_subparsers(dest="action", required=True)
+    submit_arguments(submissions.add_parser("task"))
+    snapshot = tasks.add_parser("snapshot")
+    snapshot.add_argument("trial_id")
+    for action in ("status", "stop", "result"):
+        tasks.add_parser(action).add_argument("trial_id")
+    jobs = groups.add_parser("job").add_subparsers(dest="action", required=True)
+    job_submit = jobs.add_parser("submit")
+    job_submit.add_argument(
+        "dataset", nargs="?", type=dataset_reference, metavar="NAME[@VERSION]",
+        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")
+    job_submit.add_argument("--namespace", help="explicit namespace for a short dataset name")
+    job_submit.add_argument("--config", help="dataset subset; uses its declared default when omitted")
+    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")
+    job_submit.add_argument("--attempts", type=int, default=1)
+    job_submit.add_argument("--request-id")
+    job_submit.add_argument("--profile")
+    job_submit.add_argument("--seed", type=int)
+    job_submit.add_argument("--timeout-sec", type=int)
+    job_submit.add_argument("--executor", choices=["local", "docker", "sandbox"])
+    job_submit.add_argument("--provider", choices=["e2b", "e2b-local"])
+    job_submit.add_argument("--wait", action="store_true")
+    for action in ("status", "stop", "result"):
+        jobs.add_parser(action).add_argument("job_id")
+    listing = jobs.add_parser("list")
+    listing.add_argument("--cursor")
+    listing.add_argument("--limit", type=int, default=25)
+    return cli
+
+
+def submission_options(args):
+    options = {}
+    if args.profile:
+        if "@" not in args.profile:
+            name, version = args.profile, None
+        elif args.group == "job":
+            name, version = args.profile.rsplit("@", 1)
+        else:
+            name, version = args.profile.split("@", 1)
+        options["profile_name"] = name
+        if version is not None:
+            options["profile_version"] = version
+    if args.seed is not None:
+        options["seed"] = args.seed
+    execution = {key: value for key, value in {"timeout_sec": args.timeout_sec, "executor": args.executor, "provider": args.provider}.items() if value is not None}
+    if execution:
+        options["execution"] = execution
+    return options
+
+
+def local_api_url():
+    """Read only the CLI connection setting; never import task secrets."""
+    path = Path.cwd() / ".env.local"
+    if not path.is_file():
+        return None
+    values = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        key, separator, raw = line.strip().removeprefix("export ").partition("=")
+        if separator and key.strip() in {"ENVLOOP_BASE_URL", "ENVPLATFORM_API_URL"}:
+            values[key.strip()] = raw
+    raw = values.get("ENVLOOP_BASE_URL", values.get("ENVPLATFORM_API_URL"))
+    if raw is None:
+        return None
+    parts = shlex.split(raw, comments=True)
+    if len(parts) > 1:
+        raise ValueError("invalid API URL configuration")
+    return parts[0] if parts else ""
+
+
+def main(argv=None):
+    cli = parser()
+    args = cli.parse_args(argv)
+    if args.group == "job" and args.action == "submit":
+        if (args.dataset is None) == (args.dataset_option is None):
+            cli.error("provide exactly one positional dataset or --dataset")
+        args.dataset = args.dataset if args.dataset is not None else args.dataset_option
+    if args.api_url is not None and (args.repository_root or args.repository_commit or args.work_dir or args.group == "profile"):
+        cli.error("--api-url cannot be combined with local repository/profile options")
+    try:
+        if args.api_url is None and not (
+            args.repository_root or args.repository_commit or args.work_dir
+            or args.group == "profile"
+        ):
+            args.api_url = local_api_url()
+        if args.group == "profile" and args.action == "init":
+            if args.repository_root is None:
+                cli.error("--repository-root is required")
+            Client.init_repository(args.repository_root)
+            print(json.dumps({"initialized": True}))
+            return 0
+        if args.group == "train" and args.api_url is None:
+            cli.error("train requires --api-url or ENVLOOP_BASE_URL")
+        connection = Client.remote(args.api_url, workspace_id=args.workspace_id) if args.api_url is not None else Client.local(
+            repository_root=args.repository_root,
+            repository_commit=args.repository_commit,
+            work_dir=args.work_dir,
+        )
+        with connection as client:
+            if args.group == "train":
+                result = train.execute(client.train, args)
+            elif args.group == "profile":
+                if args.action == "put":
+                    result = client.profiles.import_spec(
+                        args.file.read_bytes(), name=args.name, version=args.version
+                    )
+                elif args.action == "get":
+                    result = client.profiles.get(args.name, args.version)
+                elif args.action == "list":
+                    result = client.profiles.list(
+                        name=args.name,
+                        include_archived=args.include_archived,
+                        limit=args.limit,
+                        cursor=args.cursor,
+                    )
+                elif args.action == "set-default":
+                    result = client.profiles.set_default(
+                        args.name, args.version, expected_version=args.expected_version
+                    )
+                elif args.action == "archive":
+                    result = client.profiles.archive(args.name, args.version)
+                else:
+                    sys.stdout.buffer.write(
+                        client.profiles.export(args.name, args.version) + b"\n"
+                    )
+                    return 0
+            elif args.group == "job":
+                if args.action == "submit":
+                    result = client.jobs.submit(args.dataset, attempts=args.attempts, request_id=args.request_id,
+                                                namespace=args.namespace, config=args.config, split=args.split,
+                                                revision=args.revision, **submission_options(args))
+                    if not args.api_url or args.wait:
+                        result = client.jobs.wait(result["job_id"])
+                elif args.action == "list":
+                    result = client.jobs.list(cursor=args.cursor, limit=args.limit)
+                else:
+                    result = getattr(client.jobs, args.action)(args.job_id)
+            elif args.action in {"snapshot", "status", "stop", "result"}:
+                result = getattr(client.tasks, args.action)(args.trial_id)
+            else:
+                trial = client.tasks.submit(
+                    args.source,
+                    request_id=args.request_id,
+                    profile_sha256=args.profile_sha256,
+                    **submission_options(args),
+                )
+                if not args.api_url or args.wait:
+                    client.tasks.wait(trial["trial_id"], timeout=600)
+                    result = client.tasks.result(trial["trial_id"])
+                else:
+                    result = trial
+            print(json.dumps(result, ensure_ascii=False))
+            return 1 if result.get("status") == "failed" else 0
+    except Exception as exc:
+        # Do not emit arbitrary exception messages, file content or credentials.
+        print(getattr(exc, "code", None) or type(exc).__name__, file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

el_cli/client.py

@@ -0,0 +1,335 @@
+"""Thin synchronous SDK for direct, in-process Task calls."""
+
+import math
+import time
+import tomllib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Protocol
+from uuid import uuid4
+
+from .utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class TaskService(Protocol):
+    def submit_task(self, body: dict) -> dict: ...
+    def get_task_run(self, trial_id: str) -> dict: ...
+    def get_task_result(self, trial_id: str) -> dict: ...
+    def get_task_snapshot(self, trial_id: str) -> dict: ...
+    def stop_task(self, trial_id: str) -> dict: ...
+
+
+class ProfileService(Protocol):
+    def init_repository(self, root: str | Path) -> dict: ...
+    def put_profile(self, spec: dict) -> dict: ...
+    def get_profile(self, name: str, version: str | None = None) -> dict: ...
+    def list_profiles(
+        self,
+        *,
+        name: str | None = None,
+        include_archived: bool = False,
+        limit: int = 50,
+        cursor: str | None = None,
+    ) -> dict: ...
+    def resolve_profile(
+        self,
+        name: str,
+        version: str | None = None,
+        expected_sha256: str | None = None,
+    ) -> dict: ...
+    def set_default_profile(
+        self,
+        name: str,
+        version: str,
+        *,
+        expected_version: str | None,
+    ) -> dict: ...
+    def archive_profile(self, name: str, version: str) -> dict: ...
+    def export_profile(self, name: str, version: str) -> bytes: ...
+    def import_profile(
+        self,
+        raw: bytes,
+        *,
+        name: str | None = None,
+        version: str | None = None,
+    ) -> dict: ...
+
+
+class RpcService(TaskService, ProfileService, Protocol):
+    """Transport-independent service contract for the SDK."""
+
+
+def load_task(source: str | Path | Mapping) -> dict:
+    """Read the two UTF-8 task files without executing or modifying them."""
+    if isinstance(source, Mapping):
+        return dict(source)
+    directory = Path(source)
+    config_path = directory / "task.toml"
+    if config_path.is_symlink() or not config_path.is_file():
+        raise ValueError(f"missing regular task.toml: {directory}")
+    config = config_path.read_text(encoding="utf-8")
+    execution = tomllib.loads(config).get("execution", {})
+    if not isinstance(execution, dict):
+        raise ValueError("[execution] must be a table")
+    entry = execution.get("entrypoint")
+    if entry not in {"main.py", "main.sh"}:
+        raise ValueError("entrypoint must be main.py or main.sh")
+    path = directory / entry
+    if path.is_symlink() or not path.is_file():
+        raise ValueError(f"missing regular entrypoint: {entry}")
+    names = {p.name for p in directory.iterdir() if p.is_file() or p.is_symlink()}
+    if names != {"task.toml", entry}:
+        raise ValueError(
+            "task directory must contain exactly task.toml and its entrypoint"
+        )
+    return {"task.toml": config, entry: path.read_text(encoding="utf-8")}
+
+
+class Tasks:
+    def __init__(self, server: TaskService) -> None:
+        self._server = server
+
+    def submit(
+        self,
+        source: str | Path | Mapping | None = None,
+        *,
+        request_id: str | None = None,
+        profile: Mapping | None = None,
+        task_ref: Mapping | None = None,
+        profile_name: str | None = None,
+        profile_version: str | None = None,
+        profile_sha256: str | None = None,
+        profile_overrides: Mapping | None = None,
+        seed: int | None = None,
+        execution: Mapping | None = None,
+    ) -> dict:
+        if request_id is None:
+            request_id = str(uuid4())
+        if not isinstance(request_id, str) or not request_id.strip():
+            raise ValueError("request_id must be a non-empty string")
+        body = {"request_id": request_id}
+        if source is not None:
+            body["task"] = load_task(source)
+        for key, value in dict(
+            task_ref=task_ref,
+            profile_name=profile_name,
+            profile_version=profile_version,
+            profile_sha256=profile_sha256,
+            profile_overrides=profile_overrides,
+            seed=seed,
+            execution=execution,
+        ).items():
+            if value is not None:
+                body[key] = dict(value) if isinstance(value, Mapping) else value
+        if profile is not None:
+            body["profile"] = dict(profile)
+        logger.info("task.submitting")
+        try:
+            trial = self._server.submit_task(body)
+        except Exception as exc:
+            logger.warning("task.submit_failed error_type=%s", type(exc).__name__)
+            raise
+        logger.info("task.submitted trial_id=%s", trial["trial_id"])
+        return trial
+
+    def snapshot(self, trial_id: str) -> dict:
+        return self._server.get_task_snapshot(trial_id)
+
+    def status(self, trial_id: str) -> dict:
+        return self._server.get_task_run(trial_id)
+
+    def result(self, trial_id: str) -> dict:
+        return self._server.get_task_result(trial_id)
+
+    def stop(self, trial_id: str) -> dict:
+        return self._server.stop_task(trial_id)
+
+    def wait(
+        self, trial_id: str, *, timeout: float = 30, poll_interval: float = 0.05
+    ) -> dict:
+        if not math.isfinite(timeout) or timeout < 0:
+            raise ValueError("timeout must be finite and non-negative")
+        if not math.isfinite(poll_interval) or poll_interval <= 0:
+            raise ValueError("poll_interval must be finite and positive")
+        logger.info("task.wait_started trial_id=%s timeout_sec=%s", trial_id, timeout)
+        deadline = time.monotonic() + timeout
+        previous_status = None
+        while True:
+            trial = self.status(trial_id)
+            if trial["status"] != previous_status:
+                logger.debug(
+                    "task.status_changed trial_id=%s status=%s",
+                    trial_id,
+                    trial["status"],
+                )
+                previous_status = trial["status"]
+            if trial["status"] in {"succeeded", "failed", "cancelled"}:
+                logger.info(
+                    "task.wait_finished trial_id=%s status=%s",
+                    trial_id,
+                    trial["status"],
+                )
+                return trial
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                logger.warning(
+                    "task.wait_timed_out trial_id=%s timeout_sec=%s", trial_id, timeout
+                )
+                raise TimeoutError(f"trial {trial_id} did not finish within {timeout}s")
+            time.sleep(min(poll_interval, remaining))
+
+
+class Profiles:
+    """Thin facade over the service's public profile management API."""
+
+    def __init__(self, server: ProfileService) -> None:
+        self._server = server
+
+    def init(self, root: str | Path) -> dict:
+        return self._server.init_repository(root)
+
+    def put(self, spec: Mapping) -> dict:
+        return self._server.put_profile(dict(spec))
+
+    create = put
+
+    def get(self, name: str, version: str | None = None) -> dict:
+        return self._server.get_profile(name, version)
+
+    def list(self, **kwargs) -> dict:
+        return self._server.list_profiles(**kwargs)
+
+    def resolve(self, name, version=None, expected_sha256=None):
+        return self._server.resolve_profile(name, version, expected_sha256)
+
+    def set_default(self, name, version, *, expected_version):
+        return self._server.set_default_profile(
+            name, version, expected_version=expected_version
+        )
+
+    def archive(self, name, version):
+        return self._server.archive_profile(name, version)
+
+    def export(self, name, version):
+        return self._server.export_profile(name, version)
+
+    def import_spec(self, raw: bytes, *, name=None, version=None):
+        return self._server.import_profile(raw, name=name, version=version)
+
+
+class Jobs:
+    def __init__(self, server):
+        self._server = server
+
+    def submit(self, dataset, *, request_id=None, attempts=1, namespace=None,
+               config=None, split=None, revision=None, **options):
+        selection = {key: value for key, value in dict(namespace=namespace, config=config,
+                                                      split=split, revision=revision).items() if value is not None}
+        if isinstance(dataset, str):
+            name, version = dataset, None
+            if "@" in dataset:
+                name, version = dataset.rsplit("@", 1)
+            if not name.strip() or name != name.strip() or (version is not None and not version.strip()):
+                raise ValueError("dataset must be a non-empty name or name@version")
+            selector = {"name": name, **selection}
+            if version is not None:
+                selector["version"] = version
+            source = {"dataset": selector}
+        elif isinstance(dataset, Mapping):
+            if selection:
+                raise ValueError("selection options require a dataset name; fixed references already freeze members")
+            source = {"dataset_ref": dict(dataset)}
+        else:
+            raise ValueError("dataset must be a fixed reference, name or name@version")
+        # Resolve on the platform after its request_id check, so a retry retains
+        # its first frozen snapshot even when the source/default has changed.
+        return self._server.submit_job({"request_id": request_id if request_id is not None else str(uuid4()),
+                                        **source, "attempts": attempts, **options})
+
+    def status(self, job_id):
+        return self._server.get_job(job_id)
+
+    def result(self, job_id):
+        return self._server.get_job_result(job_id)
+
+    def list(self, **kwargs):
+        return self._server.list_jobs(**kwargs)
+
+    def stop(self, job_id):
+        return self._server.stop_job(job_id)
+
+    def wait(self, job_id, *, timeout=600, poll_interval=.1):
+        if not math.isfinite(timeout) or timeout < 0:
+            raise ValueError("timeout must be finite and non-negative")
+        if not math.isfinite(poll_interval) or poll_interval <= 0:
+            raise ValueError("poll_interval must be finite and positive")
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.status(job_id)
+            if job["status"] in {"completed", "failed", "cancelled"}:
+                return job
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError("job did not reach a terminal state")
+            time.sleep(min(poll_interval, remaining))
+
+
+class Client:
+    """A client for a caller-owned service, or use local() for an owned server."""
+
+    def __init__(self, server: RpcService) -> None:
+        from .train import Train
+
+        self.train = Train(server)
+        self.tasks = Tasks(server)
+        self.profiles = Profiles(server)
+        self.jobs = Jobs(server)
+        self._owned_server = None
+
+    @classmethod
+    def remote(cls, api_url=None, *, timeout=30, api_key=None, workspace_id=None):
+        from .http import HttpService
+
+        return cls(HttpService(api_url, timeout, api_key=api_key, workspace_id=workspace_id))
+
+    @classmethod
+    def local(
+        cls,
+        *,
+        work_dir: str | Path | None = None,
+        repository_root: str | Path | None = None,
+        repository_commit: str | None = None,
+    ):
+        try:
+            from env_platform import LocalServer
+            from env_platform.executor import LocalExecutor
+        except ImportError as exc:
+            raise ImportError(
+                "Client.local() requires EnvPlatform; install its local checkout first"
+            ) from exc
+        server = LocalServer(
+            executor=LocalExecutor(base_dir=work_dir, logs_dir=Path.cwd() / "logs"),
+            repository_root=repository_root,
+            repository_commit=repository_commit,
+        )
+        client = cls(server=server)
+        client._owned_server = server
+        return client
+
+    @staticmethod
+    def init_repository(root: str | Path) -> None:
+        """Explicitly initialize the repository-local registry, without changing Git."""
+        with Client.local() as client:
+            client.profiles.init(root)
+
+    def close(self) -> None:
+        if self._owned_server is not None:
+            self._owned_server.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, traceback):
+        self.close()

el_cli/http.py

@@ -0,0 +1,115 @@
+"""Bounded Bearer HTTPS transport with trusted loopback development support."""
+
+import base64
+import json
+import math
+import os
+import re
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode, urlsplit
+from urllib.request import HTTPRedirectHandler, ProxyHandler, Request, build_opener
+
+
+class RemoteError(RuntimeError):
+    def __init__(self, code, status_code=None):
+        self.code = code
+        self.status_code = status_code
+        super().__init__(code)
+
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, request, response, code, message, headers, new_url):
+        return None
+
+
+class HttpService:
+    def __init__(self, base_url=None, timeout=30, *, api_key=None, workspace_id=None):
+        if base_url is None:
+            base_url = os.environ.get("ENVLOOP_BASE_URL", os.environ.get("ENVPLATFORM_API_URL"))
+        if not isinstance(base_url, str) or not base_url:
+            raise ValueError("Remote API URL is required; set ENVLOOP_BASE_URL or pass api_url")
+        url = urlsplit(base_url)
+        if (not url.hostname or (url.scheme != "https" and not (url.scheme == "http" and url.hostname in {"localhost", "127.0.0.1", "::1"}))
+                or url.username or url.password or url.query or url.fragment
+                or url.path not in {"", "/", "/v1", "/v1/", "/api", "/api/", "/api/v1", "/api/v1/"}):
+            raise ValueError("remote mode requires HTTPS or loopback HTTP without URL credentials")
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("HTTP timeout must be finite and positive")
+        key = os.environ.get("ENVLOOP_API_KEY") if api_key is None else api_key
+        if key is None and url.hostname not in {"localhost", "127.0.0.1", "::1"}:
+            raise ValueError("Remote HTTPS requires an API key")
+        workspace = os.environ.get("ENVLOOP_WORKSPACE_ID") if workspace_id is None else workspace_id
+        self.headers = {"Content-Type": "application/json", "User-Agent": "envloop/0.1"}
+        if key is not None:
+            if not isinstance(key, str) or not re.fullmatch(r"[A-Za-z0-9._~-]{1,512}", key):
+                raise ValueError("Invalid API key format")
+            self.headers["Authorization"] = f"Bearer {key}"
+        if workspace is not None:
+            if not isinstance(workspace, str) or not re.fullmatch(r"[A-Za-z0-9_-]{1,128}", workspace):
+                raise ValueError("Invalid workspace ID")
+            self.headers["X-Workspace-ID"] = workspace
+        self.base = base_url.rstrip("/").removesuffix("/v1")
+        self.timeout = timeout
+        self.opener = build_opener(ProxyHandler({}), NoRedirect())
+
+    def request(self, method, path, body=None):
+        request = Request(self.base + path,
+                          data=json.dumps(body, allow_nan=False).encode() if body is not None else None,
+                          headers=self.headers, method=method)
+        try:
+            with self.opener.open(request, timeout=self.timeout) as response:
+                raw = response.read(16 * 1024 * 1024 + 1)
+                if len(raw) > 16 * 1024 * 1024:
+                    raise RemoteError("RESPONSE_TOO_LARGE")
+                return json.loads(raw)
+        except HTTPError as error:
+            try:
+                data = json.loads(error.read(8192))
+                code = data.get("code", "HTTP_ERROR")
+                if not isinstance(code, str) or len(code) > 128 or not all(character.isupper() or character.isdigit() or character == "_" for character in code):
+                    code = "HTTP_ERROR"
+            except (ValueError, UnicodeError):
+                code = "HTTP_ERROR"
+            raise RemoteError(code, error.code) from None
+        except (URLError, TimeoutError, OSError):
+            raise RemoteError("NETWORK_ERROR") from None
+        except (ValueError, UnicodeError):
+            raise RemoteError("INVALID_RESPONSE") from None
+
+    def resolve_dataset(self, name, version):
+        encoded = base64.urlsafe_b64encode(name.encode()).decode().rstrip("=")
+        page = self.request("GET", f"/v1/datasets/{encoded}/versions?{urlencode({'version': version})}")
+        matches = [item for item in page["items"] if item["name"] == name and item["version"] == version]
+        if len(matches) != 1:
+            raise RemoteError("DATASET_REVISION_NOT_FOUND", 404)
+        return {"kind": "dataset", **{key: matches[0][key] for key in ("name", "version", "manifest_sha256")}}
+
+    def submit_job(self, body):
+        return self.request("POST", "/v1/jobs", body)
+
+    def get_job(self, job_id):
+        return self.request("GET", f"/v1/jobs/{quote(job_id, safe='')}")
+
+    def get_job_result(self, job_id):
+        return self.request("GET", f"/v1/jobs/{quote(job_id, safe='')}/result")
+
+    def list_jobs(self, **kwargs):
+        return self.request("GET", "/v1/jobs?" + urlencode({key: value for key, value in kwargs.items() if value is not None}))
+
+    def stop_job(self, job_id):
+        return self.request("POST", f"/v1/jobs/{quote(job_id, safe='')}/stop")
+
+    def submit_task(self, body):
+        return self.request("POST", "/v1/tasks", body)
+
+    def get_task_run(self, trial_id):
+        return self.request("GET", f"/v1/trials/{quote(trial_id, safe='')}")
+
+    def get_task_result(self, trial_id):
+        return self.request("GET", f"/v1/trials/{quote(trial_id, safe='')}/result")
+
+    def get_task_snapshot(self, trial_id):
+        return self.request("GET", f"/v1/trials/{quote(trial_id, safe='')}/snapshot")
+
+    def stop_task(self, trial_id):
+        return self.request("POST", f"/v1/trials/{quote(trial_id, safe='')}/stop")

el_cli/train.py

@@ -0,0 +1,53 @@
+"""Read independent Train Jobs, checkpoint metadata and estimated billing."""
+
+from urllib.parse import quote, urlencode
+
+
+class Train:
+    def __init__(self, service):
+        self._service = service
+
+    def jobs(self, *, status=None, cursor=None, limit=25):
+        return self._get('/v1/train/jobs', status=status, cursor=cursor, limit=limit)
+
+    def status(self, train_job_id):
+        return self._get('/v1/train/jobs/' + quote(train_job_id, safe=''))
+
+    def checkpoints(self, *, session_id=None, run_id=None, limit=25):
+        return self._get('/v1/train/checkpoints', session_id=session_id, run_id=run_id, limit=limit)
+
+    def billing(self, starting_on, ending_before):
+        return self._get('/v1/train/billing/usage', starting_on=starting_on, ending_before=ending_before)
+
+    def _get(self, path, **query):
+        query = {key: value for key, value in query.items() if value is not None}
+        return self._service.request('GET', path + ('?' + urlencode(query) if query else ''))
+
+
+def register(groups):
+    commands = groups.add_parser('train', help='Read platform training resources').add_subparsers(dest='train_group', required=True)
+    jobs = commands.add_parser('job').add_subparsers(dest='action', required=True)
+    listing = jobs.add_parser('list')
+    listing.add_argument('--status')
+    listing.add_argument('--cursor')
+    listing.add_argument('--limit', type=int, default=25)
+    jobs.add_parser('status').add_argument('train_job_id')
+    checkpoints = commands.add_parser('checkpoint').add_subparsers(dest='action', required=True)
+    listing = checkpoints.add_parser('list')
+    listing.add_argument('--session-id')
+    listing.add_argument('--run-id')
+    listing.add_argument('--limit', type=int, default=25)
+    billing = commands.add_parser('billing').add_subparsers(dest='action', required=True)
+    usage = billing.add_parser('usage')
+    usage.add_argument('starting_on')
+    usage.add_argument('ending_before')
+
+
+def execute(train, args):
+    if args.train_group == 'job':
+        if args.action == 'status':
+            return train.status(args.train_job_id)
+        return train.jobs(status=args.status, cursor=args.cursor, limit=args.limit)
+    if args.train_group == 'checkpoint':
+        return train.checkpoints(session_id=args.session_id, run_id=args.run_id, limit=args.limit)
+    return train.billing(args.starting_on, args.ending_before)

el_cli/utils/__init__.py

@@ -0,0 +1 @@
+"""Project utilities."""

el_cli/utils/logging.py

@@ -0,0 +1,30 @@
+"""Named standard-library loggers; configure explicitly at application boundaries."""
+import logging
+import os
+
+NAMESPACE = 'envloop'
+LOG_FORMAT = '%(asctime)s %(levelname)s %(name)s %(message)s'
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    if not name:
+        name = NAMESPACE
+    elif name != NAMESPACE and not name.startswith(NAMESPACE + "."):
+        name = NAMESPACE + "." + name
+    return logging.getLogger(name)
+
+
+def configure_logging(level: str | int | None = None, *, console: bool = True) -> logging.Logger:
+    """Configure this namespace; preserve host handlers and avoid duplicate output.
+
+    pytest supplies its own handlers, so its startup uses console=False.
+    """
+    if level is None:
+        level = os.environ.get('ENVLOOP_LOG_LEVEL', "INFO")
+    if isinstance(level, str):
+        level = level.upper()
+    logger = get_logger()
+    logger.setLevel(level)
+    if console:
+        logging.basicConfig(level=level, format=LOG_FORMAT, datefmt="%H:%M:%S")
+    return logger

envloop_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: envloop-cli
+Version: 0.1.0
+Summary: Standalone el command-line client for EnvLoop
+Project-URL: Repository, https://github.com/EnvLoop/envloop
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# envloop-cli
+
+Independent Python 3.11+ project providing the existing `el` CLI, version 0.1.0.
+It builds and installs without the envloop SDK checkout or any third-party runtime
+dependencies. The distribution is `envloop-cli`; its private implementation package
+is `el_cli`, so it does not overwrite the `envloop` SDK namespace.
+
+After publication:
+
+```bash
+pip install envloop-cli==0.1.0
+el --help
+el train --help
+el --api-url https://api.envloop.ai --workspace-id YOUR_WORKSPACE train job list
+```
+
+Set `ENVLOOP_API_KEY` privately in your environment. Existing command names,
+arguments, JSON output, error codes and `envloop/0.1` User-Agent are preserved.
+Local Task/Profile commands still require a separately installed compatible
+EnvPlatform, just as before; this package does not bundle an execution backend.
+No Tinker SDK, GPU, Docker or EnvHub dependencies are needed for remote queries.
+
+## Boundary and layout
+
+```text
+el-cli/
+  pyproject.toml
+  src/el_cli/
+    __init__.py
+    cli.py
+    client.py
+    http.py
+    train.py
+    utils/{__init__,logging}.py
+  tests/
+```
+
+The actual source has `envloop/cli.py` and `envloop/train.py`, rather than the
+`cli/commands/train.py` layout in the brief. `cli.py` imports Client and Train;
+Client uses the logging helper and lazily loads HttpService and Train. All use
+the standard library. Client also lazily imports EnvPlatform for local execution.
+Retaining Client preserves existing task/job/profile behavior rather than shipping
+a train-only CLI. These modules were extracted from the training-read CLI at
+`b546830`, based on main `11a5803`. Shared SDK/transport fixes should be applied
+to both packages while their copied implementations remain separate.
+
+The SDK keeps its Python APIs and legacy `python -m envloop.cli` interface, but
+no longer registers `el`; install this project for that executable.
+
+## Build, verify and publish
+
+From this directory:
+
+```bash
+uv sync --locked
+uv run --locked pytest -q --ignore=tests/test_jobs_http.py
+uv run --locked ruff check .
+uv build
+python -m venv /tmp/el-cli-clean
+/tmp/el-cli-clean/bin/python -m pip install dist/envloop_cli-0.1.0-py3-none-any.whl
+/tmp/el-cli-clean/bin/el --help
+/tmp/el-cli-clean/bin/el train --help
+```
+
+The real JobMaster integration cases in `tests/test_jobs_http.py` also require
+a separately installed EnvPlatform and its dependencies. Run the complete suite
+with that backend installed; the other cases need only the dev group.
+
+The workstation's Aliyun index is a download mirror, not an upload endpoint.
+No existing private upload repository or publishing credentials were found on
+2026-10-08. The intended public target is PyPI, upload endpoint
+`https://upload.pypi.org/legacy/`. Release remains unpublished until an authorized
+PyPI token (or configured Trusted Publisher) is available. Never put credentials
+in this project. With a token supplied privately as `UV_PUBLISH_TOKEN`:
+
+```bash
+uv publish --publish-url https://upload.pypi.org/legacy/ dist/*
+```
+
+Building a wheel does not establish that the PyPI name is reserved or that a
+release is available. Verify index installation after a successful upload.

envloop_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+el_cli/__init__.py,sha256=tKNGG9G2weyFSMy_qv5r-J7bjxNHfL64DgxOqgMh4Qo,46
+el_cli/cli.py,sha256=IsYeB4AM5Wh4H7iftjuQMs4GLIXhjqaMqVqhQyfgH8Q,12014
+el_cli/client.py,sha256=SBs-S5cmSxmwnchuXK-7_U1YtWLJ4UPF8uOU3ENo-QM,12459
+el_cli/http.py,sha256=lS6-j5AdbJWtljoVBhHdGIKSBRToK0DTxDpCTwrWQJo,5656
+el_cli/train.py,sha256=_cf-zdyesEw7sb7GnS63cwc6SqojhtCyfnOiMslQp3Q,2392
+el_cli/utils/__init__.py,sha256=huB3qPQuKNr3JxfH3Ys09YWFtHiDamCHFsBa4epANgQ,25
+el_cli/utils/logging.py,sha256=rXN0qyxhfGEq4vWXxjwfaczPPZf_7atnOkkBTgNNRPc,1017
+envloop_cli-0.1.0.dist-info/METADATA,sha256=3_qmML7FCwdkHSIynR5LAlkgpfMIFkHSwFyzsHAQ8tE,3376
+envloop_cli-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+envloop_cli-0.1.0.dist-info/entry_points.txt,sha256=Sbu0AsML0ujuZxVXKihrgpEchXgmiCpKrgiLzTlfg3s,39
+envloop_cli-0.1.0.dist-info/RECORD,,

envloop_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

envloop_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+el = el_cli.cli:main