cmpnd 0.23.2__tar.gz → 0.24.0__tar.gz

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

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

cmpnd-0.23.2/CLAUDE.md → cmpnd-0.24.0/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.0/CLAUDE.md

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

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

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

cmpnd-0.24.0/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.0/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.0/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.0}/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.0}/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.0}/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)
 
 

cmpnd-0.24.0/cmpnd/cli/tree_help.py

@@ -0,0 +1,98 @@
+"""Recursive command-tree help for the cmpnd CLI.
+
+Argparse only lists a parser's *immediate* subcommands, so a nested group like
+``cmpnd valsets`` hides ``entries create`` / ``entries list`` / ``entries
+delete`` one level down — the surface is there but undiscoverable without
+drilling in parser by parser. ``TreeHelpParser`` replaces that one-level listing
+with the full descendant set, so ``<command> --help`` shows everything under it
+at once.
+
+Each row is the command's **full path** (``valsets entries create``), indented
+two spaces per level. The indent makes the hierarchy scannable; the repeated
+words — unlike ``├─`` glyph decoration — can be copied straight into a shell.
+Depth-first order keeps a group's children directly beneath it.
+
+The class propagates for free: ``ArgumentParser.add_subparsers`` defaults its
+``parser_class`` to ``type(self)``, so making the root parser a
+``TreeHelpParser`` makes every group and subgroup one too.
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+_MAX_LABEL = 40
+
+
+def _subparsers_action(parser: argparse.ArgumentParser) -> argparse._SubParsersAction[Any] | None:
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            return action
+    return None
+
+
+def _path(prog: str) -> str:
+    """The command path minus the binary name: 'cmpnd valsets create' → 'valsets create'."""
+    parts = prog.split(" ", 1)
+    return parts[1] if len(parts) > 1 else prog
+
+
+def _walk(parser: argparse.ArgumentParser, depth: int, out: list[tuple[int, str, str]]) -> None:
+    action = _subparsers_action(parser)
+    if action is None:
+        return
+    helps = {ca.dest: (ca.help or "") for ca in action._choices_actions}
+    seen: set[int] = set()
+    for name, sub in action.choices.items():
+        # Aliases point at the same parser object as their canonical name; list
+        # each command once, under the name argparse recorded help for.
+        if id(sub) in seen or name not in helps:
+            continue
+        seen.add(id(sub))
+        out.append((depth, _path(sub.prog), helps[name]))
+        _walk(sub, depth + 1, out)
+
+
+def format_command_tree(parser: argparse.ArgumentParser) -> str:
+    """Render the full nested subcommand set under ``parser`` (empty if none).
+
+    Each line is the copy-pasteable command path, indented by depth, followed by
+    its help.
+    """
+    out: list[tuple[int, str, str]] = []
+    _walk(parser, 0, out)
+    if not out:
+        return ""
+    labels = ["  " * depth + path for depth, path, _ in out]
+    width = min(max(len(label) for label in labels), _MAX_LABEL)
+    lines = ["commands:"]
+    for label, (_, _, help_text) in zip(labels, out):
+        lines.append(f"  {label.ljust(width)}  {help_text}".rstrip() if help_text else f"  {label}")
+    return "\n".join(lines)
+
+
+class TreeHelpParser(argparse.ArgumentParser):
+    """An ``ArgumentParser`` whose ``--help`` lists the full nested command set."""
+
+    def format_help(self) -> str:
+        # Drop the subparsers action from its body group so argparse's own
+        # one-level subcommand listing is omitted, while usage (built from
+        # self._actions) still shows the command placeholder. The full-path list
+        # below replaces the listing with the complete descendant set. The action
+        # is restored at its original index, so the mutation never leaks.
+        action = _subparsers_action(self)
+        removed: tuple[Any, int, argparse.Action] | None = None
+        if action is not None:
+            for group in self._action_groups:
+                if action in group._group_actions:
+                    idx = group._group_actions.index(action)
+                    group._group_actions.remove(action)
+                    removed = (group, idx, action)
+                    break
+        base = super().format_help()
+        if removed is not None:
+            group, idx, act = removed
+            group._group_actions.insert(idx, act)
+        tree = format_command_tree(self)
+        return f"{base}\n{tree}\n" if tree else base