cmpnd 0.26.0__tar.gz → 0.27.0__tar.gz

{cmpnd-0.26.0 → cmpnd-0.27.0}/PKG-INFO

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

cmpnd-0.27.0/cmpnd/_authored_import.py

@@ -0,0 +1,355 @@
+"""Isolated import checker for authored deployment bundles."""
+
+from __future__ import annotations
+
+import contextlib
+import importlib
+import inspect
+import json
+import sys
+import tempfile
+import traceback
+import zipfile
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+
+def _program(module: Any, entrypoint: str) -> tuple[Any, str]:
+    import dspy
+
+    if not hasattr(module, entrypoint):
+        raise ValueError(f"entrypoint {entrypoint!r} is not defined by the authored program")
+    value = getattr(module, entrypoint)
+    if isinstance(value, dspy.Module):
+        return value, "instance"
+    if inspect.isclass(value) and issubclass(value, dspy.Module):
+        _require_zero_arguments(value, f"entrypoint class {entrypoint!r}")
+        return value(), "class"
+    if callable(value):
+        _require_zero_arguments(value, f"entrypoint factory {entrypoint!r}")
+        built = value()
+        if isinstance(built, dspy.Module):
+            return built, "factory"
+    raise ValueError(
+        f"entrypoint {entrypoint!r} must be a dspy.Module instance, a dspy.Module class, or a zero-argument factory"
+    )
+
+
+def _require_zero_arguments(value: Any, label: str) -> None:
+    """Refuse required parameters without mislabelling errors inside the call."""
+    try:
+        signature = inspect.signature(value)
+    except (TypeError, ValueError):
+        return
+    try:
+        signature.bind()
+    except TypeError as exc:
+        raise ValueError(f"{label} must accept no arguments: {exc}") from exc
+
+
+def _configured(request: dict[str, Any]) -> dict[str, int | None]:
+    """Give the check its own platform configuration, and watch what the file asks for.
+
+    The child has no environment, so an authored ``cmpnd.configure(max_input_size=…)``
+    would otherwise have nothing to configure against. The wrapper keeps the check's own
+    transport while letting the file change the settings it owns, and records the two
+    trace limits the create call carries.
+    """
+    from . import configuration
+
+    original_configure = configuration.configure
+    authored_limits: dict[str, int | None] = {"max_input_size": None, "max_output_size": None}
+    if not request.get("api_key"):
+        return authored_limits
+    original_configure(api_key=request["api_key"], endpoint=request.get("endpoint"))
+
+    def source_configure(api_key=None, endpoint=None, *args, **kwargs):
+        for name in authored_limits:
+            value = kwargs.get(name)
+            authored_limits[name] = value if isinstance(value, int) else None
+        return original_configure(
+            api_key=api_key or request["api_key"],
+            endpoint=endpoint or request.get("endpoint"),
+            *args,
+            **kwargs,
+        )
+
+    # The check has its own platform configuration but exposes no secret in the child
+    # environment. Serve resolves any tool binding again on create, so nothing the file
+    # configures here decides what the run may reach.
+    configuration.configure = source_configure
+    setattr(sys.modules["cmpnd"], "configure", source_configure)
+    return authored_limits
+
+
+@contextlib.contextmanager
+def _staged(request: dict[str, Any]):
+    """Extract the exact staged ZIP and put its root first on ``sys.path``.
+
+    The root stays on the path for the whole block rather than only for the first
+    import: an authored file's sibling may be imported lazily inside a function the
+    checks below call, and a path removed at the end of the entry import would make that
+    fail here and work in the kernel, which mounts the whole tree for the run's life.
+    """
+    with tempfile.TemporaryDirectory(prefix="cmpnd-authored-") as directory:
+        root = Path(directory)
+        with zipfile.ZipFile(request["bundle"]) as archive:
+            archive.extractall(root)
+        sys.path.insert(0, str(root))
+        try:
+            yield root
+        finally:
+            if str(root) in sys.path:
+                sys.path.remove(str(root))
+
+
+def _import_member(member: str) -> Any:
+    """Import one archive member as the module the kernel will import it as."""
+    return importlib.import_module(str(member).removesuffix(".py").replace("/", "."))
+
+
+def _program_facts(
+    program: Any,
+    kind: str,
+    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
+
+    references = deployment._mcp_tool_references(program)
+    deployment._refuse_mcp_tools_outside_rlm(program, references)
+    pinned: dict[tuple[str, str], Any] = {}
+    if references:
+        import httpx
+
+        config = configuration.require_config()
+        with httpx.Client(timeout=30) as client:
+            pinned = deployment._resolve_mcp_tool_references(client, config, references)
+    tool_references = [
+        {
+            # The child already checked an explicit credential name against the
+            # registered server binding. Serve resolves that binding again and
+            # never accepts a client-selected credential name in this declaration.
+            "server_url": item.server_url,
+            "tool": item.tool_name,
+            "schema_hash": item.schema_hash,
+            "parameters": mcp_servers.synthesized_signature(item).parameter_names,
+        }
+        for item in pinned.values()
+    ]
+    tool_declarations = [
+        {
+            "server_url": item.server_url,
+            "name": item.tool_name,
+            "schema_hash": item.schema_hash,
+            "input_schema": item.input_schema,
+            "description": item.description,
+            "parameters": mcp_servers.synthesized_signature(item).parameter_names,
+        }
+        for item in pinned.values()
+    ]
+
+    signature = packaging._get_module_signature(program)
+    fields: dict[str, Any] = {}
+    if signature is not None:
+        fields = {
+            "signature_name": packaging._signature_to_string(signature),
+            "input_fields": list(signature.input_fields),
+            "output_fields": list(signature.output_fields),
+            "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
+    lm_kwargs = getattr(lm, "kwargs", {}) if lm is not None else {}
+    facts = ProgramFacts(
+        program_signature_hash=identity.compute_program_hash(program),
+        entrypoint_kind=kind,
+        module_class=type(program).__name__,
+        litellm_model=getattr(lm, "model", None),
+        temperature=lm_kwargs.get("temperature"),
+        max_tokens=lm_kwargs.get("max_tokens"),
+        thinking_effort=lm_kwargs.get("thinking_effort"),
+        max_input_size=authored_limits["max_input_size"],
+        max_output_size=authored_limits["max_output_size"],
+        tool_references=tool_references,
+        tool_declarations=tool_declarations,
+        **fields,
+    )
+    return asdict(facts)
+
+
+def _check(request: dict[str, Any]) -> dict[str, Any]:
+    """The program bundle's answer: one import, the entrypoint's facts."""
+    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)}
+
+
+def _check_optimize(request: dict[str, Any]) -> dict[str, Any]:
+    """The optimize file's answer: one import, every entrypoint the run needs.
+
+    One import for all of it, rather than one per callable: the file is one module, and
+    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
+
+    ask = request["optimize"]
+    authored_limits = _configured(request)
+    with _staged(request):
+        module = _import_member(str(ask["entry"]))
+        declared_lms: dict[str, Any] | None = None
+        if hasattr(module, "lms"):
+            lms_config: dict[str, Any] = {}
+            optimization._lms_config(lms_config, getattr(module, "lms"))
+            declared_lms = lms_config.get("lms", {})
+        metric_entrypoint = str(ask["metric_entrypoint"])
+        metric = getattr(module, metric_entrypoint, None)
+        if metric is None:
+            raise ValueError(
+                f"the optimize file binds no {metric_entrypoint!r}. An optimization scores every rollout "
+                f"with it, so define `def {metric_entrypoint}(gold, pred, trace, pred_name, pred_trace)` "
+                "returning dspy.Prediction(score=, feedback=)."
+            )
+        if not callable(metric):
+            raise ValueError(
+                f"{metric_entrypoint!r} in the optimize file is a {type(metric).__name__}, not a callable, "
+                "so nothing can score a rollout with it."
+            )
+        optimization._check_metric_call(metric, str(ask["optimizer"]))
+
+        program_entrypoint = str(ask["program_entrypoint"])
+        declared_program = getattr(module, program_entrypoint, None)
+        facts: dict[str, Any] | None = None
+        found_program: str | None = None
+        if declared_program is not None and not ask["program_allowed"]:
+            raise ValueError(
+                f"the optimize file binds {program_entrypoint!r} and a deployment id was given as well. "
+                "Those are two answers to which program this run optimizes, so neither is taken: remove "
+                f"the deployment id to optimize the file's own {program_entrypoint!r}, or remove "
+                f"{program_entrypoint!r} to optimize the deployment."
+            )
+        if declared_program is None and ask["program_allowed"]:
+            raise ValueError(
+                f"the optimize file binds no {program_entrypoint!r}, and no deployment id names one. "
+                f"Bind `{program_entrypoint} = ...` to optimize the file's own program, or pass an "
+                "existing deployment id to optimize that."
+            )
+        if declared_program is not None:
+            program, kind = _program(module, program_entrypoint)
+            facts = _program_facts(program, kind, authored_limits)
+            found_program = program_entrypoint
+
+        proposer_entrypoint = str(ask["proposer_entrypoint"])
+        declared_proposer = getattr(module, proposer_entrypoint, None)
+        found_proposer: str | None = None
+        if declared_proposer is not None:
+            optimization._check_proposer_call(declared_proposer)
+            found_proposer = proposer_entrypoint
+
+        work = Path(request["work_dir"])
+        trainset = _rows(module, "trainset")
+        valset = _rows(module, "valset")
+        (work / "trainset.ndjson").write_text(_ndjson(trainset))
+        (work / "valset.ndjson").write_text(_ndjson(valset))
+
+    answer: dict[str, Any] = {
+        "optimize": {
+            "metric_entrypoint": metric_entrypoint,
+            "program_entrypoint": found_program,
+            "proposer_entrypoint": found_proposer,
+            "lms": declared_lms,
+            "trainset_rows": len(trainset),
+            "valset_rows": len(valset),
+        }
+    }
+    if facts is not None:
+        answer["facts"] = facts
+    return answer
+
+
+def _rows(module: Any, name: str) -> list[Any]:
+    """One example set the file built, refused here rather than at the first rollout."""
+    rows = getattr(module, name, None)
+    if rows is None:
+        raise ValueError(
+            f"the optimize file binds no {name!r}. An optimization needs both `trainset` and `valset` "
+            "as lists of dspy.Example."
+        )
+    if not isinstance(rows, (list, tuple)) or not rows:
+        raise ValueError(
+            f"{name!r} in the optimize file is {type(rows).__name__} and must be a non-empty list of "
+            "dspy.Example — an empty one leaves the search nothing to score."
+        )
+    return list(rows)
+
+
+def _ndjson(rows: list[Any]) -> str:
+    """The dataset as the optimizer reads it: one flattened example per line.
+
+    Serialized HERE, in the process that imported the file, because that is the only
+    process that ever holds the Python objects. Authored source is for code the kernel
+    imports; a dataset is data the optimizer reads, and this is the shape it reads.
+    """
+    from . import optimization
+
+    return "\n".join(json.dumps(optimization._example_to_dict(row)) for row in rows) + "\n"
+
+
+def main() -> int:
+    try:
+        request = json.loads(sys.stdin.read())
+        with contextlib.redirect_stdout(sys.stderr):
+            # Anything the imported file prints goes to stderr: this process answers one
+            # JSON document on stdout, and a module-scope `print` would otherwise be read
+            # as part of it.
+            answer = _check_optimize(request) if request.get("optimize") else _check(request)
+        print(json.dumps(answer))
+        return 0
+    except ModuleNotFoundError as exc:
+        print(
+            json.dumps(
+                {
+                    "error": (
+                        f"the authored source imports {exc.name!r}, which the local import check cannot find. "
+                        "If it is a sibling module, add its file or directory with --include; otherwise install "
+                        "the dependency locally and ensure the worker supports it."
+                    )
+                }
+            )
+        )
+    except KeyError as exc:
+        print(
+            json.dumps(
+                {
+                    "error": (
+                        f"authored source import failed with KeyError: {exc}. The check runs without your "
+                        "environment because the worker has none. Do not read provider or MCP credentials at "
+                        "module scope. Name the model without its key and use cmpnd.mcp_tools(url) for a "
+                        "registered server.\n" + _concise_traceback()
+                    )
+                }
+            )
+        )
+    except BaseException as exc:
+        print(
+            json.dumps(
+                {"error": (f"authored source import failed with {type(exc).__name__}: {exc}\n" + _concise_traceback())}
+            )
+        )
+    return 1
+
+
+def _concise_traceback() -> str:
+    return "".join(traceback.format_exc(limit=6)).strip()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())