envloop-cli 0.1.1__tar.gz → 0.2.0__tar.gz

envloop_cli-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+.pytest_cache/
+dist/
+/logs/
+
+# Local environment configuration is machine-specific and must not be committed.
+.env.local

envloop_cli-0.2.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: envloop-cli
+Version: 0.2.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
+Project-URL: Agent instructions, https://docs.envloop.ai/skill.md
+Requires-Python: >=3.11
+Provides-Extra: train
+Requires-Dist: tinker==0.30.2; extra == 'train'
+Description-Content-Type: text/markdown
+
+# EnvLoop CLI and Python SDK
+
+Install the public client to run agent Jobs, inspect Trials, manage training and
+checkpoints, and deploy or call inference endpoints. The `el` and `envloop`
+commands are equivalent. The Python import package is `envloop`.
+
+## Install
+
+Use a Python virtual environment:
+
+```bash
+python -m pip install envloop-cli
+el --help
+```
+
+For Python training workflows, install the optional training dependency:
+
+```bash
+python -m pip install 'envloop-cli[train]'
+python -c 'from envloop import Client, training; print("EnvLoop SDK ready")'
+```
+
+The base client uses Python's standard library. The training extra installs the
+training protocol client. You do not need a source checkout, GitHub account,
+local execution backend, Docker, or a GPU to install the client.
+
+## Connect
+
+Use an authorized EnvLoop account and project. Browser authorization:
+
+```bash
+el auth login
+el auth status --check
+```
+
+For an existing project API key, use the masked configuration wizard:
+
+```bash
+el auth config
+el auth status --check
+```
+
+CI can read credentials from `ENVLOOP_API_KEY` and connection settings from
+`ENVLOOP_BASE_URL`, `ENVLOOP_WORKSPACE_ID` and `ENVLOOP_PROJECT_ID`. Keep keys in
+your secret manager. Public API access is scoped to the authorized project.
+
+## Explore your project
+
+```bash
+el job list --limit 5
+el train list --limit 5
+el checkpoint list --limit 5
+el inference endpoint list
+```
+
+Query a returned Job ID with `el job get JOB_ID` and `el job result JOB_ID`.
+Trial commands use the spelling `trail`, for example
+`el trail artifact list TRIAL_ID`. Use each command's `--help` for options.
+
+For the Python SDK:
+
+```python
+from envloop import Client
+
+with Client.remote() as client:
+    print(client.jobs.list(limit=5))
+```
+
+Submitting work, training a model or starting inference can allocate billable
+resources. Follow the task-specific guide and retain the outputs you need before
+cleaning up temporary resources.
+
+## Existing installations
+
+This distribution provides both the CLI and the `envloop` import package. Use a
+fresh environment if you previously installed the separate source distribution
+named `envloop`, so two distributions do not own the same Python module files.
+Existing client configuration is reused; installing a package does not change
+your account permissions or move remote resources. Check `el --help` when
+upgrading because command groups may differ from your earlier installation.
+
+## Documentation
+
+- [English documentation](https://docs.envloop.ai/)
+- [中文文档](https://docs.envloop.ai/zh-cn/)
+- [Installation](https://docs.envloop.ai/cli-install)
+- [CLI reference](https://docs.envloop.ai/reference/cli)
+- [Training and deployment](https://docs.envloop.ai/training/train-deploy)
+- [Agent entry: skill.md](https://docs.envloop.ai/skill.md)

envloop_cli-0.2.0/README.pypi.md

@@ -0,0 +1,89 @@
+# EnvLoop CLI and Python SDK
+
+Install the public client to run agent Jobs, inspect Trials, manage training and
+checkpoints, and deploy or call inference endpoints. The `el` and `envloop`
+commands are equivalent. The Python import package is `envloop`.
+
+## Install
+
+Use a Python virtual environment:
+
+```bash
+python -m pip install envloop-cli
+el --help
+```
+
+For Python training workflows, install the optional training dependency:
+
+```bash
+python -m pip install 'envloop-cli[train]'
+python -c 'from envloop import Client, training; print("EnvLoop SDK ready")'
+```
+
+The base client uses Python's standard library. The training extra installs the
+training protocol client. You do not need a source checkout, GitHub account,
+local execution backend, Docker, or a GPU to install the client.
+
+## Connect
+
+Use an authorized EnvLoop account and project. Browser authorization:
+
+```bash
+el auth login
+el auth status --check
+```
+
+For an existing project API key, use the masked configuration wizard:
+
+```bash
+el auth config
+el auth status --check
+```
+
+CI can read credentials from `ENVLOOP_API_KEY` and connection settings from
+`ENVLOOP_BASE_URL`, `ENVLOOP_WORKSPACE_ID` and `ENVLOOP_PROJECT_ID`. Keep keys in
+your secret manager. Public API access is scoped to the authorized project.
+
+## Explore your project
+
+```bash
+el job list --limit 5
+el train list --limit 5
+el checkpoint list --limit 5
+el inference endpoint list
+```
+
+Query a returned Job ID with `el job get JOB_ID` and `el job result JOB_ID`.
+Trial commands use the spelling `trail`, for example
+`el trail artifact list TRIAL_ID`. Use each command's `--help` for options.
+
+For the Python SDK:
+
+```python
+from envloop import Client
+
+with Client.remote() as client:
+    print(client.jobs.list(limit=5))
+```
+
+Submitting work, training a model or starting inference can allocate billable
+resources. Follow the task-specific guide and retain the outputs you need before
+cleaning up temporary resources.
+
+## Existing installations
+
+This distribution provides both the CLI and the `envloop` import package. Use a
+fresh environment if you previously installed the separate source distribution
+named `envloop`, so two distributions do not own the same Python module files.
+Existing client configuration is reused; installing a package does not change
+your account permissions or move remote resources. Check `el --help` when
+upgrading because command groups may differ from your earlier installation.
+
+## Documentation
+
+- [English documentation](https://docs.envloop.ai/)
+- [中文文档](https://docs.envloop.ai/zh-cn/)
+- [Installation](https://docs.envloop.ai/cli-install)
+- [CLI reference](https://docs.envloop.ai/reference/cli)
+- [Training and deployment](https://docs.envloop.ai/training/train-deploy)
+- [Agent entry: skill.md](https://docs.envloop.ai/skill.md)

envloop_cli-0.2.0/envloop/__init__.py

@@ -0,0 +1,5 @@
+"""EnvLoop Python client."""
+
+from .client import Client
+
+__all__ = ["Client"]

envloop_cli-0.2.0/envloop/agent_runs.py

@@ -0,0 +1,208 @@
+"""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``...);
+this module pages through ``GET /v1/train/jobs`` and derives runs from those tags,
+using the same rules as the Console's agent runs page.
+"""
+
+from datetime import datetime
+
+from .train import TrainJobs
+
+# The generic ``agent_*`` key wins over the RSI loop's ``rsi_*`` one (the Console's rule).
+KEYS = {
+    "run": ("agent_run", "rsi_run"),
+    "round": ("agent_round", "rsi_round"),
+    "purpose": ("agent_purpose", "rsi_purpose"),
+    "method": ("agent_method", "rsi_method"),
+    "checkpoint": ("agent_checkpoint", "rsi_checkpoint"),
+}
+RUN_KEYS = KEYS["run"]  # first non-empty string wins
+ACTIVE_STATUSES = frozenset({"LAUNCHING", "STARTING", "RUNNING", "RECOVERING"})
+TERMINAL_STATUSES = frozenset({"SUCCEEDED", "FAILED", "CANCELLED"})
+PAGE_LIMIT = 100  # the platform's maximum page size
+
+
+class AgentRunError(RuntimeError):
+    """A run lookup or listing failed; ``code`` is safe to print."""
+
+    def __init__(self, code: str) -> None:
+        self.code = code
+        super().__init__(code)
+
+
+def _metadata(job) -> dict:
+    metadata = job.get("user_metadata")
+    return metadata if isinstance(metadata, dict) else {}
+
+
+def _field(job, name: str):
+    metadata = _metadata(job)
+    for key in KEYS[name]:
+        value = metadata.get(key)
+        if value is not None and value != "":
+            return value
+    return None
+
+
+def run_key(job) -> str | None:
+    """The run a Train Job belongs to, or None when it carries no run label."""
+    metadata = _metadata(job)
+    for key in RUN_KEYS:
+        value = metadata.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return None
+
+
+def _round(job) -> int | None:
+    value = _field(job, "round")
+    if isinstance(value, int) and not isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        try:
+            return int(value.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _order(job):
+    # Creation order, as the platform pages jobs (newest first, reversed here).
+    return (str(job.get("created_at") or ""), str(job.get("train_job_id") or ""))
+
+
+def _duration_sec(job) -> int | None:
+    if job.get("status") not in TERMINAL_STATUSES:
+        return None
+    try:
+        seconds = (datetime.fromisoformat(job["updated_at"])
+                   - datetime.fromisoformat(job["created_at"])).total_seconds()
+    except (KeyError, TypeError, ValueError):
+        return None
+    return round(seconds) if seconds >= 0 else None
+
+
+def _checkpoint(job) -> dict | None:
+    """The checkpoint a job produced: its agent's version name and platform path."""
+    stored = job.get("checkpoint")
+    path = stored.get("path") if isinstance(stored, dict) else None
+    name = _field(job, "checkpoint")
+    if not isinstance(path, str) or not path:
+        return None
+    return {"name": name, "path": path}
+
+
+def _job_view(job) -> dict:
+    metadata = _metadata(job)
+    return {
+        "train_job_id": job.get("train_job_id"),
+        "status": job.get("status"),
+        "round": _round(job),
+        "purpose": _field(job, "purpose"),
+        "method": _field(job, "method"),
+        "transitions": list(job.get("transitions") or []),
+        "created_at": job.get("created_at"),
+        "updated_at": job.get("updated_at"),
+        "duration_sec": _duration_sec(job),
+        "base_model": job.get("base_model"),
+        "lora_rank": job.get("lora_rank"),
+        "model_id": job.get("model_id"),
+        "checkpoint": _checkpoint(job),
+        "user_metadata": metadata,
+    }
+
+
+def _summary(run: str, jobs: list) -> dict:
+    """Summarize one run's jobs, given in creation order."""
+    latest = jobs[-1]
+    if any(job.get("status") in ACTIVE_STATUSES for job in jobs):
+        status = "running"
+    else:
+        status = str(latest.get("status") or "unknown").lower()
+    succeeded = [job for job in jobs if job.get("status") == "SUCCEEDED"]
+    latest_saved = next((job for job in reversed(jobs) if _checkpoint(job) is not None), None)
+    latest_checkpoint = _checkpoint(latest_saved) if latest_saved is not None else None
+    if latest_checkpoint is not None:
+        latest_checkpoint["train_job_id"] = latest_saved.get("train_job_id")
+    rounds = [number for number in map(_round, jobs) if number is not None]
+    activity = [stamp for job in jobs if isinstance(stamp := job.get("updated_at") or job.get("created_at"), str)]
+    return {
+        "run": run,
+        "agent": _metadata(latest).get("source"),
+        "status": status,
+        "latest_round": max(rounds, default=None),
+        "trainings": {"succeeded": len(succeeded), "total": len(jobs)},
+        "latest_checkpoint": latest_checkpoint,
+        "base_model": latest.get("base_model"),
+        "created_at": jobs[0].get("created_at"),
+        "updated_at": max(activity, default=None),
+    }
+
+
+def _detail(run: str, jobs: list) -> dict:
+    views = [_job_view(job) for job in jobs]
+    rounds: dict = {}
+    for view in views:
+        rounds.setdefault(view["round"], []).append(view)
+    ordered = sorted(rounds, key=lambda number: (number is None, number or 0))
+    checkpoints = [
+        {**view["checkpoint"], "round": view["round"], "train_job_id": view["train_job_id"],
+         "created_at": view["created_at"]}
+        for view in views if view["checkpoint"] is not None
+    ]
+    return {
+        **_summary(run, jobs),
+        "rounds": [{"round": number, "jobs": rounds[number]} for number in ordered],
+        "checkpoints": checkpoints,
+    }
+
+
+class AgentRuns:
+    """Read-only agent runs derived from the visible Train Jobs listing."""
+
+    def __init__(self, train_jobs: TrainJobs) -> None:
+        self._train_jobs = train_jobs
+
+    def _runs(self):
+        jobs, ids, seen, cursor, observed_at = [], set(), set(), None, None
+        while True:
+            page = self._train_jobs.list(cursor=cursor, limit=PAGE_LIMIT)
+            if observed_at is None:
+                observed_at = page.get("observed_at")
+            for job in page.get("items") or []:
+                job_id = job.get("train_job_id") if isinstance(job, dict) else None
+                if not isinstance(job, dict) or job_id in ids:
+                    continue
+                if job_id is not None:
+                    ids.add(job_id)
+                jobs.append(job)
+            cursor = page.get("next_cursor")
+            if cursor is None:
+                break
+            if cursor in seen:
+                raise AgentRunError("TRAIN_JOB_CURSOR_REPEATED")
+            seen.add(cursor)
+        runs: dict = {}
+        for job in jobs:
+            key = run_key(job)
+            if key is not None:
+                runs.setdefault(key, []).append(job)
+        for group in runs.values():
+            group.sort(key=_order)
+        return runs, observed_at
+
+    def list(self) -> dict:
+        """Every run, most recently updated first, as ``{"items": [...], "observed_at"}``."""
+        runs, observed_at = self._runs()
+        items = sorted((_summary(run, jobs) for run, jobs in runs.items()),
+                       key=lambda item: (item["updated_at"] or "", item["run"]), reverse=True)
+        return {"items": items, "observed_at": observed_at}
+
+    def get(self, run: str) -> dict:
+        """One run's summary, its rounds in order with their Train Jobs, and its checkpoints."""
+        runs, observed_at = self._runs()
+        if run not in runs:
+            raise AgentRunError("AGENT_RUN_NOT_FOUND")
+        return {**_detail(run, runs[run]), "observed_at": observed_at}