cmpnd 0.51.0__tar.gz → 0.52.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.51.0
+Version: 0.52.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -88,7 +88,6 @@ no arguments. The endpoint defaults to `https://platform.cmpnd.ai`.
 ```bash
 export CMPND_API_KEY="ck_your_api_key"
 export CMPND_ENDPOINT="https://platform.cmpnd.ai"  # optional
-export CMPND_PROGRAM_ID="p_0123456789Ab"            # optional: the program these traces belong to
 ```
 
 ```python
@@ -96,7 +95,6 @@ cmpnd.configure(
     api_key="ck_xxx",                      # required, or CMPND_API_KEY
     endpoint="https://platform.cmpnd.ai",  # optional, or CMPND_ENDPOINT
     project_tags="my-project",             # optional: one tag or a list of tags
-    program_id="p_0123456789Ab",           # optional, or CMPND_PROGRAM_ID: the id `cmpnd programs create` prints
     batch_size=100,                        # optional: spans per export batch
     flush_interval_seconds=5.0,            # optional: seconds between flushes
     capture_inputs=True,                   # optional: record span inputs
@@ -111,24 +109,18 @@ captured input and output size limits, 65,536 bytes each by default.
 
 ## Deployment
 
-Every deployment belongs to a program, and the platform issues each program
-an id. Create a program first. The command prints its id:
-
-```bash
-cmpnd programs create --name qa
-```
-
-Then deploy a DSPy module under that program for server-side execution:
+Every deployment belongs to a program, and each program has a program name.
+Give a DSPy module a program name with `cmpnd.Program`, then deploy it for
+server-side execution:
 
 ```python
 import cmpnd
 import dspy
 
-cmpnd.configure(api_key="ck_xxx", program_id="p_0123456789Ab")
-dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
+cmpnd.configure(api_key="ck_xxx")
 
-module = dspy.Predict("question -> answer")
-deployed = cmpnd.deploy(module)
+qa = cmpnd.Program("qa", module=dspy.Predict("question -> answer"), lm=dspy.LM("openai/gpt-6-luna"))
+deployed = cmpnd.deploy(qa)
 
 result = deployed(question="What is DSPy?")  # runs server-side
 print(result.answer)
@@ -143,26 +135,26 @@ when the platform has inspected it. An unknown interface leaves `input_fields`
 and `output_fields` as `None`. A known interface with no fields returns empty
 lists.
 
-`cmpnd.deploy(module, program_id="p_…")` names the program for one call.
-Without a configured or passed id, `deploy` raises `ValueError` before it
-packages or sends anything.
+The platform makes the program the first time your organization uses the
+program name. Later deploys under the same program name go to the same
+program. `@cmpnd.program("qa")` above a `dspy.Module`
+class declares the same program name. [`docs/client.md`](docs/client.md)
+describes both forms.
 
-To deploy a source file, run `cmpnd deploy program.py --program-id p_…`, or
-set `CMPND_PROGRAM_ID`. The CLI uploads the file's exact bytes and does not
-reconstruct the source from a live object. Use `--source-root` and repeated
-`--include` flags for sibling modules or data, and `cmpnd inspect <id>
---source` to read the deployed entry file back. [`docs/cli.md`](docs/cli.md)
-covers the CLI.
+To deploy a source file, run `cmpnd deploy program.py qa`. The CLI uploads
+the file's exact bytes and does not reconstruct the source from a live object.
+Use `--source-root` and repeated `--include` flags for sibling modules or
+data, and `cmpnd inspect <id> --source` to read the deployed entry file back.
+[`docs/cli.md`](docs/cli.md) covers the CLI.
 
 ### Options
 
 ```python
 cmpnd.deploy(
-    module,            # required: a DSPy module
+    program,           # required: a cmpnd.Program
     metric=None,       # optional: a metric callable, packaged for optimization
     timeout=300,       # optional: seconds to wait for the parser after the upload
     metadata=None,     # optional: a JSON-serializable dict, at most 64 KiB, stored with the deployment
-    program_id="p_…",  # the program the deployment belongs to; serve requires it after self-host 2026-001
 )
 ```
 
@@ -190,10 +182,9 @@ it returns a `DeployedProgram` that you call directly, and the program's
 import cmpnd
 import dspy
 
-cmpnd.configure(api_key="ck_xxx", program_id="p_0123456789Ab")  # from `cmpnd programs create`
-dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
+cmpnd.configure(api_key="ck_xxx")
 
-program = dspy.ChainOfThought("topic -> haiku")
+program = cmpnd.Program("haiku", module=dspy.ChainOfThought("topic -> haiku"), lm=dspy.LM("openai/gpt-6-luna"))
 
 # GEPA needs a five-argument feedback metric that returns dspy.Prediction(score=, feedback=)
 def metric(example, pred, trace=None, pred_name=None, pred_trace=None):
@@ -327,13 +318,13 @@ raises `cmpnd.OptimizeFailed` when a step reaches `failed`.
 ### From the CLI
 
 ```bash
-cmpnd optimize gepa task.py --program-id p_0123456789Ab --reflection-model openai/gpt-6-luna --auto light
+cmpnd optimize gepa task.py haiku --reflection-model openai/gpt-6-luna --auto light
 ```
 
 The file, or `-` for stdin, binds `program`, `trainset`, `valset` and
 `metric`. The CLI prints the best deployment ID. The CLI deploys the file's
-program first, so it needs `--program-id` or `CMPND_PROGRAM_ID`. With
-`--deployment-id`, the program id is optional.
+program first under the program name, here `haiku`. With `--deployment-id`,
+the CLI starts from that deployment and needs no program name.
 
 ## Custom spans
 
@@ -403,8 +394,8 @@ dspy.configure(callbacks=[cmpnd.CmpndCallback()])
 
 ### `cmpnd.deploy()`
 
-Deploys a DSPy module under a program id and returns a callable
-`DeployedProgram`. It uses `program_id=`, else the configured id.
+Deploys a `cmpnd.Program` under its program name and returns a callable
+`DeployedProgram`.
 
 ### `cmpnd.optimize()`
 

{cmpnd-0.51.0 → cmpnd-0.52.0}/README.md

@@ -37,7 +37,6 @@ no arguments. The endpoint defaults to `https://platform.cmpnd.ai`.
 ```bash
 export CMPND_API_KEY="ck_your_api_key"
 export CMPND_ENDPOINT="https://platform.cmpnd.ai"  # optional
-export CMPND_PROGRAM_ID="p_0123456789Ab"            # optional: the program these traces belong to
 ```
 
 ```python
@@ -45,7 +44,6 @@ cmpnd.configure(
     api_key="ck_xxx",                      # required, or CMPND_API_KEY
     endpoint="https://platform.cmpnd.ai",  # optional, or CMPND_ENDPOINT
     project_tags="my-project",             # optional: one tag or a list of tags
-    program_id="p_0123456789Ab",           # optional, or CMPND_PROGRAM_ID: the id `cmpnd programs create` prints
     batch_size=100,                        # optional: spans per export batch
     flush_interval_seconds=5.0,            # optional: seconds between flushes
     capture_inputs=True,                   # optional: record span inputs
@@ -60,24 +58,18 @@ captured input and output size limits, 65,536 bytes each by default.
 
 ## Deployment
 
-Every deployment belongs to a program, and the platform issues each program
-an id. Create a program first. The command prints its id:
-
-```bash
-cmpnd programs create --name qa
-```
-
-Then deploy a DSPy module under that program for server-side execution:
+Every deployment belongs to a program, and each program has a program name.
+Give a DSPy module a program name with `cmpnd.Program`, then deploy it for
+server-side execution:
 
 ```python
 import cmpnd
 import dspy
 
-cmpnd.configure(api_key="ck_xxx", program_id="p_0123456789Ab")
-dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
+cmpnd.configure(api_key="ck_xxx")
 
-module = dspy.Predict("question -> answer")
-deployed = cmpnd.deploy(module)
+qa = cmpnd.Program("qa", module=dspy.Predict("question -> answer"), lm=dspy.LM("openai/gpt-6-luna"))
+deployed = cmpnd.deploy(qa)
 
 result = deployed(question="What is DSPy?")  # runs server-side
 print(result.answer)
@@ -92,26 +84,26 @@ when the platform has inspected it. An unknown interface leaves `input_fields`
 and `output_fields` as `None`. A known interface with no fields returns empty
 lists.
 
-`cmpnd.deploy(module, program_id="p_…")` names the program for one call.
-Without a configured or passed id, `deploy` raises `ValueError` before it
-packages or sends anything.
+The platform makes the program the first time your organization uses the
+program name. Later deploys under the same program name go to the same
+program. `@cmpnd.program("qa")` above a `dspy.Module`
+class declares the same program name. [`docs/client.md`](docs/client.md)
+describes both forms.
 
-To deploy a source file, run `cmpnd deploy program.py --program-id p_…`, or
-set `CMPND_PROGRAM_ID`. The CLI uploads the file's exact bytes and does not
-reconstruct the source from a live object. Use `--source-root` and repeated
-`--include` flags for sibling modules or data, and `cmpnd inspect <id>
---source` to read the deployed entry file back. [`docs/cli.md`](docs/cli.md)
-covers the CLI.
+To deploy a source file, run `cmpnd deploy program.py qa`. The CLI uploads
+the file's exact bytes and does not reconstruct the source from a live object.
+Use `--source-root` and repeated `--include` flags for sibling modules or
+data, and `cmpnd inspect <id> --source` to read the deployed entry file back.
+[`docs/cli.md`](docs/cli.md) covers the CLI.
 
 ### Options
 
 ```python
 cmpnd.deploy(
-    module,            # required: a DSPy module
+    program,           # required: a cmpnd.Program
     metric=None,       # optional: a metric callable, packaged for optimization
     timeout=300,       # optional: seconds to wait for the parser after the upload
     metadata=None,     # optional: a JSON-serializable dict, at most 64 KiB, stored with the deployment
-    program_id="p_…",  # the program the deployment belongs to; serve requires it after self-host 2026-001
 )
 ```
 
@@ -139,10 +131,9 @@ it returns a `DeployedProgram` that you call directly, and the program's
 import cmpnd
 import dspy
 
-cmpnd.configure(api_key="ck_xxx", program_id="p_0123456789Ab")  # from `cmpnd programs create`
-dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
+cmpnd.configure(api_key="ck_xxx")
 
-program = dspy.ChainOfThought("topic -> haiku")
+program = cmpnd.Program("haiku", module=dspy.ChainOfThought("topic -> haiku"), lm=dspy.LM("openai/gpt-6-luna"))
 
 # GEPA needs a five-argument feedback metric that returns dspy.Prediction(score=, feedback=)
 def metric(example, pred, trace=None, pred_name=None, pred_trace=None):
@@ -276,13 +267,13 @@ raises `cmpnd.OptimizeFailed` when a step reaches `failed`.
 ### From the CLI
 
 ```bash
-cmpnd optimize gepa task.py --program-id p_0123456789Ab --reflection-model openai/gpt-6-luna --auto light
+cmpnd optimize gepa task.py haiku --reflection-model openai/gpt-6-luna --auto light
 ```
 
 The file, or `-` for stdin, binds `program`, `trainset`, `valset` and
 `metric`. The CLI prints the best deployment ID. The CLI deploys the file's
-program first, so it needs `--program-id` or `CMPND_PROGRAM_ID`. With
-`--deployment-id`, the program id is optional.
+program first under the program name, here `haiku`. With `--deployment-id`,
+the CLI starts from that deployment and needs no program name.
 
 ## Custom spans
 
@@ -352,8 +343,8 @@ dspy.configure(callbacks=[cmpnd.CmpndCallback()])
 
 ### `cmpnd.deploy()`
 
-Deploys a DSPy module under a program id and returns a callable
-`DeployedProgram`. It uses `program_id=`, else the configured id.
+Deploys a `cmpnd.Program` under its program name and returns a callable
+`DeployedProgram`.
 
 ### `cmpnd.optimize()`
 

{cmpnd-0.51.0 → cmpnd-0.52.0}/cmpnd/callback.py

@@ -651,6 +651,15 @@ class _CallbackBase:
         self._last_eval_trace_ids.clear()
         self._unclaimed_eval_trace_ids.clear()
 
+    @property
+    def traces_globally(self) -> bool:
+        """Whether this is the ``auto_instrument()`` callback, which reads the global config.
+
+        A client's callback has its own config. The global callback records sketch
+        mode, which declares no program names.
+        """
+        return self._own_config is None
+
     def _resolve_project_tags(self) -> list[str] | None:
         """The project tags this callback stamps on the builders it creates.
 

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

@@ -61,8 +61,7 @@ class _LazyVersionAction(argparse.Action):
 _EPILOG = """\
 deploy-flow workflow (Docker-style; the path an agent should reach for first):
 
-  cmpnd programs create --name qa                       # mint a program id (p_…), once
-  cmpnd deploy program.py --program-id p_… --run '{"question": "..."}'   # deploy + smoke test
+  cmpnd deploy program.py qa --run '{"question": "..."}'   # deploy program name qa + smoke test
   cmpnd ps                                              # list deployments
   cmpnd status <id> -f                                  # wait for terminal state
   cmpnd run <id> '{"...": "..."}'                       # invoke a ready deployment

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import argparse
 import sys
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
@@ -23,21 +24,22 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         "create",
         help="Create a program with a name",
         description=(
-            "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 a program with PROGRAM_NAME in your organization. A program name that already "
+            "has a program is refused. A deploy makes the program the first time it uses the program "
+            "name, so this command is needed only to make the program first. Deploy under the program "
+            "name with `cmpnd deploy SOURCE PROGRAM_NAME`, and declare it in Python with "
+            "cmpnd.Program(PROGRAM_NAME, module=..., lm=...)."
         ),
     )
     create.add_argument(
         "name", nargs="?", default=None, metavar="PROGRAM_NAME", help="Program name, unique in your organization"
     )
+    # Deprecated program id input: --name, the display name of an unnamed program, goes when it is removed.
     create.add_argument(
         "--name",
         dest="display_name",
         default=None,
-        help="Display name of an unnamed program (need not be unique)",
+        help=argparse.SUPPRESS,
     )
     create.add_argument("--json", action="store_true", help="Emit the created program as JSON instead of its id")
     create.set_defaults(func=handle_create)
@@ -96,13 +98,19 @@ 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 triage)``) and says what it made on stderr;
-    ``--json`` returns serve's whole answer instead, printed like the group's reads."""
+    """Create a program. Prints the bare id on stdout and says what it made on stderr;
+    ``--json`` returns serve's whole answer instead, printed like the group's reads.
+
+    The form without a program name, with or without ``--name``, makes an unnamed
+    program. It is deprecated, and warns."""
     from ... import programs
 
     if args.name is not None:
         return _create_named(client, args)
+    # Deprecated program id input: a create without a program name, and this warning, go when it is removed.
+    from . import top
+
+    top.warn_program_id_input("`cmpnd programs create` without a program name", top.hint_programs_create())
     row = programs.send_create(client, name=args.display_name)
     if getattr(args, "json", False):
         return row

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

@@ -7,6 +7,7 @@ client-side deployment-id prefix resolution.
 
 from __future__ import annotations
 
+import argparse
 import json
 import os
 import sys
@@ -207,6 +208,11 @@ def _hint_program_name(verb: str, *, source: str | None = None, name: str = "cap
     return f"cmpnd deploy {source} {name}"
 
 
+def hint_programs_create(name: str = "capital-qa") -> str:
+    """How to create a program with a program name. The shell has no programs verb, so this is the CLI form."""
+    return f"cmpnd programs create {name}"
+
+
 def _hint_status(deployment_id: str, follow: bool = False) -> str:
     short = _short_id(deployment_id)
     if _SHELL_MODE:
@@ -823,6 +829,17 @@ def _parse_deploy_metadata(raw: str | None) -> dict[str, Any] | None:
         raise api_client.CliError(f"--metadata is invalid: {exc}")
 
 
+# Deprecated program id input: the CLI's warning for every one of them, which goes when they are removed.
+def warn_program_id_input(source: str, example: str) -> None:
+    """Print that the program id input ``source`` is deprecated, and show the program name form.
+
+    The CLI prints its warnings on stderr. A ``FutureWarning`` here would name a file and
+    line inside the SDK, which tells a command-line user nothing.
+    """
+    print(f"warning: {source} is deprecated; give a program name instead, as in `{example}`.", file=sys.stderr)
+
+
+# Deprecated program id input: --program-id and CMPND_PROGRAM_ID on a deploy or optimize.
 def _program_id_arg(value: str | None) -> str | None:
     """The program id a deploy or optimize names: ``--program-id``, else ``CMPND_PROGRAM_ID``.
 
@@ -858,10 +875,13 @@ def _program_name_arg(value: str | None) -> str | None:
 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.
+    The name follows the source file. ``--program-id`` and ``CMPND_PROGRAM_ID`` are the
+    deprecated inputs: they still work and warn, and ``--program-id`` cannot be given
+    with a name. A name wins over ``CMPND_PROGRAM_ID``, and the deploy says the id is not
+    used. 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. The CLI never runs inside a worker, so ``CMPND_PROGRAM_ID`` here is a
+    user's input, not a worker's.
     """
     name = _program_name_arg(getattr(args, "program_name", None))
     flag = getattr(args, "program_id", None)
@@ -869,8 +889,11 @@ def _program_args(args: Any, verb: str, *, needs_name: bool = True) -> tuple[str
     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")
+    # Deprecated program id input: both warnings go when the id inputs are removed.
     if flag is not None:
-        print(f"warning: {id_input} is deprecated; give a program name instead, as in `{example}`.", file=sys.stderr)
+        warn_program_id_input(id_input, example)
+    elif name is None and os.environ.get("CMPND_PROGRAM_ID"):
+        warn_program_id_input("CMPND_PROGRAM_ID", example)
     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)
@@ -897,7 +920,7 @@ def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
     from ... import authored, configuration, deployment
 
     program_name, program_id = _program_args(args, "deploy")
-    configuration.configure(api_key=client._api_key, endpoint=client._endpoint, program_id=program_id)
+    configuration._configure(client._api_key, client._endpoint, None, program_id)
     try:
         if args.source == "-" or args.source is None:
             prepared = authored.prepare_stdin(
@@ -991,7 +1014,7 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
 
     deployment_id = getattr(args, "deployment_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)
+    configuration._configure(client._api_key, client._endpoint, None, program_id)
     try:
         if args.source == "-" or args.source is None:
             prepared = authored.prepare_optimize_stdin(
@@ -1149,11 +1172,13 @@ def _add_program_options(parser: ArgumentParser, role: str) -> None:
         help=f"Program name {role}. The platform makes the program the first time "
         "your organization uses the program name",
     )
+    # Deprecated program id input: --program-id goes when it is removed.
     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",
+        # Hidden so that help shows program names only.
+        help=argparse.SUPPRESS,
     )
     # argparse leaves a name given after other options unplaced; cli.parse places it.
     parser.set_defaults(_late_positional="program_name")

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

@@ -485,15 +485,14 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
         entrypoint: str = "program",
         source_root: str | None = None,
         include: list[str] | None = None,
-        program_id: str | None = None,
+        program_id: str | None = None,  # Deprecated program id input: goes when it is removed.
         program: str | None = None,
     ) -> Deployment:
         """Deploy authored Python from a file or ``"-"`` for stdin.
 
-        ``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
+        ``program`` is the program name of the deployment. The platform makes the
+        program the first time your organization uses the program name. 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
@@ -504,7 +503,7 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
         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)
+        configuration._configure(client._api_key, client._endpoint, None, declared)
         if source in ("-", None):
             prepared = authored.prepare_stdin(
                 sys.stdin.buffer.read(),
@@ -541,7 +540,7 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
         max_steps: int = 10,
         patience: int = 2,
         seed: int = 0,
-        program_id: str | None = None,
+        program_id: str | None = None,  # Deprecated program id input: goes when it is removed.
         program: str | None = None,
     ) -> Any:
         """Optimize a DSPy program: ``optimize("gepa", "task.py")``.
@@ -553,8 +552,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. The ``program``
-        argument names the program being optimized, as ``deploy`` takes it.
+        ``deps`` is refreshed so the result deployment shows up. ``program`` is the
+        program name of the program being optimized, as ``deploy`` takes it.
         """
         result = commands.top.cmd_optimize(
             client,