cmpnd 0.63.0__tar.gz → 0.64.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.63.0
+Version: 0.64.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -51,9 +51,9 @@ Description-Content-Type: text/markdown
 
 # cmpnd
 
-The `cmpnd` package traces DSPy programs and deploys and optimizes them on the
-cmpnd platform. One call turns on tracing, and a client deploys, runs and
-optimizes named programs.
+The `cmpnd` package traces, deploys and optimizes DSPy programs on the cmpnd
+platform. You give a program a name, and a client records its traces,
+deployments and optimization runs under that name.
 
 ## Installation
 
@@ -66,46 +66,15 @@ uv add cmpnd      # or: pip install cmpnd
 The `cmpnd` library works with the cmpnd service at
 [platform.cmpnd.ai](https://platform.cmpnd.ai). Create an API key on the
 platform under Settings → API keys, and pass it as `api_key=` to
-`cmpnd.configure()` or `cmpnd.Client()`. For a self-hosted cmpnd install, also
+`cmpnd.Client()` or `cmpnd.configure()`. For a self-hosted cmpnd install, also
 pass the install's URL as `endpoint=`.
 
 ## Quick start
 
-`cmpnd.auto_instrument()` records a trace of every DSPy call in the process.
-Your code needs no other change. Use it to sketch a [DSPy program](https://dspy.ai/) and see what it
-does.
-
-```python
-import cmpnd
-import dspy
-
-cmpnd.configure(api_key="ck_xxx", project_tags="my-project")
-cmpnd.auto_instrument()
-
-dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
-
-cot = dspy.ChainOfThought("question -> answer")
-result = cot(question="What is DSPy?")   # the trace goes to cmpnd
-
-cmpnd.trace_id(result)  # "a1b2c3d4-...", or None outside instrumentation
-```
-
-`cmpnd.trace_id()` links a result to its platform trace, for example to attach
-feedback later. Traces recorded this way have no program name. The platform
-groups them by the structure of the program's modules. The API reference
-below lists the other options of `cmpnd.configure()`.
-
-## Program names
-
-When you’re ready to name programs, evolve them, and share them with your team, switch
-to `cmpnd.Client`. A client replaces `configure()` and `auto_instrument()` and offers
-more features. A client records only the programs you run through it, and each of
-those programs has a program name. A client takes most of the same arguments as `configure()`.
-
-A program name is the name your organization gives a program, such as `question-answerer`.
-Traces, deployments and optimization runs under one program name go to one
-program. The platform makes the program the first time your organization uses
-the program name.
+A program name is the name your organization gives a program, such as
+`question-answerer`. Traces, deployments and optimization runs under one
+program name go to one program. The platform makes the program the first time
+your organization uses the program name.
 
 `@cmpnd.program(name)` above a `dspy.Module` class gives the class a program
 name. Building the class takes its own arguments and a required `lm=`. The
@@ -128,17 +97,23 @@ class QA(dspy.Predict):
 qa1 = QA(lm=dspy.LM("openai/gpt-6-luna"))
 ```
 
-A client runs the program and records its trace under the program name:
+A `cmpnd.Client` runs the program and records its trace under the program
+name:
 
 ```python
 gepa = dspy.GEPA(metric=metric, reflection_lm=dspy.LM("openai/gpt-6-luna"), auto="light")
 
 with cmpnd.Client(api_key="ck_xxx", project_tags="my-project") as sdk:
-    # the trace will go to the program "question-answerer"
+    # the trace goes to the program "question-answerer"
     result = sdk.run_program(qa1, question="What is DSPy?")
     qa2 = sdk.optimize_program(qa1, gepa, trainset=train, valset=val)
+
+cmpnd.trace_id(result)  # "a1b2c3d4-...", the trace of this run
 ```
 
+`cmpnd.trace_id()` links a result to its platform trace, for example to attach
+feedback later. A client records only the programs you run through it.
+
 A client is active from construction. The `with` form flushes the client's
 traces and closes it on exit. Without `with`, the client stays active until
 you call `close()` or the process exits, and its traces go out at exit:
@@ -167,8 +142,26 @@ qa3 = cmpnd.Program(
 - `optimize_program` runs the optimizer in your process and returns a copy of
   the program that holds the optimized module. The copy keeps the program name
   and the LM.
-- Calling a `cmpnd.Program` directly while `auto_instrument()` is on raises a
-  `TypeError` that points to `cmpnd.Client`.
+
+## Sketching with `auto_instrument()`
+
+`cmpnd.auto_instrument()` records a trace of every DSPy call in the process,
+with no other change to your code. Use it to sketch a
+[DSPy program](https://dspy.ai/) and see what it does:
+
+```python
+cmpnd.configure(api_key="ck_xxx", project_tags="my-project")
+cmpnd.auto_instrument()
+
+dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
+dspy.ChainOfThought("question -> answer")(question="What is DSPy?")
+```
+
+These traces carry no program, so the platform files them under Unattributed.
+The first one in a process logs a warning that points to `@cmpnd.program` and
+`cmpnd.Client`. Calling a `cmpnd.Program` directly while `auto_instrument()` is
+on raises a `TypeError` that points to the client. The API reference below
+lists the options of `cmpnd.configure()`.
 
 ## Deployed programs
 
@@ -531,7 +524,7 @@ describes one:
 
 ```
 usage: cmpnd [-h] [--version] [--api-key API_KEY] [--endpoint ENDPOINT]
-             {auth,login,logout,org,credentials,tool-servers,optimizations,programs,signatures,traces,evals,datasets,deployments,ps,status,logs,inspect,schema,sample,run,deploy,optimize}
+             {auth,login,logout,org,credentials,tool-servers,optimizations,programs,traces,evals,datasets,deployments,ps,status,logs,inspect,schema,sample,run,deploy,optimize}
              ...
 
 CMPND platform CLI — deploy, run, and inspect DSPy programs.
@@ -625,7 +618,8 @@ captured input and output size limits, 65,536 bytes each by default.
 
 ### `cmpnd.auto_instrument()`
 
-Registers the callback with DSPy, so every DSPy call records a trace.
+Registers the callback with DSPy, so every DSPy call records a trace. The
+traces carry no program and land in Unattributed.
 
 ### `cmpnd.Client()`
 

{cmpnd-0.63.0 → cmpnd-0.64.0}/README.md

@@ -1,8 +1,8 @@
 # cmpnd
 
-The `cmpnd` package traces DSPy programs and deploys and optimizes them on the
-cmpnd platform. One call turns on tracing, and a client deploys, runs and
-optimizes named programs.
+The `cmpnd` package traces, deploys and optimizes DSPy programs on the cmpnd
+platform. You give a program a name, and a client records its traces,
+deployments and optimization runs under that name.
 
 ## Installation
 
@@ -15,46 +15,15 @@ uv add cmpnd      # or: pip install cmpnd
 The `cmpnd` library works with the cmpnd service at
 [platform.cmpnd.ai](https://platform.cmpnd.ai). Create an API key on the
 platform under Settings → API keys, and pass it as `api_key=` to
-`cmpnd.configure()` or `cmpnd.Client()`. For a self-hosted cmpnd install, also
+`cmpnd.Client()` or `cmpnd.configure()`. For a self-hosted cmpnd install, also
 pass the install's URL as `endpoint=`.
 
 ## Quick start
 
-`cmpnd.auto_instrument()` records a trace of every DSPy call in the process.
-Your code needs no other change. Use it to sketch a [DSPy program](https://dspy.ai/) and see what it
-does.
-
-```python
-import cmpnd
-import dspy
-
-cmpnd.configure(api_key="ck_xxx", project_tags="my-project")
-cmpnd.auto_instrument()
-
-dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
-
-cot = dspy.ChainOfThought("question -> answer")
-result = cot(question="What is DSPy?")   # the trace goes to cmpnd
-
-cmpnd.trace_id(result)  # "a1b2c3d4-...", or None outside instrumentation
-```
-
-`cmpnd.trace_id()` links a result to its platform trace, for example to attach
-feedback later. Traces recorded this way have no program name. The platform
-groups them by the structure of the program's modules. The API reference
-below lists the other options of `cmpnd.configure()`.
-
-## Program names
-
-When you’re ready to name programs, evolve them, and share them with your team, switch
-to `cmpnd.Client`. A client replaces `configure()` and `auto_instrument()` and offers
-more features. A client records only the programs you run through it, and each of
-those programs has a program name. A client takes most of the same arguments as `configure()`.
-
-A program name is the name your organization gives a program, such as `question-answerer`.
-Traces, deployments and optimization runs under one program name go to one
-program. The platform makes the program the first time your organization uses
-the program name.
+A program name is the name your organization gives a program, such as
+`question-answerer`. Traces, deployments and optimization runs under one
+program name go to one program. The platform makes the program the first time
+your organization uses the program name.
 
 `@cmpnd.program(name)` above a `dspy.Module` class gives the class a program
 name. Building the class takes its own arguments and a required `lm=`. The
@@ -77,17 +46,23 @@ class QA(dspy.Predict):
 qa1 = QA(lm=dspy.LM("openai/gpt-6-luna"))
 ```
 
-A client runs the program and records its trace under the program name:
+A `cmpnd.Client` runs the program and records its trace under the program
+name:
 
 ```python
 gepa = dspy.GEPA(metric=metric, reflection_lm=dspy.LM("openai/gpt-6-luna"), auto="light")
 
 with cmpnd.Client(api_key="ck_xxx", project_tags="my-project") as sdk:
-    # the trace will go to the program "question-answerer"
+    # the trace goes to the program "question-answerer"
     result = sdk.run_program(qa1, question="What is DSPy?")
     qa2 = sdk.optimize_program(qa1, gepa, trainset=train, valset=val)
+
+cmpnd.trace_id(result)  # "a1b2c3d4-...", the trace of this run
 ```
 
+`cmpnd.trace_id()` links a result to its platform trace, for example to attach
+feedback later. A client records only the programs you run through it.
+
 A client is active from construction. The `with` form flushes the client's
 traces and closes it on exit. Without `with`, the client stays active until
 you call `close()` or the process exits, and its traces go out at exit:
@@ -116,8 +91,26 @@ qa3 = cmpnd.Program(
 - `optimize_program` runs the optimizer in your process and returns a copy of
   the program that holds the optimized module. The copy keeps the program name
   and the LM.
-- Calling a `cmpnd.Program` directly while `auto_instrument()` is on raises a
-  `TypeError` that points to `cmpnd.Client`.
+
+## Sketching with `auto_instrument()`
+
+`cmpnd.auto_instrument()` records a trace of every DSPy call in the process,
+with no other change to your code. Use it to sketch a
+[DSPy program](https://dspy.ai/) and see what it does:
+
+```python
+cmpnd.configure(api_key="ck_xxx", project_tags="my-project")
+cmpnd.auto_instrument()
+
+dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
+dspy.ChainOfThought("question -> answer")(question="What is DSPy?")
+```
+
+These traces carry no program, so the platform files them under Unattributed.
+The first one in a process logs a warning that points to `@cmpnd.program` and
+`cmpnd.Client`. Calling a `cmpnd.Program` directly while `auto_instrument()` is
+on raises a `TypeError` that points to the client. The API reference below
+lists the options of `cmpnd.configure()`.
 
 ## Deployed programs
 
@@ -480,7 +473,7 @@ describes one:
 
 ```
 usage: cmpnd [-h] [--version] [--api-key API_KEY] [--endpoint ENDPOINT]
-             {auth,login,logout,org,credentials,tool-servers,optimizations,programs,signatures,traces,evals,datasets,deployments,ps,status,logs,inspect,schema,sample,run,deploy,optimize}
+             {auth,login,logout,org,credentials,tool-servers,optimizations,programs,traces,evals,datasets,deployments,ps,status,logs,inspect,schema,sample,run,deploy,optimize}
              ...
 
 CMPND platform CLI — deploy, run, and inspect DSPy programs.
@@ -574,7 +567,8 @@ captured input and output size limits, 65,536 bytes each by default.
 
 ### `cmpnd.auto_instrument()`
 
-Registers the callback with DSPy, so every DSPy call records a trace.
+Registers the callback with DSPy, so every DSPy call records a trace. The
+traces carry no program and land in Unattributed.
 
 ### `cmpnd.Client()`
 

{cmpnd-0.63.0 → cmpnd-0.64.0}/cmpnd/_assessments.py

@@ -13,7 +13,7 @@ import os
 from collections.abc import Sequence
 from typing import Any, Literal
 
-from . import _http, configuration
+from . import _http, configuration, programs
 
 DEFAULT_ENDPOINT = "https://platform.cmpnd.ai"
 
@@ -58,22 +58,23 @@ def list(
 ) -> dict[str, Any]:
     """List assessments by program or by trace, newest first.
 
-    Pass exactly one of ``program`` (every assessment of that program) or
-    ``trace_id`` (only that trace's assessments). Returns
+    Pass exactly one of ``program`` (every assessment of that program, named by its
+    name or ``p_`` id) or ``trace_id`` (only that trace's assessments). Returns
     ``{"assessments": [...], "total": N, "limit", "offset", "has_more"}``.
     ``limit`` (max rows) and ``offset`` (skip this many) page the full set — the
     server clamps ``limit`` to at most 200.
     """
     if program is not None and trace_id is not None:
         raise ValueError("pass exactly one of program or trace_id")
+    client = _client(api_key, endpoint)
     if trace_id is not None:
         scope: dict[str, str] = {"trace_id": trace_id}
     elif program is not None:
-        scope = {"program": program}
+        scope = {"program": programs.program_id_for(client, program)}
     else:
         raise ValueError("pass exactly one of program or trace_id")
     params = {**scope, "limit": str(limit), "offset": str(offset)}
-    return _client(api_key, endpoint).get("/api/v1/assessments", params=params)
+    return client.get("/api/v1/assessments", params=params)
 
 
 def get(assessment_id: str, *, api_key: str | None = None, endpoint: str | None = None) -> dict[str, Any]:

{cmpnd-0.63.0 → cmpnd-0.64.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`` / ``module`` / ``hash`` / ``deployment`` / ``since`` / ``until`` /
+``query`` / ``program`` / ``module`` / ``deployment`` / ``since`` / ``until`` /
 ``all_history``, and ``show`` for one trace — so the surfaces do not drift.
 """
 
@@ -29,7 +29,6 @@ def list(
     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,
     tags: list[str] | None = None,
@@ -49,11 +48,10 @@ def list(
     ``ignored_fields`` naming any request field an older server did not understand.
 
     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; ``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``;
+    ``program`` names the program by its name or its program id (``p_…``);
+    ``module`` is the root module's class, matched exactly. No index serves the
+    class, so without ``program`` 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
@@ -71,15 +69,14 @@ def list(
         ("status", status),
         ("q", query),
         ("model", model),
-        ("program_name", program),
         ("module_class", module),
         ("deployment_id", deployment),
         ("tags", tags),
     ):
         if val is not None:
             body[wire_key] = val
-    if hash is not None:
-        body.update(program_filter(hash))
+    if program is not None:
+        body.update(program_filter(program))
     if metadata is not None:
         body["metadata"] = dict(metadata)
     if since is not None:
@@ -92,14 +89,14 @@ def list(
 def program_filter(value: str) -> dict[str, str]:
     """The search-body key for one program filter value.
 
-    A program id (``p_…``) goes in ``program_id`` and a legacy signature hash in
-    ``program_signature_hash``, which the route decodes as a typed hash and would
-    refuse an id in. One helper for the CLI and the SDK, so the two cannot split.
+    A program id (``p_…``) goes in ``program_id`` and anything else is a program
+    name, since no name starts with ``p_``. One helper for the CLI and the SDK,
+    so the two cannot split.
     """
     text = value.strip()
     if identity.is_program_id(text):
         return {"program_id": text}
-    return {"program_signature_hash": value}
+    return {"program_name": value}
 
 
 def show(trace_id: str, *, api_key: str | None = None, endpoint: str | None = None) -> dict[str, Any]:

{cmpnd-0.63.0 → cmpnd-0.64.0}/cmpnd/_valsets.py

@@ -15,7 +15,7 @@ import datetime
 import os
 from typing import Any
 
-from . import _http, configuration
+from . import _http, configuration, programs
 
 DEFAULT_ENDPOINT = "https://platform.cmpnd.ai"
 
@@ -30,22 +30,24 @@ def default_name() -> str:
 def create(
     program: str, *, name: str | None = None, api_key: str | None = None, endpoint: str | None = None
 ) -> dict[str, Any]:
-    """Create a program-owned valset. ``name`` is auto-assigned when omitted."""
-    payload = {"program": program, "name": name or default_name()}
-    return _client(api_key, endpoint).post("/api/v1/valsets", json=payload)
+    """Create a valset owned by ``program``, a program name or ``p_`` id. ``name`` is auto-assigned when omitted."""
+    client = _client(api_key, endpoint)
+    payload = {"program": programs.program_id_for(client, program), "name": name or default_name()}
+    return client.post("/api/v1/valsets", json=payload)
 
 
 def list(
     program: str, *, limit: int = 50, offset: int = 0, api_key: str | None = None, endpoint: str | None = None
 ) -> dict[str, Any]:
-    """List a program's valsets, newest first.
+    """List the valsets of ``program``, a program name or ``p_`` id, newest first.
 
     Returns ``{"valsets": [...], "total": N, "limit", "offset", "has_more"}``.
     ``limit`` / ``offset`` page the full set — the server clamps ``limit`` to at
     most 200.
     """
-    params = {"program": program, "limit": str(limit), "offset": str(offset)}
-    return _client(api_key, endpoint).get("/api/v1/valsets", params=params)
+    client = _client(api_key, endpoint)
+    params = {"program": programs.program_id_for(client, program), "limit": str(limit), "offset": str(offset)}
+    return client.get("/api/v1/valsets", params=params)
 
 
 def get(valset_id: str, *, api_key: str | None = None, endpoint: str | None = None) -> dict[str, Any]:

{cmpnd-0.63.0 → cmpnd-0.64.0}/cmpnd/callback.py

@@ -39,6 +39,27 @@ def _declared_program_name() -> str | None:
     return name if isinstance(name, str) else None
 
 
+# Set once the process has warned that a trace names no program, so the warning
+# appears once per process, whichever callback records the trace.
+_warned_unattributed = False
+
+
+def _warn_once_if_unattributed(trace: models.TraceBuilder) -> None:
+    """Warn the first time a trace in this process names neither a program name nor a program id.
+
+    Such a trace belongs to no program, and the platform files it under Unattributed.
+    """
+    global _warned_unattributed
+    if _warned_unattributed or trace.declared_name is not None or trace.program_id is not None:
+        return
+    _warned_unattributed = True
+    logger.warning(
+        "cmpnd: this trace names no program, so the platform files it under Unattributed. Give the program a "
+        "name with @cmpnd.program(name) and run it through cmpnd.Client, and its traces go to that program. "
+        "This warning appears once per process."
+    )
+
+
 def trace_id(prediction: Any) -> str | None:
     """Return the cmpnd trace id for a prediction returned by an instrumented program.
 
@@ -1193,6 +1214,10 @@ class _ModuleMixin(_CallbackBase):
             module_class=instance.__class__.__name__,
         )
         self._stamp(trace)
+        # A root module call is where a program runs, so it is where an unnamed one
+        # is caught. GEPA's own LM calls (_emit_optimization_lm_trace) belong to the
+        # optimization run, which names the program, so they never warn.
+        _warn_once_if_unattributed(trace)
 
         # Attach the run ids this trace starts under, from this callback's own
         # state right now — not at finalize (on_module_end), where the

{cmpnd-0.63.0 → cmpnd-0.64.0}/cmpnd/cli/__init__.py

@@ -24,7 +24,6 @@ from .commands import (
     org,
     programs,
     provider_credentials,
-    signatures,
     tool_servers,
     top,
     traces,
@@ -164,7 +163,6 @@ def main() -> None:
     # gates each read on scope, so a caller without it gets a 403, not a
     # hidden command.
     programs.register(subparsers)
-    signatures.register(subparsers)
     traces.register(subparsers)
     evals.register(subparsers)
     datasets.register(subparsers)

{cmpnd-0.63.0 → cmpnd-0.64.0}/cmpnd/cli/commands/assessments.py

@@ -56,7 +56,8 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     scope.add_argument(
         "program",
         nargs="?",
-        help="Program id (p_…), or a legacy signature hash (16-hex, as `cmpnd signatures list` shows)",
+        metavar="PROGRAM",
+        help="Program name or p_ id",
     )
     scope.add_argument("--trace", dest="trace_id", metavar="TRACE_ID", help="A single trace's assessments")
     pagination.add_args(ls, with_page_aliases=False, default_limit=50)
@@ -88,7 +89,15 @@ def handle_create(client: api_client.ApiClient, args: Any) -> Any:
 
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
-    scope = {"trace_id": args.trace_id} if args.trace_id else {"program": args.program}
+    if args.trace_id:
+        scope = {"trace_id": args.trace_id}
+    else:
+        from . import programs
+
+        program_id, _ = programs.resolve(
+            client, args.program, old_server_remedy="Upgrade the server to name a program."
+        )
+        scope = {"program": program_id}
     params = {**scope, **pagination.wire(args, "limit_offset", as_str=True)}
     return client.get("/api/v1/assessments", params=params)
 

{cmpnd-0.63.0 → cmpnd-0.64.0}/cmpnd/cli/commands/evals.py

@@ -50,7 +50,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     # `evals compare` is deliberately absent. The route requires a
     # `dataset_hash`, and no eval read returns one: neither the list nor the
     # detail projection carries it, and nor does the compare response itself.
-    # The only surface that emits one is `signatures evals`, so the command
+    # The only surface that emits one is `programs evals`, so the command
     # would ship with a required argument its own noun cannot produce. It goes
     # in once the projection carries the hash.
 

{cmpnd-0.63.0 → cmpnd-0.64.0}/cmpnd/cli/commands/programs.py

@@ -13,8 +13,8 @@ from .. import api_client, pagination
 from . import provider_credentials
 
 
-# `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
+# `show`, `traces`, `stats`, `usage`, `examples`, `evals` and `history` 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
@@ -129,7 +129,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         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."
+            "`cmpnd traces list --program PROGRAM --since DATE` sets the window itself. --limit is at most 500."
         ),
     )
     tr.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
@@ -145,6 +145,23 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     _add_usage_window(usage)
     usage.set_defaults(func=handle_usage)
 
+    examples = sub.add_parser("examples", help="List a program's recorded input/output examples, newest first")
+    examples.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
+    pagination.add_args(examples, with_page_aliases=False, default_limit=25)
+    examples.set_defaults(func=handle_examples)
+
+    evals = sub.add_parser("evals", help="List the eval runs that touched a program, newest first")
+    evals.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
+    # This route caps rows and has no offset of any spelling, so it gets a bare
+    # --limit rather than the shared pagination pair: an --offset the server
+    # drops would read as a page the caller never received.
+    evals.add_argument("--limit", type=int, default=10, help="Max eval runs, newest first (default %(default)s)")
+    evals.set_defaults(func=handle_evals)
+
+    history = sub.add_parser("history", help="Show a program's distinct prompt instructions over time")
+    history.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
+    history.set_defaults(func=handle_history)
+
     # The registry is the programs an SDK client registered, as distinct from
     # the optimized programs `programs list` aggregates out of runs — different
     # records, so they nest rather than share a flat verb.
@@ -310,15 +327,20 @@ _RECORDED_PROGRAMS_CAP = 200
 def _list_recorded(client: api_client.ApiClient, params: dict[str, str]) -> dict[str, Any]:
     """List the programs a server from before the program list recorded traces for, paged here.
 
-    GET /api/v1/modules answers them in one array, by name and legacy hash, up to its cap. A program with no
-    traces yet is not in it. A full array may be missing programs past the cap, so the answer then has no total
-    and says it is incomplete.
+    GET /api/v1/modules answers them in one array, up to its cap. A program with no traces yet is not in it. A
+    full array may be missing programs past the cap, so the answer then has no total and says it is incomplete.
+    Each row keeps what the server recorded except its signature hash, which names no program and which no
+    command takes.
     """
-    rows = client.get("/api/v1/modules")
-    if not isinstance(rows, list):
+    answered = client.get("/api/v1/modules")
+    if not isinstance(answered, list):
         raise api_client.CliError(
             "this cmpnd server answered neither the program list nor the list of recorded programs"
         )
+    rows = [
+        {key: value for key, value in row.items() if key != "program_signature_hash"} if isinstance(row, dict) else row
+        for row in answered
+    ]
     complete = len(rows) < _RECORDED_PROGRAMS_CAP
     note = "note: this cmpnd server predates the program list, so this lists the programs it recorded traces for."
     if not complete:
@@ -376,9 +398,15 @@ def _trash_remedy() -> str:
     return "Manage its Trash in the web app, at /ui/account/trash, or upgrade the server."
 
 
+# The reads that have a `programs optimized` counterpart taking a compiled program hash.
+_OPTIMIZED_VERBS = frozenset({"show", "traces", "stats", "usage"})
+
+
 def _read_remedy(verb: str) -> str:
     from . import top
 
+    if verb not in _OPTIMIZED_VERBS:
+        return f"Upgrade the server to read a program's {verb} by its name or p_ id."
     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."
@@ -389,17 +417,15 @@ def _resolve_for_read(client: api_client.ApiClient, ref: str, verb: str, *, tras
     """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.
+    ``trashed_ok``. For a verb with a ``programs optimized`` counterpart, an
+    unknown name may be a compiled program hash, which that command 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),
-    )
+    unknown_hint = ""
+    if verb in _OPTIMIZED_VERBS:
+        unknown_hint = f"A compiled program hash goes to `{top.hint_programs('optimized', verb, ref)}`."
+    program_id, trashed = resolve(client, ref, unknown_hint=unknown_hint, 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. "
@@ -451,6 +477,23 @@ def handle_usage(client: api_client.ApiClient, args: Any) -> Any:
     return _read(client, "usage", f"/api/v1/programs/{program_id}/usage-history", _usage_params(args))
 
 
+# The per-program record reads live under /api/v1/signatures/{program}, which takes the program's p_ id.
+def handle_examples(client: api_client.ApiClient, args: Any) -> Any:
+    params = pagination.wire(args, "per_page", as_str=True)
+    program_id = _resolve_for_read(client, args.program, "examples")
+    return _read(client, "examples", f"/api/v1/signatures/{program_id}/examples", params)
+
+
+def handle_evals(client: api_client.ApiClient, args: Any) -> Any:
+    program_id = _resolve_for_read(client, args.program, "evals")
+    return _read(client, "evals", f"/api/v1/signatures/{program_id}/evals", {"limit": str(args.limit)})
+
+
+def handle_history(client: api_client.ApiClient, args: Any) -> Any:
+    program_id = _resolve_for_read(client, args.program, "history")
+    return _read(client, "history", f"/api/v1/signatures/{program_id}/history")
+
+
 def handle_optimized_show(client: api_client.ApiClient, args: Any) -> Any:
     return client.get(f"/api/v1/programs/{args.hash}")