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

lucidicai/dataset.py

@@ -0,0 +1,112 @@
+import os
+import logging
+from typing import Optional, Dict, List, Any
+from dotenv import load_dotenv
+
+from .client import Client
+from .errors import APIKeyVerificationError
+
+logger = logging.getLogger("Lucidic")
+
+
+def get_dataset(
+    dataset_id: str,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Get a dataset by ID with all its items.
+    
+    Args:
+        dataset_id: The ID of the dataset to retrieve (required).
+        api_key: API key for authentication. If not provided, will use the LUCIDIC_API_KEY environment variable.
+        agent_id: Agent ID. If not provided, will use the LUCIDIC_AGENT_ID environment variable.
+    
+    Returns:
+        A dictionary containing the dataset information including:
+        - dataset_id: The dataset ID
+        - name: Dataset name
+        - description: Dataset description
+        - tags: List of tags
+        - created_at: Creation timestamp
+        - updated_at: Last update timestamp
+        - num_items: Number of items in the dataset
+        - items: List of dataset items
+    
+    Raises:
+        APIKeyVerificationError: If API key or agent ID is missing or invalid.
+        ValueError: If dataset_id is not provided.
+    """
+    load_dotenv()
+    
+    # Validation
+    if not dataset_id:
+        raise ValueError("Dataset ID is required")
+    
+    # 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 into get_dataset() 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 into get_dataset() or set the LUCIDIC_AGENT_ID environment variable."
+            )
+    
+    # Get current client or create a new one
+    client = Client()
+    # If not yet initialized or still the NullClient -> create a real client
+    if not getattr(client, 'initialized', False):
+        client = Client(api_key=api_key, agent_id=agent_id)
+    else:
+        # Already initialized, check if we need to update credentials
+        if api_key is not None and agent_id is not None and (api_key != client.api_key or agent_id != client.agent_id):
+            client.set_api_key(api_key)
+            client.agent_id = agent_id
+    
+    # Make request to get dataset
+    response = client.make_request(
+        'getdataset',
+        'GET',
+        {'dataset_id': dataset_id}
+    )
+    
+    logger.info(f"Retrieved dataset {dataset_id} with {response.get('num_items', 0)} items")
+    return response
+
+
+def get_dataset_items(
+    dataset_id: str,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """
+    Convenience function to get just the items from a dataset.
+    
+    Args:
+        dataset_id: The ID of the dataset to retrieve items from (required).
+        api_key: API key for authentication. If not provided, will use the LUCIDIC_API_KEY environment variable.
+        agent_id: Agent ID. If not provided, will use the LUCIDIC_AGENT_ID environment variable.
+    
+    Returns:
+        A list of dataset items, where each item contains:
+        - dataset_item_id: The item ID
+        - name: Item name
+        - description: Item description
+        - tags: List of tags
+        - input: Input data for the item
+        - expected_output: Expected output data
+        - metadata: Additional metadata
+        - created_at: Creation timestamp
+    
+    Raises:
+        APIKeyVerificationError: If API key or agent ID is missing or invalid.
+        ValueError: If dataset_id is not provided.
+    """
+    dataset = get_dataset(dataset_id, api_key, agent_id)
+    return dataset.get('items', [])

lucidicai/decorators.py

@@ -1,375 +1,146 @@
-"""Decorators for the Lucidic SDK to simplify step and event tracking."""
+"""Decorators for the Lucidic SDK to create typed, nested events."""
 import functools
-import contextvars
 import inspect
 import json
 import logging
-from typing import Any, Callable, Optional, TypeVar, Union
+from datetime import datetime
+import uuid
+from typing import Any, Callable, Optional, TypeVar
 from collections.abc import Iterable
 
 from .client import Client
 from .errors import LucidicNotInitializedError
+from .context import current_parent_event_id, event_context, event_context_async
 
 logger = logging.getLogger("Lucidic")
 
 F = TypeVar('F', bound=Callable[..., Any])
 
-# Create context variables to store the current step and event
-_current_step = contextvars.ContextVar("current_step", default=None)
-_current_event = contextvars.ContextVar("current_event", default=None)
 
-def get_decorator_step():
-    return _current_step.get()
+def _serialize(value: Any):
+    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 get_decorator_event():
-    return _current_event.get()
 
+def event(**decorator_kwargs) -> Callable[[F], F]:
+    """Universal decorator creating FUNCTION_CALL events with nesting and error capture."""
 
-def step(
-    state: Optional[str] = None,
-    action: Optional[str] = None,
-    goal: Optional[str] = None,
-    screenshot_path: Optional[str] = None,
-    eval_score: Optional[float] = None,
-    eval_description: Optional[str] = None
-) -> Callable[[F], F]:
-    """
-    Decorator that wraps a function with step tracking.
-    
-    The decorated function will be wrapped with create_step() at the start
-    and end_step() at the end, ensuring proper cleanup even on exceptions.
-    
-    Args:
-        state: State description for the step
-        action: Action description for the step  
-        goal: Goal description for the step
-        eval_score: Evaluation score for the step
-        eval_description: Evaluation description for the step
-        
-    Example:
-        @lai.step(
-            state="Processing user input",
-            action="Validate and parse request",
-            goal="Extract intent from user message"
-        )
-        def process_user_input(message: str) -> dict:
-            # Function logic here
-            return parsed_intent
-    """
     def decorator(func: F) -> F:
         @functools.wraps(func)
         def sync_wrapper(*args, **kwargs):
-            # Check if SDK is initialized
             try:
                 client = Client()
                 if not client.session:
-                    # No active session, run function normally
-                    logger.warning("No active session, running function normally")
                     return func(*args, **kwargs)
-            except LucidicNotInitializedError:
-                # SDK not initialized, run function normally
-                logger.warning("Lucidic not initialized, running function normally")
+            except (LucidicNotInitializedError, AttributeError):
                 return func(*args, **kwargs)
-            
-            # Create the step
-            step_params = {
-                'state': state,
-                'action': action,
-                'goal': goal,
-                'screenshot_path': screenshot_path,
-                'eval_score': eval_score,
-                'eval_description': eval_description
-            }
-            # Remove None values
-            step_params = {k: v for k, v in step_params.items() if v is not None}
-            
-            # Import here to avoid circular imports
-            from . import create_step, end_step
-            step_id = create_step(**step_params)
-            tok = _current_step.set(step_id)
-            
+
+            # 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())
+            start_time = datetime.now().astimezone()
+            result = None
+            error: Optional[BaseException] = None
+
             try:
-                # Execute the wrapped function
-                result = func(*args, **kwargs)
-                # End step successfully
-                end_step(step_id=step_id)
-                _current_step.reset(tok)
+                with event_context(pre_event_id):
+                    result = func(*args, **kwargs)
                 return result
             except Exception as e:
-                # End step with error indication
+                error = e
+                raise
+            finally:
                 try:
-                    end_step(
-                        step_id=step_id,
-                        eval_score=0.0,
-                        eval_description=f"Step failed with error: {str(e)}"
+                    # Store error as return value with type information
+                    if error:
+                        return_val = {
+                            "error": str(error),
+                            "error_type": type(error).__name__
+                        }
+                    else:
+                        return_val = _serialize(result)
+                    
+                    client.create_event(
+                        type="function_call",
+                        event_id=pre_event_id,
+                        function_name=func.__name__,
+                        arguments=args_dict,
+                        return_value=return_val,
+                        error=str(error) if error else None,
+                        parent_event_id=parent_id,
+                        duration=(datetime.now().astimezone() - start_time).total_seconds(),
+                        **decorator_kwargs
                     )
-                    _current_step.reset(tok)
                 except Exception:
-                    # If end_step fails, just log it
-                    logger.error(f"Failed to end step {step_id} after error")
-                raise
-        
+                    pass
+
         @functools.wraps(func)
         async def async_wrapper(*args, **kwargs):
-            # Check if SDK is initialized
             try:
                 client = Client()
                 if not client.session:
-                    # No active session, run function normally
-                    logger.warning("No active session, running function normally")
                     return await func(*args, **kwargs)
-            except LucidicNotInitializedError:
-                # SDK not initialized, run function normally
-                logger.warning("Lucidic not initialized, running function normally")
+            except (LucidicNotInitializedError, AttributeError):
                 return await func(*args, **kwargs)
-            
-            # Create the step
-            step_params = {
-                'state': state,
-                'action': action,
-                'goal': goal,
-                'screenshot_path': screenshot_path,
-                'eval_score': eval_score,
-                'eval_description': eval_description
-            }
-            # Remove None values
-            step_params = {k: v for k, v in step_params.items() if v is not None}
-            
-            # Import here to avoid circular imports
-            from . import create_step, end_step
-            
-            step_id = create_step(**step_params)
-            tok = _current_step.set(step_id)
-            try:
-                # Execute the wrapped function
-                result = await func(*args, **kwargs)
-                # End step successfully
-                end_step(step_id=step_id)
-                _current_step.reset(tok)
-                return result
-            except Exception as e:
-                # End step with error indication
-                try:
-                    end_step(
-                        step_id=step_id,
-                        eval_score=0.0,
-                        eval_description=f"Step failed with error: {str(e)}"
-                    )
-                    _current_step.reset(tok)
-                except Exception:
-                    # If end_step fails, just log it
-                    logger.error(f"Failed to end step {step_id} after error")
-                raise
-        
-        # Return appropriate wrapper based on function type
-        if inspect.iscoroutinefunction(func):
-            return async_wrapper
-        else:
-            return sync_wrapper
-    
-    return decorator
 
-
-### -- TODO -- Updating even within function causes function result to not be recorded.
-def event(
-    description: Optional[str] = None,
-    result: Optional[str] = None,
-    model: Optional[str] = None,
-    cost_added: Optional[float] = 0
-) -> Callable[[F], F]:
-    """
-    Decorator that creates an event for a function call.
-    
-    The decorated function will create an event that captures:
-    - Function inputs (as string representation) if description not provided
-    - Function output (as string representation) if result not provided
-    
-    LLM calls within the function will create their own events as normal.
-    
-    Args:
-        description: Custom description for the event. If not provided,
-                    will use string representation of function inputs
-        result: Custom result for the event. If not provided,
-                will use string representation of function output
-        model: Model name if this function represents a model call (default: None)
-        cost_added: Cost to add for this event (default: 0)
-        
-    Example:
-        @lai.event(description="Parse user query", model="custom-parser")
-        def parse_query(query: str) -> dict:
-            # Function logic here
-            return {"intent": "search", "query": query}
-    """
-    def decorator(func: F) -> F:
-        @functools.wraps(func)
-        def sync_wrapper(*args, **kwargs):
-            # Check if SDK is initialized
-            try:
-                client = Client()
-                if not client.session:
-                    # No active session, run function normally
-                    logger.warning("No active session, running function normally")
-                    return func(*args, **kwargs)
-            except (LucidicNotInitializedError, AttributeError):
-                # SDK not initialized or no session, run function normally
-                logger.warning("Lucidic not initialized, running function normally")
-                return func(*args, **kwargs)
-            
-            # Import here to avoid circular imports
-            from . import create_event, end_event
-            
-            # Build event description from inputs if not provided
-            event_desc = description
-            function_name = func.__name__
-            
-            # Get function signature
             sig = inspect.signature(func)
-            bound_args = sig.bind(*args, **kwargs)
-            bound_args.apply_defaults()
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            args_dict = {name: _serialize(val) for name, val in bound.arguments.items()}
 
-            def serialize(value):
-                if isinstance(value, str):
-                    return value
-                if isinstance(value, int):
-                    return value
-                if isinstance(value, float):
-                    return value
-                if isinstance(value, bool):
-                    return value
-                if isinstance(value, dict):
-                    return {k: serialize(v) for k, v in value.items()}
-                if isinstance(value, Iterable):
-                    return [serialize(v) for v in value]
-                return str(value)
+            parent_id = current_parent_event_id.get(None)
+            pre_event_id = str(uuid.uuid4())
+            start_time = datetime.now().astimezone()
+            result = None
+            error: Optional[BaseException] = None
 
-            # Construct JSONable object of args
-            args_dict = {
-                param_name: serialize(param_value)  # Recursive - maybe change later
-                for param_name, param_value in bound_args.arguments.items()
-            }
-            
-            if not event_desc:
-                event_desc = f"Function {function_name}({json.dumps(args_dict)})"
-            
-            # Create the event
-            event_id = create_event(
-                description=event_desc,
-                model=model,
-                cost_added=cost_added,
-                function_name=function_name,
-                arguments=args_dict, 
-            )
-            tok = _current_event.set(event_id)
             try:
-                # Execute the wrapped function
-                function_result = func(*args, **kwargs)
-                
-                # Build event result from output if not provided
-                event_result = result
-                if not event_result:
-                    try:
-                        event_result = repr(function_result)
-                    except Exception:
-                        event_result = str(function_result)
-                
-                # Update and end the event
-                end_event(
-                    event_id=event_id,
-                    result=event_result,
-                )
-                _current_event.reset(tok)
-                return function_result
-                
+                async with event_context_async(pre_event_id):
+                    result = await func(*args, **kwargs)
+                return result
             except Exception as e:
-                # Update event with error
-                try:
-                    end_event(
-                        event_id=event_id,
-                        result=f"Error: {str(e)}",
-                    )
-                    _current_event.reset(tok)
-                except Exception:
-                    logger.error(f"Failed to end event {event_id} after error")
+                error = e
                 raise
-        
-        @functools.wraps(func)
-        async def async_wrapper(*args, **kwargs):
-            # Check if SDK is initialized
-            try:
-                client = Client()
-                if not client.session:
-                    # No active session, run function normally
-                    logger.warning("No active session, running function normally")
-                    return await func(*args, **kwargs)
-            except (LucidicNotInitializedError, AttributeError):
-                # SDK not initialized or no session, run function normally
-                logger.warning("Lucidic not initialized, running function normally")
-                return await func(*args, **kwargs)
-            
-            # Import here to avoid circular imports
-            from . import create_event, end_event
-            
-            # Build event description from inputs if not provided
-            event_desc = description
-            if not event_desc:
-                # Get function signature
-                sig = inspect.signature(func)
-                bound_args = sig.bind(*args, **kwargs)
-                bound_args.apply_defaults()
-                
-                # Create string representation of inputs
-                input_parts = []
-                for param_name, param_value in bound_args.arguments.items():
-                    try:
-                        input_parts.append(f"{param_name}={repr(param_value)}")
-                    except Exception:
-                        input_parts.append(f"{param_name}=<{type(param_value).__name__}>")
-                
-                event_desc = f"{func.__name__}({', '.join(input_parts)})"
-            
-            # Create the event
-            event_id = create_event(
-                description=event_desc,
-                model=model,
-                cost_added=cost_added
-            )
-            tok = _current_event.set(event_id)
-            try:
-                # Execute the wrapped function
-                function_result = await func(*args, **kwargs)
-                
-                # Build event result from output if not provided
-                event_result = result
-                if not event_result:
-                    try:
-                        event_result = repr(function_result)
-                    except Exception:
-                        event_result = str(function_result)
-                
-                # Update and end the event
-                end_event(
-                    event_id=event_id,
-                    result=event_result,
-                )
-                _current_event.reset(tok)
-                return function_result
-                
-            except Exception as e:
-                # Update event with error
+            finally:
                 try:
-                    end_event(
-                        event_id=event_id,
-                        result=f"Error: {str(e)}",
+                    # Store error as return value with type information
+                    if error:
+                        return_val = {
+                            "error": str(error),
+                            "error_type": type(error).__name__
+                        }
+                    else:
+                        return_val = _serialize(result)
+                    
+                    client.create_event(
+                        type="function_call",
+                        event_id=pre_event_id,
+                        function_name=func.__name__,
+                        arguments=args_dict,
+                        return_value=return_val,
+                        error=str(error) if error else None,
+                        parent_event_id=parent_id,
+                        duration=(datetime.now().astimezone() - start_time).total_seconds(),
+                        **decorator_kwargs
                     )
-                    _current_event.reset(tok)
                 except Exception:
-                    logger.error(f"Failed to end event {event_id} after error")
-                raise
-        
-        # Return appropriate wrapper based on function type
+                    pass
+
         if inspect.iscoroutinefunction(func):
-            return async_wrapper
-        else:
-            return sync_wrapper
-    
+            return async_wrapper  # type: ignore
+        return sync_wrapper  # type: ignore
+
     return decorator

lucidicai/errors.py

@@ -1,4 +1,6 @@
 from typing import Optional
+import sys
+import traceback
 
 class APIKeyVerificationError(Exception):
     """Exception for API key verification errors"""
@@ -19,3 +21,34 @@ class InvalidOperationError(Exception):
     "Exception for errors resulting from attempting an invalid operation"
     def __init__(self, message: str):
         super().__init__(f"An invalid Lucidic operation was attempted: {message}")
+
+
+def install_error_handler():
+    """Install global handler to create ERROR_TRACEBACK events for uncaught exceptions."""
+    from .client import Client
+    from .context import current_parent_event_id
+
+    def handle_exception(exc_type, exc_value, exc_traceback):
+        try:
+            client = Client()
+            if client and client.session:
+                tb = ''.join(traceback.format_exception(exc_type, exc_value, exc_traceback))
+                parent_id = None
+                try:
+                    parent_id = current_parent_event_id.get(None)
+                except Exception:
+                    parent_id = None
+                client.create_event(
+                    type="error_traceback",
+                    error=str(exc_value),
+                    traceback=tb,
+                    parent_event_id=parent_id
+                )
+        except Exception:
+            pass
+        try:
+            sys.__excepthook__(exc_type, exc_value, exc_traceback)
+        except Exception:
+            pass
+
+    sys.excepthook = handle_exception