lucidicai 2.0.1__tar.gz → 2.0.2__tar.gz

{lucidicai-2.0.1 → lucidicai-2.0.2}/PKG-INFO

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

{lucidicai-2.0.1 → lucidicai-2.0.2}/lucidicai/__init__.py

@@ -28,6 +28,17 @@ from .context import (
     run_session,
     run_in_session,
 )
+from .dataset import get_dataset, get_dataset_items
+from .feature_flag import (
+    get_feature_flag,
+    get_bool_flag,
+    get_int_flag,
+    get_float_flag,
+    get_string_flag,
+    get_json_flag,
+    clear_feature_flag_cache,
+    FeatureFlagError
+)
 
 ProviderType = Literal[
     "openai",
@@ -229,6 +240,16 @@ __all__ = [
     'end_session',
     'get_prompt',
     'get_session',
+    'get_dataset',
+    'get_dataset_items',
+    'get_feature_flag',
+    'get_bool_flag',
+    'get_int_flag',
+    'get_float_flag',
+    'get_string_flag',
+    'get_json_flag',
+    'clear_feature_flag_cache',
+    'FeatureFlagError',
     'ProviderType',
     'APIKeyVerificationError',
     'LucidicNotInitializedError',
@@ -257,6 +278,7 @@ def init(
     experiment_id: Optional[str] = None,
     rubrics: Optional[list] = None,
     tags: Optional[list] = None,
+    dataset_item_id: Optional[str] = None,
     masking_function = None,
     auto_end: Optional[bool] = True,
     capture_uncaught: Optional[bool] = True,
@@ -274,6 +296,7 @@ def init(
         experiment_id: Optional experiment ID, if session is to be part of an experiment.
         rubrics: Optional rubrics for evaluation, list of strings.
         tags: Optional tags for the session, list of strings.
+        dataset_item_id: Optional dataset item ID to link session to a dataset item.
         masking_function: Optional function to mask sensitive data.
         auto_end: If True, automatically end the session on process exit. Defaults to True.
     
@@ -328,6 +351,7 @@ def init(
         production_monitoring=production_monitoring,
         session_id=session_id,
         experiment_id=experiment_id,
+        dataset_item_id=dataset_item_id,
     )
     if masking_function:
         client.masking_function = masking_function

{lucidicai-2.0.1 → lucidicai-2.0.2}/lucidicai/client.py

@@ -98,6 +98,7 @@ class Client:
         production_monitoring: Optional[bool] = False,
         session_id: Optional[str] = None,
         experiment_id: Optional[str] = None,
+        dataset_item_id: Optional[str] = None,
     ) -> None:
         if session_id:
             # Check if it's a known session ID, maybe custom and maybe real
@@ -122,7 +123,9 @@ class Client:
             "experiment_id": experiment_id,
             "rubrics": rubrics,
             "tags": tags,
-            "session_id": session_id
+            "session_id": session_id,
+            "dataset_item_id": dataset_item_id,
+            "production_monitoring": production_monitoring
         }
         data = self.make_request('initsession', 'POST', request_data)
         real_session_id = data["session_id"]

lucidicai-2.0.2/lucidicai/dataset.py

@@ -0,0 +1,114 @@
+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.
+    """
+    return # no op for now
+    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.
+    """
+    return # no op for now
+    dataset = get_dataset(dataset_id, api_key, agent_id)
+    return dataset.get('items', [])

{lucidicai-2.0.1 → lucidicai-2.0.2}/lucidicai/errors.py

@@ -23,6 +23,12 @@ class InvalidOperationError(Exception):
         super().__init__(f"An invalid Lucidic operation was attempted: {message}")
 
 
+class FeatureFlagError(Exception):
+    """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 .client import Client

lucidicai-2.0.2/lucidicai/feature_flag.py

@@ -0,0 +1,344 @@
+import os
+import logging
+import time
+from typing import Union, List, Dict, Any, Optional, overload, Tuple, Literal
+from dotenv import load_dotenv
+
+from .client import Client
+from .errors import APIKeyVerificationError, FeatureFlagError
+
+logger = logging.getLogger("Lucidic")
+
+# Cache implementation
+class FeatureFlagCache:
+    def __init__(self):
+        self._cache: Dict[str, tuple[Any, float]] = {}
+        self._default_ttl = 300  # 5 minutes
+    
+    def get(self, key: str) -> Optional[Any]:
+        if key in self._cache:
+            value, expiry = self._cache[key]
+            if time.time() < expiry:
+                return value
+            else:
+                del self._cache[key]
+        return None
+    
+    def set(self, key: str, value: Any, ttl: int = None):
+        if ttl is None:
+            ttl = self._default_ttl
+        if ttl > 0:
+            self._cache[key] = (value, time.time() + ttl)
+    
+    def clear(self):
+        self._cache.clear()
+
+# Global cache instance
+_flag_cache = FeatureFlagCache()
+
+# Sentinel value to distinguish None from missing
+MISSING = object()
+
+# Function overloads for type safety
+@overload
+def get_feature_flag(
+    flag_name: str,
+    default: Any = ...,
+    *,
+    return_missing: Literal[False] = False,
+    cache_ttl: Optional[int] = 300,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Any:
+    """Get a single feature flag."""
+    ...
+
+@overload
+def get_feature_flag(
+    flag_name: str,
+    default: Any = ...,
+    *,
+    return_missing: Literal[True],
+    cache_ttl: Optional[int] = 300,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Tuple[Any, List[str]]:
+    """Get a single feature flag with missing info."""
+    ...
+
+@overload
+def get_feature_flag(
+    flag_name: List[str],
+    defaults: Optional[Dict[str, Any]] = None,
+    *,
+    return_missing: Literal[False] = False,
+    cache_ttl: Optional[int] = 300,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Get multiple feature flags."""
+    ...
+
+@overload
+def get_feature_flag(
+    flag_name: List[str],
+    defaults: Optional[Dict[str, Any]] = None,
+    *,
+    return_missing: Literal[True],
+    cache_ttl: Optional[int] = 300,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Tuple[Dict[str, Any], List[str]]:
+    """Get multiple feature flags with missing info."""
+    ...
+
+def get_feature_flag(
+    flag_name: Union[str, List[str]],
+    default_or_defaults: Any = MISSING,
+    *,
+    return_missing: bool = False,
+    cache_ttl: Optional[int] = 300,
+    api_key: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Union[Any, Tuple[Any, List[str]], Dict[str, Any], Tuple[Dict[str, Any], List[str]]]:
+    """
+    Get feature flag(s) from backend. Raises FeatureFlagError on failure unless default provided.
+    
+    Args:
+        flag_name: Single flag name (str) or list of flag names
+        default_or_defaults: 
+            - If flag_name is str: default value for that flag (optional)
+            - If flag_name is List[str]: dict of defaults {flag_name: default_value}
+        cache_ttl: Cache time-to-live in seconds (0 to disable, -1 for forever)
+        api_key: Optional API key
+        agent_id: Optional agent ID
+    
+    Returns:
+        - If flag_name is str: The flag value (or tuple with missing list if return_missing=True)
+        - If flag_name is List[str]: Dict mapping flag_name -> value (or tuple with missing list if return_missing=True)
+    
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+        APIKeyVerificationError: If credentials missing
+    
+    Examples:
+        # Single flag with default
+        retries = lai.get_feature_flag("max_retries", default=3)
+        
+        # Single flag without default (can raise)
+        retries = lai.get_feature_flag("max_retries")
+        
+        # Multiple flags
+        flags = lai.get_feature_flag(
+            ["max_retries", "timeout"],
+            defaults={"max_retries": 3}
+        )
+    """
+
+    return # no op for now
+
+    load_dotenv()
+    
+    # Determine if single or batch
+    is_single = isinstance(flag_name, str)
+    flag_names = [flag_name] if is_single else flag_name
+    
+    # Parse defaults
+    if is_single:
+        has_default = default_or_defaults is not MISSING
+        defaults = {flag_name: default_or_defaults} if has_default else {}
+    else:
+        defaults = default_or_defaults if default_or_defaults not in (None, MISSING) else {}
+    
+    # Track missing flags
+    missing_flags = []
+    
+    # Check cache first
+    uncached_flags = []
+    cached_results = {}
+    
+    if cache_ttl != 0:
+        for name in flag_names:
+            cache_key = f"{agent_id}:{name}"
+            cached_value = _flag_cache.get(cache_key)
+            if cached_value is not None:
+                cached_results[name] = cached_value
+            else:
+                uncached_flags.append(name)
+    else:
+        uncached_flags = flag_names
+    
+    # Fetch uncached flags if needed
+    if uncached_flags:
+        # 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 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 or set the LUCIDIC_AGENT_ID environment variable."
+                )
+        
+        # Get client
+        client = Client()
+        if not getattr(client, 'initialized', False):
+            client = Client(api_key=api_key, agent_id=agent_id)
+        else:
+            if api_key != client.api_key or agent_id != client.agent_id:
+                client.set_api_key(api_key)
+                client.agent_id = agent_id
+        
+        try:
+            # Make batch API call
+            response = client.make_request(
+                'getfeatureflags',
+                'POST',
+                {'flag_names': uncached_flags}
+            )
+            
+            # Process response and update cache
+            for name in uncached_flags:
+                if name in response['flags']:
+                    if response['flags'][name]['found']:
+                        value = response['flags'][name]['value']
+                        cached_results[name] = value
+                        
+                        # Cache the value
+                        if cache_ttl != 0:
+                            cache_key = f"{agent_id}:{name}"
+                            _flag_cache.set(cache_key, value, ttl=cache_ttl if cache_ttl > 0 else None)
+                    else:
+                        # Flag not found on server
+                        missing_flags.append(name)
+                        logger.warning(f"Feature flag '{name}' not found on server")
+                
+        except Exception as e:
+            # Log the error
+            logger.error(f"Failed to fetch feature flags: {e}")
+            
+            # Check if we have defaults for missing flags
+            for name in uncached_flags:
+                if name not in cached_results:
+                    if name in defaults:
+                        cached_results[name] = defaults[name]
+                    elif is_single and not return_missing:
+                        # Single flag without default and not returning missing - raise error
+                        raise FeatureFlagError(f"'{name}': {e}") from e
+    
+    # Build final result
+    result = {}
+    for name in flag_names:
+        if name in cached_results:
+            result[name] = cached_results[name]
+        elif name in defaults:
+            result[name] = defaults[name]
+        else:
+            # No value and no default
+            missing_flags.append(name)
+            if is_single and not return_missing:
+                raise FeatureFlagError(f"'{name}' not found and no default provided")
+            else:
+                result[name] = None
+    
+    # Return based on input type and return_missing flag
+    if return_missing:
+        return (result[flag_names[0]] if is_single else result, missing_flags)
+    else:
+        return result[flag_names[0]] if is_single else result
+
+
+# Typed convenience functions
+def get_bool_flag(flag_name: str, default: Optional[bool] = None, **kwargs) -> bool:
+    """
+    Get a boolean feature flag with type validation.
+    
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+        TypeError: If flag value is not a boolean
+    """
+    return # no op for now
+    value = get_feature_flag(flag_name, default=default if default is not None else MISSING, **kwargs)
+    if not isinstance(value, bool):
+        if default is not None:
+            logger.warning(f"Feature flag '{flag_name}' is not a boolean, using default")
+            return default
+        raise TypeError(f"Feature flag '{flag_name}' expected boolean, got {type(value).__name__}")
+    return value
+
+
+def get_int_flag(flag_name: str, default: Optional[int] = None, **kwargs) -> int:
+    """
+    Get an integer feature flag with type validation.
+    
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+        TypeError: If flag value is not an integer
+    """
+    return # no op for now
+    value = get_feature_flag(flag_name, default=default if default is not None else MISSING, **kwargs)
+    if not isinstance(value, int) or isinstance(value, bool):  # bool is subclass of int
+        if default is not None:
+            logger.warning(f"Feature flag '{flag_name}' is not an integer, using default")
+            return default
+        raise TypeError(f"Feature flag '{flag_name}' expected integer, got {type(value).__name__}")
+    return value
+
+
+def get_float_flag(flag_name: str, default: Optional[float] = None, **kwargs) -> float:
+    """
+    Get a float feature flag with type validation.
+    
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+        TypeError: If flag value is not a float
+    """
+    return # no op for now
+    value = get_feature_flag(flag_name, default=default if default is not None else MISSING, **kwargs)
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        if default is not None:
+            logger.warning(f"Feature flag '{flag_name}' is not a float, using default")
+            return default
+        raise TypeError(f"Feature flag '{flag_name}' expected float, got {type(value).__name__}")
+    return float(value)
+
+
+def get_string_flag(flag_name: str, default: Optional[str] = None, **kwargs) -> str:
+    """
+    Get a string feature flag with type validation.
+    
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+        TypeError: If flag value is not a string
+    """
+    return # no op for now
+    value = get_feature_flag(flag_name, default=default if default is not None else MISSING, **kwargs)
+    if not isinstance(value, str):
+        if default is not None:
+            logger.warning(f"Feature flag '{flag_name}' is not a string, using default")
+            return default
+        raise TypeError(f"Feature flag '{flag_name}' expected string, got {type(value).__name__}")
+    return value
+
+
+def get_json_flag(flag_name: str, default: Optional[dict] = None, **kwargs) -> dict:
+    """
+    Get a JSON object feature flag.
+    
+    Raises:
+        FeatureFlagError: If fetch fails and no default provided
+    """
+    return # no op for now
+    value = get_feature_flag(flag_name, default=default if default is not None else MISSING, **kwargs)
+    return value
+
+
+def clear_feature_flag_cache():
+    """Clear the feature flag cache."""
+    _flag_cache.clear()
+    logger.debug("Feature flag cache cleared")

{lucidicai-2.0.1 → lucidicai-2.0.2}/lucidicai.egg-info/PKG-INFO

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

{lucidicai-2.0.1 → lucidicai-2.0.2}/lucidicai.egg-info/SOURCES.txt

@@ -4,10 +4,12 @@ lucidicai/__init__.py
 lucidicai/client.py
 lucidicai/constants.py
 lucidicai/context.py
+lucidicai/dataset.py
 lucidicai/decorators.py
 lucidicai/errors.py
 lucidicai/event.py
 lucidicai/event_queue.py
+lucidicai/feature_flag.py
 lucidicai/image_upload.py
 lucidicai/lru.py
 lucidicai/model_pricing.py

{lucidicai-2.0.1 → lucidicai-2.0.2}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="lucidicai",
-    version="2.0.1",
+    version="2.0.2",
     packages=find_packages(),
     install_requires=[
         "requests>=2.25.1",