cmpnd 0.4.0__tar.gz → 0.4.1__tar.gz

{cmpnd-0.4.0 → cmpnd-0.4.1}/PKG-INFO

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

{cmpnd-0.4.0 → cmpnd-0.4.1}/cmpnd/callback.py

@@ -747,18 +747,20 @@ class _LMMixin(_CallbackBase):
 
         context.pop_span()
 
-        # If this LM call has no trace context but we're in an optimization,
-        # accumulate token usage for the optimization cost computation.
-        # This captures GEPA reflection LM calls which run outside traced program flow.
+        # An LM call with no active trace context, made while an optimization is
+        # running, is GEPA optimizer machinery — an LM call outside any program
+        # rollout. Two phases produce these: reflection (the instructor proposing
+        # new instructions, between evaluations) and metric (an LLM-as-judge /
+        # semantic metric scoring outputs, during evaluation). Rather than drop
+        # them, wrap each in its own trace linked to the optimization run so it
+        # shows up alongside the student traces (CMP-485). serve's
+        # TracedTokensForRun then accounts for their cost from the span, so these
+        # 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:
-            model_name = span.model_name or "unknown"
-            if model_name not in self._orphaned_lm_usage:
-                self._orphaned_lm_usage[model_name] = {"prompt_tokens": 0, "completion_tokens": 0}
-            self._orphaned_lm_usage[model_name]["prompt_tokens"] += span.prompt_tokens or 0
-            self._orphaned_lm_usage[model_name]["completion_tokens"] += span.completion_tokens or 0
-            logger.debug(f"Orphaned LM usage ({model_name}): +{span.prompt_tokens}p/{span.completion_tokens}c tokens")
-            return  # Don't export orphaned spans (no trace to attach to)
+            self._emit_optimization_lm_trace(span)
+            return  # handled as a standalone GEPA-process trace
 
         # Track span by trace_id for metric aggregation (LM spans have token info!)
         if span.trace_id:
@@ -772,6 +774,64 @@ class _LMMixin(_CallbackBase):
             if exp:
                 exp.export_span(span)
 
+    def _emit_optimization_lm_trace(self, span: models.SpanBuilder) -> None:
+        """Wrap an LM call the GEPA optimizer made outside a program rollout in
+        its own trace, linked to the active optimization run.
+
+        Two phases produce such calls, on different models:
+          - "reflection": GEPA's instruction proposer (the reflection LM), run in
+            the optimize loop between evaluations.
+          - "metric": an LLM-as-judge / semantic metric (the student LM or a
+            separate judge LM), run during candidate evaluation after the program
+            trace has already closed.
+
+        We distinguish them by `_active_eval_run` — set only while DSPy Evaluate
+        is running — instead of assuming every untraced call is reflection (that
+        would mislabel judge calls). The trace is named with the umbrella "GEPA";
+        the specific model stays on the span's model_name, and `gepa.phase`
+        carries the distinction (CMP-485). 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.
+        """
+        run_id = self._active_optimization_run_id
+        if not run_id:
+            return
+
+        phase = "metric" if self._active_eval_run is not None else "reflection"
+        span.attributes["gepa.phase"] = phase
+
+        trace = models.TraceBuilder(
+            trace_id=span.trace_id or uuid4(),
+            start_time=span.start_time,
+            end_time=span.end_time,
+            program_name="GEPA",
+        )
+        # 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
+        # trace's root, so force it parentless and pin it to this trace so tree/root
+        # reconstruction works (CMP-485, Greptile P1).
+        span.parent_span_id = None
+        span.trace_id = trace.trace_id
+        trace.signature_name = span.model_name or phase
+        trace.status = span.status
+        trace.optimization_run_id = run_id
+        trace.tags["optimization_phase"] = phase
+
+        # Single-span trace: roll the span's usage up onto the trace so the
+        # traces list shows tokens/cost without a separate aggregation pass.
+        trace.prompt_tokens = span.prompt_tokens or 0
+        trace.completion_tokens = span.completion_tokens or 0
+        trace.total_tokens = span.total_tokens or 0
+        trace.total_cost = span.cost or 0.0
+        trace.span_count = 1
+
+        exp = exporter.get_exporter()
+        if exp:
+            exp.export_trace_stats(trace)  # stats tier (never dropped)
+            trace._batch_spans = [span]
+            exp.export_trace(trace)
+
 
 class _AdapterMixin(_CallbackBase):
     """DSPy adapter callbacks (format/parse start/end)."""

{cmpnd-0.4.0 → cmpnd-0.4.1}/cmpnd/cli/api_client.py

@@ -49,6 +49,12 @@ class ApiClient:
     def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
         return self._request("POST", path, json=json)
 
+    def patch(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        return self._request("PATCH", path, json=json)
+
+    def put(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        return self._request("PUT", path, json=json)
+
     def delete(self, path: str) -> Any:
         return self._request("DELETE", path)
 
@@ -77,6 +83,10 @@ class ApiClient:
                     response = client.get(url, params=params)
                 elif method == "DELETE":
                     response = client.delete(url)
+                elif method == "PATCH":
+                    response = client.patch(url, json=json)
+                elif method == "PUT":
+                    response = client.put(url, json=json)
                 else:
                     response = client.post(url, json=json)
         except httpx.ConnectError:

cmpnd-0.4.1/cmpnd/cli/commands/admin.py

@@ -0,0 +1,274 @@
+"""Platform-operator commands, hidden behind CMPND_CLI_ADMIN=1.
+
+`cmpnd admin org create|set-owner|list|get|set-limit|set-github-login|elect-owner`
+is the closed-beta org bootstrap and steward surface (CMP-126/CMP-278/CMP-472):
+stand up a shared org with its GitHub auto-join key, anoint its first owner,
+adjust its member cap or GitHub link, and grant ownership from the election
+queue. `cmpnd admin user …` is the operator's user-lifecycle surface (list,
+inspect, create, approve/reject the pending-signup queue, promote/demote admin,
+disable/enable, reset a password, and manage a user's API-key scopes). `cmpnd
+admin feature-flags …` reads and toggles the server's runtime flags. These hit
+/api/v1/admin/* and require an API key carrying the admin:* scopes — the server
+is the real authority. The CMPND_CLI_ADMIN env gate (mirroring CMPND_CLI_DEV)
+only keeps these out of customers' --help; it grants nothing.
+"""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser, _SubParsersAction
+from typing import Any
+
+from .. import api_client
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser("admin", help="Platform-operator commands (CMPND_CLI_ADMIN)")
+    sub = parser.add_subparsers(dest="action")
+
+    _register_org(sub)
+    _register_user(sub)
+    _register_feature_flags(sub)
+
+
+def _register_org(sub: _SubParsersAction[ArgumentParser]) -> None:
+    org = sub.add_parser("org", help="Organization bootstrap")
+    osub = org.add_subparsers(dest="org_action")
+
+    create = osub.add_parser("create", help="Create an organization")
+    create.add_argument("name", help="Organization name")
+    create.add_argument(
+        "--github-login",
+        dest="github_login",
+        default="",
+        help="GitHub org login for OAuth auto-join (optional)",
+    )
+    create.set_defaults(func=handle_org_create)
+
+    set_owner = osub.add_parser("set-owner", help="Make an existing user the org's owner")
+    set_owner.add_argument("org_id", help="Organization id")
+    set_owner.add_argument("email", help="Owner email (must already be a provisioned user)")
+    set_owner.set_defaults(func=handle_org_set_owner)
+
+    ls = osub.add_parser("list", help="List organizations")
+    ls.set_defaults(func=handle_org_list)
+
+    get = osub.add_parser("get", help="Show one organization")
+    get.add_argument("org_id", help="Organization id")
+    get.set_defaults(func=handle_org_get)
+
+    set_limit = osub.add_parser("set-limit", help="Set an org's member cap")
+    set_limit.add_argument("org_id", help="Organization id")
+    set_limit.add_argument("max", type=int, help="Maximum members")
+    set_limit.set_defaults(func=handle_org_set_limit)
+
+    set_github_login = osub.add_parser("set-github-login", help="Set (or clear) an org's GitHub login")
+    set_github_login.add_argument("org_id", help="Organization id")
+    set_github_login.add_argument("login", help='GitHub org login (pass "" to unlink)')
+    set_github_login.set_defaults(func=handle_org_set_github_login)
+
+    elect_owner = osub.add_parser("elect-owner", help="Grant ownership from the election queue")
+    elect_owner.add_argument("github_login", help="The org's GitHub login")
+    elect_owner.add_argument("user_id", help="User id to make owner")
+    elect_owner.set_defaults(func=handle_org_elect_owner)
+
+
+def _register_user(sub: _SubParsersAction[ArgumentParser]) -> None:
+    user = sub.add_parser("user", help="User lifecycle management")
+    usub = user.add_subparsers(dest="user_action")
+
+    ls = usub.add_parser("list", help="List users")
+    ls.set_defaults(func=handle_user_list)
+
+    get = usub.add_parser("get", help="Show one user")
+    get.add_argument("id", help="User id")
+    get.set_defaults(func=handle_user_get)
+
+    create = usub.add_parser("create", help="Provision a user")
+    create.add_argument("email", help="User email")
+    create.add_argument("--name", default="", help="Display name (optional)")
+    create.add_argument("--org-id", dest="org_id", default="", help="Org to place the user in (optional)")
+    create.add_argument("--password", default="", help="Initial password (optional)")
+    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.add_argument("id", help="User id")
+    approve.set_defaults(func=handle_user_approve)
+
+    promote = usub.add_parser("promote", help="Grant platform-admin")
+    promote.add_argument("id", help="User id")
+    promote.set_defaults(func=handle_user_promote)
+
+    demote = usub.add_parser("demote", help="Revoke platform-admin")
+    demote.add_argument("id", help="User id")
+    demote.set_defaults(func=handle_user_demote)
+
+    reject = usub.add_parser("reject", help="Decline a pending signup")
+    reject.add_argument("id", help="User id")
+    reject.add_argument("--org-id", dest="org_id", required=True, help="Org the pending signup belongs to")
+    reject.set_defaults(func=handle_user_reject)
+
+    disable = usub.add_parser("disable", help="Disable a user")
+    disable.add_argument("id", help="User id")
+    disable.set_defaults(func=handle_user_disable)
+
+    enable = usub.add_parser("enable", help="Re-enable a user")
+    enable.add_argument("id", help="User id")
+    enable.set_defaults(func=handle_user_enable)
+
+    reset_password = usub.add_parser("reset-password", help="Set a user's password")
+    reset_password.add_argument("id", help="User id")
+    reset_password.add_argument("--password", required=True, help="New password")
+    reset_password.set_defaults(func=handle_user_reset_password)
+
+    keys = usub.add_parser("keys", help="List a user's API keys")
+    keys.add_argument("id", help="User id")
+    keys.set_defaults(func=handle_user_keys)
+
+    set_scopes = usub.add_parser("set-scopes", help="Replace an API key's scopes")
+    set_scopes.add_argument("id", help="User id")
+    set_scopes.add_argument("key_id", help="API key id")
+    set_scopes.add_argument(
+        "--scope",
+        dest="scopes",
+        action="append",
+        required=True,
+        help="A scope to grant (repeat for multiple)",
+    )
+    set_scopes.set_defaults(func=handle_user_set_scopes)
+
+
+def _register_feature_flags(sub: _SubParsersAction[ArgumentParser]) -> None:
+    ff = sub.add_parser("feature-flags", help="Runtime feature flags")
+    ffsub = ff.add_subparsers(dest="ff_action")
+
+    ls = ffsub.add_parser("list", help="List feature flags")
+    ls.set_defaults(func=handle_feature_flags_list)
+
+    set_flag = ffsub.add_parser("set", help="Enable (or, with --disabled, disable) a flag")
+    set_flag.add_argument("name", help="Flag name")
+    set_flag.add_argument("--disabled", action="store_true", help="Disable the flag (default is enable)")
+    set_flag.set_defaults(func=handle_feature_flags_set)
+
+
+# --- org handlers ---------------------------------------------------------
+
+
+def handle_org_create(client: api_client.ApiClient, args: Any) -> Any:
+    return client.post(
+        "/api/v1/admin/organizations",
+        json={"name": args.name, "github_login": args.github_login},
+    )
+
+
+def handle_org_set_owner(client: api_client.ApiClient, args: Any) -> Any:
+    # 204 No Content → post() returns None; synthesize a confirmation.
+    client.post(f"/api/v1/admin/organizations/{args.org_id}/owner", json={"email": args.email})
+    return {"org_id": args.org_id, "owner": args.email}
+
+
+def handle_org_list(client: api_client.ApiClient, _args: Any) -> Any:
+    return client.get("/api/v1/admin/organizations")
+
+
+def handle_org_get(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/admin/organizations/{args.org_id}")
+
+
+def handle_org_set_limit(client: api_client.ApiClient, args: Any) -> Any:
+    return client.patch(f"/api/v1/admin/organizations/{args.org_id}", json={"max_members": args.max})
+
+
+def handle_org_set_github_login(client: api_client.ApiClient, args: Any) -> Any:
+    # An empty login unlinks the org from GitHub auto-join; pass it through
+    # verbatim so the server can distinguish "clear" from "unchanged".
+    return client.patch(f"/api/v1/admin/organizations/{args.org_id}", json={"github_login": args.login})
+
+
+def handle_org_elect_owner(client: api_client.ApiClient, args: Any) -> Any:
+    # 204 No Content → post() returns None; synthesize a confirmation.
+    client.post(
+        "/api/v1/admin/organizations/elect-owner",
+        json={"github_login": args.github_login, "user_id": args.user_id},
+    )
+    return {"elected": args.user_id, "github_login": args.github_login}
+
+
+# --- user handlers --------------------------------------------------------
+
+
+def handle_user_list(client: api_client.ApiClient, _args: Any) -> Any:
+    return client.get("/api/v1/admin/users")
+
+
+def handle_user_get(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/admin/users/{args.id}")
+
+
+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).
+    body = {
+        "email": args.email,
+        "name": args.name,
+        "org_id": args.org_id,
+        "is_admin": args.admin,
+    }
+    if args.password:
+        body["password"] = args.password
+    return client.post("/api/v1/admin/users", json=body)
+
+
+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})
+
+
+def handle_user_promote(client: api_client.ApiClient, args: Any) -> Any:
+    return client.patch(f"/api/v1/admin/users/{args.id}", json={"is_admin": True})
+
+
+def handle_user_demote(client: api_client.ApiClient, args: Any) -> Any:
+    return client.patch(f"/api/v1/admin/users/{args.id}", json={"is_admin": False})
+
+
+def handle_user_reject(client: api_client.ApiClient, args: Any) -> Any:
+    # 204 No Content → post() returns None; synthesize a confirmation.
+    client.post(f"/api/v1/admin/users/{args.id}/reject", json={"org_id": args.org_id})
+    return {"rejected": args.id}
+
+
+def handle_user_disable(client: api_client.ApiClient, args: Any) -> Any:
+    client.post(f"/api/v1/admin/users/{args.id}/disable")
+    return {"disabled": args.id}
+
+
+def handle_user_enable(client: api_client.ApiClient, args: Any) -> Any:
+    client.post(f"/api/v1/admin/users/{args.id}/enable")
+    return {"enabled": args.id}
+
+
+def handle_user_reset_password(client: api_client.ApiClient, args: Any) -> Any:
+    client.post(f"/api/v1/admin/users/{args.id}/reset-password", json={"password": args.password})
+    return {"password_reset": args.id}
+
+
+def handle_user_keys(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/admin/users/{args.id}/keys")
+
+
+def handle_user_set_scopes(client: api_client.ApiClient, args: Any) -> Any:
+    return client.put(
+        f"/api/v1/admin/users/{args.id}/keys/{args.key_id}/scopes",
+        json={"scopes": args.scopes},
+    )
+
+
+# --- feature-flag handlers ------------------------------------------------
+
+
+def handle_feature_flags_list(client: api_client.ApiClient, _args: Any) -> Any:
+    return client.get("/api/v1/admin/feature-flags")
+
+
+def handle_feature_flags_set(client: api_client.ApiClient, args: Any) -> Any:
+    return client.put(f"/api/v1/admin/feature-flags/{args.name}", json={"enabled": not args.disabled})

{cmpnd-0.4.0 → cmpnd-0.4.1}/cmpnd/cli/commands/org.py

@@ -15,6 +15,13 @@ hit /api/v1/org/ownership-requests and are self-scoped to the calling key's
 user — no owner check (a platform admin grants ownership from the election
 queue; the request is just recorded intent).
 
+`cmpnd org keys list|create|revoke` is your own API-key surface (CMP-472):
+list the keys you've minted, mint a new scoped key (the response carries the
+one-time token — the server stores only its hash), and revoke one. These hit
+/api/v1/org/keys and are self-scoped to the calling key's user — you only ever
+see and manage your own keys, bound to your active org (the non-interactive
+alternative to the `cmpnd login` loopback).
+
 Always registered (no env gate); the server is the authority.
 """
 
@@ -66,6 +73,27 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     withdraw.add_argument("github_login", help="The org's GitHub login (e.g. acme)")
     withdraw.set_defaults(func=handle_withdraw_ownership)
 
+    keys = sub.add_parser("keys", help="Manage your organization's API keys")
+    ksub = keys.add_subparsers(dest="keys_action")
+
+    keys_list = ksub.add_parser("list", help="List the org's API keys")
+    keys_list.set_defaults(func=handle_keys_list)
+
+    keys_create = ksub.add_parser("create", help="Mint a new scoped API key")
+    keys_create.add_argument("name", help="A label for the key")
+    keys_create.add_argument(
+        "--scope",
+        dest="scopes",
+        action="append",
+        required=True,
+        help="A scope to grant (repeat for multiple)",
+    )
+    keys_create.set_defaults(func=handle_keys_create)
+
+    keys_revoke = ksub.add_parser("revoke", help="Revoke an API key")
+    keys_revoke.add_argument("key_id", help="API key id (from `org keys list`)")
+    keys_revoke.set_defaults(func=handle_keys_revoke)
+
 
 def handle_members_pending(client: api_client.ApiClient, _args: Any) -> Any:
     return client.get("/api/v1/org/members/pending")
@@ -113,3 +141,19 @@ def handle_ownership_requests(client: api_client.ApiClient, _args: Any) -> Any:
 def handle_withdraw_ownership(client: api_client.ApiClient, args: Any) -> Any:
     client.post(f"/api/v1/org/ownership-requests/{args.github_login}/withdraw")
     return {"withdrawn": args.github_login}
+
+
+def handle_keys_list(client: api_client.ApiClient, _args: Any) -> Any:
+    return client.get("/api/v1/org/keys")
+
+
+def handle_keys_create(client: api_client.ApiClient, args: Any) -> Any:
+    # The response carries the one-time key token — the server stores only its
+    # hash, so this is the single moment it's shown. Pass it straight through.
+    return client.post("/api/v1/org/keys", json={"name": args.name, "scopes": args.scopes})
+
+
+def handle_keys_revoke(client: api_client.ApiClient, args: Any) -> Any:
+    # 204 No Content → delete() returns None; synthesize a confirmation.
+    client.delete(f"/api/v1/org/keys/{args.key_id}")
+    return {"revoked": args.key_id}

{cmpnd-0.4.0 → cmpnd-0.4.1}/cmpnd/optimizers/gepa_callback.py

@@ -255,7 +255,11 @@ class CmpndGEPACallback:
                         self._tracker.best_score = c.val_aggregate_score
                         break
 
-            # Collect untraced LM usage (reflection calls) before clearing context
+            # Collect any untraced LM usage before clearing context. Reflection
+            # calls are now emitted as standalone traces linked to this run
+            # (CMP-485), so their cost is accounted for by serve's
+            # TracedTokensForRun and _orphaned_lm_usage is normally empty; this
+            # remains only as a fallback for LM calls that never got a trace.
             cmpnd_cb = self._get_cmpnd_callback()
             if cmpnd_cb:
                 if cmpnd_cb._orphaned_lm_usage:

{cmpnd-0.4.0 → cmpnd-0.4.1}/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.4.0"
+version = "0.4.1"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"

cmpnd-0.4.1/scripts/capture_review_run.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python
+"""Capture a real committee GEPA run into scripts/fixtures/review_run.json.gz.
+
+This regenerates the fixture that `scripts/seed_review_run.py` replays into every
+review app. The fixture is a list of `{"kind", "payload"}` items — one per SDK
+exporter HTTP call — captured by hooking `cmpnd.exporter._send_json` (the single
+chokepoint every export POST routes through) while running the exact committee
+GEPA optimization the stress suite runs
+(`tests/stress/test_optimize_client_committee.py` → `tests/e2e/committee_task`):
+a weak OpenRouter student + a Groq reflection LM over the vendored committee
+subset. Capturing a *real* run (rather than fabricating payloads) keeps the seed
+faithful — real prompts, token counts, span trees, and now the GEPA optimizer
+traces (program_name "GEPA", `gepa.phase` reflection/metric — CMP-485).
+
+Only the four kinds `seed_review_run.py` replays are kept — `optimization` (the
+completed run header), `traces_batch`, `spans`, `stats`; the optimization *start*
+POST, progress, start/finalize, and eval calls are dropped. Timestamps, UUIDs,
+and the run linkage are all remapped by the seeder at replay time, so the
+absolute values captured here don't matter.
+
+Usage (from python-sdk/, real third-party inference — no mocks):
+    PLATFORM_API_KEY=... PLATFORM_OPENROUTER_KEY=... PLATFORM_GROQ_KEY=... \
+    PLATFORM_ENDPOINT=http://host.orb.internal:8081 \
+    .venv-linux/bin/python scripts/capture_review_run.py
+
+Env (mirrors the stress test, with CMPND_E2E_* accepted as aliases):
+  - PLATFORM_API_KEY / CMPND_E2E_API_KEY:   cmpnd server API key
+  - PLATFORM_ENDPOINT / CMPND_E2E_ENDPOINT: server URL (default http://localhost:8081)
+  - PLATFORM_OPENROUTER_KEY:                student LM (OpenRouter)
+  - PLATFORM_GROQ_KEY:                      reflection LM (Groq)
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+import os
+import pathlib
+import re
+import sys
+
+# Import the shared committee task + the SDK from the python-sdk root (this
+# script lives one level down in scripts/).
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+
+import dspy  # noqa: E402
+
+import cmpnd  # noqa: E402
+from cmpnd import exporter as exporter_mod  # noqa: E402
+from tests.e2e import committee_task  # noqa: E402
+
+_FIXTURE = pathlib.Path(__file__).resolve().parent / "fixtures" / "review_run.json.gz"
+_SPANS_PATH = re.compile(r"^/api/v1/traces/[^/]+/spans$")
+_OPT_COMPLETE_PATH = re.compile(r"^/api/v1/optimizations/[^/]+$")
+
+
+def _kind_for(method: str, path: str, payload) -> tuple[str, object] | None:
+    """Map an exporter HTTP call to a fixture item, or None to drop it.
+
+    Keeps the four kinds `seed_review_run.py` replays. Normalizes single-trace
+    POSTs (`/api/v1/traces`) into a one-item `traces_batch` so the seeder's
+    replay (which posts every batch to `/api/v1/traces/batch`) stays uniform.
+    The completed run header arrives as a PUT to `/api/v1/optimizations/{id}`
+    (`export_optimization_complete`); the `/api/v1/optimizations` POST is just
+    the "running" start record (CMP-313) and is dropped.
+    """
+    if method == "POST":
+        if path == "/api/v1/traces/batch":
+            return ("traces_batch", payload)
+        if path == "/api/v1/traces":
+            return ("traces_batch", [payload])
+        if _SPANS_PATH.match(path):
+            return ("spans", payload)
+        if path == "/api/v1/traces/stats":
+            return ("stats", payload)
+    elif method == "PUT" and _OPT_COMPLETE_PATH.match(path):
+        return ("optimization", payload)
+    return None
+
+
+def main() -> int:
+    endpoint = (os.getenv("PLATFORM_ENDPOINT") or os.getenv("CMPND_E2E_ENDPOINT") or "http://localhost:8081").rstrip(
+        "/"
+    )
+    api_key = os.getenv("PLATFORM_API_KEY") or os.getenv("CMPND_E2E_API_KEY")
+    if not api_key:
+        print("Set PLATFORM_API_KEY (or CMPND_E2E_API_KEY)", file=sys.stderr)
+        return 2
+    if not committee_task.openrouter_key() or not committee_task.groq_key():
+        print("Set PLATFORM_OPENROUTER_KEY and PLATFORM_GROQ_KEY", file=sys.stderr)
+        return 2
+
+    captured: list[dict] = []
+
+    # Hook the single HTTP chokepoint: record every POST, then send it for real
+    # so the run also lands in the target server (a normal optimization).
+    orig_send_json = exporter_mod._send_json
+
+    def _capturing_send_json(client, method, path, payload):
+        item = _kind_for(method, path, payload)
+        if item is not None:
+            # Deep-copy via round-trip so a later in-place mutation (the
+            # exporter reuses builders) can't rewrite what we captured. `path`
+            # is what the seeder reads to route "spans" items to their trace
+            # (`/api/v1/traces/{id}/spans`); harmless on the other kinds.
+            captured.append({"kind": item[0], "path": path, "payload": json.loads(json.dumps(item[1], default=str))})
+        return orig_send_json(client, method, path, payload)
+
+    exporter_mod._send_json = _capturing_send_json  # type: ignore[assignment]
+    try:
+        cmpnd.configure(
+            api_key=api_key, endpoint=endpoint, project_tags=["capture-review-run"], flush_interval_seconds=1
+        )
+        cmpnd.auto_instrument()
+
+        program = committee_task.build_program(committee_task.STUDENT_3B)
+        trainset, valset = committee_task.load_examples()
+        reflection_lm = dspy.LM(
+            committee_task.REFLECTION_MODEL,
+            api_key=committee_task.groq_key(),
+            api_base=committee_task.GROQ_API_BASE,
+            temperature=1.0,
+            max_tokens=8192,
+            cache=False,
+        )
+        gepa = dspy.GEPA(
+            metric=committee_task.committee_feedback_metric,
+            reflection_lm=reflection_lm,
+            max_metric_calls=120,
+            reflection_minibatch_size=5,
+            num_threads=8,
+            track_stats=True,
+        )
+        gepa.compile(program, trainset=trainset, valset=valset)
+    finally:
+        cmpnd.shutdown_exporter()
+        exporter_mod._send_json = orig_send_json  # type: ignore[assignment]
+
+    # Sanity: refuse to overwrite the fixture with a broken capture.
+    kinds = [it["kind"] for it in captured]
+    n_opt = kinds.count("optimization")
+    trace_payloads = [t for it in captured if it["kind"] == "traces_batch" for t in it["payload"]]
+    programs = {t.get("program_name") for t in trace_payloads}
+    if n_opt != 1:
+        print(f"expected exactly 1 completed optimization, captured {n_opt}; not writing", file=sys.stderr)
+        return 1
+    if "GEPA" not in programs:
+        print(f"no GEPA optimizer traces captured (programs={programs}); not writing", file=sys.stderr)
+        return 1
+
+    _FIXTURE.parent.mkdir(parents=True, exist_ok=True)
+    _FIXTURE.write_bytes(gzip.compress(json.dumps(captured).encode("utf-8")))
+
+    from collections import Counter
+
+    print(f"wrote {_FIXTURE} — {len(captured)} items {dict(Counter(kinds))}")
+    print(f"  trace program_names: {dict(Counter(t.get('program_name') for t in trace_payloads))}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())