cmpnd 0.61.0__tar.gz → 0.63.0__tar.gz

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

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

{cmpnd-0.61.0 → cmpnd-0.63.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.61.0 → cmpnd-0.63.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.61.0 → cmpnd-0.63.0}/cmpnd/cli/commands/org.py

@@ -29,17 +29,21 @@ adds one) and `switch` picks which stored key later commands use, the way the
 web app switches a session's active org. `list` reads
 /api/v1/auth/organizations and marks the orgs you hold a key for and the
 active one. `switch` needs no network call when the org's key is already
-stored. `cmpnd org leave` removes your own membership and drops that org's
-stored key.
+stored. When none is stored for an org you are an approved member of, it
+offers to mint one with the current key's scopes (`--mint` skips the
+question), stores it and switches to it. `cmpnd org leave` removes your own
+membership and drops that org's stored key.
 
 Always registered (no env gate); the server is the authority.
 """
 
 from __future__ import annotations
 
+import socket
 import sys
 import urllib.parse
 from argparse import ArgumentParser, _SubParsersAction
+from datetime import datetime, timezone
 from typing import Any
 
 from .. import api_client, credentials
@@ -91,6 +95,11 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
     switch = sub.add_parser("switch", help="Use the stored key for another of your organizations")
     switch.add_argument("org", help="Organization slug or id (from `org list`)")
+    switch.add_argument(
+        "--mint",
+        action="store_true",
+        help="When no key is stored for the org, mint one with the current key's scopes without asking",
+    )
     switch.set_defaults(func=handle_switch, _skip_resolve_config=True)
 
     leave = sub.add_parser("leave", help="Leave one of your organizations and drop its stored key")
@@ -214,12 +223,70 @@ def handle_switch(_unused_client: api_client.ApiClient | None, args: Any) -> Non
         api_key, _ = api_client.resolve_config(args)
     except api_client.CliError:
         raise _no_key_stored(f"'{target}'", endpoint, target) from None
-    for row in _memberships(api_client.ApiClient(api_key, endpoint)):
+    client = api_client.ApiClient(api_key, endpoint)
+    for row in _memberships(client):
         if target in (row.get("id"), row.get("slug")):
-            raise _no_key_stored(str(row.get("name") or target), endpoint, target)
+            _mint_and_switch(client, row, target, ask=not getattr(args, "mint", False))
+            return
     raise api_client.CliError(f"You are not a member of an organization '{target}' on {endpoint}.")
 
 
+def _mint_and_switch(client: api_client.ApiClient, row: dict[str, Any], target: str, *, ask: bool) -> None:
+    """Mint a key for a member org that has none stored, store it and switch.
+
+    The request names no scopes, so serve grants the calling key's own
+    non-admin scopes and the new key is never broader than the one in use.
+    serve refuses with 400 or 403 when the calling key cannot mint, and the
+    browser login is then the way to get the key.
+    """
+    endpoint = client._endpoint
+    label = str(row.get("name") or row.get("slug") or target)
+    if row.get("approved") is False:
+        raise api_client.CliError(
+            f"Your membership in {label} is not approved yet, so no key can be minted for it. "
+            "An owner of the org approves it."
+        )
+    if ask:
+        if not sys.stdin.isatty():
+            raise api_client.CliError(
+                f"No key is stored for {label} on {endpoint}. Run {top.hint_org_switch(target, mint=True)} "
+                f"to mint one with the current key's scopes, or {top.hint_login(target)}."
+            )
+        try:
+            answer = input(f"No key is stored for {label}. Mint one with the current key's scopes? [Y/n] ")
+        except EOFError:
+            # Ctrl-D at the prompt declines.
+            print(file=sys.stderr)
+            answer = "n"
+        if answer.strip().lower() not in ("", "y", "yes"):
+            raise _no_key_stored(label, endpoint, target)
+
+    hostname = socket.gethostname() or "unknown"
+    name = f"CLI: {hostname} {datetime.now(timezone.utc).strftime('%Y-%m-%d')}"
+    try:
+        created = client.post("/api/v1/org/keys", json={"name": name, "org_id": row.get("id") or target})
+    except api_client.CliError as exc:
+        if exc.status_code in (400, 403):
+            raise api_client.CliError(
+                f"The current key could not mint a key for {label}: {exc}. Run {top.hint_login(target)} to store one."
+            ) from exc
+        raise
+    token = created.get("token") if isinstance(created, dict) else None
+    org_id = created.get("org_id") if isinstance(created, dict) else None
+    if not isinstance(token, str) or not token or not isinstance(org_id, str) or not org_id:
+        raise api_client.CliError(f"The response did not include a key for {label}. Nothing was stored.")
+    name_out = created.get("org_name")
+    slug_out = created.get("org_slug")
+    credentials.save(
+        endpoint,
+        token,
+        org_id=org_id,
+        org_name=name_out if isinstance(name_out, str) else None,
+        org_slug=slug_out if isinstance(slug_out, str) else None,
+    )
+    print(f"Minted a key for {name_out or slug_out or org_id} ({org_id}) and switched to it on {endpoint}")
+
+
 def _say_active_moved(endpoint: str, moved_to: str | None) -> None:
     if moved_to:
         k = {k.org_id: k for k in credentials.stored_keys(endpoint)}.get(moved_to)

{cmpnd-0.61.0 → cmpnd-0.63.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
 
@@ -180,8 +180,8 @@ def hint_login(org: str | None = None) -> str:
     return f"`{cmd}` in a terminal, then restart the shell" if _SHELL_MODE else f"`{cmd}`"
 
 
-def hint_org_switch(org: str) -> str:
-    cmd = f"cmpnd org switch {org}"
+def hint_org_switch(org: str, *, mint: bool = False) -> str:
+    cmd = f"cmpnd org switch {org}" + (" --mint" if mint else "")
     # Same reason as hint_login: the shell picks its key once, at startup.
     # Both are public, unlike the other hint helpers, because only org.py
     # calls them.
@@ -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.61.0 → cmpnd-0.63.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.61.0 → cmpnd-0.63.0}/cmpnd/cli/shell.py

@@ -32,7 +32,7 @@ from pathlib import Path
 from types import SimpleNamespace
 from typing import Any, Callable
 
-from . import api_client, commands, credentials, verbs
+from . import api_client, commands, credentials, trace_render, verbs
 
 # --------------------------------------------------------------------------
 # Config + dismissible-tips marker
@@ -259,13 +259,15 @@ class Trace(Entity):
         super().__init__(client, record)
         self.status_str = record.get("status")
         self.start_time = record.get("start_time")
-        self.program_name = record.get("program_name")
+        # The program's own name (None when it has none) and the root module's
+        # class, read the same way for a server that predates module_class.
+        self.program_name, self.module_class = trace_render.program_and_module(record)
 
     def __repr__(self) -> str:
         short = self.id.replace("-", "")[:12]
-        program = self.program_name or commands.top._hash_fallback(self._record.get("program_signature_hash"))
+        program, module = commands.top.trace_program_cells(self._record)
         age = commands.top._age(self.start_time)
-        return f"<Trace {short} status={self.status_str} program={program!r} age={age}>"
+        return f"<Trace {short} status={self.status_str} program={program!r} module={module!r} age={age}>"
 
     def inspect(self) -> dict[str, Any]:
         """Return the full trace record (with spans)."""

{cmpnd-0.61.0 → cmpnd-0.63.0}/cmpnd/cli/trace_render.py

@@ -267,8 +267,35 @@ def _int(v: Any) -> int:
         return 0
 
 
+def program_and_module(trace: dict[str, Any]) -> tuple[str | None, str | None]:
+    """The program's name and the root module's class a trace record carries.
+
+    A server that sends ``module_class`` puts the program's own name in
+    ``program_name``, empty when the program has none. An older server sends
+    no ``module_class``, and its ``program_name`` holds the class, so that
+    value is read as the class and the program counts as unnamed.
+    """
+    if "module_class" in trace:
+        return trace.get("program_name") or None, trace.get("module_class") or None
+    return None, trace.get("program_name") or None
+
+
+def trace_label(trace: dict[str, Any]) -> str:
+    """One label for a trace: the program's name, else its id, else its class, else its signature.
+
+    The id shows only for a program with no name: a name already identifies it.
+    """
+    name, module = program_and_module(trace)
+    return name or trace.get("program_id") or module or trace.get("signature_name") or "trace"
+
+
 def _header(trace: dict[str, Any], span_total: int, color: bool, arrivals: bool = False) -> str:
-    program = trace.get("program_name") or trace.get("signature_name") or "trace"
+    _, module = program_and_module(trace)
+    label = trace_label(trace)
+    program = _paint(label, "bold", color)
+    if module and label != module:
+        # The label names the program; the class beside it says what ran.
+        program += "  " + _paint(module, "dim", color)
     tid = str(trace.get("trace_id") or "")
     status = trace.get("status")
     meta = [
@@ -278,7 +305,7 @@ def _header(trace: dict[str, Any], span_total: int, color: bool, arrivals: bool
     ]
     if _int(trace.get("total_tokens")) > 0:
         meta.append(f"{_int(trace.get('total_tokens'))} tokens")
-    line1 = (_paint(str(program), "bold", color) + "  " + _paint(tid, "grey", color)).rstrip()
+    line1 = (program + "  " + _paint(tid, "grey", color)).rstrip()
     out = line1 + "\n" + " · ".join(meta)
     if arrivals:
         # Absolute landing time on the header (the one place there is room for

{cmpnd-0.61.0 → cmpnd-0.63.0}/cmpnd/models.py

@@ -942,7 +942,9 @@ class TraceBuilder:
     status: TraceStatus = TraceStatus.UNSET
     error_message: str | None = None
 
-    program_name: str | None = None
+    # The root DSPy module's class. The program's own name is `declared_name`,
+    # which the transport resolves to `program_id`.
+    module_class: str | None = None
     program_version: str | None = None
 
     # Signature info - identifies the program by its inputs/outputs
@@ -1071,7 +1073,9 @@ class TraceBuilder:
                 "end_time": self.end_time.isoformat() if self.end_time else None,
                 "status": self.status.value,
                 "error_message": _strip_unstorable_opt(self.error_message),
-                "program_name": self.program_name,
+                "module_class": self.module_class,
+                # Also under the key a serve from before module_class reads (StartedFact.creation_dict).
+                "program_name": self.module_class,
                 "program_version": self.program_version,
                 "signature_name": self.signature_name,
                 "signature_input_fields": self.signature_input_fields,
@@ -1112,7 +1116,9 @@ class TraceBuilder:
         return self._with_facts(
             {
                 "start_time": self.start_time.isoformat() if self.start_time else None,
-                "program_name": self.program_name,
+                "module_class": self.module_class,
+                # Also under the key a serve from before module_class reads (StartedFact.creation_dict).
+                "program_name": self.module_class,
                 "program_version": self.program_version,
                 "signature_name": self.signature_name,
                 "signature_input_fields": self.signature_input_fields,

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

@@ -291,8 +291,9 @@ caller reads it. To find where a program is slow, list recent traces, then
 read each one's spans and durations.
 
 - `cmpnd traces list [-q TEXT] [--model] [--metadata k=v …] [--status]
-  [--program] [--hash ID-OR-HASH] [--deployment] [--tag …] [--since]
-  [--until] [--all] [--limit N] [--offset N]` lists traces, newest first.
+  [--program NAME] [--module CLASS] [--hash ID-OR-HASH] [--deployment]
+  [--tag …] [--since] [--until] [--all] [--limit N] [--offset N]` lists
+  traces, newest first.
   - `--limit N` returns the N most recent, and `--offset N` skips N rows.
   - `--since` and `--until` bound the start time. Each takes ISO 8601, a date
     (`YYYY-MM-DD`, UTC, the start of the day for `--since` and the end for
@@ -305,6 +306,17 @@ read each one's spans and durations.
     must appear.
   - `--metadata` repeats and matches metadata you attached at trace time, so
     you can find a trace by your own identifier.
+  - `--program` takes the program's name, the one you gave with
+    `cmpnd.Program` or `cmpnd programs create`. The CLI sends it as the search
+    body's `program_name`. A name no program answers to is an error that names
+    it, not an empty list.
+  - `--module` takes the root module's class, such as `ReAct`, and matches it
+    exactly. The CLI sends it as `module_class`. No index serves the class.
+    Without `--program` or a program id in `--hash` it reads every trace in
+    the time range, so it slows as the range grows. When such a search takes
+    longer than five seconds, the CLI prints a line on stderr that suggests a
+    program filter or a shorter range. Stdout is unchanged. A search that
+    times out answers 503 with the same advice.
   - `--hash` takes a program id or a legacy signature hash. The CLI sends an
     id as the search body's `program_id` and a hash as
     `program_signature_hash`. `cmpnd.Client().list_traces(hash=...)` splits
@@ -312,8 +324,10 @@ read each one's spans and durations.
   - `--deployment` takes a deployment ID (`d_...`).
 - `cmpnd traces show <id> [--tree|--timeline|--notebook] [--arrivals]` prints
   one trace. The default is raw JSON with each span's duration and its
-  `created_at`. `--tree` and `--timeline` render human views, and
-  `--notebook` prints an RLM trace as a Jupyter notebook. With `--tree` or
+  `created_at`. `--tree` and `--timeline` render human views headed by the
+  program's name and its root module's class. A program with no name is headed
+  by its `p_` id instead, and a trace that names no program by its class
+  alone. `--notebook` prints an RLM trace as a Jupyter notebook. With `--tree` or
   `--timeline`, `--arrivals` shows when the server stored each span and how
   far that is from the start time the client reported, which exposes a skewed
   client clock.
@@ -322,6 +336,14 @@ read each one's spans and durations.
 - `cmpnd traces update <id> --metadata k=v …` merges metadata onto a trace,
   and `cmpnd traces delete <id>` deletes a trace and its spans.
 
+Each trace row and each `traces show` trace names what ran in three fields.
+`program_name` is the program's name, empty when the program has none or the
+trace names no program. `module_class` is the root DSPy module's class, and
+`program_id` is the program's `p_` id. A server that predates `module_class`
+sends the class in `program_name`. The shell's traces table and the `--tree`
+and `--timeline` headers then show that value as the class and leave the
+program unnamed.
+
 `-q` matches text that serve indexes on each span when it stores the span.
 Spans stored before the index existed match nothing until a backfill indexes
 them. An empty result says so, because the list alone cannot tell "nothing
@@ -416,9 +438,14 @@ mode 0600. An active pointer names the org whose key commands use.
   is stored, and `active` marks the org of the key in use. When `--api-key` or
   `CMPND_API_KEY` is set, `active` marks that key's org.
 - `cmpnd org switch <slug-or-id>` makes another org's stored key active, with
-  no network call. When no key is stored for that org, it says so and names
-  the `cmpnd login --org` command to run. It refuses while `--api-key` or
-  `CMPND_API_KEY` is set, because either one overrides the stored keys.
+  no network call. When no key is stored for an org where you are an approved
+  member, it asks whether to mint one with the current key's scopes, stores
+  it and switches to it. `--mint` mints without asking, and without a
+  terminal to ask in it mints only with `--mint`. The request names no
+  scopes, so serve grants the current key's non-admin scopes. When serve
+  refuses the mint, the error names the `cmpnd login --org` command to run.
+  `switch` refuses while `--api-key` or `CMPND_API_KEY` is set, because
+  either one overrides the stored keys.
 - `cmpnd org leave <slug-or-id>` removes your membership in that org and drops
   its stored key. If that key was active, the CLI switches to another stored
   key, preferring your new default org's, or clears the pointer, and says

{cmpnd-0.61.0 → cmpnd-0.63.0}/docs/reading-traces.md

@@ -44,8 +44,9 @@ offers only `list`.
 | `status` | `--status` | `ok`, `error`, `incomplete` or `in_progress` |
 | `query` | `--query` / `-q` | Full-text search over indexed span text: prompts, completions, tool calls and errors |
 | `model` | `--model` | Exact model name, such as `openai/gpt-6-luna` |
-| `program` | `--program` | Program name |
-| `hash` | `--hash` | Program signature hash, as a string |
+| `program` | `--program` | The program's name. A name no program answers to raises an error that names it. |
+| `module` | `--module` | The root module's class, matched exactly. No index serves it, so without `program` or a program id in `hash` it reads every trace in the time range. Pair it with a program or a shorter `since`. |
+| `hash` | `--hash` | A program id (`p_…`), or a legacy signature hash as a string |
 | `deployment` | `--deployment` | Deployment ID (`d_…`) |
 | `metadata` | `--metadata` | A `dict` matched by containment. Every pair must be on the trace. |
 | `tags` | `--tag` | A `list`. A trace matches if it has any of the project tags. |

{cmpnd-0.61.0 → cmpnd-0.63.0}/docs/sdk-instrumentation.md

@@ -673,6 +673,13 @@ Its first payload carries the optimization id, plus the active eval id for a
 metric call. A reflection call outside evaluation has no eval id. Manual
 decorators and `start_span` create spans rather than another automatic trace.
 
+A trace's creation fields name the root module's class in `module_class`, at
+the top level and in `started_fact`, and again under `program_name`, the key a
+serve from before `module_class` reads and digests a start from. A standalone
+optimizer LM trace sends `GEPA` there. No trace body carries the program's own name: a declared name
+travels as the program id it resolves to, as "A declared program name resolves
+to an id in the exporter" describes.
+
 The callback seals `started_fact` after it sets the root type, before the
 module executes. It keeps that snapshot even when start emission is disabled.
 The completion callback seals one independently identified `completion_fact`

{cmpnd-0.61.0 → cmpnd-0.63.0}/ingest/cmpnd_ingest/trace_facts.py

@@ -80,7 +80,7 @@ class StartedFact:
     """Creation fields that later builder mutation cannot change."""
 
     start_time: str | None
-    program_name: str | None
+    module_class: str | None
     program_version: str | None
     program_signature_hash: str
     signature_name: str | None
@@ -104,7 +104,7 @@ class StartedFact:
     def from_payload(cls, payload: dict[str, Any]) -> StartedFact:
         return cls(
             start_time=payload.get("start_time"),
-            program_name=payload.get("program_name"),
+            module_class=payload.get("module_class"),
             program_version=payload.get("program_version"),
             program_signature_hash=str(payload["program_signature_hash"]),
             signature_name=payload.get("signature_name"),
@@ -125,7 +125,12 @@ class StartedFact:
     def creation_dict(self) -> dict[str, Any]:
         payload = {
             "start_time": self.start_time,
-            "program_name": self.program_name,
+            "module_class": self.module_class,
+            # A serve from before module_class reads the class only under
+            # program_name, and digests a start from that key. Sending both keeps
+            # a start it accepted matching its replay to a later serve. Dropped
+            # once no such serve runs.
+            "program_name": self.module_class,
             "program_version": self.program_version,
             "program_signature_hash": self.program_signature_hash,
             "signature_name": self.signature_name,

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

{cmpnd-0.61.0 → cmpnd-0.63.0}/scripts/capture_review_run.py

@@ -10,7 +10,7 @@ GEPA optimization the stress suite runs
 a weak Bedrock student + a Bedrock reflection LM over the vendored committee
 subset. Capturing a *real* run (rather than fabricating payloads) keeps the seed
 faithful — real prompts, token counts, span trees, and now the GEPA optimizer
-traces (program_name "GEPA", `gepa.phase` reflection/metric — CMP-485).
+traces (module_class "GEPA", `gepa.phase` reflection/metric).
 
 Only the four kinds `seed_review_run.py` replays are kept — `optimization` (the
 completed run header), `traces_batch`, `spans`, `stats`; the optimization *start*
@@ -146,12 +146,12 @@ def main() -> int:
     kinds = [it["kind"] for it in captured]
     n_opt = kinds.count("optimization")
     trace_payloads = [t for it in captured if it["kind"] == "traces_batch" for t in it["payload"]]
-    programs = {t.get("program_name") for t in trace_payloads}
+    classes = {t.get("module_class") for t in trace_payloads}
     if n_opt != 1:
         print(f"expected exactly 1 completed optimization, captured {n_opt}; not writing", file=sys.stderr)
         return 1
-    if "GEPA" not in programs:
-        print(f"no GEPA optimizer traces captured (programs={programs}); not writing", file=sys.stderr)
+    if "GEPA" not in classes:
+        print(f"no GEPA optimizer traces captured (module classes={classes}); not writing", file=sys.stderr)
         return 1
 
     _FIXTURE.parent.mkdir(parents=True, exist_ok=True)
@@ -160,7 +160,7 @@ def main() -> int:
     from collections import Counter
 
     print(f"wrote {_FIXTURE} — {len(captured)} items {dict(Counter(kinds))}")
-    print(f"  trace program_names: {dict(Counter(t.get('program_name') for t in trace_payloads))}")
+    print(f"  trace module classes: {dict(Counter(t.get('module_class') for t in trace_payloads))}")
     return 0
 
 

{cmpnd-0.61.0 → cmpnd-0.63.0}/scripts/seed_review_run.py

@@ -258,7 +258,7 @@ _TOOL_KIND_DEMO_FIXTURE = (
 # A dspy.ReAct(ExtractCommittee) run (email_body->committee) that reasons, calls
 # a `lookup_disclaimer` tool to pull the "Paid for by" line, then extracts the
 # committee (CMP-634 golden-path). Flat-replay format like the two fixtures
-# above; program_name "ReAct" so the sidebar/Type badge reads ReAct. Loaded
+# above; module_class "ReAct" so the sidebar/Type badge reads ReAct. Loaded
 # lazily so a missing file degrades to skipping that seed.
 _REACT_COMMITTEE_FIXTURE = (
     pathlib.Path(__file__).resolve().parents[2] / "serve" / "scripts" / "seed_fixtures" / "react_committee.json"
@@ -390,7 +390,7 @@ def _notebook_trace(now: datetime.datetime) -> dict:
         "end_time": at(total_ns),
         "duration_ns": total_ns,
         "status": "ok",
-        "program_name": "RLM",  # DSPy module class → programs.module_class → sidebar badge
+        "module_class": "RLM",  # DSPy module class → programs.module_class → sidebar badge
         "program_version": "0.1.0",
         "program_signature_hash": fx["program_signature_hash"],
         "signature_name": fx["signature_name"],
@@ -540,7 +540,7 @@ def _notebook_trace_in_progress(now: datetime.datetime) -> dict:
         "trace_id": trace_id,
         "start_time": at(0),
         "status": "in_progress",
-        "program_name": "RLM",
+        "module_class": "RLM",
         "program_version": "0.1.0",
         "program_signature_hash": fx["program_signature_hash"],
         "signature_name": fx["signature_name"],
@@ -559,7 +559,7 @@ def _notebook_trace_in_progress(now: datetime.datetime) -> dict:
 def _replay_flat_fixture(
     fixture_path: pathlib.Path,
     now: datetime.datetime,
-    program_name: str,
+    module_class: str,
     project_tags: list[str],
     request_preview: str,
     response_preview: str,
@@ -609,7 +609,7 @@ def _replay_flat_fixture(
         "end_time": at(total_ns),
         "duration_ns": total_ns,
         "status": "ok",
-        "program_name": program_name,  # DSPy module class → programs.module_class → sidebar badge
+        "module_class": module_class,  # DSPy module class → programs.module_class → sidebar badge
         "program_version": "0.1.0",
         "program_signature_hash": root["program_signature_hash"],
         "signature_name": root["signature_name"],