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

lucidicai/__init__.py

@@ -14,6 +14,10 @@ from .sdk.init import (
     init as _init,
     get_session_id as _get_session_id,
     clear_state as _clear_state,
+    # Thread-local session management (advanced users)
+    set_thread_session,
+    clear_thread_session,
+    get_thread_session,
 )
 
 from .sdk.event import (
@@ -32,6 +36,7 @@ from .sdk.context import (
     session_async,
     run_session,
     run_in_session,
+    thread_worker_with_session,  # Thread isolation helper
     current_session_id,
     current_parent_event_id,
 )
@@ -55,12 +60,15 @@ def _update_session(
     session_eval=None,
     session_eval_reason=None,
     is_successful=None,
-    is_successful_reason=None
+    is_successful_reason=None,
+    session_id=None  # Accept explicit session_id
 ):
     """Update the current session."""
     from .sdk.init import get_resources, get_session_id
-    
-    session_id = get_session_id()
+
+    # Use provided session_id or fall back to context
+    if not session_id:
+        session_id = get_session_id()
     if not session_id:
         return
     
@@ -87,12 +95,16 @@ def _end_session(
     session_eval_reason=None,
     is_successful=None,
     is_successful_reason=None,
-    wait_for_flush=True
+    wait_for_flush=True,
+    session_id=None  # Accept explicit session_id
 ):
     """End the current session."""
     from .sdk.init import get_resources, get_session_id, get_event_queue
-    
-    session_id = get_session_id()
+    from .sdk.shutdown_manager import get_shutdown_manager
+
+    # Use provided session_id or fall back to context
+    if not session_id:
+        session_id = get_session_id()
     if not session_id:
         return
     
@@ -114,6 +126,9 @@ def _end_session(
     # Clear session context
     clear_active_session()
 
+    # unregister from shutdown manager
+    get_shutdown_manager().unregister_session(session_id)
+
 
 def _get_session():
     """Get the current session object."""
@@ -282,7 +297,7 @@ get_error_history = error_boundary.get_error_history
 clear_error_history = error_boundary.clear_error_history
 
 # Version
-__version__ = "2.0.0"
+__version__ = "2.1.2"
 
 # Apply error boundary wrapping to all SDK functions
 from .sdk.error_boundary import wrap_sdk_function
@@ -371,8 +386,14 @@ __all__ = [
     'session_async',
     'run_session',
     'run_in_session',
+    'thread_worker_with_session',
     'current_session_id',
     'current_parent_event_id',
+
+    # Thread-local session management (advanced)
+    'set_thread_session',
+    'clear_thread_session',
+    'get_thread_session',
     
     # Error types
     'LucidicError',

lucidicai/core/config.py

@@ -19,7 +19,7 @@ class Environment(Enum):
 @dataclass
 class NetworkConfig:
     """Network and connection settings"""
-    base_url: str = "https://api.lucidic.ai/api"
+    base_url: str = "https://backend.lucidic.ai/api"
     timeout: int = 30
     max_retries: int = 3
     backoff_factor: float = 0.5
@@ -31,7 +31,7 @@ class NetworkConfig:
         """Load network configuration from environment variables"""
         debug = os.getenv("LUCIDIC_DEBUG", "False").lower() == "true"
         return cls(
-            base_url="http://localhost:8000/api" if debug else "https://api.lucidic.ai/api",
+            base_url="http://localhost:8000/api" if debug else "https://backend.lucidic.ai/api",
             timeout=int(os.getenv("LUCIDIC_TIMEOUT", "30")),
             max_retries=int(os.getenv("LUCIDIC_MAX_RETRIES", "3")),
             backoff_factor=float(os.getenv("LUCIDIC_BACKOFF_FACTOR", "0.5")),

lucidicai/sdk/context.py

@@ -1,4 +1,4 @@
-"""Async-safe context helpers for session (and step, extensible).
+"""Async-safe and thread-safe context helpers for session (and step, extensible).
 
 This module exposes context variables and helpers to bind a Lucidic
 session to the current execution context (threads/async tasks), so
@@ -11,6 +11,7 @@ import contextvars
 from typing import Optional, Iterator, AsyncIterator, Callable, Any, Dict
 import logging
 import os
+import threading
 
 
 # Context variable for the active Lucidic session id
@@ -26,32 +27,71 @@ current_parent_event_id: contextvars.ContextVar[Optional[str]] = contextvars.Con
 
 
 def set_active_session(session_id: Optional[str]) -> None:
-    """Bind the given session id to the current execution context."""
+    """Bind the given session id to the current execution context.
+
+    Sets both contextvar and thread-local storage when in a thread.
+    """
+    from .init import set_thread_session, is_main_thread
+
     current_session_id.set(session_id)
 
+    # Also set thread-local storage if we're in a non-main thread
+    if session_id and not is_main_thread():
+        set_thread_session(session_id)
+
 
 def clear_active_session() -> None:
-    """Clear any active session binding in the current execution context."""
+    """Clear any active session binding in the current execution context.
+
+    Clears both contextvar and thread-local storage when in a thread.
+    """
+    from .init import clear_thread_session, is_main_thread
+
     current_session_id.set(None)
 
+    # Also clear thread-local storage if we're in a non-main thread
+    if not is_main_thread():
+        clear_thread_session()
+
 
 @contextmanager
 def bind_session(session_id: str) -> Iterator[None]:
-    """Context manager to temporarily bind an active session id."""
+    """Context manager to temporarily bind an active session id.
+
+    Handles both thread-local and context variable storage for proper isolation.
+    """
+    from .init import set_thread_session, clear_thread_session, is_main_thread
+
     token = current_session_id.set(session_id)
+
+    # If we're in a non-main thread, also set thread-local storage
+    thread_local_set = False
+    if not is_main_thread():
+        set_thread_session(session_id)
+        thread_local_set = True
+
     try:
         yield
     finally:
+        if thread_local_set:
+            clear_thread_session()
         current_session_id.reset(token)
 
 
 @asynccontextmanager
 async def bind_session_async(session_id: str) -> AsyncIterator[None]:
     """Async context manager to temporarily bind an active session id."""
+    from .init import set_task_session, clear_task_session
+
     token = current_session_id.set(session_id)
+
+    # Also set task-local for async isolation
+    set_task_session(session_id)
+
     try:
         yield
     finally:
+        clear_task_session()
         current_session_id.reset(token)
 
 
@@ -81,9 +121,11 @@ def session(**init_params) -> Iterator[None]:
     Notes:
     - Ignores any provided auto_end parameter and ends the session on context exit.
     - If LUCIDIC_DEBUG is true, logs a warning about ignoring auto_end.
+    - Handles thread-local storage for proper thread isolation.
     """
     # Lazy import to avoid circular imports
     import lucidicai as lai  # type: ignore
+    from .init import set_thread_session, clear_thread_session, is_main_thread
 
     # Force auto_end to False inside a context manager to control explicit end
     user_auto_end = init_params.get('auto_end', None)
@@ -95,12 +137,43 @@ def session(**init_params) -> Iterator[None]:
 
     session_id = lai.init(**init_params)
     token = current_session_id.set(session_id)
+
+    # If we're in a non-main thread, also set thread-local storage
+    thread_local_set = False
+    if not is_main_thread():
+        set_thread_session(session_id)
+        thread_local_set = True
+
     try:
         yield
     finally:
+        if thread_local_set:
+            clear_thread_session()
         current_session_id.reset(token)
         try:
-            lai.end_session()
+            # Force flush OpenTelemetry spans before ending session
+            from .init import get_tracer_provider
+            from ..utils.logger import debug, info
+            import time
+
+            tracer_provider = get_tracer_provider()
+            if tracer_provider:
+                debug(f"[Session] Force flushing OpenTelemetry spans for session {session_id}")
+                try:
+                    # Force flush with 5 second timeout to ensure all spans are exported
+                    flush_result = tracer_provider.force_flush(timeout_millis=5000)
+                    debug(f"[Session] Tracer provider force_flush returned: {flush_result}")
+
+                    # Give a small additional delay to ensure the exporter processes everything
+                    # This is necessary because force_flush on the provider flushes the processors,
+                    # but the exporter might still be processing the spans
+                    time.sleep(0.5)
+                    debug(f"[Session] Successfully flushed spans for session {session_id}")
+                except Exception as e:
+                    debug(f"[Session] Error flushing spans: {e}")
+
+            # Pass session_id explicitly to avoid context issues
+            lai.end_session(session_id=session_id)
         except Exception:
             # Avoid masking the original exception from the with-block
             pass
@@ -110,6 +183,7 @@ def session(**init_params) -> Iterator[None]:
 async def session_async(**init_params) -> AsyncIterator[None]:
     """Async counterpart of session(...)."""
     import lucidicai as lai  # type: ignore
+    from .init import set_task_session, clear_task_session
 
     user_auto_end = init_params.get('auto_end', None)
     init_params = dict(init_params)
@@ -120,12 +194,40 @@ async def session_async(**init_params) -> AsyncIterator[None]:
 
     session_id = lai.init(**init_params)
     token = current_session_id.set(session_id)
+
+    # Set task-local session for true isolation in async
+    set_task_session(session_id)
+
     try:
         yield
     finally:
+        # Clear task-local session first
+        clear_task_session()
         current_session_id.reset(token)
         try:
-            lai.end_session()
+            # Force flush OpenTelemetry spans before ending session
+            from .init import get_tracer_provider
+            from ..utils.logger import debug, info
+            import asyncio
+
+            tracer_provider = get_tracer_provider()
+            if tracer_provider:
+                debug(f"[Session] Force flushing OpenTelemetry spans for async session {session_id}")
+                try:
+                    # Force flush with 5 second timeout to ensure all spans are exported
+                    flush_result = tracer_provider.force_flush(timeout_millis=5000)
+                    debug(f"[Session] Tracer provider force_flush returned: {flush_result}")
+
+                    # Give a small additional delay to ensure the exporter processes everything
+                    # This is necessary because force_flush on the provider flushes the processors,
+                    # but the exporter might still be processing the spans
+                    await asyncio.sleep(0.5)
+                    debug(f"[Session] Successfully flushed spans for async session {session_id}")
+                except Exception as e:
+                    debug(f"[Session] Error flushing spans: {e}")
+
+            # Pass session_id explicitly to avoid context issues in async
+            lai.end_session(session_id=session_id)
         except Exception:
             pass
 
@@ -142,3 +244,30 @@ def run_in_session(session_id: str, fn: Callable[..., Any], *fn_args: Any, **fn_
         return fn(*fn_args, **fn_kwargs)
 
 
+def thread_worker_with_session(session_id: str, target: Callable[..., Any], *args, **kwargs) -> Any:
+    """Wrapper for thread worker functions that ensures proper session isolation.
+
+    Use this as the target function for threads to ensure each thread gets
+    its own session context without bleeding from the parent thread.
+
+    Example:
+        thread = Thread(
+            target=thread_worker_with_session,
+            args=(session_id, actual_worker_function, arg1, arg2),
+            kwargs={'key': 'value'}
+        )
+    """
+    from .init import set_thread_session, clear_thread_session
+
+    # Set thread-local session immediately
+    set_thread_session(session_id)
+
+    try:
+        # Also bind to contextvar for compatibility
+        with bind_session(session_id):
+            return target(*args, **kwargs)
+    finally:
+        # Clean up thread-local storage
+        clear_thread_session()
+
+

lucidicai/sdk/event.py

@@ -12,23 +12,27 @@ 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
-    
-    # Get current session
-    session_id = get_session_id()
+
+    # 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")

lucidicai/sdk/init.py

@@ -4,6 +4,9 @@ This module handles SDK initialization, separating concerns from the main __init
 """
 import uuid
 from typing import List, Optional
+import asyncio
+import threading
+from weakref import WeakKeyDictionary
 
 from ..api.client import HttpClient
 from ..api.resources.event import EventResource
@@ -21,14 +24,18 @@ 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 = {}
-    
+        # Task-local storage for async task isolation
+        self.task_sessions: WeakKeyDictionary = WeakKeyDictionary()
+        # Thread-local storage for thread isolation
+        self.thread_local = threading.local()
+
     def reset(self):
         """Reset SDK state."""
         # Shutdown telemetry first to ensure all spans are exported
@@ -42,17 +49,21 @@ class SDKState:
                 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 = {}
+        self.task_sessions.clear()
+        # Clear thread-local storage for current thread
+        if hasattr(self.thread_local, 'session_id'):
+            delattr(self.thread_local, 'session_id')
 
 
 # Global SDK state
@@ -243,8 +254,87 @@ def _initialize_telemetry(providers: List[str]) -> None:
     info(f"[Telemetry] Initialized for providers: {providers}")
 
 
+def set_task_session(session_id: str) -> None:
+    """Set session ID for current async task (if in async context)."""
+    try:
+        if task := asyncio.current_task():
+            _sdk_state.task_sessions[task] = session_id
+            debug(f"[SDK] Set task-local session {truncate_id(session_id)} for task {task.get_name()}")
+    except RuntimeError:
+        # Not in async context, ignore
+        pass
+
+
+def clear_task_session() -> None:
+    """Clear session ID for current async task (if in async context)."""
+    try:
+        if task := asyncio.current_task():
+            _sdk_state.task_sessions.pop(task, None)
+            debug(f"[SDK] Cleared task-local session for task {task.get_name()}")
+    except RuntimeError:
+        # Not in async context, ignore
+        pass
+
+
+def set_thread_session(session_id: str) -> None:
+    """Set session ID for current thread.
+
+    This provides true thread-local storage that doesn't inherit from parent thread.
+    """
+    _sdk_state.thread_local.session_id = session_id
+    current_thread = threading.current_thread()
+    debug(f"[SDK] Set thread-local session {truncate_id(session_id)} for thread {current_thread.name}")
+
+
+def clear_thread_session() -> None:
+    """Clear session ID for current thread."""
+    if hasattr(_sdk_state.thread_local, 'session_id'):
+        delattr(_sdk_state.thread_local, 'session_id')
+        current_thread = threading.current_thread()
+        debug(f"[SDK] Cleared thread-local session for thread {current_thread.name}")
+
+
+def get_thread_session() -> Optional[str]:
+    """Get session ID from thread-local storage."""
+    return getattr(_sdk_state.thread_local, 'session_id', None)
+
+
+def is_main_thread() -> bool:
+    """Check if we're running in the main thread."""
+    return threading.current_thread() is threading.main_thread()
+
+
 def get_session_id() -> Optional[str]:
-    """Get the current session ID."""
+    """Get the current session ID.
+
+    Priority:
+    1. Task-local session (for async tasks)
+    2. Thread-local session (for threads) - NO FALLBACK for threads
+    3. SDK state session (for main thread)
+    4. Context variable session (fallback for main thread only)
+    """
+    # First check task-local storage for async isolation
+    try:
+        if task := asyncio.current_task():
+            if task_session := _sdk_state.task_sessions.get(task):
+                debug(f"[SDK] Using task-local session {truncate_id(task_session)}")
+                return task_session
+    except RuntimeError:
+        # Not in async context
+        pass
+
+    # Check if we're in a thread
+    if not is_main_thread():
+        # For threads, ONLY use thread-local storage - no fallback!
+        # This prevents inheriting the parent thread's session
+        thread_session = get_thread_session()
+        if thread_session:
+            debug(f"[SDK] Using thread-local session {truncate_id(thread_session)}")
+        else:
+            debug(f"[SDK] Thread {threading.current_thread().name} has no thread-local session")
+        return thread_session  # Return None if not set - don't fall back!
+
+    # For main thread only: fall back to SDK state or context variable
     return _sdk_state.session_id or current_session_id.get()
 
 
@@ -263,6 +353,11 @@ def get_resources() -> dict:
     return _sdk_state.resources
 
 
+def get_tracer_provider() -> Optional[TracerProvider]:
+    """Get the tracer provider instance."""
+    return _sdk_state.tracer_provider
+
+
 def clear_state() -> None:
     """Clear SDK state (for testing)."""
     global _sdk_state

lucidicai/telemetry/litellm_bridge.py

@@ -149,6 +149,7 @@ class LucidicLiteLLMCallback(CustomLogger):
             # Create event with correct field names
             create_event(
                 type="llm_generation",
+                session_id=session_id,  # Pass session_id explicitly
                 provider=provider,
                 model=model,
                 messages=messages,
@@ -210,6 +211,7 @@ class LucidicLiteLLMCallback(CustomLogger):
 
             create_event(
                 type="error_traceback",
+                session_id=session_id,  # Pass session_id explicitly
                 error=error_msg,
                 traceback="",
                 parent_event_id=parent_id,  # This will be normalized by EventBuilder

lucidicai/telemetry/lucidic_exporter.py

@@ -41,11 +41,26 @@ class LucidicSpanExporter(SpanExporter):
             if not detect_is_llm_span(span):
                 verbose(f"[Telemetry] Skipping non-LLM span: {span.name}")
                 return
-            
+
             debug(f"[Telemetry] Processing LLM span: {span.name}")
 
             attributes = dict(span.attributes or {})
 
+            # Debug: Check what attributes we have for responses.create
+            if span.name == "openai.responses.create":
+                debug(f"[Telemetry] responses.create span has {len(attributes)} attributes")
+                # Check for specific attributes we're interested in
+                has_prompts = any(k.startswith('gen_ai.prompt') for k in attributes.keys())
+                has_completions = any(k.startswith('gen_ai.completion') for k in attributes.keys())
+                debug(f"[Telemetry] Has prompt attrs: {has_prompts}, Has completion attrs: {has_completions}")
+
+            # Skip spans that are likely duplicates or incomplete
+            # Check if this is a responses.parse span that was already handled
+            if span.name == "openai.responses.create" and not attributes.get("lucidic.instrumented"):
+                # This might be from incorrect standard instrumentation
+                verbose(f"[Telemetry] Skipping potentially duplicate responses span without our marker")
+                return
+
             # Resolve session id
             target_session_id = attributes.get('lucidic.session_id')
             if not target_session_id:
@@ -84,7 +99,23 @@ class LucidicSpanExporter(SpanExporter):
             provider = self._detect_provider_name(attributes)
             messages = extract_prompts(attributes) or []
             params = self._extract_params(attributes)
-            output_text = extract_completions(span, attributes) or "Response received"
+            output_text = extract_completions(span, attributes)
+
+            # Debug for responses.create
+            if span.name == "openai.responses.create":
+                debug(f"[Telemetry] Extracted messages: {messages}")
+                debug(f"[Telemetry] Extracted output: {output_text}")
+
+            # Skip spans with no meaningful output (likely incomplete or duplicate instrumentation)
+            if not output_text or output_text == "Response received":
+                # Only use "Response received" if we have other meaningful data
+                if not messages and not attributes.get("lucidic.instrumented"):
+                    verbose(f"[Telemetry] Skipping span {span.name} with no meaningful content")
+                    return
+                # Use a more descriptive default if we must
+                if not output_text:
+                    output_text = "Response received"
+
             input_tokens = self._extract_prompt_tokens(attributes)
             output_tokens = self._extract_completion_tokens(attributes)
             cost = self._calculate_cost(attributes)
@@ -99,9 +130,10 @@ class LucidicSpanExporter(SpanExporter):
             
             try:
                 # Create immutable event via non-blocking queue
-                debug(f"[Telemetry] Creating LLM event with parent_id: {truncate_id(parent_id)}")
+                debug(f"[Telemetry] Creating LLM event with parent_id: {truncate_id(parent_id)}, session_id: {truncate_id(target_session_id)}")
                 event_id = create_event(
                 type="llm_generation",
+                session_id=target_session_id,  # Pass the session_id explicitly
                 occurred_at=occurred_at,
                 duration=duration_seconds,
                 provider=provider,
@@ -155,14 +187,15 @@ class LucidicSpanExporter(SpanExporter):
 
             # Create event
             event_kwargs = {
+                'session_id': target_session_id,  # Pass session_id explicitly
                 'description': description,
                 'result': "Processing...",  # Will be updated when span ends
                 'model': model
             }
-            
+
             if images:
                 event_kwargs['screenshots'] = images
-                
+
             return create_event(**event_kwargs)
             
         except Exception as e:
@@ -225,31 +258,35 @@ class LucidicSpanExporter(SpanExporter):
         }
 
     def _extract_prompt_tokens(self, attributes: Dict[str, Any]) -> int:
-        return (
-            attributes.get(SpanAttributes.LLM_USAGE_PROMPT_TOKENS) or
-            attributes.get('gen_ai.usage.prompt_tokens') or
-            attributes.get('gen_ai.usage.input_tokens') or 0
-        )
+        # Check each attribute and return the first non-None value
+        value = attributes.get(SpanAttributes.LLM_USAGE_PROMPT_TOKENS)
+        if value is not None:
+            return value
+        value = attributes.get('gen_ai.usage.prompt_tokens')
+        if value is not None:
+            return value
+        value = attributes.get('gen_ai.usage.input_tokens')
+        if value is not None:
+            return value
+        return 0
 
     def _extract_completion_tokens(self, attributes: Dict[str, Any]) -> int:
-        return (
-            attributes.get(SpanAttributes.LLM_USAGE_COMPLETION_TOKENS) or
-            attributes.get('gen_ai.usage.completion_tokens') or
-            attributes.get('gen_ai.usage.output_tokens') or 0
-        )
+        # Check each attribute and return the first non-None value
+        value = attributes.get(SpanAttributes.LLM_USAGE_COMPLETION_TOKENS)
+        if value is not None:
+            return value
+        value = attributes.get('gen_ai.usage.completion_tokens')
+        if value is not None:
+            return value
+        value = attributes.get('gen_ai.usage.output_tokens')
+        if value is not None:
+            return value
+        return 0
     
     def _calculate_cost(self, attributes: Dict[str, Any]) -> Optional[float]:
-        prompt_tokens = (
-            attributes.get(SpanAttributes.LLM_USAGE_PROMPT_TOKENS) or
-            attributes.get('gen_ai.usage.prompt_tokens') or
-            attributes.get('gen_ai.usage.input_tokens') or 0
-        )
-        completion_tokens = (
-            attributes.get(SpanAttributes.LLM_USAGE_COMPLETION_TOKENS) or
-            attributes.get('gen_ai.usage.completion_tokens') or
-            attributes.get('gen_ai.usage.output_tokens') or 0
-        )
-        total_tokens = (prompt_tokens or 0) + (completion_tokens or 0)
+        prompt_tokens = self._extract_prompt_tokens(attributes)
+        completion_tokens = self._extract_completion_tokens(attributes)
+        total_tokens = prompt_tokens + completion_tokens
         if total_tokens > 0:
             model = (
                 attributes.get(SpanAttributes.LLM_RESPONSE_MODEL) or