cmpnd 0.58.0__tar.gz → 0.60.0__tar.gz

{cmpnd-0.58.0 → cmpnd-0.60.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.58.0
+Version: 0.60.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>

{cmpnd-0.58.0 → cmpnd-0.60.0}/cmpnd/cli/commands/programs.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 import urllib.parse
 from argparse import ArgumentParser, _SubParsersAction
@@ -12,8 +13,8 @@ from .. import api_client, pagination
 from . import provider_credentials
 
 
-# Every id in this group is the value `programs list` prints as `program_hash`,
-# which the routes resolve as a *compiled* program hash — they look it up
+# The hash that show, traces, stats, usage and select take is the value `programs optimized list`
+# prints as `program_hash`, which the routes resolve as a *compiled* program hash — they look it up
 # against optimization runs and map it to a program signature hash internally.
 # The two hashes are different values, so a real signature hash 404s here. The
 # argument help says which one it wants rather than naming the concept the
@@ -48,34 +49,74 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     create.add_argument("--json", action="store_true", help="Emit the created program as JSON instead of its id")
     create.set_defaults(func=handle_create)
 
-    ls = sub.add_parser("list", help="List programs")
-    ls.add_argument("--name", dest="program_name", help="Filter by program name")
-    ls.add_argument("--model", dest="model_name", help="Filter by model name")
+    ls = sub.add_parser(
+        "list",
+        help="List your organization's programs",
+        description=(
+            "List your organization's live programs, newest first, with each program's name and p_ id. A program "
+            "lists from its creation on, before anything runs under it. With --trashed, list the Trash instead."
+        ),
+    )
     ls.add_argument(
         "--trashed",
         action="store_true",
         help="List the programs in the Trash instead, with when each is purged",
     )
-    ls.add_argument("--order-by", default="run_count", help="Sort field (default: run_count)")
-    ls.add_argument("--order", default="desc", choices=["asc", "desc"], help="Sort direction")
     pagination.add_args(ls, with_page_aliases=True, default_limit=50)
+    # The optimized-program filters and sort moved to `programs optimized list`. They stay declared so that a
+    # command that passes one gets an error naming the command that takes it.
+    for flag, dest in [
+        ("--name", "program_name"),
+        ("--model", "model_name"),
+        ("--order-by", "order_by"),
+        ("--order", "order"),
+    ]:
+        ls.add_argument(flag, dest=dest, default=None, help=argparse.SUPPRESS)
     ls.set_defaults(func=handle_list)
 
+    # The optimized programs are the compiled programs optimization runs produced, grouped by compiled program
+    # hash. They are different records from the org's programs, so they nest, as the registry does.
+    optimized = sub.add_parser("optimized", help="Browse the optimized programs that optimization runs produced")
+    optimized_sub = optimized.add_subparsers(dest="optimized_action")
+    opt_list = optimized_sub.add_parser(
+        "list",
+        help="List optimized programs by compiled program hash",
+        description=(
+            "List the compiled programs your optimization runs produced, one row per compiled program hash, with "
+            "their run counts and scores. `programs show`, `traces`, `stats` and `usage` take the hash from the "
+            "program_hash column."
+        ),
+    )
+    opt_list.add_argument("--name", dest="program_name", help="Filter by program name")
+    opt_list.add_argument("--model", dest="model_name", help="Filter by model name")
+    opt_list.add_argument("--order-by", default="run_count", help="Sort field (default: run_count)")
+    opt_list.add_argument("--order", default="desc", choices=["asc", "desc"], help="Sort direction")
+    pagination.add_args(opt_list, with_page_aliases=True, default_limit=50)
+    opt_list.set_defaults(func=handle_optimized_list)
+
     show = sub.add_parser("show", help="Show program detail")
-    show.add_argument("id", help="Program hash, as `programs list` prints it in the program_hash column")
+    show.add_argument(
+        "id", help="Compiled program hash, as `programs optimized list` prints it in the program_hash column"
+    )
     show.set_defaults(func=handle_show)
 
     tr = sub.add_parser("traces", help="List traces for a program")
-    tr.add_argument("id", help="Program hash, as `programs list` prints it in the program_hash column")
+    tr.add_argument(
+        "id", help="Compiled program hash, as `programs optimized list` prints it in the program_hash column"
+    )
     pagination.add_args(tr, with_page_aliases=False, default_limit=50)
     tr.set_defaults(func=handle_traces)
 
     stats = sub.add_parser("stats", help="Show a program's execution statistics")
-    stats.add_argument("id", help="Program hash, as `programs list` prints it in the program_hash column")
+    stats.add_argument(
+        "id", help="Compiled program hash, as `programs optimized list` prints it in the program_hash column"
+    )
     stats.set_defaults(func=handle_stats)
 
     usage = sub.add_parser("usage", help="Show a program's trace volume, tokens and cost over time")
-    usage.add_argument("id", help="Program hash, as `programs list` prints it in the program_hash column")
+    usage.add_argument(
+        "id", help="Compiled program hash, as `programs optimized list` prints it in the program_hash column"
+    )
     usage.add_argument("--hours", type=int, default=24, help="Rolling window in hours (default %(default)s)")
     # Constrained on purpose: an unrecognised period buckets hourly server-side
     # rather than failing, so a typo would answer a different question silently.
@@ -132,7 +173,9 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     purge.set_defaults(func=handle_purge)
 
     select = sub.add_parser("select", help="Pin an optimization run as this program's chosen version")
-    select.add_argument("id", help="Program hash, as `programs list` prints it in the program_hash column")
+    select.add_argument(
+        "id", help="Compiled program hash, as `programs optimized list` prints it in the program_hash column"
+    )
     select.add_argument("--run", dest="run_id", required=True, help="Optimization run ID (op_...) to pin")
     select.set_defaults(func=handle_select)
 
@@ -178,14 +221,24 @@ def handle_create(client: api_client.ApiClient, args: Any) -> Any:
 
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
+    """List the org's live programs by name and p_ id, or the Trash with ``--trashed``."""
+    for attr, flag in [
+        ("program_name", "--name"),
+        ("model_name", "--model"),
+        ("order_by", "--order-by"),
+        ("order", "--order"),
+    ]:
+        if getattr(args, attr, None) is not None:
+            from . import top
+
+            raise api_client.CliError(
+                f"{flag} filters the optimized programs, which `{top.hint_programs('optimized', 'list')}` lists. "
+                f"`{top.hint_programs('list')}` lists your organization's programs by name and p_ id."
+            )
     if getattr(args, "trashed", False):
-        # The Trash is its own short list, unpaged and newest first, so the search filters, sort and paging do
-        # not apply. A flag left at its default cannot be told apart from one not passed.
+        # The Trash is its own short list, unpaged and newest first, so paging does not apply. A flag left at its
+        # default cannot be told apart from one not passed.
         for attr, flag, default in [
-            ("program_name", "--name", None),
-            ("model_name", "--model", None),
-            ("order_by", "--order-by", "run_count"),
-            ("order", "--order", "desc"),
             ("limit", "--limit", 50),
             ("offset", "--offset", 0),
             ("per_page", "--per-page", None),
@@ -194,6 +247,59 @@ def handle_list(client: api_client.ApiClient, args: Any) -> Any:
             if getattr(args, attr, default) != default:
                 raise api_client.CliError(f"{flag} does not apply to --trashed, which lists the whole Trash")
         return client.get("/api/v1/programs/trash")
+    params = pagination.wire(args, "limit_offset", as_str=True)
+    # Read as text: a server from before the program list, such as self-host release 2026-001, redirects this
+    # path to its dispatcher, and the redirect's body is HTML.
+    try:
+        raw = client.get_text("/api/v1/programs", params=params)
+    except api_client.CliError as exc:
+        if exc.status_code not in (404, 405):
+            raise
+        return _list_recorded(client, params)
+    try:
+        listed = json.loads(raw)
+    except ValueError:
+        listed = None
+    if isinstance(listed, dict) and "programs" in listed:
+        return listed
+    return _list_recorded(client, params)
+
+
+# GET /api/v1/modules on a server from before the program list answers at most this many programs
+# (modulesPageCap in self-host release 2026-001), and nothing pages past them.
+_RECORDED_PROGRAMS_CAP = 200
+
+
+def _list_recorded(client: api_client.ApiClient, params: dict[str, str]) -> dict[str, Any]:
+    """List the programs a server from before the program list recorded traces for, paged here.
+
+    GET /api/v1/modules answers them in one array, by name and legacy hash, up to its cap. A program with no
+    traces yet is not in it. A full array may be missing programs past the cap, so the answer then has no total
+    and says it is incomplete.
+    """
+    rows = client.get("/api/v1/modules")
+    if not isinstance(rows, list):
+        raise api_client.CliError(
+            "this cmpnd server answered neither the program list nor the list of recorded programs"
+        )
+    complete = len(rows) < _RECORDED_PROGRAMS_CAP
+    note = "note: this cmpnd server predates the program list, so this lists the programs it recorded traces for."
+    if not complete:
+        note += f" It answers at most {_RECORDED_PROGRAMS_CAP} of them, so programs past those are missing."
+    print(note + " Upgrade the server to list every program by name and p_ id.", file=sys.stderr)
+    limit, offset = int(params["limit"]), int(params["offset"])
+    return {
+        "programs": rows[offset : offset + limit],
+        "total": len(rows) if complete else None,
+        "complete": complete,
+        "limit": limit,
+        "offset": offset,
+        "has_more": offset + limit < len(rows),
+    }
+
+
+def handle_optimized_list(client: api_client.ApiClient, args: Any) -> Any:
+    """List the optimized programs, one row per compiled program hash."""
     params: dict[str, str] = pagination.wire(args, "per_page", as_str=True)
     params["order_by"] = args.order_by
     params["order_direction"] = args.order

{cmpnd-0.58.0 → cmpnd-0.60.0}/cmpnd/cli/commands/top.py

@@ -890,6 +890,34 @@ def _program_args(args: Any, verb: str, *, needs_name: bool = True) -> str | Non
     return name
 
 
+class _CredentialLookup:
+    """Turn a credential name a flag gave into the organization's ``cmpnd.Credential``.
+
+    Every command that takes a credential name looks it up here, before it stages or
+    sends anything. The lookup is ``cmpnd.credentials.get``, the line a Python caller
+    writes, so a mistyped name fails on the command line with the organization's names
+    and the nearest one. Serve checks the name again when the deploy or run names it,
+    which catches a credential revoked in between. Each distinct name is read once.
+    """
+
+    def __init__(self, client: api_client.ApiClient) -> None:
+        self._client = client
+        self._found: dict[str, Any] = {}
+
+    def __call__(self, flag: str, name: str) -> Any:
+        """The credential ``name``. ``flag`` is how the command line spelled it, for the error."""
+        from ... import credentials
+
+        if name not in self._found:
+            try:
+                self._found[name] = credentials.get(
+                    name, api_key=self._client._api_key, endpoint=self._client._endpoint
+                )
+            except credentials.CredentialNotFound as exc:
+                raise api_client.CliError(f"{flag}: {exc}") from exc
+        return self._found[name]
+
+
 def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
     """Stage authored Python and deploy the checked bundle.
 
@@ -904,12 +932,18 @@ def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
         dspy.configure(lm=lm)
         program = dspy.Predict("question -> answer")
         PY
+
+    ``--credential NAME`` names the credential the program's model spends, and is looked
+    up before the source is staged.
     """
     from pathlib import Path
 
     from ... import authored, deployment
 
     program_name = _program_args(args, "deploy")
+    credential_name = getattr(args, "credential", None)
+    if credential_name is not None:
+        credential_name = _CredentialLookup(client)(f"--credential {credential_name}", credential_name).name
     try:
         if args.source == "-" or args.source is None:
             prepared = authored.prepare_stdin(
@@ -939,7 +973,7 @@ def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
             metadata=metadata,
             program_name=program_name,
             config=sdk_config(client),
-            credential_name=getattr(args, "credential", None),
+            credential_name=credential_name,
         )
     except ValueError as exc:
         raise api_client.CliError(str(exc)) from exc
@@ -978,6 +1012,67 @@ def _optimizer_arg(value: str) -> str:
     return value
 
 
+def _lm_credential_arg(value: str) -> tuple[str, str]:
+    """Parse ``--lm-credential BINDING=NAME`` into the binding and the credential's name.
+
+    The program's own model is refused here, at parse time, because it spends the run's
+    credential and ``--credential`` already names that.
+    """
+    binding, sep, name = value.partition("=")
+    if not sep or not binding or not name:
+        raise ArgumentTypeError(
+            f"{value!r} is not BINDING=NAME. Give the name of an LM the optimize file's `lms` binds, then a "
+            "credential `cmpnd credentials list` shows, as in judge=typesafe"
+        )
+    from ... import optimization
+
+    if binding == optimization.DEFAULT_LM_BINDING:
+        raise ArgumentTypeError(
+            f"{binding} is the program's own model, which spends the run's credential. Name it with --credential"
+        )
+    return binding, name
+
+
+def _optimize_credentials(
+    client: api_client.ApiClient, args: Any
+) -> tuple[Any, str | Any | None, dict[str, Any] | None]:
+    """Look up every credential an optimize names, before the file is staged.
+
+    Returns the run's credential, the reflection LM to pass (the model name, wrapped in
+    ``cmpnd.HostedLM`` when ``--reflection-credential`` names its credential) and the
+    credential per binding. :class:`_CredentialLookup` turns each name into a
+    ``cmpnd.Credential``, so a mistyped one fails before the import and the deploy a run
+    makes ahead of its first step.
+    """
+    from ...lm_configuration import HostedLM
+
+    pairs: list[tuple[str, str]] = list(getattr(args, "lm_credential", None) or [])
+    seen: set[str] = set()
+    for binding, _ in pairs:
+        if binding in seen:
+            raise api_client.CliError(
+                f"--lm-credential names the binding {binding!r} more than once. Give each binding one credential."
+            )
+        seen.add(binding)
+    reflection_model = getattr(args, "reflection_model", None)
+    reflection_name = getattr(args, "reflection_credential", None)
+    if reflection_name is not None and reflection_model is None:
+        raise api_client.CliError(
+            "--reflection-credential names the credential the reflection model spends, so it needs --reflection-model."
+        )
+
+    lookup = _CredentialLookup(client)
+    run_name = getattr(args, "credential", None)
+    run = lookup(f"--credential {run_name}", run_name) if run_name is not None else None
+    reflection_lm: str | HostedLM | None = reflection_model
+    if reflection_name is not None and reflection_model is not None:
+        reflection_lm = HostedLM(
+            reflection_model, credential=lookup(f"--reflection-credential {reflection_name}", reflection_name)
+        )
+    lm_credentials = {binding: lookup(f"--lm-credential {binding}={name}", name) for binding, name in pairs}
+    return run, reflection_lm, lm_credentials or None
+
+
 def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
     """Optimize the program, metric and proposer one authored file binds.
 
@@ -1001,6 +1096,11 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
             return dspy.Prediction(score=float(ok),
                                    feedback="" if ok else f"expected {gold.answer}")
         PY
+
+    The file cannot name a credential, because the kernel that imports it reaches no
+    platform. ``--credential`` names the run's, ``--reflection-credential`` the
+    reflection model's and ``--lm-credential BINDING=NAME`` one of the file's ``lms``.
+    Each name is looked up before the file is staged.
     """
     from pathlib import Path
 
@@ -1008,6 +1108,7 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
 
     deployment_id = getattr(args, "deployment_id", None)
     program_name = _program_args(args, "optimize", needs_name=deployment_id is None)
+    credential, reflection_lm, lm_credentials = _optimize_credentials(client, args)
     try:
         if args.source == "-" or args.source is None:
             prepared = authored.prepare_optimize_stdin(
@@ -1041,7 +1142,9 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
             # The flag is named for what a command line can carry — a model name,
             # never an LM object — and the parameter for what the Python surface
             # accepts. Each layer's name says what that layer takes.
-            reflection_lm=getattr(args, "reflection_model", None),
+            reflection_lm=reflection_lm,
+            credential=credential,
+            lm_credentials=lm_credentials,
             max_metric_calls=getattr(args, "max_metric_calls", None),
             auto=getattr(args, "auto", None),
             max_steps=getattr(args, "max_steps", 10),
@@ -1402,6 +1505,8 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
             "--reflection-model openai/gpt-4o --auto light\n"
             "  cmpnd optimize gepa - capital-qa --reflection-model openai/gpt-4o "
             "--max-metric-calls 60 < task.py\n"
+            "  cmpnd optimize gepa task.py capital-qa --reflection-model openai/gpt-4o --auto light "
+            "--credential openai --lm-credential judge=typesafe\n"
             "  cmpnd optimize gepa task.py --reflection-model openai/gpt-4o --auto light --deployment-id d_a1b2c3d4\n"
         ),
         formatter_class=raw,
@@ -1438,6 +1543,31 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         "instructions (required for gepa; the server will not substitute the "
         "deployment's own model)",
     )
+    opt.add_argument(
+        "--credential",
+        metavar="NAME",
+        default=None,
+        help="The provider credential the run spends: the program's model, and every model that names no "
+        "credential of its own (default: the organization's default credential). "
+        "`cmpnd credentials list` shows the names",
+    )
+    opt.add_argument(
+        "--reflection-credential",
+        dest="reflection_credential",
+        metavar="NAME",
+        default=None,
+        help="The credential the reflection model spends instead of the run's",
+    )
+    opt.add_argument(
+        "--lm-credential",
+        dest="lm_credential",
+        metavar="BINDING=NAME",
+        type=_lm_credential_arg,
+        action="append",
+        default=None,
+        help="The credential one LM of the file's `lms` spends instead of the run's, as judge=typesafe. Repeat it "
+        "for each binding",
+    )
     # A budget is mandatory and the optimizer will not choose one — see
     # `cmpnd.optimization._apply_budget`. Two flags rather than one because a
     # caller who does not yet know what a run costs reaches for `--auto`, and one

{cmpnd-0.58.0 → cmpnd-0.60.0}/cmpnd/cli/verbs.py

@@ -185,6 +185,7 @@ RELATION_NOUNS: dict[str, str] = {
     "failed-examples": "the examples a compared candidate got wrong",
     "examples": "the examples belonging to a dataset or an eval run",
     "registry": "the registered programs or signatures, as distinct from the observed ones",
+    "optimized": "the compiled programs optimization runs produced, as distinct from the organization's programs",
     "stats": "a program's execution statistics",
     "usage": "a program's usage over time",
     "openapi": "the OpenAPI document a deployment serves",

{cmpnd-0.58.0 → cmpnd-0.60.0}/cmpnd/optimization.py

@@ -508,6 +508,62 @@ def _lms_config(config: dict[str, Any], lms: Any) -> None:
     config["lms"] = declared
 
 
+def _lm_credentials_config(config: dict[str, Any], lm_credentials: Any) -> None:
+    """Name the credential each of the run's declared LM bindings spends.
+
+    An authored file declares its ``lms`` and cannot name a credential for one, because
+    the kernel that imports it again reaches no platform to look one up. So the call that
+    starts the run names it, by binding name, and the entry gains the ``credential`` field
+    that ``cmpnd.HostedLM(lm, credential=)`` and ``cmpnd.SystemOne(model, credential=)``
+    give it in a live-object call. The wire shape is the same either way.
+
+    Each binding must be one the run declares, and must not already name a credential:
+    a second credential for one binding is two answers to one question, the refusal
+    :func:`_reflection_config` makes of ``reflection_credential``. The program's own
+    model spends the run's ``credential=``, so ``default-lm`` is refused here.
+
+    ``config["lms"]`` is replaced rather than edited, because it may be the dict the
+    import child reported, which the caller's prepared file still holds.
+    """
+    if not lm_credentials:
+        return
+    if not isinstance(lm_credentials, dict):
+        raise ValueError(f"lm_credentials must map binding names to credentials (got {type(lm_credentials).__name__})")
+    declared: dict[str, Any] = config.get("lms") or {}
+    named: dict[str, str] = {}
+    for binding, credential in lm_credentials.items():
+        if binding == DEFAULT_LM_BINDING:
+            raise ValueError(
+                f"{DEFAULT_LM_BINDING!r} is the program's own model, and it spends the run's credential. "
+                "Name that credential for the run instead of for a binding."
+            )
+        name = credentials.name_of(credential, f"lm_credentials[{binding!r}]")
+        if name is None:
+            continue
+        if binding not in declared:
+            if not declared:
+                raise ValueError(
+                    f"a credential is named for the LM binding {binding!r}, and the optimize file binds no "
+                    "`lms`, so the run has no binding to spend it."
+                )
+            raise ValueError(
+                f"a credential is named for the LM binding {binding!r}, and the optimize file's `lms` binds no "
+                f"such name. It binds {', '.join(repr(each) for each in sorted(declared))}."
+            )
+        existing = declared[binding].get("credential")
+        if existing is not None:
+            raise ValueError(
+                f"the LM binding {binding!r} already names the credential {existing!r}, and a second one was "
+                f"named for it: these are two answers to which credential it spends. Keep one."
+            )
+        named[binding] = name
+    if named:
+        config["lms"] = {
+            binding: {**entry, "credential": named[binding]} if binding in named else entry
+            for binding, entry in declared.items()
+        }
+
+
 def _check_metric_call(metric: Callable[..., Any], optimizer: str) -> None:  # pyright: ignore[reportUnusedFunction]  # called by the authored import child
     """Check the authored metric against the kernel's positional and named arguments."""
     signature = inspect.signature(metric)
@@ -938,6 +994,7 @@ def optimize_authored(
     config: dict[str, Any] | None = None,
     reflection_lm: str | Any | None = None,
     lms: dict[str, Any] | None = None,
+    lm_credentials: dict[str, credentials.Credential] | None = None,
     credential: credentials.Credential | None = None,
     max_metric_calls: int | None = None,
     auto: str | None = None,
@@ -972,6 +1029,9 @@ def optimize_authored(
     resolves, because that deployment already has its program.
 
     ``credential`` is the run's credential, as on :func:`optimize_deployment`.
+    ``lm_credentials`` maps a binding the file's ``lms`` declares to the credential it
+    spends instead, which the file itself cannot name. A ``cmpnd.HostedLM`` or
+    ``cmpnd.SystemOne`` names one in a live-object call.
     """
     check_optimizer(optimizer)
     credential_name = credentials.name_of(credential, "optimize_authored(credential=)")
@@ -985,6 +1045,7 @@ def optimize_authored(
             config["lms"] = prepared.facts.lms
     _reflection_config(config, reflection_lm)
     _lms_config(config, lms)
+    _lm_credentials_config(config, lm_credentials)
     _apply_budget(config, max_metric_calls=max_metric_calls, auto=auto)
 
     if prepared.program_bundle is None and deployment_id is not None and program_name is not None:

{cmpnd-0.58.0 → cmpnd-0.60.0}/docs/cli.md

@@ -41,6 +41,27 @@ The CLI refuses `--program-id`, `cmpnd programs create` without a program
 name, and its `--name`. These inputs are deprecated, and the error shows the
 program name form.
 
+`cmpnd programs list` lists your organization's live programs, newest first,
+with each program's `name` and `program_id`. It reads `GET /api/v1/programs`,
+which lists a program from its creation on, before anything runs under it. A
+program with no name has a null `name`. The answer also holds `total`, the
+count of live programs, and `has_more`. The command pages with `--limit` and
+`--offset`, and needs `traces:read`.
+
+A server from before the program list, such as self-host release 2026-001, has
+no `GET /api/v1/programs`. Against one, `cmpnd programs list` says so on stderr
+and lists the programs that server recorded traces for, from
+`GET /api/v1/modules`, by name and legacy hash. A program with no traces yet is
+not in that list. That route answers at most 200 programs, so when it is full
+the answer has a null `total`, `complete` is false, and the note says programs
+are missing.
+
+`cmpnd programs optimized list` lists the compiled programs that optimization
+runs produced, one row per compiled program hash, from
+`GET /api/v1/programs/v2`. It takes `--name`, `--model`, `--order-by` and
+`--order`. `cmpnd programs list` refuses those flags with an error that names
+`cmpnd programs optimized list`.
+
 ## The Trash
 
 A program in the Trash leaves every view, and its traces with it, until it is
@@ -194,9 +215,11 @@ model and the field, never the value. Seal the key with
 `cmpnd credentials create` instead.
 
 `--credential NAME` names the provider credential the program's model spends.
-Without it, the deployment spends the organization's default. The CLI sends the
-name as typed, and the platform refuses a name the organization does not hold
-and names the nearest one. The deploy prints the protocol, model and
+Without it, the deployment spends the organization's default. The CLI looks
+the name up before it stages the source. A name the organization does not hold
+fails with the names it does hold and the nearest one, and nothing is sent.
+The platform checks the name again at the deploy, which catches a credential
+an owner revoked in between. The deploy prints the protocol, model and
 credential of each binding, such as
 `default-lm: chat_completions openai/deepseek-4.1-flash → luna-exec (https://gw.lunaroute.com)`.
 
@@ -279,10 +302,10 @@ Some older spellings still run as deprecated aliases and print a warning:
 - `credentials add` for `create`
 
 Every list command pages with `--limit` and `--offset`. The `traces`, `evals`,
-`optimizations`, `deployments` and `programs` lists also accept `--page` and
-`--per-page` as deprecated aliases. On those page-number commands, `--offset`
-must be a multiple of `--limit`, and the error names the nearest valid
-offsets. `deployments runs list` still accepts the deprecated `--cursor`, which
+`optimizations`, `deployments`, `programs` and `programs optimized` lists also
+accept `--page` and `--per-page` as deprecated aliases. Every one of those
+except `programs list` pages by page number on the wire, so its `--offset` must
+be a multiple of `--limit`, and the error names the nearest valid offsets. `deployments runs list` still accepts the deprecated `--cursor`, which
 pages from a previous response's `next_cursor` and cannot be combined with
 `--offset`.
 
@@ -331,9 +354,10 @@ The `signatures` and `programs` groups name programs differently.
 hash, which identifies a program's inputs and outputs and everything recorded
 under them: traces, examples, evals and revisions. The CLI passes an id
 through unchanged, and serve tells the two apart by the `p_` prefix.
-`cmpnd programs` reads take a compiled program hash, the value in the
-`program_hash` column of `cmpnd programs list`, and its Trash commands take a
-program name or id ("The Trash" above). Its routes resolve the hash
+`cmpnd programs show`, `traces`, `stats`, `usage` and `select` take a compiled
+program hash, the value in the `program_hash` column of
+`cmpnd programs optimized list`. `cmpnd programs list` prints names and ids, and
+the Trash commands take a program name or id ("The Trash" above). Its routes resolve the hash
 through optimization runs, so they do not find a signature hash. Each group's
 `--help` names the column its IDs come from.
 
@@ -618,6 +642,27 @@ organization must hold provider credentials for every model the run uses.
 Named model declarations hold model names and sampling settings, and the CLI
 refuses a provider key on them.
 
+A run spends the organization's default credential unless the command names
+another. `--credential NAME` names the run's credential. The program's model
+spends it, and so does every model that names no credential of its own.
+`--reflection-credential NAME` names the credential the reflection model
+spends. `--lm-credential BINDING=NAME` names the credential one model in the
+file's `lms` spends, and repeats once per binding:
+
+```bash
+cmpnd optimize gepa task.py capital-qa --reflection-model openai/gpt-5 --auto light \
+  --credential openai --lm-credential judge=typesafe
+```
+
+The file cannot name a credential itself, because the kernel imports it again
+and reaches no platform there. These flags send what `credential=`,
+`cmpnd.HostedLM(lm, credential=)` and `cmpnd.SystemOne(model, credential=)`
+send from Python. The CLI looks up every name before it stages the file. A
+name the organization does not hold fails with the names it does hold and the
+nearest one. The CLI also refuses `--lm-credential` for a binding the file's
+`lms` does not declare, for one binding twice and for `default-lm`. The
+program's own model spends the run's credential, so `--credential` names it.
+
 `cmpnd.Client.optimize_deployment(deployment, metric=fn)` in a notebook packages
 live objects and takes named models through its `lms` argument. An authored file's `lms`
 binding cannot be combined with `lms` in the parent call or `config["lms"]`.

{cmpnd-0.58.0 → cmpnd-0.60.0}/pyproject.toml

@@ -5,7 +5,7 @@ name = "cmpnd"
 # it's new) — no git tags. Bump with `uv version --bump {minor,patch}` or by
 # hand. Runtime `cmpnd.__version__` reads installed metadata, so it tracks
 # this automatically. See docs/plans/2026-07-02-sdk-pypi-tag-free-publish.md.
-version = "0.58.0"
+version = "0.60.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

{cmpnd-0.58.0 → cmpnd-0.60.0}/scripts/test-in-linux.sh

@@ -33,7 +33,7 @@ set -euo pipefail
 
 SDK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 REPO_DIR="$(cd "${SDK_DIR}/.." && pwd)"
-IMAGE="${SDK_TEST_LINUX_IMAGE:-ghcr.io/astral-sh/uv:python3.12-bookworm-slim}"
+IMAGE="${SDK_TEST_LINUX_IMAGE:-ghcr.io/astral-sh/uv:python3.12-trixie-slim}"
 ARGS=("$@")
 if [ ${#ARGS[@]} -eq 0 ]; then
     ARGS=(tests/ -k "not e2e")