lucidicai 2.0.2__py3-none-any.whl → 2.1.1__py3-none-any.whl

lucidicai/sdk/decorators.py

@@ -0,0 +1,187 @@
+"""Decorators for the Lucidic SDK to create typed, nested events."""
+import functools
+import inspect
+import json
+from datetime import datetime
+import uuid
+from typing import Any, Callable, Optional, TypeVar
+from collections.abc import Iterable
+
+from .event import create_event
+from .init import get_session_id
+from ..core.errors import LucidicNotInitializedError
+from .context import current_parent_event_id, event_context, event_context_async
+from ..utils.logger import debug, error as log_error, verbose, truncate_id
+
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+def _serialize(value: Any):
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, dict):
+        return {k: _serialize(v) for k, v in value.items()}
+    if isinstance(value, Iterable) and not isinstance(value, (str, bytes)):
+        return [_serialize(v) for v in value]
+    try:
+        return json.loads(json.dumps(value, default=str))
+    except Exception:
+        return str(value)
+
+
+def event(**decorator_kwargs) -> Callable[[F], F]:
+    """Universal decorator creating FUNCTION_CALL events with nesting and error capture."""
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            session_id = get_session_id()
+            if not session_id:
+                return func(*args, **kwargs)
+
+            # Build arguments snapshot
+            sig = inspect.signature(func)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            args_dict = {name: _serialize(val) for name, val in bound.arguments.items()}
+
+            parent_id = current_parent_event_id.get(None)
+            pre_event_id = str(uuid.uuid4())
+            debug(f"[Decorator] Starting {func.__name__} with event ID {truncate_id(pre_event_id)}, parent: {truncate_id(parent_id)}")
+            start_time = datetime.now().astimezone()
+            result = None
+            error: Optional[BaseException] = None
+
+            try:
+                with event_context(pre_event_id):
+                    # Also inject into OpenTelemetry context for instrumentors
+                    from ..telemetry.context_bridge import inject_lucidic_context
+                    from opentelemetry import context as otel_context
+                    
+                    otel_ctx = inject_lucidic_context()
+                    token = otel_context.attach(otel_ctx)
+                    try:
+                        result = func(*args, **kwargs)
+                    finally:
+                        otel_context.detach(token)
+                return result
+            except Exception as e:
+                error = e
+                log_error(f"[Decorator] {func.__name__} raised exception: {e}")
+                raise
+            finally:
+                try:
+                    # Store error as return value with type information
+                    if error:
+                        return_val = {
+                            "error": str(error),
+                            "error_type": type(error).__name__
+                        }
+                        
+                        # Create a separate error_traceback event for the exception
+                        import traceback
+                        try:
+                            create_event(
+                                type="error_traceback",
+                                error=str(error),
+                                traceback=traceback.format_exc(),
+                                parent_event_id=pre_event_id  # Parent is the function that threw the error
+                            )
+                            debug(f"[Decorator] Created error_traceback event for {func.__name__}")
+                        except Exception as e:
+                            debug(f"[Decorator] Failed to create error_traceback event: {e}")
+                    else:
+                        return_val = _serialize(result)
+                    
+                    create_event(
+                        type="function_call",
+                        event_id=pre_event_id,  # Use the pre-generated ID
+                        function_name=func.__name__,
+                        arguments=args_dict,
+                        return_value=return_val,
+                        error=str(error) if error else None,
+                        duration=(datetime.now().astimezone() - start_time).total_seconds(),
+                        **decorator_kwargs
+                    )
+                    debug(f"[Decorator] Created function_call event for {func.__name__}")
+                except Exception as e:
+                    log_error(f"[Decorator] Failed to create function_call event: {e}")
+
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            session_id = get_session_id()
+            if not session_id:
+                return await func(*args, **kwargs)
+
+            sig = inspect.signature(func)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            args_dict = {name: _serialize(val) for name, val in bound.arguments.items()}
+
+            parent_id = current_parent_event_id.get(None)
+            pre_event_id = str(uuid.uuid4())
+            debug(f"[Decorator] Starting {func.__name__} with event ID {truncate_id(pre_event_id)}, parent: {truncate_id(parent_id)}")
+            start_time = datetime.now().astimezone()
+            result = None
+            error: Optional[BaseException] = None
+
+            try:
+                async with event_context_async(pre_event_id):
+                    # Also inject into OpenTelemetry context for instrumentors
+                    from ..telemetry.context_bridge import inject_lucidic_context
+                    from opentelemetry import context as otel_context
+                    
+                    otel_ctx = inject_lucidic_context()
+                    token = otel_context.attach(otel_ctx)
+                    try:
+                        result = await func(*args, **kwargs)
+                    finally:
+                        otel_context.detach(token)
+                return result
+            except Exception as e:
+                error = e
+                log_error(f"[Decorator] {func.__name__} raised exception: {e}")
+                raise
+            finally:
+                try:
+                    # Store error as return value with type information
+                    if error:
+                        return_val = {
+                            "error": str(error),
+                            "error_type": type(error).__name__
+                        }
+                        
+                        # Create a separate error_traceback event for the exception
+                        import traceback
+                        try:
+                            create_event(
+                                type="error_traceback",
+                                error=str(error),
+                                traceback=traceback.format_exc(),
+                                parent_event_id=pre_event_id  # Parent is the function that threw the error
+                            )
+                            debug(f"[Decorator] Created error_traceback event for {func.__name__}")
+                        except Exception as e:
+                            debug(f"[Decorator] Failed to create error_traceback event: {e}")
+                    else:
+                        return_val = _serialize(result)
+                    
+                    create_event(
+                        type="function_call",
+                        event_id=pre_event_id,  # Use the pre-generated ID
+                        function_name=func.__name__,
+                        arguments=args_dict,
+                        return_value=return_val,
+                        error=str(error) if error else None,
+                        duration=(datetime.now().astimezone() - start_time).total_seconds(),
+                        **decorator_kwargs
+                    )
+                    debug(f"[Decorator] Created function_call event for {func.__name__}")
+                except Exception as e:
+                    log_error(f"[Decorator] Failed to create function_call event: {e}")
+
+        if inspect.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore
+        return sync_wrapper  # type: ignore
+
+    return decorator

lucidicai/sdk/error_boundary.py

@@ -0,0 +1,299 @@
+"""Error boundary pattern for SDK error suppression.
+
+Inspired by the TypeScript SDK's error-boundary.ts, this module provides
+a clean, centralized way to handle SDK errors without affecting user code.
+"""
+import functools
+import logging
+import threading
+import traceback
+import uuid
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional, TypeVar
+
+from ..core.config import get_config
+
+logger = logging.getLogger("Lucidic")
+
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+@dataclass
+class ErrorContext:
+    """Context information about an SDK error."""
+    timestamp: datetime
+    module: str
+    function: str
+    error_type: str
+    error_message: str
+    traceback: str
+    suppressed: bool = True
+
+
+class ErrorBoundary:
+    """Centralized error boundary for the SDK.
+    
+    This class manages all error suppression, logging, and cleanup
+    in a single place, similar to the TypeScript implementation.
+    """
+    
+    def __init__(self):
+        self.error_history: List[ErrorContext] = []
+        self.max_history_size = 100
+        self.cleanup_handlers: List[Callable] = []
+        self._lock = threading.Lock()
+        self._config = None  # Lazy load config
+    
+    def wrap_function(self, func: F, module: str = "unknown") -> F:
+        """Wrap a function with error boundary protection.
+        
+        Args:
+            func: Function to wrap
+            module: Module name for error context
+            
+        Returns:
+            Wrapped function that suppresses errors based on config
+        """
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            if not self.is_silent_mode():
+                return func(*args, **kwargs)
+            
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                return self._handle_error(e, module, func.__name__, args, kwargs)
+        
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            if not self.is_silent_mode():
+                return await func(*args, **kwargs)
+            
+            try:
+                return await func(*args, **kwargs)
+            except Exception as e:
+                return self._handle_error(e, module, func.__name__, args, kwargs)
+        
+        # Return appropriate wrapper based on function type
+        import asyncio
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore
+        return sync_wrapper  # type: ignore
+    
+    def wrap_module(self, module_dict: Dict[str, Any], module_name: str) -> Dict[str, Any]:
+        """Wrap all functions in a module dictionary.
+        
+        Args:
+            module_dict: Dictionary of module exports
+            module_name: Name of the module
+            
+        Returns:
+            Dictionary with all functions wrapped
+        """
+        if not self.is_silent_mode():
+            return module_dict
+        
+        wrapped = {}
+        for name, obj in module_dict.items():
+            if callable(obj) and not name.startswith('_'):
+                wrapped[name] = self.wrap_function(obj, module_name)
+            else:
+                wrapped[name] = obj
+        
+        return wrapped
+    
+    @property
+    def config(self):
+        """Lazy load configuration."""
+        if self._config is None:
+            self._config = get_config()
+        return self._config
+    
+    def is_silent_mode(self) -> bool:
+        """Check if SDK is in silent mode (error suppression enabled)."""
+        return self.config.error_handling.suppress_errors
+    
+    def _handle_error(
+        self,
+        error: Exception,
+        module: str,
+        function: str,
+        args: tuple,
+        kwargs: dict
+    ) -> Any:
+        """Handle an error that occurred in SDK code.
+        
+        Args:
+            error: The exception that occurred
+            module: Module where error occurred
+            function: Function where error occurred
+            args: Function arguments
+            kwargs: Function keyword arguments
+            
+        Returns:
+            Default return value for the function
+        """
+        # Create error context
+        context = ErrorContext(
+            timestamp=datetime.now(),
+            module=module,
+            function=function,
+            error_type=type(error).__name__,
+            error_message=str(error),
+            traceback=traceback.format_exc(),
+            suppressed=True
+        )
+        
+        # Add to history
+        with self._lock:
+            self.error_history.append(context)
+            if len(self.error_history) > self.max_history_size:
+                self.error_history.pop(0)
+        
+        # Log if configured
+        if self.config.error_handling.log_suppressed:
+            logger.debug(
+                f"[ErrorBoundary] Suppressed {context.error_type} in {module}.{function}: "
+                f"{context.error_message}"
+            )
+            if self.config.debug:
+                logger.debug(f"[ErrorBoundary] Traceback:\n{context.traceback}")
+        
+        # Perform cleanup if configured
+        if self.config.error_handling.cleanup_on_error:
+            self._perform_cleanup()
+        
+        # Return appropriate default
+        return self._get_default_return(function)
+    
+    def _get_default_return(self, function_name: str) -> Any:
+        """Get appropriate default return value for a function.
+        
+        Args:
+            function_name: Name of the function
+            
+        Returns:
+            Appropriate default value based on function name
+        """
+        # init function should return a fallback session ID
+        if function_name == 'init':
+            return f'fallback-session-{uuid.uuid4()}'
+        
+        # Functions that return IDs
+        if any(x in function_name.lower() for x in ['id', 'create_experiment']):
+            return str(uuid.uuid4())
+        
+        # Functions that return booleans
+        if any(x in function_name.lower() for x in ['is_', 'has_', 'can_', 'should_']):
+            return False
+        
+        # Functions that return data
+        if function_name.lower().startswith('get_'):
+            if 'dataset' in function_name.lower():
+                return {}
+            elif 'prompt' in function_name.lower():
+                return ""
+            return None
+        
+        # Default
+        return None
+    
+    def _perform_cleanup(self) -> None:
+        """Perform cleanup after an error."""
+        # Run registered cleanup handlers
+        for handler in self.cleanup_handlers:
+            try:
+                handler()
+            except Exception as e:
+                logger.debug(f"[ErrorBoundary] Cleanup handler failed: {e}")
+    
+    def register_cleanup_handler(self, handler: Callable) -> None:
+        """Register a cleanup handler to run on errors.
+        
+        Args:
+            handler: Cleanup function to register
+        """
+        self.cleanup_handlers.append(handler)
+    
+    def get_error_history(self) -> List[ErrorContext]:
+        """Get the error history.
+        
+        Returns:
+            List of error contexts
+        """
+        with self._lock:
+            return list(self.error_history)
+    
+    def clear_error_history(self) -> None:
+        """Clear the error history."""
+        with self._lock:
+            self.error_history.clear()
+    
+    def reset_config(self) -> None:
+        """Reset cached configuration (for testing)."""
+        self._config = None
+
+
+# Global error boundary instance
+_error_boundary: Optional[ErrorBoundary] = None
+
+
+def get_error_boundary() -> ErrorBoundary:
+    """Get the global error boundary instance."""
+    global _error_boundary
+    if _error_boundary is None:
+        _error_boundary = ErrorBoundary()
+    return _error_boundary
+
+
+def wrap_sdk_function(func: F, module: str = "unknown") -> F:
+    """Wrap an SDK function with error boundary protection.
+    
+    Args:
+        func: Function to wrap
+        module: Module name for error context
+        
+    Returns:
+        Wrapped function
+    """
+    return get_error_boundary().wrap_function(func, module)
+
+
+def wrap_sdk_module(module_dict: Dict[str, Any], module_name: str) -> Dict[str, Any]:
+    """Wrap all functions in an SDK module.
+    
+    Args:
+        module_dict: Dictionary of module exports
+        module_name: Name of the module
+        
+    Returns:
+        Dictionary with wrapped functions
+    """
+    return get_error_boundary().wrap_module(module_dict, module_name)
+
+
+def is_silent_mode() -> bool:
+    """Check if SDK is in silent mode."""
+    return get_error_boundary().is_silent_mode()
+
+
+
+
+def get_error_history() -> List[ErrorContext]:
+    """Get the SDK error history."""
+    return get_error_boundary().get_error_history()
+
+
+def clear_error_history() -> None:
+    """Clear the SDK error history."""
+    get_error_boundary().clear_error_history()
+
+
+def register_cleanup_handler(handler: Callable) -> None:
+    """Register a cleanup handler.
+    
+    Args:
+        handler: Cleanup function to run on errors
+    """
+    get_error_boundary().register_cleanup_handler(handler)

lucidicai/sdk/event.py

@@ -0,0 +1,126 @@
+"""SDK event creation and management."""
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional, Union
+
+from .context import current_parent_event_id
+from ..core.config import get_config
+from .event_builder import EventBuilder
+from ..utils.logger import debug, truncate_id
+
+
+def create_event(
+    type: str = "generic",
+    event_id: Optional[str] = None,
+    session_id: Optional[str] = None,  # accept explicit session_id
+    **kwargs
+) -> str:
+    """Create a new event.
+
+    Args:
+        type: Event type (llm_generation, function_call, error_traceback, generic)
+        event_id: Optional client event ID (will generate if not provided)
+        session_id: Optional session ID (will use context if not provided)
+        **kwargs: Event-specific fields
+
+    Returns:
+        Event ID (client-generated or provided UUID)
+    """
+    # Import here to avoid circular dependency
+    from ..sdk.init import get_session_id, get_event_queue
+
+    # Use provided session_id or fall back to context
+    if not session_id:
+        session_id = get_session_id()
+
+    if not session_id:
+        # No active session, return dummy ID
+        debug("[Event] No active session, returning dummy event ID")
+        return str(uuid.uuid4())
+    
+    # Get parent event ID from context
+    parent_event_id = None
+    try:
+        parent_event_id = current_parent_event_id.get()
+    except Exception:
+        pass
+    
+    # Use provided event ID or generate new one
+    client_event_id = event_id or str(uuid.uuid4())
+    
+    # Build parameters for EventBuilder
+    params = {
+        'type': type,
+        'event_id': client_event_id,
+        'parent_event_id': parent_event_id,
+        'session_id': session_id,
+        'occurred_at': kwargs.get('occurred_at') or datetime.now(timezone.utc).isoformat(),
+        **kwargs  # Include all other kwargs
+    }
+    
+    # Use EventBuilder to create normalized event request
+    event_request = EventBuilder.build(params)
+    
+    debug(f"[Event] Creating {type} event {truncate_id(client_event_id)} (parent: {truncate_id(parent_event_id)}, session: {truncate_id(session_id)})")
+    
+    # Queue event for async sending
+    event_queue = get_event_queue()
+    if event_queue:
+        event_queue.queue_event(event_request)
+    
+    return client_event_id
+
+
+
+def create_error_event(
+    error: Union[str, Exception],
+    parent_event_id: Optional[str] = None,
+    **kwargs
+) -> str:
+    """Create an error traceback event.
+    
+    This is a convenience function for creating error events with proper
+    traceback information.
+    
+    Args:
+        error: The error message or exception object
+        parent_event_id: Optional parent event ID for nesting
+        **kwargs: Additional event parameters
+        
+    Returns:
+        Event ID of the created error event
+    """
+    import traceback
+    
+    if isinstance(error, Exception):
+        error_str = str(error)
+        traceback_str = traceback.format_exc()
+    else:
+        error_str = str(error)
+        traceback_str = kwargs.pop('traceback', '')
+    
+    return create_event(
+        type="error_traceback",
+        error=error_str,
+        traceback=traceback_str,
+        parent_event_id=parent_event_id,
+        **kwargs
+    )
+
+
+def flush(timeout_seconds: float = 2.0) -> bool:
+    """Flush pending events.
+    
+    Args:
+        timeout_seconds: Maximum time to wait for flush
+        
+    Returns:
+        True if flush completed, False if timeout
+    """
+    from ..sdk.init import get_event_queue
+    event_queue = get_event_queue()
+    if event_queue:
+        debug(f"[Event] Forcing flush with {timeout_seconds}s timeout")
+        event_queue.force_flush(timeout_seconds)
+        return True
+    return False