lucidicai 2.1.0__tar.gz → 2.1.2__tar.gz

{lucidicai-2.1.0 → lucidicai-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lucidicai
-Version: 2.1.0
+Version: 2.1.2
 Summary: Lucidic AI Python SDK
 Author: Andy Liang
 Author-email: andy@lucidic.ai

{lucidicai-2.1.0 → lucidicai-2.1.2}/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-2.1.0 → lucidicai-2.1.2}/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-2.1.2/lucidicai/sdk/context.py

@@ -0,0 +1,273 @@
+"""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
+OpenTelemetry spans can be deterministically attributed to the correct
+session under concurrency.
+"""
+
+from contextlib import contextmanager, asynccontextmanager
+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
+current_session_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "lucidic.session_id", default=None
+)
+
+
+# NEW: Context variable for parent event nesting
+current_parent_event_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "lucidic.parent_event_id", default=None
+)
+
+
+def set_active_session(session_id: Optional[str]) -> None:
+    """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.
+
+    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.
+
+    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)
+
+
+# NEW: Parent event context managers
+@contextmanager
+def event_context(event_id: str) -> Iterator[None]:
+    token = current_parent_event_id.set(event_id)
+    try:
+        yield
+    finally:
+        current_parent_event_id.reset(token)
+
+
+@asynccontextmanager
+async def event_context_async(event_id: str) -> AsyncIterator[None]:
+    token = current_parent_event_id.set(event_id)
+    try:
+        yield
+    finally:
+        current_parent_event_id.reset(token)
+
+
+@contextmanager
+def session(**init_params) -> Iterator[None]:
+    """All-in-one context manager: init → bind → yield → clear → end.
+
+    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)
+    init_params = dict(init_params)
+    init_params['auto_end'] = False
+
+    if os.getenv('LUCIDIC_DEBUG', 'False') == 'True' and user_auto_end is not None:
+        logging.getLogger('Lucidic').warning('session(...) ignores auto_end and will end the session at context exit')
+
+    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:
+            # 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
+
+
+@asynccontextmanager
+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)
+    init_params['auto_end'] = False
+
+    if os.getenv('LUCIDIC_DEBUG', 'False') == 'True' and user_auto_end is not None:
+        logging.getLogger('Lucidic').warning('session_async(...) ignores auto_end and will end the session at context exit')
+
+    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:
+            # 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
+
+
+def run_session(fn: Callable[..., Any], *fn_args: Any, init_params: Optional[Dict[str, Any]] = None, **fn_kwargs: Any) -> Any:
+    """Run a callable within a full Lucidic session lifecycle context."""
+    with session(**(init_params or {})):
+        return fn(*fn_args, **fn_kwargs)
+
+
+def run_in_session(session_id: str, fn: Callable[..., Any], *fn_args: Any, **fn_kwargs: Any) -> Any:
+    """Run a callable with a bound session id. Does not end the session."""
+    with bind_session(session_id):
+        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-2.1.0 → lucidicai-2.1.2}/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-2.1.0 → lucidicai-2.1.2}/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-2.1.0 → lucidicai-2.1.2}/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