cmpnd 0.23.0__tar.gz → 0.23.2__tar.gz

{cmpnd-0.23.0 → cmpnd-0.23.2}/PKG-INFO

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

{cmpnd-0.23.0 → cmpnd-0.23.2}/cmpnd/callback.py

@@ -181,6 +181,27 @@ def _normalize_usage(usage: Any) -> dict[str, int | None]:
     columns behind them are ``NOT NULL``). ``reasoning_tokens`` and
     ``cache_write_tokens`` come back as ``None`` when the provider said nothing.
     """
+    evidence = _normalize_usage_evidence(usage)
+    prompt = evidence["prompt_tokens"]
+    completion = evidence["completion_tokens"]
+    total = evidence["total_tokens"]
+    if total is None and (prompt is not None or completion is not None):
+        # The legacy span projection has always derived a total. The evidence
+        # object keeps an omitted total as null and preserves the raw block.
+        total = (prompt or 0) + (completion or 0)
+
+    return {
+        "prompt_tokens": prompt or 0,
+        "completion_tokens": completion or 0,
+        "total_tokens": total or 0,
+        "cached_prompt_tokens": evidence["cache_read_tokens"] or 0,
+        "reasoning_tokens": evidence["reasoning_tokens"],
+        "cache_write_tokens": evidence["cache_write_tokens"],
+    }
+
+
+def _normalize_usage_evidence(usage: Any) -> dict[str, int | None]:
+    """Normalize queryable counters without flattening absence into zero."""
     prompt = _reported_count(
         _usage_field(usage, "prompt_tokens"),
         _usage_field(usage, "input_tokens"),
@@ -190,11 +211,6 @@ def _normalize_usage(usage: Any) -> dict[str, int | None]:
         _usage_field(usage, "output_tokens"),
     )
     total = _reported_count(_usage_field(usage, "total_tokens"))
-    if total is None and (prompt is not None or completion is not None):
-        # Derived only where the provider omitted it — a reported total is
-        # evidence and stays as sent, even when the split disagrees with it.
-        total = (prompt or 0) + (completion or 0)
-
     cached = _reported_count(
         _usage_detail(usage, "prompt_tokens_details", "cached_tokens"),
         _usage_detail(usage, "input_tokens_details", "cached_tokens"),
@@ -209,20 +225,159 @@ def _normalize_usage(usage: Any) -> dict[str, int | None]:
     cache_write = _reported_count(
         _usage_field(usage, "cache_write_tokens"),
         _usage_field(usage, "cache_creation_input_tokens"),
+        _usage_detail(usage, "prompt_tokens_details", "cache_creation_tokens"),
+    )
+    cache_write_5m = _reported_count(
+        _usage_detail(usage, "cache_creation", "ephemeral_5m_input_tokens"),
+        _usage_detail(usage, "cache_creation_token_details", "ephemeral_5m_input_tokens"),
+    )
+    cache_write_1h = _reported_count(
+        _usage_detail(usage, "cache_creation", "ephemeral_1h_input_tokens"),
+        _usage_detail(usage, "cache_creation_token_details", "ephemeral_1h_input_tokens"),
+    )
+    audio_prompt = _reported_count(
+        _usage_detail(usage, "prompt_tokens_details", "audio_tokens"),
+        _usage_detail(usage, "input_tokens_details", "audio_tokens"),
+        _usage_field(usage, "input_audio_tokens"),
+        _usage_field(usage, "audio_prompt_tokens"),
+    )
+    audio_completion = _reported_count(
+        _usage_detail(usage, "completion_tokens_details", "audio_tokens"),
+        _usage_detail(usage, "output_tokens_details", "audio_tokens"),
+        _usage_field(usage, "output_audio_tokens"),
+        _usage_field(usage, "audio_completion_tokens"),
     )
 
     return {
-        "prompt_tokens": prompt or 0,
-        "completion_tokens": completion or 0,
-        "total_tokens": total or 0,
-        # A subset of prompt_tokens: every dialect above counts its cache reads
-        # inside the prompt total, so the subset invariant holds by construction.
-        "cached_prompt_tokens": cached or 0,
+        "prompt_tokens": prompt,
+        "completion_tokens": completion,
+        "total_tokens": total,
+        "cache_read_tokens": cached,
         "reasoning_tokens": reasoning,
         "cache_write_tokens": cache_write,
+        "cache_write_5m_tokens": cache_write_5m,
+        "cache_write_1h_tokens": cache_write_1h,
+        "audio_prompt_tokens": audio_prompt,
+        "audio_completion_tokens": audio_completion,
     }
 
 
+_MISSING = object()
+
+
+def _value_field(value: Any, key: str) -> Any:
+    """Read a field from a mapping, DSPy model, or response object."""
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return value.get(key)
+    getter = getattr(value, "get", None)
+    if callable(getter):
+        try:
+            found = getter(key, _MISSING)
+        except TypeError:
+            try:
+                found = getter(key)
+            except (KeyError, TypeError):
+                found = _MISSING
+        if found is not _MISSING:
+            return found
+    return getattr(value, key, None)
+
+
+def _text_field(value: Any, key: str) -> str | None:
+    found = _value_field(value, key)
+    if isinstance(found, str) and found:
+        return found
+    return None
+
+
+def _bool_field(value: Any, key: str) -> bool | None:
+    found = _value_field(value, key)
+    return found if isinstance(found, bool) else None
+
+
+def _present_field(value: Any, key: str) -> tuple[bool, Any]:
+    """Read a field while preserving whether the object declared it."""
+    if isinstance(value, dict):
+        return key in value, value.get(key)
+    model_fields = getattr(type(value), "model_fields", None)
+    if isinstance(model_fields, dict) and key in model_fields:
+        return True, getattr(value, key, None)
+    values = getattr(value, "__dict__", None)
+    if isinstance(values, dict) and key in values:
+        return True, values.get(key)
+    return False, None
+
+
+def _history_usage(entry: Any) -> tuple[bool, Any]:
+    """Return whether history carried usage and the value it carried."""
+    response = _value_field(entry, "response")
+    response_declares_usage, response_usage = _present_field(response, "usage")
+    if response_declares_usage:
+        return response_usage is not None, response_usage
+    if isinstance(entry, dict):
+        usage = entry.get("usage")
+        return "usage" in entry and usage is not None, usage
+    usage = _value_field(entry, "usage")
+    return usage is not None, usage
+
+
+def _usage_dialect(instance: Any, usage: Any) -> str | None:
+    """Name the response surface only when its shape establishes one."""
+    model_type = _text_field(instance, "model_type")
+    if model_type == "responses":
+        return "responses"
+    if model_type in {"chat", "text"}:
+        return "chat_completions"
+    if _usage_field(usage, "inputTokens") is not None or _usage_field(usage, "outputTokens") is not None:
+        return "converse"
+    if _usage_field(usage, "prompt_tokens") is not None or _usage_field(usage, "completion_tokens") is not None:
+        return "chat_completions"
+    return None
+
+
+def _cache_ttl_requested(*values: Any) -> str | None:
+    """Return one unambiguous requested cache TTL from request data."""
+    found: set[str] = set()
+
+    def visit(value: Any, in_cache_control: bool = False) -> None:
+        if isinstance(value, dict):
+            for key, child in value.items():
+                if key in {"cache_ttl", "cache_ttl_requested"} and child is not None:
+                    found.add(str(child))
+                elif in_cache_control and key == "ttl" and child is not None:
+                    found.add(str(child))
+                else:
+                    visit(child, in_cache_control or key == "cache_control")
+        elif isinstance(value, (list, tuple)):
+            for child in value:
+                visit(child, in_cache_control)
+
+    for value in values:
+        visit(value)
+    return next(iter(found)) if len(found) == 1 else None
+
+
+def _request_selector(entry: Any, instance: Any, key: str) -> str | None:
+    history_kwargs = _value_field(entry, "kwargs")
+    return _text_field(history_kwargs, key) or _text_field(getattr(instance, "kwargs", None), key)
+
+
+def _response_text(response: Any, key: str) -> str | None:
+    """Read provider response metadata from DSPy's supported containers."""
+    for container in (
+        response,
+        _value_field(response, "provider_data"),
+        _value_field(response, "metadata"),
+        _value_field(response, "_hidden_params"),
+    ):
+        found = _text_field(container, key)
+        if found:
+            return found
+    return None
+
+
 def _finish_reason(response: Any) -> str | None:
     """Read why the model stopped, from whichever response shape answered.
 
@@ -991,6 +1146,13 @@ class _LMMixin(_CallbackBase):
         lm_kwargs = {
             k: v for k, v in getattr(instance, "kwargs", {}).items() if k not in {"api_key", "api_base", "api_secret"}
         }
+        span.lm_usage = models.LMUsageObservationV1(
+            sdk_call_id=call_id,
+            model_requested=span.model_name,
+            service_tier_requested=_text_field(lm_kwargs, "service_tier"),
+            cache_ttl_requested=_cache_ttl_requested(lm_kwargs, inputs),
+            binding=_text_field(instance, "binding"),
+        )
         span.attributes.update(
             {
                 "lm.model_type": getattr(instance, "model_type", "unknown"),
@@ -1027,38 +1189,95 @@ class _LMMixin(_CallbackBase):
 
         span.end_time = datetime.now(timezone.utc)
 
+        latest_entry: Any = None
+        response: Any = None
+        usage: Any = None
+        usage_reported = False
+        if instance and hasattr(instance, "history") and instance.history:
+            try:
+                latest_entry = instance.history[-1]
+                usage_reported, usage = _history_usage(latest_entry)
+                response = _value_field(latest_entry, "response")
+                logger.debug(
+                    f"LM history usage for {span.model_name}: "
+                    f"history_len={len(instance.history)}, "
+                    f"usage_type={type(usage).__name__}, "
+                    f"usage={usage}"
+                )
+            except (IndexError, AttributeError, TypeError) as e:
+                logger.debug(f"LM history access failed: {e}")
+        else:
+            has_hist = hasattr(instance, "history") if instance else False
+            hist_len = len(instance.history) if has_hist else "N/A"
+            logger.debug(
+                f"LM history unavailable: instance={instance is not None}, "
+                f"has_history={has_hist}, history_len={hist_len}"
+            )
+
+        if not usage_reported and isinstance(outputs, dict) and "usage" in outputs:
+            usage = outputs.get("usage")
+            usage_reported = usage is not None
+            if response is None:
+                response = outputs
+
+        observation = span.lm_usage
+        if observation is not None:
+            observation.observed_at = span.end_time
+            observation.outcome = "success" if exception is None else None
+            cache_hit = _bool_field(response, "cache_hit")
+            if cache_hit is None:
+                cache_hit = _bool_field(_value_field(response, "_hidden_params"), "cache_hit")
+            observation.dspy_client_cache_hit = cache_hit
+            observation.usage_reported = usage_reported and cache_hit is not True
+            serialized_usage = models._safe_serialize(usage)
+            observation.usage_raw = (
+                serialized_usage if observation.usage_reported and isinstance(serialized_usage, dict) else None
+            )
+            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":
+                observation.prompt_inclusion = "excludes_cache_reads"
+
+            if usage_reported and usage is not None:
+                evidence = _normalize_usage_evidence(usage)
+                for name, value in evidence.items():
+                    setattr(observation, name, value)
+                if (
+                    observation.prompt_tokens is not None
+                    and observation.cache_read_tokens is not None
+                    and observation.prompt_inclusion == "includes_cache_reads"
+                    and observation.cache_read_tokens <= observation.prompt_tokens
+                ):
+                    observation.fresh_input_tokens = observation.prompt_tokens - observation.cache_read_tokens
+                elif observation.prompt_tokens is not None and observation.prompt_inclusion == "excludes_cache_reads":
+                    observation.fresh_input_tokens = observation.prompt_tokens
+
+            requested_model = _text_field(latest_entry, "model")
+            if requested_model:
+                observation.model_requested = requested_model
+            reported_model = _text_field(latest_entry, "response_model") or _text_field(response, "model")
+            if reported_model:
+                observation.model_reported = reported_model
+            requested_tier = _request_selector(latest_entry, instance, "service_tier")
+            if requested_tier:
+                observation.service_tier_requested = requested_tier
+            requested_ttl = _cache_ttl_requested(_value_field(latest_entry, "kwargs"))
+            if requested_ttl:
+                observation.cache_ttl_requested = requested_ttl
+            effective_tier = _response_text(response, "service_tier")
+            if effective_tier:
+                observation.service_tier_effective = effective_tier
+            observation.provider_response_id = _response_text(response, "response_id") or _response_text(response, "id")
+            observation.egress_call_id = _response_text(response, "egress_call_id") or _text_field(
+                latest_entry, "egress_call_id"
+            )
+
         if exception:
             span.set_error(exception)
         else:
             span.status = models.TraceStatus.OK
 
-            # Extract token usage - try LM's history first (where DSPy stores it),
-            # then fall back to outputs dict (for backwards compatibility / testing)
-            usage = {}
-            if instance and hasattr(instance, "history") and instance.history:
-                try:
-                    latest_entry = instance.history[-1]
-                    usage = latest_entry.get("usage", {})
-                    logger.debug(
-                        f"LM history usage for {span.model_name}: "
-                        f"history_len={len(instance.history)}, "
-                        f"usage_type={type(usage).__name__}, "
-                        f"usage={usage}"
-                    )
-                except (IndexError, AttributeError, TypeError) as e:
-                    logger.debug(f"LM history access failed: {e}")
-            else:
-                has_hist = hasattr(instance, "history") if instance else False
-                hist_len = len(instance.history) if has_hist else "N/A"
-                logger.debug(
-                    f"LM history unavailable: instance={instance is not None}, "
-                    f"has_history={has_hist}, history_len={hist_len}"
-                )
-
-            # Fallback: check outputs dict for usage (legacy / test compatibility)
-            if not usage and isinstance(outputs, dict):
-                usage = outputs.get("usage", {})
-
             if usage:
                 counts = _normalize_usage(usage)
                 span.prompt_tokens = counts["prompt_tokens"] or 0
@@ -1072,14 +1291,9 @@ class _LMMixin(_CallbackBase):
                 logger.debug(f"NO usage data for {span.model_name} (call_id={call_id})")
 
             # Extract finish_reason from LM history response
-            if instance and hasattr(instance, "history") and instance.history:
-                try:
-                    latest_entry = instance.history[-1]
-                    finish_reason = _finish_reason(latest_entry.get("response"))
-                    if finish_reason:
-                        span.set_attribute("lm.finish_reason", finish_reason)
-                except (IndexError, AttributeError, TypeError):
-                    pass
+            finish_reason = _finish_reason(response)
+            if finish_reason:
+                span.set_attribute("lm.finish_reason", finish_reason)
 
             # Capture response outputs (truncated)
             if outputs and self._capture_outputs:

{cmpnd-0.23.0 → cmpnd-0.23.2}/cmpnd/cli/commands/login.py

@@ -192,11 +192,11 @@ def _exchange_code(endpoint: str, code: str) -> str:
     bearer); the server consumes the code on read so it cannot be replayed.
     """
     # Bare HTTP POST — ApiClient requires an api_key we don't have yet.
-    import json as _json
+    import json
     import urllib.request
 
     url = f"{endpoint.rstrip('/')}/api/v1/auth/cli/exchange"
-    body = _json.dumps({"code": code}).encode("utf-8")
+    body = json.dumps({"code": code}).encode("utf-8")
     req = urllib.request.Request(
         url,
         data=body,
@@ -205,7 +205,7 @@ def _exchange_code(endpoint: str, code: str) -> str:
     )
     try:
         with urllib.request.urlopen(req, timeout=30) as resp:
-            payload = _json.loads(resp.read().decode("utf-8"))
+            payload = json.loads(resp.read().decode("utf-8"))
     except Exception as exc:
         raise api_client.CliError(f"Failed to exchange login code: {exc}") from exc
     token = payload.get("api_key") if isinstance(payload, dict) else None

{cmpnd-0.23.0 → cmpnd-0.23.2}/cmpnd/cli/commands/top.py

@@ -985,11 +985,11 @@ def cmd_run(client: api_client.ApiClient, args: Any) -> None:
 
 
 def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
-    import argparse as _ap
+    import argparse
 
     from .. import verbs
 
-    raw = _ap.RawDescriptionHelpFormatter
+    raw = argparse.RawDescriptionHelpFormatter
 
     # Resolve handler refs through VERBS so adding a CLI subparser without
     # a corresponding entry in cmpnd.cli.verbs (or vice versa) trips

{cmpnd-0.23.0 → cmpnd-0.23.2}/cmpnd/cli/shell.py

@@ -25,7 +25,7 @@ The registry handles caching, ``__dir__``, ``__iter__``, indexing,
 
 from __future__ import annotations
 
-import json as _json
+import json
 import os
 import sys
 from pathlib import Path
@@ -418,7 +418,7 @@ class Deployment(Entity):
             raise TypeError("pass either a body dict or kwargs, not both")
         if body is None:
             body = kwargs
-        body_str = body if isinstance(body, str) else _json.dumps(body)
+        body_str = body if isinstance(body, str) else json.dumps(body)
         commands.top.cmd_run(self._client, _args(id=self.id, body=body_str))
 
     def watch(self, timeout: int = 600) -> None:

{cmpnd-0.23.0 → cmpnd-0.23.2}/cmpnd/eval_handler.py

@@ -279,7 +279,7 @@ class EvalHandler:
             # not a position — is what a result is matched on.
             traces_by_id = {str(t.trace_id): t for t in eval_traces}
             # Imported here, not at module scope: callback imports eval_handler.
-            from . import callback as callback_module
+            from . import callback
 
             logger.debug(f"Collected {len(eval_traces)} traces for eval run")
             for i, t in enumerate(eval_traces[:3]):  # Show first 3
@@ -341,7 +341,7 @@ class EvalHandler:
                     # positional fallback: a result carrying no stamp is left
                     # unlinked, because a wrong trace, a wrong token count and a
                     # wrong cost are worse than none.
-                    trace = traces_by_id.get(callback_module.trace_id(prediction) or "")
+                    trace = traces_by_id.get(callback.trace_id(prediction) or "")
                     if trace is not None:
                         example_builder.trace_id = trace.trace_id
 

{cmpnd-0.23.0 → cmpnd-0.23.2}/cmpnd/models.py

@@ -2,13 +2,14 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
 import re
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from enum import Enum
 from typing import Any
-from uuid import UUID
+from uuid import UUID, uuid4
 
 from . import identity, imaging
 
@@ -412,6 +413,91 @@ class TraceStatus(str, Enum):
     ERROR = "error"
 
 
+@dataclass
+class LMUsageObservationV1:
+    """Provider-usage evidence attached to one SDK-observed LM call.
+
+    Optional counters preserve the distinction between an absent measurement
+    and a reported zero. ``provider_cost`` accepts only a provider-origin amount.
+    DSPy and LiteLLM calculated costs do not belong here.
+    """
+
+    source_observation_id: str = field(default_factory=lambda: str(uuid4()))
+    observed_at: datetime | None = None
+    usage_reported: bool = False
+    usage_raw: dict[str, Any] | None = None
+    usage_dialect: str | None = None
+    normalization_version: int = 1
+    prompt_inclusion: str | None = None
+    model_requested: str | None = None
+    model_reported: str | None = None
+    service_tier_requested: str | None = None
+    service_tier_effective: str | None = None
+    cache_ttl_requested: str | None = None
+    provider_cost: str | None = None
+    provider_cost_currency: str | None = None
+    dspy_client_cache_hit: bool | None = None
+    binding: str | None = None
+    sdk_call_id: str | None = None
+    provider_response_id: str | None = None
+    egress_call_id: str | None = None
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+    fresh_input_tokens: int | None = None
+    cache_read_tokens: int | None = None
+    cache_write_tokens: int | None = None
+    cache_write_5m_tokens: int | None = None
+    cache_write_1h_tokens: int | None = None
+    reasoning_tokens: int | None = None
+    audio_prompt_tokens: int | None = None
+    audio_completion_tokens: int | None = None
+    outcome: str | None = None
+
+    def to_api_dict(self) -> dict[str, Any]:
+        """Return the versioned wire object with a deterministic digest."""
+        payload = {
+            "schema_version": 1,
+            "source_observation_id": self.source_observation_id,
+            "observed_at": self.observed_at.isoformat() if self.observed_at else None,
+            "usage_reported": self.usage_reported,
+            "usage_raw": _safe_serialize(self.usage_raw),
+            "usage_dialect": self.usage_dialect,
+            "normalization_version": self.normalization_version,
+            "prompt_inclusion": self.prompt_inclusion,
+            "model_requested": self.model_requested,
+            "model_reported": self.model_reported,
+            "service_tier_requested": self.service_tier_requested,
+            "service_tier_effective": self.service_tier_effective,
+            "cache_ttl_requested": self.cache_ttl_requested,
+            "provider_cost": self.provider_cost,
+            "provider_cost_currency": self.provider_cost_currency,
+            "dspy_client_cache_hit": self.dspy_client_cache_hit,
+            "binding": self.binding,
+            "sdk_call_id": self.sdk_call_id,
+            "provider_response_id": self.provider_response_id,
+            "egress_call_id": self.egress_call_id,
+            "prompt_tokens": self.prompt_tokens,
+            "completion_tokens": self.completion_tokens,
+            "total_tokens": self.total_tokens,
+            "fresh_input_tokens": self.fresh_input_tokens,
+            "cache_read_tokens": self.cache_read_tokens,
+            "cache_write_tokens": self.cache_write_tokens,
+            "cache_write_5m_tokens": self.cache_write_5m_tokens,
+            "cache_write_1h_tokens": self.cache_write_1h_tokens,
+            "reasoning_tokens": self.reasoning_tokens,
+            "audio_prompt_tokens": self.audio_prompt_tokens,
+            "audio_completion_tokens": self.audio_completion_tokens,
+            "outcome": self.outcome,
+        }
+        safe_payload = _safe_serialize(payload)
+        if not isinstance(safe_payload, dict):
+            raise TypeError("LM usage observation did not serialize to a JSON object")
+        canonical = json.dumps(safe_payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+        safe_payload["source_payload_digest"] = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+        return safe_payload
+
+
 @dataclass
 class SpanBuilder:
     """Mutable span builder for collecting data during execution."""
@@ -469,6 +555,7 @@ class SpanBuilder:
     # Normalized by callback._normalize_usage.
     reasoning_tokens: int | None = None
     cache_write_tokens: int | None = None
+    lm_usage: LMUsageObservationV1 | None = None
     # Left unset by the SDK. A dollar figure is a derivation from these counts
     # and a dated rate catalog, and only serve holds the catalog; the SDK's job
     # is to report what the provider said. serve still reads the wire field, so
@@ -582,6 +669,7 @@ class SpanBuilder:
             "cached_prompt_tokens": self.cached_prompt_tokens,
             "reasoning_tokens": self.reasoning_tokens,
             "cache_write_tokens": self.cache_write_tokens,
+            "lm_usage": self.lm_usage.to_api_dict() if self.lm_usage else None,
             "cost": self.cost,
             "demos": _safe_serialize(self.demos),
             "demo_count": self.demo_count if self.demo_count else len(self.demos),

{cmpnd-0.23.0 → cmpnd-0.23.2}/cmpnd/packaging.py

@@ -544,9 +544,9 @@ def _resolve_an_mcp_tool(
     which no resolution can rescue — and they can fix it in one line, so the message
     shows the line.
     """
-    from . import mcp_servers as mcp
+    from . import mcp_servers
 
-    reference = mcp.mcp_tool_reference(tool)
+    reference = mcp_servers.mcp_tool_reference(tool)
     if reference is not None:
         entry = pinned.get((reference.server_url, reference.tool_name))
         if entry is None:
@@ -560,7 +560,7 @@ def _resolve_an_mcp_tool(
             )
         return entry
 
-    if mcp.is_bare_mcp_tool(tool):
+    if mcp_servers.is_bare_mcp_tool(tool):
         raise ValueError(
             f"tool {name!r} was built with dspy.Tool.from_mcp_tool, which closes over a live MCP session: "
             "the server it came from and the credential it was reached with are not recoverable from it, "
@@ -787,7 +787,7 @@ def generate_program_source(
     pinned_mcp_tools = mcp_tools or {}
     tools_dict = module_tools(module)
     if tools_dict:
-        from . import mcp_servers as mcp
+        from . import mcp_servers
 
         for name, tool in tools_dict.items():
             if name == "finish":
@@ -798,7 +798,7 @@ def generate_program_source(
                 # instead of a body — see [_generate_mcp_tool_stub]. The `def`'s name is
                 # the MCP tool's own, because the declaration names the tool and the
                 # worker maps that name to the token it holds.
-                signature = mcp.synthesized_signature(pinned)
+                signature = mcp_servers.synthesized_signature(pinned)
                 lines.append(_generate_mcp_tool_stub(pinned, signature))
                 mcp_declarations.append(
                     {