revenium-python-sdk 0.2.0__tar.gz → 0.4.0__tar.gz

{revenium_python_sdk-0.2.0 → revenium_python_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: revenium-python-sdk
-Version: 0.2.0
+Version: 0.4.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
@@ -195,7 +195,7 @@ from dotenv import load_dotenv
 load_dotenv()
 
 import openai
-import revenium_middleware_openai  # Auto-initializes on import
+import revenium_middleware.openai  # Auto-initializes on import
 
 client = openai.OpenAI()
 response = client.chat.completions.create(
@@ -212,6 +212,70 @@ print(response.choices[0].message.content)
 
 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`.
+
+### JobContext
+
+`JobContext` is the recommended high-level API: every AI call made inside the block is automatically metered against the job (all provider middlewares pick the job fields up from context), and the job's business outcome is reported when the work is done.
+
+```python
+from revenium_middleware import JobContext
+
+with JobContext("loan-app-12345", type="loan_processing", version="2.1") as job:
+    response = client.chat.completions.create(...)  # metered against the job automatically
+    job.report_outcome(
+        execution_status="SUCCESS",  # SUCCESS | FAILED | CANCELLED
+        outcome_type="CONVERTED",
+        outcome_value=500.0,
+        outcome_currency="USD",
+    )
+```
+
+- **Async:** `async with JobContext(...) as job:` works identically.
+- **Auto-FAILED:** if an unhandled exception escapes the block before an outcome was reported, the context automatically reports `execution_status="FAILED"` (error message and class in metadata) and always re-raises the original exception.
+- **Blocking:** outcome calls are synchronous HTTP requests with retries; tune how long they may block with the `retry_attempts`, `retry_initial_seconds`, and `retry_max_seconds` arguments, accepted by the `JobContext` constructor, `JobContext.attach()`, `get_outcome_history()`, and the CrewAI wrapper's `report_job_outcome`/`amend_job_outcome`.
+- **Team resolution:** explicit `team_id=` > `REVENIUM_TEAM_ID` > automatic resolution from the API key; `OutcomeReportingError` is raised if none of these yields a team.
+- **Nesting:** a nested `JobContext` is a different job (replace, not merge); exiting the inner context restores the outer job's fields.
+
+To tag AI calls with job fields without a context manager, use per-call `usage_metadata={"agentic_job_id": ...}`, the `@track_job` decorator (LiteLLM), or the process-wide `REVENIUM_AGENTIC_JOB_*` environment variables — see [Optional Environment Variables](#optional-environment-variables).
+
+### Amending an Outcome
+
+Outcomes are amendable: when the business result changes after the fact, amend the recorded outcome instead of re-reporting it. `JobContext.attach()` returns a lightweight handle to an existing job — it is not entered as a context manager and does not touch AI-call scoping — so amendments work from a different process than the one that ran the job.
+
+```python
+from revenium_middleware import JobContext, get_outcome_history
+
+# Two weeks after the agent converted the lead at $500,
+# the customer expands to the annual plan.
+job = JobContext.attach("sales-lead-8842")
+job.amend_outcome(
+    reason="Customer expanded to the annual plan after the initial conversion",
+    outcome_value=750.0,
+)
+job.close()
+
+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`), and returns the updated job as a dict.
+
+### Outcome Exceptions
+
+All outcome exceptions are importable from `revenium_middleware` and share the `OutcomeReportingError` base, so `except OutcomeReportingError:` catches the whole family:
+
+| Exception | Raised when | What to do |
+|-----------|-------------|------------|
+| `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 |
+
+### Low-Level Client
+
+For manual control over every metric (one `emit_completion` per LLM call, one `emit_tool_event` per tool/step), use `AgenticOutcomeClient` directly:
+
 ```python
 from revenium_middleware.agentic_outcomes import AgenticOutcomeClient, AgenticOutcomeSettings
 
@@ -335,7 +399,7 @@ from dotenv import load_dotenv
 load_dotenv()
 
 import openai
-import revenium_middleware_openai  # Auto-initializes
+import revenium_middleware.openai  # Auto-initializes
 
 client = openai.OpenAI()
 
@@ -374,7 +438,7 @@ The middleware automatically detects Azure OpenAI when using `AzureOpenAI()` and
 
 ```python
 from openai import AzureOpenAI
-import revenium_middleware_openai
+import revenium_middleware.openai
 
 client = AzureOpenAI(
     azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
@@ -407,7 +471,7 @@ from dotenv import load_dotenv
 load_dotenv()
 
 import anthropic
-import revenium_middleware_anthropic  # Auto-initializes
+import revenium_middleware.anthropic  # Auto-initializes
 
 client = anthropic.Anthropic()
 
@@ -442,7 +506,7 @@ The middleware provides complete AWS Bedrock integration with automatic detectio
 
 ```python
 import anthropic
-import revenium_middleware_anthropic
+import revenium_middleware.anthropic
 
 # Bedrock is automatically detected when AWS credentials are available
 # and base_url contains 'amazonaws.com'
@@ -511,7 +575,7 @@ pip install "revenium-python-sdk[google-vertex]"
 from dotenv import load_dotenv
 load_dotenv()
 
-import revenium_middleware_google
+import revenium_middleware.google
 from google import genai
 
 client = genai.Client()
@@ -532,7 +596,7 @@ print(response.text)
 from dotenv import load_dotenv
 load_dotenv()
 
-import revenium_middleware_google
+import revenium_middleware.google
 import vertexai
 from vertexai.generative_models import GenerativeModel
 
@@ -573,7 +637,7 @@ from dotenv import load_dotenv
 load_dotenv()
 
 import ollama
-import revenium_middleware_ollama  # Auto-initializes
+import revenium_middleware.ollama  # Auto-initializes
 
 # Chat completion
 response = ollama.chat(
@@ -608,7 +672,7 @@ response = ollama.embed(model='nomic-embed-text', input=['Text 1', 'Text 2', 'Te
 
 ```python
 import openai
-import revenium_middleware_openai
+import revenium_middleware.openai
 
 openai.api_key = 'ollama'
 openai.base_url = 'http://localhost:11434/v1/'
@@ -636,7 +700,7 @@ Supports all LLM providers available through LiteLLM with two integration patter
 from dotenv import load_dotenv
 load_dotenv()
 
-import revenium_middleware_litellm_client.middleware  # Auto-initializes
+import revenium_middleware.litellm.client.middleware  # Auto-initializes
 import litellm
 import os
 
@@ -659,7 +723,7 @@ Add the callback to your LiteLLM `config.yaml` for server-side integration:
 
 ```yaml
 litellm_settings:
-  callbacks: ["revenium_middleware_litellm_proxy.middleware.proxy_handler_instance"]
+  callbacks: ["revenium_middleware.litellm.proxy.middleware.proxy_handler_instance"]
 ```
 
 When using the LiteLLM proxy, pass metadata via HTTP headers (`x-revenium-*`).
@@ -678,17 +742,47 @@ LiteLLM provides additional tracking decorators beyond the standard `@revenium_m
 | `@track_product()` | Track product-specific usage |
 | `@track_subscriber()` | Identify end users |
 | `@track_quality()` | Track response quality scores |
+| `@track_job()` | Inject agentic job fields for cost/ROI correlation, e.g. `@track_job(job_id="loan-app-12345", type="loan_processing")` |
 
-All decorators support static values, extraction from function arguments (`name_from_arg`), or extraction from object attributes (`name_from_attr`).
+The tracking decorators above support static values, extraction from function arguments (`name_from_arg`), or extraction from object attributes (`name_from_attr`); `@track_job` supports static values and argument extraction (`job_id_from_arg`, `type_from_arg`) but has no attribute variant.
 
 #### CrewAI Integration
 
 ```bash
-pip install "revenium-middleware-litellm[crewai]"
+pip install "revenium-python-sdk[litellm]" crewai
 ```
 
 Pre-built wrapper for tracking CrewAI agent executions. **Note:** CrewAI requires Python 3.12 or earlier.
 
+**Job outcome tracking:** pass the `agentic_job_*` kwargs to tie every LLM call in the crew to one agentic job, then report (or later amend) the job's business outcome. Requires a write-scope key (`rev_sk_`) — see [Agentic Outcomes](#agentic-outcomes-outcome-based-metering).
+
+```python
+from revenium_middleware.litellm.client.integrations.crewai import ReveniumCrewWrapper
+
+crew = ReveniumCrewWrapper(
+    agents=[support_agent],
+    tasks=[triage_task],
+    organization_id="AcmeCorp",
+    subscription_id="82764738",
+    product_id="Platinum",
+    agentic_job_id="support-ticket-456",
+    agentic_job_name="Support Ticket Triage",
+    agentic_job_type="customer_support",
+    agentic_job_version="2.0",
+)
+result = crew.kickoff()
+
+crew.report_job_outcome(
+    execution_status="SUCCESS",
+    outcome_type="DEFLECTED",
+    outcome_value=25.0,
+)
+
+# Later, if the business result changes:
+# crew.amend_job_outcome(reason="Ticket reopened and escalated to a human agent",
+#                        outcome_type="ESCALATED", outcome_value=0.0)
+```
+
 **LiteLLM environment variables:**
 - `LITELLM_PROXY_URL` - Your LiteLLM proxy URL
 - `LITELLM_API_KEY` - Your LiteLLM proxy API key
@@ -708,7 +802,7 @@ from dotenv import load_dotenv
 load_dotenv()
 
 from openai import OpenAI
-import revenium_middleware_perplexity  # Auto-patches OpenAI
+import revenium_middleware.perplexity  # Auto-patches OpenAI
 
 client = OpenAI(
     api_key=os.getenv("PERPLEXITY_API_KEY"),
@@ -726,7 +820,7 @@ response = client.chat.completions.create(
 
 ```python
 from perplexity import Perplexity
-import revenium_middleware_perplexity  # Auto-patches Perplexity
+import revenium_middleware.perplexity  # Auto-patches Perplexity
 
 client = Perplexity(api_key=os.getenv("PERPLEXITY_API_KEY"))
 
@@ -761,7 +855,7 @@ for chunk in stream:
 Supports image, video, and audio generation through fal.ai with automatic media type detection.
 
 ```python
-import revenium_middleware_fal  # Auto-activates
+import revenium_middleware.fal  # Auto-activates
 import fal_client
 
 result = fal_client.subscribe(
@@ -793,16 +887,23 @@ for image in result.get("images", []):
 
 Callback handler that automatically tracks LLM calls, chains, tools, and agent actions.
 
+```bash
+pip install "revenium-python-sdk[langchain]"
+```
+
+Wrap any LangChain LLM (or embeddings model) with `wrap()` — the Revenium callback handler is attached for you:
+
 ```python
 from langchain_openai import ChatOpenAI
-from revenium_middleware_langchain import ReveniumCallbackHandler
+from revenium_middleware.openai.langchain import wrap
 
-handler = ReveniumCallbackHandler(
-    trace_id="session-123",
-    agent_name="support_agent"
+llm = wrap(
+    ChatOpenAI(model="gpt-4o-mini"),
+    usage_metadata={
+        "trace_id": "session-123",
+        "agent": "support_agent",
+    },
 )
-
-llm = ChatOpenAI(model="gpt-4o-mini", callbacks=[handler])
 response = llm.invoke("Hello!")
 ```
 
@@ -813,13 +914,14 @@ from langchain_core.prompts import ChatPromptTemplate
 from langchain_core.output_parsers import StrOutputParser
 
 prompt = ChatPromptTemplate.from_template("Tell me a joke about {topic}")
-chain = prompt | llm | output_parser
+chain = prompt | llm | StrOutputParser()
 result = chain.invoke({"topic": "programming"})
 ```
 
 **With agents:**
 
 ```python
+from langchain_core.messages import HumanMessage
 from langchain_core.tools import tool
 from langgraph.prebuilt import create_react_agent
 
@@ -829,40 +931,32 @@ def get_weather(city: str) -> str:
     return f"Sunny, 72F in {city}"
 
 agent = create_react_agent(llm, [get_weather])
-result = agent.invoke(
-    {"messages": [HumanMessage(content="Weather in NYC?")]},
-    config={"callbacks": [handler]}
-)
+result = agent.invoke({"messages": [HumanMessage(content="Weather in NYC?")]})
 ```
 
-**Async support:**
+**Async support:** the handler is async-native — wrap once and use `ainvoke`/`astream` directly:
 
 ```python
-from revenium_middleware_langchain import AsyncReveniumCallbackHandler
-
-handler = AsyncReveniumCallbackHandler(trace_id="async-session")
-llm = ChatOpenAI(model="gpt-4o-mini", callbacks=[handler])
+llm = wrap(ChatOpenAI(model="gpt-4o-mini"))
 response = await llm.ainvoke("Hello!")
 ```
 
 **Supported providers:** OpenAI, Anthropic, Google, AWS Bedrock, Azure OpenAI, Cohere, HuggingFace, Ollama. Provider is auto-detected from LangChain class name or model name prefix.
 
-**Programmatic configuration:**
+**Attaching to an existing LLM:** use `attach_to()` to add tracking in-place, with any of the standard metadata fields (see [Metadata Fields](#metadata-fields)):
 
 ```python
-from revenium_middleware_langchain import ReveniumCallbackHandler, ReveniumConfig, SubscriberConfig
-
-config = ReveniumConfig(
-    api_key="hak_your_api_key",
-    environment="production",
-    organization_name="my_org",
-    product_name="my_product",
-    subscriber=SubscriberConfig(id="user_123", email="user@example.com"),
-)
+from revenium_middleware.openai.langchain import attach_to
 
-handler = ReveniumCallbackHandler(config=config, trace_id="session-123")
+attach_to(llm, usage_metadata={
+    "organizationName": "my_org",
+    "productName": "my_product",
+    "subscriber": {"id": "user_123", "email": "user@example.com"},
+})
 ```
 
+Credentials come from the standard environment variables (`REVENIUM_METERING_API_KEY`, `REVENIUM_METERING_BASE_URL`) or `revenium_middleware.configure()`.
+
 ---
 
 ## Metadata Fields
@@ -931,6 +1025,7 @@ Enhanced observability fields for tracking AI operations across environments, re
 | `parent_transaction_id` | `REVENIUM_PARENT_TRANSACTION_ID` | Parent transaction ID | Link child operations to parents across microservices |
 | `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 |
 
 **Note:** `operation_type` (e.g., `CHAT`, `EMBED`, `TOOL_CALL`) and `operation_subtype` (e.g., `function_call`, `streaming`) are automatically detected by the middleware and cannot be overridden.
 
@@ -958,7 +1053,8 @@ response = client.chat.completions.create(
         "trace_type": "customer-support",
         "trace_name": "Support Chat Session",
         "transaction_name": "Generate Response",
-        "parent_transaction_id": "parent-txn-123"
+        "parent_transaction_id": "parent-txn-123",
+        "ticket_id": "JIRA-123"
     }
 )
 ```
@@ -1179,7 +1275,7 @@ Each field has a maximum length of **50,000 characters**. If exceeded, it's trun
 import os
 os.environ["REVENIUM_CAPTURE_PROMPTS"] = "true"
 
-import revenium_middleware_openai
+import revenium_middleware.openai
 from openai import OpenAI
 
 client = OpenAI()
@@ -1362,7 +1458,7 @@ print(get_buffer_stats())
 | `REVENIUM_LOG_LEVEL` | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
 | `REVENIUM_CAPTURE_PROMPTS` | `false` | Enable prompt capture |
 | `REVENIUM_SELECTIVE_METERING` | `false` | Only meter `@revenium_meter` decorated functions |
-| `REVENIUM_TEAM_ID` | - | Team ID for cost lookups |
+| `REVENIUM_TEAM_ID` | - | Team ID for cost lookups and outcome reporting (JobContext team resolution) |
 | `REVENIUM_ENVIRONMENT` | - | Deployment environment (auto-detects from `ENVIRONMENT`, `DEPLOYMENT_ENV`) |
 | `REVENIUM_REGION` | - | Cloud region (auto-detects from `AWS_REGION`, `AZURE_REGION`, `GCP_REGION`) |
 | `REVENIUM_CREDENTIAL_ALIAS` | - | Human-readable API key name |
@@ -1371,10 +1467,18 @@ print(get_buffer_stats())
 | `REVENIUM_PARENT_TRANSACTION_ID` | - | Parent transaction ID for distributed tracing |
 | `REVENIUM_TRANSACTION_NAME` | - | Human-friendly operation name |
 | `REVENIUM_RETRY_NUMBER` | - | Retry attempt number |
+| `REVENIUM_AGENTIC_JOB_ID` | - | Agentic job instance ID attached to all completions in the process (triggers backend job auto-creation) |
+| `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_PROFITSTREAM_BASE_URL` | `https://api.revenium.io` | Agentic outcomes API base URL |
 | `REVENIUM_BEDROCK_DISABLE` | - | Set to `1` to disable Bedrock auto-detection |
 | `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 |
 
+Per-call `usage_metadata` values take precedence over the `REVENIUM_AGENTIC_JOB_*` environment variables, and the LiteLLM proxy path sources job fields from `x-revenium-*` headers only — these process-level env fallbacks do not apply to proxied traffic.
+
 ### Provider-Specific Environment Variables
 
 | Variable | Provider | Description |
@@ -1416,7 +1520,7 @@ print(get_buffer_stats())
 
 **Force direct Anthropic API:** Set `REVENIUM_BEDROCK_DISABLE=1` to disable Bedrock auto-detection.
 
-**Check initialization status:** Use `revenium_middleware_<provider>.is_initialized()` to verify setup.
+**Check initialization status (Anthropic):** Use `revenium_middleware.anthropic.is_initialized()` to verify setup.
 
 ---