cmpnd 0.43.1__tar.gz → 0.45.0__tar.gz

{cmpnd-0.43.1 → cmpnd-0.45.0}/PKG-INFO

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

{cmpnd-0.43.1 → cmpnd-0.45.0}/cmpnd/__init__.py

@@ -13,6 +13,7 @@ Usage:
 """
 
 import importlib.metadata
+from typing import TYPE_CHECKING
 
 from . import authored, programs, traces
 from ._http import ApiError
@@ -45,7 +46,7 @@ from .deployment_runs import (
 )
 from .execution import DeployedProgram, RetryableProviderError, deployment_run_id, execute
 from .exporter import flush_exporter, shutdown_exporter
-from .lm_configuration import configure_lm
+from .lm_configuration import SystemOne, configure_lm
 from .mcp_servers import (
     Bearer,
     McpToolReference,
@@ -55,12 +56,15 @@ from .mcp_servers import (
     mcp_tools,
 )
 from .models import SpanBuilder, SpanType, TraceBuilder, TraceStatus
+
+if TYPE_CHECKING:
+    # Loaded on first use by __getattr__ below, because their module imports dspy.
+    from .named_programs import Program, program
 from .optimization import (
     OptimizeError,
     OptimizeFailed,
     optimize,
 )
-from .programs import Program
 
 try:
     __version__ = importlib.metadata.version("cmpnd")
@@ -76,6 +80,7 @@ __all__ = [
     # Configuration
     "configure",
     "configure_lm",
+    "SystemOne",
     "get_config",
     "require_config",
     # Main callback
@@ -103,6 +108,7 @@ __all__ = [
     "programs",
     # A program declared by name
     "Program",
+    "program",
     "authored",
     "ApiError",
     # Types
@@ -253,3 +259,15 @@ def de_instrument() -> None:
 def _mcp_tool(declaration):  # pyright: ignore[reportUnusedFunction] -- generated bundles call this hook
     """Keep generated declarations importable outside a worker without granting access."""
     return declaration
+
+
+def __getattr__(name: str):  # noqa: ANN202 — PEP 562 module attribute hook
+    """Load ``Program`` and ``program`` on first use, because their module imports dspy.
+
+    ``import cmpnd`` stays free of dspy until a caller asks for one of them.
+    """
+    if name in ("Program", "program"):
+        from . import named_programs
+
+        return getattr(named_programs, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{cmpnd-0.43.1 → cmpnd-0.45.0}/cmpnd/callback.py

@@ -383,6 +383,10 @@ def _lm15_cache_hit(entry: Any, response: Any) -> bool | None:
 
 def _usage_dialect(instance: Any, usage: Any) -> str | None:
     """Name the response surface only when its shape establishes one."""
+    # A decision client (DSPy's `TypeSafe`) speaks System One. Its usage names chat's token
+    # fields, so the shape alone would misname it. DSPy dispatches on the same flag.
+    if getattr(instance, "supports_decision_requests", False) is True:
+        return "system_one"
     model_type = _text_field(instance, "model_type")
     if model_type == "responses":
         return "responses"
@@ -1489,7 +1493,8 @@ class _LMMixin(_CallbackBase):
             observation.usage_dialect = _usage_dialect(instance, usage)
             if observation.usage_dialect in {"chat_completions", "responses"}:
                 observation.prompt_inclusion = "includes_cache_reads"
-            elif observation.usage_dialect == "converse":
+            elif observation.usage_dialect in {"converse", "system_one"}:
+                # System One serves nothing from a cache, so its prompt is all fresh input.
                 observation.prompt_inclusion = "excludes_cache_reads"
 
             if usage_reported and usage is not None:

{cmpnd-0.43.1 → cmpnd-0.45.0}/cmpnd/client.py

@@ -29,7 +29,7 @@ import dataclasses
 import os
 from typing import Any, Literal
 
-from . import _assessments, _deployments, _exporter_pool, _traces, _valsets, callback, configuration, programs
+from . import _assessments, _deployments, _exporter_pool, _traces, _valsets, callback, configuration
 from .deployment_metadata import DeploymentSignatureResponse
 
 
@@ -106,28 +106,44 @@ class Client:
 
     # -- scoped runs ------------------------------------------------------
 
+    @staticmethod
+    def _as_program(obj: Any) -> Any:
+        """``obj`` when it is a ``cmpnd.Program``, else None."""
+        from . import named_programs
+
+        return obj if isinstance(obj, named_programs.Program) else None
+
     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.
+        A ``cmpnd.Program`` runs on its own LM, which an enclosing program's LM would
+        override, and declares its name. Any other module declares no name and no
+        program LM, which also clears the ones 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}
+        from . import named_programs
+
+        named = self._as_program(program)
+        if named is not None:
+            return {
+                "lm": named.lm,
+                named_programs.PROGRAM_LM_SETTING: named.lm,
+                callback.DECLARED_PROGRAM_SETTING: named.name,
+            }
+        return {named_programs.PROGRAM_LM_SETTING: None, callback.DECLARED_PROGRAM_SETTING: None}
 
     def run_program(self, program: Any, **inputs: Any) -> Any:
         """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.
+        on its own LM, and its traces go to the program with its name. A program adds
+        no span of its own, so a program and its module run plain record the same
+        structure.
         """
         self._check_active()
         import dspy
 
-        module = program.module if isinstance(program, programs.Program) else program
         with dspy.context(callbacks=self._scoped_callbacks(), **self._declared(program)):
-            return module(**inputs)
+            return program(**inputs)
 
     def run_optimization(
         self,
@@ -150,14 +166,22 @@ class Client:
         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.
+        ``student`` is a ``cmpnd.Program`` or a plain DSPy module. The optimizer
+        works on a ``Program``'s module, on the program's LM, and its rollouts and run
+        record go to the program with its name. The result is a copy of the student,
+        of the same class and with the same name and LM, holding the optimized module.
         """
         self._check_active()
+        import copy
+
         import dspy
 
-        module = student.module if isinstance(student, programs.Program) else student
+        from . import named_programs
+
+        named = self._as_program(student)
+        whole = named is not None and named_programs.runs_itself(named)
+        module = named.module if named is not None and not whole else student
+        result: Any = None
         with dspy.context(callbacks=self._scoped_callbacks(), **self._declared(student)):
             try:
                 if isinstance(optimizer, dspy.GEPA):
@@ -167,15 +191,22 @@ class Client:
                         trainset=trainset,
                         valset=valset,
                         kwargs=kwargs,
-                        declared_name=student.name if isinstance(student, programs.Program) else None,
+                        declared_name=named.name if named is not None 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
+        if named is None:
+            return result
+        if whole and isinstance(result, type(named)):
+            # The optimizer worked on the program itself and returned a copy of it, which
+            # deep-copied the LM; the copy gets the student's back.
+            result.lm = named.lm
+            return result
+        optimized = copy.copy(named)
+        optimized.module = result
+        return optimized
 
     # -- data surface (flat verb-object over the client's credentials) -----
     #

{cmpnd-0.43.1 → cmpnd-0.45.0}/cmpnd/lm_configuration.py

@@ -9,11 +9,25 @@ 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."""
+class LMCapabilities(TypedDict, total=False):
+    """Explicit adapter hints for a hosted model, independent of its provider.
+
+    ``dialect`` is present only for a System One binding, which :class:`SystemOne`
+    writes. Absent, the binding is a chat model.
+    """
 
     supported_params: list[str]
     supports_response_schema: bool
+    dialect: str
+
+
+# The wire protocol a binding's model speaks, named for the protocol and never for a
+# provider or a client library: a chat model answers chat completions, and a System One
+# model (TypeSafe's System One protocol, which other providers serve too) answers a set
+# of questions about a state.
+CHAT_COMPLETIONS = "chat_completions"
+SYSTEM_ONE = "system_one"
+_DIALECTS = frozenset({CHAT_COMPLETIONS, SYSTEM_ONE})
 
 
 def _validate_lm_capabilities(value: object) -> dict[str, LMCapabilities]:
@@ -27,7 +41,7 @@ def _validate_lm_capabilities(value: object) -> dict[str, LMCapabilities]:
             )
         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"}
+        unknown = declaration.keys() - {"supported_params", "supports_response_schema", "dialect"}
         if unknown:
             raise LMConfigurationError(f"lm_capabilities[{binding!r}] has unknown fields: {sorted(unknown, key=str)}")
         params = declaration.get("supported_params", [])
@@ -38,11 +52,24 @@ def _validate_lm_capabilities(value: object) -> dict[str, LMCapabilities]:
         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")
+        dialect = declaration.get("dialect", CHAT_COMPLETIONS)
+        if dialect not in _DIALECTS:
+            raise LMConfigurationError(
+                f"lm_capabilities[{binding!r}].dialect must be one of {sorted(_DIALECTS)} (got {dialect!r})"
+            )
+        if dialect == SYSTEM_ONE and (params or schema):
+            raise LMConfigurationError(
+                f"lm_capabilities[{binding!r}] is a System One binding, which takes no sampling "
+                "parameters and no response schema"
+            )
         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}
+        hints: LMCapabilities = {"supported_params": list(dict.fromkeys(params)), "supports_response_schema": schema}
+        if dialect == SYSTEM_ONE:
+            hints["dialect"] = SYSTEM_ONE
+        result[binding] = hints
     return result
 
 
@@ -122,6 +149,11 @@ def configure_lm(
             )
         _merge(_names, _name(lm), hints)
         return
+    _declare(lm, hints)
+
+
+def _declare(lm: Any, hints: dict[str, Any]) -> None:
+    """Attach a declaration to one LM object, shared by every binding made from it."""
     model = _model(lm)
     declared = _object_declaration(lm)
     if declared is not None and declared != (model, hints):
@@ -131,6 +163,38 @@ def configure_lm(
         _objects.append(lm)
 
 
+class SystemOne:
+    """A System One decision model, for a run's ``lms``.
+
+    A System One model answers a set of questions about a state instead of continuing a
+    conversation: TypeSafe's Jev, or another endpoint serving the same schema. A hosted
+    judge built on ``dspy.experimental.TypeSafe`` runs against the run's System One
+    binding without naming a key or a URL::
+
+        cmpnd.optimize(..., lms={"judge": cmpnd.SystemOne("typesafe/jev-latest")})
+
+    ``model`` is a platform model id: the prefix names the organization's sealed
+    credential, and the rest is the model at that credential's endpoint. Writing the
+    binding this way is the only thing that makes it a System One binding; a model name
+    on its own never does.
+    """
+
+    def __init__(self, model: object):
+        if not isinstance(model, str) or not model.strip():
+            raise ValueError(f"cmpnd.SystemOne needs a model id such as 'typesafe/jev-latest' (got {model!r})")
+        credential, _, name = model.strip().partition("/")
+        if not credential or not name:
+            raise ValueError(
+                f"cmpnd.SystemOne({model!r}) names no credential: write the model as "
+                "'<credential>/<model>', for example 'typesafe/jev-latest'"
+            )
+        self.model = model.strip()
+        _declare(self, {"supported_params": [], "supports_response_schema": False, "dialect": SYSTEM_ONE})
+
+    def __repr__(self) -> str:
+        return f"cmpnd.SystemOne({self.model!r})"
+
+
 def restore(declarations: object) -> None:
     """Load model-pinned declarations from a packaged artifact."""
     if not isinstance(declarations, dict):

cmpnd-0.45.0/cmpnd/named_programs.py

@@ -0,0 +1,274 @@
+"""Programs declared by name: ``cmpnd.Program`` and the ``@cmpnd.program`` decorator.
+
+A ``cmpnd.Program`` is a DSPy module with two more things: the name of the program it
+is, and the LM it runs on. It holds the module that does the work as a submodule, so
+it nests inside a larger DSPy program like any other module. The name is the
+program's handle: traces from a ``cmpnd.Client`` run of it go to the program with that
+name in the caller's organization, which the platform creates on first use.
+
+``@cmpnd.program(name)`` is a shorter way to define one. Above a ``dspy.Module`` class,
+it returns a ``cmpnd.Program`` subclass of the same name, so that
+
+    @cmpnd.program("capital-qa")
+    class CapitalQA(dspy.Module): ...
+
+    qa = CapitalQA(lm=lm)
+
+builds the same program as ``cmpnd.Program("capital-qa", module=<the class as
+written>(), lm=lm)``.
+
+When programs nest, the outermost program's LM wins, so a caller can always choose the
+model from outside. Each program records the LM it applied in a DSPy settings key, and
+a program inside applies its own LM only when the key is unset.
+
+A program adds no span to a trace. Calling one calls its module directly, past the
+``dspy.Module.__call__`` that traces a module, so a program, a program that wraps
+another, and a program nested in a larger module all trace as the module they hold.
+
+This module imports dspy, so ``cmpnd`` loads it only when a caller first uses
+``cmpnd.Program`` or ``cmpnd.program``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import inspect
+import weakref
+from collections.abc import Callable
+from typing import Any
+
+import dspy
+from dspy.clients import base_lm  # pyright: ignore[reportMissingTypeStubs]  # dspy re-exports BaseLM untyped
+
+from . import programs
+
+# The DSPy settings key that holds the LM the outermost running program applied.
+PROGRAM_LM_SETTING = "cmpnd_program_lm"
+
+# The source of each class @cmpnd.program decorated, read when it was decorated. The
+# class's qualified name changes then (see `program`), and before Python 3.13
+# `inspect.getsource` finds a class by that name.
+_DECLARED_SOURCE: weakref.WeakKeyDictionary[type, str] = weakref.WeakKeyDictionary()
+
+
+def _check_lm(lm: Any, usage: str) -> None:
+    if not isinstance(lm, base_lm.BaseLM):
+        raise TypeError(f"A program needs an LM such as dspy.LM(...), not {type(lm).__name__}: {usage}")
+
+
+def _check_module(module: object) -> None:
+    if not isinstance(module, dspy.Module):
+        raise TypeError(f"A Program needs a DSPy module, not {type(module).__name__}")
+
+
+def _without_self(signature: inspect.Signature) -> inspect.Signature:
+    return signature.replace(
+        parameters=list(signature.parameters.values())[1:], return_annotation=inspect.Signature.empty
+    )
+
+
+_ModuleMeta: Any = type(dspy.Module)  # DSPy's metaclass, which every dspy.Module uses
+
+
+class _ProgramMeta(_ModuleMeta):
+    """DSPy's metaclass, with each program class's constructor arguments for help().
+
+    DSPy's metaclass defines ``__call__``, which hides a class's ``__init__`` from
+    ``inspect.signature``. A property here is read by ``inspect`` and not listed by
+    ``help()``.
+    """
+
+    @property
+    def __signature__(cls) -> inspect.Signature:
+        return _without_self(inspect.signature(cls.__init__))
+
+
+class Program(dspy.Module, metaclass=_ProgramMeta):
+    """A DSPy module with a program name and the LM it runs on.
+
+    A program holds the DSPy module that does the work. Run it through a
+    ``cmpnd.Client``, and its traces go to the program with its name in your
+    organization:
+
+        >>> 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?")
+
+    ``@cmpnd.program(name)`` is a shorter way to define a program on a class you
+    write. Use this constructor when one class serves several programs, when you
+    cannot edit the class, or when its constructor already takes ``lm``.
+
+    Attributes:
+        name: The program's name: 1 to 64 letters, digits, ".", "_" or "-", starting
+            with a letter or digit and not with "p_". Programs in one organization
+            that share a name share a history.
+        module: The DSPy module that does the work. It is a submodule of the program,
+            so ``named_predictors()`` and optimizers find its predictors, also when
+            the program is inside a larger DSPy module.
+        lm: The LM the program runs on. When programs nest, the outermost program's
+            LM wins, so a caller can choose the model from outside.
+
+    Declaring a program makes no network call. The platform creates the program
+    the first time a client sends one of its traces. Calling a program directly
+    runs it on its LM and records nothing under its name.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        module: dspy.Module,
+        lm: dspy.BaseLM,  # pyright: ignore[reportAttributeAccessIssue]  # dspy re-exports BaseLM untyped
+    ) -> None:
+        """Declare a program named ``name`` that runs ``module`` on ``lm``."""
+        super().__init__()
+        self.name = programs.validate_program_name(name)
+        _check_module(module)
+        _check_lm(lm, "cmpnd.Program(name, module=..., lm=dspy.LM(...))")
+        self.module: Any = module
+        self.lm = lm
+
+    def _lm_context(self) -> Any:
+        """A context that applies this program's LM, unless an enclosing program applied one."""
+        if dspy.settings.get(PROGRAM_LM_SETTING) is not None:
+            return contextlib.nullcontext()
+        return dspy.context(lm=self.lm, **{PROGRAM_LM_SETTING: self.lm})
+
+    def __call__(self, *args: Any, **inputs: Any) -> dspy.Prediction:
+        """Run the module on this program's LM, and return its prediction.
+
+        The program makes no span of its own. ``dspy.Module.__call__`` makes a span for
+        each module it runs, and this method calls the module directly instead, so
+        wrapped and nested programs add no layers to a trace. A subclass that overrides
+        ``forward`` goes through ``dspy.Module.__call__`` and traces as itself.
+        """
+        with self._lm_context():
+            if runs_itself(self):
+                return super().__call__(*args, **inputs)
+            return self.module(*args, **inputs)
+
+    async def acall(self, *args: Any, **inputs: Any) -> dspy.Prediction:
+        """Run the module asynchronously, with no span for the program itself, as ``__call__`` does."""
+        with self._lm_context():
+            if runs_itself(self):
+                return await getattr(super(), "acall")(*args, **inputs)  # dspy's Module.acall is untyped
+            return await self.module.acall(*args, **inputs)
+
+    def forward(self, *args: Any, **inputs: Any) -> dspy.Prediction:
+        """Run the module on this program's LM. A subclass may override this to add behavior."""
+        with self._lm_context():
+            return self.module(*args, **inputs)
+
+    async def aforward(self, *args: Any, **inputs: Any) -> dspy.Prediction:
+        """Run the module asynchronously on this program's LM, as ``forward`` does."""
+        with self._lm_context():
+            return await self.module.acall(*args, **inputs)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.name!r}, lm={getattr(self.lm, 'model', self.lm)!r})"
+
+
+def _with_lm(signature: inspect.Signature) -> inspect.Signature:
+    """``signature`` with a required keyword ``lm`` added before any ``**kwargs``."""
+    parameters = list(signature.parameters.values())
+    at = next((i for i, p in enumerate(parameters) if p.kind is inspect.Parameter.VAR_KEYWORD), len(parameters))
+    parameters.insert(at, inspect.Parameter("lm", inspect.Parameter.KEYWORD_ONLY, annotation="dspy.BaseLM"))
+    return signature.replace(parameters=parameters)
+
+
+def runs_itself(program: Program) -> bool:
+    """Whether running ``program`` means running its own code, not only its module.
+
+    A subclass that overrides ``forward`` or ``aforward`` adds behavior around its
+    module, so calling it runs that code as a traced module, and a client optimizes the
+    program itself. Any other program only runs its module, so its trace's root and
+    structure match the module run plain.
+    """
+    cls = type(program)
+    return cls.forward is not Program.forward or cls.aforward is not Program.aforward
+
+
+def program(name: str) -> Callable[[type[dspy.Module]], type[Program]]:
+    """Declare a program on a DSPy module class, where the class is defined.
+
+    ``@cmpnd.program(name)`` is a shorter way to write the ``cmpnd.Program``
+    constructor. Above a ``dspy.Module`` class, it returns a ``cmpnd.Program``
+    subclass of the same name. That subclass takes the class's own constructor
+    arguments and a required keyword ``lm``, and builds the class as written as the
+    program's ``module``:
+
+        >>> @cmpnd.program("capital-qa")
+        ... class CapitalQA(dspy.Module):
+        ...     def __init__(self):
+        ...         super().__init__()
+        ...         self.answer = dspy.Predict("question -> answer")
+        ...
+        ...     def forward(self, question):
+        ...         return self.answer(question=question)
+        >>> qa = CapitalQA(lm=dspy.LM("openai/gpt-5-mini"))
+        >>> with cmpnd.Client() as client:
+        ...     client.run_program(qa, question="What is the capital of France?")
+
+    ``qa`` is the same program as ``cmpnd.Program("capital-qa", module=<CapitalQA as
+    written>(), lm=...)``, and the class's attributes are on ``qa.module``.
+
+    A decorated class has one name. Use the ``cmpnd.Program`` constructor when one
+    class serves several programs, when you cannot edit the class, or when its
+    constructor already takes ``lm``. ``help(cmpnd.Program)`` gives the name rules
+    and how a program runs.
+    """
+    programs.validate_program_name(name)
+
+    def decorate(module_class: Any) -> Any:
+        if not (isinstance(module_class, type) and issubclass(module_class, dspy.Module)):
+            raise TypeError("@cmpnd.program() decorates a dspy.Module class")
+        if issubclass(module_class, Program):
+            raise TypeError(f"{module_class.__name__} is already a program; subclass it instead of decorating it")
+        if "lm" in inspect.signature(module_class.__init__).parameters:
+            raise TypeError(
+                f"{module_class.__name__}.__init__ already takes lm, so it cannot be decorated. "
+                "Wrap an instance instead: cmpnd.Program(name, module=..., lm=...)"
+            )
+        try:
+            _DECLARED_SOURCE[module_class] = inspect.getsource(module_class)
+        except (OSError, TypeError):
+            pass  # no source to read, as in a bare REPL; a deploy then fails as it would undecorated
+
+        def __init__(self: Any, *args: Any, lm: Any = None, **kwargs: Any) -> None:
+            # lm has a default only so that a missing LM gets the message below.
+            _check_lm(lm, f"{module_class.__name__}(..., lm=dspy.LM(...))")
+            Program.__init__(self, name, module=module_class(*args, **kwargs), lm=lm)
+
+        qualname = module_class.__qualname__
+        signature = _with_lm(inspect.signature(module_class.__init__))
+        __init__.__qualname__ = f"{qualname}.__init__"
+        __init__.__module__ = module_class.__module__
+        __init__.__doc__ = f"Build a {module_class.__name__} as the module of a program named {name!r}."
+        setattr(__init__, "__signature__", signature)
+        doc = f"A cmpnd.Program named {name!r}, which runs {module_class.__name__} as written."
+        if module_class.__doc__:
+            doc += "\n\n" + inspect.cleandoc(module_class.__doc__)
+        decorated = _ProgramMeta(
+            module_class.__name__,
+            (Program,),
+            {
+                "__init__": __init__,
+                "__module__": module_class.__module__,
+                "__qualname__": qualname,
+                "__doc__": doc,
+                "_cmpnd_module": module_class,
+            },
+        )
+        # The decorated class takes the class's name in its module, so pickle would find
+        # it, not the class as written, when it looks a module instance's class up by
+        # name. The class as written moves under the decorated one, where pickle finds it.
+        # The attribute's single leading underscore keeps it out of help().
+        module_class.__qualname__ = f"{qualname}._cmpnd_module"
+        return decorated
+
+    return decorate
+
+
+def declared_source(cls: type) -> str | None:
+    """The source of a class ``@cmpnd.program`` decorated, read before it was renamed."""
+    return _DECLARED_SOURCE.get(cls)

{cmpnd-0.43.1 → cmpnd-0.45.0}/cmpnd/optimization.py

@@ -462,6 +462,23 @@ def _lms_config(config: dict[str, Any], lms: Any) -> None:
         if isinstance(lm, str):
             declared[name] = {"model": lm}
             continue
+        from .lm_configuration import SystemOne
+
+        if isinstance(lm, SystemOne):
+            # A System One model takes no sampling, and its declaration (which says it
+            # is one) travels in the bundle rather than on the wire.
+            declared[name] = {"model": lm.model}
+            continue
+        if getattr(lm, "supports_decision_requests", False):
+            # dspy.experimental.TypeSafe, or a client like it: it carries a key and a URL
+            # rather than the name of a sealed credential, so the platform has nothing to
+            # resolve. Duck-typed so this module never imports dspy at scope.
+            raise ValueError(
+                f"{subject} is a {type(lm).__name__} client, which names a key and a URL rather "
+                f"than a credential. Bind the model with cmpnd.SystemOne, for example "
+                f"lms={{{name!r}: cmpnd.SystemOne('typesafe/jev-latest')}}; a judge that builds "
+                f"its own {type(lm).__name__} runs against that binding when hosted"
+            )
         model = _lm_model(lm, subject)
         _refuse_credential_on(lm, model, subject)
         entry: dict[str, Any] = {"model": model}