cmpnd 0.49.0__tar.gz → 0.51.0__tar.gz

{cmpnd-0.49.0 → cmpnd-0.51.0}/PKG-INFO

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

{cmpnd-0.49.0 → cmpnd-0.51.0}/cmpnd/_http.py

@@ -234,23 +234,25 @@ class ApiClient:
             # which is the difference a user needs most and had the least of.
             raise error(server_detail(response) or "Resource not found.")
         if response.status_code >= 500:
-            # 5xx usually means the server is up but blew up handling the
-            # request — a database hiccup, an unhandled exception, etc.
-            # Include the response body excerpt so the user has something
-            # to act on. The actual exception lives in the operator's
-            # server logs, which we can't reach from here.
+            # 5xx means the cmpnd platform failed to handle the request — a
+            # database hiccup, an unhandled exception, a hop between its own
+            # services. A failure at something the user runs (their tool
+            # server, their provider) answers 4xx with a sentence naming it,
+            # so this hint names the platform and nothing of theirs. The cause
+            # lives in the platform's logs, which we can't reach from here.
             body_excerpt = (response.text or "").strip()[:200]
             msg = f"Server error ({response.status_code}) for {method} {path}"
             if body_excerpt:
                 msg += f": {body_excerpt}"
-            msg += "\n  If you operate this server, check its logs for the underlying exception."
+            msg += (
+                "\n  The cmpnd platform failed to handle this request. If you run this cmpnd "
+                "instance yourself, its logs hold the cause."
+            )
             raise error(msg, exit_code=2)
         if response.status_code >= 400:
-            try:
-                detail = response.json()
-            except Exception:
-                detail = response.text
-            raise error(f"Request failed ({response.status_code}): {detail}")
+            # The server's own sentence: a 4xx says what to change, and the
+            # JSON envelope around it is noise.
+            raise error(f"Request failed ({response.status_code}): {server_detail(response)}")
 
         if return_response:
             return response

{cmpnd-0.49.0 → cmpnd-0.51.0}/cmpnd/cli/__init__.py

@@ -88,6 +88,24 @@ Auth: set CMPND_API_KEY and (optionally) CMPND_ENDPOINT, or pass --api-key /
 """
 
 
+def parse(parser: argparse.ArgumentParser, argv: list[str]) -> argparse.Namespace:
+    """Parse ``argv``, and give a late positional the one word argparse could not place.
+
+    argparse fills optional positionals from the first run of bare words, so in
+    ``cmpnd deploy program.py --entrypoint qa capital-qa`` the program name comes too
+    late and is left over. A command that sets ``_late_positional`` takes one such
+    word into that argument when it is still empty. Anything else left over is the
+    usual usage error.
+    """
+    args, extras = parser.parse_known_args(argv)
+    late = getattr(args, "_late_positional", None)
+    if late and len(extras) == 1 and not extras[0].startswith("-") and getattr(args, late) is None:
+        setattr(args, late, extras.pop())
+    if extras:
+        parser.error("unrecognized arguments: " + " ".join(extras))
+    return args
+
+
 def main() -> None:
     parser = tree_help.TreeHelpParser(
         prog="cmpnd",
@@ -165,7 +183,7 @@ def main() -> None:
     # Top-level Docker-style shortcuts (human-readable by default; --json opts in)
     top.register(subparsers)
 
-    args = parser.parse_args()
+    args = parse(parser, sys.argv[1:])
 
     if not args.resource:
         # Bare `cmpnd` drops into an interactive Python shell with platform

{cmpnd-0.49.0 → cmpnd-0.51.0}/cmpnd/cli/commands/programs.py

@@ -21,15 +21,24 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
     create = sub.add_parser(
         "create",
-        help="Create a program and print its id",
+        help="Create a program with a name",
         description=(
-            "Ask the platform for a new program id (p_…) and print it on stdout. Declare it "
-            "with `cmpnd deploy --program-id`, `cmpnd.configure(program_id=...)` or "
-            "CMPND_PROGRAM_ID so deployments, traces and optimization runs carry it. Each "
-            "call creates a new program."
+            "Create a program with PROGRAM_NAME in your organization and print its id on stdout. "
+            "A program name that already has a program is refused. Deploy under the program name with "
+            "`cmpnd deploy SOURCE PROGRAM_NAME`, and declare it in Python with "
+            "cmpnd.Program(PROGRAM_NAME, module=..., lm=...). Without PROGRAM_NAME, --name creates an "
+            "unnamed program with a display name, as earlier releases did."
         ),
     )
-    create.add_argument("--name", default=None, help="Display name (need not be unique)")
+    create.add_argument(
+        "name", nargs="?", default=None, metavar="PROGRAM_NAME", help="Program name, unique in your organization"
+    )
+    create.add_argument(
+        "--name",
+        dest="display_name",
+        default=None,
+        help="Display name of an unnamed program (need not be unique)",
+    )
     create.add_argument("--json", action="store_true", help="Emit the created program as JSON instead of its id")
     create.set_defaults(func=handle_create)
 
@@ -88,11 +97,13 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
 def handle_create(client: api_client.ApiClient, args: Any) -> Any:
     """Create a program. Prints the bare id on stdout so a script can capture it
-    (``PROGRAM_ID=$(cmpnd programs create --name triage)``) and says what it made on
-    stderr; ``--json`` returns the whole row instead, printed like the group's reads."""
+    (``PROGRAM_ID=$(cmpnd programs create triage)``) and says what it made on stderr;
+    ``--json`` returns serve's whole answer instead, printed like the group's reads."""
     from ... import programs
 
-    row = programs.send_create(client, name=args.name)
+    if args.name is not None:
+        return _create_named(client, args)
+    row = programs.send_create(client, name=args.display_name)
     if getattr(args, "json", False):
         return row
     print(row["id"])
@@ -101,6 +112,36 @@ def handle_create(client: api_client.ApiClient, args: Any) -> Any:
     return None
 
 
+def _create_named(client: api_client.ApiClient, args: Any) -> Any:
+    """Create the program named ``args.name``, and refuse a name that already has one."""
+    from ... import programs
+    from . import top
+
+    if args.display_name is not None:
+        raise api_client.CliError("give a program name or --name, not both: --name is the older display name")
+    try:
+        answer = programs.send_resolve(client, args.name)
+    except ValueError as exc:
+        raise api_client.CliError(str(exc)) from exc
+    if answer is None:
+        raise api_client.CliError(
+            "This server has no program names, so it cannot create a program from a program name. A serve from "
+            "before program names, such as self-host release 2026-001, needs no program first: "
+            f"`{top._hint_program_name('deploy', source='SOURCE', name='PROGRAM_NAME')}` deploys there without "
+            "a program id."
+        )
+    if not answer.get("created"):
+        raise api_client.CliError(
+            f"the program name {args.name!r} already has a program, {answer['program_id']}. "
+            f"Deploy under it with `{top._hint_program_name('deploy', source='SOURCE', name=args.name)}`."
+        )
+    if getattr(args, "json", False):
+        return answer
+    print(answer["program_id"])
+    print(f"created program {answer['program_id']} named {args.name}", file=sys.stderr)
+    return None
+
+
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
     params: dict[str, str] = pagination.wire(args, "per_page", as_str=True)
     params["order_by"] = args.order_by

{cmpnd-0.49.0 → cmpnd-0.51.0}/cmpnd/cli/commands/top.py

@@ -194,6 +194,19 @@ def _hint_run(deployment_id: str, body: str = '{"...": "..."}') -> str:
     return f"cmpnd run {short} '{body}'"
 
 
+def _hint_program_name(verb: str, *, source: str | None = None, name: str = "capital-qa") -> str:
+    """How to name the program a deploy or optimize runs under, as this front-end spells it."""
+    if verb == "optimize":
+        source = source or "task.py"
+        if _SHELL_MODE:
+            return f'optimize("gepa", "{source}", program="{name}")'
+        return f"cmpnd optimize gepa {source} {name}"
+    source = source or "program.py"
+    if _SHELL_MODE:
+        return f'deploy("{source}", program="{name}")'
+    return f"cmpnd deploy {source} {name}"
+
+
 def _hint_status(deployment_id: str, follow: bool = False) -> str:
     short = _short_id(deployment_id)
     if _SHELL_MODE:
@@ -830,15 +843,49 @@ def _program_id_arg(value: str | None) -> str | None:
         raise api_client.CliError(str(exc)) from exc
 
 
+def _program_name_arg(value: str | None) -> str | None:
+    """The program name a deploy or optimize names, checked before a file is staged."""
+    if value is None:
+        return None
+    from ... import programs
+
+    try:
+        return programs.validate_program_name(value)
+    except ValueError as exc:
+        raise api_client.CliError(str(exc)) from exc
+
+
+def _program_args(args: Any, verb: str, *, needs_name: bool = True) -> tuple[str | None, str | None]:
+    """The program name and program id a deploy or optimize names, checked before a file is staged.
+
+    The name follows the source file. ``--program-id`` is the older input: it still
+    works, warns, and cannot be given with a name. A command with no name and no id
+    from either input warns that it will need a name, unless ``needs_name`` is false
+    because a deployment it reuses already names its program.
+    """
+    name = _program_name_arg(getattr(args, "program_name", None))
+    flag = getattr(args, "program_id", None)
+    example = _hint_program_name(verb)
+    id_input = "program_id=" if _SHELL_MODE else "--program-id"
+    if name is not None and flag is not None:
+        raise api_client.CliError(f"give a program name or {id_input}, not both")
+    if flag is not None:
+        print(f"warning: {id_input} is deprecated; give a program name instead, as in `{example}`.", file=sys.stderr)
+    program_id = _program_id_arg(flag)
+    if name is None and program_id is None and needs_name:
+        print(f"warning: this command has no program name; give one, as in `{example}`.", file=sys.stderr)
+    return name, program_id
+
+
 def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
     """Stage authored Python and deploy the checked bundle.
 
     A fresh child imports the staged bundle to inspect the declared entrypoint.
     The CLI process does not execute the file. ``--run '{json}'`` chains into
-    the new deployment as a one-shot smoke test. ``--program-id`` (or
-    ``CMPND_PROGRAM_ID``) names the program, from ``cmpnd programs create``:
+    the new deployment as a one-shot smoke test. The name after the source names the
+    program, which the platform makes the first time your organization uses the name:
 
-        cat <<'PY' | cmpnd deploy - --program-id p_0123456789Ab --run '{"question": "2+2?"}'
+        cat <<'PY' | cmpnd deploy - capital-qa --run '{"question": "2+2?"}'
         import dspy
         lm = dspy.LM("openai/gemma4:e4b", temperature=0.0, max_tokens=64)
         dspy.configure(lm=lm)
@@ -849,7 +896,7 @@ def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
 
     from ... import authored, configuration, deployment
 
-    program_id = _program_id_arg(getattr(args, "program_id", None))
+    program_name, program_id = _program_args(args, "deploy")
     configuration.configure(api_key=client._api_key, endpoint=client._endpoint, program_id=program_id)
     try:
         if args.source == "-" or args.source is None:
@@ -874,7 +921,9 @@ def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
     metadata = _parse_deploy_metadata(getattr(args, "metadata", None))
     print(_c("deploying…", "dim"), file=sys.stderr)
     try:
-        deployed = deployment.deploy_bundle(prepared.bundle, prepared.facts, metadata=metadata, program_id=program_id)
+        deployed = deployment.deploy_bundle(
+            prepared.bundle, prepared.facts, metadata=metadata, program_id=program_id, program_name=program_name
+        )
     except ValueError as exc:
         raise api_client.CliError(str(exc)) from exc
 
@@ -924,7 +973,7 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
     The file binds ``metric`` always, ``trainset`` and ``valset``, ``program`` unless
     ``--deployment-id`` names one, and ``proposer`` when the run brings its own::
 
-        cat <<'PY' | cmpnd optimize gepa - --program-id p_0123456789Ab --reflection-model openai/gpt-4o --auto light
+        cat <<'PY' | cmpnd optimize gepa - capital-qa --reflection-model openai/gpt-4o --auto light
         import dspy
         dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
         program = dspy.Predict("question -> answer")
@@ -941,7 +990,7 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
     from ... import authored, configuration, optimization
 
     deployment_id = getattr(args, "deployment_id", None)
-    program_id = _program_id_arg(getattr(args, "program_id", None))
+    program_name, program_id = _program_args(args, "optimize", needs_name=deployment_id is None)
     configuration.configure(api_key=client._api_key, endpoint=client._endpoint, program_id=program_id)
     try:
         if args.source == "-" or args.source is None:
@@ -972,6 +1021,7 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
             optimizer=args.optimizer,
             deployment_id=deployment_id,
             program_id=program_id,
+            program_name=program_name,
             # 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.
@@ -1089,6 +1139,26 @@ def cmd_run(client: api_client.ApiClient, args: Any) -> None:
 # --------------------------------------------------------------------------
 
 
+def _add_program_options(parser: ArgumentParser, role: str) -> None:
+    """The program name, a positional after the source, and the ``--program-id`` it replaces."""
+    parser.add_argument(
+        "program_name",
+        nargs="?",
+        metavar="PROGRAM_NAME",
+        default=None,
+        help=f"Program name {role}. The platform makes the program the first time "
+        "your organization uses the program name",
+    )
+    parser.add_argument(
+        "--program-id",
+        dest="program_id",
+        default=None,
+        help="Deprecated; give a program name instead. Program id (p_…), defaults to CMPND_PROGRAM_ID",
+    )
+    # argparse leaves a name given after other options unplaced; cli.parse places it.
+    parser.set_defaults(_late_positional="program_name")
+
+
 def _add_source_options(parser: ArgumentParser) -> None:
     """The two options that decide what a bundle holds, on every verb that stages one.
 
@@ -1247,20 +1317,13 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         ),
         epilog=(
             "Examples:\n"
-            "  cmpnd programs create --name qa   # prints the id to deploy under\n"
-            "  cmpnd deploy program.py --program-id p_0123456789Ab\n"
-            '  cmpnd deploy - --program-id p_0123456789Ab --run \'{"question":"2+2?"}\' < program.py\n'
+            "  cmpnd deploy program.py capital-qa\n"
+            '  cmpnd deploy - capital-qa --run \'{"question":"2+2?"}\' < program.py\n'
         ),
         formatter_class=raw,
     )
     dp.add_argument("source", nargs="?", help="Path to a .py file, or '-' to read stdin")
-    dp.add_argument(
-        "--program-id",
-        dest="program_id",
-        default=None,
-        help="Program id (p_…) the deployment belongs to, from `cmpnd programs create`. "
-        "Defaults to CMPND_PROGRAM_ID. Required by every serve after self-host release 2026-001",
-    )
+    _add_program_options(dp, "of the deployment")
     dp.add_argument(
         "--entrypoint",
         default="program",
@@ -1307,10 +1370,10 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         ),
         epilog=(
             "Examples:\n"
-            "  cmpnd optimize gepa task.py --program-id p_0123456789Ab --reflection-model openai/gpt-4o --auto light\n"
-            "  cmpnd optimize gepa task.py --program-id p_0123456789Ab --include judge.py "
+            "  cmpnd optimize gepa task.py capital-qa --reflection-model openai/gpt-4o --auto light\n"
+            "  cmpnd optimize gepa task.py capital-qa --include judge.py "
             "--reflection-model openai/gpt-4o --auto light\n"
-            "  cmpnd optimize gepa - --program-id p_0123456789Ab --reflection-model openai/gpt-4o "
+            "  cmpnd optimize gepa - capital-qa --reflection-model openai/gpt-4o "
             "--max-metric-calls 60 < task.py\n"
             "  cmpnd optimize gepa task.py --reflection-model openai/gpt-4o --auto light --deployment-id d_a1b2c3d4\n"
         ),
@@ -1339,14 +1402,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         default=None,
         help="Reuse an existing ready deployment as the starting program",
     )
-    opt.add_argument(
-        "--program-id",
-        dest="program_id",
-        default=None,
-        help="Program id (p_…) being optimized, from `cmpnd programs create`; defaults to "
-        "CMPND_PROGRAM_ID. Required by every serve after self-host release 2026-001 when "
-        "the file's program is deployed here, optional with --deployment-id",
-    )
+    _add_program_options(opt, "of the program to optimize")
     opt.add_argument(
         "--reflection-model",
         dest="reflection_model",

{cmpnd-0.49.0 → cmpnd-0.51.0}/cmpnd/cli/shell.py

@@ -486,12 +486,14 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
         source_root: str | None = None,
         include: list[str] | None = None,
         program_id: str | None = None,
+        program: str | None = None,
     ) -> Deployment:
         """Deploy authored Python from a file or ``"-"`` for stdin.
 
-        ``program_id`` (``p_…``, from ``cmpnd programs create``) names the program
-        the deployment belongs to; it defaults to ``CMPND_PROGRAM_ID``. serve
-        decides whether a deployment needs one. A fresh child imports the staged bundle. The shell
+        ``program`` names the program the deployment belongs to, which the platform
+        makes the first time your organization uses the name. ``program_id``
+        (``p_…``) is the older way to name it, and defaults to ``CMPND_PROGRAM_ID``.
+        A name wins over an id. A fresh child imports the staged bundle. The shell
         does not execute the file in its own process. Returns the
         new Deployment entity so you can chain ``.watch()`` / ``.run({...})``
         directly; also invalidates ``deps`` so the new deployment shows up
@@ -499,7 +501,9 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
         """
         from .. import authored, configuration, deployment
 
-        declared = commands.top._program_id_arg(program_id)
+        program_name, declared = commands.top._program_args(
+            _args(program_name=program, program_id=program_id), "deploy"
+        )
         configuration.configure(api_key=client._api_key, endpoint=client._endpoint, program_id=declared)
         if source in ("-", None):
             prepared = authored.prepare_stdin(
@@ -519,7 +523,9 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
             )
         sys.stderr.write(_c("deploying…\n", "dim"))
         sys.stderr.flush()
-        deployed = deployment.deploy_bundle(prepared.bundle, prepared.facts, program_id=declared)
+        deployed = deployment.deploy_bundle(
+            prepared.bundle, prepared.facts, program_id=declared, program_name=program_name
+        )
 
         record = client.get(f"/api/v1/deployments/{deployed.deployment_id}")
         deps.refresh()  # new deployment becomes visible in the registry
@@ -536,6 +542,7 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
         patience: int = 2,
         seed: int = 0,
         program_id: str | None = None,
+        program: str | None = None,
     ) -> Any:
         """Optimize a DSPy program: ``optimize("gepa", "task.py")``.
 
@@ -546,7 +553,8 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
         than executed here, so what scores the run is the file's own bytes. ``include``
         adds the siblings it imports and the files it reads. Returns the best
         ``DeployedProgram`` (call it directly; ``.score`` is the best score found);
-        ``deps`` is refreshed so the result deployment shows up.
+        ``deps`` is refreshed so the result deployment shows up. The ``program``
+        argument names the program being optimized, as ``deploy`` takes it.
         """
         result = commands.top.cmd_optimize(
             client,
@@ -555,6 +563,7 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
                 optimizer=optimizer,
                 deployment_id=deployment_id,
                 program_id=program_id,
+                program_name=program,
                 reflection_model=reflection_model,
                 source_root=source_root,
                 include=list(include or []),

{cmpnd-0.49.0 → cmpnd-0.51.0}/cmpnd/deployment.py

@@ -26,6 +26,7 @@ from . import (
     mcp_servers,
     models,
     packaging,
+    programs,
     retry,
 )
 
@@ -92,8 +93,8 @@ def _raise_http_error(response: httpx.Response, action: str) -> None:
     """Convert an HTTP error response into an actionable RuntimeError.
 
     Replaces ``response.raise_for_status()`` so callers see a useful
-    message instead of a raw httpx traceback. 5xx points the user at
-    server logs and the local-dev preflight; 4xx surfaces the response
+    message instead of a raw httpx traceback. 5xx says the platform
+    failed and points a self-hosting operator at its logs; 4xx surfaces the response
     body so e.g. ``{"error": "Invalid 'since' timestamp"}`` round-trips
     to the terminal.
     """
@@ -105,8 +106,8 @@ def _raise_http_error(response: httpx.Response, action: str) -> None:
         if body:
             msg += f"\n  Body: {body}"
         msg += (
-            "\n  The server reached, but errored handling the request. "
-            "If you operate it, check its logs for the underlying exception."
+            "\n  The cmpnd platform failed to handle this request. "
+            "If you run this cmpnd instance yourself, its logs hold the cause."
         )
     else:
         msg = f"Failed to {action}: HTTP {response.status_code}"
@@ -356,8 +357,8 @@ def _resolve_mcp_tool_references(client: httpx.Client, config, references: list[
 
 
 MISSING_PROGRAM_ID = (
-    "this server requires a program id: pass program_id= (`cmpnd deploy --program-id`), or set "
-    "cmpnd.configure(program_id=...) or CMPND_PROGRAM_ID. Create one with `cmpnd programs create`."
+    "this server requires a program name: give one after the source, as in `cmpnd deploy SOURCE PROGRAM_NAME`, or "
+    "deploy a cmpnd.Program(PROGRAM_NAME, module=..., lm=...) with cmpnd.deploy()."
 )
 
 # The error serve answers, with a 400, to a create that names no program. A serve
@@ -376,6 +377,55 @@ def declared_program_id(explicit: str | None, config: configuration.Config) -> s
     return identity.validate_program_id(chosen) if chosen is not None else None
 
 
+def program_for(program_id: str | None, program_name: str | None, config: configuration.Config) -> str | None:
+    """The program a deployment is created under, when the caller may name it by name or id.
+
+    A name wins over an explicit or configured id, and the SDK warns that the id is
+    not used. The name resolves to its program id with ``PUT``, which makes the program
+    the first time the organization uses the name. On a server with no program names,
+    the deployment goes without an id, and the SDK warns.
+    """
+    if program_name is None:
+        return declared_program_id(program_id, config)
+    programs.validate_program_name(program_name)
+    unused = program_id if program_id is not None else config.program_id
+    if unused is not None:
+        logger.warning("cmpnd: the deploy uses program name %r, and program id %s is not used.", program_name, unused)
+    return _program_by_name(program_name, config)
+
+
+def _program_by_name(name: str, config: configuration.Config) -> str | None:
+    """The program id serve gives ``name``, or None when the server has no program names."""
+    answer = programs.send_resolve(_http.ApiClient(config.api_key, config.endpoint), name)
+    if answer is None:
+        logger.warning(
+            "cmpnd: program name %r is not used: the server has no program names, so the deploy has no program id.",
+            name,
+        )
+        return None
+    return answer["program_id"]
+
+
+def _program_module(program: Any) -> Any:
+    """The module a program deploys: the module inside it, and inside each program it holds.
+
+    A program that overrides ``forward`` runs its own code around its module, and
+    packaging cannot rebuild that code yet, so it is refused.
+    """
+    from . import named_programs
+
+    module = program
+    while isinstance(module, named_programs.Program):
+        if named_programs.runs_itself(module):
+            raise ValueError(
+                f"{type(module).__name__} overrides forward, and deploying a cmpnd.Program that runs its own "
+                "code is not supported yet. Move that code into a dspy.Module, and deploy a cmpnd.Program "
+                "that holds it."
+            )
+        module = module.module
+    return module
+
+
 def _refused_for_missing_program_id(response: httpx.Response, deploy_body: dict[str, Any]) -> bool:
     """Whether serve refused a create that named no program because it needs one."""
     if response.status_code != 400 or "program_id" in deploy_body:
@@ -393,8 +443,14 @@ def deploy(module, metric=None, timeout=300, metadata=None, *, program_id=None):
     Packages the module into a source ZIP, uploads it through the platform API to the
     deploy stack, and polls until the program is parsed and ready.
 
+    A ``cmpnd.Program`` deploys its module under the program's name and on the
+    program's LM. The name resolves to its program id, which the platform makes the
+    first time your organization uses the name. A predictor with its own LM keeps it,
+    and the deployment's model is the LM the packaged source names.
+
     Args:
-        module: A DSPy module (e.g. dspy.Predict, dspy.ChainOfThought).
+        module: A DSPy module (e.g. dspy.Predict, dspy.ChainOfThought), or a
+            ``cmpnd.Program``.
         metric: Optional metric callable for optimization support.
         timeout: Seconds to wait for the program to become ready (default 300),
             measured from the moment the upload completes. A transient blip
@@ -415,7 +471,8 @@ def deploy(module, metric=None, timeout=300, metadata=None, *, program_id=None):
             id (``cmpnd.configure(program_id=...)`` or ``CMPND_PROGRAM_ID``) is
             used. With neither, the create names no program, and serve decides:
             every serve with program ids refuses it, and a serve from before
-            them, such as self-host release 2026-001, accepts it.
+            them, such as self-host release 2026-001, accepts it. A
+            ``cmpnd.Program``'s name wins over this id.
 
     Returns:
         A DeployedProgram that can be called with the same inputs as the
@@ -428,8 +485,29 @@ def deploy(module, metric=None, timeout=300, metadata=None, *, program_id=None):
         TimeoutError: If the program isn't ready within timeout seconds.
     """
     config = configuration.require_config()
-    program = declared_program_id(program_id, config)
+    from . import named_programs
+
+    if not isinstance(module, named_programs.Program):
+        return _deploy_module(module, metric, timeout, metadata, declared_program_id(program_id, config), config)
+    inner = _program_module(module)
+    program = program_for(program_id, module.name, config)
+    import dspy
+
+    # Applied the same way the program applies it when it runs, so a nested program's
+    # LM is not used, and a predictor's own LM is.
+    with dspy.context(lm=module.lm, **{named_programs.PROGRAM_LM_SETTING: module.lm}):
+        return _deploy_module(inner, metric, timeout, metadata, program, config)
 
+
+def _deploy_module(
+    module: Any,
+    metric: Any,
+    timeout: float,
+    metadata: Any,
+    program: str | None,
+    config: configuration.Config,
+) -> execution.DeployedProgram:
+    """Package and deploy a live module under ``program``, which the caller already chose."""
     # Resolve the program's MCP tool references against the org's registry, before
     # anything is packaged and before a deployment row exists. A program with no MCP
     # tools asks the registry nothing.
@@ -499,9 +577,8 @@ def deploy(module, metric=None, timeout=300, metadata=None, *, program_id=None):
     # the LM explicitly and so rides this same path; raw AWS creds never do.
     # When no key is forwardable, the server decides whether it can resolve a
     # provider and fails the deploy loudly if not — we do not guess here.
-    import dspy
-
-    lm = dspy.settings.lm
+    # The same LM the packaged source names: a predictor's own LM, else the context's.
+    lm = packaging._extract_lm_object(module)
     if lm is not None:
         if getattr(lm, "model", None):
             deploy_body["litellm_model"] = lm.model
@@ -522,14 +599,33 @@ def deploy_bundle(
     metadata: Any = None,
     *,
     program_id: str | None = None,
+    program_name: str | None = None,
 ) -> execution.DeployedProgram:
     """Upload a checked authored-source bundle without packaging a live module.
 
     ``program_id`` works as it does for :func:`deploy`: the explicit id, else the
     configured one, else none, and serve decides whether a deployment needs one.
+    ``program_name`` names the program instead, and wins over both ids.
+    """
+    config = configuration.require_config()
+    return deploy_bundle_under(
+        zip_bytes, facts, program_for(program_id, program_name, config), timeout=timeout, metadata=metadata
+    )
+
+
+def deploy_bundle_under(
+    zip_bytes: bytes,
+    facts: authored.ProgramFacts,
+    program: str | None,
+    *,
+    timeout: float = 300,
+    metadata: Any = None,
+) -> execution.DeployedProgram:
+    """Upload a checked bundle under ``program``, which the caller already chose.
+
+    None deploys without a program id, with no fallback to the configured one.
     """
     config = configuration.require_config()
-    program = declared_program_id(program_id, config)
     deploy_body = facts.deploy_body()
     if program is not None:
         deploy_body["program_id"] = program