revenium-python-sdk 0.9.0__tar.gz → 0.9.2__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 (171) hide show
  1. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/PKG-INFO +163 -22
  2. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/README.md +155 -21
  3. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/pyproject.toml +10 -1
  4. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/__init__.py +12 -4
  5. revenium_python_sdk-0.9.2/revenium_middleware/_core/call_ownership.py +229 -0
  6. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/config.py +36 -1
  7. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/context.py +16 -13
  8. revenium_python_sdk-0.9.2/revenium_middleware/_core/delivery_circuit.py +93 -0
  9. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/enforcement.py +262 -122
  10. revenium_python_sdk-0.9.2/revenium_middleware/_core/metering.py +370 -0
  11. revenium_python_sdk-0.9.2/revenium_middleware/_core/metering_buffer.py +1048 -0
  12. revenium_python_sdk-0.9.2/revenium_middleware/_core/metering_pool.py +428 -0
  13. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/metering_status.py +20 -4
  14. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/metering_submission.py +23 -7
  15. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/patch_registry.py +5 -0
  16. revenium_python_sdk-0.9.2/revenium_middleware/_core/shutdown_signals.py +87 -0
  17. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/decorator.py +26 -13
  18. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/anthropic/middleware.py +257 -292
  19. revenium_python_sdk-0.9.2/revenium_middleware/anthropic/raw_response.py +215 -0
  20. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/fal/__init__.py +5 -2
  21. revenium_python_sdk-0.9.2/revenium_middleware/fal/_call.py +62 -0
  22. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/fal/_metering.py +3 -2
  23. revenium_python_sdk-0.9.2/revenium_middleware/fal/_queue.py +89 -0
  24. revenium_python_sdk-0.9.2/revenium_middleware/fal/middleware.py +169 -0
  25. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/__init__.py +1 -10
  26. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/common/utils.py +9 -3
  27. revenium_python_sdk-0.9.2/revenium_middleware/google/google_ai/middleware.py +659 -0
  28. revenium_python_sdk-0.9.2/revenium_middleware/google/vertex_ai/middleware.py +1052 -0
  29. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/client/__init__.py +2 -1
  30. revenium_python_sdk-0.9.2/revenium_middleware/litellm/client/middleware.py +565 -0
  31. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/proxy/_metering_owner.py +24 -0
  32. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/proxy/guardrail.py +125 -14
  33. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/proxy/middleware.py +31 -4
  34. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/ollama/__init__.py +8 -5
  35. revenium_python_sdk-0.9.2/revenium_middleware/ollama/middleware.py +485 -0
  36. revenium_python_sdk-0.9.2/revenium_middleware/openai/langchain/_model_call.py +109 -0
  37. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/langchain/unified_handler.py +85 -12
  38. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/middleware.py +485 -427
  39. revenium_python_sdk-0.9.2/revenium_middleware/perplexity/_metering_scope.py +7 -0
  40. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/perplexity/middleware.py +72 -92
  41. revenium_python_sdk-0.9.2/revenium_middleware/perplexity/patching.py +27 -0
  42. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/perplexity/perplexity_sdk.py +64 -109
  43. revenium_python_sdk-0.9.2/revenium_middleware/perplexity/streaming.py +138 -0
  44. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_python_sdk.egg-info/PKG-INFO +163 -22
  45. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_python_sdk.egg-info/SOURCES.txt +15 -1
  46. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_python_sdk.egg-info/requires.txt +7 -0
  47. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/tests/test_metering.py +14 -14
  48. revenium_python_sdk-0.9.2/tests/test_metering_dispatch_timestamps.py +270 -0
  49. revenium_python_sdk-0.9.2/tests/test_patch_coverage.py +448 -0
  50. revenium_python_sdk-0.9.2/tests/test_release_verify_ticket.py +257 -0
  51. revenium_python_sdk-0.9.0/revenium_middleware/_core/metering.py +0 -323
  52. revenium_python_sdk-0.9.0/revenium_middleware/_core/metering_buffer.py +0 -367
  53. revenium_python_sdk-0.9.0/revenium_middleware/fal/middleware.py +0 -234
  54. revenium_python_sdk-0.9.0/revenium_middleware/google/google_ai/middleware.py +0 -652
  55. revenium_python_sdk-0.9.0/revenium_middleware/google/vertex_ai/middleware.py +0 -1189
  56. revenium_python_sdk-0.9.0/revenium_middleware/litellm/client/middleware.py +0 -283
  57. revenium_python_sdk-0.9.0/revenium_middleware/ollama/middleware.py +0 -487
  58. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/LICENSE +0 -0
  59. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/__init__.py +0 -0
  60. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/cache_tokens.py +0 -0
  61. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/decorators.py +0 -0
  62. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/exceptions.py +0 -0
  63. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/fields.py +0 -0
  64. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/load_diagnostics.py +0 -0
  65. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/log_sanitize.py +0 -0
  66. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/outcomes.py +0 -0
  67. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/prompt_extraction.py +0 -0
  68. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/subscriber.py +0 -0
  69. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_core/trace_fields.py +0 -0
  70. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/LICENSE +0 -0
  71. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/__init__.py +0 -0
  72. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_base_client.py +0 -0
  73. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_client.py +0 -0
  74. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_compat.py +0 -0
  75. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_constants.py +0 -0
  76. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_exceptions.py +0 -0
  77. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_files.py +0 -0
  78. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_models.py +0 -0
  79. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_qs.py +0 -0
  80. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_resource.py +0 -0
  81. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_response.py +0 -0
  82. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_streaming.py +0 -0
  83. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_types.py +0 -0
  84. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_utils/__init__.py +0 -0
  85. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_utils/_logs.py +0 -0
  86. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_utils/_proxy.py +0 -0
  87. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_utils/_reflection.py +0 -0
  88. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_utils/_resources_proxy.py +0 -0
  89. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_utils/_streams.py +0 -0
  90. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_utils/_sync.py +0 -0
  91. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_utils/_transform.py +0 -0
  92. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_utils/_typing.py +0 -0
  93. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_utils/_utils.py +0 -0
  94. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/_version.py +0 -0
  95. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/context.py +0 -0
  96. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/py.typed +0 -0
  97. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/resources/__init__.py +0 -0
  98. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/resources/ai.py +0 -0
  99. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/resources/apis.py +0 -0
  100. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/resources/events.py +0 -0
  101. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/types/__init__.py +0 -0
  102. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/types/ai_create_audio_params.py +0 -0
  103. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/types/ai_create_completion_params.py +0 -0
  104. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/types/ai_create_image_params.py +0 -0
  105. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/types/ai_create_video_params.py +0 -0
  106. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/types/api_meter_request_params.py +0 -0
  107. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/types/api_meter_response_params.py +0 -0
  108. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/types/event_create_params.py +0 -0
  109. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/_metering/types/metering_response_resource.py +0 -0
  110. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/agentic_outcomes.py +0 -0
  111. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/anthropic/__init__.py +0 -0
  112. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/anthropic/bedrock_adapter.py +0 -0
  113. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/anthropic/bedrock_transport.py +0 -0
  114. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/anthropic/config.py +0 -0
  115. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/anthropic/prompt_extractor.py +0 -0
  116. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/anthropic/provider.py +0 -0
  117. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/anthropic/stream_create.py +0 -0
  118. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/anthropic/trace_fields.py +0 -0
  119. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/fal/config.py +0 -0
  120. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/fal/trace_fields.py +0 -0
  121. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/common/__init__.py +0 -0
  122. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/common/exceptions.py +0 -0
  123. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/common/protocols.py +0 -0
  124. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/common/trace_fields.py +0 -0
  125. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/common/types.py +0 -0
  126. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/config.py +0 -0
  127. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/google_ai/__init__.py +0 -0
  128. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/google_ai/provider.py +0 -0
  129. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/prompt_extractor.py +0 -0
  130. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/vertex_ai/__init__.py +0 -0
  131. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/google/vertex_ai/provider.py +0 -0
  132. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/griptape/__init__.py +0 -0
  133. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/griptape/_metadata.py +0 -0
  134. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/griptape/anthropic_driver.py +0 -0
  135. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/griptape/litellm_driver.py +0 -0
  136. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/griptape/ollama_driver.py +0 -0
  137. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/griptape/openai_driver.py +0 -0
  138. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/griptape/openai_embedding_driver.py +0 -0
  139. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/griptape/universal_driver.py +0 -0
  140. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/job_context.py +0 -0
  141. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/job_history.py +0 -0
  142. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/job_type_economics.py +0 -0
  143. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/__init__.py +0 -0
  144. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/client/config.py +0 -0
  145. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/client/context.py +0 -0
  146. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/client/decorators.py +0 -0
  147. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/client/hooks.py +0 -0
  148. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/client/integrations/__init__.py +0 -0
  149. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/client/integrations/crewai.py +0 -0
  150. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/client/trace_fields.py +0 -0
  151. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/client/validation.py +0 -0
  152. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/litellm/proxy/__init__.py +0 -0
  153. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/ollama/trace_fields.py +0 -0
  154. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/__init__.py +0 -0
  155. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/azure_config.py +0 -0
  156. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/azure_model_resolver.py +0 -0
  157. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/config.py +0 -0
  158. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/exceptions.py +0 -0
  159. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/langchain/__init__.py +0 -0
  160. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/langchain/_utils.py +0 -0
  161. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/prompt_extractor.py +0 -0
  162. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/provider.py +0 -0
  163. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/openai/trace_fields.py +0 -0
  164. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/perplexity/__init__.py +0 -0
  165. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/perplexity/provider.py +0 -0
  166. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/perplexity/trace_fields.py +0 -0
  167. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/webhooks/__init__.py +0 -0
  168. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_middleware/webhooks/_verify.py +0 -0
  169. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_python_sdk.egg-info/dependency_links.txt +0 -0
  170. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/revenium_python_sdk.egg-info/top_level.txt +0 -0
  171. {revenium_python_sdk-0.9.0 → revenium_python_sdk-0.9.2}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: revenium-python-sdk
3
- Version: 0.9.0
3
+ Version: 0.9.2
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
@@ -93,6 +93,13 @@ Requires-Dist: anthropic>=0.30.0; extra == "dev"
93
93
  Requires-Dist: boto3; extra == "dev"
94
94
  Requires-Dist: ollama>=0.3.0; extra == "dev"
95
95
  Requires-Dist: griptape<2.0.0,>=1.0.0; python_version >= "3.10" and extra == "dev"
96
+ Requires-Dist: langchain-anthropic; python_version >= "3.10" and extra == "dev"
97
+ Requires-Dist: openai>=1.0.0; extra == "dev"
98
+ Requires-Dist: litellm>=1.40.0; extra == "dev"
99
+ Requires-Dist: fal-client>=0.13.0; extra == "dev"
100
+ Requires-Dist: perplexityai>=0.1.0; extra == "dev"
101
+ Requires-Dist: google-genai>=0.1.0; extra == "dev"
102
+ Requires-Dist: pyyaml; extra == "dev"
96
103
  Dynamic: license-file
97
104
 
98
105
  # Revenium Python SDK
@@ -115,8 +122,8 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
115
122
  - **Prompt Capture**: Optional capture of prompts and responses for analytics and debugging
116
123
  - **Terminal Summary**: Real-time cost and usage summaries in your terminal (human-readable or JSON)
117
124
  - **Distributed Tracing**: Built-in trace visualization fields for cross-service observability
118
- - **Asynchronous Processing**: Background thread management for non-blocking metering operations
119
- - **Graceful Shutdown**: Ensures all metering data is properly sent even during application shutdown
125
+ - **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
120
127
  - **Thread-Safe**: Production-ready with `contextvars`-based context management for concurrent applications
121
128
 
122
129
  ## Supported Providers
@@ -248,6 +255,7 @@ print(status.success_count) # events delivered successfully
248
255
  print(status.error_count) # delivery failures
249
256
  print(status.last_error) # most recent exception, or None
250
257
  print(status.last_error_at) # UTC datetime of the most recent failure
258
+ print(status.evicted_count) # undelivered events dropped because the buffer was full
251
259
  ```
252
260
 
253
261
  `reset_metering_status()` zeroes the counters and clears registered
@@ -788,7 +796,7 @@ that Foundry bills at. `AsyncAnthropicFoundry` is metered the same way, as is
788
796
 
789
797
  ### Google AI (Gemini / Vertex AI)
790
798
 
791
- Supports chat completions, streaming, embeddings, image generation (Imagen), video generation, and vision/multimodal. Choose between Google AI SDK (simple API key setup) or Vertex AI SDK (production-grade with full token counting).
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).
792
800
 
793
801
  ```bash
794
802
  # Google AI SDK only (Gemini Developer API)
@@ -895,7 +903,7 @@ response = ollama.embed(model='nomic-embed-text', input='Hello world')
895
903
  response = ollama.embed(model='nomic-embed-text', input=['Text 1', 'Text 2', 'Text 3'])
896
904
  ```
897
905
 
898
- **Supported endpoints:** `ollama.chat()`, `ollama.generate()`, `ollama.embed()`
906
+ **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.
899
907
 
900
908
  **OpenAI compatibility mode:** You can also use Ollama with the OpenAI SDK:
901
909
 
@@ -946,6 +954,10 @@ response = litellm.completion(
946
954
  )
947
955
  ```
948
956
 
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`.
958
+
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.
960
+
949
961
  #### Proxy Mode
950
962
 
951
963
  `ReveniumGuardrail` is the LiteLLM proxy integration. It is a LiteLLM
@@ -978,7 +990,7 @@ guardrail to that one event type. `pre_call` alone enforces without metering;
978
990
 
979
991
  **Budget enforcement** reuses the SDK's own circuit breaker, so a proxy enforces
980
992
  exactly what every other Revenium integration enforces — including department
981
- (org-unit) budgets. It is opt-in via `REVENIUM_CIRCUIT_BREAKER_ENABLED=true`; see
993
+ budgets. It is opt-in via `REVENIUM_CIRCUIT_BREAKER_ENABLED=true`; see
982
994
  [Cost Controls](#cost-controls). A blocked call never reaches the provider and the
983
995
  caller receives HTTP 429:
984
996
 
@@ -990,8 +1002,15 @@ caller receives HTTP 429:
990
1002
  ```
991
1003
 
992
1004
  Enforcement **fails open**: if the enforcement path is unreachable or misbehaves,
993
- the call proceeds. Metering is likewise non-disruptive — nothing in the post-call
994
- path can turn a successful LLM call into an error for the client.
1005
+ the call proceeds, and it proceeds without waiting. The pre-call check reads the
1006
+ rules the SDK already has cached and refreshes them on a background thread, so a
1007
+ Revenium endpoint that hangs, refuses connections, returns errors or rejects your
1008
+ key (403) neither blocks nor slows the proxy. A failed refresh is retried once
1009
+ per `REVENIUM_CB_POLL_INTERVAL_SECONDS`, not once per request. Right after the
1010
+ proxy starts, before the first rules fetch completes, no rules are cached and
1011
+ calls go through; see [Fail-Open vs Fail-Closed](#fail-open-vs-fail-closed).
1012
+ Metering is likewise non-disruptive — nothing in the post-call path can turn a
1013
+ successful LLM call into an error for the client.
995
1014
 
996
1015
  **Attribution** travels as `x-revenium-*` request headers (subscriber, organization,
997
1016
  product, trace, task type, agent, subscription, quality score, and `x-revenium-effort`
@@ -1001,6 +1020,27 @@ for reasoning effort), with the calling virtual key's metadata as the fallback
1001
1020
  `-type`, `-version`) ride along for cost/ROI correlation; the job id is required for
1002
1021
  the others to be recorded.
1003
1022
 
1023
+ **Who made the call.** By default a proxied call is metered and budget-checked as the
1024
+ owner of the virtual key it used, which is right when every person has their own key.
1025
+ When several people share one key, have each client send
1026
+ `x-revenium-subscriber-email` (and optionally `x-revenium-subscriber-id`) naming the
1027
+ person making the call. Per-person and department budgets are looked up by that email,
1028
+ so without it a shared key's calls all count against its owner, and a blocked
1029
+ developer keeps getting through on the owner's budget. A call that sends someone
1030
+ else's email without an id carries no id at all, rather than the key's
1031
+ `revenium_user_id`, so it is checked against that person's balance and not the owner's. The captured header wins over a
1032
+ copy of the same key in the request's `metadata`; a blank value is ignored. Both are
1033
+ taken as the caller sends them: a shared key trusts its users to name themselves. On
1034
+ a team with strict ingestion enabled, the email must belong to a registered user, or
1035
+ the call's metering row is rejected instead of falling back to the key owner.
1036
+
1037
+ ```bash
1038
+ curl http://localhost:4000/v1/messages \
1039
+ -H "x-api-key: sk-shared-team-key" \
1040
+ -H "x-revenium-subscriber-email: dev@acme.com" \
1041
+ ...
1042
+ ```
1043
+
1004
1044
  ##### Counting a Claude Code call once (shared call id)
1005
1045
 
1006
1046
  If you run Claude Code through your proxy **and** point Claude Code's own usage
@@ -1276,7 +1316,9 @@ for image in result.get("images", []):
1276
1316
  print(f"Image URL: {image['url']}")
1277
1317
  ```
1278
1318
 
1279
- **Supported methods:** `fal_client.run`, `fal_client.subscribe`, `fal_client.stream` (and their async variants: `run_async`, `subscribe_async`, `stream_async`)
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`.
1320
+
1321
+ **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.
1280
1322
 
1281
1323
  **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.
1282
1324
 
@@ -1820,8 +1862,9 @@ The pre-call check fires before every chat / embeddings / responses call. When t
1820
1862
 
1821
1863
  1. A daemon thread (`revenium-enforcement-poll`) starts on first use.
1822
1864
  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.
1823
- 3. Rules are cached in-process (120 s TTL, refresh-on-stale with thundering-herd guard).
1824
- 4. `204 No Content` is treated as "no rules configured" — the cache is cleared.
1865
+ 3. Rules are cached in-process. The pre-call check only reads that cache: it never makes a network request and never sleeps, so it is safe on an event loop (LiteLLM proxy, `AsyncOpenAI`). When the cache is more than 120 s old the check wakes the poller to refresh it early and carries on with the rules it has. Only one refresh runs at a time per process.
1866
+ 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
+ 5. `204 No Content` is treated as "no rules configured" — the cache is cleared.
1825
1868
 
1826
1869
  ### Exception Contract
1827
1870
 
@@ -1860,9 +1903,9 @@ except BudgetExceededError as exc:
1860
1903
 
1861
1904
  ### Fail-Open vs Fail-Closed
1862
1905
 
1863
- By default (`REVENIUM_CB_FAIL_MODE=open`) enforcement failures never propagate to user code. If the rule fetch errors (network, 5xx, auth), the previous in-memory cache is preserved and a debug log line is emitted. If there is no cache yet, enforcement behaves as if no rules are configured and the request continues.
1906
+ By default (`REVENIUM_CB_FAIL_MODE=open`) enforcement failures never propagate to user code and never delay it. If the rule fetch errors (network, 5xx, auth), the previous in-memory cache is preserved, a warning is logged, and the next attempt waits one poll interval. If there is no cache yet — the first moments after a process starts, or the whole of an outage that began before the first successful fetch — enforcement behaves as if no rules are configured and the request continues immediately; it does not wait for the fetch.
1864
1907
 
1865
- Set `REVENIUM_CB_FAIL_MODE=closed` to refuse calls until at least one rule fetch (or `REVENIUM_CACHE_DIR` snapshot) succeeds. Pair with `REVENIUM_CACHE_DIR` so a process restart loads the last-known rules rather than blocking every call until the first poll completes.
1908
+ Set `REVENIUM_CB_FAIL_MODE=closed` to refuse calls until at least one rule fetch (or `REVENIUM_CACHE_DIR` snapshot) succeeds. The refusal is immediate too: a call made before the first fetch completes raises `BudgetExceededError` rather than waiting for it. Pair with `REVENIUM_CACHE_DIR` so a process restart loads the last-known rules rather than refusing every call until the first poll completes.
1866
1909
 
1867
1910
  ### Shadow Mode
1868
1911
 
@@ -1926,22 +1969,113 @@ revenium_middleware.initialize_metering(
1926
1969
  `initialize_metering()` returns `True` when metering is enabled after the
1927
1970
  call; invoke it with no arguments to re-read the environment.
1928
1971
 
1972
+ ### Metering Delivery and Timeouts
1973
+
1974
+ Usage records are never sent on your request path. A metered call puts its
1975
+ record on a bounded in-process queue and returns at once; a fixed pool of
1976
+ background threads sends queued records to Revenium. The number of threads
1977
+ does not grow with traffic, so a slow or unreachable metering endpoint costs
1978
+ a few idle threads and the queue's memory, never a thread per call.
1979
+
1980
+ | Variable | Default | What it sets |
1981
+ |----------|---------|--------------|
1982
+ | `REVENIUM_METERING_WORKERS` | `32` | Background threads that send records |
1983
+ | `REVENIUM_METERING_QUEUE_SIZE` | `1000` | Records that can wait for a thread |
1984
+ | `REVENIUM_METERING_TIMEOUT_SECONDS` | `10` | Seconds one attempt waits for a response |
1985
+ | `REVENIUM_METERING_CONNECT_TIMEOUT_SECONDS` | `5` | Seconds one attempt waits for a connection |
1986
+ | `REVENIUM_METERING_MAX_RETRIES` | `2` | Retries after the first attempt |
1987
+
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
1990
+ that waits at most `REVENIUM_METERING_TIMEOUT_SECONDS`.
1991
+
1992
+ Each thread sends one record at a time, so the threads keep up with about one
1993
+ record per thread per round trip to Revenium. The 32 default threads send
1994
+ about 100 records a second at a 300 ms round trip and keep up with 30 a
1995
+ second until a round trip takes about a second. Measured against a local
1996
+ endpoint answering in 250 ms and 300 ms, 30 calls a second for five minutes
1997
+ delivered every record within 0.35 seconds of the call, and so did 60
1998
+ records a second at 250 ms (a service that sends two records per call).
1999
+ From one client in Brazil to a US East Revenium API host, a request on an
2000
+ open connection took 113 ms (p50) and 123 ms (p99), and one that also opened
2001
+ the connection 333 ms and 462 ms;
2002
+ measure from your own region before sizing for a slower path. Idle, the 32
2003
+ threads cost about 1.4 MB of memory. Raise `REVENIUM_METERING_WORKERS` for a
2004
+ service that meters more than 30 records a second against a slow round trip;
2005
+ the queue absorbs short bursts. When the queue is full, new records go
2006
+ straight to the store-and-forward buffer below instead of waiting, and
2007
+ `get_buffer_stats()["total_overflowed"]` counts them; one warning marks the
2008
+ start of each such episode and one, with a count, its end.
2009
+
2010
+ When Revenium stops answering, the threads stop waiting on it. After three
2011
+ records in a row fail with a retryable error, new records go straight to the
2012
+ store-and-forward buffer without being sent, and one record every 5 seconds
2013
+ is still sent to find out whether Revenium is back. The first one that
2014
+ succeeds resumes sending and starts replaying the buffer at once. A warning
2015
+ marks each change. Tool events from `@meter_tool` and `report_tool_call` are
2016
+ not held back: `configure()` can send them to another endpoint, so they keep
2017
+ being sent, and the buffer replays them even while the AI records ahead of
2018
+ them are still failing.
2019
+
2020
+ At exit, queued records get the first share of the shutdown budget (see
2021
+ [Shutdown](#shutdown)).
2022
+
1929
2023
  ### Delivery Resilience (Store-and-Forward)
1930
2024
 
1931
2025
  Metering events that still fail after the client's own retries (network
1932
- outages, 5xx, rate limiting) are not lost: they are held in a bounded
1933
- in-memory buffer and replayed automatically in the background every 30
1934
- seconds, reusing each event's original `Idempotency-Key` so replays can
1935
- never double-bill. Permanent failures (401/403/404/422) are never buffered.
1936
- The buffer holds up to 1000 events (oldest evicted first) for at most 24
1937
- hours, and is drained on graceful shutdown. Inspect it programmatically:
2026
+ outages, 5xx, rate limiting), and the records held back while Revenium is not
2027
+ answering, are not lost: they are held in a bounded in-memory buffer and
2028
+ replayed automatically in the background every 30 seconds, or as soon as a
2029
+ delivery succeeds again, reusing each event's original `Idempotency-Key` so
2030
+ replays can never double-bill. A backlog replays 16 records at a time, about
2031
+ 50 a second at a 300 ms round trip next to your live traffic. Permanent
2032
+ failures (401/403/404/422) are never buffered, and buffered events expire
2033
+ after 24 hours. The buffer is drained on shutdown (see below).
2034
+
2035
+ The buffer holds up to 20,000 events, eleven minutes of an outage at 30
2036
+ records a second. A typical LiteLLM record takes about 2.3 KB in memory, so a
2037
+ full buffer holds about 45 MB; with `REVENIUM_CAPTURE_PROMPTS` each record
2038
+ can also carry up to 50,000 characters per captured prompt field, so lower
2039
+ `REVENIUM_BUFFER_MAX_SIZE` if you capture prompts. In a five-minute outage at
2040
+ 30 calls a second against the defaults, all 9,000 records were held and then
2041
+ delivered within two and a half minutes of Revenium answering again, while
2042
+ new traffic kept flowing. When the buffer is full the oldest
2043
+ events are evicted and their usage is lost: one warning marks the first
2044
+ eviction, the flush thread logs how many were evicted at most once per flush
2045
+ interval, and `get_metering_status().evicted_count` and
2046
+ `get_buffer_stats()["total_evicted"]` count them. Inspect it programmatically:
1938
2047
 
1939
2048
  ```python
1940
2049
  from revenium_middleware import get_buffer_stats
1941
2050
 
1942
2051
  print(get_buffer_stats())
1943
- # {'size': 0, 'max_size': 1000, 'total_buffered': 3, 'total_replayed': 3, ...}
1944
- ```
2052
+ # {'size': 0, 'max_size': 20000, 'total_buffered': 3, 'total_replayed': 3, 'total_evicted': 0, ...}
2053
+ ```
2054
+
2055
+ ### Shutdown
2056
+
2057
+ The SDK does not install signal handlers: SIGTERM and SIGINT reach your
2058
+ application or server exactly as they would without it. When the interpreter
2059
+ exits normally, including after Ctrl+C, an `atexit` hook works through three
2060
+ steps against one budget of `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` (5 seconds by
2061
+ default), each using whatever time the previous ones left: it waits for the
2062
+ background threads to send the records still queued, builds the records that
2063
+ 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
2065
+ in a way worth retrying (unreachable, timed out, 429 or 5xx), the flush sends
2066
+ no more records of that kind, leaving them unsent, and keeps sending the other
2067
+ kind, since tool events can go to a different endpoint. Records still queued, being sent, unbuilt
2068
+ or unsent at the end are dropped and logged once, as a warning with a count.
2069
+
2070
+ A process ended by SIGTERM's default action skips `atexit`, and with it that
2071
+ final flush. uvicorn, and so the LiteLLM proxy, ends that way once its own
2072
+ graceful shutdown has finished. For a script or worker with no SIGTERM handling
2073
+ of its own, set `REVENIUM_INSTALL_SIGNAL_HANDLERS=1`: SIGTERM then flushes
2074
+ first and ends the process the same way. A SIGTERM handler your code installed
2075
+ before importing the SDK is called unchanged, and one installed afterwards
2076
+ replaces the SDK's. The flush then happens only if that handler exits
2077
+ normally: a handler that restores SIGTERM's default action and re-raises it,
2078
+ as uvicorn does after its own shutdown, ends the process before `atexit` runs.
1945
2079
 
1946
2080
  ### Optional Environment Variables
1947
2081
 
@@ -1968,8 +2102,15 @@ print(get_buffer_stats())
1968
2102
  | `REVENIUM_OUTCOME_API_KEY` | - | Deprecated fallback name for the write-scope key; used only when `REVENIUM_WRITE_API_KEY` is unset |
1969
2103
  | `REVENIUM_PROFITSTREAM_BASE_URL` | `https://api.revenium.io` | Agentic outcomes API base URL |
1970
2104
  | `REVENIUM_BEDROCK_DISABLE` | - | Set to `1` to disable Bedrock auto-detection; Foundry detection is unaffected |
1971
- | `REVENIUM_BUFFER_MAX_SIZE` | `1000` | Store-and-forward buffer capacity (oldest events evicted when full) |
2105
+ | `REVENIUM_BUFFER_MAX_SIZE` | `20000` | Store-and-forward buffer capacity (oldest events evicted when full) |
1972
2106
  | `REVENIUM_BUFFER_FLUSH_INTERVAL` | `30` | Seconds between automatic replay attempts for buffered events |
2107
+ | `REVENIUM_METERING_WORKERS` | `32` | Background threads that send usage records (see [Metering Delivery and Timeouts](#metering-delivery-and-timeouts)) |
2108
+ | `REVENIUM_METERING_QUEUE_SIZE` | `1000` | Usage records that can wait for a sending thread; overflow goes to the store-and-forward buffer |
2109
+ | `REVENIUM_METERING_TIMEOUT_SECONDS` | `10` | Seconds one attempt to send a usage record waits for a response |
2110
+ | `REVENIUM_METERING_CONNECT_TIMEOUT_SECONDS` | `5` | Seconds one attempt waits for a connection |
2111
+ | `REVENIUM_METERING_MAX_RETRIES` | `2` | Retries after the first attempt before a record moves to the buffer |
2112
+ | `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` | `5` | Total seconds the exit hook may spend sending queued usage records, building overflowed ones and flushing the buffer |
2113
+ | `REVENIUM_INSTALL_SIGNAL_HANDLERS` | `false` | Set to `1` to flush metering before SIGTERM's default action ends the process (see [Shutdown](#shutdown)) |
1973
2114
 
1974
2115
  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.
1975
2116
 
@@ -18,8 +18,8 @@ The official Revenium Python SDK — unified AI metering middleware for deeply a
18
18
  - **Prompt Capture**: Optional capture of prompts and responses for analytics and debugging
19
19
  - **Terminal Summary**: Real-time cost and usage summaries in your terminal (human-readable or JSON)
20
20
  - **Distributed Tracing**: Built-in trace visualization fields for cross-service observability
21
- - **Asynchronous Processing**: Background thread management for non-blocking metering operations
22
- - **Graceful Shutdown**: Ensures all metering data is properly sent even during application shutdown
21
+ - **Asynchronous Processing**: Usage records are sent from a fixed pool of background threads, never on your request path
22
+ - **Graceful Shutdown**: Flushes pending metering data when the process exits, within a bounded time, without taking over your application's signal handling
23
23
  - **Thread-Safe**: Production-ready with `contextvars`-based context management for concurrent applications
24
24
 
25
25
  ## Supported Providers
@@ -151,6 +151,7 @@ print(status.success_count) # events delivered successfully
151
151
  print(status.error_count) # delivery failures
152
152
  print(status.last_error) # most recent exception, or None
153
153
  print(status.last_error_at) # UTC datetime of the most recent failure
154
+ print(status.evicted_count) # undelivered events dropped because the buffer was full
154
155
  ```
155
156
 
156
157
  `reset_metering_status()` zeroes the counters and clears registered
@@ -691,7 +692,7 @@ that Foundry bills at. `AsyncAnthropicFoundry` is metered the same way, as is
691
692
 
692
693
  ### Google AI (Gemini / Vertex AI)
693
694
 
694
- Supports chat completions, streaming, embeddings, image generation (Imagen), video generation, and vision/multimodal. Choose between Google AI SDK (simple API key setup) or Vertex AI SDK (production-grade with full token counting).
695
+ 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).
695
696
 
696
697
  ```bash
697
698
  # Google AI SDK only (Gemini Developer API)
@@ -798,7 +799,7 @@ response = ollama.embed(model='nomic-embed-text', input='Hello world')
798
799
  response = ollama.embed(model='nomic-embed-text', input=['Text 1', 'Text 2', 'Text 3'])
799
800
  ```
800
801
 
801
- **Supported endpoints:** `ollama.chat()`, `ollama.generate()`, `ollama.embed()`
802
+ **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.
802
803
 
803
804
  **OpenAI compatibility mode:** You can also use Ollama with the OpenAI SDK:
804
805
 
@@ -849,6 +850,10 @@ response = litellm.completion(
849
850
  )
850
851
  ```
851
852
 
853
+ 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`.
854
+
855
+ 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.
856
+
852
857
  #### Proxy Mode
853
858
 
854
859
  `ReveniumGuardrail` is the LiteLLM proxy integration. It is a LiteLLM
@@ -881,7 +886,7 @@ guardrail to that one event type. `pre_call` alone enforces without metering;
881
886
 
882
887
  **Budget enforcement** reuses the SDK's own circuit breaker, so a proxy enforces
883
888
  exactly what every other Revenium integration enforces — including department
884
- (org-unit) budgets. It is opt-in via `REVENIUM_CIRCUIT_BREAKER_ENABLED=true`; see
889
+ budgets. It is opt-in via `REVENIUM_CIRCUIT_BREAKER_ENABLED=true`; see
885
890
  [Cost Controls](#cost-controls). A blocked call never reaches the provider and the
886
891
  caller receives HTTP 429:
887
892
 
@@ -893,8 +898,15 @@ caller receives HTTP 429:
893
898
  ```
894
899
 
895
900
  Enforcement **fails open**: if the enforcement path is unreachable or misbehaves,
896
- the call proceeds. Metering is likewise non-disruptive — nothing in the post-call
897
- path can turn a successful LLM call into an error for the client.
901
+ the call proceeds, and it proceeds without waiting. The pre-call check reads the
902
+ rules the SDK already has cached and refreshes them on a background thread, so a
903
+ Revenium endpoint that hangs, refuses connections, returns errors or rejects your
904
+ key (403) neither blocks nor slows the proxy. A failed refresh is retried once
905
+ per `REVENIUM_CB_POLL_INTERVAL_SECONDS`, not once per request. Right after the
906
+ proxy starts, before the first rules fetch completes, no rules are cached and
907
+ calls go through; see [Fail-Open vs Fail-Closed](#fail-open-vs-fail-closed).
908
+ Metering is likewise non-disruptive — nothing in the post-call path can turn a
909
+ successful LLM call into an error for the client.
898
910
 
899
911
  **Attribution** travels as `x-revenium-*` request headers (subscriber, organization,
900
912
  product, trace, task type, agent, subscription, quality score, and `x-revenium-effort`
@@ -904,6 +916,27 @@ for reasoning effort), with the calling virtual key's metadata as the fallback
904
916
  `-type`, `-version`) ride along for cost/ROI correlation; the job id is required for
905
917
  the others to be recorded.
906
918
 
919
+ **Who made the call.** By default a proxied call is metered and budget-checked as the
920
+ owner of the virtual key it used, which is right when every person has their own key.
921
+ When several people share one key, have each client send
922
+ `x-revenium-subscriber-email` (and optionally `x-revenium-subscriber-id`) naming the
923
+ person making the call. Per-person and department budgets are looked up by that email,
924
+ so without it a shared key's calls all count against its owner, and a blocked
925
+ developer keeps getting through on the owner's budget. A call that sends someone
926
+ else's email without an id carries no id at all, rather than the key's
927
+ `revenium_user_id`, so it is checked against that person's balance and not the owner's. The captured header wins over a
928
+ copy of the same key in the request's `metadata`; a blank value is ignored. Both are
929
+ taken as the caller sends them: a shared key trusts its users to name themselves. On
930
+ a team with strict ingestion enabled, the email must belong to a registered user, or
931
+ the call's metering row is rejected instead of falling back to the key owner.
932
+
933
+ ```bash
934
+ curl http://localhost:4000/v1/messages \
935
+ -H "x-api-key: sk-shared-team-key" \
936
+ -H "x-revenium-subscriber-email: dev@acme.com" \
937
+ ...
938
+ ```
939
+
907
940
  ##### Counting a Claude Code call once (shared call id)
908
941
 
909
942
  If you run Claude Code through your proxy **and** point Claude Code's own usage
@@ -1179,7 +1212,9 @@ for image in result.get("images", []):
1179
1212
  print(f"Image URL: {image['url']}")
1180
1213
  ```
1181
1214
 
1182
- **Supported methods:** `fal_client.run`, `fal_client.subscribe`, `fal_client.stream` (and their async variants: `run_async`, `subscribe_async`, `stream_async`)
1215
+ **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`.
1216
+
1217
+ **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.
1183
1218
 
1184
1219
  **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.
1185
1220
 
@@ -1723,8 +1758,9 @@ The pre-call check fires before every chat / embeddings / responses call. When t
1723
1758
 
1724
1759
  1. A daemon thread (`revenium-enforcement-poll`) starts on first use.
1725
1760
  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.
1726
- 3. Rules are cached in-process (120 s TTL, refresh-on-stale with thundering-herd guard).
1727
- 4. `204 No Content` is treated as "no rules configured" — the cache is cleared.
1761
+ 3. Rules are cached in-process. The pre-call check only reads that cache: it never makes a network request and never sleeps, so it is safe on an event loop (LiteLLM proxy, `AsyncOpenAI`). When the cache is more than 120 s old the check wakes the poller to refresh it early and carries on with the rules it has. Only one refresh runs at a time per process.
1762
+ 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.
1763
+ 5. `204 No Content` is treated as "no rules configured" — the cache is cleared.
1728
1764
 
1729
1765
  ### Exception Contract
1730
1766
 
@@ -1763,9 +1799,9 @@ except BudgetExceededError as exc:
1763
1799
 
1764
1800
  ### Fail-Open vs Fail-Closed
1765
1801
 
1766
- By default (`REVENIUM_CB_FAIL_MODE=open`) enforcement failures never propagate to user code. If the rule fetch errors (network, 5xx, auth), the previous in-memory cache is preserved and a debug log line is emitted. If there is no cache yet, enforcement behaves as if no rules are configured and the request continues.
1802
+ By default (`REVENIUM_CB_FAIL_MODE=open`) enforcement failures never propagate to user code and never delay it. If the rule fetch errors (network, 5xx, auth), the previous in-memory cache is preserved, a warning is logged, and the next attempt waits one poll interval. If there is no cache yet — the first moments after a process starts, or the whole of an outage that began before the first successful fetch — enforcement behaves as if no rules are configured and the request continues immediately; it does not wait for the fetch.
1767
1803
 
1768
- Set `REVENIUM_CB_FAIL_MODE=closed` to refuse calls until at least one rule fetch (or `REVENIUM_CACHE_DIR` snapshot) succeeds. Pair with `REVENIUM_CACHE_DIR` so a process restart loads the last-known rules rather than blocking every call until the first poll completes.
1804
+ Set `REVENIUM_CB_FAIL_MODE=closed` to refuse calls until at least one rule fetch (or `REVENIUM_CACHE_DIR` snapshot) succeeds. The refusal is immediate too: a call made before the first fetch completes raises `BudgetExceededError` rather than waiting for it. Pair with `REVENIUM_CACHE_DIR` so a process restart loads the last-known rules rather than refusing every call until the first poll completes.
1769
1805
 
1770
1806
  ### Shadow Mode
1771
1807
 
@@ -1829,22 +1865,113 @@ revenium_middleware.initialize_metering(
1829
1865
  `initialize_metering()` returns `True` when metering is enabled after the
1830
1866
  call; invoke it with no arguments to re-read the environment.
1831
1867
 
1868
+ ### Metering Delivery and Timeouts
1869
+
1870
+ Usage records are never sent on your request path. A metered call puts its
1871
+ record on a bounded in-process queue and returns at once; a fixed pool of
1872
+ background threads sends queued records to Revenium. The number of threads
1873
+ does not grow with traffic, so a slow or unreachable metering endpoint costs
1874
+ a few idle threads and the queue's memory, never a thread per call.
1875
+
1876
+ | Variable | Default | What it sets |
1877
+ |----------|---------|--------------|
1878
+ | `REVENIUM_METERING_WORKERS` | `32` | Background threads that send records |
1879
+ | `REVENIUM_METERING_QUEUE_SIZE` | `1000` | Records that can wait for a thread |
1880
+ | `REVENIUM_METERING_TIMEOUT_SECONDS` | `10` | Seconds one attempt waits for a response |
1881
+ | `REVENIUM_METERING_CONNECT_TIMEOUT_SECONDS` | `5` | Seconds one attempt waits for a connection |
1882
+ | `REVENIUM_METERING_MAX_RETRIES` | `2` | Retries after the first attempt |
1883
+
1884
+ The two timeouts also apply to tool events, which are sent once without
1885
+ retries, and a replay from the store-and-forward buffer is a single attempt
1886
+ that waits at most `REVENIUM_METERING_TIMEOUT_SECONDS`.
1887
+
1888
+ Each thread sends one record at a time, so the threads keep up with about one
1889
+ record per thread per round trip to Revenium. The 32 default threads send
1890
+ about 100 records a second at a 300 ms round trip and keep up with 30 a
1891
+ second until a round trip takes about a second. Measured against a local
1892
+ endpoint answering in 250 ms and 300 ms, 30 calls a second for five minutes
1893
+ delivered every record within 0.35 seconds of the call, and so did 60
1894
+ records a second at 250 ms (a service that sends two records per call).
1895
+ From one client in Brazil to a US East Revenium API host, a request on an
1896
+ open connection took 113 ms (p50) and 123 ms (p99), and one that also opened
1897
+ the connection 333 ms and 462 ms;
1898
+ measure from your own region before sizing for a slower path. Idle, the 32
1899
+ threads cost about 1.4 MB of memory. Raise `REVENIUM_METERING_WORKERS` for a
1900
+ service that meters more than 30 records a second against a slow round trip;
1901
+ the queue absorbs short bursts. When the queue is full, new records go
1902
+ straight to the store-and-forward buffer below instead of waiting, and
1903
+ `get_buffer_stats()["total_overflowed"]` counts them; one warning marks the
1904
+ start of each such episode and one, with a count, its end.
1905
+
1906
+ When Revenium stops answering, the threads stop waiting on it. After three
1907
+ records in a row fail with a retryable error, new records go straight to the
1908
+ store-and-forward buffer without being sent, and one record every 5 seconds
1909
+ is still sent to find out whether Revenium is back. The first one that
1910
+ succeeds resumes sending and starts replaying the buffer at once. A warning
1911
+ marks each change. Tool events from `@meter_tool` and `report_tool_call` are
1912
+ not held back: `configure()` can send them to another endpoint, so they keep
1913
+ being sent, and the buffer replays them even while the AI records ahead of
1914
+ them are still failing.
1915
+
1916
+ At exit, queued records get the first share of the shutdown budget (see
1917
+ [Shutdown](#shutdown)).
1918
+
1832
1919
  ### Delivery Resilience (Store-and-Forward)
1833
1920
 
1834
1921
  Metering events that still fail after the client's own retries (network
1835
- outages, 5xx, rate limiting) are not lost: they are held in a bounded
1836
- in-memory buffer and replayed automatically in the background every 30
1837
- seconds, reusing each event's original `Idempotency-Key` so replays can
1838
- never double-bill. Permanent failures (401/403/404/422) are never buffered.
1839
- The buffer holds up to 1000 events (oldest evicted first) for at most 24
1840
- hours, and is drained on graceful shutdown. Inspect it programmatically:
1922
+ outages, 5xx, rate limiting), and the records held back while Revenium is not
1923
+ answering, are not lost: they are held in a bounded in-memory buffer and
1924
+ replayed automatically in the background every 30 seconds, or as soon as a
1925
+ delivery succeeds again, reusing each event's original `Idempotency-Key` so
1926
+ replays can never double-bill. A backlog replays 16 records at a time, about
1927
+ 50 a second at a 300 ms round trip next to your live traffic. Permanent
1928
+ failures (401/403/404/422) are never buffered, and buffered events expire
1929
+ after 24 hours. The buffer is drained on shutdown (see below).
1930
+
1931
+ The buffer holds up to 20,000 events, eleven minutes of an outage at 30
1932
+ records a second. A typical LiteLLM record takes about 2.3 KB in memory, so a
1933
+ full buffer holds about 45 MB; with `REVENIUM_CAPTURE_PROMPTS` each record
1934
+ can also carry up to 50,000 characters per captured prompt field, so lower
1935
+ `REVENIUM_BUFFER_MAX_SIZE` if you capture prompts. In a five-minute outage at
1936
+ 30 calls a second against the defaults, all 9,000 records were held and then
1937
+ delivered within two and a half minutes of Revenium answering again, while
1938
+ new traffic kept flowing. When the buffer is full the oldest
1939
+ events are evicted and their usage is lost: one warning marks the first
1940
+ eviction, the flush thread logs how many were evicted at most once per flush
1941
+ interval, and `get_metering_status().evicted_count` and
1942
+ `get_buffer_stats()["total_evicted"]` count them. Inspect it programmatically:
1841
1943
 
1842
1944
  ```python
1843
1945
  from revenium_middleware import get_buffer_stats
1844
1946
 
1845
1947
  print(get_buffer_stats())
1846
- # {'size': 0, 'max_size': 1000, 'total_buffered': 3, 'total_replayed': 3, ...}
1847
- ```
1948
+ # {'size': 0, 'max_size': 20000, 'total_buffered': 3, 'total_replayed': 3, 'total_evicted': 0, ...}
1949
+ ```
1950
+
1951
+ ### Shutdown
1952
+
1953
+ The SDK does not install signal handlers: SIGTERM and SIGINT reach your
1954
+ application or server exactly as they would without it. When the interpreter
1955
+ exits normally, including after Ctrl+C, an `atexit` hook works through three
1956
+ steps against one budget of `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` (5 seconds by
1957
+ default), each using whatever time the previous ones left: it waits for the
1958
+ background threads to send the records still queued, builds the records that
1959
+ overflowed to the store-and-forward buffer, then flushes the buffer, oldest
1960
+ first and one attempt per record. Once a usage record or a tool event fails
1961
+ in a way worth retrying (unreachable, timed out, 429 or 5xx), the flush sends
1962
+ no more records of that kind, leaving them unsent, and keeps sending the other
1963
+ kind, since tool events can go to a different endpoint. Records still queued, being sent, unbuilt
1964
+ or unsent at the end are dropped and logged once, as a warning with a count.
1965
+
1966
+ A process ended by SIGTERM's default action skips `atexit`, and with it that
1967
+ final flush. uvicorn, and so the LiteLLM proxy, ends that way once its own
1968
+ graceful shutdown has finished. For a script or worker with no SIGTERM handling
1969
+ of its own, set `REVENIUM_INSTALL_SIGNAL_HANDLERS=1`: SIGTERM then flushes
1970
+ first and ends the process the same way. A SIGTERM handler your code installed
1971
+ before importing the SDK is called unchanged, and one installed afterwards
1972
+ replaces the SDK's. The flush then happens only if that handler exits
1973
+ normally: a handler that restores SIGTERM's default action and re-raises it,
1974
+ as uvicorn does after its own shutdown, ends the process before `atexit` runs.
1848
1975
 
1849
1976
  ### Optional Environment Variables
1850
1977
 
@@ -1871,8 +1998,15 @@ print(get_buffer_stats())
1871
1998
  | `REVENIUM_OUTCOME_API_KEY` | - | Deprecated fallback name for the write-scope key; used only when `REVENIUM_WRITE_API_KEY` is unset |
1872
1999
  | `REVENIUM_PROFITSTREAM_BASE_URL` | `https://api.revenium.io` | Agentic outcomes API base URL |
1873
2000
  | `REVENIUM_BEDROCK_DISABLE` | - | Set to `1` to disable Bedrock auto-detection; Foundry detection is unaffected |
1874
- | `REVENIUM_BUFFER_MAX_SIZE` | `1000` | Store-and-forward buffer capacity (oldest events evicted when full) |
2001
+ | `REVENIUM_BUFFER_MAX_SIZE` | `20000` | Store-and-forward buffer capacity (oldest events evicted when full) |
1875
2002
  | `REVENIUM_BUFFER_FLUSH_INTERVAL` | `30` | Seconds between automatic replay attempts for buffered events |
2003
+ | `REVENIUM_METERING_WORKERS` | `32` | Background threads that send usage records (see [Metering Delivery and Timeouts](#metering-delivery-and-timeouts)) |
2004
+ | `REVENIUM_METERING_QUEUE_SIZE` | `1000` | Usage records that can wait for a sending thread; overflow goes to the store-and-forward buffer |
2005
+ | `REVENIUM_METERING_TIMEOUT_SECONDS` | `10` | Seconds one attempt to send a usage record waits for a response |
2006
+ | `REVENIUM_METERING_CONNECT_TIMEOUT_SECONDS` | `5` | Seconds one attempt waits for a connection |
2007
+ | `REVENIUM_METERING_MAX_RETRIES` | `2` | Retries after the first attempt before a record moves to the buffer |
2008
+ | `REVENIUM_SHUTDOWN_TIMEOUT_SECONDS` | `5` | Total seconds the exit hook may spend sending queued usage records, building overflowed ones and flushing the buffer |
2009
+ | `REVENIUM_INSTALL_SIGNAL_HANDLERS` | `false` | Set to `1` to flush metering before SIGTERM's default action ends the process (see [Shutdown](#shutdown)) |
1876
2010
 
1877
2011
  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.
1878
2012
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "revenium-python-sdk"
7
- version = "0.9.0"
7
+ version = "0.9.2"
8
8
  description = "The official Revenium Python SDK — unified AI metering middleware for OpenAI, Anthropic, Google, Ollama, LiteLLM, Perplexity, and fal.ai."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.8"
@@ -127,6 +127,15 @@ dev = [
127
127
  "boto3",
128
128
  "ollama>=0.3.0",
129
129
  "griptape>=1.0.0,<2.0.0; python_version >= '3.10'",
130
+ "langchain-anthropic; python_version >= '3.10'",
131
+ # tests/test_patch_coverage.py and tests/entry_points import every provider
132
+ # SDK unconditionally, so a missing one fails the run instead of skipping.
133
+ "openai>=1.0.0",
134
+ "litellm>=1.40.0",
135
+ "fal-client>=0.13.0",
136
+ "perplexityai>=0.1.0",
137
+ "google-genai>=0.1.0",
138
+ "pyyaml",
130
139
  ]
131
140
 
132
141
  [tool.pytest.ini_options]
@@ -124,14 +124,22 @@ except AttributeError:
124
124
  logger.setLevel(logging.INFO)
125
125
  logger.warning(f"Invalid log level: {log_level}, defaulting to INFO")
126
126
 
127
- # Configure a handler with the readable formatter if none exists
127
+
128
+ def _application_logs_nothing(record: logging.LogRecord) -> bool:
129
+ """Whether ``record`` would reach no handler of the application's, the only time the SDK prints it."""
130
+ return not (logger.propagate and logging.root.handlers)
131
+
132
+
133
+ # Python's guidance is that a library leaves output to the application. A
134
+ # script that never configures logging has always seen the SDK's lines from
135
+ # this handler, so it stays, standing down once the application adds a root
136
+ # handler, which would otherwise print every line a second time.
128
137
  if not logger.handlers and not logging.root.handlers:
129
138
  handler = logging.StreamHandler()
130
- formatter = ReadableFormatter()
131
- handler.setFormatter(formatter)
139
+ handler.setFormatter(ReadableFormatter())
140
+ handler.addFilter(_application_logs_nothing)
132
141
  logger.addHandler(handler)
133
142
 
134
- # Allow propagation to root logger for testing
135
143
  logger.propagate = True
136
144
 
137
145
  # Re-export everything from _core for backward compatibility.