cmpnd 0.65.0__tar.gz → 0.67.0__tar.gz

{cmpnd-0.65.0 → cmpnd-0.67.0}/AGENTS.md

@@ -92,7 +92,7 @@ knowing:
   Run `uv lock` and commit the result. A stale lock makes every `uv` command
   rewrite it.
 - `basedpyright` takes no path argument. A path overrides pyproject's
-  `include`, so `basedpyright cmpnd` skips `tests/e2e` and `tests/stress` and
+  `include`, so `basedpyright cmpnd` skips `tests/e2e` and `tests/real_models` and
   passes changes CI rejects.
 
 **This tree's SDK and CLI run against each live self-host release.**
@@ -234,7 +234,10 @@ first. Its failures name the attribute or class that moved.
 
 To add a verb to both front-ends, add a `Verb(...)` row to `cli/verbs.py`, add
 its `add_parser` call in `top.register()`, and add the entity method or the
-`_make_namespace` function. The parity test fails until all three agree.
+`_make_namespace` function. The parity test fails until all three agree. A
+verb that repeats a namespaced command sets `shortcut_for`, and its help then
+starts with "Shortcut for `cmpnd deployments list`". The parity test checks
+that the named command exists.
 
 When you touch a handler:
 

{cmpnd-0.65.0 → cmpnd-0.67.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.65.0
+Version: 0.67.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -526,8 +526,17 @@ for candidate in sdk.list_candidates(best.optimization_run_id):  # read each one
 other = sdk.continue_optimization(best, candidate="ca_...", auto="light")
 ```
 
+`model=` runs the candidate on another student model, and `credential=` names
+the credential that model spends. A loop over models is a model sweep:
+
+```python
+for model in ["openai/gpt-4o-mini", "openai/gpt-4.1-nano"]:
+    swept = sdk.continue_optimization(best, model=model, auto="light")
+    print(model, swept.score)
+```
+
 A refusal raises `cmpnd.OptimizeError`, whose `error_code` says why, such as
-`not_completed` or `unknown_candidate`.
+`not_completed`, `unknown_candidate` or `no_credential`.
 
 ## Command line
 
@@ -654,11 +663,18 @@ global config. Use it as a context manager or as a plain object.
   found. It raises `cmpnd.OptimizeError` or `cmpnd.OptimizeFailed` on failure.
 - `list_candidates(run_id)` returns a run's candidates as dicts, each with its
   `ca_` id, score, parent and instructions.
-- `continue_optimization(run, candidate=None, ...)` runs a new optimization
-  from one candidate of a completed run, with that run's data and a new budget,
-  and returns its best `DeployedProgram`.
+- `continue_optimization(run, candidate=None, model=None, credential=None, ...)`
+  runs a new optimization from one candidate of a completed run, with that
+  run's data and a new budget, optionally on another student model, and returns
+  its best `DeployedProgram`.
 - `list_traces(**filters)` and `get_trace(trace_id)` read traces with the
   client's credentials. They flush the client's traces first.
+- `list_deployments(status=None, since=None, limit=50, offset=0)` and
+  `get_deployment(deployment_id)` read deployment records, as
+  `cmpnd deployments list` and `show` do.
+- `get_deployment_source(deployment_id, path=None)` returns the program file a
+  deployment stores, as `cmpnd inspect --source` does. A continuation's
+  deployment holds the program the continuation runs.
 - `close()` flushes the client's traces and closes the client. A closed
   client raises `RuntimeError` on every method.
 

{cmpnd-0.65.0 → cmpnd-0.67.0}/README.md

@@ -475,8 +475,17 @@ for candidate in sdk.list_candidates(best.optimization_run_id):  # read each one
 other = sdk.continue_optimization(best, candidate="ca_...", auto="light")
 ```
 
+`model=` runs the candidate on another student model, and `credential=` names
+the credential that model spends. A loop over models is a model sweep:
+
+```python
+for model in ["openai/gpt-4o-mini", "openai/gpt-4.1-nano"]:
+    swept = sdk.continue_optimization(best, model=model, auto="light")
+    print(model, swept.score)
+```
+
 A refusal raises `cmpnd.OptimizeError`, whose `error_code` says why, such as
-`not_completed` or `unknown_candidate`.
+`not_completed`, `unknown_candidate` or `no_credential`.
 
 ## Command line
 
@@ -603,11 +612,18 @@ global config. Use it as a context manager or as a plain object.
   found. It raises `cmpnd.OptimizeError` or `cmpnd.OptimizeFailed` on failure.
 - `list_candidates(run_id)` returns a run's candidates as dicts, each with its
   `ca_` id, score, parent and instructions.
-- `continue_optimization(run, candidate=None, ...)` runs a new optimization
-  from one candidate of a completed run, with that run's data and a new budget,
-  and returns its best `DeployedProgram`.
+- `continue_optimization(run, candidate=None, model=None, credential=None, ...)`
+  runs a new optimization from one candidate of a completed run, with that
+  run's data and a new budget, optionally on another student model, and returns
+  its best `DeployedProgram`.
 - `list_traces(**filters)` and `get_trace(trace_id)` read traces with the
   client's credentials. They flush the client's traces first.
+- `list_deployments(status=None, since=None, limit=50, offset=0)` and
+  `get_deployment(deployment_id)` read deployment records, as
+  `cmpnd deployments list` and `show` do.
+- `get_deployment_source(deployment_id, path=None)` returns the program file a
+  deployment stores, as `cmpnd inspect --source` does. A continuation's
+  deployment holds the program the continuation runs.
 - `close()` flushes the client's traces and closes the client. A closed
   client raises `RuntimeError` on every method.
 

cmpnd-0.67.0/cmpnd/_deployments.py

@@ -0,0 +1,105 @@
+"""Deployment reads behind ``cmpnd.Client``: the record list, one record, its stored source and its typed metadata."""
+
+from __future__ import annotations
+
+import io
+import tokenize
+from typing import Any, Protocol
+
+from . import _http
+from .deployment_metadata import DeploymentMetadataError, DeploymentSignatureResponse
+
+MAX_DEPLOYMENTS_PER_PAGE = 500
+
+
+class _JSONReader(Protocol):
+    def get(self, path: str) -> Any: ...
+
+
+def read_signature(client: _JSONReader, deployment_id: str) -> DeploymentSignatureResponse:
+    """Read one deployment's persisted signature through an existing client."""
+    value = client.get(f"/api/v1/deployments/{deployment_id}/signature")
+    response = DeploymentSignatureResponse.from_dict(value)
+    if response.deployment_id != deployment_id:
+        raise DeploymentMetadataError(
+            f"response deployment_id {response.deployment_id!r} does not match {deployment_id!r}"
+        )
+    return response
+
+
+def get_signature(
+    deployment_id: str,
+    *,
+    api_key: str,
+    endpoint: str,
+    timeout: float | None = None,
+) -> DeploymentSignatureResponse:
+    """Read one deployment's persisted signature with explicit credentials."""
+    client = (
+        _http.ApiClient(api_key, endpoint) if timeout is None else _http.ApiClient(api_key, endpoint, timeout=timeout)
+    )
+    return read_signature(client, deployment_id)
+
+
+def list_deployments(
+    *,
+    status: str | None = None,
+    since: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    api_key: str,
+    endpoint: str,
+) -> dict[str, Any]:
+    """List the organization's deployments, newest first.
+
+    Returns ``{"deployments": [...], "has_more": bool, ...}``. ``status`` is one
+    of ``pending``, ``parsing``, ``optimizing``, ``ready`` or ``failed``, and
+    ``since`` is an ISO 8601 timestamp. The route pages by page number, so
+    ``offset`` must be a whole multiple of ``limit``. The route returns at most
+    500 deployments per page, so ``limit`` must not exceed 500.
+    """
+    if limit <= 0:
+        raise _http.ApiError("limit must be positive")
+    if limit > MAX_DEPLOYMENTS_PER_PAGE:
+        raise _http.ApiError(
+            f"limit must not exceed {MAX_DEPLOYMENTS_PER_PAGE}; the deployments route returns at most "
+            f"{MAX_DEPLOYMENTS_PER_PAGE} per page"
+        )
+    if offset < 0:
+        raise _http.ApiError("offset must not be negative")
+    if offset % limit != 0:
+        lower = (offset // limit) * limit
+        raise _http.ApiError(
+            f"offset must be a multiple of limit (the deployments route pages by page number); "
+            f"try offset {lower} or {lower + limit}"
+        )
+    params = {"per_page": str(limit), "page": str(offset // limit + 1)}
+    if status is not None:
+        params["status"] = status
+    if since is not None:
+        params["since"] = since
+    return _http.ApiClient(api_key, endpoint).get("/api/v1/deployments", params=params)
+
+
+def get_deployment(deployment_id: str, *, api_key: str, endpoint: str) -> dict[str, Any]:
+    """Read one deployment's record: its status, program, model and metadata."""
+    return _http.ApiClient(api_key, endpoint).get(f"/api/v1/deployments/{deployment_id}")
+
+
+def get_source(deployment_id: str, *, path: str | None = None, api_key: str, endpoint: str) -> str:
+    """Read one file of a deployment's stored source as text.
+
+    Without ``path`` it reads the program file the stored bundle names. With
+    ``path`` it reads that archive-relative member. It decodes the file with the
+    encoding the file declares in a PEP 263 coding comment, and with UTF-8 when
+    the file declares none.
+    """
+    client = _http.ApiClient(api_key, endpoint)
+    route = f"/api/v1/deployments/{deployment_id}/source"
+    if path is None:
+        path = client.get(route).get("program")
+        if not path:
+            raise _http.ApiError(f"the stored source of deployment {deployment_id} names no program file")
+    raw = client.get_bytes(route, params={"path": path})
+    encoding, _lines = tokenize.detect_encoding(io.BytesIO(raw).readline)
+    return raw.decode(encoding)

{cmpnd-0.65.0 → cmpnd-0.67.0}/cmpnd/cli/__init__.py

@@ -107,7 +107,11 @@ def parse(parser: argparse.ArgumentParser, argv: list[str]) -> argparse.Namespac
 def main() -> None:
     parser = tree_help.TreeHelpParser(
         prog="cmpnd",
-        description="CMPND platform CLI — deploy, run, and inspect DSPy programs.",
+        description=(
+            "CMPND platform CLI — deploy, run, and inspect DSPy programs.\n\n"
+            "The top-level commands are the Docker-style deploy-and-run loop. ps, run and inspect are\n"
+            "shortcuts for deployments list, run and show."
+        ),
         epilog=_EPILOG,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )

{cmpnd-0.65.0 → cmpnd-0.67.0}/cmpnd/cli/commands/optimizations.py

@@ -93,7 +93,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     cont = sub.add_parser(
         "continue",
         help="Run a new optimization from one candidate of a completed run. It reuses that run's data, models "
-        "and credentials, and takes a new budget",
+        "and credentials, and takes a new budget. --model runs the candidate on another student model",
     )
     cont.add_argument("id", help="Completed optimization run ID (op_...)")
     cont.add_argument(
@@ -102,6 +102,19 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         help="The ca_ id of the candidate to start from, as `cmpnd optimizations candidates ID` lists them "
         "(default: the run's best)",
     )
+    cont.add_argument(
+        "--model",
+        default=None,
+        help="The student model the new run spends, as a deploy records it, for example openai/gpt-4o-mini "
+        "(default: the completed run's). Only the program's own model changes",
+    )
+    cont.add_argument(
+        "--credential",
+        metavar="NAME",
+        default=None,
+        help="The provider credential the student model spends (default: the completed run's). "
+        "`cmpnd credentials list` shows the names",
+    )
     # The budget flags are `cmpnd optimize`'s, and the SDK refuses a run with none or two,
     # so both commands answer a missing budget the same way.
     cont.add_argument(
@@ -258,17 +271,23 @@ def handle_continue(client: api_client.ApiClient, args: Any) -> Any:
     """Run a new optimization from one candidate of a completed run, as `cmpnd optimize` runs one.
 
     The new run reuses the completed run's data and configuration and takes a new budget.
-    The command names the candidate it starts from, waits for the run, and prints the
-    best program as `cmpnd optimize` does. `--async` returns the queued run instead.
+    `--model` and `--credential` run the candidate on another student model. The command
+    names the candidate it starts from, waits for the run, and prints the best program as
+    `cmpnd optimize` does. `--async` returns the queued run instead.
     """
     from ... import optimization
 
+    credential_name = args.credential
+    if credential_name is not None:
+        credential_name = top._CredentialLookup(client)(f"--credential {credential_name}", credential_name).name
     cfg = top.sdk_config(client)
     try:
         started = optimization.start_continuation(
             args.id,
             cfg=cfg,
             candidate=args.candidate,
+            model=args.model,
+            credential_name=credential_name,
             max_metric_calls=args.max_metric_calls,
             auto=args.auto,
         )
@@ -289,6 +308,11 @@ def handle_continue(client: api_client.ApiClient, args: Any) -> Any:
         ),
         file=sys.stderr,
     )
+    if args.model is not None or args.credential is not None:
+        print(
+            top._c(f"on {started.get('model')} with the credential {started.get('credential_name')}", "dim"),
+            file=sys.stderr,
+        )
     print(top._c(f"optimizing with {started.get('optimizer')}…", "dim"), file=sys.stderr)
     try:
         result = optimization.wait_for_continuation(started, cfg=cfg)
@@ -301,6 +325,7 @@ def handle_continue(client: api_client.ApiClient, args: Any) -> Any:
             "optimization_id": started.get("optimization_id"),
             "continued_from_run_id": started.get("continued_from_run_id"),
             "continued_from_candidate_id": started.get("continued_from_candidate_id"),
+            **{key: started[key] for key in ("model", "credential_name") if key in started},
         },
     )
     return None

{cmpnd-0.65.0 → cmpnd-0.67.0}/cmpnd/cli/commands/provider_credentials.py

@@ -5,7 +5,7 @@ platform spend on your behalf when a program of yours runs?
 
     cmpnd credentials create --name luna-exec --preset lunaroute       # a model provider
     cmpnd credentials create --kind mcp --server URL --name n …         # an MCP tool server
-    cmpnd credentials list
+    cmpnd credentials list --text
     cmpnd credentials protocols luna-exec --add system_one
     cmpnd credentials default luna-exec
     cmpnd credentials delete --name luna-exec --force
@@ -70,7 +70,7 @@ import sys
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
-from .. import api_client, deprecation
+from .. import api_client, deprecation, views
 
 #: The placements the platform's credentialed egress can compose a credential into.
 #: Closed set, and the same three strings `cmpnd.mcp_tools`'s auth shapes record.
@@ -156,7 +156,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     deprecation.alias(sub, "add", "create", func=handle_create, configure=_seal_args)
 
     listing = sub.add_parser("list", help="Show your org's credentials, their protocols and the default")
-    listing.add_argument("--json", action="store_true", help="Emit the raw JSON instead of the rendering")
+    views.add_text_flag(listing)
     listing.set_defaults(func=handle_list)
 
     protocols = sub.add_parser(
@@ -393,7 +393,7 @@ def handle_list(client: api_client.ApiClient, args: Any) -> Any:
     # Metadata only: the platform's projection carries no key material, not even its
     # length, so there is nothing here to redact.
     payload = client.get(_ROOT)
-    if getattr(args, "json", False) or not isinstance(payload, dict):
+    if not getattr(args, "text", False) or not isinstance(payload, dict):
         return payload
     credentials = [c for c in payload.get("credentials") or [] if isinstance(c, dict)]
     default = payload.get("default")

{cmpnd-0.65.0 → cmpnd-0.67.0}/cmpnd/cli/commands/tool_servers.py

@@ -6,8 +6,8 @@ agreed those declarations may reach. A server here carries the credential it is
 with, and the allow-list of tools on it a deploy is permitted to name.
 
     cmpnd tool-servers create --url https://mcp.exa.ai/mcp --credential exa-prod
-    cmpnd tool-servers list
-    cmpnd tool-servers show <server_id>
+    cmpnd tool-servers list --text
+    cmpnd tool-servers show <server_id> --text
     cmpnd tool-servers allow <server_id> web_search_exa
     cmpnd tool-servers deny <server_id> --all
     cmpnd tool-servers refresh <server_id>
@@ -48,7 +48,7 @@ import json
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
-from .. import api_client
+from .. import api_client, views
 from . import provider_credentials
 
 _ROOT = "/api/v1/org/tool-servers"
@@ -66,7 +66,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     create.set_defaults(func=handle_create)
 
     listing = sub.add_parser("list", help="Show the tool servers your org has registered")
-    listing.add_argument("--json", action="store_true", help="Emit the raw JSON instead of the rendering")
+    views.add_text_flag(listing)
     listing.set_defaults(func=handle_list)
 
     show = sub.add_parser("show", help="Show one server, its credential, and its tools")
@@ -74,9 +74,9 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     show.add_argument(
         "--schemas",
         action="store_true",
-        help="Also print each tool's reduced argument schema — the shape the platform will enforce",
+        help="With --text, also print each tool's reduced argument schema — the shape the platform will enforce",
     )
-    show.add_argument("--json", action="store_true", help="Emit the raw JSON instead of the rendering")
+    views.add_text_flag(show)
     show.set_defaults(func=handle_show)
 
     for verb, effect in (
@@ -232,7 +232,7 @@ def handle_create(client: api_client.ApiClient, args: Any) -> Any:
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
     payload = client.get(_ROOT)
-    if getattr(args, "json", False):
+    if not getattr(args, "text", False):
         return payload
     servers = _servers(payload)
     if not servers:
@@ -246,13 +246,13 @@ def handle_list(client: api_client.ApiClient, args: Any) -> Any:
             f"{str(server.get('id', '')).ljust(14)} {str(server.get('name') or '').ljust(16)} "
             f"{server.get('url', '')}  [{server.get('credential_name') or 'no credential'}]"
         )
-    print("Read one server's tools and its allow-list with `cmpnd tool-servers show <server_id>`.")
+    print("Read one server's tools and its allow-list with `cmpnd tool-servers show <server_id> --text`.")
     return None
 
 
 def handle_show(client: api_client.ApiClient, args: Any) -> Any:
     server = client.get(f"{_ROOT}/{args.server_id}")
-    if getattr(args, "json", False):
+    if not getattr(args, "text", False):
         return server
     _render_server(server if isinstance(server, dict) else {}, schemas=getattr(args, "schemas", False))
     return None
@@ -283,7 +283,7 @@ def _grant(client: api_client.ApiClient, args: Any, verb: str) -> Any:
     if not getattr(args, "all", False) and not tools:
         raise SystemExit(
             f"`tool-servers {verb}` needs at least one tool name, or --all. Run "
-            f"`cmpnd tool-servers show {args.server_id}` to see what this server lists."
+            f"`cmpnd tool-servers show {args.server_id} --text` to see what this server lists."
         )
     body: dict[str, Any] = {"all": True} if getattr(args, "all", False) else {"tools": tools}
     server = client.post(f"{_ROOT}/{args.server_id}/{verb}", json=body)

{cmpnd-0.65.0 → cmpnd-0.67.0}/cmpnd/cli/commands/top.py

@@ -1301,10 +1301,22 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     def _handler(name: str) -> Any:
         return verbs.by_name(name).handler
 
+    # A verb that repeats a namespaced command says so first, from its VERBS
+    # row, so `cmpnd -h` tells a shortcut from a separate feature.
+    def _help(name: str, text: str = "") -> str:
+        shortcut_for = verbs.by_name(name).shortcut_for
+        if not shortcut_for:
+            return text
+        prefix = f"Shortcut for `cmpnd {shortcut_for}`"
+        return f"{prefix}; {text}" if text else prefix
+
     ps = subparsers.add_parser(
         "ps",
-        help="List deployments (Docker-style)",
-        description="List deployments belonging to the calling org, newest first.",
+        help=_help("ps", "renders a table"),
+        description=(
+            "List deployments belonging to the calling org, newest first. Shortcut for "
+            "`cmpnd deployments list` that renders a table; --json prints the same response."
+        ),
         epilog="Examples:\n  cmpnd ps\n  cmpnd ps --status ready --json\n",
         formatter_class=raw,
     )
@@ -1352,8 +1364,11 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
     insp = subparsers.add_parser(
         "inspect",
-        help="Full JSON for a deployment",
-        description="Print the full deployment record as JSON. Equivalent to `cmpnd status <id> --json`.",
+        help=_help("inspect", "--source prints the stored program"),
+        description=(
+            "Print the full deployment record as JSON, as `cmpnd deployments show` does. "
+            "--source prints the deployment's stored program file instead."
+        ),
         formatter_class=raw,
     )
     insp.add_argument("id")
@@ -1396,8 +1411,11 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
     rn = subparsers.add_parser(
         "run",
-        help="Run a deployment with a JSON input body",
-        description="Submit one durable run to a ready deployment and wait for its result.",
+        help=_help("run"),
+        description=(
+            "Submit one durable run to a ready deployment and wait for its result. "
+            "Shortcut for `cmpnd deployments run`."
+        ),
         epilog=(
             "Examples:\n"
             '  cmpnd run d_a1b2c3d4 \'{"question": "what is dspy?"}\'\n'

{cmpnd-0.65.0 → cmpnd-0.67.0}/cmpnd/cli/verbs.py

@@ -41,7 +41,9 @@ class Verb:
     ``deploy(path)``); ``"entity"`` binds it as a method on
     ``shell_entity`` (e.g. ``deps.d_xxx.status()``). ``shell_method``
     defaults to ``name`` and gives the registry a single hook to rename
-    a method without the hint helpers going stale.
+    a method without the hint helpers going stale. ``shortcut_for`` names the
+    namespaced command a verb repeats, such as ``"deployments list"`` for
+    ``ps``. Its CLI help starts with "Shortcut for `cmpnd deployments list`".
     """
 
     name: str
@@ -49,6 +51,7 @@ class Verb:
     shell_kind: Literal["top_level", "entity"]
     shell_entity: str | None = None
     shell_method: str | None = None
+    shortcut_for: str | None = None
 
     def __post_init__(self) -> None:
         if self.shell_kind == "entity" and not self.shell_entity:
@@ -65,13 +68,13 @@ class Verb:
 # functions (`_shell_method`, `register`), never at module scope.
 # Module-scope binding also makes the table trivially inspectable.
 _VERBS: tuple["Verb", ...] = (
-    Verb("ps", commands.top.cmd_ps, "top_level"),
+    Verb("ps", commands.top.cmd_ps, "top_level", shortcut_for="deployments list"),
     Verb("deploy", commands.top.cmd_deploy, "top_level"),
     Verb("optimize", commands.top.cmd_optimize, "top_level"),
     Verb("status", commands.top.cmd_status, "entity", "Deployment"),
     Verb("logs", commands.top.cmd_logs, "entity", "Deployment"),
-    Verb("inspect", commands.top.cmd_inspect, "entity", "Deployment"),
-    Verb("run", commands.top.cmd_run, "entity", "Deployment"),
+    Verb("inspect", commands.top.cmd_inspect, "entity", "Deployment", shortcut_for="deployments show"),
+    Verb("run", commands.top.cmd_run, "entity", "Deployment", shortcut_for="deployments run"),
     Verb("schema", commands.top.cmd_schema, "entity", "Deployment"),
     Verb("sample", commands.top.cmd_sample, "entity", "Deployment"),
 )

cmpnd-0.67.0/cmpnd/cli/views.py

@@ -0,0 +1,25 @@
+"""The output rule for namespaced commands.
+
+A namespaced read, such as `cmpnd traces show` or `cmpnd tool-servers list`, prints
+the platform's JSON by default, and a human view is an opt-in flag: `--tree` and
+`--timeline` on `traces show`, `--text` on the reads below. An action command may
+print a short result instead and take `--json` for the whole answer, as
+`cmpnd programs create` prints the id. The top-level commands (`cmpnd ps`,
+`cmpnd status`) are the human loop: they render text and take `--json`.
+`tests/test_cli/test_parity.py` refuses a namespaced read that offers `--json`.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+
+def add_text_flag(parser: argparse.ArgumentParser) -> None:
+    """Give a namespaced read the opt-in `--text` view.
+
+    Some reads rendered text by default and took `--json` before the CLI settled on
+    the rule, so `--json` stays accepted and hidden, and a script that passes it
+    keeps working.
+    """
+    parser.add_argument("--text", action="store_true", help="Render for a person instead of printing JSON")
+    parser.add_argument("--json", action="store_true", help=argparse.SUPPRESS)

{cmpnd-0.65.0 → cmpnd-0.67.0}/cmpnd/client.py

@@ -721,6 +721,8 @@ class Client:
         run: Any,
         *,
         candidate: str | None = None,
+        model: str | None = None,
+        credential: credentials.Credential | None = None,
         max_metric_calls: int | None = None,
         auto: str | None = None,
         poll_interval: float = 3.0,
@@ -735,12 +737,27 @@ class Client:
             best = client.optimize_deployment(deployed, ..., max_metric_calls=120)
             better = client.continue_optimization(best, max_metric_calls=120)
 
+        With ``model``, the new run is a model sweep: the candidate runs and optimizes on
+        that student model instead of the completed run's. A loop over models compares
+        them on one task::
+
+            for model in ["openai/gpt-4o-mini", "openai/gpt-4.1-nano"]:
+                swept = client.continue_optimization(best, model=model, auto="light")
+                print(model, swept.score)
+
         Args:
             run: The completed run's ``op_`` id, or the ``DeployedProgram`` an
                 optimization returned.
             candidate: The ``ca_`` id of the candidate to start from, as
                 ``list_candidates`` and ``cmpnd optimizations candidates`` list it. The
                 default is the run's best.
+            model: The student model the new run spends, as a deploy records it, for
+                example ``"openai/gpt-4o-mini"``. The default is the completed run's.
+                Only the program's own model changes: a predictor with its own LM, the
+                run's ``lms`` and the reflection model stay as the completed run had
+                them.
+            credential: The credential the student model spends, from
+                ``cmpnd.credentials.get(NAME)``. The default is the completed run's.
             max_metric_calls: The budget as a ceiling on metric calls. Pass this or
                 ``auto``, exactly one.
             auto: The budget as ``"light"``, ``"medium"`` or ``"heavy"``.
@@ -754,11 +771,15 @@ class Client:
         Raises:
             ValueError: No budget or two budgets, or a ``DeployedProgram`` that no
                 optimization produced.
+            TypeError: ``credential`` is a string. Look a credential up with
+                ``cmpnd.credentials.get``.
             OptimizeError: The platform refused the continuation. Its ``error_code``
-                says why, for example ``not_completed`` or ``unknown_candidate``.
+                says why, for example ``not_completed``, ``unknown_candidate`` or
+                ``no_credential``.
             OptimizeFailed: The new run transitioned to ``status="failed"``.
         """
         self._check_active()
+        credential_name = credentials.name_of(credential, "cmpnd.Client.continue_optimization(credential=)")
         from . import execution, optimization
 
         run_id = run.optimization_run_id if isinstance(run, execution.DeployedProgram) else run
@@ -770,6 +791,8 @@ class Client:
             run_id,
             cfg=self._config,
             candidate=candidate,
+            model=model,
+            credential_name=credential_name,
             max_metric_calls=max_metric_calls,
             auto=auto,
             poll_interval=poll_interval,
@@ -813,6 +836,47 @@ class Client:
 
         return optimization.list_candidates(run_id, cfg=self._config)
 
+    def list_deployments(
+        self, *, status: str | None = None, since: str | None = None, limit: int = 50, offset: int = 0
+    ) -> list[dict[str, Any]]:
+        """The organization's deployments, newest first.
+
+        Returns the list itself, not the response envelope. ``status`` is one of
+        ``pending``, ``parsing``, ``optimizing``, ``ready`` or ``failed``, and
+        ``since`` is an ISO 8601 timestamp. ``offset`` must be a whole multiple of
+        ``limit``, because the route pages by page number. ``limit`` must not
+        exceed 500, the most deployments the route returns per page.
+        """
+        self._check_active()
+        page = _deployments.list_deployments(
+            status=status,
+            since=since,
+            limit=limit,
+            offset=offset,
+            api_key=self._config.api_key,
+            endpoint=self._config.endpoint,
+        )
+        return page.get("deployments", [])
+
+    def get_deployment(self, deployment_id: str) -> dict[str, Any]:
+        """Fetch one deployment's record: its status, program, model and metadata."""
+        self._check_active()
+        return _deployments.get_deployment(deployment_id, api_key=self._config.api_key, endpoint=self._config.endpoint)
+
+    def get_deployment_source(self, deployment_id: str, path: str | None = None) -> str:
+        """Read the program source a deployment stores, as text.
+
+        Without ``path`` it returns the program file the deployment runs. A
+        continuation's deployment holds the chosen candidate's program, so this
+        reads what the continuation runs. ``path`` names another archive-relative
+        file of the stored bundle. The file decodes with the encoding its PEP 263
+        coding comment declares, and with UTF-8 when it declares none.
+        """
+        self._check_active()
+        return _deployments.get_source(
+            deployment_id, path=path, api_key=self._config.api_key, endpoint=self._config.endpoint
+        )
+
     def get_deployment_signature(self, deployment_id: str) -> DeploymentSignatureResponse:
         """Fetch one deployment's persisted artifact metadata."""
         self._check_active()

{cmpnd-0.65.0 → cmpnd-0.67.0}/cmpnd/deployment.py

@@ -345,7 +345,7 @@ def _resolve_mcp_tool_references(client: httpx.Client, config, references: list[
                 f"your organization's registry holds no tool named {reference.tool_name!r} on "
                 f"{reference.server_url}, so this deploy cannot pin the schema its calls would be "
                 "validated against. Read what the registry does hold with "
-                f"`cmpnd tool-servers show {server_id}`, and if the server has grown the tool since it "
+                f"`cmpnd tool-servers show {server_id} --text`, and if the server has grown the tool since it "
                 f"was registered, `cmpnd tool-servers refresh {server_id}` re-reads its listing."
             )
         pinned[(reference.server_url, reference.tool_name)] = mcp_servers.PinnedTool(