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

lucidicai/sdk/features/feature_flag.py

@@ -0,0 +1,383 @@
+import os
+import logging
+import time
+from typing import Union, List, Dict, Any, Optional, overload, Tuple, Literal
+from dotenv import load_dotenv
+
+from ..init import get_http
+from ...core.errors import APIKeyVerificationError, FeatureFlagError
+
+logger = logging.getLogger("Lucidic")
+
+# Cache implementation
+class FeatureFlagCache:
+    def __init__(self):
+        self._cache: Dict[str, tuple[Any, float]] = {}
+        self._default_ttl = 300  # 5 minutes
+    
+    def get(self, key: str) -> Optional[Any]:
+        if key in self._cache:
+            value, expiry = self._cache[key]
+            if time.time() < expiry:
+                return value
+            else:
+                del self._cache[key]
+        return None
+    
+    def set(self, key: str, value: Any, ttl: int = None):
+        if ttl is None:
+            ttl = self._default_ttl
+        if ttl > 0:
+            self._cache[key] = (value, time.time() + ttl)
+    
+    def clear(self):
+        self._cache.clear()
+
+# Global cache instance
+_flag_cache = FeatureFlagCache()
+
+# Sentinel value to distinguish None from missing
+MISSING = object()
+
+# Function overloads for type safety
+@overload
+def get_feature_flag(
+    flag_name: str,
+    default: Any = ...,
+    *,
+    return_missing: Literal[False] = False,
+    cache_ttl: Optional[int] = 300,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Any:
+    """Get a single feature flag."""
+    ...
+
+@overload
+def get_feature_flag(
+    flag_name: str,
+    default: Any = ...,
+    *,
+    return_missing: Literal[True],
+    cache_ttl: Optional[int] = 300,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Tuple[Any, List[str]]:
+    """Get a single feature flag with missing info."""
+    ...
+
+@overload
+def get_feature_flag(
+    flag_name: List[str],
+    defaults: Optional[Dict[str, Any]] = None,
+    *,
+    return_missing: Literal[False] = False,
+    cache_ttl: Optional[int] = 300,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Get multiple feature flags."""
+    ...
+
+@overload
+def get_feature_flag(
+    flag_name: List[str],
+    defaults: Optional[Dict[str, Any]] = None,
+    *,
+    return_missing: Literal[True],
+    cache_ttl: Optional[int] = 300,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Tuple[Dict[str, Any], List[str]]:
+    """Get multiple feature flags with missing info."""
+    ...
+
+def get_feature_flag(
+    flag_name: Union[str, List[str]],
+    default_or_defaults: Any = MISSING,
+    *,
+    return_missing: bool = False,
+    cache_ttl: Optional[int] = 300,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Union[Any, Tuple[Any, List[str]], Dict[str, Any], Tuple[Dict[str, Any], List[str]]]:
+    """
+    Get feature flag(s) from backend. Raises FeatureFlagError on failure unless default provided.
+    
+    Args:
+        flag_name: Single flag name (str) or list of flag names
+        default_or_defaults: 
+            - If flag_name is str: default value for that flag (optional)
+            - If flag_name is List[str]: dict of defaults {flag_name: default_value}
+        cache_ttl: Cache time-to-live in seconds (0 to disable, -1 for forever)
+        api_key: Optional API key
+        agent_id: Optional agent ID
+    
+    Returns:
+        - If flag_name is str: The flag value (or tuple with missing list if return_missing=True)
+        - If flag_name is List[str]: Dict mapping flag_name -> value (or tuple with missing list if return_missing=True)
+    
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+        APIKeyVerificationError: If credentials missing
+    
+    Examples:
+        # Single flag with default
+        retries = lai.get_feature_flag("max_retries", default=3)
+        
+        # Single flag without default (can raise)
+        retries = lai.get_feature_flag("max_retries")
+        
+        # Multiple flags
+        flags = lai.get_feature_flag(
+            ["max_retries", "timeout"],
+            defaults={"max_retries": 3}
+        )
+    """
+
+    load_dotenv()
+    
+    # Determine if single or batch
+    is_single = isinstance(flag_name, str)
+    flag_names = [flag_name] if is_single else flag_name
+    
+    # Parse defaults
+    if is_single:
+        has_default = default_or_defaults is not MISSING
+        defaults = {flag_name: default_or_defaults} if has_default else {}
+    else:
+        defaults = default_or_defaults if default_or_defaults not in (None, MISSING) else {}
+    
+    # Track missing flags
+    missing_flags = []
+    
+    # Check cache first
+    uncached_flags = []
+    cached_results = {}
+    
+    if cache_ttl != 0:
+        for name in flag_names:
+            cache_key = f"{agent_id}:{name}"
+            cached_value = _flag_cache.get(cache_key)
+            if cached_value is not None:
+                cached_results[name] = cached_value
+            else:
+                uncached_flags.append(name)
+    else:
+        uncached_flags = flag_names
+    
+    # Fetch uncached flags if needed
+    if uncached_flags:
+        # Get credentials
+        if api_key is None:
+            api_key = os.getenv("LUCIDIC_API_KEY", None)
+            if api_key is None:
+                raise APIKeyVerificationError(
+                    "Make sure to either pass your API key or set the LUCIDIC_API_KEY environment variable."
+                )
+        
+        if agent_id is None:
+            agent_id = os.getenv("LUCIDIC_AGENT_ID", None)
+            if agent_id is None:
+                raise APIKeyVerificationError(
+                    "Lucidic agent ID not specified. Make sure to either pass your agent ID or set the LUCIDIC_AGENT_ID environment variable."
+                )
+        
+        # Get HTTP client
+        http = get_http()
+        if not http:
+            from ..init import init
+            init(api_key=api_key, agent_id=agent_id)
+            http = get_http()
+
+        # check for active session
+        from ..init import get_session_id
+        session_id = get_session_id()
+
+        try:
+            if len(uncached_flags) == 1:
+                # Single flag evaluation
+                if session_id:
+                    # Use session-based evaluation for consistency
+                    response = http.post('evaluatefeatureflag', {
+                        'session_id': session_id,
+                        'flag_name': uncached_flags[0],
+                        'context': {},
+                        'default': defaults.get(uncached_flags[0])
+                    })
+                else:
+                    # Use stateless evaluation as fallback
+                    response = http.post('evaluatefeatureflagstateless', {
+                        'agent_id': agent_id,
+                        'flag_name': uncached_flags[0],
+                        'context': {},
+                        'default': defaults.get(uncached_flags[0])
+                    })
+
+                # Extract value from response
+                if 'value' in response:
+                    value = response['value']
+                    cached_results[uncached_flags[0]] = value
+
+                    # Cache the result
+                    if cache_ttl != 0:
+                        cache_key = f"{agent_id}:{uncached_flags[0]}"
+                        _flag_cache.set(cache_key, value, ttl=cache_ttl if cache_ttl > 0 else None)
+                elif 'error' in response:
+                    # Flag not found or error
+                    logger.warning(f"Feature flag error: {response['error']}")
+                    missing_flags.append(uncached_flags[0])
+
+            else:
+                # Batch evaluation
+                if session_id:
+                    # Use session-based batch evaluation
+                    response = http.post('evaluatebatchfeatureflags', {
+                        'session_id': session_id,
+                        'flag_names': uncached_flags,
+                        'context': {},
+                        'defaults': {k: v for k, v in defaults.items() if k in uncached_flags}
+                    })
+                else:
+                    # Use stateless batch evaluation
+                    response = http.post('evaluatebatchfeatureflagsstateless', {
+                        'agent_id': agent_id,
+                        'flag_names': uncached_flags,
+                        'context': {},
+                        'defaults': {k: v for k, v in defaults.items() if k in uncached_flags}
+                    })
+
+                # Process batch response
+                if 'flags' in response:
+                    for name in uncached_flags:
+                        flag_data = response['flags'].get(name)
+                        if flag_data and 'value' in flag_data:
+                            value = flag_data['value']
+                            cached_results[name] = value
+
+                            # Cache it
+                            if cache_ttl != 0:
+                                cache_key = f"{agent_id}:{name}"
+                                _flag_cache.set(cache_key, value, ttl=cache_ttl if cache_ttl > 0 else None)
+                        else:
+                            missing_flags.append(name)
+
+        except Exception as e:
+            # HTTP client raises on errors, fall back to defaults
+            logger.error(f"Failed to fetch feature flags: {e}")
+
+            # Use defaults for all uncached flags
+            for name in uncached_flags:
+                if name in defaults:
+                    cached_results[name] = defaults[name]
+                else:
+                    missing_flags.append(name)
+                    if is_single and not return_missing:
+                        raise FeatureFlagError(f"'{name}': {e}") from e
+    
+    # Build final result
+    result = {}
+    for name in flag_names:
+        if name in cached_results:
+            result[name] = cached_results[name]
+        elif name in defaults:
+            result[name] = defaults[name]
+        else:
+            # No value and no default
+            missing_flags.append(name)
+            if is_single and not return_missing:
+                raise FeatureFlagError(f"'{name}' not found and no default provided")
+            else:
+                result[name] = None
+    
+    # Return based on input type and return_missing flag
+    if return_missing:
+        return (result[flag_names[0]] if is_single else result, missing_flags)
+    else:
+        return result[flag_names[0]] if is_single else result
+
+
+# Typed convenience functions
+def get_bool_flag(flag_name: str, default: Optional[bool] = None, **kwargs) -> bool:
+    """
+    Get a boolean feature flag with type validation.
+
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+        TypeError: If flag value is not a boolean
+    """
+    value = get_feature_flag(flag_name, default=default if default is not None else MISSING, **kwargs)
+    if not isinstance(value, bool):
+        if default is not None:
+            logger.warning(f"Feature flag '{flag_name}' is not a boolean, using default")
+            return default
+        raise TypeError(f"Feature flag '{flag_name}' expected boolean, got {type(value).__name__}")
+    return value
+
+
+def get_int_flag(flag_name: str, default: Optional[int] = None, **kwargs) -> int:
+    """
+    Get an integer feature flag with type validation.
+
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+        TypeError: If flag value is not an integer
+    """
+    value = get_feature_flag(flag_name, default=default if default is not None else MISSING, **kwargs)
+    if not isinstance(value, int) or isinstance(value, bool):  # bool is subclass of int
+        if default is not None:
+            logger.warning(f"Feature flag '{flag_name}' is not an integer, using default")
+            return default
+        raise TypeError(f"Feature flag '{flag_name}' expected integer, got {type(value).__name__}")
+    return value
+
+
+def get_float_flag(flag_name: str, default: Optional[float] = None, **kwargs) -> float:
+    """
+    Get a float feature flag with type validation.
+
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+        TypeError: If flag value is not a float
+    """
+    value = get_feature_flag(flag_name, default=default if default is not None else MISSING, **kwargs)
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        if default is not None:
+            logger.warning(f"Feature flag '{flag_name}' is not a float, using default")
+            return default
+        raise TypeError(f"Feature flag '{flag_name}' expected float, got {type(value).__name__}")
+    return float(value)
+
+
+def get_string_flag(flag_name: str, default: Optional[str] = None, **kwargs) -> str:
+    """
+    Get a string feature flag with type validation.
+
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+        TypeError: If flag value is not a string
+    """
+    value = get_feature_flag(flag_name, default=default if default is not None else MISSING, **kwargs)
+    if not isinstance(value, str):
+        if default is not None:
+            logger.warning(f"Feature flag '{flag_name}' is not a string, using default")
+            return default
+        raise TypeError(f"Feature flag '{flag_name}' expected string, got {type(value).__name__}")
+    return value
+
+
+def get_json_flag(flag_name: str, default: Optional[dict] = None, **kwargs) -> dict:
+    """
+    Get a JSON object feature flag.
+
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+    """
+    value = get_feature_flag(flag_name, default=default if default is not None else MISSING, **kwargs)
+    return value
+
+
+def clear_feature_flag_cache():
+    """Clear the feature flag cache."""
+    _flag_cache.clear()
+    logger.debug("Feature flag cache cleared")

lucidicai/sdk/init.py

@@ -0,0 +1,271 @@
+"""SDK initialization module.
+
+This module handles SDK initialization, separating concerns from the main __init__.py
+"""
+import uuid
+from typing import List, Optional
+
+from ..api.client import HttpClient
+from ..api.resources.event import EventResource
+from ..api.resources.session import SessionResource
+from ..api.resources.dataset import DatasetResource
+from ..core.config import SDKConfig, get_config, set_config
+from ..utils.queue import EventQueue
+from ..utils.logger import debug, info, warning, error, truncate_id
+from .context import set_active_session, current_session_id
+from .error_boundary import register_cleanup_handler
+from .shutdown_manager import get_shutdown_manager, SessionState
+from ..telemetry.telemetry_init import instrument_providers
+from opentelemetry.sdk.trace import TracerProvider
+
+
+class SDKState:
+    """Container for SDK runtime state."""
+    
+    def __init__(self):
+        self.http: Optional[HttpClient] = None
+        self.event_queue: Optional[EventQueue] = None
+        self.session_id: Optional[str] = None
+        self.tracer_provider: Optional[TracerProvider] = None
+        self.resources = {}
+    
+    def reset(self):
+        """Reset SDK state."""
+        # Shutdown telemetry first to ensure all spans are exported
+        if self.tracer_provider:
+            try:
+                # Force flush all pending spans with 5 second timeout
+                debug("[SDK] Flushing OpenTelemetry spans...")
+                self.tracer_provider.force_flush(timeout_millis=5000)
+                # Shutdown the tracer provider and all processors
+                self.tracer_provider.shutdown()
+                debug("[SDK] TracerProvider shutdown complete")
+            except Exception as e:
+                error(f"[SDK] Error shutting down TracerProvider: {e}")
+        
+        if self.event_queue:
+            self.event_queue.shutdown()
+        if self.http:
+            self.http.close()
+        
+        self.http = None
+        self.event_queue = None
+        self.session_id = None
+        self.tracer_provider = None
+        self.resources = {}
+
+
+# Global SDK state
+_sdk_state = SDKState()
+
+
+def init(
+    session_name: Optional[str] = None,
+    session_id: Optional[str] = None,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+    task: Optional[str] = None,
+    providers: Optional[List[str]] = None,
+    production_monitoring: bool = False,
+    experiment_id: Optional[str] = None,
+    evaluators: Optional[List] = None,
+    tags: Optional[List] = None,
+    datasetitem_id: Optional[str] = None,
+    masking_function: Optional[callable] = None,
+    auto_end: bool = True,
+    capture_uncaught: bool = True,
+) -> str:
+    """Initialize the Lucidic SDK.
+    
+    Args:
+        session_name: Name for the session
+        session_id: Custom session ID (optional)
+        api_key: API key (uses env if not provided)
+        agent_id: Agent ID (uses env if not provided)
+        task: Task description
+        providers: List of telemetry providers to instrument
+        production_monitoring: Enable production monitoring
+        experiment_id: Experiment ID to associate with session
+        evaluators: Ealuators to use
+        tags: Session tags
+        datasetitem_id: Dataset item ID
+        masking_function: Function to mask sensitive data
+        auto_end: Automatically end session on exit
+        capture_uncaught: Capture uncaught exceptions
+        
+    Returns:
+        Session ID
+        
+    Raises:
+        APIKeyVerificationError: If API credentials are invalid
+    """
+    global _sdk_state
+    
+    # Create or update configuration
+    config = SDKConfig.from_env(
+        api_key=api_key,
+        agent_id=agent_id,
+        auto_end=auto_end,
+        production_monitoring=production_monitoring
+    )
+    
+    if providers:
+        config.telemetry.providers = providers
+    
+    config.error_handling.capture_uncaught = capture_uncaught
+    
+    # Validate configuration
+    errors = config.validate()
+    if errors:
+        raise ValueError(f"Invalid configuration: {', '.join(errors)}")
+    
+    # Set global config
+    set_config(config)
+    
+    # Initialize HTTP client
+    if not _sdk_state.http:
+        debug("[SDK] Initializing HTTP client")
+        _sdk_state.http = HttpClient(config)
+    
+    # Initialize resources
+    if not _sdk_state.resources:
+        _sdk_state.resources = {
+            'events': EventResource(_sdk_state.http),
+            'sessions': SessionResource(_sdk_state.http),
+            'datasets': DatasetResource(_sdk_state.http)
+        }
+    
+    # Initialize event queue
+    if not _sdk_state.event_queue:
+        debug("[SDK] Initializing event queue")
+        # Create a mock client object for backward compatibility
+        # The queue needs a client with make_request method
+        class ClientAdapter:
+            def make_request(self, endpoint, method, data):
+                return _sdk_state.http.request(method, endpoint, json=data)
+        
+        _sdk_state.event_queue = EventQueue(ClientAdapter())
+        
+        # Register cleanup handler
+        register_cleanup_handler(lambda: _sdk_state.event_queue.force_flush())
+        debug("[SDK] Event queue initialized and cleanup handler registered")
+    
+    # Create or retrieve session
+    if session_id:
+        # Use provided session ID
+        real_session_id = session_id
+    else:
+        # Create new session
+        real_session_id = str(uuid.uuid4())
+    
+    # Create session via API - only send non-None values
+    session_params = {
+        'session_id': real_session_id,
+        'session_name': session_name or 'Unnamed Session',
+        'agent_id': config.agent_id,
+    }
+    
+    # Only add optional fields if they have values
+    if task:
+        session_params['task'] = task
+    if tags:
+        session_params['tags'] = tags
+    if experiment_id:
+        session_params['experiment_id'] = experiment_id
+    if datasetitem_id:
+        session_params['datasetitem_id'] = datasetitem_id
+    if evaluators:
+        session_params['evaluators'] = evaluators
+    if production_monitoring:
+        session_params['production_monitoring'] = production_monitoring
+    
+    debug(f"[SDK] Creating session with params: {session_params}")
+    session_resource = _sdk_state.resources['sessions']
+    session_data = session_resource.create_session(session_params)
+    
+    # Use the session_id returned by the backend
+    real_session_id = session_data.get('session_id', real_session_id)
+    _sdk_state.session_id = real_session_id
+    
+    info(f"[SDK] Session created: {truncate_id(real_session_id)} (name: {session_name or 'Unnamed Session'})")
+    
+    # Set active session in context
+    set_active_session(real_session_id)
+    
+    # Register session with shutdown manager
+    debug(f"[SDK] Registering session with shutdown manager (auto_end={auto_end})")
+    shutdown_manager = get_shutdown_manager()
+    session_state = SessionState(
+        session_id=real_session_id,
+        http_client=_sdk_state.resources,  # Pass resources dict which has sessions
+        event_queue=_sdk_state.event_queue,
+        auto_end=auto_end
+    )
+    shutdown_manager.register_session(real_session_id, session_state)
+    
+    # Initialize telemetry if providers specified
+    if providers:
+        debug(f"[SDK] Initializing telemetry for providers: {providers}")
+        _initialize_telemetry(providers)
+    
+    return real_session_id
+
+
+def _initialize_telemetry(providers: List[str]) -> None:
+    """Initialize telemetry providers.
+    
+    Args:
+        providers: List of provider names
+    """
+    global _sdk_state
+    
+    if not _sdk_state.tracer_provider:
+        # Import here to avoid circular dependency
+        from ..telemetry.lucidic_exporter import LucidicSpanExporter
+        from ..telemetry.context_capture_processor import ContextCaptureProcessor
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+        
+        # Create tracer provider with our processors
+        _sdk_state.tracer_provider = TracerProvider()
+        
+        # Add context capture processor FIRST to capture context before export
+        context_processor = ContextCaptureProcessor()
+        _sdk_state.tracer_provider.add_span_processor(context_processor)
+        
+        # Add exporter processor
+        exporter = LucidicSpanExporter()
+        export_processor = BatchSpanProcessor(exporter)
+        _sdk_state.tracer_provider.add_span_processor(export_processor)
+    
+    # Instrument providers
+    instrument_providers(providers, _sdk_state.tracer_provider, {})
+    
+    info(f"[Telemetry] Initialized for providers: {providers}")
+
+
+def get_session_id() -> Optional[str]:
+    """Get the current session ID."""
+    return _sdk_state.session_id or current_session_id.get()
+
+
+def get_http() -> Optional[HttpClient]:
+    """Get the HTTP client instance."""
+    return _sdk_state.http
+
+
+def get_event_queue() -> Optional[EventQueue]:
+    """Get the event queue instance."""
+    return _sdk_state.event_queue
+
+
+def get_resources() -> dict:
+    """Get API resource instances."""
+    return _sdk_state.resources
+
+
+def clear_state() -> None:
+    """Clear SDK state (for testing)."""
+    global _sdk_state
+    debug("[SDK] Clearing SDK state")
+    _sdk_state.reset()
+    _sdk_state = SDKState()