cmpnd 0.6.0__tar.gz → 0.6.2__tar.gz

{cmpnd-0.6.0 → cmpnd-0.6.2}/CLAUDE.md

@@ -2,6 +2,23 @@
 
 Part of the CMPND monorepo. See `../CLAUDE.md` for cross-cutting rules (hash architecture, null handling, testing philosophy).
 
+## This code is released publicly — no private references
+
+Unlike the rest of the monorepo (private), the `cmpnd` package ships to PyPI:
+`python-sdk/cmpnd/**` is **public source**. Anything written there is
+world-readable in the published wheel. So **never put private information in the
+shipped package** — no internal issue-tracker IDs (`CMP-…`), internal URLs or
+dashboards, customer/org names, infra hostnames, or secrets — and that includes
+comments, docstrings, `--help`/CLI strings, error messages, and log lines, not
+just code. Reference an internal ticket in the **commit message or PR
+description** (those live in the private repo), never in the source that ships.
+
+This applies only to the shipped package (`python-sdk/cmpnd/`). Tests
+(`python-sdk/tests/`), `docs/`, and `docs/plans/` are not published in the
+wheel, but prefer keeping issue IDs out of docstrings you might later move into
+the package. When you cite prior work in shipped code, describe the behavior,
+not the ticket.
+
 ## Documentation discipline (docs are as-built, updated in the same commit)
 
 This mirrors the practice that has kept `serve/docs/` in sync with the Go

{cmpnd-0.6.0 → cmpnd-0.6.2}/PKG-INFO

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

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/__init__.py

@@ -131,13 +131,13 @@ def auto_instrument() -> CmpndCallback:
 
     # Persist the compiled-from lineage tag across state-only save/load so a
     # continued optimization still stamps compiled_from_run_id after a disk
-    # reload / process restart (CMP-444).
+    # reload / process restart.
     from . import _program_patch
 
     _program_patch.patch_program_state()
 
     # Emit tool spans for dspy.RLM tool calls, which otherwise bypass
-    # dspy.Tool.__call__'s callbacks and produce no spans (CMP-187).
+    # dspy.Tool.__call__'s callbacks and produce no spans.
     from . import _rlm_patch
 
     _rlm_patch.patch_rlm_tools()

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/_gepa_patch.py

@@ -84,7 +84,7 @@ def patch_gepa() -> None:
 
             # Build the config dict from the GEPA instance, then hand the live
             # program to the shared enrichment helper (one definition of the
-            # optimization_run payload shape, reused by the deploy path — CMP-323).
+            # optimization_run payload shape, reused by the deploy path).
             config = {}
             for key in ["auto", "max_metric_calls", "max_full_evals", "seed", "log_dir"]:
                 val = getattr(self, key, None)
@@ -97,7 +97,7 @@ def patch_gepa() -> None:
             except Exception:
                 pass
 
-            # Restore the up-front budget estimate (CMP-555): for an `auto`
+            # Restore the up-front budget estimate: for an `auto`
             # preset `self.max_metric_calls` is None until GEPA's first budget
             # event, so the initial "running" record shipped 0 and the progress
             # bar / ETA had no denominator. Estimate now instead.
@@ -160,7 +160,7 @@ def patch_gepa() -> None:
         except Exception as e:
             if callback is not None:  # pyright: ignore[reportUnnecessaryComparison]
                 # Flush a terminal 'failed', not just in-memory state — else the
-                # running row start() sent lingers forever (CMP-414).
+                # running row start() sent lingers forever.
                 callback._tracker.finalize_error(e)
             raise
 

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/_program_patch.py

@@ -17,7 +17,7 @@ the state-only path, which is the one DSPy steers users toward.)
 
 DSPy exposes no extension point for out-of-band instance state (no
 ``get_extra_state`` / attribute allowlist; ``metadata`` is DSPy-owned). Rather
-than change DSPy upstream (CMP-444 decision), ``patch_program_state()`` wraps
+than change DSPy upstream, ``patch_program_state()`` wraps
 ``dump_state`` / ``load_state`` on the two classes that define them — the
 composite ``Module`` path and the bare ``Predict`` path — to round-trip the tag
 under a namespaced carrier key. Installed lazily from

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/_rlm_patch.py

@@ -1,4 +1,4 @@
-"""Emit tool spans for ``dspy.RLM`` tool calls (CMP-187).
+"""Emit tool spans for ``dspy.RLM`` tool calls.
 
 cmpnd creates a ``TOOL`` span only from DSPy's ``on_tool_start``/``on_tool_end``
 callbacks, and those fire only through ``dspy.Tool.__call__`` (decorated

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/callback.py

@@ -71,7 +71,7 @@ class _CallbackBase:
         self._capture_inputs = (
             capture_inputs if capture_inputs is not None else (config.capture_inputs if config else True)
         )
-        # Emit an in_progress start for every root trace, not just RLM (CMP-257).
+        # Emit an in_progress start for every root trace, not just RLM.
         self._stream_trace_starts = (
             stream_trace_starts if stream_trace_starts is not None else (config.stream_trace_starts if config else True)
         )
@@ -117,7 +117,7 @@ class _CallbackBase:
         self._eval_handler = eval_handler.EvalHandler(self)
 
         # Active optimization run ID - stored on instance for same thread-safety reason.
-        # Prefixed text id (`op_…`), minted via cmpnd.identity (CMP-238).
+        # Prefixed text id (`op_…`), minted via cmpnd.identity.
         self._active_optimization_run_id: str | None = None
 
         # Token usage from LM calls without a trace context (e.g., GEPA reflection calls)
@@ -188,7 +188,7 @@ class _ModuleMixin(_CallbackBase):
             context.set_current_trace(trace)
 
             # Carry the root module's type so serve can classify the trace at
-            # start (CMP-537) — before any span lands — instead of inferring it
+            # start — before any span lands — instead of inferring it
             # from span shape later.
             trace.root_span_type = span_type.value
             # RLM traces use streaming export (per-span); everything else
@@ -197,7 +197,7 @@ class _ModuleMixin(_CallbackBase):
                 trace.streaming = True
             self._streaming_traces[str(trace.trace_id)] = trace.streaming
 
-            # Emit an in_progress start row for EVERY root trace (CMP-257), not
+            # Emit an in_progress start row for EVERY root trace, not
             # just streaming/RLM ones, so a non-RLM program is visible the moment
             # it starts (`traces search --status in_progress`, a lookupable id)
             # instead of only appearing at finalize. `trace.streaming` still
@@ -251,7 +251,7 @@ class _ModuleMixin(_CallbackBase):
                     # Surface the previous turn's code output on THIS (turn N+1)
                     # span so a streaming reader can fill in turn N's notebook
                     # output mid-run, rather than waiting for the whole trajectory
-                    # on the RLM parent span at finalize (CMP-537). The prior
+                    # on the RLM parent span at finalize. The prior
                     # turn's span has already ended + been exported, so it rides
                     # here instead; the RLM's final turn (no successor) still
                     # resolves at finalize. Capped like an output field so a large
@@ -433,7 +433,7 @@ class _ModuleMixin(_CallbackBase):
                         trace._batch_spans = trace_spans
                         exp.export_trace(trace)
 
-                # Correlate the returned Prediction to its trace (CMP-291).
+                # Correlate the returned Prediction to its trace.
                 # Stored under a leading underscore so it stays a plain instance
                 # attribute — a bare name would route into dspy.Prediction's field
                 # store and surface as a phantom output field. Read it back via the
@@ -785,7 +785,7 @@ class _LMMixin(_CallbackBase):
         # new instructions, between evaluations) and metric (an LLM-as-judge /
         # semantic metric scoring outputs, during evaluation). Rather than drop
         # them, wrap each in its own trace linked to the optimization run so it
-        # shows up alongside the student traces (CMP-485). serve's
+        # shows up alongside the student traces. serve's
         # TracedTokensForRun then accounts for their cost from the span, so these
         # must NOT also be added to _orphaned_lm_usage / untraced_lm_usage — that
         # would double-count them in the optimization total.
@@ -821,7 +821,7 @@ class _LMMixin(_CallbackBase):
         is running — instead of assuming every untraced call is reflection (that
         would mislabel judge calls). The trace is named with the umbrella "GEPA";
         the specific model stays on the span's model_name, and `gepa.phase`
-        carries the distinction (CMP-485). Each becomes a standalone one-span
+        carries the distinction. Each becomes a standalone one-span
         trace so the prompt, response, tokens and cost are visible alongside the
         student traces instead of being reduced to an aggregate token count.
         """
@@ -842,7 +842,7 @@ class _LMMixin(_CallbackBase):
         # context stack, so on_lm_start stamped this span with a parent_span_id for
         # a span that isn't in this standalone one-span trace. This span IS the
         # trace's root, so force it parentless and pin it to this trace so tree/root
-        # reconstruction works (CMP-485, Greptile P1).
+        # reconstruction works.
         span.parent_span_id = None
         span.trace_id = trace.trace_id
         trace.signature_name = span.model_name or phase

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/cli/__init__.py

@@ -87,7 +87,7 @@ def main() -> None:
     auth.register(subparsers)
     login.register(subparsers)
 
-    # Org membership (owner-facing approval queue, CMP-126). Always
+    # Org membership (owner-facing approval queue). Always
     # registered — the server gates each action on org ownership, so a
     # non-owner just gets a 403, not a hidden command.
     org.register(subparsers)
@@ -99,7 +99,7 @@ def main() -> None:
     if os.environ.get("CMPND_CLI_ADMIN") == "1":
         admin.register(subparsers)
 
-    # CMP-70: resource subcommands are dev-only until productized.
+    # Resource subcommands are dev-only until productized.
     # Set CMPND_CLI_DEV=1 to expose programs, traces, optimizations,
     # evals, datasets, and deployments in --help.
     if os.environ.get("CMPND_CLI_DEV") == "1":

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/cli/commands/admin.py

@@ -1,7 +1,7 @@
 """Platform-operator commands, hidden behind CMPND_CLI_ADMIN=1.
 
 `cmpnd admin org create|set-owner|list|get|set-limit|set-github-login|elect-owner`
-is the closed-beta org bootstrap and steward surface (CMP-126/CMP-278/CMP-472):
+is the closed-beta org bootstrap and steward surface:
 stand up a shared org with its GitHub auto-join key, anoint its first owner,
 adjust its member cap or GitHub link, and grant ownership from the election
 queue. `cmpnd admin user …` is the operator's user-lifecycle surface (list,

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/cli/commands/org.py

@@ -1,7 +1,7 @@
 """Org membership + ownership commands (customer-facing).
 
-`cmpnd org members …` is the owner's delegated membership surface (CMP-126,
-CMP-278): list the GitHub users who auto-joined and are awaiting approval and
+`cmpnd org members …` is the owner's delegated membership surface: list
+the GitHub users who auto-joined and are awaiting approval and
 admit/decline them (the pull direction), and issue/list/revoke single-use
 invite links for teammates you want to add (the push direction — `invite`
 prints a URL you share out-of-band; the invitee joins as a member when they
@@ -15,7 +15,7 @@ hit /api/v1/org/ownership-requests and are self-scoped to the calling key's
 user — no owner check (a platform admin grants ownership from the election
 queue; the request is just recorded intent).
 
-`cmpnd org keys list|create|revoke` is your own API-key surface (CMP-472):
+`cmpnd org keys list|create|revoke` is your own API-key surface:
 list the keys you've minted, mint a new scoped key (the response carries the
 one-time token — the server stores only its hash), and revoke one. These hit
 /api/v1/org/keys and are self-scoped to the calling key's user — you only ever

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/cli/commands/top.py

@@ -113,8 +113,8 @@ def _hash_fallback(sig: Any) -> str:
     is what someone would copy/paste. Names should be the common case once the
     Program registry has caught up — this is just the fallback.
     """
-    # program_signature_hash now arrives as a decimal string on the wire
-    # (CMP-331); int(sig) below handles both forms. "0" is the unset sentinel
+    # program_signature_hash now arrives as a decimal string on the wire;
+    # int(sig) below handles both forms. "0" is the unset sentinel
     # alongside numeric 0 / None / "".
     if sig in (None, "", 0, "0"):
         return "—"
@@ -379,7 +379,7 @@ def _render_status(d: dict[str, Any], endpoint: str) -> None:
         print(f"  Deploy prog:   {deploy_program_id}")
     print(f"  Status:        {_status(d.get('status', '—'))}  ({age})")
     print(f"  Created:       {d.get('created_at', '—')}")
-    # The caller's deploy(metadata=…) blob, if any (CMP-293) — the
+    # The caller's deploy(metadata=…) blob, if any — the
     # checkpoint/cursor that produced this program. Omitted when empty ({}).
     metadata = d.get("metadata") or {}
     if metadata:

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/cli/shell.py

@@ -92,7 +92,7 @@ def _logged_out_banner(endpoint: str) -> str:
         f"{_c('cmpnd shell', 'bold')} — not signed in ({endpoint}).\n"
         f"  Set {_c('CMPND_API_KEY', 'bold')} (and optionally "
         f"{_c('CMPND_ENDPOINT', 'bold')}), then restart.\n"
-        f"  Browser-based {_c('cmpnd login', 'bold')} is on the way (CMP-69).\n"
+        f"  Browser-based {_c('cmpnd login', 'bold')} is on the way.\n"
     )
 
 
@@ -300,7 +300,7 @@ def _parse_signature_inputs(program_name: str | None) -> list[str]:
     ``run(body=None, **kwargs)`` form for those.
 
     Stopgap: the deployment record only carries ``program_name`` as a
-    string today, not structured input/output fields. CMP-91 tracks
+    string today, not structured input/output fields. A follow-up tracks
     surfacing those on the serializer (sourced from what the deploy
     service already produces for ``/openapi``). Once that lands, delete
     this function and key off the structured fields instead — they'll

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/cli/trace_render.py

@@ -1,6 +1,6 @@
 """Render a trace's span forest as a tree or an ASCII timeline.
 
-Consumed by ``cmpnd traces show <id>`` (CMP-260). The raw
+Consumed by ``cmpnd traces show <id>``. The raw
 ``GET /api/v1/traces/{id}`` response — ``{"trace": {...}, "spans": [...]}``
 with flat, raw-column-named spans — is turned into something readable when the
 caller opts into ``--tree`` / ``--timeline`` (``show`` is JSON by default, like
@@ -241,7 +241,7 @@ def span_line(span: dict[str, Any], *, color: bool) -> str:
     """One span rendered as a single line: '<type label>  <name> · <duration> ·
     <tokens> · <model>', mirroring serve's span-badge + span-name, then the same
     duration string. Used both as a tree node body and as `traces follow`'s
-    per-span line (CMP-258)."""
+    per-span line."""
     # Two visually distinct segments: the span-type label carries the status
     # hue (green/red/yellow), the span name is bold default-foreground. Bold on
     # the terminal's own fg reads on any background; the two never share a color.

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/configuration.py

@@ -78,12 +78,12 @@ class Config:
     max_queue_size: int = 10000
     max_export_workers: int = 4
 
-    # Emit an in_progress trace_start for every root trace (CMP-257), not just
+    # Emit an in_progress trace_start for every root trace, not just
     # RLM, so non-RLM programs (Predict/ReAct/CoT/optimizer students) are
     # visible while running instead of appearing only at finalize. The exporter
     # coalesces start + batch in one flush, so a fast trace still pays a single
     # insert. Set False to opt out of the extra start (traces then reappear only
-    # at finalize, the pre-CMP-257 behavior).
+    # at finalize, the prior behavior).
     stream_trace_starts: bool = True
 
     # Feature flags

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/context.py

@@ -20,7 +20,7 @@ _span_stack: ContextVar[list[models.SpanBuilder] | None] = ContextVar("cmpnd_spa
 _current_eval_run: ContextVar[models.EvalRunBuilder | None] = ContextVar("cmpnd_current_eval_run", default=None)
 
 # Current optimization run context (set during optimization, used to link
-# evals). Prefixed text id (`op_…`), minted via cmpnd.identity (CMP-238).
+# evals). Prefixed text id (`op_…`), minted via cmpnd.identity.
 _current_optimization_run_id: ContextVar[str | None] = ContextVar("cmpnd_current_optimization_run_id", default=None)
 
 

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/deployment.py

@@ -20,7 +20,7 @@ from . import configuration, execution, identity, packaging
 
 logger = logging.getLogger(__name__)
 
-# CMP-293: the deploy metadata blob is a free-form JSON object committed with
+# The deploy metadata blob is a free-form JSON object committed with
 # the deployment record (the checkpoint/cursor that produced the program). Cap
 # its size — a checkpoint/cursor is a pointer, not a payload. Mirrors serve's
 # maxMetadataBytes so the call-site error matches the server's 413.
@@ -127,7 +127,7 @@ def deploy(module, metric=None, timeout=300, metadata=None):
         metadata: Optional free-form structured dict committed atomically with
             the deployment record — somewhere to put the checkpoint/cursor that
             produced this program, so the deployment is self-describing for a
-            continual-learning loop (CMP-293). Must be a JSON-serializable dict
+            continual-learning loop. Must be a JSON-serializable dict
             with string keys, within 64 KiB. Read it back via the deployment
             record (``cmpnd.status`` / the deployment GET API).
 
@@ -155,7 +155,7 @@ def deploy(module, metric=None, timeout=300, metadata=None):
         # slot and reject an oversized deploy before signing it (Slice E).
         "declared_content_length": len(zip_bytes),
     }
-    # CMP-293: carry the caller's metadata blob (validated at the call site) as a
+    # Carry the caller's metadata blob (validated at the call site) as a
     # reserved top-level body key, committed with the deployment record server-side.
     if metadata is not None:
         _validate_deploy_metadata(metadata)
@@ -170,7 +170,7 @@ def deploy(module, metric=None, timeout=300, metadata=None):
 
     # Forward LM credentials so the server can auto-create a Provider+ProviderKey.
     #
-    # CMP-289 credential policy: forward ONLY a key explicitly set on the LM
+    # Credential policy: forward ONLY a key explicitly set on the LM
     # (`lm.kwargs["api_key"]`). Never harvest it from the environment or the
     # boto3 credential chain — auto-resolving and forwarding env credentials
     # (especially AWS access key / secret / session token for a `bedrock/...`
@@ -211,7 +211,7 @@ def deploy(module, metric=None, timeout=300, metadata=None):
         # Surface non-fatal deploy-time warnings (e.g. no provider credential
         # resolves yet, so execute will 422 until one is configured). The
         # server decides — it knows whether a provider exists — so the SDK only
-        # relays. Backward-compatible: absent on older servers (CMP-289).
+        # relays. Backward-compatible: absent on older servers.
         for warning in data.get("warnings") or []:
             logger.warning("deploy: %s", warning)
 

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/eval_handler.py

@@ -51,7 +51,7 @@ class EvalHandler:
 
         dspy, _ = callback._get_dspy()
 
-        # Create the eval run. CMP-313: no id minted here — the server assigns
+        # Create the eval run. No id minted here — the server assigns
         # it via the synchronous export_eval_start below, once the header
         # fields (program/metric/dataset) are populated.
         eval_run = models.EvalRunBuilder(
@@ -180,7 +180,7 @@ class EvalHandler:
             f"dataset_size={eval_run.dataset_size}"
         )
 
-        # CMP-313: the SDK doesn't mint the eval_run_id — the component behind
+        # The SDK doesn't mint the eval_run_id — the component behind
         # the exporter (serve/observe, or deploy in-Lambda) assigns it. Obtain
         # it synchronously now, before any eval trace ships, since every
         # in-flight trace and the dict keys / span below are stamped with it.

{cmpnd-0.6.0 → cmpnd-0.6.2}/cmpnd/execution.py

@@ -11,6 +11,12 @@ from typing import TYPE_CHECKING
 
 import httpx
 
+# Bound by name, not reached as `httpx.HTTPStatusError`: the SDK's own tests patch this
+# module's whole `httpx` attribute, so constructing the exception off that attribute
+# raises "exceptions must derive from BaseException" under test while working in
+# production. A direct import is the same class both ways.
+from httpx import HTTPStatusError
+
 from . import configuration
 
 if TYPE_CHECKING:
@@ -118,6 +124,26 @@ def _validate_str_map(name, value):
     return value
 
 
+def _upstream_detail(resp: httpx.Response) -> str:
+    """The server's own message for a failed execute, for the exception text.
+
+    Both shapes the platform emits: `{"error": {"message": …}}` (a data plane'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 omits the suffix.
+    """
+    try:
+        data = resp.json()
+    except ValueError:
+        return (resp.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 (resp.text or "").strip()[:2000]
+
+
 def execute(deployment_id, timeout=30, metadata=None, tags=None, **inputs):
     """Execute a deployed DSPy program.
 
@@ -173,5 +199,20 @@ def execute(deployment_id, timeout=30, metadata=None, tags=None, **inputs):
             data = resp.json()
             raise RuntimeError(data.get("error", "Execution failed"))
 
-        resp.raise_for_status()
+        if resp.status_code >= 400:
+            # Same exception `raise_for_status()` would raise — the type is a contract:
+            # this function's docstring promises it, and `tests/stress/_reliability.py`
+            # keys its upstream-outage tolerance on it, so turning a 5xx into anything
+            # else would make every provider hiccup fail a PR instead of skipping.
+            # Only the MESSAGE changes: raise_for_status reports the status and the URL
+            # and drops the body, and the body is where the data plane says what
+            # happened — serve passes it through verbatim (`WriteUpstreamError`). A
+            # sandbox refusal naming the missing module and the user's own file and line
+            # was arriving as a bare "Server error '500 Internal Server Error'".
+            detail = _upstream_detail(resp)
+            raise HTTPStatusError(
+                f"Execution failed with {resp.status_code} for {resp.request.url}" + (f": {detail}" if detail else ""),
+                request=resp.request,
+                response=resp,
+            )
         return Prediction(**resp.json())

cmpnd-0.6.2/cmpnd/exporter.py

@@ -0,0 +1,108 @@
+"""Which exporter the SDK is currently publishing through, and its lifecycle.
+
+The HTTP implementation lives in :mod:`cmpnd.exporter_http`; this module holds
+only the global that names the current one. The split is an import-weight
+change: :mod:`cmpnd.callback` reaches this module for
+:func:`ensure_exporter_started` and :func:`get_exporter` and nothing else, so
+with the transport moved out the whole trace-production path — ``callback``,
+``models``, ``context``, ``helpers``, ``configuration``, ``eval_handler`` —
+imports no third-party module at all, and *defining* a trace no longer costs
+httpx's import. The transport is imported on first export instead, by the
+process that actually exports.
+
+The global is duck-typed, and deliberately so: three callers replace it with an
+in-memory collector to read traces back with no server in the loop —
+``deploy/deploy/executor_handler.py``, ``deploy/deploy/iterate_handler.py`` and
+``worker-sandbox/kernel/worker_kernel/run.py``. They assign
+``cmpnd.exporter._exporter`` under ``_exporter_lock`` directly, which is why the
+registry stays in this module while the implementation moves: an implementation
+detail can be relocated, a seam three components already write to cannot.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING, Any
+
+from . import configuration
+
+if TYPE_CHECKING:
+    # Redundant aliases, which is PEP 484's way of saying "re-exported" rather than
+    # "imported for local use". Without them a type checker is right to warn that
+    # `from cmpnd.exporter import BatchExporter` reaches a private import — and these
+    # two names are deliberately still part of this module's surface, so saying so
+    # here is the fix rather than silencing the warning at each callsite. The runtime
+    # half is `__getattr__` at the bottom of this file.
+    from .exporter_http import BatchExporter as BatchExporter
+    from .exporter_http import ExportItem as ExportItem
+
+_exporter: BatchExporter | None = None
+_exporter_lock = threading.Lock()
+
+
+def get_exporter() -> BatchExporter | None:
+    """Get the global exporter instance."""
+    return _exporter
+
+
+def ensure_exporter_started() -> BatchExporter | None:
+    """Ensure the exporter is started, creating it if necessary."""
+    global _exporter
+
+    with _exporter_lock:
+        if _exporter is None:
+            config = configuration.get_config()
+            if config:
+                # The one place the transport is imported at run time. An
+                # unconfigured SDK — and every collector-backed host, which
+                # installs its own exporter before the callback asks for one —
+                # never reaches it.
+                from .exporter_http import BatchExporter
+
+                _exporter = BatchExporter(config)
+                _exporter.start()
+        return _exporter
+
+
+def flush_exporter(timeout: float = 5.0) -> bool:
+    """Force-publish everything the global exporter has queued, keeping it running.
+
+    A non-destructive alternative to :func:`shutdown_exporter` for a mid-run
+    reader that wants the just-produced trace to exist server-side before
+    fetching it — without tearing the exporter down (which would silently stop
+    later spans from publishing).
+
+    Returns ``True`` if the drain completed within ``timeout``, ``False`` if it
+    timed out or there is no exporter running — so a caller can avoid fetching a
+    trace that may not have been published yet, rather than assuming success.
+    """
+    exp = get_exporter()
+    if exp:
+        return exp.flush(timeout)
+    return False
+
+
+def shutdown_exporter() -> None:
+    """Shutdown the global exporter."""
+    global _exporter
+
+    with _exporter_lock:
+        if _exporter:
+            _exporter.shutdown()
+            _exporter = None
+
+
+# The transport's two names, still importable from here (PEP 562). Moving the
+# implementation was supposed to change what `import cmpnd.exporter` costs, not
+# what it offers, and `from cmpnd.exporter import BatchExporter` is what callers
+# already write. Resolving on attribute access is what keeps the two facts
+# compatible — the import happens only if someone asks for the name.
+_MOVED_TO_TRANSPORT = ("BatchExporter", "ExportItem")
+
+
+def __getattr__(name: str) -> Any:
+    if name in _MOVED_TO_TRANSPORT:
+        from . import exporter_http
+
+        return getattr(exporter_http, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")