revenium-python-sdk 0.1.4__tar.gz → 0.1.5__tar.gz

{revenium_python_sdk-0.1.4/revenium_python_sdk.egg-info → revenium_python_sdk-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: revenium-python-sdk
-Version: 0.1.4
+Version: 0.1.5
 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
@@ -194,7 +194,7 @@ import revenium_middleware_openai  # Auto-initializes on import
 
 client = openai.OpenAI()
 response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Hello!"}]
 )
 print(response.choices[0].message.content)
@@ -203,6 +203,30 @@ print(response.choices[0].message.content)
 
 ---
 
+## Agentic Outcomes (Outcome-Based Metering)
+
+Emit per-agent terminal outcomes (`CONVERTED`, `DEFLECTED`, `ESCALATED`) alongside completion and tool-event records, so dashboards show business value next to AI cost.
+
+```python
+from revenium_middleware.agentic_outcomes import AgenticOutcomeClient, AgenticOutcomeSettings
+
+settings = AgenticOutcomeSettings(api_key="rev_sk_...")
+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.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.
+
+See [`examples/agentic_outcomes/`](examples/agentic_outcomes/) for runnable demos (sales / coding / support) with configurable failure rates and outcome distributions.
+
+**API reference:** [docs.revenium.io](https://docs.revenium.io) · per-endpoint reference at [revenium.readme.io/reference/meter_ai_completion](https://revenium.readme.io/reference/meter_ai_completion).
+
+---
+
 ## Provider Usage Guides
 
 ### OpenAI
@@ -220,7 +244,7 @@ client = openai.OpenAI()
 
 # Basic chat completion
 response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Hello!"}],
     usage_metadata={
         "organizationName": "AcmeCorp",
@@ -232,7 +256,7 @@ response = client.chat.completions.create(
 
 # Streaming
 stream = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Tell me a story"}],
     stream=True
 )
@@ -292,7 +316,7 @@ client = anthropic.Anthropic()
 
 # Basic message
 message = client.messages.create(
-    model="claude-3-haiku-20240307",
+    model="claude-opus-4-7",
     max_tokens=100,
     messages=[{"role": "user", "content": "Hello!"}],
     usage_metadata={
@@ -304,7 +328,7 @@ message = client.messages.create(
 
 # Streaming
 with client.messages.stream(
-    model="claude-3-haiku-20240307",
+    model="claude-opus-4-7",
     max_tokens=200,
     messages=[{"role": "user", "content": "Tell me a story"}],
     usage_metadata={"task_type": "creative"}
@@ -330,7 +354,7 @@ client = anthropic.AnthropicBedrock(
 )
 
 message = client.messages.create(
-    model="anthropic.claude-3-haiku-20240307-v1:0",
+    model="claude-opus-4-7",
     max_tokens=100,
     messages=[{"role": "user", "content": "Hello from Bedrock!"}]
 )
@@ -354,6 +378,11 @@ message = client.messages.create(
 
 | Anthropic Model | Bedrock Model ID |
 |----------------|------------------|
+| `claude-opus-4-7` | `anthropic.claude-opus-4-7` |
+| `us.claude-opus-4-7` | `us.anthropic.claude-opus-4-7` |
+| `eu.claude-opus-4-7` | `eu.anthropic.claude-opus-4-7` |
+| `au.claude-opus-4-7` | `au.anthropic.claude-opus-4-7` |
+| `global.claude-opus-4-7` | `global.anthropic.claude-opus-4-7` |
 | `claude-3-opus-20240229` | `anthropic.claude-3-opus-20240229-v1:0` |
 | `claude-3-sonnet-20240229` | `anthropic.claude-3-sonnet-20240229-v1:0` |
 | `claude-3-haiku-20240307` | `us.anthropic.claude-3-5-haiku-20241022-v1:0` |
@@ -518,7 +547,7 @@ litellm.api_base = os.getenv("LITELLM_PROXY_URL")
 litellm.api_key = os.getenv("LITELLM_API_KEY")
 
 response = litellm.completion(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Hello!"}],
     usage_metadata={
         "organizationName": "AcmeCorp",
@@ -676,7 +705,7 @@ handler = ReveniumCallbackHandler(
     agent_name="support_agent"
 )
 
-llm = ChatOpenAI(model="gpt-4", callbacks=[handler])
+llm = ChatOpenAI(model="gpt-5.5", callbacks=[handler])
 response = llm.invoke("Hello!")
 ```
 
@@ -715,7 +744,7 @@ result = agent.invoke(
 from revenium_middleware_langchain import AsyncReveniumCallbackHandler
 
 handler = AsyncReveniumCallbackHandler(trace_id="async-session")
-llm = ChatOpenAI(model="gpt-4", callbacks=[handler])
+llm = ChatOpenAI(model="gpt-5.5", callbacks=[handler])
 response = await llm.ainvoke("Hello!")
 ```
 
@@ -761,7 +790,7 @@ Add business context to any API call by passing a `usage_metadata` dictionary. A
 
 ```python
 response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Hello!"}],
     usage_metadata={
         "trace_id": "conv-28a7e9d4",
@@ -824,7 +853,7 @@ REVENIUM_TRACE_TYPE=customer-support
 
 ```python
 response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Hello!"}],
     usage_metadata={
         "environment": "production",
@@ -848,7 +877,7 @@ workflow_id = str(uuid.uuid4())
 
 # Step 1: Parent operation
 parent_response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Analyze this document"}],
     usage_metadata={
         "trace_id": "analysis-session-456",
@@ -859,7 +888,7 @@ parent_response = client.chat.completions.create(
 
 # Step 2: Child operation linked to parent
 child_response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Summarize findings"}],
     usage_metadata={
         "trace_id": "analysis-session-456",
@@ -890,7 +919,7 @@ from revenium_middleware import revenium_metadata
 def handle_customer_query(question: str) -> str:
     # All API calls automatically include the decorator metadata
     response = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": question}]
     )
     return response.choices[0].message.content
@@ -929,13 +958,13 @@ def outer_function():
 def mixed_metadata():
     # Uses decorator metadata
     response1 = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": "Hello"}]
     )
 
     # API-level metadata overrides decorator's task_type
     response2 = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": "Hello"}],
         usage_metadata={
             "task_type": "special-override",  # Overrides decorator
@@ -964,7 +993,7 @@ from revenium_middleware import revenium_meter, revenium_metadata
 def premium_feature(prompt: str) -> str:
     # This WILL be metered (decorated with @revenium_meter)
     response = client.chat.completions.create(
-        model="gpt-4o",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": prompt}]
     )
     return response.choices[0].message.content
@@ -972,7 +1001,7 @@ def premium_feature(prompt: str) -> str:
 def free_feature(prompt: str) -> str:
     # This will NOT be metered (no @revenium_meter decorator)
     response = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": prompt}]
     )
     return response.choices[0].message.content
@@ -1058,7 +1087,7 @@ from openai import OpenAI
 
 client = OpenAI()
 response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[
         {"role": "system", "content": "You are a helpful assistant."},
         {"role": "user", "content": "What is the capital of France?"}
@@ -1105,7 +1134,7 @@ export REVENIUM_TEAM_ID=your-team-id-here
 ============================================================
 REVENIUM USAGE SUMMARY
 ============================================================
-Model: gpt-4o-mini
+Model: gpt-5.5
 Provider: OPENAI
 Duration: 1.23s
 
@@ -1123,7 +1152,7 @@ Trace ID: abc-123
 ### JSON Format
 
 ```json
-{"model":"gpt-4o-mini","provider":"OPENAI","durationSeconds":1.23,"inputTokenCount":150,"outputTokenCount":250,"totalTokenCount":400,"cost":0.000045,"costStatus":"available","traceId":"abc-123"}
+{"model":"gpt-5.5","provider":"OPENAI","durationSeconds":1.23,"inputTokenCount":150,"outputTokenCount":250,"totalTokenCount":400,"cost":0.000045,"costStatus":"available","traceId":"abc-123"}
 ```
 
 ### Cost Status
@@ -1138,7 +1167,9 @@ Trace ID: abc-123
 
 ## Cost Controls / Enforcement
 
-Block outbound provider requests client-side when a Revenium cost-limit rule trips. When the circuit breaker is enabled, the middleware polls enforcement rules from the Revenium API in a background daemon thread and raises `ReveniumCostLimitExceeded` **before** the upstream call, preventing spend beyond the configured limit.
+Block outbound provider requests client-side when a Revenium cost control trips. When the circuit breaker is enabled, the middleware polls compiled enforcement rules from the Revenium API in a background daemon thread and raises `BudgetExceededError` **before** the upstream call, preventing spend beyond the configured limit.
+
+> **Terminology note:** The customer-facing entity is called a **cost control**, served by the backend at `/v2/api/ai/cost-controls`. This SDK polls a separate compiled-rules feed at `/v2/api/ai/enforcement-rules/{teamId}` and is unaffected by changes to the CRUD path — no SDK upgrade is required.
 
 Currently wired for the OpenAI provider (other providers land via per-provider follow-on tickets).
 
@@ -1164,7 +1195,7 @@ REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream  # optional
 | `REVENIUM_TEAM_ID` | — | Hashed team ID. Path component on rule fetches; required when the breaker is enabled. |
 | `REVENIUM_ENFORCEMENT_BASE_URL` | origin of `REVENIUM_METERING_BASE_URL` | Base URL for the enforcement API. Set when the enforcement API lives behind a context-path. |
 | `REVENIUM_CB_POLL_INTERVAL_SECONDS` | `60` | Background poll interval for rule refreshes. |
-| `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `ReveniumCostLimitExceeded` until rules are loaded. |
+| `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `BudgetExceededError` until rules are loaded. |
 | `REVENIUM_CACHE_DIR` | — | When set, the rule cache is mirrored to `<dir>/revenium_enforcement_rules.json` so a restarted process doesn't fail-closed on the very first call. |
 
 ### Public API
@@ -1188,7 +1219,7 @@ The pre-call check fires before every chat / embeddings / responses call. When t
 ### Exception Contract
 
 ```python
-from revenium_middleware.openai import ReveniumCostLimitExceeded
+from revenium_middleware.openai import BudgetExceededError
 ```
 
 When a tripped rule matches the current request, the middleware raises before the OpenAI call is made. All structured fields are populated when the server provides them:
@@ -1202,20 +1233,20 @@ When a tripped rule matches the current request, the middleware raises before th
 | `resets_at` | `str \| None` | ISO-8601 timestamp the rule next resets |
 | `rule_id` | `str \| int \| None` | Server-side rule identifier |
 
-`ReveniumCostLimitExceeded` does **not** inherit from `ReveniumMiddlewareError`, so the OpenAI middleware's `handle_exception_safely` decorator never swallows it — it always reaches your `except` block.
+`BudgetExceededError` does **not** inherit from `ReveniumMiddlewareError`, so the OpenAI middleware's `handle_exception_safely` decorator never swallows it — it always reaches your `except` block.
 
 ```python
-from revenium_middleware.openai import ReveniumCostLimitExceeded
+from revenium_middleware.openai import BudgetExceededError
 import openai
 
 client = openai.OpenAI()
 
 try:
     response = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": "Summarize the meeting notes"}],
     )
-except ReveniumCostLimitExceeded as exc:
+except BudgetExceededError as exc:
     print(f"Cost limit reached: {exc.message}")
     print(f"Rule {exc.rule_name}: {exc.current_value} / {exc.threshold}; resets {exc.resets_at}")
 ```

{revenium_python_sdk-0.1.4 → revenium_python_sdk-0.1.5}/README.md

@@ -106,7 +106,7 @@ import revenium_middleware_openai  # Auto-initializes on import
 
 client = openai.OpenAI()
 response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Hello!"}]
 )
 print(response.choices[0].message.content)
@@ -115,6 +115,30 @@ print(response.choices[0].message.content)
 
 ---
 
+## Agentic Outcomes (Outcome-Based Metering)
+
+Emit per-agent terminal outcomes (`CONVERTED`, `DEFLECTED`, `ESCALATED`) alongside completion and tool-event records, so dashboards show business value next to AI cost.
+
+```python
+from revenium_middleware.agentic_outcomes import AgenticOutcomeClient, AgenticOutcomeSettings
+
+settings = AgenticOutcomeSettings(api_key="rev_sk_...")
+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.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.
+
+See [`examples/agentic_outcomes/`](examples/agentic_outcomes/) for runnable demos (sales / coding / support) with configurable failure rates and outcome distributions.
+
+**API reference:** [docs.revenium.io](https://docs.revenium.io) · per-endpoint reference at [revenium.readme.io/reference/meter_ai_completion](https://revenium.readme.io/reference/meter_ai_completion).
+
+---
+
 ## Provider Usage Guides
 
 ### OpenAI
@@ -132,7 +156,7 @@ client = openai.OpenAI()
 
 # Basic chat completion
 response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Hello!"}],
     usage_metadata={
         "organizationName": "AcmeCorp",
@@ -144,7 +168,7 @@ response = client.chat.completions.create(
 
 # Streaming
 stream = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Tell me a story"}],
     stream=True
 )
@@ -204,7 +228,7 @@ client = anthropic.Anthropic()
 
 # Basic message
 message = client.messages.create(
-    model="claude-3-haiku-20240307",
+    model="claude-opus-4-7",
     max_tokens=100,
     messages=[{"role": "user", "content": "Hello!"}],
     usage_metadata={
@@ -216,7 +240,7 @@ message = client.messages.create(
 
 # Streaming
 with client.messages.stream(
-    model="claude-3-haiku-20240307",
+    model="claude-opus-4-7",
     max_tokens=200,
     messages=[{"role": "user", "content": "Tell me a story"}],
     usage_metadata={"task_type": "creative"}
@@ -242,7 +266,7 @@ client = anthropic.AnthropicBedrock(
 )
 
 message = client.messages.create(
-    model="anthropic.claude-3-haiku-20240307-v1:0",
+    model="claude-opus-4-7",
     max_tokens=100,
     messages=[{"role": "user", "content": "Hello from Bedrock!"}]
 )
@@ -266,6 +290,11 @@ message = client.messages.create(
 
 | Anthropic Model | Bedrock Model ID |
 |----------------|------------------|
+| `claude-opus-4-7` | `anthropic.claude-opus-4-7` |
+| `us.claude-opus-4-7` | `us.anthropic.claude-opus-4-7` |
+| `eu.claude-opus-4-7` | `eu.anthropic.claude-opus-4-7` |
+| `au.claude-opus-4-7` | `au.anthropic.claude-opus-4-7` |
+| `global.claude-opus-4-7` | `global.anthropic.claude-opus-4-7` |
 | `claude-3-opus-20240229` | `anthropic.claude-3-opus-20240229-v1:0` |
 | `claude-3-sonnet-20240229` | `anthropic.claude-3-sonnet-20240229-v1:0` |
 | `claude-3-haiku-20240307` | `us.anthropic.claude-3-5-haiku-20241022-v1:0` |
@@ -430,7 +459,7 @@ litellm.api_base = os.getenv("LITELLM_PROXY_URL")
 litellm.api_key = os.getenv("LITELLM_API_KEY")
 
 response = litellm.completion(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Hello!"}],
     usage_metadata={
         "organizationName": "AcmeCorp",
@@ -588,7 +617,7 @@ handler = ReveniumCallbackHandler(
     agent_name="support_agent"
 )
 
-llm = ChatOpenAI(model="gpt-4", callbacks=[handler])
+llm = ChatOpenAI(model="gpt-5.5", callbacks=[handler])
 response = llm.invoke("Hello!")
 ```
 
@@ -627,7 +656,7 @@ result = agent.invoke(
 from revenium_middleware_langchain import AsyncReveniumCallbackHandler
 
 handler = AsyncReveniumCallbackHandler(trace_id="async-session")
-llm = ChatOpenAI(model="gpt-4", callbacks=[handler])
+llm = ChatOpenAI(model="gpt-5.5", callbacks=[handler])
 response = await llm.ainvoke("Hello!")
 ```
 
@@ -673,7 +702,7 @@ Add business context to any API call by passing a `usage_metadata` dictionary. A
 
 ```python
 response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Hello!"}],
     usage_metadata={
         "trace_id": "conv-28a7e9d4",
@@ -736,7 +765,7 @@ REVENIUM_TRACE_TYPE=customer-support
 
 ```python
 response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Hello!"}],
     usage_metadata={
         "environment": "production",
@@ -760,7 +789,7 @@ workflow_id = str(uuid.uuid4())
 
 # Step 1: Parent operation
 parent_response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Analyze this document"}],
     usage_metadata={
         "trace_id": "analysis-session-456",
@@ -771,7 +800,7 @@ parent_response = client.chat.completions.create(
 
 # Step 2: Child operation linked to parent
 child_response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[{"role": "user", "content": "Summarize findings"}],
     usage_metadata={
         "trace_id": "analysis-session-456",
@@ -802,7 +831,7 @@ from revenium_middleware import revenium_metadata
 def handle_customer_query(question: str) -> str:
     # All API calls automatically include the decorator metadata
     response = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": question}]
     )
     return response.choices[0].message.content
@@ -841,13 +870,13 @@ def outer_function():
 def mixed_metadata():
     # Uses decorator metadata
     response1 = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": "Hello"}]
     )
 
     # API-level metadata overrides decorator's task_type
     response2 = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": "Hello"}],
         usage_metadata={
             "task_type": "special-override",  # Overrides decorator
@@ -876,7 +905,7 @@ from revenium_middleware import revenium_meter, revenium_metadata
 def premium_feature(prompt: str) -> str:
     # This WILL be metered (decorated with @revenium_meter)
     response = client.chat.completions.create(
-        model="gpt-4o",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": prompt}]
     )
     return response.choices[0].message.content
@@ -884,7 +913,7 @@ def premium_feature(prompt: str) -> str:
 def free_feature(prompt: str) -> str:
     # This will NOT be metered (no @revenium_meter decorator)
     response = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": prompt}]
     )
     return response.choices[0].message.content
@@ -970,7 +999,7 @@ from openai import OpenAI
 
 client = OpenAI()
 response = client.chat.completions.create(
-    model="gpt-4o-mini",
+    model="gpt-5.5",
     messages=[
         {"role": "system", "content": "You are a helpful assistant."},
         {"role": "user", "content": "What is the capital of France?"}
@@ -1017,7 +1046,7 @@ export REVENIUM_TEAM_ID=your-team-id-here
 ============================================================
 REVENIUM USAGE SUMMARY
 ============================================================
-Model: gpt-4o-mini
+Model: gpt-5.5
 Provider: OPENAI
 Duration: 1.23s
 
@@ -1035,7 +1064,7 @@ Trace ID: abc-123
 ### JSON Format
 
 ```json
-{"model":"gpt-4o-mini","provider":"OPENAI","durationSeconds":1.23,"inputTokenCount":150,"outputTokenCount":250,"totalTokenCount":400,"cost":0.000045,"costStatus":"available","traceId":"abc-123"}
+{"model":"gpt-5.5","provider":"OPENAI","durationSeconds":1.23,"inputTokenCount":150,"outputTokenCount":250,"totalTokenCount":400,"cost":0.000045,"costStatus":"available","traceId":"abc-123"}
 ```
 
 ### Cost Status
@@ -1050,7 +1079,9 @@ Trace ID: abc-123
 
 ## Cost Controls / Enforcement
 
-Block outbound provider requests client-side when a Revenium cost-limit rule trips. When the circuit breaker is enabled, the middleware polls enforcement rules from the Revenium API in a background daemon thread and raises `ReveniumCostLimitExceeded` **before** the upstream call, preventing spend beyond the configured limit.
+Block outbound provider requests client-side when a Revenium cost control trips. When the circuit breaker is enabled, the middleware polls compiled enforcement rules from the Revenium API in a background daemon thread and raises `BudgetExceededError` **before** the upstream call, preventing spend beyond the configured limit.
+
+> **Terminology note:** The customer-facing entity is called a **cost control**, served by the backend at `/v2/api/ai/cost-controls`. This SDK polls a separate compiled-rules feed at `/v2/api/ai/enforcement-rules/{teamId}` and is unaffected by changes to the CRUD path — no SDK upgrade is required.
 
 Currently wired for the OpenAI provider (other providers land via per-provider follow-on tickets).
 
@@ -1076,7 +1107,7 @@ REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream  # optional
 | `REVENIUM_TEAM_ID` | — | Hashed team ID. Path component on rule fetches; required when the breaker is enabled. |
 | `REVENIUM_ENFORCEMENT_BASE_URL` | origin of `REVENIUM_METERING_BASE_URL` | Base URL for the enforcement API. Set when the enforcement API lives behind a context-path. |
 | `REVENIUM_CB_POLL_INTERVAL_SECONDS` | `60` | Background poll interval for rule refreshes. |
-| `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `ReveniumCostLimitExceeded` until rules are loaded. |
+| `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `BudgetExceededError` until rules are loaded. |
 | `REVENIUM_CACHE_DIR` | — | When set, the rule cache is mirrored to `<dir>/revenium_enforcement_rules.json` so a restarted process doesn't fail-closed on the very first call. |
 
 ### Public API
@@ -1100,7 +1131,7 @@ The pre-call check fires before every chat / embeddings / responses call. When t
 ### Exception Contract
 
 ```python
-from revenium_middleware.openai import ReveniumCostLimitExceeded
+from revenium_middleware.openai import BudgetExceededError
 ```
 
 When a tripped rule matches the current request, the middleware raises before the OpenAI call is made. All structured fields are populated when the server provides them:
@@ -1114,20 +1145,20 @@ When a tripped rule matches the current request, the middleware raises before th
 | `resets_at` | `str \| None` | ISO-8601 timestamp the rule next resets |
 | `rule_id` | `str \| int \| None` | Server-side rule identifier |
 
-`ReveniumCostLimitExceeded` does **not** inherit from `ReveniumMiddlewareError`, so the OpenAI middleware's `handle_exception_safely` decorator never swallows it — it always reaches your `except` block.
+`BudgetExceededError` does **not** inherit from `ReveniumMiddlewareError`, so the OpenAI middleware's `handle_exception_safely` decorator never swallows it — it always reaches your `except` block.
 
 ```python
-from revenium_middleware.openai import ReveniumCostLimitExceeded
+from revenium_middleware.openai import BudgetExceededError
 import openai
 
 client = openai.OpenAI()
 
 try:
     response = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.5",
         messages=[{"role": "user", "content": "Summarize the meeting notes"}],
     )
-except ReveniumCostLimitExceeded as exc:
+except BudgetExceededError as exc:
     print(f"Cost limit reached: {exc.message}")
     print(f"Rule {exc.rule_name}: {exc.current_value} / {exc.threshold}; resets {exc.resets_at}")
 ```

{revenium_python_sdk-0.1.4 → revenium_python_sdk-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "revenium-python-sdk"
-version = "0.1.4"
+version = "0.1.5"
 description = "The official Revenium Python SDK — unified AI metering middleware for OpenAI, Anthropic, Google, Ollama, LiteLLM, Perplexity, and fal.ai."
 readme = "README.md"
 requires-python = ">=3.8"

{revenium_python_sdk-0.1.4 → revenium_python_sdk-0.1.5}/revenium_middleware/__init__.py

@@ -157,6 +157,9 @@ from ._core import (  # noqa: E402
 # Re-export tool metering utilities from revenium_metering (v6.8.2+)
 from revenium_metering import meter_tool, report_tool_call, configure  # noqa: E402
 
+# Agentic-outcome client (used by examples/agentic_outcomes/ pack)
+from .agentic_outcomes import AgenticOutcomeClient, AgenticOutcomeSettings  # noqa: E402
+
 __all__ = [
     # Metering exports
     "client",
@@ -181,4 +184,7 @@ __all__ = [
     "meter_tool",
     "report_tool_call",
     "configure",
+    # Agentic-outcome exports
+    "AgenticOutcomeClient",
+    "AgenticOutcomeSettings",
 ]

{revenium_python_sdk-0.1.4 → revenium_python_sdk-0.1.5}/revenium_middleware/_core/__init__.py

@@ -6,7 +6,7 @@ provider-specific middleware implementations.
 """
 
 from .metering import run_async_in_thread, shutdown_event, client
-from .exceptions import ReveniumCostLimitExceeded
+from .exceptions import BudgetExceededError
 from .enforcement import check_enforcement, is_circuit_breaker_enabled, stop_polling
 from .context import (
     is_inside_decorated_function,
@@ -49,7 +49,7 @@ __all__ = [
     "run_async_in_thread",
     "shutdown_event",
     # Enforcement / circuit breaker
-    "ReveniumCostLimitExceeded",
+    "BudgetExceededError",
     "check_enforcement",
     "is_circuit_breaker_enabled",
     "stop_polling",

{revenium_python_sdk-0.1.4 → revenium_python_sdk-0.1.5}/revenium_middleware/_core/enforcement.py

@@ -3,7 +3,7 @@ Enforcement engine for the Revenium circuit breaker.
 
 Polls cost-limit rules from the Revenium API in a daemon thread and caches
 them in memory. ``check_enforcement(...)`` is a pre-call hook that raises
-``ReveniumCostLimitExceeded`` when a tripped rule matches the current
+``BudgetExceededError`` when a tripped rule matches the current
 request, blocking the outbound provider call before any spend occurs.
 
 Opt-in via ``REVENIUM_CIRCUIT_BREAKER_ENABLED``. Disabled by default so the
@@ -21,7 +21,7 @@ from urllib.parse import quote, urlparse
 import httpx
 
 from .config import Config
-from .exceptions import ReveniumCostLimitExceeded
+from .exceptions import BudgetExceededError
 
 logger = logging.getLogger("revenium_middleware.extension")
 
@@ -276,7 +276,7 @@ def check_enforcement(usage_metadata: Optional[dict] = None) -> None:
     is disabled or no rules are tripped.
 
     Raises:
-        ReveniumCostLimitExceeded: when a cost-limit rule blocks the call.
+        BudgetExceededError: when a cost-limit rule blocks the call.
             All structured fields (``rule_name``, ``current_value``,
             ``threshold``, ``resets_at``, ``rule_id``) are populated when the
             server provides them.
@@ -295,7 +295,7 @@ def check_enforcement(usage_metadata: Optional[dict] = None) -> None:
     # valid initialized state and must pass through. Use the snapshot taken
     # under _cache_lock so the decision can't see a torn write.
     if _fail_mode_is_closed() and not initialized:
-        raise ReveniumCostLimitExceeded(
+        raise BudgetExceededError(
             "Request blocked: enforcement cache is uninitialized and "
             "REVENIUM_CB_FAIL_MODE=closed."
         )
@@ -319,7 +319,7 @@ def check_enforcement(usage_metadata: Optional[dict] = None) -> None:
             continue
 
         rule_name = rule.get("name", "cost limit")
-        raise ReveniumCostLimitExceeded(
+        raise BudgetExceededError(
             message=f"Request blocked by Revenium enforcement rule: {rule_name}",
             rule_name=rule_name,
             current_value=_coerce_float(rule.get("currentValue")),