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

agentops/integration/callbacks/langchain/utils.py

@@ -0,0 +1,54 @@
+"""
+Utility functions for LangChain integration.
+"""
+
+from typing import Any, Dict, Optional
+
+from agentops.logging import logger
+
+
+def get_model_info(serialized: Optional[Dict[str, Any]]) -> Dict[str, str]:
+    """
+    Extract model information from serialized LangChain data.
+
+    This function attempts to extract model name information
+    from the serialized data of a LangChain model.
+
+    Args:
+        serialized: Serialized data from LangChain
+
+    Returns:
+        Dictionary with model_name key
+    """
+    if serialized is None:
+        return {"model_name": "unknown"}
+
+    model_info = {"model_name": "unknown"}
+
+    try:
+        if isinstance(serialized.get("id"), list) and len(serialized["id"]) > 0:
+            id_list = serialized["id"]
+            if len(id_list) > 0:
+                model_info["model_name"] = id_list[-1]
+
+        if isinstance(serialized.get("model_name"), str):
+            model_info["model_name"] = serialized["model_name"]
+
+        elif serialized.get("id") and isinstance(serialized.get("id"), str):
+            model_id = serialized.get("id", "")
+            if "/" in model_id:
+                _, model_name = model_id.split("/", 1)
+                model_info["model_name"] = model_name
+            else:
+                model_info["model_name"] = model_id
+
+        if serialized.get("kwargs") and isinstance(serialized["kwargs"], dict):
+            if serialized["kwargs"].get("model_name"):
+                model_info["model_name"] = serialized["kwargs"]["model_name"]
+            elif serialized["kwargs"].get("model"):
+                model_info["model_name"] = serialized["kwargs"]["model"]
+
+    except Exception as e:
+        logger.warning(f"Error extracting model info: {e}")
+
+    return model_info

agentops/legacy/crewai.md

@@ -0,0 +1,121 @@
+# CrewAI Integration Reference
+
+## Overview
+This document provides information about CrewAI's integration with AgentOps and how our legacy compatibility layer supports different versions of CrewAI.
+
+## CrewAI Integration Points
+
+CrewAI has two distinct integration patterns with AgentOps:
+
+### 1. Direct Integration (CrewAI < 0.105.0)
+In CrewAI versions 0.98.0 through 0.102.0, integration is done directly in the core code:
+
+- In `crew.py` (_finish_execution method):
+  ```python
+  if agentops:
+      agentops.end_session(
+          end_state="Success",
+          end_state_reason="Finished Execution",
+          is_auto_end=True,
+      )
+  ```
+
+- In `tools/tool_usage.py`:
+  ```python
+  # Tool event creation
+  tool_event = agentops.ToolEvent(name=calling.tool_name) if agentops else None
+  
+  # Error recording
+  if agentops:
+      agentops.record(agentops.ErrorEvent(exception=e, trigger_event=tool_event))
+  
+  # Tool usage recording
+  if agentops:
+      agentops.record(tool_event)
+  ```
+
+### 2. Event-Based Integration (CrewAI >= 0.105.0)
+In CrewAI versions 0.105.0 and above, integration uses an event-based system:
+
+```python
+# In utilities/events/third_party/agentops_listener.py
+class AgentOpsListener(BaseEventListener):
+    # Called when a crew kickoff starts
+    @crewai_event_bus.on(CrewKickoffStartedEvent)
+    def on_crew_kickoff_started(source, event):
+        self.session = agentops.init()
+        for agent in source.agents:
+            if self.session:
+                self.session.create_agent(
+                    name=agent.role,
+                    agent_id=str(agent.id),
+                )
+
+    # Called when a crew kickoff completes
+    @crewai_event_bus.on(CrewKickoffCompletedEvent)
+    def on_crew_kickoff_completed(source, event):
+        if self.session:
+            self.session.end_session(
+                end_state="Success",
+                end_state_reason="Finished Execution",
+            )
+
+    # Tool usage and other events are also tracked
+    # ...
+```
+
+## Required AgentOps Legacy API
+
+To maintain compatibility with all CrewAI versions, our legacy API must support:
+
+### Function Signatures
+
+| Function | Parameters | Used By |
+|----------|------------|---------|
+| `agentops.init()` | - | All versions, returns a Session object |
+| `agentops.end_session()` | Various (see below) | All versions |
+| `agentops.record()` | Event object | CrewAI < 0.105.0 |
+| `agentops.ToolEvent()` | `name` | CrewAI < 0.105.0 |
+| `agentops.ErrorEvent()` | `exception`, `trigger_event` | CrewAI < 0.105.0 |
+| `agentops.ActionEvent()` | `action_type` | Used in tests |
+
+### Supported `end_session()` Calls
+
+The `end_session()` function must handle:
+
+1. A simple string status:
+   ```python
+   agentops.end_session("Success")
+   ```
+
+2. Named arguments from CrewAI < 0.105.0:
+   ```python
+   agentops.end_session(
+       end_state="Success",
+       end_state_reason="Finished Execution",
+       is_auto_end=True
+   )
+   ```
+
+3. Session object method calls from CrewAI >= 0.105.0:
+   ```python
+   session.end_session(
+       end_state="Success",
+       end_state_reason="Finished Execution"
+   )
+   ```
+
+### Session Class Methods
+
+The Session class must support:
+
+1. `create_agent(name, agent_id)` - Used in CrewAI >= 0.105.0
+2. `record(event)` - Used in CrewAI >= 0.105.0
+3. `end_session(**kwargs)` - Used in CrewAI >= 0.105.0
+
+## Implementation Guidelines
+
+- All legacy interfaces should accept their parameters without errors but don't need to implement actual functionality.
+- New code should use OpenTelemetry instrumentation instead of these legacy interfaces.
+- This compatibility layer will be maintained until CrewAI migrates to using OpenTelemetry directly.
+- Tests ensure backward compatibility with both integration patterns.

agentops/logging/instrument_logging.py

@@ -9,6 +9,8 @@ _original_print = builtins.print
 # Global buffer to store logs
 _log_buffer = StringIO()
 
+print_logger = None
+
 
 def setup_print_logger() -> None:
     """
@@ -29,6 +31,8 @@ def setup_print_logger() -> None:
         # Ensure the new logger doesn't propagate to root
         buffer_logger.propagate = False
 
+    global print_logger
+
     def print_logger(*args: Any, **kwargs: Any) -> None:
         """
         Custom print function that logs to buffer and console.

agentops/sdk/README.md

@@ -0,0 +1,220 @@
+# AgentOps v0.4 Architecture
+
+## Transition from Events to Spans
+
+In AgentOps v0.4, we've transitioned from the "Event" concept to using "Spans" for all event tracking. This proposal outlines a new architecture that supports this transition and enables custom implementations through decorators.
+
+## Core Concepts
+
+1. **Session**: The master trace that serves as the root for all spans. No spans can exist without a session at the top.
+2. **Spans**: Represent different types of operations (Agent, Tool, etc.) and are organized hierarchically.
+3. **Decorators**: Allow users to easily mark their custom components with AgentOps-specific span types.
+4. **TracingConfig**: A dedicated configuration structure for the tracing core, separate from the main application configuration.
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    %% Core Tracing Components
+    subgraph "Core Tracing Infrastructure"
+        TracingCore[Tracing Core]
+        TracingConfig[Tracing Config]
+        SpanFactory[Span Factory]
+        SpanProcessor[Span Processor]
+        SpanExporter[Span Exporter]
+        
+        TracingConfig --> TracingCore
+        TracingCore --> SpanFactory
+        TracingCore --> SpanProcessor
+        SpanProcessor --> SpanExporter
+    end
+    
+    %% Span Base Classes
+    subgraph "Span Base Classes"
+        TracedObject[TracedObject]
+    end
+    
+    %% Span Types
+    subgraph "Span Types"
+        SessionSpan[SessionSpan]
+        AgentSpan[AgentSpan]
+        ToolSpan[ToolSpan]
+        LLMSpan[LLMSpan]
+        CustomSpan[CustomSpan]
+        
+        TracedObject --> SessionSpan
+        TracedObject --> AgentSpan
+        TracedObject --> ToolSpan
+        TracedObject --> LLMSpan
+        TracedObject --> CustomSpan
+    end
+    
+    %% Decorators
+    subgraph "Decorators"
+        SessionDecorator[session]
+        AgentDecorator[agent]
+        ToolDecorator[tool]
+        LLMDecorator[llm]
+        
+        AgentDecorator --> AgentSpan
+        ToolDecorator --> ToolSpan
+        SessionDecorator --> SessionSpan
+        LLMDecorator --> LLMSpan
+    end
+    
+    %% User-Facing Classes
+    subgraph "User-Facing Classes"
+        Session[Session]
+        Agent[Agent]
+        Tool[Tool]
+        
+        SessionSpan --> Session
+        AgentSpan --> Agent
+        ToolSpan --> Tool
+    end
+    
+    %% Relationships
+    SpanFactory --> TracedObject
+    Session -.->|"Master Trace"| Agent
+    Session -.->|"Master Trace"| Tool
+    
+    %% Context Management
+    subgraph "Context Management"
+        SpanContext[Span Context]
+        Registry[Registry]
+        
+        SpanContext <--> Registry
+    end
+    
+    TracingCore <--> SpanContext
+    
+    class TracingCore,SpanFactory,SpanProcessor,SpanExporter core
+    class TracedObject base
+    class SessionSpan,AgentSpan,ToolSpan,LLMSpan,CustomSpan span
+    class SessionDecorator,AgentDecorator,ToolDecorator,LLMDecorator decorator
+    class Session,Agent,Tool user
+    class SpanContext,Registry context
+```
+
+## Component Descriptions
+
+### Core Tracing Infrastructure
+
+- **Tracing Core**: Central component that manages the creation, processing, and export of spans.
+- **Tracing Config**: Configuration specific to the tracing infrastructure, separate from the main application configuration.
+- **Span Factory**: Creates spans of different types based on context and decorator information.
+- **Span Processor**: Processes spans (adds attributes, manages context, etc.) before they are exported.
+- **Span Exporter**: Exports spans to the configured destination (e.g., AgentOps backend).
+
+### Span Base Classes
+
+- **TracedObject**: Base class that provides core tracing functionality (trace ID, span ID, etc.) and common span operations (start, end, attributes).
+
+### Span Types
+
+- **SessionSpan**: Represents a session (master trace).
+- **AgentSpan**: Represents an agent operation.
+- **ToolSpan**: Represents a tool operation.
+- **LLMSpan**: Represents an LLM operation.
+- **CustomSpan**: Allows for custom span types.
+
+### Decorators
+
+- **@session**: Creates a new session span.
+- **@agent**: Creates a new agent span.
+- **@tool**: Creates a new tool span.
+- **@llm**: Creates a new LLM span.
+
+### User-Facing Classes
+
+- **Session**: User-facing session class that wraps SessionSpan.
+- **Agent**: User-facing agent class that wraps AgentSpan.
+- **Tool**: User-facing tool class that wraps ToolSpan.
+
+### Context Management
+
+- **Span Context**: Manages the current span context (parent-child relationships).
+- **Registry**: Keeps track of active spans and their relationships.
+
+## Implementation Considerations
+
+1. **Decorator Implementation**:
+   ```python
+   def agent(cls=None, **kwargs):
+       def decorator(cls):
+           # Wrap methods with span creation/management
+           original_init = cls.__init__
+           
+           def __init__(self, *args, **init_kwargs):
+               # Get current session from context
+               session = get_current_session()
+               if not session:
+                   raise ValueError("No active session found. Create a session first.")
+               
+               # Create agent span as child of session
+               self._span = create_span("agent", parent=session.span, **kwargs)
+               
+               # Call original init
+               original_init(self, *args, **init_kwargs)
+           
+           cls.__init__ = __init__
+           return cls
+       
+       if cls is None:
+           return decorator
+       return decorator(cls)
+   ```
+
+2. **Session as Master Trace**:
+   - All spans must have a session as their root ancestor.
+   - Session creation should be explicit and precede any agent or tool operations.
+
+3. **Context Propagation**:
+   - Span context should be propagated automatically through the call stack.
+   - Context should be accessible globally but thread-safe.
+
+## Example Usage
+
+```python
+from agentops import Session, agent, tool, tracer
+from agentops.sdk import TracingConfig
+
+# Initialize the global tracer with a dedicated configuration
+tracer.initialize(
+    service_name="my-service",
+    exporter_endpoint="https://my-exporter-endpoint.com",
+    max_queue_size=1000,
+    max_wait_time=10000
+)
+
+# Create a session (master trace)
+with Session() as session:
+    # Create an agent
+    @agent
+    class MyAgent:
+        def __init__(self, name):
+            self.name = name
+        
+        def run(self):
+            # Agent operations are automatically traced
+            result = self.use_tool()
+            return result
+        
+        @tool
+        def use_tool(self):
+            # Tool operations are automatically traced
+            return "Tool result"
+    
+    # Use the agent
+    agent = MyAgent("Agent1")
+    result = agent.run()
+```
+
+## Benefits
+
+1. **Simplified API**: Users can easily mark their components with decorators.
+2. **Hierarchical Tracing**: All operations are organized hierarchically with the session as the root.
+3. **Automatic Context Propagation**: Context is propagated automatically through the call stack.
+4. **Extensibility**: Custom span types can be added easily.
+5. **Separation of Concerns**: Tracing configuration is separate from the main application configuration.
+

agentops/sdk/core.py

@@ -2,11 +2,10 @@ from __future__ import annotations
 
 import atexit
 import threading
-from typing import Optional, Any, Dict, Union
+from typing import Optional, Any, Dict, Union, Callable
 
 from opentelemetry import metrics, trace
 from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
-from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 from opentelemetry.sdk.metrics import MeterProvider
 from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
 from opentelemetry.sdk.resources import Resource
@@ -18,6 +17,7 @@ from agentops.exceptions import AgentOpsClientNotInitializedException
 from agentops.logging import logger, setup_print_logger
 from agentops.sdk.processors import InternalSpanProcessor
 from agentops.sdk.types import TracingConfig
+from agentops.sdk.exporters import AuthenticatedOTLPExporter
 from agentops.sdk.attributes import (
     get_global_resource_attributes,
     get_trace_attributes,
@@ -83,7 +83,7 @@ def setup_telemetry(
     max_queue_size: int = 512,
     max_wait_time: int = 5000,
     export_flush_interval: int = 1000,
-    jwt: Optional[str] = None,
+    jwt_provider: Optional[Callable[[], Optional[str]]] = None,
 ) -> tuple[TracerProvider, MeterProvider]:
     """
     Setup the telemetry system.
@@ -96,7 +96,7 @@ def setup_telemetry(
         max_queue_size: Maximum number of spans to queue before forcing a flush
         max_wait_time: Maximum time in milliseconds to wait before flushing
         export_flush_interval: Time interval in milliseconds between automatic exports of telemetry data
-        jwt: JWT token for authentication
+        jwt_provider: Function that returns the current JWT token
 
     Returns:
         Tuple of (TracerProvider, MeterProvider)
@@ -113,8 +113,8 @@ def setup_telemetry(
     # Set as global provider
     trace.set_tracer_provider(provider)
 
-    # Create exporter with authentication
-    exporter = OTLPSpanExporter(endpoint=exporter_endpoint, headers={"Authorization": f"Bearer {jwt}"} if jwt else {})
+    # Create exporter with dynamic JWT support
+    exporter = AuthenticatedOTLPExporter(endpoint=exporter_endpoint, jwt_provider=jwt_provider)
 
     # Regular processor for normal spans and immediate export
     processor = BatchSpanProcessor(
@@ -126,10 +126,13 @@ def setup_telemetry(
     internal_processor = InternalSpanProcessor()  # Catches spans for AgentOps on-terminal printing
     provider.add_span_processor(internal_processor)
 
-    # Setup metrics
-    metric_exporter = OTLPMetricExporter(
-        endpoint=metrics_endpoint, headers={"Authorization": f"Bearer {jwt}"} if jwt else {}
-    )
+    # Setup metrics with JWT provider
+    def get_metrics_headers():
+        token = jwt_provider() if jwt_provider else None
+        return {"Authorization": f"Bearer {token}"} if token else {}
+
+    metric_exporter = OTLPMetricExporter(endpoint=metrics_endpoint, headers=get_metrics_headers())
+
     metric_reader = PeriodicExportingMetricReader(metric_exporter)
     meter_provider = MeterProvider(resource=resource, metric_readers=[metric_reader])
     metrics.set_meter_provider(meter_provider)
@@ -162,16 +165,17 @@ class TracingCore:
         self._span_processors: list = []
         self._active_traces: dict = {}
         self._traces_lock = threading.Lock()
+        self._jwt_provider: Optional[Callable[[], Optional[str]]] = None
 
         # Register shutdown handler
         atexit.register(self.shutdown)
 
-    def initialize(self, jwt: Optional[str] = None, **kwargs: Any) -> None:
+    def initialize(self, jwt_provider: Optional[Callable[[], Optional[str]]] = None, **kwargs: Any) -> None:
         """
         Initialize the tracing core with the given configuration.
 
         Args:
-            jwt: JWT token for authentication
+            jwt_provider: Function that returns the current JWT token
             **kwargs: Configuration parameters for tracing
                 service_name: Name of the service
                 exporter: Custom span exporter
@@ -185,6 +189,9 @@ class TracingCore:
         if self._initialized:
             return
 
+        # Store JWT provider for potential updates
+        self._jwt_provider = jwt_provider
+
         # Set default values for required fields
         kwargs.setdefault("service_name", "agentops")
         kwargs.setdefault("exporter_endpoint", "https://otlp.agentops.ai/v1/traces")
@@ -216,7 +223,7 @@ class TracingCore:
             max_queue_size=config["max_queue_size"],
             max_wait_time=config["max_wait_time"],
             export_flush_interval=config["export_flush_interval"],
-            jwt=jwt,
+            jwt_provider=jwt_provider,
         )
 
         self.provider = provider
@@ -225,6 +232,29 @@ class TracingCore:
         self._initialized = True
         logger.debug("Tracing core initialized")
 
+    def update_config(self, config_updates: Dict[str, Any]) -> None:
+        """
+        Update the tracing configuration.
+
+        Args:
+            config_updates: Dictionary of configuration updates
+        """
+        if not self._initialized:
+            logger.warning("Cannot update config: tracer not initialized")
+            return
+
+        if self._config:
+            # Update the stored config
+            self._config.update(config_updates)
+
+            # Update resource attributes if project_id changed
+            if "project_id" in config_updates:
+                new_project_id = config_updates["project_id"]
+                if new_project_id and new_project_id != "temporary":
+                    logger.debug(f"Updating tracer project_id to: {new_project_id}")
+                    # Note: OpenTelemetry doesn't easily support updating resource attributes
+                    # after initialization, but we can log the change for debugging
+
     @property
     def initialized(self) -> bool:
         """Check if the tracing core is initialized."""
@@ -239,29 +269,39 @@ class TracingCore:
         return self._config
 
     def shutdown(self) -> None:
-        """Shutdown the tracing core."""
-
-        if not self._initialized or not self.provider:
+        """Shutdown the tracing core and clean up resources."""
+        if not self._initialized:
             return
 
-        logger.debug("Attempting to flush span processors during shutdown...")
-        self._flush_span_processors()
-
-        # Shutdown provider
         try:
-            self.provider.shutdown()
-        except Exception as e:
-            logger.warning(f"Error shutting down provider: {e}")
+            # End all active traces
+            with self._traces_lock:
+                active_traces = list(self._active_traces.values())
+                logger.debug(f"Shutting down tracer with {len(active_traces)} active traces")
 
-        # Shutdown meter_provider
-        if hasattr(self, "_meter_provider") and self._meter_provider:
-            try:
+            for trace_context in active_traces:
+                try:
+                    self._end_single_trace(trace_context, "Shutdown")
+                except Exception as e:
+                    logger.error(f"Error ending trace during shutdown: {e}")
+
+            # Force flush all processors
+            self._flush_span_processors()
+
+            # Shutdown providers
+            if self.provider:
+                self.provider.shutdown()
+
+            if self._meter_provider:
                 self._meter_provider.shutdown()
-            except Exception as e:
-                logger.warning(f"Error shutting down meter provider: {e}")
 
-        self._initialized = False
-        logger.debug("Tracing core shut down")
+            logger.debug("Tracing core shutdown complete")
+
+        except Exception as e:
+            logger.error(f"Error during tracing core shutdown: {e}")
+
+        finally:
+            self._initialized = False
 
     def _flush_span_processors(self) -> None:
         """Helper to force flush all span processors."""
@@ -291,12 +331,15 @@ class TracingCore:
         return trace.get_tracer(name)
 
     @classmethod
-    def initialize_from_config(cls, config_obj: Any, **kwargs: Any) -> None:
+    def initialize_from_config(
+        cls, config_obj: Any, jwt_provider: Optional[Callable[[], Optional[str]]] = None, **kwargs: Any
+    ) -> None:
         """
         Initialize the tracing core from a configuration object.
 
         Args:
             config: Configuration object (dict or object with dict method)
+            jwt_provider: Function that returns the current JWT token
             **kwargs: Additional keyword arguments to pass to initialize
         """
         # Use the global tracer instance instead of getting singleton
@@ -330,7 +373,7 @@ class TracingCore:
         tracing_kwargs.update(kwargs)
 
         # Initialize with the extracted configuration
-        instance.initialize(**tracing_kwargs)
+        instance.initialize(jwt_provider=jwt_provider, **tracing_kwargs)
 
         # Span types are registered in the constructor
         # No need to register them here anymore

agentops/sdk/descriptors/classproperty.py

@@ -0,0 +1,28 @@
+class ClassPropertyDescriptor(object):
+    def __init__(self, fget, fset=None):
+        self.fget = fget
+        self.fset = fset
+
+    def __get__(self, obj, klass=None):
+        if klass is None:
+            klass = type(obj)
+        return self.fget.__get__(obj, klass)()
+
+    def __set__(self, obj, value):
+        if not self.fset:
+            raise AttributeError("can't set attribute")
+        type_ = type(obj)
+        return self.fset.__get__(obj, type_)(value)
+
+    def setter(self, func):
+        if not isinstance(func, (classmethod, staticmethod)):
+            func = classmethod(func)
+        self.fset = func
+        return self
+
+
+def classproperty(func):
+    if not isinstance(func, (classmethod, staticmethod)):
+        func = classmethod(func)
+
+    return ClassPropertyDescriptor(func)