cmpnd 0.50.0__tar.gz → 0.52.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.50.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.50.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.50.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.50.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
@@ -88,6 +87,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 +182,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.50.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
@@ -21,15 +22,25 @@ 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. 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", 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"
+    )
+    # 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=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)
 
@@ -87,12 +98,20 @@ 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."""
+    """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
 
-    row = programs.send_create(client, name=args.name)
+    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
     print(row["id"])
@@ -101,6 +120,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