lucidicai 1.3.5__py3-none-any.whl → 2.0.1__py3-none-any.whl

lucidicai/feature_flag.py

@@ -0,0 +1,336 @@
+import os
+import logging
+import time
+from typing import Union, List, Dict, Any, Optional, overload, Tuple, Literal
+from dotenv import load_dotenv
+
+from .client import Client
+from .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 client
+        client = Client()
+        if not getattr(client, 'initialized', False):
+            client = Client(api_key=api_key, agent_id=agent_id)
+        else:
+            if api_key != client.api_key or agent_id != client.agent_id:
+                client.set_api_key(api_key)
+                client.agent_id = agent_id
+        
+        try:
+            # Make batch API call
+            response = client.make_request(
+                'getfeatureflags',
+                'POST',
+                {'flag_names': uncached_flags}
+            )
+            
+            # Process response and update cache
+            for name in uncached_flags:
+                if name in response['flags']:
+                    if response['flags'][name]['found']:
+                        value = response['flags'][name]['value']
+                        cached_results[name] = value
+                        
+                        # Cache the value
+                        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:
+                        # Flag not found on server
+                        missing_flags.append(name)
+                        logger.warning(f"Feature flag '{name}' not found on server")
+                
+        except Exception as e:
+            # Log the error
+            logger.error(f"Failed to fetch feature flags: {e}")
+            
+            # Check if we have defaults for missing flags
+            for name in uncached_flags:
+                if name not in cached_results:
+                    if name in defaults:
+                        cached_results[name] = defaults[name]
+                    elif is_single and not return_missing:
+                        # Single flag without default and not returning missing - raise error
+                        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/session.py

@@ -1,16 +1,7 @@
-import base64
-import io
-import logging
-from typing import List, Optional
-
-from PIL import Image
+from typing import Optional
 
 from .errors import InvalidOperationError, LucidicNotInitializedError
-from .image_upload import get_presigned_url, upload_image_to_s3
-from .step import Step
-from .event import Event
 
-logger = logging.getLogger("Lucidic")
 
 class Session:
     def __init__(
@@ -21,9 +12,7 @@ class Session:
     ):
         self.agent_id = agent_id
         self.session_id = session_id
-        self.step_history = dict()
-        self._active_step: Optional[str] = None  # Step ID, not Step object
-        self.event_history = dict()
+        self.event_history = []  # List[Event]
         self.latest_event = None
         self.is_finished = False
         self.is_successful = None
@@ -32,13 +21,6 @@ class Session:
         self.session_eval_reason = None
         self.has_gif = None
         
-    @property   
-    def active_step(self) -> Optional[Step]:
-        """Get the active step object"""
-        if self._active_step and self._active_step in self.step_history:
-            return self.step_history[self._active_step]
-        return None
-    
     def update_session(
         self, 
         **kwargs
@@ -54,60 +36,16 @@ class Session:
             "session_eval_reason": Client().mask(kwargs.get("session_eval_reason", None)),
             "tags": kwargs.get("tags", None)
         }
-
-        # auto end any unfinished steps
-        if kwargs.get("is_finished", None) is True:
-            for step_id, step in self.step_history.items():
-                if not step.is_finished:
-                    self.update_step(step_id=step_id, is_finished=True)
-
         Client().make_request('updatesession', 'PUT', request_data)
 
-    def create_step(self, **kwargs) -> str:
+    def create_event(self, type: str = "generic", **kwargs) -> str:
+        """Proxy to client.create_event bound to this session."""
         if not self.session_id:
             raise LucidicNotInitializedError()
-        step = Step(session_id=self.session_id, **kwargs)
-        self.step_history[step.step_id] = step
-        self._active_step = step.step_id
-        return step.step_id
-
-    def update_step(self, **kwargs) -> None:
-        if 'step_id' in kwargs and kwargs['step_id'] is not None:
-            if kwargs['step_id'] not in self.step_history:
-                raise InvalidOperationError("Step ID not found in session history")
-            self.step_history[kwargs['step_id']].update_step(**kwargs)
-        else:
-            if not self._active_step:
-                raise InvalidOperationError("No active step to update")
-            self.step_history[self._active_step].update_step(**kwargs)
-
-
-    def create_event(self, **kwargs):
-        # Get step_id from kwargs or active step
-        if 'step_id' in kwargs and kwargs['step_id'] is not None:
-            step_id = kwargs['step_id']
-        elif self._active_step:
-            step_id = self._active_step
-        else:
-            step_id = None
-        kwargs.pop('step_id', None)
-        event = Event(
-            session_id=self.session_id,
-            step_id=step_id,
-            **kwargs
-        )
-        self.event_history[event.event_id] = event
-        self._active_event = event
-        return event.event_id
-
-    def update_event(self, **kwargs):
-        if 'event_id' in kwargs and kwargs['event_id'] is not None:
-            if kwargs['event_id'] not in self.event_history:
-                raise InvalidOperationError("Event ID not found in session history")
-            self.event_history[kwargs['event_id']].update_event(**kwargs)
-        else:
-            if not self._active_event:
-                raise InvalidOperationError("No active event to update")
-            self._active_event.update_event(**kwargs)
+        from .client import Client
+        kwargs = dict(kwargs)
+        kwargs['session_id'] = self.session_id
+        event_id = Client().create_event(type=type, **kwargs)
+        return event_id
 
             

lucidicai/singleton.py

@@ -1,28 +1,31 @@
+import threading
 from .errors import LucidicNotInitializedError
 
 lai_inst = {}
+_singleton_lock = threading.Lock()
 
 def singleton(class_):
     def getinstance(*args, **kwargs):
-
-        inst = lai_inst.get(class_)
-
-        # on first access -> no instance yet
-        if inst is None:
-            # no args/kwargs -> return a NullClient for Client
-            if class_.__name__ == 'Client' and not args and not kwargs:
-                inst = NullClient()
-            else:
+        # Thread-safe singleton pattern
+        with _singleton_lock:
+            inst = lai_inst.get(class_)
+
+            # on first access -> no instance yet
+            if inst is None:
+                # no args/kwargs -> return a NullClient for Client
+                if class_.__name__ == 'Client' and not args and not kwargs:
+                    inst = NullClient()
+                else:
+                    inst = class_(*args, **kwargs)
+                lai_inst[class_] = inst
+                return inst
+
+            # existing instance present
+            # if NullClient and now real init args are passed -> upgrade it
+            if isinstance(inst, NullClient) and (args or kwargs):
                 inst = class_(*args, **kwargs)
-            lai_inst[class_] = inst
+                lai_inst[class_] = inst
             return inst
-
-        # existing instance present
-        # if NullClient and now real init args are passed -> upgrade it
-        if isinstance(inst, NullClient) and (args or kwargs):
-            inst = class_(*args, **kwargs)
-            lai_inst[class_] = inst
-        return inst
     
     return getinstance
 

lucidicai/streaming.py

@@ -21,42 +21,10 @@ class StreamingResponseWrapper:
         self.accumulated_content = ""
         self.usage = None
         
-        # Create initial event
-        self._create_initial_event()
+        # We no longer create an initial event; emit a single immutable event on finalize
     
     def _create_initial_event(self):
-        """Create the initial event for streaming response"""
-        try:
-            # Check if event_id was already created
-            if '_event_id' in self.kwargs:
-                self.event_id = self.kwargs['_event_id']
-                logger.info(f"[Streaming] Using existing event ID: {self.event_id}")
-                return
-                
-            if Client().session:
-                description, images = self._format_messages(self.kwargs.get('messages', ''))
-                
-                event_data = {
-                    'action': description,
-                    'cost': 0,
-                    'provider': 'OpenAI',
-                    'model': self.kwargs.get('model', 'unknown'),
-                    'tool': 'streaming',
-                    'raw_request': json.dumps({
-                        'model': self.kwargs.get('model'),
-                        'messages': self._serialize_messages(self.kwargs.get('messages', [])),
-                        'stream': True,
-                        **{k: v for k, v in self.kwargs.items() if k not in ['messages', 'model', 'stream', '_event_id']}
-                    })
-                }
-                
-                if images:
-                    event_data['screenshots'] = images
-                
-                self.event_id = Client().session.create_event(**event_data)
-                logger.debug(f"[Streaming] Created new streaming event with ID: {self.event_id}")
-        except Exception as e:
-            logger.error(f"[Streaming] Error creating initial streaming event: {str(e)}")
+        return
     
     def _format_messages(self, messages):
         """Format messages for description and extract images"""
@@ -195,10 +163,6 @@ class StreamingResponseWrapper:
         try:
             logger.info(f"[Streaming] Finalizing event {self.event_id}, accumulated content length: {len(self.accumulated_content)}")
             
-            if not self.event_id:
-                logger.warning("[Streaming] No event_id to finalize")
-                return
-                
             if not self.session:
                 # Try to get session from client
                 try:
@@ -229,18 +193,19 @@ class StreamingResponseWrapper:
             model = self.kwargs.get('model', 'unknown')
             cost = self._calculate_cost(model, prompt_tokens, completion_tokens)
             
-            # Update event with safe defaults
-            update_data = {
-                'result': self.accumulated_content if self.accumulated_content else "Stream completed (no content received)",
-                'cost_added': cost if cost else 0.0,
-                'is_finished': True,
-                'model': model
-            }
-            
-            update_data['event_id'] = self.event_id
-            logger.info(f"[Streaming] Updating event with: result='{update_data.get('result', '')[:50]}...', cost_added={update_data.get('cost_added', 0)}, is_finished=True")
-            self.session.update_event(**update_data)
-            logger.info(f"[Streaming] Successfully finalized streaming event {self.event_id}")
+            # Create single immutable event at end
+            result_text = self.accumulated_content if self.accumulated_content else "Stream completed (no content received)"
+            Client().create_event(
+                type="llm_generation",
+                model=model,
+                messages=self.kwargs.get('messages', []),
+                output=result_text,
+                input_tokens=int(prompt_tokens),
+                output_tokens=int(completion_tokens),
+                cost=cost,
+                duration=duration,
+            )
+            logger.info(f"[Streaming] Emitted immutable streaming event")
             
         except Exception as e:
             logger.error(f"[Streaming] Error finalizing event {self.event_id}: {str(e)}")

lucidicai/telemetry/context_capture_processor.py

@@ -0,0 +1,65 @@
+"""
+Context Capture Processor for OpenTelemetry spans.
+
+This processor captures Lucidic context (session_id, parent_event_id) at span creation time
+and stores it in span attributes. This ensures context is preserved even when spans are
+processed asynchronously in different threads/contexts.
+
+This fixes the nesting issue for ALL providers (OpenAI, Anthropic, LangChain, etc.)
+"""
+
+import logging
+from typing import Optional
+from opentelemetry.sdk.trace import SpanProcessor, ReadableSpan
+from opentelemetry.trace import Span
+from opentelemetry import context as otel_context
+
+logger = logging.getLogger("Lucidic")
+
+
+class ContextCaptureProcessor(SpanProcessor):
+    """Captures Lucidic context at span creation and stores in attributes."""
+    
+    def on_start(self, span: Span, parent_context: Optional[otel_context.Context] = None) -> None:
+        """Called when a span is started - capture context here."""
+        try:
+            # Import here to avoid circular imports
+            from lucidicai.context import current_session_id, current_parent_event_id
+            
+            # Capture session ID from context
+            session_id = None
+            try:
+                session_id = current_session_id.get(None)
+            except Exception:
+                pass
+            
+            # Capture parent event ID from context
+            parent_event_id = None
+            try:
+                parent_event_id = current_parent_event_id.get(None)
+            except Exception:
+                pass
+            
+            # Store in span attributes for later retrieval
+            if session_id:
+                span.set_attribute("lucidic.session_id", session_id)
+            
+            if parent_event_id:
+                span.set_attribute("lucidic.parent_event_id", parent_event_id)
+                logger.debug(f"[ContextCapture] Captured parent_event_id {parent_event_id[:8]}... for span {span.name}")
+            
+        except Exception as e:
+            # Never fail span creation due to context capture
+            logger.debug(f"[ContextCapture] Failed to capture context: {e}")
+    
+    def on_end(self, span: ReadableSpan) -> None:
+        """Called when a span ends - no action needed."""
+        pass
+    
+    def shutdown(self) -> None:
+        """Shutdown the processor."""
+        pass
+    
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        """Force flush - no buffering in this processor."""
+        return True