lucidicai 2.1.3__py3-none-any.whl → 3.1.0__py3-none-any.whl

lucidicai/core/config.py

@@ -16,22 +16,71 @@ class Environment(Enum):
     DEBUG = "debug"
 
 
+class Region(Enum):
+    """Supported deployment regions"""
+    US = "us"
+    INDIA = "india"
+
+    @classmethod
+    def from_string(cls, value: str) -> 'Region':
+        """Convert string to Region enum, case-insensitive."""
+        value_lower = value.lower().strip()
+        for region in cls:
+            if region.value == value_lower:
+                return region
+        valid_regions = [r.value for r in cls]
+        raise ValueError(f"Invalid region '{value}'. Valid regions: {', '.join(valid_regions)}")
+
+
+# Region to URL mapping
+REGION_URLS: Dict[str, str] = {
+    Region.US: "https://backend.lucidic.ai/api",
+    Region.INDIA: "https://in.backend.lucidic.ai/api",
+}
+DEFAULT_REGION = Region.US
+DEBUG_URL = "http://localhost:8000/api"
+
+
 @dataclass
 class NetworkConfig:
     """Network and connection settings"""
     base_url: str = "https://backend.lucidic.ai/api"
+    region: Optional[Region] = None
     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"
+    def from_env(cls, region: Optional[str] = None, debug: bool = False) -> 'NetworkConfig':
+        """Load network configuration from environment variables.
+
+        Priority: debug > region argument > LUCIDIC_REGION env var > default
+
+        Args:
+            region: Region string override (e.g., "us", "india")
+            debug: If True, use localhost URL regardless of region
+        """
+        # If debug mode, use localhost (ignores region)
+        if debug:
+            return cls(
+                base_url=DEBUG_URL,
+                region=None,
+                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"))
+            )
+
+        # Resolve region: argument > env var > default
+        region_str = region or os.getenv("LUCIDIC_REGION")
+        resolved_region = Region.from_string(region_str) if region_str else DEFAULT_REGION
+
         return cls(
-            base_url="http://localhost:8000/api" if debug else "https://backend.lucidic.ai/api",
+            base_url=REGION_URLS[resolved_region],
+            region=resolved_region,
             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")),
@@ -40,31 +89,6 @@ class NetworkConfig:
         )
 
 
-@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"""
@@ -110,9 +134,11 @@ class SDKConfig:
     auto_end: bool = True
     production_monitoring: bool = False
     
+    # Blob threshold for large event payloads (default 64KB)
+    blob_threshold: int = 65536
+    
     # 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)
     
@@ -121,26 +147,31 @@ class SDKConfig:
     debug: bool = False
     
     @classmethod
-    def from_env(cls, **overrides) -> 'SDKConfig':
-        """Create configuration from environment variables with optional overrides"""
+    def from_env(cls, region: Optional[str] = None, **overrides) -> 'SDKConfig':
+        """Create configuration from environment variables with optional overrides.
+
+        Args:
+            region: Region string (e.g., "us", "india"). Priority: arg > env var > default
+            **overrides: Additional configuration 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(),
+            blob_threshold=int(os.getenv("LUCIDIC_BLOB_THRESHOLD", "65536")),
+            network=NetworkConfig.from_env(region=region, debug=debug),
             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
@@ -165,11 +196,8 @@ class SDKConfig:
         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")
+        if self.blob_threshold < 1024:
+            errors.append("Blob threshold must be at least 1024 bytes")
         
         return errors
     
@@ -181,17 +209,14 @@ class SDKConfig:
             "environment": self.environment.value,
             "debug": self.debug,
             "auto_end": self.auto_end,
+            "blob_threshold": self.blob_threshold,
             "network": {
                 "base_url": self.network.base_url,
+                "region": self.network.region.value if self.network.region else None,
                 "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

lucidicai/core/errors.py

@@ -37,9 +37,9 @@ class FeatureFlagError(LucidicError):
 
 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
+    from ..sdk.event import create_event
+    from ..sdk.init import get_session_id
+    from ..sdk.context import current_parent_event_id
 
     def handle_exception(exc_type, exc_value, exc_traceback):
         try:

lucidicai/sdk/bound_decorators.py

@@ -0,0 +1,321 @@
+"""Client-bound decorators for the Lucidic SDK.
+
+These decorators are bound to a specific LucidicAI client instance and only
+track events when the current context belongs to that client.
+"""
+
+import functools
+import inspect
+import json
+import traceback
+from datetime import datetime
+import uuid
+from typing import Any, Callable, Optional, TypeVar, TYPE_CHECKING
+from collections.abc import Iterable
+
+from .context import (
+    current_session_id,
+    current_client,
+    current_parent_event_id,
+    event_context,
+    event_context_async,
+)
+from ..utils.logger import debug, error as log_error, truncate_id
+
+if TYPE_CHECKING:
+    from ..client import LucidicAI
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _serialize(value: Any) -> Any:
+    """Serialize a value to JSON-compatible format."""
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, dict):
+        return {k: _serialize(v) for k, v in value.items()}
+    if isinstance(value, Iterable) and not isinstance(value, (str, bytes)):
+        return [_serialize(v) for v in value]
+    try:
+        return json.loads(json.dumps(value, default=str))
+    except Exception:
+        return str(value)
+
+
+def create_bound_event_decorator(
+    client: "LucidicAI", **decorator_kwargs
+) -> Callable[[F], F]:
+    """Create an event decorator bound to a specific client.
+
+    This decorator only tracks events when:
+    1. The current context has this client active
+    2. There is an active session for this client
+
+    Args:
+        client: The LucidicAI client to bind this decorator to
+        **decorator_kwargs: Additional keyword arguments passed to the event
+
+    Returns:
+        A decorator function that wraps the target function
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            # Check if this client is active in the current context
+            active_client = current_client.get(None)
+            if active_client is not client:
+                # Not our client - just execute the function
+                return func(*args, **kwargs)
+
+            session_id = current_session_id.get(None)
+            if not session_id:
+                # No active session - just execute the function
+                return func(*args, **kwargs)
+
+            # Build arguments snapshot
+            sig = inspect.signature(func)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            args_dict = {
+                name: _serialize(val) for name, val in bound.arguments.items()
+            }
+
+            parent_id = current_parent_event_id.get(None)
+            pre_event_id = str(uuid.uuid4())
+            debug(
+                f"[Decorator] Starting {func.__name__} with event ID {truncate_id(pre_event_id)}, parent: {truncate_id(parent_id)}"
+            )
+            start_time = datetime.now().astimezone()
+            result = None
+            error: Optional[BaseException] = None
+
+            try:
+                with event_context(pre_event_id):
+                    # Also inject into OpenTelemetry context for instrumentors
+                    from ..telemetry.context_bridge import inject_lucidic_context
+                    from opentelemetry import context as otel_context
+
+                    otel_ctx = inject_lucidic_context()
+                    token = otel_context.attach(otel_ctx)
+                    try:
+                        result = func(*args, **kwargs)
+                    finally:
+                        otel_context.detach(token)
+                return result
+            except Exception as e:
+                error = e
+                log_error(f"[Decorator] {func.__name__} raised exception: {e}")
+                raise
+            finally:
+                try:
+                    # Store error as return value with type information
+                    if error:
+                        return_val = {
+                            "error": str(error),
+                            "error_type": type(error).__name__,
+                        }
+
+                        # Create a separate error_traceback event for the exception
+                        try:
+                            _emit_event_to_client(
+                                client,
+                                session_id,
+                                type="error_traceback",
+                                error=str(error),
+                                traceback=traceback.format_exc(),
+                                parent_event_id=pre_event_id,
+                            )
+                            debug(
+                                f"[Decorator] Created error_traceback event for {func.__name__}"
+                            )
+                        except Exception as e:
+                            debug(
+                                f"[Decorator] Failed to create error_traceback event: {e}"
+                            )
+                    else:
+                        return_val = _serialize(result)
+
+                    _emit_event_to_client(
+                        client,
+                        session_id,
+                        type="function_call",
+                        event_id=pre_event_id,
+                        parent_event_id=parent_id,
+                        function_name=func.__name__,
+                        arguments=args_dict,
+                        return_value=return_val,
+                        error=str(error) if error else None,
+                        duration=(datetime.now().astimezone() - start_time).total_seconds(),
+                        **decorator_kwargs,
+                    )
+                    debug(
+                        f"[Decorator] Created function_call event for {func.__name__}"
+                    )
+                except Exception as e:
+                    log_error(f"[Decorator] Failed to create function_call event: {e}")
+
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            # Check if this client is active in the current context
+            active_client = current_client.get(None)
+            if active_client is not client:
+                # Not our client - just execute the function
+                return await func(*args, **kwargs)
+
+            session_id = current_session_id.get(None)
+            if not session_id:
+                # No active session - just execute the function
+                return await func(*args, **kwargs)
+
+            # Build arguments snapshot
+            sig = inspect.signature(func)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            args_dict = {
+                name: _serialize(val) for name, val in bound.arguments.items()
+            }
+
+            parent_id = current_parent_event_id.get(None)
+            pre_event_id = str(uuid.uuid4())
+            debug(
+                f"[Decorator] Starting {func.__name__} with event ID {truncate_id(pre_event_id)}, parent: {truncate_id(parent_id)}"
+            )
+            start_time = datetime.now().astimezone()
+            result = None
+            error: Optional[BaseException] = None
+
+            try:
+                async with event_context_async(pre_event_id):
+                    # Also inject into OpenTelemetry context for instrumentors
+                    from ..telemetry.context_bridge import inject_lucidic_context
+                    from opentelemetry import context as otel_context
+
+                    otel_ctx = inject_lucidic_context()
+                    token = otel_context.attach(otel_ctx)
+                    try:
+                        result = await func(*args, **kwargs)
+                    finally:
+                        otel_context.detach(token)
+                return result
+            except Exception as e:
+                error = e
+                log_error(f"[Decorator] {func.__name__} raised exception: {e}")
+                raise
+            finally:
+                try:
+                    # Store error as return value with type information
+                    if error:
+                        return_val = {
+                            "error": str(error),
+                            "error_type": type(error).__name__,
+                        }
+
+                        # Create a separate error_traceback event for the exception
+                        try:
+                            await _aemit_event_to_client(
+                                client,
+                                session_id,
+                                type="error_traceback",
+                                error=str(error),
+                                traceback=traceback.format_exc(),
+                                parent_event_id=pre_event_id,
+                            )
+                            debug(
+                                f"[Decorator] Created error_traceback event for {func.__name__}"
+                            )
+                        except Exception as e:
+                            debug(
+                                f"[Decorator] Failed to create error_traceback event: {e}"
+                            )
+                    else:
+                        return_val = _serialize(result)
+
+                    await _aemit_event_to_client(
+                        client,
+                        session_id,
+                        type="function_call",
+                        event_id=pre_event_id,
+                        parent_event_id=parent_id,
+                        function_name=func.__name__,
+                        arguments=args_dict,
+                        return_value=return_val,
+                        error=str(error) if error else None,
+                        duration=(datetime.now().astimezone() - start_time).total_seconds(),
+                        **decorator_kwargs,
+                    )
+                    debug(
+                        f"[Decorator] Created function_call event for {func.__name__}"
+                    )
+                except Exception as e:
+                    log_error(f"[Decorator] Failed to create function_call event: {e}")
+
+        if inspect.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore
+        return sync_wrapper  # type: ignore
+
+    return decorator
+
+
+def _emit_event_to_client(
+    client: "LucidicAI",
+    session_id: str,
+    type: str,
+    **event_data,
+) -> Optional[str]:
+    """Emit an event using the client's event resource.
+
+    Args:
+        client: The LucidicAI client
+        session_id: The session ID to associate the event with
+        type: The event type (e.g., "function_call", "error_traceback")
+        **event_data: Additional event data
+
+    Returns:
+        The event ID if created successfully, None otherwise
+    """
+    try:
+        event_payload = {
+            "type": type,
+            "session_id": session_id,
+            **event_data,
+        }
+
+        # Use the client's event resource
+        response = client._resources["events"].create_event(event_payload)
+        return response.get("event_id") if response else None
+    except Exception as e:
+        debug(f"[Decorator] Failed to emit event: {e}")
+        return None
+
+
+async def _aemit_event_to_client(
+    client: "LucidicAI",
+    session_id: str,
+    type: str,
+    **event_data,
+) -> Optional[str]:
+    """Emit an event using the client's event resource (async).
+
+    Args:
+        client: The LucidicAI client
+        session_id: The session ID to associate the event with
+        type: The event type (e.g., "function_call", "error_traceback")
+        **event_data: Additional event data
+
+    Returns:
+        The event ID if created successfully, None otherwise
+    """
+    try:
+        event_payload = {
+            "type": type,
+            "session_id": session_id,
+            **event_data,
+        }
+
+        # Use the client's event resource
+        response = await client._resources["events"].acreate_event(event_payload)
+        return response.get("event_id") if response else None
+    except Exception as e:
+        debug(f"[Decorator] Failed to emit async event: {e}")
+        return None

lucidicai/sdk/context.py

@@ -8,11 +8,14 @@ session under concurrency.
 
 from contextlib import contextmanager, asynccontextmanager
 import contextvars
-from typing import Optional, Iterator, AsyncIterator, Callable, Any, Dict
+from typing import Optional, Iterator, AsyncIterator, Callable, Any, Dict, TYPE_CHECKING
 import logging
 import os
 import threading
 
+if TYPE_CHECKING:
+    from ..client import LucidicAI
+
 
 # Context variable for the active Lucidic session id
 current_session_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
@@ -20,12 +23,27 @@ current_session_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextV
 )
 
 
-# NEW: Context variable for parent event nesting
+# Context variable for parent event nesting
 current_parent_event_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
     "lucidic.parent_event_id", default=None
 )
 
 
+# Context variable for the active client (for multi-client support)
+current_client: contextvars.ContextVar[Optional["LucidicAI"]] = contextvars.ContextVar(
+    "lucidic.client", default=None
+)
+
+
+def get_active_client() -> Optional["LucidicAI"]:
+    """Get the currently active LucidicAI client from context.
+
+    Returns:
+        The active client, or None if no client is bound to the current context.
+    """
+    return current_client.get(None)
+
+
 def set_active_session(session_id: Optional[str]) -> None:
     """Bind the given session id to the current execution context.