revenium-python-sdk 0.9.2__tar.gz → 0.10.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/PKG-INFO +609 -92
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/README.md +595 -90
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/pyproject.toml +23 -2
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/__init__.py +46 -6
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/__init__.py +7 -1
- revenium_python_sdk-0.10.1/revenium_middleware/_core/cache_tokens.py +456 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/call_context.py +37 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/call_ownership.py +172 -16
- revenium_python_sdk-0.10.1/revenium_middleware/_core/closable_scope.py +39 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/config.py +208 -48
- revenium_python_sdk-0.10.1/revenium_middleware/_core/context.py +503 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/decorators.py +383 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/delivery_circuit.py +10 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/enforcement.py +871 -101
- revenium_python_sdk-0.10.1/revenium_middleware/_core/error_text.py +87 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/exceptions.py +4 -3
- revenium_python_sdk-0.10.1/revenium_middleware/_core/failed_calls.py +125 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/fields.py +67 -19
- revenium_python_sdk-0.10.1/revenium_middleware/_core/json_safe.py +266 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/langchain_settings.py +55 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/log_sanitize.py +266 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/metering.py +722 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/metering_buffer.py +268 -74
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/metering_pool.py +45 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/metering_status.py +11 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/metering_submission.py +215 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/outcomes.py +202 -22
- revenium_python_sdk-0.10.1/revenium_middleware/_core/package_versions.py +22 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/parse_failures.py +44 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/patch_registry.py +47 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/perplexity_cost.py +141 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/perplexity_usage_metadata.py +23 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/prompt_extraction.py +549 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/responses_status.py +29 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/secret_shapes.py +211 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/selective_metering.py +44 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/sse_body_tap.py +264 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/subscriber.py +117 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/tool_event_transport.py +69 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/trace_fields.py +102 -55
- revenium_python_sdk-0.10.1/revenium_middleware/_core/usage_iterations.py +184 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/vendor_model_aliases.py +69 -0
- revenium_python_sdk-0.10.1/revenium_middleware/_core/wire_guards.py +199 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_base_client.py +8 -3
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_client.py +35 -82
- revenium_python_sdk-0.10.1/revenium_middleware/_metering/decorator.py +779 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/resources/ai.py +45 -24
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/types/ai_create_audio_params.py +1 -3
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/types/ai_create_completion_params.py +8 -3
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/types/ai_create_image_params.py +1 -3
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/types/ai_create_video_params.py +1 -3
- revenium_python_sdk-0.10.1/revenium_middleware/agentic_outcomes.py +565 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/anthropic/__init__.py +10 -9
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/anthropic/bedrock_adapter.py +53 -19
- revenium_python_sdk-0.10.1/revenium_middleware/anthropic/bedrock_model_names.py +66 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/anthropic/bedrock_transport.py +260 -52
- revenium_python_sdk-0.10.1/revenium_middleware/anthropic/inference_profiles.py +453 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/anthropic/middleware.py +658 -422
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/anthropic/prompt_extractor.py +81 -57
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/anthropic/provider.py +1 -1
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/anthropic/raw_response.py +73 -7
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/anthropic/stream_create.py +95 -10
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/fal/__init__.py +2 -2
- revenium_python_sdk-0.10.1/revenium_middleware/fal/_call.py +97 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/fal/_metering.py +105 -17
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/fal/_queue.py +25 -3
- revenium_python_sdk-0.10.1/revenium_middleware/fal/middleware.py +338 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/fal/trace_fields.py +42 -108
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/__init__.py +2 -29
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/common/__init__.py +14 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/common/types.py +6 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/common/utils.py +252 -36
- revenium_python_sdk-0.10.1/revenium_middleware/google/config.py +41 -0
- revenium_python_sdk-0.10.1/revenium_middleware/google/google_ai/middleware.py +1304 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/prompt_extractor.py +5 -69
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/vertex_ai/middleware.py +363 -162
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/griptape/__init__.py +4 -0
- revenium_python_sdk-0.10.1/revenium_middleware/griptape/_retry.py +12 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/griptape/anthropic_driver.py +2 -0
- revenium_python_sdk-0.10.1/revenium_middleware/griptape/budget_errors.py +150 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/griptape/litellm_driver.py +150 -43
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/griptape/ollama_driver.py +2 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/griptape/openai_driver.py +18 -1
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/griptape/openai_embedding_driver.py +2 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/griptape/universal_driver.py +63 -47
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/job_context.py +81 -37
- revenium_python_sdk-0.10.1/revenium_middleware/job_history.py +392 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/job_type_economics.py +2 -5
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/client/decorators.py +180 -303
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/client/integrations/__init__.py +2 -2
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/client/integrations/crewai.py +173 -74
- revenium_python_sdk-0.10.1/revenium_middleware/litellm/client/middleware.py +1038 -0
- revenium_python_sdk-0.10.1/revenium_middleware/litellm/proxy/_metering_owner.py +131 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/proxy/guardrail.py +416 -100
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/proxy/middleware.py +186 -76
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/ollama/middleware.py +127 -45
- revenium_python_sdk-0.10.1/revenium_middleware/openai/audio.py +463 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/openai/azure_model_resolver.py +56 -3
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/openai/langchain/__init__.py +48 -4
- revenium_python_sdk-0.10.1/revenium_middleware/openai/langchain/_abandoned_runs.py +109 -0
- revenium_python_sdk-0.10.1/revenium_middleware/openai/langchain/_model_call.py +385 -0
- revenium_python_sdk-0.10.1/revenium_middleware/openai/langchain/_perplexity_cost_capture.py +103 -0
- revenium_python_sdk-0.10.1/revenium_middleware/openai/langchain/_prompt_capture.py +75 -0
- revenium_python_sdk-0.10.1/revenium_middleware/openai/langchain/_text_completion_usage.py +218 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/openai/langchain/_utils.py +2 -1
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/openai/langchain/unified_handler.py +421 -100
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/openai/middleware.py +1154 -387
- revenium_python_sdk-0.10.1/revenium_middleware/openai/prompt_extractor.py +13 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/openai/provider.py +33 -3
- revenium_python_sdk-0.10.1/revenium_middleware/openai/raw_response.py +52 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/openai/trace_fields.py +2 -2
- revenium_python_sdk-0.10.1/revenium_middleware/openai/xai_usage.py +29 -0
- revenium_python_sdk-0.10.1/revenium_middleware/perplexity/_metering_scope.py +9 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/perplexity/middleware.py +228 -47
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/perplexity/patching.py +12 -9
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/perplexity/perplexity_sdk.py +134 -33
- revenium_python_sdk-0.10.1/revenium_middleware/perplexity/raw_response.py +141 -0
- revenium_python_sdk-0.10.1/revenium_middleware/perplexity/streaming.py +253 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/webhooks/_verify.py +1 -1
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_python_sdk.egg-info/PKG-INFO +609 -92
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_python_sdk.egg-info/SOURCES.txt +30 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_python_sdk.egg-info/requires.txt +16 -1
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/tests/test_patch_coverage.py +18 -2
- revenium_python_sdk-0.9.2/revenium_middleware/_core/cache_tokens.py +0 -172
- revenium_python_sdk-0.9.2/revenium_middleware/_core/context.py +0 -257
- revenium_python_sdk-0.9.2/revenium_middleware/_core/decorators.py +0 -202
- revenium_python_sdk-0.9.2/revenium_middleware/_core/log_sanitize.py +0 -100
- revenium_python_sdk-0.9.2/revenium_middleware/_core/metering.py +0 -370
- revenium_python_sdk-0.9.2/revenium_middleware/_core/metering_submission.py +0 -117
- revenium_python_sdk-0.9.2/revenium_middleware/_core/patch_registry.py +0 -26
- revenium_python_sdk-0.9.2/revenium_middleware/_core/prompt_extraction.py +0 -55
- revenium_python_sdk-0.9.2/revenium_middleware/_core/subscriber.py +0 -51
- revenium_python_sdk-0.9.2/revenium_middleware/_metering/decorator.py +0 -524
- revenium_python_sdk-0.9.2/revenium_middleware/agentic_outcomes.py +0 -424
- revenium_python_sdk-0.9.2/revenium_middleware/fal/_call.py +0 -62
- revenium_python_sdk-0.9.2/revenium_middleware/fal/middleware.py +0 -169
- revenium_python_sdk-0.9.2/revenium_middleware/google/config.py +0 -63
- revenium_python_sdk-0.9.2/revenium_middleware/google/google_ai/middleware.py +0 -659
- revenium_python_sdk-0.9.2/revenium_middleware/job_history.py +0 -130
- revenium_python_sdk-0.9.2/revenium_middleware/litellm/client/middleware.py +0 -565
- revenium_python_sdk-0.9.2/revenium_middleware/litellm/proxy/_metering_owner.py +0 -74
- revenium_python_sdk-0.9.2/revenium_middleware/openai/langchain/_model_call.py +0 -109
- revenium_python_sdk-0.9.2/revenium_middleware/openai/prompt_extractor.py +0 -173
- revenium_python_sdk-0.9.2/revenium_middleware/perplexity/_metering_scope.py +0 -7
- revenium_python_sdk-0.9.2/revenium_middleware/perplexity/streaming.py +0 -138
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/LICENSE +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/load_diagnostics.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_core/shutdown_signals.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/LICENSE +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_compat.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_constants.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_exceptions.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_files.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_models.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_qs.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_resource.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_response.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_streaming.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_types.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_utils/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_utils/_logs.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_utils/_proxy.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_utils/_reflection.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_utils/_resources_proxy.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_utils/_streams.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_utils/_sync.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_utils/_transform.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_utils/_typing.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_utils/_utils.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/_version.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/context.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/py.typed +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/resources/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/resources/apis.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/resources/events.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/types/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/types/api_meter_request_params.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/types/api_meter_response_params.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/types/event_create_params.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/_metering/types/metering_response_resource.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/anthropic/config.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/anthropic/trace_fields.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/fal/config.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/common/exceptions.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/common/protocols.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/common/trace_fields.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/google_ai/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/google_ai/provider.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/vertex_ai/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/google/vertex_ai/provider.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/griptape/_metadata.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/client/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/client/config.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/client/context.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/client/hooks.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/client/trace_fields.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/client/validation.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/litellm/proxy/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/ollama/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/ollama/trace_fields.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/openai/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/openai/azure_config.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/openai/config.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/openai/exceptions.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/perplexity/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/perplexity/provider.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/perplexity/trace_fields.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_middleware/webhooks/__init__.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_python_sdk.egg-info/dependency_links.txt +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/revenium_python_sdk.egg-info/top_level.txt +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/setup.cfg +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/tests/test_metering.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/tests/test_metering_dispatch_timestamps.py +0 -0
- {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.1}/tests/test_release_verify_ticket.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: revenium-python-sdk
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.10.1
|
|
4
4
|
Summary: The official Revenium Python SDK — unified AI metering middleware for OpenAI, Anthropic, Google, Ollama, LiteLLM, Perplexity, and fal.ai.
|
|
5
5
|
Author-email: Revenium <support@revenium.io>
|
|
6
6
|
License: MIT
|
|
@@ -28,11 +28,13 @@ Requires-Dist: httpx<1,>=0.23.0
|
|
|
28
28
|
Requires-Dist: pydantic<3,>=1.9.0
|
|
29
29
|
Requires-Dist: sniffio
|
|
30
30
|
Requires-Dist: typing-extensions<5,>=4.10
|
|
31
|
+
Requires-Dist: wrapt>=1.14.0
|
|
31
32
|
Provides-Extra: openai
|
|
32
33
|
Requires-Dist: wrapt>=1.14.0; extra == "openai"
|
|
33
34
|
Requires-Dist: openai>=1.0.0; extra == "openai"
|
|
34
35
|
Requires-Dist: python-dotenv>=0.19.0; extra == "openai"
|
|
35
36
|
Provides-Extra: langchain
|
|
37
|
+
Requires-Dist: wrapt>=1.14.0; extra == "langchain"
|
|
36
38
|
Requires-Dist: langchain>=0.1.16; extra == "langchain"
|
|
37
39
|
Requires-Dist: langchain-openai>=0.1.0; extra == "langchain"
|
|
38
40
|
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
|
|
@@ -58,7 +60,7 @@ Requires-Dist: google-genai>=0.1.0; extra == "google-genai"
|
|
|
58
60
|
Requires-Dist: python-dotenv; extra == "google-genai"
|
|
59
61
|
Provides-Extra: google-vertex
|
|
60
62
|
Requires-Dist: wrapt>=1.14.0; extra == "google-vertex"
|
|
61
|
-
Requires-Dist:
|
|
63
|
+
Requires-Dist: google-cloud-aiplatform>=1.71.1; extra == "google-vertex"
|
|
62
64
|
Requires-Dist: python-dotenv; extra == "google-vertex"
|
|
63
65
|
Provides-Extra: anthropic
|
|
64
66
|
Requires-Dist: wrapt>=1.14.0; extra == "anthropic"
|
|
@@ -67,6 +69,7 @@ Requires-Dist: python-dotenv>=0.19.0; extra == "anthropic"
|
|
|
67
69
|
Provides-Extra: ollama
|
|
68
70
|
Requires-Dist: wrapt>=1.14.0; extra == "ollama"
|
|
69
71
|
Requires-Dist: ollama>=0.3.0; extra == "ollama"
|
|
72
|
+
Requires-Dist: python-dotenv>=0.19.0; extra == "ollama"
|
|
70
73
|
Provides-Extra: fal
|
|
71
74
|
Requires-Dist: wrapt>=1.14.0; extra == "fal"
|
|
72
75
|
Requires-Dist: fal-client>=0.13.0; extra == "fal"
|
|
@@ -74,6 +77,7 @@ Requires-Dist: python-dotenv>=0.19.0; extra == "fal"
|
|
|
74
77
|
Provides-Extra: litellm
|
|
75
78
|
Requires-Dist: wrapt>=1.14.0; extra == "litellm"
|
|
76
79
|
Requires-Dist: litellm>=1.40.0; extra == "litellm"
|
|
80
|
+
Requires-Dist: python-dotenv>=0.19.0; extra == "litellm"
|
|
77
81
|
Provides-Extra: litellm-proxy
|
|
78
82
|
Requires-Dist: wrapt>=1.14.0; extra == "litellm-proxy"
|
|
79
83
|
Requires-Dist: litellm[proxy]>=1.93.0; extra == "litellm-proxy"
|
|
@@ -94,12 +98,20 @@ Requires-Dist: boto3; extra == "dev"
|
|
|
94
98
|
Requires-Dist: ollama>=0.3.0; extra == "dev"
|
|
95
99
|
Requires-Dist: griptape<2.0.0,>=1.0.0; python_version >= "3.10" and extra == "dev"
|
|
96
100
|
Requires-Dist: langchain-anthropic; python_version >= "3.10" and extra == "dev"
|
|
101
|
+
Requires-Dist: langchain; python_version >= "3.10" and extra == "dev"
|
|
102
|
+
Requires-Dist: langchain-openai; python_version >= "3.10" and extra == "dev"
|
|
103
|
+
Requires-Dist: langchain-mistralai; python_version >= "3.10" and extra == "dev"
|
|
104
|
+
Requires-Dist: langchain-perplexity; python_version >= "3.10" and extra == "dev"
|
|
105
|
+
Requires-Dist: langchain-cohere; python_version >= "3.10" and extra == "dev"
|
|
106
|
+
Requires-Dist: langchain-huggingface; python_version >= "3.10" and extra == "dev"
|
|
97
107
|
Requires-Dist: openai>=1.0.0; extra == "dev"
|
|
98
108
|
Requires-Dist: litellm>=1.40.0; extra == "dev"
|
|
99
109
|
Requires-Dist: fal-client>=0.13.0; extra == "dev"
|
|
100
110
|
Requires-Dist: perplexityai>=0.1.0; extra == "dev"
|
|
101
111
|
Requires-Dist: google-genai>=0.1.0; extra == "dev"
|
|
102
112
|
Requires-Dist: pyyaml; extra == "dev"
|
|
113
|
+
Provides-Extra: dev-langchain-aws
|
|
114
|
+
Requires-Dist: langchain-aws[anthropic]>=1.7.5; python_version >= "3.10" and extra == "dev-langchain-aws"
|
|
103
115
|
Dynamic: license-file
|
|
104
116
|
|
|
105
117
|
# Revenium Python SDK
|
|
@@ -120,11 +132,10 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
|
|
|
120
132
|
- **Decorator Support**: `@revenium_metadata` for automatic metadata injection and `@revenium_meter` for selective metering
|
|
121
133
|
- **Tool Metering**: `@meter_tool` to meter arbitrary tool/function calls alongside LLM API metering
|
|
122
134
|
- **Prompt Capture**: Optional capture of prompts and responses for analytics and debugging
|
|
123
|
-
- **Terminal Summary**: Real-time cost and usage summaries in your terminal (human-readable or JSON)
|
|
124
135
|
- **Distributed Tracing**: Built-in trace visualization fields for cross-service observability
|
|
125
136
|
- **Asynchronous Processing**: Usage records are sent from a fixed pool of background threads, never on your request path
|
|
126
|
-
- **Graceful Shutdown**: Flushes pending metering data when the process exits, within a bounded time, without taking over your application's signal handling
|
|
127
|
-
- **Thread-Safe**: Production-ready with `contextvars`-based context management for concurrent applications
|
|
137
|
+
- **Graceful Shutdown**: Flushes pending metering data when the process exits, and when a `multiprocessing` worker process finishes its job, within a bounded time, without taking over your application's signal handling; `flush_metering()` flushes on demand
|
|
138
|
+
- **Thread-Safe**: Production-ready with `contextvars`-based context management for concurrent applications; wrap worker thread targets with `carry_context` (see [Decorator Support](#decorator-support))
|
|
128
139
|
|
|
129
140
|
## Supported Providers
|
|
130
141
|
|
|
@@ -132,6 +143,7 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
|
|
|
132
143
|
|----------|-------|----------------|
|
|
133
144
|
| OpenAI | `openai` | `pip install revenium-python-sdk[openai]` |
|
|
134
145
|
| Azure OpenAI | `openai` | `pip install revenium-python-sdk[openai]` |
|
|
146
|
+
| xAI (Grok, via OpenAI SDK) | `openai` | `pip install revenium-python-sdk[openai]` |
|
|
135
147
|
| Anthropic | `anthropic` | `pip install revenium-python-sdk[anthropic]` |
|
|
136
148
|
| AWS Bedrock (Anthropic) | `anthropic` | `pip install revenium-python-sdk[anthropic]` |
|
|
137
149
|
| Google Gemini | `google-genai` | `pip install revenium-python-sdk[google-genai]` |
|
|
@@ -145,24 +157,57 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
|
|
|
145
157
|
| LangChain | `langchain` | `pip install revenium-python-sdk[langchain]` |
|
|
146
158
|
| Griptape | `griptape` | `pip install revenium-python-sdk[griptape]` |
|
|
147
159
|
|
|
160
|
+
Not supported: Runway video generation is not metered automatically; to record those calls, wrap them with `@meter_tool` (see [Tool Metering](#tool-metering)).
|
|
161
|
+
|
|
148
162
|
## Feature Matrix
|
|
149
163
|
|
|
150
164
|
| Feature | OpenAI | Anthropic | Google | Ollama | LiteLLM | Perplexity | fal.ai |
|
|
151
165
|
|---------|--------|-----------|--------|--------|---------|------------|--------|
|
|
152
|
-
| Chat Completions | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
|
|
166
|
+
| Chat Completions | Yes\* | Yes | Yes | Yes | Yes | Yes | Yes |
|
|
153
167
|
| Streaming | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
|
|
154
168
|
| Embeddings | Yes | - | Yes | Yes | Yes | - | - |
|
|
155
169
|
| Vision/Multimodal | Yes | Yes | Yes | - | Yes | - | Yes |
|
|
170
|
+
| Audio (speech, transcription, translation) | Yes | - | - | - | Proxy mode | - | Yes |
|
|
156
171
|
| Image Generation | - | - | Yes | - | - | - | Yes |
|
|
157
|
-
| Video Generation | - | - | Yes | - | - | - | Yes |
|
|
158
|
-
| Prompt Capture | Yes | Yes | Yes | - |
|
|
159
|
-
| Terminal Summary | Yes | Yes | Yes | Yes | Yes | - | - |
|
|
172
|
+
| Video Generation | - | - | Yes[^veo] | - | - | - | Yes |
|
|
173
|
+
| Prompt Capture | Yes | Yes | Yes | - | Client mode[^litellm-capture] | - | - |
|
|
160
174
|
| Azure / Bedrock | Azure | Bedrock | Vertex AI | - | All | - | - |
|
|
161
175
|
| LangChain Integration | Yes | - | - | - | - | - | - |
|
|
162
176
|
| Griptape Integration | Yes | Yes | - | Yes | Yes | - | - |
|
|
163
|
-
| CrewAI Integration |
|
|
177
|
+
| CrewAI Integration | Yes | Yes | Yes | - | Yes | - | - |
|
|
164
178
|
| Proxy Mode | - | - | - | - | Yes | - | - |
|
|
165
179
|
|
|
180
|
+
[^litellm-capture]: LiteLLM prompt capture covers chat calls your own code makes (`completion`, `acompletion` and their streams). The LiteLLM gateway plugin (`ReveniumGuardrail`) does not capture prompts or replies.
|
|
181
|
+
|
|
182
|
+
\* OpenAI's `chat.completions` and `responses` calls are metered[^openai-background]; the legacy `completions.create` endpoint is not.
|
|
183
|
+
|
|
184
|
+
[^openai-background]: An OpenAI background response (`responses.create(background=True)`) is recorded when your code's `responses.retrieve(...)`, a resumed stream (`responses.retrieve(..., stream=True)` or `responses.stream(response_id=...)`) or `responses.cancel(...)` first sees the job finish, with the `usage_metadata` you gave at create. A background job you never retrieve, or retrieve only from a different process than the one that created it or after a restart, is not recorded. A cancelled background job is recorded when OpenAI reports usage for it on the first call that sees it cancelled, usually `responses.cancel(...)`; a cancelled job with no usage on that call is not recorded. A background stream cut off part-way and never resumed or retrieved is not recorded. Background jobs created through `beta.responses` are not metered. A background job created through `responses.with_streaming_response.create(..., background=True)` is not recorded, even when you retrieve it later. Reading a finished job only through `responses.with_streaming_response.retrieve(...)` does not record it; the job stays pending, and the next `responses.retrieve(...)` or `responses.with_raw_response.retrieve(...)` in the same process records it once.
|
|
185
|
+
|
|
186
|
+
[^veo]: A Veo video through `google.genai` (the Gemini API, or Vertex AI with `vertexai=True`) is recorded when your code's `client.operations.get(...)` (or `client.aio.operations.get(...)`) first sees the operation finish, billed at the requested clip length times the videos returned (Google's response carries no duration). A failed operation is recorded as a failed, zero-second video. When the request sets `webhook_config` or `pubsub_topic`, the video is recorded when you submit it. A video you never poll, or poll from a different process than the one that submitted it, is not recorded.
|
|
187
|
+
|
|
188
|
+
Some billable provider calls are not metered at all: see [Calls the SDK does not meter](#calls-the-sdk-does-not-meter).
|
|
189
|
+
|
|
190
|
+
## Calls the SDK does not meter
|
|
191
|
+
|
|
192
|
+
The calls below are billed by the provider (some, such as batch and fine-tuning jobs, when the job runs rather than when you call them), but the SDK records no usage for them: nothing reaches Revenium and nothing is logged. On every build a test compares this list with the SDK's inventory of the public calls of the OpenAI, Anthropic, Perplexity, Gemini, Ollama, LiteLLM and fal clients, boto3's Bedrock Runtime client, and the Vertex AI model, session, batch prediction, tuning and context-cache classes, on the provider versions the SDK is tested on. Calls reached another way, for example LangChain classes that call their own vendor SDK, are outside that check, except LangChain embeddings, listed by hand below; wrapping one with `wrap()` logs a warning. Sync and async forms are folded into one name, and the `with_raw_response` and `with_streaming_response` forms of a listed call are not metered either. To record any of these calls, wrap it with `@meter_tool` (see [Tool Metering](#tool-metering)).
|
|
193
|
+
|
|
194
|
+
<!-- not-metered:start -->
|
|
195
|
+
- **OpenAI** (`OpenAI` and `AsyncOpenAI` clients): `batches.create`, `beta.agents.sessions.create`, `beta.agents.sessions.events.create`, `beta.agents.sessions.events.stream`, `beta.agents.sessions.stream`, `beta.agents.sessions.update`, `beta.chatkit.sessions.create`, `beta.realtime.connect`, `beta.responses.compact`, `beta.responses.connect`, `beta.responses.create`, `beta.threads.create_and_run`, `beta.threads.create_and_run_poll`, `beta.threads.create_and_run_stream`, `beta.threads.runs.create`, `beta.threads.runs.create_and_poll`, `beta.threads.runs.create_and_stream`, `beta.threads.runs.stream`, `beta.threads.runs.submit_tool_outputs`, `beta.threads.runs.submit_tool_outputs_and_poll`, `beta.threads.runs.submit_tool_outputs_stream`, `completions.create`, `decisions.create`, `evals.runs.create`, `fine_tuning.alpha.graders.run`, `fine_tuning.jobs.create`, `images.create_variation`, `images.edit`, `images.generate`, `live.connect`, `live.create`, `live.forks.connect`, `live.sessions.accept`, `live.sessions.fork`, `live.sideband.connect`, `realtime.calls.accept`, `realtime.calls.create`, `realtime.connect`, `responses.compact`, `responses.connect`, `videos.create`, `videos.create_and_poll`, `videos.create_character`, `videos.edit`, `videos.extend`, `videos.remix`
|
|
196
|
+
- **Anthropic** (`Anthropic` and `AsyncAnthropic` clients): `beta.deployments.run`, `beta.dreams.create`, `beta.environments.work.poller`, `beta.environments.work.worker`, `beta.messages.batches.create`, `beta.sessions.create`, `beta.sessions.events.send`, `beta.sessions.events.stream`, `beta.sessions.events.tool_runner`, `beta.sessions.threads.events.stream`, `messages.batches.create`
|
|
197
|
+
- **Google Gemini** (`google.genai` `Client` and `Client.aio`): `batches.create`, `batches.create_embeddings`, `caches.create`, `caches.update`, `file_search_stores.import_file`, `file_search_stores.upload_to_file_search_store`, `interactions.create`, `live.connect`, `live.music.connect`, `models.edit_image`, `models.recontext_image`, `models.segment_image`, `models.upscale_image`, `triggers.run`, `tunings.tune`
|
|
198
|
+
- **Google Vertex AI** (`vertexai` classes): `batch_prediction.BatchPredictionJob.submit`, `caching.CachedContent.create`, `caching.CachedContent.update`, `language_models.ChatModel.tune_model`, `language_models.ChatModel.tune_model_rlhf`, `language_models.ChatSession.send_message`, `language_models.ChatSession.send_message_async`, `language_models.ChatSession.send_message_streaming`, `language_models.ChatSession.send_message_streaming_async`, `language_models.CodeChatModel.tune_model`, `language_models.CodeChatSession.send_message`, `language_models.CodeChatSession.send_message_async`, `language_models.CodeChatSession.send_message_streaming`, `language_models.CodeChatSession.send_message_streaming_async`, `language_models.CodeGenerationModel.batch_predict`, `language_models.CodeGenerationModel.predict`, `language_models.CodeGenerationModel.predict_async`, `language_models.CodeGenerationModel.predict_streaming`, `language_models.CodeGenerationModel.predict_streaming_async`, `language_models.CodeGenerationModel.tune_model`, `language_models.TextEmbeddingModel.batch_predict`, `language_models.TextEmbeddingModel.deploy_tuned_model`, `language_models.TextEmbeddingModel.tune_model`, `language_models.TextGenerationModel.batch_predict`, `language_models.TextGenerationModel.predict`, `language_models.TextGenerationModel.predict_async`, `language_models.TextGenerationModel.predict_streaming`, `language_models.TextGenerationModel.predict_streaming_async`, `language_models.TextGenerationModel.tune_model`, `language_models.TextGenerationModel.tune_model_rlhf`, `preview.caching.CachedContent.create`, `preview.caching.CachedContent.update`, `preview.vision_models.ImageCaptioningModel.get_captions`, `preview.vision_models.ImageGenerationModel.upscale_image`, `preview.vision_models.ImageQnAModel.ask_question`, `preview.vision_models.ImageSegmentationModel.segment_image`, `preview.vision_models.ImageTextModel.ask_question`, `preview.vision_models.ImageTextModel.get_captions`, `preview.vision_models.MultiModalEmbeddingModel.get_embeddings`, `preview.vision_models.WatermarkVerificationModel.verify_image`, `tuning.sft.train`, `vision_models.ImageCaptioningModel.get_captions`, `vision_models.ImageGenerationModel.upscale_image`, `vision_models.ImageQnAModel.ask_question`, `vision_models.ImageTextModel.ask_question`, `vision_models.ImageTextModel.get_captions`, `vision_models.MultiModalEmbeddingModel.get_embeddings`
|
|
199
|
+
- **AWS Bedrock** (boto3 bedrock-runtime client; Claude models are metered when REVENIUM_BEDROCK_TRANSPORT is on): `apply_guardrail`, `converse`, `converse_stream`, `invoke_guardrail_checks`, `invoke_model`, `invoke_model_with_response_stream`, `start_async_invoke`
|
|
200
|
+
- **Perplexity** (`Perplexity` and `AsyncPerplexity` clients): `async_.chat.completions.create`, `browser.sessions.create`, `contextualized_embeddings.create`, `embeddings.create`, `responses.create`, `search.create`
|
|
201
|
+
- **LiteLLM** (the `litellm` module): `aadapter_completion`, `aadapter_generate_content`, `acode_interpreter_tool`, `acompact_responses`, `acreate_batch`, `acreate_fine_tuning_job`, `acreate_run`, `acreate_sandbox`, `adapter_completion`, `adecisions`, `agenerate_content`, `aimage_edit`, `aimage_generation`, `aimage_variation`, `aingest`, `anthropic_interface.messages.acreate`, `anthropic_interface.messages.create`, `anthropic_messages`, `anthropic_messages_handler`, `aocr`, `aquery`, `arealtime_calls`, `arerank`, `aresponses`, `aresponses_api_with_mcp`, `aresponses_with_retries`, `arun_code`, `arun_thread`, `arun_thread_stream`, `asearch`, `aspeech`, `asystemone`, `atranscription`, `avideo_create_character`, `avideo_edit`, `avideo_extension`, `avideo_generation`, `avideo_remix`, `compact_responses`, `config_completion`, `create_batch`, `create_fine_tuning_job`, `create_run`, `decisions`, `image_edit`, `image_generation`, `image_variation`, `ingest`, `nlp_cloud_chat_completion`, `ocr`, `query`, `replicate_chat_completion`, `rerank`, `responses`, `responses_with_retries`, `run_thread`, `run_thread_stream`, `search`, `speech`, `systemone`, `transcription`, `video_create_character`, `video_edit`, `video_extension`, `video_generation`, `video_remix`
|
|
202
|
+
- **Ollama** (`Client`, `AsyncClient` and the `ollama` module): `systemone`, `web_fetch`, `web_search`
|
|
203
|
+
- **fal.ai** (`SyncClient`, `AsyncClient` and the `fal_client` module): `realtime`, `realtime_async`, `ws_connect`, `ws_connect_async`
|
|
204
|
+
- **LangChain** (embeddings models from vendors other than OpenAI, Azure OpenAI and Ollama, such as `MistralAIEmbeddings`): `Embeddings.aembed_documents`, `Embeddings.aembed_query`, `Embeddings.embed_documents`, `Embeddings.embed_query`
|
|
205
|
+
<!-- not-metered:end -->
|
|
206
|
+
|
|
207
|
+
Raw boto3 calls to AWS Bedrock send no usage record for any model unless `REVENIUM_BEDROCK_TRANSPORT` is set to `1` or `true`; with it set, Claude models on `invoke_model`, `invoke_model_with_response_stream`, `converse` and `converse_stream` are metered, and other models still are not. Claude through `AnthropicBedrock` is metered either way. `boto3.client("bedrock-agent-runtime")` (`invoke_agent`, `retrieve_and_generate`), Bedrock batch inference through `boto3.client("bedrock").create_model_invocation_job`, and Vertex AI `evaluation`, `agent_engines` and `rag` are also not metered and are outside the check.
|
|
208
|
+
|
|
209
|
+
LiteLLM's `transcription` and `atranscription` calls to OpenAI models are recorded when `revenium_middleware.openai` is also imported, because LiteLLM sends them through the OpenAI SDK, which that integration meters; that record carries none of the `usage_metadata` passed to LiteLLM. Without that import they are not recorded.
|
|
210
|
+
|
|
166
211
|
## Installation
|
|
167
212
|
|
|
168
213
|
```bash
|
|
@@ -274,6 +319,8 @@ Emit per-agent terminal outcomes (`CONVERTED`, `DEFLECTED`, `ESCALATED`) alongsi
|
|
|
274
319
|
|
|
275
320
|
> **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`.
|
|
276
321
|
|
|
322
|
+
Outcome, job and job-type economics calls go to the same Revenium address as usage records: `REVENIUM_METERING_BASE_URL`, or `https://api.revenium.ai` when it is unset. Set `REVENIUM_PROFITSTREAM_BASE_URL`, or pass `profitstream_base_url=`, only when outcomes live at a different address.
|
|
323
|
+
|
|
277
324
|
### Job-Type Economics and Outcome Facts
|
|
278
325
|
|
|
279
326
|
Keep a metering key for AI telemetry and a separate write key for outcomes and
|
|
@@ -355,8 +402,10 @@ with JobContext("loan-app-12345", type="loan_processing", version="2.1") as job:
|
|
|
355
402
|
```
|
|
356
403
|
|
|
357
404
|
- **Async:** `async with JobContext(...) as job:` works identically.
|
|
358
|
-
- **Auto-FAILED:** if an unhandled exception escapes the block
|
|
359
|
-
- **
|
|
405
|
+
- **Auto-FAILED:** if an unhandled exception escapes the block, the context automatically reports `execution_status="FAILED"` (the exception's class in `metadata.error`, `metadata.errorType` and the outcome reason; its message too when `REVENIUM_CAPTURE_ERROR_MESSAGES=true`, redacted as for failed tool events and capped at 2048 characters; an exception from a provider's HTTP error, which can quote the request, sends its class only unless `REVENIUM_CAPTURE_PROMPTS=true` as well) and always re-raises the original exception. It skips the FAILED when a `report_outcome` or `amend_outcome` call succeeded, the platform answered that the job already has an outcome, the exception escaping the block is the one your own `report_outcome`/`amend_outcome` raised, or that call found no such job (404). So a report you caught that failed, followed by a crash, still gets FAILED. If the caught report was in fact stored (a timeout after the platform saved it), the automatic FAILED is refused as already reported and only logged; the stored outcome stands.
|
|
406
|
+
- **Job id format:** Revenium refuses any other job id on AI calls, so a job id must start with an ASCII letter or digit, contain only ASCII letters, digits, `.`, `_` and `-`, be at most 255 characters, and not be `types` or `conversion-funnel`. Entering `JobContext` with any other id raises `ValueError` before any call is made. `JobContext.attach()` still accepts such an id, for reporting on a job created with `create_job`. An id from `usage_metadata`, `@track_job`, `REVENIUM_AGENTIC_JOB_ID` or proxy headers that breaks the rule is left off the call: the call is still metered, a warning is logged once per id, and the call does not fall back to the surrounding job's id. AI calls never create a job under such an id, so `report_outcome` on it fails with a 404 after its retries unless the job was created with `create_job`.
|
|
407
|
+
- **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()`, the job reads in [Reading Jobs Back](#reading-jobs-back), and the CrewAI wrapper's `report_job_outcome`/`amend_job_outcome`.
|
|
408
|
+
- **Retry after a gateway error:** when a gateway answers 502, 503 or 504 and the retry is then refused as already reported, the SDK reads the job once and treats the report as delivered if the stored outcome is the one it sent, unamended. An identical outcome stored by another writer in that gap is reported as success too; the reporter label (`reported_by`) and `metrics` facts are not checked. A timeout or connection error on the report itself is not retried.
|
|
360
409
|
- **Team resolution:** explicit `team_id=` > `REVENIUM_TEAM_ID` > automatic resolution from the API key; `OutcomeReportingError` is raised if none of these yields a team.
|
|
361
410
|
- **Nesting:** a nested `JobContext` is a different job (replace, not merge); exiting the inner context restores the outer job's fields.
|
|
362
411
|
|
|
@@ -403,7 +452,7 @@ except OutcomeAmendConflictError as conflict:
|
|
|
403
452
|
expected_entity_version=conflict.current_entity_version)
|
|
404
453
|
```
|
|
405
454
|
|
|
406
|
-
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;
|
|
455
|
+
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; read it with `get_job(job_id)["entityVersion"]`; 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.
|
|
407
456
|
|
|
408
457
|
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.
|
|
409
458
|
|
|
@@ -441,12 +490,40 @@ handle.close()
|
|
|
441
490
|
|
|
442
491
|
- **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.
|
|
443
492
|
- **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.
|
|
444
|
-
- **
|
|
493
|
+
- **One active fact per key:** a job keeps one active fact for each metric key. Appending a key the job already has supersedes the earlier fact (the earlier fact is deactivated, not deleted), and the platform refuses that append with a 400 unless the entry carries a `reason`. The same key twice in one request is refused. The SDK sends entries as written and never dedupes them. `metrics=` on `amend_outcome()` records facts as part of the amendment; a repeated key there also supersedes the earlier fact, and the amendment's own reason (or the platform's automated reason for an API-key caller) is used when an entry has none.
|
|
445
494
|
- **Not part of outcome history:** `get_outcome_history()` returns the outcome revisions only — appended facts do not appear in those rows.
|
|
446
|
-
- **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
|
|
495
|
+
- **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 resending a key that is already recorded is a correction, refused without a `reason` and, with one, superseding the fact, so the decision to resend is yours (check the recorded facts first).
|
|
447
496
|
- **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.)
|
|
448
497
|
- **Why it matters:** AI Alerts evaluate `QUALITY_RATE` from these facts, so a job whose integration emits none is invisible to those rules.
|
|
449
498
|
|
|
499
|
+
### Reading Jobs Back
|
|
500
|
+
|
|
501
|
+
These calls need a write-scope key (`rev_sk_`), like every other outcome call. A metering key (`rev_mk_`) is rejected before any request.
|
|
502
|
+
|
|
503
|
+
```python
|
|
504
|
+
from revenium_middleware import (
|
|
505
|
+
get_conversion_funnel, get_job, get_job_roi, get_job_transactions,
|
|
506
|
+
get_job_types, list_jobs,
|
|
507
|
+
)
|
|
508
|
+
|
|
509
|
+
page = list_jobs(job_type="loan_processing", execution_status="SUCCESS", size=50)
|
|
510
|
+
for job in page["content"]:
|
|
511
|
+
print(job["agenticJobId"], job["outcomeType"])
|
|
512
|
+
|
|
513
|
+
version = get_job("loan-app-12345")["entityVersion"]
|
|
514
|
+
types = get_job_types()
|
|
515
|
+
roi = get_job_roi("loan-app-12345")["roi"]
|
|
516
|
+
calls = get_job_transactions("loan-app-12345")["transactions"]
|
|
517
|
+
rate = get_conversion_funnel(
|
|
518
|
+
start_date="2026-09-01T00:00:00Z", end_date="2026-09-30T23:59:59Z",
|
|
519
|
+
)["conversionRate"]
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
- **Results are the API's JSON:** each call returns dicts with the field names the API sends (camelCase), so a field the platform adds later reaches you without an SDK upgrade.
|
|
523
|
+
- **Paging:** `list_jobs` returns `{"content": [...], "page": {...}}`; `page` is 0-based and only the filters you pass are sent.
|
|
524
|
+
- **Missing job:** a job that does not exist raises `httpx.HTTPStatusError` (404).
|
|
525
|
+
- **Team and retries:** team resolution and the retry knobs work as for `get_outcome_history()`.
|
|
526
|
+
|
|
450
527
|
### Outcome Exceptions
|
|
451
528
|
|
|
452
529
|
All outcome exceptions are importable from `revenium_middleware` and share the `OutcomeReportingError` base, so `except OutcomeReportingError:` catches the whole family:
|
|
@@ -475,6 +552,16 @@ client.append_outcome_metrics(job_id, [...]) # append declared per-job facts la
|
|
|
475
552
|
client.close()
|
|
476
553
|
```
|
|
477
554
|
|
|
555
|
+
In an `emit_completion` payload the agent is named by `agent`. `agentName` and `currency` are not sent (Revenium does not store them); `emit_completion` names them in its one-time warning about unsent keys.
|
|
556
|
+
|
|
557
|
+
`emit_completion` and `emit_tool_event` queue the record and return at once, like every automatic record: the SDK's background threads send it with the same timeouts and retries (see [Metering Delivery and Timeouts](#metering-delivery-and-timeouts)), and a record that fails with a timeout, a refused connection or a 5xx goes to the store-and-forward buffer and is sent when Revenium is reachable again. Delivery errors are logged, not raised; `emit_completion` still raises `ValueError` before anything is queued when the payload is missing a required key. Both calls return the payload you passed.
|
|
558
|
+
|
|
559
|
+
Records go to the address set in code with `initialize_metering(base_url=...)` or a `metering_key(..., base_url=...)` block when one is set, else `REVENIUM_METERING_BASE_URL`; pass `meter_base_url=` to `AgenticOutcomeSettings` to pin another address. They are always sent under the settings' `api_key`, never a `metering_key()` key. `http_client=` serves jobs and outcomes only.
|
|
560
|
+
|
|
561
|
+
A script that emits many records and exits right away has `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` (default 5) to send the records still queued; raise it if records are reported unsent at exit.
|
|
562
|
+
|
|
563
|
+
`emit_tool_event` sends one `Idempotency-Key` per call and reuses it when the buffer replays the event, so a tool event replayed after a gateway error is stored once.
|
|
564
|
+
|
|
478
565
|
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`.
|
|
479
566
|
|
|
480
567
|
See [`examples/agentic_outcomes/`](examples/agentic_outcomes/) for runnable demos (sales / coding / support) with configurable failure rates and outcome distributions.
|
|
@@ -504,6 +591,16 @@ with idempotency_key(f"order-{order_id}"):
|
|
|
504
591
|
|
|
505
592
|
The context manager is backed by `contextvars`, so it scopes correctly across threads and asyncio tasks.
|
|
506
593
|
|
|
594
|
+
### Several calls in one block
|
|
595
|
+
|
|
596
|
+
- Each model call in a block gets its own key: `order-42`, then `order-42:2`, `order-42:3` and so on, in the order its usage record is delivered. That can differ from the order the calls were made, because records are delivered in the background. Every call in the block is recorded.
|
|
597
|
+
- A retry the SDK makes itself (an HTTP retry, or a replay from the delivery buffer) reuses the same key and is stored once.
|
|
598
|
+
- Rerunning the same block is refused call by call, up to the number of calls the original block made: each refusal is logged and counted as a metering error, and the rerun's provider spend is not recorded. Calls beyond the original count are recorded.
|
|
599
|
+
- A block key that ends in `:<number>`, such as `order-42:2`, can collide with another block's derived keys. Avoid that shape.
|
|
600
|
+
- Tool events are not keyed by the block; each tool event carries its own key (see [Tool Metering](#tool-metering)).
|
|
601
|
+
- fal queue jobs are not keyed by the block either; each job's record uses its own key, `fal-<request id>` (see [fal.ai](#falai)).
|
|
602
|
+
- If a derived key would be longer than 255 characters, the SDK uses the SHA-256 hex digest of the block key in its place, so the key stays valid and the same on every rerun.
|
|
603
|
+
|
|
507
604
|
### Backend behavior
|
|
508
605
|
|
|
509
606
|
| Scenario | Backend response |
|
|
@@ -518,7 +615,7 @@ See [docs.revenium.io/integrations/idempotency](https://docs.revenium.io/integra
|
|
|
518
615
|
|
|
519
616
|
### Key format
|
|
520
617
|
|
|
521
|
-
`Idempotency-Key` must be 1–255 printable ASCII characters. UUID v4 is the recommended format and what the SDK generates by default.
|
|
618
|
+
`Idempotency-Key` must be 1–255 printable ASCII characters, with no leading or trailing spaces. `idempotency_key()` and `set_idempotency_key()` raise `ValueError` for an empty key and for any other key that breaks this rule (an accented or non-Latin letter, a line break, a tab, a leading or trailing space, or more than 255 characters), before anything in the block runs. UUID v4 is the recommended format and what the SDK generates by default.
|
|
522
619
|
|
|
523
620
|
---
|
|
524
621
|
|
|
@@ -579,7 +676,7 @@ Webhook deliveries without a configured signing secret arrive without HMAC heade
|
|
|
579
676
|
|
|
580
677
|
### OpenAI
|
|
581
678
|
|
|
582
|
-
Supports chat completions, streaming, embeddings, function calling,
|
|
679
|
+
Supports chat completions, streaming, embeddings, function calling, vision/multimodal, and audio (speech, transcription and translation).
|
|
583
680
|
|
|
584
681
|
```python
|
|
585
682
|
from dotenv import load_dotenv
|
|
@@ -619,9 +716,28 @@ embedding = client.embeddings.create(
|
|
|
619
716
|
)
|
|
620
717
|
```
|
|
621
718
|
|
|
719
|
+
A chat or Responses call the provider refuses (a 400, 429 or 500, for example), streamed or not, sends one record with stop reason `ERROR`, zero tokens and the error's class and HTTP status as its error reason (plus the provider's redacted error message when both `REVENIUM_CAPTURE_ERROR_MESSAGES` and `REVENIUM_CAPTURE_PROMPTS` are `true`; a provider's error can quote the request, so it is never sent with prompt capture off), cut to 255 characters with its "(HTTP <status>)" ending kept; a stream that breaks off part-way is recorded with stop reason `ERROR` too. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer (a connection error, a timeout, or a stream that broke off) has none. Your code still gets the original exception. Embeddings, `parse()` and calls a spending cap refuses send no error record.
|
|
720
|
+
|
|
721
|
+
#### Audio
|
|
722
|
+
|
|
723
|
+
`audio.transcriptions.create`, `audio.translations.create` and `audio.speech.create` (sync, async, `with_raw_response` and `with_streaming_response`, on `OpenAI` and `AzureOpenAI`) each send one audio record, with `usage_metadata` attribution like a chat call. Spending caps apply to them as they do to chat.
|
|
724
|
+
|
|
725
|
+
```python
|
|
726
|
+
transcript = client.audio.transcriptions.create(model="whisper-1", file=open("call.mp3", "rb"))
|
|
727
|
+
speech = client.audio.speech.create(model="tts-1", voice="alloy", input="Your order has shipped.")
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
What each record carries:
|
|
731
|
+
- **Transcription and translation:** the audio seconds OpenAI bills (`usage.seconds`, else the `duration` of a `verbose_json` response), or, for models OpenAI bills by token (`gpt-4o-transcribe`, `gpt-4o-mini-transcribe`), the input, output and audio input tokens. A streamed transcription is recorded once, when the stream ends or is closed.
|
|
732
|
+
- **Speech:** the number of characters in `input`, plus `voice`, `speed` and `response_format`. The audio itself is never read.
|
|
733
|
+
|
|
734
|
+
Some calls report no duration, so their record is stored with a duration of zero and no cost: transcriptions with `response_format` `text`, `srt` or `vtt`, translations in the default `json` format (use `verbose_json` to get the duration), anything called through `with_streaming_response`, and a `with_raw_response` call with `stream=True`. Revenium may also show $0 for models it prices by token, such as `gpt-4o-mini-tts`, as it does for the Go and Node SDKs.
|
|
735
|
+
|
|
736
|
+
If a LiteLLM gateway with `ReveniumGuardrail` also imports `revenium_middleware.openai`, an OpenAI audio call proxied through it is recorded twice; import only the LiteLLM integration in the gateway process.
|
|
737
|
+
|
|
622
738
|
#### Azure OpenAI
|
|
623
739
|
|
|
624
|
-
The middleware automatically detects Azure OpenAI when using `AzureOpenAI()` and resolves deployment names to standard model names for accurate pricing.
|
|
740
|
+
The middleware automatically detects Azure OpenAI when using `AzureOpenAI()` and resolves deployment names to standard model names for accurate pricing. The model Azure reports (for example `gpt-4.1-nano-2025-04-14`) is recorded as is; a custom deployment name is mapped to its model family.
|
|
625
741
|
|
|
626
742
|
```python
|
|
627
743
|
from openai import AzureOpenAI
|
|
@@ -647,6 +763,30 @@ response = client.chat.completions.create(
|
|
|
647
763
|
|
|
648
764
|
**Examples:** `examples/openai/` - `openai_basic.py`, `openai_streaming.py`, `azure_basic.py`, `azure_streaming.py`
|
|
649
765
|
|
|
766
|
+
#### xAI (Grok)
|
|
767
|
+
|
|
768
|
+
Point the OpenAI client at xAI and calls are recorded with provider `XAI`, so xAI spend is priced and reported as xAI rather than OpenAI.
|
|
769
|
+
|
|
770
|
+
A spending cap on a Grok model also stops calls that use the short names xAI publishes for it, such as `grok-4.20`; see [Cost Controls / Enforcement](#cost-controls--enforcement) for how model filters treat vendor aliases.
|
|
771
|
+
|
|
772
|
+
On a Grok reasoning model the reasoning tokens xAI bills are counted as output, and each record carries xAI's own charge for the call (`cost_in_usd_ticks`) as its total cost. This applies when the client's base URL is on `x.ai`; Grok reached through a proxy or gateway is recorded as the OpenAI-compatible call it appears to be.
|
|
773
|
+
|
|
774
|
+
```python
|
|
775
|
+
import os
|
|
776
|
+
from openai import OpenAI
|
|
777
|
+
import revenium_middleware.openai
|
|
778
|
+
|
|
779
|
+
client = OpenAI(
|
|
780
|
+
api_key=os.getenv("XAI_API_KEY"),
|
|
781
|
+
base_url="https://api.x.ai/v1"
|
|
782
|
+
)
|
|
783
|
+
|
|
784
|
+
response = client.chat.completions.create(
|
|
785
|
+
model="grok-4.20-0309-non-reasoning",
|
|
786
|
+
messages=[{"role": "user", "content": "Hello!"}]
|
|
787
|
+
)
|
|
788
|
+
```
|
|
789
|
+
|
|
650
790
|
---
|
|
651
791
|
|
|
652
792
|
### Anthropic
|
|
@@ -709,11 +849,13 @@ async def main():
|
|
|
709
849
|
asyncio.run(main())
|
|
710
850
|
```
|
|
711
851
|
|
|
712
|
-
**Note:** The middleware
|
|
852
|
+
**Note:** The middleware meters `messages.create` (including `create(stream=True)`), `messages.stream` and `messages.parse`, and the same calls on `client.beta.messages` (`create`, `stream`, `parse` and each step of `tool_runner`), sync and async, including their `with_raw_response` and `with_streaming_response` forms, on the Anthropic, Bedrock and Vertex AI clients. Calls listed under [Calls the SDK does not meter](#calls-the-sdk-does-not-meter), message batches among them, are not metered.
|
|
853
|
+
|
|
854
|
+
A call the provider refuses sends one record with stop reason `ERROR`, zero tokens and the error's class and HTTP status as its error reason (plus the provider's redacted error message when both `REVENIUM_CAPTURE_ERROR_MESSAGES` and `REVENIUM_CAPTURE_PROMPTS` are `true`; a provider's error can quote the request, so it is never sent with prompt capture off; at most 255 characters, keeping its "(HTTP <status>)" ending), as does a `create(stream=True)` stream that breaks off part-way. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer (a connection error, a timeout, or a stream that broke off) has none. Your code still gets the original exception. Calls served through the Bedrock fast path, and calls a spending cap refuses, send no error record.
|
|
713
855
|
|
|
714
856
|
#### AWS Bedrock
|
|
715
857
|
|
|
716
|
-
The middleware
|
|
858
|
+
The middleware meters Claude on AWS Bedrock through `AnthropicBedrock`, with automatic detection.
|
|
717
859
|
|
|
718
860
|
```python
|
|
719
861
|
import anthropic
|
|
@@ -742,9 +884,12 @@ message = client.messages.create(
|
|
|
742
884
|
| Variable | Description | Default |
|
|
743
885
|
|----------|-------------|---------|
|
|
744
886
|
| `AWS_REGION` | AWS region for Bedrock | `us-east-1` |
|
|
745
|
-
| `REVENIUM_BEDROCK_DISABLE` | Set to `1` to disable Bedrock support (Bedrock detection only - Foundry detection is unaffected) | Not set |
|
|
887
|
+
| `REVENIUM_BEDROCK_DISABLE` | Set to `1` to disable Bedrock support for Anthropic clients (Bedrock detection only - Foundry detection is unaffected). Raw boto3 calls metered with `REVENIUM_BEDROCK_TRANSPORT`, and LangChain's `ChatBedrock` and `ChatBedrockConverse`, are still recorded as AWS | Not set |
|
|
888
|
+
| `REVENIUM_BEDROCK_TRANSPORT` | Set to `1` or `true` to meter Claude models called through a raw `boto3.client("bedrock-runtime")` (`invoke_model`, `invoke_model_with_response_stream`, `converse`, `converse_stream`); other Bedrock models are never metered this way | Not set |
|
|
889
|
+
|
|
890
|
+
**AWS authentication**: an `AnthropicBedrock` client uses its own `aws_access_key` / `aws_secret_key` / `aws_session_token`, `aws_profile` or Bedrock `api_key`, exactly as without the middleware. A plain `anthropic.Anthropic` client with a Bedrock `base_url` uses the standard credential chain: environment variables, `~/.aws/credentials`, IAM roles, AWS SSO. Required permissions: `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream`.
|
|
746
891
|
|
|
747
|
-
**
|
|
892
|
+
**Raw boto3 calls, application inference profiles and Provisioned Throughput**: with `REVENIUM_BEDROCK_TRANSPORT=1`, raw `boto3.client("bedrock-runtime")` calls to Claude (`invoke_model`, `invoke_model_with_response_stream`, `converse`, `converse_stream`) are metered and capped. A call written as a cross-Region inference profile ARN or a foundation model ARN is recorded and priced under the model id the ARN names (`us.anthropic.claude-haiku-4-5-20251001-v1:0`, `anthropic.claude-haiku-4-5-20251001-v1:0`), as the same call by that plain id is. A Claude call through an application inference profile ARN (`arn:aws:bedrock:<region>:<account>:application-inference-profile/<id>`) also needs `bedrock:GetInferenceProfile`, and one through a Provisioned Throughput ARN (`arn:aws:bedrock:<region>:<account>:provisioned-model/<id>`) needs `bedrock:GetProvisionedModelThroughput`, because neither ARN names the model: the SDK looks each ARN up once per process, in the background, starting at its first call, and from then on records and caps the call under the Claude model it runs. The lookup never delays your call: calls made before it answers, usually only the first in a process, are neither metered nor capped. The lookup uses the proxy, client certificate and CA bundle set on your boto3 client. A Provisioned Throughput call is recorded under its foundation model (for example `anthropic.claude-haiku-4-5-20251001-v1:0`), so the cost Revenium shows is the on-demand equivalent of its tokens, not the hourly price AWS bills, and a cost cap fills at that rate: a breached cost BLOCK cap can stop calls on capacity you have already paid for. Without the permission the call still goes through, unmetered and uncapped, and the SDK logs one warning per ARN. A lookup that fails for a temporary reason (an outage, a dropped connection, an expired session token) is retried every 5 minutes in the background. Profiles and Provisioned Throughputs that run a non-Claude model are not metered. A profile copied from a US or EU cross-Region profile is recorded and priced as that profile (for example `us.anthropic.claude-haiku-4-5-20251001-v1:0`), so its cost matches the regional rate AWS bills. A profile copied from an Australia, Japan, APAC, India or global cross-Region profile, or on a single Region, is recorded under the model id (`anthropic.claude-haiku-4-5-20251001-v1:0`). A cap on either id or on the Claude model name (`claude-haiku-4-5-20251001`) applies to the call. With cost controls on, a sync `AnthropicBedrock` call by an application inference profile ARN is also capped under the Claude model the profile routes to, using the same once-per-process lookup and the same `bedrock:GetInferenceProfile` permission; without the permission it is still metered but cannot be capped by model. A failed lookup is remembered only for the credentials that made it, so a client with the permission still looks the profile up and is metered and capped. An `AsyncAnthropicBedrock` call by a profile is capped that way once the profile has been looked up by a sync or raw boto3 call in the same process.
|
|
748
893
|
|
|
749
894
|
**Supported Bedrock models:**
|
|
750
895
|
|
|
@@ -796,13 +941,13 @@ that Foundry bills at. `AsyncAnthropicFoundry` is metered the same way, as is
|
|
|
796
941
|
|
|
797
942
|
### Google AI (Gemini / Vertex AI)
|
|
798
943
|
|
|
799
|
-
Supports chat completions, streaming, embeddings, image generation (Imagen), and vision/multimodal.
|
|
944
|
+
Supports chat completions, streaming, embeddings, image generation (Imagen), and vision/multimodal. The Google AI SDK (`google-genai`) is the recommended path for both the Gemini Developer API (API key) and Vertex AI (`genai.Client(vertexai=True, ...)`): it counts chat tokens on both, and embedding tokens on Vertex AI. The SDK still meters calls made through the Vertex AI SDK (`vertexai`), but Google deprecated that SDK's generative AI modules (`generative_models`, `language_models`, `vision_models`) and its releases after June 24, 2026 do not include them; see [Google's notice](https://cloud.google.com/vertex-ai/generative-ai/docs/deprecations/genai-vertexai-sdk). Use google-genai with `vertexai=True` for new work.
|
|
800
945
|
|
|
801
946
|
```bash
|
|
802
|
-
# Google AI SDK
|
|
947
|
+
# Google AI SDK (Gemini Developer API, or Vertex AI with vertexai=True)
|
|
803
948
|
pip install "revenium-python-sdk[google-genai]"
|
|
804
949
|
|
|
805
|
-
# Vertex AI SDK
|
|
950
|
+
# Vertex AI SDK (vertexai package)
|
|
806
951
|
pip install "revenium-python-sdk[google-vertex]"
|
|
807
952
|
```
|
|
808
953
|
|
|
@@ -827,7 +972,21 @@ response = client.models.generate_content(
|
|
|
827
972
|
print(response.text)
|
|
828
973
|
```
|
|
829
974
|
|
|
830
|
-
|
|
975
|
+
The same call on Vertex AI, with the same metering:
|
|
976
|
+
|
|
977
|
+
```python
|
|
978
|
+
client = genai.Client(vertexai=True, project="your-gcp-project", location="us-central1")
|
|
979
|
+
response = client.models.generate_content(
|
|
980
|
+
model="gemini-2.0-flash-001",
|
|
981
|
+
contents="Hello! Introduce yourself in one sentence.",
|
|
982
|
+
usage_metadata={"organizationName": "AcmeCorp", "task_type": "chat"}
|
|
983
|
+
)
|
|
984
|
+
print(response.text)
|
|
985
|
+
```
|
|
986
|
+
|
|
987
|
+
#### Vertex AI SDK (deprecated by Google)
|
|
988
|
+
|
|
989
|
+
Google deprecated the generative AI modules of this SDK; see the notice above. Use the google-genai example above for new code.
|
|
831
990
|
|
|
832
991
|
```python
|
|
833
992
|
from dotenv import load_dotenv
|
|
@@ -848,11 +1007,15 @@ print(response.text)
|
|
|
848
1007
|
| Use Case | Recommended SDK | Why |
|
|
849
1008
|
|----------|----------------|-----|
|
|
850
1009
|
| Quick prototyping | Google AI SDK | Simple API key setup |
|
|
851
|
-
| Production applications |
|
|
852
|
-
| Embeddings-heavy workloads |
|
|
853
|
-
|
|
|
1010
|
+
| Production applications | Google AI SDK with `vertexai=True` | Full token counting, including embeddings, on Vertex AI |
|
|
1011
|
+
| Embeddings-heavy workloads | Google AI SDK with `vertexai=True` | Vertex AI returns a token count for every embedded text |
|
|
1012
|
+
| Existing Vertex AI SDK code | Vertex AI SDK (deprecated by Google) | Still metered; migrate to google-genai with `vertexai=True` |
|
|
854
1013
|
|
|
855
|
-
**Note:**
|
|
1014
|
+
**Note:** On Vertex AI (`genai.Client(vertexai=True, ...)`) google-genai embeddings are recorded with the input tokens Google returns for every text. The Gemini API (API key) returns no token count for embeddings, so those calls are recorded with 0 tokens, and still tracked.
|
|
1015
|
+
|
|
1016
|
+
A `generate_content` or `generate_content_stream` call through the Google AI SDK (the Gemini API, or Vertex AI with `genai.Client(vertexai=True)`) that Google refuses (a 429 or 500, for example), sync, async or streamed, sends one record with stop reason `ERROR`, zero tokens and the error's class and HTTP status as its error reason; a stream that breaks off part-way is recorded with stop reason `ERROR` too. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer (a connection error, a timeout, or a stream that broke off) has none. Your code still gets Google's own exception. Embeddings, Imagen, Veo, calls made with the `vertexai` library and calls a spending cap refuses send no error record.
|
|
1017
|
+
|
|
1018
|
+
**Images from Gemini image models:** an image made with `generate_content` or `generate_content_stream` on a Gemini image model (for example `gemini-3.1-flash-lite-image`), through google-genai (the Gemini API, or `genai.Client(vertexai=True)`) or the `vertexai` library, sync, async or streamed, sends two records that share the call's trace, job and customer. An image record (operation type `IMAGE`, transaction id the chat record's plus `-image`) carries the number of images and is priced at the model's per-image price in Revenium; the chat record carries only the answer's text tokens, with the image tokens Google reports removed. Known limits: the per-image price is one fixed price per model, so 2K and 4K images are under-billed; interim "thought" images are not counted, only the final images are; when Google does not report the image's token share, the image tokens also stay on the chat record; a call that fails or a stream that breaks off is recorded as chat only. Gemini images made through LiteLLM (`gemini/...`), the LangChain unified handler fallback or griptape are still recorded as chat.
|
|
856
1019
|
|
|
857
1020
|
**Google AI environment variables:**
|
|
858
1021
|
- `GOOGLE_API_KEY` - For Google AI SDK
|
|
@@ -905,6 +1068,8 @@ response = ollama.embed(model='nomic-embed-text', input=['Text 1', 'Text 2', 'Te
|
|
|
905
1068
|
|
|
906
1069
|
**Supported endpoints:** `chat()`, `generate()`, `embed()` and the legacy `embeddings()`, whether called at module level (`ollama.chat()`) or on an explicit client such as `ollama.Client(host="http://my-ollama:11434")` or `ollama.AsyncClient(...)`, streamed or not.
|
|
907
1070
|
|
|
1071
|
+
A `chat()` or `generate()` call the Ollama server refuses (a 500, for example), streamed or not, sends one record with stop reason `ERROR`, zero tokens and the error's class and HTTP status as its error reason; a stream that breaks off part-way is recorded with stop reason `ERROR` too. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer (a connection error, a timeout, or a stream that broke off) has none. Your code still gets Ollama's own exception. Embeddings and calls a spending cap refuses send no error record.
|
|
1072
|
+
|
|
908
1073
|
**OpenAI compatibility mode:** You can also use Ollama with the OpenAI SDK:
|
|
909
1074
|
|
|
910
1075
|
```python
|
|
@@ -954,15 +1119,16 @@ response = litellm.completion(
|
|
|
954
1119
|
)
|
|
955
1120
|
```
|
|
956
1121
|
|
|
957
|
-
Client mode meters `completion`, `acompletion`, `text_completion`, `atext_completion`, `completion_with_retries` and `acompletion_with_retries`, streamed or not, and `embedding` / `aembedding` as embedding calls. When you stream without `stream_options={"include_usage": True}`, the middleware asks LiteLLM for the usage chunk itself and keeps it out of your stream. LiteLLM adds that chunk for every provider, including ones it does not send `stream_options` to. `litellm.responses` and `litellm.aresponses` are not metered, except on providers LiteLLM serves through `completion`.
|
|
1122
|
+
Client mode meters `completion`, `acompletion`, `text_completion`, `atext_completion`, `completion_with_retries` and `acompletion_with_retries`, streamed or not, and `embedding` / `aembedding` as embedding calls. When you stream without `stream_options={"include_usage": True}`, the middleware asks LiteLLM for the usage chunk itself and keeps it out of your stream. LiteLLM adds that chunk for every provider, including ones it does not send `stream_options` to. `litellm.responses` and `litellm.aresponses` are not metered, except on providers LiteLLM serves through `completion`. A completion that fails, or a stream that breaks off, sends one record with stop reason `ERROR`, zero tokens for a call that never started, and the error's class and HTTP status as its error reason (plus the provider's redacted error message when both `REVENIUM_CAPTURE_ERROR_MESSAGES` and `REVENIUM_CAPTURE_PROMPTS` are `true`; a provider's error can quote the request, so it is never sent with prompt capture off); your code still gets the original exception. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer (a connection error, a timeout, or a stream that broke off) has none. LiteLLM gives a connection error a 500 and a timeout a 408 that no server answered, so those get no error code and no HTTP status in their error reason, including the `InternalServerError` LiteLLM raises for a refused connection on its `openai/` and `anthropic/` providers. LiteLLM also raises a few real provider answers, such as a Vertex AI 502, as connection errors, and those get no error code either. Failure records sent by the LiteLLM gateway (proxy) do not carry the error code yet.
|
|
958
1123
|
|
|
959
|
-
Inside a LiteLLM proxy running `ReveniumGuardrail` with `default_on: true` and `post_call` among its modes, client mode leaves each proxied request to the guardrail, so the request is recorded once, with the guardrail's subscriber
|
|
1124
|
+
Inside a LiteLLM proxy running `ReveniumGuardrail` with `default_on: true` and `post_call` among its modes, client mode leaves each proxied request to the guardrail, so the request is recorded once, with the guardrail's subscriber. The row names the deployment's model (the `litellm_params.model` behind the `model_name` your callers use, without its provider prefix), so a call to an alias is priced as the model it reached. The guardrail also meters streamed `/v1/responses` calls (Codex CLI, the OpenAI Agents SDK) for every provider. Client mode still records the proxied calls the guardrail does not meter, which today are streamed `/v1/completions` calls, and every call your own code in the proxy's process makes to LiteLLM directly.
|
|
960
1125
|
|
|
961
1126
|
#### Proxy Mode
|
|
962
1127
|
|
|
963
1128
|
`ReveniumGuardrail` is the LiteLLM proxy integration. It is a LiteLLM
|
|
964
1129
|
`CustomGuardrail` that **enforces the caller's budget before** the proxied call and
|
|
965
|
-
**meters usage after** it
|
|
1130
|
+
**meters usage after** it: successes, failures and streamed responses alike,
|
|
1131
|
+
except calls a spending cap refuses.
|
|
966
1132
|
|
|
967
1133
|
```bash
|
|
968
1134
|
pip install "revenium-python-sdk[litellm-proxy]" # requires Python 3.10+
|
|
@@ -985,14 +1151,21 @@ expects a different shape and exits the proxy at startup with
|
|
|
985
1151
|
`GuardrailItem() argument after ** must be a mapping, not str`.
|
|
986
1152
|
|
|
987
1153
|
`mode` must be a **list** to enable both hooks; a single string restricts the
|
|
988
|
-
guardrail to that one event type. `pre_call` alone enforces without metering
|
|
989
|
-
`post_call` alone meters without enforcing
|
|
1154
|
+
guardrail to that one event type. `pre_call` alone enforces without metering.
|
|
1155
|
+
`post_call` alone meters successful calls without enforcing, but records no failed
|
|
1156
|
+
calls: a failed call is recorded only for a request the Revenium guardrail's
|
|
1157
|
+
`pre_call` hook ran on, so a request LiteLLM refuses for a wrong or missing key
|
|
1158
|
+
sends no record. Adding `pre_call` enforces no budget unless
|
|
1159
|
+
`REVENIUM_CIRCUIT_BREAKER_ENABLED=true`.
|
|
990
1160
|
|
|
991
1161
|
**Budget enforcement** reuses the SDK's own circuit breaker, so a proxy enforces
|
|
992
1162
|
exactly what every other Revenium integration enforces — including department
|
|
993
|
-
budgets.
|
|
994
|
-
|
|
995
|
-
|
|
1163
|
+
budgets. An organization cap is checked against the organization the call names,
|
|
1164
|
+
which a caller can choose by header unless you pin it to the key's team (see
|
|
1165
|
+
"Organization caps and the organization header" below). It is opt-in via `REVENIUM_CIRCUIT_BREAKER_ENABLED=true`; see
|
|
1166
|
+
[Cost Controls](#cost-controls). A blocked call never reaches the provider, the
|
|
1167
|
+
caller receives HTTP 429, and no failed-call record is sent, as with the OpenAI and
|
|
1168
|
+
Anthropic integrations:
|
|
996
1169
|
|
|
997
1170
|
```json
|
|
998
1171
|
{"error": {"message": "Request blocked by Revenium enforcement rule: Team Budget",
|
|
@@ -1001,6 +1174,8 @@ caller receives HTTP 429:
|
|
|
1001
1174
|
"currentValue": 11.5, "resetsAt": "2026-10-01T00:00:00Z"}]}}
|
|
1002
1175
|
```
|
|
1003
1176
|
|
|
1177
|
+
When the rule carries a deny message, the body's `message` ends with it, as `BudgetExceededError.message` does (see [Exception Contract](#exception-contract)).
|
|
1178
|
+
|
|
1004
1179
|
Enforcement **fails open**: if the enforcement path is unreachable or misbehaves,
|
|
1005
1180
|
the call proceeds, and it proceeds without waiting. The pre-call check reads the
|
|
1006
1181
|
rules the SDK already has cached and refreshes them on a background thread, so a
|
|
@@ -1018,7 +1193,63 @@ for reasoning effort), with the calling virtual key's metadata as the fallback
|
|
|
1018
1193
|
`revenium_user_id`, `revenium_organization_name`, `revenium_key_name`, and
|
|
1019
1194
|
`revenium_agentic_job_*`. Agentic job tags (`x-revenium-agentic-job-id`, `-name`,
|
|
1020
1195
|
`-type`, `-version`) ride along for cost/ROI correlation; the job id is required for
|
|
1021
|
-
the others to be recorded.
|
|
1196
|
+
the others to be recorded. A malformed header value, such as a quality score of
|
|
1197
|
+
`high` or an effort of `very high`, is left off the record with a WARNING in the
|
|
1198
|
+
gateway log; the call is still recorded.
|
|
1199
|
+
|
|
1200
|
+
**Trace id.** The guardrail takes a record's trace id from `x-revenium-trace-id`.
|
|
1201
|
+
Without that header it takes the LiteLLM session id the caller sent: the
|
|
1202
|
+
`x-litellm-session-id` or `x-litellm-trace-id` header, or `litellm_session_id` or
|
|
1203
|
+
`metadata.session_id` in the request body (`litellm_metadata.session_id` on
|
|
1204
|
+
`/v1/messages`). Calls a customer groups into one LiteLLM session therefore read
|
|
1205
|
+
as one trace in Revenium. Failing both, it uses Claude Code's
|
|
1206
|
+
`x-claude-code-session-id`, so one Claude Code session is one trace. A call with
|
|
1207
|
+
none of these has no trace id. The id LiteLLM generates for every request is never
|
|
1208
|
+
used, because it would make each call a trace of its own, and neither is a session
|
|
1209
|
+
id LiteLLM minted itself under its `missing_session_id: generate` policy. The
|
|
1210
|
+
deprecated callback reads only `x-revenium-trace-id` and `x-claude-code-session-id`.
|
|
1211
|
+
|
|
1212
|
+
**Organization caps and the organization header.** By default the
|
|
1213
|
+
`x-revenium-organization-name` header (and the retired `x-revenium-organization-id`)
|
|
1214
|
+
wins over the calling virtual key's team alias, for the budget check and the record
|
|
1215
|
+
alike. That means anyone holding a team's key can send another organization's name
|
|
1216
|
+
and move their spend off their own organization's cap: the call is checked against,
|
|
1217
|
+
and recorded under, the name they sent. To make the key's team decide instead, set
|
|
1218
|
+
|
|
1219
|
+
```bash
|
|
1220
|
+
export REVENIUM_LITELLM_PIN_ORGANIZATION_TO_KEY_TEAM=true
|
|
1221
|
+
```
|
|
1222
|
+
|
|
1223
|
+
With it on, a call made with a key that belongs to a LiteLLM team is checked and
|
|
1224
|
+
recorded under that team's alias whatever organization header it sends, so the team
|
|
1225
|
+
alias is the organization: renaming the team in LiteLLM renames where its spend is
|
|
1226
|
+
booked. A key with no team alias (none set, or blank) still takes the organization
|
|
1227
|
+
from the header; on the guardrail, a key with neither falls back to its
|
|
1228
|
+
`revenium_organization_name` metadata. `1`, `yes` and `on` also turn the setting on.
|
|
1229
|
+
Unset, `false`, `0`, `no` and `off` leave it off; any other value leaves it off too,
|
|
1230
|
+
and the proxy logs a warning at startup naming the setting. The deprecated callback
|
|
1231
|
+
honours the same setting for its record.
|
|
1232
|
+
|
|
1233
|
+
**Trace fields** come from the gateway host's own settings, and a matching header wins
|
|
1234
|
+
per call: `REVENIUM_ENVIRONMENT` (or `ENVIRONMENT`, or `DEPLOYMENT_ENV`) and
|
|
1235
|
+
`x-revenium-environment`; `REVENIUM_REGION` (or `AWS_REGION`, `AWS_DEFAULT_REGION`,
|
|
1236
|
+
`AZURE_REGION`, `GCP_REGION`, `GOOGLE_CLOUD_REGION`) and `x-revenium-region`;
|
|
1237
|
+
`REVENIUM_CREDENTIAL_ALIAS` and `x-revenium-credential-alias`;
|
|
1238
|
+
`REVENIUM_TICKET_ID` and `x-revenium-ticket-id`; `REVENIUM_TRANSACTION_NAME`, `REVENIUM_TRACE_TYPE`, `REVENIUM_TRACE_NAME`,
|
|
1239
|
+
`REVENIUM_PARENT_TRANSACTION_ID`, `REVENIUM_RETRY_NUMBER` and `REVENIUM_SKILL_*`, with
|
|
1240
|
+
the headers `x-revenium-transaction-name`, `-trace-type`, `-trace-name`,
|
|
1241
|
+
`-parent-transaction-id`, `-retry-number`, `-skill-name`, `-skill-source`,
|
|
1242
|
+
`-skill-kind`, `-skill-plugin-name`, `-skill-marketplace-name` and
|
|
1243
|
+
`-skill-invocation-trigger`. The gateway does not fall back to the task type for the
|
|
1244
|
+
transaction name, and sends a retry number only when the header or
|
|
1245
|
+
`REVENIUM_RETRY_NUMBER` sets one. The credential alias names the credential only on
|
|
1246
|
+
calls with no subscriber id or email and no virtual key alias; most virtual keys carry
|
|
1247
|
+
their owner's email, so those calls keep the owner's own credential. A spending cap on
|
|
1248
|
+
a credential alias therefore covers only calls with no subscriber identity, and on
|
|
1249
|
+
those calls a caller's `x-revenium-credential-alias` wins over the host's alias, for
|
|
1250
|
+
the cap check and the record alike. The agent's own version rides in
|
|
1251
|
+
`x-revenium-agent-version`, per call only with no host setting, and is cut to 64
|
|
1252
|
+
characters.
|
|
1022
1253
|
|
|
1023
1254
|
**Who made the call.** By default a proxied call is metered and budget-checked as the
|
|
1024
1255
|
owner of the virtual key it used, which is right when every person has their own key.
|
|
@@ -1054,13 +1285,16 @@ reports the same value as the call's transaction id. Claude Code copies `request
|
|
|
1054
1285
|
onto its own record, Revenium's duplicate check sees two records with one identifier,
|
|
1055
1286
|
and one call becomes one record.
|
|
1056
1287
|
|
|
1057
|
-
**It is on by default.** To opt out
|
|
1058
|
-
|
|
1288
|
+
**It is on by default.** To opt out, with no `request-id` header added (each
|
|
1289
|
+
`/v1/messages` record then carries a per-request id the proxy assigns, never
|
|
1290
|
+
Anthropic's `msg_` id):
|
|
1059
1291
|
|
|
1060
1292
|
```bash
|
|
1061
1293
|
export REVENIUM_LITELLM_SHARED_CALL_ID=false
|
|
1062
1294
|
```
|
|
1063
1295
|
|
|
1296
|
+
Blank or unset means on; `true`, `1`, `yes`, `on` mean on; any other value turns it off and the guardrail logs that at startup.
|
|
1297
|
+
|
|
1064
1298
|
New calls go straight back to two records when you do; records already merged stay
|
|
1065
1299
|
merged. Four things have to be true for it to work:
|
|
1066
1300
|
|
|
@@ -1122,6 +1356,11 @@ stays quiet.
|
|
|
1122
1356
|
meters but never enforces a budget. It keeps working in this release and emits a
|
|
1123
1357
|
`DeprecationWarning` (and a log line) when the proxy builds it.
|
|
1124
1358
|
|
|
1359
|
+
While the callback is listed, client mode leaves each proxied completion to it, so the
|
|
1360
|
+
call is recorded once, with the subscriber, organization and product from the
|
|
1361
|
+
`x-revenium-*` headers. Proxied embeddings are recorded by client mode, without those
|
|
1362
|
+
headers, as the callback has never metered them.
|
|
1363
|
+
|
|
1125
1364
|
To migrate, delete the callbacks entry and add the `guardrails` block above:
|
|
1126
1365
|
|
|
1127
1366
|
```diff
|
|
@@ -1162,10 +1401,12 @@ proxy running would be a logger with no pre-call hook and no ability to block a
|
|
|
1162
1401
|
call — the enforcement half would silently not exist.
|
|
1163
1402
|
|
|
1164
1403
|
So the client integration keeps its own path, unchanged: use
|
|
1165
|
-
`revenium_middleware.litellm.client` as documented above.
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1404
|
+
`revenium_middleware.litellm.client` as documented above. The LiteLLM client
|
|
1405
|
+
wrapper runs the same pre-call circuit breaker with the caller's `usage_metadata`
|
|
1406
|
+
(and any `@revenium_metadata` identity) and raises `BudgetExceededError` before
|
|
1407
|
+
LiteLLM is called, so LiteLLM's retries never send a blocked call. That check runs
|
|
1408
|
+
only outside the proxy: requests the proxy serves are enforced by this guardrail.
|
|
1409
|
+
Both the guardrail and the client wrapper
|
|
1169
1410
|
already share their metering plumbing (`revenium_middleware._core`: field
|
|
1170
1411
|
extraction, cache-token extraction and `submit_ai_event`), so the guardrail adds no
|
|
1171
1412
|
second copy of it.
|
|
@@ -1191,10 +1432,25 @@ The tracking decorators above support static values, extraction from function ar
|
|
|
1191
1432
|
#### CrewAI Integration
|
|
1192
1433
|
|
|
1193
1434
|
```bash
|
|
1194
|
-
pip install "revenium-python-sdk[
|
|
1435
|
+
pip install "revenium-python-sdk[openai]" crewai
|
|
1195
1436
|
```
|
|
1196
1437
|
|
|
1197
|
-
Pre-built wrapper for tracking CrewAI agent executions.
|
|
1438
|
+
Pre-built wrapper for tracking CrewAI agent executions. Use the extra for your agents' models: `[openai]`, `[anthropic]`, `[google-genai]`, or `[litellm]` for models CrewAI sends through LiteLLM. CrewAI 1.x supports Python 3.10 to 3.13.
|
|
1439
|
+
|
|
1440
|
+
**Import the middleware for your agents' models before you build the crew.** CrewAI 1.x calls OpenAI, Anthropic and Gemini through their own SDKs, not through LiteLLM, so those calls are recorded by the matching Revenium middleware:
|
|
1441
|
+
|
|
1442
|
+
```python
|
|
1443
|
+
import revenium_middleware.openai # OpenAI models, e.g. LLM(model="gpt-4o-mini")
|
|
1444
|
+
import revenium_middleware.anthropic # Anthropic models, e.g. LLM(model="anthropic/claude-3-5-haiku-latest")
|
|
1445
|
+
import revenium_middleware.google.google_ai # Gemini models, e.g. LLM(model="gemini/gemini-2.5-flash")
|
|
1446
|
+
import revenium_middleware.litellm.client.middleware # LLM(..., is_litellm=True) and models CrewAI routes to LiteLLM
|
|
1447
|
+
```
|
|
1448
|
+
|
|
1449
|
+
Each model call the crew makes during `kickoff()` or `kickoff_async()`, including a crew built with `stream=True` as you iterate it, is recorded once and carries the wrapper's organization, subscription, product, trace and agentic job fields. Importing more than one of these is safe: a call is still recorded once. When an agent's model has no matching middleware imported, the wrapper logs one warning naming the import to add.
|
|
1450
|
+
|
|
1451
|
+
What the wrapper does not cover:
|
|
1452
|
+
- CrewAI's native Azure (`azure-ai-inference`), Bedrock (boto3 Converse) and Snowflake providers are not metered. Build those LLMs with `LLM(model=..., is_litellm=True)` and import the LiteLLM middleware.
|
|
1453
|
+
- Only `kickoff()` and `kickoff_async()` are attributed. Calls started through the underlying crew's `akickoff()` or `kickoff_for_each*()` are not.
|
|
1198
1454
|
|
|
1199
1455
|
**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).
|
|
1200
1456
|
|
|
@@ -1204,9 +1460,9 @@ from revenium_middleware.litellm.client.integrations.crewai import ReveniumCrewW
|
|
|
1204
1460
|
crew = ReveniumCrewWrapper(
|
|
1205
1461
|
agents=[support_agent],
|
|
1206
1462
|
tasks=[triage_task],
|
|
1207
|
-
|
|
1463
|
+
organization_name="AcmeCorp",
|
|
1208
1464
|
subscription_id="82764738",
|
|
1209
|
-
|
|
1465
|
+
product_name="Platinum",
|
|
1210
1466
|
agentic_job_id="support-ticket-456",
|
|
1211
1467
|
agentic_job_name="Support Ticket Triage",
|
|
1212
1468
|
agentic_job_type="customer_support",
|
|
@@ -1268,11 +1524,14 @@ client = Perplexity(api_key=os.getenv("PERPLEXITY_API_KEY"))
|
|
|
1268
1524
|
|
|
1269
1525
|
response = client.chat.completions.create(
|
|
1270
1526
|
model="sonar",
|
|
1271
|
-
messages=[{"role": "user", "content": "Hello!"}]
|
|
1527
|
+
messages=[{"role": "user", "content": "Hello!"}],
|
|
1528
|
+
usage_metadata={"organizationName": "AcmeCorp"}
|
|
1272
1529
|
)
|
|
1273
1530
|
```
|
|
1274
1531
|
|
|
1275
|
-
Both approaches work identically - the middleware automatically detects which SDK you're using.
|
|
1532
|
+
Both approaches work identically - the middleware automatically detects which SDK you're using. Both clients accept Revenium metadata as `usage_metadata=` or as `extra_body={"usage_metadata": ...}`, and the middleware removes it before the request reaches Perplexity. The one exception is the OpenAI client's `responses.stream()` helper, sync or async: it takes `usage_metadata=` only when `revenium_middleware.openai` is imported, and otherwise raises `TypeError` before any request is sent. With only `revenium_middleware.perplexity` imported, pass `extra_body={"usage_metadata": ...}` to that helper instead. Search, embeddings, contextualized embeddings, async chat and browser session calls on the native client are not metered or capped (see [Calls the SDK does not meter](#calls-the-sdk-does-not-meter)); metadata passed to them is removed and not used. An OpenAI-client embeddings call to Perplexity is recorded only when `revenium_middleware.openai` is imported.
|
|
1533
|
+
|
|
1534
|
+
A native Perplexity SDK `chat.completions.create` call that Perplexity refuses (a 400, 429 or 500, for example), streamed or not, sends one record with stop reason `ERROR`, zero tokens and the error's class and HTTP status as its error reason. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer has none. Your code still gets Perplexity's own exception. A native stream that breaks off after it started, and calls a spending cap refuses, send no error record.
|
|
1276
1535
|
|
|
1277
1536
|
**Streaming:**
|
|
1278
1537
|
|
|
@@ -1288,13 +1547,15 @@ for chunk in stream:
|
|
|
1288
1547
|
print(chunk.choices[0].delta.content, end="", flush=True)
|
|
1289
1548
|
```
|
|
1290
1549
|
|
|
1550
|
+
**Through LangChain:** `ChatPerplexity` keeps only token counts from Perplexity's answer, so the charge Perplexity reports (`usage.cost`, which includes its flat per-request fee) would never reach a LangChain record. When `perplexityai` is installed, importing `revenium_middleware.openai.langchain` therefore adds a read-only hook to the Perplexity SDK's `chat.completions.create` and `responses.create` (sync, async and streamed). Inside a LangChain run it hands the reported cost to the Revenium callback's record; it sends no record of its own, checks no spending cap, and leaves calls made outside a LangChain run untouched. Importing `revenium_middleware.perplexity` as well still works as above: its own record carries the cost for chat calls, and calls with a built-in tool (which go to the Responses API) are recorded by the callback.
|
|
1551
|
+
|
|
1291
1552
|
**Examples:** `examples/perplexity/` - `getting_started.py`, `basic.py`, `streaming.py`, `example_decorator.py`
|
|
1292
1553
|
|
|
1293
1554
|
---
|
|
1294
1555
|
|
|
1295
1556
|
### fal.ai
|
|
1296
1557
|
|
|
1297
|
-
Supports image, video, and audio generation through fal.ai with automatic media type detection.
|
|
1558
|
+
Supports image, video, and audio generation through fal.ai with automatic media type detection. Language model endpoints (`fal-ai/any-llm`, the OpenRouter router `openrouter/router`) are recorded as chat completions with the tokens fal reports.
|
|
1298
1559
|
|
|
1299
1560
|
```python
|
|
1300
1561
|
import revenium_middleware.fal # Auto-activates
|
|
@@ -1316,10 +1577,14 @@ for image in result.get("images", []):
|
|
|
1316
1577
|
print(f"Image URL: {image['url']}")
|
|
1317
1578
|
```
|
|
1318
1579
|
|
|
1319
|
-
**Supported methods:** `run`, `subscribe`, `stream` and the queue flow (`submit`, then `status` and `result` or the handle's `get()`), on the module-level functions (`fal_client.run`, `fal_client.run_async`, and so on) and on clients you construct yourself (`fal_client.SyncClient(key=...)`, `fal_client.AsyncClient(key=...)`). Pass `usage_metadata` to `run`, `subscribe`, `stream` or `
|
|
1580
|
+
**Supported methods:** `run`, `subscribe`, `stream` and the queue flow (`submit`, then `status` and `result` or the handle's `get()`), on the module-level functions (`fal_client.run`, `fal_client.run_async`, and so on) and on clients you construct yourself (`fal_client.SyncClient(key=...)`, `fal_client.AsyncClient(key=...)`). Pass `usage_metadata` to `run`, `subscribe`, `stream`, `submit`, `result` or the handle's `get()`.
|
|
1320
1581
|
|
|
1321
1582
|
**Queued jobs** are metered once, when the result is fetched: `submit` and `status` send nothing, fetching the same result again sends nothing more, and a job whose result is never fetched is not metered. A stream is metered from its last event once you have read it to the end.
|
|
1322
1583
|
|
|
1584
|
+
**Jobs fetched in another process:** the tags given to `submit` stay in the process that submitted the job, because fal has no field that carries them with it. When another process fetches the result (another worker, a webhook handler, the same service after a restart), pass the tags there: `fal_client.result(application, request_id, usage_metadata={...})` or `handle.get(usage_metadata={...})`. Without them the job is recorded with no organization, product, subscriber, trace or agent, and the SDK logs a warning naming the request id. In the process that submitted the job, the tags given at submit win, and tags given at fetch fill only the fields the submit left unset.
|
|
1585
|
+
|
|
1586
|
+
Every record of a queued job is sent under `fal-<request id>`, as both its transaction id and its Idempotency-Key, so fetching the same job again in another process does not bill it twice: Revenium refuses the repeat, and the SDK logs the refusal and counts it as one metering error. Revenium keeps the first record it receives for a transaction id, so this holds however long after the first fetch the repeat comes, and a later fetch without tags never replaces a tagged record.
|
|
1587
|
+
|
|
1323
1588
|
**Media type detection:** The middleware automatically detects the type of media being generated (image, video, audio) based on the application name for accurate cost tracking.
|
|
1324
1589
|
|
|
1325
1590
|
**Environment variables:**
|
|
@@ -1335,7 +1600,7 @@ Callback handler that automatically tracks LLM calls, chains, tools, and agent a
|
|
|
1335
1600
|
pip install "revenium-python-sdk[langchain]"
|
|
1336
1601
|
```
|
|
1337
1602
|
|
|
1338
|
-
Wrap any LangChain
|
|
1603
|
+
Wrap any LangChain chat model or LLM with `wrap()`; the Revenium callback handler is attached for you:
|
|
1339
1604
|
|
|
1340
1605
|
```python
|
|
1341
1606
|
from langchain_openai import ChatOpenAI
|
|
@@ -1385,7 +1650,13 @@ llm = wrap(ChatOpenAI(model="gpt-4o-mini"))
|
|
|
1385
1650
|
response = await llm.ainvoke("Hello!")
|
|
1386
1651
|
```
|
|
1387
1652
|
|
|
1388
|
-
**Supported providers:** OpenAI, Anthropic, Google, AWS Bedrock, Azure OpenAI, Cohere, HuggingFace, Ollama. Provider is auto-detected from LangChain class name or model name prefix.
|
|
1653
|
+
**Supported providers:** OpenAI, Anthropic, Google, AWS Bedrock, Azure OpenAI, Cohere, HuggingFace, Mistral, Ollama. Provider is auto-detected from LangChain class name or model name prefix.
|
|
1654
|
+
|
|
1655
|
+
**Perplexity cost:** a `ChatPerplexity` record carries the cost Perplexity reported, per-request fee included, for chat calls and for calls with a built-in tool such as web search. Importing this module installs a read-only hook on the Perplexity SDK for this (see [Perplexity](#perplexity)); the hook sends nothing itself.
|
|
1656
|
+
|
|
1657
|
+
**Text-completion models:** streamed calls from `langchain_openai.OpenAI` and `AzureOpenAI` (`stream`, `astream`, `invoke` with `streaming=True`) are recorded with the provider's token counts. Importing this module installs a read-only hook on the OpenAI SDK's legacy `completions.create` that asks the endpoint for its usage chunk during a LangChain stream and keeps that chunk out of your stream, except that a server whose usage chunk also carries an empty choice, such as the LiteLLM proxy, passes it through as one extra empty text chunk. The hook sends nothing itself, and a direct `completions.create` call outside LangChain is untouched and still not metered. A server that ignores the request gets a record with zero tokens and a warning. These streamed calls still send no record: `ainvoke` on a `streaming=True` model, a stream you stop reading early, and Azure OpenAI api-versions before `2024-09-01-preview`, which reject the usage request, so it is not sent there.
|
|
1658
|
+
|
|
1659
|
+
**Claude advisor and compaction passes:** a `ChatAnthropic` call metered by the callback alone sends one record per advisor or compaction pass when LangChain does not stream the call. Whenever LangChain streams it, only the main call is recorded, because LangChain keeps no per-pass usage on a streamed result: `stream`, `astream`, `streaming=True`, a `stream=True` call keyword, `astream_events`, or a LangGraph run streamed in `messages` mode, even when your code calls `invoke`. To record the passes for those calls too, also `import revenium_middleware.anthropic`, which covers every form.
|
|
1389
1660
|
|
|
1390
1661
|
**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)):
|
|
1391
1662
|
|
|
@@ -1395,11 +1666,52 @@ from revenium_middleware.openai.langchain import attach_to
|
|
|
1395
1666
|
attach_to(llm, usage_metadata={
|
|
1396
1667
|
"organizationName": "my_org",
|
|
1397
1668
|
"productName": "my_product",
|
|
1398
|
-
"subscriber": {"id": "user_123", "email": "user@example.com"},
|
|
1399
1669
|
})
|
|
1400
1670
|
```
|
|
1401
1671
|
|
|
1402
|
-
|
|
1672
|
+
Calling `attach_to()` again on the same model replaces its Revenium handler rather than adding a second one. Attach once at startup with the fields every call shares. Do not call `attach_to()` per request on a model your requests share: overlapping requests would all be recorded under whichever person was attached last. To name the person per request, use one of these:
|
|
1673
|
+
|
|
1674
|
+
```python
|
|
1675
|
+
from revenium_middleware import revenium_metadata
|
|
1676
|
+
from revenium_middleware.openai.langchain import UnifiedReveniumCallbackHandler
|
|
1677
|
+
|
|
1678
|
+
# (a) Model attached once at startup; name the person inside the request handler.
|
|
1679
|
+
def handle_request(user, question):
|
|
1680
|
+
@revenium_metadata(subscriber={"id": user.id, "email": user.email})
|
|
1681
|
+
def answer():
|
|
1682
|
+
return llm.invoke(question)
|
|
1683
|
+
return answer()
|
|
1684
|
+
|
|
1685
|
+
# (b) A model with no attach_to(); pass a handler with the call.
|
|
1686
|
+
def handle_request(user, question):
|
|
1687
|
+
handler = UnifiedReveniumCallbackHandler(usage_metadata={"subscriber": {"id": user.id}})
|
|
1688
|
+
return bare_llm.invoke(question, config={"callbacks": [handler]})
|
|
1689
|
+
```
|
|
1690
|
+
|
|
1691
|
+
With pattern (a), consume a stream inside the decorated function, or open the decorator around the iteration: a stream returned unconsumed (for example in a FastAPI `StreamingResponse`) is recorded without the decorator's fields.
|
|
1692
|
+
|
|
1693
|
+
Where the handler attached with `attach_to()` and `@revenium_metadata` both name a field (for example `subscriber`), the attached handler's value is used, on every model.
|
|
1694
|
+
|
|
1695
|
+
Combining a startup `attach_to()` with a per-call handler on the same model records each call once, with the attached handler's fields; the per-call handler's fields are used only when the attached handler has none.
|
|
1696
|
+
|
|
1697
|
+
**Embeddings models:** LangChain embeddings models run no callbacks, so `wrap()` and `attach_to()` return the model unchanged, attach nothing and log one warning per model class. Wrapping a chain or other runnable that has no callbacks field also attaches nothing and logs a warning; wrap the model inside it instead. `OpenAIEmbeddings` and `AzureOpenAIEmbeddings` calls are still recorded by the OpenAI middleware, without the `usage_metadata` given to `wrap()`; tag them with `@revenium_metadata` on the function that makes the call:
|
|
1698
|
+
|
|
1699
|
+
```python
|
|
1700
|
+
from revenium_middleware import revenium_metadata
|
|
1701
|
+
from langchain_openai import OpenAIEmbeddings
|
|
1702
|
+
|
|
1703
|
+
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
|
|
1704
|
+
|
|
1705
|
+
@revenium_metadata(organization_name="AcmeCorp", agent="support_agent", trace_id="session-123")
|
|
1706
|
+
def embed(texts):
|
|
1707
|
+
return embeddings.embed_documents(texts)
|
|
1708
|
+
```
|
|
1709
|
+
|
|
1710
|
+
Embeddings from vendors other than OpenAI, Azure OpenAI and Ollama through LangChain, such as `MistralAIEmbeddings`, are not metered (see [Calls the SDK does not meter](#calls-the-sdk-does-not-meter)).
|
|
1711
|
+
|
|
1712
|
+
**OpenAI Decisions, model router and auto mode:** a request made through langchain-openai's `OpenAIDecisions`, including the one `OpenAIModelRouterMiddleware` and `OpenAIAutoModeMiddleware` make on every agent run, is recorded with its input and output tokens when the handler reaches that run: pass it in the run's `config={"callbacks": [handler]}` (for example `agent.invoke(inputs, config={"callbacks": [handler]})`), or give the middleware a configured `OpenAIDecisions(...).with_config(callbacks=[handler])`. A handler attached to the chat model with `attach_to()` or `wrap()` does not see these requests. Decisions requests are not checked against spending caps, and a direct `client.decisions.create` call on the OpenAI client is not metered.
|
|
1713
|
+
|
|
1714
|
+
Credentials come from the standard environment variables (`REVENIUM_METERING_API_KEY`, `REVENIUM_METERING_BASE_URL`) or `revenium_middleware.initialize_metering(api_key=..., base_url=...)`. `revenium_middleware.configure()` sets the key for tool events only, so it does not meter LangChain calls.
|
|
1403
1715
|
|
|
1404
1716
|
---
|
|
1405
1717
|
|
|
@@ -1419,19 +1731,32 @@ pip install "revenium-python-sdk[griptape,litellm,litellm-proxy]" # 100+ provid
|
|
|
1419
1731
|
```python
|
|
1420
1732
|
import os
|
|
1421
1733
|
from griptape.structures import Agent
|
|
1422
|
-
from revenium_middleware
|
|
1734
|
+
from revenium_middleware import BudgetExceededError
|
|
1735
|
+
from revenium_middleware.griptape import ReveniumDriver, enable_budget_errors
|
|
1423
1736
|
|
|
1424
1737
|
os.environ["REVENIUM_METERING_API_KEY"] = "your_revenium_key"
|
|
1738
|
+
enable_budget_errors() # once at startup, so a spending-cap refusal reaches your except block
|
|
1425
1739
|
|
|
1426
1740
|
agent = Agent(prompt_driver=ReveniumDriver(
|
|
1427
1741
|
model="gpt-4o-mini",
|
|
1428
1742
|
usage_metadata={"task_type": "demo"},
|
|
1429
1743
|
))
|
|
1430
|
-
|
|
1744
|
+
try:
|
|
1745
|
+
agent.run("Hello!")
|
|
1746
|
+
except BudgetExceededError as e:
|
|
1747
|
+
print(f"Spending cap reached: {e.message}")
|
|
1431
1748
|
```
|
|
1432
1749
|
|
|
1433
1750
|
Force a provider with `force_provider="litellm"`, or wrap an existing driver with `ReveniumDriver(base_driver=...)`.
|
|
1434
1751
|
|
|
1752
|
+
A wrapped OpenAI, Azure OpenAI, Claude or Ollama driver keeps every setting you gave it, including your own client, address, key, streaming and retry settings. A setting the Revenium driver cannot carry, such as an extra field on your own driver subclass, is named in a warning instead of being dropped silently.
|
|
1753
|
+
|
|
1754
|
+
To route Griptape through a LiteLLM gateway, pass `proxy_url=` (and `proxy_api_key=`) to `ReveniumDriver`, either as a base address or ending in `/chat/completions`. On that route Griptape tools are not sent and the gateway, not the SDK, records usage. The `LITELLM_PROXY_URL` environment variable alone does not change which provider a Griptape model uses, so `ReveniumDriver(model="gpt-4o-mini")` still calls OpenAI and records usage. Models that already route through LiteLLM (`force_provider="litellm"`, `gemini-*` and provider-qualified ids) still follow `LITELLM_PROXY_URL` through the LiteLLM driver's own setting. The proxy arguments are ignored, with a warning, when you wrap an existing driver.
|
|
1755
|
+
|
|
1756
|
+
**Spending caps:** Griptape turns any error inside a task into an error result, so without `enable_budget_errors()` an agent stopped by a cap returns the refusal text as its answer. With it, `agent.run(...)`, `Pipeline.run()` and `Workflow.run()` raise `BudgetExceededError`, in any thread. `run_stream` never raises: call `raise_if_budget_exceeded(agent)` after the stream ends, or after any run when you do not use the setup line. A refused call is never sent to the provider and is not retried. Nothing is installed on import: `enable_budget_errors()` sets Griptape's global observability driver, wrapping one you already set with `Observability.set_global_driver(...)` so it still sees every call, and `disable_budget_errors()` turns it off. If you use a `with Observability(...)` or `with GriptapeCloudStructure(observe=True)` block, call `enable_budget_errors()` inside each block, after it opens: leaving the block turns it off, and calling it before the block makes Griptape refuse the block. Pass your driver as `delegate=` only if you have already entered it or it has no enter or exit work.
|
|
1757
|
+
|
|
1758
|
+
Not covered: on the LiteLLM gateway route (`proxy_url=`) the gateway answers a cap with HTTP 429, which reaches you as `requests.HTTPError`, not `BudgetExceededError`. A refusal inside a tool (for example a vector-store embedding) reaches the model as the tool's output, not your `except`. The refusal is saved as the run's output in conversation memory, and Griptape still logs it at ERROR.
|
|
1759
|
+
|
|
1435
1760
|
**Embeddings:**
|
|
1436
1761
|
|
|
1437
1762
|
```python
|
|
@@ -1448,7 +1773,11 @@ driver = ReveniumEmbeddingDriver(model="text-embedding-3-large")
|
|
|
1448
1773
|
|
|
1449
1774
|
## Metadata Fields
|
|
1450
1775
|
|
|
1451
|
-
Add business context to
|
|
1776
|
+
Add business context to a call the SDK records by passing a `usage_metadata` dictionary. All fields are optional. The calls listed in [Calls the SDK does not meter](#calls-the-sdk-does-not-meter) record nothing from it; on LiteLLM's image generation, image edit, transcription, video generation and search calls, after `revenium_middleware.litellm` is imported, the SDK removes it before the request is sent, so it never reaches the provider.
|
|
1777
|
+
These fields are shortened with a WARNING when longer than Revenium stores, so the call is still
|
|
1778
|
+
recorded: `trace_id`, `task_type`, `agent`, `subscription_id`, `parent_transaction_id`, `environment`,
|
|
1779
|
+
`region`, `transaction_name`, `operation_subtype`, `subscriber.id` and `subscriber.email` at 255
|
|
1780
|
+
characters, and `product_name` at 224. Other text fields are sent as given.
|
|
1452
1781
|
|
|
1453
1782
|
| Field | Description | Use Case |
|
|
1454
1783
|
|-------|-------------|----------|
|
|
@@ -1497,10 +1826,9 @@ high-effort reasoning spend can be separated from the rest. It is a free-form
|
|
|
1497
1826
|
string, not an enum -- vendor vocabularies differ and drift, so `low`, `medium`,
|
|
1498
1827
|
`high`, `xhigh` and `ultra` are all real values, and a level this SDK release has
|
|
1499
1828
|
never heard of is passed through untouched rather than rejected or rewritten. The
|
|
1500
|
-
Revenium backend
|
|
1501
|
-
|
|
1502
|
-
|
|
1503
|
-
`get_metering_status()`. It is distinct from the reported reasoning token count,
|
|
1829
|
+
Revenium backend rule is at most 16 characters, matching `^[A-Za-z0-9_-]+$`; a
|
|
1830
|
+
value outside it is left off the record with a WARNING, and the call is still
|
|
1831
|
+
recorded with its tokens and cost. It is distinct from the reported reasoning token count,
|
|
1504
1832
|
which measures the tokens actually spent rather than the level requested.
|
|
1505
1833
|
|
|
1506
1834
|
Set it per call in `usage_metadata` on any provider integration. In LiteLLM proxy
|
|
@@ -1523,7 +1851,7 @@ Enhanced observability fields for tracking AI operations across environments, re
|
|
|
1523
1851
|
|-------|----------------------------------|-------------|----------|
|
|
1524
1852
|
| `environment` | `REVENIUM_ENVIRONMENT` (auto-detects: `ENVIRONMENT`, `DEPLOYMENT_ENV`) | Deployment environment | Track usage across `production`, `staging`, `dev` |
|
|
1525
1853
|
| `region` | `REVENIUM_REGION` (auto-detects: `AWS_REGION`, `AZURE_REGION`, `GCP_REGION`) | Cloud region identifier | Multi-region deployment tracking and latency analysis |
|
|
1526
|
-
| `credential_alias` | `REVENIUM_CREDENTIAL_ALIAS` |
|
|
1854
|
+
| `credential_alias` | `REVENIUM_CREDENTIAL_ALIAS` | Name of the provider API key used for the call, recorded as the subscriber's credential name | See usage and spend per provider key on calls with no subscriber id or email; a credential name or value you set on the subscriber wins |
|
|
1527
1855
|
| `trace_type` | `REVENIUM_TRACE_TYPE` | Workflow category (max 128 chars, alphanumeric/hyphens/underscores) | Group similar workflows (e.g., `"customer-support"`, `"data-analysis"`) |
|
|
1528
1856
|
| `trace_name` | `REVENIUM_TRACE_NAME` | Human-readable trace label (max 256 chars) | Label trace instances (e.g., `"Customer Support Chat"`) |
|
|
1529
1857
|
| `parent_transaction_id` | `REVENIUM_PARENT_TRANSACTION_ID` | Parent transaction ID | Link child operations to parents across microservices |
|
|
@@ -1538,7 +1866,7 @@ Enhanced observability fields for tracking AI operations across environments, re
|
|
|
1538
1866
|
| `skill_marketplace_name` | `REVENIUM_SKILL_MARKETPLACE_NAME` | Marketplace the skill or plugin was installed from (max 256 chars) | Track marketplace-sourced skill usage |
|
|
1539
1867
|
| `skill_invocation_trigger` | `REVENIUM_SKILL_INVOCATION_TRIGGER` | What triggered the skill (max 32 chars; common values: `user-slash`, `claude-proactive`, `nested-skill`) | Separate user-invoked from proactive skill usage |
|
|
1540
1868
|
|
|
1541
|
-
**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.
|
|
1869
|
+
**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. To label a function's calls, use `metadata={"task_type": "..."}` on `@revenium_meter` or a `transaction_name`.
|
|
1542
1870
|
|
|
1543
1871
|
### Usage
|
|
1544
1872
|
|
|
@@ -1573,6 +1901,8 @@ response = client.chat.completions.create(
|
|
|
1573
1901
|
|
|
1574
1902
|
**Best practice:** Use environment variables for static deployment configuration (`environment`, `region`, `credential_alias`) and pass dynamic values (`trace_name`, `transaction_name`, `organizationName`) directly in `usage_metadata` or via decorators.
|
|
1575
1903
|
|
|
1904
|
+
The credential alias is stored as the subscriber's credential name (`subscriber.credential.name`). A call with no subscriber id or email is recorded under a credential named after the alias. A call that names a subscriber, by id or email, keeps that subscriber's own credential, and the SDK does not send the alias on it, so different subscribers are never linked to one shared credential. A credential name or value you set on the subscriber yourself (`subscriber.credential`, or `subscriber_credential_name` / `subscriber_credential`) wins over the alias in what the SDK sends. If your team uses strict ingestion, register the alias as a credential first, or calls that carry it can be refused.
|
|
1905
|
+
|
|
1576
1906
|
### Distributed Tracing Example
|
|
1577
1907
|
|
|
1578
1908
|
```python
|
|
@@ -1635,8 +1965,8 @@ answer = handle_customer_query("How do I reset my password?")
|
|
|
1635
1965
|
**Features:**
|
|
1636
1966
|
- **DRY Principle**: Define metadata once, apply to all API calls in the function
|
|
1637
1967
|
- **Composable**: Decorators can be nested - inner decorators inherit and override outer ones
|
|
1638
|
-
- **API-level override**: `usage_metadata` passed directly to API calls always takes precedence over decorator metadata
|
|
1639
|
-
- **Async support**: Works with
|
|
1968
|
+
- **API-level override**: `usage_metadata` passed directly to API calls always takes precedence over decorator metadata; a `None` or empty per-call value leaves the decorator's value in place
|
|
1969
|
+
- **Async and streaming support**: Works with sync and async functions, and with generator and async generator functions such as streaming endpoints. In a generator, the metadata applies to the calls the generator body makes, not to code that handles each yielded item. The same holds for a streaming function behind a retry, tracing or caching decorator, and for a plain or async function that returns a generator
|
|
1640
1970
|
- **Thread-safe**: Uses `contextvars` for proper isolation
|
|
1641
1971
|
|
|
1642
1972
|
**Nested decorators (metadata merging):**
|
|
@@ -1685,6 +2015,8 @@ Control which functions are metered when selective metering mode is enabled. Thi
|
|
|
1685
2015
|
|
|
1686
2016
|
**Note:** This decorator only has an effect when `REVENIUM_SELECTIVE_METERING=true` is set. By default, all API calls are metered automatically.
|
|
1687
2017
|
|
|
2018
|
+
Calls outside a `@revenium_meter` function are not metered, but they still accept `usage_metadata`: the middleware removes it before the request reaches the AI provider. This covers LangChain models carrying the Revenium callback and raw boto3 Bedrock calls with `REVENIUM_BEDROCK_TRANSPORT=1`. A stream, through LangChain or raw boto3, is judged when it starts, so a stream started inside a metered function is recorded even if it is read to the end outside it. Spending caps (`REVENIUM_CIRCUIT_BREAKER_ENABLED=true`) still apply to calls outside a metered function, through every provider middleware. Nested `@revenium_meter` functions keep the outer function metered after the inner one returns. A decorated generator or async generator function, such as a streaming endpoint, has the calls its body makes metered and tagged. So does one that also carries another decorator listed below the Revenium ones, such as a retry, tracing or caching decorator, and a plain or async function that returns a generator. A generator handed back inside another object, such as `StreamingResponse(gen())`, is not seen: decorate the generator function itself.
|
|
2019
|
+
|
|
1688
2020
|
```bash
|
|
1689
2021
|
# Enable selective metering
|
|
1690
2022
|
export REVENIUM_SELECTIVE_METERING=true
|
|
@@ -1716,6 +2048,36 @@ def free_feature(prompt: str) -> str:
|
|
|
1716
2048
|
- `"true"`, `"1"`, `"yes"`, `"on"` (case-insensitive) - Selective metering enabled
|
|
1717
2049
|
- `"false"`, `"0"`, `"no"`, `"off"`, or unset - All calls metered (default)
|
|
1718
2050
|
|
|
2051
|
+
**Worker threads:** The metering mark of `@revenium_meter` and the tags of
|
|
2052
|
+
`@revenium_metadata` follow `await`, asyncio tasks and `asyncio.to_thread`, but
|
|
2053
|
+
not `ThreadPoolExecutor`, `threading.Thread` or `loop.run_in_executor`: those
|
|
2054
|
+
start the thread in an empty context. AI calls made on such a thread are not metered when selective metering
|
|
2055
|
+
is on, and are recorded without the decorator's tags when it is off.
|
|
2056
|
+
|
|
2057
|
+
To carry them, wrap the thread's target with `carry_context` inside the decorated
|
|
2058
|
+
function, each time you hand work to a thread:
|
|
2059
|
+
|
|
2060
|
+
```python
|
|
2061
|
+
from concurrent.futures import ThreadPoolExecutor
|
|
2062
|
+
from revenium_middleware import carry_context, revenium_meter, revenium_metadata
|
|
2063
|
+
|
|
2064
|
+
@revenium_meter()
|
|
2065
|
+
@revenium_metadata(task_type="premium-feature", organizationName="PremiumTier")
|
|
2066
|
+
def summarize_all(docs: list[str]) -> list[str]:
|
|
2067
|
+
with ThreadPoolExecutor() as pool:
|
|
2068
|
+
return list(pool.map(carry_context(summarize), docs))
|
|
2069
|
+
```
|
|
2070
|
+
|
|
2071
|
+
`carry_context` is not a decorator: a wrap made outside the decorated function
|
|
2072
|
+
carries nothing. With selective metering on, a thread started outside any
|
|
2073
|
+
decorated function is never metered through it; with it off, such calls are
|
|
2074
|
+
still metered, without the decorator's tags. Wrapping an `async def` carries
|
|
2075
|
+
nothing either, because its coroutine runs later on the event loop, outside the
|
|
2076
|
+
copied context: wrap the sync function the thread runs instead, or copy the
|
|
2077
|
+
context around the awaited call. It also carries a `metering_key()` or `idempotency_key()`
|
|
2078
|
+
block in force where it is called. The first time selective metering skips a
|
|
2079
|
+
call, the SDK logs one INFO line saying so.
|
|
2080
|
+
|
|
1719
2081
|
**Decorator order matters:** Place `@revenium_meter` before `@revenium_metadata` (outer to inner).
|
|
1720
2082
|
|
|
1721
2083
|
---
|
|
@@ -1744,6 +2106,8 @@ def lookup_customer(customer_id: str) -> dict:
|
|
|
1744
2106
|
result = lookup_customer("CUST-42")
|
|
1745
2107
|
```
|
|
1746
2108
|
|
|
2109
|
+
When a decorated tool raises, the event is sent with `success: false` and the exception's class (for example `HTTPStatusError`) as `errorMessage`, and the exception is re-raised. The message itself often holds request URLs, keys or personal data, so it is sent only when `REVENIUM_CAPTURE_ERROR_MESSAGES=true`, as `<Class>: <message>` capped at 2048 characters, with `[REDACTED]` in place of card numbers, every key shape prompt capture masks (plus `pk-` and `Token` values), JSON Web Tokens, query-string values, `Bearer` and `Basic` tokens, URL user names and passwords, values under labels ending in a sensitive name (`password`, `secret`, `token`, `api_key`, `authorization` and the like) and emails. An exception raised from a provider's HTTP error (an OpenAI, Anthropic, LiteLLM, google-genai, Perplexity or Ollama error, or an exception raised while handling one) can quote the request, prompt included, so its message is sent only when `REVENIUM_CAPTURE_PROMPTS=true` as well; otherwise the class alone is sent.
|
|
2110
|
+
|
|
1747
2111
|
**Manual reporting:**
|
|
1748
2112
|
|
|
1749
2113
|
```python
|
|
@@ -1758,6 +2122,8 @@ report_tool_call(
|
|
|
1758
2122
|
)
|
|
1759
2123
|
```
|
|
1760
2124
|
|
|
2125
|
+
**Transaction ids:** each tool event gets its own transaction id, so every tool call is recorded. A `transaction_id` you set through `context()`, `set_context()` or `report_tool_call()` groups tool calls: it is sent as the event's `traceId`, or as `usageMetadata.callerTransactionId` when you also set a `trace_id`. A retry the SDK makes itself (an HTTP retry, or a replay from the delivery buffer) reuses the event's id and is stored once. Calling `report_tool_call` twice records two events, even with identical arguments.
|
|
2126
|
+
|
|
1761
2127
|
---
|
|
1762
2128
|
|
|
1763
2129
|
## Prompt Capture
|
|
@@ -1774,12 +2140,30 @@ export REVENIUM_CAPTURE_PROMPTS=true
|
|
|
1774
2140
|
|
|
1775
2141
|
| Field | Description | Source |
|
|
1776
2142
|
|-------|-------------|--------|
|
|
1777
|
-
| `system_prompt` | System prompt content | From `system` parameter / system message |
|
|
1778
|
-
| `input_messages` | User/assistant messages as JSON | From `messages` parameter |
|
|
1779
|
-
| `output_response` | Assistant's response content | From response content blocks |
|
|
1780
|
-
| `prompts_truncated` | Truncation flag | Set to `true` if any field exceeded
|
|
2143
|
+
| `system_prompt` | System prompt content | From `system` parameter / system message; for the OpenAI Responses API, `instructions` (else the first `system` or `developer` input item) |
|
|
2144
|
+
| `input_messages` | User/assistant messages as JSON | From `messages` parameter, or the Responses API `input` |
|
|
2145
|
+
| `output_response` | Assistant's response content | From response content blocks, or the text of a Responses API reply's messages |
|
|
2146
|
+
| `prompts_truncated` | Truncation flag | Set to `true` if any field exceeded its maximum length |
|
|
2147
|
+
|
|
2148
|
+
Each field has a maximum length of **50,000 characters**. If exceeded, it's truncated with a `...[TRUNCATED]` marker. `input_messages` is always stored as valid JSON: when the messages do not fit, the longest texts are shortened first, each ending in the marker, and if that is not enough the oldest messages are left out.
|
|
2149
|
+
|
|
2150
|
+
Credentials in these three fields are masked before they leave your process, both in the records the provider integrations send with prompt capture on and in the text values of `systemPrompt`, `inputMessages` and `outputResponse` sent with `AgenticOutcomeClient.emit_completion`: keys starting `sk-`, `sk-proj-`, `sk-ant-`, `pplx-`, `xai-`, `gsk_`, `AIza`, `AKIA`, `ghp_`, `ghs_`, `gho_`, `ghu_`, `ghr_`, `github_pat_`, `hf_`, `rev_sk_`, `rev_mk_` and `hak_`, Slack tokens (`xoxb-`, `xoxp-` and the other `xox?-` forms), the secret half of a fal key (`<key id>:<secret>`), PEM private key blocks (`-----BEGIN PRIVATE KEY-----` and the RSA, EC and OpenSSH forms), card numbers, JSON Web Tokens, `Bearer` tokens, `Basic` credentials, the password in an address such as `postgres://user:password@host`, the signature of a presigned S3, Google Cloud Storage or Azure link, and the value after any label ending in `password`, `passwd`, `pwd`, `secret`, `secrets`, `token`, `api_key`, `credential` or `credentials`, or ending in `key` and naming a secret, private, access, API, auth, signing, client, session, master, encryption, account or storage key (so `AWS_SECRET_ACCESS_KEY=` and `private_key:` are masked, `password_hint:` and `max_tokens:` are not). The key's prefix, a fal key's id, a link's path and other parameters, and an address's user and host are kept; the secret is replaced with `***REDACTED***` (`***REDACTED_JWT***` for a JSON Web Token). A key glued to the letters or digits before it is not recognized.
|
|
2151
|
+
|
|
2152
|
+
Only signed JSON Web Tokens are masked to `***REDACTED_JWT***`, wherever the SDK masks them: three parts joined by dots, the first containing `eyJ` and the second starting with it. An encrypted five-part token and an unsigned token whose last part is empty are sent as written.
|
|
2153
|
+
|
|
2154
|
+
For LiteLLM, capture covers client mode chat calls (`completion`, `acompletion` and their streams), with the same fields and truncation as the OpenAI integration. Embeddings are not captured, and the LiteLLM gateway plugin does not capture the prompts or replies of the calls it proxies.
|
|
2155
|
+
|
|
2156
|
+
### Maximum Length
|
|
2157
|
+
|
|
2158
|
+
```bash
|
|
2159
|
+
export REVENIUM_MAX_PROMPT_SIZE=20000
|
|
2160
|
+
```
|
|
2161
|
+
|
|
2162
|
+
`REVENIUM_MAX_PROMPT_SIZE` sets the maximum length for every integration, as in the Go and Node SDKs. It must be a positive whole number; any other value is ignored with a warning. A value below 200 is raised to 200, the smallest length that still holds the `...[TRUNCATED]` marker, with a warning. Gemini and Vertex AI also read `REVENIUM_MAX_PROMPT_LENGTH`, and `REVENIUM_MAX_PROMPT_SIZE` wins when both are set. For Gemini and Vertex AI the length is capped at 1,000,000 characters; this cap is Python only.
|
|
2163
|
+
|
|
2164
|
+
The SDK reads these settings once, when it is imported, so call `load_dotenv()` before importing it.
|
|
1781
2165
|
|
|
1782
|
-
|
|
2166
|
+
The Go and Node SDKs also read `REVENIUM_ORGANIZATION_ID`, `REVENIUM_ORGANIZATION_NAME` and `REVENIUM_PRINT_SUMMARY`; the Python SDK does not.
|
|
1783
2167
|
|
|
1784
2168
|
### Example
|
|
1785
2169
|
|
|
@@ -1804,6 +2188,10 @@ response = client.chat.completions.create(
|
|
|
1804
2188
|
|
|
1805
2189
|
Prompt capture works with both streaming and non-streaming requests, and with multimodal content (text, images, etc.).
|
|
1806
2190
|
|
|
2191
|
+
On the OpenAI Responses API, capture covers `responses.create` and `responses.stream`, sync or async, streamed or not, through `with_raw_response`, and background calls. A Responses call captures only its own `instructions` and `input`: earlier turns OpenAI holds for you through `previous_response_id` or `conversation`, and a stored prompt template passed as `prompt=`, are not captured. `output_response` holds the text of the assistant's messages only; tool calls, reasoning and refusals are not captured, as for chat calls. Async `with_streaming_response` calls that are not streamed (`AsyncOpenAI` `chat.completions.with_streaming_response.create(...)` and `responses.with_streaming_response.create(...)`, read with `await response.parse()`) are not recorded today, so nothing is captured for them. Calls the SDK does not meter at all are not captured either; see [Calls the SDK does not meter](#calls-the-sdk-does-not-meter).
|
|
2192
|
+
|
|
2193
|
+
LangChain calls the SDK records through its callback (chat models no Revenium client integration meters, for example ChatMistralAI, ChatCohere, Fireworks, Hugging Face and langchain-google-vertexai models, and text-completion models) capture the system prompt, input messages and reply too, sync or async, streamed or not. A text-completion prompt is stored as one `user` message. Tool calls inside the history are not captured, though the OpenAI chat integration keeps them; a tool message keeps its `tool_call_id`.
|
|
2194
|
+
|
|
1807
2195
|
### Security Considerations
|
|
1808
2196
|
|
|
1809
2197
|
- Prompts may contain sensitive user data
|
|
@@ -1820,7 +2208,7 @@ Block outbound provider requests client-side when a Revenium cost control trips.
|
|
|
1820
2208
|
|
|
1821
2209
|
> **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.
|
|
1822
2210
|
|
|
1823
|
-
|
|
2211
|
+
Every provider middleware checks the cap: OpenAI, Azure OpenAI, Anthropic (including Claude on Bedrock and Foundry), Google Gemini and Vertex AI, Ollama, Perplexity, fal, the LiteLLM client and proxy, and the LangChain callback.
|
|
1824
2212
|
|
|
1825
2213
|
### Enable
|
|
1826
2214
|
|
|
@@ -1845,11 +2233,13 @@ REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream # optional
|
|
|
1845
2233
|
| `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. |
|
|
1846
2234
|
| `REVENIUM_CB_POLL_INTERVAL_SECONDS` | `60` | Background poll interval for rule refreshes. |
|
|
1847
2235
|
| `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `BudgetExceededError` until rules are loaded. |
|
|
1848
|
-
| `REVENIUM_CACHE_DIR` |
|
|
2236
|
+
| `REVENIUM_CACHE_DIR` | unset | When set, the rule cache is mirrored to `<dir>/revenium_enforcement_rules.<scope>.json` so a restarted process doesn't fail-closed on the very first call. `<scope>` is a short hash of the enforcement base URL and `REVENIUM_TEAM_ID`, so services for different teams can share one folder and each loads only its own rules. Nothing is saved without `REVENIUM_TEAM_ID`. |
|
|
2237
|
+
|
|
2238
|
+
On/off and mode settings ignore case and surrounding spaces or line endings; a value the SDK does not recognise keeps the default and logs one warning naming the setting.
|
|
1849
2239
|
|
|
1850
2240
|
### Public API
|
|
1851
2241
|
|
|
1852
|
-
Enforcement
|
|
2242
|
+
Enforcement starts with the first call any provider middleware checks, for example:
|
|
1853
2243
|
|
|
1854
2244
|
```python
|
|
1855
2245
|
import revenium_middleware.openai # auto-instruments openai
|
|
@@ -1858,7 +2248,20 @@ import openai
|
|
|
1858
2248
|
client = openai.OpenAI()
|
|
1859
2249
|
```
|
|
1860
2250
|
|
|
1861
|
-
The pre-call check fires before every
|
|
2251
|
+
The pre-call check fires before every call these middlewares meter, including streamed, raw-response, beta and async variants and calls selective metering leaves unmetered:
|
|
2252
|
+
|
|
2253
|
+
- OpenAI and Azure OpenAI: chat completions, responses, embeddings and audio.
|
|
2254
|
+
- Anthropic, including Claude on Bedrock (`AnthropicBedrock`, and raw boto3 calls with `REVENIUM_BEDROCK_TRANSPORT=1`), Claude on Vertex AI (`AnthropicVertex`) and Foundry: `messages.create`, `stream` and `parse`, and their beta twins.
|
|
2255
|
+
- Google: google-genai content, embeddings, Imagen and Veo, and Vertex AI generation, chat, embeddings and Imagen.
|
|
2256
|
+
- Ollama: chat, generate, embed and embeddings.
|
|
2257
|
+
- Perplexity: the native client and the OpenAI-compatible client.
|
|
2258
|
+
- fal: run, stream, submit and subscribe.
|
|
2259
|
+
- LiteLLM: client completions and embeddings, and the proxy guardrail.
|
|
2260
|
+
- LangChain: the callback checks every model unless its calls go through a Revenium middleware that is imported and checks them itself (OpenAI and Azure OpenAI, including DeepSeek, xAI, Together, Cerebras, Upstage and `ChatOpenAIMantle`; Anthropic, including `ChatAnthropicBedrock`, `ChatAnthropicMantle` and `ChatAnthropicVertex`; Gemini through `langchain-google-genai`; Ollama; LiteLLM; Perplexity; Claude on Bedrock with the Bedrock transport). So Groq, Fireworks, Mistral, Cohere, Hugging Face, `langchain-google-vertexai` Gemini and any vendor not listed here are checked by the callback. So are LangChain's text-completion models (`OpenAI`, `AzureOpenAI` and other `BaseOpenAI` subclasses): they call the legacy completions endpoint, which no middleware checks. `AnthropicLLM` and `OllamaLLM` are checked by their middleware. A refusal there is logged by LangChain at WARNING before it reaches your code.
|
|
2261
|
+
|
|
2262
|
+
LangChain embeddings models run no callbacks: `OpenAIEmbeddings` and `AzureOpenAIEmbeddings` are checked by the OpenAI middleware, Ollama embeddings are checked by the Ollama middleware, embeddings from other vendors are not checked.
|
|
2263
|
+
|
|
2264
|
+
When the circuit breaker is disabled, it is a no-op. When enabled:
|
|
1862
2265
|
|
|
1863
2266
|
1. A daemon thread (`revenium-enforcement-poll`) starts on first use.
|
|
1864
2267
|
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.
|
|
@@ -1866,13 +2269,17 @@ The pre-call check fires before every chat / embeddings / responses call. When t
|
|
|
1866
2269
|
4. A refresh that fails (timeout, refused connection, 5xx, or any 4xx such as a 403 for a wrong key or team id) keeps the cached rules, logs a warning, and is not retried for one `REVENIUM_CB_POLL_INTERVAL_SECONDS`, however much traffic arrives meanwhile.
|
|
1867
2270
|
5. `204 No Content` is treated as "no rules configured" — the cache is cleared.
|
|
1868
2271
|
|
|
2272
|
+
A rule with filters (a cap scoped to an agent, model, provider, subscriber, credential, task type, product or organization) blocks or warns only the calls that match all of them; a filter the SDK cannot evaluate, such as the model of a LiteLLM proxy request, keeps the rule applying.
|
|
2273
|
+
|
|
2274
|
+
A model filter also holds a vendor's own aliases for the model it names, because Revenium records those calls under the model the vendor serves; an alias is honoured only on a call that can reach that vendor (its own client, a LiteLLM route to it, or a bare LiteLLM model name), so an Ollama model that shares the name is not held. A Gemini `-latest` alias (`gemini-flash-latest`, `gemini-flash-lite-latest`, `gemini-pro-latest`) is held by a `MODEL IS` or `MODEL IN` cap on any version of the same tier, such as `gemini-3.8-flash`, since Google moves the alias to each new model of that tier; a cap on another tier, or on a TTS, audio or image variant, does not hold it. A substring model filter (`CONTAINS`, `STARTS_WITH`, `ENDS_WITH`) whose value is a full model name of the same tier, such as `CONTAINS gemini-3.8-flash`, holds the alias the same way. A substring filter whose value is only part of a name, such as `STARTS_WITH gemini-3.8`, holds it only when the alias text itself matches, because which model Google will serve is not known before the call. Google's other `-latest` names that do not follow `gemini-<tier>-latest` (`antigravity-preview-latest`, `gemini-2.5-flash-native-audio-latest`) are held only by a cap on that name. On Vertex AI, which records the alias itself, a cap on the alias name holds it as well. An xAI short name such as `grok-4.20` or `grok-code-fast-1` is held by a cap on the full model xAI answers with (`grok-4.20-0309-reasoning`, `grok-build-0.1`), for every name xAI listed when this SDK version shipped; a name xAI adds or repoints later is held only after an SDK update.
|
|
2275
|
+
|
|
1869
2276
|
### Exception Contract
|
|
1870
2277
|
|
|
1871
2278
|
```python
|
|
1872
|
-
from revenium_middleware
|
|
2279
|
+
from revenium_middleware import BudgetExceededError
|
|
1873
2280
|
```
|
|
1874
2281
|
|
|
1875
|
-
When a tripped rule matches the current request, the middleware raises before the
|
|
2282
|
+
When a tripped rule matches the current request, the middleware raises before the provider call is made. `revenium_middleware.openai` still exports the same class. All structured fields are populated when the server provides them:
|
|
1876
2283
|
|
|
1877
2284
|
| Attribute | Type | Description |
|
|
1878
2285
|
|-----------|------|-------------|
|
|
@@ -1882,11 +2289,29 @@ When a tripped rule matches the current request, the middleware raises before th
|
|
|
1882
2289
|
| `threshold` | `float \| None` | Configured limit |
|
|
1883
2290
|
| `resets_at` | `str \| None` | ISO-8601 timestamp the rule next resets |
|
|
1884
2291
|
| `rule_id` | `str \| int \| None` | Server-side rule identifier |
|
|
2292
|
+
| `deny_message` | `str \| None` | The message written for the rule, when it has one; also appended to `message` |
|
|
2293
|
+
|
|
2294
|
+
When the breached rule carries a deny message, `message` is the usual text followed by that message, for example `"Request blocked by Revenium enforcement rule: monthly-gpt4-cap. Ask the user before retrying."`, and `deny_message` holds the message alone, so your code can show it as written. Placeholders in it, such as `{spent}` or `{model}`, are shown exactly as written and not filled in by this SDK; read `current_value`, `threshold`, `rule_name` and `resets_at` from the exception for those values. A rule without a deny message keeps the usual text and leaves `deny_message` as `None`.
|
|
2295
|
+
|
|
2296
|
+
`BudgetExceededError` does **not** inherit from `ReveniumMiddlewareError`, and no provider middleware swallows it, so it reaches your `except` block, with two exceptions.
|
|
1885
2297
|
|
|
1886
|
-
|
|
2298
|
+
Griptape turns errors inside a task into an error result, so call `enable_budget_errors()` once at setup, or `raise_if_budget_exceeded(agent)` after a run; see [Griptape](#griptape).
|
|
2299
|
+
|
|
2300
|
+
`litellm.batch_completion` runs each item on its own thread and returns a refused item's `BudgetExceededError` as that item's entry in the result list instead of raising it, so check each entry:
|
|
1887
2301
|
|
|
1888
2302
|
```python
|
|
1889
|
-
|
|
2303
|
+
import litellm
|
|
2304
|
+
from revenium_middleware import BudgetExceededError
|
|
2305
|
+
|
|
2306
|
+
batch = [[{"role": "user", "content": "Summarize A"}], [{"role": "user", "content": "Summarize B"}]]
|
|
2307
|
+
results = litellm.batch_completion(model="gpt-4o-mini", messages=batch)
|
|
2308
|
+
refused = [r for r in results if isinstance(r, BudgetExceededError)]
|
|
2309
|
+
```
|
|
2310
|
+
|
|
2311
|
+
`litellm.batch_completion_models_all_responses` leaves a refused model out of its result list without raising.
|
|
2312
|
+
|
|
2313
|
+
```python
|
|
2314
|
+
from revenium_middleware import BudgetExceededError
|
|
1890
2315
|
import openai
|
|
1891
2316
|
|
|
1892
2317
|
client = openai.OpenAI()
|
|
@@ -1969,6 +2394,55 @@ revenium_middleware.initialize_metering(
|
|
|
1969
2394
|
`initialize_metering()` returns `True` when metering is enabled after the
|
|
1970
2395
|
call; invoke it with no arguments to re-read the environment.
|
|
1971
2396
|
|
|
2397
|
+
#### Metering Several Customers in One Process
|
|
2398
|
+
|
|
2399
|
+
`initialize_metering()` sets one key for the whole process. The record of a non-streamed
|
|
2400
|
+
OpenAI (chat, Responses or embeddings), Anthropic `messages.create` (including
|
|
2401
|
+
Claude on Bedrock through the Anthropic client), LiteLLM, Ollama or Perplexity
|
|
2402
|
+
call is filed under the key that is current when the call returns. The
|
|
2403
|
+
exceptions are an Anthropic `with_streaming_response` call and a Perplexity
|
|
2404
|
+
response read raw or lazily, which keep the key from when they started. Every
|
|
2405
|
+
other record, including streamed calls, `@meter_tool` tool events, and Google
|
|
2406
|
+
Gemini, Vertex AI, OpenAI audio, fal.ai and raw boto3 Bedrock calls, keeps the
|
|
2407
|
+
key that was current when it started; one started while metering was off is not
|
|
2408
|
+
recorded. A call that fails with a provider error is also filed under the key
|
|
2409
|
+
from when it started. A call made through LangChain, CrewAI or Griptape follows
|
|
2410
|
+
the rule of the provider client it uses, except that a LangChain call recorded
|
|
2411
|
+
by the Revenium callback rather than by a provider client, such as
|
|
2412
|
+
`wrap(ChatOllama(...))` without the Ollama middleware, keeps the key from when the
|
|
2413
|
+
run started. So switching keys with
|
|
2414
|
+
`initialize_metering()` while another thread or asyncio task still has a call
|
|
2415
|
+
or a metered tool running can send that record under the new key.
|
|
2416
|
+
|
|
2417
|
+
To meter several of your own customers at once, give each thread or asyncio
|
|
2418
|
+
task its own key with `metering_key()`:
|
|
2419
|
+
|
|
2420
|
+
```python
|
|
2421
|
+
import revenium_middleware
|
|
2422
|
+
|
|
2423
|
+
with revenium_middleware.metering_key("hak_customer_key"):
|
|
2424
|
+
client.chat.completions.create(...)
|
|
2425
|
+
```
|
|
2426
|
+
|
|
2427
|
+
The key applies to the usage records and tool events of calls made inside the
|
|
2428
|
+
block, on that thread or asyncio task only: a thread started inside the block
|
|
2429
|
+
does not inherit it, while an asyncio task created inside it does. Wrap the
|
|
2430
|
+
thread's target with `carry_context` to carry the key.
|
|
2431
|
+
`base_url` is optional and defaults to the address set with
|
|
2432
|
+
`initialize_metering()` or `REVENIUM_METERING_BASE_URL`. An empty or malformed
|
|
2433
|
+
key raises `ValueError`.
|
|
2434
|
+
|
|
2435
|
+
- A key set with `configure(api_key=...)` still wins for tool events, and those events go to the address set with `configure(metering_url=...)`, else the process-wide address, never to the block's `base_url`. Without a `configure()` key, tool events in the block go out with the block's key and the block's address together, even when the block sets no `base_url` (the block's key then goes to the process-wide address); `configure(metering_url=...)` alone does not redirect them.
|
|
2436
|
+
- Spending caps follow the process-wide key (the environment or
|
|
2437
|
+
`initialize_metering()`) and `REVENIUM_TEAM_ID`, never the key of a
|
|
2438
|
+
`metering_key()` block. A service that sets keys only with `metering_key()`
|
|
2439
|
+
has no process-wide key, so it gets no spending caps, and with
|
|
2440
|
+
`REVENIUM_CB_FAIL_MODE=closed` every call is refused.
|
|
2441
|
+
- Outcomes and jobs are not covered: they need a write key (`rev_sk_`).
|
|
2442
|
+
- Delivery pauses for the whole process while Revenium is not answering at
|
|
2443
|
+
any one address (see [Metering Delivery and Timeouts](#metering-delivery-and-timeouts));
|
|
2444
|
+
the records held back meanwhile are replayed later under their own key.
|
|
2445
|
+
|
|
1972
2446
|
### Metering Delivery and Timeouts
|
|
1973
2447
|
|
|
1974
2448
|
Usage records are never sent on your request path. A metered call puts its
|
|
@@ -1985,8 +2459,8 @@ a few idle threads and the queue's memory, never a thread per call.
|
|
|
1985
2459
|
| `REVENIUM_METERING_CONNECT_TIMEOUT_SECONDS` | `5` | Seconds one attempt waits for a connection |
|
|
1986
2460
|
| `REVENIUM_METERING_MAX_RETRIES` | `2` | Retries after the first attempt |
|
|
1987
2461
|
|
|
1988
|
-
The two timeouts also apply to tool events,
|
|
1989
|
-
retries, and a replay from the store-and-forward buffer is a single attempt
|
|
2462
|
+
The two timeouts also apply to tool events, including those sent with
|
|
2463
|
+
`emit_tool_event`, which are sent once without retries, and a replay from the store-and-forward buffer is a single attempt
|
|
1990
2464
|
that waits at most `REVENIUM_METERING_TIMEOUT_SECONDS`.
|
|
1991
2465
|
|
|
1992
2466
|
Each thread sends one record at a time, so the threads keep up with about one
|
|
@@ -2061,7 +2535,7 @@ steps against one budget of `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` (5 seconds by
|
|
|
2061
2535
|
default), each using whatever time the previous ones left: it waits for the
|
|
2062
2536
|
background threads to send the records still queued, builds the records that
|
|
2063
2537
|
overflowed to the store-and-forward buffer, then flushes the buffer, oldest
|
|
2064
|
-
first
|
|
2538
|
+
first, up to 32 records at a time, one attempt per record. Once a usage record or a tool event fails
|
|
2065
2539
|
in a way worth retrying (unreachable, timed out, 429 or 5xx), the flush sends
|
|
2066
2540
|
no more records of that kind, leaving them unsent, and keeps sending the other
|
|
2067
2541
|
kind, since tool events can go to a different endpoint. Records still queued, being sent, unbuilt
|
|
@@ -2077,6 +2551,43 @@ replaces the SDK's. The flush then happens only if that handler exits
|
|
|
2077
2551
|
normally: a handler that restores SIGTERM's default action and re-raises it,
|
|
2078
2552
|
as uvicorn does after its own shutdown, ends the process before `atexit` runs.
|
|
2079
2553
|
|
|
2554
|
+
#### Worker processes
|
|
2555
|
+
|
|
2556
|
+
A `multiprocessing` child started with the fork or forkserver start method
|
|
2557
|
+
(the Linux default) ends through `os._exit`, which skips `atexit`. The SDK
|
|
2558
|
+
therefore also flushes a `multiprocessing.Process` child when its target
|
|
2559
|
+
returns, with the same budget and the same warning. Both start methods fork
|
|
2560
|
+
the child from a process that has imported the SDK, and a forked child starts
|
|
2561
|
+
with its own metering queue, buffer and connections: it never sends records
|
|
2562
|
+
its parent queued, and its warning counts only its own records.
|
|
2563
|
+
|
|
2564
|
+
Some worker shapes still need a call from you, or are not covered:
|
|
2565
|
+
|
|
2566
|
+
- `multiprocessing.Pool` workers flush when the worker process exits (after
|
|
2567
|
+
`pool.close(); pool.join()`, or at `maxtasksperchild`), not after each task.
|
|
2568
|
+
Leaving a `with Pool() as pool:` block calls `terminate()`, which kills the
|
|
2569
|
+
workers and can still lose their last records.
|
|
2570
|
+
- A raw `os.fork()` worker, or an RQ work horse, that ends with `os._exit`
|
|
2571
|
+
must call `flush_metering()` at the end of each job.
|
|
2572
|
+
- Celery's prefork pool (billiard) is not covered; call `flush_metering()` at
|
|
2573
|
+
the end of a task if its worker processes end that way.
|
|
2574
|
+
- Under fork and forkserver, records made by threads still running after the
|
|
2575
|
+
target returns are not delivered.
|
|
2576
|
+
|
|
2577
|
+
```python
|
|
2578
|
+
import revenium_middleware
|
|
2579
|
+
|
|
2580
|
+
def job():
|
|
2581
|
+
... # model calls
|
|
2582
|
+
left = revenium_middleware.flush_metering() # waits up to REVENIUM_SHUTDOWN_TIMEOUT_SECONDS
|
|
2583
|
+
# left == 0: every record was sent; otherwise that many are still unsent
|
|
2584
|
+
```
|
|
2585
|
+
|
|
2586
|
+
`flush_metering(timeout_seconds=None)` sends the records queued or held so
|
|
2587
|
+
far and returns how many are still unsent. Metering carries on afterwards, so
|
|
2588
|
+
a long-lived worker can call it after every job. A negative or non-finite
|
|
2589
|
+
timeout raises `ValueError`.
|
|
2590
|
+
|
|
2080
2591
|
### Optional Environment Variables
|
|
2081
2592
|
|
|
2082
2593
|
| Variable | Default | Description |
|
|
@@ -2084,24 +2595,26 @@ as uvicorn does after its own shutdown, ends the process before `atexit` runs.
|
|
|
2084
2595
|
| `REVENIUM_METERING_BASE_URL` | `https://api.revenium.ai` | Revenium API endpoint |
|
|
2085
2596
|
| `REVENIUM_LOG_LEVEL` | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
|
|
2086
2597
|
| `REVENIUM_CAPTURE_PROMPTS` | `false` | Enable prompt capture |
|
|
2598
|
+
| `REVENIUM_CAPTURE_ERROR_MESSAGES` | `false` | Send the exception message, redacted and capped at 2048 characters, with failed `@meter_tool` events and auto-failed `JobContext` outcomes, and cut to 255 characters (keeping its "(HTTP <status>)" ending) on the record of a failed OpenAI, Anthropic, LiteLLM, Google, Perplexity or Ollama call; off sends the exception class only (with the HTTP status for a failed call). A provider HTTP error's message, which can quote the request, is sent only when `REVENIUM_CAPTURE_PROMPTS` is also on |
|
|
2087
2599
|
| `REVENIUM_SELECTIVE_METERING` | `false` | Only meter `@revenium_meter` decorated functions |
|
|
2088
2600
|
| `REVENIUM_TEAM_ID` | - | Team ID for cost lookups and outcome reporting (JobContext team resolution) |
|
|
2089
2601
|
| `REVENIUM_ENVIRONMENT` | - | Deployment environment (auto-detects from `ENVIRONMENT`, `DEPLOYMENT_ENV`) |
|
|
2090
2602
|
| `REVENIUM_REGION` | - | Cloud region (auto-detects from `AWS_REGION`, `AZURE_REGION`, `GCP_REGION`) |
|
|
2091
|
-
| `REVENIUM_CREDENTIAL_ALIAS` | - |
|
|
2603
|
+
| `REVENIUM_CREDENTIAL_ALIAS` | - | Provider API key name, recorded as the subscriber's credential name on calls with no subscriber id or email |
|
|
2092
2604
|
| `REVENIUM_TRACE_TYPE` | - | Workflow category identifier |
|
|
2093
2605
|
| `REVENIUM_TRACE_NAME` | - | Human-readable trace label |
|
|
2094
2606
|
| `REVENIUM_PARENT_TRANSACTION_ID` | - | Parent transaction ID for distributed tracing |
|
|
2095
2607
|
| `REVENIUM_TRANSACTION_NAME` | - | Human-friendly operation name |
|
|
2096
2608
|
| `REVENIUM_RETRY_NUMBER` | - | Retry attempt number |
|
|
2097
|
-
| `REVENIUM_AGENTIC_JOB_ID` | - | Agentic job instance ID attached to all completions in the process (triggers backend job auto-creation) |
|
|
2609
|
+
| `REVENIUM_AGENTIC_JOB_ID` | - | Agentic job instance ID attached to all completions in the process (triggers backend job auto-creation; same format rule as `JobContext`) |
|
|
2098
2610
|
| `REVENIUM_AGENTIC_JOB_NAME` | - | Human-readable agentic job name |
|
|
2099
2611
|
| `REVENIUM_AGENTIC_JOB_TYPE` | - | Agentic job type category |
|
|
2100
2612
|
| `REVENIUM_AGENTIC_JOB_VERSION` | - | Agentic job version |
|
|
2101
2613
|
| `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` |
|
|
2102
2614
|
| `REVENIUM_OUTCOME_API_KEY` | - | Deprecated fallback name for the write-scope key; used only when `REVENIUM_WRITE_API_KEY` is unset |
|
|
2103
|
-
| `REVENIUM_PROFITSTREAM_BASE_URL` | `
|
|
2104
|
-
| `REVENIUM_BEDROCK_DISABLE` | - | Set to `1` to
|
|
2615
|
+
| `REVENIUM_PROFITSTREAM_BASE_URL` | same address as `REVENIUM_METERING_BASE_URL` | Agentic outcomes API base URL. Only needed when outcomes live at a different address than usage. By default it follows the `REVENIUM_METERING_BASE_URL` environment variable: a trailing `/meter` is removed and a path prefix is kept. `AgenticOutcomeClient` also follows a usage address set in code with `initialize_metering(base_url=...)` or a `metering_key(..., base_url=...)` block, for its jobs and outcomes as for its usage records, unless this variable or `profitstream_base_url=` sets an outcome address, or `meter_base_url=` names an address other than the one in `REVENIUM_METERING_BASE_URL`. |
|
|
2616
|
+
| `REVENIUM_BEDROCK_DISABLE` | - | Set to `1` to stop Anthropic clients being detected as Bedrock; Foundry detection is unaffected. Raw boto3 calls metered with `REVENIUM_BEDROCK_TRANSPORT`, and LangChain's `ChatBedrock` and `ChatBedrockConverse`, are still recorded as AWS |
|
|
2617
|
+
| `REVENIUM_BEDROCK_TRANSPORT` | - | Set to `1` or `true` to meter Claude models called through a raw `boto3.client("bedrock-runtime")` (`invoke_model`, `invoke_model_with_response_stream`, `converse`, `converse_stream`); other Bedrock models are never metered this way |
|
|
2105
2618
|
| `REVENIUM_BUFFER_MAX_SIZE` | `20000` | Store-and-forward buffer capacity (oldest events evicted when full) |
|
|
2106
2619
|
| `REVENIUM_BUFFER_FLUSH_INTERVAL` | `30` | Seconds between automatic replay attempts for buffered events |
|
|
2107
2620
|
| `REVENIUM_METERING_WORKERS` | `32` | Background threads that send usage records (see [Metering Delivery and Timeouts](#metering-delivery-and-timeouts)) |
|
|
@@ -2112,6 +2625,8 @@ as uvicorn does after its own shutdown, ends the process before `atexit` runs.
|
|
|
2112
2625
|
| `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` | `5` | Total seconds the exit hook may spend sending queued usage records, building overflowed ones and flushing the buffer |
|
|
2113
2626
|
| `REVENIUM_INSTALL_SIGNAL_HANDLERS` | `false` | Set to `1` to flush metering before SIGTERM's default action ends the process (see [Shutdown](#shutdown)) |
|
|
2114
2627
|
|
|
2628
|
+
On/off and mode settings ignore case and surrounding spaces or line endings; a value the SDK does not recognise keeps the default and logs one warning naming the setting. `REVENIUM_DEBUG` and `REVENIUM_BEDROCK_DISABLE` are the exceptions: they ignore surrounding spaces or line endings, but `REVENIUM_DEBUG` accepts only `true`, `1` or `yes`, `REVENIUM_BEDROCK_DISABLE` accepts only `1`, and neither logs a warning for any other value.
|
|
2629
|
+
|
|
2115
2630
|
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.
|
|
2116
2631
|
|
|
2117
2632
|
### Provider-Specific Environment Variables
|
|
@@ -2142,18 +2657,18 @@ Per-call `usage_metadata` values take precedence over the `REVENIUM_AGENTIC_JOB_
|
|
|
2142
2657
|
| **No data in dashboard** | Enable debug logging with `REVENIUM_LOG_LEVEL=DEBUG` |
|
|
2143
2658
|
| **Import errors** | Ensure the correct extra is installed (e.g., `pip install revenium-python-sdk[openai]`) |
|
|
2144
2659
|
| **Azure: wrong model name** | Middleware auto-resolves deployment names; check with debug logging |
|
|
2145
|
-
| **Bedrock: AccessDenied** | Ensure `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` permissions |
|
|
2660
|
+
| **Bedrock: AccessDenied** | Ensure `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` permissions; add `bedrock:GetInferenceProfile` for application inference profile ARNs with `REVENIUM_BEDROCK_TRANSPORT=1`, or with `AnthropicBedrock` and cost controls on, and `bedrock:GetProvisionedModelThroughput` for Provisioned Throughput ARNs with `REVENIUM_BEDROCK_TRANSPORT=1` |
|
|
2146
2661
|
| **Bedrock: requests go to Anthropic** | Verify AWS credentials: `aws sts get-caller-identity` |
|
|
2147
|
-
| **Google: embeddings show 0 tokens** | Expected
|
|
2662
|
+
| **Google: embeddings show 0 tokens** | Expected on the Gemini API, which returns no embedding token count; use google-genai with `vertexai=True` (Vertex AI) for counted embeddings |
|
|
2148
2663
|
| **Google: "No module named 'vertexai'"** | Install correct extra: `pip install "revenium-python-sdk[google-vertex]"` |
|
|
2149
2664
|
| **Vertex AI: authentication errors** | Run `gcloud auth application-default login` |
|
|
2150
2665
|
| **Ollama: connection errors** | Ensure Ollama is running: `ollama serve` |
|
|
2151
2666
|
| **LangChain: provider shows "unknown"** | Ensure you're using a supported LangChain LLM class |
|
|
2152
2667
|
| **Streaming errors** | Check provider credentials; middleware auto-falls back gracefully |
|
|
2153
2668
|
|
|
2154
|
-
**Debug mode:** Set `REVENIUM_LOG_LEVEL=DEBUG` to see detailed provider detection, routing decisions, and metering payloads.
|
|
2669
|
+
**Debug mode:** Set `REVENIUM_LOG_LEVEL=DEBUG` (or `REVENIUM_DEBUG=true`, which is the same for every integration) to see detailed provider detection, routing decisions, and metering payloads, with credentials, emails and prompt or reply text redacted. Token counts, ids, model names and attribution names still print.
|
|
2155
2670
|
|
|
2156
|
-
**
|
|
2671
|
+
**Stop Bedrock detection on Anthropic clients:** Set `REVENIUM_BEDROCK_DISABLE=1` to disable Bedrock auto-detection on Anthropic clients. It does not send your calls to Anthropic directly: an `AnthropicBedrock` call still goes to AWS and is billed by AWS, but is recorded as provider `anthropic` at the Anthropic price. Foundry detection is unaffected - a Foundry client is still labelled `Foundry`. Raw boto3 calls metered with `REVENIUM_BEDROCK_TRANSPORT` and LangChain's `ChatBedrock` and `ChatBedrockConverse` are still recorded as AWS.
|
|
2157
2672
|
|
|
2158
2673
|
**Check initialization status (Anthropic):** Use `revenium_middleware.anthropic.is_initialized()` to verify setup.
|
|
2159
2674
|
|
|
@@ -2178,6 +2693,8 @@ Available log levels:
|
|
|
2178
2693
|
- `ERROR`: Error messages only
|
|
2179
2694
|
- `CRITICAL`: Critical error messages only
|
|
2180
2695
|
|
|
2696
|
+
`REVENIUM_DEBUG=true` is the same as `REVENIUM_LOG_LEVEL=DEBUG` for every integration, and takes precedence over `REVENIUM_LOG_LEVEL`. Both are read when `revenium_middleware` is first imported; a level your application sets on the `revenium_middleware` logger afterwards takes precedence.
|
|
2697
|
+
|
|
2181
2698
|
## Compatibility
|
|
2182
2699
|
|
|
2183
2700
|
- Python 3.8+
|