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

lucidicai/core/config.py

@@ -0,0 +1,223 @@
+"""Centralized configuration management for Lucidic SDK.
+
+This module provides a single source of truth for all SDK configuration,
+including environment variables, defaults, and runtime settings.
+"""
+import os
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, List
+from enum import Enum
+
+
+class Environment(Enum):
+    """SDK environment modes"""
+    PRODUCTION = "production"
+    DEVELOPMENT = "development"
+    DEBUG = "debug"
+
+
+@dataclass
+class NetworkConfig:
+    """Network and connection settings"""
+    base_url: str = "https://backend.lucidic.ai/api"
+    timeout: int = 30
+    max_retries: int = 3
+    backoff_factor: float = 0.5
+    connection_pool_size: int = 20
+    connection_pool_maxsize: int = 100
+    
+    @classmethod
+    def from_env(cls) -> '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://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")),
+            connection_pool_size=int(os.getenv("LUCIDIC_CONNECTION_POOL_SIZE", "20")),
+            connection_pool_maxsize=int(os.getenv("LUCIDIC_CONNECTION_POOL_MAXSIZE", "100"))
+        )
+
+
+@dataclass
+class EventQueueConfig:
+    """Event queue processing settings"""
+    max_queue_size: int = 100000
+    flush_interval_ms: int = 100
+    flush_at_count: int = 100
+    blob_threshold: int = 65536
+    daemon_mode: bool = True
+    max_parallel_workers: int = 10
+    retry_failed: bool = True
+    
+    @classmethod
+    def from_env(cls) -> 'EventQueueConfig':
+        """Load event queue configuration from environment variables"""
+        return cls(
+            max_queue_size=int(os.getenv("LUCIDIC_MAX_QUEUE_SIZE", "100000")),
+            flush_interval_ms=int(os.getenv("LUCIDIC_FLUSH_INTERVAL", "1000")),
+            flush_at_count=int(os.getenv("LUCIDIC_FLUSH_AT", "50")),
+            blob_threshold=int(os.getenv("LUCIDIC_BLOB_THRESHOLD", "65536")),
+            daemon_mode=os.getenv("LUCIDIC_DAEMON_QUEUE", "true").lower() == "true",
+            max_parallel_workers=int(os.getenv("LUCIDIC_MAX_PARALLEL", "10")),
+            retry_failed=os.getenv("LUCIDIC_RETRY_FAILED", "true").lower() == "true"
+        )
+
+
+@dataclass
+class ErrorHandlingConfig:
+    """Error handling and suppression settings"""
+    suppress_errors: bool = True
+    cleanup_on_error: bool = True
+    log_suppressed: bool = True
+    capture_uncaught: bool = True
+    
+    @classmethod
+    def from_env(cls) -> 'ErrorHandlingConfig':
+        """Load error handling configuration from environment variables"""
+        return cls(
+            suppress_errors=os.getenv("LUCIDIC_SUPPRESS_ERRORS", "true").lower() == "true",
+            cleanup_on_error=os.getenv("LUCIDIC_CLEANUP_ON_ERROR", "true").lower() == "true",
+            log_suppressed=os.getenv("LUCIDIC_LOG_SUPPRESSED", "true").lower() == "true",
+            capture_uncaught=os.getenv("LUCIDIC_CAPTURE_UNCAUGHT", "true").lower() == "true"
+        )
+
+
+@dataclass
+class TelemetryConfig:
+    """Telemetry and instrumentation settings"""
+    providers: List[str] = field(default_factory=list)
+    verbose: bool = False
+    
+    @classmethod
+    def from_env(cls) -> 'TelemetryConfig':
+        """Load telemetry configuration from environment variables"""
+        return cls(
+            providers=[],  # Set during initialization
+            verbose=os.getenv("LUCIDIC_VERBOSE", "False").lower() == "true"
+        )
+
+
+@dataclass
+class SDKConfig:
+    """Main SDK configuration container"""
+    # Required settings
+    api_key: Optional[str] = None
+    agent_id: Optional[str] = None
+    
+    # Feature flags
+    auto_end: bool = True
+    production_monitoring: bool = False
+    
+    # Sub-configurations
+    network: NetworkConfig = field(default_factory=NetworkConfig)
+    event_queue: EventQueueConfig = field(default_factory=EventQueueConfig)
+    error_handling: ErrorHandlingConfig = field(default_factory=ErrorHandlingConfig)
+    telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)
+    
+    # Runtime settings
+    environment: Environment = Environment.PRODUCTION
+    debug: bool = False
+    
+    @classmethod
+    def from_env(cls, **overrides) -> 'SDKConfig':
+        """Create configuration from environment variables with optional overrides"""
+        from dotenv import load_dotenv
+        load_dotenv()
+        
+        debug = os.getenv("LUCIDIC_DEBUG", "False").lower() == "true"
+        
+        config = cls(
+            api_key=os.getenv("LUCIDIC_API_KEY"),
+            agent_id=os.getenv("LUCIDIC_AGENT_ID"),
+            auto_end=os.getenv("LUCIDIC_AUTO_END", "true").lower() == "true",
+            production_monitoring=False,
+            network=NetworkConfig.from_env(),
+            event_queue=EventQueueConfig.from_env(),
+            error_handling=ErrorHandlingConfig.from_env(),
+            telemetry=TelemetryConfig.from_env(),
+            environment=Environment.DEBUG if debug else Environment.PRODUCTION,
+            debug=debug
+        )
+        
+        # Apply any overrides
+        config.update(**overrides)
+        return config
+    
+    def update(self, **kwargs):
+        """Update configuration with new values"""
+        for key, value in kwargs.items():
+            # Only update if value is not None (to preserve env defaults)
+            if value is not None:
+                if hasattr(self, key):
+                    setattr(self, key, value)
+                elif key == "providers" and hasattr(self.telemetry, "providers"):
+                    self.telemetry.providers = value
+    
+    def validate(self) -> List[str]:
+        """Validate configuration and return list of errors"""
+        errors = []
+        
+        if not self.api_key:
+            errors.append("API key is required (LUCIDIC_API_KEY)")
+        
+        if not self.agent_id:
+            errors.append("Agent ID is required (LUCIDIC_AGENT_ID)")
+        
+        if self.event_queue.max_parallel_workers < 1:
+            errors.append("Max parallel workers must be at least 1")
+        
+        if self.event_queue.flush_interval_ms < 10:
+            errors.append("Flush interval must be at least 10ms")
+        
+        return errors
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert configuration to dictionary"""
+        return {
+            "api_key": self.api_key[:8] + "..." if self.api_key else None,
+            "agent_id": self.agent_id,
+            "environment": self.environment.value,
+            "debug": self.debug,
+            "auto_end": self.auto_end,
+            "network": {
+                "base_url": self.network.base_url,
+                "timeout": self.network.timeout,
+                "max_retries": self.network.max_retries,
+                "connection_pool_size": self.network.connection_pool_size
+            },
+            "event_queue": {
+                "max_workers": self.event_queue.max_parallel_workers,
+                "flush_interval_ms": self.event_queue.flush_interval_ms,
+                "flush_at_count": self.event_queue.flush_at_count
+            },
+            "error_handling": {
+                "suppress": self.error_handling.suppress_errors,
+                "cleanup": self.error_handling.cleanup_on_error
+            }
+        }
+
+
+# Global configuration instance
+_config: Optional[SDKConfig] = None
+
+
+def get_config() -> SDKConfig:
+    """Get the current SDK configuration"""
+    global _config
+    if _config is None:
+        _config = SDKConfig.from_env()
+    return _config
+
+
+def set_config(config: SDKConfig):
+    """Set the SDK configuration"""
+    global _config
+    _config = config
+
+
+def reset_config():
+    """Reset configuration to defaults"""
+    global _config
+    _config = None

lucidicai/core/errors.py

@@ -0,0 +1,60 @@
+from typing import Optional
+import sys
+import traceback
+
+
+class LucidicError(Exception):
+    """Base exception for all Lucidic SDK errors"""
+    pass
+
+
+class APIKeyVerificationError(LucidicError):
+    """Exception for API key verification errors"""
+    def __init__(self, message):
+        super().__init__(f"Could not verify Lucidic API key: {message}")
+
+class LucidicNotInitializedError(LucidicError):
+    """Exception for calling Lucidic functions before Lucidic Client is initialized (lai.init())"""
+    def __init__(self):
+        super().__init__("Client is not initialized. Make sure to call lai.init() to initialize the client before calling other functions.")
+
+class PromptError(LucidicError):
+    "Exception for errors related to prompt management"
+    def __init__(self, message: str):
+        super().__init__(f"Error getting Lucidic prompt: {message}")
+
+class InvalidOperationError(LucidicError):
+    "Exception for errors resulting from attempting an invalid operation"
+    def __init__(self, message: str):
+        super().__init__(f"An invalid Lucidic operation was attempted: {message}")
+
+
+class FeatureFlagError(LucidicError):
+    """Exception for feature flag fetch failures"""
+    def __init__(self, message: str):
+        super().__init__(f"Failed to fetch feature flag: {message}")
+
+
+def install_error_handler():
+    """Install global handler to create ERROR_TRACEBACK events for uncaught exceptions."""
+    from .sdk.event import create_event
+    from .sdk.init import get_session_id
+    from .context import current_parent_event_id
+
+    def handle_exception(exc_type, exc_value, exc_traceback):
+        try:
+            if get_session_id():
+                tb = ''.join(traceback.format_exception(exc_type, exc_value, exc_traceback))
+                create_event(
+                    type="error_traceback",
+                    error=str(exc_value),
+                    traceback=tb
+                )
+        except Exception:
+            pass
+        try:
+            sys.__excepthook__(exc_type, exc_value, exc_traceback)
+        except Exception:
+            pass
+
+    sys.excepthook = handle_exception

lucidicai/core/types.py

@@ -0,0 +1,35 @@
+"""Type definitions for the Lucidic SDK."""
+from enum import Enum
+from typing import Literal
+
+
+class EventType(Enum):
+    """Supported event types."""
+    LLM_GENERATION = "llm_generation"
+    FUNCTION_CALL = "function_call"
+    ERROR_TRACEBACK = "error_traceback"
+    GENERIC = "generic"
+
+
+# Provider type literals
+ProviderType = Literal[
+    "openai",
+    "anthropic",
+    "langchain",
+    "pydantic_ai",
+    "openai_agents",
+    "litellm",
+    "bedrock",
+    "aws_bedrock",
+    "amazon_bedrock",
+    "vertexai",
+    "vertex_ai",
+    "google",
+    "google_generativeai",
+    "cohere",
+    "groq",
+]
+
+
+# Deprecated type aliases (for backward compatibility)
+StepType = EventType  # Steps are now events

lucidicai/sdk/__init__.py

@@ -0,0 +1 @@
+"""SDK module for Lucidic AI."""

lucidicai/sdk/context.py

@@ -0,0 +1,231 @@
+"""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:
+            # 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:
+            # 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()
+
+