cmpnd 0.72.0__tar.gz → 0.74.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.72.0
+Version: 0.74.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -157,9 +157,12 @@ dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
 dspy.ChainOfThought("question -> answer")(question="What is DSPy?")
 ```
 
-These traces carry no program, so the platform files them under Unattributed.
-The first one in a process logs a warning that points to `@cmpnd.program` and
-`cmpnd.Client`. Calling a `cmpnd.Program` directly while `auto_instrument()` is
+Each program shape gets a program of its own, under a name the SDK generates
+from its class and signature, such as `ChainOfThought-17e1f4089a24`. These
+programs do not count toward your plan's program limit. The first such trace in
+a process logs a warning that names the generated name and shows how to give the
+program a real one: `@cmpnd.program(name)` or `cmpnd.Program(name, module=..., lm=...)`,
+run through `cmpnd.Client`. Calling a `cmpnd.Program` directly while `auto_instrument()` is
 on raises a `TypeError` that points to the client. The API reference below
 lists the options of `cmpnd.configure()`.
 
@@ -640,8 +643,8 @@ captured input and output size limits, 65,536 bytes each by default.
 
 ### `cmpnd.auto_instrument()`
 
-Registers the callback with DSPy, so every DSPy call records a trace. The
-traces carry no program and land in Unattributed.
+Registers the callback with DSPy, so every DSPy call records a trace. Each
+trace goes to a program under a name the SDK generates for its root module.
 
 ### `cmpnd.Client()`
 

{cmpnd-0.72.0 → cmpnd-0.74.0}/README.md

@@ -106,9 +106,12 @@ dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
 dspy.ChainOfThought("question -> answer")(question="What is DSPy?")
 ```
 
-These traces carry no program, so the platform files them under Unattributed.
-The first one in a process logs a warning that points to `@cmpnd.program` and
-`cmpnd.Client`. Calling a `cmpnd.Program` directly while `auto_instrument()` is
+Each program shape gets a program of its own, under a name the SDK generates
+from its class and signature, such as `ChainOfThought-17e1f4089a24`. These
+programs do not count toward your plan's program limit. The first such trace in
+a process logs a warning that names the generated name and shows how to give the
+program a real one: `@cmpnd.program(name)` or `cmpnd.Program(name, module=..., lm=...)`,
+run through `cmpnd.Client`. Calling a `cmpnd.Program` directly while `auto_instrument()` is
 on raises a `TypeError` that points to the client. The API reference below
 lists the options of `cmpnd.configure()`.
 
@@ -589,8 +592,8 @@ captured input and output size limits, 65,536 bytes each by default.
 
 ### `cmpnd.auto_instrument()`
 
-Registers the callback with DSPy, so every DSPy call records a trace. The
-traces carry no program and land in Unattributed.
+Registers the callback with DSPy, so every DSPy call records a trace. Each
+trace goes to a program under a name the SDK generates for its root module.
 
 ### `cmpnd.Client()`
 

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

@@ -58,13 +58,19 @@ def _run_tracked_compile(
 
     ``client_config`` scopes the run record to a client: the record takes that
     config's project tags and program id as they are, absent ones included, so a
-    client that names no program sends none rather than the global config's. The
-    global path passes no client config and keeps the tracker's global snapshot.
+    client that names no program sends none rather than the global config's. A client
+    always runs a named program, so its run never takes a generated name, even when the
+    name did not resolve. The global path passes no client config and keeps the
+    tracker's global snapshot. With no program id there, the run takes the name the SDK
+    generates for the student, the name its rollouts' traces carry, unless the call
+    declares a name.
     ``has_callbacks`` is passed by the patch (resolved once at patch time); a
     client leaves it None and it is resolved here.
     """
     import dspy
 
+    from . import callback as dspy_callback
+    from . import program_naming
     from .optimizers import gepa_callback, tracker
 
     if has_callbacks is None:
@@ -127,6 +133,10 @@ 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)
+
     restore_attribution = callback.start_trace_attribution()
 
     try:

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

@@ -9,7 +9,7 @@ from datetime import datetime, timezone
 from typing import Any
 from uuid import UUID, uuid4
 
-from . import configuration, context, eval_handler, exporter, helpers, identity, models, references
+from . import configuration, context, eval_handler, exporter, helpers, identity, models, program_naming, references
 
 logger = logging.getLogger(__name__)
 
@@ -39,24 +39,23 @@ def _declared_program_name() -> str | None:
     return name if isinstance(name, str) else None
 
 
-# Set once the process has warned that a trace names no program, so the warning
-# appears once per process, whichever callback records the trace.
-_warned_unattributed = False
+# Set once the process has warned that a program has no name, so the warning appears
+# once per process, whichever callback records the trace.
+_warned_unnamed = False
 
 
-def _warn_once_if_unattributed(trace: models.TraceBuilder) -> None:
-    """Warn the first time a trace in this process names neither a program name nor a program id.
-
-    Such a trace belongs to no program, and the platform files it under Unattributed.
-    """
-    global _warned_unattributed
-    if _warned_unattributed or trace.declared_name is not None or trace.program_id is not None:
+def _warn_once_about_generated_name(trace: models.TraceBuilder) -> None:
+    """Warn the first time a trace in this process goes to a program under a generated name."""
+    global _warned_unnamed
+    if _warned_unnamed or trace.generated_name is None:
         return
-    _warned_unattributed = True
+    _warned_unnamed = True
     logger.warning(
-        "cmpnd: this trace names no program, so the platform files it under Unattributed. Give the program a "
-        "name with @cmpnd.program(name) and run it through cmpnd.Client, and its traces go to that program. "
-        "This warning appears once per process."
+        "cmpnd: this program has no name, so its traces go to the program named %r, a name cmpnd generated from "
+        "its class and its signature. Name the program with @cmpnd.program(name) or "
+        "cmpnd.Program(name, module=..., lm=...) and run it through a cmpnd.Client, and its traces go to the program "
+        "with that name. This warning appears once per process.",
+        trace.generated_name,
     )
 
 
@@ -711,6 +710,7 @@ class _CallbackBase:
         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):
@@ -1214,10 +1214,6 @@ class _ModuleMixin(_CallbackBase):
             module_class=instance.__class__.__name__,
         )
         self._stamp(trace)
-        # A root module call is where a program runs, so it is where an unnamed one
-        # is caught. GEPA's own LM calls (_emit_optimization_lm_trace) belong to the
-        # optimization run, which names the program, so they never warn.
-        _warn_once_if_unattributed(trace)
 
         # Attach the run ids this trace starts under, from this callback's own
         # state right now — not at finalize (on_module_end), where the
@@ -1261,6 +1257,9 @@ 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)
@@ -1288,7 +1287,8 @@ class _ModuleMixin(_CallbackBase):
                     identity.get_field_schema(field_info.annotation) for field_info in output_fields.values()
                 ]
 
-            trace.program_signature_hash = identity.compute_program_hash(instance) or 0
+            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
@@ -1303,7 +1303,8 @@ class _ModuleMixin(_CallbackBase):
 
             if children:
                 trace.signature_name = instance.__class__.__name__
-                trace.program_signature_hash = identity.compute_program_hash(instance) or 0
+                program_hash = identity.compute_program_hash(instance)
+                trace.program_signature_hash = program_hash or 0
 
                 # Build component_signatures for grouped field display
                 components = []
@@ -1332,6 +1333,16 @@ class _ModuleMixin(_CallbackBase):
                     components.append(comp)
                 trace.component_signatures = components
 
+        # A trace that declares neither an id nor a name takes the program of the
+        # optimization run it belongs to, so a run's judge modules land in the program it
+        # optimizes. Otherwise a root module call is where a program runs, so it is where
+        # an unnamed one gets its generated name. A span never names a program.
+        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)
+            _warn_once_about_generated_name(trace)
+
         # Detect if this is a compiled program (from optimization)
         if hasattr(instance, "_optimization_run_id"):
             trace.compiled_from_run_id = str(instance._optimization_run_id)
@@ -1661,6 +1672,10 @@ class _LMMixin(_CallbackBase):
             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)
         # 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

{cmpnd-0.72.0 → cmpnd-0.74.0}/cmpnd/cli/commands/admin.py

@@ -121,6 +121,12 @@ def _register_org(sub: _SubParsersAction[ArgumentParser]) -> None:
     elect_owner.add_argument("user_id", help="User id to make owner")
     elect_owner.set_defaults(func=handle_org_elect_owner)
 
+    usage = osub.add_parser(
+        "usage", help="Show the org's limits in use and its activity over 24 hours, 7 days and 30 days"
+    )
+    _org_id_arg(usage)
+    usage.set_defaults(func=handle_org_usage)
+
     plan = osub.add_parser("plan", help="An org's plan and its limits")
     plsub = plan.add_subparsers(dest="org_plan_action")
     plan_show = plsub.add_parser("show", help="Show the org's plan and every limit as it resolves for the org")
@@ -162,6 +168,10 @@ def _register_user(sub: _SubParsersAction[ArgumentParser]) -> None:
     _user_id_arg(show)
     show.set_defaults(func=handle_user_show)
 
+    activity = usub.add_parser("activity", help="Show a user's milestones, memberships and recorded changes")
+    _user_id_arg(activity)
+    activity.set_defaults(func=handle_user_activity)
+
     deprecation.alias(usub, "get", "show", func=handle_user_show, configure=_user_id_arg)
 
     create = usub.add_parser("create", help="Provision a user")
@@ -349,6 +359,10 @@ def handle_org_elect_owner(client: api_client.ApiClient, args: Any) -> Any:
     return {"elected": args.user_id, "github_login": args.github_login}
 
 
+def handle_org_usage(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/admin/organizations/{args.org_id}/usage")
+
+
 def handle_org_plan_show(client: api_client.ApiClient, args: Any) -> Any:
     return client.get(f"/api/v1/admin/organizations/{args.org_id}/plan")
 
@@ -424,6 +438,10 @@ def handle_user_show(client: api_client.ApiClient, args: Any) -> Any:
     return client.get(f"/api/v1/admin/users/{args.id}")
 
 
+def handle_user_activity(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/admin/users/{args.id}/activity")
+
+
 def handle_user_create(client: api_client.ApiClient, args: Any) -> Any:
     # email/name/org_id/is_admin are always sent; password is only included
     # when supplied so the server keeps its own default (e.g. no local login).

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

@@ -192,7 +192,8 @@ RELATION_NOUNS: dict[str, str] = {
     "registry": "the registered programs, as distinct from the organization's programs",
     "optimized": "the compiled programs optimization runs produced, as distinct from the organization's programs",
     "stats": "a program's execution statistics",
-    "usage": "a program's usage over time",
+    "usage": "a program's usage over time, or an organization's limits in use and recent activity",
+    "activity": "a user's account milestones, memberships and recorded changes",
     "openapi": "the OpenAPI document a deployment serves",
     "history": "a program's distinct prompt instructions over time",
     "evals": "the eval runs recorded against a program",

{cmpnd-0.72.0 → cmpnd-0.74.0}/cmpnd/context.py

@@ -79,6 +79,33 @@ def set_current_optimization_run_id(optimization_run_id: str | None) -> None:
     _current_optimization_run_id.set(optimization_run_id)
 
 
+# The program each optimization run this process started optimizes, by run id. A trace
+# linked to a run that names no program of its own takes its run's, so everything a run
+# emits is reachable through that program: GEPA's reflection and judge calls, a judge
+# module's trace, the rollouts. Keyed by run id rather than held in a context variable
+# because the run id reaches a trace two ways (the callback's field and a context
+# variable, for evaluator threads), and whichever way a trace learns its run, this
+# answers for it. One entry per run, kept for the life of the process: a trace may still
+# be built after its run's record settles, and the map holds two short strings a run.
+_optimization_program_ids: dict[str, str] = {}
+
+
+def set_optimization_program_id(optimization_run_id: str, program_id: str) -> None:
+    """Record the program an optimization run optimizes, once the run has both ids."""
+    _optimization_program_ids[optimization_run_id] = program_id
+
+
+def optimization_program_id(optimization_run_id: str | None) -> str | None:
+    """The program the optimization run ``optimization_run_id`` optimizes, or None.
+
+    None for no run, and for a run that names no program, as one whose generated name
+    serve could not answer for does.
+    """
+    if optimization_run_id is None:
+        return None
+    return _optimization_program_ids.get(optimization_run_id)
+
+
 def create_child_span(
     name: str, span_type: models.SpanType, *, root: bool = False, **kwargs: Any
 ) -> models.SpanBuilder:
@@ -121,3 +148,4 @@ def clear_context() -> None:
     _span_stack.set(())
     _current_eval_run.set(None)
     _current_optimization_run_id.set(None)
+    _optimization_program_ids.clear()

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

@@ -10,7 +10,7 @@ import logging
 from datetime import datetime, timezone
 from typing import Any
 
-from . import context, helpers, identity, models
+from . import context, helpers, identity, models, program_naming
 
 logger = logging.getLogger(__name__)
 
@@ -177,7 +177,9 @@ 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)
+        eval_run.program_id = self._program_id(
+            exp, program, eval_run.program_signature_hash, eval_run.optimization_run_id
+        )
 
         logger.info(
             f"EvalRun created: program_id={eval_run.program_id}, "
@@ -214,20 +216,31 @@ class EvalHandler:
         self._callback._call_id_to_span[call_id] = span
         context.push_span(span)
 
-    def _program_id(self, exp: Any) -> str | None:
+    def _program_id(
+        self, exp: Any, program: Any, program_hash: int | None, 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. The
-        exporter resolves the 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.
+        A program name the call declares wins over the callback's program id. A run
+        that has neither takes the program of the optimization run it belongs to, else
+        the name the SDK generates for the evaluated program, the name its traces carry.
+        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.
         """
         from . import callback
 
         name = callback._declared_program_name()
         if name is None:
-            return self._callback._resolve_program_id()
+            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)
+            )
         # 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.72.0 → cmpnd-0.74.0}/cmpnd/models.py

@@ -967,6 +967,10 @@ class TraceBuilder:
     # 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.
     declared_name: str | None = None
+    # The name the SDK generated for the trace's program, when the trace declares neither
+    # an id nor a name (`program_naming`). The exporter resolves it as it resolves a
+    # declared name, and tells serve that the SDK generated it.
+    generated_name: str | None = None
 
     # Optimization lineage - tracks which optimization produced this program
     compiled_from_run_id: str | None = None
@@ -1275,14 +1279,17 @@ class EvalRunBuilder:
 
     # Eval Identity (defines comparability)
     # The program the run evaluates: the id serve gave the program name the call
-    # declared, or the client's program id. None when the run names no program.
+    # declared, else the client's program id, else the id serve gave the name the SDK
+    # generated for the evaluated module. None when the run has no program.
     program_id: str | None = None
     # The evaluated module's class, such as "ReAct".
     module_class: str | None = None
     metric_name: str | None = None
     dataset_hash: str | None = None
     dataset_size: int = 0
-    program_signature_hash: int = 0  # xxhash64 of signature - program identity
+    # 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

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

@@ -5,7 +5,7 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Any
 
-from .. import _gepa_patch, identity
+from .. import _gepa_patch, callback, identity, program_naming
 from . import gepa_callback, tracker
 
 if TYPE_CHECKING:
@@ -166,6 +166,14 @@ class TrackedGEPA:
         # program's `dspy.Flex` components itself.
         self._tracker.component_types = tracker.code_component_types(student)
 
+        # A run that declares neither a program id nor a program name takes the name the
+        # 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
+            )
+
         # Store both sets for dataset payload building
         self._tracker._trainset = list(trainset)
         self._tracker._valset = list(effective_valset)

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

@@ -11,7 +11,7 @@ from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any
 from uuid import UUID
 
-from .. import configuration, identity, models
+from .. import configuration, context, identity, models, program_naming
 
 if TYPE_CHECKING:
     from .. import exporter_http
@@ -287,6 +287,10 @@ class OptimizationTracker:
         # The program the run optimizes, snapshotted like project_tags. None
         # declares none, and the key is then left off the run upsert.
         self.program_id: str | None = configuration._current_program_id()
+        # The name the SDK generated for the program, for a run that declares neither a
+        # program id nor a program name (`program_naming`). The run resolves it when it
+        # is first sent, on the caller's thread, and carries the id serve gives.
+        self.generated_program_name: str | None = None
         # A client's optimize_program sets this to its own pooled transport, so the
         # run record is published on the client's account (its endpoint + key)
         # rather than the process-global exporter. None means the global exporter.
@@ -842,6 +846,7 @@ class OptimizationTracker:
         if not exp:
             logger.debug("No exporter available, optimization start not exported")
             return
+        self._resolve_generated_program(exp)
 
         # A GEPA job resumed from the same log_dir is one continuous
         # run. If a prior run left a checkpoint + our run_id sidecar, re-adopt
@@ -853,6 +858,7 @@ class OptimizationTracker:
             self.optimization_run_id, prior_start = readopted
             if prior_start is not None:
                 self.start_time = prior_start
+            self._publish_program()
             logger.info(f"Resuming optimization run: run_id={self.optimization_run_id} (log_dir={log_dir})")
             return
 
@@ -861,6 +867,7 @@ class OptimizationTracker:
         assigned = exp.export_optimization_start(self)
         if assigned:
             self.optimization_run_id = assigned
+        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)
@@ -1089,6 +1096,28 @@ class OptimizationTracker:
             return
         self._export_update()
 
+    def _resolve_generated_program(self, exp: Any) -> None:
+        """Give a run that names no program the id of its generated name, before it is sent.
+
+        Resolved now, on the caller's thread, because the run's first record goes out
+        synchronously and must carry its program id. The exporter keeps the answer for
+        the process, so the run's rollouts, whose traces carry the same name, cost no
+        second request. A name serve refuses or cannot answer leaves the run without an
+        id.
+        """
+        if self.program_id is None and self.generated_program_name is not None:
+            self.program_id = program_naming.resolve_generated_name(exp, self.generated_program_name)
+
+    def _publish_program(self) -> None:
+        """Let the traces this run emits find its program by its run id.
+
+        A trace with no program of its own, such as a reflection or judge call, or a
+        judge module's trace, takes the run's program (`context.optimization_program_id`).
+        The id is the one this run resolved, so publishing it costs no request.
+        """
+        if self.optimization_run_id and self.program_id is not None:
+            context.set_optimization_program_id(self.optimization_run_id, self.program_id)
+
     def _export_update(self) -> None:
         """Update existing optimization run record."""
         exp = self._active_exporter()
@@ -1113,6 +1142,7 @@ class OptimizationTracker:
         if not exp:
             logger.warning("No exporter available, optimization run not exported")
             return
+        self._resolve_generated_program(exp)
         # Guarded exactly as start() guards it: the exporters that never reach
         # serve return None here, so an unconditional assignment would write None
         # over a real id the moment one of them meets a run that already has one.

cmpnd-0.74.0/cmpnd/program_naming.py

@@ -0,0 +1,86 @@
+"""The names the SDK gives programs their users never named.
+
+A trace, an eval run or an optimization run takes its program from the id its config
+declares, else the name its call declares, else a name this module generates for its
+root module. The SDK resolves a generated name to a program id through the same route
+as a declared one, ``PUT /api/v1/programs/by-name/{name}``, and says that it generated
+the name, so the program does not count toward the plan's program limit.
+
+Serve gives a generated name no meaning. It stores and resolves it like any other
+program name, and never parses it. So the derivation belongs to the SDK alone, and
+``generated_program_name`` is the only function that knows it. A later SDK may derive
+names some other way, such as from where the program was constructed, without any
+change to serve. Programs then fork once, because the new name names no program yet.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import Any
+
+from . import identity
+
+# A program name is at most 64 characters. The suffix takes 13 of them, "-" and twelve
+# hex digits, and the class takes the rest.
+_MAX_NAME_LENGTH = 64
+_SUFFIX_DIGITS = 12
+_MAX_CLASS_LENGTH = _MAX_NAME_LENGTH - 1 - _SUFFIX_DIGITS
+# A class whose name leaves nothing a program name may hold.
+_FALLBACK_CLASS = "Module"
+
+_NOT_IN_A_NAME = re.compile(r"[^A-Za-z0-9._-]+")
+_NAME_PUNCTUATION = "._-"
+_RESERVED_PREFIX = "p_"
+
+
+def generated_program_name(module: Any, signature_hash: int | None = None) -> 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
+    ``ChainOfThought-17e1f4089a24``. Programs of one shape get one name in every process,
+    so their traces land in one program, and programs of different shapes get different
+    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.
+    """
+    if signature_hash is None:
+        signature_hash = identity.compute_program_hash(module)
+    signature_hash = signature_hash or 0
+    suffix = f"{signature_hash & 0xFFFF_FFFF_FFFF_FFFF:016x}"[:_SUFFIX_DIGITS]
+    return f"{_class_part(module.__class__.__name__)}-{suffix}"
+
+
+def _class_part(class_name: str) -> str:
+    """``class_name`` as the start of a program name: ASCII, no reserved prefix, short enough."""
+    ascii_name = unicodedata.normalize("NFKD", class_name).encode("ascii", "ignore").decode("ascii")
+    part = _NOT_IN_A_NAME.sub("_", ascii_name)
+    # A name starts with a letter or digit and never with "p_", in any case.
+    while True:
+        part = part.lstrip(_NAME_PUNCTUATION)
+        if not part.lower().startswith(_RESERVED_PREFIX):
+            break
+        part = part[len(_RESERVED_PREFIX) :]
+    part = part[:_MAX_CLASS_LENGTH].rstrip(_NAME_PUNCTUATION)
+    return part or _FALLBACK_CLASS
+
+
+def resolve_generated_name(exporter: Any, name: str) -> str | None:
+    """The program id for a generated name, resolved now on the caller's thread.
+
+    For a run record that is sent synchronously and must carry its program id then, as
+    an eval run's start and an optimization run's start are. The exporter keeps the
+    answer for the process, so a name its traces already resolved costs no request.
+    Returns None when the exporter resolves no names, as a worker's in-memory collector
+    does, or when serve refused the name or could not be reached.
+    """
+    # Read with getattr because the member is optional: an exporter that resolves no
+    # names has none.
+    resolve = getattr(exporter, "resolve_program_name", None)
+    if not callable(resolve):
+        return None
+    program_id = resolve(name, generated=True)
+    return program_id if isinstance(program_id, str) else None

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

@@ -890,6 +890,23 @@ and a value of `none` lifts the plan's limit for that org.
 `cmpnd admin org overrides delete ORG_ID NAME` deletes the override, so the org
 follows its plan again.
 
+`cmpnd admin org usage ORG_ID` shows what each limit bounds now, in `in_use`,
+and the org's activity in the last 24 hours, 7 days and 30 days, in `windows`.
+Each window counts traces, model calls and tokens, deployment runs by status,
+and hosted optimizations started and cancelled with their compute. `since` is
+the start of the window's first hour. `traces` or `model_usage` is `null` when
+the server has no published count for the window yet.
+
+`cmpnd admin user activity USER_ID` shows a user's milestones, every org they
+belong to, and the newest 50 authority changes recorded about them, such as
+approvals, ownership grants, invites and leaves. A milestone that has not
+happened is `null`. `first_approved_at` is the first approval still on record: an admin-created
+user, an invite redemption and an approved founder write no approval event, so
+their date survives only while a membership keeps it. `oldest_key_at` and
+`last_key_used_at` cover only the keys
+the user still holds, because leaving an org deletes the user's keys there.
+Sign-ins are not recorded, and deployment keys do not count as the user's keys.
+
 `cmpnd admin plans list` shows every plan's limits and feature flags.
 `cmpnd admin plans limits update PLAN NAME VALUE` and `limits delete PLAN NAME`
 change a plan's default for every org on it. `cmpnd admin plans flags update

{cmpnd-0.72.0 → cmpnd-0.74.0}/docs/client.md

@@ -122,9 +122,12 @@ qa = CapitalQA(lm=dspy.LM("openai/gpt-5-mini"))
 ## Sketch mode
 
 `auto_instrument()` is sketch mode. It traces every DSPy call and declares no
-program names. Its traces belong to no program, so the platform files them under
-Unattributed, and the first one in a process logs a warning that points to
-`@cmpnd.program(name)` and `cmpnd.Client`. A named program refuses sketch mode: calling a `cmpnd.Program`
+program names. Each trace goes to a program under a name the SDK generates from
+its root module's class and signature, such as `ChainOfThought-17e1f4089a24`, so
+each program shape lands in a program of its own. Such a program does not count
+toward the plan's program limit. The first such trace in a process logs a warning
+that names the generated name and points to `@cmpnd.program(name)`,
+`cmpnd.Program(name, module=..., lm=...)` and `cmpnd.Client`. A named program refuses sketch mode: calling a `cmpnd.Program`
 directly while `auto_instrument()` is on raises a `TypeError` that points to
 `cmpnd.Client`. The refusal applies at any depth, so a program nested inside a
 plain module called under `auto_instrument()` raises it too. A program run