cmpnd 0.25.0__tar.gz → 0.26.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.25.0
+Version: 0.26.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -137,6 +137,11 @@ print(result.answer)
 
 The SDK packages the module's source code into a ZIP, uploads it to the platform, and polls until the server-side parser finishes. Returns a `DeployedProgram` you can **call directly** to execute server-side; `str(deployed)` is its `deployment_id` and `deployed.deployment_id` exposes it explicitly.
 
+For a source file, use `cmpnd deploy program.py`. The CLI uploads the file's
+exact bytes instead of reconstructing it from a live object. Use
+`--source-root` and repeated `--include` flags for sibling modules or data, and
+`cmpnd inspect <id> --source` to read the deployed entry file back.
+
 ### With a metric (for optimization)
 
 ```python

{cmpnd-0.25.0 → cmpnd-0.26.0}/README.md

@@ -89,6 +89,11 @@ print(result.answer)
 
 The SDK packages the module's source code into a ZIP, uploads it to the platform, and polls until the server-side parser finishes. Returns a `DeployedProgram` you can **call directly** to execute server-side; `str(deployed)` is its `deployment_id` and `deployed.deployment_id` exposes it explicitly.
 
+For a source file, use `cmpnd deploy program.py`. The CLI uploads the file's
+exact bytes instead of reconstructing it from a live object. Use
+`--source-root` and repeated `--include` flags for sibling modules or data, and
+`cmpnd inspect <id> --source` to read the deployed entry file back.
+
 ### With a metric (for optimization)
 
 ```python

{cmpnd-0.25.0 → cmpnd-0.26.0}/cmpnd/__init__.py

@@ -14,7 +14,7 @@ Usage:
 
 import importlib.metadata
 
-from . import traces
+from . import authored, traces
 from ._http import ApiError
 from .callback import CmpndCallback, trace_id
 from .client import Client
@@ -26,7 +26,7 @@ from .context import (
 )
 from .datasets import DatasetNotFoundError, VersionNotFoundError, load_dataset
 from .decorators import start_span, trace
-from .deployment import DeployFailed, deploy
+from .deployment import DeployFailed, deploy, deploy_bundle
 from .execution import DeployedProgram, execute
 from .exporter import flush_exporter, shutdown_exporter
 from .mcp_servers import (
@@ -80,6 +80,7 @@ __all__ = [
     "shutdown_exporter",
     # Programmatic backend reads (cmpnd.traces.list / cmpnd.traces.show)
     "traces",
+    "authored",
     "ApiError",
     # Types
     "SpanType",
@@ -88,6 +89,7 @@ __all__ = [
     "TraceBuilder",
     # Deploy & execute
     "deploy",
+    "deploy_bundle",
     "DeployFailed",
     "execute",
     "DeployedProgram",

cmpnd-0.26.0/cmpnd/_authored_import.py

@@ -0,0 +1,201 @@
+"""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 _check(request: dict[str, Any]) -> dict[str, Any]:
+    from . import configuration, deployment, identity, mcp_servers, packaging
+    from .authored import ProgramFacts
+
+    original_configure = configuration.configure
+    authored_limits: dict[str, int | None] = {"max_input_size": None, "max_output_size": None}
+    if request.get("api_key"):
+        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. Let authored ``cmpnd.configure(max_...)`` keep
+        # that transport while it changes the settings the program owns.
+        configuration.configure = source_configure
+        setattr(sys.modules["cmpnd"], "configure", source_configure)
+    with tempfile.TemporaryDirectory(prefix="cmpnd-authored-") as directory:
+        root = Path(directory)
+        with zipfile.ZipFile(request["bundle"]) as archive:
+            archive.extractall(root)
+        manifest = json.loads((root / "manifest.json").read_text())
+        module_name = str(manifest["program"]).removesuffix(".py").replace("/", ".")
+        sys.path.insert(0, str(root))
+        try:
+            module = importlib.import_module(module_name)
+        finally:
+            sys.path.remove(str(root))
+        program, kind = _program(module, str(manifest["entrypoint"]))
+
+        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()
+                ],
+            }
+        import dspy
+
+        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 main() -> int:
+    try:
+        request = json.loads(sys.stdin.read())
+        with contextlib.redirect_stdout(sys.stderr):
+            facts = _check(request)
+        print(json.dumps({"facts": facts}))
+        return 0
+    except ModuleNotFoundError as exc:
+        print(
+            json.dumps(
+                {
+                    "error": (
+                        f"the authored program 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())

{cmpnd-0.25.0 → cmpnd-0.26.0}/cmpnd/_http.py

@@ -30,6 +30,27 @@ class ApiError(Exception):
         self.status_code = status_code
 
 
+def server_detail(response: httpx.Response) -> str:
+    """The server's own message for a failed request, for the error text.
+
+    Both shapes the platform emits: ``{"error": {"message": …}}`` (a worker's
+    refusal, passed through by serve) and ``{"error": "…"}`` (serve's own
+    ``writeError``). Falls back to the raw text, trimmed, because an unparseable
+    body still beats no body — and returns "" rather than guessing when there is
+    nothing, so the caller can supply its own wording.
+    """
+    try:
+        data = response.json()
+    except ValueError:
+        return (response.text or "").strip()[:2000]
+    error = data.get("error") if isinstance(data, dict) else None
+    if isinstance(error, dict):
+        return str(error.get("message") or error).strip()[:2000]
+    if error:
+        return str(error).strip()[:2000]
+    return (response.text or "").strip()[:2000]
+
+
 class ApiClient:
     """Thin HTTP client for the cmpnd backend API."""
 
@@ -41,7 +62,7 @@ class ApiClient:
         return self._request("GET", path, params=params)
 
     def get_text(self, path: str, params: dict[str, str] | None = None) -> str:
-        """GET a route that does not answer JSON, returning the body undecoded.
+        """GET a route that does not answer JSON, returning its decoded text.
 
         Most of this API is JSON and `get` is right for it; a handful of routes
         serve another media type (a deployment's OpenAPI document is YAML), and
@@ -52,6 +73,10 @@ class ApiClient:
         """
         return self._request("GET", path, params=params, decode=False)
 
+    def get_bytes(self, path: str, params: dict[str, str] | None = None) -> bytes:
+        """GET a route whose response bytes must survive unchanged."""
+        return self._request("GET", path, params=params, decode=None)
+
     def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
         return self._request("POST", path, json=json)
 
@@ -73,7 +98,7 @@ class ApiClient:
         path: str,
         params: dict[str, str] | None = None,
         json: dict[str, Any] | None = None,
-        decode: bool = True,
+        decode: bool | None = True,
     ) -> Any:
         url = f"{self._endpoint}{path}"
         # 180s default: deploy/optimize/run wait in-band on an LM round-trip
@@ -111,7 +136,12 @@ class ApiClient:
         if response.status_code == 401:
             raise ApiError("Invalid or missing API key. Check CMPND_API_KEY or --api-key.", status_code=401)
         if response.status_code == 404:
-            raise ApiError("Resource not found.", status_code=404)
+            # The server's own words, not a generic stand-in. Every route here 404s
+            # for a reason it already states — "signature not found", "deployment
+            # not found", "no such organization" — and flattening them into one
+            # sentence makes a missing record and a mistyped URL read identically,
+            # which is the difference a user needs most and had the least of.
+            raise ApiError(server_detail(response) or "Resource not found.", status_code=404)
         if response.status_code >= 500:
             # 5xx usually means the server is up but blew up handling the
             # request — a database hiccup, an unhandled exception, etc.
@@ -131,7 +161,11 @@ class ApiClient:
                 detail = response.text
             raise ApiError(f"Request failed ({response.status_code}): {detail}", status_code=response.status_code)
 
-        # A non-JSON route hands its body back verbatim. Checked before the
+        # A bytes route hands the raw body back before httpx decodes it.
+        if decode is None:
+            return response.content
+
+        # A non-JSON text route hands its decoded body back. Checked before the
         # empty-body arm so such a route answers "" rather than None, which is
         # what lets a caller print it without a None guard.
         if not decode:

cmpnd-0.26.0/cmpnd/authored.py

@@ -0,0 +1,328 @@
+"""Build and check source bundles for ``cmpnd deploy <file>``.
+
+The CLI copies authored files into a deterministic ZIP. It never imports the
+program in the CLI process. A short-lived child imports the exact staged ZIP,
+resolves its declared entrypoint, and returns the facts the deployment API needs.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import json
+import math
+import os
+import platform
+import re
+import stat
+import subprocess
+import sys
+import tempfile
+import warnings
+import zipfile
+from dataclasses import dataclass, field
+from io import BytesIO
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+_MAX_BUNDLE_BYTES = 50 * 1024 * 1024
+_CHECK_TIMEOUT_SECONDS = 60.0
+_CHECK_TIMEOUT_ENV = "CMPND_AUTHORED_IMPORT_TIMEOUT_SECONDS"
+_WORKER_DSPY_BASELINE = (3, 3, 1)
+
+
+class SourceCheckError(ValueError):
+    """The isolated authored-source import check refused a bundle."""
+
+
+@dataclass(frozen=True)
+class ProgramFacts:
+    """Facts derived by importing the staged program without calling forward."""
+
+    program_signature_hash: int | None = None
+    entrypoint_kind: str = "instance"
+    module_class: str | None = None
+    signature_name: str | None = None
+    input_fields: list[str] = field(default_factory=list)
+    output_fields: list[str] = field(default_factory=list)
+    input_field_types: list[str] = field(default_factory=list)
+    output_field_types: list[str] = field(default_factory=list)
+    litellm_model: str | None = None
+    temperature: float | None = None
+    max_tokens: int | None = None
+    thinking_effort: str | None = None
+    max_input_size: int | None = None
+    max_output_size: int | None = None
+    tool_references: list[dict[str, Any]] = field(default_factory=list)
+    tool_declarations: list[dict[str, Any]] = field(default_factory=list)
+
+    @classmethod
+    def minimal(cls) -> ProgramFacts:
+        """Return a small fixture-friendly value."""
+        return cls()
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> ProgramFacts:
+        return cls(**{name: value[name] for name in cls.__dataclass_fields__ if name in value})
+
+    def deploy_body(self) -> dict[str, Any]:
+        """Return fields the deployment create route accepts."""
+        from . import identity
+
+        body: dict[str, Any] = {}
+        if self.program_signature_hash is not None:
+            body["program_signature_hash"] = identity.format_signature_hash(self.program_signature_hash)
+        for name in (
+            "module_class",
+            "signature_name",
+            "litellm_model",
+            "temperature",
+            "max_tokens",
+            "thinking_effort",
+            "max_input_size",
+            "max_output_size",
+        ):
+            value = getattr(self, name)
+            if value is not None and value != "":
+                body[name] = value
+        if self.signature_name is not None:
+            for name in ("input_fields", "output_fields", "input_field_types", "output_field_types"):
+                body[name] = getattr(self, name)
+        if self.tool_references:
+            body["tool_references"] = self.tool_references
+        return body
+
+
+@dataclass(frozen=True)
+class PreparedSource:
+    bundle: bytes
+    facts: ProgramFacts
+    dependency_versions: dict[str, str]
+
+
+def prepare_file(
+    source: str | Path,
+    *,
+    source_root: str | Path | None = None,
+    includes: list[str | Path] | None = None,
+    entrypoint: str = "program",
+    api_key: str | None = None,
+    endpoint: str | None = None,
+) -> PreparedSource:
+    """Stage one authored Python file and its explicit includes."""
+    source_path = Path(source).expanduser()
+    root = Path(source_root).expanduser() if source_root is not None else source_path.parent
+    root = _plain_directory(root, "source root")
+    source_path = _plain_file(source_path, "program")
+    members: dict[str, bytes] = {}
+    _add_file(members, root, source_path)
+    for included in includes or []:
+        _add_path(members, root, Path(included).expanduser())
+    program = _relative_name(root, source_path)
+    return _prepare(members, program, entrypoint, api_key=api_key, endpoint=endpoint)
+
+
+def prepare_stdin(
+    source: bytes | str,
+    *,
+    entrypoint: str = "program",
+    api_key: str | None = None,
+    endpoint: str | None = None,
+) -> PreparedSource:
+    """Stage stdin as the single authored ``program.py`` member."""
+    raw = source.encode() if isinstance(source, str) else source
+    return _prepare({"program.py": raw}, "program.py", entrypoint, api_key=api_key, endpoint=endpoint)
+
+
+def _prepare(
+    members: dict[str, bytes],
+    program: str,
+    entrypoint: str,
+    *,
+    api_key: str | None,
+    endpoint: str | None,
+) -> PreparedSource:
+    if not members.get(program, b"").strip():
+        raise ValueError("the authored program is empty")
+    if not entrypoint or not entrypoint.isidentifier():
+        raise ValueError("entrypoint must be a Python identifier")
+    versions = _dependency_versions()
+    local_dspy = _release_tuple(versions["dspy"])
+    if local_dspy is not None and local_dspy > _WORKER_DSPY_BASELINE:
+        worker_dspy = ".".join(str(part) for part in _WORKER_DSPY_BASELINE)
+        warnings.warn(
+            f"local DSPy {versions['dspy']} is newer than the worker's {worker_dspy} compatibility baseline. "
+            "The local import check can pass even when the worker rejects a newer DSPy spelling.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+    bundle_members = ["manifest.json", *sorted(members)]
+    manifest: dict[str, Any] = {
+        "program": program,
+        "entrypoint": entrypoint,
+        "members": bundle_members,
+        "authored": True,
+        "dependency_versions": versions,
+    }
+    bundle = _zip(manifest, members)
+    facts = _check_bundle(bundle, api_key=api_key, endpoint=endpoint)
+    if facts.tool_declarations:
+        # The child pinned these declarations while importing this exact source.
+        # Serve checks each schema hash against the registry again on create, so
+        # adding the declarations to the manifest does not need a second import.
+        manifest["tools"] = facts.tool_declarations
+        bundle = _zip(manifest, members)
+    return PreparedSource(bundle=bundle, facts=facts, dependency_versions=versions)
+
+
+def _dependency_versions() -> dict[str, str]:
+    def version(name: str) -> str:
+        try:
+            return importlib.metadata.version(name)
+        except importlib.metadata.PackageNotFoundError:
+            return "unknown"
+
+    return {"python": platform.python_version(), "dspy": version("dspy"), "cmpnd": version("cmpnd")}
+
+
+def _release_tuple(value: str) -> tuple[int, int, int] | None:
+    """Return the numeric release prefix needed for the compatibility warning."""
+    matched = re.match(r"^(\d+)\.(\d+)\.(\d+)", value)
+    if matched is None:
+        return None
+    return (int(matched.group(1)), int(matched.group(2)), int(matched.group(3)))
+
+
+def _zip(manifest: dict[str, Any], members: dict[str, bytes]) -> bytes:
+    manifest_bytes = json.dumps(manifest, indent=2, sort_keys=True).encode() + b"\n"
+    uncompressed_size = len(manifest_bytes) + sum(len(contents) for contents in members.values())
+    if uncompressed_size > _MAX_BUNDLE_BYTES:
+        raise ValueError(
+            f"source bundle is {uncompressed_size} bytes uncompressed; the limit is {_MAX_BUNDLE_BYTES} bytes"
+        )
+    output = BytesIO()
+    with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        _write_member(archive, "manifest.json", manifest_bytes)
+        for name in sorted(members):
+            _write_member(archive, name, members[name])
+    bundle = output.getvalue()
+    if len(bundle) > _MAX_BUNDLE_BYTES:
+        raise ValueError(f"source bundle is {len(bundle)} bytes; the limit is {_MAX_BUNDLE_BYTES} bytes")
+    return bundle
+
+
+def _write_member(archive: zipfile.ZipFile, name: str, contents: bytes) -> None:
+    info = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0))
+    info.compress_type = zipfile.ZIP_DEFLATED
+    info.external_attr = (stat.S_IFREG | 0o644) << 16
+    archive.writestr(info, contents)
+
+
+def _plain_directory(path: Path, label: str) -> Path:
+    if path.is_symlink():
+        raise ValueError(f"{label} may not be a symbolic link: {path}")
+    resolved = path.resolve()
+    if not resolved.is_dir():
+        raise ValueError(f"{label} is not a directory: {path}")
+    return resolved
+
+
+def _plain_file(path: Path, label: str) -> Path:
+    if path.is_symlink():
+        raise ValueError(f"{label} may not be a symbolic link: {path}")
+    resolved = path.resolve()
+    if not resolved.is_file():
+        raise ValueError(f"{label} is not a regular file: {path}")
+    return resolved
+
+
+def _relative_name(root: Path, path: Path) -> str:
+    try:
+        relative = path.relative_to(root)
+    except ValueError as exc:
+        raise ValueError(f"{path} is outside source root {root}") from exc
+    name = PurePosixPath(*relative.parts).as_posix()
+    if name in ("", ".") or name == "manifest.json":
+        raise ValueError(f"{path} cannot become a source-bundle member")
+    return name
+
+
+def _add_file(members: dict[str, bytes], root: Path, path: Path) -> None:
+    path = _plain_file(path, "included path")
+    name = _relative_name(root, path)
+    if name in members:
+        raise ValueError(f"source bundle member is included more than once: {name}")
+    members[name] = path.read_bytes()
+    source_size = sum(len(value) for value in members.values())
+    if source_size > _MAX_BUNDLE_BYTES:
+        raise ValueError(f"source members are {source_size} bytes; the limit is {_MAX_BUNDLE_BYTES} bytes")
+
+
+def _add_path(members: dict[str, bytes], root: Path, path: Path) -> None:
+    if path.is_symlink():
+        raise ValueError(f"included path may not be a symbolic link: {path}")
+    resolved = path.resolve()
+    _relative_name(root, resolved)
+    if resolved.is_file():
+        _add_file(members, root, resolved)
+        return
+    if not resolved.is_dir():
+        raise ValueError(f"included path is not a regular file or directory: {path}")
+    for directory, directory_names, file_names in os.walk(resolved, followlinks=False):
+        base = Path(directory)
+        for name in directory_names:
+            child = base / name
+            if child.is_symlink():
+                raise ValueError(f"included path may not contain a symbolic link: {child}")
+        for name in file_names:
+            _add_file(members, root, base / name)
+
+
+def _check_bundle(bundle: bytes, *, api_key: str | None, endpoint: str | None) -> ProgramFacts:
+    """Import the exact ZIP in a fresh child with no user environment."""
+    timeout = _check_timeout()
+    with tempfile.TemporaryDirectory(prefix="cmpnd-source-check-") as directory:
+        bundle_path = Path(directory) / "source.zip"
+        bundle_path.write_bytes(bundle)
+        request = json.dumps({"bundle": str(bundle_path), "api_key": api_key, "endpoint": endpoint})
+        environment = {
+            key: value
+            for key, value in os.environ.items()
+            if key in {"PATH", "SYSTEMROOT", "TMPDIR", "TEMP", "TMP", "LANG", "LC_ALL"}
+        }
+        environment.update({"PYTHONNOUSERSITE": "1", "PYTHONDONTWRITEBYTECODE": "1"})
+        try:
+            checked = subprocess.run(
+                [sys.executable, "-m", "cmpnd._authored_import"],
+                input=request,
+                text=True,
+                capture_output=True,
+                env=environment,
+                timeout=timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise SourceCheckError(
+                f"the authored program did not finish importing within {timeout:g}s. "
+                f"Raise {_CHECK_TIMEOUT_ENV} if module-scope setup needs longer."
+            ) from exc
+    try:
+        answer = json.loads(checked.stdout)
+    except json.JSONDecodeError as exc:
+        detail = checked.stderr.strip() or "the import checker returned no readable answer"
+        raise SourceCheckError(detail) from exc
+    if checked.returncode != 0 or answer.get("error"):
+        raise SourceCheckError(str(answer.get("error") or checked.stderr.strip()))
+    return ProgramFacts.from_json(answer["facts"])
+
+
+def _check_timeout() -> float:
+    raw = os.environ.get(_CHECK_TIMEOUT_ENV)
+    if raw is None:
+        return _CHECK_TIMEOUT_SECONDS
+    try:
+        timeout = float(raw)
+    except ValueError as exc:
+        raise ValueError(f"{_CHECK_TIMEOUT_ENV} must be a positive number of seconds") from exc
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError(f"{_CHECK_TIMEOUT_ENV} must be a positive number of seconds")
+    return timeout