mseep-agentops 0.4.18__py3-none-any.whl → 0.4.23__py3-none-any.whl

agentops/sdk/exporters.py

@@ -1,10 +1,11 @@
 # Define a separate class for the authenticated OTLP exporter
 # This is imported conditionally to avoid dependency issues
-from typing import Dict, Optional, Sequence
+import threading
+from typing import Callable, Dict, Optional, Sequence
+import time
 
 import requests
-from opentelemetry.exporter.otlp.proto.http import Compression
-from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter, Compression
 from opentelemetry.sdk.trace import ReadableSpan
 from opentelemetry.sdk.trace.export import SpanExportResult
 
@@ -14,64 +15,182 @@ from agentops.logging import logger
 
 class AuthenticatedOTLPExporter(OTLPSpanExporter):
     """
-    OTLP exporter with JWT authentication support.
+    OTLP exporter with dynamic JWT authentication support.
 
-    This exporter automatically handles JWT authentication and token refresh
-    for telemetry data sent to the AgentOps API using a dedicated HTTP session
-    with authentication retry logic built in.
+    This exporter allows for updating JWT tokens dynamically without recreating
+    the exporter. It maintains a reference to a JWT token that can be updated
+    by external code, and automatically includes the latest token in requests.
     """
 
     def __init__(
         self,
         endpoint: str,
-        jwt: str,
+        jwt: Optional[str] = None,
+        jwt_provider: Optional[Callable[[], Optional[str]]] = None,
         headers: Optional[Dict[str, str]] = None,
         timeout: Optional[int] = None,
         compression: Optional[Compression] = None,
         **kwargs,
     ):
-        # TODO: Implement re-authentication
-        # FIXME: endpoint here is not "endpoint" from config
-        # self._session = HttpClient.get_authenticated_session(endpoint, api_key)
-
-        # Initialize the parent class
-        super().__init__(
-            endpoint=endpoint,
-            headers={
-                "Authorization": f"Bearer {jwt}",
-            },  # Base headers
-            timeout=timeout,
-            compression=compression,
-            # session=self._session,  # Use our authenticated session
-        )
+        """
+        Initialize the authenticated OTLP exporter.
 
-    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        Args:
+            endpoint: The OTLP endpoint URL
+            jwt: Initial JWT token (optional)
+            jwt_provider: Function to get JWT token dynamically (optional)
+            headers: Additional headers to include
+            timeout: Request timeout
+            compression: Compression type
+            **kwargs: Additional arguments (stored but not passed to parent)
         """
-        Export spans with automatic authentication handling
+        # Store JWT-related parameters separately
+        self._jwt = jwt
+        self._jwt_provider = jwt_provider
+        self._lock = threading.Lock()
+        self._last_auth_failure = 0
+        self._auth_failure_threshold = 60  # Don't retry auth failures more than once per minute
 
-        The authentication and retry logic is now handled by the underlying
-        HTTP session adapter, so we just need to call the parent export method.
+        # Store any additional kwargs for potential future use
+        self._custom_kwargs = kwargs
 
-        Args:
-            spans: The list of spans to export
+        # Filter headers to prevent override of critical headers
+        filtered_headers = self._filter_user_headers(headers) if headers else None
+
+        # Initialize parent with only known parameters
+        parent_kwargs = {}
+        if filtered_headers is not None:
+            parent_kwargs["headers"] = filtered_headers
+        if timeout is not None:
+            parent_kwargs["timeout"] = timeout
+        if compression is not None:
+            parent_kwargs["compression"] = compression
+
+        super().__init__(endpoint=endpoint, **parent_kwargs)
+
+    def _get_current_jwt(self) -> Optional[str]:
+        """Get the current JWT token from the provider or stored JWT."""
+        if self._jwt_provider:
+            try:
+                return self._jwt_provider()
+            except Exception as e:
+                logger.warning(f"Failed to get JWT token: {e}")
+        return self._jwt
+
+    def _filter_user_headers(self, headers: Optional[Dict[str, str]]) -> Optional[Dict[str, str]]:
+        """Filter user-supplied headers to prevent override of critical headers."""
+        if not headers:
+            return None
 
-        Returns:
-            The result of the export
+        # Define critical headers that cannot be overridden by user-supplied headers
+        PROTECTED_HEADERS = {
+            "authorization",
+            "content-type",
+            "user-agent",
+            "x-api-key",
+            "api-key",
+            "bearer",
+            "x-auth-token",
+            "x-session-token",
+        }
+
+        filtered_headers = {}
+        for key, value in headers.items():
+            if key.lower() not in PROTECTED_HEADERS:
+                filtered_headers[key] = value
+
+        return filtered_headers if filtered_headers else None
+
+    def _prepare_headers(self, headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        """Prepare headers with current JWT token."""
+        # Start with base headers
+        prepared_headers = dict(self._headers)
+
+        # Add any additional headers, but only allow non-critical headers
+        filtered_headers = self._filter_user_headers(headers)
+        if filtered_headers:
+            prepared_headers.update(filtered_headers)
+
+        # Add current JWT token if available (this ensures Authorization cannot be overridden)
+        jwt_token = self._get_current_jwt()
+        if jwt_token:
+            prepared_headers["Authorization"] = f"Bearer {jwt_token}"
+
+        return prepared_headers
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
         """
+        Export spans with dynamic JWT authentication.
+
+        This method overrides the parent's export to ensure we always use
+        the latest JWT token and handle authentication failures gracefully.
+        """
+        # Check if we should skip due to recent auth failure
+        with self._lock:
+            current_time = time.time()
+            if self._last_auth_failure > 0 and current_time - self._last_auth_failure < self._auth_failure_threshold:
+                logger.debug("Skipping export due to recent authentication failure")
+                return SpanExportResult.FAILURE
+
         try:
-            return super().export(spans)
+            # Get current JWT and prepare headers
+            current_headers = self._prepare_headers()
+
+            # Temporarily update the session headers for this request
+            original_headers = dict(self._session.headers)
+            self._session.headers.update(current_headers)
+
+            try:
+                # Call parent export method
+                result = super().export(spans)
+
+                # Reset auth failure timestamp on success
+                if result == SpanExportResult.SUCCESS:
+                    with self._lock:
+                        self._last_auth_failure = 0
+
+                return result
+
+            finally:
+                # Restore original headers
+                self._session.headers.clear()
+                self._session.headers.update(original_headers)
+
+        except requests.exceptions.HTTPError as e:
+            if e.response and e.response.status_code in (401, 403):
+                # Authentication error - record timestamp and warn
+                with self._lock:
+                    self._last_auth_failure = time.time()
+
+                logger.warning(
+                    f"Authentication failed during span export: {e}. "
+                    f"Will retry in {self._auth_failure_threshold} seconds."
+                )
+                return SpanExportResult.FAILURE
+            else:
+                logger.error(f"HTTP error during span export: {e}")
+                return SpanExportResult.FAILURE
+
         except AgentOpsApiJwtExpiredException as e:
-            # Authentication token expired or invalid
-            logger.warning(f"Authentication error during span export: {e}")
+            # JWT expired - record timestamp and warn
+            with self._lock:
+                self._last_auth_failure = time.time()
+
+            logger.warning(
+                f"JWT token expired during span export: {e}. Will retry in {self._auth_failure_threshold} seconds."
+            )
             return SpanExportResult.FAILURE
+
         except ApiServerException as e:
             # Server-side error
             logger.error(f"API server error during span export: {e}")
             return SpanExportResult.FAILURE
+
         except requests.RequestException as e:
             # Network or HTTP error
             logger.error(f"Network error during span export: {e}")
             return SpanExportResult.FAILURE
+
         except Exception as e:
             # Any other error
             logger.error(f"Unexpected error during span export: {e}")

agentops/semconv/README.md

@@ -0,0 +1,125 @@
+# OpenTelemetry Semantic Conventions for Generative AI Systems
+
+This module provides semantic conventions for telemetry data in AI and LLM systems, following OpenTelemetry GenAI conventions where applicable.
+
+## Core Conventions
+
+### Agent Attributes (`agent.py`)
+```python
+from agentops.semconv import AgentAttributes
+
+AgentAttributes.AGENT_NAME     # Agent name
+AgentAttributes.AGENT_ROLE     # Agent role/type
+AgentAttributes.AGENT_ID       # Unique agent identifier
+```
+
+### Tool Attributes (`tool.py`)
+```python
+from agentops.semconv import ToolAttributes, ToolStatus
+
+ToolAttributes.TOOL_NAME        # Tool name
+ToolAttributes.TOOL_PARAMETERS  # Tool input parameters
+ToolAttributes.TOOL_RESULT      # Tool execution result
+ToolAttributes.TOOL_STATUS      # Tool execution status
+
+# Tool status values
+ToolStatus.EXECUTING   # Tool is executing
+ToolStatus.SUCCEEDED   # Tool completed successfully
+ToolStatus.FAILED      # Tool execution failed
+```
+
+### Workflow Attributes (`workflow.py`)
+```python
+from agentops.semconv import WorkflowAttributes
+
+WorkflowAttributes.WORKFLOW_NAME      # Workflow name
+WorkflowAttributes.WORKFLOW_TYPE      # Workflow type
+WorkflowAttributes.WORKFLOW_STEP_NAME # Step name
+WorkflowAttributes.WORKFLOW_STEP_STATUS # Step status
+```
+
+### LLM/GenAI Attributes (`span_attributes.py`)
+Following OpenTelemetry GenAI conventions:
+
+```python
+from agentops.semconv import SpanAttributes
+
+# Request attributes
+SpanAttributes.LLM_REQUEST_MODEL        # Model name (e.g., "gpt-4")
+SpanAttributes.LLM_REQUEST_TEMPERATURE  # Temperature setting
+SpanAttributes.LLM_REQUEST_MAX_TOKENS   # Max tokens to generate
+
+# Response attributes  
+SpanAttributes.LLM_RESPONSE_MODEL       # Model that generated response
+SpanAttributes.LLM_RESPONSE_FINISH_REASON # Why generation stopped
+
+# Token usage
+SpanAttributes.LLM_USAGE_PROMPT_TOKENS     # Input tokens
+SpanAttributes.LLM_USAGE_COMPLETION_TOKENS # Output tokens
+SpanAttributes.LLM_USAGE_TOTAL_TOKENS      # Total tokens
+```
+
+### Message Attributes (`message.py`)
+For chat-based interactions:
+
+```python
+from agentops.semconv import MessageAttributes
+
+# Prompt messages (indexed)
+MessageAttributes.PROMPT_ROLE.format(i=0)     # Role at index 0
+MessageAttributes.PROMPT_CONTENT.format(i=0)  # Content at index 0
+
+# Completion messages (indexed)
+MessageAttributes.COMPLETION_ROLE.format(i=0)    # Role at index 0
+MessageAttributes.COMPLETION_CONTENT.format(i=0) # Content at index 0
+
+# Tool calls (indexed)
+MessageAttributes.TOOL_CALL_NAME.format(i=0)      # Tool name
+MessageAttributes.TOOL_CALL_ARGUMENTS.format(i=0) # Tool arguments
+```
+
+### Core Attributes (`core.py`)
+```python
+from agentops.semconv import CoreAttributes
+
+CoreAttributes.TRACE_ID    # Trace identifier
+CoreAttributes.SPAN_ID     # Span identifier
+CoreAttributes.PARENT_ID   # Parent span identifier
+CoreAttributes.TAGS        # User-defined tags
+```
+
+## Usage Guidelines
+
+1. **Follow OpenTelemetry conventions** - Use `gen_ai.*` prefixed attributes for LLM operations
+2. **Use indexed attributes for collections** - Messages, tool calls, etc. should use `.format(i=index)`
+3. **Prefer specific over generic** - Use `SpanAttributes.LLM_REQUEST_MODEL` over custom attributes
+4. **Document custom attributes** - If you need provider-specific attributes, document them clearly
+
+## Provider-Specific Conventions
+
+### OpenAI
+- `SpanAttributes.LLM_OPENAI_RESPONSE_SYSTEM_FINGERPRINT`
+- `SpanAttributes.LLM_OPENAI_API_VERSION`
+
+### LangChain  
+- `LangChainAttributes.CHAIN_TYPE`
+- `LangChainAttributes.TOOL_NAME`
+
+## Metrics (`meters.py`)
+
+Standard metrics for instrumentation:
+
+```python
+from agentops.semconv import Meters
+
+Meters.LLM_TOKEN_USAGE         # Token usage histogram
+Meters.LLM_OPERATION_DURATION  # Operation duration histogram
+Meters.LLM_COMPLETIONS_EXCEPTIONS # Exception counter
+```
+
+## Best Practices
+
+1. **Consistency** - Use the same attributes across instrumentations
+2. **Completeness** - Capture essential attributes for debugging
+3. **Performance** - Avoid capturing large payloads as attributes
+4. **Privacy** - Be mindful of sensitive data in attributes

agentops/semconv/span_kinds.py

@@ -13,7 +13,6 @@ class AgentOpsSpanKindValues(Enum):
     AGENT = "agent"
     TOOL = "tool"
     LLM = "llm"
-    TEAM = "team"
     CHAIN = "chain"
     TEXT = "text"
     GUARDRAIL = "guardrail"
@@ -42,7 +41,6 @@ class SpanKind:
     AGENT = AgentOpsSpanKindValues.AGENT.value
     TOOL = AgentOpsSpanKindValues.TOOL.value
     LLM = AgentOpsSpanKindValues.LLM.value
-    TEAM = AgentOpsSpanKindValues.TEAM.value
     UNKNOWN = AgentOpsSpanKindValues.UNKNOWN.value
     CHAIN = AgentOpsSpanKindValues.CHAIN.value
     TEXT = AgentOpsSpanKindValues.TEXT.value

agentops/validation.py

@@ -5,12 +5,15 @@ This module provides functions to validate that spans have been sent to AgentOps
 using the public API. This is useful for testing and verification purposes.
 """
 
+import asyncio
+import os
 import time
-import requests
 from typing import Optional, Dict, List, Any, Tuple
 
-from agentops.logging import logger
+import requests
+
 from agentops.exceptions import ApiServerException
+from agentops.logging import logger
 
 
 class ValidationError(Exception):
@@ -19,40 +22,84 @@ class ValidationError(Exception):
     pass
 
 
-def get_jwt_token(api_key: Optional[str] = None) -> str:
+async def get_jwt_token(api_key: Optional[str] = None) -> str:
     """
-    Exchange API key for JWT token.
+    Exchange API key for JWT token asynchronously.
 
     Args:
         api_key: Optional API key. If not provided, uses AGENTOPS_API_KEY env var.
 
     Returns:
-        JWT bearer token
+        JWT bearer token, or None if failed
 
-    Raises:
-        ApiServerException: If token exchange fails
+    Note:
+        This function never throws exceptions - all errors are handled gracefully
     """
-    if api_key is None:
-        from agentops import get_client
+    try:
+        if api_key is None:
+            from agentops import get_client
 
-        client = get_client()
-        if client and client.config.api_key:
-            api_key = client.config.api_key
-        else:
-            import os
+            client = get_client()
+            if client and client.config.api_key:
+                api_key = client.config.api_key
+            else:
+                api_key = os.getenv("AGENTOPS_API_KEY")
+                if not api_key:
+                    logger.warning("No API key provided and AGENTOPS_API_KEY environment variable not set")
+                    return None
+
+        # Use a separate aiohttp session for validation to avoid conflicts
+        import aiohttp
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                "https://api.agentops.ai/public/v1/auth/access_token",
+                json={"api_key": api_key},
+                timeout=aiohttp.ClientTimeout(total=10),
+            ) as response:
+                if response.status >= 400:
+                    logger.warning(f"Failed to get JWT token: HTTP {response.status} - backend may be unavailable")
+                    return None
+
+                response_data = await response.json()
+
+                if "bearer" not in response_data:
+                    logger.warning("Failed to get JWT token: No bearer token in response")
+                    return None
+
+                return response_data["bearer"]
+
+    except Exception as e:
+        logger.warning(f"Failed to get JWT token: {e} - continuing without authentication")
+        return None
+
+
+def get_jwt_token_sync(api_key: Optional[str] = None) -> Optional[str]:
+    """
+    Synchronous wrapper for get_jwt_token - runs async function in event loop.
 
-            api_key = os.getenv("AGENTOPS_API_KEY")
-            if not api_key:
-                raise ValueError("No API key provided and AGENTOPS_API_KEY environment variable not set")
+    Args:
+        api_key: Optional API key. If not provided, uses AGENTOPS_API_KEY env var.
 
+    Returns:
+        JWT bearer token, or None if failed
+
+    Note:
+        This function never throws exceptions - all errors are handled gracefully
+    """
     try:
-        response = requests.post(
-            "https://api.agentops.ai/public/v1/auth/access_token", json={"api_key": api_key}, timeout=10
-        )
-        response.raise_for_status()
-        return response.json()["bearer"]
-    except requests.exceptions.RequestException as e:
-        raise ApiServerException(f"Failed to get JWT token: {e}")
+        import concurrent.futures
+
+        # Always run in a separate thread to avoid event loop issues
+        def run_in_thread():
+            return asyncio.run(get_jwt_token(api_key))
+
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            future = executor.submit(run_in_thread)
+            return future.result()
+    except Exception as e:
+        logger.warning(f"Failed to get JWT token synchronously: {e}")
+        return None
 
 
 def get_trace_details(trace_id: str, jwt_token: str) -> Dict[str, Any]:
@@ -121,60 +168,36 @@ def check_llm_spans(spans: List[Dict[str, Any]]) -> Tuple[bool, List[str]]:
 
     for span in spans:
         span_name = span.get("span_name", "unnamed_span")
-
-        # Check span attributes for LLM span kind
         span_attributes = span.get("span_attributes", {})
         is_llm_span = False
 
-        # If we have span_attributes, check them
         if span_attributes:
-            # Try different possible structures for span kind
-            span_kind = None
-
-            # Structure 1: span_attributes.agentops.span.kind
-            if isinstance(span_attributes, dict):
+            # Check for LLM span kind - handle both flat and nested structures
+            span_kind = span_attributes.get("agentops.span.kind", "")
+            if not span_kind:
+                # Check nested structure: agentops.span.kind or agentops -> span -> kind
                 agentops_attrs = span_attributes.get("agentops", {})
                 if isinstance(agentops_attrs, dict):
-                    span_info = agentops_attrs.get("span", {})
-                    if isinstance(span_info, dict):
-                        span_kind = span_info.get("kind", "")
-
-            # Structure 2: Direct in span_attributes
-            if not span_kind and isinstance(span_attributes, dict):
-                # Try looking for agentops.span.kind as a flattened key
-                span_kind = span_attributes.get("agentops.span.kind", "")
-
-            # Structure 3: Look for SpanAttributes.AGENTOPS_SPAN_KIND
-            if not span_kind and isinstance(span_attributes, dict):
-                from agentops.semconv import SpanAttributes
+                    span_attrs = agentops_attrs.get("span", {})
+                    if isinstance(span_attrs, dict):
+                        span_kind = span_attrs.get("kind", "")
 
-                span_kind = span_attributes.get(SpanAttributes.AGENTOPS_SPAN_KIND, "")
-
-            # Check if this is an LLM span by span kind
             is_llm_span = span_kind == "llm"
 
-            # Alternative check: Look for gen_ai.prompt or gen_ai.completion attributes
-            # These are standard semantic conventions for LLM spans
-            if not is_llm_span and isinstance(span_attributes, dict):
+            # Alternative check: Look for gen_ai attributes
+            if not is_llm_span:
                 gen_ai_attrs = span_attributes.get("gen_ai", {})
                 if isinstance(gen_ai_attrs, dict):
-                    # If we have prompt or completion data, it's an LLM span
                     if "prompt" in gen_ai_attrs or "completion" in gen_ai_attrs:
                         is_llm_span = True
 
-            # Check for LLM_REQUEST_TYPE attribute (used by provider instrumentations)
-            if not is_llm_span and isinstance(span_attributes, dict):
-                from agentops.semconv import SpanAttributes, LLMRequestTypeValues
-
-                # Check for LLM request type - try both gen_ai.* and llm.* prefixes
-                # The instrumentation sets gen_ai.* but the API might return llm.*
-                llm_request_type = span_attributes.get(SpanAttributes.LLM_REQUEST_TYPE, "")
+            # Check for LLM request type
+            if not is_llm_span:
+                llm_request_type = span_attributes.get("gen_ai.request.type", "")
                 if not llm_request_type:
-                    # Try the llm.* prefix version
+                    # Also check for older llm.request.type format
                     llm_request_type = span_attributes.get("llm.request.type", "")
-
-                # Check if it's a chat or completion request (the main LLM types)
-                if llm_request_type in [LLMRequestTypeValues.CHAT.value, LLMRequestTypeValues.COMPLETION.value]:
+                if llm_request_type in ["chat", "completion"]:
                     is_llm_span = True
 
         if is_llm_span:
@@ -242,7 +265,19 @@ def validate_trace_spans(
         raise ValueError("No trace ID found. Provide either trace_id or trace_context parameter.")
 
     # Get JWT token
-    jwt_token = get_jwt_token(api_key)
+    jwt_token = get_jwt_token_sync(api_key)
+    if not jwt_token:
+        logger.warning("Could not obtain JWT token - validation will be skipped")
+        return {
+            "trace_id": trace_id,
+            "span_count": 0,
+            "spans": [],
+            "has_llm_spans": False,
+            "llm_span_names": [],
+            "metrics": None,
+            "validation_skipped": True,
+            "reason": "No JWT token available",
+        }
 
     logger.info(f"Validating spans for trace ID: {trace_id}")
 
@@ -335,6 +370,10 @@ def print_validation_summary(result: Dict[str, Any]) -> None:
     print("🔍 AgentOps Span Validation Results")
     print("=" * 50)
 
+    if result.get("validation_skipped"):
+        print(f"⚠️  Validation skipped: {result.get('reason', 'Unknown reason')}")
+        return
+
     print(f"✅ Found {result['span_count']} span(s) in trace")
 
     if result.get("has_llm_spans"):