paid-python 0.3.3__tar.gz → 0.3.5__tar.gz

{paid_python-0.3.3 → paid_python-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: paid-python
-Version: 0.3.3
+Version: 0.3.5
 Summary: 
 Requires-Python: >=3.9,<3.14
 Classifier: Intended Audience :: Developers
@@ -26,7 +26,6 @@ Requires-Dist: opentelemetry-api (>=1.23.0)
 Requires-Dist: opentelemetry-exporter-otlp-proto-http (>=1.23.0)
 Requires-Dist: opentelemetry-instrumentation-anthropic (>=0.47.0)
 Requires-Dist: opentelemetry-instrumentation-langchain (>=0.47.0)
-Requires-Dist: opentelemetry-instrumentation-openai (>=0.47.0)
 Requires-Dist: opentelemetry-sdk (>=1.23.0)
 Requires-Dist: pydantic (>=1.9.0)
 Requires-Dist: pydantic-core (>=2.18.0)
@@ -123,6 +122,56 @@ export PAID_LOG_LEVEL=DEBUG
 
 Defaults to ERROR.
 
+## Environment Variables
+
+The Paid SDK supports the following environment variables for configuration:
+
+### `PAID_API_KEY`
+
+Your Paid API key for authentication. This is used as a fallback when you don't explicitly pass the `token` parameter to the `Paid()` client or `initialize_tracing()`.
+
+```bash
+export PAID_API_KEY="your_api_key_here"
+```
+
+You can then initialize the client without passing the token:
+
+```python
+from paid import Paid
+
+# API key is read from PAID_API_KEY environment variable
+client = Paid()
+```
+
+### `PAID_ENABLED`
+
+Controls whether Paid tracing is enabled. Set to `false` (case-insensitive) to disable all tracing functionality.
+
+```bash
+export PAID_ENABLED=false
+```
+
+This is useful for:
+- Development/testing environments where tracing isn't needed
+- Temporarily disabling tracing without modifying code
+- Feature flagging in different deployment environments
+
+Defaults to `true` if not set.
+
+### `PAID_LOG_LEVEL`
+
+Sets the logging level for Paid SDK operations. See the [Logging](#logging) section for details.
+
+### `PAID_OTEL_COLLECTOR_ENDPOINT`
+
+Overrides the default OpenTelemetry collector endpoint URL. Only needed if you want to route traces to a custom endpoint.
+
+```bash
+export PAID_OTEL_COLLECTOR_ENDPOINT="https://your-custom-endpoint.com:4318/v1/traces"
+```
+
+Defaults to `https://collector.agentpaid.io:4318/v1/traces`.
+
 ## Cost Tracking via OTEL tracing
 
 ### Simple Decorator and Context Manager Methods

{paid_python-0.3.3 → paid_python-0.3.5}/README.md

@@ -87,6 +87,56 @@ export PAID_LOG_LEVEL=DEBUG
 
 Defaults to ERROR.
 
+## Environment Variables
+
+The Paid SDK supports the following environment variables for configuration:
+
+### `PAID_API_KEY`
+
+Your Paid API key for authentication. This is used as a fallback when you don't explicitly pass the `token` parameter to the `Paid()` client or `initialize_tracing()`.
+
+```bash
+export PAID_API_KEY="your_api_key_here"
+```
+
+You can then initialize the client without passing the token:
+
+```python
+from paid import Paid
+
+# API key is read from PAID_API_KEY environment variable
+client = Paid()
+```
+
+### `PAID_ENABLED`
+
+Controls whether Paid tracing is enabled. Set to `false` (case-insensitive) to disable all tracing functionality.
+
+```bash
+export PAID_ENABLED=false
+```
+
+This is useful for:
+- Development/testing environments where tracing isn't needed
+- Temporarily disabling tracing without modifying code
+- Feature flagging in different deployment environments
+
+Defaults to `true` if not set.
+
+### `PAID_LOG_LEVEL`
+
+Sets the logging level for Paid SDK operations. See the [Logging](#logging) section for details.
+
+### `PAID_OTEL_COLLECTOR_ENDPOINT`
+
+Overrides the default OpenTelemetry collector endpoint URL. Only needed if you want to route traces to a custom endpoint.
+
+```bash
+export PAID_OTEL_COLLECTOR_ENDPOINT="https://your-custom-endpoint.com:4318/v1/traces"
+```
+
+Defaults to `https://collector.agentpaid.io:4318/v1/traces`.
+
 ## Cost Tracking via OTEL tracing
 
 ### Simple Decorator and Context Manager Methods

{paid_python-0.3.3 → paid_python-0.3.5}/pyproject.toml

@@ -3,7 +3,7 @@ name = "paid-python"
 
 [tool.poetry]
 name = "paid-python"
-version = "0.3.3"
+version = "0.3.5"
 description = ""
 readme = "README.md"
 authors = []
@@ -44,7 +44,7 @@ opentelemetry-exporter-otlp-proto-http = ">=1.23.0"
 mutagen = ">=1.47.0"
 python-dotenv = ">=0.15.0"
 opentelemetry-instrumentation-anthropic = ">=0.47.0"
-opentelemetry-instrumentation-openai = ">=0.47.0"
+# opentelemetry-instrumentation-openai is vendored from https://github.com/paid-ai/openllmetry-instrumentation-patch (patched version)
 opentelemetry-instrumentation-langchain = ">=0.47.0"
 openinference-instrumentation-openai-agents = ">=1.0.0"
 openinference-instrumentation-bedrock = ">=0.1.0"
@@ -87,8 +87,11 @@ module = [
     "agents",
     "agents.*",
     "langchain_core.*",
+    "paid._vendor", # remove once openai instrumentor is upstream
+    "paid._vendor.*", # remove once openai instrumentor is upstream
 ]
 ignore_missing_imports = true
+ignore_errors = true # remove once openai instrumentor is upstream
 
 [tool.ruff]
 line-length = 120

paid_python-0.3.5/src/paid/_vendor/opentelemetry/instrumentation/openai/__init__.py

@@ -0,0 +1,54 @@
+from typing import Callable, Collection, Optional
+
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from paid._vendor.opentelemetry.instrumentation.openai.shared.config import Config
+from paid._vendor.opentelemetry.instrumentation.openai.utils import is_openai_v1
+from typing_extensions import Coroutine
+
+_instruments = ("openai >= 0.27.0",)
+
+
+class OpenAIInstrumentor(BaseInstrumentor):
+    """An instrumentor for OpenAI's client library."""
+
+    def __init__(
+        self,
+        enrich_assistant: bool = False,
+        exception_logger=None,
+        get_common_metrics_attributes: Callable[[], dict] = lambda: {},
+        upload_base64_image: Optional[
+            Callable[[str, str, str, str], Coroutine[None, None, str]]
+        ] = lambda *args: "",
+        enable_trace_context_propagation: bool = True,
+        use_legacy_attributes: bool = True,
+    ):
+        super().__init__()
+        Config.enrich_assistant = enrich_assistant
+        Config.exception_logger = exception_logger
+        Config.get_common_metrics_attributes = get_common_metrics_attributes
+        Config.upload_base64_image = upload_base64_image
+        Config.enable_trace_context_propagation = enable_trace_context_propagation
+        Config.use_legacy_attributes = use_legacy_attributes
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return _instruments
+
+    def _instrument(self, **kwargs):
+        if is_openai_v1():
+            from paid._vendor.opentelemetry.instrumentation.openai.v1 import OpenAIV1Instrumentor
+
+            OpenAIV1Instrumentor().instrument(**kwargs)
+        else:
+            from paid._vendor.opentelemetry.instrumentation.openai.v0 import OpenAIV0Instrumentor
+
+            OpenAIV0Instrumentor().instrument(**kwargs)
+
+    def _uninstrument(self, **kwargs):
+        if is_openai_v1():
+            from paid._vendor.opentelemetry.instrumentation.openai.v1 import OpenAIV1Instrumentor
+
+            OpenAIV1Instrumentor().uninstrument(**kwargs)
+        else:
+            from paid._vendor.opentelemetry.instrumentation.openai.v0 import OpenAIV0Instrumentor
+
+            OpenAIV0Instrumentor().uninstrument(**kwargs)

paid_python-0.3.5/src/paid/_vendor/opentelemetry/instrumentation/openai/shared/__init__.py

@@ -0,0 +1,399 @@
+import json
+import logging
+import types
+import openai
+import pydantic
+from importlib.metadata import version
+
+from paid._vendor.opentelemetry.instrumentation.openai.shared.config import Config
+from paid._vendor.opentelemetry.instrumentation.openai.utils import (
+    dont_throw,
+    is_openai_v1,
+)
+from opentelemetry.semconv._incubating.attributes import (
+    gen_ai_attributes as GenAIAttributes,
+    openai_attributes as OpenAIAttributes,
+)
+from opentelemetry.semconv_ai import SpanAttributes
+from opentelemetry.trace.propagation import set_span_in_context
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+OPENAI_LLM_USAGE_TOKEN_TYPES = ["prompt_tokens", "completion_tokens"]
+PROMPT_FILTER_KEY = "prompt_filter_results"
+PROMPT_ERROR = "prompt_error"
+
+_PYDANTIC_VERSION = version("pydantic")
+
+
+logger = logging.getLogger(__name__)
+
+
+def _set_span_attribute(span, name, value):
+    if value is None or value == "":
+        return
+
+    if hasattr(openai, "NOT_GIVEN") and value == openai.NOT_GIVEN:
+        return
+
+    span.set_attribute(name, value)
+
+
+def _set_client_attributes(span, instance):
+    if not span.is_recording():
+        return
+
+    if not is_openai_v1():
+        return
+
+    client = instance._client  # pylint: disable=protected-access
+    if isinstance(client, (openai.AsyncOpenAI, openai.OpenAI)):
+        _set_span_attribute(
+            span, SpanAttributes.LLM_OPENAI_API_BASE, str(client.base_url)
+        )
+    if isinstance(client, (openai.AsyncAzureOpenAI, openai.AzureOpenAI)):
+        _set_span_attribute(
+            span, SpanAttributes.LLM_OPENAI_API_VERSION, client._api_version
+        )  # pylint: disable=protected-access
+
+
+def _set_api_attributes(span):
+    if not span.is_recording():
+        return
+
+    if is_openai_v1():
+        return
+
+    base_url = openai.base_url if hasattr(openai, "base_url") else openai.api_base
+
+    _set_span_attribute(span, SpanAttributes.LLM_OPENAI_API_BASE, base_url)
+    _set_span_attribute(span, SpanAttributes.LLM_OPENAI_API_TYPE, openai.api_type)
+    _set_span_attribute(span, SpanAttributes.LLM_OPENAI_API_VERSION, openai.api_version)
+
+    return
+
+
+def _set_functions_attributes(span, functions):
+    if not functions:
+        return
+
+    for i, function in enumerate(functions):
+        prefix = f"{SpanAttributes.LLM_REQUEST_FUNCTIONS}.{i}"
+        _set_span_attribute(span, f"{prefix}.name", function.get("name"))
+        _set_span_attribute(span, f"{prefix}.description", function.get("description"))
+        _set_span_attribute(
+            span, f"{prefix}.parameters", json.dumps(function.get("parameters"))
+        )
+
+
+def set_tools_attributes(span, tools):
+    if not tools:
+        return
+
+    for i, tool in enumerate(tools):
+        function = tool.get("function")
+        if not function:
+            continue
+
+        prefix = f"{SpanAttributes.LLM_REQUEST_FUNCTIONS}.{i}"
+        _set_span_attribute(span, f"{prefix}.name", function.get("name"))
+        _set_span_attribute(span, f"{prefix}.description", function.get("description"))
+        _set_span_attribute(
+            span, f"{prefix}.parameters", json.dumps(function.get("parameters"))
+        )
+
+
+def _set_request_attributes(span, kwargs, instance=None):
+    if not span.is_recording():
+        return
+
+    _set_api_attributes(span)
+
+    base_url = _get_openai_base_url(instance) if instance else ""
+    vendor = _get_vendor_from_url(base_url)
+    _set_span_attribute(span, GenAIAttributes.GEN_AI_SYSTEM, vendor)
+
+    model = kwargs.get("model")
+    if vendor == "AWS" and model and "." in model:
+        model = _cross_region_check(model)
+    elif vendor == "OpenRouter":
+        model = _extract_model_name_from_provider_format(model)
+
+    _set_span_attribute(span, GenAIAttributes.GEN_AI_REQUEST_MODEL, model)
+    _set_span_attribute(
+        span, GenAIAttributes.GEN_AI_REQUEST_MAX_TOKENS, kwargs.get("max_tokens")
+    )
+    _set_span_attribute(
+        span, GenAIAttributes.GEN_AI_REQUEST_TEMPERATURE, kwargs.get("temperature")
+    )
+    _set_span_attribute(span, GenAIAttributes.GEN_AI_REQUEST_TOP_P, kwargs.get("top_p"))
+    _set_span_attribute(
+        span, SpanAttributes.LLM_FREQUENCY_PENALTY, kwargs.get("frequency_penalty")
+    )
+    _set_span_attribute(
+        span, SpanAttributes.LLM_PRESENCE_PENALTY, kwargs.get("presence_penalty")
+    )
+    _set_span_attribute(span, SpanAttributes.LLM_USER, kwargs.get("user"))
+    _set_span_attribute(span, SpanAttributes.LLM_HEADERS, str(kwargs.get("headers")))
+    # The new OpenAI SDK removed the `headers` and create new field called `extra_headers`
+    if kwargs.get("extra_headers") is not None:
+        _set_span_attribute(
+            span, SpanAttributes.LLM_HEADERS, str(kwargs.get("extra_headers"))
+        )
+    _set_span_attribute(
+        span, SpanAttributes.LLM_IS_STREAMING, kwargs.get("stream") or False
+    )
+    _set_span_attribute(
+        span, OpenAIAttributes.OPENAI_REQUEST_SERVICE_TIER, kwargs.get("service_tier")
+    )
+    if response_format := kwargs.get("response_format"):
+        # backward-compatible check for
+        # openai.types.shared_params.response_format_json_schema.ResponseFormatJSONSchema
+        if (
+            isinstance(response_format, dict)
+            and response_format.get("type") == "json_schema"
+            and response_format.get("json_schema")
+        ):
+            schema = dict(response_format.get("json_schema")).get("schema")
+            if schema:
+                _set_span_attribute(
+                    span,
+                    SpanAttributes.LLM_REQUEST_STRUCTURED_OUTPUT_SCHEMA,
+                    json.dumps(schema),
+                )
+        elif (
+            isinstance(response_format, pydantic.BaseModel)
+            or (
+                hasattr(response_format, "model_json_schema")
+                and callable(response_format.model_json_schema)
+            )
+        ):
+            _set_span_attribute(
+                span,
+                SpanAttributes.LLM_REQUEST_STRUCTURED_OUTPUT_SCHEMA,
+                json.dumps(response_format.model_json_schema()),
+            )
+        else:
+            schema = None
+            try:
+                schema = json.dumps(pydantic.TypeAdapter(response_format).json_schema())
+            except Exception:
+                try:
+                    schema = json.dumps(response_format)
+                except Exception:
+                    pass
+
+            if schema:
+                _set_span_attribute(
+                    span,
+                    SpanAttributes.LLM_REQUEST_STRUCTURED_OUTPUT_SCHEMA,
+                    schema,
+                )
+
+
+@dont_throw
+def _set_response_attributes(span, response):
+    if not span.is_recording():
+        return
+
+    if "error" in response:
+        _set_span_attribute(
+            span,
+            f"{GenAIAttributes.GEN_AI_PROMPT}.{PROMPT_ERROR}",
+            json.dumps(response.get("error")),
+        )
+        return
+
+    response_model = response.get("model")
+    if response_model:
+        response_model = _extract_model_name_from_provider_format(response_model)
+    _set_span_attribute(span, GenAIAttributes.GEN_AI_RESPONSE_MODEL, response_model)
+    _set_span_attribute(span, GenAIAttributes.GEN_AI_RESPONSE_ID, response.get("id"))
+
+    _set_span_attribute(
+        span,
+        SpanAttributes.LLM_OPENAI_RESPONSE_SYSTEM_FINGERPRINT,
+        response.get("system_fingerprint"),
+    )
+    _set_span_attribute(
+        span,
+        OpenAIAttributes.OPENAI_RESPONSE_SERVICE_TIER,
+        response.get("service_tier"),
+    )
+    _log_prompt_filter(span, response)
+    usage = response.get("usage")
+    if not usage:
+        return
+
+    if is_openai_v1() and not isinstance(usage, dict):
+        usage = usage.__dict__
+
+    _set_span_attribute(
+        span, SpanAttributes.LLM_USAGE_TOTAL_TOKENS, usage.get("total_tokens")
+    )
+    _set_span_attribute(
+        span,
+        GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS,
+        usage.get("completion_tokens"),
+    )
+    _set_span_attribute(
+        span, GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS, usage.get("prompt_tokens")
+    )
+    prompt_tokens_details = dict(usage.get("prompt_tokens_details", {}))
+    _set_span_attribute(
+        span,
+        SpanAttributes.LLM_USAGE_CACHE_READ_INPUT_TOKENS,
+        prompt_tokens_details.get("cached_tokens", 0),
+    )
+    return
+
+
+def _log_prompt_filter(span, response_dict):
+    if response_dict.get("prompt_filter_results"):
+        _set_span_attribute(
+            span,
+            f"{GenAIAttributes.GEN_AI_PROMPT}.{PROMPT_FILTER_KEY}",
+            json.dumps(response_dict.get("prompt_filter_results")),
+        )
+
+
+@dont_throw
+def _set_span_stream_usage(span, prompt_tokens, completion_tokens):
+    if not span.is_recording():
+        return
+
+    if isinstance(completion_tokens, int) and completion_tokens >= 0:
+        _set_span_attribute(
+            span, GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS, completion_tokens
+        )
+
+    if isinstance(prompt_tokens, int) and prompt_tokens >= 0:
+        _set_span_attribute(span, GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS, prompt_tokens)
+
+    if (
+        isinstance(prompt_tokens, int)
+        and isinstance(completion_tokens, int)
+        and completion_tokens + prompt_tokens >= 0
+    ):
+        _set_span_attribute(
+            span,
+            SpanAttributes.LLM_USAGE_TOTAL_TOKENS,
+            completion_tokens + prompt_tokens,
+        )
+
+
+def _get_openai_base_url(instance):
+    if hasattr(instance, "_client"):
+        client = instance._client  # pylint: disable=protected-access
+        if isinstance(client, (openai.AsyncOpenAI, openai.OpenAI)):
+            return str(client.base_url)
+
+    return ""
+
+
+def _get_vendor_from_url(base_url):
+    if not base_url:
+        return "openai"
+
+    if "openai.azure.com" in base_url:
+        return "Azure"
+    elif "amazonaws.com" in base_url or "bedrock" in base_url:
+        return "AWS"
+    elif "googleapis.com" in base_url or "vertex" in base_url:
+        return "Google"
+    elif "openrouter.ai" in base_url:
+        return "OpenRouter"
+
+    return "openai"
+
+
+def _cross_region_check(value):
+    if not value or "." not in value:
+        return value
+
+    prefixes = ["us", "us-gov", "eu", "apac"]
+    if any(value.startswith(prefix + ".") for prefix in prefixes):
+        parts = value.split(".")
+        if len(parts) > 2:
+            return parts[2]
+        else:
+            return value
+    else:
+        vendor, model = value.split(".", 1)
+        return model
+
+
+def _extract_model_name_from_provider_format(model_name):
+    """
+    Extract model name from provider/model format.
+    E.g., 'openai/gpt-4o' -> 'gpt-4o', 'anthropic/claude-3-sonnet' -> 'claude-3-sonnet'
+    """
+    if not model_name:
+        return model_name
+
+    if "/" in model_name:
+        parts = model_name.split("/")
+        return parts[-1]  # Return the last part (actual model name)
+
+    return model_name
+
+
+def is_streaming_response(response):
+    if is_openai_v1():
+        return isinstance(response, openai.Stream) or isinstance(
+            response, openai.AsyncStream
+        )
+
+    return isinstance(response, types.GeneratorType) or isinstance(
+        response, types.AsyncGeneratorType
+    )
+
+
+def model_as_dict(model):
+    if isinstance(model, dict):
+        return model
+    if _PYDANTIC_VERSION < "2.0.0":
+        return model.dict()
+    if hasattr(model, "model_dump"):
+        return model.model_dump()
+    elif hasattr(model, "parse"):  # Raw API response
+        return model_as_dict(model.parse())
+    else:
+        return model
+
+
+def _token_type(token_type: str):
+    if token_type == "prompt_tokens":
+        return "input"
+    elif token_type == "completion_tokens":
+        return "output"
+
+    return None
+
+
+def metric_shared_attributes(
+    response_model: str, operation: str, server_address: str, is_streaming: bool = False
+):
+    attributes = Config.get_common_metrics_attributes()
+    vendor = _get_vendor_from_url(server_address)
+
+    return {
+        **attributes,
+        GenAIAttributes.GEN_AI_SYSTEM: vendor,
+        GenAIAttributes.GEN_AI_RESPONSE_MODEL: response_model,
+        "gen_ai.operation.name": operation,
+        "server.address": server_address,
+        "stream": is_streaming,
+    }
+
+
+def propagate_trace_context(span, kwargs):
+    if is_openai_v1():
+        extra_headers = kwargs.get("extra_headers", {})
+        ctx = set_span_in_context(span)
+        TraceContextTextMapPropagator().inject(extra_headers, context=ctx)
+        kwargs["extra_headers"] = extra_headers
+    else:
+        headers = kwargs.get("headers", {})
+        ctx = set_span_in_context(span)
+        TraceContextTextMapPropagator().inject(headers, context=ctx)
+        kwargs["headers"] = headers