cmpnd 0.23.2__tar.gz → 0.24.1__tar.gz

{cmpnd-0.23.2 → cmpnd-0.24.1}/.gitignore

@@ -21,6 +21,7 @@ wheels/
 # Virtual environments
 .env
 .venv
+.venv-linux
 env/
 venv/
 ENV/

cmpnd-0.23.2/CLAUDE.md → cmpnd-0.24.1/AGENTS.md

@@ -1,6 +1,6 @@
-# Claude Code Instructions
+# Agent Instructions
 
-Part of the CMPND monorepo. See `../CLAUDE.md` for cross-cutting rules (hash architecture, null handling, testing philosophy).
+Part of the CMPND monorepo. See `../AGENTS.md` for cross-cutting rules (hash architecture, null handling, testing philosophy).
 
 ## This code is released publicly — no private references
 
@@ -104,7 +104,7 @@ code while the top-level `docs/` rotted: **the docs are part of the diff.**
   exporter transport, the IR/hash, the optimizer tracker), or changes the wire
   shape the SDK emits **updates the matching doc in the same commit.** If a
   change leaves a doc describing the old behavior, the change isn't done.
-- The `cmpnd-*` skills under `.claude/skills/` point at these docs rather than
+- The `cmpnd-*` skills under `../.agents/skills/` point at these docs rather than
   duplicating them — keep the doc authoritative and let the skill be the thin
   trigger. (Anchor paths are checked by `bin/check-skill-anchors`.)
 - `docs/plans/*` is append-only design history and is exempt — don't rewrite it.

cmpnd-0.24.1/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

{cmpnd-0.23.2 → cmpnd-0.24.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.23.2
+Version: 0.24.1
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -22,6 +22,7 @@ Requires-Dist: httpx>=0.27.0
 Requires-Dist: ipython>=8.20
 Requires-Dist: openai<2
 Requires-Dist: pydantic>=2.0
+Requires-Dist: typing-extensions>=4.1.0
 Requires-Dist: xxhash>=3.0.0
 Provides-Extra: dev
 Requires-Dist: basedpyright>=1.39; extra == 'dev'
@@ -41,7 +42,8 @@ Requires-Dist: cmpnd-fake-provider; (python_version >= '3.11') and extra == 'fak
 Provides-Extra: images
 Requires-Dist: pillow>=10.0; extra == 'images'
 Provides-Extra: mcp
-Requires-Dist: mcp<2,>=1.9; extra == 'mcp'
+Requires-Dist: dspy>=3.3.1; extra == 'mcp'
+Requires-Dist: mcp>=1.9; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # cmpnd

cmpnd-0.24.1/cmpnd/_assessments.py

@@ -0,0 +1,72 @@
+"""Assessment HTTP calls behind ``cmpnd.Client``'s assessment methods.
+
+Private helpers: the public surface is ``create_assessment`` /
+``list_assessments`` / ``get_assessment`` on :class:`cmpnd.Client`, which
+delegate here with the client's credentials. Each function reaches one backend
+route over the shared ``_http`` transport. An omitted ``conclusion`` is
+``"neutral"`` — neither affirming nor disputing the trace.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from typing import Any, Literal
+
+from . import _http, configuration
+
+DEFAULT_ENDPOINT = "https://platform.cmpnd.ai"
+
+Conclusion = Literal["up", "down", "neutral"]
+
+
+def create(
+    trace_id: str,
+    *,
+    conclusion: Conclusion = "neutral",
+    body: str | None = None,
+    annotations: Sequence[tuple[str, str]] | None = None,
+    api_key: str | None = None,
+    endpoint: str | None = None,
+) -> dict[str, Any]:
+    """Record one judgement of a trace and return the created assessment.
+
+    ``conclusion`` affirms (``"up"``), disputes (``"down"``), or neither
+    (``"neutral"``, the default). ``annotations`` are ``(span_id, note)`` pairs,
+    each attaching a note to one span of the trace; the server rejects a span id
+    that does not belong to the trace. ``api_key`` / ``endpoint`` override the
+    configured credentials for this call.
+    """
+    payload: dict[str, Any] = {"trace_id": trace_id, "conclusion": conclusion}
+    if body is not None:
+        payload["body"] = body
+    if annotations:
+        payload["annotations"] = [{"span_id": span, "note": note} for span, note in annotations]
+    return _client(api_key, endpoint).post("/api/v1/assessments", 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 assessments, newest first.
+
+    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.
+    """
+    params = {"program": program, "limit": str(limit), "offset": str(offset)}
+    return _client(api_key, endpoint).get("/api/v1/assessments", params=params)
+
+
+def get(assessment_id: str, *, api_key: str | None = None, endpoint: str | None = None) -> dict[str, Any]:
+    """Fetch one assessment with its annotations."""
+    return _client(api_key, endpoint).get(f"/api/v1/assessments/{assessment_id}")
+
+
+def _client(api_key: str | None, endpoint: str | None) -> _http.ApiClient:
+    cfg = configuration.get_config()
+    resolved_key = api_key or (cfg.api_key if cfg else None) or os.getenv("CMPND_API_KEY")
+    if not resolved_key:
+        raise _http.ApiError("No API key. Pass api_key=, call cmpnd.configure(api_key=...), or set CMPND_API_KEY.")
+    resolved_endpoint = endpoint or (cfg.endpoint if cfg else None) or os.getenv("CMPND_ENDPOINT") or DEFAULT_ENDPOINT
+    return _http.ApiClient(resolved_key, resolved_endpoint)

cmpnd-0.23.2/cmpnd/traces.py → cmpnd-0.24.1/cmpnd/_traces.py

@@ -1,22 +1,11 @@
-"""Programmatic trace reads for the cmpnd backend.
-
-``import cmpnd`` already emits traces; this module reads them back. ``cmpnd.traces``
-reaches the same two backend reads the CLI does — ``list`` and ``show`` — over the
-same HTTP transport, so the library and the CLI cannot drift. It follows the SDK's
-existing shape: module-level verbs over the credentials ``cmpnd.configure()`` set,
-like ``cmpnd.deploy`` / ``cmpnd.execute`` / ``cmpnd.load_dataset``.
-
-    >>> import cmpnd
-    >>> cmpnd.configure(api_key="ct_xxx")
-    >>> page = cmpnd.traces.list(status="error", since="30d", limit=10)
-    >>> for row in page["traces"]:
-    ...     detail = cmpnd.traces.show(row["trace_id"])
-
-The verbs and filter names match the ``cmpnd traces`` CLI vocabulary — ``list`` and
-``show``, filtered by ``query``, ``program``, ``hash``, ``deployment``, ``since`` /
-``until``, ``all_history`` — so a user moves between the two surfaces without
-relearning names. (The CLI's ``traces search`` spelling is a deprecated alias of
-``traces list``; this surface offers only ``list``.)
+"""Trace-read HTTP calls behind ``cmpnd.Client``'s trace methods.
+
+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`` /
+``all_history``, and ``show`` for one trace — so the surfaces do not drift.
 """
 
 from __future__ import annotations

cmpnd-0.24.1/cmpnd/_valsets.py

@@ -0,0 +1,107 @@
+"""Validation-set HTTP calls behind ``cmpnd.Client``'s valset methods.
+
+Private helpers: the public surface is ``create_valset`` / ``list_valsets`` /
+``get_valset`` / ``list_valset_entries`` / ``create_valset_entry`` /
+``delete_valset_entry`` on :class:`cmpnd.Client`, which delegate here with the
+client's credentials. Each function reaches one backend route over the shared
+``_http`` transport. An entry's input comes from exactly one source — an
+assessment's trace (``from_assessment``) or a JSON ``inputs`` object; the
+expected output is always the caller's.
+"""
+
+from __future__ import annotations
+
+import datetime
+import os
+from typing import Any
+
+from . import _http, configuration
+
+DEFAULT_ENDPOINT = "https://platform.cmpnd.ai"
+
+
+def default_name() -> str:
+    """The valset name assigned when the caller omits one — a human-readable
+    date label. Names are not required to be unique (the id identifies a
+    valset), so a repeated name is fine and needs no collision suffix."""
+    return f"valset-{datetime.datetime.now():%Y%m%d-%H%M%S}"
+
+
+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)
+
+
+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.
+
+    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)
+
+
+def get(valset_id: str, *, api_key: str | None = None, endpoint: str | None = None) -> dict[str, Any]:
+    """Fetch one valset with its field shape and current version."""
+    return _client(api_key, endpoint).get(f"/api/v1/valsets/{valset_id}")
+
+
+def list_entries(
+    valset_id: str, *, limit: int = 50, offset: int = 0, api_key: str | None = None, endpoint: str | None = None
+) -> dict[str, Any]:
+    """List a valset's active entries.
+
+    Returns ``{"entries": [...], "total": N, "limit", "offset", "has_more"}``.
+    ``limit`` / ``offset`` page the full set — the server clamps ``limit`` to at
+    most 200.
+    """
+    params = {"limit": str(limit), "offset": str(offset)}
+    return _client(api_key, endpoint).get(f"/api/v1/valsets/{valset_id}/entries", params=params)
+
+
+def create_entry(
+    valset_id: str,
+    *,
+    expected_outputs: dict[str, Any],
+    inputs: dict[str, Any] | None = None,
+    from_assessment: str | None = None,
+    api_key: str | None = None,
+    endpoint: str | None = None,
+) -> dict[str, Any]:
+    """Add one entry to a valset.
+
+    The input comes from exactly one source: pass ``from_assessment`` and the
+    server derives the inputs from that assessment's trace, or pass ``inputs``
+    directly. Supplying both or neither is an error. ``expected_outputs`` is
+    always required — the server never infers it.
+    """
+    if (inputs is None) == (from_assessment is None):
+        raise _http.ApiError("pass exactly one of inputs= or from_assessment=")
+    payload: dict[str, Any] = {"expected_outputs": expected_outputs}
+    if from_assessment is not None:
+        payload["from_assessment"] = from_assessment
+    else:
+        payload["inputs"] = inputs
+    return _client(api_key, endpoint).post(f"/api/v1/valsets/{valset_id}/entries", json=payload)
+
+
+def delete_entry(entry_id: str, *, api_key: str | None = None, endpoint: str | None = None) -> dict[str, Any]:
+    """Retire an entry (versioned, not a hard delete)."""
+    _client(api_key, endpoint).delete(f"/api/v1/valsets/entries/{entry_id}")
+    return {"deleted": entry_id}
+
+
+def _client(api_key: str | None, endpoint: str | None) -> _http.ApiClient:
+    cfg = configuration.get_config()
+    resolved_key = api_key or (cfg.api_key if cfg else None) or os.getenv("CMPND_API_KEY")
+    if not resolved_key:
+        raise _http.ApiError("No API key. Pass api_key=, call cmpnd.configure(api_key=...), or set CMPND_API_KEY.")
+    resolved_endpoint = endpoint or (cfg.endpoint if cfg else None) or os.getenv("CMPND_ENDPOINT") or DEFAULT_ENDPOINT
+    return _http.ApiClient(resolved_key, resolved_endpoint)

{cmpnd-0.23.2 → cmpnd-0.24.1}/cmpnd/cli/__init__.py

@@ -7,10 +7,11 @@ import importlib.metadata
 import json
 import os
 import sys
+import typing
 
 import httpx
 
-from . import api_client, deprecation
+from . import api_client, deprecation, tree_help
 from .commands import (
     admin,
     assessments,
@@ -87,7 +88,7 @@ Auth: set CMPND_API_KEY and (optionally) CMPND_ENDPOINT, or pass --api-key /
 
 
 def main() -> None:
-    parser = argparse.ArgumentParser(
+    parser = tree_help.TreeHelpParser(
         prog="cmpnd",
         description="CMPND platform CLI — deploy, invoke, and inspect DSPy programs.",
         epilog=_EPILOG,
@@ -97,7 +98,14 @@ def main() -> None:
     parser.add_argument("--api-key", dest="api_key", help="API key (or set CMPND_API_KEY)")
     parser.add_argument("--endpoint", help="API endpoint (or set CMPND_ENDPOINT)")
 
-    subparsers = parser.add_subparsers(dest="resource")
+    # The root parser is a TreeHelpParser, so add_subparsers() is typed
+    # _SubParsersAction[TreeHelpParser]; the command modules' register() take
+    # _SubParsersAction[ArgumentParser], and that generic is invariant. A
+    # TreeHelpParser IS an ArgumentParser at runtime, so cast to the base.
+    subparsers = typing.cast(
+        "argparse._SubParsersAction[argparse.ArgumentParser]",
+        parser.add_subparsers(dest="resource"),
+    )
 
     # Auth subcommand (part of the primary flow, always available)
     auth.register(subparsers)

{cmpnd-0.23.2 → cmpnd-0.24.1}/cmpnd/cli/commands/assessments.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
-from .. import api_client
+from .. import api_client, pagination
 
 
 def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
@@ -18,7 +18,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
     create = sub.add_parser("create", help="Record a judgement of a trace")
     create.add_argument("trace_id", help="The trace to assess (its SDK trace id)")
-    conclusion = create.add_mutually_exclusive_group(required=True)
+    conclusion = create.add_mutually_exclusive_group()
     conclusion.add_argument(
         "--up", dest="conclusion", action="store_const", const="up", help="Affirm the trace's output"
     )
@@ -26,8 +26,13 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         "--down", dest="conclusion", action="store_const", const="down", help="Dispute the trace's output"
     )
     conclusion.add_argument(
-        "--neutral", dest="conclusion", action="store_const", const="neutral", help="Neither affirm nor dispute"
+        "--neutral",
+        dest="conclusion",
+        action="store_const",
+        const="neutral",
+        help="Neither affirm nor dispute (the default when no conclusion is given)",
     )
+    create.set_defaults(conclusion="neutral")
     create.add_argument("-m", "--message", dest="body", help="The prose body of the judgement")
     create.add_argument(
         "--annotate",
@@ -40,9 +45,8 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     create.set_defaults(func=handle_create)
 
     ls = sub.add_parser("list", help="List a program's assessments")
-    ls.add_argument(
-        "--program", required=True, help="Program signature hash (16-hex, as `cmpnd signatures list` shows)"
-    )
+    ls.add_argument("program", help="Program signature hash (16-hex, as `cmpnd signatures list` shows)")
+    pagination.add_args(ls, with_page_aliases=False, default_limit=50)
     ls.set_defaults(func=handle_list)
 
     show = sub.add_parser("show", help="Show one assessment with its annotations")
@@ -60,7 +64,8 @@ def handle_create(client: api_client.ApiClient, args: Any) -> Any:
 
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
-    return client.get("/api/v1/assessments", params={"program": args.program})
+    params = {"program": args.program, **pagination.wire(args, "limit_offset", as_str=True)}
+    return client.get("/api/v1/assessments", params=params)
 
 
 def handle_show(client: api_client.ApiClient, args: Any) -> Any:

{cmpnd-0.23.2 → cmpnd-0.24.1}/cmpnd/cli/commands/top.py

@@ -15,7 +15,7 @@ from argparse import ArgumentParser, ArgumentTypeError, _SubParsersAction
 from datetime import datetime, timezone
 from typing import Any
 
-from .. import api_client, pagination
+from .. import api_client, pagination, snippet
 from . import signatures
 
 # --------------------------------------------------------------------------
@@ -782,30 +782,35 @@ def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
 
     configuration.configure(api_key=client._api_key, endpoint=client._endpoint)
 
-    namespace: dict[str, Any] = {"__name__": "__cmpnd_deploy__", "__file__": source_label}
-    try:
-        exec(compile(source, source_label, "exec"), namespace)
-    except Exception as exc:
-        raise api_client.CliError(f"Snippet raised {type(exc).__name__}: {exc}")
-
-    program = namespace.get("program")
-    if program is None:
-        # Fallback: pick the last dspy.Module instance defined.
+    # The whole packaging step stays inside the registration, not just the exec:
+    # both the annotations DSPy resolves and the class sources the packager
+    # inlines are read back out of `sys.modules` after the snippet has run.
+    with snippet.as_module("__cmpnd_deploy__", source_label) as module:
+        namespace: dict[str, Any] = module.__dict__
         try:
-            import dspy
-        except ImportError:
-            raise api_client.CliError("Snippet did not bind `program`, and dspy isn't importable to scan for one.")
-        candidates = [v for v in namespace.values() if isinstance(v, dspy.Module)]
-        if not candidates:
-            raise api_client.CliError(
-                "Snippet did not bind `program` to a dspy.Module instance. Add e.g. `program = dspy.Predict(...)`."
-            )
-        program = candidates[-1]
+            exec(compile(source, source_label, "exec"), namespace)
+        except Exception as exc:
+            raise api_client.CliError(f"Snippet raised {type(exc).__name__}: {exc}")
+
+        program = namespace.get("program")
+        if program is None:
+            # Fallback: pick the last dspy.Module instance defined.
+            try:
+                import dspy
+            except ImportError:
+                raise api_client.CliError("Snippet did not bind `program`, and dspy isn't importable to scan for one.")
+            candidates = [v for v in namespace.values() if isinstance(v, dspy.Module)]
+            if not candidates:
+                raise api_client.CliError(
+                    "Snippet did not bind `program` to a dspy.Module instance. Add e.g. `program = dspy.Predict(...)`."
+                )
+            program = candidates[-1]
+
+        metadata = _parse_deploy_metadata(getattr(args, "metadata", None))
 
-    metadata = _parse_deploy_metadata(getattr(args, "metadata", None))
+        print(_c("deploying…", "dim"), file=sys.stderr)
+        deployed = deployment.deploy(program, metadata=metadata)
 
-    print(_c("deploying…", "dim"), file=sys.stderr)
-    deployed = deployment.deploy(program, metadata=metadata)
     deployment_id = deployed.deployment_id
     print(deployment_id)
 
@@ -882,42 +887,46 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
 
     configuration.configure(api_key=client._api_key, endpoint=client._endpoint)
 
-    namespace: dict[str, Any] = {"__name__": "__cmpnd_optimize__", "__file__": source_label}
-    try:
-        exec(compile(source, source_label, "exec"), namespace)
-    except Exception as exc:
-        raise api_client.CliError(f"Snippet raised {type(exc).__name__}: {exc}")
+    # Registered for the whole run, not just the exec: optimize deploys the
+    # program, and packaging reads the snippet's classes back through
+    # `sys.modules`. See `cmpnd.cli.snippet`.
+    with snippet.as_module("__cmpnd_optimize__", source_label) as module:
+        namespace: dict[str, Any] = module.__dict__
+        try:
+            exec(compile(source, source_label, "exec"), namespace)
+        except Exception as exc:
+            raise api_client.CliError(f"Snippet raised {type(exc).__name__}: {exc}")
 
-    missing = [name for name in ("program", "trainset", "valset", "metric") if namespace.get(name) is None]
-    if missing:
-        raise api_client.CliError(
-            f"Snippet must bind {missing} — e.g. `program = dspy.Predict('q -> a')`, "
-            "`trainset = [...]`, `valset = [...]`, "
-            "`def metric(gold, pred, trace, pred_name, pred_trace): ...` returning "
-            "`dspy.Prediction(score=, feedback=)`."
-        )
+        missing = [name for name in ("program", "trainset", "valset", "metric") if namespace.get(name) is None]
+        if missing:
+            raise api_client.CliError(
+                f"Snippet must bind {missing} — e.g. `program = dspy.Predict('q -> a')`, "
+                "`trainset = [...]`, `valset = [...]`, "
+                "`def metric(gold, pred, trace, pred_name, pred_trace): ...` returning "
+                "`dspy.Prediction(score=, feedback=)`."
+            )
 
-    print(_c(f"optimizing with {args.optimizer}…", "dim"), file=sys.stderr)
-    try:
-        result = optimization.optimize(
-            namespace["program"],
-            optimizer=args.optimizer,
-            trainset=namespace["trainset"],
-            valset=namespace["valset"],
-            metric=namespace["metric"],
-            deployment_id=getattr(args, "deployment_id", None),
-            # The flag is named for what a command line can carry — a model name,
-            # never an LM object — and the parameter for what the Python surface
-            # accepts. Each layer's name says what that layer takes.
-            reflection_lm=getattr(args, "reflection_model", None),
-            max_metric_calls=getattr(args, "max_metric_calls", None),
-            auto=getattr(args, "auto", None),
-            max_steps=getattr(args, "max_steps", 10),
-            patience=getattr(args, "patience", 2),
-            seed=getattr(args, "seed", 0),
-        )
-    except (optimization.OptimizeError, optimization.OptimizeFailed, ValueError) as exc:
-        raise api_client.CliError(str(exc))
+        print(_c(f"optimizing with {args.optimizer}…", "dim"), file=sys.stderr)
+        try:
+            result = optimization.optimize(
+                namespace["program"],
+                optimizer=args.optimizer,
+                trainset=namespace["trainset"],
+                valset=namespace["valset"],
+                metric=namespace["metric"],
+                deployment_id=getattr(args, "deployment_id", None),
+                # The flag is named for what a command line can carry — a model name,
+                # never an LM object — and the parameter for what the Python surface
+                # accepts. Each layer's name says what that layer takes.
+                reflection_lm=getattr(args, "reflection_model", None),
+                max_metric_calls=getattr(args, "max_metric_calls", None),
+                auto=getattr(args, "auto", None),
+                max_steps=getattr(args, "max_steps", 10),
+                patience=getattr(args, "patience", 2),
+                seed=getattr(args, "seed", 0),
+            )
+        except (optimization.OptimizeError, optimization.OptimizeFailed, ValueError) as exc:
+            raise api_client.CliError(str(exc))
 
     if getattr(args, "json", False):
         print(

{cmpnd-0.23.2 → cmpnd-0.24.1}/cmpnd/cli/commands/valsets.py

@@ -11,7 +11,8 @@ import json
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
-from .. import api_client
+from ... import _valsets
+from .. import api_client, pagination
 
 
 def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
@@ -20,11 +21,15 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
     create = sub.add_parser("create", help="Create a validation set owned by a program")
     create.add_argument("program_hash", help="Owning program signature hash (16-hex, as `cmpnd signatures list` shows)")
-    create.add_argument("--name", required=True, help="Validation-set name (unique within the program)")
+    create.add_argument(
+        "--name",
+        help="Validation-set name — a memory-aid label, need not be unique; auto-assigned from the date when omitted",
+    )
     create.set_defaults(func=handle_create)
 
     ls = sub.add_parser("list", help="List a program's validation sets")
-    ls.add_argument("--program", required=True, help="Program signature hash (16-hex)")
+    ls.add_argument("program", help="Program signature hash (16-hex)")
+    pagination.add_args(ls, with_page_aliases=False, default_limit=50)
     ls.set_defaults(func=handle_list)
 
     show = sub.add_parser("show", help="Show a validation set")
@@ -36,12 +41,20 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
     elist = esub.add_parser("list", help="List a valset's active entries")
     elist.add_argument("valset_id", help="Valset id")
+    pagination.add_args(elist, with_page_aliases=False, default_limit=50)
     elist.set_defaults(func=handle_entries_list)
 
-    ecreate = esub.add_parser("create", help="Add an entry from JSON content")
+    ecreate = esub.add_parser("create", help="Add an entry from an assessment or from JSON inputs")
     ecreate.add_argument("valset_id", help="Valset id")
-    ecreate.add_argument(
-        "--inputs", required=True, metavar="JSON", help="Inputs object; its keys are the valset's input fields"
+    # The entry's input comes from exactly one source: an assessment's trace, or
+    # a JSON inputs object supplied directly. The expected output is always the
+    # caller's — the server never infers it.
+    source = ecreate.add_mutually_exclusive_group(required=True)
+    source.add_argument("--inputs", metavar="JSON", help="Inputs object; its keys are the valset's input fields")
+    source.add_argument(
+        "--from-assessment",
+        dest="from_assessment",
+        help="Source assessment id; its trace supplies the inputs and records the entry's provenance",
     )
     ecreate.add_argument(
         "--expected-outputs",
@@ -50,9 +63,6 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         metavar="JSON",
         help="Expected-outputs object; its keys are the valset's output fields",
     )
-    ecreate.add_argument(
-        "--from-assessment", dest="from_assessment", help="Source assessment id, recorded as the entry's provenance"
-    )
     ecreate.set_defaults(func=handle_entries_create)
 
     edelete = esub.add_parser("delete", help="Retire an entry (versioned, not a hard delete)")
@@ -61,11 +71,15 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
 
 def handle_create(client: api_client.ApiClient, args: Any) -> Any:
-    return client.post("/api/v1/valsets", json={"program": args.program_hash, "name": args.name})
+    # 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})
 
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
-    return client.get("/api/v1/valsets", params={"program": args.program})
+    params = {"program": args.program, **pagination.wire(args, "limit_offset", as_str=True)}
+    return client.get("/api/v1/valsets", params=params)
 
 
 def handle_show(client: api_client.ApiClient, args: Any) -> Any:
@@ -73,15 +87,17 @@ def handle_show(client: api_client.ApiClient, args: Any) -> Any:
 
 
 def handle_entries_list(client: api_client.ApiClient, args: Any) -> Any:
-    return client.get(f"/api/v1/valsets/{args.valset_id}/entries")
+    params = pagination.wire(args, "limit_offset", as_str=True)
+    return client.get(f"/api/v1/valsets/{args.valset_id}/entries", params=params)
 
 
 def handle_entries_create(client: api_client.ApiClient, args: Any) -> Any:
-    inputs = _parse_json_flag("--inputs", args.inputs)
-    expected = _parse_json_flag("--expected-outputs", args.expected_outputs)
-    body: dict[str, Any] = {"inputs": inputs, "expected_outputs": expected}
+    body: dict[str, Any] = {"expected_outputs": _parse_json_flag("--expected-outputs", args.expected_outputs)}
     if args.from_assessment:
+        # The source assessment's trace supplies the inputs; the server derives them.
         body["from_assessment"] = args.from_assessment
+    else:
+        body["inputs"] = _parse_json_flag("--inputs", args.inputs)
     return client.post(f"/api/v1/valsets/{args.valset_id}/entries", json=body)