revenium-python-sdk 0.9.1__tar.gz → 0.10.0__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.
Files changed (224) hide show
  1. revenium_python_sdk-0.10.0/PKG-INFO +2730 -0
  2. revenium_python_sdk-0.10.0/README.md +2614 -0
  3. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/pyproject.toml +32 -2
  4. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/__init__.py +58 -10
  5. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/__init__.py +7 -1
  6. revenium_python_sdk-0.10.0/revenium_middleware/_core/cache_tokens.py +456 -0
  7. revenium_python_sdk-0.10.0/revenium_middleware/_core/call_context.py +37 -0
  8. revenium_python_sdk-0.10.0/revenium_middleware/_core/call_ownership.py +385 -0
  9. revenium_python_sdk-0.10.0/revenium_middleware/_core/closable_scope.py +39 -0
  10. revenium_python_sdk-0.10.0/revenium_middleware/_core/config.py +414 -0
  11. revenium_python_sdk-0.10.0/revenium_middleware/_core/context.py +503 -0
  12. revenium_python_sdk-0.10.0/revenium_middleware/_core/decorators.py +383 -0
  13. revenium_python_sdk-0.10.0/revenium_middleware/_core/delivery_circuit.py +103 -0
  14. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/enforcement.py +1055 -164
  15. revenium_python_sdk-0.10.0/revenium_middleware/_core/error_text.py +87 -0
  16. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/exceptions.py +4 -3
  17. revenium_python_sdk-0.10.0/revenium_middleware/_core/failed_calls.py +125 -0
  18. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/fields.py +67 -19
  19. revenium_python_sdk-0.10.0/revenium_middleware/_core/json_safe.py +266 -0
  20. revenium_python_sdk-0.10.0/revenium_middleware/_core/langchain_settings.py +55 -0
  21. revenium_python_sdk-0.10.0/revenium_middleware/_core/log_sanitize.py +266 -0
  22. revenium_python_sdk-0.10.0/revenium_middleware/_core/metering.py +722 -0
  23. revenium_python_sdk-0.10.0/revenium_middleware/_core/metering_buffer.py +1242 -0
  24. revenium_python_sdk-0.10.0/revenium_middleware/_core/metering_pool.py +473 -0
  25. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/metering_status.py +31 -4
  26. revenium_python_sdk-0.10.0/revenium_middleware/_core/metering_submission.py +215 -0
  27. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/outcomes.py +202 -22
  28. revenium_python_sdk-0.10.0/revenium_middleware/_core/package_versions.py +22 -0
  29. revenium_python_sdk-0.10.0/revenium_middleware/_core/parse_failures.py +44 -0
  30. revenium_python_sdk-0.10.0/revenium_middleware/_core/patch_registry.py +47 -0
  31. revenium_python_sdk-0.10.0/revenium_middleware/_core/perplexity_cost.py +141 -0
  32. revenium_python_sdk-0.10.0/revenium_middleware/_core/perplexity_usage_metadata.py +23 -0
  33. revenium_python_sdk-0.10.0/revenium_middleware/_core/prompt_extraction.py +549 -0
  34. revenium_python_sdk-0.10.0/revenium_middleware/_core/responses_status.py +29 -0
  35. revenium_python_sdk-0.10.0/revenium_middleware/_core/secret_shapes.py +211 -0
  36. revenium_python_sdk-0.10.0/revenium_middleware/_core/selective_metering.py +44 -0
  37. revenium_python_sdk-0.10.0/revenium_middleware/_core/shutdown_signals.py +87 -0
  38. revenium_python_sdk-0.10.0/revenium_middleware/_core/sse_body_tap.py +264 -0
  39. revenium_python_sdk-0.10.0/revenium_middleware/_core/subscriber.py +117 -0
  40. revenium_python_sdk-0.10.0/revenium_middleware/_core/tool_event_transport.py +69 -0
  41. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/trace_fields.py +102 -55
  42. revenium_python_sdk-0.10.0/revenium_middleware/_core/usage_iterations.py +184 -0
  43. revenium_python_sdk-0.10.0/revenium_middleware/_core/vendor_model_aliases.py +69 -0
  44. revenium_python_sdk-0.10.0/revenium_middleware/_core/wire_guards.py +199 -0
  45. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_base_client.py +8 -3
  46. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_client.py +35 -82
  47. revenium_python_sdk-0.10.0/revenium_middleware/_metering/decorator.py +779 -0
  48. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/resources/ai.py +45 -24
  49. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/ai_create_audio_params.py +1 -3
  50. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/ai_create_completion_params.py +8 -3
  51. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/ai_create_image_params.py +1 -3
  52. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/ai_create_video_params.py +1 -3
  53. revenium_python_sdk-0.10.0/revenium_middleware/agentic_outcomes.py +565 -0
  54. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/__init__.py +10 -9
  55. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/bedrock_adapter.py +53 -19
  56. revenium_python_sdk-0.10.0/revenium_middleware/anthropic/bedrock_model_names.py +66 -0
  57. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/bedrock_transport.py +260 -52
  58. revenium_python_sdk-0.10.0/revenium_middleware/anthropic/inference_profiles.py +453 -0
  59. revenium_python_sdk-0.10.0/revenium_middleware/anthropic/middleware.py +1749 -0
  60. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/prompt_extractor.py +81 -57
  61. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/provider.py +1 -1
  62. revenium_python_sdk-0.10.0/revenium_middleware/anthropic/raw_response.py +281 -0
  63. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/stream_create.py +95 -10
  64. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/fal/__init__.py +5 -2
  65. revenium_python_sdk-0.10.0/revenium_middleware/fal/_call.py +97 -0
  66. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/fal/_metering.py +108 -19
  67. revenium_python_sdk-0.10.0/revenium_middleware/fal/_queue.py +111 -0
  68. revenium_python_sdk-0.10.0/revenium_middleware/fal/middleware.py +338 -0
  69. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/fal/trace_fields.py +42 -108
  70. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/__init__.py +2 -38
  71. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/__init__.py +14 -0
  72. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/types.py +6 -0
  73. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/utils.py +261 -39
  74. revenium_python_sdk-0.10.0/revenium_middleware/google/config.py +41 -0
  75. revenium_python_sdk-0.10.0/revenium_middleware/google/google_ai/middleware.py +1304 -0
  76. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/prompt_extractor.py +5 -69
  77. revenium_python_sdk-0.10.0/revenium_middleware/google/vertex_ai/middleware.py +1253 -0
  78. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/__init__.py +4 -0
  79. revenium_python_sdk-0.10.0/revenium_middleware/griptape/_retry.py +12 -0
  80. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/anthropic_driver.py +2 -0
  81. revenium_python_sdk-0.10.0/revenium_middleware/griptape/budget_errors.py +150 -0
  82. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/litellm_driver.py +150 -43
  83. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/ollama_driver.py +2 -0
  84. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/openai_driver.py +18 -1
  85. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/openai_embedding_driver.py +2 -0
  86. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/universal_driver.py +63 -47
  87. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/job_context.py +81 -37
  88. revenium_python_sdk-0.10.0/revenium_middleware/job_history.py +392 -0
  89. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/job_type_economics.py +2 -5
  90. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/__init__.py +2 -1
  91. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/decorators.py +180 -303
  92. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/integrations/__init__.py +2 -2
  93. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/integrations/crewai.py +173 -74
  94. revenium_python_sdk-0.10.0/revenium_middleware/litellm/client/middleware.py +1038 -0
  95. revenium_python_sdk-0.10.0/revenium_middleware/litellm/proxy/_metering_owner.py +131 -0
  96. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/proxy/guardrail.py +476 -107
  97. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/proxy/middleware.py +217 -80
  98. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/ollama/__init__.py +8 -5
  99. revenium_python_sdk-0.10.0/revenium_middleware/ollama/middleware.py +567 -0
  100. revenium_python_sdk-0.10.0/revenium_middleware/openai/audio.py +463 -0
  101. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/azure_model_resolver.py +56 -3
  102. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/langchain/__init__.py +48 -4
  103. revenium_python_sdk-0.10.0/revenium_middleware/openai/langchain/_abandoned_runs.py +109 -0
  104. revenium_python_sdk-0.10.0/revenium_middleware/openai/langchain/_model_call.py +385 -0
  105. revenium_python_sdk-0.10.0/revenium_middleware/openai/langchain/_perplexity_cost_capture.py +103 -0
  106. revenium_python_sdk-0.10.0/revenium_middleware/openai/langchain/_prompt_capture.py +75 -0
  107. revenium_python_sdk-0.10.0/revenium_middleware/openai/langchain/_text_completion_usage.py +218 -0
  108. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/langchain/_utils.py +2 -1
  109. revenium_python_sdk-0.10.0/revenium_middleware/openai/langchain/unified_handler.py +999 -0
  110. revenium_python_sdk-0.10.0/revenium_middleware/openai/middleware.py +2777 -0
  111. revenium_python_sdk-0.10.0/revenium_middleware/openai/prompt_extractor.py +13 -0
  112. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/provider.py +33 -3
  113. revenium_python_sdk-0.10.0/revenium_middleware/openai/raw_response.py +52 -0
  114. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/trace_fields.py +2 -2
  115. revenium_python_sdk-0.10.0/revenium_middleware/openai/xai_usage.py +29 -0
  116. revenium_python_sdk-0.10.0/revenium_middleware/perplexity/_metering_scope.py +9 -0
  117. revenium_python_sdk-0.10.0/revenium_middleware/perplexity/middleware.py +555 -0
  118. revenium_python_sdk-0.10.0/revenium_middleware/perplexity/patching.py +30 -0
  119. revenium_python_sdk-0.10.0/revenium_middleware/perplexity/perplexity_sdk.py +333 -0
  120. revenium_python_sdk-0.10.0/revenium_middleware/perplexity/raw_response.py +141 -0
  121. revenium_python_sdk-0.10.0/revenium_middleware/perplexity/streaming.py +253 -0
  122. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/webhooks/_verify.py +1 -1
  123. revenium_python_sdk-0.10.0/revenium_python_sdk.egg-info/PKG-INFO +2730 -0
  124. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_python_sdk.egg-info/SOURCES.txt +45 -1
  125. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_python_sdk.egg-info/requires.txt +23 -1
  126. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/tests/test_metering.py +14 -14
  127. revenium_python_sdk-0.10.0/tests/test_metering_dispatch_timestamps.py +270 -0
  128. revenium_python_sdk-0.10.0/tests/test_patch_coverage.py +464 -0
  129. revenium_python_sdk-0.10.0/tests/test_release_verify_ticket.py +257 -0
  130. revenium_python_sdk-0.9.1/PKG-INFO +0 -2084
  131. revenium_python_sdk-0.9.1/README.md +0 -1987
  132. revenium_python_sdk-0.9.1/revenium_middleware/_core/cache_tokens.py +0 -172
  133. revenium_python_sdk-0.9.1/revenium_middleware/_core/config.py +0 -219
  134. revenium_python_sdk-0.9.1/revenium_middleware/_core/context.py +0 -254
  135. revenium_python_sdk-0.9.1/revenium_middleware/_core/decorators.py +0 -202
  136. revenium_python_sdk-0.9.1/revenium_middleware/_core/log_sanitize.py +0 -100
  137. revenium_python_sdk-0.9.1/revenium_middleware/_core/metering.py +0 -323
  138. revenium_python_sdk-0.9.1/revenium_middleware/_core/metering_buffer.py +0 -367
  139. revenium_python_sdk-0.9.1/revenium_middleware/_core/metering_submission.py +0 -101
  140. revenium_python_sdk-0.9.1/revenium_middleware/_core/patch_registry.py +0 -21
  141. revenium_python_sdk-0.9.1/revenium_middleware/_core/prompt_extraction.py +0 -55
  142. revenium_python_sdk-0.9.1/revenium_middleware/_core/subscriber.py +0 -51
  143. revenium_python_sdk-0.9.1/revenium_middleware/_metering/decorator.py +0 -511
  144. revenium_python_sdk-0.9.1/revenium_middleware/agentic_outcomes.py +0 -424
  145. revenium_python_sdk-0.9.1/revenium_middleware/anthropic/middleware.py +0 -1548
  146. revenium_python_sdk-0.9.1/revenium_middleware/fal/middleware.py +0 -234
  147. revenium_python_sdk-0.9.1/revenium_middleware/google/config.py +0 -63
  148. revenium_python_sdk-0.9.1/revenium_middleware/google/google_ai/middleware.py +0 -652
  149. revenium_python_sdk-0.9.1/revenium_middleware/google/vertex_ai/middleware.py +0 -1189
  150. revenium_python_sdk-0.9.1/revenium_middleware/job_history.py +0 -130
  151. revenium_python_sdk-0.9.1/revenium_middleware/litellm/client/middleware.py +0 -283
  152. revenium_python_sdk-0.9.1/revenium_middleware/litellm/proxy/_metering_owner.py +0 -50
  153. revenium_python_sdk-0.9.1/revenium_middleware/ollama/middleware.py +0 -487
  154. revenium_python_sdk-0.9.1/revenium_middleware/openai/langchain/unified_handler.py +0 -605
  155. revenium_python_sdk-0.9.1/revenium_middleware/openai/middleware.py +0 -1952
  156. revenium_python_sdk-0.9.1/revenium_middleware/openai/prompt_extractor.py +0 -173
  157. revenium_python_sdk-0.9.1/revenium_middleware/perplexity/middleware.py +0 -394
  158. revenium_python_sdk-0.9.1/revenium_middleware/perplexity/perplexity_sdk.py +0 -277
  159. revenium_python_sdk-0.9.1/revenium_python_sdk.egg-info/PKG-INFO +0 -2084
  160. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/LICENSE +0 -0
  161. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/load_diagnostics.py +0 -0
  162. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/LICENSE +0 -0
  163. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/__init__.py +0 -0
  164. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_compat.py +0 -0
  165. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_constants.py +0 -0
  166. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_exceptions.py +0 -0
  167. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_files.py +0 -0
  168. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_models.py +0 -0
  169. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_qs.py +0 -0
  170. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_resource.py +0 -0
  171. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_response.py +0 -0
  172. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_streaming.py +0 -0
  173. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_types.py +0 -0
  174. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/__init__.py +0 -0
  175. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_logs.py +0 -0
  176. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_proxy.py +0 -0
  177. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_reflection.py +0 -0
  178. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_resources_proxy.py +0 -0
  179. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_streams.py +0 -0
  180. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_sync.py +0 -0
  181. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_transform.py +0 -0
  182. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_typing.py +0 -0
  183. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_utils.py +0 -0
  184. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_version.py +0 -0
  185. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/context.py +0 -0
  186. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/py.typed +0 -0
  187. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/resources/__init__.py +0 -0
  188. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/resources/apis.py +0 -0
  189. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/resources/events.py +0 -0
  190. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/__init__.py +0 -0
  191. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/api_meter_request_params.py +0 -0
  192. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/api_meter_response_params.py +0 -0
  193. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/event_create_params.py +0 -0
  194. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/metering_response_resource.py +0 -0
  195. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/config.py +0 -0
  196. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/trace_fields.py +0 -0
  197. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/fal/config.py +0 -0
  198. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/exceptions.py +0 -0
  199. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/protocols.py +0 -0
  200. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/trace_fields.py +0 -0
  201. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/google_ai/__init__.py +0 -0
  202. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/google_ai/provider.py +0 -0
  203. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/vertex_ai/__init__.py +0 -0
  204. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/google/vertex_ai/provider.py +0 -0
  205. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/_metadata.py +0 -0
  206. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/__init__.py +0 -0
  207. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/config.py +0 -0
  208. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/context.py +0 -0
  209. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/hooks.py +0 -0
  210. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/trace_fields.py +0 -0
  211. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/validation.py +0 -0
  212. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/proxy/__init__.py +0 -0
  213. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/ollama/trace_fields.py +0 -0
  214. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/__init__.py +0 -0
  215. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/azure_config.py +0 -0
  216. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/config.py +0 -0
  217. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/exceptions.py +0 -0
  218. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/perplexity/__init__.py +0 -0
  219. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/perplexity/provider.py +0 -0
  220. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/perplexity/trace_fields.py +0 -0
  221. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_middleware/webhooks/__init__.py +0 -0
  222. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_python_sdk.egg-info/dependency_links.txt +0 -0
  223. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/revenium_python_sdk.egg-info/top_level.txt +0 -0
  224. {revenium_python_sdk-0.9.1 → revenium_python_sdk-0.10.0}/setup.cfg +0 -0
@@ -0,0 +1,2730 @@
1
+ Metadata-Version: 2.4
2
+ Name: revenium-python-sdk
3
+ Version: 0.10.0
4
+ Summary: The official Revenium Python SDK — unified AI metering middleware for OpenAI, Anthropic, Google, Ollama, LiteLLM, Perplexity, and fal.ai.
5
+ Author-email: Revenium <support@revenium.io>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/revenium/revenium-python-sdk
8
+ Project-URL: Bug Tracker, https://github.com/revenium/revenium-python-sdk/issues
9
+ Project-URL: Documentation, https://docs.revenium.io
10
+ Keywords: sdk,ai,llm,middleware,metering,revenium,openai,anthropic,google,ollama,litellm,perplexity,fal
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.8
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: License :: OSI Approved :: MIT License
19
+ Classifier: Operating System :: OS Independent
20
+ Classifier: Intended Audience :: Developers
21
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
22
+ Requires-Python: >=3.8
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: anyio<5,>=3.5.0
26
+ Requires-Dist: distro<2,>=1.7.0
27
+ Requires-Dist: httpx<1,>=0.23.0
28
+ Requires-Dist: pydantic<3,>=1.9.0
29
+ Requires-Dist: sniffio
30
+ Requires-Dist: typing-extensions<5,>=4.10
31
+ Requires-Dist: wrapt>=1.14.0
32
+ Provides-Extra: openai
33
+ Requires-Dist: wrapt>=1.14.0; extra == "openai"
34
+ Requires-Dist: openai>=1.0.0; extra == "openai"
35
+ Requires-Dist: python-dotenv>=0.19.0; extra == "openai"
36
+ Provides-Extra: langchain
37
+ Requires-Dist: wrapt>=1.14.0; extra == "langchain"
38
+ Requires-Dist: langchain>=0.1.16; extra == "langchain"
39
+ Requires-Dist: langchain-openai>=0.1.0; extra == "langchain"
40
+ Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
41
+ Provides-Extra: griptape
42
+ Requires-Dist: griptape<2.0.0,>=1.0.0; python_version >= "3.10" and extra == "griptape"
43
+ Requires-Dist: requests>=2.25.0; extra == "griptape"
44
+ Provides-Extra: perplexity
45
+ Requires-Dist: wrapt>=1.14.0; extra == "perplexity"
46
+ Requires-Dist: python-dotenv>=0.19.0; extra == "perplexity"
47
+ Provides-Extra: perplexity-openai
48
+ Requires-Dist: wrapt>=1.14.0; extra == "perplexity-openai"
49
+ Requires-Dist: openai>=1.0.0; extra == "perplexity-openai"
50
+ Requires-Dist: python-dotenv>=0.19.0; extra == "perplexity-openai"
51
+ Provides-Extra: perplexity-native
52
+ Requires-Dist: wrapt>=1.14.0; extra == "perplexity-native"
53
+ Requires-Dist: perplexityai>=0.1.0; extra == "perplexity-native"
54
+ Requires-Dist: python-dotenv>=0.19.0; extra == "perplexity-native"
55
+ Provides-Extra: google
56
+ Requires-Dist: wrapt>=1.14.0; extra == "google"
57
+ Provides-Extra: google-genai
58
+ Requires-Dist: wrapt>=1.14.0; extra == "google-genai"
59
+ Requires-Dist: google-genai>=0.1.0; extra == "google-genai"
60
+ Requires-Dist: python-dotenv; extra == "google-genai"
61
+ Provides-Extra: google-vertex
62
+ Requires-Dist: wrapt>=1.14.0; extra == "google-vertex"
63
+ Requires-Dist: google-cloud-aiplatform>=1.71.1; extra == "google-vertex"
64
+ Requires-Dist: python-dotenv; extra == "google-vertex"
65
+ Provides-Extra: anthropic
66
+ Requires-Dist: wrapt>=1.14.0; extra == "anthropic"
67
+ Requires-Dist: anthropic>=0.30.0; extra == "anthropic"
68
+ Requires-Dist: python-dotenv>=0.19.0; extra == "anthropic"
69
+ Provides-Extra: ollama
70
+ Requires-Dist: wrapt>=1.14.0; extra == "ollama"
71
+ Requires-Dist: ollama>=0.3.0; extra == "ollama"
72
+ Requires-Dist: python-dotenv>=0.19.0; extra == "ollama"
73
+ Provides-Extra: fal
74
+ Requires-Dist: wrapt>=1.14.0; extra == "fal"
75
+ Requires-Dist: fal-client>=0.13.0; extra == "fal"
76
+ Requires-Dist: python-dotenv>=0.19.0; extra == "fal"
77
+ Provides-Extra: litellm
78
+ Requires-Dist: wrapt>=1.14.0; extra == "litellm"
79
+ Requires-Dist: litellm>=1.40.0; extra == "litellm"
80
+ Requires-Dist: python-dotenv>=0.19.0; extra == "litellm"
81
+ Provides-Extra: litellm-proxy
82
+ Requires-Dist: wrapt>=1.14.0; extra == "litellm-proxy"
83
+ Requires-Dist: litellm[proxy]>=1.93.0; extra == "litellm-proxy"
84
+ Provides-Extra: dev
85
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
86
+ Requires-Dist: pytest-asyncio; extra == "dev"
87
+ Requires-Dist: pytest-cov; extra == "dev"
88
+ Requires-Dist: flake8; extra == "dev"
89
+ Requires-Dist: black; extra == "dev"
90
+ Requires-Dist: mypy; extra == "dev"
91
+ Requires-Dist: freezegun; extra == "dev"
92
+ Requires-Dist: openai-responses>=0.12.0; extra == "dev"
93
+ Requires-Dist: requests; extra == "dev"
94
+ Requires-Dist: wrapt>=1.14.0; extra == "dev"
95
+ Requires-Dist: python-dotenv>=0.19.0; extra == "dev"
96
+ Requires-Dist: anthropic>=0.30.0; extra == "dev"
97
+ Requires-Dist: boto3; extra == "dev"
98
+ Requires-Dist: ollama>=0.3.0; extra == "dev"
99
+ Requires-Dist: griptape<2.0.0,>=1.0.0; python_version >= "3.10" and extra == "dev"
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"
107
+ Requires-Dist: openai>=1.0.0; extra == "dev"
108
+ Requires-Dist: litellm>=1.40.0; extra == "dev"
109
+ Requires-Dist: fal-client>=0.13.0; extra == "dev"
110
+ Requires-Dist: perplexityai>=0.1.0; extra == "dev"
111
+ Requires-Dist: google-genai>=0.1.0; extra == "dev"
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"
115
+ Dynamic: license-file
116
+
117
+ # Revenium Python SDK
118
+
119
+ [![PyPI version](https://img.shields.io/pypi/v/revenium-python-sdk.svg)](https://pypi.org/project/revenium-python-sdk/)
120
+ [![Python Versions](https://img.shields.io/pypi/pyversions/revenium-python-sdk.svg)](https://pypi.org/project/revenium-python-sdk/)
121
+ [![Documentation](https://img.shields.io/badge/docs-revenium.io-blue)](https://docs.revenium.io)
122
+ [![Website](https://img.shields.io/badge/website-revenium.ai-blue)](https://www.revenium.ai)
123
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
124
+
125
+ The official Revenium Python SDK — unified AI metering middleware for deeply attributed AI usage metrics. Supports OpenAI, Anthropic, Google (Gemini/Vertex AI), fal.ai, Ollama, LiteLLM, and Perplexity.
126
+
127
+ ## Features
128
+
129
+ - **Unified SDK**: Single package with middleware for all major AI providers — install only what you need
130
+ - **Zero Code Changes**: Drop-in integration — just import and all API calls are automatically metered
131
+ - **Streaming Support**: Full streaming support for all providers (both sync and async)
132
+ - **Decorator Support**: `@revenium_metadata` for automatic metadata injection and `@revenium_meter` for selective metering
133
+ - **Tool Metering**: `@meter_tool` to meter arbitrary tool/function calls alongside LLM API metering
134
+ - **Prompt Capture**: Optional capture of prompts and responses for analytics and debugging
135
+ - **Distributed Tracing**: Built-in trace visualization fields for cross-service observability
136
+ - **Asynchronous Processing**: Usage records are sent from a fixed pool of background threads, never on your request path
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))
139
+
140
+ ## Supported Providers
141
+
142
+ | Provider | Extra | Install Command |
143
+ |----------|-------|----------------|
144
+ | OpenAI | `openai` | `pip install revenium-python-sdk[openai]` |
145
+ | Azure OpenAI | `openai` | `pip install revenium-python-sdk[openai]` |
146
+ | xAI (Grok, via OpenAI SDK) | `openai` | `pip install revenium-python-sdk[openai]` |
147
+ | Anthropic | `anthropic` | `pip install revenium-python-sdk[anthropic]` |
148
+ | AWS Bedrock (Anthropic) | `anthropic` | `pip install revenium-python-sdk[anthropic]` |
149
+ | Google Gemini | `google-genai` | `pip install revenium-python-sdk[google-genai]` |
150
+ | Google Vertex AI | `google-vertex` | `pip install revenium-python-sdk[google-vertex]` |
151
+ | Ollama | `ollama` | `pip install revenium-python-sdk[ollama]` |
152
+ | LiteLLM (Client) | `litellm` | `pip install revenium-python-sdk[litellm]` |
153
+ | LiteLLM (Proxy) | `litellm-proxy` | `pip install revenium-python-sdk[litellm-proxy]` |
154
+ | Perplexity (via OpenAI) | `perplexity-openai` | `pip install revenium-python-sdk[perplexity-openai]` |
155
+ | Perplexity (Native SDK) | `perplexity-native` | `pip install revenium-python-sdk[perplexity-native]` |
156
+ | fal.ai | `fal` | `pip install revenium-python-sdk[fal]` |
157
+ | LangChain | `langchain` | `pip install revenium-python-sdk[langchain]` |
158
+ | Griptape | `griptape` | `pip install revenium-python-sdk[griptape]` |
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
+
162
+ ## Feature Matrix
163
+
164
+ | Feature | OpenAI | Anthropic | Google | Ollama | LiteLLM | Perplexity | fal.ai |
165
+ |---------|--------|-----------|--------|--------|---------|------------|--------|
166
+ | Chat Completions | Yes\* | Yes | Yes | Yes | Yes | Yes | Yes |
167
+ | Streaming | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
168
+ | Embeddings | Yes | - | Yes | Yes | Yes | - | - |
169
+ | Vision/Multimodal | Yes | Yes | Yes | - | Yes | - | Yes |
170
+ | Audio (speech, transcription, translation) | Yes | - | - | - | Proxy mode | - | Yes |
171
+ | Image Generation | - | - | Yes | - | - | - | Yes |
172
+ | Video Generation | - | - | Yes[^veo] | - | - | - | Yes |
173
+ | Prompt Capture | Yes | Yes | Yes | - | Client mode[^litellm-capture] | - | - |
174
+ | Azure / Bedrock | Azure | Bedrock | Vertex AI | - | All | - | - |
175
+ | LangChain Integration | Yes | - | - | - | - | - | - |
176
+ | Griptape Integration | Yes | Yes | - | Yes | Yes | - | - |
177
+ | CrewAI Integration | Yes | Yes | Yes | - | Yes | - | - |
178
+ | Proxy Mode | - | - | - | - | Yes | - | - |
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
+
211
+ ## Installation
212
+
213
+ ```bash
214
+ # Core SDK only
215
+ pip install revenium-python-sdk
216
+
217
+ # With a specific provider
218
+ pip install revenium-python-sdk[openai]
219
+
220
+ # Multiple providers
221
+ pip install "revenium-python-sdk[openai,anthropic,ollama]"
222
+ ```
223
+
224
+ ## Quick Start
225
+
226
+ ### 1. Configure Environment Variables
227
+
228
+ Create a `.env` file in your project directory:
229
+
230
+ ```env
231
+ # Required
232
+ REVENIUM_METERING_API_KEY=hak_your_revenium_api_key_here
233
+ REVENIUM_METERING_BASE_URL=https://api.revenium.ai
234
+
235
+ # Provider API keys (set whichever you use)
236
+ OPENAI_API_KEY=sk-your_openai_key
237
+ ANTHROPIC_API_KEY=sk-ant-your_anthropic_key
238
+ GOOGLE_API_KEY=your_google_key
239
+ PERPLEXITY_API_KEY=pplx_your_key
240
+ FAL_KEY=your_fal_key
241
+ FIREWORKS_API_KEY=your_fireworks_key
242
+
243
+ # Optional
244
+ # REVENIUM_LOG_LEVEL=DEBUG
245
+ ```
246
+
247
+ ### 2. Import and Use
248
+
249
+ Just import the middleware for your provider. That's it - all API calls are automatically metered:
250
+
251
+ ```python
252
+ from dotenv import load_dotenv
253
+ load_dotenv()
254
+
255
+ import openai
256
+ import revenium_middleware.openai # Auto-initializes on import
257
+
258
+ client = openai.OpenAI()
259
+ response = client.chat.completions.create(
260
+ model="gpt-4o-mini",
261
+ messages=[{"role": "user", "content": "Hello!"}]
262
+ )
263
+ print(response.choices[0].message.content)
264
+ # Usage data automatically sent to Revenium
265
+ ```
266
+
267
+ ---
268
+
269
+ ## Metering Error Visibility
270
+
271
+ Metering runs in background threads and never raises into your code path — a
272
+ metering failure will never break your AI calls. To make failures observable
273
+ anyway, the SDK provides two mechanisms:
274
+
275
+ **Subscribe to failures** with a callback:
276
+
277
+ ```python
278
+ import revenium_middleware
279
+
280
+ @revenium_middleware.on_metering_error
281
+ def alert_on_metering_failure(event):
282
+ # event.error -- the exception (e.g. an HTTP 401/500 from Revenium)
283
+ # event.operation -- "completion", "image", "tool", ... (may be None)
284
+ # event.timestamp -- UTC datetime of the failure
285
+ my_monitoring.notify(f"Revenium metering failed: {event.error}")
286
+ ```
287
+
288
+ Callbacks run on the background metering thread; exceptions they raise are
289
+ suppressed and logged, so they can never disrupt your application.
290
+
291
+ Authentication headers (`x-api-key`, `authorization`) on any HTTP
292
+ request/response attached to the exception are redacted before the error is
293
+ exposed to callbacks or `last_error`.
294
+
295
+ **Poll the status counters:**
296
+
297
+ ```python
298
+ status = revenium_middleware.get_metering_status()
299
+ print(status.success_count) # events delivered successfully
300
+ print(status.error_count) # delivery failures
301
+ print(status.last_error) # most recent exception, or None
302
+ print(status.last_error_at) # UTC datetime of the most recent failure
303
+ print(status.evicted_count) # undelivered events dropped because the buffer was full
304
+ ```
305
+
306
+ `reset_metering_status()` zeroes the counters and clears registered
307
+ callbacks; `remove_metering_error_callback(cb)` unsubscribes a single one.
308
+
309
+ Failures are also logged at **ERROR** level on the `revenium_middleware`
310
+ logger, including HTTP 4xx/5xx responses, a missing
311
+ `REVENIUM_METERING_API_KEY`, and a provider middleware that fails to import
312
+ when the provider's SDK is installed.
313
+
314
+ ---
315
+
316
+ ## Agentic Outcomes (Outcome-Based Metering)
317
+
318
+ Emit per-agent terminal outcomes (`CONVERTED`, `DEFLECTED`, `ESCALATED`) alongside completion and tool-event records, so dashboards show business value next to AI cost.
319
+
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`.
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
+
324
+ ### Job-Type Economics and Outcome Facts
325
+
326
+ Keep a metering key for AI telemetry and a separate write key for outcomes and
327
+ job-type configuration. A registered `valuePerUnit` rule takes precedence over
328
+ an outcome's `outcome_value`; the backend never sums the two value sources.
329
+
330
+ ```python
331
+ from revenium_middleware import (
332
+ Baseline, JobTypeEconomics, PeriodFactEntry, create_baseline,
333
+ report_period_facts, upsert_job_type_economics,
334
+ )
335
+
336
+ upsert_job_type_economics("claim", JobTypeEconomics(
337
+ unit_metric_key="completed_claims", unit_label="claim",
338
+ metrics=[
339
+ {
340
+ "key": "completed_claims", "type": "COUNT",
341
+ "direction": "HIGHER_IS_BETTER", "aggregation": "SUM",
342
+ "resolution": "PER_JOB",
343
+ },
344
+ {
345
+ "key": "claims_processed", "type": "COUNT",
346
+ "direction": "HIGHER_IS_BETTER", "aggregation": "SUM",
347
+ "resolution": "PERIOD",
348
+ },
349
+ ],
350
+ dimensions=[{"key": "region", "allowedValues": ["us", "ca"]}],
351
+ monetization={
352
+ "metricKey": "completed_claims", "valuePerUnit": 4.25,
353
+ "currency": "USD", "category": "COST_AVOIDED", "basis": "REALIZED",
354
+ },
355
+ ))
356
+ create_baseline("claim", Baseline(
357
+ effective_from="2026-08-01T00:00:00Z", cost_per_unit=4.25, currency="USD",
358
+ ))
359
+ report_period_facts("claim", [PeriodFactEntry(
360
+ period_start="2026-08-01T00:00:00Z", period_end="2026-09-01T00:00:00Z",
361
+ dimension_key="region", dimension_value="us",
362
+ key="claims_processed", value=1280,
363
+ )])
364
+ ```
365
+
366
+ `effective_from` is the only required field on a baseline; every other field
367
+ is optional, and a baseline without it is rejected. A job type must be
368
+ declared with `upsert_job_type_economics` before it accepts baselines or
369
+ facts, and `report_period_facts` accepts only metrics declared with
370
+ `"resolution": "PERIOD"`.
371
+
372
+ Job economics currency values must be USD. Baselines and period facts use
373
+ server-supplied attribution when their provenance,
374
+ reporter, and source fields are omitted. Set those fields only when you need an
375
+ explicit override. Economics metric directions are
376
+ `HIGHER_IS_BETTER` or `LOWER_IS_BETTER`; monetization categories are
377
+ `REVENUE`, `COST_AVOIDED`, `TIME_SAVED`, and `LEADING_VALUE`, with a
378
+ `REALIZED` or `EXPECTED` basis.
379
+
380
+ Use `CUSTOMER_DECLARED` or `MEASURED` for a baseline override. Use `MEASURED`,
381
+ `SELF_REPORTED`, or `DERIVED` for a period fact override.
382
+
383
+ Facts are append-only and keyed on the period, dimension and metric key
384
+ together. Re-appending that tuple supersedes the active fact, and the server
385
+ requires `reason=` on the entry when it does.
386
+
387
+ ### JobContext
388
+
389
+ `JobContext` is the recommended high-level API: every AI call made inside the block is automatically metered against the job (all provider middlewares pick the job fields up from context), and the job's business outcome is reported when the work is done.
390
+
391
+ ```python
392
+ from revenium_middleware import JobContext
393
+
394
+ with JobContext("loan-app-12345", type="loan_processing", version="2.1") as job:
395
+ response = client.chat.completions.create(...) # metered against the job automatically
396
+ job.report_outcome(
397
+ execution_status="SUCCESS", # SUCCESS | FAILED | CANCELLED
398
+ outcome_type="CONVERTED",
399
+ outcome_value=500.0,
400
+ outcome_currency="USD",
401
+ )
402
+ ```
403
+
404
+ - **Async:** `async with JobContext(...) as job:` works identically.
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.
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.
410
+ - **Nesting:** a nested `JobContext` is a different job (replace, not merge); exiting the inner context restores the outer job's fields.
411
+
412
+ To tag AI calls with job fields without a context manager, use per-call `usage_metadata={"agentic_job_id": ...}`, the `@track_job` decorator (LiteLLM), or the process-wide `REVENIUM_AGENTIC_JOB_*` environment variables — see [Optional Environment Variables](#optional-environment-variables).
413
+
414
+ ### Amending an Outcome
415
+
416
+ Outcomes are amendable: when the business result changes after the fact, amend the recorded outcome instead of re-reporting it. `JobContext.attach()` returns a lightweight handle to an existing job — it is not entered as a context manager and does not touch AI-call scoping — so amendments work from a different process than the one that ran the job.
417
+
418
+ ```python
419
+ from revenium_middleware import JobContext, get_outcome_history
420
+
421
+ # Two weeks after the agent converted the lead at $500,
422
+ # the customer expands to the annual plan.
423
+ job = JobContext.attach("sales-lead-8842")
424
+ job.amend_outcome(
425
+ reason="Customer expanded to the annual plan after the initial conversion",
426
+ outcome_value=750.0,
427
+ )
428
+ job.close()
429
+
430
+ history = get_outcome_history("sales-lead-8842")
431
+ # List[JobOutcomeAmendment], ordered by amendment_sequence (1 = the initial report)
432
+ ```
433
+
434
+ `amend_outcome()` takes `reason` — the amendment's audit justification, still the first positional argument — plus the same optional fields as `report_outcome()` (`execution_status`, `outcome_type`, `outcome_value`, `outcome_currency`, `metadata`, `reported_by`, `outcome_reason`, `metrics`), and returns the updated job as a dict.
435
+
436
+ - **Detecting a lost update:** `report_outcome()` and `amend_outcome()` record the job's `entityVersion` from the response on the handle (readable as `job.entity_version`). The next `amend_outcome()` on that same handle sends it as `expectedEntityVersion`, so an amendment that would overwrite a change made by another writer in the meantime raises `OutcomeAmendConflictError` instead of silently winning. Pass `expected_entity_version=` to lock against a version you fetched yourself; use a fresh `JobContext.attach()` handle — which has recorded nothing — for the old last-write-wins behavior.
437
+
438
+ ```python
439
+ from revenium_middleware import OutcomeAmendConflictError, get_outcome_history
440
+
441
+ try:
442
+ job.amend_outcome(reason="Chargeback", outcome_value=0.0)
443
+ except OutcomeAmendConflictError as conflict:
444
+ # The conflict reports the version the platform actually holds.
445
+ print(conflict.current_entity_version) # e.g. 9
446
+
447
+ # Look at what the other writer changed, and only re-issue the amendment
448
+ # if it still applies to what is recorded now.
449
+ history = get_outcome_history("sales-lead-8842")
450
+ if still_applies(history[-1]):
451
+ job.amend_outcome(reason="Chargeback, re-checked", outcome_value=0.0,
452
+ expected_entity_version=conflict.current_entity_version)
453
+ ```
454
+
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.
456
+
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.
458
+
459
+ - **Omitting `reason`:** an API-key caller may leave `reason` out and the platform records an automated correction reason derived from the source. A session caller must supply one; a blank string is rejected client-side either way.
460
+ - **`reason` vs `outcome_reason`:** `reason` is the amendment's own audit justification (why the record changed); `outcome_reason` is the business explanation of why the job failed or was cancelled. Use `outcome_reason` for failure explanations rather than burying them in `metadata` — it is a first-class field on the outcome and is returned on every `get_outcome_history()` row.
461
+ - **Clearing `outcome_reason`:** omit the argument to leave the stored value untouched; pass an empty string (`outcome_reason=""`) to clear it.
462
+ - **`metrics`:** both `report_outcome()` and `amend_outcome()` accept a `metrics` argument for recording the measurable facts behind an outcome.
463
+
464
+ ### Recording Metric Facts
465
+
466
+ Beyond the single `outcome_value`, a job can carry the measurable facts its job type declares — `quality_rate` and its siblings — either with the outcome or later, once they are measurable.
467
+
468
+ ```python
469
+ from revenium_middleware import JobContext
470
+
471
+ with JobContext("claim-8842", type="claims_triage") as job:
472
+ ...
473
+ job.report_outcome(
474
+ execution_status="SUCCESS",
475
+ outcome_type="CONVERTED",
476
+ metrics=[
477
+ {"key": "quality_rate", "value": 0.93, "provenance": "MEASURED"},
478
+ {"key": "cases_closed", "value": 12},
479
+ ],
480
+ )
481
+
482
+ # Two days later a human grades a sample of that same job's output.
483
+ handle = JobContext.attach("claim-8842")
484
+ handle.append_outcome_metrics([
485
+ {"key": "quality_rate", "value": 0.87, "provenance": "ATTESTED",
486
+ "reason": "graded sample of 200 cases"},
487
+ ])
488
+ handle.close()
489
+ ```
490
+
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.
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.
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.
494
+ - **Not part of outcome history:** `get_outcome_history()` returns the outcome revisions only — appended facts do not appear in those rows.
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).
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.)
497
+ - **Why it matters:** AI Alerts evaluate `QUALITY_RATE` from these facts, so a job whose integration emits none is invisible to those rules.
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
+
527
+ ### Outcome Exceptions
528
+
529
+ All outcome exceptions are importable from `revenium_middleware` and share the `OutcomeReportingError` base, so `except OutcomeReportingError:` catches the whole family:
530
+
531
+ | Exception | Raised when | What to do |
532
+ |-----------|-------------|------------|
533
+ | `OutcomeReportingError` | Base class — configuration failures (no API key available, unresolvable `team_id`) | Fix the key / team configuration |
534
+ | `OutcomeAlreadyReportedError` | Re-reporting a job that already has an outcome (backend 409) | Amend with `amend_outcome()` instead; the exception carries `reported_at` and `amendment_count` |
535
+ | `OutcomeNotReportedError` | Amending a job that has no outcome yet (backend 422) | Call `report_outcome()` first |
536
+ | `OutcomeAmendConflictError` | A concurrent amendment changed the outcome (backend 409, optimistic lock) | Re-check the outcome against `get_outcome_history()`, then retry with `expected_entity_version=conflict.current_entity_version` — the SDK does not auto-retry |
537
+
538
+ ### Low-Level Client
539
+
540
+ For manual control over every metric (one `emit_completion` per LLM call, one `emit_tool_event` per tool/step), use `AgenticOutcomeClient` directly:
541
+
542
+ ```python
543
+ from revenium_middleware.agentic_outcomes import AgenticOutcomeClient, AgenticOutcomeSettings
544
+
545
+ settings = AgenticOutcomeSettings(api_key="rev_sk_...")
546
+ client = AgenticOutcomeClient(settings)
547
+
548
+ client.emit_completion(...) # one per LLM call
549
+ client.emit_tool_event(...) # one per tool / step
550
+ client.report_outcome(job_id, {...}) # close the job with a terminal outcome
551
+ client.append_outcome_metrics(job_id, [...]) # append declared per-job facts later
552
+ client.close()
553
+ ```
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
+
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`.
566
+
567
+ See [`examples/agentic_outcomes/`](examples/agentic_outcomes/) for runnable demos (sales / coding / support) with configurable failure rates and outcome distributions.
568
+
569
+ **API reference:** [docs.revenium.io](https://docs.revenium.io) · per-endpoint reference at [revenium.readme.io/reference/meter_ai_completion](https://revenium.readme.io/reference/meter_ai_completion).
570
+
571
+ ---
572
+
573
+ ## Idempotency
574
+
575
+ Every metering POST from the provider middleware automatically includes an `Idempotency-Key` header. If the Revenium API receives the same key with the same body within 24 hours, it returns the cached response instead of double-billing — making metering submissions safe to retry.
576
+
577
+ ### Default
578
+
579
+ A fresh UUID v4 is generated automatically for every metering call. No action required.
580
+
581
+ ### Override
582
+
583
+ Use the `idempotency_key` context manager to tie metering to a business-level identifier so the same logical operation never double-meters across retries:
584
+
585
+ ```python
586
+ from revenium_middleware import idempotency_key
587
+
588
+ with idempotency_key(f"order-{order_id}"):
589
+ response = openai.chat.completions.create(...)
590
+ ```
591
+
592
+ The context manager is backed by `contextvars`, so it scopes correctly across threads and asyncio tasks.
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
+
604
+ ### Backend behavior
605
+
606
+ | Scenario | Backend response |
607
+ | -- | -- |
608
+ | First call with key K and body B | Executes, caches for 24h |
609
+ | Retry with same K and same B | Returns cached response (no double-bill) |
610
+ | Same K with different B | `409 idempotency_key_mismatch` |
611
+ | Concurrent in-flight with same K | `409 idempotency_key_in_progress` + `Retry-After: 1` |
612
+ | Malformed key | `400 invalid_idempotency_key` |
613
+
614
+ See [docs.revenium.io/integrations/idempotency](https://docs.revenium.io/integrations/idempotency) for full backend semantics.
615
+
616
+ ### Key format
617
+
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.
619
+
620
+ ---
621
+
622
+ ## Webhook Signature Verification
623
+
624
+ Revenium signs every outbound webhook with HMAC-SHA256 when a signing secret is configured. The SDK ships a verification helper so your handler can validate signatures without writing crypto.
625
+
626
+ Two headers arrive on every signed delivery:
627
+
628
+ | Header | Value |
629
+ | -- | -- |
630
+ | `X-Revenium-Signature-256` | `sha256=<hex>`. During a 24h rotation overlap: `sha256=A, sha256=B`. |
631
+ | `X-Revenium-Webhook-Timestamp` | Unix seconds at signing time. |
632
+
633
+ ### FastAPI example
634
+
635
+ ```python
636
+ import os
637
+
638
+ from fastapi import FastAPI, Header, HTTPException, Request
639
+
640
+ from revenium_middleware.webhooks import verify_signature
641
+
642
+ app = FastAPI()
643
+ SIGNING_SECRETS = [os.environ["REVENIUM_WEBHOOK_SECRET"]]
644
+
645
+
646
+ @app.post("/webhooks/revenium")
647
+ async def receive(
648
+ request: Request,
649
+ x_revenium_signature_256: str = Header(...),
650
+ x_revenium_webhook_timestamp: str = Header(...),
651
+ ):
652
+ body = await request.body()
653
+ if not verify_signature(
654
+ payload=body,
655
+ signature_header=x_revenium_signature_256,
656
+ timestamp_header=x_revenium_webhook_timestamp,
657
+ secrets=SIGNING_SECRETS,
658
+ ):
659
+ raise HTTPException(status_code=401, detail="Invalid signature")
660
+
661
+ # ... process the event
662
+ return {"ok": True}
663
+ ```
664
+
665
+ ### Secret rotation
666
+
667
+ When you rotate a signing secret in the Revenium dashboard with the default 24-hour overlap, both the old and new secrets are active simultaneously and every webhook is signed with both. Supply both values in `SIGNING_SECRETS` during the overlap window; remove the old one once it expires.
668
+
669
+ ### Webhooks without a signing secret
670
+
671
+ Webhook deliveries without a configured signing secret arrive without HMAC headers. If your endpoint receives both signed and unsigned traffic, branch on header presence: treat missing headers as legacy unsigned mode and missing-signature-on-signed-only endpoints as an authentication failure.
672
+
673
+ ---
674
+
675
+ ## Provider Usage Guides
676
+
677
+ ### OpenAI
678
+
679
+ Supports chat completions, streaming, embeddings, function calling, vision/multimodal, and audio (speech, transcription and translation).
680
+
681
+ ```python
682
+ from dotenv import load_dotenv
683
+ load_dotenv()
684
+
685
+ import openai
686
+ import revenium_middleware.openai # Auto-initializes
687
+
688
+ client = openai.OpenAI()
689
+
690
+ # Basic chat completion
691
+ response = client.chat.completions.create(
692
+ model="gpt-4o-mini",
693
+ messages=[{"role": "user", "content": "Hello!"}],
694
+ usage_metadata={
695
+ "organizationName": "AcmeCorp",
696
+ "productName": "customer-chatbot",
697
+ "trace_id": "session-123",
698
+ "task_type": "chat"
699
+ }
700
+ )
701
+
702
+ # Streaming
703
+ stream = client.chat.completions.create(
704
+ model="gpt-4o-mini",
705
+ messages=[{"role": "user", "content": "Tell me a story"}],
706
+ stream=True
707
+ )
708
+ for chunk in stream:
709
+ if chunk.choices[0].delta.content:
710
+ print(chunk.choices[0].delta.content, end="", flush=True)
711
+
712
+ # Embeddings
713
+ embedding = client.embeddings.create(
714
+ model="text-embedding-3-small",
715
+ input="The quick brown fox"
716
+ )
717
+ ```
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
+
738
+ #### Azure OpenAI
739
+
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.
741
+
742
+ ```python
743
+ from openai import AzureOpenAI
744
+ import revenium_middleware.openai
745
+
746
+ client = AzureOpenAI(
747
+ azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
748
+ api_key=os.getenv("AZURE_OPENAI_API_KEY"),
749
+ api_version="2024-02-01"
750
+ )
751
+
752
+ response = client.chat.completions.create(
753
+ model="my-gpt4-deployment", # Azure deployment name
754
+ messages=[{"role": "user", "content": "Hello!"}]
755
+ )
756
+ # Model name automatically resolved for pricing
757
+ ```
758
+
759
+ **Azure environment variables:**
760
+ - `AZURE_OPENAI_ENDPOINT` - Your Azure OpenAI endpoint
761
+ - `AZURE_OPENAI_API_KEY` - Your Azure OpenAI API key
762
+ - `AZURE_OPENAI_DEPLOYMENT` - Default deployment name
763
+
764
+ **Examples:** `examples/openai/` - `openai_basic.py`, `openai_streaming.py`, `azure_basic.py`, `azure_streaming.py`
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
+
790
+ ---
791
+
792
+ ### Anthropic
793
+
794
+ Supports messages, streaming, vision/multimodal, and AWS Bedrock integration.
795
+
796
+ ```python
797
+ from dotenv import load_dotenv
798
+ load_dotenv()
799
+
800
+ import anthropic
801
+ import revenium_middleware.anthropic # Auto-initializes
802
+
803
+ client = anthropic.Anthropic()
804
+
805
+ # Basic message
806
+ message = client.messages.create(
807
+ model="claude-opus-4-7",
808
+ max_tokens=100,
809
+ messages=[{"role": "user", "content": "Hello!"}],
810
+ usage_metadata={
811
+ "organizationName": "AcmeCorp",
812
+ "productName": "support-bot",
813
+ "trace_id": "session-456"
814
+ }
815
+ )
816
+
817
+ # Streaming
818
+ with client.messages.stream(
819
+ model="claude-opus-4-7",
820
+ max_tokens=200,
821
+ messages=[{"role": "user", "content": "Tell me a story"}],
822
+ usage_metadata={"task_type": "creative"}
823
+ ) as stream:
824
+ for text in stream.text_stream:
825
+ print(text, end="", flush=True)
826
+ ```
827
+
828
+ Async streaming is metered the same way, with the same metadata:
829
+
830
+ ```python
831
+ import asyncio
832
+ import anthropic
833
+ import revenium_middleware.anthropic
834
+
835
+ client = anthropic.AsyncAnthropic()
836
+
837
+ async def main():
838
+ async with client.messages.stream(
839
+ model="claude-opus-4-7",
840
+ max_tokens=200,
841
+ messages=[{"role": "user", "content": "Tell me a story"}],
842
+ usage_metadata={"task_type": "creative"}
843
+ ) as stream:
844
+ async for text in stream.text_stream:
845
+ print(text, end="", flush=True)
846
+ # await stream.get_final_message() works too; either way the
847
+ # completion is metered once when the block exits.
848
+
849
+ asyncio.run(main())
850
+ ```
851
+
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.
855
+
856
+ #### AWS Bedrock
857
+
858
+ The middleware meters Claude on AWS Bedrock through `AnthropicBedrock`, with automatic detection.
859
+
860
+ ```python
861
+ import anthropic
862
+ import revenium_middleware.anthropic
863
+
864
+ # Bedrock is automatically detected when AWS credentials are available
865
+ # and base_url contains 'amazonaws.com'
866
+ client = anthropic.AnthropicBedrock(
867
+ aws_region="us-east-1"
868
+ )
869
+
870
+ message = client.messages.create(
871
+ model="claude-opus-4-7",
872
+ max_tokens=100,
873
+ messages=[{"role": "user", "content": "Hello from Bedrock!"}]
874
+ )
875
+ ```
876
+
877
+ **Provider detection** automatically routes between Bedrock and direct Anthropic API based on:
878
+ - AWS credentials availability (`aws configure`, IAM roles, environment variables)
879
+ - Base URL detection (when `base_url` contains `amazonaws.com`)
880
+ - Defaults to direct Anthropic API - Bedrock only used when explicitly configured
881
+
882
+ **Bedrock environment variables:**
883
+
884
+ | Variable | Description | Default |
885
+ |----------|-------------|---------|
886
+ | `AWS_REGION` | AWS region for Bedrock | `us-east-1` |
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`.
891
+
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.
893
+
894
+ **Supported Bedrock models:**
895
+
896
+ | Anthropic Model | Bedrock Model ID |
897
+ |----------------|------------------|
898
+ | `claude-opus-4-7` | `anthropic.claude-opus-4-7` |
899
+ | `us.claude-opus-4-7` | `us.anthropic.claude-opus-4-7` |
900
+ | `eu.claude-opus-4-7` | `eu.anthropic.claude-opus-4-7` |
901
+ | `au.claude-opus-4-7` | `au.anthropic.claude-opus-4-7` |
902
+ | `global.claude-opus-4-7` | `global.anthropic.claude-opus-4-7` |
903
+ | `claude-3-opus-20240229` | `anthropic.claude-3-opus-20240229-v1:0` |
904
+ | `claude-3-sonnet-20240229` | `anthropic.claude-3-sonnet-20240229-v1:0` |
905
+ | `claude-3-haiku-20240307` | `us.anthropic.claude-3-5-haiku-20241022-v1:0` |
906
+ | `claude-3-5-sonnet-20240620` | `anthropic.claude-3-5-sonnet-20240620-v1:0` |
907
+ | `claude-3-5-sonnet-20241022` | `anthropic.claude-3-5-sonnet-20241022-v2:0` |
908
+ | `claude-3-5-haiku-20241022` | `anthropic.claude-3-5-haiku-20241022-v1:0` |
909
+
910
+ For other models, the middleware uses the format `anthropic.{model_name}`.
911
+
912
+ #### Microsoft Foundry
913
+
914
+ Claude served through Microsoft Foundry is metered by the same patched endpoints as the
915
+ direct Anthropic API - the Anthropic SDK's Foundry clients need no extra setup.
916
+
917
+ ```python
918
+ import anthropic
919
+ import revenium_middleware.anthropic
920
+
921
+ # Foundry is detected from the client class, so a custom base_url is fine too
922
+ client = anthropic.AnthropicFoundry(
923
+ resource="your-resource", # or ANTHROPIC_FOUNDRY_RESOURCE
924
+ )
925
+
926
+ message = client.messages.create(
927
+ model="claude-opus-4-7",
928
+ max_tokens=100,
929
+ messages=[{"role": "user", "content": "Hello from Foundry!"}]
930
+ )
931
+ ```
932
+
933
+ Foundry usage is reported with provider `Foundry` and model source `ANTHROPIC`, so the spend
934
+ is separated from direct-Anthropic totals while still priced against the Anthropic rate card
935
+ that Foundry bills at. `AsyncAnthropicFoundry` is metered the same way, as is
936
+ `client.messages.stream()`.
937
+
938
+ **Examples:** `examples/anthropic/` - `anthropic-basic.py`, `anthropic-streaming.py`, `anthropic-bedrock.py`, `anthropic-advanced.py`
939
+
940
+ ---
941
+
942
+ ### Google AI (Gemini / Vertex AI)
943
+
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.
945
+
946
+ ```bash
947
+ # Google AI SDK (Gemini Developer API, or Vertex AI with vertexai=True)
948
+ pip install "revenium-python-sdk[google-genai]"
949
+
950
+ # Vertex AI SDK (vertexai package)
951
+ pip install "revenium-python-sdk[google-vertex]"
952
+ ```
953
+
954
+ #### Google AI SDK
955
+
956
+ ```python
957
+ from dotenv import load_dotenv
958
+ load_dotenv()
959
+
960
+ import revenium_middleware.google
961
+ from google import genai
962
+
963
+ client = genai.Client()
964
+ response = client.models.generate_content(
965
+ model="gemini-2.0-flash-001",
966
+ contents="Hello! Introduce yourself in one sentence.",
967
+ usage_metadata={
968
+ "organizationName": "AcmeCorp",
969
+ "task_type": "chat"
970
+ }
971
+ )
972
+ print(response.text)
973
+ ```
974
+
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.
990
+
991
+ ```python
992
+ from dotenv import load_dotenv
993
+ load_dotenv()
994
+
995
+ import revenium_middleware.google
996
+ import vertexai
997
+ from vertexai.generative_models import GenerativeModel
998
+
999
+ vertexai.init(project="your-gcp-project", location="us-central1")
1000
+ model = GenerativeModel("gemini-2.0-flash-001")
1001
+ response = model.generate_content("Hello!")
1002
+ print(response.text)
1003
+ ```
1004
+
1005
+ **Which SDK should I choose?**
1006
+
1007
+ | Use Case | Recommended SDK | Why |
1008
+ |----------|----------------|-----|
1009
+ | Quick prototyping | Google AI SDK | Simple API key setup |
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` |
1013
+
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.
1019
+
1020
+ **Google AI environment variables:**
1021
+ - `GOOGLE_API_KEY` - For Google AI SDK
1022
+ - `GOOGLE_CLOUD_PROJECT` - For Vertex AI SDK
1023
+ - `GOOGLE_CLOUD_LOCATION` - Vertex AI region (default: `us-central1`)
1024
+
1025
+ **For Vertex AI**, authenticate with: `gcloud auth application-default login`
1026
+
1027
+ **Examples:** `examples/google/` - `getting_started_google_ai.py`, `getting_started_vertex_ai.py`, `simple_streaming_test.py`, `simple_embeddings_test.py`
1028
+
1029
+ ---
1030
+
1031
+ ### Ollama
1032
+
1033
+ Supports chat completions, text generation, embeddings, and streaming. Works with any Ollama model.
1034
+
1035
+ ```python
1036
+ from dotenv import load_dotenv
1037
+ load_dotenv()
1038
+
1039
+ import ollama
1040
+ import revenium_middleware.ollama # Auto-initializes
1041
+
1042
+ # Chat completion
1043
+ response = ollama.chat(
1044
+ model='qwen2.5:0.5b',
1045
+ messages=[{'role': 'user', 'content': 'Why is the sky blue?'}],
1046
+ usage_metadata={
1047
+ "organizationName": "AcmeCorp",
1048
+ "task_type": "chat"
1049
+ }
1050
+ )
1051
+ print(response['message']['content'])
1052
+
1053
+ # Streaming
1054
+ for chunk in ollama.chat(
1055
+ model='qwen2.5:0.5b',
1056
+ messages=[{'role': 'user', 'content': 'Tell me a story'}],
1057
+ stream=True
1058
+ ):
1059
+ print(chunk['message']['content'], end='', flush=True)
1060
+
1061
+ # Text generation
1062
+ response = ollama.generate(model='qwen2.5:0.5b', prompt='Once upon a time')
1063
+
1064
+ # Embeddings (single and batch)
1065
+ response = ollama.embed(model='nomic-embed-text', input='Hello world')
1066
+ response = ollama.embed(model='nomic-embed-text', input=['Text 1', 'Text 2', 'Text 3'])
1067
+ ```
1068
+
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.
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
+
1073
+ **OpenAI compatibility mode:** You can also use Ollama with the OpenAI SDK:
1074
+
1075
+ ```python
1076
+ import openai
1077
+ import revenium_middleware.openai
1078
+
1079
+ openai.api_key = 'ollama'
1080
+ openai.base_url = 'http://localhost:11434/v1/'
1081
+
1082
+ response = openai.chat.completions.create(
1083
+ model="gemma2:2b",
1084
+ messages=[{"role": "user", "content": "Hello!"}],
1085
+ usage_metadata={"organizationName": "AcmeCorp"}
1086
+ )
1087
+ ```
1088
+
1089
+ **Prerequisites:** Ensure Ollama is running (`ollama serve`) before making API calls.
1090
+
1091
+ **Examples:** `examples/ollama/` - `getting_started.py`, `example_streaming.py`, `example_metadata.py`, `embeddings_example.py`
1092
+
1093
+ ---
1094
+
1095
+ ### LiteLLM
1096
+
1097
+ Supports all LLM providers available through LiteLLM with two integration patterns: client-side middleware and server-side proxy callbacks.
1098
+
1099
+ #### Client Mode
1100
+
1101
+ ```python
1102
+ from dotenv import load_dotenv
1103
+ load_dotenv()
1104
+
1105
+ import revenium_middleware.litellm.client.middleware # Auto-initializes
1106
+ import litellm
1107
+ import os
1108
+
1109
+ litellm.api_base = os.getenv("LITELLM_PROXY_URL")
1110
+ litellm.api_key = os.getenv("LITELLM_API_KEY")
1111
+
1112
+ response = litellm.completion(
1113
+ model="gpt-4o-mini",
1114
+ messages=[{"role": "user", "content": "Hello!"}],
1115
+ usage_metadata={
1116
+ "organizationName": "AcmeCorp",
1117
+ "task_type": "chat"
1118
+ }
1119
+ )
1120
+ ```
1121
+
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.
1123
+
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.
1125
+
1126
+ #### Proxy Mode
1127
+
1128
+ `ReveniumGuardrail` is the LiteLLM proxy integration. It is a LiteLLM
1129
+ `CustomGuardrail` that **enforces the caller's budget before** the proxied call and
1130
+ **meters usage after** it: successes, failures and streamed responses alike,
1131
+ except calls a spending cap refuses.
1132
+
1133
+ ```bash
1134
+ pip install "revenium-python-sdk[litellm-proxy]" # requires Python 3.10+
1135
+ ```
1136
+
1137
+ ```yaml
1138
+ guardrails:
1139
+ - guardrail_name: "revenium"
1140
+ litellm_params:
1141
+ guardrail: revenium_middleware.litellm.proxy.guardrail.ReveniumGuardrail
1142
+ mode:
1143
+ - "pre_call" # budget enforcement
1144
+ - "post_call" # usage metering
1145
+ default_on: true
1146
+ ```
1147
+
1148
+ `guardrails` is a **top-level** key, not a member of `litellm_settings`. Nested
1149
+ under `litellm_settings` it reaches LiteLLM's legacy v1 guardrail loader, which
1150
+ expects a different shape and exits the proxy at startup with
1151
+ `GuardrailItem() argument after ** must be a mapping, not str`.
1152
+
1153
+ `mode` must be a **list** to enable both hooks; a single string restricts the
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`.
1160
+
1161
+ **Budget enforcement** reuses the SDK's own circuit breaker, so a proxy enforces
1162
+ exactly what every other Revenium integration enforces — including department
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:
1169
+
1170
+ ```json
1171
+ {"error": {"message": "Request blocked by Revenium enforcement rule: Team Budget",
1172
+ "type": "budget_exceeded", "guardrail": "revenium", "model": "gpt-4o",
1173
+ "budgets": [{"name": "Team Budget", "ruleId": 7, "threshold": 10.0,
1174
+ "currentValue": 11.5, "resetsAt": "2026-10-01T00:00:00Z"}]}}
1175
+ ```
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
+
1179
+ Enforcement **fails open**: if the enforcement path is unreachable or misbehaves,
1180
+ the call proceeds, and it proceeds without waiting. The pre-call check reads the
1181
+ rules the SDK already has cached and refreshes them on a background thread, so a
1182
+ Revenium endpoint that hangs, refuses connections, returns errors or rejects your
1183
+ key (403) neither blocks nor slows the proxy. A failed refresh is retried once
1184
+ per `REVENIUM_CB_POLL_INTERVAL_SECONDS`, not once per request. Right after the
1185
+ proxy starts, before the first rules fetch completes, no rules are cached and
1186
+ calls go through; see [Fail-Open vs Fail-Closed](#fail-open-vs-fail-closed).
1187
+ Metering is likewise non-disruptive — nothing in the post-call path can turn a
1188
+ successful LLM call into an error for the client.
1189
+
1190
+ **Attribution** travels as `x-revenium-*` request headers (subscriber, organization,
1191
+ product, trace, task type, agent, subscription, quality score, and `x-revenium-effort`
1192
+ for reasoning effort), with the calling virtual key's metadata as the fallback —
1193
+ `revenium_user_id`, `revenium_organization_name`, `revenium_key_name`, and
1194
+ `revenium_agentic_job_*`. Agentic job tags (`x-revenium-agentic-job-id`, `-name`,
1195
+ `-type`, `-version`) ride along for cost/ROI correlation; the job id is required for
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
+ **Organization caps and the organization header.** By default the
1201
+ `x-revenium-organization-name` header (and the retired `x-revenium-organization-id`)
1202
+ wins over the calling virtual key's team alias, for the budget check and the record
1203
+ alike. That means anyone holding a team's key can send another organization's name
1204
+ and move their spend off their own organization's cap: the call is checked against,
1205
+ and recorded under, the name they sent. To make the key's team decide instead, set
1206
+
1207
+ ```bash
1208
+ export REVENIUM_LITELLM_PIN_ORGANIZATION_TO_KEY_TEAM=true
1209
+ ```
1210
+
1211
+ With it on, a call made with a key that belongs to a LiteLLM team is checked and
1212
+ recorded under that team's alias whatever organization header it sends, so the team
1213
+ alias is the organization: renaming the team in LiteLLM renames where its spend is
1214
+ booked. A key with no team alias (none set, or blank) still takes the organization
1215
+ from the header; on the guardrail, a key with neither falls back to its
1216
+ `revenium_organization_name` metadata. `1`, `yes` and `on` also turn the setting on.
1217
+ Unset, `false`, `0`, `no` and `off` leave it off; any other value leaves it off too,
1218
+ and the proxy logs a warning at startup naming the setting. The deprecated callback
1219
+ honours the same setting for its record.
1220
+
1221
+ **Trace fields** come from the gateway host's own settings, and a matching header wins
1222
+ per call: `REVENIUM_ENVIRONMENT` (or `ENVIRONMENT`, or `DEPLOYMENT_ENV`) and
1223
+ `x-revenium-environment`; `REVENIUM_REGION` (or `AWS_REGION`, `AWS_DEFAULT_REGION`,
1224
+ `AZURE_REGION`, `GCP_REGION`, `GOOGLE_CLOUD_REGION`) and `x-revenium-region`;
1225
+ `REVENIUM_CREDENTIAL_ALIAS` and `x-revenium-credential-alias`;
1226
+ `REVENIUM_TICKET_ID` and `x-revenium-ticket-id`; `REVENIUM_TRANSACTION_NAME`, `REVENIUM_TRACE_TYPE`, `REVENIUM_TRACE_NAME`,
1227
+ `REVENIUM_PARENT_TRANSACTION_ID`, `REVENIUM_RETRY_NUMBER` and `REVENIUM_SKILL_*`, with
1228
+ the headers `x-revenium-transaction-name`, `-trace-type`, `-trace-name`,
1229
+ `-parent-transaction-id`, `-retry-number`, `-skill-name`, `-skill-source`,
1230
+ `-skill-kind`, `-skill-plugin-name`, `-skill-marketplace-name` and
1231
+ `-skill-invocation-trigger`. The gateway does not fall back to the task type for the
1232
+ transaction name, and sends a retry number only when the header or
1233
+ `REVENIUM_RETRY_NUMBER` sets one. The credential alias names the credential only on
1234
+ calls with no subscriber id or email and no virtual key alias; most virtual keys carry
1235
+ their owner's email, so those calls keep the owner's own credential. A spending cap on
1236
+ a credential alias therefore covers only calls with no subscriber identity, and on
1237
+ those calls a caller's `x-revenium-credential-alias` wins over the host's alias, for
1238
+ the cap check and the record alike. The agent's own version rides in
1239
+ `x-revenium-agent-version`, per call only with no host setting, and is cut to 64
1240
+ characters.
1241
+
1242
+ **Who made the call.** By default a proxied call is metered and budget-checked as the
1243
+ owner of the virtual key it used, which is right when every person has their own key.
1244
+ When several people share one key, have each client send
1245
+ `x-revenium-subscriber-email` (and optionally `x-revenium-subscriber-id`) naming the
1246
+ person making the call. Per-person and department budgets are looked up by that email,
1247
+ so without it a shared key's calls all count against its owner, and a blocked
1248
+ developer keeps getting through on the owner's budget. A call that sends someone
1249
+ else's email without an id carries no id at all, rather than the key's
1250
+ `revenium_user_id`, so it is checked against that person's balance and not the owner's. The captured header wins over a
1251
+ copy of the same key in the request's `metadata`; a blank value is ignored. Both are
1252
+ taken as the caller sends them: a shared key trusts its users to name themselves. On
1253
+ a team with strict ingestion enabled, the email must belong to a registered user, or
1254
+ the call's metering row is rejected instead of falling back to the key owner.
1255
+
1256
+ ```bash
1257
+ curl http://localhost:4000/v1/messages \
1258
+ -H "x-api-key: sk-shared-team-key" \
1259
+ -H "x-revenium-subscriber-email: dev@acme.com" \
1260
+ ...
1261
+ ```
1262
+
1263
+ ##### Counting a Claude Code call once (shared call id)
1264
+
1265
+ If you run Claude Code through your proxy **and** point Claude Code's own usage
1266
+ reporting at Revenium, every call is recorded twice: Claude Code files it under an
1267
+ identifier of its own making, the proxy files it under another, and the two can
1268
+ never match. `ReveniumGuardrail` makes them match, and does so by default.
1269
+
1270
+ The guardrail mints one identifier per proxied `/v1/messages` request, returns it to
1271
+ the client as the `request-id` and `x-revenium-transaction-id` response headers, and
1272
+ reports the same value as the call's transaction id. Claude Code copies `request-id`
1273
+ onto its own record, Revenium's duplicate check sees two records with one identifier,
1274
+ and one call becomes one record.
1275
+
1276
+ **It is on by default.** To opt out, with no `request-id` header added (each
1277
+ `/v1/messages` record then carries a per-request id the proxy assigns, never
1278
+ Anthropic's `msg_` id):
1279
+
1280
+ ```bash
1281
+ export REVENIUM_LITELLM_SHARED_CALL_ID=false
1282
+ ```
1283
+
1284
+ Blank or unset means on; `true`, `1`, `yes`, `on` mean on; any other value turns it off and the guardrail logs that at startup.
1285
+
1286
+ New calls go straight back to two records when you do; records already merged stay
1287
+ merged. Four things have to be true for it to work:
1288
+
1289
+ * **LiteLLM 1.93.0 or newer.** That is the floor of the `litellm-proxy` extra, which
1290
+ is what installs the guardrail. On an older LiteLLM the guardrail logs one warning
1291
+ at startup and behaves exactly as it does when opted out: no header is added,
1292
+ the provider's response id is reported, and you get two records rather than none.
1293
+ * **`mode` includes `pre_call`.** The identifier is minted in the pre-call hook, and
1294
+ LiteLLM runs that hook only when the configured mode asks for it. A
1295
+ `mode: ["post_call"]` proxy mints nothing, and the guardrail says so at startup
1296
+ with one warning naming this variable. Add `pre_call` to the mode, or set the
1297
+ variable to `false` if the proxy only meters.
1298
+ * **The Anthropic messages route.** Other routes are untouched, so the provider's own
1299
+ `request-id` on the pass-through route is never overwritten.
1300
+ * **Both sides report to the same Revenium team.** The duplicate check is
1301
+ team-scoped.
1302
+
1303
+ **Point Claude Code at the proxy root, not at `/anthropic`.** Set `ANTHROPIC_BASE_URL`
1304
+ to the proxy's own base URL so Claude Code calls `<proxy>/v1/messages`:
1305
+
1306
+ ```bash
1307
+ export ANTHROPIC_BASE_URL=https://proxy.example.com
1308
+ ```
1309
+
1310
+ LiteLLM also offers an Anthropic pass-through at `<proxy>/anthropic/v1/messages`, and
1311
+ its own API reference recommends that route over `/v1/messages`. The shared identifier
1312
+ is minted only on `/v1/messages`. A proxy serving the pass-through route hands the
1313
+ provider's response straight back, so nothing is minted there, no `request-id` of ours
1314
+ is returned, and the counter described below stays silent on that route by design.
1315
+ The flag will appear to be on and the calls will keep being counted twice, with
1316
+ nothing in the proxy log to say why. If your Claude Code base URL ends in
1317
+ `/anthropic`, drop that suffix.
1318
+
1319
+ Only the guardrail mints. A proxy still on the deprecated callback alone gets no
1320
+ identifier and keeps reporting two records, which is one more reason to migrate.
1321
+
1322
+ One caution for a proxy running **both** the guardrail and the deprecated callback
1323
+ without `default_on: true`. That configuration meters every call twice already, and
1324
+ this flag hides the symptom rather than fixing it: both rows now carry the same
1325
+ identifier and Revenium's duplicate check keeps one. The configuration is still
1326
+ wrong. Delete the `litellm_settings.callbacks` entry.
1327
+
1328
+ Also do not register `ReveniumGuardrail` in `litellm_settings.callbacks` as well as
1329
+ in the `guardrails` block. LiteLLM keys registered callbacks on the class name plus
1330
+ its simple attributes, and the two instances differ, so both are registered and every
1331
+ logging hook runs twice.
1332
+
1333
+ If the flag is on and an Anthropic messages call is metered with no identifier on it,
1334
+ the guardrail counts it and logs a warning at most once a minute with the running
1335
+ total, so a mint that quietly stopped shows up in the proxy log rather than as a
1336
+ return of double counting. Your other routes never carry an identifier and are never
1337
+ counted or warned about, so a proxy that also serves chat completions or embeddings
1338
+ stays quiet.
1339
+
1340
+ ##### Migrating from the callback
1341
+
1342
+ `revenium_middleware.litellm.proxy.middleware.MiddlewareHandler` — the
1343
+ `litellm_settings.callbacks` entry `proxy_handler_instance` — is **deprecated**. It
1344
+ meters but never enforces a budget. It keeps working in this release and emits a
1345
+ `DeprecationWarning` (and a log line) when the proxy builds it.
1346
+
1347
+ While the callback is listed, client mode leaves each proxied completion to it, so the
1348
+ call is recorded once, with the subscriber, organization and product from the
1349
+ `x-revenium-*` headers. Proxied embeddings are recorded by client mode, without those
1350
+ headers, as the callback has never metered them.
1351
+
1352
+ To migrate, delete the callbacks entry and add the `guardrails` block above:
1353
+
1354
+ ```diff
1355
+ litellm_settings:
1356
+ - callbacks: ["revenium_middleware.litellm.proxy.middleware.proxy_handler_instance"]
1357
+ +
1358
+ +guardrails:
1359
+ + - guardrail_name: "revenium"
1360
+ + litellm_params:
1361
+ + guardrail: revenium_middleware.litellm.proxy.guardrail.ReveniumGuardrail
1362
+ + mode: ["pre_call", "post_call"]
1363
+ + default_on: true
1364
+ ```
1365
+
1366
+ Nothing else changes: the same headers, the same metered fields. Metered rows
1367
+ record `middleware_source: "GUARDRAIL"` instead of `"PROXY"`.
1368
+
1369
+ Leaving both enabled would meter every call twice. As a safety net for a proxy
1370
+ mid-migration, when the guardrail is configured to run on every request
1371
+ (`default_on: true` with `post_call` among its modes) it claims metering ownership
1372
+ and the deprecated callback stops submitting rows, logging once to say so. That net
1373
+ does **not** apply to a guardrail without `default_on`, without `post_call`, or
1374
+ configured with a per-tag `Mode` (which selects hooks per request): such a guardrail
1375
+ may not run on a given request, and suppressing the callback could drop metering
1376
+ entirely. A per-tag configuration logs, at info level, that it is not claiming
1377
+ ownership. Delete the callbacks entry rather than relying on the net.
1378
+
1379
+ ##### Client API and guardrails
1380
+
1381
+ `CustomGuardrail`'s lifecycle hooks cannot be hosted by LiteLLM's client API.
1382
+ Verified against **litellm 1.100.1**: `async_pre_call_hook`,
1383
+ `async_post_call_success_hook` and `async_post_call_failure_hook` are dispatched
1384
+ only from `litellm/proxy/utils.py` (`ProxyLogging`) and
1385
+ `litellm/proxy/common_request_processing.py`. The client path
1386
+ (`litellm_core_utils/litellm_logging.py`) dispatches only the `CustomLogger`
1387
+ logging events, so a `CustomGuardrail` added to `litellm.callbacks` without the
1388
+ proxy running would be a logger with no pre-call hook and no ability to block a
1389
+ call — the enforcement half would silently not exist.
1390
+
1391
+ So the client integration keeps its own path, unchanged: use
1392
+ `revenium_middleware.litellm.client` as documented above. The LiteLLM client
1393
+ wrapper runs the same pre-call circuit breaker with the caller's `usage_metadata`
1394
+ (and any `@revenium_metadata` identity) and raises `BudgetExceededError` before
1395
+ LiteLLM is called, so LiteLLM's retries never send a blocked call. That check runs
1396
+ only outside the proxy: requests the proxy serves are enforced by this guardrail.
1397
+ Both the guardrail and the client wrapper
1398
+ already share their metering plumbing (`revenium_middleware._core`: field
1399
+ extraction, cache-token extraction and `submit_ai_event`), so the guardrail adds no
1400
+ second copy of it.
1401
+
1402
+ #### LiteLLM Decorators
1403
+
1404
+ LiteLLM provides additional tracking decorators beyond the standard `@revenium_metadata` and `@revenium_meter`:
1405
+
1406
+ | Decorator | Purpose |
1407
+ |-----------|---------|
1408
+ | `@track_agent()` | Identify the AI agent |
1409
+ | `@track_task()` | Classify the type of work |
1410
+ | `@track_trace()` | Set trace ID for distributed tracing |
1411
+ | `@track_organization()` | Track multi-tenant organizations |
1412
+ | `@track_subscription()` | Track subscription-based billing |
1413
+ | `@track_product()` | Track product-specific usage |
1414
+ | `@track_subscriber()` | Identify end users |
1415
+ | `@track_quality()` | Track response quality scores |
1416
+ | `@track_job()` | Inject agentic job fields for cost/ROI correlation, e.g. `@track_job(job_id="loan-app-12345", type="loan_processing")` |
1417
+
1418
+ The tracking decorators above support static values, extraction from function arguments (`name_from_arg`), or extraction from object attributes (`name_from_attr`); `@track_job` supports static values and argument extraction (`job_id_from_arg`, `type_from_arg`) but has no attribute variant.
1419
+
1420
+ #### CrewAI Integration
1421
+
1422
+ ```bash
1423
+ pip install "revenium-python-sdk[openai]" crewai
1424
+ ```
1425
+
1426
+ 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.
1427
+
1428
+ **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:
1429
+
1430
+ ```python
1431
+ import revenium_middleware.openai # OpenAI models, e.g. LLM(model="gpt-4o-mini")
1432
+ import revenium_middleware.anthropic # Anthropic models, e.g. LLM(model="anthropic/claude-3-5-haiku-latest")
1433
+ import revenium_middleware.google.google_ai # Gemini models, e.g. LLM(model="gemini/gemini-2.5-flash")
1434
+ import revenium_middleware.litellm.client.middleware # LLM(..., is_litellm=True) and models CrewAI routes to LiteLLM
1435
+ ```
1436
+
1437
+ 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.
1438
+
1439
+ What the wrapper does not cover:
1440
+ - 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.
1441
+ - Only `kickoff()` and `kickoff_async()` are attributed. Calls started through the underlying crew's `akickoff()` or `kickoff_for_each*()` are not.
1442
+
1443
+ **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).
1444
+
1445
+ ```python
1446
+ from revenium_middleware.litellm.client.integrations.crewai import ReveniumCrewWrapper
1447
+
1448
+ crew = ReveniumCrewWrapper(
1449
+ agents=[support_agent],
1450
+ tasks=[triage_task],
1451
+ organization_name="AcmeCorp",
1452
+ subscription_id="82764738",
1453
+ product_name="Platinum",
1454
+ agentic_job_id="support-ticket-456",
1455
+ agentic_job_name="Support Ticket Triage",
1456
+ agentic_job_type="customer_support",
1457
+ agentic_job_version="2.0",
1458
+ )
1459
+ result = crew.kickoff()
1460
+
1461
+ crew.report_job_outcome(
1462
+ execution_status="SUCCESS",
1463
+ outcome_type="DEFLECTED",
1464
+ outcome_value=25.0,
1465
+ )
1466
+
1467
+ # Later, if the business result changes:
1468
+ # crew.amend_job_outcome(reason="Ticket reopened and escalated to a human agent",
1469
+ # outcome_type="ESCALATED", outcome_value=0.0)
1470
+ ```
1471
+
1472
+ **LiteLLM environment variables:**
1473
+ - `LITELLM_PROXY_URL` - Your LiteLLM proxy URL
1474
+ - `LITELLM_API_KEY` - Your LiteLLM proxy API key
1475
+
1476
+ **Examples:** `examples/litellm/` - `getting_started.py`, `litellm_proxy_example.py`, `crewai_decorator_example.py`
1477
+
1478
+ ---
1479
+
1480
+ ### Perplexity
1481
+
1482
+ Supports both the OpenAI SDK (with Perplexity base URL) and the native Perplexity SDK, with streaming support.
1483
+
1484
+ #### Using OpenAI SDK
1485
+
1486
+ ```python
1487
+ from dotenv import load_dotenv
1488
+ load_dotenv()
1489
+
1490
+ from openai import OpenAI
1491
+ import revenium_middleware.perplexity # Auto-patches OpenAI
1492
+
1493
+ client = OpenAI(
1494
+ api_key=os.getenv("PERPLEXITY_API_KEY"),
1495
+ base_url="https://api.perplexity.ai"
1496
+ )
1497
+
1498
+ response = client.chat.completions.create(
1499
+ model="sonar",
1500
+ messages=[{"role": "user", "content": "What is the capital of France?"}],
1501
+ usage_metadata={"organizationName": "AcmeCorp"}
1502
+ )
1503
+ ```
1504
+
1505
+ #### Using Native Perplexity SDK
1506
+
1507
+ ```python
1508
+ from perplexity import Perplexity
1509
+ import revenium_middleware.perplexity # Auto-patches Perplexity
1510
+
1511
+ client = Perplexity(api_key=os.getenv("PERPLEXITY_API_KEY"))
1512
+
1513
+ response = client.chat.completions.create(
1514
+ model="sonar",
1515
+ messages=[{"role": "user", "content": "Hello!"}],
1516
+ usage_metadata={"organizationName": "AcmeCorp"}
1517
+ )
1518
+ ```
1519
+
1520
+ 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.
1521
+
1522
+ 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.
1523
+
1524
+ **Streaming:**
1525
+
1526
+ ```python
1527
+ stream = client.chat.completions.create(
1528
+ model="sonar-pro",
1529
+ messages=[{"role": "user", "content": "Write a poem"}],
1530
+ stream=True,
1531
+ usage_metadata={"task_type": "creative_writing"}
1532
+ )
1533
+ for chunk in stream:
1534
+ if chunk.choices[0].delta.content:
1535
+ print(chunk.choices[0].delta.content, end="", flush=True)
1536
+ ```
1537
+
1538
+ **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.
1539
+
1540
+ **Examples:** `examples/perplexity/` - `getting_started.py`, `basic.py`, `streaming.py`, `example_decorator.py`
1541
+
1542
+ ---
1543
+
1544
+ ### fal.ai
1545
+
1546
+ 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.
1547
+
1548
+ ```python
1549
+ import revenium_middleware.fal # Auto-activates
1550
+ import fal_client
1551
+
1552
+ result = fal_client.subscribe(
1553
+ "fal-ai/flux/dev",
1554
+ arguments={
1555
+ "prompt": "A beautiful sunset over mountains",
1556
+ "image_size": "landscape_16_9"
1557
+ },
1558
+ usage_metadata={
1559
+ "organizationName": "AcmeCorp",
1560
+ "task_type": "image-generation"
1561
+ }
1562
+ )
1563
+
1564
+ for image in result.get("images", []):
1565
+ print(f"Image URL: {image['url']}")
1566
+ ```
1567
+
1568
+ **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()`.
1569
+
1570
+ **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.
1571
+
1572
+ **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.
1573
+
1574
+ 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.
1575
+
1576
+ **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.
1577
+
1578
+ **Environment variables:**
1579
+ - `FAL_KEY` - Your fal.ai API key
1580
+
1581
+ ---
1582
+
1583
+ ### LangChain
1584
+
1585
+ Callback handler that automatically tracks LLM calls, chains, tools, and agent actions.
1586
+
1587
+ ```bash
1588
+ pip install "revenium-python-sdk[langchain]"
1589
+ ```
1590
+
1591
+ Wrap any LangChain chat model or LLM with `wrap()`; the Revenium callback handler is attached for you:
1592
+
1593
+ ```python
1594
+ from langchain_openai import ChatOpenAI
1595
+ from revenium_middleware.openai.langchain import wrap
1596
+
1597
+ llm = wrap(
1598
+ ChatOpenAI(model="gpt-4o-mini"),
1599
+ usage_metadata={
1600
+ "trace_id": "session-123",
1601
+ "agent": "support_agent",
1602
+ },
1603
+ )
1604
+ response = llm.invoke("Hello!")
1605
+ ```
1606
+
1607
+ **With chains:**
1608
+
1609
+ ```python
1610
+ from langchain_core.prompts import ChatPromptTemplate
1611
+ from langchain_core.output_parsers import StrOutputParser
1612
+
1613
+ prompt = ChatPromptTemplate.from_template("Tell me a joke about {topic}")
1614
+ chain = prompt | llm | StrOutputParser()
1615
+ result = chain.invoke({"topic": "programming"})
1616
+ ```
1617
+
1618
+ **With agents:**
1619
+
1620
+ ```python
1621
+ from langchain_core.messages import HumanMessage
1622
+ from langchain_core.tools import tool
1623
+ from langgraph.prebuilt import create_react_agent
1624
+
1625
+ @tool
1626
+ def get_weather(city: str) -> str:
1627
+ """Get the weather for a city."""
1628
+ return f"Sunny, 72F in {city}"
1629
+
1630
+ agent = create_react_agent(llm, [get_weather])
1631
+ result = agent.invoke({"messages": [HumanMessage(content="Weather in NYC?")]})
1632
+ ```
1633
+
1634
+ **Async support:** the handler is async-native — wrap once and use `ainvoke`/`astream` directly:
1635
+
1636
+ ```python
1637
+ llm = wrap(ChatOpenAI(model="gpt-4o-mini"))
1638
+ response = await llm.ainvoke("Hello!")
1639
+ ```
1640
+
1641
+ **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.
1642
+
1643
+ **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.
1644
+
1645
+ **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.
1646
+
1647
+ **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.
1648
+
1649
+ **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)):
1650
+
1651
+ ```python
1652
+ from revenium_middleware.openai.langchain import attach_to
1653
+
1654
+ attach_to(llm, usage_metadata={
1655
+ "organizationName": "my_org",
1656
+ "productName": "my_product",
1657
+ })
1658
+ ```
1659
+
1660
+ 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:
1661
+
1662
+ ```python
1663
+ from revenium_middleware import revenium_metadata
1664
+ from revenium_middleware.openai.langchain import UnifiedReveniumCallbackHandler
1665
+
1666
+ # (a) Model attached once at startup; name the person inside the request handler.
1667
+ def handle_request(user, question):
1668
+ @revenium_metadata(subscriber={"id": user.id, "email": user.email})
1669
+ def answer():
1670
+ return llm.invoke(question)
1671
+ return answer()
1672
+
1673
+ # (b) A model with no attach_to(); pass a handler with the call.
1674
+ def handle_request(user, question):
1675
+ handler = UnifiedReveniumCallbackHandler(usage_metadata={"subscriber": {"id": user.id}})
1676
+ return bare_llm.invoke(question, config={"callbacks": [handler]})
1677
+ ```
1678
+
1679
+ 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.
1680
+
1681
+ 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.
1682
+
1683
+ 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.
1684
+
1685
+ **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:
1686
+
1687
+ ```python
1688
+ from revenium_middleware import revenium_metadata
1689
+ from langchain_openai import OpenAIEmbeddings
1690
+
1691
+ embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
1692
+
1693
+ @revenium_metadata(organization_name="AcmeCorp", agent="support_agent", trace_id="session-123")
1694
+ def embed(texts):
1695
+ return embeddings.embed_documents(texts)
1696
+ ```
1697
+
1698
+ 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)).
1699
+
1700
+ **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.
1701
+
1702
+ 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.
1703
+
1704
+ ---
1705
+
1706
+ ### Griptape
1707
+
1708
+ Metered prompt and embedding drivers for [Griptape](https://github.com/griptape-ai/griptape) applications. Requires Python 3.10+.
1709
+
1710
+ ```bash
1711
+ pip install "revenium-python-sdk[griptape,openai]" # OpenAI
1712
+ pip install "revenium-python-sdk[griptape,anthropic]" # Anthropic
1713
+ pip install "revenium-python-sdk[griptape,ollama]" # Ollama
1714
+ pip install "revenium-python-sdk[griptape,litellm,litellm-proxy]" # 100+ providers via LiteLLM
1715
+ ```
1716
+
1717
+ `ReveniumDriver` auto-detects the provider from the model name (`gpt-*` → OpenAI, `claude-*` → Anthropic, `llama`/`mistral`/... → Ollama, anything else → LiteLLM) and wraps the matching Griptape prompt driver with Revenium metering:
1718
+
1719
+ ```python
1720
+ import os
1721
+ from griptape.structures import Agent
1722
+ from revenium_middleware import BudgetExceededError
1723
+ from revenium_middleware.griptape import ReveniumDriver, enable_budget_errors
1724
+
1725
+ os.environ["REVENIUM_METERING_API_KEY"] = "your_revenium_key"
1726
+ enable_budget_errors() # once at startup, so a spending-cap refusal reaches your except block
1727
+
1728
+ agent = Agent(prompt_driver=ReveniumDriver(
1729
+ model="gpt-4o-mini",
1730
+ usage_metadata={"task_type": "demo"},
1731
+ ))
1732
+ try:
1733
+ agent.run("Hello!")
1734
+ except BudgetExceededError as e:
1735
+ print(f"Spending cap reached: {e.message}")
1736
+ ```
1737
+
1738
+ Force a provider with `force_provider="litellm"`, or wrap an existing driver with `ReveniumDriver(base_driver=...)`.
1739
+
1740
+ 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.
1741
+
1742
+ 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.
1743
+
1744
+ **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.
1745
+
1746
+ 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.
1747
+
1748
+ **Embeddings:**
1749
+
1750
+ ```python
1751
+ from revenium_middleware.griptape import ReveniumEmbeddingDriver
1752
+
1753
+ driver = ReveniumEmbeddingDriver(model="text-embedding-3-large")
1754
+ ```
1755
+
1756
+ **Provider-specific drivers:** for direct control, use `ReveniumOpenAiDriver`, `ReveniumAnthropicDriver`, `ReveniumOllamaDriver`, `ReveniumLiteLLMDriver` or `ReveniumOpenAiEmbeddingDriver` — each subclasses the corresponding Griptape driver and accepts a `usage_metadata` dict (see [Metadata Fields](#metadata-fields)).
1757
+
1758
+ **Migrating from `revenium-griptape`:** the standalone package is deprecated — install the `griptape` extra and change `from revenium_griptape import ReveniumDriver` to `from revenium_middleware.griptape import ReveniumDriver`. All driver class names are unchanged. One behaviour difference: the old package called `load_dotenv()` automatically at import time; the SDK never mutates your environment on import, so if you keep credentials in a `.env` file, call `load_dotenv()` yourself before creating a driver.
1759
+
1760
+ ---
1761
+
1762
+ ## Metadata Fields
1763
+
1764
+ 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.
1765
+ These fields are shortened with a WARNING when longer than Revenium stores, so the call is still
1766
+ recorded: `trace_id`, `task_type`, `agent`, `subscription_id`, `parent_transaction_id`, `environment`,
1767
+ `region`, `transaction_name`, `operation_subtype`, `subscriber.id` and `subscriber.email` at 255
1768
+ characters, and `product_name` at 224. Other text fields are sent as given.
1769
+
1770
+ | Field | Description | Use Case |
1771
+ |-------|-------------|----------|
1772
+ | `trace_id` | Unique session or conversation identifier | Link multiple API calls together for debugging, session analytics, or distributed tracing |
1773
+ | `task_type` | Type of AI task being performed | Categorize usage by workload (e.g., `"chat"`, `"code-generation"`, `"doc-summary"`) for cost analysis |
1774
+ | `subscriber.id` | Unique user identifier | Track individual user consumption for billing, rate limiting, or analytics |
1775
+ | `subscriber.email` | User email address | Identify users for support, compliance, or usage reports |
1776
+ | `subscriber.credential.name` | Authentication credential name | Track which API key or service account made the request |
1777
+ | `subscriber.credential.value` | Authentication credential value | Associate usage with specific credentials for security auditing |
1778
+ | `organizationName` | Organization or company name | Multi-tenant cost allocation, usage quotas per organization. Auto-creates if not found |
1779
+ | `subscription_id` | Subscription plan identifier | Track usage against subscription limits, identify plan upgrade opportunities |
1780
+ | `productName` | Your product or feature name | Attribute AI costs to specific features (e.g., `"customer-chatbot"`, `"email-assistant"`). Auto-creates if not found |
1781
+ | `agent` | AI agent or bot identifier | Distinguish between multiple AI agents or automation workflows |
1782
+ | `response_quality_score` | Custom quality rating (0.0-1.0) | Track user satisfaction or automated quality metrics for model performance analysis |
1783
+ | `effort` | Reasoning effort level requested of the model (free-form string, max 16 chars, `^[A-Za-z0-9_-]+$`) | Report what share of AI spend is high-effort reasoning, and compare cost per effort level |
1784
+
1785
+ **Example:**
1786
+
1787
+ ```python
1788
+ response = client.chat.completions.create(
1789
+ model="gpt-4o-mini",
1790
+ messages=[{"role": "user", "content": "Hello!"}],
1791
+ usage_metadata={
1792
+ "trace_id": "conv-28a7e9d4",
1793
+ "task_type": "customer-support",
1794
+ "subscriber": {
1795
+ "id": "user-1234",
1796
+ "email": "user@example.com",
1797
+ "credential": {
1798
+ "name": "engineering-api-key",
1799
+ "value": "sk-1234567890abcdef"
1800
+ }
1801
+ },
1802
+ "organizationName": "AcmeCorp",
1803
+ "subscription_id": "pro-plan-Q1",
1804
+ "productName": "customer-support-chatbot",
1805
+ "agent": "support-agent",
1806
+ "response_quality_score": 0.92,
1807
+ "effort": "high"
1808
+ }
1809
+ )
1810
+ ```
1811
+
1812
+ **Reasoning effort:** `effort` records how hard the model was asked to think, so
1813
+ high-effort reasoning spend can be separated from the rest. It is a free-form
1814
+ string, not an enum -- vendor vocabularies differ and drift, so `low`, `medium`,
1815
+ `high`, `xhigh` and `ultra` are all real values, and a level this SDK release has
1816
+ never heard of is passed through untouched rather than rejected or rewritten. The
1817
+ Revenium backend rule is at most 16 characters, matching `^[A-Za-z0-9_-]+$`; a
1818
+ value outside it is left off the record with a WARNING, and the call is still
1819
+ recorded with its tokens and cost. It is distinct from the reported reasoning token count,
1820
+ which measures the tokens actually spent rather than the level requested.
1821
+
1822
+ Set it per call in `usage_metadata` on any provider integration. In LiteLLM proxy
1823
+ mode, where per-call attribution travels as request headers rather than
1824
+ `usage_metadata`, send `x-revenium-effort` instead.
1825
+
1826
+ **Deprecation notice:** The legacy field aliases `organizationId`, `organization_id`, `productId`, and `product_id` are accepted by this SDK only as an input-layer convenience and emit a `DeprecationWarning`. The Revenium backend no longer accepts them — they are translated to `organizationName` / `productName` before the wire call. Migrate to `organization_name` / `organizationName` and `product_name` / `productName` now; the input-layer aliases will be removed in the next major release.
1827
+
1828
+ **API Reference:** [Complete metadata field documentation](https://revenium.readme.io/reference/meter_ai_completion)
1829
+
1830
+ ---
1831
+
1832
+ ## Trace Visualization & Distributed Tracing
1833
+
1834
+ Enhanced observability fields for tracking AI operations across environments, regions, and workflows. Fields can be set via environment variables (static/deployment-level defaults) or passed directly in `usage_metadata` (dynamic/per-request values). Direct values always take precedence.
1835
+
1836
+ ### Available Fields
1837
+
1838
+ | Field | Environment Variable (Fallback) | Description | Use Case |
1839
+ |-------|----------------------------------|-------------|----------|
1840
+ | `environment` | `REVENIUM_ENVIRONMENT` (auto-detects: `ENVIRONMENT`, `DEPLOYMENT_ENV`) | Deployment environment | Track usage across `production`, `staging`, `dev` |
1841
+ | `region` | `REVENIUM_REGION` (auto-detects: `AWS_REGION`, `AZURE_REGION`, `GCP_REGION`) | Cloud region identifier | Multi-region deployment tracking and latency analysis |
1842
+ | `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 |
1843
+ | `trace_type` | `REVENIUM_TRACE_TYPE` | Workflow category (max 128 chars, alphanumeric/hyphens/underscores) | Group similar workflows (e.g., `"customer-support"`, `"data-analysis"`) |
1844
+ | `trace_name` | `REVENIUM_TRACE_NAME` | Human-readable trace label (max 256 chars) | Label trace instances (e.g., `"Customer Support Chat"`) |
1845
+ | `parent_transaction_id` | `REVENIUM_PARENT_TRANSACTION_ID` | Parent transaction ID | Link child operations to parents across microservices |
1846
+ | `transaction_name` | `REVENIUM_TRANSACTION_NAME` | Human-friendly operation name | Label operations (e.g., `"Generate Response"`, `"Analyze Sentiment"`) |
1847
+ | `retry_number` | `REVENIUM_RETRY_NUMBER` | Retry attempt number (0 = first attempt) | Track retry attempts for failed operations |
1848
+ | `ticket_id` | `REVENIUM_TICKET_ID` | External ticket or issue ID (e.g., Jira, Linear) (max 256 chars) | Attribute AI costs to individual tickets or issues |
1849
+ | `agent_version` | _(none — per call only)_ | Version of the AI agent that produced the call (max 64 chars) | Compare cost across agent releases; not `agentic_job_version`, which versions the job definition |
1850
+ | `skill_name` | `REVENIUM_SKILL_NAME` | Name of the agent skill that produced the call (max 256 chars) | Attribute AI costs to the skill that generated them |
1851
+ | `skill_source` | `REVENIUM_SKILL_SOURCE` | Where the skill was loaded from — accepted values: `bundled`, `projectSettings`, `userSettings`, `plugin` (case-sensitive) | Classify skill origin in the shared skill catalog |
1852
+ | `skill_kind` | `REVENIUM_SKILL_KIND` | Kind of skill invoked — accepted value: `workflow` (omit otherwise) | Distinguish workflow skills in reporting |
1853
+ | `skill_plugin_name` | `REVENIUM_SKILL_PLUGIN_NAME` | Plugin providing the skill, when `skill_source` is `plugin` (max 256 chars) | Attribute costs to a specific plugin |
1854
+ | `skill_marketplace_name` | `REVENIUM_SKILL_MARKETPLACE_NAME` | Marketplace the skill or plugin was installed from (max 256 chars) | Track marketplace-sourced skill usage |
1855
+ | `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 |
1856
+
1857
+ **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`.
1858
+
1859
+ ### Usage
1860
+
1861
+ **Static fields via environment variables** (deployment-level defaults):
1862
+
1863
+ ```bash
1864
+ # .env file
1865
+ REVENIUM_ENVIRONMENT=production
1866
+ REVENIUM_REGION=us-east-1
1867
+ REVENIUM_CREDENTIAL_ALIAS=prod-openai-key
1868
+ REVENIUM_TRACE_TYPE=customer-support
1869
+ ```
1870
+
1871
+ **Dynamic fields via `usage_metadata`** (per-request values):
1872
+
1873
+ ```python
1874
+ response = client.chat.completions.create(
1875
+ model="gpt-4o-mini",
1876
+ messages=[{"role": "user", "content": "Hello!"}],
1877
+ usage_metadata={
1878
+ "environment": "production",
1879
+ "region": "us-east-1",
1880
+ "trace_type": "customer-support",
1881
+ "trace_name": "Support Chat Session",
1882
+ "transaction_name": "Generate Response",
1883
+ "parent_transaction_id": "parent-txn-123",
1884
+ "ticket_id": "JIRA-123",
1885
+ "agent_version": "1.4.2"
1886
+ }
1887
+ )
1888
+ ```
1889
+
1890
+ **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.
1891
+
1892
+ 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.
1893
+
1894
+ ### Distributed Tracing Example
1895
+
1896
+ ```python
1897
+ import uuid
1898
+
1899
+ workflow_id = str(uuid.uuid4())
1900
+
1901
+ # Step 1: Parent operation
1902
+ parent_response = client.chat.completions.create(
1903
+ model="gpt-4o-mini",
1904
+ messages=[{"role": "user", "content": "Analyze this document"}],
1905
+ usage_metadata={
1906
+ "trace_id": "analysis-session-456",
1907
+ "transaction_name": "Document Analysis",
1908
+ "task_type": "analysis"
1909
+ }
1910
+ )
1911
+
1912
+ # Step 2: Child operation linked to parent
1913
+ child_response = client.chat.completions.create(
1914
+ model="gpt-4o-mini",
1915
+ messages=[{"role": "user", "content": "Summarize findings"}],
1916
+ usage_metadata={
1917
+ "trace_id": "analysis-session-456",
1918
+ "parent_transaction_id": parent_response.id,
1919
+ "transaction_name": "Summarize Results",
1920
+ "task_type": "summarization"
1921
+ }
1922
+ )
1923
+ ```
1924
+
1925
+ ---
1926
+
1927
+ ## Decorator Support
1928
+
1929
+ ### `@revenium_metadata` - Automatic Metadata Injection
1930
+
1931
+ Automatically injects metadata into all API calls within a function's scope. Eliminates the need to pass `usage_metadata` to every API call.
1932
+
1933
+ ```python
1934
+ from revenium_middleware import revenium_metadata
1935
+
1936
+ @revenium_metadata(
1937
+ trace_id="session-12345",
1938
+ task_type="customer-support",
1939
+ organizationName="AcmeCorp",
1940
+ environment="production"
1941
+ )
1942
+ def handle_customer_query(question: str) -> str:
1943
+ # All API calls automatically include the decorator metadata
1944
+ response = client.chat.completions.create(
1945
+ model="gpt-4o-mini",
1946
+ messages=[{"role": "user", "content": question}]
1947
+ )
1948
+ return response.choices[0].message.content
1949
+
1950
+ answer = handle_customer_query("How do I reset my password?")
1951
+ ```
1952
+
1953
+ **Features:**
1954
+ - **DRY Principle**: Define metadata once, apply to all API calls in the function
1955
+ - **Composable**: Decorators can be nested - inner decorators inherit and override outer ones
1956
+ - **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
1957
+ - **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
1958
+ - **Thread-safe**: Uses `contextvars` for proper isolation
1959
+
1960
+ **Nested decorators (metadata merging):**
1961
+
1962
+ ```python
1963
+ @revenium_metadata(organizationName="AcmeCorp", environment="production")
1964
+ def outer_function():
1965
+ # Gets: organizationName, environment
1966
+ response1 = client.chat.completions.create(...)
1967
+
1968
+ @revenium_metadata(trace_id="inner-trace", task_type="analysis")
1969
+ def inner_function():
1970
+ # Gets: organizationName, environment (inherited) + trace_id, task_type (added)
1971
+ response2 = client.chat.completions.create(...)
1972
+ return response2
1973
+
1974
+ return inner_function()
1975
+ ```
1976
+
1977
+ **API-level override:**
1978
+
1979
+ ```python
1980
+ @revenium_metadata(organizationName="AcmeCorp", task_type="default")
1981
+ def mixed_metadata():
1982
+ # Uses decorator metadata
1983
+ response1 = client.chat.completions.create(
1984
+ model="gpt-4o-mini",
1985
+ messages=[{"role": "user", "content": "Hello"}]
1986
+ )
1987
+
1988
+ # API-level metadata overrides decorator's task_type
1989
+ response2 = client.chat.completions.create(
1990
+ model="gpt-4o-mini",
1991
+ messages=[{"role": "user", "content": "Hello"}],
1992
+ usage_metadata={
1993
+ "task_type": "special-override", # Overrides decorator
1994
+ "trace_id": "api-level-trace" # Adds new field
1995
+ # organizationName still inherited from decorator
1996
+ }
1997
+ )
1998
+ ```
1999
+
2000
+ ### `@revenium_meter` - Selective Metering
2001
+
2002
+ Control which functions are metered when selective metering mode is enabled. This is useful for metering only specific high-value operations while ignoring others.
2003
+
2004
+ **Note:** This decorator only has an effect when `REVENIUM_SELECTIVE_METERING=true` is set. By default, all API calls are metered automatically.
2005
+
2006
+ 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.
2007
+
2008
+ ```bash
2009
+ # Enable selective metering
2010
+ export REVENIUM_SELECTIVE_METERING=true
2011
+ ```
2012
+
2013
+ ```python
2014
+ from revenium_middleware import revenium_meter, revenium_metadata
2015
+
2016
+ @revenium_meter()
2017
+ @revenium_metadata(task_type="premium-feature", organizationName="PremiumTier")
2018
+ def premium_feature(prompt: str) -> str:
2019
+ # This WILL be metered (decorated with @revenium_meter)
2020
+ response = client.chat.completions.create(
2021
+ model="gpt-4o-mini",
2022
+ messages=[{"role": "user", "content": prompt}]
2023
+ )
2024
+ return response.choices[0].message.content
2025
+
2026
+ def free_feature(prompt: str) -> str:
2027
+ # This will NOT be metered (no @revenium_meter decorator)
2028
+ response = client.chat.completions.create(
2029
+ model="gpt-4o-mini",
2030
+ messages=[{"role": "user", "content": prompt}]
2031
+ )
2032
+ return response.choices[0].message.content
2033
+ ```
2034
+
2035
+ **Accepted values for `REVENIUM_SELECTIVE_METERING`:**
2036
+ - `"true"`, `"1"`, `"yes"`, `"on"` (case-insensitive) - Selective metering enabled
2037
+ - `"false"`, `"0"`, `"no"`, `"off"`, or unset - All calls metered (default)
2038
+
2039
+ **Worker threads:** The metering mark of `@revenium_meter` and the tags of
2040
+ `@revenium_metadata` follow `await`, asyncio tasks and `asyncio.to_thread`, but
2041
+ not `ThreadPoolExecutor`, `threading.Thread` or `loop.run_in_executor`: those
2042
+ start the thread in an empty context. AI calls made on such a thread are not metered when selective metering
2043
+ is on, and are recorded without the decorator's tags when it is off.
2044
+
2045
+ To carry them, wrap the thread's target with `carry_context` inside the decorated
2046
+ function, each time you hand work to a thread:
2047
+
2048
+ ```python
2049
+ from concurrent.futures import ThreadPoolExecutor
2050
+ from revenium_middleware import carry_context, revenium_meter, revenium_metadata
2051
+
2052
+ @revenium_meter()
2053
+ @revenium_metadata(task_type="premium-feature", organizationName="PremiumTier")
2054
+ def summarize_all(docs: list[str]) -> list[str]:
2055
+ with ThreadPoolExecutor() as pool:
2056
+ return list(pool.map(carry_context(summarize), docs))
2057
+ ```
2058
+
2059
+ `carry_context` is not a decorator: a wrap made outside the decorated function
2060
+ carries nothing. With selective metering on, a thread started outside any
2061
+ decorated function is never metered through it; with it off, such calls are
2062
+ still metered, without the decorator's tags. Wrapping an `async def` carries
2063
+ nothing either, because its coroutine runs later on the event loop, outside the
2064
+ copied context: wrap the sync function the thread runs instead, or copy the
2065
+ context around the awaited call. It also carries a `metering_key()` or `idempotency_key()`
2066
+ block in force where it is called. The first time selective metering skips a
2067
+ call, the SDK logs one INFO line saying so.
2068
+
2069
+ **Decorator order matters:** Place `@revenium_meter` before `@revenium_metadata` (outer to inner).
2070
+
2071
+ ---
2072
+
2073
+ ## Tool Metering
2074
+
2075
+ The `@meter_tool` decorator lets you meter arbitrary tool/function calls (web scrapers, database lookups, API fetchers, image generators, etc.) alongside your automatic LLM API metering.
2076
+
2077
+ ```python
2078
+ import os
2079
+ from revenium_middleware import meter_tool, configure
2080
+
2081
+ # Configure the metering client for tool calls
2082
+ configure(
2083
+ metering_url=os.getenv("REVENIUM_METERING_BASE_URL", "https://api.revenium.ai"),
2084
+ api_key=os.environ["REVENIUM_METERING_API_KEY"],
2085
+ )
2086
+
2087
+ # Decorate any tool function to automatically meter it
2088
+ @meter_tool("customer-database", operation="lookup", agent="support-bot")
2089
+ def lookup_customer(customer_id: str) -> dict:
2090
+ """Timing and success/failure are automatically tracked."""
2091
+ return {"name": "Jane Smith", "plan": "Enterprise"}
2092
+
2093
+ # The decorator reports the tool call to Revenium automatically
2094
+ result = lookup_customer("CUST-42")
2095
+ ```
2096
+
2097
+ 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.
2098
+
2099
+ **Manual reporting:**
2100
+
2101
+ ```python
2102
+ from revenium_middleware import report_tool_call
2103
+
2104
+ report_tool_call(
2105
+ tool_id="my-tool",
2106
+ operation="fetch",
2107
+ duration_ms=1234,
2108
+ success=True,
2109
+ usage_metadata={"records": 42},
2110
+ )
2111
+ ```
2112
+
2113
+ **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.
2114
+
2115
+ ---
2116
+
2117
+ ## Prompt Capture
2118
+
2119
+ Optional capture of prompts and responses for analytics and debugging. **Disabled by default** to protect sensitive data.
2120
+
2121
+ ### Enable
2122
+
2123
+ ```bash
2124
+ export REVENIUM_CAPTURE_PROMPTS=true
2125
+ ```
2126
+
2127
+ ### What Gets Captured
2128
+
2129
+ | Field | Description | Source |
2130
+ |-------|-------------|--------|
2131
+ | `system_prompt` | System prompt content | From `system` parameter / system message; for the OpenAI Responses API, `instructions` (else the first `system` or `developer` input item) |
2132
+ | `input_messages` | User/assistant messages as JSON | From `messages` parameter, or the Responses API `input` |
2133
+ | `output_response` | Assistant's response content | From response content blocks, or the text of a Responses API reply's messages |
2134
+ | `prompts_truncated` | Truncation flag | Set to `true` if any field exceeded its maximum length |
2135
+
2136
+ 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.
2137
+
2138
+ 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.
2139
+
2140
+ 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.
2141
+
2142
+ 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.
2143
+
2144
+ ### Maximum Length
2145
+
2146
+ ```bash
2147
+ export REVENIUM_MAX_PROMPT_SIZE=20000
2148
+ ```
2149
+
2150
+ `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.
2151
+
2152
+ The SDK reads these settings once, when it is imported, so call `load_dotenv()` before importing it.
2153
+
2154
+ The Go and Node SDKs also read `REVENIUM_ORGANIZATION_ID`, `REVENIUM_ORGANIZATION_NAME` and `REVENIUM_PRINT_SUMMARY`; the Python SDK does not.
2155
+
2156
+ ### Example
2157
+
2158
+ ```python
2159
+ import os
2160
+ os.environ["REVENIUM_CAPTURE_PROMPTS"] = "true"
2161
+
2162
+ import revenium_middleware.openai
2163
+ from openai import OpenAI
2164
+
2165
+ client = OpenAI()
2166
+ response = client.chat.completions.create(
2167
+ model="gpt-4o-mini",
2168
+ messages=[
2169
+ {"role": "system", "content": "You are a helpful assistant."},
2170
+ {"role": "user", "content": "What is the capital of France?"}
2171
+ ],
2172
+ usage_metadata={"organizationName": "DemoOrg"}
2173
+ )
2174
+ # System prompt, input messages, and output response are now captured
2175
+ ```
2176
+
2177
+ Prompt capture works with both streaming and non-streaming requests, and with multimodal content (text, images, etc.).
2178
+
2179
+ 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).
2180
+
2181
+ 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`.
2182
+
2183
+ ### Security Considerations
2184
+
2185
+ - Prompts may contain sensitive user data
2186
+ - Responses may include confidential information
2187
+ - Only enable in environments where data capture is appropriate
2188
+ - Ensure compliance with your data privacy policies
2189
+ - Use selective metering with `@revenium_meter` to control which calls are captured
2190
+
2191
+ ---
2192
+
2193
+ ## Cost Controls / Enforcement
2194
+
2195
+ Block outbound provider requests client-side when a Revenium cost control trips. When the circuit breaker is enabled, the middleware polls compiled enforcement rules from the Revenium API in a background daemon thread and raises `BudgetExceededError` **before** the upstream call, preventing spend beyond the configured limit.
2196
+
2197
+ > **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.
2198
+
2199
+ 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.
2200
+
2201
+ ### Enable
2202
+
2203
+ ```bash
2204
+ pip install 'revenium-python-sdk[openai]'
2205
+ ```
2206
+
2207
+ ```env
2208
+ REVENIUM_CIRCUIT_BREAKER_ENABLED=true
2209
+ REVENIUM_METERING_API_KEY=hak_your_key_here
2210
+ REVENIUM_TEAM_ID=your_hashed_team_id
2211
+ REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream # optional
2212
+ ```
2213
+
2214
+ ### Environment Variables
2215
+
2216
+ | Variable | Default | Description |
2217
+ |----------|---------|-------------|
2218
+ | `REVENIUM_CIRCUIT_BREAKER_ENABLED` | `false` | Master switch. `true` / `1` / `yes` / `on` to enable. |
2219
+ | `REVENIUM_BYPASS` | `false` | When `true`, every `check_enforcement` call short-circuits to a no-op. Useful for incident response. |
2220
+ | `REVENIUM_TEAM_ID` | — | Hashed team ID. Path component on rule fetches; required when the breaker is enabled. |
2221
+ | `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. |
2222
+ | `REVENIUM_CB_POLL_INTERVAL_SECONDS` | `60` | Background poll interval for rule refreshes. |
2223
+ | `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `BudgetExceededError` until rules are loaded. |
2224
+ | `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`. |
2225
+
2226
+ 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.
2227
+
2228
+ ### Public API
2229
+
2230
+ Enforcement starts with the first call any provider middleware checks, for example:
2231
+
2232
+ ```python
2233
+ import revenium_middleware.openai # auto-instruments openai
2234
+ import openai
2235
+
2236
+ client = openai.OpenAI()
2237
+ ```
2238
+
2239
+ 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:
2240
+
2241
+ - OpenAI and Azure OpenAI: chat completions, responses, embeddings and audio.
2242
+ - 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.
2243
+ - Google: google-genai content, embeddings, Imagen and Veo, and Vertex AI generation, chat, embeddings and Imagen.
2244
+ - Ollama: chat, generate, embed and embeddings.
2245
+ - Perplexity: the native client and the OpenAI-compatible client.
2246
+ - fal: run, stream, submit and subscribe.
2247
+ - LiteLLM: client completions and embeddings, and the proxy guardrail.
2248
+ - 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.
2249
+
2250
+ 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.
2251
+
2252
+ When the circuit breaker is disabled, it is a no-op. When enabled:
2253
+
2254
+ 1. A daemon thread (`revenium-enforcement-poll`) starts on first use.
2255
+ 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.
2256
+ 3. Rules are cached in-process. The pre-call check only reads that cache: it never makes a network request and never sleeps, so it is safe on an event loop (LiteLLM proxy, `AsyncOpenAI`). When the cache is more than 120 s old the check wakes the poller to refresh it early and carries on with the rules it has. Only one refresh runs at a time per process.
2257
+ 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.
2258
+ 5. `204 No Content` is treated as "no rules configured" — the cache is cleared.
2259
+
2260
+ 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.
2261
+
2262
+ 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.
2263
+
2264
+ ### Exception Contract
2265
+
2266
+ ```python
2267
+ from revenium_middleware import BudgetExceededError
2268
+ ```
2269
+
2270
+ 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:
2271
+
2272
+ | Attribute | Type | Description |
2273
+ |-----------|------|-------------|
2274
+ | `message` | `str` | Human-readable reason, e.g. `"Request blocked by Revenium enforcement rule: monthly-gpt4-cap"` |
2275
+ | `rule_name` | `str \| None` | Server-side rule name |
2276
+ | `current_value` | `float \| None` | Current metric value at the time of the block |
2277
+ | `threshold` | `float \| None` | Configured limit |
2278
+ | `resets_at` | `str \| None` | ISO-8601 timestamp the rule next resets |
2279
+ | `rule_id` | `str \| int \| None` | Server-side rule identifier |
2280
+ | `deny_message` | `str \| None` | The message written for the rule, when it has one; also appended to `message` |
2281
+
2282
+ 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`.
2283
+
2284
+ `BudgetExceededError` does **not** inherit from `ReveniumMiddlewareError`, and no provider middleware swallows it, so it reaches your `except` block, with two exceptions.
2285
+
2286
+ 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).
2287
+
2288
+ `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:
2289
+
2290
+ ```python
2291
+ import litellm
2292
+ from revenium_middleware import BudgetExceededError
2293
+
2294
+ batch = [[{"role": "user", "content": "Summarize A"}], [{"role": "user", "content": "Summarize B"}]]
2295
+ results = litellm.batch_completion(model="gpt-4o-mini", messages=batch)
2296
+ refused = [r for r in results if isinstance(r, BudgetExceededError)]
2297
+ ```
2298
+
2299
+ `litellm.batch_completion_models_all_responses` leaves a refused model out of its result list without raising.
2300
+
2301
+ ```python
2302
+ from revenium_middleware import BudgetExceededError
2303
+ import openai
2304
+
2305
+ client = openai.OpenAI()
2306
+
2307
+ try:
2308
+ response = client.chat.completions.create(
2309
+ model="gpt-4o-mini",
2310
+ messages=[{"role": "user", "content": "Summarize the meeting notes"}],
2311
+ )
2312
+ except BudgetExceededError as exc:
2313
+ print(f"Cost limit reached: {exc.message}")
2314
+ print(f"Rule {exc.rule_name}: {exc.current_value} / {exc.threshold}; resets {exc.resets_at}")
2315
+ ```
2316
+
2317
+ ### Fail-Open vs Fail-Closed
2318
+
2319
+ By default (`REVENIUM_CB_FAIL_MODE=open`) enforcement failures never propagate to user code and never delay it. If the rule fetch errors (network, 5xx, auth), the previous in-memory cache is preserved, a warning is logged, and the next attempt waits one poll interval. If there is no cache yet — the first moments after a process starts, or the whole of an outage that began before the first successful fetch — enforcement behaves as if no rules are configured and the request continues immediately; it does not wait for the fetch.
2320
+
2321
+ Set `REVENIUM_CB_FAIL_MODE=closed` to refuse calls until at least one rule fetch (or `REVENIUM_CACHE_DIR` snapshot) succeeds. The refusal is immediate too: a call made before the first fetch completes raises `BudgetExceededError` rather than waiting for it. Pair with `REVENIUM_CACHE_DIR` so a process restart loads the last-known rules rather than refusing every call until the first poll completes.
2322
+
2323
+ ### Shadow Mode
2324
+
2325
+ Rules with `shadowMode: true` are observe-and-log: they are skipped by `check_enforcement`. Use shadow mode on the server side to audit a rule before flipping it to enforce.
2326
+
2327
+ ### Inspecting a Rule and Its Roster
2328
+
2329
+ Two read-only calls answer "why was this caller blocked, and who else does this rule cover?" without going anywhere near the pre-call path. Both talk to the server directly, neither is cached, and neither reads or writes the cache `check_enforcement` evaluates — so what they report is what the server holds right now.
2330
+
2331
+ ```python
2332
+ from revenium_middleware._core import (
2333
+ fetch_enforcement_rule,
2334
+ fetch_enforcement_rule_roster,
2335
+ )
2336
+
2337
+ rule = fetch_enforcement_rule("mN3xpQz") # one rule, or None
2338
+ roster = fetch_enforcement_rule_roster("mN3xpQz") # who it measures, or None
2339
+
2340
+ if roster:
2341
+ print(f"{roster['blockedCount']} over the cap, {roster['warnedCount']} warned")
2342
+ for row in roster["rows"]:
2343
+ print(f"{row['label']}: ${row['spend']} / ${row['limit']} ({row['band']})")
2344
+ ```
2345
+
2346
+ `fetch_enforcement_rule_roster` takes `page`, `size`, `search` and `band` (`BLOCKED`, `WARNED`, `UNDER`, `ALL`); the server does the filtering, sorting, banding and paging, and the three band counts always describe the whole roster rather than the page you asked for. Both calls return `None` rather than raising when the team has no such compiled rule, the rule has no reading yet, or the enforcement API cannot be reached — the same fail-open posture as the rest of the circuit breaker. An empty `rule_id` raises `ValueError`.
2347
+
2348
+ The background poller is unaffected: it keeps reading the **whole team's** rules every `REVENIUM_CB_POLL_INTERVAL_SECONDS`. That is deliberate. The server computes the department-budget maps team-wide and attaches them to the team-wide read, so a poll narrowed to a single rule would stop receiving them and department budgets would quietly stop blocking anyone. Narrowing is an explicit, opt-in inspection call and never the refresh.
2349
+
2350
+ ### End-to-End Example
2351
+
2352
+ See [`examples/openai/openai_blocking_demo.py`](examples/openai/openai_blocking_demo.py) for a runnable end-to-end demo using a seeded budget rule.
2353
+
2354
+ ---
2355
+
2356
+ ## Configuration Reference
2357
+
2358
+ ### Required Environment Variables
2359
+
2360
+ | Variable | Description |
2361
+ |----------|-------------|
2362
+ | `REVENIUM_METERING_API_KEY` | Your Revenium API key (starts with `hak_` or `rev_`) |
2363
+
2364
+ ### Configuring After Import
2365
+
2366
+ The metering client is normally built from the environment when
2367
+ `revenium_middleware` is first imported. If your credentials only become
2368
+ available later (a secrets-vault bootstrap, framework settings hooks, import
2369
+ ordering), you don't need to restart: as soon as `REVENIUM_METERING_API_KEY`
2370
+ appears in the environment, the next metered call picks it up automatically.
2371
+ You can also configure programmatically at any time:
2372
+
2373
+ ```python
2374
+ import revenium_middleware
2375
+
2376
+ revenium_middleware.initialize_metering(
2377
+ api_key="hak_your_key", # defaults to REVENIUM_METERING_API_KEY
2378
+ base_url="https://api.revenium.ai", # defaults to REVENIUM_METERING_BASE_URL
2379
+ )
2380
+ ```
2381
+
2382
+ `initialize_metering()` returns `True` when metering is enabled after the
2383
+ call; invoke it with no arguments to re-read the environment.
2384
+
2385
+ #### Metering Several Customers in One Process
2386
+
2387
+ `initialize_metering()` sets one key for the whole process. The record of a non-streamed
2388
+ OpenAI (chat, Responses or embeddings), Anthropic `messages.create` (including
2389
+ Claude on Bedrock through the Anthropic client), LiteLLM, Ollama or Perplexity
2390
+ call is filed under the key that is current when the call returns. The
2391
+ exceptions are an Anthropic `with_streaming_response` call and a Perplexity
2392
+ response read raw or lazily, which keep the key from when they started. Every
2393
+ other record, including streamed calls, `@meter_tool` tool events, and Google
2394
+ Gemini, Vertex AI, OpenAI audio, fal.ai and raw boto3 Bedrock calls, keeps the
2395
+ key that was current when it started; one started while metering was off is not
2396
+ recorded. A call that fails with a provider error is also filed under the key
2397
+ from when it started. A call made through LangChain, CrewAI or Griptape follows
2398
+ the rule of the provider client it uses, except that a LangChain call recorded
2399
+ by the Revenium callback rather than by a provider client, such as
2400
+ `wrap(ChatOllama(...))` without the Ollama middleware, keeps the key from when the
2401
+ run started. So switching keys with
2402
+ `initialize_metering()` while another thread or asyncio task still has a call
2403
+ or a metered tool running can send that record under the new key.
2404
+
2405
+ To meter several of your own customers at once, give each thread or asyncio
2406
+ task its own key with `metering_key()`:
2407
+
2408
+ ```python
2409
+ import revenium_middleware
2410
+
2411
+ with revenium_middleware.metering_key("hak_customer_key"):
2412
+ client.chat.completions.create(...)
2413
+ ```
2414
+
2415
+ The key applies to the usage records and tool events of calls made inside the
2416
+ block, on that thread or asyncio task only: a thread started inside the block
2417
+ does not inherit it, while an asyncio task created inside it does. Wrap the
2418
+ thread's target with `carry_context` to carry the key.
2419
+ `base_url` is optional and defaults to the address set with
2420
+ `initialize_metering()` or `REVENIUM_METERING_BASE_URL`. An empty or malformed
2421
+ key raises `ValueError`.
2422
+
2423
+ - 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.
2424
+ - Spending caps follow the process-wide key (the environment or
2425
+ `initialize_metering()`) and `REVENIUM_TEAM_ID`, never the key of a
2426
+ `metering_key()` block. A service that sets keys only with `metering_key()`
2427
+ has no process-wide key, so it gets no spending caps, and with
2428
+ `REVENIUM_CB_FAIL_MODE=closed` every call is refused.
2429
+ - Outcomes and jobs are not covered: they need a write key (`rev_sk_`).
2430
+ - Delivery pauses for the whole process while Revenium is not answering at
2431
+ any one address (see [Metering Delivery and Timeouts](#metering-delivery-and-timeouts));
2432
+ the records held back meanwhile are replayed later under their own key.
2433
+
2434
+ ### Metering Delivery and Timeouts
2435
+
2436
+ Usage records are never sent on your request path. A metered call puts its
2437
+ record on a bounded in-process queue and returns at once; a fixed pool of
2438
+ background threads sends queued records to Revenium. The number of threads
2439
+ does not grow with traffic, so a slow or unreachable metering endpoint costs
2440
+ a few idle threads and the queue's memory, never a thread per call.
2441
+
2442
+ | Variable | Default | What it sets |
2443
+ |----------|---------|--------------|
2444
+ | `REVENIUM_METERING_WORKERS` | `32` | Background threads that send records |
2445
+ | `REVENIUM_METERING_QUEUE_SIZE` | `1000` | Records that can wait for a thread |
2446
+ | `REVENIUM_METERING_TIMEOUT_SECONDS` | `10` | Seconds one attempt waits for a response |
2447
+ | `REVENIUM_METERING_CONNECT_TIMEOUT_SECONDS` | `5` | Seconds one attempt waits for a connection |
2448
+ | `REVENIUM_METERING_MAX_RETRIES` | `2` | Retries after the first attempt |
2449
+
2450
+ The two timeouts also apply to tool events, including those sent with
2451
+ `emit_tool_event`, which are sent once without retries, and a replay from the store-and-forward buffer is a single attempt
2452
+ that waits at most `REVENIUM_METERING_TIMEOUT_SECONDS`.
2453
+
2454
+ Each thread sends one record at a time, so the threads keep up with about one
2455
+ record per thread per round trip to Revenium. The 32 default threads send
2456
+ about 100 records a second at a 300 ms round trip and keep up with 30 a
2457
+ second until a round trip takes about a second. Measured against a local
2458
+ endpoint answering in 250 ms and 300 ms, 30 calls a second for five minutes
2459
+ delivered every record within 0.35 seconds of the call, and so did 60
2460
+ records a second at 250 ms (a service that sends two records per call).
2461
+ From one client in Brazil to a US East Revenium API host, a request on an
2462
+ open connection took 113 ms (p50) and 123 ms (p99), and one that also opened
2463
+ the connection 333 ms and 462 ms;
2464
+ measure from your own region before sizing for a slower path. Idle, the 32
2465
+ threads cost about 1.4 MB of memory. Raise `REVENIUM_METERING_WORKERS` for a
2466
+ service that meters more than 30 records a second against a slow round trip;
2467
+ the queue absorbs short bursts. When the queue is full, new records go
2468
+ straight to the store-and-forward buffer below instead of waiting, and
2469
+ `get_buffer_stats()["total_overflowed"]` counts them; one warning marks the
2470
+ start of each such episode and one, with a count, its end.
2471
+
2472
+ When Revenium stops answering, the threads stop waiting on it. After three
2473
+ records in a row fail with a retryable error, new records go straight to the
2474
+ store-and-forward buffer without being sent, and one record every 5 seconds
2475
+ is still sent to find out whether Revenium is back. The first one that
2476
+ succeeds resumes sending and starts replaying the buffer at once. A warning
2477
+ marks each change. Tool events from `@meter_tool` and `report_tool_call` are
2478
+ not held back: `configure()` can send them to another endpoint, so they keep
2479
+ being sent, and the buffer replays them even while the AI records ahead of
2480
+ them are still failing.
2481
+
2482
+ At exit, queued records get the first share of the shutdown budget (see
2483
+ [Shutdown](#shutdown)).
2484
+
2485
+ ### Delivery Resilience (Store-and-Forward)
2486
+
2487
+ Metering events that still fail after the client's own retries (network
2488
+ outages, 5xx, rate limiting), and the records held back while Revenium is not
2489
+ answering, are not lost: they are held in a bounded in-memory buffer and
2490
+ replayed automatically in the background every 30 seconds, or as soon as a
2491
+ delivery succeeds again, reusing each event's original `Idempotency-Key` so
2492
+ replays can never double-bill. A backlog replays 16 records at a time, about
2493
+ 50 a second at a 300 ms round trip next to your live traffic. Permanent
2494
+ failures (401/403/404/422) are never buffered, and buffered events expire
2495
+ after 24 hours. The buffer is drained on shutdown (see below).
2496
+
2497
+ The buffer holds up to 20,000 events, eleven minutes of an outage at 30
2498
+ records a second. A typical LiteLLM record takes about 2.3 KB in memory, so a
2499
+ full buffer holds about 45 MB; with `REVENIUM_CAPTURE_PROMPTS` each record
2500
+ can also carry up to 50,000 characters per captured prompt field, so lower
2501
+ `REVENIUM_BUFFER_MAX_SIZE` if you capture prompts. In a five-minute outage at
2502
+ 30 calls a second against the defaults, all 9,000 records were held and then
2503
+ delivered within two and a half minutes of Revenium answering again, while
2504
+ new traffic kept flowing. When the buffer is full the oldest
2505
+ events are evicted and their usage is lost: one warning marks the first
2506
+ eviction, the flush thread logs how many were evicted at most once per flush
2507
+ interval, and `get_metering_status().evicted_count` and
2508
+ `get_buffer_stats()["total_evicted"]` count them. Inspect it programmatically:
2509
+
2510
+ ```python
2511
+ from revenium_middleware import get_buffer_stats
2512
+
2513
+ print(get_buffer_stats())
2514
+ # {'size': 0, 'max_size': 20000, 'total_buffered': 3, 'total_replayed': 3, 'total_evicted': 0, ...}
2515
+ ```
2516
+
2517
+ ### Shutdown
2518
+
2519
+ The SDK does not install signal handlers: SIGTERM and SIGINT reach your
2520
+ application or server exactly as they would without it. When the interpreter
2521
+ exits normally, including after Ctrl+C, an `atexit` hook works through three
2522
+ steps against one budget of `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` (5 seconds by
2523
+ default), each using whatever time the previous ones left: it waits for the
2524
+ background threads to send the records still queued, builds the records that
2525
+ overflowed to the store-and-forward buffer, then flushes the buffer, oldest
2526
+ first, up to 32 records at a time, one attempt per record. Once a usage record or a tool event fails
2527
+ in a way worth retrying (unreachable, timed out, 429 or 5xx), the flush sends
2528
+ no more records of that kind, leaving them unsent, and keeps sending the other
2529
+ kind, since tool events can go to a different endpoint. Records still queued, being sent, unbuilt
2530
+ or unsent at the end are dropped and logged once, as a warning with a count.
2531
+
2532
+ A process ended by SIGTERM's default action skips `atexit`, and with it that
2533
+ final flush. uvicorn, and so the LiteLLM proxy, ends that way once its own
2534
+ graceful shutdown has finished. For a script or worker with no SIGTERM handling
2535
+ of its own, set `REVENIUM_INSTALL_SIGNAL_HANDLERS=1`: SIGTERM then flushes
2536
+ first and ends the process the same way. A SIGTERM handler your code installed
2537
+ before importing the SDK is called unchanged, and one installed afterwards
2538
+ replaces the SDK's. The flush then happens only if that handler exits
2539
+ normally: a handler that restores SIGTERM's default action and re-raises it,
2540
+ as uvicorn does after its own shutdown, ends the process before `atexit` runs.
2541
+
2542
+ #### Worker processes
2543
+
2544
+ A `multiprocessing` child started with the fork or forkserver start method
2545
+ (the Linux default) ends through `os._exit`, which skips `atexit`. The SDK
2546
+ therefore also flushes a `multiprocessing.Process` child when its target
2547
+ returns, with the same budget and the same warning. Both start methods fork
2548
+ the child from a process that has imported the SDK, and a forked child starts
2549
+ with its own metering queue, buffer and connections: it never sends records
2550
+ its parent queued, and its warning counts only its own records.
2551
+
2552
+ Some worker shapes still need a call from you, or are not covered:
2553
+
2554
+ - `multiprocessing.Pool` workers flush when the worker process exits (after
2555
+ `pool.close(); pool.join()`, or at `maxtasksperchild`), not after each task.
2556
+ Leaving a `with Pool() as pool:` block calls `terminate()`, which kills the
2557
+ workers and can still lose their last records.
2558
+ - A raw `os.fork()` worker, or an RQ work horse, that ends with `os._exit`
2559
+ must call `flush_metering()` at the end of each job.
2560
+ - Celery's prefork pool (billiard) is not covered; call `flush_metering()` at
2561
+ the end of a task if its worker processes end that way.
2562
+ - Under fork and forkserver, records made by threads still running after the
2563
+ target returns are not delivered.
2564
+
2565
+ ```python
2566
+ import revenium_middleware
2567
+
2568
+ def job():
2569
+ ... # model calls
2570
+ left = revenium_middleware.flush_metering() # waits up to REVENIUM_SHUTDOWN_TIMEOUT_SECONDS
2571
+ # left == 0: every record was sent; otherwise that many are still unsent
2572
+ ```
2573
+
2574
+ `flush_metering(timeout_seconds=None)` sends the records queued or held so
2575
+ far and returns how many are still unsent. Metering carries on afterwards, so
2576
+ a long-lived worker can call it after every job. A negative or non-finite
2577
+ timeout raises `ValueError`.
2578
+
2579
+ ### Optional Environment Variables
2580
+
2581
+ | Variable | Default | Description |
2582
+ |----------|---------|-------------|
2583
+ | `REVENIUM_METERING_BASE_URL` | `https://api.revenium.ai` | Revenium API endpoint |
2584
+ | `REVENIUM_LOG_LEVEL` | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
2585
+ | `REVENIUM_CAPTURE_PROMPTS` | `false` | Enable prompt capture |
2586
+ | `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 |
2587
+ | `REVENIUM_SELECTIVE_METERING` | `false` | Only meter `@revenium_meter` decorated functions |
2588
+ | `REVENIUM_TEAM_ID` | - | Team ID for cost lookups and outcome reporting (JobContext team resolution) |
2589
+ | `REVENIUM_ENVIRONMENT` | - | Deployment environment (auto-detects from `ENVIRONMENT`, `DEPLOYMENT_ENV`) |
2590
+ | `REVENIUM_REGION` | - | Cloud region (auto-detects from `AWS_REGION`, `AZURE_REGION`, `GCP_REGION`) |
2591
+ | `REVENIUM_CREDENTIAL_ALIAS` | - | Provider API key name, recorded as the subscriber's credential name on calls with no subscriber id or email |
2592
+ | `REVENIUM_TRACE_TYPE` | - | Workflow category identifier |
2593
+ | `REVENIUM_TRACE_NAME` | - | Human-readable trace label |
2594
+ | `REVENIUM_PARENT_TRANSACTION_ID` | - | Parent transaction ID for distributed tracing |
2595
+ | `REVENIUM_TRANSACTION_NAME` | - | Human-friendly operation name |
2596
+ | `REVENIUM_RETRY_NUMBER` | - | Retry attempt number |
2597
+ | `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`) |
2598
+ | `REVENIUM_AGENTIC_JOB_NAME` | - | Human-readable agentic job name |
2599
+ | `REVENIUM_AGENTIC_JOB_TYPE` | - | Agentic job type category |
2600
+ | `REVENIUM_AGENTIC_JOB_VERSION` | - | Agentic job version |
2601
+ | `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` |
2602
+ | `REVENIUM_OUTCOME_API_KEY` | - | Deprecated fallback name for the write-scope key; used only when `REVENIUM_WRITE_API_KEY` is unset |
2603
+ | `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`. |
2604
+ | `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 |
2605
+ | `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 |
2606
+ | `REVENIUM_BUFFER_MAX_SIZE` | `20000` | Store-and-forward buffer capacity (oldest events evicted when full) |
2607
+ | `REVENIUM_BUFFER_FLUSH_INTERVAL` | `30` | Seconds between automatic replay attempts for buffered events |
2608
+ | `REVENIUM_METERING_WORKERS` | `32` | Background threads that send usage records (see [Metering Delivery and Timeouts](#metering-delivery-and-timeouts)) |
2609
+ | `REVENIUM_METERING_QUEUE_SIZE` | `1000` | Usage records that can wait for a sending thread; overflow goes to the store-and-forward buffer |
2610
+ | `REVENIUM_METERING_TIMEOUT_SECONDS` | `10` | Seconds one attempt to send a usage record waits for a response |
2611
+ | `REVENIUM_METERING_CONNECT_TIMEOUT_SECONDS` | `5` | Seconds one attempt waits for a connection |
2612
+ | `REVENIUM_METERING_MAX_RETRIES` | `2` | Retries after the first attempt before a record moves to the buffer |
2613
+ | `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` | `5` | Total seconds the exit hook may spend sending queued usage records, building overflowed ones and flushing the buffer |
2614
+ | `REVENIUM_INSTALL_SIGNAL_HANDLERS` | `false` | Set to `1` to flush metering before SIGTERM's default action ends the process (see [Shutdown](#shutdown)) |
2615
+
2616
+ 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.
2617
+
2618
+ 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.
2619
+
2620
+ ### Provider-Specific Environment Variables
2621
+
2622
+ | Variable | Provider | Description |
2623
+ |----------|----------|-------------|
2624
+ | `OPENAI_API_KEY` | OpenAI | OpenAI API key |
2625
+ | `AZURE_OPENAI_ENDPOINT` | Azure OpenAI | Azure endpoint URL |
2626
+ | `AZURE_OPENAI_API_KEY` | Azure OpenAI | Azure API key |
2627
+ | `AZURE_OPENAI_DEPLOYMENT` | Azure OpenAI | Default deployment name |
2628
+ | `ANTHROPIC_API_KEY` | Anthropic | Anthropic API key |
2629
+ | `AWS_REGION` | Bedrock | AWS region for Bedrock (default: `us-east-1`) |
2630
+ | `GOOGLE_API_KEY` | Google AI | Google AI SDK API key |
2631
+ | `GOOGLE_CLOUD_PROJECT` | Vertex AI | GCP project ID |
2632
+ | `GOOGLE_CLOUD_LOCATION` | Vertex AI | GCP location (default: `us-central1`) |
2633
+ | `PERPLEXITY_API_KEY` | Perplexity | Perplexity API key |
2634
+ | `FAL_KEY` | fal.ai | fal.ai API key |
2635
+ | `LITELLM_PROXY_URL` | LiteLLM | LiteLLM proxy URL |
2636
+ | `LITELLM_API_KEY` | LiteLLM | LiteLLM proxy API key |
2637
+
2638
+ ---
2639
+
2640
+ ## Troubleshooting
2641
+
2642
+ | Issue | Solution |
2643
+ |-------|----------|
2644
+ | **Middleware not working** | Verify `REVENIUM_METERING_API_KEY` is set correctly (must start with `hak_` or `rev_`) |
2645
+ | **No data in dashboard** | Enable debug logging with `REVENIUM_LOG_LEVEL=DEBUG` |
2646
+ | **Import errors** | Ensure the correct extra is installed (e.g., `pip install revenium-python-sdk[openai]`) |
2647
+ | **Azure: wrong model name** | Middleware auto-resolves deployment names; check with debug logging |
2648
+ | **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` |
2649
+ | **Bedrock: requests go to Anthropic** | Verify AWS credentials: `aws sts get-caller-identity` |
2650
+ | **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 |
2651
+ | **Google: "No module named 'vertexai'"** | Install correct extra: `pip install "revenium-python-sdk[google-vertex]"` |
2652
+ | **Vertex AI: authentication errors** | Run `gcloud auth application-default login` |
2653
+ | **Ollama: connection errors** | Ensure Ollama is running: `ollama serve` |
2654
+ | **LangChain: provider shows "unknown"** | Ensure you're using a supported LangChain LLM class |
2655
+ | **Streaming errors** | Check provider credentials; middleware auto-falls back gracefully |
2656
+
2657
+ **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.
2658
+
2659
+ **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.
2660
+
2661
+ **Check initialization status (Anthropic):** Use `revenium_middleware.anthropic.is_initialized()` to verify setup.
2662
+
2663
+ ---
2664
+
2665
+ ## Logging
2666
+
2667
+ This module uses Python's standard logging system. Control the log level with the `REVENIUM_LOG_LEVEL` environment variable:
2668
+
2669
+ ```bash
2670
+ # Enable debug logging
2671
+ export REVENIUM_LOG_LEVEL=DEBUG
2672
+
2673
+ # Or when running your script
2674
+ REVENIUM_LOG_LEVEL=DEBUG python your_script.py
2675
+ ```
2676
+
2677
+ Available log levels:
2678
+ - `DEBUG`: Detailed debugging information (provider detection, routing decisions, metering payloads)
2679
+ - `INFO`: General information (default)
2680
+ - `WARNING`: Warning messages only
2681
+ - `ERROR`: Error messages only
2682
+ - `CRITICAL`: Critical error messages only
2683
+
2684
+ `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.
2685
+
2686
+ ## Compatibility
2687
+
2688
+ - Python 3.8+
2689
+ - Works with all supported AI provider SDKs (latest versions recommended)
2690
+ - Thread-safe and production-ready for concurrent applications
2691
+
2692
+ ## Documentation
2693
+
2694
+ For detailed documentation, visit [docs.revenium.io](https://docs.revenium.io)
2695
+
2696
+ ### Server-Side Cost Controls
2697
+
2698
+ Cost controls (spend limits, throttling, alerts) are managed server-side in Revenium, not in this SDK. The SDK reports usage; Revenium evaluates it against your configured cost controls.
2699
+
2700
+ The cost-controls API endpoint is `/v2/api/ai/cost-controls`. This Python SDK does not call the endpoint directly — no SDK changes are required to use cost controls. If you manage cost controls via the Revenium API, HTTP client, or `curl`, see [docs.revenium.io](https://docs.revenium.io) for the current API reference.
2701
+
2702
+ ## Contributing
2703
+
2704
+ See [CONTRIBUTING.md](./CONTRIBUTING.md)
2705
+
2706
+ ## Code of Conduct
2707
+
2708
+ See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
2709
+
2710
+ ## Security
2711
+
2712
+ See [SECURITY.md](./SECURITY.md)
2713
+
2714
+ ## License
2715
+
2716
+ This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
2717
+
2718
+ ## Support
2719
+
2720
+ For issues, feature requests, or contributions:
2721
+
2722
+ - **Website**: [www.revenium.ai](https://www.revenium.ai)
2723
+ - **GitHub Repository**: [revenium/revenium-python-sdk](https://github.com/revenium/revenium-python-sdk)
2724
+ - **Issues**: [Report bugs or request features](https://github.com/revenium/revenium-python-sdk/issues)
2725
+ - **Documentation**: [docs.revenium.io](https://docs.revenium.io)
2726
+ - **Email**: support@revenium.io
2727
+
2728
+ ---
2729
+
2730
+ **Built by Revenium**