paid-python 1.2.0__tar.gz → 1.3.0__tar.gz

{paid_python-1.2.0 → paid_python-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: paid-python
-Version: 1.2.0
+Version: 1.3.0
 Summary: 
 Requires-Python: >=3.10,<3.14
 Classifier: Intended Audience :: Developers

{paid_python-1.2.0 → paid_python-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ dynamic = ["version"]
 
 [tool.poetry]
 name = "paid-python"
-version = "1.2.0"
+version = "1.3.0"
 description = ""
 readme = "README.md"
 authors = []

{paid_python-1.2.0 → paid_python-1.3.0}/src/paid/core/client_wrapper.py

@@ -24,12 +24,12 @@ class BaseClientWrapper:
         import platform
 
         headers: typing.Dict[str, str] = {
-            "User-Agent": "paid-python/1.2.0",
+            "User-Agent": "paid-python/1.3.0",
             "X-Fern-Language": "Python",
             "X-Fern-Runtime": f"python/{platform.python_version()}",
             "X-Fern-Platform": f"{platform.system().lower()}/{platform.release()}",
             "X-Fern-SDK-Name": "paid-python",
-            "X-Fern-SDK-Version": "1.2.0",
+            "X-Fern-SDK-Version": "1.3.0",
             **(self.get_custom_headers() or {}),
         }
         headers["Authorization"] = f"Bearer {self._get_token()}"

{paid_python-1.2.0 → paid_python-1.3.0}/src/paid/tracing/autoinstrumentation.py

@@ -203,10 +203,13 @@ def _instrument_openai_agents() -> None:
         logger.warning("OpenAI Agents library not available, skipping instrumentation")
         return
 
+    from .openai_agents_patches import instrument_openai_agents
+
     logger.debug("[paid:autoinstrument] Instrumenting openai-agents with OpenAIAgentsInstrumentor, provider=%s",
                  type(tracing.paid_tracer_provider).__name__)
     # Instrument OpenAI Agents with Paid's tracer provider
     OpenAIAgentsInstrumentor().instrument(tracer_provider=tracing.paid_tracer_provider)
+    instrument_openai_agents()
 
     _initialized_instrumentors.append("openai-agents")
     logger.info("OpenAI Agents auto-instrumentation enabled")

paid_python-1.3.0/src/paid/tracing/openai_agents_patches/__init__.py

@@ -0,0 +1,15 @@
+"""Patches for openinference-instrumentation-openai-agents.
+
+Adds tool metadata to function/tool spans by carrying schema details from
+response spans onto the later function execution spans.
+"""
+
+from .patches import (
+    instrument_openai_agents,
+    uninstrument_openai_agents,
+)
+
+__all__ = [
+    "instrument_openai_agents",
+    "uninstrument_openai_agents",
+]

paid_python-1.3.0/src/paid/tracing/openai_agents_patches/patches.py

@@ -0,0 +1,189 @@
+"""Monkey-patches for openinference-instrumentation-openai-agents.
+
+Upstream records full tool schemas on response spans, but function/tool spans only
+get `tool.name`. This patch caches function tool metadata per trace when the
+response span ends, then applies that metadata to subsequent function spans.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+from agents.tracing.span_data import FunctionSpanData, ResponseSpanData
+from openai.types.responses import FunctionTool, Response
+from openinference.instrumentation import safe_json_dumps
+from opentelemetry.context import detach
+from opentelemetry.trace import Status, StatusCode
+from opentelemetry.util.types import AttributeValue
+
+from paid.logger import logger
+
+_originals: dict[str, Any] = {}
+_SEMCONV_FALLBACKS = {
+    "TOOL_DESCRIPTION": "tool.description",
+    "TOOL_PARAMETERS": "tool.parameters",
+    "TOOL_JSON_SCHEMA": "tool.json_schema",
+}
+
+
+def instrument_openai_agents() -> None:
+    """Apply all OpenAI Agents patches. Call after instrumenting the SDK."""
+    _patch_tracing_processor()
+
+
+def uninstrument_openai_agents() -> None:
+    """Restore original OpenAI Agents methods."""
+    try:
+        from openinference.instrumentation.openai_agents import _processor as processor_mod
+    except ImportError:
+        _originals.clear()
+        return
+
+    processor = processor_mod.OpenInferenceTracingProcessor
+    if "on_span_end" in _originals:
+        processor.on_span_end = _originals.pop("on_span_end")  # type: ignore[method-assign]
+    if "on_trace_end" in _originals:
+        processor.on_trace_end = _originals.pop("on_trace_end")  # type: ignore[method-assign]
+    _originals.clear()
+
+
+def _patch_tracing_processor() -> None:
+    try:
+        from openinference.instrumentation.openai_agents import _processor as processor_mod
+    except ImportError:
+        logger.debug("Could not import openai-agents tracing processor, skipping patch")
+        return
+
+    processor = processor_mod.OpenInferenceTracingProcessor
+    if "on_span_end" in _originals:
+        return
+
+    _originals["on_span_end"] = processor.on_span_end
+    _originals["on_trace_end"] = processor.on_trace_end
+
+    def _patched_on_trace_end(self, trace):  # type: ignore[misc]
+        try:
+            return _originals["on_trace_end"](self, trace)
+        finally:
+            tool_cache = getattr(self, "_paid_tool_schemas_by_trace", None)
+            if isinstance(tool_cache, dict):
+                tool_cache.pop(trace.trace_id, None)
+
+    def _patched_on_span_end(self, span):  # type: ignore[misc]
+        if token := self._tokens.pop(span.span_id, None):
+            detach(token)  # type: ignore[arg-type]
+        if not (otel_span := self._otel_spans.pop(span.span_id, None)):
+            return
+
+        processing_error: Exception | None = None
+        end_time: Optional[int] = None
+        try:
+            otel_span.update_name(processor_mod._get_span_name(span))
+            data = span.span_data
+            if isinstance(data, ResponseSpanData):
+                if hasattr(data, "response") and isinstance(response := data.response, Response):
+                    _cache_tool_schemas(self, span.trace_id, response)
+                    otel_span.set_attribute(processor_mod.OUTPUT_MIME_TYPE, processor_mod.JSON)
+                    otel_span.set_attribute(processor_mod.OUTPUT_VALUE, response.model_dump_json())
+                    for k, v in processor_mod._get_attributes_from_response(response):
+                        otel_span.set_attribute(k, v)
+                if hasattr(data, "input") and (input := data.input):
+                    if isinstance(input, str):
+                        otel_span.set_attribute(processor_mod.INPUT_VALUE, input)
+                    elif isinstance(input, list):
+                        otel_span.set_attribute(processor_mod.INPUT_MIME_TYPE, processor_mod.JSON)
+                        otel_span.set_attribute(processor_mod.INPUT_VALUE, safe_json_dumps(input))
+                        for k, v in processor_mod._get_attributes_from_input(input):
+                            otel_span.set_attribute(k, v)
+            elif isinstance(data, FunctionSpanData):
+                for k, v in processor_mod._get_attributes_from_function_span_data(data):
+                    otel_span.set_attribute(k, v)
+                for k, v in _get_enriched_function_attributes(self, span.trace_id, data.name):
+                    otel_span.set_attribute(k, v)
+            elif isinstance(data, processor_mod.MCPListToolsSpanData):
+                for k, v in processor_mod._get_attributes_from_mcp_list_tool_span_data(data):
+                    otel_span.set_attribute(k, v)
+            elif isinstance(data, processor_mod.HandoffSpanData):
+                if data.to_agent and data.from_agent:
+                    key = f"{data.to_agent}:{span.trace_id}"
+                    self._reverse_handoffs_dict[key] = data.from_agent
+                    while len(self._reverse_handoffs_dict) > self._MAX_HANDOFFS_IN_FLIGHT:
+                        self._reverse_handoffs_dict.popitem(last=False)
+            elif isinstance(data, processor_mod.AgentSpanData):
+                otel_span.set_attribute(processor_mod.GRAPH_NODE_ID, data.name)
+                key = f"{data.name}:{span.trace_id}"
+                if parent_node := self._reverse_handoffs_dict.pop(key, None):
+                    otel_span.set_attribute(processor_mod.GRAPH_NODE_PARENT_ID, parent_node)
+            elif isinstance(data, processor_mod.GenerationSpanData):
+                for k, v in processor_mod._get_attributes_from_generation_span_data(data):
+                    otel_span.set_attribute(k, v)
+            elif isinstance(data, (processor_mod.CustomSpanData, processor_mod.GuardrailSpanData)):
+                for k, v in processor_mod._flatten(data.export()):
+                    otel_span.set_attribute(k, v)
+        except Exception as exc:
+            processing_error = exc
+            logger.debug("Failed to enrich openai-agents span", exc_info=True)
+            try:
+                otel_span.record_exception(exc)
+            except Exception:
+                logger.debug("Failed to record openai-agents patch exception", exc_info=True)
+        finally:
+            if span.ended_at:
+                try:
+                    end_time = processor_mod._as_utc_nano(datetime.fromisoformat(span.ended_at))
+                except ValueError:
+                    pass
+            if processing_error is not None:
+                otel_span.set_status(Status(StatusCode.ERROR, str(processing_error)))
+            else:
+                otel_span.set_status(status=processor_mod._get_span_status(span))
+            otel_span.end(end_time)
+
+    processor.on_trace_end = _patched_on_trace_end  # type: ignore[method-assign]
+    processor.on_span_end = _patched_on_span_end  # type: ignore[method-assign]
+    logger.debug("Patched OpenInferenceTracingProcessor to enrich openai-agents tool spans")
+
+
+def _cache_tool_schemas(processor: Any, trace_id: str, response: Response) -> None:
+    per_trace = getattr(processor, "_paid_tool_schemas_by_trace", None)
+    if not isinstance(per_trace, dict):
+        per_trace = {}
+        setattr(processor, "_paid_tool_schemas_by_trace", per_trace)
+
+    tool_map = per_trace.setdefault(trace_id, {})
+    for tool in response.tools or []:
+        if not isinstance(tool, FunctionTool):
+            continue
+        attrs: dict[str, AttributeValue] = {}
+        if tool.description:
+            attrs[processor_mod_attr("TOOL_DESCRIPTION")] = tool.description
+        if tool.parameters is not None:
+            attrs[processor_mod_attr("TOOL_PARAMETERS")] = safe_json_dumps(tool.parameters)
+        attrs[processor_mod_attr("TOOL_JSON_SCHEMA")] = safe_json_dumps(
+            {
+                "type": "function",
+                "function": {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "parameters": tool.parameters,
+                    "strict": tool.strict,
+                },
+            }
+        )
+        tool_map[tool.name] = attrs
+
+
+def _get_enriched_function_attributes(
+    processor: Any,
+    trace_id: str,
+    tool_name: str,
+):
+    tool_map = getattr(processor, "_paid_tool_schemas_by_trace", {}).get(trace_id, {})
+    yield from tool_map.get(tool_name, {}).items()
+
+
+def processor_mod_attr(name: str) -> str:
+    from openinference.instrumentation.openai_agents import _processor as processor_mod
+
+    return getattr(processor_mod, name, _SEMCONV_FALLBACKS.get(name, name.lower()))

{paid_python-1.2.0 → paid_python-1.3.0}/src/paid/tracing/tracing.py

@@ -5,7 +5,7 @@ import os
 import random
 import signal
 from dataclasses import dataclass
-from typing import Any, Awaitable, Callable, Dict, Optional, Tuple, TypeVar, Union
+from typing import Any, Awaitable, Callable, Dict, Literal, Optional, Tuple, TypeVar, Union
 
 from . import distributed_tracing
 from .context_data import ContextData
@@ -13,7 +13,7 @@ from opentelemetry import trace
 from opentelemetry.context import Context
 from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 from opentelemetry.sdk.trace import ReadableSpan, Span, SpanLimits, SpanProcessor, TracerProvider
-from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SimpleSpanProcessor
 from opentelemetry.sdk.trace.sampling import ALWAYS_ON
 from opentelemetry.trace import NonRecordingSpan, NoOpTracerProvider, SpanContext, Status, StatusCode, TraceFlags
 from opentelemetry.util.types import Attributes
@@ -43,6 +43,9 @@ class ProcessorSettings:
     pydantic: Optional[PydanticProcessorSettings] = None
     """Settings for Pydantic AI span processing. If provided, enables Pydantic-specific filtering."""
 
+    export_mode: Literal["batch", "simple"] = "simple"
+    """Span export strategy. Defaults to simple."""
+
 
 # Scope name constants for library-specific tracers
 PYDANTIC_SCOPE_NAME = "paid.pydantic"
@@ -201,6 +204,10 @@ class PaidSpanProcessor(SpanProcessor):
         "logfire.json_schema",
     }
 
+    def __init__(self, span_processor_mode: Literal["batch", "simple"] = "simple") -> None:
+        """Initialize processor with the export mode used by the OTLP span processor."""
+        self._span_processor_mode = span_processor_mode
+
     def on_start(self, span: Span, parent_context: Optional[Context] = None) -> None:
         """Called when a span is started. Prefix the span name and add attributes."""
 
@@ -232,6 +239,7 @@ class PaidSpanProcessor(SpanProcessor):
 
         # Always stamp the SDK version so the backend can identify the source
         span.set_attribute("paid.sdk.version", f"python-{_paid_version}")
+        span.set_attribute("paid_span_processor_mode", self._span_processor_mode)
 
         logger.debug(
             "[paid:span] on_start: name=%s, customer_id=%s, agent_id=%s",
@@ -419,7 +427,8 @@ def initialize_tracing(
     Args:
         api_key: The API key for authentication. If not provided, will try to get from PAID_API_KEY environment variable.
         collector_endpoint: The OTLP collector endpoint URL.
-        processor_settings: Optional configuration for span processors (deprecated for Pydantic - use get_paid_tracer_pydantic instead).
+        processor_settings: Optional configuration for span processors. Pydantic settings here are deprecated;
+            use get_paid_tracer_pydantic instead.
 
     Example:
         # Basic initialization
@@ -479,8 +488,10 @@ def initialize_tracing(
         paid_tracer_provider._disabled = False
         logger.debug("[paid:init] TracerProvider created (sampler=ALWAYS_ON, OTEL_SDK_DISABLED overridden)")
 
+        processor_settings = processor_settings or ProcessorSettings()
+
         # Add span processor to prefix span names and add customer/agent ID attributes
-        paid_tracer_provider.add_span_processor(PaidSpanProcessor())
+        paid_tracer_provider.add_span_processor(PaidSpanProcessor(span_processor_mode=processor_settings.export_mode))
         logger.debug("[paid:init] Added PaidSpanProcessor")
 
         # Add Pydantic span processor - it self-filters by scope using the settings registry
@@ -500,12 +511,31 @@ def initialize_tracing(
             timeout=10,  # Explicit timeout to prevent env var OTEL_EXPORTER_OTLP_TIMEOUT override
         )
 
-        # Use SimpleSpanProcessor for immediate span export.
-        # There are problems with BatchSpanProcessor in some environments - ex. Airflow.
-        # Airflow terminates processes before the batch is sent, losing traces.
-        span_processor = SimpleSpanProcessor(otlp_exporter)
+        span_processor: SpanProcessor
+
+        if processor_settings.export_mode == "batch":
+            # BatchSpanProcessor exports from a worker thread so collector outages do not
+            # block user logic on span end.
+            span_processor = BatchSpanProcessor(
+                otlp_exporter,
+                schedule_delay_millis=500,
+                max_export_batch_size=64,
+                max_queue_size=2048,
+                export_timeout_millis=10_000,
+            )
+            logger.debug("[paid:init] Using BatchSpanProcessor for non-blocking span export")
+        else:
+            # SimpleSpanProcessor exports inline. Keep it as an opt-in for short-lived
+            # environments where losing spans on process exit is worse than blocking.
+            span_processor = SimpleSpanProcessor(otlp_exporter)
+            logger.debug("[paid:init] Using SimpleSpanProcessor for immediate span export")
+
         paid_tracer_provider.add_span_processor(span_processor)
-        logger.debug("[paid:init] Added SimpleSpanProcessor with OTLPSpanExporter -> %s", collector_endpoint)
+        logger.debug(
+            "[paid:init] Added %s with OTLPSpanExporter -> %s",
+            type(span_processor).__name__,
+            collector_endpoint,
+        )
 
         setup_graceful_termination(paid_tracer_provider)  # doesn't throw