cmpnd 0.74.0__tar.gz → 0.76.0__tar.gz

{cmpnd-0.74.0 → cmpnd-0.76.0}/PKG-INFO

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

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/_gepa_patch.py

@@ -133,9 +133,8 @@ def _run_tracked_compile(
         max_metric_calls=max_metric_calls,
     )
 
-    # `enrich_from_program` hashed the student, so its generated name reuses that hash.
     if client_config is None and trk.program_id is None and dspy_callback._declared_program_name() is None:
-        trk.generated_program_name = program_naming.generated_program_name(student, trk.program_signature_hash)
+        trk.generated_program_name = program_naming.generated_program_name(student)
 
     restore_attribution = callback.start_trace_attribution()
 

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/callback.py

@@ -1188,16 +1188,11 @@ class _ModuleMixin(_CallbackBase):
                     identity.get_field_schema(field_info.annotation) for field_info in output_fields.values()
                 ]
 
-            span.program_signature_hash = identity.compute_program_hash(instance) or 0
-
             # For ChainOfThought, also capture extended signature
             if hasattr(instance, "extended_signature"):
                 ext_sig = instance.extended_signature
                 span.attributes["extended_signature"] = getattr(ext_sig, "signature", str(ext_sig))
 
-        else:
-            span.program_signature_hash = identity.compute_program_hash(instance) or 0
-
         # Capture demo count and contents if available
         demos = getattr(instance, "demos", None)
         if demos:
@@ -1257,9 +1252,6 @@ class _ModuleMixin(_CallbackBase):
         elif hasattr(instance, "predict") and hasattr(instance.predict, "signature"):
             signature = instance.predict.signature
 
-        # The root module's signature hash, once a branch below computes it. An unnamed
-        # program's generated name reuses it rather than reflecting the module again.
-        program_hash: int | None = None
         if signature:
             # Single-signature module (Predict, ChainOfThought, etc.)
             sig_name = getattr(signature, "__name__", None)
@@ -1287,12 +1279,10 @@ class _ModuleMixin(_CallbackBase):
                     identity.get_field_schema(field_info.annotation) for field_info in output_fields.values()
                 ]
 
-            program_hash = identity.compute_program_hash(instance)
-            trace.program_signature_hash = program_hash or 0
             trace.signature_summary = identity.build_signature_summary(signature)
         else:
             # Multi-child module: collect Predict children via DSPy's own walker
-            # for metadata; the hash is the structural one from the IR reflector.
+            # for metadata.
             dspy_mod, _ = _get_dspy()
             children: list[tuple[str, Any]] = []
             if dspy_mod and hasattr(instance, "named_predictors"):
@@ -1303,8 +1293,6 @@ class _ModuleMixin(_CallbackBase):
 
             if children:
                 trace.signature_name = instance.__class__.__name__
-                program_hash = identity.compute_program_hash(instance)
-                trace.program_signature_hash = program_hash or 0
 
                 # Build component_signatures for grouped field display
                 components = []
@@ -1340,7 +1328,7 @@ class _ModuleMixin(_CallbackBase):
         if trace.program_id is None and trace.declared_name is None:
             trace.program_id = context.optimization_program_id(trace.optimization_run_id)
         if trace.program_id is None and trace.declared_name is None:
-            trace.generated_name = program_naming.generated_program_name(instance, program_hash)
+            trace.generated_name = program_naming.generated_program_name(instance)
             _warn_once_about_generated_name(trace)
 
         # Detect if this is a compiled program (from optimization)

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/cli/commands/evals.py

@@ -13,7 +13,7 @@ def _add_list_args(p: ArgumentParser) -> None:
         "--program",
         dest="program_name",
         metavar="NAME",
-        help="Only the runs of the program with this name, current or retired",
+        help="Only the runs of the program whose current name is NAME",
     )
     p.add_argument(
         "--module",

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/cli/commands/programs.py

@@ -211,9 +211,9 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         "rename",
         help="Name or rename a program",
         description=(
-            "Make NAME the current name of PROGRAM. The name it had keeps resolving to it, so code that still "
-            "declares the old name reaches the same program, with its id and history. A name another program "
-            "answers to is refused."
+            "Make NAME the current name of PROGRAM, which keeps its id and history. The name it had is free at "
+            "once: it no longer resolves, and any program can take it, so code that still declares the old name "
+            "reaches a new program. Another program's current name is refused."
         ),
     )
     rename.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/cli/commands/top.py

@@ -1440,7 +1440,10 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         help="Deploy authored Python source (file or stdin)",
         description=(
             "Stage authored Python without executing it in this process, check its "
-            "entrypoint in a fresh child, and upload the exact staged bundle."
+            "entrypoint in a fresh child, and upload the exact staged bundle.\n\n"
+            "The platform deploys only a program a user named. PROGRAM_NAME is such a name. "
+            "A program with no name, or with a name a client generated, is refused until "
+            "`cmpnd programs rename <p_id> <name>` names it."
         ),
         epilog=(
             "Examples:\n"
@@ -1501,7 +1504,10 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
             "dspy.Prediction(score=, feedback=): gepa writes each new instruction by "
             "reading that feedback, so a score-only metric is refused before the run "
             "starts. `--reflection-model` is required for the same reason — it names "
-            "the model that does the writing."
+            "the model that does the writing.\n\n"
+            "The platform optimizes only a program a user named. A --deployment-id whose "
+            "program has no name, or a name a client generated, such as an optimization's "
+            "result, is refused until `cmpnd programs rename <p_id> <name>` names it."
         ),
         epilog=(
             "Examples:\n"

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/cli/verbs.py

@@ -167,7 +167,7 @@ DOMAIN_VERBS: dict[str, str] = {
     "trash": "moves a program to the Trash, where it stays restorable, and delete would read as the permanent purge",
     "restore": "returns a program from the Trash with its history, which create would not",
     "purge": "deletes a program in the Trash for good, the irreversible step after trash",
-    "rename": "gives a program a new current name and keeps the old one resolving to it, which update would hide",
+    "rename": "gives a program a new current name and frees the old one for any program, which update would hide",
 }
 
 #: Leaves naming a related collection or sub-record rather than an action.

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/eval_handler.py

@@ -87,16 +87,10 @@ class EvalHandler:
         if program:
             eval_run.module_class = program.__class__.__name__
 
-            # Hash via the IR reflector on the live module so the class tag
-            # discriminates correctly; signature_summary is still derived from
-            # the root signature for human display.
-            program_hash = identity.compute_program_hash(program)
-            if program_hash is not None:
-                eval_run.program_signature_hash = program_hash
+            # The summary comes from the root signature, for human display.
             signature = identity.get_program_signature(program)
             if signature:
                 eval_run.signature_summary = identity.build_signature_summary(signature)
-                logger.debug(f"Eval run program_signature_hash: {eval_run.program_signature_hash}")
 
                 # Extract input field names for filtering example inputs in on_evaluate_end
                 if hasattr(signature, "input_fields"):
@@ -177,9 +171,7 @@ class EvalHandler:
                 eval_run._dataset_exists = None  # Will include examples as fallback
 
         exp = self._callback._current_exporter()
-        eval_run.program_id = self._program_id(
-            exp, program, eval_run.program_signature_hash, eval_run.optimization_run_id
-        )
+        eval_run.program_id = self._program_id(exp, program, eval_run.optimization_run_id)
 
         logger.info(
             f"EvalRun created: program_id={eval_run.program_id}, "
@@ -216,9 +208,7 @@ class EvalHandler:
         self._callback._call_id_to_span[call_id] = span
         context.push_span(span)
 
-    def _program_id(
-        self, exp: Any, program: Any, program_hash: int | None, optimization_run_id: str | None
-    ) -> str | None:
+    def _program_id(self, exp: Any, program: Any, optimization_run_id: str | None) -> str | None:
         """The program id the eval run carries, resolved the way a trace's is.
 
         A program name the call declares wins over the callback's program id. A run
@@ -227,9 +217,7 @@ class EvalHandler:
         The exporter resolves either name now, on the caller's thread, because the run's
         start is sent synchronously and must carry the id. The exporter keeps the answer
         for the process, so a name its traces already resolved costs no request. A name
-        the exporter cannot resolve leaves the run without an id. ``program_hash`` is the
-        evaluated program's signature hash, already computed for the run, so naming the
-        program does not reflect it again.
+        the exporter cannot resolve leaves the run without an id.
         """
         from . import callback
 
@@ -238,9 +226,7 @@ class EvalHandler:
             program_id = self._callback._resolve_program_id() or context.optimization_program_id(optimization_run_id)
             if program_id is not None or program is None:
                 return program_id
-            return program_naming.resolve_generated_name(
-                exp, program_naming.generated_program_name(program, program_hash)
-            )
+            return program_naming.resolve_generated_name(exp, program_naming.generated_program_name(program))
         # Read with getattr because the member is optional: an in-memory collector
         # that resolves no names has none.
         resolve = getattr(exp, "resolve_program_name", None)

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/identity.py

@@ -97,23 +97,6 @@ def _unsigned_to_signed_int64(value: int) -> int:  # pyright: ignore[reportUnuse
     return masked - 0x10000000000000000 if masked >= 0x8000000000000000 else masked
 
 
-def format_signature_hash(value: int | None) -> str | None:
-    """Render a ``program_signature_hash`` for the JSON wire as a quoted decimal
-    string (e.g. ``"-935109221252960526"``), or ``None`` when absent.
-
-    The hash is a signed int64 (xxhash64). Emitting it as a JSON *number* is
-    unsafe: any consumer that decodes through an untyped path floats it and
-    loses precision above 2^53 (Go ``any``/``map[string]any``, JavaScript
-    natively). Carrying it as a string makes the safe representation automatic
-    end to end. Storage stays signed int64; only the wire value is a
-    string. ``None`` stays ``None`` (nullable optimization hash); the trace/span
-    ``0`` sentinel renders as ``"0"``.
-    """
-    if value is None:
-        return None
-    return str(value)
-
-
 # A program id is server-issued: ``p_`` and twelve base62 characters, the shape
 # every platform id shares. The SDK never mints one; it carries the id serve gives
 # a program name, or the id a deployment's worker passes to the kernel.

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/models.py

@@ -13,7 +13,7 @@ from uuid import UUID, uuid4
 
 from cmpnd_ingest.trace_facts import CompletionFact, MetadataFact, StartedFact, StringMapChange
 
-from . import identity, imaging
+from . import imaging
 
 # U+0000 (NUL) and lone UTF-16 surrogates are valid JSON, and valid in a Python
 # str, but the server cannot store either: a JSON column rejects both, and a NUL
@@ -758,8 +758,6 @@ class SpanBuilder:
     # Each element is None for primitives, or a schema dict for complex types
     signature_input_field_schemas: list[dict[str, Any] | None] = field(default_factory=list)
     signature_output_field_schemas: list[dict[str, Any] | None] = field(default_factory=list)
-    # Hash of input/output fields+types for program identity (xxhash64, signed)
-    program_signature_hash: int = 0
 
     # DSPy-specific: Module info
     module_type: str | None = None
@@ -905,7 +903,6 @@ class SpanBuilder:
             "signature_output_field_descs": self.signature_output_field_descs,
             "signature_input_field_schemas": self.signature_input_field_schemas,
             "signature_output_field_schemas": self.signature_output_field_schemas,
-            "program_signature_hash": identity.format_signature_hash(self.program_signature_hash),
             "module_type": self.module_type,
             "module_name": self.module_name,
             "model_name": self.model_name,
@@ -945,7 +942,6 @@ class TraceBuilder:
     # The root DSPy module's class. The program's own name is `declared_name`,
     # which the transport resolves to `program_id`.
     module_class: str | None = None
-    program_version: str | None = None
 
     # Signature info - identifies the program by its inputs/outputs
     signature_name: str | None = None
@@ -956,7 +952,6 @@ class TraceBuilder:
     # Schemas for complex types (Pydantic models, dataclasses)
     signature_input_field_schemas: list[dict[str, Any] | None] = field(default_factory=list)
     signature_output_field_schemas: list[dict[str, Any] | None] = field(default_factory=list)
-    program_signature_hash: int = 0  # Hash of input/output fields+types (legacy program key)
     signature_summary: str | None = None  # Human-readable: "input1, input2 -> output1, output2"
     component_signatures: list[dict[str, Any]] = field(default_factory=list)
     # The server-issued program id the trace declares (`p_…`), snapshotted from
@@ -1080,7 +1075,6 @@ class TraceBuilder:
                 "module_class": self.module_class,
                 # Also under the key a serve from before module_class reads (StartedFact.creation_dict).
                 "program_name": self.module_class,
-                "program_version": self.program_version,
                 "signature_name": self.signature_name,
                 "signature_input_fields": self.signature_input_fields,
                 "signature_output_fields": self.signature_output_fields,
@@ -1088,7 +1082,6 @@ class TraceBuilder:
                 "signature_output_field_types": self.signature_output_field_types,
                 "signature_input_field_schemas": self.signature_input_field_schemas,
                 "signature_output_field_schemas": self.signature_output_field_schemas,
-                "program_signature_hash": identity.format_signature_hash(self.program_signature_hash),
                 "signature_summary": self.signature_summary,
                 # The server forwards this blob verbatim into a jsonb column, and its
                 # program registration is best-effort (a rejection is only logged), so
@@ -1123,13 +1116,11 @@ class TraceBuilder:
                 "module_class": self.module_class,
                 # Also under the key a serve from before module_class reads (StartedFact.creation_dict).
                 "program_name": self.module_class,
-                "program_version": self.program_version,
                 "signature_name": self.signature_name,
                 "signature_input_fields": self.signature_input_fields,
                 "signature_output_fields": self.signature_output_fields,
                 "signature_input_field_types": self.signature_input_field_types,
                 "signature_output_field_types": self.signature_output_field_types,
-                "program_signature_hash": identity.format_signature_hash(self.program_signature_hash),
                 "signature_summary": self.signature_summary,
                 "component_signatures": _safe_serialize(self.component_signatures),
                 "root_span_type": self.root_span_type,
@@ -1287,9 +1278,6 @@ class EvalRunBuilder:
     metric_name: str | None = None
     dataset_hash: str | None = None
     dataset_size: int = 0
-    # The evaluated module's signature hash (legacy program key). None when the run has
-    # no module, and then sent as null.
-    program_signature_hash: int | None = None
     signature_summary: str | None = None  # Human-readable: "input1, input2 -> output1"
 
     # Model Configuration
@@ -1411,7 +1399,6 @@ class EvalRunBuilder:
             "metric_name": self.metric_name or "",
             "dataset_hash": self.dataset_hash or "",
             "dataset_size": self.dataset_size,
-            "program_signature_hash": identity.format_signature_hash(self.program_signature_hash),
             "signature_summary": self.signature_summary,
             "model_name": self.model_name,
             "model_provider": self.model_provider,
@@ -1432,7 +1419,6 @@ class EvalRunBuilder:
             "metric_name": self.metric_name or "",
             "dataset_hash": self.dataset_hash or "",
             "dataset_size": self.dataset_size,
-            "program_signature_hash": identity.format_signature_hash(self.program_signature_hash),
             "signature_summary": self.signature_summary,
             "model_name": self.model_name,
             "model_provider": self.model_provider,

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/optimizers/gepa.py

@@ -146,10 +146,6 @@ class TrackedGEPA:
 
         component_signature_hash = identity.compute_signature_hash(config.get("components", []))
 
-        # Compute program_signature_hash via the IR reflector — same encoder
-        # the trace path uses, so optimization_runs and traces join on identity.
-        program_signature_hash = identity.compute_program_hash(student) or 0
-
         # Initialize optimization tracking
         self._tracker = tracker.OptimizationTracker(
             optimizer_type="gepa",
@@ -159,7 +155,6 @@ class TrackedGEPA:
             reflection_model_name=reflection_model_name,
             valset_hash=valset_hash,
             component_signature_hash=component_signature_hash,
-            program_signature_hash=program_signature_hash,
         )
 
         # This path builds its tracker without `enrich_from_program`, so it types the
@@ -170,9 +165,7 @@ class TrackedGEPA:
         # SDK generates for the student, the name its rollouts' traces carry, and
         # resolves it when the run starts.
         if self._tracker.program_id is None and callback._declared_program_name() is None:
-            self._tracker.generated_program_name = program_naming.generated_program_name(
-                student, program_signature_hash
-            )
+            self._tracker.generated_program_name = program_naming.generated_program_name(student)
 
         # Store both sets for dataset payload building
         self._tracker._trainset = list(trainset)

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/optimizers/resume.py

@@ -30,7 +30,7 @@ def sidecar_path(log_dir: str) -> str:
     return os.path.join(log_dir, _SIDECAR)
 
 
-def write_run_id(log_dir: str, run_id: str, program_signature_hash: int | None, start_time: datetime | None) -> None:
+def write_run_id(log_dir: str, run_id: str, program_id: str | None, start_time: datetime | None) -> None:
     """Persist the server-assigned ``run_id`` into ``log_dir`` so a later resume
     can re-adopt it. Called at ``start()``, which runs before GEPA creates its
     ``run_dir`` — so create the directory if it isn't there yet. Best-effort: a
@@ -38,7 +38,7 @@ def write_run_id(log_dir: str, run_id: str, program_signature_hash: int | None,
     """
     payload = {
         "run_id": run_id,
-        "program_signature_hash": program_signature_hash,
+        "program_id": program_id,
         "start_time": start_time.isoformat() if start_time is not None else None,
     }
     try:
@@ -49,15 +49,16 @@ def write_run_id(log_dir: str, run_id: str, program_signature_hash: int | None,
         logger.warning("could not write resume sidecar in %s: %s", log_dir, e)
 
 
-def read_resumable(log_dir: str, program_signature_hash: int | None) -> tuple[str, datetime | None] | None:
+def read_resumable(log_dir: str, program_id: str | None) -> tuple[str, datetime | None] | None:
     """Return ``(run_id, start_time)`` to re-adopt, or ``None`` if this is not a
     resumable job.
 
     Resumable requires: GEPA's ``gepa_state.bin`` checkpoint present (else GEPA
     itself starts fresh) AND a readable sidecar carrying a ``run_id``. A definite
-    ``program_signature_hash`` mismatch (a different program reusing the same
-    ``log_dir``) is rejected so it can't hijack the id; a missing hash on either
-    side errs toward stitching, since ``log_dir`` is the strong identity signal.
+    ``program_id`` mismatch (a different program reusing the same ``log_dir``) is
+    rejected so it can't hijack the id. A missing program id on either side errs
+    toward stitching, since ``log_dir`` is the strong identity signal. A sidecar an
+    older SDK wrote names no program id, so it stitches.
     """
     if not os.path.exists(os.path.join(log_dir, _CHECKPOINT)):
         return None
@@ -71,13 +72,13 @@ def read_resumable(log_dir: str, program_signature_hash: int | None) -> tuple[st
     if not run_id:
         return None
 
-    prior_hash = data.get("program_signature_hash")
-    if prior_hash is not None and program_signature_hash is not None and prior_hash != program_signature_hash:
+    prior_program = data.get("program_id")
+    if prior_program is not None and program_id is not None and prior_program != program_id:
         logger.warning(
-            "resume sidecar in %s is for a different program (hash %s != %s); not re-adopting",
+            "resume sidecar in %s is for a different program (%s != %s); not re-adopting",
             log_dir,
-            prior_hash,
-            program_signature_hash,
+            prior_program,
+            program_id,
         )
         return None
 

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/optimizers/tracker.py

@@ -274,7 +274,6 @@ class OptimizationTracker:
         reflection_model_name: str = "",
         valset_hash: str = "",
         component_signature_hash: str = "",
-        program_signature_hash: int = 0,
     ):
         # The SDK no longer mints this id. It stays None until start()
         # runs the synchronous start POST and adopts the id assigned by the
@@ -303,8 +302,6 @@ class OptimizationTracker:
         self.trainset_hash = ""  # individual trainset hash
         self.valset_individual_hash = ""  # individual valset hash
         self.component_signature_hash = component_signature_hash  # SHA256[:16] for model sweep grouping
-        # Program signature hash - matches trace format (64-bit int from input/output fields+types)
-        self.program_signature_hash = program_signature_hash
         self.start_time = datetime.now(timezone.utc)
 
         # Collected data
@@ -751,7 +748,7 @@ class OptimizationTracker:
         log_dir = self.config.get("log_dir") if self.config else None
         if not log_dir or not self.optimization_run_id:
             return False
-        readopted = resume.read_resumable(log_dir, self.program_signature_hash)
+        readopted = resume.read_resumable(log_dir, self.program_id)
         return readopted is not None and readopted[0] == self.optimization_run_id
 
     def finalize_error(self, exception: BaseException) -> None:
@@ -853,7 +850,7 @@ class OptimizationTracker:
         # that id (and its original start_time, so duration stays cumulative)
         # instead of minting a fresh row. Jobs without a log_dir stay per-run.
         log_dir = self.config.get("log_dir") if self.config else None
-        readopted = resume.read_resumable(log_dir, self.program_signature_hash) if log_dir else None
+        readopted = resume.read_resumable(log_dir, self.program_id) if log_dir else None
         if readopted is not None:
             self.optimization_run_id, prior_start = readopted
             if prior_start is not None:
@@ -870,7 +867,7 @@ class OptimizationTracker:
         self._publish_program()
         # Persist the id so a later resume of the same log_dir re-adopts it.
         if log_dir and self.optimization_run_id:
-            resume.write_run_id(log_dir, self.optimization_run_id, self.program_signature_hash, self.start_time)
+            resume.write_run_id(log_dir, self.optimization_run_id, self.program_id, self.start_time)
         logger.info(
             f"Started optimization tracking: run_id={self.optimization_run_id}, "
             f"max_metric_calls={self.max_metric_calls}"
@@ -1169,7 +1166,6 @@ class OptimizationTracker:
             "reflection_model_name": self.reflection_model_name,
             "valset_hash": self.valset_hash,
             "component_signature_hash": self.component_signature_hash,
-            "program_signature_hash": identity.format_signature_hash(self.program_signature_hash),
             "start_time": self.start_time.isoformat() if self.start_time else None,
             "end_time": self.end_time.isoformat() if self.end_time else None,
             "duration_ms": duration_ms,
@@ -1435,13 +1431,6 @@ def enrich_from_program(
     trk.component_signature_hash = identity.compute_signature_hash(components)
     trk.component_types = code_component_types(student)
 
-    # Program signature hash from the live module (routes through the IR
-    # reflector so Predict vs ChainOfThought discriminates — don't pass a bare
-    # signature).
-    program_hash = identity.compute_program_hash(student)
-    if program_hash is not None:
-        trk.program_signature_hash = program_hash
-
     # Model names.
     if lm is not None and getattr(lm, "model", None):
         trk.model_name = lm.model or ""

{cmpnd-0.74.0 → cmpnd-0.76.0}/cmpnd/program_naming.py

@@ -34,7 +34,7 @@ _NAME_PUNCTUATION = "._-"
 _RESERVED_PREFIX = "p_"
 
 
-def generated_program_name(module: Any, signature_hash: int | None = None) -> str:
+def generated_program_name(module: Any) -> str:
     """The name the SDK gives the program ``module`` runs as, when its user named none.
 
     The name is the module's class and twelve hex digits of its signature hash, such as
@@ -43,13 +43,10 @@ def generated_program_name(module: Any, signature_hash: int | None = None) -> st
     names. An optimizer's new instructions and demos keep the shape, so they keep the
     name. The name always fits the program-name syntax, whatever the class is called.
 
-    A caller that already holds ``identity.compute_program_hash(module)`` passes it as
-    ``signature_hash``, so the module is reflected once. Without it, this function
-    computes the hash.
+    The SDK sends the signature hash nowhere else, so naming the program is the only
+    place that reflects the module for it.
     """
-    if signature_hash is None:
-        signature_hash = identity.compute_program_hash(module)
-    signature_hash = signature_hash or 0
+    signature_hash = identity.compute_program_hash(module) or 0
     suffix = f"{signature_hash & 0xFFFF_FFFF_FFFF_FFFF:016x}"[:_SUFFIX_DIGITS]
     return f"{_class_part(module.__class__.__name__)}-{suffix}"
 

{cmpnd-0.74.0 → cmpnd-0.76.0}/docs/cli.md

@@ -28,6 +28,18 @@ already has its program, and a program name with it is refused when the file
 binds no program. In the shell, `deploy()` and `optimize()` take the
 program name as `program=`.
 
+The platform deploys and optimizes only a program a user named. A program name
+given here, to `cmpnd.Program(name, ...)` or to `cmpnd programs rename` is one.
+A program with no name, or with a name a client generated, such as an
+optimization's result, is refused with `409` and error code `program_unnamed`,
+and the error names the command that fixes it:
+`cmpnd programs rename <p_id> <name>`. It also tells you to declare that name in
+your code with `@cmpnd.program("<name>")` or `cmpnd.Program("<name>", ...)`. The
+rename frees the generated name, so code that declares no name sends its later
+traces to a new program under the generated name. Deployments of such a program that
+already exist keep serving. A rename never clears the name of a program with
+a deployment that can serve.
+
 `cmpnd programs create PROGRAM_NAME` makes the program ahead of time and prints
 its id on stdout. It refuses a program name that already has a program. The
 command reports what it created on stderr, and `--json` prints serve's whole
@@ -108,11 +120,12 @@ PROGRAM name up as the other `cmpnd programs` commands do, and sends
 `POST /api/v1/programs/{id}/rename`. The command needs `traces:write` or
 `optimizations:write`.
 
-The old name keeps resolving to the program, so code that still declares it
-reaches the same program. A program with no name takes its first name this
-way, and code that declares the new name with `cmpnd.Program(name, ...)`
-traces to it. Serve refuses a name another live
-program answers to, as its current or a retired name. A program in the Trash
+The old name is free at once. It no longer resolves to the program, and any
+program of the organization can take it, so code that still declares the old
+name with `cmpnd.Program(name, ...)` reaches a new program, not this one.
+Update that code to the new name. A program with no name takes its first name
+this way, and code that declares the new name traces to it. Serve refuses
+another live program's current name. A program in the Trash
 is refused until `cmpnd programs restore` returns it. A server from before the
 rename route says so, and the error points at the program's page in the web
 app, which renames it too.
@@ -460,8 +473,8 @@ optimization result, not a program. Each group's `--help` names the column its
 IDs come from.
 
 `cmpnd evals list [--program NAME] [--module CLASS] [--metric] [--status]`
-lists eval runs, newest first. `--program` takes the program's name, current
-or retired, and a name no program answers to is an error that names it.
+lists eval runs, newest first. `--program` takes the program's current
+name, and a name no program holds is an error that names it.
 `--module` takes the evaluated module's class, such as `ReAct`, and matches it
 exactly. The CLI sends them as `program_name` and `module_class`. Each eval
 run in `evals list`, `evals show` and `programs evals` names what it evaluated

{cmpnd-0.74.0 → cmpnd-0.76.0}/docs/sdk-instrumentation.md

@@ -139,14 +139,16 @@ and every other name still raises. `TestDspyHookCoverage` in
 `tests/test_callback.py` asserts the coverage against whatever DSPy is installed,
 so the next release that adds a hook is caught by CI rather than by a user's logs.
 
-### Signature extraction and signature_hash
+### Signature extraction and the program signature hash
 
-This doc does not re-derive hash semantics — see [`./clustering.md`](../../docs/CLUSTERING.md) for why `signature_hash` exists and how xxhash maps to a signed Int64. Here's only _where_ it gets attached:
+No record the SDK sends carries the program signature hash. A trace, an eval run and an
+optimization run name their program by `program_id`.
+[`CLUSTERING.md`](../../docs/CLUSTERING.md) explains how the hash is computed.
 
-- **On a span** — `_capture_module_attributes` in `callback.py`. After walking `instance.signature.input_fields` / `output_fields` and recording types and schemas, it calls `compute_signature_hash(signature)` and stores the result on `span.signature_hash`. Composite modules (multi-child `dspy.Module` subclasses) take the `compute_composite_signature_hash` branch.
-- **On a trace** — `_create_trace` in `callback.py`. Same split: single-signature modules hash directly; composite modules walk `dspy.Predict` children and call the composite helper.
+- **On a span** — `_capture_module_attributes` in `callback.py` walks `instance.signature.input_fields` / `output_fields` and records names, types, descriptions and schemas. It reflects nothing, because a span never names a program.
+- **On a trace** — `_create_trace` in `callback.py` records the root signature, or for a composite module the `dspy.Predict` children's signatures as `component_signatures`. A root module call that names no program reflects the module once, for the name the SDK generates (`program_naming.generated_program_name`). The hash goes into that name and nowhere else.
 
-Both code paths import from `python-sdk/cmpnd/identity.py`, which is the authoritative home of every hash the SDK computes.
+`python-sdk/cmpnd/identity.py` is the home of every hash the SDK computes.
 
 ---
 
@@ -690,7 +692,10 @@ the top level and in `started_fact`, and again under `program_name`, the key a
 serve from before `module_class` reads and digests a start from. A standalone
 optimizer LM trace sends `GEPA` there. No trace body carries the program's own name: a declared name
 travels as the program id it resolves to, as "A declared program name resolves
-to an id in the exporter" describes.
+to an id in the exporter" describes. No trace body carries a version either. A
+trace serve executed names its version by the `deployment_id` serve stamps on
+it, and `TraceBuilder` has no `program_version` field. A program that wants to
+record a version of its own, such as a git SHA, adds it as a project tag.
 
 The callback seals `started_fact` after it sets the root type, before the
 module executes. It keeps that snapshot even when start emission is disabled.
@@ -735,7 +740,7 @@ What it captures beyond the normal span flow:
 - An `EvalRunBuilder` (constructed at `eval_handler.py:79`) that groups all per-example traces under one eval ID.
 - The metric name (via `get_metric_name` from `python-sdk/cmpnd/helpers.py`) and inferred provider.
 - Links to the enclosing optimization run when one exists (`eval_handler.py:85`), so eval runs triggered inside `GEPA.compile` roll up under the optimization in the UI.
-- The program the run evaluates, as `program_id`. A program name the call declares wins: the exporter resolves it with `resolve_program_name`, the same once-per-process answer its traces use, on the caller's thread because the eval start is sent synchronously. Without a declared name, the run takes the callback's program id, else the program of the optimization run it belongs to. A run with none of these resolves the name the SDK generates for the evaluated module, the name that module's traces carry, with `resolve_program_name(name, generated=True)`. A name serve refuses leaves the run without an id. The evaluated module's class goes as `module_class`, and again under `program_name`, the key a serve from before `module_class` reads. A run with no module sends `program_signature_hash` as null.
+- The program the run evaluates, as `program_id`. A program name the call declares wins: the exporter resolves it with `resolve_program_name`, the same once-per-process answer its traces use, on the caller's thread because the eval start is sent synchronously. Without a declared name, the run takes the callback's program id, else the program of the optimization run it belongs to. A run with none of these resolves the name the SDK generates for the evaluated module, the name that module's traces carry, with `resolve_program_name(name, generated=True)`. A name serve refuses leaves the run without an id. The evaluated module's class goes as `module_class`, and again under `program_name`, the key a serve from before `module_class` reads. The run sends no `program_signature_hash`.
 - The exporter it publishes through: the callback's own (`_current_exporter`), so a client's eval runs go to the client's account.
 - The dataset — on `on_evaluate_start` it triggers the `dataset_sync` pre-flight described above.
 
@@ -761,7 +766,6 @@ The trace payload is built in `python-sdk/cmpnd/models.py` by `TraceBuilder.to_a
     "trace_id": "...",
     "parent_span_id": "...",
     "span_type": "predict",
-    "signature_hash": -3847510293847,  # signed Int64
     "signature_input_fields": ["question"],
     "signature_output_fields": ["answer"],
     "model_name": "gpt-4o-mini",
@@ -813,9 +817,8 @@ name form. A program name wins over the config's id. `configure()`
 checks the id's shape and raises `ValueError` on a bad one, and a `Config` built directly
 is checked the same way.
 
-The id rides every body that can declare a program. A deployment create names its program
-by the id alone and sends no `program_signature_hash`. The other bodies still carry the
-hash beside the id:
+The id rides every body that can declare a program. No body carries a
+`program_signature_hash`:
 
 | Body | Where | Built by |
 |---|---|---|

{cmpnd-0.74.0 → cmpnd-0.76.0}/ingest/cmpnd_ingest/program_names.py

@@ -11,8 +11,9 @@ This module keeps the answers. The transport makes the requests, because they ri
 client and its retry budget.
 
 An answer is kept for the life of the process. A name that serve later points at
-another program reaches a process only when the process starts again, and a renamed
-program's old name keeps resolving to it.
+another program reaches a process only when the process starts again. A rename frees
+the old name, so a process that resolved it before the rename keeps sending to the
+renamed program, and a process started after it gets a new program under that name.
 
 A name settles in one of two ways. Serve gives an id, or serve refuses the name, as a
 server without program names does with ``405``. A refused name sends its traces without