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

lucidicai/api/__init__.py

@@ -0,0 +1 @@
+"""API client and resources."""

lucidicai/api/client.py

@@ -0,0 +1,218 @@
+"""Pure HTTP client for Lucidic API communication.
+
+This module contains only the HTTP client logic, separated from
+session management and other concerns.
+"""
+import json
+from typing import Any, Dict, Optional
+from urllib.parse import urlencode
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util import Retry
+
+from ..core.config import SDKConfig, get_config
+from ..core.errors import APIKeyVerificationError
+from ..utils.logger import debug, info, warning, error, mask_sensitive, truncate_data
+
+
+class HttpClient:
+    """HTTP client for API communication."""
+    
+    def __init__(self, config: Optional[SDKConfig] = None):
+        """Initialize the HTTP client.
+        
+        Args:
+            config: SDK configuration (uses global if not provided)
+        """
+        self.config = config or get_config()
+        self.base_url = self.config.network.base_url
+        
+        # Create session with connection pooling
+        self.session = requests.Session()
+        
+        # Configure retries
+        retry_cfg = Retry(
+            total=self.config.network.max_retries,
+            backoff_factor=self.config.network.backoff_factor,
+            status_forcelist=[502, 503, 504],
+            allowed_methods=["GET", "POST", "PUT", "DELETE"],
+        )
+        
+        # Configure adapter with connection pooling
+        adapter = HTTPAdapter(
+            max_retries=retry_cfg,
+            pool_connections=self.config.network.connection_pool_size,
+            pool_maxsize=self.config.network.connection_pool_maxsize
+        )
+        
+        self.session.mount("https://", adapter)
+        self.session.mount("http://", adapter)
+        
+        # Set headers
+        self._update_headers()
+        
+        # Verify API key if configured
+        if self.config.api_key:
+            self._verify_api_key()
+    
+    def _update_headers(self) -> None:
+        """Update session headers with authentication."""
+        headers = {
+            "User-Agent": "lucidic-sdk/2.0",
+            "Content-Type": "application/json"
+        }
+        
+        if self.config.api_key:
+            headers["Authorization"] = f"Api-Key {self.config.api_key}"
+        
+        if self.config.agent_id:
+            headers["x-agent-id"] = self.config.agent_id
+        
+        self.session.headers.update(headers)
+    
+    def _verify_api_key(self) -> None:
+        """Verify the API key with the backend."""
+        debug("[HTTP] Verifying API key")
+        try:
+            response = self.get("verifyapikey")
+            # Backend returns 200 OK for valid key, check if we got a response
+            if response is None:
+                raise APIKeyVerificationError("No response from API")
+            info("[HTTP] API key verified successfully")
+        except APIKeyVerificationError:
+            raise
+        except requests.RequestException as e:
+            raise APIKeyVerificationError(f"Could not verify API key: {e}")
+    
+    def get(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Make a GET request.
+        
+        Args:
+            endpoint: API endpoint (without base URL)
+            params: Query parameters
+            
+        Returns:
+            Response data as dictionary
+        """
+        return self.request("GET", endpoint, params=params)
+    
+    def post(self, endpoint: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Make a POST request.
+        
+        Args:
+            endpoint: API endpoint (without base URL)
+            data: Request body data
+            
+        Returns:
+            Response data as dictionary
+        """
+        # Add current_time to all POST requests like TypeScript SDK does
+        from datetime import datetime, timezone
+        if data is None:
+            data = {}
+        data["current_time"] = datetime.now(timezone.utc).isoformat()
+        return self.request("POST", endpoint, json=data)
+    
+    def put(self, endpoint: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Make a PUT request.
+        
+        Args:
+            endpoint: API endpoint (without base URL)
+            data: Request body data
+            
+        Returns:
+            Response data as dictionary
+        """
+        # Add current_time to all PUT requests like TypeScript SDK does
+        from datetime import datetime, timezone
+        if data is None:
+            data = {}
+        data["current_time"] = datetime.now(timezone.utc).isoformat()
+        return self.request("PUT", endpoint, json=data)
+    
+    def delete(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Make a DELETE request.
+        
+        Args:
+            endpoint: API endpoint (without base URL)
+            params: Query parameters
+            
+        Returns:
+            Response data as dictionary
+        """
+        return self.request("DELETE", endpoint, params=params)
+    
+    def request(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Make an HTTP request.
+        
+        Args:
+            method: HTTP method
+            endpoint: API endpoint (without base URL)
+            params: Query parameters
+            json: Request body (for POST/PUT)
+            **kwargs: Additional arguments for requests
+            
+        Returns:
+            Response data as dictionary
+            
+        Raises:
+            requests.RequestException: On HTTP errors
+        """
+        url = f"{self.base_url}/{endpoint}"
+        
+        # Log request details
+        debug(f"[HTTP] {method} {url}")
+        if params:
+            debug(f"[HTTP] Query params: {mask_sensitive(params)}")
+        if json:
+            debug(f"[HTTP] Request body: {truncate_data(mask_sensitive(json))}")
+        
+        response = self.session.request(
+            method=method,
+            url=url,
+            params=params,
+            json=json,
+            timeout=self.config.network.timeout,
+            **kwargs
+        )
+        
+        # Raise for HTTP errors with more detail
+        if not response.ok:
+            # Try to get error details from response
+            try:
+                error_data = response.json()
+                error_msg = error_data.get('detail', response.text)
+            except:
+                error_msg = response.text
+            
+            error(f"[HTTP] Error {response.status_code}: {error_msg}")
+        
+        response.raise_for_status()
+        
+        # Parse JSON response
+        try:
+            data = response.json()
+        except ValueError:
+            # For empty responses (like verifyapikey), return success
+            if response.status_code == 200 and not response.text:
+                data = {"success": True}
+            else:
+                # Return text if not JSON
+                data = {"response": response.text}
+        
+        debug(f"[HTTP] Response ({response.status_code}): {truncate_data(data)}")
+        
+        return data
+    
+    def close(self) -> None:
+        """Close the HTTP session."""
+        if self.session:
+            self.session.close()

lucidicai/api/resources/__init__.py

@@ -0,0 +1 @@
+"""API resource modules."""

lucidicai/api/resources/dataset.py

@@ -0,0 +1,192 @@
+"""Dataset resource API operations."""
+from typing import Any, Dict, List, Optional
+
+from ..client import HttpClient
+
+
+class DatasetResource:
+    """Handle dataset-related API operations."""
+
+    def __init__(self, http: HttpClient):
+        """Initialize dataset resource.
+
+        Args:
+            http: HTTP client instance
+        """
+        self.http = http
+
+    def list_datasets(self, agent_id=None):
+        """List all datasets for agent.
+
+        Args:
+            agent_id: Optional agent ID to filter by
+
+        Returns:
+            Dictionary with num_datasets and datasets list
+        """
+        params = {}
+        if agent_id:
+            params["agent_id"] = agent_id
+        return self.http.get("sdk/datasets", params)
+
+    def create_dataset(self, name, description=None, tags=None,
+                      suggested_flag_config=None, agent_id=None):
+        """Create new dataset.
+
+        Args:
+            name: Dataset name (must be unique per agent)
+            description: Optional description
+            tags: Optional list of tags
+            suggested_flag_config: Optional flag configuration
+            agent_id: Optional agent ID
+
+        Returns:
+            Dictionary with dataset_id
+        """
+        data = {"name": name}
+        if description is not None:
+            data["description"] = description
+        if tags is not None:
+            data["tags"] = tags
+        if suggested_flag_config is not None:
+            data["suggested_flag_config"] = suggested_flag_config
+        if agent_id is not None:
+            data["agent_id"] = agent_id
+        return self.http.post("sdk/datasets/create", data)
+
+    def get_dataset(self, dataset_id):
+        """Get dataset with all items - uses existing endpoint.
+
+        Args:
+            dataset_id: Dataset UUID
+
+        Returns:
+            Full dataset data including all items
+        """
+        return self.http.get("getdataset", {"dataset_id": dataset_id})
+
+    def update_dataset(self, dataset_id, **kwargs):
+        """Update dataset metadata.
+
+        Args:
+            dataset_id: Dataset UUID
+            **kwargs: Fields to update (name, description, tags, suggested_flag_config)
+
+        Returns:
+            Updated dataset data
+        """
+        data = {"dataset_id": dataset_id}
+        data.update(kwargs)
+        return self.http.put("sdk/datasets/update", data)
+
+    def delete_dataset(self, dataset_id):
+        """Delete dataset and all items.
+
+        Args:
+            dataset_id: Dataset UUID
+
+        Returns:
+            Success message
+        """
+        return self.http.delete("sdk/datasets/delete", {"dataset_id": dataset_id})
+
+    def create_item(self, dataset_id, name, input_data,
+                   expected_output=None, description=None,
+                   tags=None, metadata=None, flag_overrides=None):
+        """Create dataset item.
+
+        Args:
+            dataset_id: Dataset UUID
+            name: Item name
+            input_data: Input data dictionary
+            expected_output: Optional expected output
+            description: Optional description
+            tags: Optional list of tags
+            metadata: Optional metadata dictionary
+            flag_overrides: Optional flag overrides
+
+        Returns:
+            Dictionary with datasetitem_id
+        """
+        data = {
+            "dataset_id": dataset_id,
+            "name": name,
+            "input": input_data
+        }
+
+        # Add optional fields if provided
+        if expected_output is not None:
+            data["expected_output"] = expected_output
+        if description is not None:
+            data["description"] = description
+        if tags is not None:
+            data["tags"] = tags
+        if metadata is not None:
+            data["metadata"] = metadata
+        if flag_overrides is not None:
+            data["flag_overrides"] = flag_overrides
+
+        return self.http.post("sdk/datasets/items/create", data)
+
+    def get_item(self, dataset_id, item_id):
+        """Get specific dataset item.
+
+        Args:
+            dataset_id: Dataset UUID
+            item_id: Item UUID
+
+        Returns:
+            Dataset item data
+        """
+        return self.http.get("sdk/datasets/items/get", {
+            "dataset_id": dataset_id,
+            "datasetitem_id": item_id
+        })
+
+    def update_item(self, dataset_id, item_id, **kwargs):
+        """Update dataset item.
+
+        Args:
+            dataset_id: Dataset UUID
+            item_id: Item UUID
+            **kwargs: Fields to update
+
+        Returns:
+            Updated item data
+        """
+        data = {
+            "dataset_id": dataset_id,
+            "datasetitem_id": item_id
+        }
+        data.update(kwargs)
+        return self.http.put("sdk/datasets/items/update", data)
+
+    def delete_item(self, dataset_id, item_id):
+        """Delete dataset item.
+
+        Args:
+            dataset_id: Dataset UUID
+            item_id: Item UUID
+
+        Returns:
+            Success message
+        """
+        return self.http.delete("sdk/datasets/items/delete", {
+            "dataset_id": dataset_id,
+            "datasetitem_id": item_id
+        })
+
+    def list_item_sessions(self, dataset_id, item_id):
+        """List all sessions for a dataset item.
+
+        Args:
+            dataset_id: Dataset UUID
+            item_id: Item UUID
+
+        Returns:
+            Dictionary with num_sessions and sessions list
+        """
+        return self.http.get("sdk/datasets/items/sessions", {
+            "dataset_id": dataset_id,
+            "datasetitem_id": item_id
+        })

lucidicai/api/resources/event.py

@@ -0,0 +1,88 @@
+"""Event resource API operations."""
+from typing import Any, Dict, Optional
+from datetime import datetime
+
+from ..client import HttpClient
+
+
+class EventResource:
+    """Handle event-related API operations."""
+    
+    def __init__(self, http: HttpClient):
+        """Initialize event resource.
+        
+        Args:
+            http: HTTP client instance
+        """
+        self.http = http
+    
+    def create_event(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Create a new event.
+        
+        Args:
+            params: Event parameters including:
+                - client_event_id: Client-generated event ID
+                - session_id: Session ID
+                - type: Event type
+                - occurred_at: When the event occurred
+                - payload: Event payload
+                - etc.
+                
+        Returns:
+            API response with optional blob_url for large payloads
+        """
+        return self.http.post("events", params)
+    
+    def get_event(self, event_id: str) -> Dict[str, Any]:
+        """Get an event by ID.
+        
+        Args:
+            event_id: Event ID
+            
+        Returns:
+            Event data
+        """
+        return self.http.get(f"events/{event_id}")
+    
+    def update_event(self, event_id: str, updates: Dict[str, Any]) -> Dict[str, Any]:
+        """Update an existing event.
+        
+        Args:
+            event_id: Event ID
+            updates: Fields to update
+            
+        Returns:
+            Updated event data
+        """
+        return self.http.put(f"events/{event_id}", updates)
+    
+    def list_events(
+        self,
+        session_id: Optional[str] = None,
+        event_type: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0
+    ) -> Dict[str, Any]:
+        """List events with optional filters.
+        
+        Args:
+            session_id: Filter by session ID
+            event_type: Filter by event type
+            limit: Maximum number of events to return
+            offset: Pagination offset
+            
+        Returns:
+            List of events and pagination info
+        """
+        params = {
+            "limit": limit,
+            "offset": offset
+        }
+        
+        if session_id:
+            params["session_id"] = session_id
+        
+        if event_type:
+            params["type"] = event_type
+        
+        return self.http.get("events", params)

lucidicai/api/resources/session.py

@@ -0,0 +1,126 @@
+"""Session resource API operations."""
+from typing import Any, Dict, List, Optional
+
+from ..client import HttpClient
+
+
+class SessionResource:
+    """Handle session-related API operations."""
+    
+    def __init__(self, http: HttpClient):
+        """Initialize session resource.
+        
+        Args:
+            http: HTTP client instance
+        """
+        self.http = http
+    
+    def create_session(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Create a new session.
+        
+        Args:
+            params: Session parameters including:
+                - session_name: Name of the session
+                - agent_id: Agent ID
+                - task: Optional task description
+                - tags: Optional tags
+                - etc.
+                
+        Returns:
+            Created session data with session_id
+        """
+        return self.http.post("initsession", params)
+    
+    def get_session(self, session_id: str) -> Dict[str, Any]:
+        """Get a session by ID.
+        
+        Args:
+            session_id: Session ID
+            
+        Returns:
+            Session data
+        """
+        return self.http.get(f"sessions/{session_id}")
+    
+    def update_session(self, session_id: str, updates: Dict[str, Any]) -> Dict[str, Any]:
+        """Update an existing session.
+        
+        Args:
+            session_id: Session ID
+            updates: Fields to update (task, is_finished, etc.)
+            
+        Returns:
+            Updated session data
+        """
+        # Add session_id to the updates payload
+        updates["session_id"] = session_id
+        return self.http.put("updatesession", updates)
+    
+    def end_session(
+        self,
+        session_id: str,
+        is_successful: Optional[bool] = None,
+        is_successful_reason: Optional[str] = None,
+        session_eval: Optional[float] = None,
+        session_eval_reason: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """End a session.
+        
+        Args:
+            session_id: Session ID
+            is_successful: Whether session was successful
+            is_successful_reason: Reason for success or failure
+            session_eval: Session evaluation score
+            session_eval_reason: Reason for evaluation
+            
+        Returns:
+            Final session data
+        """
+        updates = {
+            "is_finished": True
+        }
+        
+        if is_successful is not None:
+            updates["is_successful"] = is_successful
+        
+        if session_eval is not None:
+            updates["session_eval"] = session_eval
+        
+        if session_eval_reason is not None:
+            updates["session_eval_reason"] = session_eval_reason
+
+        if is_successful_reason is not None:
+            updates["is_successful_reason"] = is_successful_reason
+        
+        return self.update_session(session_id, updates)
+    
+    def list_sessions(
+        self,
+        agent_id: Optional[str] = None,
+        experiment_id: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0
+    ) -> Dict[str, Any]:
+        """List sessions with optional filters.
+        
+        Args:
+            agent_id: Filter by agent ID
+            experiment_id: Filter by experiment ID
+            limit: Maximum number of sessions
+            offset: Pagination offset
+            
+        Returns:
+            List of sessions and pagination info
+        """
+        params = {
+            "limit": limit,
+            "offset": offset
+        }
+        
+        if agent_id:
+            params["agent_id"] = agent_id
+        
+        if experiment_id:
+            params["experiment_id"] = experiment_id
+        
+        return self.http.get("sessions", params)

lucidicai/core/__init__.py

@@ -0,0 +1 @@
+"""Core utilities and configuration."""