cmpnd 0.40.0__tar.gz → 0.41.0__tar.gz

{cmpnd-0.40.0 → cmpnd-0.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.40.0
+Version: 0.41.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: dspy>=3.1.3
@@ -27,8 +28,10 @@ Requires-Dist: xxhash>=3.0.0
 Provides-Extra: dev
 Requires-Dist: basedpyright>=1.39; extra == 'dev'
 Requires-Dist: boto3>=1.34; extra == 'dev'
+Requires-Dist: gepa; extra == 'dev'
 Requires-Dist: hypothesis>=6.100; extra == 'dev'
 Requires-Dist: jsonschema>=4.0; extra == 'dev'
+Requires-Dist: litellm; extra == 'dev'
 Requires-Dist: numpy>=1.26; (python_version < '3.11') and extra == 'dev'
 Requires-Dist: numpy>=2.3; (python_version >= '3.11') and extra == 'dev'
 Requires-Dist: pandas>=2.2; extra == 'dev'
@@ -161,7 +164,7 @@ cmpnd.deploy(
     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_…",  # required unless configured: the program the deployment belongs to
+    program_id="p_…",  # the program the deployment belongs to; serve requires it after self-host 2026-001
 )
 ```
 

{cmpnd-0.40.0 → cmpnd-0.41.0}/README.md

@@ -111,7 +111,7 @@ cmpnd.deploy(
     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_…",  # required unless configured: the program the deployment belongs to
+    program_id="p_…",  # the program the deployment belongs to; serve requires it after self-host 2026-001
 )
 ```
 

{cmpnd-0.40.0 → cmpnd-0.41.0}/cmpnd/callback.py

@@ -1949,6 +1949,14 @@ class _ToolMixin(_CallbackBase):
                 exp.export_span(span)
 
 
+# The variable DSPy (3.4.1 and later) hands the interpreter when RLM installs its
+# sandboxed `dspy` stand-in, as `dspy.primitives.facade.HOST_TOKEN_VAR`. That setup runs
+# as the session's first cell on every forward, and it is DSPy's machinery rather than a
+# step the program took, so it records no span. Spelled out rather than imported because
+# older DSPy has no such module.
+SANDBOX_SETUP_VARIABLE = "__dspy_host_token"
+
+
 class _InterpreterMixin(_CallbackBase):
     """DSPy CodeInterpreter callbacks — one span per REPL code execution.
 
@@ -1975,6 +1983,9 @@ class _InterpreterMixin(_CallbackBase):
         # has no span to attach to and no trace to root, so drop it.
         if context.get_current_trace() is None and context.get_current_span() is None:
             return
+        variables = inputs.get("variables")
+        if isinstance(variables, dict) and SANDBOX_SETUP_VARIABLE in variables:
+            return
 
         span = self._new_span(f"{instance.__class__.__name__}.execute", models.SpanType.INTERPRETER_EXECUTE)
 

{cmpnd-0.40.0 → cmpnd-0.41.0}/cmpnd/cli/commands/top.py

@@ -811,11 +811,12 @@ def _parse_deploy_metadata(raw: str | None) -> dict[str, Any] | None:
         raise api_client.CliError(f"--metadata is invalid: {exc}")
 
 
-def _program_id_arg(value: str | None, *, required: bool) -> str | None:
+def _program_id_arg(value: str | None) -> str | None:
     """The program id a deploy or optimize names: ``--program-id``, else ``CMPND_PROGRAM_ID``.
 
-    Checked here, before a file is staged, so a missing or mistyped id is a usage
-    error naming the flag rather than a refusal after work was done.
+    Checked here, before a file is staged, so a mistyped id is a usage error naming
+    its source rather than a refusal after work was done. serve decides whether a
+    deployment needs an id, so a missing one is not refused here.
     """
     from ... import identity
 
@@ -823,12 +824,6 @@ def _program_id_arg(value: str | None, *, required: bool) -> str | None:
     if value is None and os.environ.get("CMPND_PROGRAM_ID"):
         value, source = os.environ["CMPND_PROGRAM_ID"], "CMPND_PROGRAM_ID"
     if value is None:
-        if required:
-            raise api_client.CliError(
-                "--program-id is required: a deployment always names its program. "
-                "Create one with `cmpnd programs create`, then pass --program-id p_… "
-                "(or set CMPND_PROGRAM_ID)."
-            )
         return None
     try:
         return identity.validate_program_id(value, source=source)
@@ -855,9 +850,7 @@ def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
 
     from ... import authored, configuration, deployment
 
-    # Refused before the file is staged or anything is sent: a deployment always
-    # names its program, and the server would refuse the create anyway.
-    program_id = _program_id_arg(getattr(args, "program_id", None), required=True)
+    program_id = _program_id_arg(getattr(args, "program_id", None))
     configuration.configure(api_key=client._api_key, endpoint=client._endpoint, program_id=program_id)
     try:
         if args.source == "-" or args.source is None:
@@ -881,7 +874,10 @@ 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)
-    deployed = deployment.deploy_bundle(prepared.bundle, prepared.facts, metadata=metadata, program_id=program_id)
+    try:
+        deployed = deployment.deploy_bundle(prepared.bundle, prepared.facts, metadata=metadata, program_id=program_id)
+    except ValueError as exc:
+        raise api_client.CliError(str(exc)) from exc
 
     deployment_id = deployed.deployment_id
     print(deployment_id)
@@ -946,9 +942,7 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
     from ... import authored, configuration, optimization
 
     deployment_id = getattr(args, "deployment_id", None)
-    # Required only when the file's program is deployed here; a reused deployment
-    # already names its program.
-    program_id = _program_id_arg(getattr(args, "program_id", None), required=deployment_id is None)
+    program_id = _program_id_arg(getattr(args, "program_id", None))
     configuration.configure(api_key=client._api_key, endpoint=client._endpoint, program_id=program_id)
     try:
         if args.source == "-" or args.source is None:
@@ -1266,7 +1260,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         dest="program_id",
         default=None,
         help="Program id (p_…) the deployment belongs to, from `cmpnd programs create`. "
-        "Required; defaults to CMPND_PROGRAM_ID",
+        "Defaults to CMPND_PROGRAM_ID. Required by every serve after self-host release 2026-001",
     )
     dp.add_argument(
         "--entrypoint",
@@ -1351,8 +1345,8 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         dest="program_id",
         default=None,
         help="Program id (p_…) being optimized, from `cmpnd programs create`; defaults to "
-        "CMPND_PROGRAM_ID. Required when the file's program is deployed here, optional "
-        "with --deployment-id",
+        "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",
     )
     opt.add_argument(
         "--reflection-model",

{cmpnd-0.40.0 → cmpnd-0.41.0}/cmpnd/cli/shell.py

@@ -490,8 +490,8 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
         """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`` and one of
-        the two is required. A fresh child imports the staged bundle. The shell
+        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
         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 +499,7 @@ 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, required=True)
+        declared = commands.top._program_id_arg(program_id)
         configuration.configure(api_key=client._api_key, endpoint=client._endpoint, program_id=declared)
         if source in ("-", None):
             prepared = authored.prepare_stdin(

{cmpnd-0.40.0 → cmpnd-0.41.0}/cmpnd/deployment.py

@@ -346,21 +346,35 @@ def _resolve_mcp_tool_references(client: httpx.Client, config, references: list[
 
 
 MISSING_PROGRAM_ID = (
-    "deploying needs a program id: pass program_id= (`cmpnd deploy --program-id`), or set "
+    "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`."
 )
 
+# The error serve answers, with a 400, to a create that names no program. A serve
+# from before program ids accepts the create instead. serve pins this prefix in
+# deploymentsapi.missingProgramIDError.
+_SERVE_MISSING_PROGRAM_ID = "program_id is required"
 
-def require_program_id(explicit: str | None, config: configuration.Config) -> str:
+
+def declared_program_id(explicit: str | None, config: configuration.Config) -> str | None:
     """The program a deployment is created under: the explicit id, else the configured one.
 
-    A deployment always names its program, so a missing id is refused here, before
-    anything is packaged or sent, rather than by the server after a create.
+    A declared id is checked for shape before anything is packaged or sent. serve
+    decides whether a deployment needs an id, so a missing one is not refused here.
     """
     chosen = explicit if explicit is not None else config.program_id
-    if chosen is None:
-        raise ValueError(MISSING_PROGRAM_ID)
-    return identity.validate_program_id(chosen)
+    return identity.validate_program_id(chosen) if chosen is not None else None
+
+
+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:
+        return False
+    try:
+        error = response.json().get("error")
+    except (ValueError, AttributeError):
+        return False
+    return isinstance(error, str) and error.startswith(_SERVE_MISSING_PROGRAM_ID)
 
 
 def deploy(module, metric=None, timeout=300, metadata=None, *, program_id=None):
@@ -387,22 +401,24 @@ def deploy(module, metric=None, timeout=300, metadata=None, *, program_id=None):
             with string keys, within 64 KiB. Read it back via the deployment
             record (``cmpnd.status`` / the deployment GET API).
         program_id: The program (``p_…``) the deployment belongs to, as
-            ``cmpnd programs create`` printed it. Required: when omitted, the
-            configured id (``cmpnd.configure(program_id=...)`` or
-            ``CMPND_PROGRAM_ID``) is used, and with neither the deploy is
-            refused before anything is packaged.
+            ``cmpnd programs create`` printed it. When omitted, the configured
+            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.
 
     Returns:
         A DeployedProgram that can be called with the same inputs as the
         original module. Has a .deployment_id attribute and str() returns it.
 
     Raises:
-        ValueError: If no program id is given or configured, or it is malformed.
+        ValueError: If the program id is malformed, or if serve requires one and
+            none was given or configured.
         RuntimeError: If cmpnd is not configured, or if deployment fails.
         TimeoutError: If the program isn't ready within timeout seconds.
     """
     config = configuration.require_config()
-    declared_program_id = require_program_id(program_id, config)
+    program = declared_program_id(program_id, config)
 
     # 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
@@ -423,12 +439,15 @@ def deploy(module, metric=None, timeout=300, metadata=None, *, program_id=None):
     program_signature_hash = identity.compute_program_hash(module) or 0
 
     deploy_body: dict[str, Any] = {
-        "program_id": declared_program_id,
         "program_signature_hash": identity.format_signature_hash(program_signature_hash),
         # Declare the ZIP's exact length so the server can size-bound the upload
         # slot and reject an oversized deploy before signing it (Slice E).
         "declared_content_length": len(zip_bytes),
     }
+    # Left off when undeclared, so a serve from before program ids reads the body it
+    # always read and a newer serve answers with its own refusal.
+    if program is not None:
+        deploy_body["program_id"] = program
     # Carry the caller's metadata blob (validated and made jsonb-storable at the
     # call site) as a reserved top-level body key, committed with the deployment
     # record server-side.
@@ -496,13 +515,14 @@ def deploy_bundle(
 ) -> execution.DeployedProgram:
     """Upload a checked authored-source bundle without packaging a live module.
 
-    ``program_id`` is required as it is for :func:`deploy`: the explicit id, else
-    the configured one, else a ``ValueError`` before anything is sent.
+    ``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.
     """
     config = configuration.require_config()
-    declared_program_id = require_program_id(program_id, config)
+    program = declared_program_id(program_id, config)
     deploy_body = facts.deploy_body()
-    deploy_body["program_id"] = declared_program_id
+    if program is not None:
+        deploy_body["program_id"] = program
     deploy_body["source_format"] = "authored"
     deploy_body["declared_content_length"] = len(zip_bytes)
     if metadata is not None:
@@ -531,6 +551,8 @@ def _deploy_prepared(
             may_resend_with_no_answer=retry.never_left_the_client,
             may_resend_after_answer=lambda _: False,
         )
+        if _refused_for_missing_program_id(created, deploy_body):
+            raise ValueError(MISSING_PROGRAM_ID)
         _raise_http_error(created, "create deployment")
         answer = created.json()
         deployment_id = answer["deployment_id"]

{cmpnd-0.40.0 → cmpnd-0.41.0}/cmpnd/optimization.py

@@ -38,7 +38,7 @@ from typing import TYPE_CHECKING, Any, Callable, cast
 import httpx
 from httpx import HTTPError
 
-from . import _deployments, _http, authored, configuration, deployment, execution, identity, packaging, retry
+from . import _deployments, _http, authored, configuration, deployment, execution, packaging, retry
 from .deployment_metadata import DeploymentMetadataError, DeploymentSignatureResponse
 
 if TYPE_CHECKING:
@@ -831,10 +831,11 @@ def optimize(
         deployment_id: Skip the initial deploy by reusing an existing ready
             deployment as program A.
         program_id: The program (``p_…``) being optimized. Defaults to the
-            configured id. Required when the program is deployed here (no
-            ``deployment_id``), because a deployment always names its program;
-            optional otherwise, since the deployment already names one. Sent on
-            the first optimize step, the one that optimizes your deployment.
+            configured id. When the program is deployed here (no
+            ``deployment_id``), the deploy carries it, and serve decides whether
+            that deploy needs one. A reused deployment already names its program.
+            Sent on the first optimize step, the one that optimizes your
+            deployment.
         reflection_lm: **Required** — the model that proposes new instructions.
             The search is only as good as it is, so this is a strong model,
             typically not the one being optimized. Pass the ``dspy.LM`` you would
@@ -925,7 +926,7 @@ def optimize(
     _apply_budget(config, max_metric_calls=max_metric_calls, auto=auto)
 
     cfg = configuration.require_config()
-    program_id = _declared_program_id(program_id, cfg, deploys=deployment_id is None)
+    program_id = deployment.declared_program_id(program_id, cfg)
 
     from . import lm_configuration
 
@@ -957,19 +958,6 @@ def optimize(
     return _deployed_program(best_deployment_id, cfg, score=best_score)
 
 
-def _declared_program_id(explicit: str | None, cfg: configuration.Config, *, deploys: bool) -> str | None:
-    """The program an optimization names: the explicit id, else the configured one.
-
-    Required when this call deploys the program, since a deployment always names its
-    program, and refused before anything is sent. Optional when an existing
-    deployment is reused, because that deployment already names one.
-    """
-    if deploys:
-        return deployment.require_program_id(explicit, cfg)
-    chosen = explicit if explicit is not None else cfg.program_id
-    return identity.validate_program_id(chosen) if chosen is not None else None
-
-
 def _run_steps(
     cfg: configuration.Config,
     bundle: bytes,
@@ -1094,8 +1082,8 @@ def optimize_authored(
     one directory on the executor, so a path they disagree about is refused, and it is
     worth refusing here where both files are in reach.
 
-    ``program_id`` is :func:`optimize`'s: required when the file's program is deployed
-    here, optional when ``deployment_id`` names the program.
+    ``program_id`` is :func:`optimize`'s: the deploy of the file's program carries it,
+    and serve decides whether that deploy needs one.
     """
     check_optimizer(optimizer)
     config = dict(config or {})
@@ -1111,7 +1099,7 @@ def optimize_authored(
     _apply_budget(config, max_metric_calls=max_metric_calls, auto=auto)
 
     cfg = configuration.require_config()
-    program_id = _declared_program_id(program_id, cfg, deploys=prepared.program_bundle is not None)
+    program_id = deployment.declared_program_id(program_id, cfg)
 
     facts = prepared.facts.program
     if prepared.program_bundle is not None:

{cmpnd-0.40.0 → cmpnd-0.41.0}/cmpnd/programs.py

@@ -19,6 +19,11 @@ from . import _http, configuration
 
 DEFAULT_ENDPOINT = "https://platform.cmpnd.ai"
 
+# Self-host release 2026-001 answers a programs create with 405, because it routes
+# GET requests under /api/v1/programs/ and has no create. Every newer serve accepts
+# the create, so on this one route a 405 means a serve from before program ids.
+UNSUPPORTED_STATUS = 405
+
 
 def create(
     name: str | None = None,
@@ -61,7 +66,18 @@ def send_create(
         body["name"] = name
     if optimized_from_run_id is not None:
         body["optimized_from_run_id"] = optimized_from_run_id
-    return client.post("/api/v1/programs", json=body)
+    try:
+        return client.post("/api/v1/programs", json=body)
+    except _http.ApiError as exc:
+        if exc.status_code == UNSUPPORTED_STATUS:
+            raise _http.ApiError(
+                "This server does not support program ids. A serve from before program ids, such as "
+                "self-host release 2026-001, deploys without one: run `cmpnd deploy` without "
+                f"--program-id.\n  {exc}",
+                exc.exit_code,
+                status_code=exc.status_code,
+            ) from exc
+        raise
 
 
 def _client(api_key: str | None, endpoint: str | None) -> _http.ApiClient:

{cmpnd-0.40.0 → cmpnd-0.41.0}/docs/cli.md

@@ -19,10 +19,15 @@ PROGRAM_ID=$(cmpnd programs create --name triage)
 ```
 
 The command reports what it created on stderr, and `--json` prints the whole
-registry row instead. `cmpnd deploy` requires the id. `cmpnd optimize` takes
-it as `--program-id` too. It is required when the command deploys the file's
-program first, and optional with `--deployment-id`, because that deployment
-already names its program. Each call creates a new program. The command never
+registry row instead. `cmpnd deploy` takes the id as `--program-id`, and so
+does `cmpnd optimize` when it deploys the file's program first. With
+`--deployment-id`, the id is optional because that deployment already names its
+program. The CLI checks a given id's shape and leaves the requirement to serve.
+Every serve after self-host release 2026-001 refuses a deploy with no id, and
+the CLI then names `--program-id` and `cmpnd programs create`. Self-host release
+2026-001 has no program ids, so a deploy there omits `--program-id`, and
+`cmpnd programs create` reports that the server does not support them. Each
+call creates a new program. The command never
 retries, because a second send would create a second program.
 `cmpnd.programs.create(name=...)` makes the same call from Python and returns
 the row.

{cmpnd-0.40.0 → cmpnd-0.41.0}/docs/sdk-instrumentation.md

@@ -20,11 +20,11 @@ cmpnd.auto_instrument()
 ```
 
 - **`cmpnd.configure()`** — `cmpnd/configuration.py`. Reads `api_key`, `endpoint` and `program_id` from args or `CMPND_API_KEY` / `CMPND_ENDPOINT` / `CMPND_PROGRAM_ID` env vars, builds a `Config` dataclass (`configuration.py`), and stores it under a lock. This call does not start any threads. It also does not touch DSPy. You can call `configure()` in a library and let the user decide whether to instrument. See [The program id](#the-program-id) for what `program_id` does.
-- **`cmpnd.auto_instrument()`** — `python-sdk/cmpnd/__init__.py:272`. Requires `configure()` to have been called. It instantiates a `CmpndCallback`, appends it to `dspy.settings.callbacks` (deduplicating if already installed), and patches `dspy.GEPA.__init__` / `GEPA.compile` so optimization runs are tracked automatically. See [`./optimization-tracking.md`](../../docs/optimization-tracking.md) for what that patch does.
+- **`cmpnd.auto_instrument()`** — `auto_instrument` in `python-sdk/cmpnd/__init__.py`. Requires `configure()` to have been called. It instantiates a `CmpndCallback`, appends it to `dspy.settings.callbacks` (deduplicating if already installed), and patches `dspy.GEPA.__init__` / `GEPA.compile` so optimization runs are tracked automatically. See [`./optimization-tracking.md`](../../docs/optimization-tracking.md) for what that patch does.
 
 The exporter thread isn't started here directly. It is lazily started on first export via `ensure_exporter_started()` in `python-sdk/cmpnd/exporter.py:41`.
 
-If you want to instrument manually (for example, to wire the callback into a non-global `dspy.Settings`), you can construct `CmpndCallback` yourself from `python-sdk/cmpnd/callback.py:88` and hand it to DSPy. `auto_instrument` is just the convenient path.
+If you want to instrument manually (for example, to wire the callback into a non-global `dspy.Settings`), you can construct `CmpndCallback` yourself from `python-sdk/cmpnd/callback.py` and hand it to DSPy. `auto_instrument` is just the convenient path.
 
 For an explicit, scoped alternative that traces only the programs you run through it — with its own tags and credentials, orthogonal to this global path — see [`./client.md`](./client.md) (`cmpnd.Client`). `cmpnd.de_instrument()` removes this global instrumentation and restores the patched classes; it is documented there too.
 
@@ -79,12 +79,12 @@ capability lookup.
 
 The hook methods, in the order you'd expect them to fire for a typical `dspy.ChainOfThought` call:
 
-- **Module lifecycle** — `on_module_start` (`callback.py:195`) creates a new `SpanBuilder`, and, if this is the root module call, also creates a new `TraceBuilder` via `_create_trace` (`callback.py:579`). `on_module_end` (`callback.py:307`) closes the span, attaches outputs, and, if it was the root, exports the trace. A call is root when no span is on the stack — or when the only span above it is the `Evaluate` span, which contains many independent program runs and parents none of them, so each run under a `dspy.Evaluate` roots its own trace. Such a root span is built with `create_child_span(..., root=True)` so it does not adopt the `Evaluate` span as its parent.
+- **Module lifecycle** — `on_module_start` (`callback.py`) creates a new `SpanBuilder`, and, if this is the root module call, also creates a new `TraceBuilder` via `_create_trace`. `on_module_end` closes the span, attaches outputs, and, if it was the root, exports the trace. A call is root when no span is on the stack — or when the only span above it is the `Evaluate` span, which contains many independent program runs and parents none of them, so each run under a `dspy.Evaluate` roots its own trace. Such a root span is built with `create_child_span(..., root=True)` so it does not adopt the `Evaluate` span as its parent.
 - **LM calls.** `on_lm_start` and `on_lm_end` wrap the provider call. The callback records the model, the current span token projections, and a versioned `lm_usage` evidence object. `capture_prompts` controls whether the prompt payload is recorded.
 - **Adapter format/parse** — `on_adapter_format_start` / `_end` and `on_adapter_parse_start` / `_end`. Both route through the shared helpers `_start_adapter_span` and `_end_adapter_span`. The callback records one span per adapter call. DSPy's `Adapter.__init_subclass__` wraps `format` and `parse` on every subclass, so a `JSONAdapter.format` call fires the hooks twice and a `BAMLAdapter.format` call three times, each with a fresh `call_id` and the same instance. `_start_adapter_span` skips a call when the current span is the same method's adapter span on the same instance, and `_end_adapter_span` returns early for the skipped `call_id`. The outermost span is kept, since its output is what reaches the LM. `tests/test_adapter_reentrancy.py` runs the real adapters under DSPy's dispatch. An adapter span's inputs are the method's arguments, so they include the predictor's `signature`. `helpers.clean_inputs` records any signature class among a span's inputs by its label, the class name or the `in1, in2 -> out1` fields of a string signature. It never records the repr, which embeds the whole instructions and every field's metadata. The same rule covers a `Predict` called with `signature=`, as DSPy's RLM does on every turn from DSPy `main` on. The span records the signature's fields and instructions once, as its own attributes.
-- **Tools** — `on_tool_start` (`callback.py:700`) / `on_tool_end` (`callback.py:733`). One span per `dspy.Tool` invocation, with the tool's args as inputs.
-- **Interpreter (code execution)** — `_InterpreterMixin` (`callback.py:1119`), for the DSPy `CodeInterpreter` hooks DSPy >= 3.3.1 fires around a program running code in the interpreter (`RLM`, `ProgramOfThought`, `CodeAct`, `Flex` — every module reaching it through `_create_interpreter`; `ReAct` / `ReActV2` use no interpreter and fire none). `on_interpreter_execute_start` / `_end` emit one `INTERPRETER_EXECUTE` span per REPL cell — the code in, its captured stdout out, and the `SUBMIT()` result (a DSPy `FinalOutput`) recorded distinctly from stdout. `on_interpreter_tool_call_start` / `_end` synthesize a `TOOL` span for a tool called from interpreter code **only when no real `dspy.Tool` span covered the call** (a user tool routes through `Tool.__call__` and fires `on_tool_*`, so its row is suppressed to avoid a duplicate; the `llm_query` builtins fire no tool hook, so they get the synthesized span). `on_interpreter_startup_*` / `on_interpreter_shutdown_*` emit no span — their duration folds into an `interpreter.startup_ms` / `interpreter.shutdown_ms` attribute on the enclosing span, and an event with no enclosing span (a pooled pre-warm) is dropped.
-- **Evaluate** — `on_evaluate_start` (`callback.py:773`) / `on_evaluate_end` (`callback.py:782`). These are thin forwarders that delegate to `EvalHandler` (see "Eval handling" below).
+- **Tools** — `on_tool_start` / `on_tool_end` (`callback.py`). One span per `dspy.Tool` invocation, with the tool's args as inputs.
+- **Interpreter (code execution)** — `_InterpreterMixin` (`callback.py`), for the DSPy `CodeInterpreter` hooks DSPy >= 3.3.1 fires around a program running code in the interpreter (`RLM`, `ProgramOfThought`, `CodeAct`, `Flex` — every module reaching it through `_create_interpreter`; `ReAct` / `ReActV2` use no interpreter and fire none). `on_interpreter_execute_start` / `_end` emit one `INTERPRETER_EXECUTE` span per REPL cell — the code in, its captured stdout out, and the `SUBMIT()` result (a DSPy `FinalOutput`) recorded distinctly from stdout. On DSPy 3.4.1 and later, `RLM` runs the sandbox side of its `dspy` stand-in as each session's first cell, marked by the `__dspy_host_token` variable (`dspy.primitives.facade.HOST_TOKEN_VAR`). That cell is DSPy's machinery rather than a step the program took, so it emits no span. `on_interpreter_tool_call_start` / `_end` synthesize a `TOOL` span for a tool called from interpreter code **only when no real `dspy.Tool` span covered the call** (a user tool routes through `Tool.__call__` and fires `on_tool_*`, so its row is suppressed to avoid a duplicate; the `llm_query` builtins fire no tool hook, so they get the synthesized span). `on_interpreter_startup_*` / `on_interpreter_shutdown_*` emit no span — their duration folds into an `interpreter.startup_ms` / `interpreter.shutdown_ms` attribute on the enclosing span, and an event with no enclosing span (a pooled pre-warm) is dropped.
+- **Evaluate** — `on_evaluate_start` / `on_evaluate_end` (`callback.py`). These are thin forwarders that delegate to `EvalHandler` (see "Eval handling" below).
 
 During a GEPA evaluation, DSPy wraps the program prediction with its internal
 bootstrap trace. The callback recognizes this pair only while an optimization
@@ -108,8 +108,8 @@ so the next release that adds a hook is caught by CI rather than by a user's log
 
 This doc does not re-derive hash semantics — see [`./clustering.md`](../../docs/CLUSTERING.md) for why `signature_hash` exists and how xxhash maps to a signed Int64. Here's only _where_ it gets attached:
 
-- **On a span** — `_capture_module_attributes` in `callback.py:810`. After walking `instance.signature.input_fields` / `output_fields` and recording types and schemas, it calls `compute_signature_hash(signature)` at `callback.py:870` and stores the result on `span.signature_hash`. Composite modules (multi-child `dspy.Module` subclasses) take the `compute_composite_signature_hash` branch at `callback.py:889`.
-- **On a trace** — `_create_trace` in `callback.py:897`. Same split: single-signature modules hash directly at `callback.py:945`; composite modules walk `dspy.Predict` children and call the composite helper at `callback.py:964`.
+- **On a span** — `_capture_module_attributes` in `callback.py`. After walking `instance.signature.input_fields` / `output_fields` and recording types and schemas, it calls `compute_signature_hash(signature)` and stores the result on `span.signature_hash`. Composite modules (multi-child `dspy.Module` subclasses) take the `compute_composite_signature_hash` branch.
+- **On a trace** — `_create_trace` in `callback.py`. Same split: single-signature modules hash directly; composite modules walk `dspy.Predict` children and call the composite helper.
 
 Both code paths import from `python-sdk/cmpnd/identity.py`, which is the authoritative home of every hash the SDK computes.
 
@@ -117,11 +117,11 @@ Both code paths import from `python-sdk/cmpnd/identity.py`, which is the authori
 
 ## Span types
 
-`SpanType` is an enum defined in `python-sdk/cmpnd/models.py:157`. Grouped by hook that produces them:
+`SpanType` is an enum defined in `python-sdk/cmpnd/models.py`. Grouped by hook that produces them:
 
 | Group         | Values                                                            | Triggered when...                                                                                              |
 | ------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| Module-ish    | `MODULE`, `PREDICT`, `CHAIN_OF_THOUGHT`, `REACT`, `RLM`, `RETRIEVE` | `on_module_start` fires. The concrete type is chosen by `_get_span_type_for_module` at `callback.py:793`.       |
+| Module-ish    | `MODULE`, `PREDICT`, `CHAIN_OF_THOUGHT`, `REACT`, `RLM`, `RETRIEVE` | `on_module_start` fires. The concrete type is chosen by `_get_span_type_for_module`.       |
 | LM            | `LM_CALL`                                                         | `on_lm_start` fires — one per provider round-trip.                                                             |
 | Adapter       | `ADAPTER_FORMAT`, `ADAPTER_PARSE`                                 | DSPy's adapter serializes the prompt or parses the response.                                                   |
 | Tool          | `TOOL`                                                            | `dspy.Tool` is invoked (inside a ReAct loop), or synthesized for a builtin called from interpreter code.       |
@@ -660,7 +660,7 @@ Two files, both kept deliberately thin:
 - **`python-sdk/cmpnd/datasets.py`** — the user-facing `load_dataset()` helper (`datasets.py:142`). Fetches a named dataset + version from the backend, applies an optional field mapping via `_apply_field_mapping` (`datasets.py:33`), and returns DSPy `Example` objects. This is how you _pull_ a dataset down.
 - **`python-sdk/cmpnd/dataset_sync.py`** — utilities for _pushing_ a dataset up during an eval or optimization. `check_dataset_exists` at `dataset_sync.py:21` hits `GET /api/v1/datasets/check/:hash` to skip the upload if the backend already has it. `build_dataset_payload` at `dataset_sync.py:55` computes example hashes and assembles the payload.
 
-The callers are `python-sdk/cmpnd/eval_handler.py:192` (eval-time dataset capture) and `python-sdk/cmpnd/optimizers/tracker.py:866` (optimization-time capture, where it fires per compile and also per reflective dataset in GEPA). The devset never leaves the SDK unless the backend actually asks for it via the existence check — that's the whole reason these two modules are split from `datasets.py`.
+The callers are `python-sdk/cmpnd/eval_handler.py` (eval-time dataset capture) and `python-sdk/cmpnd/optimizers/tracker.py` (optimization-time capture, where it fires per compile and also per reflective dataset in GEPA). The devset never leaves the SDK unless the backend actually asks for it via the existence check — that's the whole reason these two modules are split from `datasets.py`.
 
 ---
 
@@ -757,11 +757,14 @@ the key is left off the wire rather than sent as `null`, so an undeclared trace
 it did before ids existed. The finalize body carries no id, because it restates no
 creation field.
 
-A deployment always names its program. `deploy()` and `deploy_bundle()` take
-`program_id=` and fall back to the configured id; with neither they raise `ValueError`
-before anything is packaged or sent (`deployment.require_program_id`). `optimize()` and
-`optimize_authored()` need the id only when they deploy the program themselves. A reused
-`deployment_id` already names its program, so the id is optional there. Later steps
+`deploy()` and `deploy_bundle()` take `program_id=` and fall back to the configured id
+(`deployment.declared_program_id`). A given id is checked for shape before anything is
+packaged or sent. With no id the create body leaves the key off, and serve decides.
+Every serve after self-host release 2026-001 refuses that create with a `400`, which the
+SDK raises as `ValueError` naming `cmpnd programs create`. Self-host release 2026-001
+has no program ids and accepts it. `optimize()` and `optimize_authored()` pass the id to
+the deploy when they deploy the program themselves. A reused `deployment_id` already
+names its program, so the id is optional there. Later steps
 optimize a result deployment the platform created and whose program it allocated, so
 the caller's id rides only the steps on the caller's own deployment.
 

{cmpnd-0.40.0 → cmpnd-0.41.0}/pyproject.toml

@@ -5,7 +5,7 @@ name = "cmpnd"
 # it's new) — no git tags. Bump with `uv version --bump {minor,patch}` or by
 # hand. Runtime `cmpnd.__version__` reads installed metadata, so it tracks
 # this automatically. See docs/plans/2026-07-02-sdk-pypi-tag-free-publish.md.
-version = "0.40.0"
+version = "0.41.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 
@@ -95,6 +96,12 @@ dev = [
     "ruff>=0.4.0",
     "basedpyright>=1.39",
     "jsonschema>=4.0",
+    # The tests import litellm (tests/e2e/fake_lm.py and the modules that reuse it) and
+    # gepa directly. dspy 3.4.1 installs both only below Python 3.15, because both declare
+    # requires-python <3.15. uv ignores that upper bound, so the 3.15 test leg still
+    # installs them.
+    "litellm",
+    "gepa",
     # litellm's bedrock/ provider imports boto3 in-process, so the client-side
     # Bedrock stress tests (committee twins) need it in the test env.
     "boto3>=1.34",

cmpnd-0.41.0/scripts/check-pip-install.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Install cmpnd with pip's own resolver and check that the installed package
+# imports and instruments DSPy. Called by .github/workflows/ci-sdk.yml (the
+# sdk-test leg for Python 3.15).
+#
+# `pip install cmpnd` is the install PyPI advertises. pip honours the
+# requires-python upper bounds that uv ignores, so this check fails when no
+# dspy release admits the Python version. PYO3_USE_ABI3_FORWARD_COMPATIBILITY
+# is set to 0, so an extension without a wheel for this Python fails the
+# install and does not build from source.
+#
+# Usage: scripts/check-pip-install.sh <python-version> <dspy-version>
+#   e.g. scripts/check-pip-install.sh 3.15 3.4.1
+set -euo pipefail
+
+if [ "$#" -ne 2 ]; then
+    echo "usage: $0 <python-version> <dspy-version>" >&2
+    exit 2
+fi
+python_version=$1
+dspy_version=$2
+
+sdk_dir=$(cd "$(dirname "$0")/.." && pwd)
+venv_dir=$(mktemp -d)
+trap 'rm -rf "$venv_dir"' EXIT
+
+uv venv --seed --python "$python_version" "$venv_dir"
+PYO3_USE_ABI3_FORWARD_COMPATIBILITY=0 \
+    "$venv_dir/bin/python" -m pip install "$sdk_dir" "dspy==$dspy_version"
+
+# -I keeps the checkout off sys.path, so the import reads the installed
+# package and not the source tree.
+cd "$venv_dir"
+"$venv_dir/bin/python" -I -c "import cmpnd; cmpnd.configure(api_key='ci'); cmpnd.auto_instrument(); print('cmpnd', cmpnd.__file__)"

{cmpnd-0.40.0 → cmpnd-0.41.0}/tests/load/rlm_size_report.py

@@ -44,6 +44,11 @@ from dspy.utils.dummies import DummyLM
 
 ADAPTERS = {"chat": dspy.ChatAdapter, "json": dspy.JSONAdapter, "xml": dspy.XMLAdapter}
 
+# The variable that marks RLM's sandboxed-dspy setup run on DSPy 3.4.1 and later
+# (`dspy.primitives.facade.HOST_TOKEN_VAR`). Spelled out rather than imported from
+# `cmpnd.callback`, because `--at` measures revisions of cmpnd that predate it.
+SANDBOX_SETUP_VARIABLE = "__dspy_host_token"
+
 
 def interpreter_output(turn: int, size: int) -> str:
     """About ``size`` characters of interpreter output only ``turn`` produces.
@@ -91,7 +96,11 @@ class FakeInterpreter:
 
     @with_callbacks
     def execute(self, code: str, variables: Any = None) -> str:
-        del code, variables  # the answer depends on the turn alone
+        del code  # the answer depends on the turn alone
+        # DSPy 3.4.1's RLM runs its sandboxed-dspy setup as the session's first cell.
+        # That is no turn of the program's, so it takes no turn's output.
+        if isinstance(variables, dict) and SANDBOX_SETUP_VARIABLE in variables:
+            return ""
         self.turn += 1
         return self._output(self.turn)