revenium-python-sdk 0.12.0__tar.gz → 0.13.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 (194) hide show
  1. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/PKG-INFO +76 -6
  2. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/README.md +75 -5
  3. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/pyproject.toml +1 -1
  4. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/cache_tokens.py +9 -0
  5. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/enforcement.py +165 -26
  6. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/log_sanitize.py +6 -0
  7. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/metering_buffer.py +1 -5
  8. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/proxy/guardrail.py +301 -35
  9. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/proxy/middleware.py +17 -7
  10. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_python_sdk.egg-info/PKG-INFO +76 -6
  11. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/LICENSE +0 -0
  12. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/__init__.py +0 -0
  13. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/__init__.py +0 -0
  14. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/call_context.py +0 -0
  15. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/call_ownership.py +0 -0
  16. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/closable_scope.py +0 -0
  17. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/config.py +0 -0
  18. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/context.py +0 -0
  19. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/decorators.py +0 -0
  20. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/delivery_circuit.py +0 -0
  21. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/error_text.py +0 -0
  22. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/exceptions.py +0 -0
  23. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/failed_calls.py +0 -0
  24. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/fields.py +0 -0
  25. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/json_safe.py +0 -0
  26. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/langchain_settings.py +0 -0
  27. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/load_diagnostics.py +0 -0
  28. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/metering.py +0 -0
  29. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/metering_pool.py +0 -0
  30. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/metering_status.py +0 -0
  31. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/metering_submission.py +0 -0
  32. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/outcomes.py +0 -0
  33. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/package_versions.py +0 -0
  34. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/parse_failures.py +0 -0
  35. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/patch_registry.py +0 -0
  36. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/perplexity_cost.py +0 -0
  37. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/perplexity_usage_metadata.py +0 -0
  38. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/prompt_extraction.py +0 -0
  39. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/responses_status.py +0 -0
  40. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/secret_shapes.py +0 -0
  41. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/selective_metering.py +0 -0
  42. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/shutdown_signals.py +0 -0
  43. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/sse_body_tap.py +0 -0
  44. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/subscriber.py +0 -0
  45. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/tool_event_transport.py +0 -0
  46. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/trace_fields.py +0 -0
  47. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/usage_iterations.py +0 -0
  48. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/vendor_model_aliases.py +0 -0
  49. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_core/wire_guards.py +0 -0
  50. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/LICENSE +0 -0
  51. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/__init__.py +0 -0
  52. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_base_client.py +0 -0
  53. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_client.py +0 -0
  54. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_compat.py +0 -0
  55. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_constants.py +0 -0
  56. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_exceptions.py +0 -0
  57. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_files.py +0 -0
  58. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_models.py +0 -0
  59. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_qs.py +0 -0
  60. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_resource.py +0 -0
  61. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_response.py +0 -0
  62. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_streaming.py +0 -0
  63. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_types.py +0 -0
  64. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_utils/__init__.py +0 -0
  65. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_utils/_logs.py +0 -0
  66. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_utils/_proxy.py +0 -0
  67. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_utils/_reflection.py +0 -0
  68. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_utils/_resources_proxy.py +0 -0
  69. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_utils/_streams.py +0 -0
  70. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_utils/_sync.py +0 -0
  71. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_utils/_transform.py +0 -0
  72. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_utils/_typing.py +0 -0
  73. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_utils/_utils.py +0 -0
  74. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/_version.py +0 -0
  75. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/context.py +0 -0
  76. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/decorator.py +0 -0
  77. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/py.typed +0 -0
  78. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/resources/__init__.py +0 -0
  79. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/resources/ai.py +0 -0
  80. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/resources/apis.py +0 -0
  81. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/resources/events.py +0 -0
  82. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/types/__init__.py +0 -0
  83. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/types/ai_create_audio_params.py +0 -0
  84. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/types/ai_create_completion_params.py +0 -0
  85. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/types/ai_create_image_params.py +0 -0
  86. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/types/ai_create_video_params.py +0 -0
  87. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/types/api_meter_request_params.py +0 -0
  88. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/types/api_meter_response_params.py +0 -0
  89. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/types/event_create_params.py +0 -0
  90. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/_metering/types/metering_response_resource.py +0 -0
  91. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/agentic_outcomes.py +0 -0
  92. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/__init__.py +0 -0
  93. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/bedrock_adapter.py +0 -0
  94. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/bedrock_model_names.py +0 -0
  95. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/bedrock_transport.py +0 -0
  96. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/config.py +0 -0
  97. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/inference_profiles.py +0 -0
  98. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/middleware.py +0 -0
  99. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/prompt_extractor.py +0 -0
  100. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/provider.py +0 -0
  101. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/raw_response.py +0 -0
  102. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/stream_create.py +0 -0
  103. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/anthropic/trace_fields.py +0 -0
  104. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/fal/__init__.py +0 -0
  105. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/fal/_call.py +0 -0
  106. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/fal/_metering.py +0 -0
  107. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/fal/_queue.py +0 -0
  108. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/fal/config.py +0 -0
  109. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/fal/middleware.py +0 -0
  110. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/fal/trace_fields.py +0 -0
  111. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/__init__.py +0 -0
  112. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/common/__init__.py +0 -0
  113. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/common/exceptions.py +0 -0
  114. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/common/protocols.py +0 -0
  115. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/common/trace_fields.py +0 -0
  116. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/common/types.py +0 -0
  117. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/common/utils.py +0 -0
  118. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/config.py +0 -0
  119. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/google_ai/__init__.py +0 -0
  120. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/google_ai/middleware.py +0 -0
  121. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/google_ai/provider.py +0 -0
  122. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/prompt_extractor.py +0 -0
  123. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/vertex_ai/__init__.py +0 -0
  124. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/vertex_ai/middleware.py +0 -0
  125. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/google/vertex_ai/provider.py +0 -0
  126. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/griptape/__init__.py +0 -0
  127. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/griptape/_metadata.py +0 -0
  128. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/griptape/_retry.py +0 -0
  129. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/griptape/anthropic_driver.py +0 -0
  130. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/griptape/budget_errors.py +0 -0
  131. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/griptape/litellm_driver.py +0 -0
  132. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/griptape/ollama_driver.py +0 -0
  133. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/griptape/openai_driver.py +0 -0
  134. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/griptape/openai_embedding_driver.py +0 -0
  135. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/griptape/universal_driver.py +0 -0
  136. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/job_context.py +0 -0
  137. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/job_history.py +0 -0
  138. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/job_type_economics.py +0 -0
  139. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/__init__.py +0 -0
  140. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/client/__init__.py +0 -0
  141. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/client/config.py +0 -0
  142. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/client/context.py +0 -0
  143. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/client/decorators.py +0 -0
  144. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/client/hooks.py +0 -0
  145. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/client/integrations/__init__.py +0 -0
  146. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/client/integrations/crewai.py +0 -0
  147. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/client/middleware.py +0 -0
  148. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/client/trace_fields.py +0 -0
  149. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/client/validation.py +0 -0
  150. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/proxy/__init__.py +0 -0
  151. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/litellm/proxy/_metering_owner.py +0 -0
  152. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/ollama/__init__.py +0 -0
  153. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/ollama/middleware.py +0 -0
  154. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/ollama/trace_fields.py +0 -0
  155. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/__init__.py +0 -0
  156. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/audio.py +0 -0
  157. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/azure_config.py +0 -0
  158. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/azure_model_resolver.py +0 -0
  159. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/config.py +0 -0
  160. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/exceptions.py +0 -0
  161. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/langchain/__init__.py +0 -0
  162. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/langchain/_abandoned_runs.py +0 -0
  163. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/langchain/_model_call.py +0 -0
  164. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/langchain/_perplexity_cost_capture.py +0 -0
  165. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/langchain/_prompt_capture.py +0 -0
  166. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/langchain/_text_completion_usage.py +0 -0
  167. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/langchain/_utils.py +0 -0
  168. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/langchain/unified_handler.py +0 -0
  169. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/middleware.py +0 -0
  170. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/prompt_extractor.py +0 -0
  171. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/provider.py +0 -0
  172. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/raw_response.py +0 -0
  173. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/trace_fields.py +0 -0
  174. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/openai/xai_usage.py +0 -0
  175. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/perplexity/__init__.py +0 -0
  176. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/perplexity/_metering_scope.py +0 -0
  177. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/perplexity/middleware.py +0 -0
  178. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/perplexity/patching.py +0 -0
  179. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/perplexity/perplexity_sdk.py +0 -0
  180. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/perplexity/provider.py +0 -0
  181. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/perplexity/raw_response.py +0 -0
  182. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/perplexity/streaming.py +0 -0
  183. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/perplexity/trace_fields.py +0 -0
  184. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/webhooks/__init__.py +0 -0
  185. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_middleware/webhooks/_verify.py +0 -0
  186. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_python_sdk.egg-info/SOURCES.txt +0 -0
  187. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_python_sdk.egg-info/dependency_links.txt +0 -0
  188. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_python_sdk.egg-info/requires.txt +0 -0
  189. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/revenium_python_sdk.egg-info/top_level.txt +0 -0
  190. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/setup.cfg +0 -0
  191. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/tests/test_metering.py +0 -0
  192. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/tests/test_metering_dispatch_timestamps.py +0 -0
  193. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.0}/tests/test_patch_coverage.py +0 -0
  194. {revenium_python_sdk-0.12.0 → revenium_python_sdk-0.13.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.12.0
3
+ Version: 0.13.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
@@ -192,7 +192,7 @@ Some billable provider calls are not metered at all: see [Calls the SDK does not
192
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
193
 
194
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`, `realtime.translations.connect`, `responses.compact`, `responses.connect`, `videos.create`, `videos.create_and_poll`, `videos.create_character`, `videos.edit`, `videos.extend`, `videos.remix`
195
+ - **OpenAI** (`OpenAI` and `AsyncOpenAI` clients): `batches.create`, `beta.agents.automations.create`, `beta.agents.automations.invocations.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`, `realtime.translations.connect`, `responses.compact`, `responses.connect`, `videos.create`, `videos.create_and_poll`, `videos.create_character`, `videos.edit`, `videos.extend`, `videos.remix`
196
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
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
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`
@@ -849,7 +849,7 @@ async def main():
849
849
  asyncio.run(main())
850
850
  ```
851
851
 
852
- **Note:** The middleware meters `messages.create` (including `create(stream=True)`), `messages.stream` and `messages.parse`, and the same calls on `client.beta.messages` (`create`, `stream`, `parse` and each step of `tool_runner`), sync and async, including their `with_raw_response` and `with_streaming_response` forms, on the Anthropic, Bedrock and Vertex AI clients. Calls listed under [Calls the SDK does not meter](#calls-the-sdk-does-not-meter), message batches among them, are not metered.
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`, each step of `tool_runner` and, on the Anthropic client, each turn of a `thread`), sync and async, including their `with_raw_response` and `with_streaming_response` forms, on the Anthropic, Bedrock and Vertex AI clients. `tool_runner` and `thread` do not accept `usage_metadata=`; set metadata for their calls with `@revenium_metadata` (see [Decorator Support](#decorator-support)). Calls listed under [Calls the SDK does not meter](#calls-the-sdk-does-not-meter), message batches among them, are not metered.
853
853
 
854
854
  A call the provider refuses sends one record with stop reason `ERROR`, zero tokens and the error's class and HTTP status as its error reason (plus the provider's redacted error message when both `REVENIUM_CAPTURE_ERROR_MESSAGES` and `REVENIUM_CAPTURE_PROMPTS` are `true`; a provider's error can quote the request, so it is never sent with prompt capture off; at most 255 characters, keeping its "(HTTP <status>)" ending), as does a `create(stream=True)` stream that breaks off part-way. The HTTP status is also sent as the record's error code; a call that got no HTTP error answer (a connection error, a timeout, or a stream that broke off) has none. Your code still gets the original exception. Calls served through the Bedrock fast path, and calls a spending cap refuses, send no error record.
855
855
 
@@ -1197,6 +1197,24 @@ the others to be recorded. A malformed header value, such as a quality score of
1197
1197
  `high` or an effort of `very high`, is left off the record with a WARNING in the
1198
1198
  gateway log; the call is still recorded.
1199
1199
 
1200
+ **LiteLLM identities.** Below those sources, the guardrail also reads what
1201
+ LiteLLM itself resolved for the call:
1202
+
1203
+ | Revenium field | LiteLLM source | Used when |
1204
+ |---|---|---|
1205
+ | `subscriber.id` | The end user: the request's `user`, or the header named by LiteLLM's `user_header_name` | Nothing else named a subscriber id or email. A key with an owner keeps attributing to the owner, and the end user is never paired with the owner's email. |
1206
+ | `organizationName` | The alias of the LiteLLM organization the key belongs to | No header, team alias or `revenium_organization_name` key metadata named one |
1207
+ | `productName` | The alias of the LiteLLM project the key belongs to | No `x-revenium-product-name` header or `product_name:` tag |
1208
+
1209
+ LiteLLM organizations and projects need a LiteLLM enterprise license; without
1210
+ one these fallbacks never apply. Every record also carries `reasoningTokenCount`
1211
+ from LiteLLM's normalized usage (it is already inside the output count, which is
1212
+ unchanged) and `modelHost`, the LiteLLM provider that served the call (`openai`,
1213
+ `azure`, `bedrock`, ...; LiteLLM's `vertex_ai` is sent as `vertex` and `azure_ai` as
1214
+ `foundry`, the names coding-assistant records use). `provider` stays `LITELLM`, so
1215
+ provider-scoped spending caps and existing breakdowns are unaffected. The
1216
+ deprecated callback reads none of these.
1217
+
1200
1218
  **Trace id.** The guardrail takes a record's trace id from `x-revenium-trace-id`.
1201
1219
  Without that header it takes the LiteLLM session id the caller sent: the
1202
1220
  `x-litellm-session-id` or `x-litellm-trace-id` header, or `litellm_session_id` or
@@ -1220,6 +1238,58 @@ never named after its LiteLLM session. A name over 256 characters is cut to 256.
1220
1238
  with no LiteLLM session and no name has no trace name. The deprecated callback
1221
1239
  reads only the header and `REVENIUM_TRACE_NAME`.
1222
1240
 
1241
+ **Attribution from LiteLLM tags.** Six fields can also come from LiteLLM's own tags,
1242
+ so a gateway caller needs no Revenium header to set them. A tag `<field>:<value>`
1243
+ fills the field when its `x-revenium-*` header is absent or blank:
1244
+
1245
+ | Tag | Fills | Instead of |
1246
+ |-----|-------|------------|
1247
+ | `trace_type:<value>` | trace type | `x-revenium-trace-type` |
1248
+ | `task_type:<value>` | task type | `x-revenium-task-type` |
1249
+ | `agent:<value>` | agent | `x-revenium-agent` |
1250
+ | `product_name:<value>` | product name | `x-revenium-product-name` |
1251
+ | `environment:<value>` | environment | `x-revenium-environment` |
1252
+ | `transaction_name:<value>` | transaction name | `x-revenium-transaction-name` |
1253
+
1254
+ The guardrail reads the tags LiteLLM has merged by the time it runs: the caller's
1255
+ (body `metadata.tags` or root `tags`, or the `x-litellm-tags` header) and those of
1256
+ the calling virtual key, team and project. For each field the header wins, then the
1257
+ caller's tag, then a key, team or project tag, then the gateway setting such as
1258
+ `REVENIUM_TRACE_TYPE`. Two different values at one level are ignored and the next
1259
+ level decides; a WARNING names the field once per request. Values are validated as
1260
+ the header's are. A key or team tag is a per-customer default; a request tag
1261
+ describes one call:
1262
+
1263
+ ```python
1264
+ client.chat.completions.create(
1265
+ model="gpt-4o-mini",
1266
+ messages=[...],
1267
+ extra_body={"metadata": {"tags": ["trace_type:research-brief", "agent:research-planner"]}},
1268
+ )
1269
+ ```
1270
+
1271
+ A tag carries the same weight as its header. Agent, task type and product also
1272
+ decide which spending caps apply, so a `product_name:`, `agent:` or `task_type:` tag
1273
+ can move a call into or out of a cap filtered on that field, and a caller's request
1274
+ tag overrides a key's or team's. On upgrade, a key or team that already carries tags
1275
+ of this form starts setting these fields, for the record and the cap check alike;
1276
+ review existing tags before upgrading if you filter caps on agent, task type or
1277
+ product.
1278
+
1279
+ Tags reach the pre-call cap check only when the guardrail writes the record itself
1280
+ (`default_on: true` with `post_call` in its mode), so a call is never checked under a
1281
+ value its record lacks. The deprecated callback reads headers only.
1282
+
1283
+ LiteLLM records which tags the request itself sent (`caller_tags`), so a caller's tag
1284
+ stays the caller's even when the key or team carries the same string. Body
1285
+ `metadata.tags` on `/chat/completions` is the exception: LiteLLM leaves it out of
1286
+ that record, so there a tag that is also a key or team tag counts as the key's or
1287
+ team's.
1288
+
1289
+ Tags never set the organization, subscriber, subscription, agentic job or trace id:
1290
+ those are billing identity and trace grouping, and keep coming from headers and the
1291
+ virtual key.
1292
+
1223
1293
  **Organization caps and the organization header.** By default the
1224
1294
  `x-revenium-organization-name` header (and the retired `x-revenium-organization-id`)
1225
1295
  wins over the calling virtual key's team alias, for the budget check and the record
@@ -2241,7 +2311,7 @@ pip install 'revenium-python-sdk[openai]'
2241
2311
  REVENIUM_CIRCUIT_BREAKER_ENABLED=true
2242
2312
  REVENIUM_METERING_API_KEY=hak_your_key_here
2243
2313
  REVENIUM_TEAM_ID=your_hashed_team_id
2244
- REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream # optional
2314
+ REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream # optional: this is the default
2245
2315
  ```
2246
2316
 
2247
2317
  ### Environment Variables
@@ -2251,7 +2321,7 @@ REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream # optional
2251
2321
  | `REVENIUM_CIRCUIT_BREAKER_ENABLED` | `false` | Master switch. `true` / `1` / `yes` / `on` to enable. |
2252
2322
  | `REVENIUM_BYPASS` | `false` | When `true`, every `check_enforcement` call short-circuits to a no-op. Useful for incident response. |
2253
2323
  | `REVENIUM_TEAM_ID` | — | Hashed team ID. Path component on rule fetches; required when the breaker is enabled. |
2254
- | `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. |
2324
+ | `REVENIUM_ENFORCEMENT_BASE_URL` | `https://api.revenium.ai/profitstream` | Base URL for the enforcement API, taken as given. When unset it is the address outcomes and jobs use (`REVENIUM_PROFITSTREAM_BASE_URL`, else the Revenium address `REVENIUM_METERING_BASE_URL` or `initialize_metering(base_url=...)` sits under, without its `/meter` segment) plus `/profitstream`. A rules fetch that answers 404 is retried once at the same address with `/profitstream` removed, or added if it was missing, and the address that answers with rules is used from then on, so a self-hosted server that serves the API at the root, or a value set without `/profitstream`, still reaches the rules. |
2255
2325
  | `REVENIUM_CB_POLL_INTERVAL_SECONDS` | `60` | Background poll interval for rule refreshes. |
2256
2326
  | `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `BudgetExceededError` until rules are loaded. |
2257
2327
  | `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`. |
@@ -2287,7 +2357,7 @@ When the circuit breaker is disabled, it is a no-op. When enabled:
2287
2357
  1. A daemon thread (`revenium-enforcement-poll`) starts on first use.
2288
2358
  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.
2289
2359
  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.
2290
- 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.
2360
+ 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. A 4xx answer the SDK does not retry (any but 408 and 429) is logged at WARNING with the URL and the status, so a wrong address (404) or a wrong key or team id (401, 403) is visible without debug logging.
2291
2361
  5. `204 No Content` is treated as "no rules configured" — the cache is cleared.
2292
2362
 
2293
2363
  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.
@@ -76,7 +76,7 @@ Some billable provider calls are not metered at all: see [Calls the SDK does not
76
76
  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)).
77
77
 
78
78
  <!-- not-metered:start -->
79
- - **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`, `realtime.translations.connect`, `responses.compact`, `responses.connect`, `videos.create`, `videos.create_and_poll`, `videos.create_character`, `videos.edit`, `videos.extend`, `videos.remix`
79
+ - **OpenAI** (`OpenAI` and `AsyncOpenAI` clients): `batches.create`, `beta.agents.automations.create`, `beta.agents.automations.invocations.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`, `realtime.translations.connect`, `responses.compact`, `responses.connect`, `videos.create`, `videos.create_and_poll`, `videos.create_character`, `videos.edit`, `videos.extend`, `videos.remix`
80
80
  - **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`
81
81
  - **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`
82
82
  - **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`
@@ -733,7 +733,7 @@ async def main():
733
733
  asyncio.run(main())
734
734
  ```
735
735
 
736
- **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.
736
+ **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`, each step of `tool_runner` and, on the Anthropic client, each turn of a `thread`), sync and async, including their `with_raw_response` and `with_streaming_response` forms, on the Anthropic, Bedrock and Vertex AI clients. `tool_runner` and `thread` do not accept `usage_metadata=`; set metadata for their calls with `@revenium_metadata` (see [Decorator Support](#decorator-support)). Calls listed under [Calls the SDK does not meter](#calls-the-sdk-does-not-meter), message batches among them, are not metered.
737
737
 
738
738
  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.
739
739
 
@@ -1081,6 +1081,24 @@ the others to be recorded. A malformed header value, such as a quality score of
1081
1081
  `high` or an effort of `very high`, is left off the record with a WARNING in the
1082
1082
  gateway log; the call is still recorded.
1083
1083
 
1084
+ **LiteLLM identities.** Below those sources, the guardrail also reads what
1085
+ LiteLLM itself resolved for the call:
1086
+
1087
+ | Revenium field | LiteLLM source | Used when |
1088
+ |---|---|---|
1089
+ | `subscriber.id` | The end user: the request's `user`, or the header named by LiteLLM's `user_header_name` | Nothing else named a subscriber id or email. A key with an owner keeps attributing to the owner, and the end user is never paired with the owner's email. |
1090
+ | `organizationName` | The alias of the LiteLLM organization the key belongs to | No header, team alias or `revenium_organization_name` key metadata named one |
1091
+ | `productName` | The alias of the LiteLLM project the key belongs to | No `x-revenium-product-name` header or `product_name:` tag |
1092
+
1093
+ LiteLLM organizations and projects need a LiteLLM enterprise license; without
1094
+ one these fallbacks never apply. Every record also carries `reasoningTokenCount`
1095
+ from LiteLLM's normalized usage (it is already inside the output count, which is
1096
+ unchanged) and `modelHost`, the LiteLLM provider that served the call (`openai`,
1097
+ `azure`, `bedrock`, ...; LiteLLM's `vertex_ai` is sent as `vertex` and `azure_ai` as
1098
+ `foundry`, the names coding-assistant records use). `provider` stays `LITELLM`, so
1099
+ provider-scoped spending caps and existing breakdowns are unaffected. The
1100
+ deprecated callback reads none of these.
1101
+
1084
1102
  **Trace id.** The guardrail takes a record's trace id from `x-revenium-trace-id`.
1085
1103
  Without that header it takes the LiteLLM session id the caller sent: the
1086
1104
  `x-litellm-session-id` or `x-litellm-trace-id` header, or `litellm_session_id` or
@@ -1104,6 +1122,58 @@ never named after its LiteLLM session. A name over 256 characters is cut to 256.
1104
1122
  with no LiteLLM session and no name has no trace name. The deprecated callback
1105
1123
  reads only the header and `REVENIUM_TRACE_NAME`.
1106
1124
 
1125
+ **Attribution from LiteLLM tags.** Six fields can also come from LiteLLM's own tags,
1126
+ so a gateway caller needs no Revenium header to set them. A tag `<field>:<value>`
1127
+ fills the field when its `x-revenium-*` header is absent or blank:
1128
+
1129
+ | Tag | Fills | Instead of |
1130
+ |-----|-------|------------|
1131
+ | `trace_type:<value>` | trace type | `x-revenium-trace-type` |
1132
+ | `task_type:<value>` | task type | `x-revenium-task-type` |
1133
+ | `agent:<value>` | agent | `x-revenium-agent` |
1134
+ | `product_name:<value>` | product name | `x-revenium-product-name` |
1135
+ | `environment:<value>` | environment | `x-revenium-environment` |
1136
+ | `transaction_name:<value>` | transaction name | `x-revenium-transaction-name` |
1137
+
1138
+ The guardrail reads the tags LiteLLM has merged by the time it runs: the caller's
1139
+ (body `metadata.tags` or root `tags`, or the `x-litellm-tags` header) and those of
1140
+ the calling virtual key, team and project. For each field the header wins, then the
1141
+ caller's tag, then a key, team or project tag, then the gateway setting such as
1142
+ `REVENIUM_TRACE_TYPE`. Two different values at one level are ignored and the next
1143
+ level decides; a WARNING names the field once per request. Values are validated as
1144
+ the header's are. A key or team tag is a per-customer default; a request tag
1145
+ describes one call:
1146
+
1147
+ ```python
1148
+ client.chat.completions.create(
1149
+ model="gpt-4o-mini",
1150
+ messages=[...],
1151
+ extra_body={"metadata": {"tags": ["trace_type:research-brief", "agent:research-planner"]}},
1152
+ )
1153
+ ```
1154
+
1155
+ A tag carries the same weight as its header. Agent, task type and product also
1156
+ decide which spending caps apply, so a `product_name:`, `agent:` or `task_type:` tag
1157
+ can move a call into or out of a cap filtered on that field, and a caller's request
1158
+ tag overrides a key's or team's. On upgrade, a key or team that already carries tags
1159
+ of this form starts setting these fields, for the record and the cap check alike;
1160
+ review existing tags before upgrading if you filter caps on agent, task type or
1161
+ product.
1162
+
1163
+ Tags reach the pre-call cap check only when the guardrail writes the record itself
1164
+ (`default_on: true` with `post_call` in its mode), so a call is never checked under a
1165
+ value its record lacks. The deprecated callback reads headers only.
1166
+
1167
+ LiteLLM records which tags the request itself sent (`caller_tags`), so a caller's tag
1168
+ stays the caller's even when the key or team carries the same string. Body
1169
+ `metadata.tags` on `/chat/completions` is the exception: LiteLLM leaves it out of
1170
+ that record, so there a tag that is also a key or team tag counts as the key's or
1171
+ team's.
1172
+
1173
+ Tags never set the organization, subscriber, subscription, agentic job or trace id:
1174
+ those are billing identity and trace grouping, and keep coming from headers and the
1175
+ virtual key.
1176
+
1107
1177
  **Organization caps and the organization header.** By default the
1108
1178
  `x-revenium-organization-name` header (and the retired `x-revenium-organization-id`)
1109
1179
  wins over the calling virtual key's team alias, for the budget check and the record
@@ -2125,7 +2195,7 @@ pip install 'revenium-python-sdk[openai]'
2125
2195
  REVENIUM_CIRCUIT_BREAKER_ENABLED=true
2126
2196
  REVENIUM_METERING_API_KEY=hak_your_key_here
2127
2197
  REVENIUM_TEAM_ID=your_hashed_team_id
2128
- REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream # optional
2198
+ REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream # optional: this is the default
2129
2199
  ```
2130
2200
 
2131
2201
  ### Environment Variables
@@ -2135,7 +2205,7 @@ REVENIUM_ENFORCEMENT_BASE_URL=https://api.revenium.ai/profitstream # optional
2135
2205
  | `REVENIUM_CIRCUIT_BREAKER_ENABLED` | `false` | Master switch. `true` / `1` / `yes` / `on` to enable. |
2136
2206
  | `REVENIUM_BYPASS` | `false` | When `true`, every `check_enforcement` call short-circuits to a no-op. Useful for incident response. |
2137
2207
  | `REVENIUM_TEAM_ID` | — | Hashed team ID. Path component on rule fetches; required when the breaker is enabled. |
2138
- | `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. |
2208
+ | `REVENIUM_ENFORCEMENT_BASE_URL` | `https://api.revenium.ai/profitstream` | Base URL for the enforcement API, taken as given. When unset it is the address outcomes and jobs use (`REVENIUM_PROFITSTREAM_BASE_URL`, else the Revenium address `REVENIUM_METERING_BASE_URL` or `initialize_metering(base_url=...)` sits under, without its `/meter` segment) plus `/profitstream`. A rules fetch that answers 404 is retried once at the same address with `/profitstream` removed, or added if it was missing, and the address that answers with rules is used from then on, so a self-hosted server that serves the API at the root, or a value set without `/profitstream`, still reaches the rules. |
2139
2209
  | `REVENIUM_CB_POLL_INTERVAL_SECONDS` | `60` | Background poll interval for rule refreshes. |
2140
2210
  | `REVENIUM_CB_FAIL_MODE` | `open` | `open` (default) lets calls through when no cache exists; `closed` raises `BudgetExceededError` until rules are loaded. |
2141
2211
  | `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`. |
@@ -2171,7 +2241,7 @@ When the circuit breaker is disabled, it is a no-op. When enabled:
2171
2241
  1. A daemon thread (`revenium-enforcement-poll`) starts on first use.
2172
2242
  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.
2173
2243
  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.
2174
- 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.
2244
+ 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. A 4xx answer the SDK does not retry (any but 408 and 429) is logged at WARNING with the URL and the status, so a wrong address (404) or a wrong key or team id (401, 403) is visible without debug logging.
2175
2245
  5. `204 No Content` is treated as "no rules configured" — the cache is cleared.
2176
2246
 
2177
2247
  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.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "revenium-python-sdk"
7
- version = "0.12.0"
7
+ version = "0.13.0"
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"
@@ -238,6 +238,15 @@ def _upstream_provider(sources) -> Optional[str]:
238
238
  return None
239
239
 
240
240
 
241
+ def upstream_provider(*sources) -> Optional[str]:
242
+ """The LiteLLM provider that served the call, lower-cased, or None.
243
+
244
+ ``sources`` are LiteLLM-populated surfaces in lookup order, as for
245
+ ``prompt_tokens_fold_cache``; the first that names a provider decides.
246
+ """
247
+ return _upstream_provider(sources)
248
+
249
+
241
250
  def _provider_folds_cache(provider: str, sources) -> bool:
242
251
  if provider in _CACHE_FOLDING_PROVIDERS:
243
252
  return True
@@ -69,13 +69,14 @@ import threading
69
69
  import time
70
70
  from email.utils import parsedate_to_datetime
71
71
  from typing import Dict, List, NamedTuple, Optional, Set, Tuple
72
- from urllib.parse import quote, urlparse
72
+ from urllib.parse import quote, urlsplit, urlunsplit
73
73
 
74
74
  import httpx
75
75
 
76
76
  from .call_ownership import peek_callback_metadata
77
77
  from .closable_scope import ClosableScope
78
- from .config import Config, env_choice, env_flag_enabled
78
+ from .config import Config, env_choice, env_flag_enabled, get_profitstream_base_url
79
+ from .log_sanitize import address_without_credentials
79
80
  from .context import merge_metadata, overlay_metadata
80
81
  from .exceptions import BudgetExceededError
81
82
  from .fields import extract_common_metadata, extract_organization_name, extract_product_name
@@ -462,21 +463,73 @@ def _process_metering_url() -> Optional[str]:
462
463
  return _valid_base_url(str(client.base_url)) if client is not None else None
463
464
 
464
465
 
466
+ _PROFITSTREAM_PATH = "/profitstream"
467
+
468
+ # Configured enforcement address -> the sibling address (with or without
469
+ # ``/profitstream``) that served the rules after the configured one answered
470
+ # 404. The cache owner and the snapshot scope keep the configured address;
471
+ # only the request URL moves (BACK-5240).
472
+ _recovered_enforcement_addresses: Dict[str, str] = {}
473
+
474
+
465
475
  def _get_enforcement_base_url() -> str:
466
- """Base URL for enforcement API calls.
476
+ """The enforcement address as configured: the one the cache belongs to.
467
477
 
468
- Prefers ``REVENIUM_ENFORCEMENT_BASE_URL`` so a context-path
469
- (``http://localhost:8080/profitstream``) survives intact. Falls back to
470
- the origin of the metering client's URL, set by ``initialize_metering()``
471
- or ``REVENIUM_METERING_BASE_URL``.
478
+ ``REVENIUM_ENFORCEMENT_BASE_URL`` is taken as given, so a context path
479
+ (``http://localhost:8080/profitstream``) survives intact. Otherwise it is
480
+ the address outcomes and jobs use (``REVENIUM_PROFITSTREAM_BASE_URL``,
481
+ else the Revenium address the metering client's URL sits under, set by
482
+ ``initialize_metering()`` or ``REVENIUM_METERING_BASE_URL``) plus
483
+ ``/profitstream``, where the hosted API serves the enforcement rules.
472
484
  """
473
485
  explicit = os.environ.get(Config.ENV_REVENIUM_ENFORCEMENT_BASE_URL, "")
474
486
  if explicit:
475
487
  return explicit.rstrip("/")
476
- metering_url = _process_metering_url() or os.environ.get(
477
- Config.ENV_REVENIUM_BASE_URL, "https://api.revenium.ai/meter/")
478
- parsed = urlparse(metering_url)
479
- return f"{parsed.scheme}://{parsed.netloc}"
488
+ revenium_address = get_profitstream_base_url(metering_base_url=_process_metering_url())
489
+ return revenium_address.rstrip("/") + _PROFITSTREAM_PATH
490
+
491
+
492
+ def _sibling_enforcement_address(address: str) -> str:
493
+ """The same address with ``/profitstream`` removed if present, added if not."""
494
+ parts = urlsplit(address)
495
+ path = parts.path.rstrip("/")
496
+ if path.lower().endswith(_PROFITSTREAM_PATH):
497
+ path = path[: -len(_PROFITSTREAM_PATH)]
498
+ else:
499
+ path = path + _PROFITSTREAM_PATH
500
+ return urlunsplit(parts._replace(path=path)).rstrip("/")
501
+
502
+
503
+ def _effective_enforcement_address(configured: str) -> str:
504
+ return _recovered_enforcement_addresses.get(configured, configured)
505
+
506
+
507
+ def _loggable_address(address: str) -> str:
508
+ """An address as the logs may show it: no credentials, query or fragment."""
509
+ try:
510
+ return address_without_credentials(httpx.URL(address)).rstrip("/")
511
+ except Exception: # noqa: BLE001 - an address httpx cannot parse is not worth a traceback
512
+ return "the configured enforcement address"
513
+
514
+
515
+ def _adopt_enforcement_address(configured: str, tried: str, served: str) -> None:
516
+ """Send every later read for ``configured`` to ``served``, which just proved it serves the rules."""
517
+ if served == configured:
518
+ _recovered_enforcement_addresses.pop(configured, None)
519
+ else:
520
+ _recovered_enforcement_addresses[configured] = served
521
+ logger.warning(
522
+ "Enforcement rules were not found at %s (HTTP 404) but are served at %s; using that "
523
+ "address from now on. Set %s to it to skip this lookup.",
524
+ _loggable_address(tried), _loggable_address(served), Config.ENV_REVENIUM_ENFORCEMENT_BASE_URL,
525
+ )
526
+
527
+
528
+ def _team_rules_url(address: str, team_id: str) -> str:
529
+ # Percent-encode the team_id path segment so a misconfigured value
530
+ # containing '/', '..', or '?' cannot retarget the request to a
531
+ # different endpoint on the same origin.
532
+ return f"{address}/v2/api/ai/enforcement-rules/{quote(team_id, safe='')}"
480
533
 
481
534
 
482
535
  class _DepartmentBudgets(NamedTuple):
@@ -969,6 +1022,9 @@ class _FetchTarget(NamedTuple):
969
1022
  api_key: str
970
1023
  team_url: str
971
1024
  owner: Tuple[str, str]
1025
+ # The address ``team_url`` was built on: the configured one, or the
1026
+ # sibling an earlier 404 recovered to.
1027
+ address: str
972
1028
 
973
1029
 
974
1030
  def _fetch_target() -> Optional[_FetchTarget]:
@@ -1007,19 +1063,26 @@ def _fetch_target() -> Optional[_FetchTarget]:
1007
1063
  return None
1008
1064
 
1009
1065
  base_url = _get_enforcement_base_url()
1010
- # Percent-encode the team_id path segment so a misconfigured value
1011
- # containing '/', '..', or '?' cannot retarget the request to a
1012
- # different endpoint on the same origin.
1013
- safe_team_id = quote(team_id, safe="")
1014
- return _FetchTarget(api_key, f"{base_url}/v2/api/ai/enforcement-rules/{safe_team_id}",
1015
- (base_url, team_id))
1066
+ address = _effective_enforcement_address(base_url)
1067
+ return _FetchTarget(api_key, _team_rules_url(address, team_id), (base_url, team_id), address)
1016
1068
 
1017
1069
 
1018
1070
  def _get_enforcement(url: str, api_key: str, resource: str,
1019
1071
  params: Optional[dict], retry_after_budget: float,
1020
1072
  owner: Tuple[str, str]) -> Optional["httpx.Response"]:
1073
+ """``_get_enforcement_spending`` for a read that has no second address to spend the rest on."""
1074
+ return _get_enforcement_spending(url, api_key, resource, params, retry_after_budget, owner)[0]
1075
+
1076
+
1077
+ def _get_enforcement_spending(url: str, api_key: str, resource: str,
1078
+ params: Optional[dict], retry_after_budget: float,
1079
+ owner: Tuple[str, str]) -> Tuple[Optional["httpx.Response"], float]:
1021
1080
  """GET one enforcement resource under the shared retry and Retry-After budget.
1022
1081
 
1082
+ Returns the response and the Retry-After budget this read left unspent, so
1083
+ a read that goes on to a second address (``_rules_at_sibling_address``)
1084
+ spends one budget across both and never doubles the documented wait.
1085
+
1023
1086
  Returns the first response the retry policy does not retry -- the caller
1024
1087
  reads its status and its body -- or ``None`` once the fetch has given up,
1025
1088
  so every caller fails open on what it already holds. ``resource`` names
@@ -1051,10 +1114,10 @@ def _get_enforcement(url: str, api_key: str, resource: str,
1051
1114
  continue
1052
1115
  except Exception:
1053
1116
  logger.debug("Failed to fetch enforcement %s, falling open", resource, exc_info=True)
1054
- return None
1117
+ return None, retry_after_budget
1055
1118
 
1056
1119
  if not _is_retryable_status(response.status_code):
1057
- return response
1120
+ return response, retry_after_budget
1058
1121
 
1059
1122
  plan = _plan_retry(response, backoff, retry_after_budget, budget_total, owner)
1060
1123
  retry_after_budget = plan.budget_remaining
@@ -1062,7 +1125,7 @@ def _get_enforcement(url: str, api_key: str, resource: str,
1062
1125
  # Give up without waiting and without retrying: the cooldown
1063
1126
  # _plan_retry recorded keeps the server's interval, and the caller
1064
1127
  # falls open on the reading it already has.
1065
- return None
1128
+ return None, retry_after_budget
1066
1129
  if attempt == _FETCH_MAX_ATTEMPTS - 1:
1067
1130
  break
1068
1131
  if _sleep(plan.wait_seconds):
@@ -1075,7 +1138,7 @@ def _get_enforcement(url: str, api_key: str, resource: str,
1075
1138
  "Enforcement %s fetch exhausted %d attempts; failing open",
1076
1139
  resource, _FETCH_MAX_ATTEMPTS,
1077
1140
  )
1078
- return None
1141
+ return None, retry_after_budget
1079
1142
 
1080
1143
 
1081
1144
  def _rules_query(rule_id: Optional[str], include_advisory: bool) -> Optional[dict]:
@@ -1121,15 +1184,25 @@ def _fetch_rules(rule_id: Optional[str] = None,
1121
1184
  if target is None:
1122
1185
  return None
1123
1186
 
1124
- response = _get_enforcement(target.team_url, target.api_key, "rule", params,
1125
- retry_after_budget, target.owner)
1187
+ response, budget_left = _get_enforcement_spending(target.team_url, target.api_key, "rule",
1188
+ params, retry_after_budget, target.owner)
1126
1189
  if response is None:
1127
1190
  return None
1191
+ if response.status_code == 404:
1192
+ recovered = _rules_at_sibling_address(target, params, budget_left)
1193
+ if recovered is not None:
1194
+ return recovered.fetched
1195
+ return _rules_from_response(response)
1196
+
1128
1197
 
1198
+ def _rules_from_response(response: "httpx.Response") -> Optional[_FetchedRules]:
1199
+ """The rules a rules read answered with, or ``None`` when it answered with anything else."""
1129
1200
  try:
1130
1201
  # 204 No Content == no rules configured for this team; cache empty
1131
1202
  if response.status_code == 204:
1132
1203
  return _FetchedRules([], {}, {}, {}, {})
1204
+ if 400 <= response.status_code < 500:
1205
+ _warn_refused_rules_read(response)
1133
1206
  response.raise_for_status()
1134
1207
  # Server currently returns ``{"rules": [...], "compiledAt": ...,
1135
1208
  # "departmentBudgetBlocks": {...}, "departmentBudgetBlockBalances":
@@ -1141,6 +1214,60 @@ def _fetch_rules(rule_id: Optional[str] = None,
1141
1214
  return None
1142
1215
 
1143
1216
 
1217
+ class _RecoveredRules(NamedTuple):
1218
+ address: str
1219
+ fetched: _FetchedRules
1220
+ budget_left: float
1221
+
1222
+
1223
+ def _rules_at_sibling_address(target: _FetchTarget, params: Optional[dict],
1224
+ retry_after_budget: float) -> Optional[_RecoveredRules]:
1225
+ """Read the rules once at the sibling of the address that answered 404, and adopt it if it serves them.
1226
+
1227
+ The hosted API serves enforcement under ``/profitstream``; a self-hosted
1228
+ server may serve it at the root, and an operator may have configured
1229
+ either address without that segment. A 404 says the rules are not at this
1230
+ address at all, not that the team has none (that is a 204), so the one
1231
+ other address is tried. It is adopted for every later read only once it
1232
+ has answered with rules (a 204, or a body ``_fetched_from_payload``
1233
+ accepts): a refusal or an unreadable body there leaves the configured
1234
+ address in use, so the next poll reads it again. A refusal at the sibling
1235
+ (any 4xx but 404) is logged by ``_warn_refused_rules_read`` as well, so a
1236
+ wrong key or team id at the working address is not hidden behind the
1237
+ first address's 404.
1238
+ """
1239
+ configured, team_id = target.owner
1240
+ sibling = _sibling_enforcement_address(target.address)
1241
+ response, budget_left = _get_enforcement_spending(
1242
+ _team_rules_url(sibling, team_id), target.api_key, "rule", params,
1243
+ retry_after_budget, target.owner)
1244
+ if response is None:
1245
+ return None
1246
+ if not (response.is_success or response.status_code == 204):
1247
+ if 400 <= response.status_code < 500 and response.status_code != 404:
1248
+ _warn_refused_rules_read(response)
1249
+ return None
1250
+ fetched = _rules_from_response(response)
1251
+ if fetched is None:
1252
+ return None
1253
+ _adopt_enforcement_address(configured, target.address, sibling)
1254
+ return _RecoveredRules(sibling, fetched, budget_left)
1255
+
1256
+
1257
+ def _warn_refused_rules_read(response: "httpx.Response") -> None:
1258
+ """Say which URL refused the rules read and why, so a wrong address or key is visible."""
1259
+ status = response.status_code
1260
+ if status == 404:
1261
+ hint = (" The enforcement API is not at this address: set %s to the Revenium address "
1262
+ "that serves /v2/api/ai/enforcement-rules." % Config.ENV_REVENIUM_ENFORCEMENT_BASE_URL)
1263
+ elif status in (401, 403):
1264
+ hint = " Check %s and %s." % (Config.ENV_REVENIUM_API_KEY, Config.ENV_REVENIUM_TEAM_ID)
1265
+ else:
1266
+ hint = ""
1267
+ logger.warning("Enforcement rules could not be read: GET %s answered HTTP %d.%s",
1268
+ address_without_credentials(response.request.url), status, hint)
1269
+
1270
+
1144
1271
  def _fetch_roster(rule_id: str, page: int = 0, size: int = 25,
1145
1272
  search: Optional[str] = None,
1146
1273
  band: Optional[str] = None) -> Optional[dict]:
@@ -1172,11 +1299,23 @@ def _fetch_roster(rule_id: str, page: int = 0, size: int = 25,
1172
1299
  if band:
1173
1300
  params["band"] = band
1174
1301
 
1175
- response = _get_enforcement(f"{target.team_url}/roster", target.api_key,
1176
- "roster", params, _INSPECTION_RETRY_AFTER_GIVE_UP_SECONDS,
1177
- target.owner)
1302
+ response, budget_left = _get_enforcement_spending(
1303
+ f"{target.team_url}/roster", target.api_key, "roster", params,
1304
+ _INSPECTION_RETRY_AFTER_GIVE_UP_SECONDS, target.owner)
1178
1305
  if response is None:
1179
1306
  return None
1307
+ if response.status_code == 404:
1308
+ # Either the rule has no roster or the rules are not at this address.
1309
+ # Only a rules read can tell: if it recovers the address, the roster
1310
+ # is read once more there.
1311
+ recovered = _rules_at_sibling_address(target, None, budget_left)
1312
+ if recovered is None:
1313
+ return None
1314
+ response = _get_enforcement(f"{_team_rules_url(recovered.address, target.owner[1])}/roster",
1315
+ target.api_key, "roster", params, recovered.budget_left,
1316
+ target.owner)
1317
+ if response is None:
1318
+ return None
1180
1319
 
1181
1320
  try:
1182
1321
  # 204 No Content == the rule has no compiled reading yet, which is a
@@ -264,3 +264,9 @@ def redact_error_text(text: str, max_len: int) -> str:
264
264
  redacted = _EMAIL_WORD_PATTERN.sub(_REDACTED, redacted)
265
265
  redacted = _SECRET_SHAPED_WORD_PATTERN.sub(_REDACTED, redacted)
266
266
  return redacted[:max_len]
267
+
268
+
269
+ def address_without_credentials(url) -> str:
270
+ """Scheme, host, port and path of an ``httpx.URL``: never its userinfo, query or fragment."""
271
+ port = f":{url.port}" if url.port is not None else ""
272
+ return f"{url.scheme}://{url.host}{port}{url.path}"