mseep-agentops 0.4.18__py3-none-any.whl

agentops/helpers/__init__.py

@@ -0,0 +1,44 @@
+from agentops.helpers.time import get_ISO_time
+from agentops.helpers.serialization import (
+    AgentOpsJSONEncoder,
+    serialize_uuid,
+    safe_serialize,
+    is_jsonable,
+    filter_unjsonable,
+)
+from agentops.helpers.system import (
+    get_host_env,
+    get_sdk_details,
+    get_os_details,
+    get_cpu_details,
+    get_ram_details,
+    get_disk_details,
+    get_installed_packages,
+    get_current_directory,
+    get_virtual_env,
+)
+from agentops.helpers.version import get_agentops_version, check_agentops_update
+from agentops.helpers.env import get_env_bool, get_env_int, get_env_list
+
+__all__ = [
+    "get_ISO_time",
+    "AgentOpsJSONEncoder",
+    "serialize_uuid",
+    "safe_serialize",
+    "is_jsonable",
+    "filter_unjsonable",
+    "get_host_env",
+    "get_sdk_details",
+    "get_os_details",
+    "get_cpu_details",
+    "get_ram_details",
+    "get_disk_details",
+    "get_installed_packages",
+    "get_current_directory",
+    "get_virtual_env",
+    "get_agentops_version",
+    "check_agentops_update",
+    "get_env_bool",
+    "get_env_int",
+    "get_env_list",
+]

agentops/helpers/dashboard.py

@@ -0,0 +1,54 @@
+"""
+Helpers for interacting with the AgentOps dashboard.
+"""
+
+from typing import Union, Optional
+from termcolor import colored
+from opentelemetry.sdk.trace import Span, ReadableSpan
+from agentops.logging import logger
+
+
+def get_trace_url(span: Union[Span, ReadableSpan]) -> str:
+    """
+    Generate a trace URL for a direct link to the session on the AgentOps dashboard.
+
+    Args:
+        span: The span to generate the URL for.
+
+    Returns:
+        The session URL.
+    """
+    trace_id: Union[int, str] = span.context.trace_id
+
+    # Convert trace_id to hex string if it's not already
+    # We don't add dashes to this to format it as a UUID since the dashboard doesn't either
+    if isinstance(trace_id, int):
+        trace_id = format(trace_id, "032x")
+
+    # Get the app_url from the config - import here to avoid circular imports
+    from agentops import get_client
+
+    app_url = get_client().config.app_url
+
+    return f"{app_url}/sessions?trace_id={trace_id}"
+
+
+def log_trace_url(span: Union[Span, ReadableSpan], title: Optional[str] = None) -> None:
+    """
+    Log the trace URL for the AgentOps dashboard.
+
+    Args:
+        span: The span to log the URL for.
+        title: Optional title for the trace.
+    """
+    from agentops import get_client
+
+    try:
+        client = get_client()
+        if not client.config.log_session_replay_url:
+            return
+    except Exception:
+        return
+
+    session_url = get_trace_url(span)
+    logger.info(colored(f"\x1b[34mSession Replay for {title} trace: {session_url}\x1b[0m", "blue"))

agentops/helpers/deprecation.py

@@ -0,0 +1,50 @@
+"""
+Deprecation utilities for AgentOps SDK.
+"""
+
+import functools
+from typing import Set, Callable, Any
+from agentops.logging import logger
+
+# Track which deprecation warnings have been shown to avoid spam
+_shown_warnings: Set[str] = set()
+
+
+def deprecated(message: str):
+    """
+    Decorator to mark functions as deprecated.
+
+    Args:
+        message: Deprecation message to show
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            warning_key = f"{func.__module__}.{func.__name__}"
+            if warning_key not in _shown_warnings:
+                logger.warning(f"{func.__name__}() is deprecated and will be removed in v4 in the future. {message}")
+                _shown_warnings.add(warning_key)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def warn_deprecated_param(param_name: str, replacement: str = None):
+    """
+    Warn about deprecated parameter usage.
+
+    Args:
+        param_name: Name of the deprecated parameter
+        replacement: Suggested replacement parameter
+    """
+    warning_key = f"param.{param_name}"
+    if warning_key not in _shown_warnings:
+        if replacement:
+            message = f"Parameter '{param_name}' is deprecated and will be removed in v4 in the future. Use '{replacement}' instead."
+        else:
+            message = f"Parameter '{param_name}' is deprecated and will be removed in v4 in the future."
+        logger.warning(message)
+        _shown_warnings.add(warning_key)

agentops/helpers/env.py

@@ -0,0 +1,52 @@
+"""Environment variable helper functions"""
+
+import os
+from typing import List, Optional, Set
+
+
+def get_env_bool(key: str, default: bool) -> bool:
+    """Get boolean from environment variable
+
+    Args:
+        key: Environment variable name
+        default: Default value if not set
+
+    Returns:
+        bool: Parsed boolean value
+    """
+    val = os.getenv(key)
+    if val is None:
+        return default
+    return val.lower() in ("true", "1", "t", "yes")
+
+
+def get_env_int(key: str, default: int) -> int:
+    """Get integer from environment variable
+
+    Args:
+        key: Environment variable name
+        default: Default value if not set
+
+    Returns:
+        int: Parsed integer value
+    """
+    try:
+        return int(os.getenv(key, default))
+    except (TypeError, ValueError):
+        return default
+
+
+def get_env_list(key: str, default: Optional[List[str]] = None) -> Set[str]:
+    """Get comma-separated list from environment variable
+
+    Args:
+        key: Environment variable name
+        default: Default list if not set
+
+    Returns:
+        Set[str]: Set of parsed values
+    """
+    val = os.getenv(key)
+    if val is None:
+        return set(default or [])
+    return set(val.split(","))

agentops/helpers/serialization.py

@@ -0,0 +1,137 @@
+"""Serialization helpers for AgentOps"""
+
+import json
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+from agentops.logging import logger
+
+
+def is_jsonable(x):
+    try:
+        json.dumps(x)
+        return True
+    except (TypeError, OverflowError):
+        return False
+
+
+def filter_unjsonable(d: dict) -> dict:
+    def filter_dict(obj):
+        if isinstance(obj, dict):
+            return {
+                k: (
+                    filter_dict(v)
+                    if isinstance(v, (dict, list)) or is_jsonable(v)
+                    else str(v)
+                    if isinstance(v, UUID)
+                    else ""
+                )
+                for k, v in obj.items()
+            }
+        elif isinstance(obj, list):
+            return [
+                (
+                    filter_dict(x)
+                    if isinstance(x, (dict, list)) or is_jsonable(x)
+                    else str(x)
+                    if isinstance(x, UUID)
+                    else ""
+                )
+                for x in obj
+            ]
+        else:
+            return obj if is_jsonable(obj) or isinstance(obj, UUID) else ""
+
+    return filter_dict(d)
+
+
+class AgentOpsJSONEncoder(json.JSONEncoder):
+    """Custom JSON encoder for AgentOps types"""
+
+    def default(self, obj: Any) -> Any:
+        if isinstance(obj, UUID):
+            return str(obj)
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        if isinstance(obj, Decimal):
+            return str(obj)
+        if isinstance(obj, set):
+            return list(obj)
+        if hasattr(obj, "to_json"):
+            return obj.to_json()
+        if isinstance(obj, Enum):
+            return obj.value
+        return str(obj)
+
+
+def serialize_uuid(obj: UUID) -> str:
+    """Serialize UUID to string"""
+    return str(obj)
+
+
+def model_to_dict(obj: Any) -> dict:
+    """Convert a model object to a dictionary safely.
+
+    Handles various model types including:
+    - Pydantic models (model_dump/dict methods)
+    - Dictionary-like objects
+    - API response objects with parse method
+    - Objects with __dict__ attribute
+
+    Args:
+        obj: The model object to convert to dictionary
+
+    Returns:
+        Dictionary representation of the object, or empty dict if conversion fails
+    """
+    if obj is None:
+        return {}
+    if isinstance(obj, dict):
+        return obj
+    if hasattr(obj, "model_dump"):  # Pydantic v2
+        return obj.model_dump()
+    elif hasattr(obj, "dict"):  # Pydantic v1
+        return obj.dict()
+    # TODO this is causing recursion on nested objects.
+    # elif hasattr(obj, "parse"):  # Raw API response
+    #     return model_to_dict(obj.parse())
+    else:
+        # Try to use __dict__ as fallback
+        try:
+            return obj.__dict__
+        except:
+            return {}
+
+
+def safe_serialize(obj: Any) -> Any:
+    """Safely serialize an object to JSON-compatible format
+
+    This function handles complex objects by:
+    1. Returning strings untouched (even if they contain JSON)
+    2. Converting models to dictionaries
+    3. Using custom JSON encoder to handle special types
+    4. Falling back to string representation only when necessary
+
+    Args:
+        obj: The object to serialize
+
+    Returns:
+        If obj is a string, returns the original string untouched.
+        Otherwise, returns a JSON string representation of the object.
+    """
+    # Return strings untouched
+    if isinstance(obj, str):
+        return obj
+
+    # Convert any model objects to dictionaries
+    if hasattr(obj, "model_dump") or hasattr(obj, "dict") or hasattr(obj, "parse"):
+        obj = model_to_dict(obj)
+
+    try:
+        return json.dumps(obj, cls=AgentOpsJSONEncoder)
+    except (TypeError, ValueError) as e:
+        logger.warning(f"Failed to serialize object: {e}")
+        return str(obj)

agentops/helpers/system.py

@@ -0,0 +1,178 @@
+import importlib.metadata
+import os
+import platform
+import socket
+import sys
+
+import psutil  # type: ignore
+
+from agentops.logging import logger
+from agentops.helpers.version import get_agentops_version
+
+
+def get_imported_libraries():
+    """
+    Get the top-level imported libraries in the current script.
+
+    Returns:
+        list: List of imported libraries
+    """
+    user_libs = []
+
+    builtin_modules = {
+        "builtins",
+        "sys",
+        "os",
+        "_thread",
+        "abc",
+        "io",
+        "re",
+        "types",
+        "collections",
+        "enum",
+        "math",
+        "datetime",
+        "time",
+        "warnings",
+    }
+
+    try:
+        main_module = sys.modules.get("__main__")
+        if main_module and hasattr(main_module, "__dict__"):
+            for name, obj in main_module.__dict__.items():
+                if isinstance(obj, type(sys)) and hasattr(obj, "__name__"):
+                    mod_name = obj.__name__.split(".")[0]
+                    if mod_name and not mod_name.startswith("_") and mod_name not in builtin_modules:
+                        user_libs.append(mod_name)
+    except Exception as e:
+        logger.debug(f"Error getting imports: {e}")
+
+    return user_libs
+
+
+def get_sdk_details():
+    try:
+        return {
+            "AgentOps SDK Version": get_agentops_version(),
+            "Python Version": platform.python_version(),
+            "System Packages": get_sys_packages(),
+        }
+    except:
+        return {}
+
+
+def get_sys_packages():
+    sys_packages = {}
+    for module in sys.modules:
+        try:
+            version = importlib.metadata.version(module)
+            sys_packages[module] = version
+        except importlib.metadata.PackageNotFoundError:
+            # Skip built-in modules and those without package metadata
+            continue
+
+    return sys_packages
+
+
+def get_installed_packages():
+    try:
+        return {
+            # TODO: add to opt out
+            "Installed Packages": {
+                dist.metadata.get("Name"): dist.metadata.get("Version") for dist in importlib.metadata.distributions()
+            }
+        }
+    except:
+        return {}
+
+
+def get_current_directory():
+    try:
+        return {"Project Working Directory": os.getcwd()}
+    except:
+        return {}
+
+
+def get_virtual_env():
+    try:
+        return {"Virtual Environment": os.environ.get("VIRTUAL_ENV", None)}
+    except:
+        return {}
+
+
+def get_os_details():
+    try:
+        return {
+            "Hostname": socket.gethostname(),
+            "OS": platform.system(),
+            "OS Version": platform.version(),
+            "OS Release": platform.release(),
+        }
+    except:
+        return {}
+
+
+def get_cpu_details():
+    try:
+        return {
+            "Physical cores": psutil.cpu_count(logical=False),
+            "Total cores": psutil.cpu_count(logical=True),
+            # "Max Frequency": f"{psutil.cpu_freq().max:.2f}Mhz", # Fails right now
+            "CPU Usage": f"{psutil.cpu_percent()}%",
+        }
+    except:
+        return {}
+
+
+def get_ram_details():
+    try:
+        ram_info = psutil.virtual_memory()
+        return {
+            "Total": f"{ram_info.total / (1024**3):.2f} GB",
+            "Available": f"{ram_info.available / (1024**3):.2f} GB",
+            "Used": f"{ram_info.used / (1024**3):.2f} GB",
+            "Percentage": f"{ram_info.percent}%",
+        }
+    except:
+        return {}
+
+
+def get_disk_details():
+    partitions = psutil.disk_partitions()
+    disk_info = {}
+    for partition in partitions:
+        try:
+            usage = psutil.disk_usage(partition.mountpoint)
+            disk_info[partition.device] = {
+                "Mountpoint": partition.mountpoint,
+                "Total": f"{usage.total / (1024**3):.2f} GB",
+                "Used": f"{usage.used / (1024**3):.2f} GB",
+                "Free": f"{usage.free / (1024**3):.2f} GB",
+                "Percentage": f"{usage.percent}%",
+            }
+        except OSError as inaccessible:
+            # Skip inaccessible partitions, such as removable drives with no media
+            logger.debug("Mountpoint %s inaccessible: %s", partition.mountpoint, inaccessible)
+
+    return disk_info
+
+
+def get_host_env(opt_out: bool = False):
+    if opt_out:
+        return {
+            "SDK": get_sdk_details(),
+            "OS": get_os_details(),
+            "Project Working Directory": get_current_directory(),
+            "Virtual Environment": get_virtual_env(),
+        }
+    else:
+        return {
+            "SDK": get_sdk_details(),
+            "OS": get_os_details(),
+            "CPU": get_cpu_details(),
+            "RAM": get_ram_details(),
+            "Disk": get_disk_details(),
+            "Installed Packages": get_installed_packages(),
+            "Project Working Directory": get_current_directory(),
+            "Virtual Environment": get_virtual_env(),
+        }

agentops/helpers/time.py

@@ -0,0 +1,11 @@
+from datetime import datetime, timezone
+
+
+def get_ISO_time():
+    """
+    Get the current UTC time in ISO 8601 format with milliseconds precision in UTC timezone.
+
+    Returns:
+        str: The current UTC time as a string in ISO 8601 format.
+    """
+    return datetime.now(timezone.utc).isoformat()

agentops/helpers/version.py

@@ -0,0 +1,36 @@
+from importlib.metadata import PackageNotFoundError, version
+
+import requests
+
+from agentops.logging import logger
+
+
+def get_agentops_version():
+    try:
+        pkg_version = version("agentops")
+        return pkg_version
+    except Exception as e:
+        logger.warning("Error reading package version: %s", e)
+        return None
+
+
+def check_agentops_update():
+    try:
+        response = requests.get("https://pypi.org/pypi/agentops/json")
+
+        if response.status_code == 200:
+            json_data = response.json()
+            latest_version = json_data["info"]["version"]
+
+            try:
+                current_version = version("agentops")
+            except PackageNotFoundError:
+                return None
+
+            if not latest_version == current_version:
+                logger.warning(
+                    " WARNING: agentops is out of date. Please update with the command: 'pip install --upgrade agentops'"
+                )
+    except Exception as e:
+        logger.debug(f"Failed to check for updates: {e}")
+        return None