cmpnd 0.77.0__tar.gz → 0.79.0__tar.gz

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

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

{cmpnd-0.77.0 → cmpnd-0.79.0}/cmpnd/_gepa_patch.py

@@ -9,6 +9,10 @@ module-style (``from . import identity``); basedpyright can't resolve
 """
 
 import contextvars
+import functools
+from collections.abc import Callable
+
+from . import context
 
 _gepa_patched = False
 
@@ -39,6 +43,43 @@ def _gepa_supports_callbacks() -> bool:
         return False
 
 
+# Marks a metric wrapper _judge_metric_calls installed, so a compile nested in another
+# (TrackedGEPA under auto_instrument) leaves the outer wrapper in place. An attribute
+# on our own wrapper, read with getattr, because the user's metric may be any
+# callable: a dataclass instance is unhashable, so no set or dict can hold it.
+_JUDGED_METRIC_MARK = "_cmpnd_judges_metric_calls"
+
+
+def _judge_metric_calls(gepa) -> Callable[[], None]:
+    """Run each of ``gepa``'s metric calls as the metric phase; return the undo.
+
+    dspy.GEPA reads its metric from ``metric_fn`` once its compile starts, so
+    swapping in a wrapper for the compile's span reaches every metric call, those
+    DSPy Evaluate makes and those GEPA's feedback makes. A trace a grading module
+    roots inside a call is then tagged ``optimization_phase: metric``, as a hosted
+    run's judge traces are, while the rollout the metric grades ran before it and
+    carries no phase. The wrapper keeps the metric's signature (``functools.wraps``)
+    for DSPy's checks of it, and the undo restores the optimizer's own metric.
+    """
+    metric = getattr(gepa, "metric_fn", None)
+    if not callable(metric) or getattr(metric, _JUDGED_METRIC_MARK, False) is True:
+        return lambda: None
+
+    @functools.wraps(metric)
+    def judged_metric(*args, **kwargs):
+        with context.optimization_phase("metric"):
+            return metric(*args, **kwargs)
+
+    setattr(judged_metric, _JUDGED_METRIC_MARK, True)
+    gepa.metric_fn = judged_metric
+
+    def restore() -> None:
+        if getattr(gepa, "metric_fn", None) is judged_metric:
+            gepa.metric_fn = metric
+
+    return restore
+
+
 def _run_tracked_compile(
     gepa,
     student,
@@ -137,8 +178,10 @@ def _run_tracked_compile(
         trk.generated_program_name = program_naming.generated_program_name(student)
 
     restore_attribution = callback.start_trace_attribution()
+    restore_metric = None
 
     try:
+        restore_metric = _judge_metric_calls(gepa)
         result = run_original()
 
         if not has_callbacks:
@@ -164,6 +207,8 @@ def _run_tracked_compile(
         raise
 
     finally:
+        if restore_metric is not None:
+            restore_metric()
         restore_attribution()
 
 

{cmpnd-0.77.0 → cmpnd-0.79.0}/cmpnd/callback.py

@@ -517,6 +517,11 @@ def _finish_reason(response: Any) -> str | None:
     return "stop"
 
 
+# The `optimization.role` an LM call in each GEPA phase is priced under. A metric scores a
+# rollout, so its calls are rollout spend; reflection proposes the next candidate.
+_OPTIMIZATION_PHASE_ROLES = {"metric": "rollout", "reflection": "reflection"}
+
+
 class _CallbackBase:
     """Shared state and span-tracking primitives for the CmpndCallback mixins."""
 
@@ -532,6 +537,7 @@ class _CallbackBase:
         max_output_field_size: int | None = None,
         stream_trace_starts: bool | None = None,
         own_config: configuration.Config | None = None,
+        optimization_phase: str | 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()
@@ -541,6 +547,19 @@ class _CallbackBase:
         # later cmpnd.configure(). That fixedness is what keeps a client
         # orthogonal to the global config.
         self._own_config = own_config
+        # 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
+        # run optimizes and not the run's id, which the ingest key it pushes with decides.
+        # With a phase set, an LM call outside any trace becomes a standalone GEPA trace as
+        # a local optimization's judge and reflection calls do, and a trace a module opens
+        # is tagged with the phase. None is every other caller.
+        if optimization_phase not in (None, *_OPTIMIZATION_PHASE_ROLES):
+            raise ValueError(
+                f"optimization_phase must be one of {sorted(_OPTIMIZATION_PHASE_ROLES)} or None, "
+                f"got {optimization_phase!r}"
+            )
+        self._optimization_phase = optimization_phase
         # Set once this callback has warned that a declared name replaced the program
         # id its config read from the environment, so the warning appears once per client.
         self._warned_name_over_id = False
@@ -1348,6 +1367,12 @@ class _ModuleMixin(_CallbackBase):
         # Apply default tags
         if config and config.default_tags:
             trace.tags.update(config.default_tags)
+        # 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
 
@@ -1401,7 +1426,9 @@ class _LMMixin(_CallbackBase):
         span.model_name = getattr(instance, "model", None)
         span.model_provider = helpers.infer_provider(instance)
 
-        if self._active_optimization_run_id is not None or context.get_current_optimization_run_id() is not None:
+        if self._optimization_phase is not None:
+            span.attributes["optimization.role"] = _OPTIMIZATION_PHASE_ROLES[self._optimization_phase]
+        elif self._active_optimization_run_id is not None or context.get_current_optimization_run_id() is not None:
             span.attributes["optimization.role"] = "rollout"
 
         # The usage fields read one named value each out of the raw kwargs. The
@@ -1603,7 +1630,9 @@ class _LMMixin(_CallbackBase):
         # must NOT also be added to _orphaned_lm_usage / untraced_lm_usage — that
         # 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:
+        if current_trace is None and (
+            self._active_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
 
@@ -1644,14 +1673,18 @@ class _LMMixin(_CallbackBase):
         carries the distinction. Each becomes a standalone one-span
         trace so the prompt, response, tokens and cost are visible alongside the
         student traces instead of being reduced to an aggregate token count.
+
+        A callback built with an ``optimization_phase`` takes its phase from that
+        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
-        if not run_id:
+        if not run_id and self._optimization_phase is None:
             return
 
-        phase = "metric" if self._active_eval_run is not None else "reflection"
+        phase = self._optimization_phase or ("metric" if self._active_eval_run is not None else "reflection")
         span.attributes["gepa.phase"] = phase
-        span.attributes["optimization.role"] = "reflection" if phase == "reflection" else "rollout"
+        span.attributes["optimization.role"] = _OPTIMIZATION_PHASE_ROLES[phase]
 
         trace = models.TraceBuilder(
             trace_id=span.trace_id or uuid4(),

{cmpnd-0.77.0 → cmpnd-0.79.0}/cmpnd/cli/commands/admin.py

@@ -182,8 +182,14 @@ def _register_user(sub: _SubParsersAction[ArgumentParser]) -> None:
     create.add_argument("--admin", dest="admin", action="store_true", help="Grant platform-admin")
     create.set_defaults(func=handle_user_create)
 
-    approve = usub.add_parser("approve", help="Approve a pending signup")
+    approve = usub.add_parser("approve", help="Approve a pending membership")
     approve.add_argument("id", help="User id")
+    approve.add_argument(
+        "--org-id",
+        dest="org_id",
+        default="",
+        help="Org whose membership to approve (default: the user's active org)",
+    )
     approve.set_defaults(func=handle_user_approve)
 
     promote = usub.add_parser("promote", help="Grant platform-admin")
@@ -457,7 +463,30 @@ def handle_user_create(client: api_client.ApiClient, args: Any) -> Any:
 
 
 def handle_user_approve(client: api_client.ApiClient, args: Any) -> Any:
-    return client.patch(f"/api/v1/admin/users/{args.id}", json={"is_approved": True})
+    user_path = f"/api/v1/admin/users/{args.id}"
+    org_id = args.org_id or client.get(user_path)["org_id"]
+    try:
+        return client.post(f"{user_path}/approve", json={"org_id": org_id})
+    except api_client.CliError as err:
+        if not _route_unmounted(err):
+            raise
+        # A server older than the approve route approves only the active org,
+        # through PATCH.
+        if args.org_id:
+            raise api_client.CliError(
+                "This server cannot approve a membership in a named org. Upgrade it, or omit --org-id "
+                "to approve the membership in the user's active org."
+            ) from err
+        return client.patch(user_path, json={"is_approved": True})
+
+
+def _route_unmounted(err: api_client.CliError) -> bool:
+    """Whether a 404 came from a server that has no such route.
+
+    Go's ServeMux answers an unmounted route with plain text. A mounted route's
+    own 404 is JSON, such as an approval for a membership that does not exist.
+    """
+    return err.status_code == 404 and "404 page not found" in str(err)
 
 
 def handle_user_promote(client: api_client.ApiClient, args: Any) -> Any:

{cmpnd-0.77.0 → cmpnd-0.79.0}/cmpnd/context.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from collections.abc import Generator
+from contextlib import contextmanager
 from contextvars import ContextVar
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any
@@ -27,6 +29,12 @@ _current_eval_run: ContextVar[models.EvalRunBuilder | None] = ContextVar("cmpnd_
 # evals). Prefixed text id (`op_…`), minted via cmpnd.identity.
 _current_optimization_run_id: ContextVar[str | None] = ContextVar("cmpnd_current_optimization_run_id", default=None)
 
+# The optimization phase the code running now serves, when that code is an
+# optimizer's metric rather than the program it optimizes. A local GEPA run sets it
+# around each metric call, so a trace the metric's grading module roots is tagged as
+# the metric's, as a hosted run's kernel tags it through its callback's own phase.
+_current_optimization_phase: ContextVar[str | None] = ContextVar("cmpnd_current_optimization_phase", default=None)
+
 
 def get_current_trace() -> models.TraceBuilder | None:
     """Get the current trace."""
@@ -79,6 +87,21 @@ def set_current_optimization_run_id(optimization_run_id: str | None) -> None:
     _current_optimization_run_id.set(optimization_run_id)
 
 
+def get_current_optimization_phase() -> str | None:
+    """The optimization phase the running code serves, or None outside a metric call."""
+    return _current_optimization_phase.get()
+
+
+@contextmanager
+def optimization_phase(phase: str) -> Generator[None]:
+    """Run the block as the optimization phase ``phase``, restoring the outer phase after."""
+    token = _current_optimization_phase.set(phase)
+    try:
+        yield
+    finally:
+        _current_optimization_phase.reset(token)
+
+
 # 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
@@ -148,4 +171,5 @@ def clear_context() -> None:
     _span_stack.set(())
     _current_eval_run.set(None)
     _current_optimization_run_id.set(None)
+    _current_optimization_phase.set(None)
     _optimization_program_ids.clear()

{cmpnd-0.77.0 → cmpnd-0.79.0}/cmpnd/optimizers/gepa.py

@@ -205,9 +205,11 @@ class TrackedGEPA:
         existing_callbacks = self._gepa.gepa_kwargs.get("callbacks") or []
         self._gepa.gepa_kwargs["callbacks"] = existing_callbacks + [gcb]
         restore_attribution = None
+        restore_metric = None
 
         try:
             restore_attribution = gcb.start_trace_attribution()
+            restore_metric = _gepa_patch._judge_metric_calls(self._gepa)
             # Run optimization (trainset/valset are keyword-only in GEPA)
             compile_token = _gepa_patch._tracked_compile_optimizer.set(self._gepa)
             try:
@@ -246,6 +248,8 @@ class TrackedGEPA:
             raise
 
         finally:
+            if restore_metric is not None:
+                restore_metric()
             if restore_attribution is not None:
                 restore_attribution()
             # Remove our callback from gepa_kwargs

{cmpnd-0.77.0 → cmpnd-0.79.0}/docs/cli.md

@@ -494,6 +494,8 @@ stores one key per org per endpoint in `~/.config/cmpnd/credentials.json`, or
 `$CMPND_CONFIG_DIR/credentials.json` when that variable is set. The file has
 mode 0600. An active pointer names the org whose key commands use.
 `cmpnd login` stores a new key beside the others and makes its org active.
+When you belong to more than one org, the approval page asks which org the
+key is for and starts on your active org in the web app.
 
 - `cmpnd login --org <slug-or-id>` mints a key for that org instead of the
   active one. The approval page names the org, and serve refuses an org where
@@ -891,6 +893,14 @@ EMAIL` withdraws the open owner invites sent to that address, and the links
 stop working. `cmpnd admin org show` lists pending addresses under
 `seed.pending_owner_emails`.
 
+`cmpnd admin user approve USER_ID --org-id ORG_ID` approves the user's pending
+membership in that org, which need not be their active org. Without
+`--org-id` it approves the membership in their active org, and a server
+older than the approve route approves it the way older releases did. Serve applies the
+operator queue's rules. A member waiting to join an org that has its own owner
+belongs to that owner's queue, so serve refuses it with 400. `cmpnd admin user
+reject USER_ID --org-id ORG_ID` declines a pending membership.
+
 ### Plans, limits and signups
 
 Every org has a plan, `free`, `pro` or `enterprise`, and each plan sets

{cmpnd-0.77.0 → cmpnd-0.79.0}/docs/sdk-instrumentation.md

@@ -180,6 +180,7 @@ Everything lives in `python-sdk/cmpnd/context.py`:
 - `_span_stack` — an immutable tuple of `SpanBuilder`s. `push_span` and `pop_span` set a new tuple rather than mutating the old one, because a context copy shares the objects its parent context holds: a mutable stack would be one list shared by every sibling copy, so concurrent runs (GEPA's `DspyAdapter.batch_evaluate`, which runs each candidate in a `copy_context()`, or `asyncio.gather` over `acall`) would read each other's spans as their parent. `get_current_span` returns the innermost. `tests/test_trace_context_concurrency.py` pins this.
 - `_current_eval_run` (`context.py:24`) — set while an `EvalHandler` is active.
 - `_current_optimization_run_id` (`context.py:29`) — set while a patched `GEPA.compile` is running, so evals triggered inside it can be linked back.
+- `_current_optimization_phase` — set to `"metric"` for the span of each metric call a tracked GEPA compile makes, so a trace the metric's grading module roots is tagged as the metric's. `context.optimization_phase(phase)` sets it for a block.
 
 `create_child_span` at `context.py:83` is the standard constructor: it reads the current trace + span, assigns `trace_id` and `parent_span_id`, and returns an unpushed `SpanBuilder`. The callback uses it for every child span; so does the `start_span` context manager below. Pass `root=True` to have it ignore the stack and leave `parent_span_id` unset, for a span that starts a trace beneath one that does not parent it.
 
@@ -202,7 +203,41 @@ callback never fires. This prevents an ordinary evaluation after a failure from
 being queued under the failed run or being claimed as the next optimization's
 seed evidence.
 
-For tests that need a clean slate, `clear_context()` at `context.py:122` resets all four vars — see the `cmpnd-testing` skill and [`../AGENTS.md`](../AGENTS.md) § "Running Tests & Checks".
+### A callback that traces one phase of a run it does not own
+
+`CmpndCallback(optimization_phase=...)` takes `"metric"` or `"reflection"`. A worker
+kernel builds one around a hosted run's metric and around its custom GEPA proposer.
+That process knows the program the run optimizes, from its config, and not the run's
+id, which serve stamps from the ingest key the traces are pushed with. Such a callback
+makes those calls look like a local optimization's:
+
+- An LM call outside any trace becomes the standalone one-span `GEPA` trace that
+  `_emit_optimization_lm_trace` writes for a local run. Its span carries `gepa.phase`
+  and `optimization.role`, and its trace carries the `optimization_phase` tag. The
+  callback takes the phase from its constructor, not from an active eval run, and
+  leaves `optimization_run_id` unset.
+- A trace that a dspy module opens is tagged `optimization_phase`, so a program's trace
+  list tells a judge module from a rollout of the same class.
+- Every LM span gets `optimization.role`: `rollout` for a metric, `reflection` for a
+  proposer.
+
+A local run owns its run, so its callback declares no phase. It tags its judge traces
+through context instead. While a tracked GEPA compile runs, through `auto_instrument`,
+`TrackedGEPA` or a client's `optimize_program`, `_gepa_patch._judge_metric_calls`
+swaps the optimizer's `metric_fn` for a wrapper that runs each call under
+`context.optimization_phase("metric")`, and restores the metric when the compile ends.
+`_create_trace` reads that phase when its callback has none. So a judge module the
+metric grades through roots a trace tagged `optimization_phase: metric`, as a hosted
+judge's module trace is. The rollout the metric grades ran before the call and carries
+no tag. The context phase changes only that tag: a direct judge or reflection call is
+still the trace `_emit_optimization_lm_trace` builds, and module spans get no
+`optimization.role`.
+
+`tests/test_optimization_phase_callback.py` drives both paths, and the context phase,
+through real DSPy dispatch. `tests/test_run_attribution_paths.py` runs a real GEPA
+search whose metric grades through a module.
+
+For tests that need a clean slate, `clear_context()` in `context.py` resets these vars — see the `cmpnd-testing` skill and [`../AGENTS.md`](../AGENTS.md) § "Running Tests & Checks".
 
 ### Across a real fork
 

{cmpnd-0.77.0 → cmpnd-0.79.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.77.0"
+version = "0.79.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

{cmpnd-0.77.0 → cmpnd-0.79.0}/tests/test_cli/test_admin.py

@@ -2,8 +2,15 @@
 
 from __future__ import annotations
 
+import json
 from argparse import Namespace
+from collections.abc import Callable
+from unittest import mock
 
+import httpx
+import pytest
+
+from cmpnd.cli import api_client
 from cmpnd.cli.commands import admin
 
 
@@ -183,11 +190,15 @@ class TestAdminUser:
             },
         )
 
-    def test_approve_patches_is_approved(self, mock_client):
-        mock_client.patch.return_value = {"id": "u_1", "is_approved": True}
-        result = admin.handle_user_approve(mock_client, Namespace(id="u_1"))
-        mock_client.patch.assert_called_once_with("/api/v1/admin/users/u_1", json={"is_approved": True})
-        assert result["is_approved"] is True
+    def test_approve_parser_takes_an_optional_org(self):
+        from argparse import ArgumentParser
+
+        parser = ArgumentParser()
+        admin.register(parser.add_subparsers())
+        args = parser.parse_args(["admin", "user", "approve", "u_1", "--org-id", "o_2"])
+        assert args.org_id == "o_2"
+        assert args.func is admin.handle_user_approve
+        assert parser.parse_args(["admin", "user", "approve", "u_1"]).org_id == ""
 
     def test_promote_patches_is_admin_true(self, mock_client):
         mock_client.patch.return_value = {"id": "u_1", "is_admin": True}
@@ -413,3 +424,78 @@ class TestAdminSignup:
         with pytest.raises(SystemExit):
             args.func(mock_client, args)
         mock_client.patch.assert_not_called()
+
+
+def _serve(answer: Callable[[httpx.Request], httpx.Response]):
+    """A real ApiClient over a captured transport: `sent` collects each request."""
+    sent: list[httpx.Request] = []
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        sent.append(request)
+        return answer(request)
+
+    real = httpx.Client
+    patch = mock.patch("httpx.Client", lambda **kwargs: real(**kwargs, transport=httpx.MockTransport(handle)))
+    return api_client.ApiClient("k", "http://serve.test"), sent, patch
+
+
+def _wire(sent: list[httpx.Request]) -> list[tuple[str, str, object]]:
+    return [(r.method, r.url.path, json.loads(r.content) if r.content else None) for r in sent]
+
+
+# Go's ServeMux answers an unmounted route with this plain-text 404.
+_UNMOUNTED = httpx.Response(404, text="404 page not found\n")
+
+
+class TestAdminUserApproveWire:
+    def test_approve_posts_the_named_org(self):
+        client, sent, patch = _serve(lambda _r: httpx.Response(200, json={"newly_approved": True}))
+        with patch:
+            result = admin.handle_user_approve(client, _parse("user", "approve", "u_1", "--org-id", "o_2"))
+        assert _wire(sent) == [("POST", "/api/v1/admin/users/u_1/approve", {"org_id": "o_2"})]
+        assert result["newly_approved"] is True
+
+    def test_approve_without_org_approves_the_active_org(self):
+        def answer(request: httpx.Request) -> httpx.Response:
+            if request.method == "GET":
+                return httpx.Response(200, json={"id": "u_1", "org_id": "o_1"})
+            return httpx.Response(200, json={"newly_approved": True})
+
+        client, sent, patch = _serve(answer)
+        with patch:
+            admin.handle_user_approve(client, _parse("user", "approve", "u_1"))
+        assert _wire(sent) == [
+            ("GET", "/api/v1/admin/users/u_1", None),
+            ("POST", "/api/v1/admin/users/u_1/approve", {"org_id": "o_1"}),
+        ]
+
+    def test_approve_without_org_falls_back_to_patch_on_a_server_without_the_route(self):
+        def answer(request: httpx.Request) -> httpx.Response:
+            if request.method == "GET":
+                return httpx.Response(200, json={"id": "u_1", "org_id": "o_1"})
+            if request.method == "POST":
+                return _UNMOUNTED
+            return httpx.Response(200, json={"id": "u_1", "is_approved": True})
+
+        client, sent, patch = _serve(answer)
+        with patch:
+            result = admin.handle_user_approve(client, _parse("user", "approve", "u_1"))
+        assert _wire(sent)[-1] == ("PATCH", "/api/v1/admin/users/u_1", {"is_approved": True})
+        assert result["is_approved"] is True
+
+    def test_approve_with_org_on_a_server_without_the_route_says_so(self):
+        client, sent, patch = _serve(lambda _r: _UNMOUNTED)
+        with patch, pytest.raises(api_client.CliError, match="--org-id"):
+            admin.handle_user_approve(client, _parse("user", "approve", "u_1", "--org-id", "o_2"))
+        assert [r.method for r in sent] == ["POST"]
+
+    def test_a_missing_membership_is_not_mistaken_for_an_old_server(self):
+        def answer(request: httpx.Request) -> httpx.Response:
+            if request.method == "GET":
+                return httpx.Response(200, json={"id": "u_1", "org_id": "o_1"})
+            return httpx.Response(404, json={"error": "no membership for that user in that org"})
+
+        client, sent, patch = _serve(answer)
+        with patch, pytest.raises(api_client.CliError, match="no membership"):
+            admin.handle_user_approve(client, _parse("user", "approve", "u_1"))
+        assert [r.method for r in sent] == ["GET", "POST"]