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

{revenium_python_sdk-0.1.3/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.3
+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
@@ -1136,6 +1165,108 @@ Trace ID: abc-123
 
 ---
 
+## Cost Controls / Enforcement
+
+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).
+
+### Enable
+
+```bash
+pip install 'revenium-python-sdk[openai]'
+```
+
+```env
+REVENIUM_CIRCUIT_BREAKER_ENABLED=true
+REVENIUM_METERING_API_KEY=hak_your_key_here
+REVENIUM_TEAM_ID=your_hashed_team_id
+REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream  # optional
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `REVENIUM_CIRCUIT_BREAKER_ENABLED` | `false` | Master switch. `true` / `1` / `yes` / `on` to enable. |
+| `REVENIUM_BYPASS` | `false` | When `true`, every `check_enforcement` call short-circuits to a no-op. Useful for incident response. |
+| `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 `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
+
+Enforcement auto-initializes when the OpenAI middleware loads:
+
+```python
+import revenium_middleware.openai  # auto-instruments openai
+import openai
+
+client = openai.OpenAI()
+```
+
+The pre-call check fires before every chat / embeddings / responses call. When the circuit breaker is disabled, it is a no-op. When enabled:
+
+1. A daemon thread (`revenium-enforcement-poll`) starts on first use.
+2. It polls `GET {REVENIUM_ENFORCEMENT_BASE_URL}/v2/api/ai/enforcement-rules/{REVENIUM_TEAM_ID}` every `REVENIUM_CB_POLL_INTERVAL_SECONDS` with the `x-api-key` header.
+3. Rules are cached in-process (120 s TTL, refresh-on-stale with thundering-herd guard).
+4. `204 No Content` is treated as "no rules configured" — the cache is cleared.
+
+### Exception Contract
+
+```python
+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:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `message` | `str` | Human-readable reason, e.g. `"Request blocked by Revenium enforcement rule: monthly-gpt4-cap"` |
+| `rule_name` | `str \| None` | Server-side rule name |
+| `current_value` | `float \| None` | Current metric value at the time of the block |
+| `threshold` | `float \| None` | Configured limit |
+| `resets_at` | `str \| None` | ISO-8601 timestamp the rule next resets |
+| `rule_id` | `str \| int \| None` | Server-side rule identifier |
+
+`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 BudgetExceededError
+import openai
+
+client = openai.OpenAI()
+
+try:
+    response = client.chat.completions.create(
+        model="gpt-5.5",
+        messages=[{"role": "user", "content": "Summarize the meeting notes"}],
+    )
+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}")
+```
+
+### Fail-Open vs Fail-Closed
+
+By default (`REVENIUM_CB_FAIL_MODE=open`) enforcement failures never propagate to user code. If the rule fetch errors (network, 5xx, auth), the previous in-memory cache is preserved and a debug log line is emitted. If there is no cache yet, enforcement behaves as if no rules are configured and the request continues.
+
+Set `REVENIUM_CB_FAIL_MODE=closed` to refuse calls until at least one rule fetch (or `REVENIUM_CACHE_DIR` snapshot) succeeds. Pair with `REVENIUM_CACHE_DIR` so a process restart loads the last-known rules rather than blocking every call until the first poll completes.
+
+### Shadow Mode
+
+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.
+
+### 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.
+
+---
+
 ## Configuration Reference
 
 ### Required Environment Variables
@@ -1238,6 +1369,12 @@ Available log levels:
 
 For detailed documentation, visit [docs.revenium.io](https://docs.revenium.io)
 
+### Server-Side Cost Controls
+
+Cost controls (spend limits, throttling, alerts) are managed server-side in Revenium, not in this SDK. The SDK reports usage; Revenium evaluates it against your configured cost controls.
+
+The cost-controls API endpoint is `/v2/api/ai/cost-controls`. This Python SDK does not call the endpoint directly — no SDK changes are required to use cost controls. If you manage cost controls via the Revenium API, HTTP client, or `curl`, see [docs.revenium.io](https://docs.revenium.io) for the current API reference.
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md)