freesolo-flash-dev 0.2.34__tar.gz → 0.2.35__tar.gz

{freesolo_flash_dev-0.2.34 → freesolo_flash_dev-0.2.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freesolo-flash-dev
-Version: 0.2.34
+Version: 0.2.35
 Summary: Flash — managed LoRA post-training (SFT/GRPO) for Freesolo environments, driven by the `flash` CLI
 Project-URL: Homepage, https://github.com/freesolo-co/flash
 Project-URL: Repository, https://github.com/freesolo-co/flash

{freesolo_flash_dev-0.2.34 → freesolo_flash_dev-0.2.35}/flash/cli/__init__.py

@@ -348,14 +348,17 @@ def _build_parser() -> argparse.ArgumentParser:
     checkpoints.set_defaults(func=cmd_checkpoints)
 
     deploy = sub.add_parser("deploy", help="deploy a run's adapter to a serving endpoint")
-    deploy.add_argument("run_id")
+    deploy.add_argument(
+        "run_id",
+        metavar="RUN_ID[/step-N]",
+        help="run id for the final adapter, or RUN_ID/step-N for a saved checkpoint",
+    )
     deploy.add_argument("--dry-run", action="store_true")
     deploy.add_argument(
-        "--step",
-        type=int,
-        default=None,
-        help="deploy a specific intermediate checkpoint (see `flash checkpoints <run_id>`) "
-        "instead of the run's final adapter; works even for a run cancelled mid-RL",
+        "--no-verify",
+        action="store_true",
+        help="skip the server-side post-deploy smoke generation (registration alone does NOT "
+        "guarantee the adapter serves; only ready deployments should be scored by evals)",
     )
     deploy.set_defaults(func=cmd_deploy)
 
@@ -368,7 +371,8 @@ def _build_parser() -> argparse.ArgumentParser:
         "--adapter-id",
         dest="adapter_id",
         required=True,
-        help="the Freesolo adapter id (the run id) to export",
+        metavar="RUN_ID[/step-N]",
+        help="run id for the final adapter, or RUN_ID/step-N for a saved checkpoint",
     )
     export.add_argument(
         "--repository",
@@ -380,13 +384,6 @@ def _build_parser() -> argparse.ArgumentParser:
         help="HuggingFace token with write access to --repository "
         "(default: HF_TOKEN from your shell or a local .env / .env.local)",
     )
-    export.add_argument(
-        "--step",
-        type=int,
-        default=None,
-        help="export a specific intermediate checkpoint (see `flash checkpoints <adapter-id>`) "
-        "instead of the run's final adapter; works even for a run cancelled mid-RL",
-    )
     export.add_argument(
         "--public",
         action="store_true",
@@ -400,6 +397,12 @@ def _build_parser() -> argparse.ArgumentParser:
     chat = sub.add_parser("chat", help="chat with a deployed adapter")
     chat.add_argument("run_id")
     chat.add_argument("-m", "--message", required=True)
+    chat.add_argument(
+        "--system",
+        default=None,
+        help="optional system prompt sent ahead of the user message "
+        "(training-prompt parity for evals)",
+    )
     chat.add_argument("--max-tokens", type=int, default=512)
     chat.add_argument("--temperature", type=float, default=0.0)
     chat.set_defaults(func=cmd_chat)

{freesolo_flash_dev-0.2.34 → freesolo_flash_dev-0.2.35}/flash/cli/commands.py

@@ -407,9 +407,12 @@ def cmd_train(args) -> int:
     return _follow_run(client, run_id)
 
 
-def _poll_logs(client: ApiClient, run_id: str, interval: float) -> str:
-    """Stream offset-paged logs until the run reaches a terminal state; return that state."""
+def _poll_logs(client: ApiClient, run_id: str, interval: float) -> tuple[str, bool]:
+    """Stream offset-paged logs until the run reaches a terminal state.
+
+    Returns (terminal state, whether any log bytes were printed)."""
     offset = 0
+    printed_any = False
     spinner = _LogFollowSpinner(run_id)
     try:
         while True:
@@ -417,23 +420,25 @@ def _poll_logs(client: ApiClient, run_id: str, interval: float) -> str:
             if page["logs"]:
                 spinner.clear()
                 print(page["logs"], end="", flush=True)
+                printed_any = True
             offset = page["offset"]
             if page["state"] in _CLI_DONE_STATES:
                 spinner.clear()
-                return page["state"]
+                return page["state"], printed_any
             _sleep_with_spinner(interval, spinner, page["state"])
     finally:
         spinner.clear()
 
 
+def _render_status(status: dict) -> str:
+    """One rendering of a run status: themed panel on a TTY, indented JSON on the machine path."""
+    return render.run_status(status) if render.styled() else json.dumps(status, indent=2)
+
+
 def _follow_run(client: ApiClient, run_id: str) -> int:
     """Poll logs until the run reaches a terminal state, then print the final status."""
-    state = _poll_logs(client, run_id, interval=2.0)
-    status = client.get_run(run_id)
-    if render.styled():
-        print(render.run_status(status))
-    else:
-        print(json.dumps(status, indent=2))
+    state, _ = _poll_logs(client, run_id, interval=2.0)
+    print(_render_status(client.get_run(run_id)))
     return 0 if state in _OK_STATES else 1
 
 
@@ -442,7 +447,7 @@ def _follow_status(client: ApiClient, run_id: str, interval: float = 2.0) -> int
     last_rendered: str | None = None
     while True:
         status = client.get_run(run_id)
-        rendered = render.run_status(status) if render.styled() else json.dumps(status, indent=2)
+        rendered = _render_status(status)
         if rendered != last_rendered:
             print(rendered)
             last_rendered = rendered
@@ -452,21 +457,6 @@ def _follow_status(client: ApiClient, run_id: str, interval: float = 2.0) -> int
         time.sleep(interval)
 
 
-def _print_log_text(text: str) -> bool:
-    if not text:
-        return False
-    print(text, end="")
-    if not text.endswith("\n"):
-        print()
-    return True
-
-
-def _print_log_snapshot(client: ApiClient, run_id: str) -> bool:
-    """Print a finite snapshot from the log endpoint without following new bytes."""
-    page = client.get_logs(run_id, offset=0)
-    return _print_log_text(str(page.get("logs") or ""))
-
-
 def _print_worker_output(client: ApiClient, run_id: str, *, printed_any: bool = False) -> bool:
     for name, text in (client.get_worker_output(run_id) or {}).items():
         if not text:
@@ -484,11 +474,13 @@ def _print_worker_output(client: ApiClient, run_id: str, *, printed_any: bool =
 def cmd_log(args) -> int:
     client = client_from_config()
     if getattr(args, "follow", False):
-        state = _poll_logs(client, args.run_id, interval=2.0)
-        _print_worker_output(client, args.run_id, printed_any=True)
+        state, printed_any = _poll_logs(client, args.run_id, interval=2.0)
+        _print_worker_output(client, args.run_id, printed_any=printed_any)
         return 0 if state in _OK_STATES else 1
-    printed_any = _print_log_snapshot(client, args.run_id)
-    _print_worker_output(client, args.run_id, printed_any=printed_any)
+    text = str(client.get_logs(args.run_id, offset=0).get("logs") or "")
+    if text:
+        print(text, end="" if text.endswith("\n") else "\n")
+    _print_worker_output(client, args.run_id, printed_any=bool(text))
     return 0
 
 
@@ -496,11 +488,7 @@ def cmd_status(args) -> int:
     client = client_from_config()
     if getattr(args, "follow", False):
         return _follow_status(client, args.run_id)
-    status = client.get_run(args.run_id)
-    if render.styled():
-        print(render.run_status(status))
-    else:
-        print(json.dumps(status, indent=2))
+    print(_render_status(client.get_run(args.run_id)))
     return 0
 
 
@@ -553,20 +541,37 @@ def cmd_checkpoints(args) -> int:
     if render.styled():
         print(render.checkpoints_table(args.run_id, checkpoints))
         return 0
+    from flash.schema import format_checkpoint_ref
+
     for c in checkpoints:
-        print(f"step {c['step']:>6}  {c['repo_id']}:{c['subfolder']}")
+        # single-space, unpadded columns so a plain `grep "step N"` / awk split works; the ref is
+        # the canonical short form, paste-able into train.init_from_adapter.
+        print(f"step {c['step']} {format_checkpoint_ref(args.run_id, c['step'])}")
     print(
-        f"\ndeploy one with `flash deploy {args.run_id} --step <STEP>`.",
+        f"\ndeploy one with `flash deploy {args.run_id}/step-<STEP>`.",
         file=sys.stderr,
     )
     return 0
 
 
 def cmd_deploy(args) -> int:
-    dep = client_from_config().deploy(
+    from flash.schema import parse_checkpoint_ref
+
+    # `flash deploy <run_id>/step-N` is the same checkpoint ref `flash checkpoints` prints.
+    parsed = parse_checkpoint_ref(args.run_id)
+    if parsed is None:
+        print(
+            f"invalid run/checkpoint reference {args.run_id!r} "
+            "(expected <run_id> or <run_id>/step-N)",
+            file=sys.stderr,
+        )
+        return 1
+    base_run_id, _step = parsed
+    client = client_from_config()
+    dep = client.deploy(
         args.run_id,
         dry_run=args.dry_run,
-        step=getattr(args, "step", None),
+        verify=not getattr(args, "no_verify", False),
     )
     if render.styled():
         print(render.deployed(dep))
@@ -574,11 +579,35 @@ def cmd_deploy(args) -> int:
         print(json.dumps(dep, indent=2))
     # a dry run creates no deployment, so the billing / undeploy hint would be misleading.
     if dep.get("state") != "dry_run":
+        endpoint = str(dep.get("endpoint_name") or "").rstrip("/")
+        openai_base = dep.get("url") or (f"{endpoint}/v1" if endpoint else "")
         note = (
-            f"serving is billed per token only; use `flash undeploy {args.run_id}` "
+            f"serving is billed per token only; use `flash undeploy {base_run_id}` "
             "to deregister the adapter."
         )
         print(render.arrow(note) if render.styled() else f"note: {note}", file=sys.stderr)
+        if openai_base:
+            url_note = (
+                f"OpenAI-compatible base URL: {openai_base} — point clients at this /v1 base, "
+                "not the bare endpoint (which 404s on /chat/completions)."
+            )
+            print(render.arrow(url_note) if render.styled() else f"note: {url_note}", file=sys.stderr)
+    if dep.get("state") != "dry_run":
+        state = dep.get("state", "deploying")
+        status_note = (
+            f"deployment state is {state!r}; run `flash deployments` to check progress "
+            "and use `flash chat` once it is ready."
+        )
+        print(
+            render.arrow(status_note) if render.styled() else f"note: {status_note}",
+            file=sys.stderr,
+        )
+        if getattr(args, "no_verify", False):
+            skip_note = "server-side smoke verification was skipped for this deployment."
+            print(
+                render.arrow(skip_note) if render.styled() else f"note: {skip_note}",
+                file=sys.stderr,
+            )
     return 0
 
 
@@ -592,9 +621,8 @@ def cmd_export(args) -> int:
             "(export it in your shell or put it in a local .env / .env.local)"
         )
     client = client_from_config()
-    where = f" (step {args.step})" if args.step is not None else ""
     progress = (
-        f"exporting adapter {args.adapter_id}{where} to {args.repository} — "
+        f"exporting adapter {args.adapter_id} to {args.repository} — "
         "downloading then re-uploading; this can take a minute..."
     )
     print(render.note(progress) if render.styled() else progress, file=sys.stderr)
@@ -602,7 +630,6 @@ def cmd_export(args) -> int:
         args.adapter_id,
         repository=args.repository,
         hf_token=hf_token,
-        step=args.step,
         private=not args.public,
     )
     if render.styled():
@@ -639,16 +666,23 @@ def cmd_deployments(args) -> int:
     if render.styled():
         print(render.deployments_table(rows))
         return 0
-    print(f"{'RUN_ID':<32}  {'GPU':<9}  ENDPOINT")
+    print(f"{'RUN_ID':<32}  {'STATE':<10}  {'GPU':<9}  {'ENDPOINT':<32}  DETAIL")
     for r in rows:
         d = r.get("deployment") or {}
-        print(f"{r['run_id']:<32}  {d.get('gpu', '?'):<9}  {d.get('endpoint_name', '')}")
+        detail = str(d.get("error") or d.get("detail") or "")
+        print(
+            f"{r['run_id']:<32}  {d.get('state', '?'):<10}  "
+            f"{d.get('gpu', '?'):<9}  {d.get('endpoint_name', ''):<32}  {detail}"
+        )
     return 0
 
 
 def cmd_chat(args) -> int:
     client = client_from_config()
     messages = [{"role": "user", "content": args.message}]
+    system = getattr(args, "system", None)
+    if system:
+        messages.insert(0, {"role": "system", "content": system})
     if render.styled():
         print(render.chat_label())
     stream = getattr(client, "chat_stream", None)

{freesolo_flash_dev-0.2.34 → freesolo_flash_dev-0.2.35}/flash/cli/envpush.py

@@ -188,25 +188,23 @@ _ENV_PUSH_SIDECAR_SUFFIXES = frozenset(
 
 
 def _normalize_env_name(raw: str) -> str | None:
-    import re
+    """Normalize only the NAME segment; a namespace prefix is passed through verbatim.
 
-    def normalize_segment(value: str) -> str | None:
-        segment = re.sub(r"[^a-z0-9._-]+", "-", value.lower()).strip("-")
-        if segment in {"", ".", ".."} or not re.search(r"[a-z0-9]", segment):
-            return None
-        return segment
+    The server is the sole authority on namespace grammar and ownership — rewriting the
+    namespace client-side would silently target a different (possibly forbidden) slug.
+    """
+    from flash.schema import normalize_env_name_segment
 
     text = str(raw or "").strip()
     if "/" not in text:
-        return normalize_segment(text)
+        return normalize_env_name_segment(text)
     parts = [part.strip() for part in text.split("/")]
     if len(parts) != 2 or not all(parts):
         return None
-    namespace = normalize_segment(parts[0])
-    name = normalize_segment(parts[1])
-    if not namespace or not name:
+    name = normalize_env_name_segment(parts[1])
+    if name is None:
         return None
-    return f"{namespace}/{name}"
+    return f"{parts[0]}/{name}"
 
 
 def _with_syspath_bootstrap(env_source: str) -> str:

{freesolo_flash_dev-0.2.34 → freesolo_flash_dev-0.2.35}/flash/cli/render.py

@@ -439,28 +439,37 @@ def deployments_table(rows: list[dict]) -> str:
     body = []
     for r in rows:
         d = r.get("deployment") or {}
+        state = str(d.get("state") or "?")
+        color = _GREEN if state in {"ready", "deployed"} else _RED if state == "failed" else _AMBER
+        detail = str(d.get("error") or d.get("detail") or "")
+        if len(detail) > 64:
+            detail = detail[:61] + "..."
         body.append(
             [
                 (r["run_id"], _ACCENT2),
+                (state, color),
                 (d.get("gpu", "?"), _GRAY),
                 (d.get("endpoint_name", ""), _GREEN),
+                (detail, _GRAY),
             ]
         )
-    table = _table(["RUN ID", "GPU", "ENDPOINT"], body)
+    table = _table(["RUN ID", "STATE", "GPU", "ENDPOINT", "DETAIL"], body)
     return _safe(f"{header('deployments', f'{len(rows)} active')}\n{table}")
 
 
 def checkpoints_table(run_id: str, rows: list[dict]) -> str:
-    """Deployable per-step RL checkpoints: the step number + the stable repo path it lives at."""
+    """Deployable per-step RL checkpoints: step number + the canonical `<run_id>/step-N` ref."""
+    from flash.schema import format_checkpoint_ref
+
     body = [
         [
             (str(c.get("step", "")), _TEAL),
-            (f"{c.get('repo_id', '')}:{c.get('subfolder', '')}", _ACCENT2),
+            (format_checkpoint_ref(run_id, c.get("step", 0)), _ACCENT2),
         ]
         for c in sorted(rows, key=lambda c: c.get("step", 0))
     ]
     table = _table(["STEP", "CHECKPOINT"], body, aligns=["r", "l"])
-    foot = arrow(f"deploy one with: flash deploy {run_id} --step <STEP>")
+    foot = arrow(f"deploy one with: flash deploy {run_id}/step-<STEP>")
     return _safe(f"{header('checkpoints', f'{len(rows)} deployable')}\n{table}\n\n{foot}")
 
 
@@ -541,11 +550,14 @@ def cancelled(payload: dict) -> str:
 
 def deployed(dep: dict) -> str:
     """`flash deploy`: the endpoint, gpu, and serving url as an aligned card (not a JSON dump)."""
+    endpoint = str(dep.get("endpoint_name") or "")
+    # OpenAI clients need the /v1 base; older servers omit `url`, so derive it from the endpoint.
+    url = dep.get("url") or (f"{endpoint.rstrip('/')}/v1" if endpoint else None)
     pairs = [
         ("run", _paint(dep.get("run_id", ""), _ACCENT2)),
-        ("endpoint", _paint(dep["endpoint_name"], _GREEN) if dep.get("endpoint_name") else None),
+        ("endpoint", _paint(endpoint, _GREEN) if endpoint else None),
         ("gpu", dep.get("gpu")),
-        ("url", _paint(dep["url"], _ACCENT2) if dep.get("url") else None),
+        ("url", _paint(url, _ACCENT2) if url else None),
     ]
     state = dep.get("state", "deployed")
     if state == "dry_run":
@@ -571,6 +583,10 @@ def undeployed(result: dict) -> str:
     line = ok(f"torn down {rid}")
     if deleted:
         line += "\n" + _dim(f"  deregistered {', '.join(deleted)}")
+    else:
+        line += "\n" + _dim(
+            "  serving had no registered adapter to deregister (already gone or never registered)"
+        )
     return _safe(line)
 
 

{freesolo_flash_dev-0.2.34 → freesolo_flash_dev-0.2.35}/flash/cli/training_doc.py

@@ -138,7 +138,8 @@ flash cancel <run-id>            # stop a run
 
 ```bash
 flash checkpoints <run-id>       # deployable per-step RL checkpoints
-flash deploy <run-id>            # serve the trained adapter (--step N for an intermediate checkpoint)
+flash deploy <run-id>            # serve the trained adapter
+flash deploy <run-id>/step-N     # serve an intermediate checkpoint
 flash chat <run-id> -m "hello"   # chat with the deployed adapter
 flash deployments                # active serving endpoints
 flash undeploy <run-id>          # tear the endpoint down
@@ -208,7 +209,7 @@ spending another GPU run:
 | Output is truncated | Correct-looking answers cut off mid-response or JSON is incomplete | Increase `max_tokens` for GRPO rollouts or `max_length` for SFT only after seeing truncation. Oversizing them by default just burns memory/cost. |
 | Infrastructure, CUDA, OOM, vLLM, or kernel failure | Run errors before useful metrics, often during setup/model load | Treat this as infrastructure pressure, not proof the model is too large. Read `flash log <run-id>`, reduce footprint (`max_length`, `max_tokens`, `group_size`) if needed, and let Flash retry/allocate another fitting GPU class. |
 | Run looks stuck after disconnecting | Terminal stopped streaming but the job may still be alive | Ctrl-C detaches. Use `flash log <run-id> --follow` to reattach, `flash log <run-id>` for the console/error output, or `flash cancel <run-id>` if you intentionally want to stop it. |
-| Final checkpoint regresses | Last step is worse than an earlier checkpoint | Run `flash checkpoints <run-id>`, deploy a specific step with `flash deploy <run-id> --step N`, and compare with held-out probes before exporting or relying on the final adapter. |
+| Final checkpoint regresses | Last step is worse than an earlier checkpoint | Run `flash checkpoints <run-id>`, deploy a specific step with `flash deploy <run-id>/step-N`, and compare with held-out probes before exporting or relying on the final adapter. |
 | Export fails before upload | CLI says no HuggingFace token | Pass `flash export --api-key hf_...`, or set `HF_TOKEN` in your shell, `.env`, or `.env.local`. Exports are private unless you pass `--public`. |
 | SFT loss improves but quality does not | Train loss falls while held-out behavior stalls or degrades | Keep a held-out split outside training. Deploy and score that split; if quality drops, reduce epochs or improve data instead of adding more passes. |
 | Cost surprises | A quick experiment uses more GPU time than intended | Start with `--dry-run` and `--cost`, cap steps/epochs for smoke tests, and scale only after reward/data wiring is proven. Setup time is reported for observability; customer cost is based on training-loop GPU time. |
@@ -350,9 +351,9 @@ Pick SFT when you already have good answers and want the model to imitate them.
 algorithm = "grpo"
 
 [train]
-# paste the full adapter_ref `flash status <sft-run-id>` prints, verbatim
-# (shape: <owner>/<repo>:sft/<run-id> — the owner/repo prefix is required)
-init_from_adapter = "your-org/your-repo:sft/<sft-run-id>"
+# the SFT run id (as printed by `flash status`); add /step-N to warm-start from a
+# specific checkpoint listed by `flash checkpoints <run-id>`
+init_from_adapter = "<sft-run-id>"
 lora_rank = 16     # for VL warm-starts, SFT rank + GRPO rank must fit the effective serving cap
 lora_alpha = 32
 ```
@@ -479,12 +480,12 @@ flash runs                            # list your runs and their state/cost
 flash cancel <run-id>                 # stop a live run
 flash checkpoints <run-id>            # list deployable RL checkpoints
 flash deploy <run-id>                 # serve the trained adapter
-flash deploy <run-id> --step N        # serve a specific RL checkpoint
+flash deploy <run-id>/step-N          # serve a specific RL checkpoint
 flash chat <run-id> -m "probe"        # stream a reply from the deployed adapter
 flash deployments                     # list active serving deployments
 flash undeploy <run-id>               # tear down an active deployment
 flash export --adapter-id <run-id> --repository <you>/<repo>  # export final adapter
-flash export --adapter-id <run-id> --repository <you>/<repo> --step N  # export a checkpoint
+flash export --adapter-id <run-id>/step-N --repository <you>/<repo>  # export a checkpoint
 ```
 
 See the full reference at https://freesolo.co/docs.

{freesolo_flash_dev-0.2.34 → freesolo_flash_dev-0.2.35}/flash/client/http.py

@@ -98,18 +98,6 @@ class _ProgressReader:
         return chunk
 
 
-def _validate_checkpoint_step(step: int | float) -> int:
-    """Validate a checkpoint step before the request: reject bool (int(True)==1) and fractional floats
-    (int(2.7)==2 would target the WRONG checkpoint), then return the int — fail fast before the server."""
-    if isinstance(step, bool):
-        raise ClientError(f"invalid checkpoint step: {step!r} (must be an integer)")
-    if isinstance(step, float) and not step.is_integer():
-        raise ClientError(
-            f"invalid checkpoint step: {step!r} (must be a whole number, not fractional)"
-        )
-    return int(step)
-
-
 def _validate_chat_messages(messages: list[dict]) -> None:
     if not isinstance(messages, list):
         raise ClientError("chat messages must be a list")
@@ -233,31 +221,45 @@ class ApiClient:
         return self._request("GET", f"/v1/runs/{run_id}/logs?offset={int(offset)}")
 
     def get_worker_output(self, run_id: str) -> dict[str, str]:
-        return self._request("GET", f"/v1/runs/{run_id}/worker").get("worker", {})
+        try:
+            return self._request("GET", f"/v1/runs/{run_id}/worker").get("worker", {})
+        except ApiError as exc:
+            if exc.status == 404 and "not found" in str(exc).strip().lower():
+                return {}
+            raise
 
     def cancel_run(self, run_id: str) -> dict:
-        return self._request("POST", f"/v1/runs/{run_id}/cancel")
+        # Cancel blocks on synchronous provider teardown (worker stop + instance destroy +
+        # endpoint GC), which can far exceed the default 60s — timing out here left the CLI
+        # printing a traceback while the server went on to mark the run cancelled anyway.
+        return self._request("POST", f"/v1/runs/{run_id}/cancel", timeout=10 * 60)
 
     def checkpoints(self, run_id: str) -> list[dict]:
-        """Deployable per-step RL checkpoints for a run (each `flash deploy --step N`-able)."""
+        """Deployable per-step RL checkpoints for a run (serve one with `flash deploy RUN/step-N`)."""
         return self._request("GET", f"/v1/runs/{run_id}/checkpoints")["checkpoints"]
 
     def deploy(
         self,
         run_id: str,
         dry_run: bool = False,
-        step: int | None = None,
+        verify: bool = True,
     ) -> dict:
-        # Deploy blocks on registration and serving warmup, which can take many minutes.
-        deploy_timeout = 30 * 60 if not dry_run else None
-        body: dict = {"dry_run": dry_run}
+        from flash.schema import parse_checkpoint_ref
+
+        parsed = parse_checkpoint_ref(run_id)
+        if parsed is None:
+            raise ClientError(
+                "invalid adapter id: expected RUN_ID for the final adapter or RUN_ID/step-N "
+                "for a saved checkpoint"
+            )
+        base_run_id, step = parsed
+        body: dict = {"dry_run": dry_run, "verify": verify}
         if step is not None:
-            body["step"] = _validate_checkpoint_step(step)
+            body["step"] = step
         return self._request(
             "POST",
-            f"/v1/runs/{run_id}/deploy",
+            f"/v1/runs/{base_run_id}/deploy",
             body=body,
-            timeout=deploy_timeout,
         )
 
     def export(
@@ -266,15 +268,23 @@ class ApiClient:
         *,
         repository: str,
         hf_token: str,
-        step: int | None = None,
         private: bool = True,
     ) -> dict:
         """Copy a run's adapter into a user-owned HuggingFace repo."""
+        from flash.schema import parse_checkpoint_ref
+
+        parsed = parse_checkpoint_ref(run_id)
+        if parsed is None:
+            raise ClientError(
+                "invalid adapter id: expected RUN_ID for the final adapter or RUN_ID/step-N "
+                "for a saved checkpoint"
+            )
+        base_run_id, step = parsed
         body: dict = {"repository": repository, "hf_token": hf_token, "private": private}
         if step is not None:
-            body["step"] = _validate_checkpoint_step(step)
+            body["step"] = step
         return self._request(
-            "POST", f"/v1/runs/{run_id}/export", body=body, timeout=30 * 60
+            "POST", f"/v1/runs/{base_run_id}/export", body=body, timeout=30 * 60
         )
 
     def undeploy(self, run_id: str) -> dict:
@@ -289,13 +299,14 @@ class ApiClient:
         messages: list[dict],
         temperature: float = 0.0,
         max_tokens: int = 512,
+        timeout: float | None = None,
     ) -> dict:
         _validate_chat_messages(messages)
         return self._request(
             "POST",
             f"/v1/runs/{run_id}/chat",
             body={"messages": messages, "temperature": temperature, "max_tokens": max_tokens},
-            timeout=30 * 60,
+            timeout=timeout if timeout is not None else 30 * 60,
         )
 
     def chat_stream(