cmpnd 0.71.0__tar.gz → 0.73.0__tar.gz

{cmpnd-0.71.0 → cmpnd-0.73.0}/PKG-INFO

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

{cmpnd-0.71.0 → cmpnd-0.73.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.71.0 → cmpnd-0.73.0}/cmpnd/cli/commands/deployments.py

@@ -191,6 +191,9 @@ def submit_cli_run(
         raise
     except httpx.HTTPStatusError as exc:
         raise _http_refusal(exc) from exc
+    trace_id = settled.get("trace_id")
+    if isinstance(trace_id, str) and trace_id:
+        print(f"Trace: {trace_id}", file=sys.stderr)
     if settled["status"] == "failed":
         return settled, None
     result = settled.get("result")

{cmpnd-0.71.0 → cmpnd-0.73.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.71.0 → cmpnd-0.73.0}/cmpnd/client.py

@@ -390,6 +390,19 @@ class Client:
 
         return execution.deployment_run_id(result_or_error)
 
+    def get_trace_id(self, result_or_error: Any) -> str | None:
+        """The root trace id of a ``run_deployment`` prediction or exception.
+
+        It reads the id serve returned with the settled run and sends no
+        request. ``get_trace`` opens the trace.
+        The id lives outside the prediction's output fields. A run that stored no
+        trace, a server that names none, and a failure before serve accepted a run
+        all return ``None``.
+        """
+        from . import execution
+
+        return execution.get_trace_id(result_or_error)
+
     def submit_deployment_run(
         self,
         deployment_or_id: Any,

{cmpnd-0.71.0 → cmpnd-0.73.0}/cmpnd/execution.py

@@ -33,6 +33,21 @@ def deployment_run_id(result_or_error: Any) -> str | None:
     return getattr(result_or_error, "_cmpnd_deployment_run_id", None)
 
 
+def get_trace_id(result_or_error: Any) -> str | None:
+    """Return the root trace id serve named for a run's prediction or exception.
+
+    The id lives outside the prediction's program output fields. A run that
+    stored no trace, a server that names none, and a failure before serve
+    accepted a run all return ``None``.
+    """
+    return getattr(result_or_error, "_cmpnd_deployment_trace_id", None)
+
+
+def _settled_trace_id(settled: dict[str, Any]) -> str | None:
+    trace_id = settled.get("trace_id")
+    return trace_id if isinstance(trace_id, str) and trace_id else None
+
+
 def _with_run_id(error: Exception, run_id: str | None) -> Exception:
     error._cmpnd_deployment_run_id = run_id  # pyright: ignore[reportAttributeAccessIssue]
     return error
@@ -247,14 +262,20 @@ def run_deployment(
         raise
 
     settled_id: str = settled["deployment_run_id"]
+    trace_id = _settled_trace_id(settled)
     result = settled["result"]
     if settled["status"] == "failed":
-        _raise_stored_failure(settled_id, result, config.endpoint)
+        try:
+            _raise_stored_failure(settled_id, result, config.endpoint)
+        except Exception as error:
+            error._cmpnd_deployment_trace_id = trace_id  # pyright: ignore[reportAttributeAccessIssue]
+            raise
     if not isinstance(result, dict) or "output" not in result:
         raise _with_run_id(RuntimeError("Deployment run result has no program output"), settled_id)
     output = result["output"]
     prediction = Prediction(**output) if isinstance(output, dict) else Prediction(**{"output": output})
     setattr(prediction, "_cmpnd_deployment_run_id", settled_id)
+    setattr(prediction, "_cmpnd_deployment_trace_id", trace_id)
     return prediction
 
 

{cmpnd-0.71.0 → cmpnd-0.73.0}/docs/cli.md

@@ -228,6 +228,10 @@ seconds, unless `--timeout` sets the budget. The CLI prints the accepted run ID
 on stderr as soon as serve replies, which can take up to serve's five-second
 wait. A failed run exits nonzero. Human mode prints the stored error code,
 message and provider status. `--json` prints the whole settled run on stdout.
+When a settled run names its root trace, the CLI prints `Trace: <id>` on
+stderr, completed or failed. `cmpnd traces show <id>` opens that trace. The
+run's `trace_id` field holds the same ID, and serve leaves it out when the run
+stored no trace.
 The CLI retries status reads that time out or answer `408`, `429` or `5xx`
 within the budget.
 
@@ -886,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.71.0 → cmpnd-0.73.0}/docs/client.md

@@ -147,7 +147,9 @@ endpoint. None of these reads the global config:
 - `sdk.submit_deployment_run`, `list_deployment_runs`, `get_deployment_run`,
   `get_deployment_run_result` and `wait_deployment_run` submit, find and resume
   runs without waiting in one call. `sdk.deployment_run_id(result)` reads the run
-  id of a prediction or an exception.
+  id of a prediction or an exception. `sdk.get_trace_id(result)` reads the
+  id of the run's root trace the same way, or returns `None` when serve named no
+  trace.
 - `sdk.optimize_deployment(deployment, optimizer="gepa", ...)` runs the
   platform's optimization on a deployment and returns the best
   `DeployedProgram`, with `.score`. It never deploys. The program's model comes

{cmpnd-0.71.0 → cmpnd-0.73.0}/docs/sdk-instrumentation.md

@@ -432,7 +432,12 @@ command, and re-raises.
 `client.deployment_run_id(result)` reads the ID from
 private prediction metadata, so a program can use `output` or
 `deployment_run_id` as an output field. The accessor also accepts a stored
-execution error, a refused read, `RunWaitTimeout` and `RunResultExpired`. A
+execution error, a refused read, `RunWaitTimeout` and `RunResultExpired`.
+`client.get_trace_id(result)` reads the id of the run's root trace from
+the same metadata, for a completed run's prediction and a failed run's error.
+`cmpnd traces show` opens that trace. It returns `None` when the run stored no
+trace, when the server names none, and when the run failed before serve
+accepted it. A
 retained provider failure keeps its structured `RetryableProviderError` type but
 does not start another run. Trace delivery can finish after the result is
 available.
@@ -454,8 +459,10 @@ header readable.
 try:
     result = client.run_deployment(deployed, question="What changed?")
     run_id = client.deployment_run_id(result)
+    trace_id = client.get_trace_id(result)
 except Exception as error:
     run_id = client.deployment_run_id(error)
+    trace_id = client.get_trace_id(error)
     raise
 ```
 

{cmpnd-0.71.0 → cmpnd-0.73.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.71.0"
+version = "0.73.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

{cmpnd-0.71.0 → cmpnd-0.73.0}/tests/test_cli/test_admin.py

@@ -283,6 +283,24 @@ def _parse(*argv: str) -> Namespace:
     return parser.parse_args(["admin", *argv])
 
 
+class TestAdminUserActivity:
+    def test_activity_reads_the_users_history(self, mock_client):
+        mock_client.get.return_value = {"user_id": "u_1", "memberships": [], "events": []}
+        args = _parse("user", "activity", "u_1")
+        result = args.func(mock_client, args)
+        mock_client.get.assert_called_once_with("/api/v1/admin/users/u_1/activity")
+        assert result["user_id"] == "u_1"
+
+
+class TestAdminOrgUsage:
+    def test_usage_reads_the_orgs_limits_in_use_and_activity(self, mock_client):
+        mock_client.get.return_value = {"org_id": "o_1", "in_use": {"members.approved": 2}, "windows": []}
+        args = _parse("org", "usage", "o_1")
+        result = args.func(mock_client, args)
+        mock_client.get.assert_called_once_with("/api/v1/admin/organizations/o_1/usage")
+        assert result["in_use"] == {"members.approved": 2}
+
+
 class TestAdminOrgPlan:
     def test_plan_shows_the_orgs_plan(self, mock_client):
         mock_client.get.return_value = {"org_id": "o_1", "plan": "free", "limits": []}

{cmpnd-0.71.0 → cmpnd-0.73.0}/tests/test_cli/test_deployment_runs.py

@@ -537,3 +537,37 @@ def test_json_run_commands_do_not_import_dspy(argv: list[str], replies: list):
     assert "JSON run command imported dspy" not in result.stderr
     out = json.loads(result.stdout)
     assert RUN_ID in result.stdout or "yes" in json.dumps(out)
+
+
+TRACE_ID = "0b9c6f2e-4f1d-4c3a-9e2b-7a1d5c3e8f00"
+
+
+def test_failed_run_names_its_trace_on_stderr(monkeypatch: pytest.MonkeyPatch, capsys):
+    failure = {"error": {"type": "ProgramError", "message": "bad input"}, "execution_status": 500}
+
+    def answer(req):
+        return httpx.Response(200, json={**_envelope("failed", failure), "trace_id": TRACE_ID}, request=req)
+
+    with pytest.raises(SystemExit):
+        _run_cli(monkeypatch, ["run", DEPLOYMENT_ID, "{}"], answer)
+    assert f"Trace: {TRACE_ID}" in capsys.readouterr().err
+
+
+def test_completed_run_names_its_trace_on_stderr_and_keeps_stdout_the_output(monkeypatch: pytest.MonkeyPatch, capsys):
+    def answer(req):
+        return httpx.Response(
+            200, json={**_envelope("completed", {"output": {"answer": "yes"}}), "trace_id": TRACE_ID}, request=req
+        )
+
+    _run_cli(monkeypatch, ["run", DEPLOYMENT_ID, "{}", "--json"], answer)
+    out = capsys.readouterr()
+    assert json.loads(out.out) == {"answer": "yes"}
+    assert f"Trace: {TRACE_ID}" in out.err
+
+
+def test_run_without_a_trace_names_none(monkeypatch: pytest.MonkeyPatch, capsys):
+    def answer(req):
+        return httpx.Response(200, json=_envelope("completed", {"output": {"answer": "yes"}}), request=req)
+
+    _run_cli(monkeypatch, ["run", DEPLOYMENT_ID, "{}", "--json"], answer)
+    assert "Trace:" not in capsys.readouterr().err

{cmpnd-0.71.0 → cmpnd-0.73.0}/tests/test_deployment_runs.py

@@ -505,3 +505,71 @@ def test_failure_summary_names_code_message_and_provider_status():
         f"Deployment run {RUN_ID} failed: EgressFailed: provider failed (provider status 429)"
     )
     assert deployment_runs.failure_summary(_run("failed", {"error": "boom"})) == f"Deployment run {RUN_ID} failed: boom"
+
+
+TRACE_ID = "0b9c6f2e-4f1d-4c3a-9e2b-7a1d5c3e8f00"
+
+
+def test_a_completed_run_names_its_trace_beside_its_run_id(monkeypatch: pytest.MonkeyPatch):
+    def answer(req: httpx.Request) -> httpx.Response:
+        body = {**_run("completed", {"output": {"answer": "yes"}}, available=True), "trace_id": TRACE_ID}
+        return httpx.Response(200, json=body, request=req)
+
+    _transport(monkeypatch, answer)
+    prediction = _client().run_deployment(DEPLOYMENT_ID, question="hi")
+    assert prediction.answer == "yes"
+    assert _client().get_trace_id(prediction) == TRACE_ID
+    assert _client().deployment_run_id(prediction) == RUN_ID
+    assert "trace_id" not in prediction.keys()
+
+
+def test_a_failed_run_names_its_trace_on_the_raised_error(monkeypatch: pytest.MonkeyPatch):
+    failure = {"error": {"type": "ProgramError", "message": "bad input"}, "execution_status": 500}
+
+    def answer(req: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={**_run("failed", failure, available=True), "trace_id": TRACE_ID}, request=req)
+
+    _transport(monkeypatch, answer)
+    with pytest.raises(httpx.HTTPStatusError) as caught:
+        _client().run_deployment(DEPLOYMENT_ID)
+    assert _client().get_trace_id(caught.value) == TRACE_ID
+    assert _client().deployment_run_id(caught.value) == RUN_ID
+
+
+def test_a_retryable_provider_failure_names_its_trace(monkeypatch: pytest.MonkeyPatch):
+    failure = {
+        "error": {"type": "EgressFailed", "message": "provider refused"},
+        "execution_status": 503,
+        "retryable": True,
+        "failure": {"domain": "provider", "upstream_status": 429, "attempts": 3},
+    }
+
+    def answer(req: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={**_run("failed", failure, available=True), "trace_id": TRACE_ID}, request=req)
+
+    _transport(monkeypatch, answer)
+    with pytest.raises(cmpnd.RetryableProviderError) as caught:
+        _client().run_deployment(DEPLOYMENT_ID)
+    assert _client().get_trace_id(caught.value) == TRACE_ID
+
+
+@pytest.mark.parametrize("trace_field", [{}, {"trace_id": None}, {"trace_id": ""}, {"trace_id": 7}])
+def test_a_run_serve_names_no_trace_for_has_none(monkeypatch: pytest.MonkeyPatch, trace_field: dict):
+    def answer(req: httpx.Request) -> httpx.Response:
+        body = {**_run("completed", {"output": {"answer": "yes"}}, available=True), **trace_field}
+        return httpx.Response(200, json=body, request=req)
+
+    _transport(monkeypatch, answer)
+    prediction = _client().run_deployment(DEPLOYMENT_ID, question="hi")
+    assert _client().get_trace_id(prediction) is None
+
+
+def test_a_failure_before_acceptance_has_no_trace(monkeypatch: pytest.MonkeyPatch):
+    def answer(req: httpx.Request) -> httpx.Response:
+        return httpx.Response(404, json={"error": "not found"}, request=req)
+
+    _transport(monkeypatch, answer)
+    with pytest.raises(httpx.HTTPStatusError) as caught:
+        _client().run_deployment(DEPLOYMENT_ID)
+    assert _client().get_trace_id(caught.value) is None
+    assert _client().get_trace_id(object()) is None

{cmpnd-0.71.0 → cmpnd-0.73.0}/uv.lock

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