cmpnd 0.83.0__tar.gz → 0.84.0__tar.gz

{cmpnd-0.83.0 → cmpnd-0.84.0}/AGENTS.md

@@ -137,7 +137,13 @@ still install against the `dspy>=…` floor in `dependencies`.
 - `scripts/install-test-env.sh <python> <dspy>` builds `.venv` from one group's
   locked tree, as each `sdk-test` leg in `ci-sdk.yml` does. From the repo root,
   run `just sdk-test-env 3.13 3.3.0`, then, from `python-sdk/`,
-  `.venv/bin/python -m pytest tests/ -k "not e2e"`. `uv sync --extra dev` in
+  `.venv/bin/python -m pytest tests/ -k "not e2e"`. The root recipe
+  `SDK_TEST_PYTHON_VERSION=3.13 SDK_TEST_DSPY_VERSION=3.4.0 just sdk-test-linux`
+  runs the same locked environment in Linux. `SDK_TEST_LINUX_IMAGE` selects a
+  pinned CI builder when reproducing a job. The helper copies the worker pins
+  and truncation vectors and mounts Git metadata read-only for revision tests.
+  The revision tests require Git, which the CI builder provides.
+  `uv sync --extra dev` in
   `python-sdk/` returns to the default group.
 - `--latest` resolves every package fresh, as a user's install today would.
   With the DSPy version `newest` it pins no DSPy either. The daily

{cmpnd-0.83.0 → cmpnd-0.84.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.83.0
+Version: 0.84.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -685,7 +685,7 @@ cmpnd.configure(
     flush_interval_seconds=5.0,            # optional: seconds between flushes
     capture_inputs=True,                   # optional: record span inputs
     capture_outputs=True,                  # optional: record span outputs
-    default_tags={"env": "prod"},          # optional: tags on every trace
+    default_tags={"env": "prod"},          # optional: tags on every trace; a run's own tags override them
 )
 ```
 

{cmpnd-0.83.0 → cmpnd-0.84.0}/README.md

@@ -634,7 +634,7 @@ cmpnd.configure(
     flush_interval_seconds=5.0,            # optional: seconds between flushes
     capture_inputs=True,                   # optional: record span inputs
     capture_outputs=True,                  # optional: record span outputs
-    default_tags={"env": "prod"},          # optional: tags on every trace
+    default_tags={"env": "prod"},          # optional: tags on every trace; a run's own tags override them
 )
 ```
 

{cmpnd-0.83.0 → cmpnd-0.84.0}/cmpnd/callback.py

@@ -538,6 +538,7 @@ class _CallbackBase:
         stream_trace_starts: bool | None = None,
         own_config: configuration.Config | None = None,
         optimization_phase: str | None = None,
+        producer_context: dict[str, Any] | None = None,
     ) -> None:
         # A client passes its own config here; the auto_instrument callback leaves
         # it None and reads the process-global config live, so a reconfigure()
@@ -547,6 +548,24 @@ class _CallbackBase:
         # later cmpnd.configure(). That fixedness is what keeps a client
         # orthogonal to the global config.
         self._own_config = own_config
+        producer_context = producer_context or {}
+        self._producer_references = tuple(
+            (name, producer_context[name])
+            for name in (
+                "program_id",
+                "deployment_id",
+                "deployment_run_id",
+                "optimization_run_id",
+                "eval_run_id",
+                "compiled_from_run_id",
+            )
+            if producer_context.get(name) is not None
+        )
+        self._producer_tags = tuple((producer_context.get("tags") or {}).items())
+        self._producer_metadata = tuple((producer_context.get("metadata") or {}).items())
+        self._producer_projects = (
+            tuple(producer_context["project_tags"]) if "project_tags" in producer_context else None
+        )
         # The optimization phase this callback traces for a run it does not own: an
         # executor that scores a hosted rollout with the author's metric ("metric") or runs
         # the author's GEPA proposer ("reflection"). Such a process knows the program the
@@ -621,7 +640,7 @@ class _CallbackBase:
 
         # Active optimization run ID - stored on instance for same thread-safety reason.
         # Prefixed text id (`op_…`), minted via cmpnd.identity.
-        self._active_optimization_run_id: str | None = None
+        self._active_optimization_run_id: str | None = dict(self._producer_references).get("optimization_run_id")
 
         # Token usage from LM calls without a trace context (e.g., GEPA reflection calls)
         # Accumulated during optimization and included in the finalization payload
@@ -722,19 +741,18 @@ class _CallbackBase:
         return configuration._current_program_id()
 
     def _stamp(self, builder: Any) -> Any:
-        """Stamp this callback's project tags, and on a trace its program, onto a
-        builder it just created. A span's program is its trace's, so a span carries
-        no program of its own.
+        """Stamp this callback's trace context before any spans begin.
 
         A trace from a call that declares a program name carries the name and no id,
         and the exporter resolves the name. The declared name wins over a program id the
         client's config read from ``CMPND_PROGRAM_ID``, and the callback warns once that it did.
         A trace that gets neither gets a generated name in `_create_trace`.
         """
-        builder.project_tags = self._resolve_project_tags()
         if isinstance(builder, models.TraceBuilder):
-            program_id = self._resolve_program_id()
-            name = _declared_program_name()
+            builder.project_tags = list(self._resolve_project_tags() or ())
+            producer_program_id = dict(self._producer_references).get("program_id")
+            program_id = producer_program_id or self._resolve_program_id()
+            name = None if producer_program_id else _declared_program_name()
             if name is not None:
                 if program_id is not None and not self._warned_name_over_id:
                     self._warned_name_over_id = True
@@ -765,6 +783,18 @@ class _CallbackBase:
             return _exporter_pool.ensure_exporter_started(self._own_config)
         return exporter.get_exporter()
 
+    def _apply_producer_context(self, trace: models.TraceBuilder) -> None:
+        for name, value in self._producer_references:
+            setattr(trace, name, value)
+        if dict(self._producer_references).get("program_id") is not None:
+            trace.declared_name = trace.generated_name = None
+        if self._producer_projects is not None:
+            trace.project_tags = list(self._producer_projects)
+        # A run's tags and metadata are more specific than the process defaults
+        # already on the trace, so they override them.
+        trace.tags.update(self._producer_tags)
+        trace.metadata.update(self._producer_metadata)
+
     def _ensure_exporter(self) -> Any:
         """Start this callback's exporter if it is not already running."""
         if self._own_config is not None:
@@ -780,6 +810,60 @@ class _CallbackBase:
         span makes ``to_api_dict`` bound the whole body by the same limits rather
         than by the 64 KiB default.
         """
+        if context.get_current_trace() is None:
+            config = self._own_config or configuration.get_config()
+            kwargs.setdefault(
+                "project_tags",
+                list(
+                    self._producer_projects
+                    if self._producer_projects is not None
+                    else self._resolve_project_tags() or ()
+                ),
+            )
+            # Most specific wins: process defaults, then the run's tags, then the span's own.
+            kwargs["tags"] = {
+                **(config.default_tags if config else {}),
+                **dict(self._producer_tags),
+                **kwargs.get("tags", {}),
+            }
+            for key, value in self._producer_references:
+                kwargs.setdefault(key, value)
+            run_id = self._active_optimization_run_id or context.get_current_optimization_run_id()
+            kwargs.setdefault("optimization_run_id", run_id)
+            kwargs.setdefault("eval_run_id", self._active_eval_run.eval_run_id if self._active_eval_run else None)
+            program_id = (
+                kwargs.get("program_id") or self._resolve_program_id() or context.optimization_program_id(run_id)
+            )
+            declared = None if kwargs.get("program_id") else _declared_program_name()
+            if declared is not None:
+                program_id = None
+            kwargs.setdefault("program_id", program_id)
+            from cmpnd_ingest.program_names import ProgramName
+            from cmpnd_ingest.span_context import ExportContext, SpanContext
+
+            kwargs.setdefault(
+                "export_context",
+                ExportContext(
+                    ProgramName(declared) if declared else None,
+                    program_id,
+                    declared is None or program_id is not None,
+                ),
+            )
+            phase = self._optimization_phase or (
+                ("metric" if self._active_eval_run else "reflection") if run_id else None
+            )
+            if phase is not None:
+                kwargs["tags"]["optimization_phase"] = phase
+            kwargs.setdefault(
+                "span_context",
+                SpanContext(
+                    project_tags=tuple(kwargs["project_tags"]),
+                    tags=tuple(kwargs["tags"].items()),
+                    program_id=program_id,
+                    optimization_run_id=kwargs["optimization_run_id"],
+                    eval_run_id=kwargs["eval_run_id"],
+                ),
+            )
         return context.create_child_span(
             name,
             span_type,
@@ -1220,7 +1304,7 @@ class _ModuleMixin(_CallbackBase):
 
     def _create_trace(self, instance: Any, inputs: dict[str, Any]) -> models.TraceBuilder:
         """Create a new trace for a root module call."""
-        config = configuration.get_config()
+        config = self._own_config or configuration.get_config()
 
         trace = models.TraceBuilder(
             trace_id=uuid4(),
@@ -1364,16 +1448,16 @@ class _ModuleMixin(_CallbackBase):
         preview = helpers.create_preview(helpers.clean_inputs(inputs, dspy, self._max_input_field_size))
         trace.request_preview = preview
 
-        # Apply default tags
+        # Process default tags first, then the run's own labels over them.
         if config and config.default_tags:
             trace.tags.update(config.default_tags)
+        self._apply_producer_context(trace)
         # A trace opened while this callback traces a phase, or while a local run
         # calls its metric, is the metric's or the proposer's, never a rollout, even
         # when its module is the program's own class.
         phase = self._optimization_phase or context.get_current_optimization_phase()
         if phase is not None:
             trace.tags["optimization_phase"] = phase
-
         return trace
 
     def _extract_usage_from_prediction(self, span: models.SpanBuilder, outputs: Any, dspy: Any) -> None:
@@ -1631,7 +1715,8 @@ class _LMMixin(_CallbackBase):
         # would double-count them in the optimization total.
         current_trace = context.get_current_trace()
         if current_trace is None and (
-            self._active_optimization_run_id is not None or self._optimization_phase is not None
+            (span.span_context is not None and span.span_context.optimization_run_id is not None)
+            or self._optimization_phase is not None
         ):
             self._emit_optimization_lm_trace(span)
             return  # handled as a standalone GEPA-process trace
@@ -1678,11 +1763,12 @@ class _LMMixin(_CallbackBase):
         instead, and may have no run id: it traces the metric or the proposer of a
         run whose id the ingest key the trace is pushed with decides.
         """
-        run_id = self._active_optimization_run_id
+        assert span.span_context is not None
+        run_id = span.span_context.optimization_run_id
         if not run_id and self._optimization_phase is None:
             return
 
-        phase = self._optimization_phase or ("metric" if self._active_eval_run is not None else "reflection")
+        phase = dict(span.span_context.tags).get("optimization_phase", "reflection")
         span.attributes["gepa.phase"] = phase
         span.attributes["optimization.role"] = _OPTIMIZATION_PHASE_ROLES[phase]
 
@@ -1692,11 +1778,14 @@ class _LMMixin(_CallbackBase):
             end_time=span.end_time,
             module_class="GEPA",
         )
-        self._stamp(trace)
-        # The call has no root module to name a program after, so a trace that declares
-        # neither an id nor a name takes the program the run optimizes.
-        if trace.program_id is None and trace.declared_name is None:
-            trace.program_id = context.optimization_program_id(run_id)
+        trace.program_id = span.span_context.program_id
+        trace.deployment_id = span.span_context.deployment_id
+        trace.deployment_run_id = span.span_context.deployment_run_id
+        trace.compiled_from_run_id = span.span_context.compiled_from_run_id
+        trace.project_tags = list(span.span_context.project_tags)
+        trace.tags = dict(span.span_context.tags)
+        trace.metadata = dict(self._producer_metadata)
+        trace._export_context = span.export_context
         # A metric-phase call can start while DSPy's Evaluate span is still on the
         # 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
@@ -1707,8 +1796,7 @@ class _LMMixin(_CallbackBase):
         trace.signature_name = span.model_name or phase
         trace.status = span.status
         trace.optimization_run_id = run_id
-        if self._active_eval_run is not None:
-            trace.eval_run_id = self._active_eval_run.eval_run_id
+        trace.eval_run_id = span.span_context.eval_run_id
         trace.tags["optimization_phase"] = phase
 
         # Single-span trace: roll the span's usage up onto the trace so the
@@ -2169,6 +2257,11 @@ class _InterpreterMixin(_CallbackBase):
             "parent_span": context.get_current_span(),
             "start_time": datetime.now(timezone.utc),
         }
+        trace = context.get_current_trace()
+        parent = frame["parent_span"]
+        frame["trace_id"] = trace.trace_id if trace else parent.trace_id
+        frame["span_context"] = trace.span_context() if trace else parent.span_context
+        frame["export_context"] = trace.export_context if trace else parent.export_context
         self._interpreter_tool_frames[call_id] = frame
         # Publish this frame as the one a nested on_tool_start marks, in this
         # context only. The token restores the prior frame (nested tool calls) on
@@ -2209,13 +2302,15 @@ class _InterpreterMixin(_CallbackBase):
         parent = frame["parent_span"]
         span = models.SpanBuilder(
             span_id=uuid4(),
-            trace_id=parent.trace_id if parent else None,
+            trace_id=frame["trace_id"],
             name=f"Tool.{frame['tool_name']}",
             span_type=models.SpanType.TOOL,
             parent_span_id=parent.span_id if parent else None,
             start_time=frame["start_time"],
             max_input_size=self._max_input_field_size,
             max_output_size=self._max_output_field_size,
+            span_context=frame["span_context"],
+            export_context=frame["export_context"],
         )
         span.attributes["tool.name"] = str(frame["tool_name"])
         span.attributes["tool.synthesized"] = "true"

{cmpnd-0.83.0 → cmpnd-0.84.0}/cmpnd/configuration.py

@@ -257,11 +257,11 @@ def require_config() -> Config:
 def _current_project_tags() -> list[str] | None:  # pyright: ignore[reportUnusedFunction]  # used cross-module as a dataclass default_factory
     """Read the currently-configured project tags, or None if unconfigured.
 
-    Called at payload serialization time so that a configure(project_tags=...)
-    call after a TraceBuilder is constructed still gets the fresh value.
+    Builders copy these values when execution begins, so later configuration
+    changes affect only future traces and spans.
     """
     cfg = get_config()
-    return cfg.project_tags if cfg else None
+    return list(cfg.project_tags) if cfg and cfg.project_tags is not None else None
 
 
 def _current_program_id() -> str | None:  # pyright: ignore[reportUnusedFunction]  # used cross-module as a dataclass default_factory

{cmpnd-0.83.0 → cmpnd-0.84.0}/cmpnd/context.py

@@ -2,11 +2,13 @@
 
 from __future__ import annotations
 
+import json
 from collections.abc import Generator
 from contextlib import contextmanager
-from contextvars import ContextVar
+from contextvars import ContextVar, Token
 from datetime import datetime, timezone
-from typing import TYPE_CHECKING, Any
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, Literal
 from uuid import uuid4
 
 if TYPE_CHECKING:
@@ -14,6 +16,42 @@ if TYPE_CHECKING:
 
 # Current trace context
 _current_trace: ContextVar[models.TraceBuilder | None] = ContextVar("cmpnd_current_trace", default=None)
+_producer_context: ContextVar[str | None] = ContextVar("cmpnd_producer_context", default=None)
+
+
+def producer_context(encoded: str | None) -> _ProducerContext:
+    """Bind one immutable producer snapshot without changing process configuration."""
+    return _ProducerContext(encoded)
+
+
+class _ProducerContext:
+    # Generator context managers assign exception.__traceback__ while unwinding.
+    # A worker's frozen WIT error must cross this boundary unchanged.
+    def __init__(self, encoded: str | None) -> None:
+        self._encoded = encoded
+        self._token: Token[str | None] | None = None
+
+    def __enter__(self) -> None:
+        if self._token is not None:
+            raise RuntimeError("producer context is already active")
+        if self._encoded is not None and not isinstance(json.loads(self._encoded), dict):
+            raise TypeError("producer context must be a JSON object")
+        self._token = _producer_context.set(self._encoded)
+
+    def __exit__(
+        self, _kind: type[BaseException] | None, _error: BaseException | None, _traceback: TracebackType | None
+    ) -> Literal[False]:
+        if self._token is not None:
+            _producer_context.reset(self._token)
+            self._token = None
+        return False
+
+
+def _current_producer_context() -> dict[str, Any]:  # pyright: ignore[reportUnusedFunction]  # read by span builders
+    """Return a fresh view so a builder cannot mutate another span's context."""
+    encoded = _producer_context.get()
+    return json.loads(encoded) if encoded else {}
+
 
 # Stack of active spans (for nested spans). A tuple, replaced on every push and
 # pop and never mutated: a context copy (``contextvars.copy_context()``, an
@@ -168,6 +206,7 @@ def create_child_span(
 def clear_context() -> None:
     """Clear all trace/span context. Useful for testing."""
     _current_trace.set(None)
+    _producer_context.set(None)
     _span_stack.set(())
     _current_eval_run.set(None)
     _current_optimization_run_id.set(None)

{cmpnd-0.83.0 → cmpnd-0.84.0}/cmpnd/models.py

@@ -11,6 +11,9 @@ from enum import Enum
 from typing import Any
 from uuid import UUID, uuid4
 
+from cmpnd_ingest.bodies import SpanBody
+from cmpnd_ingest.program_names import ProgramName
+from cmpnd_ingest.span_context import ExportContext, SpanContext
 from cmpnd_ingest.trace_facts import CompletionFact, MetadataFact, StartedFact, StringMapChange
 
 from . import imaging
@@ -736,9 +739,9 @@ class SpanBuilder:
     name: str
     span_type: SpanType = SpanType.UNKNOWN
     parent_span_id: UUID | None = None
-    trace_id: UUID | None = None
+    trace_id: UUID | None = field(default_factory=uuid4)
 
-    start_time: datetime | None = None
+    start_time: datetime | None = field(default_factory=lambda: datetime.now(timezone.utc))
     end_time: datetime | None = None
 
     status: TraceStatus = TraceStatus.UNSET
@@ -817,7 +820,73 @@ class SpanBuilder:
     max_output_size: int | None = None
 
     # Snapshot project_tags at construction time to avoid reconfigure races in async export
-    project_tags: list[str] | None = field(default_factory=configuration._current_project_tags)
+    project_tags: list[str] | None = None
+    tags: dict[str, str] = field(default_factory=dict)
+    program_id: str | None = None
+    deployment_id: str | None = None
+    deployment_run_id: str | None = None
+    optimization_run_id: str | None = None
+    eval_run_id: str | None = None
+    compiled_from_run_id: str | None = None
+    span_context: SpanContext | None = field(default=None, repr=False)
+    export_context: ExportContext | None = field(default=None, repr=False)
+    _submitted_body: SpanBody | None = field(default=None, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        from . import context
+
+        if self.trace_id is None:
+            self.trace_id = uuid4()
+        if self.start_time is None:
+            self.start_time = datetime.now(timezone.utc)
+        trace = context.get_current_trace()
+        if trace is not None and self.trace_id == trace.trace_id:
+            inherited = trace.span_context()
+            if self.export_context is None:
+                self.export_context = trace.export_context
+        else:
+            config = configuration.get_config()
+            producer = context._current_producer_context()
+            optimization_run_id = producer.get("optimization_run_id") or context.get_current_optimization_run_id()
+            eval_run = context.get_current_eval_run()
+            inherited = SpanContext(
+                project_tags=tuple(producer["project_tags"])
+                if "project_tags" in producer
+                else (tuple(config.project_tags or ()) if config else ()),
+                # A run's tags are more specific than the process defaults, so they win.
+                tags=tuple({**(config.default_tags if config else {}), **producer.get("tags", {})}.items()),
+                program_id=producer.get("program_id")
+                or (config.program_id if config else None)
+                or context.optimization_program_id(optimization_run_id),
+                deployment_id=producer.get("deployment_id"),
+                deployment_run_id=producer.get("deployment_run_id"),
+                optimization_run_id=optimization_run_id,
+                eval_run_id=producer.get("eval_run_id") or (eval_run.eval_run_id if eval_run else None),
+                compiled_from_run_id=producer.get("compiled_from_run_id"),
+            )
+        inherited = self.span_context or inherited
+        refs = {
+            name: getattr(self, name) if getattr(self, name) is not None else getattr(inherited, name)
+            for name in (
+                "program_id",
+                "deployment_id",
+                "deployment_run_id",
+                "optimization_run_id",
+                "eval_run_id",
+                "compiled_from_run_id",
+            )
+        }
+        self.span_context = SpanContext(
+            project_tags=tuple(self.project_tags) if self.project_tags is not None else inherited.project_tags,
+            tags=tuple({**dict(inherited.tags), **self.tags}.items()),
+            **refs,
+        )
+        self.project_tags = list(self.span_context.project_tags)
+        self.tags = dict(self.span_context.tags)
+        if self.export_context is None:
+            self.export_context = ExportContext(program_id=self.span_context.program_id, resolved=True)
+        if self.span_type == SpanType.LM_CALL and self.lm_usage is None:
+            self.lm_usage = LMUsageObservationV1()
 
     def set_inputs(self, inputs: dict[str, Any]) -> None:
         """Set span inputs."""
@@ -882,7 +951,13 @@ class SpanBuilder:
     def to_api_dict(self) -> dict[str, Any]:
         """Convert to API-compatible dictionary."""
         max_in, max_out = self._limits()
+        if self.span_type == SpanType.LM_CALL:
+            if self.lm_usage is None:
+                self.lm_usage = LMUsageObservationV1()
+            if self.lm_usage.observed_at is None:
+                self.lm_usage.observed_at = self.end_time or self.start_time
         return {
+            "schema_version": 1,
             "span_id": str(self.span_id),
             "trace_id": str(self.trace_id) if self.trace_id else None,
             "parent_span_id": str(self.parent_span_id) if self.parent_span_id else None,
@@ -923,10 +998,18 @@ class SpanBuilder:
             "attributes": _safe_serialize(self._build_attributes(max_out)),
             "events": truncate_field(_safe_serialize(self.events), max_out),
             "adapter_type": self.adapter_type,
-            "project": self.project_tags[0] if self.project_tags else None,
-            "project_tags": self.project_tags if self.project_tags else [],
+            "project": self.span_context.project_tags[0]
+            if self.span_context and self.span_context.project_tags
+            else None,
+            **(_safe_serialize(self.span_context.to_dict()) if self.span_context else {}),
         }
 
+    def seal_for_export(self) -> SpanBody:
+        """Freeze the first completed body for every route that later carries it."""
+        if self._submitted_body is None:
+            self._submitted_body = SpanBody(self.to_api_dict())
+        return self._submitted_body
+
 
 @dataclass
 class TraceBuilder:
@@ -958,6 +1041,8 @@ class TraceBuilder:
     # the configuration at construction like project_tags. None declares none,
     # and the key is then left off the wire rather than sent as null.
     program_id: str | None = field(default_factory=configuration._current_program_id)
+    deployment_id: str | None = None
+    deployment_run_id: str | None = None
     # The program name the trace declares, or None. It never goes on the wire: the
     # exporter resolves it to a program id and writes that into ``program_id`` on the
     # bodies it sends, unless the trace already carries an id.
@@ -1010,10 +1095,41 @@ class TraceBuilder:
     _sealed_tags: dict[str, str] = field(default_factory=dict, init=False, repr=False)
     _sealed_metadata: dict[str, str] = field(default_factory=dict, init=False, repr=False)
     _sealed_project_tags: tuple[str, ...] = field(default=(), init=False, repr=False)
+    _export_context: ExportContext | None = field(default=None, init=False, repr=False)
+
+    @property
+    def export_context(self) -> ExportContext:
+        """One resolution decision shared by the trace and every queued span."""
+        if self._export_context is None:
+            name = (
+                ProgramName(self.declared_name)
+                if self.declared_name
+                else (ProgramName(self.generated_name, generated=True) if self.generated_name else None)
+            )
+            self._export_context = ExportContext(name, self.program_id, self.program_id is not None or name is None)
+        return self._export_context
+
+    @property
+    def span_export_contexts(self) -> tuple[ExportContext | None, ...]:
+        return tuple(span.export_context for span in self._batch_spans)
+
+    def span_context(self) -> SpanContext:
+        """Snapshot the context for a span beginning now."""
+        return SpanContext(
+            project_tags=tuple(self.project_tags or ()),
+            tags=tuple(self.tags.items()),
+            program_id=self.program_id,
+            deployment_id=self.deployment_id,
+            deployment_run_id=self.deployment_run_id,
+            optimization_run_id=self.optimization_run_id,
+            eval_run_id=self.eval_run_id,
+            compiled_from_run_id=self.compiled_from_run_id,
+        )
 
     def seal_start(self) -> None:
         """Retain the first creation snapshot and its independent annotations."""
         if self._started_fact is None:
+            self.export_context
             self._started_fact = StartedFact.from_payload(self.to_start_dict())
             self.seal_metadata()
 
@@ -1052,8 +1168,16 @@ class TraceBuilder:
         self.seal_metadata()
 
     def _with_facts(self, payload: dict[str, Any], *, completion: bool = False, started: bool = True) -> dict[str, Any]:
+        payload["schema_version"] = 1
+        if self.deployment_id is not None:
+            payload["deployment_id"] = self.deployment_id
+        if self.deployment_run_id is not None:
+            payload["deployment_run_id"] = self.deployment_run_id
         if self._started_fact is not None:
             creation = self._started_fact.creation_dict()
+            for name in ("program_id", "deployment_id", "deployment_run_id"):
+                if name not in creation:
+                    payload.pop(name, None)
             payload.update(creation if started else {key: value for key, value in creation.items() if key in payload})
             if started:
                 payload["started_fact"] = self._started_fact.to_dict()
@@ -1099,7 +1223,7 @@ class TraceBuilder:
                 "metadata": _safe_serialize(self.metadata),
                 "project": self.project_tags[0] if self.project_tags else None,
                 "project_tags": self.project_tags if self.project_tags else [],
-                "spans": [s.to_api_dict() for s in self._batch_spans] if self._batch_spans else [],
+                "spans": [s.seal_for_export().to_api_dict() for s in self._batch_spans] if self._batch_spans else [],
                 **self._declared_program(),
             },
             completion=True,

{cmpnd-0.83.0 → cmpnd-0.84.0}/docs/client.md

@@ -151,8 +151,8 @@ endpoint. None of these reads the global config:
   metadata=None, tags=None, lm=None, **inputs)` runs one deployment and returns
   a `dspy.Prediction`. `deployment` is a `DeployedProgram` or a deployment id.
   `entrypoint` picks the module to run inside a deployment that holds more than
-  one. `metadata` and `tags` are `dict[str, str]` values the platform applies
-  to the run's root trace. The run spends the credential its deployment
+  one. `metadata` and `tags` are `dict[str, str]` values the run's traces and
+  spans carry, overriding the worker process's `default_tags`. The run spends the credential its deployment
   recorded. A `program_name` among the inputs raises `TypeError` and names
   `entrypoint=`.
 - `sdk.submit_deployment_run`, `list_deployment_runs`, `get_deployment_run`,