cmpnd 0.60.0__tar.gz → 0.62.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.60.0
+Version: 0.62.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.62.0}/cmpnd/_traces.py

@@ -4,7 +4,7 @@ The implementation of ``list`` and ``show`` over the shared ``_http`` transport.
 :class:`cmpnd.Client`'s ``list_traces`` / ``get_trace`` call these directly; the
 deprecated :mod:`cmpnd.traces` shim wraps them with a warning. The filter and
 verb names match the ``cmpnd traces`` CLI vocabulary — ``list`` filtered by
-``query`` / ``program`` / ``hash`` / ``deployment`` / ``since`` / ``until`` /
+``query`` / ``program`` / ``module`` / ``hash`` / ``deployment`` / ``since`` / ``until`` /
 ``all_history``, and ``show`` for one trace — so the surfaces do not drift.
 """
 
@@ -28,6 +28,7 @@ def list(
     query: str | None = None,
     model: str | None = None,
     program: str | None = None,
+    module: str | None = None,
     hash: str | None = None,
     deployment: str | None = None,
     metadata: dict[str, str] | None = None,
@@ -49,7 +50,10 @@ def list(
 
     The filters mirror ``cmpnd traces list``: ``query`` searches indexed span text;
     ``program`` names the program by name, and ``hash`` by its program id (``p_…``)
-    or a legacy signature hash;
+    or a legacy signature hash; ``module`` is the root module's class, matched exactly.
+    No index serves the class, so without ``program`` or a program id in ``hash`` it
+    reads every trace in the time range and slows as the range grows. Pair it with a program or a shorter
+    ``since``;
     ``deployment`` is a deployment id; ``metadata`` is matched by containment (every
     pair must be present); ``tags`` matches any of the given tags. ``since`` /
     ``until`` accept an ISO 8601 timestamp, a bare date (``YYYY-MM-DD``), or a
@@ -68,6 +72,7 @@ def list(
         ("q", query),
         ("model", model),
         ("program_name", program),
+        ("module_class", module),
         ("deployment_id", deployment),
         ("tags", tags),
     ):

{cmpnd-0.60.0 → cmpnd-0.62.0}/cmpnd/callback.py

@@ -1190,7 +1190,7 @@ class _ModuleMixin(_CallbackBase):
         trace = models.TraceBuilder(
             trace_id=uuid4(),
             start_time=datetime.now(timezone.utc),
-            program_name=instance.__class__.__name__,
+            module_class=instance.__class__.__name__,
         )
         self._stamp(trace)
 
@@ -1633,7 +1633,7 @@ class _LMMixin(_CallbackBase):
             trace_id=span.trace_id or uuid4(),
             start_time=span.start_time,
             end_time=span.end_time,
-            program_name="GEPA",
+            module_class="GEPA",
         )
         self._stamp(trace)
         # A metric-phase call can start while DSPy's Evaluate span is still on the

{cmpnd-0.60.0 → cmpnd-0.62.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.62.0}/cmpnd/cli/commands/top.py

@@ -18,7 +18,7 @@ from typing import Any, NoReturn
 
 from ... import _deployments, deployment_runs
 from ...deployment_metadata import DeploymentMetadataError
-from .. import api_client, pagination
+from .. import api_client, pagination, trace_render
 from . import deployments as deployment_commands
 from . import signatures
 
@@ -338,8 +338,20 @@ def render_deployments_table(deployments: list[dict[str, Any]]) -> str:
     return "\n".join(lines)
 
 
+def trace_program_cells(trace: dict[str, Any]) -> tuple[str, str]:
+    """The PROGRAM and MODULE cells for one trace record.
+
+    PROGRAM is the name the user gave the program, or a dash when it has none.
+    MODULE is the root module's class, or a dash when the trace carries no
+    class. `trace_render.program_and_module` reads an older server's shape,
+    where `program_name` holds the class.
+    """
+    name, module = trace_render.program_and_module(trace)
+    return name or "—", module or "—"
+
+
 def render_traces_table(traces: list[dict[str, Any]]) -> str:
-    """Return a colored TRACE / STATUS / PROGRAM / AGE table as a string.
+    """Return a colored TRACE / STATUS / PROGRAM / MODULE / AGE table as a string.
 
     Reused by the shell when typing `d.traces` at the REPL (via
     `Trace._render_table`). Mirrors `render_deployments_table` so the
@@ -353,13 +365,13 @@ def render_traces_table(traces: list[dict[str, Any]]) -> str:
         (
             id_render(t["trace_id"]),
             t.get("status", "—"),
-            _truncate(t.get("program_name") or _hash_fallback(t.get("program_signature_hash")), 28),
+            *(_truncate(cell, 28) for cell in trace_program_cells(t)),
             _age(t.get("start_time")),
         )
         for t in traces
     ]
 
-    headers = ("TRACE", "STATUS", "PROGRAM", "AGE")
+    headers = ("TRACE", "STATUS", "PROGRAM", "MODULE", "AGE")
     widths = [max(len(h), max((len(r[i]) for r in rows), default=0)) for i, h in enumerate(headers)]
 
     header_line = "  ".join(h.ljust(widths[i]) for i, h in enumerate(headers))
@@ -370,6 +382,7 @@ def render_traces_table(traces: list[dict[str, Any]]) -> str:
             _trace_status(r[1]).ljust(widths[1] + (len(_trace_status(r[1])) - len(r[1]))),
             r[2].ljust(widths[2]),
             r[3].ljust(widths[3]),
+            r[4].ljust(widths[4]),
         ]
         lines.append("  ".join(cells))
     return "\n".join(lines)

{cmpnd-0.60.0 → cmpnd-0.62.0}/cmpnd/cli/commands/traces.py

@@ -28,6 +28,16 @@ def _metadata_pair(value: str) -> tuple[str, str]:
     return key, val
 
 
+# The wait after which a class search with no program filter gets a hint.
+MODULE_SLOW_HINT_SECONDS = 5.0
+
+# The search-body keys that name a program, whichever spelling the flag took.
+_PROGRAM_FILTER_KEYS = ("program_name", "program_id", "program_signature_hash")
+
+# The clock the hint measures with, a seam for tests.
+_monotonic = time.monotonic
+
+
 def _add_list_args(p: ArgumentParser) -> None:
     p.add_argument("--status", help="Filter by status (ok, error, incomplete, in_progress)")
     p.add_argument(
@@ -49,7 +59,20 @@ def _add_list_args(p: ArgumentParser) -> None:
         help="Filter by a metadata pair your program recorded; repeat for all-of. "
         "This is how you find a trace by your own identifier",
     )
-    p.add_argument("--program", dest="program_name", help="Filter by program name")
+    p.add_argument(
+        "--program",
+        dest="program_name",
+        metavar="NAME",
+        help="Filter by the program's name, the one given with cmpnd.Program or `cmpnd programs create`",
+    )
+    p.add_argument(
+        "--module",
+        dest="module_class",
+        metavar="CLASS",
+        help="Filter by the root module's class (exact, e.g. ReAct). No index serves the class: "
+        "without --program or --hash it reads every trace in the time range, so it gets slower "
+        "as the range grows. Narrow it with --program, --hash or --since",
+    )
     p.add_argument(
         "--hash",
         dest="program_signature_hash",
@@ -189,6 +212,7 @@ def handle_list(client: api_client.ApiClient, args: Any) -> Any:
         ("q", "q"),
         ("model", "model"),
         ("program_name", "program_name"),
+        ("module_class", "module_class"),
         ("deployment_id", "deployment_id"),
         ("tags", "tags"),
         ("start_time_from", "start_time_from"),
@@ -211,7 +235,22 @@ def handle_list(client: api_client.ApiClient, args: Any) -> Any:
         body["start_time_from"] = _timespec.resolve_search_time(str(body["start_time_from"]))
     if "start_time_to" in body:
         body["start_time_to"] = _timespec.resolve_search_time(str(body["start_time_to"]), end_of_day=True)
+    started = _monotonic()
     resp = client.post("/api/v1/traces/search", json=body)
+    # No index serves the class, so a class search with no program filter reads
+    # every trace in the range. Say what narrows it once the wait is long enough
+    # to notice, on stderr so stdout stays the response.
+    if (
+        "module_class" in body
+        and not any(key in body for key in _PROGRAM_FILTER_KEYS)
+        and _monotonic() - started > MODULE_SLOW_HINT_SECONDS
+    ):
+        print(
+            "note: --module reads every trace in the time range when no program is given. "
+            "Consider filtering by program (--program or --hash) or a shorter range (--since) "
+            "for faster results.",
+            file=sys.stderr,
+        )
 
     # A window the caller did not ask for has to be visible: read as an org
     # figure, a windowed total is simply wrong, and nothing in the numbers says

{cmpnd-0.60.0 → cmpnd-0.62.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)