revenium-python-sdk 0.7.0__tar.gz → 0.9.0__tar.gz

{revenium_python_sdk-0.7.0 → revenium_python_sdk-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: revenium-python-sdk
-Version: 0.7.0
+Version: 0.9.0
 Summary: The official Revenium Python SDK — unified AI metering middleware for OpenAI, Anthropic, Google, Ollama, LiteLLM, Perplexity, and fal.ai.
 Author-email: Revenium <support@revenium.io>
 License: MIT
@@ -76,7 +76,7 @@ Requires-Dist: wrapt>=1.14.0; extra == "litellm"
 Requires-Dist: litellm>=1.40.0; extra == "litellm"
 Provides-Extra: litellm-proxy
 Requires-Dist: wrapt>=1.14.0; extra == "litellm-proxy"
-Requires-Dist: litellm[proxy]>=1.40.0; extra == "litellm-proxy"
+Requires-Dist: litellm[proxy]>=1.93.0; extra == "litellm-proxy"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
@@ -264,7 +264,70 @@ when the provider's SDK is installed.
 
 Emit per-agent terminal outcomes (`CONVERTED`, `DEFLECTED`, `ESCALATED`) alongside completion and tool-event records, so dashboards show business value next to AI cost.
 
-> **You need a write-scope key (`rev_sk_`) to use the agentic outcomes API.** Metering keys (`rev_mk_`) can only meter completions and tool events — they cannot report, amend, or read job outcomes, and the SDK rejects them client-side before any HTTP request is made. Key resolution: explicit `api_key=` > `REVENIUM_OUTCOME_API_KEY` > `REVENIUM_METERING_API_KEY`.
+> **You need a write-scope key (`rev_sk_`) to use the agentic outcomes API.** Metering keys (`rev_mk_`) can only meter completions and tool events — they cannot report, amend, or read job outcomes, and the SDK rejects them client-side before any HTTP request is made. Key resolution: explicit `api_key=` > `REVENIUM_WRITE_API_KEY` > `REVENIUM_OUTCOME_API_KEY` (deprecated fallback) > `REVENIUM_METERING_API_KEY`.
+
+### Job-Type Economics and Outcome Facts
+
+Keep a metering key for AI telemetry and a separate write key for outcomes and
+job-type configuration. A registered `valuePerUnit` rule takes precedence over
+an outcome's `outcome_value`; the backend never sums the two value sources.
+
+```python
+from revenium_middleware import (
+    Baseline, JobTypeEconomics, PeriodFactEntry, create_baseline,
+    report_period_facts, upsert_job_type_economics,
+)
+
+upsert_job_type_economics("claim", JobTypeEconomics(
+    unit_metric_key="completed_claims", unit_label="claim",
+    metrics=[
+        {
+            "key": "completed_claims", "type": "COUNT",
+            "direction": "HIGHER_IS_BETTER", "aggregation": "SUM",
+            "resolution": "PER_JOB",
+        },
+        {
+            "key": "claims_processed", "type": "COUNT",
+            "direction": "HIGHER_IS_BETTER", "aggregation": "SUM",
+            "resolution": "PERIOD",
+        },
+    ],
+    dimensions=[{"key": "region", "allowedValues": ["us", "ca"]}],
+    monetization={
+        "metricKey": "completed_claims", "valuePerUnit": 4.25,
+        "currency": "USD", "category": "COST_AVOIDED", "basis": "REALIZED",
+    },
+))
+create_baseline("claim", Baseline(
+    effective_from="2026-08-01T00:00:00Z", cost_per_unit=4.25, currency="USD",
+))
+report_period_facts("claim", [PeriodFactEntry(
+    period_start="2026-08-01T00:00:00Z", period_end="2026-09-01T00:00:00Z",
+    dimension_key="region", dimension_value="us",
+    key="claims_processed", value=1280,
+)])
+```
+
+`effective_from` is the only required field on a baseline; every other field
+is optional, and a baseline without it is rejected. A job type must be
+declared with `upsert_job_type_economics` before it accepts baselines or
+facts, and `report_period_facts` accepts only metrics declared with
+`"resolution": "PERIOD"`.
+
+Job economics currency values must be USD. Baselines and period facts use
+server-supplied attribution when their provenance,
+reporter, and source fields are omitted. Set those fields only when you need an
+explicit override. Economics metric directions are
+`HIGHER_IS_BETTER` or `LOWER_IS_BETTER`; monetization categories are
+`REVENUE`, `COST_AVOIDED`, `TIME_SAVED`, and `LEADING_VALUE`, with a
+`REALIZED` or `EXPECTED` basis.
+
+Use `CUSTOMER_DECLARED` or `MEASURED` for a baseline override. Use `MEASURED`,
+`SELF_REPORTED`, or `DERIVED` for a period fact override.
+
+Facts are append-only and keyed on the period, dimension and metric key
+together. Re-appending that tuple supersedes the active fact, and the server
+requires `reason=` on the entry when it does.
 
 ### JobContext
 
@@ -311,10 +374,70 @@ history = get_outcome_history("sales-lead-8842")
 # List[JobOutcomeAmendment], ordered by amendment_sequence (1 = the initial report)
 ```
 
-`amend_outcome()` takes a mandatory non-blank `reason` plus the same optional fields as `report_outcome()` (`execution_status`, `outcome_type`, `outcome_value`, `outcome_currency`, `metadata`, `reported_by`, `outcome_reason`), and returns the updated job as a dict.
+`amend_outcome()` takes `reason` — the amendment's audit justification, still the first positional argument — plus the same optional fields as `report_outcome()` (`execution_status`, `outcome_type`, `outcome_value`, `outcome_currency`, `metadata`, `reported_by`, `outcome_reason`, `metrics`), and returns the updated job as a dict.
+
+- **Detecting a lost update:** `report_outcome()` and `amend_outcome()` record the job's `entityVersion` from the response on the handle (readable as `job.entity_version`). The next `amend_outcome()` on that same handle sends it as `expectedEntityVersion`, so an amendment that would overwrite a change made by another writer in the meantime raises `OutcomeAmendConflictError` instead of silently winning. Pass `expected_entity_version=` to lock against a version you fetched yourself; use a fresh `JobContext.attach()` handle — which has recorded nothing — for the old last-write-wins behavior.
+
+```python
+from revenium_middleware import OutcomeAmendConflictError, get_outcome_history
+
+try:
+    job.amend_outcome(reason="Chargeback", outcome_value=0.0)
+except OutcomeAmendConflictError as conflict:
+    # The conflict reports the version the platform actually holds.
+    print(conflict.current_entity_version)          # e.g. 9
+
+    # Look at what the other writer changed, and only re-issue the amendment
+    # if it still applies to what is recorded now.
+    history = get_outcome_history("sales-lead-8842")
+    if still_applies(history[-1]):
+        job.amend_outcome(reason="Chargeback, re-checked", outcome_value=0.0,
+                          expected_entity_version=conflict.current_entity_version)
+```
 
+The handle also records that version, so the retry above works with or without passing `expected_entity_version=` explicitly. `current_entity_version` is `None` when the conflict body carries no version; the version then has to come from a job read (`GET /v2/api/jobs/{agenticJobId}`), which this SDK does not wrap yet, and a retry without it is unlocked (last-write-wins). `get_outcome_history()` rows carry an `amendment_sequence`, not an entity version — history tells you *what* changed, never which version to retry with.
+
+Every outcome call replaces the recorded version with the one its response reports, including clearing it when a response carries none, so a completed call never leaves a token behind that the platform has already moved past.
+
+- **Omitting `reason`:** an API-key caller may leave `reason` out and the platform records an automated correction reason derived from the source. A session caller must supply one; a blank string is rejected client-side either way.
 - **`reason` vs `outcome_reason`:** `reason` is the amendment's own audit justification (why the record changed); `outcome_reason` is the business explanation of why the job failed or was cancelled. Use `outcome_reason` for failure explanations rather than burying them in `metadata` — it is a first-class field on the outcome and is returned on every `get_outcome_history()` row.
 - **Clearing `outcome_reason`:** omit the argument to leave the stored value untouched; pass an empty string (`outcome_reason=""`) to clear it.
+- **`metrics`:** both `report_outcome()` and `amend_outcome()` accept a `metrics` argument for recording the measurable facts behind an outcome.
+
+### Recording Metric Facts
+
+Beyond the single `outcome_value`, a job can carry the measurable facts its job type declares — `quality_rate` and its siblings — either with the outcome or later, once they are measurable.
+
+```python
+from revenium_middleware import JobContext
+
+with JobContext("claim-8842", type="claims_triage") as job:
+    ...
+    job.report_outcome(
+        execution_status="SUCCESS",
+        outcome_type="CONVERTED",
+        metrics=[
+            {"key": "quality_rate", "value": 0.93, "provenance": "MEASURED"},
+            {"key": "cases_closed", "value": 12},
+        ],
+    )
+
+# Two days later a human grades a sample of that same job's output.
+handle = JobContext.attach("claim-8842")
+handle.append_outcome_metrics([
+    {"key": "quality_rate", "value": 0.87, "provenance": "ATTESTED",
+     "reason": "graded sample of 200 cases"},
+])
+handle.close()
+```
+
+- **Declare the metric first:** a fact only lands if the job type's economics contract declares that key as a `PER_JOB` metric; an undeclared key is rejected with a 400. `quality_rate` is a rate and the platform range-checks it to 0..1.
+- **Entry shape:** `key` and `value` are required; `provenance` (`MEASURED` | `SELF_REPORTED` | `DERIVED` | `ATTESTED`), `recordedBy`, `source`, `reason` and `recordedAt` are optional. Entries are sent exactly as you write them, so the fields you omit take the platform's defaults (`SELF_REPORTED`, the calling principal, `api`) instead of being guessed by the SDK. A missing `key` or `value` — or no entries at all on `append_outcome_metrics()` — raises `ValueError` before any HTTP request, on `JobContext` and `AgenticOutcomeClient` alike.
+- **Append-only:** facts accumulate; the SDK never dedupes or replaces one, because the platform owns fact identity. `metrics=` on `amend_outcome()` appends as part of the amendment.
+- **Not part of outcome history:** `get_outcome_history()` returns the outcome revisions only — appended facts do not appear in those rows.
+- **Retries:** an append is retried only on `429`, which proves the platform rejected the request before recording anything. A `502`/`503`/`504` is raised instead of retried: the facts may already be recorded, and a second append is a second fact, so the decision to resend is yours (check the recorded facts first).
+- **Locking is unaffected:** appending facts does not change the job's `entityVersion`, so the handle keeps the version it recorded and a following `amend_outcome()` still locks against it. (`report_outcome()` and `amend_outcome()` clear the recorded version when their response carries none, because those calls advance it; an append does not.)
+- **Why it matters:** AI Alerts evaluate `QUALITY_RATE` from these facts, so a job whose integration emits none is invisible to those rules.
 
 ### Outcome Exceptions
 
@@ -325,7 +448,7 @@ All outcome exceptions are importable from `revenium_middleware` and share the `
 | `OutcomeReportingError` | Base class — configuration failures (no API key available, unresolvable `team_id`) | Fix the key / team configuration |
 | `OutcomeAlreadyReportedError` | Re-reporting a job that already has an outcome (backend 409) | Amend with `amend_outcome()` instead; the exception carries `reported_at` and `amendment_count` |
 | `OutcomeNotReportedError` | Amending a job that has no outcome yet (backend 422) | Call `report_outcome()` first |
-| `OutcomeAmendConflictError` | A concurrent amendment changed the outcome (backend 409, optimistic lock) | Refetch with `get_outcome_history()` and retry — the SDK does not auto-retry |
+| `OutcomeAmendConflictError` | A concurrent amendment changed the outcome (backend 409, optimistic lock) | Re-check the outcome against `get_outcome_history()`, then retry with `expected_entity_version=conflict.current_entity_version` — the SDK does not auto-retry |
 
 ### Low-Level Client
 
@@ -340,10 +463,11 @@ client = AgenticOutcomeClient(settings)
 client.emit_completion(...)                # one per LLM call
 client.emit_tool_event(...)                # one per tool / step
 client.report_outcome(job_id, {...})       # close the job with a terminal outcome
+client.append_outcome_metrics(job_id, [...])  # append declared per-job facts later
 client.close()
 ```
 
-The job is created implicitly by the first metric ingested for `agenticJobId`. Call `client.create_job(job_id)` explicitly if you need to record an agent run before emitting any metrics.
+The job is created implicitly by the first metric ingested for `agenticJobId`. Call `client.create_job(job_id)` explicitly if you need to record an agent run before emitting any metrics; it returns the created job resource merged over the fields you supplied, including the `entityVersion` an outcome amendment sends back as `expectedEntityVersion`.
 
 See [`examples/agentic_outcomes/`](examples/agentic_outcomes/) for runnable demos (sales / coding / support) with configurable failure rates and outcome distributions.
 
@@ -553,7 +677,31 @@ with client.messages.stream(
         print(text, end="", flush=True)
 ```
 
-**Note:** The middleware only wraps `messages.create` and `messages.stream` endpoints. Other Anthropic SDK features work normally but aren't metered.
+Async streaming is metered the same way, with the same metadata:
+
+```python
+import asyncio
+import anthropic
+import revenium_middleware.anthropic
+
+client = anthropic.AsyncAnthropic()
+
+async def main():
+    async with client.messages.stream(
+        model="claude-opus-4-7",
+        max_tokens=200,
+        messages=[{"role": "user", "content": "Tell me a story"}],
+        usage_metadata={"task_type": "creative"}
+    ) as stream:
+        async for text in stream.text_stream:
+            print(text, end="", flush=True)
+        # await stream.get_final_message() works too; either way the
+        # completion is metered once when the block exits.
+
+asyncio.run(main())
+```
+
+**Note:** The middleware wraps the `messages.create` and `messages.stream` endpoints, sync and async alike (including `create(stream=True)`). Other Anthropic SDK features work normally but aren't metered.
 
 #### AWS Bedrock
 
@@ -586,7 +734,7 @@ message = client.messages.create(
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `AWS_REGION` | AWS region for Bedrock | `us-east-1` |
-| `REVENIUM_BEDROCK_DISABLE` | Set to `1` to disable Bedrock support | Not set |
+| `REVENIUM_BEDROCK_DISABLE` | Set to `1` to disable Bedrock support (Bedrock detection only - Foundry detection is unaffected) | Not set |
 
 **AWS authentication** uses the standard credential chain: environment variables, `~/.aws/credentials`, IAM roles, AWS SSO. Required permissions: `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream`.
 
@@ -608,6 +756,32 @@ message = client.messages.create(
 
 For other models, the middleware uses the format `anthropic.{model_name}`.
 
+#### Microsoft Foundry
+
+Claude served through Microsoft Foundry is metered by the same patched endpoints as the
+direct Anthropic API - the Anthropic SDK's Foundry clients need no extra setup.
+
+```python
+import anthropic
+import revenium_middleware.anthropic
+
+# Foundry is detected from the client class, so a custom base_url is fine too
+client = anthropic.AnthropicFoundry(
+    resource="your-resource",  # or ANTHROPIC_FOUNDRY_RESOURCE
+)
+
+message = client.messages.create(
+    model="claude-opus-4-7",
+    max_tokens=100,
+    messages=[{"role": "user", "content": "Hello from Foundry!"}]
+)
+```
+
+Foundry usage is reported with provider `Foundry` and model source `ANTHROPIC`, so the spend
+is separated from direct-Anthropic totals while still priced against the Anthropic rate card
+that Foundry bills at. `AsyncAnthropicFoundry` is metered the same way, as is
+`client.messages.stream()`.
+
 **Examples:** `examples/anthropic/` - `anthropic-basic.py`, `anthropic-streaming.py`, `anthropic-bedrock.py`, `anthropic-advanced.py`
 
 ---
@@ -774,15 +948,187 @@ response = litellm.completion(
 
 #### Proxy Mode
 
-Add the callback to your LiteLLM `config.yaml` for server-side integration:
+`ReveniumGuardrail` is the LiteLLM proxy integration. It is a LiteLLM
+`CustomGuardrail` that **enforces the caller's budget before** the proxied call and
+**meters usage after** it — successes, failures and streamed responses alike.
+
+```bash
+pip install "revenium-python-sdk[litellm-proxy]"   # requires Python 3.10+
+```
 
 ```yaml
-litellm_settings:
-  callbacks: ["revenium_middleware.litellm.proxy.middleware.proxy_handler_instance"]
+guardrails:
+  - guardrail_name: "revenium"
+    litellm_params:
+      guardrail: revenium_middleware.litellm.proxy.guardrail.ReveniumGuardrail
+      mode:
+        - "pre_call"    # budget enforcement
+        - "post_call"   # usage metering
+      default_on: true
+```
+
+`guardrails` is a **top-level** key, not a member of `litellm_settings`. Nested
+under `litellm_settings` it reaches LiteLLM's legacy v1 guardrail loader, which
+expects a different shape and exits the proxy at startup with
+`GuardrailItem() argument after ** must be a mapping, not str`.
+
+`mode` must be a **list** to enable both hooks; a single string restricts the
+guardrail to that one event type. `pre_call` alone enforces without metering;
+`post_call` alone meters without enforcing.
+
+**Budget enforcement** reuses the SDK's own circuit breaker, so a proxy enforces
+exactly what every other Revenium integration enforces — including department
+(org-unit) budgets. It is opt-in via `REVENIUM_CIRCUIT_BREAKER_ENABLED=true`; see
+[Cost Controls](#cost-controls). A blocked call never reaches the provider and the
+caller receives HTTP 429:
+
+```json
+{"error": {"message": "Request blocked by Revenium enforcement rule: Team Budget",
+           "type": "budget_exceeded", "guardrail": "revenium", "model": "gpt-4o",
+           "budgets": [{"name": "Team Budget", "ruleId": 7, "threshold": 10.0,
+                        "currentValue": 11.5, "resetsAt": "2026-10-01T00:00:00Z"}]}}
+```
+
+Enforcement **fails open**: if the enforcement path is unreachable or misbehaves,
+the call proceeds. Metering is likewise non-disruptive — nothing in the post-call
+path can turn a successful LLM call into an error for the client.
+
+**Attribution** travels as `x-revenium-*` request headers (subscriber, organization,
+product, trace, task type, agent, subscription, quality score, and `x-revenium-effort`
+for reasoning effort), with the calling virtual key's metadata as the fallback —
+`revenium_user_id`, `revenium_organization_name`, `revenium_key_name`, and
+`revenium_agentic_job_*`. Agentic job tags (`x-revenium-agentic-job-id`, `-name`,
+`-type`, `-version`) ride along for cost/ROI correlation; the job id is required for
+the others to be recorded.
+
+##### Counting a Claude Code call once (shared call id)
+
+If you run Claude Code through your proxy **and** point Claude Code's own usage
+reporting at Revenium, every call is recorded twice: Claude Code files it under an
+identifier of its own making, the proxy files it under another, and the two can
+never match. `ReveniumGuardrail` makes them match, and does so by default.
+
+The guardrail mints one identifier per proxied `/v1/messages` request, returns it to
+the client as the `request-id` and `x-revenium-transaction-id` response headers, and
+reports the same value as the call's transaction id. Claude Code copies `request-id`
+onto its own record, Revenium's duplicate check sees two records with one identifier,
+and one call becomes one record.
+
+**It is on by default.** To opt out and keep LiteLLM's own response id as the
+transaction id, with no `request-id` header added:
+
+```bash
+export REVENIUM_LITELLM_SHARED_CALL_ID=false
+```
+
+New calls go straight back to two records when you do; records already merged stay
+merged. Four things have to be true for it to work:
+
+* **LiteLLM 1.93.0 or newer.** That is the floor of the `litellm-proxy` extra, which
+  is what installs the guardrail. On an older LiteLLM the guardrail logs one warning
+  at startup and behaves exactly as it does when opted out: no header is added,
+  the provider's response id is reported, and you get two records rather than none.
+* **`mode` includes `pre_call`.** The identifier is minted in the pre-call hook, and
+  LiteLLM runs that hook only when the configured mode asks for it. A
+  `mode: ["post_call"]` proxy mints nothing, and the guardrail says so at startup
+  with one warning naming this variable. Add `pre_call` to the mode, or set the
+  variable to `false` if the proxy only meters.
+* **The Anthropic messages route.** Other routes are untouched, so the provider's own
+  `request-id` on the pass-through route is never overwritten.
+* **Both sides report to the same Revenium team.** The duplicate check is
+  team-scoped.
+
+**Point Claude Code at the proxy root, not at `/anthropic`.** Set `ANTHROPIC_BASE_URL`
+to the proxy's own base URL so Claude Code calls `<proxy>/v1/messages`:
+
+```bash
+export ANTHROPIC_BASE_URL=https://proxy.example.com
+```
+
+LiteLLM also offers an Anthropic pass-through at `<proxy>/anthropic/v1/messages`, and
+its own API reference recommends that route over `/v1/messages`. The shared identifier
+is minted only on `/v1/messages`. A proxy serving the pass-through route hands the
+provider's response straight back, so nothing is minted there, no `request-id` of ours
+is returned, and the counter described below stays silent on that route by design.
+The flag will appear to be on and the calls will keep being counted twice, with
+nothing in the proxy log to say why. If your Claude Code base URL ends in
+`/anthropic`, drop that suffix.
+
+Only the guardrail mints. A proxy still on the deprecated callback alone gets no
+identifier and keeps reporting two records, which is one more reason to migrate.
+
+One caution for a proxy running **both** the guardrail and the deprecated callback
+without `default_on: true`. That configuration meters every call twice already, and
+this flag hides the symptom rather than fixing it: both rows now carry the same
+identifier and Revenium's duplicate check keeps one. The configuration is still
+wrong. Delete the `litellm_settings.callbacks` entry.
+
+Also do not register `ReveniumGuardrail` in `litellm_settings.callbacks` as well as
+in the `guardrails` block. LiteLLM keys registered callbacks on the class name plus
+its simple attributes, and the two instances differ, so both are registered and every
+logging hook runs twice.
+
+If the flag is on and an Anthropic messages call is metered with no identifier on it,
+the guardrail counts it and logs a warning at most once a minute with the running
+total, so a mint that quietly stopped shows up in the proxy log rather than as a
+return of double counting. Your other routes never carry an identifier and are never
+counted or warned about, so a proxy that also serves chat completions or embeddings
+stays quiet.
+
+##### Migrating from the callback
+
+`revenium_middleware.litellm.proxy.middleware.MiddlewareHandler` — the
+`litellm_settings.callbacks` entry `proxy_handler_instance` — is **deprecated**. It
+meters but never enforces a budget. It keeps working in this release and emits a
+`DeprecationWarning` (and a log line) when the proxy builds it.
+
+To migrate, delete the callbacks entry and add the `guardrails` block above:
+
+```diff
+ litellm_settings:
+-  callbacks: ["revenium_middleware.litellm.proxy.middleware.proxy_handler_instance"]
++
++guardrails:
++  - guardrail_name: "revenium"
++    litellm_params:
++      guardrail: revenium_middleware.litellm.proxy.guardrail.ReveniumGuardrail
++      mode: ["pre_call", "post_call"]
++      default_on: true
 ```
 
-When using the LiteLLM proxy, pass metadata via HTTP headers (`x-revenium-*`).
-Reasoning effort travels as `x-revenium-effort` on the proxied request.
+Nothing else changes: the same headers, the same metered fields. Metered rows
+record `middleware_source: "GUARDRAIL"` instead of `"PROXY"`.
+
+Leaving both enabled would meter every call twice. As a safety net for a proxy
+mid-migration, when the guardrail is configured to run on every request
+(`default_on: true` with `post_call` among its modes) it claims metering ownership
+and the deprecated callback stops submitting rows, logging once to say so. That net
+does **not** apply to a guardrail without `default_on`, without `post_call`, or
+configured with a per-tag `Mode` (which selects hooks per request): such a guardrail
+may not run on a given request, and suppressing the callback could drop metering
+entirely. A per-tag configuration logs, at info level, that it is not claiming
+ownership. Delete the callbacks entry rather than relying on the net.
+
+##### Client API and guardrails
+
+`CustomGuardrail`'s lifecycle hooks cannot be hosted by LiteLLM's client API.
+Verified against **litellm 1.100.1**: `async_pre_call_hook`,
+`async_post_call_success_hook` and `async_post_call_failure_hook` are dispatched
+only from `litellm/proxy/utils.py` (`ProxyLogging`) and
+`litellm/proxy/common_request_processing.py`. The client path
+(`litellm_core_utils/litellm_logging.py`) dispatches only the `CustomLogger`
+logging events, so a `CustomGuardrail` added to `litellm.callbacks` without the
+proxy running would be a logger with no pre-call hook and no ability to block a
+call — the enforcement half would silently not exist.
+
+So the client integration keeps its own path, unchanged: use
+`revenium_middleware.litellm.client` as documented above. Note that the LiteLLM
+client wrapper meters but does not currently run the pre-call circuit breaker —
+enforcement in client mode is available today through the OpenAI middleware, and
+through this guardrail in proxy mode. Both the guardrail and the client wrapper
+already share their metering plumbing (`revenium_middleware._core`: field
+extraction, cache-token extraction and `submit_ai_event`), so the guardrail adds no
+second copy of it.
 
 #### LiteLLM Decorators
 
@@ -1142,6 +1488,7 @@ Enhanced observability fields for tracking AI operations across environments, re
 | `transaction_name` | `REVENIUM_TRANSACTION_NAME` | Human-friendly operation name | Label operations (e.g., `"Generate Response"`, `"Analyze Sentiment"`) |
 | `retry_number` | `REVENIUM_RETRY_NUMBER` | Retry attempt number (0 = first attempt) | Track retry attempts for failed operations |
 | `ticket_id` | `REVENIUM_TICKET_ID` | External ticket or issue ID (e.g., Jira, Linear) (max 256 chars) | Attribute AI costs to individual tickets or issues |
+| `agent_version` | _(none — per call only)_ | Version of the AI agent that produced the call (max 64 chars) | Compare cost across agent releases; not `agentic_job_version`, which versions the job definition |
 | `skill_name` | `REVENIUM_SKILL_NAME` | Name of the agent skill that produced the call (max 256 chars) | Attribute AI costs to the skill that generated them |
 | `skill_source` | `REVENIUM_SKILL_SOURCE` | Where the skill was loaded from — accepted values: `bundled`, `projectSettings`, `userSettings`, `plugin` (case-sensitive) | Classify skill origin in the shared skill catalog |
 | `skill_kind` | `REVENIUM_SKILL_KIND` | Kind of skill invoked — accepted value: `workflow` (omit otherwise) | Distinguish workflow skills in reporting |
@@ -1176,7 +1523,8 @@ response = client.chat.completions.create(
         "trace_name": "Support Chat Session",
         "transaction_name": "Generate Response",
         "parent_transaction_id": "parent-txn-123",
-        "ticket_id": "JIRA-123"
+        "ticket_id": "JIRA-123",
+        "agent_version": "1.4.2"
     }
 )
 ```
@@ -1520,6 +1868,29 @@ Set `REVENIUM_CB_FAIL_MODE=closed` to refuse calls until at least one rule fetch
 
 Rules with `shadowMode: true` are observe-and-log: they are skipped by `check_enforcement`. Use shadow mode on the server side to audit a rule before flipping it to enforce.
 
+### Inspecting a Rule and Its Roster
+
+Two read-only calls answer "why was this caller blocked, and who else does this rule cover?" without going anywhere near the pre-call path. Both talk to the server directly, neither is cached, and neither reads or writes the cache `check_enforcement` evaluates — so what they report is what the server holds right now.
+
+```python
+from revenium_middleware._core import (
+    fetch_enforcement_rule,
+    fetch_enforcement_rule_roster,
+)
+
+rule = fetch_enforcement_rule("mN3xpQz")          # one rule, or None
+roster = fetch_enforcement_rule_roster("mN3xpQz")  # who it measures, or None
+
+if roster:
+    print(f"{roster['blockedCount']} over the cap, {roster['warnedCount']} warned")
+    for row in roster["rows"]:
+        print(f"{row['label']}: ${row['spend']} / ${row['limit']} ({row['band']})")
+```
+
+`fetch_enforcement_rule_roster` takes `page`, `size`, `search` and `band` (`BLOCKED`, `WARNED`, `UNDER`, `ALL`); the server does the filtering, sorting, banding and paging, and the three band counts always describe the whole roster rather than the page you asked for. Both calls return `None` rather than raising when the team has no such compiled rule, the rule has no reading yet, or the enforcement API cannot be reached — the same fail-open posture as the rest of the circuit breaker. An empty `rule_id` raises `ValueError`.
+
+The background poller is unaffected: it keeps reading the **whole team's** rules every `REVENIUM_CB_POLL_INTERVAL_SECONDS`. That is deliberate. The server computes the department-budget maps team-wide and attaches them to the team-wide read, so a poll narrowed to a single rule would stop receiving them and department budgets would quietly stop blocking anyone. Narrowing is an explicit, opt-in inspection call and never the refresh.
+
 ### End-to-End Example
 
 See [`examples/openai/openai_blocking_demo.py`](examples/openai/openai_blocking_demo.py) for a runnable end-to-end demo using a seeded budget rule.
@@ -1593,9 +1964,10 @@ print(get_buffer_stats())
 | `REVENIUM_AGENTIC_JOB_NAME` | - | Human-readable agentic job name |
 | `REVENIUM_AGENTIC_JOB_TYPE` | - | Agentic job type category |
 | `REVENIUM_AGENTIC_JOB_VERSION` | - | Agentic job version |
-| `REVENIUM_OUTCOME_API_KEY` | - | Write-scope key (`rev_sk_`) for the agentic outcomes API (report/amend/history); falls back to `REVENIUM_METERING_API_KEY` |
+| `REVENIUM_WRITE_API_KEY` | - | Primary write-scope key (`rev_sk_`) for the agentic outcomes API (report/amend/history); falls back to `REVENIUM_OUTCOME_API_KEY` (deprecated), then `REVENIUM_METERING_API_KEY` |
+| `REVENIUM_OUTCOME_API_KEY` | - | Deprecated fallback name for the write-scope key; used only when `REVENIUM_WRITE_API_KEY` is unset |
 | `REVENIUM_PROFITSTREAM_BASE_URL` | `https://api.revenium.io` | Agentic outcomes API base URL |
-| `REVENIUM_BEDROCK_DISABLE` | - | Set to `1` to disable Bedrock auto-detection |
+| `REVENIUM_BEDROCK_DISABLE` | - | Set to `1` to disable Bedrock auto-detection; Foundry detection is unaffected |
 | `REVENIUM_BUFFER_MAX_SIZE` | `1000` | Store-and-forward buffer capacity (oldest events evicted when full) |
 | `REVENIUM_BUFFER_FLUSH_INTERVAL` | `30` | Seconds between automatic replay attempts for buffered events |
 
@@ -1640,7 +2012,7 @@ Per-call `usage_metadata` values take precedence over the `REVENIUM_AGENTIC_JOB_
 
 **Debug mode:** Set `REVENIUM_LOG_LEVEL=DEBUG` to see detailed provider detection, routing decisions, and metering payloads.
 
-**Force direct Anthropic API:** Set `REVENIUM_BEDROCK_DISABLE=1` to disable Bedrock auto-detection.
+**Force direct Anthropic API (instead of Bedrock):** Set `REVENIUM_BEDROCK_DISABLE=1` to disable Bedrock auto-detection. Foundry detection is unaffected - a Foundry client is still labelled `Foundry`.
 
 **Check initialization status (Anthropic):** Use `revenium_middleware.anthropic.is_initialized()` to verify setup.