cmpnd 0.42.2__tar.gz → 0.43.0__tar.gz

{cmpnd-0.42.2 → cmpnd-0.43.0}/PKG-INFO

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

{cmpnd-0.42.2 → cmpnd-0.43.0}/cmpnd/__init__.py

@@ -60,6 +60,7 @@ from .optimization import (
     OptimizeFailed,
     optimize,
 )
+from .programs import Program
 
 try:
     __version__ = importlib.metadata.version("cmpnd")
@@ -100,6 +101,8 @@ __all__ = [
     "traces",
     # Program ids (cmpnd.programs.create)
     "programs",
+    # A program declared by name
+    "Program",
     "authored",
     "ApiError",
     # Types

{cmpnd-0.42.2 → cmpnd-0.43.0}/cmpnd/callback.py

@@ -24,6 +24,21 @@ _current_interpreter_tool_frame: contextvars.ContextVar[dict[str, Any] | None] =
 )
 
 
+# The DSPy settings key that carries the name of the program a client is running.
+# ``cmpnd.Client`` sets it with ``dspy.context`` around a call, so it reaches the
+# threads DSPy starts for evaluation and parallel work, and the callback stamps it on
+# the trace it creates for the call. None means the call declares no program.
+DECLARED_PROGRAM_SETTING = "cmpnd_declared_program"
+
+
+def _declared_program_name() -> str | None:
+    """The program name the current call declares, read from DSPy's settings."""
+    import dspy
+
+    name = dspy.settings.get(DECLARED_PROGRAM_SETTING)
+    return name if isinstance(name, str) else None
+
+
 def trace_id(prediction: Any) -> str | None:
     """Return the cmpnd trace id for a prediction returned by an instrumented program.
 
@@ -502,6 +517,9 @@ class _CallbackBase:
         # later cmpnd.configure(). That fixedness is what keeps a client
         # orthogonal to the global config.
         self._own_config = own_config
+        # Set once this callback has warned that a declared name replaced its
+        # configured program id, so the warning appears once per client.
+        self._warned_name_over_id = False
 
         # Resolve feature flags: explicit param > config > default
         config = own_config or configuration.get_config()
@@ -652,12 +670,30 @@ class _CallbackBase:
         return configuration._current_program_id()
 
     def _stamp(self, builder: Any) -> Any:
-        """Stamp this callback's project tags, and on a trace its program id, onto a
+        """Stamp this callback's project tags, and on a trace its program, onto a
         builder it just created. A span's program is its trace's, so a span carries
-        no id of its own."""
+        no program of its own.
+
+        A trace from a call that declares a program name carries the name and no id,
+        and the exporter resolves the name. The declared name wins over a program id
+        the client was configured with, and the callback warns once that it did.
+        """
         builder.project_tags = self._resolve_project_tags()
         if isinstance(builder, models.TraceBuilder):
-            builder.program_id = self._resolve_program_id()
+            program_id = self._resolve_program_id()
+            name = _declared_program_name()
+            if name is not None:
+                if program_id is not None and not self._warned_name_over_id:
+                    self._warned_name_over_id = True
+                    logger.warning(
+                        "cmpnd: traces of program %r go to the program with that name, not to the configured "
+                        "program id %s.",
+                        name,
+                        program_id,
+                    )
+                builder.declared_name = name
+                program_id = None
+            builder.program_id = program_id
         return builder
 
     def _current_exporter(self) -> Any:

{cmpnd-0.42.2 → cmpnd-0.43.0}/cmpnd/client.py

@@ -25,10 +25,11 @@ CLI groups from customers.
 
 from __future__ import annotations
 
+import dataclasses
 import os
 from typing import Any, Literal
 
-from . import _assessments, _deployments, _exporter_pool, _traces, _valsets, callback, configuration
+from . import _assessments, _deployments, _exporter_pool, _traces, _valsets, callback, configuration, programs
 from .deployment_metadata import DeploymentSignatureResponse
 
 
@@ -105,13 +106,28 @@ class Client:
 
     # -- scoped runs ------------------------------------------------------
 
+    def _declared(self, program: Any) -> dict[str, Any]:
+        """The ``dspy.context`` settings that run ``program`` under its declared name.
+
+        A ``cmpnd.Program`` runs on its own LM and declares its name. Any other module
+        declares no name, which also clears a name an enclosing call declared.
+        """
+        if isinstance(program, programs.Program):
+            return {"lm": program.lm, callback.DECLARED_PROGRAM_SETTING: program.name}
+        return {callback.DECLARED_PROGRAM_SETTING: None}
+
     def run_program(self, program: Any, **inputs: Any) -> Any:
-        """Run ``program(**inputs)`` traced on this client's account."""
+        """Run ``program(**inputs)`` traced on this client's account.
+
+        ``program`` is a ``cmpnd.Program`` or a plain DSPy module. A ``Program`` runs
+        on its own LM, and its traces go to the program with its name.
+        """
         self._check_active()
         import dspy
 
-        with dspy.context(callbacks=self._scoped_callbacks()):
-            return program(**inputs)
+        module = program.module if isinstance(program, programs.Program) else program
+        with dspy.context(callbacks=self._scoped_callbacks(), **self._declared(program)):
+            return module(**inputs)
 
     def run_optimization(
         self,
@@ -133,17 +149,33 @@ class Client:
         client's own transport, and — when ``auto_instrument`` is also active —
         suppresses the global class patch so the run is recorded once, on the
         client's account, not the global one.
+
+        ``student`` is a ``cmpnd.Program`` or a plain DSPy module. A ``Program`` is
+        optimized on its own LM, its rollouts and run record go to the program with
+        its name, and the result is a ``Program`` with the same name and LM.
         """
         self._check_active()
         import dspy
 
-        with dspy.context(callbacks=self._scoped_callbacks()):
+        module = student.module if isinstance(student, programs.Program) else student
+        with dspy.context(callbacks=self._scoped_callbacks(), **self._declared(student)):
             try:
                 if isinstance(optimizer, dspy.GEPA):
-                    return self._run_gepa(optimizer, student, trainset=trainset, valset=valset, kwargs=kwargs)
-                return optimizer.compile(student, trainset=trainset, valset=valset, **kwargs)
+                    result = self._run_gepa(
+                        optimizer,
+                        module,
+                        trainset=trainset,
+                        valset=valset,
+                        kwargs=kwargs,
+                        declared_name=student.name if isinstance(student, programs.Program) else None,
+                    )
+                else:
+                    result = optimizer.compile(module, trainset=trainset, valset=valset, **kwargs)
             finally:
                 self._callback._clear_optimization_trace_state()
+        if isinstance(student, programs.Program):
+            return programs.Program(student.name, module=result, lm=student.lm)
+        return result
 
     # -- data surface (flat verb-object over the client's credentials) -----
     #
@@ -285,11 +317,30 @@ class Client:
         self._check_active()
         return _valsets.delete_entry(entry_id, api_key=self._config.api_key, endpoint=self._config.endpoint)
 
-    def _run_gepa(self, optimizer: Any, student: Any, *, trainset: Any, valset: Any, kwargs: dict[str, Any]) -> Any:
-        """Track a GEPA compile on this client's account and suppress the global patch."""
+    def _run_gepa(
+        self,
+        optimizer: Any,
+        student: Any,
+        *,
+        trainset: Any,
+        valset: Any,
+        kwargs: dict[str, Any],
+        declared_name: str | None = None,
+    ) -> Any:
+        """Track a GEPA compile on this client's account and suppress the global patch.
+
+        A declared name is resolved here, on the caller's thread, because the run
+        record is sent synchronously when the run starts and must carry its program
+        id then. The record goes without an id when the name does not resolve.
+        """
         from . import _exporter_pool, _gepa_patch
 
         client_exporter = _exporter_pool.ensure_exporter_started(self._config)
+        run_config = self._config
+        if declared_name is not None:
+            resolve = getattr(client_exporter, "resolve_program_name", None)
+            program_id = resolve(declared_name) if callable(resolve) else None
+            run_config = dataclasses.replace(self._config, program_id=program_id)
 
         def _search() -> Any:
             return optimizer.compile(student, trainset=trainset, valset=valset, **kwargs)
@@ -302,7 +353,7 @@ class Client:
                 trainset=trainset,
                 valset=valset,
                 run_original=_search,
-                client_config=self._config,
+                client_config=run_config,
                 exporter_override=client_exporter,
             )
         finally:

{cmpnd-0.42.2 → cmpnd-0.43.0}/cmpnd/programs.py

@@ -13,10 +13,17 @@ call that lost its answer leaves a second, empty program behind. That is why
 from __future__ import annotations
 
 import os
+import re
 from typing import Any
 
 from . import _http, configuration
 
+# A program name is an ASCII letter or digit, then letters, digits, ".", "_" or "-",
+# at most 64 characters. Serve compares names without case and keeps the case typed.
+_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}")
+# Reserved in any case, so that a name never looks like a program id.
+_RESERVED_PREFIX = "p_"
+
 DEFAULT_ENDPOINT = "https://platform.cmpnd.ai"
 
 # Self-host release 2026-001 answers a programs create with 405, because it routes
@@ -87,3 +94,60 @@ def _client(api_key: str | None, endpoint: str | None) -> _http.ApiClient:
         raise _http.ApiError("No API key. Pass api_key=, call cmpnd.configure(api_key=...), or set CMPND_API_KEY.")
     resolved_endpoint = endpoint or (cfg.endpoint if cfg else None) or os.getenv("CMPND_ENDPOINT") or DEFAULT_ENDPOINT
     return _http.ApiClient(resolved_key, resolved_endpoint)
+
+
+def validate_program_name(name: object) -> str:
+    """Return ``name`` when it is a valid program name, and raise ``ValueError`` otherwise.
+
+    Serve checks the same syntax. Checking it here makes a bad name fail where it is
+    declared, with no network call, instead of in the exporter after the program runs.
+    """
+    if not isinstance(name, str) or not _NAME.fullmatch(name) or name.lower().startswith(_RESERVED_PREFIX):
+        raise ValueError(
+            f"{name!r} is not a valid program name. A program name is a letter or digit followed by "
+            "letters, digits, '.', '_' or '-', at most 64 characters, and does not start with p_."
+        )
+    return name
+
+
+class Program:
+    """A DSPy module, the LM it runs on, and the name of the program it is.
+
+    The name is the program's handle: traces from a ``cmpnd.Client`` run of this
+    program go to the program with this name in the caller's organization, which the
+    platform creates on first use. Programs in one organization that share a name
+    share a history.
+
+    Declaring a program makes no network call. The SDK asks the platform for the
+    program behind the name the first time a client sends one of its traces.
+
+        >>> qa = cmpnd.Program("capital-qa", module=dspy.Predict("question -> answer"), lm=dspy.LM("openai/gpt-5-mini"))
+        >>> with cmpnd.Client() as client:
+        ...     client.run_program(qa, question="What is the capital of France?")
+    """
+
+    def __init__(self, name: str, *, module: Any, lm: Any) -> None:
+        import dspy
+        from dspy.clients import base_lm  # pyright: ignore[reportMissingTypeStubs]  # dspy re-exports BaseLM untyped
+
+        self.name = validate_program_name(name)
+        if not isinstance(module, dspy.Module):
+            raise TypeError(f"A Program needs a DSPy module, not {type(module).__name__}")
+        if not isinstance(lm, base_lm.BaseLM):
+            raise TypeError(f"A Program needs an LM such as dspy.LM(...), not {type(lm).__name__}")
+        self.module = module
+        self.lm = lm
+
+    def __call__(self, **inputs: Any) -> Any:
+        """Run the module on this program's LM, as plain DSPy.
+
+        A direct call records nothing under the program's name. Run the program
+        through ``cmpnd.Client.run_program`` to trace it under its name.
+        """
+        import dspy
+
+        with dspy.context(lm=self.lm):
+            return self.module(**inputs)
+
+    def __repr__(self) -> str:
+        return f"Program({self.name!r}, lm={getattr(self.lm, 'model', self.lm)!r})"

{cmpnd-0.42.2 → cmpnd-0.43.0}/docs/client.md

@@ -43,6 +43,43 @@ and run records use the client's own id and never the id given to
 `configure()`. A client with no id declares no program, so its runs go out
 without one. Project tags follow the same rule.
 
+## Programs declared by name
+
+`cmpnd.Program(name, module=..., lm=...)` declares a program by name. It holds a
+DSPy module and the `dspy.LM` it runs on. A client that runs a `Program` traces
+it under its name:
+
+```python
+qa = cmpnd.Program("capital-qa", module=dspy.Predict("question -> answer"), lm=dspy.LM("openai/gpt-5-mini"))
+
+with cmpnd.Client() as sdk:
+    sdk.run_program(qa, question="What is the capital of France?")
+    better = sdk.run_optimization(gepa, qa, trainset=train, valset=val)
+```
+
+- **A name is checked where it is declared.** It is an ASCII letter or digit,
+  then letters, digits, `.`, `_` or `-`, at most 64 characters, and it does not
+  start with `p_` in any case. A bad name raises `ValueError`. Declaring a
+  program makes no network call.
+- **The name finds the program.** The exporter asks the platform for the
+  program with that name in the caller's organization, which the platform
+  creates on first use, and sends the program's id on each trace. Each process
+  asks once per name. Two processes that declare one name write to one program.
+- **A `Program` runs on its own LM**, with no global `dspy.configure` needed.
+  Calling it directly runs the module on its LM as plain DSPy, and traces
+  nothing under its name.
+- **An optimized program keeps its name.** `run_optimization` returns a
+  `Program` with the same name and LM and the optimized module. For a
+  `dspy.GEPA` optimizer, the client resolves the name before the run starts, so
+  the run record carries the program's id.
+- **The name wins over `program_id=`.** A client configured with an id sends a
+  declared program's traces to the named program, and warns once.
+- **A serve without program names**, such as self-host release 2026-001, gets
+  the traces without an id. The exporter warns once per name.
+
+A plain DSPy module passed to `run_program` or `run_optimization` declares no
+name, as before.
+
 ## Membership
 
 A client records a call only when the call runs through one of its methods.

{cmpnd-0.42.2 → cmpnd-0.43.0}/docs/sdk-instrumentation.md

@@ -771,7 +771,10 @@ the caller's id rides only the steps on the caller's own deployment.
 #### A declared program name resolves to an id in the exporter
 
 A trace can declare its program by name instead of by id, in `TraceBuilder.declared_name`.
-No public API sets it yet. The name never goes on the wire. The exporter resolves it with
+A `cmpnd.Client` run of a `cmpnd.Program` sets it: the client puts the name in the DSPy
+settings key `callback.DECLARED_PROGRAM_SETTING` with `dspy.context`, which reaches the
+threads DSPy starts, and `CmpndCallback._stamp` copies it onto the trace and drops any id
+the client was configured with. The name never goes on the wire. The exporter resolves it with
 `PUT /api/v1/programs/by-name/{name}` and writes the id into the trace start and full
 trace bodies, at the top level and in `started_fact`, before it compares or sends them.
 `cmpnd_ingest/program_names.py` keeps the answers, and
@@ -784,6 +787,9 @@ trace bodies, at the top level and in `started_fact`, before it compares or send
   does. The exit flush resolves the names still waiting, with no retries.
 - **An id already on the trace stands.** Inside a worker, a deployment's traces carry
   its id from the start, and no name is resolved.
+- **A run record resolves on the caller's thread.** An optimization run's start is sent
+  synchronously, so `Client.run_optimization` calls `BatchExporter.resolve_program_name`
+  before a `dspy.GEPA` run starts. It shares the flush's answers.
 - **A refusal settles the name with no id.** Serve answers 404 or 405 when it has no
   program names, as self-host release 2026-001 does, and 409, 422 or 403 for a name it
   will not resolve. The traces go without an id, and the exporter warns once per name.

{cmpnd-0.42.2 → cmpnd-0.43.0}/ingest/cmpnd_ingest/exporter_http.py

@@ -1435,7 +1435,21 @@ class BatchExporter:
         for trace_id in ended_traces:
             self._program_names.trace_ended(trace_id)
 
-    def _resolve_program_name(self, name: str, tally: retry.TransientTally) -> None:
+    def resolve_program_name(self, name: str) -> str | None:
+        """The program id for a declared name, resolved now on the caller's thread.
+
+        For a record that must carry its program id when it is sent synchronously,
+        such as an optimization run's start. It shares the answers the flush keeps, so
+        a name the flush resolved costs no request here, and the reverse. Returns None
+        when serve refused the name or could not be reached, and the record goes
+        without an id.
+        """
+        if not self._program_names.unsettled([name]):
+            return self._program_names.program_id(name)
+        self._resolve_program_name(name, retry.TransientTally(), self._sync_http_client())
+        return self._program_names.program_id(name)
+
+    def _resolve_program_name(self, name: str, tally: retry.TransientTally, client: httpx.Client | None = None) -> None:
         """Ask serve for a name's program id, and settle the name unless serve was unreachable.
 
         The request has no body. A 429, a 5xx or an unreachable server is retried on
@@ -1443,7 +1457,7 @@ class BatchExporter:
         leaves the name unsettled for the next batch. A refusal settles the name with
         no id. Each name warns once.
         """
-        client = self._require_client()
+        client = client if client is not None else self._require_client()
         path = "/api/v1/programs/by-name/" + urllib.parse.quote(name, safe="")
         try:
             response = self._send_retrying(

{cmpnd-0.42.2 → cmpnd-0.43.0}/ingest/cmpnd_ingest/program_names.py

@@ -57,6 +57,11 @@ class ProgramNames:
         with self._lock:
             self._ids[name] = program_id
 
+    def program_id(self, name: str) -> str | None:
+        """The id serve gave for a settled name, or None for a refused or unsettled one."""
+        with self._lock:
+            return self._ids.get(name)
+
     def first_warning(self, name: str) -> bool:
         """True the first time this is asked for a name, so each name warns once."""
         with self._lock:

{cmpnd-0.42.2 → cmpnd-0.43.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.42.2"
+version = "0.43.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"