cmpnd 0.27.1__tar.gz → 0.27.2__tar.gz

{cmpnd-0.27.1 → cmpnd-0.27.2}/AGENTS.md

@@ -130,7 +130,7 @@ not a copy — see the reasoning at the top of `cmpnd/exporter_http.py`).
 
 The transport sits under its own directory, with its own `pyproject.toml`
 (`cmpnd-ingest`), so a producer that is not a DSPy program can install it without
-dspy: its entire dependency set is httpx. The wasm worker's native GEPA child
+dspy: its entire dependency set is httpx. The optimizer's search process
 (`search-process/`) is that producer, and a venv unable to supply dspy is
 what enforces its boundary. `ingest/README.md` has the full argument.
 
@@ -158,7 +158,7 @@ What that costs you, before touching either pyproject:
 - `cmpnd/callback.py` - DSPy instrumentation, signature extraction
 - `cmpnd/optimizers/tracker.py` - Optimization tracking
 - `cmpnd/packaging.py` - Source ZIP generation for deploy (ported from the retired `deploy/local_cmpnd.py`)
-- `cmpnd/deployment.py` - `deploy()` function: SDK -> serve -> AWS deploy stack
+- `cmpnd/deployment.py` - `deploy()` function: package the module, create the deployment on serve, PUT the bundle to the upload slot serve provisioned (a presigned S3 PUT when hosted, the worker's own slot on-prem), poll the parser
 
 ## Reflector ↔ DSPy compatibility
 

{cmpnd-0.27.1 → cmpnd-0.27.2}/PKG-INFO

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

{cmpnd-0.27.1 → cmpnd-0.27.2}/cmpnd/__init__.py

@@ -29,6 +29,7 @@ from .decorators import start_span, trace
 from .deployment import DeployFailed, deploy, deploy_bundle
 from .execution import DeployedProgram, RetryableProviderError, execute
 from .exporter import flush_exporter, shutdown_exporter
+from .lm_configuration import configure_lm
 from .mcp_servers import (
     Bearer,
     McpToolReference,
@@ -57,6 +58,7 @@ _auto_instrument_callback: CmpndCallback | None = None
 __all__ = [
     # Configuration
     "configure",
+    "configure_lm",
     "get_config",
     "require_config",
     # Main callback

{cmpnd-0.27.1 → cmpnd-0.27.2}/cmpnd/_authored_import.py

@@ -56,7 +56,9 @@ def _configured(request: dict[str, Any]) -> dict[str, int | None]:
     transport while letting the file change the settings it owns, and records the two
     trace limits the create call carries.
     """
-    from . import configuration
+    from . import configuration, lm_configuration
+
+    lm_configuration.begin_authored()
 
     original_configure = configuration.configure
     authored_limits: dict[str, int | None] = {"max_input_size": None, "max_output_size": None}
@@ -115,7 +117,6 @@ def _program_facts(
     authored_limits: dict[str, int | None],
 ) -> dict[str, Any]:
     """Everything the deployment create call reads off the imported program."""
-    import dspy
 
     from . import configuration, deployment, identity, mcp_servers, packaging
     from .authored import ProgramFacts
@@ -163,7 +164,9 @@ def _program_facts(
             "input_field_types": [identity.get_type_string(f.annotation) for f in signature.input_fields.values()],
             "output_field_types": [identity.get_type_string(f.annotation) for f in signature.output_fields.values()],
         }
-    lm = dspy.settings.lm
+    from . import lm_configuration
+
+    lm = packaging._extract_lm_object(program)
     lm_kwargs = getattr(lm, "kwargs", {}) if lm is not None else {}
     facts = ProgramFacts(
         program_signature_hash=identity.compute_program_hash(program),
@@ -177,6 +180,7 @@ def _program_facts(
         max_output_size=authored_limits["max_output_size"],
         tool_references=tool_references,
         tool_declarations=tool_declarations,
+        lm_capabilities=lm_configuration.resolve({"default-lm": lm} if lm is not None else {}, require_all=False),
         **fields,
     )
     return asdict(facts)
@@ -184,12 +188,20 @@ def _program_facts(
 
 def _check(request: dict[str, Any]) -> dict[str, Any]:
     """The program bundle's answer: one import, the entrypoint's facts."""
+    from . import lm_configuration, packaging
+
     authored_limits = _configured(request)
     with _staged(request) as root:
         manifest = json.loads((root / "manifest.json").read_text())
         module = _import_member(str(manifest["program"]))
         program, kind = _program(module, str(manifest["entrypoint"]))
-        return {"facts": _program_facts(program, kind, authored_limits)}
+        facts = _program_facts(program, kind, authored_limits)
+        bindings = dict(getattr(module, "lms", None) or {})
+        default_lm = packaging._extract_lm_object(program)
+        if default_lm is not None:
+            bindings["default-lm"] = default_lm
+        facts["lm_capabilities"] = lm_configuration.resolve(bindings)
+        return {"facts": facts}
 
 
 def _check_optimize(request: dict[str, Any]) -> dict[str, Any]:
@@ -199,7 +211,7 @@ def _check_optimize(request: dict[str, Any]) -> dict[str, Any]:
     importing it three times would run its module scope three times — which is neither
     what the author's own script does nor what the kernel does.
     """
-    from . import optimization
+    from . import lm_configuration, optimization, packaging
 
     ask = request["optimize"]
     authored_limits = _configured(request)
@@ -242,6 +254,7 @@ def _check_optimize(request: dict[str, Any]) -> dict[str, Any]:
                 f"Bind `{program_entrypoint} = ...` to optimize the file's own program, or pass an "
                 "existing deployment id to optimize that."
             )
+        program = None
         if declared_program is not None:
             program, kind = _program(module, program_entrypoint)
             facts = _program_facts(program, kind, authored_limits)
@@ -254,6 +267,13 @@ def _check_optimize(request: dict[str, Any]) -> dict[str, Any]:
             optimization._check_proposer_call(declared_proposer)
             found_proposer = proposer_entrypoint
 
+        bindings = dict(getattr(module, "lms", None) or {})
+        if program is not None:
+            default_lm = packaging._extract_lm_object(program)
+            if default_lm is not None:
+                bindings["default-lm"] = default_lm
+        declarations = lm_configuration.resolve(bindings)
+
         work = Path(request["work_dir"])
         trainset = _rows(module, "trainset")
         valset = _rows(module, "valset")
@@ -266,6 +286,7 @@ def _check_optimize(request: dict[str, Any]) -> dict[str, Any]:
             "program_entrypoint": found_program,
             "proposer_entrypoint": found_proposer,
             "lms": declared_lms,
+            "lm_capabilities": declarations,
             "trainset_rows": len(trainset),
             "valset_rows": len(valset),
         }

{cmpnd-0.27.1 → cmpnd-0.27.2}/cmpnd/authored.py

@@ -59,6 +59,7 @@ class ProgramFacts:
     max_output_size: int | None = None
     tool_references: list[dict[str, Any]] = field(default_factory=list)
     tool_declarations: list[dict[str, Any]] = field(default_factory=list)
+    lm_capabilities: dict[str, Any] = field(default_factory=dict)
 
     @classmethod
     def minimal(cls) -> ProgramFacts:
@@ -177,6 +178,9 @@ def _prepare(
     }
     bundle = _zip(manifest, members)
     facts = _check_bundle(bundle, api_key=api_key, endpoint=endpoint)
+    if facts.lm_capabilities:
+        manifest["lm_capabilities"] = facts.lm_capabilities
+        bundle = _zip(manifest, members)
     if facts.tool_declarations:
         # The child pinned these declarations while importing this exact source.
         # Serve checks each schema hash against the registry again on create, so
@@ -350,6 +354,8 @@ def _prepare_optimize(
         manifest["proposer_entrypoint"] = facts.proposer_entrypoint
     if program_facts is not None and program_facts.tool_declarations:
         manifest["tools"] = program_facts.tool_declarations
+    if found.get("lm_capabilities"):
+        manifest["lm_capabilities"] = found["lm_capabilities"]
     program_bundle = _zip(manifest, members) if facts.program_entrypoint else None
     optimization_bundle = _zip(manifest, {**members, **produced})
     return PreparedOptimize(

cmpnd-0.27.2/cmpnd/lm_configuration.py

@@ -0,0 +1,203 @@
+"""Hosted LM declarations, resolved by binding name and object identity."""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class LMConfigurationError(ValueError):
+    """A hosted binding declaration cannot be resolved consistently."""
+
+
+class LMCapabilities(TypedDict):
+    """Explicit adapter hints for a hosted model, independent of its provider."""
+
+    supported_params: list[str]
+    supports_response_schema: bool
+
+
+def _validate_lm_capabilities(value: object) -> dict[str, LMCapabilities]:
+    if not isinstance(value, dict):
+        raise LMConfigurationError("lm_capabilities must map exact binding names to capability declarations")
+    result: dict[str, LMCapabilities] = {}
+    for binding, declaration in value.items():
+        if not isinstance(binding, str) or not binding or binding != binding.strip():
+            raise LMConfigurationError(
+                "lm_capabilities binding names must be nonempty strings without surrounding whitespace"
+            )
+        if not isinstance(declaration, dict):
+            raise LMConfigurationError(f"lm_capabilities[{binding!r}] must be a capability declaration")
+        unknown = declaration.keys() - {"supported_params", "supports_response_schema"}
+        if unknown:
+            raise LMConfigurationError(f"lm_capabilities[{binding!r}] has unknown fields: {sorted(unknown, key=str)}")
+        params = declaration.get("supported_params", [])
+        if not isinstance(params, list) or any(not isinstance(param, str) or not param for param in params):
+            raise LMConfigurationError(
+                f"lm_capabilities[{binding!r}].supported_params must be a list of nonempty strings"
+            )
+        schema = declaration.get("supports_response_schema", False)
+        if not isinstance(schema, bool):
+            raise LMConfigurationError(f"lm_capabilities[{binding!r}].supports_response_schema must be a boolean")
+        if schema and "response_format" not in params:
+            raise LMConfigurationError(
+                f"lm_capabilities[{binding!r}] requires response_format in supported_params for schema output"
+            )
+        result[binding] = {"supported_params": list(dict.fromkeys(params)), "supports_response_schema": schema}
+    return result
+
+
+_objects: list[Any] = []
+_authored = False
+_names: dict[str, dict[str, Any]] = {}
+_restored: dict[str, dict[str, Any]] = {}
+
+
+def reset() -> None:
+    global _authored
+    _authored = False
+    _objects.clear()
+    _names.clear()
+    _restored.clear()
+
+
+def begin_authored() -> None:
+    """Start the isolated importer or kernel scope before loading authored code."""
+    global _authored
+    reset()
+    _authored = True
+
+
+def _object_declaration(lm: Any) -> Any:
+    declaration = getattr(lm, "_cmpnd_lm_capabilities", None)
+    if declaration is not None and declaration[0] == id(lm):
+        return declaration[1:]
+    return None
+
+
+def _name(value: object) -> str:
+    if not isinstance(value, str) or not value or value != value.strip():
+        raise LMConfigurationError("an LM binding name must be a nonempty string without surrounding whitespace")
+    return value
+
+
+def _model(lm: Any) -> str:
+    model = lm if isinstance(lm, str) else getattr(lm, "model", None)
+    if not isinstance(model, str) or not model:
+        raise LMConfigurationError("configure_lm needs an LM object with a nonempty model name")
+    return model
+
+
+def _merge(target: dict[str, Any], name: str, declaration: dict[str, Any]) -> None:
+    if name in target and target[name] != declaration:
+        raise LMConfigurationError(f"conflicting LM capability declarations for binding {name!r}")
+    target[name] = declaration
+
+
+def configure_lm(
+    lm: Any,
+    *,
+    supported_params: list[str] | None = None,
+    supports_response_schema: bool = False,
+) -> None:
+    """Declare capabilities once for an LM object or explicit hosted binding name.
+
+    Every binding created from the same object shares its declaration. Separate
+    objects remain independent, even when their settings match. Packaged
+    declarations retain their resolved model and cannot follow a model change.
+    """
+    hints = dict(
+        _validate_lm_capabilities(
+            {
+                "binding": {
+                    "supported_params": supported_params if supported_params is not None else [],
+                    "supports_response_schema": supports_response_schema,
+                }
+            }
+        )["binding"]
+    )
+    if isinstance(lm, str):
+        if not _authored:
+            raise LMConfigurationError(
+                "named LM declarations are supported only inside authored programs; pass an LM object"
+            )
+        _merge(_names, _name(lm), hints)
+        return
+    model = _model(lm)
+    declared = _object_declaration(lm)
+    if declared is not None and declared != (model, hints):
+        raise LMConfigurationError("conflicting LM capability declarations for the same LM object")
+    lm._cmpnd_lm_capabilities = (id(lm), model, hints)
+    if _authored and not any(obj is lm for obj in _objects):
+        _objects.append(lm)
+
+
+def restore(declarations: object) -> None:
+    """Load model-pinned declarations from a packaged artifact."""
+    if not isinstance(declarations, dict):
+        raise LMConfigurationError("lm_capabilities must map binding names to declarations")
+    for name, declaration in declarations.items():
+        _name(name)
+        if not isinstance(declaration, dict):
+            raise LMConfigurationError(f"lm_capabilities[{name!r}] must be a capability declaration")
+        model = _model(declaration.get("model"))
+        hints = _validate_lm_capabilities({name: {k: v for k, v in declaration.items() if k != "model"}})[name]
+        _merge(_restored, name, {"model": model, **hints})
+
+
+def resolve(bindings: dict[str, Any], *, require_all: bool = True) -> dict[str, Any]:
+    """Resolve aliases and names, rejecting conflicts before any LM call.
+
+    Packaging a program alone may defer named optimization declarations. The
+    optimization package resolves the full set and rejects names it cannot bind.
+    """
+    result: dict[str, Any] = {}
+    for name, lm in bindings.items():
+        _name(name)
+        if name not in _restored and name not in _names and _object_declaration(lm) is None:
+            continue
+        model = _model(lm)
+        if name in _restored:
+            stored = _restored[name]
+            if stored["model"] != model:
+                raise LMConfigurationError(
+                    f"model changed for binding {name!r}; configure the replacement with a new declaration"
+                )
+            _merge(result, name, dict(stored))
+        if name in _names:
+            _merge(result, name, {"model": model, **_names[name]})
+        declaration = _object_declaration(lm)
+        if declaration is not None:
+            declared_model, hints = declaration
+            if declared_model != model:
+                raise LMConfigurationError(
+                    f"model changed for binding {name!r}; configure the replacement with a new declaration"
+                )
+            _merge(result, name, {"model": model, **hints})
+    if require_all:
+        unresolved = sorted((_names.keys() | _restored.keys()) - bindings.keys())
+        if unresolved:
+            raise LMConfigurationError(f"unresolved LM capability binding declarations: {', '.join(unresolved)}")
+        if any(not any(obj is lm for lm in bindings.values()) for obj in _objects):
+            raise LMConfigurationError(
+                "unresolved LM object capability declaration; pass that object as a hosted binding"
+            )
+    return result
+
+
+def resolve_call(identities: dict[str, Any], models: dict[str, Any]) -> dict[str, Any]:
+    """Resolve the objects loaded for one call against its granted model names."""
+    declarations = resolve(identities, require_all=False)
+    unresolved = _names.keys() - identities.keys() - _restored.keys()
+    if unresolved:
+        raise LMConfigurationError(f"unresolved LM capability binding declarations: {', '.join(sorted(unresolved))}")
+    for obj in _objects:
+        if not any(obj is value for value in identities.values()):
+            raise LMConfigurationError(
+                "unresolved LM object capability declaration; pass that object as a hosted binding"
+            )
+    for name, model in models.items():
+        if name in declarations and declarations[name]["model"] != model:
+            raise LMConfigurationError(
+                f"model changed for binding {name!r}; configure the replacement with a new declaration"
+            )
+    return {name: declaration for name, declaration in declarations.items() if name in models}

{cmpnd-0.27.1 → cmpnd-0.27.2}/cmpnd/optimization.py

@@ -658,6 +658,7 @@ def _build_optimization_bundle(
     valset: list[Any],
     metric: Callable[..., Any],
     proposer: Callable[..., Any] | None = None,
+    lm_capabilities: dict[str, Any] | None = None,
 ) -> bytes:
     """Build the optimization-bundle ZIP: ``trainset.ndjson`` +
     ``valset.ndjson`` (one flattened example per line) + ``metric.py`` (the
@@ -679,6 +680,13 @@ def _build_optimization_bundle(
                 "runs in a sandbox from its own source, so there is nothing else to send."
             )
 
+    if lm_capabilities:
+        preamble = "from cmpnd.lm_configuration import restore as _restore_lms\n"
+        preamble += f"_restore_lms({lm_capabilities!r})\n"
+        metric_source += "\n" + preamble
+        if proposer_source is not None:
+            proposer_source += "\n" + preamble
+
     def _ndjson(rows: list[Any]) -> str:
         return "\n".join(json.dumps(_example_to_dict(r)) for r in rows) + "\n"
 
@@ -919,7 +927,15 @@ def optimize(
 
     cfg = configuration.require_config()
 
-    bundle = _build_optimization_bundle(trainset, valset, metric, proposer)
+    from . import lm_configuration
+
+    bindings = {name: entry["model"] for name, entry in (config.get("lms") or {}).items()}
+    bindings.update(lms or {})
+    default_lm = packaging._extract_lm_object(program)
+    if default_lm is not None:
+        bindings["default-lm"] = default_lm
+    declarations = lm_configuration.resolve(bindings)
+    bundle = _build_optimization_bundle(trainset, valset, metric, proposer, declarations)
 
     if deployment_id is None:
         deployment_id = str(deployment.deploy(program, metric=metric))
@@ -1083,9 +1099,18 @@ def optimize_authored(
         _refuse_conflicting_members(cfg, deployment_id, prepared.members)
         facts = _deployment_signature_facts(cfg, deployment_id)
 
+    from . import lm_configuration
+
+    bindings = {name: entry["model"] for name, entry in (config.get("lms") or {}).items()}
+    bindings.update(lms or {})
+    if facts is not None and facts.litellm_model:
+        bindings["default-lm"] = facts.litellm_model
+    declarations = lm_configuration.resolve(bindings)
+    bundle = _authored_capabilities_bundle(prepared.optimization_bundle, declarations)
+
     best_deployment_id, best_score = _run_steps(
         cfg,
-        prepared.optimization_bundle,
+        bundle,
         deployment_id,
         optimizer=optimizer,
         config=config,
@@ -1110,6 +1135,28 @@ def optimize_authored(
     )
 
 
+def _authored_capabilities_bundle(bundle: bytes, declarations: dict[str, Any]) -> bytes:
+    """Add caller-resolved bindings without changing any authored source bytes."""
+    if not declarations:
+        return bundle
+    from .lm_configuration import LMConfigurationError
+
+    output = io.BytesIO()
+    with zipfile.ZipFile(io.BytesIO(bundle)) as archive:
+        manifest = json.loads(archive.read("manifest.json"))
+        merged = dict(manifest.get("lm_capabilities") or {})
+        for name, declaration in declarations.items():
+            if name in merged and merged[name] != declaration:
+                raise LMConfigurationError(f"conflicting LM capability declarations for binding {name!r}")
+            merged[name] = declaration
+        manifest["lm_capabilities"] = merged
+        with zipfile.ZipFile(output, "w", zipfile.ZIP_DEFLATED) as updated:
+            for member in archive.infolist():
+                body = json.dumps(manifest).encode() if member.filename == "manifest.json" else archive.read(member)
+                updated.writestr(member, body)
+    return output.getvalue()
+
+
 def _deployment_signature_facts(cfg: configuration.Config, deployment_id: str) -> authored.ProgramFacts | None:
     """Read an existing deployment's signature without making metadata a run prerequisite."""
     from . import identity
@@ -1120,7 +1167,8 @@ def _deployment_signature_facts(cfg: configuration.Config, deployment_id: str) -
             response = client.get(f"{cfg.endpoint}/api/v1/deployments/{deployment_id}", headers=headers)
             if not response.is_success:
                 return None
-            value = response.json().get("program_signature_hash")
+            deployment_row = response.json()
+            value = deployment_row.get("program_signature_hash")
             if value is None or value == "":
                 return None
             # Deployment responses use the 16-digit hex display form. Signature routes
@@ -1133,6 +1181,7 @@ def _deployment_signature_facts(cfg: configuration.Config, deployment_id: str) -
             row = response.json()
             return authored.ProgramFacts(
                 program_signature_hash=signature_hash,
+                litellm_model=deployment_row.get("litellm_model"),
                 signature_name=row.get("signature_name"),
                 input_fields=row.get("input_fields") or [],
                 output_fields=row.get("output_fields") or [],

{cmpnd-0.27.1 → cmpnd-0.27.2}/cmpnd/packaging.py

@@ -34,12 +34,11 @@ if TYPE_CHECKING:
     import dspy
 
 
-def _extract_lm_state(module: dspy.Module) -> dict[str, typing.Any] | None:
-    """Extract LM config from module predictors or global dspy.settings.
+def _extract_lm_object(module: dspy.Module) -> dspy.LM | None:
+    """Find the program's LM object without losing its identity.
 
-    Walks the module tree looking for any object with a non-None ``.lm``
-    attribute, calls ``.dump_state()`` on the first one found. Falls back
-    to ``dspy.settings.lm`` if no module-level LM exists.
+    Walk the module tree for a non-None ``.lm`` attribute, then fall back to
+    ``dspy.settings.lm`` if no module-level LM exists.
     """
     seen: set[int] = set()
 
@@ -62,9 +61,12 @@ def _extract_lm_state(module: dspy.Module) -> dict[str, typing.Any] | None:
     lm = _find_lm(module)
     if lm is None:
         lm = dspy.settings.lm
-    if lm is not None and hasattr(lm, "dump_state"):
-        return lm.dump_state()
-    return None
+    return lm
+
+
+def _extract_lm_state(module: dspy.Module) -> dict[str, typing.Any] | None:
+    lm = _extract_lm_object(module)
+    return lm.dump_state() if lm is not None and hasattr(lm, "dump_state") else None
 
 
 class ImportEntry(typing.NamedTuple):
@@ -1248,7 +1250,12 @@ def generate_source_zip(
         if metric_source is not None:
             metric_filename = "metric_source.py"
 
+    from . import lm_configuration
+
+    lm = _extract_lm_object(module)
+    declarations = lm_configuration.resolve({"default-lm": lm} if lm is not None else {}, require_all=False)
     manifest = {
+        "lm_capabilities": declarations,
         "dependency_versions": {
             "python": platform.python_version(),
             "dspy": dspy.__version__,

{cmpnd-0.27.1 → cmpnd-0.27.2}/docs/sdk-instrumentation.md

@@ -19,7 +19,7 @@ cmpnd.configure(api_key="ck_...", project="my-app")
 cmpnd.auto_instrument()
 ```
 
-- **`cmpnd.configure()`** — `python-sdk/cmpnd/config.py:42`. Reads `api_key` and `endpoint` from args or `CMPND_API_KEY` / `CMPND_ENDPOINT` env vars, builds a `Config` dataclass (`config.py:12`), and stores it in a `ContextVar`. 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.
+- **`cmpnd.configure()`** — `cmpnd/configuration.py`. Reads `api_key` and `endpoint` from args or `CMPND_API_KEY` / `CMPND_ENDPOINT` 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.
 - **`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.
 
 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`.
@@ -30,6 +30,49 @@ For an explicit, scoped alternative that traces only the programs you run throug
 
 ---
 
+## Hosted LM capabilities
+
+Declare hosted capabilities once for an LM object. Inside an authored program,
+you can also name an explicit binding.
+Every binding created from the same object shares its declaration. Separate LM
+objects remain independent, even when their model names and sampling match.
+
+```python
+import cmpnd
+import dspy
+
+lm = dspy.LM("provider/model", reasoning_effort="low")
+cmpnd.configure_lm(
+    lm,
+    supported_params=["response_format"],
+    supports_response_schema=True,
+)
+dspy.configure(lm=lm, adapter=dspy.JSONAdapter())
+```
+
+The object form follows the object into `default-lm` or the named `lms` passed to
+optimization. The string form names a binding such as `default-lm`, `judge`, or
+an authored proposer's LM. Call that form inside the authored source file, for
+example `cmpnd.configure_lm("judge", supported_params=["response_format"])`.
+Notebook and other live SDK callers pass LM objects. Object declarations belong
+to those objects and apply only to workflows that use them, so independent
+optimizations can run sequentially in one process.
+Each binding has one model within a program or run.
+Identical declarations are idempotent. Conflicting declarations and names that
+an optimization cannot resolve raise an error before inference.
+
+The SDK records resolved declarations in the program and optimization bundles.
+Execute, metric, and authored proposer turns use those snapshots. A declaration
+retains its resolved model, so replacing that model requires a new declaration.
+An LM object's identity stays local to Python. The bundle carries its resolved
+binding names and capabilities.
+
+List `response_format` to request JSON-object mode. Add
+`supports_response_schema=True` when the model and its configured provider
+endpoint accept JSON schemas. Undeclared bindings keep prompt-only JSON. These
+hints do not add a format the provider cannot accept or change local DSPy's
+capability lookup.
+
 ## The callback
 
 `python-sdk/cmpnd/callback.py` implements `CmpndCallback`, which satisfies `dspy.utils.callback.BaseCallback` without inheriting it — `callback.py` must import on the standard library alone (`tests/test_import_weight.py`), so it cannot import dspy to get a base class. DSPy calls its hook methods synchronously on whatever thread is executing the module. The callback owns no long-lived state beyond a per-call span builder map; everything trace/span related flows through context vars (see next section).

{cmpnd-0.27.1 → cmpnd-0.27.2}/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.27.1"
+version = "0.27.2"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"