cmpnd 0.75.0__tar.gz → 0.77.0__tar.gz

{cmpnd-0.75.0 → cmpnd-0.77.0}/PKG-INFO

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

{cmpnd-0.75.0 → cmpnd-0.77.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.75.0 → cmpnd-0.77.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.75.0 → cmpnd-0.77.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.75.0 → cmpnd-0.77.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.75.0 → cmpnd-0.77.0}/cmpnd/identity.py

@@ -1,9 +1,10 @@
 """Identity and hash computations.
 
-The 64-bit program-identity hash is produced by the structural IR in
+A program's identity is its server-issued program id (``is_program_id``).
+The 64-bit program signature hash is produced by the structural IR in
 :mod:`cmpnd.ir`. ``compute_program_hash`` reflects a live ``dspy.Module``
-through that pipeline; trace, eval, and optimization paths share the
-one encoder.
+through that pipeline, and ``program_naming`` uses the hash only to
+generate a name for a program its user never named.
 
 Sibling hashes (``compute_signature_hash`` for model-sweep grouping,
 ``compute_valset_hash``, ``compute_dataset_hash``, ``compute_metric_hash``,
@@ -84,10 +85,9 @@ def _unsigned_to_signed_int64(value: int) -> int:  # pyright: ignore[reportUnuse
     Written as arithmetic rather than as ``ctypes.c_int64(value).value``, which
     is the identical operation spelled with a C type: mask to 64 bits, then
     subtract 2^64 from anything at or above the sign bit. ``ctypes`` is not
-    merely heavy for a two-line cast, it is *absent* where this has to run — the
-    wasm guest (`worker-wasm/guest/`) imports this module to reproduce the SDK's
-    ``program_signature_hash``, and its CPython has no ``_ctypes`` because there
-    is no libffi for wasi, so the module was never compiled. Equivalence with
+    merely heavy for a two-line cast, it is *absent* from the worker's wasm
+    kernel (`worker-wasm/guest/`), which imports this module, and whose CPython
+    has no ``_ctypes`` because there is no libffi for wasi. Equivalence with
     the ctypes form is asserted over every boundary in ``tests/test_identity.py``.
 
     Imported by ``cmpnd.ir.hash`` and exercised by ``tests/test_identity.py``;
@@ -156,8 +156,9 @@ def validate_program_id(value: object, *, source: str = "program_id") -> str:
 def compute_program_hash(module: Any) -> int | None:
     """Reflect a live ``dspy.Module`` to IR and hash it.
 
-    Returns ``None`` when ``module`` is ``None`` (callers commonly fold
-    this with ``or 0`` for trace-side DEFAULT-0 columns).
+    Returns ``None`` when ``module`` is ``None``. The worker's kernel does not
+    bundle :mod:`cmpnd.ir`, so this raises ``ModuleNotFoundError`` there; the
+    kernel generates no program names, so it never calls this.
     """
     if module is None:
         return None

{cmpnd-0.75.0 → cmpnd-0.77.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.75.0 → cmpnd-0.77.0}/docs/sdk-instrumentation.md

@@ -146,7 +146,7 @@ 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` 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.
+- **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. The worker's kernel replaces that function with one that generates no name, so a kernel never reflects a module.
 
 `python-sdk/cmpnd/identity.py` is the home of every hash the SDK computes.
 
@@ -1035,7 +1035,7 @@ A new hand-rolled serializer on any of those paths reopens the hole. `tests/test
 
 ## See also
 
-- [`./clustering.md`](../../docs/CLUSTERING.md) — the canonical explainer for `signature_hash`. Start here if you're wondering why two identical-looking modules have different hashes. A hash never decides a trace's program.
+- [`CLUSTERING.md`](../../docs/CLUSTERING.md) explains how traces and runs group under a program, and how the program signature hash is computed. A hash never decides a trace's program.
 - [`./optimization-tracking.md`](../../docs/optimization-tracking.md) — how `auto_instrument`'s GEPA patch and `cmpnd/optimizers/tracker.py` turn a `GEPA.compile` call into an `OptimizationRun` with linked evals.
 - The `cmpnd-testing` skill + [`../AGENTS.md`](../AGENTS.md) § "Running Tests & Checks" — patterns for writing callback tests against real databases, including `clear_context()` usage.
 - [`serve/DB.md`](../../serve/DB.md) — the Postgres schema these payloads land in.

{cmpnd-0.75.0 → cmpnd-0.77.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

{cmpnd-0.75.0 → cmpnd-0.77.0}/pyproject.toml

@@ -5,7 +5,7 @@ name = "cmpnd"
 # it's new) — no git tags. Bump with `uv version --bump {minor,patch}` or by
 # hand. Runtime `cmpnd.__version__` reads installed metadata, so it tracks
 # this automatically. See docs/plans/2026-07-02-sdk-pypi-tag-free-publish.md.
-version = "0.75.0"
+version = "0.77.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -41,7 +41,7 @@ dependencies = [
     # Still required, and still the fast path — but `cmpnd/ir/xxh64.py` no
     # longer *needs* it: it falls back to a pure-Python xxh64 that the tests
     # check against this module, so a platform with no wheel and no compiler can
-    # still compute a program's identity. Don't drop the dependency on that
+    # still compute a program's signature hash. Don't drop the dependency on that
     # basis; the C module is an order of magnitude faster and every ordinary
     # install should have it.
     "xxhash>=3.0.0",

{cmpnd-0.75.0 → cmpnd-0.77.0}/uv.lock

@@ -505,7 +505,7 @@ wheels = [
 
 [[package]]
 name = "cmpnd"
-version = "0.75.0"
+version = "0.77.0"
 source = { editable = "." }
 default-groups = ["dspy-3-4-1"]
 dependencies = [