revenium-python-sdk 0.9.2__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 (216) hide show
  1. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/PKG-INFO +597 -92
  2. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/README.md +583 -90
  3. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/pyproject.toml +23 -2
  4. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/__init__.py +46 -6
  5. {revenium_python_sdk-0.9.2 → 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.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/call_ownership.py +172 -16
  9. revenium_python_sdk-0.10.0/revenium_middleware/_core/closable_scope.py +39 -0
  10. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/config.py +208 -48
  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.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/delivery_circuit.py +10 -0
  14. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/enforcement.py +871 -101
  15. revenium_python_sdk-0.10.0/revenium_middleware/_core/error_text.py +87 -0
  16. {revenium_python_sdk-0.9.2 → 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.2 → 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.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/metering_buffer.py +268 -74
  24. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/metering_pool.py +45 -0
  25. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/metering_status.py +11 -0
  26. revenium_python_sdk-0.10.0/revenium_middleware/_core/metering_submission.py +215 -0
  27. {revenium_python_sdk-0.9.2 → 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/sse_body_tap.py +264 -0
  38. revenium_python_sdk-0.10.0/revenium_middleware/_core/subscriber.py +117 -0
  39. revenium_python_sdk-0.10.0/revenium_middleware/_core/tool_event_transport.py +69 -0
  40. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/trace_fields.py +102 -55
  41. revenium_python_sdk-0.10.0/revenium_middleware/_core/usage_iterations.py +184 -0
  42. revenium_python_sdk-0.10.0/revenium_middleware/_core/vendor_model_aliases.py +69 -0
  43. revenium_python_sdk-0.10.0/revenium_middleware/_core/wire_guards.py +199 -0
  44. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_base_client.py +8 -3
  45. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_client.py +35 -82
  46. revenium_python_sdk-0.10.0/revenium_middleware/_metering/decorator.py +779 -0
  47. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/resources/ai.py +45 -24
  48. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/ai_create_audio_params.py +1 -3
  49. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/ai_create_completion_params.py +8 -3
  50. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/ai_create_image_params.py +1 -3
  51. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/ai_create_video_params.py +1 -3
  52. revenium_python_sdk-0.10.0/revenium_middleware/agentic_outcomes.py +565 -0
  53. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/__init__.py +10 -9
  54. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/bedrock_adapter.py +53 -19
  55. revenium_python_sdk-0.10.0/revenium_middleware/anthropic/bedrock_model_names.py +66 -0
  56. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/bedrock_transport.py +260 -52
  57. revenium_python_sdk-0.10.0/revenium_middleware/anthropic/inference_profiles.py +453 -0
  58. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/middleware.py +658 -422
  59. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/prompt_extractor.py +81 -57
  60. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/provider.py +1 -1
  61. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/raw_response.py +73 -7
  62. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/stream_create.py +95 -10
  63. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/fal/__init__.py +2 -2
  64. revenium_python_sdk-0.10.0/revenium_middleware/fal/_call.py +97 -0
  65. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/fal/_metering.py +105 -17
  66. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/fal/_queue.py +25 -3
  67. revenium_python_sdk-0.10.0/revenium_middleware/fal/middleware.py +338 -0
  68. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/fal/trace_fields.py +42 -108
  69. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/__init__.py +2 -29
  70. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/__init__.py +14 -0
  71. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/types.py +6 -0
  72. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/utils.py +252 -36
  73. revenium_python_sdk-0.10.0/revenium_middleware/google/config.py +41 -0
  74. revenium_python_sdk-0.10.0/revenium_middleware/google/google_ai/middleware.py +1304 -0
  75. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/prompt_extractor.py +5 -69
  76. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/vertex_ai/middleware.py +363 -162
  77. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/__init__.py +4 -0
  78. revenium_python_sdk-0.10.0/revenium_middleware/griptape/_retry.py +12 -0
  79. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/anthropic_driver.py +2 -0
  80. revenium_python_sdk-0.10.0/revenium_middleware/griptape/budget_errors.py +150 -0
  81. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/litellm_driver.py +150 -43
  82. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/ollama_driver.py +2 -0
  83. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/openai_driver.py +18 -1
  84. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/openai_embedding_driver.py +2 -0
  85. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/universal_driver.py +63 -47
  86. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/job_context.py +81 -37
  87. revenium_python_sdk-0.10.0/revenium_middleware/job_history.py +392 -0
  88. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/job_type_economics.py +2 -5
  89. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/decorators.py +180 -303
  90. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/integrations/__init__.py +2 -2
  91. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/integrations/crewai.py +173 -74
  92. revenium_python_sdk-0.10.0/revenium_middleware/litellm/client/middleware.py +1038 -0
  93. revenium_python_sdk-0.10.0/revenium_middleware/litellm/proxy/_metering_owner.py +131 -0
  94. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/proxy/guardrail.py +355 -97
  95. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/proxy/middleware.py +186 -76
  96. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/ollama/middleware.py +127 -45
  97. revenium_python_sdk-0.10.0/revenium_middleware/openai/audio.py +463 -0
  98. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/azure_model_resolver.py +56 -3
  99. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/langchain/__init__.py +48 -4
  100. revenium_python_sdk-0.10.0/revenium_middleware/openai/langchain/_abandoned_runs.py +109 -0
  101. revenium_python_sdk-0.10.0/revenium_middleware/openai/langchain/_model_call.py +385 -0
  102. revenium_python_sdk-0.10.0/revenium_middleware/openai/langchain/_perplexity_cost_capture.py +103 -0
  103. revenium_python_sdk-0.10.0/revenium_middleware/openai/langchain/_prompt_capture.py +75 -0
  104. revenium_python_sdk-0.10.0/revenium_middleware/openai/langchain/_text_completion_usage.py +218 -0
  105. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/langchain/_utils.py +2 -1
  106. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/langchain/unified_handler.py +421 -100
  107. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/middleware.py +1154 -387
  108. revenium_python_sdk-0.10.0/revenium_middleware/openai/prompt_extractor.py +13 -0
  109. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/provider.py +33 -3
  110. revenium_python_sdk-0.10.0/revenium_middleware/openai/raw_response.py +52 -0
  111. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/trace_fields.py +2 -2
  112. revenium_python_sdk-0.10.0/revenium_middleware/openai/xai_usage.py +29 -0
  113. revenium_python_sdk-0.10.0/revenium_middleware/perplexity/_metering_scope.py +9 -0
  114. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/perplexity/middleware.py +228 -47
  115. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/perplexity/patching.py +12 -9
  116. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/perplexity/perplexity_sdk.py +134 -33
  117. revenium_python_sdk-0.10.0/revenium_middleware/perplexity/raw_response.py +141 -0
  118. revenium_python_sdk-0.10.0/revenium_middleware/perplexity/streaming.py +253 -0
  119. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/webhooks/_verify.py +1 -1
  120. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_python_sdk.egg-info/PKG-INFO +597 -92
  121. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_python_sdk.egg-info/SOURCES.txt +30 -0
  122. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_python_sdk.egg-info/requires.txt +16 -1
  123. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/tests/test_patch_coverage.py +18 -2
  124. revenium_python_sdk-0.9.2/revenium_middleware/_core/cache_tokens.py +0 -172
  125. revenium_python_sdk-0.9.2/revenium_middleware/_core/context.py +0 -257
  126. revenium_python_sdk-0.9.2/revenium_middleware/_core/decorators.py +0 -202
  127. revenium_python_sdk-0.9.2/revenium_middleware/_core/log_sanitize.py +0 -100
  128. revenium_python_sdk-0.9.2/revenium_middleware/_core/metering.py +0 -370
  129. revenium_python_sdk-0.9.2/revenium_middleware/_core/metering_submission.py +0 -117
  130. revenium_python_sdk-0.9.2/revenium_middleware/_core/patch_registry.py +0 -26
  131. revenium_python_sdk-0.9.2/revenium_middleware/_core/prompt_extraction.py +0 -55
  132. revenium_python_sdk-0.9.2/revenium_middleware/_core/subscriber.py +0 -51
  133. revenium_python_sdk-0.9.2/revenium_middleware/_metering/decorator.py +0 -524
  134. revenium_python_sdk-0.9.2/revenium_middleware/agentic_outcomes.py +0 -424
  135. revenium_python_sdk-0.9.2/revenium_middleware/fal/_call.py +0 -62
  136. revenium_python_sdk-0.9.2/revenium_middleware/fal/middleware.py +0 -169
  137. revenium_python_sdk-0.9.2/revenium_middleware/google/config.py +0 -63
  138. revenium_python_sdk-0.9.2/revenium_middleware/google/google_ai/middleware.py +0 -659
  139. revenium_python_sdk-0.9.2/revenium_middleware/job_history.py +0 -130
  140. revenium_python_sdk-0.9.2/revenium_middleware/litellm/client/middleware.py +0 -565
  141. revenium_python_sdk-0.9.2/revenium_middleware/litellm/proxy/_metering_owner.py +0 -74
  142. revenium_python_sdk-0.9.2/revenium_middleware/openai/langchain/_model_call.py +0 -109
  143. revenium_python_sdk-0.9.2/revenium_middleware/openai/prompt_extractor.py +0 -173
  144. revenium_python_sdk-0.9.2/revenium_middleware/perplexity/_metering_scope.py +0 -7
  145. revenium_python_sdk-0.9.2/revenium_middleware/perplexity/streaming.py +0 -138
  146. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/LICENSE +0 -0
  147. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/load_diagnostics.py +0 -0
  148. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_core/shutdown_signals.py +0 -0
  149. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/LICENSE +0 -0
  150. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/__init__.py +0 -0
  151. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_compat.py +0 -0
  152. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_constants.py +0 -0
  153. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_exceptions.py +0 -0
  154. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_files.py +0 -0
  155. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_models.py +0 -0
  156. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_qs.py +0 -0
  157. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_resource.py +0 -0
  158. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_response.py +0 -0
  159. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_streaming.py +0 -0
  160. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_types.py +0 -0
  161. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/__init__.py +0 -0
  162. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_logs.py +0 -0
  163. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_proxy.py +0 -0
  164. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_reflection.py +0 -0
  165. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_resources_proxy.py +0 -0
  166. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_streams.py +0 -0
  167. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_sync.py +0 -0
  168. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_transform.py +0 -0
  169. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_typing.py +0 -0
  170. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_utils/_utils.py +0 -0
  171. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/_version.py +0 -0
  172. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/context.py +0 -0
  173. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/py.typed +0 -0
  174. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/resources/__init__.py +0 -0
  175. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/resources/apis.py +0 -0
  176. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/resources/events.py +0 -0
  177. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/__init__.py +0 -0
  178. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/api_meter_request_params.py +0 -0
  179. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/api_meter_response_params.py +0 -0
  180. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/event_create_params.py +0 -0
  181. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/_metering/types/metering_response_resource.py +0 -0
  182. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/config.py +0 -0
  183. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/anthropic/trace_fields.py +0 -0
  184. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/fal/config.py +0 -0
  185. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/exceptions.py +0 -0
  186. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/protocols.py +0 -0
  187. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/common/trace_fields.py +0 -0
  188. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/google_ai/__init__.py +0 -0
  189. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/google_ai/provider.py +0 -0
  190. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/vertex_ai/__init__.py +0 -0
  191. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/google/vertex_ai/provider.py +0 -0
  192. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/griptape/_metadata.py +0 -0
  193. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/__init__.py +0 -0
  194. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/__init__.py +0 -0
  195. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/config.py +0 -0
  196. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/context.py +0 -0
  197. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/hooks.py +0 -0
  198. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/trace_fields.py +0 -0
  199. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/client/validation.py +0 -0
  200. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/litellm/proxy/__init__.py +0 -0
  201. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/ollama/__init__.py +0 -0
  202. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/ollama/trace_fields.py +0 -0
  203. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/__init__.py +0 -0
  204. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/azure_config.py +0 -0
  205. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/config.py +0 -0
  206. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/openai/exceptions.py +0 -0
  207. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/perplexity/__init__.py +0 -0
  208. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/perplexity/provider.py +0 -0
  209. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/perplexity/trace_fields.py +0 -0
  210. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_middleware/webhooks/__init__.py +0 -0
  211. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_python_sdk.egg-info/dependency_links.txt +0 -0
  212. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/revenium_python_sdk.egg-info/top_level.txt +0 -0
  213. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/setup.cfg +0 -0
  214. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/tests/test_metering.py +0 -0
  215. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/tests/test_metering_dispatch_timestamps.py +0 -0
  216. {revenium_python_sdk-0.9.2 → revenium_python_sdk-0.10.0}/tests/test_release_verify_ticket.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: revenium-python-sdk
3
- Version: 0.9.2
3
+ Version: 0.10.0
4
4
  Summary: The official Revenium Python SDK — unified AI metering middleware for OpenAI, Anthropic, Google, Ollama, LiteLLM, Perplexity, and fal.ai.
5
5
  Author-email: Revenium <support@revenium.io>
6
6
  License: MIT
@@ -28,11 +28,13 @@ Requires-Dist: httpx<1,>=0.23.0
28
28
  Requires-Dist: pydantic<3,>=1.9.0
29
29
  Requires-Dist: sniffio
30
30
  Requires-Dist: typing-extensions<5,>=4.10
31
+ Requires-Dist: wrapt>=1.14.0
31
32
  Provides-Extra: openai
32
33
  Requires-Dist: wrapt>=1.14.0; extra == "openai"
33
34
  Requires-Dist: openai>=1.0.0; extra == "openai"
34
35
  Requires-Dist: python-dotenv>=0.19.0; extra == "openai"
35
36
  Provides-Extra: langchain
37
+ Requires-Dist: wrapt>=1.14.0; extra == "langchain"
36
38
  Requires-Dist: langchain>=0.1.16; extra == "langchain"
37
39
  Requires-Dist: langchain-openai>=0.1.0; extra == "langchain"
38
40
  Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
@@ -58,7 +60,7 @@ Requires-Dist: google-genai>=0.1.0; extra == "google-genai"
58
60
  Requires-Dist: python-dotenv; extra == "google-genai"
59
61
  Provides-Extra: google-vertex
60
62
  Requires-Dist: wrapt>=1.14.0; extra == "google-vertex"
61
- Requires-Dist: vertexai>=1.0.0; extra == "google-vertex"
63
+ Requires-Dist: google-cloud-aiplatform>=1.71.1; extra == "google-vertex"
62
64
  Requires-Dist: python-dotenv; extra == "google-vertex"
63
65
  Provides-Extra: anthropic
64
66
  Requires-Dist: wrapt>=1.14.0; extra == "anthropic"
@@ -67,6 +69,7 @@ Requires-Dist: python-dotenv>=0.19.0; extra == "anthropic"
67
69
  Provides-Extra: ollama
68
70
  Requires-Dist: wrapt>=1.14.0; extra == "ollama"
69
71
  Requires-Dist: ollama>=0.3.0; extra == "ollama"
72
+ Requires-Dist: python-dotenv>=0.19.0; extra == "ollama"
70
73
  Provides-Extra: fal
71
74
  Requires-Dist: wrapt>=1.14.0; extra == "fal"
72
75
  Requires-Dist: fal-client>=0.13.0; extra == "fal"
@@ -74,6 +77,7 @@ Requires-Dist: python-dotenv>=0.19.0; extra == "fal"
74
77
  Provides-Extra: litellm
75
78
  Requires-Dist: wrapt>=1.14.0; extra == "litellm"
76
79
  Requires-Dist: litellm>=1.40.0; extra == "litellm"
80
+ Requires-Dist: python-dotenv>=0.19.0; extra == "litellm"
77
81
  Provides-Extra: litellm-proxy
78
82
  Requires-Dist: wrapt>=1.14.0; extra == "litellm-proxy"
79
83
  Requires-Dist: litellm[proxy]>=1.93.0; extra == "litellm-proxy"
@@ -94,12 +98,20 @@ Requires-Dist: boto3; extra == "dev"
94
98
  Requires-Dist: ollama>=0.3.0; extra == "dev"
95
99
  Requires-Dist: griptape<2.0.0,>=1.0.0; python_version >= "3.10" and extra == "dev"
96
100
  Requires-Dist: langchain-anthropic; python_version >= "3.10" and extra == "dev"
101
+ Requires-Dist: langchain; python_version >= "3.10" and extra == "dev"
102
+ Requires-Dist: langchain-openai; python_version >= "3.10" and extra == "dev"
103
+ Requires-Dist: langchain-mistralai; python_version >= "3.10" and extra == "dev"
104
+ Requires-Dist: langchain-perplexity; python_version >= "3.10" and extra == "dev"
105
+ Requires-Dist: langchain-cohere; python_version >= "3.10" and extra == "dev"
106
+ Requires-Dist: langchain-huggingface; python_version >= "3.10" and extra == "dev"
97
107
  Requires-Dist: openai>=1.0.0; extra == "dev"
98
108
  Requires-Dist: litellm>=1.40.0; extra == "dev"
99
109
  Requires-Dist: fal-client>=0.13.0; extra == "dev"
100
110
  Requires-Dist: perplexityai>=0.1.0; extra == "dev"
101
111
  Requires-Dist: google-genai>=0.1.0; extra == "dev"
102
112
  Requires-Dist: pyyaml; extra == "dev"
113
+ Provides-Extra: dev-langchain-aws
114
+ Requires-Dist: langchain-aws[anthropic]>=1.7.5; python_version >= "3.10" and extra == "dev-langchain-aws"
103
115
  Dynamic: license-file
104
116
 
105
117
  # Revenium Python SDK
@@ -120,11 +132,10 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
120
132
  - **Decorator Support**: `@revenium_metadata` for automatic metadata injection and `@revenium_meter` for selective metering
121
133
  - **Tool Metering**: `@meter_tool` to meter arbitrary tool/function calls alongside LLM API metering
122
134
  - **Prompt Capture**: Optional capture of prompts and responses for analytics and debugging
123
- - **Terminal Summary**: Real-time cost and usage summaries in your terminal (human-readable or JSON)
124
135
  - **Distributed Tracing**: Built-in trace visualization fields for cross-service observability
125
136
  - **Asynchronous Processing**: Usage records are sent from a fixed pool of background threads, never on your request path
126
- - **Graceful Shutdown**: Flushes pending metering data when the process exits, within a bounded time, without taking over your application's signal handling
127
- - **Thread-Safe**: Production-ready with `contextvars`-based context management for concurrent applications
137
+ - **Graceful Shutdown**: Flushes pending metering data when the process exits, and when a `multiprocessing` worker process finishes its job, within a bounded time, without taking over your application's signal handling; `flush_metering()` flushes on demand
138
+ - **Thread-Safe**: Production-ready with `contextvars`-based context management for concurrent applications; wrap worker thread targets with `carry_context` (see [Decorator Support](#decorator-support))
128
139
 
129
140
  ## Supported Providers
130
141
 
@@ -132,6 +143,7 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
132
143
  |----------|-------|----------------|
133
144
  | OpenAI | `openai` | `pip install revenium-python-sdk[openai]` |
134
145
  | Azure OpenAI | `openai` | `pip install revenium-python-sdk[openai]` |
146
+ | xAI (Grok, via OpenAI SDK) | `openai` | `pip install revenium-python-sdk[openai]` |
135
147
  | Anthropic | `anthropic` | `pip install revenium-python-sdk[anthropic]` |
136
148
  | AWS Bedrock (Anthropic) | `anthropic` | `pip install revenium-python-sdk[anthropic]` |
137
149
  | Google Gemini | `google-genai` | `pip install revenium-python-sdk[google-genai]` |
@@ -145,24 +157,57 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
145
157
  | LangChain | `langchain` | `pip install revenium-python-sdk[langchain]` |
146
158
  | Griptape | `griptape` | `pip install revenium-python-sdk[griptape]` |
147
159
 
160
+ Not supported: Runway video generation is not metered automatically; to record those calls, wrap them with `@meter_tool` (see [Tool Metering](#tool-metering)).
161
+
148
162
  ## Feature Matrix
149
163
 
150
164
  | Feature | OpenAI | Anthropic | Google | Ollama | LiteLLM | Perplexity | fal.ai |
151
165
  |---------|--------|-----------|--------|--------|---------|------------|--------|
152
- | Chat Completions | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
166
+ | Chat Completions | Yes\* | Yes | Yes | Yes | Yes | Yes | Yes |
153
167
  | Streaming | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
154
168
  | Embeddings | Yes | - | Yes | Yes | Yes | - | - |
155
169
  | Vision/Multimodal | Yes | Yes | Yes | - | Yes | - | Yes |
170
+ | Audio (speech, transcription, translation) | Yes | - | - | - | Proxy mode | - | Yes |
156
171
  | Image Generation | - | - | Yes | - | - | - | Yes |
157
- | Video Generation | - | - | Yes | - | - | - | Yes |
158
- | Prompt Capture | Yes | Yes | Yes | - | Yes | - | - |
159
- | Terminal Summary | Yes | Yes | Yes | Yes | Yes | - | - |
172
+ | Video Generation | - | - | Yes[^veo] | - | - | - | Yes |
173
+ | Prompt Capture | Yes | Yes | Yes | - | Client mode[^litellm-capture] | - | - |
160
174
  | Azure / Bedrock | Azure | Bedrock | Vertex AI | - | All | - | - |
161
175
  | LangChain Integration | Yes | - | - | - | - | - | - |
162
176
  | Griptape Integration | Yes | Yes | - | Yes | Yes | - | - |
163
- | CrewAI Integration | - | - | - | - | Yes | - | - |
177
+ | CrewAI Integration | Yes | Yes | Yes | - | Yes | - | - |
164
178
  | Proxy Mode | - | - | - | - | Yes | - | - |
165
179
 
180
+ [^litellm-capture]: LiteLLM prompt capture covers chat calls your own code makes (`completion`, `acompletion` and their streams). The LiteLLM gateway plugin (`ReveniumGuardrail`) does not capture prompts or replies.
181
+
182
+ \* OpenAI's `chat.completions` and `responses` calls are metered[^openai-background]; the legacy `completions.create` endpoint is not.
183
+
184
+ [^openai-background]: An OpenAI background response (`responses.create(background=True)`) is recorded when your code's `responses.retrieve(...)`, a resumed stream (`responses.retrieve(..., stream=True)` or `responses.stream(response_id=...)`) or `responses.cancel(...)` first sees the job finish, with the `usage_metadata` you gave at create. A background job you never retrieve, or retrieve only from a different process than the one that created it or after a restart, is not recorded. A cancelled background job is recorded when OpenAI reports usage for it on the first call that sees it cancelled, usually `responses.cancel(...)`; a cancelled job with no usage on that call is not recorded. A background stream cut off part-way and never resumed or retrieved is not recorded. Background jobs created through `beta.responses` are not metered. A background job created through `responses.with_streaming_response.create(..., background=True)` is not recorded, even when you retrieve it later. Reading a finished job only through `responses.with_streaming_response.retrieve(...)` does not record it; the job stays pending, and the next `responses.retrieve(...)` or `responses.with_raw_response.retrieve(...)` in the same process records it once.
185
+
186
+ [^veo]: A Veo video through `google.genai` (the Gemini API, or Vertex AI with `vertexai=True`) is recorded when your code's `client.operations.get(...)` (or `client.aio.operations.get(...)`) first sees the operation finish, billed at the requested clip length times the videos returned (Google's response carries no duration). A failed operation is recorded as a failed, zero-second video. When the request sets `webhook_config` or `pubsub_topic`, the video is recorded when you submit it. A video you never poll, or poll from a different process than the one that submitted it, is not recorded.
187
+
188
+ Some billable provider calls are not metered at all: see [Calls the SDK does not meter](#calls-the-sdk-does-not-meter).
189
+
190
+ ## Calls the SDK does not meter
191
+
192
+ The calls below are billed by the provider (some, such as batch and fine-tuning jobs, when the job runs rather than when you call them), but the SDK records no usage for them: nothing reaches Revenium and nothing is logged. On every build a test compares this list with the SDK's inventory of the public calls of the OpenAI, Anthropic, Perplexity, Gemini, Ollama, LiteLLM and fal clients, boto3's Bedrock Runtime client, and the Vertex AI model, session, batch prediction, tuning and context-cache classes, on the provider versions the SDK is tested on. Calls reached another way, for example LangChain classes that call their own vendor SDK, are outside that check, except LangChain embeddings, listed by hand below; wrapping one with `wrap()` logs a warning. Sync and async forms are folded into one name, and the `with_raw_response` and `with_streaming_response` forms of a listed call are not metered either. To record any of these calls, wrap it with `@meter_tool` (see [Tool Metering](#tool-metering)).
193
+
194
+ <!-- not-metered:start -->
195
+ - **OpenAI** (`OpenAI` and `AsyncOpenAI` clients): `batches.create`, `beta.agents.sessions.create`, `beta.agents.sessions.events.create`, `beta.agents.sessions.events.stream`, `beta.agents.sessions.stream`, `beta.agents.sessions.update`, `beta.chatkit.sessions.create`, `beta.realtime.connect`, `beta.responses.compact`, `beta.responses.connect`, `beta.responses.create`, `beta.threads.create_and_run`, `beta.threads.create_and_run_poll`, `beta.threads.create_and_run_stream`, `beta.threads.runs.create`, `beta.threads.runs.create_and_poll`, `beta.threads.runs.create_and_stream`, `beta.threads.runs.stream`, `beta.threads.runs.submit_tool_outputs`, `beta.threads.runs.submit_tool_outputs_and_poll`, `beta.threads.runs.submit_tool_outputs_stream`, `completions.create`, `decisions.create`, `evals.runs.create`, `fine_tuning.alpha.graders.run`, `fine_tuning.jobs.create`, `images.create_variation`, `images.edit`, `images.generate`, `live.connect`, `live.create`, `live.forks.connect`, `live.sessions.accept`, `live.sessions.fork`, `live.sideband.connect`, `realtime.calls.accept`, `realtime.calls.create`, `realtime.connect`, `responses.compact`, `responses.connect`, `videos.create`, `videos.create_and_poll`, `videos.create_character`, `videos.edit`, `videos.extend`, `videos.remix`
196
+ - **Anthropic** (`Anthropic` and `AsyncAnthropic` clients): `beta.deployments.run`, `beta.dreams.create`, `beta.environments.work.poller`, `beta.environments.work.worker`, `beta.messages.batches.create`, `beta.sessions.create`, `beta.sessions.events.send`, `beta.sessions.events.stream`, `beta.sessions.events.tool_runner`, `beta.sessions.threads.events.stream`, `messages.batches.create`
197
+ - **Google Gemini** (`google.genai` `Client` and `Client.aio`): `batches.create`, `batches.create_embeddings`, `caches.create`, `caches.update`, `file_search_stores.import_file`, `file_search_stores.upload_to_file_search_store`, `interactions.create`, `live.connect`, `live.music.connect`, `models.edit_image`, `models.recontext_image`, `models.segment_image`, `models.upscale_image`, `triggers.run`, `tunings.tune`
198
+ - **Google Vertex AI** (`vertexai` classes): `batch_prediction.BatchPredictionJob.submit`, `caching.CachedContent.create`, `caching.CachedContent.update`, `language_models.ChatModel.tune_model`, `language_models.ChatModel.tune_model_rlhf`, `language_models.ChatSession.send_message`, `language_models.ChatSession.send_message_async`, `language_models.ChatSession.send_message_streaming`, `language_models.ChatSession.send_message_streaming_async`, `language_models.CodeChatModel.tune_model`, `language_models.CodeChatSession.send_message`, `language_models.CodeChatSession.send_message_async`, `language_models.CodeChatSession.send_message_streaming`, `language_models.CodeChatSession.send_message_streaming_async`, `language_models.CodeGenerationModel.batch_predict`, `language_models.CodeGenerationModel.predict`, `language_models.CodeGenerationModel.predict_async`, `language_models.CodeGenerationModel.predict_streaming`, `language_models.CodeGenerationModel.predict_streaming_async`, `language_models.CodeGenerationModel.tune_model`, `language_models.TextEmbeddingModel.batch_predict`, `language_models.TextEmbeddingModel.deploy_tuned_model`, `language_models.TextEmbeddingModel.tune_model`, `language_models.TextGenerationModel.batch_predict`, `language_models.TextGenerationModel.predict`, `language_models.TextGenerationModel.predict_async`, `language_models.TextGenerationModel.predict_streaming`, `language_models.TextGenerationModel.predict_streaming_async`, `language_models.TextGenerationModel.tune_model`, `language_models.TextGenerationModel.tune_model_rlhf`, `preview.caching.CachedContent.create`, `preview.caching.CachedContent.update`, `preview.vision_models.ImageCaptioningModel.get_captions`, `preview.vision_models.ImageGenerationModel.upscale_image`, `preview.vision_models.ImageQnAModel.ask_question`, `preview.vision_models.ImageSegmentationModel.segment_image`, `preview.vision_models.ImageTextModel.ask_question`, `preview.vision_models.ImageTextModel.get_captions`, `preview.vision_models.MultiModalEmbeddingModel.get_embeddings`, `preview.vision_models.WatermarkVerificationModel.verify_image`, `tuning.sft.train`, `vision_models.ImageCaptioningModel.get_captions`, `vision_models.ImageGenerationModel.upscale_image`, `vision_models.ImageQnAModel.ask_question`, `vision_models.ImageTextModel.ask_question`, `vision_models.ImageTextModel.get_captions`, `vision_models.MultiModalEmbeddingModel.get_embeddings`
199
+ - **AWS Bedrock** (boto3 bedrock-runtime client; Claude models are metered when REVENIUM_BEDROCK_TRANSPORT is on): `apply_guardrail`, `converse`, `converse_stream`, `invoke_guardrail_checks`, `invoke_model`, `invoke_model_with_response_stream`, `start_async_invoke`
200
+ - **Perplexity** (`Perplexity` and `AsyncPerplexity` clients): `async_.chat.completions.create`, `browser.sessions.create`, `contextualized_embeddings.create`, `embeddings.create`, `responses.create`, `search.create`
201
+ - **LiteLLM** (the `litellm` module): `aadapter_completion`, `aadapter_generate_content`, `acode_interpreter_tool`, `acompact_responses`, `acreate_batch`, `acreate_fine_tuning_job`, `acreate_run`, `acreate_sandbox`, `adapter_completion`, `adecisions`, `agenerate_content`, `aimage_edit`, `aimage_generation`, `aimage_variation`, `aingest`, `anthropic_interface.messages.acreate`, `anthropic_interface.messages.create`, `anthropic_messages`, `anthropic_messages_handler`, `aocr`, `aquery`, `arealtime_calls`, `arerank`, `aresponses`, `aresponses_api_with_mcp`, `aresponses_with_retries`, `arun_code`, `arun_thread`, `arun_thread_stream`, `asearch`, `aspeech`, `asystemone`, `atranscription`, `avideo_create_character`, `avideo_edit`, `avideo_extension`, `avideo_generation`, `avideo_remix`, `compact_responses`, `config_completion`, `create_batch`, `create_fine_tuning_job`, `create_run`, `decisions`, `image_edit`, `image_generation`, `image_variation`, `ingest`, `nlp_cloud_chat_completion`, `ocr`, `query`, `replicate_chat_completion`, `rerank`, `responses`, `responses_with_retries`, `run_thread`, `run_thread_stream`, `search`, `speech`, `systemone`, `transcription`, `video_create_character`, `video_edit`, `video_extension`, `video_generation`, `video_remix`
202
+ - **Ollama** (`Client`, `AsyncClient` and the `ollama` module): `systemone`, `web_fetch`, `web_search`
203
+ - **fal.ai** (`SyncClient`, `AsyncClient` and the `fal_client` module): `realtime`, `realtime_async`, `ws_connect`, `ws_connect_async`
204
+ - **LangChain** (embeddings models from vendors other than OpenAI, Azure OpenAI and Ollama, such as `MistralAIEmbeddings`): `Embeddings.aembed_documents`, `Embeddings.aembed_query`, `Embeddings.embed_documents`, `Embeddings.embed_query`
205
+ <!-- not-metered:end -->
206
+
207
+ Raw boto3 calls to AWS Bedrock send no usage record for any model unless `REVENIUM_BEDROCK_TRANSPORT` is set to `1` or `true`; with it set, Claude models on `invoke_model`, `invoke_model_with_response_stream`, `converse` and `converse_stream` are metered, and other models still are not. Claude through `AnthropicBedrock` is metered either way. `boto3.client("bedrock-agent-runtime")` (`invoke_agent`, `retrieve_and_generate`), Bedrock batch inference through `boto3.client("bedrock").create_model_invocation_job`, and Vertex AI `evaluation`, `agent_engines` and `rag` are also not metered and are outside the check.
208
+
209
+ LiteLLM's `transcription` and `atranscription` calls to OpenAI models are recorded when `revenium_middleware.openai` is also imported, because LiteLLM sends them through the OpenAI SDK, which that integration meters; that record carries none of the `usage_metadata` passed to LiteLLM. Without that import they are not recorded.
210
+
166
211
  ## Installation
167
212
 
168
213
  ```bash
@@ -274,6 +319,8 @@ Emit per-agent terminal outcomes (`CONVERTED`, `DEFLECTED`, `ESCALATED`) alongsi
274
319
 
275
320
  > **You need a write-scope key (`rev_sk_`) to use the agentic outcomes API.** Metering keys (`rev_mk_`) can only meter completions and tool events — they cannot report, amend, or read job outcomes, and the SDK rejects them client-side before any HTTP request is made. Key resolution: explicit `api_key=` > `REVENIUM_WRITE_API_KEY` > `REVENIUM_OUTCOME_API_KEY` (deprecated fallback) > `REVENIUM_METERING_API_KEY`.
276
321
 
322
+ Outcome, job and job-type economics calls go to the same Revenium address as usage records: `REVENIUM_METERING_BASE_URL`, or `https://api.revenium.ai` when it is unset. Set `REVENIUM_PROFITSTREAM_BASE_URL`, or pass `profitstream_base_url=`, only when outcomes live at a different address.
323
+
277
324
  ### Job-Type Economics and Outcome Facts
278
325
 
279
326
  Keep a metering key for AI telemetry and a separate write key for outcomes and
@@ -355,8 +402,10 @@ with JobContext("loan-app-12345", type="loan_processing", version="2.1") as job:
355
402
  ```
356
403
 
357
404
  - **Async:** `async with JobContext(...) as job:` works identically.
358
- - **Auto-FAILED:** if an unhandled exception escapes the block before an outcome was reported, the context automatically reports `execution_status="FAILED"` (error message and class in metadata) and always re-raises the original exception.
359
- - **Blocking:** outcome calls are synchronous HTTP requests with retries; tune how long they may block with the `retry_attempts`, `retry_initial_seconds`, and `retry_max_seconds` arguments, accepted by the `JobContext` constructor, `JobContext.attach()`, `get_outcome_history()`, and the CrewAI wrapper's `report_job_outcome`/`amend_job_outcome`.
405
+ - **Auto-FAILED:** if an unhandled exception escapes the block, the context automatically reports `execution_status="FAILED"` (the exception's class in `metadata.error`, `metadata.errorType` and the outcome reason; its message too when `REVENIUM_CAPTURE_ERROR_MESSAGES=true`, redacted as for failed tool events and capped at 2048 characters; an exception from a provider's HTTP error, which can quote the request, sends its class only unless `REVENIUM_CAPTURE_PROMPTS=true` as well) and always re-raises the original exception. It skips the FAILED when a `report_outcome` or `amend_outcome` call succeeded, the platform answered that the job already has an outcome, the exception escaping the block is the one your own `report_outcome`/`amend_outcome` raised, or that call found no such job (404). So a report you caught that failed, followed by a crash, still gets FAILED. If the caught report was in fact stored (a timeout after the platform saved it), the automatic FAILED is refused as already reported and only logged; the stored outcome stands.
406
+ - **Job id format:** Revenium refuses any other job id on AI calls, so a job id must start with an ASCII letter or digit, contain only ASCII letters, digits, `.`, `_` and `-`, be at most 255 characters, and not be `types` or `conversion-funnel`. Entering `JobContext` with any other id raises `ValueError` before any call is made. `JobContext.attach()` still accepts such an id, for reporting on a job created with `create_job`. An id from `usage_metadata`, `@track_job`, `REVENIUM_AGENTIC_JOB_ID` or proxy headers that breaks the rule is left off the call: the call is still metered, a warning is logged once per id, and the call does not fall back to the surrounding job's id. AI calls never create a job under such an id, so `report_outcome` on it fails with a 404 after its retries unless the job was created with `create_job`.
407
+ - **Blocking:** outcome calls are synchronous HTTP requests with retries; tune how long they may block with the `retry_attempts`, `retry_initial_seconds`, and `retry_max_seconds` arguments, accepted by the `JobContext` constructor, `JobContext.attach()`, `get_outcome_history()`, the job reads in [Reading Jobs Back](#reading-jobs-back), and the CrewAI wrapper's `report_job_outcome`/`amend_job_outcome`.
408
+ - **Retry after a gateway error:** when a gateway answers 502, 503 or 504 and the retry is then refused as already reported, the SDK reads the job once and treats the report as delivered if the stored outcome is the one it sent, unamended. An identical outcome stored by another writer in that gap is reported as success too; the reporter label (`reported_by`) and `metrics` facts are not checked. A timeout or connection error on the report itself is not retried.
360
409
  - **Team resolution:** explicit `team_id=` > `REVENIUM_TEAM_ID` > automatic resolution from the API key; `OutcomeReportingError` is raised if none of these yields a team.
361
410
  - **Nesting:** a nested `JobContext` is a different job (replace, not merge); exiting the inner context restores the outer job's fields.
362
411
 
@@ -403,7 +452,7 @@ except OutcomeAmendConflictError as conflict:
403
452
  expected_entity_version=conflict.current_entity_version)
404
453
  ```
405
454
 
406
- The handle also records that version, so the retry above works with or without passing `expected_entity_version=` explicitly. `current_entity_version` is `None` when the conflict body carries no version; the version then has to come from a job read (`GET /v2/api/jobs/{agenticJobId}`), which this SDK does not wrap yet, and 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.
455
+ The handle also records that version, so the retry above works with or without passing `expected_entity_version=` explicitly. `current_entity_version` is `None` when the conflict body carries no version; read it with `get_job(job_id)["entityVersion"]`; a retry without it is unlocked (last-write-wins). `get_outcome_history()` rows carry an `amendment_sequence`, not an entity version. History tells you *what* changed, never which version to retry with.
407
456
 
408
457
  Every outcome call replaces the recorded version with the one its response reports, including clearing it when a response carries none, so a completed call never leaves a token behind that the platform has already moved past.
409
458
 
@@ -441,12 +490,40 @@ handle.close()
441
490
 
442
491
  - **Declare the metric first:** a fact only lands if the job type's economics contract declares that key as a `PER_JOB` metric; an undeclared key is rejected with a 400. `quality_rate` is a rate and the platform range-checks it to 0..1.
443
492
  - **Entry shape:** `key` and `value` are required; `provenance` (`MEASURED` | `SELF_REPORTED` | `DERIVED` | `ATTESTED`), `recordedBy`, `source`, `reason` and `recordedAt` are optional. Entries are sent exactly as you write them, so the fields you omit take the platform's defaults (`SELF_REPORTED`, the calling principal, `api`) instead of being guessed by the SDK. A missing `key` or `value` — or no entries at all on `append_outcome_metrics()` — raises `ValueError` before any HTTP request, on `JobContext` and `AgenticOutcomeClient` alike.
444
- - **Append-only:** facts accumulate; the SDK never dedupes or replaces one, because the platform owns fact identity. `metrics=` on `amend_outcome()` appends as part of the amendment.
493
+ - **One active fact per key:** a job keeps one active fact for each metric key. Appending a key the job already has supersedes the earlier fact (the earlier fact is deactivated, not deleted), and the platform refuses that append with a 400 unless the entry carries a `reason`. The same key twice in one request is refused. The SDK sends entries as written and never dedupes them. `metrics=` on `amend_outcome()` records facts as part of the amendment; a repeated key there also supersedes the earlier fact, and the amendment's own reason (or the platform's automated reason for an API-key caller) is used when an entry has none.
445
494
  - **Not part of outcome history:** `get_outcome_history()` returns the outcome revisions only — appended facts do not appear in those rows.
446
- - **Retries:** an append is retried only on `429`, which proves the platform rejected the request before recording anything. A `502`/`503`/`504` is raised instead of retried: the facts may already be recorded, and a second append is a second fact, so the decision to resend is yours (check the recorded facts first).
495
+ - **Retries:** an append is retried only on `429`, which proves the platform rejected the request before recording anything. A `502`/`503`/`504` is raised instead of retried: the facts may already be recorded, and resending a key that is already recorded is a correction, refused without a `reason` and, with one, superseding the fact, so the decision to resend is yours (check the recorded facts first).
447
496
  - **Locking is unaffected:** appending facts does not change the job's `entityVersion`, so the handle keeps the version it recorded and a following `amend_outcome()` still locks against it. (`report_outcome()` and `amend_outcome()` clear the recorded version when their response carries none, because those calls advance it; an append does not.)
448
497
  - **Why it matters:** AI Alerts evaluate `QUALITY_RATE` from these facts, so a job whose integration emits none is invisible to those rules.
449
498
 
499
+ ### Reading Jobs Back
500
+
501
+ These calls need a write-scope key (`rev_sk_`), like every other outcome call. A metering key (`rev_mk_`) is rejected before any request.
502
+
503
+ ```python
504
+ from revenium_middleware import (
505
+ get_conversion_funnel, get_job, get_job_roi, get_job_transactions,
506
+ get_job_types, list_jobs,
507
+ )
508
+
509
+ page = list_jobs(job_type="loan_processing", execution_status="SUCCESS", size=50)
510
+ for job in page["content"]:
511
+ print(job["agenticJobId"], job["outcomeType"])
512
+
513
+ version = get_job("loan-app-12345")["entityVersion"]
514
+ types = get_job_types()
515
+ roi = get_job_roi("loan-app-12345")["roi"]
516
+ calls = get_job_transactions("loan-app-12345")["transactions"]
517
+ rate = get_conversion_funnel(
518
+ start_date="2026-09-01T00:00:00Z", end_date="2026-09-30T23:59:59Z",
519
+ )["conversionRate"]
520
+ ```
521
+
522
+ - **Results are the API's JSON:** each call returns dicts with the field names the API sends (camelCase), so a field the platform adds later reaches you without an SDK upgrade.
523
+ - **Paging:** `list_jobs` returns `{"content": [...], "page": {...}}`; `page` is 0-based and only the filters you pass are sent.
524
+ - **Missing job:** a job that does not exist raises `httpx.HTTPStatusError` (404).
525
+ - **Team and retries:** team resolution and the retry knobs work as for `get_outcome_history()`.
526
+
450
527
  ### Outcome Exceptions
451
528
 
452
529
  All outcome exceptions are importable from `revenium_middleware` and share the `OutcomeReportingError` base, so `except OutcomeReportingError:` catches the whole family:
@@ -475,6 +552,16 @@ client.append_outcome_metrics(job_id, [...]) # append declared per-job facts la
475
552
  client.close()
476
553
  ```
477
554
 
555
+ In an `emit_completion` payload the agent is named by `agent`. `agentName` and `currency` are not sent (Revenium does not store them); `emit_completion` names them in its one-time warning about unsent keys.
556
+
557
+ `emit_completion` and `emit_tool_event` queue the record and return at once, like every automatic record: the SDK's background threads send it with the same timeouts and retries (see [Metering Delivery and Timeouts](#metering-delivery-and-timeouts)), and a record that fails with a timeout, a refused connection or a 5xx goes to the store-and-forward buffer and is sent when Revenium is reachable again. Delivery errors are logged, not raised; `emit_completion` still raises `ValueError` before anything is queued when the payload is missing a required key. Both calls return the payload you passed.
558
+
559
+ Records go to the address set in code with `initialize_metering(base_url=...)` or a `metering_key(..., base_url=...)` block when one is set, else `REVENIUM_METERING_BASE_URL`; pass `meter_base_url=` to `AgenticOutcomeSettings` to pin another address. They are always sent under the settings' `api_key`, never a `metering_key()` key. `http_client=` serves jobs and outcomes only.
560
+
561
+ A script that emits many records and exits right away has `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` (default 5) to send the records still queued; raise it if records are reported unsent at exit.
562
+
563
+ `emit_tool_event` sends one `Idempotency-Key` per call and reuses it when the buffer replays the event, so a tool event replayed after a gateway error is stored once.
564
+
478
565
  The job is created implicitly by the first metric ingested for `agenticJobId`. Call `client.create_job(job_id)` explicitly if you need to record an agent run before emitting any metrics; it returns the created job resource merged over the fields you supplied, including the `entityVersion` an outcome amendment sends back as `expectedEntityVersion`.
479
566
 
480
567
  See [`examples/agentic_outcomes/`](examples/agentic_outcomes/) for runnable demos (sales / coding / support) with configurable failure rates and outcome distributions.
@@ -504,6 +591,16 @@ with idempotency_key(f"order-{order_id}"):
504
591
 
505
592
  The context manager is backed by `contextvars`, so it scopes correctly across threads and asyncio tasks.
506
593
 
594
+ ### Several calls in one block
595
+
596
+ - Each model call in a block gets its own key: `order-42`, then `order-42:2`, `order-42:3` and so on, in the order its usage record is delivered. That can differ from the order the calls were made, because records are delivered in the background. Every call in the block is recorded.
597
+ - A retry the SDK makes itself (an HTTP retry, or a replay from the delivery buffer) reuses the same key and is stored once.
598
+ - Rerunning the same block is refused call by call, up to the number of calls the original block made: each refusal is logged and counted as a metering error, and the rerun's provider spend is not recorded. Calls beyond the original count are recorded.
599
+ - A block key that ends in `:<number>`, such as `order-42:2`, can collide with another block's derived keys. Avoid that shape.
600
+ - Tool events are not keyed by the block; each tool event carries its own key (see [Tool Metering](#tool-metering)).
601
+ - fal queue jobs are not keyed by the block either; each job's record uses its own key, `fal-<request id>` (see [fal.ai](#falai)).
602
+ - If a derived key would be longer than 255 characters, the SDK uses the SHA-256 hex digest of the block key in its place, so the key stays valid and the same on every rerun.
603
+
507
604
  ### Backend behavior
508
605
 
509
606
  | Scenario | Backend response |
@@ -518,7 +615,7 @@ See [docs.revenium.io/integrations/idempotency](https://docs.revenium.io/integra
518
615
 
519
616
  ### Key format
520
617
 
521
- `Idempotency-Key` must be 1–255 printable ASCII characters. UUID v4 is the recommended format and what the SDK generates by default.
618
+ `Idempotency-Key` must be 1–255 printable ASCII characters, with no leading or trailing spaces. `idempotency_key()` and `set_idempotency_key()` raise `ValueError` for an empty key and for any other key that breaks this rule (an accented or non-Latin letter, a line break, a tab, a leading or trailing space, or more than 255 characters), before anything in the block runs. UUID v4 is the recommended format and what the SDK generates by default.
522
619
 
523
620
  ---
524
621
 
@@ -579,7 +676,7 @@ Webhook deliveries without a configured signing secret arrive without HMAC heade
579
676
 
580
677
  ### OpenAI
581
678
 
582
- Supports chat completions, streaming, embeddings, function calling, and vision/multimodal.
679
+ Supports chat completions, streaming, embeddings, function calling, vision/multimodal, and audio (speech, transcription and translation).
583
680
 
584
681
  ```python
585
682
  from dotenv import load_dotenv
@@ -619,9 +716,28 @@ embedding = client.embeddings.create(
619
716
  )
620
717
  ```
621
718
 
719
+ A chat or Responses call the provider refuses (a 400, 429 or 500, for example), streamed or not, sends one record with stop reason `ERROR`, zero tokens and the error's class and HTTP status as its error reason (plus the provider's redacted error message when both `REVENIUM_CAPTURE_ERROR_MESSAGES` and `REVENIUM_CAPTURE_PROMPTS` are `true`; a provider's error can quote the request, so it is never sent with prompt capture off), cut to 255 characters with its "(HTTP <status>)" ending kept; a stream that breaks off part-way is recorded with stop reason `ERROR` too. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer (a connection error, a timeout, or a stream that broke off) has none. Your code still gets the original exception. Embeddings, `parse()` and calls a spending cap refuses send no error record.
720
+
721
+ #### Audio
722
+
723
+ `audio.transcriptions.create`, `audio.translations.create` and `audio.speech.create` (sync, async, `with_raw_response` and `with_streaming_response`, on `OpenAI` and `AzureOpenAI`) each send one audio record, with `usage_metadata` attribution like a chat call. Spending caps apply to them as they do to chat.
724
+
725
+ ```python
726
+ transcript = client.audio.transcriptions.create(model="whisper-1", file=open("call.mp3", "rb"))
727
+ speech = client.audio.speech.create(model="tts-1", voice="alloy", input="Your order has shipped.")
728
+ ```
729
+
730
+ What each record carries:
731
+ - **Transcription and translation:** the audio seconds OpenAI bills (`usage.seconds`, else the `duration` of a `verbose_json` response), or, for models OpenAI bills by token (`gpt-4o-transcribe`, `gpt-4o-mini-transcribe`), the input, output and audio input tokens. A streamed transcription is recorded once, when the stream ends or is closed.
732
+ - **Speech:** the number of characters in `input`, plus `voice`, `speed` and `response_format`. The audio itself is never read.
733
+
734
+ Some calls report no duration, so their record is stored with a duration of zero and no cost: transcriptions with `response_format` `text`, `srt` or `vtt`, translations in the default `json` format (use `verbose_json` to get the duration), anything called through `with_streaming_response`, and a `with_raw_response` call with `stream=True`. Revenium may also show $0 for models it prices by token, such as `gpt-4o-mini-tts`, as it does for the Go and Node SDKs.
735
+
736
+ If a LiteLLM gateway with `ReveniumGuardrail` also imports `revenium_middleware.openai`, an OpenAI audio call proxied through it is recorded twice; import only the LiteLLM integration in the gateway process.
737
+
622
738
  #### Azure OpenAI
623
739
 
624
- The middleware automatically detects Azure OpenAI when using `AzureOpenAI()` and resolves deployment names to standard model names for accurate pricing.
740
+ The middleware automatically detects Azure OpenAI when using `AzureOpenAI()` and resolves deployment names to standard model names for accurate pricing. The model Azure reports (for example `gpt-4.1-nano-2025-04-14`) is recorded as is; a custom deployment name is mapped to its model family.
625
741
 
626
742
  ```python
627
743
  from openai import AzureOpenAI
@@ -647,6 +763,30 @@ response = client.chat.completions.create(
647
763
 
648
764
  **Examples:** `examples/openai/` - `openai_basic.py`, `openai_streaming.py`, `azure_basic.py`, `azure_streaming.py`
649
765
 
766
+ #### xAI (Grok)
767
+
768
+ Point the OpenAI client at xAI and calls are recorded with provider `XAI`, so xAI spend is priced and reported as xAI rather than OpenAI.
769
+
770
+ A spending cap on a Grok model also stops calls that use the short names xAI publishes for it, such as `grok-4.20`; see [Cost Controls / Enforcement](#cost-controls--enforcement) for how model filters treat vendor aliases.
771
+
772
+ On a Grok reasoning model the reasoning tokens xAI bills are counted as output, and each record carries xAI's own charge for the call (`cost_in_usd_ticks`) as its total cost. This applies when the client's base URL is on `x.ai`; Grok reached through a proxy or gateway is recorded as the OpenAI-compatible call it appears to be.
773
+
774
+ ```python
775
+ import os
776
+ from openai import OpenAI
777
+ import revenium_middleware.openai
778
+
779
+ client = OpenAI(
780
+ api_key=os.getenv("XAI_API_KEY"),
781
+ base_url="https://api.x.ai/v1"
782
+ )
783
+
784
+ response = client.chat.completions.create(
785
+ model="grok-4.20-0309-non-reasoning",
786
+ messages=[{"role": "user", "content": "Hello!"}]
787
+ )
788
+ ```
789
+
650
790
  ---
651
791
 
652
792
  ### Anthropic
@@ -709,11 +849,13 @@ async def main():
709
849
  asyncio.run(main())
710
850
  ```
711
851
 
712
- **Note:** The middleware wraps the `messages.create` and `messages.stream` endpoints, sync and async alike (including `create(stream=True)`). Other Anthropic SDK features work normally but aren't metered.
852
+ **Note:** The middleware meters `messages.create` (including `create(stream=True)`), `messages.stream` and `messages.parse`, and the same calls on `client.beta.messages` (`create`, `stream`, `parse` and each step of `tool_runner`), sync and async, including their `with_raw_response` and `with_streaming_response` forms, on the Anthropic, Bedrock and Vertex AI clients. Calls listed under [Calls the SDK does not meter](#calls-the-sdk-does-not-meter), message batches among them, are not metered.
853
+
854
+ A call the provider refuses sends one record with stop reason `ERROR`, zero tokens and the error's class and HTTP status as its error reason (plus the provider's redacted error message when both `REVENIUM_CAPTURE_ERROR_MESSAGES` and `REVENIUM_CAPTURE_PROMPTS` are `true`; a provider's error can quote the request, so it is never sent with prompt capture off; at most 255 characters, keeping its "(HTTP <status>)" ending), as does a `create(stream=True)` stream that breaks off part-way. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer (a connection error, a timeout, or a stream that broke off) has none. Your code still gets the original exception. Calls served through the Bedrock fast path, and calls a spending cap refuses, send no error record.
713
855
 
714
856
  #### AWS Bedrock
715
857
 
716
- The middleware provides complete AWS Bedrock integration with automatic detection.
858
+ The middleware meters Claude on AWS Bedrock through `AnthropicBedrock`, with automatic detection.
717
859
 
718
860
  ```python
719
861
  import anthropic
@@ -742,9 +884,12 @@ message = client.messages.create(
742
884
  | Variable | Description | Default |
743
885
  |----------|-------------|---------|
744
886
  | `AWS_REGION` | AWS region for Bedrock | `us-east-1` |
745
- | `REVENIUM_BEDROCK_DISABLE` | Set to `1` to disable Bedrock support (Bedrock detection only - Foundry detection is unaffected) | Not set |
887
+ | `REVENIUM_BEDROCK_DISABLE` | Set to `1` to disable Bedrock support for Anthropic clients (Bedrock detection only - Foundry detection is unaffected). Raw boto3 calls metered with `REVENIUM_BEDROCK_TRANSPORT`, and LangChain's `ChatBedrock` and `ChatBedrockConverse`, are still recorded as AWS | Not set |
888
+ | `REVENIUM_BEDROCK_TRANSPORT` | Set to `1` or `true` to meter Claude models called through a raw `boto3.client("bedrock-runtime")` (`invoke_model`, `invoke_model_with_response_stream`, `converse`, `converse_stream`); other Bedrock models are never metered this way | Not set |
889
+
890
+ **AWS authentication**: an `AnthropicBedrock` client uses its own `aws_access_key` / `aws_secret_key` / `aws_session_token`, `aws_profile` or Bedrock `api_key`, exactly as without the middleware. A plain `anthropic.Anthropic` client with a Bedrock `base_url` uses the standard credential chain: environment variables, `~/.aws/credentials`, IAM roles, AWS SSO. Required permissions: `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream`.
746
891
 
747
- **AWS authentication** uses the standard credential chain: environment variables, `~/.aws/credentials`, IAM roles, AWS SSO. Required permissions: `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream`.
892
+ **Raw boto3 calls, application inference profiles and Provisioned Throughput**: with `REVENIUM_BEDROCK_TRANSPORT=1`, raw `boto3.client("bedrock-runtime")` calls to Claude (`invoke_model`, `invoke_model_with_response_stream`, `converse`, `converse_stream`) are metered and capped. A call written as a cross-Region inference profile ARN or a foundation model ARN is recorded and priced under the model id the ARN names (`us.anthropic.claude-haiku-4-5-20251001-v1:0`, `anthropic.claude-haiku-4-5-20251001-v1:0`), as the same call by that plain id is. A Claude call through an application inference profile ARN (`arn:aws:bedrock:<region>:<account>:application-inference-profile/<id>`) also needs `bedrock:GetInferenceProfile`, and one through a Provisioned Throughput ARN (`arn:aws:bedrock:<region>:<account>:provisioned-model/<id>`) needs `bedrock:GetProvisionedModelThroughput`, because neither ARN names the model: the SDK looks each ARN up once per process, in the background, starting at its first call, and from then on records and caps the call under the Claude model it runs. The lookup never delays your call: calls made before it answers, usually only the first in a process, are neither metered nor capped. The lookup uses the proxy, client certificate and CA bundle set on your boto3 client. A Provisioned Throughput call is recorded under its foundation model (for example `anthropic.claude-haiku-4-5-20251001-v1:0`), so the cost Revenium shows is the on-demand equivalent of its tokens, not the hourly price AWS bills, and a cost cap fills at that rate: a breached cost BLOCK cap can stop calls on capacity you have already paid for. Without the permission the call still goes through, unmetered and uncapped, and the SDK logs one warning per ARN. A lookup that fails for a temporary reason (an outage, a dropped connection, an expired session token) is retried every 5 minutes in the background. Profiles and Provisioned Throughputs that run a non-Claude model are not metered. A profile copied from a US or EU cross-Region profile is recorded and priced as that profile (for example `us.anthropic.claude-haiku-4-5-20251001-v1:0`), so its cost matches the regional rate AWS bills. A profile copied from an Australia, Japan, APAC, India or global cross-Region profile, or on a single Region, is recorded under the model id (`anthropic.claude-haiku-4-5-20251001-v1:0`). A cap on either id or on the Claude model name (`claude-haiku-4-5-20251001`) applies to the call. With cost controls on, a sync `AnthropicBedrock` call by an application inference profile ARN is also capped under the Claude model the profile routes to, using the same once-per-process lookup and the same `bedrock:GetInferenceProfile` permission; without the permission it is still metered but cannot be capped by model. A failed lookup is remembered only for the credentials that made it, so a client with the permission still looks the profile up and is metered and capped. An `AsyncAnthropicBedrock` call by a profile is capped that way once the profile has been looked up by a sync or raw boto3 call in the same process.
748
893
 
749
894
  **Supported Bedrock models:**
750
895
 
@@ -796,13 +941,13 @@ that Foundry bills at. `AsyncAnthropicFoundry` is metered the same way, as is
796
941
 
797
942
  ### Google AI (Gemini / Vertex AI)
798
943
 
799
- Supports chat completions, streaming, embeddings, image generation (Imagen), and vision/multimodal. Choose between Google AI SDK (simple API key setup) or Vertex AI SDK (production-grade with full token counting).
944
+ Supports chat completions, streaming, embeddings, image generation (Imagen), and vision/multimodal. The Google AI SDK (`google-genai`) is the recommended path for both the Gemini Developer API (API key) and Vertex AI (`genai.Client(vertexai=True, ...)`): it counts chat tokens on both, and embedding tokens on Vertex AI. The SDK still meters calls made through the Vertex AI SDK (`vertexai`), but Google deprecated that SDK's generative AI modules (`generative_models`, `language_models`, `vision_models`) and its releases after June 24, 2026 do not include them; see [Google's notice](https://cloud.google.com/vertex-ai/generative-ai/docs/deprecations/genai-vertexai-sdk). Use google-genai with `vertexai=True` for new work.
800
945
 
801
946
  ```bash
802
- # Google AI SDK only (Gemini Developer API)
947
+ # Google AI SDK (Gemini Developer API, or Vertex AI with vertexai=True)
803
948
  pip install "revenium-python-sdk[google-genai]"
804
949
 
805
- # Vertex AI SDK only (recommended for production)
950
+ # Vertex AI SDK (vertexai package)
806
951
  pip install "revenium-python-sdk[google-vertex]"
807
952
  ```
808
953
 
@@ -827,7 +972,21 @@ response = client.models.generate_content(
827
972
  print(response.text)
828
973
  ```
829
974
 
830
- #### Vertex AI SDK
975
+ The same call on Vertex AI, with the same metering:
976
+
977
+ ```python
978
+ client = genai.Client(vertexai=True, project="your-gcp-project", location="us-central1")
979
+ response = client.models.generate_content(
980
+ model="gemini-2.0-flash-001",
981
+ contents="Hello! Introduce yourself in one sentence.",
982
+ usage_metadata={"organizationName": "AcmeCorp", "task_type": "chat"}
983
+ )
984
+ print(response.text)
985
+ ```
986
+
987
+ #### Vertex AI SDK (deprecated by Google)
988
+
989
+ Google deprecated the generative AI modules of this SDK; see the notice above. Use the google-genai example above for new code.
831
990
 
832
991
  ```python
833
992
  from dotenv import load_dotenv
@@ -848,11 +1007,15 @@ print(response.text)
848
1007
  | Use Case | Recommended SDK | Why |
849
1008
  |----------|----------------|-----|
850
1009
  | Quick prototyping | Google AI SDK | Simple API key setup |
851
- | Production applications | Vertex AI SDK | Full token counting, enterprise features |
852
- | Embeddings-heavy workloads | Vertex AI SDK | Complete token tracking for embeddings |
853
- | Enterprise/GCP environments | Vertex AI SDK | Advanced Google Cloud integration |
1010
+ | Production applications | Google AI SDK with `vertexai=True` | Full token counting, including embeddings, on Vertex AI |
1011
+ | Embeddings-heavy workloads | Google AI SDK with `vertexai=True` | Vertex AI returns a token count for every embedded text |
1012
+ | Existing Vertex AI SDK code | Vertex AI SDK (deprecated by Google) | Still metered; migrate to google-genai with `vertexai=True` |
854
1013
 
855
- **Note:** Google AI SDK embeddings don't return token counts due to API limitations, but requests are still tracked.
1014
+ **Note:** On Vertex AI (`genai.Client(vertexai=True, ...)`) google-genai embeddings are recorded with the input tokens Google returns for every text. The Gemini API (API key) returns no token count for embeddings, so those calls are recorded with 0 tokens, and still tracked.
1015
+
1016
+ A `generate_content` or `generate_content_stream` call through the Google AI SDK (the Gemini API, or Vertex AI with `genai.Client(vertexai=True)`) that Google refuses (a 429 or 500, for example), sync, async or streamed, sends one record with stop reason `ERROR`, zero tokens and the error's class and HTTP status as its error reason; a stream that breaks off part-way is recorded with stop reason `ERROR` too. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer (a connection error, a timeout, or a stream that broke off) has none. Your code still gets Google's own exception. Embeddings, Imagen, Veo, calls made with the `vertexai` library and calls a spending cap refuses send no error record.
1017
+
1018
+ **Images from Gemini image models:** an image made with `generate_content` or `generate_content_stream` on a Gemini image model (for example `gemini-3.1-flash-lite-image`), through google-genai (the Gemini API, or `genai.Client(vertexai=True)`) or the `vertexai` library, sync, async or streamed, sends two records that share the call's trace, job and customer. An image record (operation type `IMAGE`, transaction id the chat record's plus `-image`) carries the number of images and is priced at the model's per-image price in Revenium; the chat record carries only the answer's text tokens, with the image tokens Google reports removed. Known limits: the per-image price is one fixed price per model, so 2K and 4K images are under-billed; interim "thought" images are not counted, only the final images are; when Google does not report the image's token share, the image tokens also stay on the chat record; a call that fails or a stream that breaks off is recorded as chat only. Gemini images made through LiteLLM (`gemini/...`), the LangChain unified handler fallback or griptape are still recorded as chat.
856
1019
 
857
1020
  **Google AI environment variables:**
858
1021
  - `GOOGLE_API_KEY` - For Google AI SDK
@@ -905,6 +1068,8 @@ response = ollama.embed(model='nomic-embed-text', input=['Text 1', 'Text 2', 'Te
905
1068
 
906
1069
  **Supported endpoints:** `chat()`, `generate()`, `embed()` and the legacy `embeddings()`, whether called at module level (`ollama.chat()`) or on an explicit client such as `ollama.Client(host="http://my-ollama:11434")` or `ollama.AsyncClient(...)`, streamed or not.
907
1070
 
1071
+ A `chat()` or `generate()` call the Ollama server refuses (a 500, for example), streamed or not, sends one record with stop reason `ERROR`, zero tokens and the error's class and HTTP status as its error reason; a stream that breaks off part-way is recorded with stop reason `ERROR` too. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer (a connection error, a timeout, or a stream that broke off) has none. Your code still gets Ollama's own exception. Embeddings and calls a spending cap refuses send no error record.
1072
+
908
1073
  **OpenAI compatibility mode:** You can also use Ollama with the OpenAI SDK:
909
1074
 
910
1075
  ```python
@@ -954,15 +1119,16 @@ response = litellm.completion(
954
1119
  )
955
1120
  ```
956
1121
 
957
- Client mode meters `completion`, `acompletion`, `text_completion`, `atext_completion`, `completion_with_retries` and `acompletion_with_retries`, streamed or not, and `embedding` / `aembedding` as embedding calls. When you stream without `stream_options={"include_usage": True}`, the middleware asks LiteLLM for the usage chunk itself and keeps it out of your stream. LiteLLM adds that chunk for every provider, including ones it does not send `stream_options` to. `litellm.responses` and `litellm.aresponses` are not metered, except on providers LiteLLM serves through `completion`.
1122
+ Client mode meters `completion`, `acompletion`, `text_completion`, `atext_completion`, `completion_with_retries` and `acompletion_with_retries`, streamed or not, and `embedding` / `aembedding` as embedding calls. When you stream without `stream_options={"include_usage": True}`, the middleware asks LiteLLM for the usage chunk itself and keeps it out of your stream. LiteLLM adds that chunk for every provider, including ones it does not send `stream_options` to. `litellm.responses` and `litellm.aresponses` are not metered, except on providers LiteLLM serves through `completion`. A completion that fails, or a stream that breaks off, sends one record with stop reason `ERROR`, zero tokens for a call that never started, and the error's class and HTTP status as its error reason (plus the provider's redacted error message when both `REVENIUM_CAPTURE_ERROR_MESSAGES` and `REVENIUM_CAPTURE_PROMPTS` are `true`; a provider's error can quote the request, so it is never sent with prompt capture off); your code still gets the original exception. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer (a connection error, a timeout, or a stream that broke off) has none. LiteLLM gives a connection error a 500 and a timeout a 408 that no server answered, so those get no error code and no HTTP status in their error reason, including the `InternalServerError` LiteLLM raises for a refused connection on its `openai/` and `anthropic/` providers. LiteLLM also raises a few real provider answers, such as a Vertex AI 502, as connection errors, and those get no error code either. Failure records sent by the LiteLLM gateway (proxy) do not carry the error code yet.
958
1123
 
959
- Inside a LiteLLM proxy running `ReveniumGuardrail` with `default_on: true` and `post_call` among its modes, client mode leaves each proxied request to the guardrail, so the request is recorded once, with the guardrail's subscriber and model naming. Client mode still records the proxied calls the guardrail does not meter, which today are streamed `/v1/completions` and `/v1/responses` calls, and every call your own code in the proxy's process makes to LiteLLM directly.
1124
+ Inside a LiteLLM proxy running `ReveniumGuardrail` with `default_on: true` and `post_call` among its modes, client mode leaves each proxied request to the guardrail, so the request is recorded once, with the guardrail's subscriber. The row names the deployment's model (the `litellm_params.model` behind the `model_name` your callers use, without its provider prefix), so a call to an alias is priced as the model it reached. The guardrail also meters streamed `/v1/responses` calls (Codex CLI, the OpenAI Agents SDK) for every provider. Client mode still records the proxied calls the guardrail does not meter, which today are streamed `/v1/completions` calls, and every call your own code in the proxy's process makes to LiteLLM directly.
960
1125
 
961
1126
  #### Proxy Mode
962
1127
 
963
1128
  `ReveniumGuardrail` is the LiteLLM proxy integration. It is a LiteLLM
964
1129
  `CustomGuardrail` that **enforces the caller's budget before** the proxied call and
965
- **meters usage after** it — successes, failures and streamed responses alike.
1130
+ **meters usage after** it: successes, failures and streamed responses alike,
1131
+ except calls a spending cap refuses.
966
1132
 
967
1133
  ```bash
968
1134
  pip install "revenium-python-sdk[litellm-proxy]" # requires Python 3.10+
@@ -985,14 +1151,21 @@ expects a different shape and exits the proxy at startup with
985
1151
  `GuardrailItem() argument after ** must be a mapping, not str`.
986
1152
 
987
1153
  `mode` must be a **list** to enable both hooks; a single string restricts the
988
- guardrail to that one event type. `pre_call` alone enforces without metering;
989
- `post_call` alone meters without enforcing.
1154
+ guardrail to that one event type. `pre_call` alone enforces without metering.
1155
+ `post_call` alone meters successful calls without enforcing, but records no failed
1156
+ calls: a failed call is recorded only for a request the Revenium guardrail's
1157
+ `pre_call` hook ran on, so a request LiteLLM refuses for a wrong or missing key
1158
+ sends no record. Adding `pre_call` enforces no budget unless
1159
+ `REVENIUM_CIRCUIT_BREAKER_ENABLED=true`.
990
1160
 
991
1161
  **Budget enforcement** reuses the SDK's own circuit breaker, so a proxy enforces
992
1162
  exactly what every other Revenium integration enforces — including department
993
- budgets. It is opt-in via `REVENIUM_CIRCUIT_BREAKER_ENABLED=true`; see
994
- [Cost Controls](#cost-controls). A blocked call never reaches the provider and the
995
- caller receives HTTP 429:
1163
+ budgets. An organization cap is checked against the organization the call names,
1164
+ which a caller can choose by header unless you pin it to the key's team (see
1165
+ "Organization caps and the organization header" below). It is opt-in via `REVENIUM_CIRCUIT_BREAKER_ENABLED=true`; see
1166
+ [Cost Controls](#cost-controls). A blocked call never reaches the provider, the
1167
+ caller receives HTTP 429, and no failed-call record is sent, as with the OpenAI and
1168
+ Anthropic integrations:
996
1169
 
997
1170
  ```json
998
1171
  {"error": {"message": "Request blocked by Revenium enforcement rule: Team Budget",
@@ -1001,6 +1174,8 @@ caller receives HTTP 429:
1001
1174
  "currentValue": 11.5, "resetsAt": "2026-10-01T00:00:00Z"}]}}
1002
1175
  ```
1003
1176
 
1177
+ When the rule carries a deny message, the body's `message` ends with it, as `BudgetExceededError.message` does (see [Exception Contract](#exception-contract)).
1178
+
1004
1179
  Enforcement **fails open**: if the enforcement path is unreachable or misbehaves,
1005
1180
  the call proceeds, and it proceeds without waiting. The pre-call check reads the
1006
1181
  rules the SDK already has cached and refreshes them on a background thread, so a
@@ -1018,7 +1193,51 @@ for reasoning effort), with the calling virtual key's metadata as the fallback
1018
1193
  `revenium_user_id`, `revenium_organization_name`, `revenium_key_name`, and
1019
1194
  `revenium_agentic_job_*`. Agentic job tags (`x-revenium-agentic-job-id`, `-name`,
1020
1195
  `-type`, `-version`) ride along for cost/ROI correlation; the job id is required for
1021
- the others to be recorded.
1196
+ the others to be recorded. A malformed header value, such as a quality score of
1197
+ `high` or an effort of `very high`, is left off the record with a WARNING in the
1198
+ gateway log; the call is still recorded.
1199
+
1200
+ **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.
1022
1241
 
1023
1242
  **Who made the call.** By default a proxied call is metered and budget-checked as the
1024
1243
  owner of the virtual key it used, which is right when every person has their own key.
@@ -1054,13 +1273,16 @@ reports the same value as the call's transaction id. Claude Code copies `request
1054
1273
  onto its own record, Revenium's duplicate check sees two records with one identifier,
1055
1274
  and one call becomes one record.
1056
1275
 
1057
- **It is on by default.** To opt out and keep LiteLLM's own response id as the
1058
- transaction id, with no `request-id` header added:
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):
1059
1279
 
1060
1280
  ```bash
1061
1281
  export REVENIUM_LITELLM_SHARED_CALL_ID=false
1062
1282
  ```
1063
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
+
1064
1286
  New calls go straight back to two records when you do; records already merged stay
1065
1287
  merged. Four things have to be true for it to work:
1066
1288
 
@@ -1122,6 +1344,11 @@ stays quiet.
1122
1344
  meters but never enforces a budget. It keeps working in this release and emits a
1123
1345
  `DeprecationWarning` (and a log line) when the proxy builds it.
1124
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
+
1125
1352
  To migrate, delete the callbacks entry and add the `guardrails` block above:
1126
1353
 
1127
1354
  ```diff
@@ -1162,10 +1389,12 @@ proxy running would be a logger with no pre-call hook and no ability to block a
1162
1389
  call — the enforcement half would silently not exist.
1163
1390
 
1164
1391
  So the client integration keeps its own path, unchanged: use
1165
- `revenium_middleware.litellm.client` as documented above. Note that the LiteLLM
1166
- client wrapper meters but does not currently run the pre-call circuit breaker —
1167
- enforcement in client mode is available today through the OpenAI middleware, and
1168
- through this guardrail in proxy mode. Both the guardrail and the client wrapper
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
1169
1398
  already share their metering plumbing (`revenium_middleware._core`: field
1170
1399
  extraction, cache-token extraction and `submit_ai_event`), so the guardrail adds no
1171
1400
  second copy of it.
@@ -1191,10 +1420,25 @@ The tracking decorators above support static values, extraction from function ar
1191
1420
  #### CrewAI Integration
1192
1421
 
1193
1422
  ```bash
1194
- pip install "revenium-python-sdk[litellm]" crewai
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
1195
1435
  ```
1196
1436
 
1197
- Pre-built wrapper for tracking CrewAI agent executions. **Note:** CrewAI requires Python 3.12 or earlier.
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.
1198
1442
 
1199
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).
1200
1444
 
@@ -1204,9 +1448,9 @@ from revenium_middleware.litellm.client.integrations.crewai import ReveniumCrewW
1204
1448
  crew = ReveniumCrewWrapper(
1205
1449
  agents=[support_agent],
1206
1450
  tasks=[triage_task],
1207
- organization_id="AcmeCorp",
1451
+ organization_name="AcmeCorp",
1208
1452
  subscription_id="82764738",
1209
- product_id="Platinum",
1453
+ product_name="Platinum",
1210
1454
  agentic_job_id="support-ticket-456",
1211
1455
  agentic_job_name="Support Ticket Triage",
1212
1456
  agentic_job_type="customer_support",
@@ -1268,11 +1512,14 @@ client = Perplexity(api_key=os.getenv("PERPLEXITY_API_KEY"))
1268
1512
 
1269
1513
  response = client.chat.completions.create(
1270
1514
  model="sonar",
1271
- messages=[{"role": "user", "content": "Hello!"}]
1515
+ messages=[{"role": "user", "content": "Hello!"}],
1516
+ usage_metadata={"organizationName": "AcmeCorp"}
1272
1517
  )
1273
1518
  ```
1274
1519
 
1275
- Both approaches work identically - the middleware automatically detects which SDK you're using.
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.
1276
1523
 
1277
1524
  **Streaming:**
1278
1525
 
@@ -1288,13 +1535,15 @@ for chunk in stream:
1288
1535
  print(chunk.choices[0].delta.content, end="", flush=True)
1289
1536
  ```
1290
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
+
1291
1540
  **Examples:** `examples/perplexity/` - `getting_started.py`, `basic.py`, `streaming.py`, `example_decorator.py`
1292
1541
 
1293
1542
  ---
1294
1543
 
1295
1544
  ### fal.ai
1296
1545
 
1297
- Supports image, video, and audio generation through fal.ai with automatic media type detection.
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.
1298
1547
 
1299
1548
  ```python
1300
1549
  import revenium_middleware.fal # Auto-activates
@@ -1316,10 +1565,14 @@ for image in result.get("images", []):
1316
1565
  print(f"Image URL: {image['url']}")
1317
1566
  ```
1318
1567
 
1319
- **Supported methods:** `run`, `subscribe`, `stream` and the queue flow (`submit`, then `status` and `result` or the handle's `get()`), on the module-level functions (`fal_client.run`, `fal_client.run_async`, and so on) and on clients you construct yourself (`fal_client.SyncClient(key=...)`, `fal_client.AsyncClient(key=...)`). Pass `usage_metadata` to `run`, `subscribe`, `stream` or `submit`.
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()`.
1320
1569
 
1321
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.
1322
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
+
1323
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.
1324
1577
 
1325
1578
  **Environment variables:**
@@ -1335,7 +1588,7 @@ Callback handler that automatically tracks LLM calls, chains, tools, and agent a
1335
1588
  pip install "revenium-python-sdk[langchain]"
1336
1589
  ```
1337
1590
 
1338
- Wrap any LangChain LLM (or embeddings model) with `wrap()` — the Revenium callback handler is attached for you:
1591
+ Wrap any LangChain chat model or LLM with `wrap()`; the Revenium callback handler is attached for you:
1339
1592
 
1340
1593
  ```python
1341
1594
  from langchain_openai import ChatOpenAI
@@ -1385,7 +1638,13 @@ llm = wrap(ChatOpenAI(model="gpt-4o-mini"))
1385
1638
  response = await llm.ainvoke("Hello!")
1386
1639
  ```
1387
1640
 
1388
- **Supported providers:** OpenAI, Anthropic, Google, AWS Bedrock, Azure OpenAI, Cohere, HuggingFace, Ollama. Provider is auto-detected from LangChain class name or model name prefix.
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.
1389
1648
 
1390
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)):
1391
1650
 
@@ -1395,11 +1654,52 @@ from revenium_middleware.openai.langchain import attach_to
1395
1654
  attach_to(llm, usage_metadata={
1396
1655
  "organizationName": "my_org",
1397
1656
  "productName": "my_product",
1398
- "subscriber": {"id": "user_123", "email": "user@example.com"},
1399
1657
  })
1400
1658
  ```
1401
1659
 
1402
- Credentials come from the standard environment variables (`REVENIUM_METERING_API_KEY`, `REVENIUM_METERING_BASE_URL`) or `revenium_middleware.configure()`.
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.
1403
1703
 
1404
1704
  ---
1405
1705
 
@@ -1419,19 +1719,32 @@ pip install "revenium-python-sdk[griptape,litellm,litellm-proxy]" # 100+ provid
1419
1719
  ```python
1420
1720
  import os
1421
1721
  from griptape.structures import Agent
1422
- from revenium_middleware.griptape import ReveniumDriver
1722
+ from revenium_middleware import BudgetExceededError
1723
+ from revenium_middleware.griptape import ReveniumDriver, enable_budget_errors
1423
1724
 
1424
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
1425
1727
 
1426
1728
  agent = Agent(prompt_driver=ReveniumDriver(
1427
1729
  model="gpt-4o-mini",
1428
1730
  usage_metadata={"task_type": "demo"},
1429
1731
  ))
1430
- agent.run("Hello!")
1732
+ try:
1733
+ agent.run("Hello!")
1734
+ except BudgetExceededError as e:
1735
+ print(f"Spending cap reached: {e.message}")
1431
1736
  ```
1432
1737
 
1433
1738
  Force a provider with `force_provider="litellm"`, or wrap an existing driver with `ReveniumDriver(base_driver=...)`.
1434
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
+
1435
1748
  **Embeddings:**
1436
1749
 
1437
1750
  ```python
@@ -1448,7 +1761,11 @@ driver = ReveniumEmbeddingDriver(model="text-embedding-3-large")
1448
1761
 
1449
1762
  ## Metadata Fields
1450
1763
 
1451
- Add business context to any API call by passing a `usage_metadata` dictionary. All fields are optional.
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.
1452
1769
 
1453
1770
  | Field | Description | Use Case |
1454
1771
  |-------|-------------|----------|
@@ -1497,10 +1814,9 @@ high-effort reasoning spend can be separated from the rest. It is a free-form
1497
1814
  string, not an enum -- vendor vocabularies differ and drift, so `low`, `medium`,
1498
1815
  `high`, `xhigh` and `ultra` are all real values, and a level this SDK release has
1499
1816
  never heard of is passed through untouched rather than rejected or rewritten. The
1500
- Revenium backend owns validation (at most 16 characters, matching
1501
- `^[A-Za-z0-9_-]+$`); a value it rejects fails the metering call visibly instead
1502
- of being silently dropped, so it surfaces in the log and in
1503
- `get_metering_status()`. It is distinct from the reported reasoning token count,
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,
1504
1820
  which measures the tokens actually spent rather than the level requested.
1505
1821
 
1506
1822
  Set it per call in `usage_metadata` on any provider integration. In LiteLLM proxy
@@ -1523,7 +1839,7 @@ Enhanced observability fields for tracking AI operations across environments, re
1523
1839
  |-------|----------------------------------|-------------|----------|
1524
1840
  | `environment` | `REVENIUM_ENVIRONMENT` (auto-detects: `ENVIRONMENT`, `DEPLOYMENT_ENV`) | Deployment environment | Track usage across `production`, `staging`, `dev` |
1525
1841
  | `region` | `REVENIUM_REGION` (auto-detects: `AWS_REGION`, `AZURE_REGION`, `GCP_REGION`) | Cloud region identifier | Multi-region deployment tracking and latency analysis |
1526
- | `credential_alias` | `REVENIUM_CREDENTIAL_ALIAS` | Human-readable API key name | Track which credential was used for rotation and auditing |
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 |
1527
1843
  | `trace_type` | `REVENIUM_TRACE_TYPE` | Workflow category (max 128 chars, alphanumeric/hyphens/underscores) | Group similar workflows (e.g., `"customer-support"`, `"data-analysis"`) |
1528
1844
  | `trace_name` | `REVENIUM_TRACE_NAME` | Human-readable trace label (max 256 chars) | Label trace instances (e.g., `"Customer Support Chat"`) |
1529
1845
  | `parent_transaction_id` | `REVENIUM_PARENT_TRANSACTION_ID` | Parent transaction ID | Link child operations to parents across microservices |
@@ -1538,7 +1854,7 @@ Enhanced observability fields for tracking AI operations across environments, re
1538
1854
  | `skill_marketplace_name` | `REVENIUM_SKILL_MARKETPLACE_NAME` | Marketplace the skill or plugin was installed from (max 256 chars) | Track marketplace-sourced skill usage |
1539
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 |
1540
1856
 
1541
- **Note:** `operation_type` (e.g., `CHAT`, `EMBED`, `TOOL_CALL`) and `operation_subtype` (e.g., `function_call`, `streaming`) are automatically detected by the middleware and cannot be overridden.
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`.
1542
1858
 
1543
1859
  ### Usage
1544
1860
 
@@ -1573,6 +1889,8 @@ response = client.chat.completions.create(
1573
1889
 
1574
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.
1575
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
+
1576
1894
  ### Distributed Tracing Example
1577
1895
 
1578
1896
  ```python
@@ -1635,8 +1953,8 @@ answer = handle_customer_query("How do I reset my password?")
1635
1953
  **Features:**
1636
1954
  - **DRY Principle**: Define metadata once, apply to all API calls in the function
1637
1955
  - **Composable**: Decorators can be nested - inner decorators inherit and override outer ones
1638
- - **API-level override**: `usage_metadata` passed directly to API calls always takes precedence over decorator metadata
1639
- - **Async support**: Works with both sync and async functions
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
1640
1958
  - **Thread-safe**: Uses `contextvars` for proper isolation
1641
1959
 
1642
1960
  **Nested decorators (metadata merging):**
@@ -1685,6 +2003,8 @@ Control which functions are metered when selective metering mode is enabled. Thi
1685
2003
 
1686
2004
  **Note:** This decorator only has an effect when `REVENIUM_SELECTIVE_METERING=true` is set. By default, all API calls are metered automatically.
1687
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
+
1688
2008
  ```bash
1689
2009
  # Enable selective metering
1690
2010
  export REVENIUM_SELECTIVE_METERING=true
@@ -1716,6 +2036,36 @@ def free_feature(prompt: str) -> str:
1716
2036
  - `"true"`, `"1"`, `"yes"`, `"on"` (case-insensitive) - Selective metering enabled
1717
2037
  - `"false"`, `"0"`, `"no"`, `"off"`, or unset - All calls metered (default)
1718
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
+
1719
2069
  **Decorator order matters:** Place `@revenium_meter` before `@revenium_metadata` (outer to inner).
1720
2070
 
1721
2071
  ---
@@ -1744,6 +2094,8 @@ def lookup_customer(customer_id: str) -> dict:
1744
2094
  result = lookup_customer("CUST-42")
1745
2095
  ```
1746
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
+
1747
2099
  **Manual reporting:**
1748
2100
 
1749
2101
  ```python
@@ -1758,6 +2110,8 @@ report_tool_call(
1758
2110
  )
1759
2111
  ```
1760
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
+
1761
2115
  ---
1762
2116
 
1763
2117
  ## Prompt Capture
@@ -1774,12 +2128,30 @@ export REVENIUM_CAPTURE_PROMPTS=true
1774
2128
 
1775
2129
  | Field | Description | Source |
1776
2130
  |-------|-------------|--------|
1777
- | `system_prompt` | System prompt content | From `system` parameter / system message |
1778
- | `input_messages` | User/assistant messages as JSON | From `messages` parameter |
1779
- | `output_response` | Assistant's response content | From response content blocks |
1780
- | `prompts_truncated` | Truncation flag | Set to `true` if any field exceeded 50,000 characters |
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.
1781
2153
 
1782
- Each field has a maximum length of **50,000 characters**. If exceeded, it's truncated with a `...[TRUNCATED]` marker.
2154
+ The Go and Node SDKs also read `REVENIUM_ORGANIZATION_ID`, `REVENIUM_ORGANIZATION_NAME` and `REVENIUM_PRINT_SUMMARY`; the Python SDK does not.
1783
2155
 
1784
2156
  ### Example
1785
2157
 
@@ -1804,6 +2176,10 @@ response = client.chat.completions.create(
1804
2176
 
1805
2177
  Prompt capture works with both streaming and non-streaming requests, and with multimodal content (text, images, etc.).
1806
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
+
1807
2183
  ### Security Considerations
1808
2184
 
1809
2185
  - Prompts may contain sensitive user data
@@ -1820,7 +2196,7 @@ Block outbound provider requests client-side when a Revenium cost control trips.
1820
2196
 
1821
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.
1822
2198
 
1823
- Currently wired for the OpenAI provider (other providers land via per-provider follow-on tickets).
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.
1824
2200
 
1825
2201
  ### Enable
1826
2202
 
@@ -1845,11 +2221,13 @@ REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream # optional
1845
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. |
1846
2222
  | `REVENIUM_CB_POLL_INTERVAL_SECONDS` | `60` | Background poll interval for rule refreshes. |
1847
2223
  | `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `BudgetExceededError` until rules are loaded. |
1848
- | `REVENIUM_CACHE_DIR` | — | When set, the rule cache is mirrored to `<dir>/revenium_enforcement_rules.json` so a restarted process doesn't fail-closed on the very first call. |
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.
1849
2227
 
1850
2228
  ### Public API
1851
2229
 
1852
- Enforcement auto-initializes when the OpenAI middleware loads:
2230
+ Enforcement starts with the first call any provider middleware checks, for example:
1853
2231
 
1854
2232
  ```python
1855
2233
  import revenium_middleware.openai # auto-instruments openai
@@ -1858,7 +2236,20 @@ import openai
1858
2236
  client = openai.OpenAI()
1859
2237
  ```
1860
2238
 
1861
- The pre-call check fires before every chat / embeddings / responses call. When the circuit breaker is disabled, it is a no-op. When enabled:
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:
1862
2253
 
1863
2254
  1. A daemon thread (`revenium-enforcement-poll`) starts on first use.
1864
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.
@@ -1866,13 +2257,17 @@ The pre-call check fires before every chat / embeddings / responses call. When t
1866
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.
1867
2258
  5. `204 No Content` is treated as "no rules configured" — the cache is cleared.
1868
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
+
1869
2264
  ### Exception Contract
1870
2265
 
1871
2266
  ```python
1872
- from revenium_middleware.openai import BudgetExceededError
2267
+ from revenium_middleware import BudgetExceededError
1873
2268
  ```
1874
2269
 
1875
- When a tripped rule matches the current request, the middleware raises before the OpenAI call is made. All structured fields are populated when the server provides them:
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:
1876
2271
 
1877
2272
  | Attribute | Type | Description |
1878
2273
  |-----------|------|-------------|
@@ -1882,11 +2277,29 @@ When a tripped rule matches the current request, the middleware raises before th
1882
2277
  | `threshold` | `float \| None` | Configured limit |
1883
2278
  | `resets_at` | `str \| None` | ISO-8601 timestamp the rule next resets |
1884
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.
1885
2285
 
1886
- `BudgetExceededError` does **not** inherit from `ReveniumMiddlewareError`, so the OpenAI middleware's `handle_exception_safely` decorator never swallows it — it always reaches your `except` block.
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:
1887
2289
 
1888
2290
  ```python
1889
- from revenium_middleware.openai import BudgetExceededError
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
1890
2303
  import openai
1891
2304
 
1892
2305
  client = openai.OpenAI()
@@ -1969,6 +2382,55 @@ revenium_middleware.initialize_metering(
1969
2382
  `initialize_metering()` returns `True` when metering is enabled after the
1970
2383
  call; invoke it with no arguments to re-read the environment.
1971
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
+
1972
2434
  ### Metering Delivery and Timeouts
1973
2435
 
1974
2436
  Usage records are never sent on your request path. A metered call puts its
@@ -1985,8 +2447,8 @@ a few idle threads and the queue's memory, never a thread per call.
1985
2447
  | `REVENIUM_METERING_CONNECT_TIMEOUT_SECONDS` | `5` | Seconds one attempt waits for a connection |
1986
2448
  | `REVENIUM_METERING_MAX_RETRIES` | `2` | Retries after the first attempt |
1987
2449
 
1988
- The two timeouts also apply to tool events, which are sent once without
1989
- retries, and a replay from the store-and-forward buffer is a single attempt
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
1990
2452
  that waits at most `REVENIUM_METERING_TIMEOUT_SECONDS`.
1991
2453
 
1992
2454
  Each thread sends one record at a time, so the threads keep up with about one
@@ -2061,7 +2523,7 @@ steps against one budget of `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` (5 seconds by
2061
2523
  default), each using whatever time the previous ones left: it waits for the
2062
2524
  background threads to send the records still queued, builds the records that
2063
2525
  overflowed to the store-and-forward buffer, then flushes the buffer, oldest
2064
- first and one attempt per record. Once a usage record or a tool event fails
2526
+ first, up to 32 records at a time, one attempt per record. Once a usage record or a tool event fails
2065
2527
  in a way worth retrying (unreachable, timed out, 429 or 5xx), the flush sends
2066
2528
  no more records of that kind, leaving them unsent, and keeps sending the other
2067
2529
  kind, since tool events can go to a different endpoint. Records still queued, being sent, unbuilt
@@ -2077,6 +2539,43 @@ replaces the SDK's. The flush then happens only if that handler exits
2077
2539
  normally: a handler that restores SIGTERM's default action and re-raises it,
2078
2540
  as uvicorn does after its own shutdown, ends the process before `atexit` runs.
2079
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
+
2080
2579
  ### Optional Environment Variables
2081
2580
 
2082
2581
  | Variable | Default | Description |
@@ -2084,24 +2583,26 @@ as uvicorn does after its own shutdown, ends the process before `atexit` runs.
2084
2583
  | `REVENIUM_METERING_BASE_URL` | `https://api.revenium.ai` | Revenium API endpoint |
2085
2584
  | `REVENIUM_LOG_LEVEL` | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
2086
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 |
2087
2587
  | `REVENIUM_SELECTIVE_METERING` | `false` | Only meter `@revenium_meter` decorated functions |
2088
2588
  | `REVENIUM_TEAM_ID` | - | Team ID for cost lookups and outcome reporting (JobContext team resolution) |
2089
2589
  | `REVENIUM_ENVIRONMENT` | - | Deployment environment (auto-detects from `ENVIRONMENT`, `DEPLOYMENT_ENV`) |
2090
2590
  | `REVENIUM_REGION` | - | Cloud region (auto-detects from `AWS_REGION`, `AZURE_REGION`, `GCP_REGION`) |
2091
- | `REVENIUM_CREDENTIAL_ALIAS` | - | Human-readable API key name |
2591
+ | `REVENIUM_CREDENTIAL_ALIAS` | - | Provider API key name, recorded as the subscriber's credential name on calls with no subscriber id or email |
2092
2592
  | `REVENIUM_TRACE_TYPE` | - | Workflow category identifier |
2093
2593
  | `REVENIUM_TRACE_NAME` | - | Human-readable trace label |
2094
2594
  | `REVENIUM_PARENT_TRANSACTION_ID` | - | Parent transaction ID for distributed tracing |
2095
2595
  | `REVENIUM_TRANSACTION_NAME` | - | Human-friendly operation name |
2096
2596
  | `REVENIUM_RETRY_NUMBER` | - | Retry attempt number |
2097
- | `REVENIUM_AGENTIC_JOB_ID` | - | Agentic job instance ID attached to all completions in the process (triggers backend job auto-creation) |
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`) |
2098
2598
  | `REVENIUM_AGENTIC_JOB_NAME` | - | Human-readable agentic job name |
2099
2599
  | `REVENIUM_AGENTIC_JOB_TYPE` | - | Agentic job type category |
2100
2600
  | `REVENIUM_AGENTIC_JOB_VERSION` | - | Agentic job version |
2101
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` |
2102
2602
  | `REVENIUM_OUTCOME_API_KEY` | - | Deprecated fallback name for the write-scope key; used only when `REVENIUM_WRITE_API_KEY` is unset |
2103
- | `REVENIUM_PROFITSTREAM_BASE_URL` | `https://api.revenium.io` | Agentic outcomes API base URL |
2104
- | `REVENIUM_BEDROCK_DISABLE` | - | Set to `1` to disable Bedrock auto-detection; Foundry detection is unaffected |
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 |
2105
2606
  | `REVENIUM_BUFFER_MAX_SIZE` | `20000` | Store-and-forward buffer capacity (oldest events evicted when full) |
2106
2607
  | `REVENIUM_BUFFER_FLUSH_INTERVAL` | `30` | Seconds between automatic replay attempts for buffered events |
2107
2608
  | `REVENIUM_METERING_WORKERS` | `32` | Background threads that send usage records (see [Metering Delivery and Timeouts](#metering-delivery-and-timeouts)) |
@@ -2112,6 +2613,8 @@ as uvicorn does after its own shutdown, ends the process before `atexit` runs.
2112
2613
  | `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` | `5` | Total seconds the exit hook may spend sending queued usage records, building overflowed ones and flushing the buffer |
2113
2614
  | `REVENIUM_INSTALL_SIGNAL_HANDLERS` | `false` | Set to `1` to flush metering before SIGTERM's default action ends the process (see [Shutdown](#shutdown)) |
2114
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
+
2115
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.
2116
2619
 
2117
2620
  ### Provider-Specific Environment Variables
@@ -2142,18 +2645,18 @@ Per-call `usage_metadata` values take precedence over the `REVENIUM_AGENTIC_JOB_
2142
2645
  | **No data in dashboard** | Enable debug logging with `REVENIUM_LOG_LEVEL=DEBUG` |
2143
2646
  | **Import errors** | Ensure the correct extra is installed (e.g., `pip install revenium-python-sdk[openai]`) |
2144
2647
  | **Azure: wrong model name** | Middleware auto-resolves deployment names; check with debug logging |
2145
- | **Bedrock: AccessDenied** | Ensure `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` permissions |
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` |
2146
2649
  | **Bedrock: requests go to Anthropic** | Verify AWS credentials: `aws sts get-caller-identity` |
2147
- | **Google: embeddings show 0 tokens** | Expected with Google AI SDK; use Vertex AI for full token counting |
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 |
2148
2651
  | **Google: "No module named 'vertexai'"** | Install correct extra: `pip install "revenium-python-sdk[google-vertex]"` |
2149
2652
  | **Vertex AI: authentication errors** | Run `gcloud auth application-default login` |
2150
2653
  | **Ollama: connection errors** | Ensure Ollama is running: `ollama serve` |
2151
2654
  | **LangChain: provider shows "unknown"** | Ensure you're using a supported LangChain LLM class |
2152
2655
  | **Streaming errors** | Check provider credentials; middleware auto-falls back gracefully |
2153
2656
 
2154
- **Debug mode:** Set `REVENIUM_LOG_LEVEL=DEBUG` to see detailed provider detection, routing decisions, and metering payloads.
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.
2155
2658
 
2156
- **Force direct Anthropic API (instead of Bedrock):** Set `REVENIUM_BEDROCK_DISABLE=1` to disable Bedrock auto-detection. Foundry detection is unaffected - a Foundry client is still labelled `Foundry`.
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.
2157
2660
 
2158
2661
  **Check initialization status (Anthropic):** Use `revenium_middleware.anthropic.is_initialized()` to verify setup.
2159
2662
 
@@ -2178,6 +2681,8 @@ Available log levels:
2178
2681
  - `ERROR`: Error messages only
2179
2682
  - `CRITICAL`: Critical error messages only
2180
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
+
2181
2686
  ## Compatibility
2182
2687
 
2183
2688
  - Python 3.8+