runwhere 0.1.0__tar.gz

runwhere-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: runwhere
+Version: 0.1.0
+Summary: RunWhere.ai CLI — GPU job management tool
+License: MIT
+Keywords: gpu,ai,cloud,cli
+Author: RunWhere.ai
+Author-email: dev@runwhere.ai
+Requires-Python: >=3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: dev
+Requires-Dist: click (>=8.0)
+Requires-Dist: httpx (>=0.27)
+Requires-Dist: pathspec (>=0.12)
+Requires-Dist: pydantic (>=2.0)
+Requires-Dist: pytest (>=8.0) ; extra == "dev"
+Requires-Dist: pytest-mock ; extra == "dev"
+Requires-Dist: pyyaml (>=6.0)
+Requires-Dist: rich (>=13.0)
+Requires-Dist: tomli-w (>=1.0)
+Requires-Dist: websockets (>=12.0)
+Project-URL: Homepage, https://runwhere.ai
+Project-URL: Repository, https://github.com/runwhere/runw
+Description-Content-Type: text/markdown
+
+# runw — RunWhere.ai CLI
+
+GPU 任务管理工具。通过 HTTP API 管理云端 GPU 资源和 AI 计算任务。
+
+## 安装
+
+```bash
+pip install -e ".[dev]"
+```
+
+## 使用
+
+```bash
+runw login --endpoint https://api.runwhere.ai
+runw sync -f train.yaml
+runw submit -f train.yaml
+runw logs <job-name> -f
+runw price summary
+runw jobs get
+runw usage
+```
+
+## 开发
+
+```bash
+pytest tests/ -v
+```
+
+## 构建
+
+```bash
+bash scripts/build.sh
+```
+

runwhere-0.1.0/README.md

@@ -0,0 +1,33 @@
+# runw — RunWhere.ai CLI
+
+GPU 任务管理工具。通过 HTTP API 管理云端 GPU 资源和 AI 计算任务。
+
+## 安装
+
+```bash
+pip install -e ".[dev]"
+```
+
+## 使用
+
+```bash
+runw login --endpoint https://api.runwhere.ai
+runw sync -f train.yaml
+runw submit -f train.yaml
+runw logs <job-name> -f
+runw price summary
+runw jobs get
+runw usage
+```
+
+## 开发
+
+```bash
+pytest tests/ -v
+```
+
+## 构建
+
+```bash
+bash scripts/build.sh
+```

runwhere-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "runwhere"
+version = "0.1.0"
+description = "RunWhere.ai CLI — GPU job management tool"
+authors = [
+    {name = "RunWhere.ai", email = "dev@runwhere.ai"}
+]
+license = {text = "MIT"}
+readme = {file = "README.md", content-type = "text/markdown"}
+keywords = ["gpu", "ai", "cloud", "cli"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "click>=8.0",
+    "httpx>=0.27",
+    "rich>=13.0",
+    "pydantic>=2.0",
+    "tomli-w>=1.0",
+    "websockets>=12.0",
+    "pyyaml>=6.0",
+    "pathspec>=0.12",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-mock",
+]
+
+[project.urls]
+Homepage = "https://runwhere.ai"
+Repository = "https://github.com/runwhere/runw"
+
+[project.scripts]
+runw = "runw.cli.main:main"
+
+[tool.poetry]
+packages = [{include = "runw", from = "src"}]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"

runwhere-0.1.0/src/runw/__init__.py

@@ -0,0 +1,3 @@
+"""RunWhere.ai CLI — GPU job management tool."""
+
+__version__ = "0.1.0"

runwhere-0.1.0/src/runw/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m runw`."""
+
+from runw.cli.main import main
+
+main()

runwhere-0.1.0/src/runw/cli/auth.py

@@ -0,0 +1,64 @@
+"""Auth commands: login, whoami."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from runw.client.base import BaseClient
+from runw.config.store import ConfigStore
+from runw.output import console
+
+
+@click.command()
+@click.option("--endpoint", required=True, help="API 服务地址")
+@click.pass_context
+def login(ctx: click.Context, endpoint: str) -> None:
+    """登录 RunWhere.ai"""
+    json_mode: bool = ctx.obj["json_mode"]
+
+    # 交互式：隐藏输入提示粘贴 API Token。
+    # 非交互（管道/CI，如 `echo $TOKEN | runw login`）：从 stdin 读，
+    # 避免 hide_input 走 getpass 读 TTY，在无终端时永久挂起。
+    if sys.stdin.isatty():
+        token = click.prompt("Token", hide_input=True)
+    else:
+        token = sys.stdin.read().strip()
+        if not token:
+            console.fatal(
+                "未提供 API Token（stdin 为空）",
+                suggestion="交互式直接运行 runw login，或 `echo <token> | runw login --endpoint <url>`",
+            )
+
+    store = ConfigStore()
+    store.save(endpoint=endpoint, token=token)
+
+    console.success(f"登录成功（endpoint: {endpoint}）", json_mode=json_mode)
+
+
+@click.command()
+@click.pass_context
+def whoami(ctx: click.Context) -> None:
+    """查看当前登录用户"""
+    json_mode: bool = ctx.obj["json_mode"]
+
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录", suggestion="请先执行 runw login --endpoint <URL>")
+
+    client = BaseClient(store)
+    data = client.get("/api/v1/auth/me")
+
+    # /auth/me 返回 UserInfo：username 可能为空，身份回退到 phone；
+    # org 字段实际叫 current_org_id（旧代码取 "org" 永远空）。
+    user = data.get("username") or data.get("phone") or f"user#{data.get('id', '')}"
+    # PRD §1：whoami 输出「当前用户 + workspace 地址」。workspace = 登录 endpoint。
+    console.output(
+        {
+            "user": user,
+            "org_id": data.get("current_org_id", ""),
+            "workspace": store.endpoint or "",
+        },
+        json_mode=json_mode,
+    )

runwhere-0.1.0/src/runw/cli/explain.py

@@ -0,0 +1,159 @@
+"""--explain 实现：列出平台自动填充的默认值与来源（spec 027 FR-011 / SC-005）。
+
+设计：CLI 端预演平台填充规则（与 backend job_orchestrator.fill_defaults 对齐），
+给用户在提交前完整透明的可解释视图。
+
+输出条目格式：
+- name: 字段路径（如 environment.command）
+- value: 填充后的值
+- source: "user_yaml" / "platform_default" / "auto_pricing" / "computed"
+- reason: 为什么填这个值（人类可读）
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class FillEntry:
+    name: str
+    value: Any
+    source: str  # user_yaml / platform_default / auto_pricing / computed
+    reason: str
+
+
+# 平台默认填充规则——与 backend manifest_builder.build_platform_env_vars 对齐
+# 当用户 YAML 未指定时填充
+DEFAULT_RULES: list[dict[str, Any]] = [
+    {
+        "name": "kind",
+        "default": "Training",
+        "reason": "未指定 kind 时默认 Training（spec PRD-runw §6）",
+    },
+    {
+        "name": "resources.gpuNum",
+        "default": 1,
+        "reason": "未指定 gpuNum 时默认 1 卡",
+    },
+    {
+        "name": "environment.command",
+        "default": "python main.py",
+        "reason": "未指定 command 时默认 `python main.py`（用户应在 YAML 显式指定）",
+    },
+]
+
+
+# 平台自动注入的 env（spec PRD-workload §6 + spec 031 Wandb）
+PLATFORM_INJECTED_ENVS: list[dict[str, str]] = [
+    {
+        "name": "RUNW_JOB_ID",
+        "reason": "由 backend 生成，注入到 Pod 用于关联日志/指标",
+    },
+    {
+        "name": "RUNW_JOB_NAME",
+        "reason": "用户 YAML 中 job.name",
+    },
+    {
+        "name": "RUNW_ORG_ID",
+        "reason": "当前 token 的 org",
+    },
+    {
+        "name": "RUNW_USER_ID",
+        "reason": "当前用户",
+    },
+    {
+        "name": "RUNW_NPROC_PER_NODE",
+        "reason": "Training 任务自动设为 gpuNum（torch.distributed 用）",
+    },
+    {
+        "name": "NCCL_TIMEOUT=1800",
+        "reason": "防止 NCCL 通信超时崩溃（30 分钟）",
+    },
+    {
+        "name": "TORCH_NCCL_ASYNC_ERROR_HANDLING=1",
+        "reason": "PyTorch NCCL 异常异步处理",
+    },
+    {
+        "name": "NCCL_DEBUG=WARN",
+        "reason": "NCCL 调试输出限制为 WARN 级别",
+    },
+    {
+        "name": "WANDB_BASE_URL / WANDB_API_KEY / WANDB_ENTITY / WANDB_PROJECT",
+        "reason": "spec 031 — Org 注册时自动建 Wandb 账号，submit 时注入；YAML 设 environment.wandb_external=true 可禁用",
+    },
+]
+
+
+def compute_fill_entries(spec_dict: dict[str, Any]) -> list[FillEntry]:
+    """对照 DEFAULT_RULES 计算用户 YAML 哪些字段是平台填充的。"""
+    entries: list[FillEntry] = []
+
+    for rule in DEFAULT_RULES:
+        name = rule["name"]
+        path = name.split(".")
+        cur: Any = spec_dict
+        present = True
+        for p in path:
+            if not isinstance(cur, dict) or p not in cur or cur[p] is None:
+                present = False
+                break
+            cur = cur[p]
+
+        if present:
+            entries.append(
+                FillEntry(
+                    name=name, value=cur, source="user_yaml",
+                    reason="用户 YAML 显式指定",
+                )
+            )
+        else:
+            entries.append(
+                FillEntry(
+                    name=name, value=rule["default"],
+                    source="platform_default", reason=rule["reason"],
+                )
+            )
+    return entries
+
+
+def render_explain(
+    spec_dict: dict[str, Any],
+    *,
+    json_mode: bool = False,
+) -> dict[str, Any] | None:
+    """渲染 --explain 输出。json_mode=True 返回 dict 供 console.output；
+    否则直接打印到 stderr 并返回 None。
+    """
+    entries = compute_fill_entries(spec_dict)
+
+    payload: dict[str, Any] = {
+        "explain": {
+            "fields": [
+                {
+                    "name": e.name,
+                    "value": e.value,
+                    "source": e.source,
+                    "reason": e.reason,
+                }
+                for e in entries
+            ],
+            "platform_envs": PLATFORM_INJECTED_ENVS,
+        }
+    }
+
+    if json_mode:
+        return payload
+
+    from runw.output import console
+
+    console.info("─── 平台默认值填充过程（--explain）───")
+    for e in entries:
+        marker = "·" if e.source == "user_yaml" else "+"
+        console.info(f"  {marker} {e.name} = {e.value}  [{e.source}] — {e.reason}")
+    console.info("─── 自动注入的环境变量 ───")
+    for env in PLATFORM_INJECTED_ENVS:
+        console.info(f"  + {env['name']}  — {env['reason']}")
+    console.info("───────────────────────────────")
+    return None

runwhere-0.1.0/src/runw/cli/jobs.py

@@ -0,0 +1,279 @@
+"""作业管理命令（PRD 对齐：动词在前）。
+
+PRD §7/§8/§11 命令形：
+  runw get jobs [--kind] [--status]   列出作业
+  runw get usage [--from] [--to]      用量与费用
+  runw describe job <name>            作业详情
+  runw stop job <name>               停止作业（保留 checkpoint，释放 GPU）
+  runw delete job <name> [--force]   删除作业记录
+"""
+
+from __future__ import annotations
+
+import click
+
+from runw.client.api_client import ApiClient
+from runw.config.store import ConfigStore
+from runw.output import console
+
+
+def _format_duration(seconds: int | float) -> str:
+    if not seconds:
+        return "-"
+    s = int(seconds)
+    if s < 60:
+        return f"{s}s"
+    if s < 3600:
+        return f"{s // 60}m {s % 60}s"
+    h = s // 3600
+    m = (s % 3600) // 60
+    return f"{h}h {m}m"
+
+
+def _fnum(value: object, prec: int = 1) -> str:
+    """数值格式化（容错）。后端 JSON 把 Decimal 序列化成**字符串**（如 "0.0000"），
+    直接 `:.1f` 会 ValueError 崩 → `runw get jobs`/`get usage` 整条命令挂。先 float 兜底。"""
+    try:
+        return f"{float(value):,.{prec}f}"  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return str(value)
+
+
+# 配额资源类型 → 展示名（与后端 quota_service.PLAN_QUOTAS 的 key 对齐）
+_QUOTA_LABELS = {
+    "inference": "推理服务",
+    "notebook": "Notebook",
+    "training": "训练作业",
+}
+
+_CLOUD_BILL_NOTE_FALLBACK = "GPU、存储等云资源费用由您的云账户直接结算，请前往云厂商费用中心查看"
+
+
+# ══════════════════ get 组（get jobs / get usage）══════════════════
+
+
+@click.group()
+@click.pass_context
+def get(ctx: click.Context) -> None:
+    """查询资源（jobs / usage）"""
+    pass
+
+
+@get.command("jobs")
+@click.option("--status", default=None, help="按状态筛选（running/stopped/failed）")
+@click.option("--kind", default=None, help="按类型筛选（Training/Inference/Notebook）")
+@click.pass_context
+def get_jobs(ctx: click.Context, status: str | None, kind: str | None) -> None:
+    """列出所有作业"""
+    json_mode: bool = ctx.obj["json_mode"]
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录", suggestion="请先执行 runw login")
+        return
+
+    client = ApiClient(store)
+    data = client.get_jobs(status=status, kind=kind)
+    job_list = data.get("data", []) if isinstance(data, dict) else data
+
+    if json_mode:
+        console.output(data if isinstance(data, dict) else {"data": job_list}, json_mode=True)
+        return
+
+    if not job_list:
+        console.info("暂无作业")
+        return
+
+    # 边界（2026-07-10，PRD §8）：不展示云账单估算列——平台不替云厂商报钱
+    columns = ["名称", "类型", "状态", "GPU", "运行时长", "URL"]
+    rows = []
+    for j in job_list:
+        gpu_info = f"{j.get('gpu_count', 1)}×{j.get('gpu_type', '?')}"
+        elapsed = _format_duration(j.get("elapsed_seconds", 0))
+        rows.append([
+            j.get("name", j.get("gpuctl_job_id", "")),
+            j.get("job_type", j.get("kind", "")),
+            j.get("status", ""),
+            gpu_info,
+            elapsed,
+            j.get("url") or "-",  # 推理/Notebook 访问地址；训练无
+        ])
+    console.table(columns, rows)
+
+
+@get.command("usage")
+@click.option("--from", "from_date", default=None, help="起始日期 YYYY-MM-DD")
+@click.option("--to", "to_date", default=None, help="结束日期 YYYY-MM-DD")
+@click.pass_context
+def get_usage(ctx: click.Context, from_date: str | None, to_date: str | None) -> None:
+    """查看用量与平台账单（配额占用 + GPU 时长 + 订阅/超额）"""
+    json_mode: bool = ctx.obj["json_mode"]
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录", suggestion="请先执行 runw login")
+        return
+
+    client = ApiClient(store)
+    data = client.get_usage(from_date=from_date, to_date=to_date)
+
+    if json_mode:
+        console.output(data, json_mode=True)
+        return
+
+    # 边界（2026-07-10，PRD §8）：只报事实（配额/时长/平台账单），
+    # 云侧金额不估算不展示——指路云厂商费用中心。
+    period = data.get("period", {})
+    summary = data.get("summary", {})
+
+    console.success(f"{period.get('from_date', '')} ~ {period.get('to_date', '')} 用量\n")
+
+    # 配额使用（并发数量制：在用 X / 上限 Y）
+    quota = data.get("quota", [])
+    if quota:
+        plan = data.get("plan", "free")
+        console.info(f"配额使用（{plan} 套餐）")
+        for q in quota:
+            label = _QUOTA_LABELS.get(q.get("resource_type", ""), q.get("resource_type", ""))
+            current = q.get("current", 0)
+            limit = q.get("limit")
+            usage = f"{current}（不限）" if limit is None else f"{current} / {limit}"
+            console.info(f"  {label}: {usage}")
+        console.info("")
+
+    # 资源用量（分型号 GPU 时长——超额计费的事实依据）
+    total_hours = summary.get("total_gpu_hours", 0)
+    if total_hours:
+        console.info(f"资源用量：GPU·小时 {_fnum(total_hours, 1)} hr")
+        for g in data.get("gpu_usage", []):
+            console.info(f"  {g.get('gpu_type', '')}: {_fnum(g.get('gpu_hours', 0), 1)} h")
+        console.info("")
+    else:
+        console.info("本期暂无 GPU 用量\n")
+
+    # 平台账单（RunWhere 实际出账：订阅 + 超额）——本命令的核心
+    platform_bill = data.get("platform_bill", {})
+    if platform_bill:
+        console.info("平台账单（RunWhere 出账）")
+        console.info(f"  订阅已摊销:   ¥{_fnum(platform_bill.get('subscription', 0), 2)}")
+        console.info(f"  超额预估:     ¥{_fnum(platform_bill.get('overage', 0), 2)}")
+        console.info(f"  本期平台账单: ¥{_fnum(platform_bill.get('total', 0), 2)}\n")
+
+    console.info(data.get("cloud_bill_note") or _CLOUD_BILL_NOTE_FALLBACK)
+
+
+# ══════════════════ describe 组（describe job）══════════════════
+
+
+@click.group()
+@click.pass_context
+def describe(ctx: click.Context) -> None:
+    """查看资源详情（job）"""
+    pass
+
+
+@describe.command("job")
+@click.argument("job_name")
+@click.pass_context
+def describe_job(ctx: click.Context, job_name: str) -> None:
+    """查看作业详情"""
+    json_mode: bool = ctx.obj["json_mode"]
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录")
+        return
+
+    client = ApiClient(store)
+    data = client.describe_job(job_name)
+
+    if json_mode:
+        console.output(data, json_mode=True)
+        return
+
+    console.success(f"作业: {data.get('name', job_name)}")
+    console.info(f"  ID: {data.get('job_id', data.get('gpuctl_job_id', ''))}")
+    console.info(f"  类型: {data.get('job_type', data.get('kind', ''))}")
+    console.info(f"  状态: {data.get('status', '')}")
+    if data.get("url"):  # 推理/Notebook 访问地址
+        console.info(f"  URL: {data['url']}")
+
+    metrics = data.get("gpu_metrics")
+    if metrics:
+        console.info("\n  GPU 指标（运行期滚动统计）:")
+        console.info(
+            f"    利用率: 平均 {metrics.get('gpu_util_avg', 0):.1f}% / 峰值 "
+            f"{metrics.get('gpu_util_max', 0):.1f}%"
+        )
+        console.info(
+            f"    显存峰值: {metrics.get('gpu_mem_used_max_gb', 0):.1f} GB"
+        )
+        console.info(f"    温度峰值: {metrics.get('gpu_temp_max', 0):.0f} °C")
+        console.info(f"    采样数: {metrics.get('samples_count', 0)}")
+
+    if data.get("platform_defaults"):
+        console.info("\n  平台自动行为:")
+        for key, val in data["platform_defaults"].items():
+            if isinstance(val, dict):
+                console.info(f"    {key}: {val.get('value', '')}（{val.get('reason', '')}）")
+            else:
+                console.info(f"    {key}: {val}")
+
+
+# ══════════════════ stop 组（stop job）══════════════════
+
+
+@click.group()
+@click.pass_context
+def stop(ctx: click.Context) -> None:
+    """停止资源（job）"""
+    pass
+
+
+@stop.command("job")
+@click.argument("job_name")
+@click.pass_context
+def stop_job(ctx: click.Context, job_name: str) -> None:
+    """停止运行中的作业（保留 checkpoint，释放 GPU）"""
+    json_mode: bool = ctx.obj["json_mode"]
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录")
+        return
+
+    client = ApiClient(store)
+    data = client.stop_job(job_name)
+
+    if json_mode:
+        console.output(data, json_mode=True)
+    else:
+        # 边界（2026-07-10，PRD §8）：不展示云侧金额（final_cost 是内部审计口径）
+        console.success(f"作业 {job_name} 已停止，GPU 已释放，计费停止")
+
+
+# ══════════════════ delete 组（delete job）══════════════════
+
+
+@click.group()
+@click.pass_context
+def delete(ctx: click.Context) -> None:
+    """删除资源（job）"""
+    pass
+
+
+@delete.command("job")
+@click.argument("job_name")
+@click.option("--force", is_flag=True, help="强制删除运行中的作业")
+@click.pass_context
+def delete_job(ctx: click.Context, job_name: str, force: bool) -> None:
+    """删除作业记录（不删 checkpoint / workspace 数据）"""
+    json_mode: bool = ctx.obj["json_mode"]
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录")
+        return
+
+    client = ApiClient(store)
+    data = client.delete_job(job_name, force=force)
+
+    if json_mode:
+        console.output(data, json_mode=True)
+    else:
+        console.success(f"作业 {job_name} 已删除")