cmpnd 0.60.0__tar.gz → 0.61.0__tar.gz

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

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

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

@@ -13,12 +13,12 @@ from .. import api_client, pagination
 from . import provider_credentials
 
 
-# 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
-# route resolves it to, because the caller has only the former to paste.
+# `show`, `traces`, `stats` and `usage` take a program name or a p_ id, as the
+# Trash commands do. The `programs optimized` group and `select` take a compiled
+# program hash, the value `programs optimized list` prints as `program_hash`.
+# The routes resolve that hash against optimization runs, so a program
+# signature hash 404s there. A compiled hash and a program name have the same
+# shape, so no command takes both in one slot.
 def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     parser = subparsers.add_parser("programs", help="Create and browse programs")
     sub = parser.add_subparsers(dest="action")
@@ -83,7 +83,8 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         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 "
+            "their run counts and scores. `programs optimized show`, `traces`, `stats` and `usage` take the hash "
+            "from the "
             "program_hash column."
         ),
     )
@@ -94,37 +95,54 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     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="Compiled program hash, as `programs optimized list` prints it in the program_hash column"
+    opt_show = optimized_sub.add_parser("show", help="Show the optimization runs that produced a compiled program")
+    opt_show.add_argument("hash", help=_COMPILED_HASH_HELP)
+    opt_show.set_defaults(func=handle_optimized_show)
+
+    opt_traces = optimized_sub.add_parser("traces", help="List the traces of a compiled program's program")
+    opt_traces.add_argument("hash", help=_COMPILED_HASH_HELP)
+    pagination.add_args(opt_traces, with_page_aliases=False, default_limit=50)
+    opt_traces.set_defaults(func=handle_optimized_traces)
+
+    opt_stats = optimized_sub.add_parser("stats", help="Show the execution statistics of a compiled program's program")
+    opt_stats.add_argument("hash", help=_COMPILED_HASH_HELP)
+    opt_stats.set_defaults(func=handle_optimized_stats)
+
+    opt_usage = optimized_sub.add_parser("usage", help="Show the usage over time of a compiled program's program")
+    opt_usage.add_argument("hash", help=_COMPILED_HASH_HELP)
+    _add_usage_window(opt_usage)
+    opt_usage.set_defaults(func=handle_optimized_usage)
+
+    show = sub.add_parser(
+        "show",
+        help="Show a program",
+        description=(
+            "Show PROGRAM: its name, p_ id, whether it is in the Trash, its trace count and latest trace, and "
+            "the optimized programs its optimization runs produced."
+        ),
     )
+    show.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
     show.set_defaults(func=handle_show)
 
-    tr = sub.add_parser("traces", help="List traces for a program")
-    tr.add_argument(
-        "id", help="Compiled program hash, as `programs optimized list` prints it in the program_hash column"
+    tr = sub.add_parser(
+        "traces",
+        help="List a program's traces, newest first, over the widest window trace search reads",
+        description=(
+            "List PROGRAM's traces, newest first, through trace search over its widest window, 365 days. "
+            "`cmpnd traces list --hash ID --since DATE` sets the window itself. --limit is at most 500."
+        ),
     )
+    tr.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
     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="Compiled program hash, as `programs optimized list` prints it in the program_hash column"
-    )
+    stats = sub.add_parser("stats", help="Show a program's execution statistics over all history")
+    stats.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
     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="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.
-    usage.add_argument(
-        "--period",
-        choices=["minute", "5m", "10m", "30m", "hour", "day"],
-        help="Bucket width (default: hour)",
-    )
+    usage.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
+    _add_usage_window(usage)
     usage.set_defaults(func=handle_usage)
 
     # The registry is the programs an SDK client registered, as distinct from
@@ -173,13 +191,32 @@ 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="Compiled program hash, as `programs optimized list` prints it in the program_hash column"
-    )
+    select.add_argument("id", help=_COMPILED_HASH_HELP)
     select.add_argument("--run", dest="run_id", required=True, help="Optimization run ID (op_...) to pin")
     select.set_defaults(func=handle_select)
 
 
+_COMPILED_HASH_HELP = "Compiled program hash, as `programs optimized list` prints it in the program_hash column"
+
+
+def _add_usage_window(parser: ArgumentParser) -> None:
+    parser.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.
+    parser.add_argument(
+        "--period",
+        choices=["minute", "5m", "10m", "30m", "hour", "day"],
+        help="Bucket width (default: hour)",
+    )
+
+
+def _usage_params(args: Any) -> dict[str, str]:
+    params = {"hours": str(args.hours)}
+    if args.period:
+        params["period"] = args.period
+    return params
+
+
 def handle_create(client: api_client.ApiClient, args: Any) -> Any:
     """Create the program named ``args.name``, and refuse a name that already has one.
 
@@ -246,7 +283,7 @@ 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")
+        return _trash_listing(client)
     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.
@@ -310,24 +347,125 @@ def handle_optimized_list(client: api_client.ApiClient, args: Any) -> Any:
     return client.get("/api/v1/programs/v2", params=params)
 
 
+# A server from before program names, p_ ids and the Trash API, such as self-host release 2026-001, reads every
+# path under /api/v1/programs/ as a compiled program hash. A GET there answers 404 and a POST answers 405, and its
+# trace search ignores program_id. A current server answers the Trash listing with 200, so that read tells them
+# apart once a command has already failed.
+_OLD_SERVER = "this cmpnd server predates program names, p_ ids and the Trash API, as self-host release 2026-001 does."
+
+
+def _predates_program_ids(client: api_client.ApiClient) -> bool:
+    try:
+        client.get("/api/v1/programs/trash")
+    except api_client.CliError as exc:
+        return exc.status_code == 404
+    return False
+
+
+def _old_server_refusal(remedy: str) -> api_client.CliError:
+    return api_client.CliError(f"{_OLD_SERVER} {remedy}")
+
+
+def _refuse_if_old(client: api_client.ApiClient, exc: api_client.CliError, remedy: str) -> None:
+    """Raise the old-server refusal in place of ``exc`` when the server predates program ids."""
+    if exc.status_code in (404, 405) and _predates_program_ids(client):
+        raise _old_server_refusal(remedy) from exc
+
+
+def _trash_remedy() -> str:
+    return "Manage its Trash in the web app, at /ui/account/trash, or upgrade the server."
+
+
+def _read_remedy(verb: str) -> str:
+    from . import top
+
+    return (
+        f"`{top.hint_programs('optimized', verb, 'HASH')}` reads a compiled program hash there, and "
+        f"`{top.hint_programs('list')}` lists the programs it recorded traces for."
+    )
+
+
+def _resolve_for_read(client: api_client.ApiClient, ref: str, verb: str, *, trashed_ok: bool = False) -> str:
+    """Return the p_ id of the program ``ref`` names, for a read of its activity.
+
+    A program in the Trash has no activity to read, so it is refused unless
+    ``trashed_ok``. An unknown name may be a compiled program hash, which the
+    ``programs optimized`` command of the same verb takes.
+    """
+    from . import top
+
+    program_id, trashed = resolve(
+        client,
+        ref,
+        unknown_hint=f"A compiled program hash goes to `{top.hint_programs('optimized', verb, ref)}`.",
+        old_server_remedy=_read_remedy(verb),
+    )
+    if trashed and not trashed_ok:
+        raise api_client.CliError(
+            f"{ref} is in the Trash, so it has no activity to read. "
+            f"Restore it with `{top.hint_programs('restore', ref)}`."
+        )
+    return program_id
+
+
+def _read(client: api_client.ApiClient, verb: str, path: str, params: dict[str, str] | None = None) -> Any:
+    try:
+        return client.get(path) if params is None else client.get(path, params=params)
+    except api_client.CliError as exc:
+        _refuse_if_old(client, exc, _read_remedy(verb))
+        raise
+
+
 def handle_show(client: api_client.ApiClient, args: Any) -> Any:
-    return client.get(f"/api/v1/programs/{args.id}")
+    program_id = _resolve_for_read(client, args.program, "show", trashed_ok=True)
+    return _read(client, "show", f"/api/v1/programs/{program_id}")
+
+
+# Trace search reads a page_size above this as its default of 50, which would answer other rows than the ones asked
+# for.
+_MAX_TRACE_PAGE = 500
 
 
 def handle_traces(client: api_client.ApiClient, args: Any) -> Any:
-    params = pagination.wire(args, "limit_offset", as_str=True)
-    return client.get(f"/api/v1/programs/{args.id}/traces", params=params)
+    """List the program's traces through trace search, which takes a program id, over its widest window."""
+    if args.limit > _MAX_TRACE_PAGE:
+        raise api_client.CliError(
+            f"--limit is at most {_MAX_TRACE_PAGE}, the largest page trace search returns. Page with --offset."
+        )
+    program_id = _resolve_for_read(client, args.program, "traces")
+    body: dict[str, Any] = {"program_id": program_id, **pagination.wire(args, "page_size"), "max_window": True}
+    answer = client.post("/api/v1/traces/search", json=body)
+    # A server that ignores program_id answers every trace in the org, which must not pass for the program's.
+    if "program_id" in (answer.get("ignored_fields") or []):
+        raise _old_server_refusal(_read_remedy("traces"))
+    return answer
 
 
 def handle_stats(client: api_client.ApiClient, args: Any) -> Any:
-    return client.get(f"/api/v1/programs/{args.id}/execution-stats")
+    program_id = _resolve_for_read(client, args.program, "stats")
+    return _read(client, "stats", f"/api/v1/programs/{program_id}/execution-stats")
 
 
 def handle_usage(client: api_client.ApiClient, args: Any) -> Any:
-    params = {"hours": str(args.hours)}
-    if args.period:
-        params["period"] = args.period
-    return client.get(f"/api/v1/programs/{args.id}/usage-history", params=params)
+    program_id = _resolve_for_read(client, args.program, "usage")
+    return _read(client, "usage", f"/api/v1/programs/{program_id}/usage-history", _usage_params(args))
+
+
+def handle_optimized_show(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/programs/{args.hash}")
+
+
+def handle_optimized_traces(client: api_client.ApiClient, args: Any) -> Any:
+    params = pagination.wire(args, "limit_offset", as_str=True)
+    return client.get(f"/api/v1/programs/{args.hash}/traces", params=params)
+
+
+def handle_optimized_stats(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/programs/{args.hash}/execution-stats")
+
+
+def handle_optimized_usage(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/programs/{args.hash}/usage-history", params=_usage_params(args))
 
 
 def handle_registry_list(client: api_client.ApiClient, args: Any) -> Any:
@@ -351,12 +489,17 @@ def handle_select(client: api_client.ApiClient, args: Any) -> Any:
     return client.post(f"/api/v1/programs/{args.id}/select", json={"optimization_run_id": args.run_id})
 
 
-def _resolve(client: api_client.ApiClient, ref: str) -> tuple[str, bool | None]:
+def resolve(
+    client: api_client.ApiClient, ref: str, *, unknown_hint: str = "", old_server_remedy: str = ""
+) -> tuple[str, bool | None]:
     """Return the program id ``ref`` names, and whether it is in the Trash when known.
 
     A ``p_`` id is used as given, because no program name starts with ``p_``, and its
     Trash state is unknown until the route answers. A name is looked up, which never
-    makes a program, and the answer says whether it is in the Trash.
+    makes a program, and the answer says whether it is in the Trash. ``unknown_hint``
+    follows the error for a name no program has. On a server from before program
+    names the lookup fails too, and the error is the old-server refusal with
+    ``old_server_remedy``.
     """
     from ... import programs
 
@@ -370,7 +513,9 @@ def _resolve(client: api_client.ApiClient, ref: str) -> tuple[str, bool | None]:
         answer = client.get("/api/v1/programs/by-name/" + urllib.parse.quote(ref, safe=""))
     except api_client.CliError as exc:
         if exc.status_code == 404:
-            raise api_client.CliError(f"no program in your organization is named {ref!r}") from exc
+            _refuse_if_old(client, exc, old_server_remedy)
+            message = f"no program in your organization is named {ref!r}"
+            raise api_client.CliError(f"{message}. {unknown_hint}" if unknown_hint else message) from exc
         if exc.status_code == 410:
             raise api_client.CliError(f"{ref!r} belongs to a purged program, which nothing restores") from exc
         raise
@@ -381,21 +526,21 @@ def handle_trash(client: api_client.ApiClient, args: Any) -> Any:
     """Move a program to the Trash, which frees its place under the plan's program limit."""
     from . import top
 
-    program_id, trashed = _resolve(client, args.program)
+    program_id, trashed = resolve(client, args.program, old_server_remedy=_trash_remedy())
     if trashed:
         print(
             f"{args.program} is already in the Trash. Restore it with `{top.hint_programs('restore', args.program)}`.",
             file=sys.stderr,
         )
         return {"program_id": program_id, "trashed": True}
-    return client.post(f"/api/v1/programs/{program_id}/trash")
+    return _trash_write(client, f"/api/v1/programs/{program_id}/trash")
 
 
 def handle_restore(client: api_client.ApiClient, args: Any) -> Any:
     """Return a program from the Trash. The server refuses it when the plan's program limit is full."""
     from . import top
 
-    program_id, trashed = _resolve(client, args.program)
+    program_id, trashed = resolve(client, args.program, old_server_remedy=_trash_remedy())
     if trashed is False:
         # A name another program took from a Trashed one reaches the new, live program. The Trashed one is
         # restored by its id.
@@ -403,7 +548,7 @@ def handle_restore(client: api_client.ApiClient, args: Any) -> Any:
             f"{args.program} is not in the Trash. If its name now belongs to another program, restore the one "
             f"in the Trash by the p_ id that `{top.hint_programs('list', '--trashed')}` prints."
         )
-    return client.post(f"/api/v1/programs/{program_id}/restore")
+    return _trash_write(client, f"/api/v1/programs/{program_id}/restore")
 
 
 def handle_purge(client: api_client.ApiClient, args: Any) -> Any:
@@ -417,20 +562,38 @@ def handle_purge(client: api_client.ApiClient, args: Any) -> Any:
         # The count is for the person confirming. --force skips the listing, which needs traces:read, so a key
         # that may only write can still empty the Trash.
         if not args.force:
-            listed = client.get("/api/v1/programs/trash")
+            listed = _trash_listing(client)
             count = len(listed.get("programs") or [])
             if count == 0:
                 return {"purged": 0, "kept": 0}
             noun = "program" if count == 1 else "programs"
             provider_credentials.confirm(args, f"the {count} {noun} in the Trash for good", consequence)
-        return client.post("/api/v1/programs/trash/empty")
+        return _trash_write(client, "/api/v1/programs/trash/empty")
     if args.program is None:
         raise api_client.CliError("name the PROGRAM to purge, or pass --all to empty the Trash")
-    program_id, trashed = _resolve(client, args.program)
+    program_id, trashed = resolve(client, args.program, old_server_remedy=_trash_remedy())
     if trashed is False:
         raise api_client.CliError(
             f"{args.program} is live, and only a program in the Trash can be purged. "
             f"Move it there first with `{top.hint_programs('trash', args.program)}`."
         )
     provider_credentials.confirm(args, f"the program {args.program} for good", consequence)
-    return client.post(f"/api/v1/programs/{program_id}/purge")
+    return _trash_write(client, f"/api/v1/programs/{program_id}/purge")
+
+
+def _trash_listing(client: api_client.ApiClient) -> Any:
+    """GET the Trash. On a server from before the Trash API it answers 404, which is the old-server signal."""
+    try:
+        return client.get("/api/v1/programs/trash")
+    except api_client.CliError as exc:
+        if exc.status_code == 404:
+            raise _old_server_refusal(_trash_remedy()) from exc
+        raise
+
+
+def _trash_write(client: api_client.ApiClient, path: str) -> Any:
+    try:
+        return client.post(path)
+    except api_client.CliError as exc:
+        _refuse_if_old(client, exc, _trash_remedy())
+        raise

{cmpnd-0.60.0 → cmpnd-0.61.0}/cmpnd/cli/commands/valsets.py

@@ -8,6 +8,7 @@ inputs and expected outputs of one validation example.
 from __future__ import annotations
 
 import json
+import re
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
@@ -23,7 +24,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     create.add_argument(
         "program_hash",
         metavar="program",
-        help="Owning program: a program id (p_…), or a legacy signature hash "
+        help="Owning program: a program name, a program id (p_…), or a legacy signature hash "
         "(16-hex, as `cmpnd signatures list` shows)",
     )
     create.add_argument(
@@ -33,7 +34,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     create.set_defaults(func=handle_create)
 
     ls = sub.add_parser("list", help="List a program's validation sets")
-    ls.add_argument("program", help="Program id (p_…), or a legacy signature hash (16-hex)")
+    ls.add_argument("program", help="Program name, program id (p_…), or a legacy signature hash (16-hex)")
     pagination.add_args(ls, with_page_aliases=False, default_limit=50)
     ls.set_defaults(func=handle_list)
 
@@ -75,15 +76,39 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     edelete.set_defaults(func=handle_entries_delete)
 
 
+# A legacy program signature hash in its display form: 16 hex digits.
+_LEGACY_HASH = re.compile(r"[0-9a-fA-F]{16}")
+
+
+def _program(client: api_client.ApiClient, ref: str) -> str:
+    """The value the valsets routes take for ``ref``.
+
+    A p_ id and a legacy 16-hex hash pass unchanged. Anything else is a program
+    name, which resolves to its p_ id without making a program. A program whose
+    name is 16 hex digits is reached by its p_ id.
+    """
+    from . import programs
+
+    if _LEGACY_HASH.fullmatch(ref):
+        return ref
+    program_id, _ = programs.resolve(
+        client,
+        ref,
+        old_server_remedy="Name the program by its 16-hex signature hash, as `cmpnd signatures list` shows, "
+        "or upgrade the server.",
+    )
+    return program_id
+
+
 def handle_create(client: api_client.ApiClient, args: Any) -> Any:
     # One generator (cmpnd._valsets.default_name) for both the CLI and the
     # Client, so the collision-avoiding suffix can't drift between them.
     name = args.name or _valsets.default_name()
-    return client.post("/api/v1/valsets", json={"program": args.program_hash, "name": name})
+    return client.post("/api/v1/valsets", json={"program": _program(client, args.program_hash), "name": name})
 
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
-    params = {"program": args.program, **pagination.wire(args, "limit_offset", as_str=True)}
+    params = {"program": _program(client, args.program), **pagination.wire(args, "limit_offset", as_str=True)}
     return client.get("/api/v1/valsets", params=params)
 
 

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

@@ -62,6 +62,32 @@ runs produced, one row per compiled program hash, from
 `--order`. `cmpnd programs list` refuses those flags with an error that names
 `cmpnd programs optimized list`.
 
+`cmpnd programs show`, `traces`, `stats` and `usage` take a program name or a
+`p_` id. The CLI looks a name up with `GET /api/v1/programs/by-name/{name}`,
+which never makes a program. An unknown name fails with an error that names
+the `cmpnd programs optimized` command for a compiled program hash.
+
+- `show` prints the program's name and id, whether it is in the Trash, its
+  trace count, when its latest trace started, and the optimized programs its
+  completed optimization runs produced, newest first. It holds at most 499 of
+  them, and `optimized_programs_complete` is false when the program has more.
+- `traces` lists the program's traces, newest first, over the widest window
+  trace search reads, 365 days. It sends `POST /api/v1/traces/search` with
+  `program_id` and `max_window`. `--limit` is at most 500, the largest page the
+  search returns. `cmpnd traces list --hash ID --since DATE` reaches older
+  traces.
+- `stats` covers all history, and `usage` covers `--hours`, 24 by default.
+- A program in the Trash has no activity to read, so `traces`, `stats` and
+  `usage` refuse it. `show` reports it as Trashed.
+- On a server from before program names, such as self-host release 2026-001,
+  each of them fails with an error that names the `cmpnd programs optimized`
+  command for a compiled hash. Its trace search ignores `program_id`, so
+  `traces` refuses rather than print every trace in the organization.
+
+`cmpnd programs optimized show`, `traces`, `stats` and `usage` take a compiled
+program hash, the value in the `program_hash` column of
+`cmpnd programs optimized list`, as `cmpnd programs select` does.
+
 ## The Trash
 
 A program in the Trash leaves every view, and its traces with it, until it is
@@ -90,6 +116,13 @@ The purge job purges a program 7 days after it entered the Trash. Listing the
 Trash needs `traces:read`, and the other commands need `traces:write` or
 `optimizations:write`.
 
+A server from before program names, `p_` ids and the Trash API, such as
+self-host release 2026-001, reads every path under `/api/v1/programs/` as a
+compiled program hash. Against one, each Trash command fails with an error that
+says the server predates the Trash API and points at the web app's Trash page,
+`/ui/account/trash`. The CLI recognizes such a server once a command fails, by
+the `404` it answers to `GET /api/v1/programs/trash`.
+
 A plan may cap an organization's live programs, the ones outside the Trash
 that no optimization produced. At the cap, a new program name in
 `cmpnd programs create`, `cmpnd deploy` or `cmpnd optimize` and
@@ -354,12 +387,11 @@ 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 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.
+`cmpnd programs` commands take a program name or id ("Program names" and "The
+Trash" above). `cmpnd programs optimized` commands and `cmpnd programs select`
+take a compiled program hash, which their routes resolve through optimization
+runs, so they do not find a signature hash. Each group's `--help` names the
+column its IDs come from.
 
 `cmpnd deployments openapi <id>` prints the OpenAPI document a deployment
 serves, which an agent reads before it calls the deployment.
@@ -413,16 +445,19 @@ converted key stays in use, `org list` marks its org active, and
 
 `cmpnd valsets` manages validation sets that a program owns. A validation set
 is a named set of validation examples whose fields come from the owning
-program's signature. Name the program by its program id (`p_…`) or by the
-legacy 16-hex signature hash that `cmpnd signatures list` shows. Serve tells
-them apart by the `p_` prefix. Entries live in an `entries` subgroup, the same
+program's signature. Name the program by its program name, its program id
+(`p_…`) or the legacy 16-hex signature hash that `cmpnd signatures list` shows.
+The CLI looks a name up with `GET /api/v1/programs/by-name/{name}`, which never
+makes a program, and sends the id. A value of 16 hex digits is a hash, so a
+program whose name is 16 hex digits is named by its id. On a server from before
+program names, a name fails with an error that asks for the hash. Entries live in an `entries` subgroup, the same
 shape as `cmpnd datasets examples`.
 
 The group is in development. The CLI registers it only when
 `CMPND_CLI_DEV=1` is set. Serve still checks each action against the
 `valsets:*` scopes.
 
-- `cmpnd valsets create <program-hash> [--name <name>]` creates a validation
+- `cmpnd valsets create <program> [--name <name>]` creates a validation
   set for a program. The valset ID is its identity, and the name is a label
   that need not be unique. Without `--name`, the CLI assigns a date label
   (`valset-<date>`).

{cmpnd-0.60.0 → cmpnd-0.61.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.60.0"
+version = "0.61.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"