cmpnd 0.58.0__tar.gz → 0.59.0__tar.gz

{cmpnd-0.58.0 → cmpnd-0.59.0}/PKG-INFO

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

{cmpnd-0.58.0 → cmpnd-0.59.0}/cmpnd/cli/commands/top.py

@@ -890,6 +890,34 @@ def _program_args(args: Any, verb: str, *, needs_name: bool = True) -> str | Non
     return name
 
 
+class _CredentialLookup:
+    """Turn a credential name a flag gave into the organization's ``cmpnd.Credential``.
+
+    Every command that takes a credential name looks it up here, before it stages or
+    sends anything. The lookup is ``cmpnd.credentials.get``, the line a Python caller
+    writes, so a mistyped name fails on the command line with the organization's names
+    and the nearest one. Serve checks the name again when the deploy or run names it,
+    which catches a credential revoked in between. Each distinct name is read once.
+    """
+
+    def __init__(self, client: api_client.ApiClient) -> None:
+        self._client = client
+        self._found: dict[str, Any] = {}
+
+    def __call__(self, flag: str, name: str) -> Any:
+        """The credential ``name``. ``flag`` is how the command line spelled it, for the error."""
+        from ... import credentials
+
+        if name not in self._found:
+            try:
+                self._found[name] = credentials.get(
+                    name, api_key=self._client._api_key, endpoint=self._client._endpoint
+                )
+            except credentials.CredentialNotFound as exc:
+                raise api_client.CliError(f"{flag}: {exc}") from exc
+        return self._found[name]
+
+
 def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
     """Stage authored Python and deploy the checked bundle.
 
@@ -904,12 +932,18 @@ def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
         dspy.configure(lm=lm)
         program = dspy.Predict("question -> answer")
         PY
+
+    ``--credential NAME`` names the credential the program's model spends, and is looked
+    up before the source is staged.
     """
     from pathlib import Path
 
     from ... import authored, deployment
 
     program_name = _program_args(args, "deploy")
+    credential_name = getattr(args, "credential", None)
+    if credential_name is not None:
+        credential_name = _CredentialLookup(client)(f"--credential {credential_name}", credential_name).name
     try:
         if args.source == "-" or args.source is None:
             prepared = authored.prepare_stdin(
@@ -939,7 +973,7 @@ def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
             metadata=metadata,
             program_name=program_name,
             config=sdk_config(client),
-            credential_name=getattr(args, "credential", None),
+            credential_name=credential_name,
         )
     except ValueError as exc:
         raise api_client.CliError(str(exc)) from exc
@@ -978,6 +1012,67 @@ def _optimizer_arg(value: str) -> str:
     return value
 
 
+def _lm_credential_arg(value: str) -> tuple[str, str]:
+    """Parse ``--lm-credential BINDING=NAME`` into the binding and the credential's name.
+
+    The program's own model is refused here, at parse time, because it spends the run's
+    credential and ``--credential`` already names that.
+    """
+    binding, sep, name = value.partition("=")
+    if not sep or not binding or not name:
+        raise ArgumentTypeError(
+            f"{value!r} is not BINDING=NAME. Give the name of an LM the optimize file's `lms` binds, then a "
+            "credential `cmpnd credentials list` shows, as in judge=typesafe"
+        )
+    from ... import optimization
+
+    if binding == optimization.DEFAULT_LM_BINDING:
+        raise ArgumentTypeError(
+            f"{binding} is the program's own model, which spends the run's credential. Name it with --credential"
+        )
+    return binding, name
+
+
+def _optimize_credentials(
+    client: api_client.ApiClient, args: Any
+) -> tuple[Any, str | Any | None, dict[str, Any] | None]:
+    """Look up every credential an optimize names, before the file is staged.
+
+    Returns the run's credential, the reflection LM to pass (the model name, wrapped in
+    ``cmpnd.HostedLM`` when ``--reflection-credential`` names its credential) and the
+    credential per binding. :class:`_CredentialLookup` turns each name into a
+    ``cmpnd.Credential``, so a mistyped one fails before the import and the deploy a run
+    makes ahead of its first step.
+    """
+    from ...lm_configuration import HostedLM
+
+    pairs: list[tuple[str, str]] = list(getattr(args, "lm_credential", None) or [])
+    seen: set[str] = set()
+    for binding, _ in pairs:
+        if binding in seen:
+            raise api_client.CliError(
+                f"--lm-credential names the binding {binding!r} more than once. Give each binding one credential."
+            )
+        seen.add(binding)
+    reflection_model = getattr(args, "reflection_model", None)
+    reflection_name = getattr(args, "reflection_credential", None)
+    if reflection_name is not None and reflection_model is None:
+        raise api_client.CliError(
+            "--reflection-credential names the credential the reflection model spends, so it needs --reflection-model."
+        )
+
+    lookup = _CredentialLookup(client)
+    run_name = getattr(args, "credential", None)
+    run = lookup(f"--credential {run_name}", run_name) if run_name is not None else None
+    reflection_lm: str | HostedLM | None = reflection_model
+    if reflection_name is not None and reflection_model is not None:
+        reflection_lm = HostedLM(
+            reflection_model, credential=lookup(f"--reflection-credential {reflection_name}", reflection_name)
+        )
+    lm_credentials = {binding: lookup(f"--lm-credential {binding}={name}", name) for binding, name in pairs}
+    return run, reflection_lm, lm_credentials or None
+
+
 def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
     """Optimize the program, metric and proposer one authored file binds.
 
@@ -1001,6 +1096,11 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
             return dspy.Prediction(score=float(ok),
                                    feedback="" if ok else f"expected {gold.answer}")
         PY
+
+    The file cannot name a credential, because the kernel that imports it reaches no
+    platform. ``--credential`` names the run's, ``--reflection-credential`` the
+    reflection model's and ``--lm-credential BINDING=NAME`` one of the file's ``lms``.
+    Each name is looked up before the file is staged.
     """
     from pathlib import Path
 
@@ -1008,6 +1108,7 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
 
     deployment_id = getattr(args, "deployment_id", None)
     program_name = _program_args(args, "optimize", needs_name=deployment_id is None)
+    credential, reflection_lm, lm_credentials = _optimize_credentials(client, args)
     try:
         if args.source == "-" or args.source is None:
             prepared = authored.prepare_optimize_stdin(
@@ -1041,7 +1142,9 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
             # The flag is named for what a command line can carry — a model name,
             # never an LM object — and the parameter for what the Python surface
             # accepts. Each layer's name says what that layer takes.
-            reflection_lm=getattr(args, "reflection_model", None),
+            reflection_lm=reflection_lm,
+            credential=credential,
+            lm_credentials=lm_credentials,
             max_metric_calls=getattr(args, "max_metric_calls", None),
             auto=getattr(args, "auto", None),
             max_steps=getattr(args, "max_steps", 10),
@@ -1402,6 +1505,8 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
             "--reflection-model openai/gpt-4o --auto light\n"
             "  cmpnd optimize gepa - capital-qa --reflection-model openai/gpt-4o "
             "--max-metric-calls 60 < task.py\n"
+            "  cmpnd optimize gepa task.py capital-qa --reflection-model openai/gpt-4o --auto light "
+            "--credential openai --lm-credential judge=typesafe\n"
             "  cmpnd optimize gepa task.py --reflection-model openai/gpt-4o --auto light --deployment-id d_a1b2c3d4\n"
         ),
         formatter_class=raw,
@@ -1438,6 +1543,31 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         "instructions (required for gepa; the server will not substitute the "
         "deployment's own model)",
     )
+    opt.add_argument(
+        "--credential",
+        metavar="NAME",
+        default=None,
+        help="The provider credential the run spends: the program's model, and every model that names no "
+        "credential of its own (default: the organization's default credential). "
+        "`cmpnd credentials list` shows the names",
+    )
+    opt.add_argument(
+        "--reflection-credential",
+        dest="reflection_credential",
+        metavar="NAME",
+        default=None,
+        help="The credential the reflection model spends instead of the run's",
+    )
+    opt.add_argument(
+        "--lm-credential",
+        dest="lm_credential",
+        metavar="BINDING=NAME",
+        type=_lm_credential_arg,
+        action="append",
+        default=None,
+        help="The credential one LM of the file's `lms` spends instead of the run's, as judge=typesafe. Repeat it "
+        "for each binding",
+    )
     # A budget is mandatory and the optimizer will not choose one — see
     # `cmpnd.optimization._apply_budget`. Two flags rather than one because a
     # caller who does not yet know what a run costs reaches for `--auto`, and one

{cmpnd-0.58.0 → cmpnd-0.59.0}/cmpnd/optimization.py

@@ -508,6 +508,62 @@ def _lms_config(config: dict[str, Any], lms: Any) -> None:
     config["lms"] = declared
 
 
+def _lm_credentials_config(config: dict[str, Any], lm_credentials: Any) -> None:
+    """Name the credential each of the run's declared LM bindings spends.
+
+    An authored file declares its ``lms`` and cannot name a credential for one, because
+    the kernel that imports it again reaches no platform to look one up. So the call that
+    starts the run names it, by binding name, and the entry gains the ``credential`` field
+    that ``cmpnd.HostedLM(lm, credential=)`` and ``cmpnd.SystemOne(model, credential=)``
+    give it in a live-object call. The wire shape is the same either way.
+
+    Each binding must be one the run declares, and must not already name a credential:
+    a second credential for one binding is two answers to one question, the refusal
+    :func:`_reflection_config` makes of ``reflection_credential``. The program's own
+    model spends the run's ``credential=``, so ``default-lm`` is refused here.
+
+    ``config["lms"]`` is replaced rather than edited, because it may be the dict the
+    import child reported, which the caller's prepared file still holds.
+    """
+    if not lm_credentials:
+        return
+    if not isinstance(lm_credentials, dict):
+        raise ValueError(f"lm_credentials must map binding names to credentials (got {type(lm_credentials).__name__})")
+    declared: dict[str, Any] = config.get("lms") or {}
+    named: dict[str, str] = {}
+    for binding, credential in lm_credentials.items():
+        if binding == DEFAULT_LM_BINDING:
+            raise ValueError(
+                f"{DEFAULT_LM_BINDING!r} is the program's own model, and it spends the run's credential. "
+                "Name that credential for the run instead of for a binding."
+            )
+        name = credentials.name_of(credential, f"lm_credentials[{binding!r}]")
+        if name is None:
+            continue
+        if binding not in declared:
+            if not declared:
+                raise ValueError(
+                    f"a credential is named for the LM binding {binding!r}, and the optimize file binds no "
+                    "`lms`, so the run has no binding to spend it."
+                )
+            raise ValueError(
+                f"a credential is named for the LM binding {binding!r}, and the optimize file's `lms` binds no "
+                f"such name. It binds {', '.join(repr(each) for each in sorted(declared))}."
+            )
+        existing = declared[binding].get("credential")
+        if existing is not None:
+            raise ValueError(
+                f"the LM binding {binding!r} already names the credential {existing!r}, and a second one was "
+                f"named for it: these are two answers to which credential it spends. Keep one."
+            )
+        named[binding] = name
+    if named:
+        config["lms"] = {
+            binding: {**entry, "credential": named[binding]} if binding in named else entry
+            for binding, entry in declared.items()
+        }
+
+
 def _check_metric_call(metric: Callable[..., Any], optimizer: str) -> None:  # pyright: ignore[reportUnusedFunction]  # called by the authored import child
     """Check the authored metric against the kernel's positional and named arguments."""
     signature = inspect.signature(metric)
@@ -938,6 +994,7 @@ def optimize_authored(
     config: dict[str, Any] | None = None,
     reflection_lm: str | Any | None = None,
     lms: dict[str, Any] | None = None,
+    lm_credentials: dict[str, credentials.Credential] | None = None,
     credential: credentials.Credential | None = None,
     max_metric_calls: int | None = None,
     auto: str | None = None,
@@ -972,6 +1029,9 @@ def optimize_authored(
     resolves, because that deployment already has its program.
 
     ``credential`` is the run's credential, as on :func:`optimize_deployment`.
+    ``lm_credentials`` maps a binding the file's ``lms`` declares to the credential it
+    spends instead, which the file itself cannot name. A ``cmpnd.HostedLM`` or
+    ``cmpnd.SystemOne`` names one in a live-object call.
     """
     check_optimizer(optimizer)
     credential_name = credentials.name_of(credential, "optimize_authored(credential=)")
@@ -985,6 +1045,7 @@ def optimize_authored(
             config["lms"] = prepared.facts.lms
     _reflection_config(config, reflection_lm)
     _lms_config(config, lms)
+    _lm_credentials_config(config, lm_credentials)
     _apply_budget(config, max_metric_calls=max_metric_calls, auto=auto)
 
     if prepared.program_bundle is None and deployment_id is not None and program_name is not None:

{cmpnd-0.58.0 → cmpnd-0.59.0}/docs/cli.md

@@ -194,9 +194,11 @@ model and the field, never the value. Seal the key with
 `cmpnd credentials create` instead.
 
 `--credential NAME` names the provider credential the program's model spends.
-Without it, the deployment spends the organization's default. The CLI sends the
-name as typed, and the platform refuses a name the organization does not hold
-and names the nearest one. The deploy prints the protocol, model and
+Without it, the deployment spends the organization's default. The CLI looks
+the name up before it stages the source. A name the organization does not hold
+fails with the names it does hold and the nearest one, and nothing is sent.
+The platform checks the name again at the deploy, which catches a credential
+an owner revoked in between. The deploy prints the protocol, model and
 credential of each binding, such as
 `default-lm: chat_completions openai/deepseek-4.1-flash → luna-exec (https://gw.lunaroute.com)`.
 
@@ -618,6 +620,27 @@ organization must hold provider credentials for every model the run uses.
 Named model declarations hold model names and sampling settings, and the CLI
 refuses a provider key on them.
 
+A run spends the organization's default credential unless the command names
+another. `--credential NAME` names the run's credential. The program's model
+spends it, and so does every model that names no credential of its own.
+`--reflection-credential NAME` names the credential the reflection model
+spends. `--lm-credential BINDING=NAME` names the credential one model in the
+file's `lms` spends, and repeats once per binding:
+
+```bash
+cmpnd optimize gepa task.py capital-qa --reflection-model openai/gpt-5 --auto light \
+  --credential openai --lm-credential judge=typesafe
+```
+
+The file cannot name a credential itself, because the kernel imports it again
+and reaches no platform there. These flags send what `credential=`,
+`cmpnd.HostedLM(lm, credential=)` and `cmpnd.SystemOne(model, credential=)`
+send from Python. The CLI looks up every name before it stages the file. A
+name the organization does not hold fails with the names it does hold and the
+nearest one. The CLI also refuses `--lm-credential` for a binding the file's
+`lms` does not declare, for one binding twice and for `default-lm`. The
+program's own model spends the run's credential, so `--credential` names it.
+
 `cmpnd.Client.optimize_deployment(deployment, metric=fn)` in a notebook packages
 live objects and takes named models through its `lms` argument. An authored file's `lms`
 binding cannot be combined with `lms` in the parent call or `config["lms"]`.

{cmpnd-0.58.0 → cmpnd-0.59.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.58.0"
+version = "0.59.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

{cmpnd-0.58.0 → cmpnd-0.59.0}/scripts/test-in-linux.sh

@@ -33,7 +33,7 @@ set -euo pipefail
 
 SDK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 REPO_DIR="$(cd "${SDK_DIR}/.." && pwd)"
-IMAGE="${SDK_TEST_LINUX_IMAGE:-ghcr.io/astral-sh/uv:python3.12-bookworm-slim}"
+IMAGE="${SDK_TEST_LINUX_IMAGE:-ghcr.io/astral-sh/uv:python3.12-trixie-slim}"
 ARGS=("$@")
 if [ ${#ARGS[@]} -eq 0 ]; then
     ARGS=(tests/ -k "not e2e")

{cmpnd-0.58.0 → cmpnd-0.59.0}/tests/span_reference_fixture.py

@@ -130,6 +130,30 @@ def read_committed() -> str:
     return gzip.decompress(FIXTURE_PATH.read_bytes()).decode("utf-8")
 
 
+def assert_current(committed: str, fresh: str) -> None:
+    """Fail when the committed fixture text differs from the fresh render.
+
+    The texts are hundreds of kilobytes, and pytest's string diff on them runs
+    for minutes. This reports the first differing span and its keys instead.
+    The comparison stays exact: equal strings pass and any other pair fails.
+    """
+    if committed == fresh:
+        return
+    refresh = f"{FIXTURE_PATH.name} is stale; refresh it with `uv run python -m tests.span_reference_fixture`"
+    found = json.loads(committed)["trace"]["spans"]
+    wanted = json.loads(fresh)["trace"]["spans"]
+    for i, (old, new) in enumerate(zip(found, wanted)):
+        if old != new:
+            # A sentinel, so a key added or removed with a null value still differs.
+            missing = object()
+            keys = sorted(k for k in old.keys() | new.keys() if old.get(k, missing) != new.get(k, missing))
+            raise AssertionError(f"{refresh}. First differing span {i}, differing keys: {keys}")
+    if len(found) != len(wanted):
+        raise AssertionError(f"{refresh}. It holds {len(found)} spans and the SDK emits {len(wanted)}")
+    offset = next((i for i, (a, b) in enumerate(zip(committed, fresh)) if a != b), min(len(committed), len(fresh)))
+    raise AssertionError(f"{refresh}. The spans match; the texts differ outside the spans at character {offset}")
+
+
 def write(doc: dict[str, Any]) -> None:
     # mtime=0 so the same document always compresses to the same bytes.
     FIXTURE_PATH.write_bytes(gzip.compress(render(doc).encode("utf-8"), mtime=0))