feat: Codebase sanitization to improve maintainability & readability

agentops/__init__.py

@@ -20,6 +20,7 @@
 from opentelemetry.trace.status import StatusCode
 
 from agentops.logging.config import logger
+from agentops.helpers.deprecation import deprecated, warn_deprecated_param
 import threading
 
 # Thread-safe client management
@@ -40,6 +41,7 @@
     return _client
 
 
+@deprecated("Automatically tracked in v4.")
 def record(event):
     """
     Legacy function to record an event. This is kept for backward compatibility.
@@ -107,6 +109,10 @@
     """
     global _client
 
+    # Check for deprecated parameters and emit warnings
+    if tags is not None:
+        warn_deprecated_param("tags", "default_tags")
+
     # Merge tags and default_tags if both are provided
     merged_tags = None
     if tags and default_tags:
@@ -241,7 +247,7 @@
 
     Args:
         trace_context: The TraceContext object returned by start_trace. If None, ends all active traces.
-        end_state: The final state of the trace (e.g., "Success", "Failure", "Error").
+        end_state: The final state of the trace (e.g., "Success", "Indeterminate", "Error").
     """
     if not tracer.initialized:
         logger.warning("AgentOps SDK not initialized. Cannot end trace.")

agentops/client/__init__.py

@@ -1,5 +1,5 @@
-from .client import Client
-from .api import ApiClient
+from agentops.client.client import Client
+from agentops.client.api import ApiClient
 
 
 __all__ = ["Client", "ApiClient"]

agentops/helpers/__init__.py

@@ -1,12 +1,12 @@
-from .time import get_ISO_time, iso_to_unix_nano, from_unix_nano_to_iso
-from .serialization import (
+from agentops.helpers.time import get_ISO_time
+from agentops.helpers.serialization import (
     AgentOpsJSONEncoder,
     serialize_uuid,
     safe_serialize,
     is_jsonable,
     filter_unjsonable,
 )
-from .system import (
+from agentops.helpers.system import (
     get_host_env,
     get_sdk_details,
     get_os_details,
@@ -17,14 +17,11 @@
     get_current_directory,
     get_virtual_env,
 )
-from .version import get_agentops_version, check_agentops_update
-from .debug import debug_print_function_params
-from .env import get_env_bool, get_env_int, get_env_list
+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",
-    "iso_to_unix_nano",
-    "from_unix_nano_to_iso",
     "AgentOpsJSONEncoder",
     "serialize_uuid",
     "safe_serialize",
@@ -41,7 +38,6 @@
     "get_virtual_env",
     "get_agentops_version",
     "check_agentops_update",
-    "debug_print_function_params",
     "get_env_bool",
     "get_env_int",
     "get_env_list",

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/system.py

@@ -61,20 +61,6 @@ def get_sdk_details():
         return {}
 
 
-def get_python_details():
-    try:
-        return {"Python Version": platform.python_version()}
-    except:
-        return {}
-
-
-def get_agentops_details():
-    try:
-        return {"AgentOps SDK Version": get_agentops_version()}
-    except:
-        return {}
-
-
 def get_sys_packages():
     sys_packages = {}
     for module in sys.modules:

agentops/helpers/time.py

@@ -9,12 +9,3 @@ def get_ISO_time():
         str: The current UTC time as a string in ISO 8601 format.
     """
     return datetime.now(timezone.utc).isoformat()
-
-
-def iso_to_unix_nano(iso_time: str) -> int:
-    dt = datetime.fromisoformat(iso_time)
-    return int(dt.timestamp() * 1_000_000_000)
-
-
-def from_unix_nano_to_iso(unix_nano: int) -> str:
-    return datetime.fromtimestamp(unix_nano / 1_000_000_000, timezone.utc).isoformat()

agentops/instrumentation/ag2/instrumentor.py

@@ -424,7 +424,7 @@
 
                     if tool_type == "function" and isinstance(result, tuple) and len(result) > 0:
                         success = result[0] if isinstance(result[0], bool) else False
-                        span.set_attribute(ToolAttributes.TOOL_STATUS, "success" if success else "failure")
+                        span.set_attribute(ToolAttributes.TOOL_STATUS, "success" if success else "error")
 
                         if len(result) > 1 and isinstance(result[1], dict):
                             try:
@@ -435,7 +435,7 @@
                     if tool_type == "code" and isinstance(result, tuple) and len(result) >= 3:
                         exit_code = result[0]
                         span.set_attribute("exit_code", exit_code)
-                        span.set_attribute(ToolAttributes.TOOL_STATUS, "success" if exit_code == 0 else "failure")
+                        span.set_attribute(ToolAttributes.TOOL_STATUS, "success" if exit_code == 0 else "error")
 
                         if len(result) > 1 and result[1]:
                             stdout = result[1]

agentops/instrumentation/common/__init__.py

@@ -1,4 +1,4 @@
-from .attributes import AttributeMap, _extract_attributes_from_mapping
-from .wrappers import _with_tracer_wrapper
+from agentops.instrumentation.common.attributes import AttributeMap, _extract_attributes_from_mapping
+from agentops.instrumentation.common.wrappers import _with_tracer_wrapper
 
 __all__ = ["AttributeMap", "_extract_attributes_from_mapping", "_with_tracer_wrapper"]

agentops/instrumentation/common/objects.py

@@ -1,5 +1,5 @@
 from agentops.client.api.types import UploadedObjectResponse
-from . import AttributeMap, _extract_attributes_from_mapping
+from agentops.instrumentation.common import AttributeMap, _extract_attributes_from_mapping
 
 
 UPLOADED_OBJECT_ATTRIBUTES: AttributeMap = {

agentops/instrumentation/crewai/instrumentation.py

@@ -14,7 +14,7 @@
 from agentops.instrumentation.crewai.version import __version__
 from agentops.semconv import SpanAttributes, AgentOpsSpanKindValues, Meters, ToolAttributes, MessageAttributes
 from agentops.semconv.core import CoreAttributes
-from .crewai_span_attributes import CrewAISpanAttributes, set_span_attribute
+from agentops.instrumentation.crewai.crewai_span_attributes import CrewAISpanAttributes, set_span_attribute
 from agentops import get_client
 
 # Initialize logger

agentops/instrumentation/openai_agents/__init__.py

@@ -31,7 +31,7 @@ def get_version() -> str:
 LIBRARY_VERSION: str = get_version()
 
 # Import after defining constants to avoid circular imports
-from .instrumentor import OpenAIAgentsInstrumentor  # noqa: E402
+from agentops.instrumentation.openai_agents.instrumentor import OpenAIAgentsInstrumentor  # noqa: E402
 
 __all__ = [
     "LIBRARY_NAME",

agentops/legacy/__init__.py

@@ -13,6 +13,7 @@
 
 from agentops.logging import logger
 from agentops.sdk.core import TraceContext, tracer
+from agentops.helpers.deprecation import deprecated
 
 _current_session: Optional["Session"] = None
 _current_trace_context: Optional[TraceContext] = None
@@ -60,6 +61,7 @@ def end_session(self, **kwargs: Any):
         end_session(session_or_status=self, **kwargs)
 
 
+@deprecated("Use agentops.start_trace() instead.")
 def start_session(
     tags: Union[Dict[str, Any], List[str], None] = None,
 ) -> Session:
@@ -121,6 +123,7 @@ def _set_span_attributes(span: Any, attributes: Dict[str, Any]) -> None:
             span.set_attribute(f"agentops.legacy.{key}", str(value))
 
 
+@deprecated("Use agentops.end_trace() instead.")
 def end_session(session_or_status: Any = None, **kwargs: Any) -> None:
     """
     @deprecated Use agentops.end_trace() instead.
@@ -186,6 +189,7 @@ def end_session(session_or_status: Any = None, **kwargs: Any) -> None:
         pass
 
 
+@deprecated("Use agentops.end_trace() instead.")
 def end_all_sessions() -> None:
     """@deprecated Ends all active sessions/traces."""
     if not tracer.initialized:
@@ -201,13 +205,15 @@ def end_all_sessions() -> None:
     _current_trace_context = None
 
 
+@deprecated("Automatically tracked in v4.")
 def ToolEvent(*args: Any, **kwargs: Any) -> None:
-    """@deprecated Use tracing instead."""
+    """@deprecated Automatically tracked in v4."""
     return None
 
 
+@deprecated("Automatically tracked in v4.")
 def ErrorEvent(*args: Any, **kwargs: Any) -> Any:
-    """@deprecated Use tracing instead. Returns minimal object for test compatibility."""
+    """@deprecated Automatically tracked in v4. Returns minimal object for test compatibility."""
     from agentops.helpers.time import get_ISO_time
 
     class LegacyErrorEvent:
@@ -218,8 +224,9 @@ def __init__(self):
     return LegacyErrorEvent()
 
 
+@deprecated("Automatically tracked in v4.")
 def ActionEvent(*args: Any, **kwargs: Any) -> Any:
-    """@deprecated Use tracing instead. Returns minimal object for test compatibility."""
+    """@deprecated Automatically tracked in v4. Returns minimal object for test compatibility."""
     from agentops.helpers.time import get_ISO_time
 
     class LegacyActionEvent:
@@ -230,11 +237,13 @@ def __init__(self):
     return LegacyActionEvent()
 
 
+@deprecated("Automatically tracked in v4.")
 def LLMEvent(*args: Any, **kwargs: Any) -> None:
-    """@deprecated Use tracing instead."""
+    """@deprecated Automatically tracked in v4."""
     return None
 
 
+@deprecated("Use @agent decorator instead.")
 def track_agent(*args: Any, **kwargs: Any) -> Any:
     """@deprecated No-op decorator."""
 
@@ -244,6 +253,7 @@ def noop(f: Any) -> Any:
     return noop
 
 
+@deprecated("Use @tool decorator instead.")
 def track_tool(*args: Any, **kwargs: Any) -> Any:
     """@deprecated No-op decorator."""
 
@@ -262,6 +272,6 @@ def noop(f: Any) -> Any:
     "track_agent",
     "track_tool",
     "end_all_sessions",
-    "Session",  # Exposing the legacy Session class itself
+    "Session",
     "LLMEvent",
 ]

agentops/logging/__init__.py

@@ -1,4 +1,4 @@
-from .config import configure_logging, logger
-from .instrument_logging import setup_print_logger, upload_logfile
+from agentops.logging.config import configure_logging, logger
+from agentops.logging.instrument_logging import setup_print_logger, upload_logfile
 
 __all__ = ["logger", "configure_logging", "setup_print_logger", "upload_logfile"]

agentops/logging/config.py

@@ -1,7 +1,7 @@
 import logging
 import os
 
-from .formatters import AgentOpsLogFileFormatter, AgentOpsLogFormatter
+from agentops.logging.formatters import AgentOpsLogFileFormatter, AgentOpsLogFormatter
 
 # Create the logger at module level
 logger = logging.getLogger("agentops")