lucidicai 3.0.0__py3-none-any.whl → 3.1.1__py3-none-any.whl

lucidicai/__init__.py

@@ -35,7 +35,7 @@ from .core.errors import (
 )
 
 # Version
-__version__ = "3.0.0"
+__version__ = "3.1.1"
 
 # All exports
 __all__ = [

lucidicai/api/resources/evals.py

@@ -0,0 +1,209 @@
+"""Evals resource API operations."""
+import logging
+import threading
+from typing import Any, Dict, Optional, Union
+
+from ..client import HttpClient
+
+logger = logging.getLogger("Lucidic")
+
+
+def _truncate_id(id_str: Optional[str]) -> str:
+    """Truncate ID for logging."""
+    if not id_str:
+        return "None"
+    return f"{id_str[:8]}..." if len(id_str) > 8 else id_str
+
+
+def _infer_result_type(result: Any) -> str:
+    """Infer result type from Python value.
+
+    Note: bool must be checked first because bool is a subclass of int in Python.
+
+    Args:
+        result: The evaluation result value.
+
+    Returns:
+        The result type string: "boolean", "number", or "string".
+
+    Raises:
+        ValueError: If result is not a supported type.
+    """
+    if isinstance(result, bool):
+        return "boolean"
+    elif isinstance(result, (int, float)):
+        return "number"
+    elif isinstance(result, str):
+        return "string"
+    else:
+        raise ValueError(
+            f"Unsupported result type: {type(result).__name__}. "
+            "Must be bool, int, float, or str."
+        )
+
+
+def _validate_result_type(result: Any, result_type: str) -> bool:
+    """Validate that result matches the specified result_type.
+
+    Args:
+        result: The evaluation result value.
+        result_type: The expected type ("boolean", "number", "string").
+
+    Returns:
+        True if the result matches the type, False otherwise.
+    """
+    if result_type == "boolean":
+        return isinstance(result, bool)
+    elif result_type == "number":
+        # Check for bool first since bool is subclass of int
+        return isinstance(result, (int, float)) and not isinstance(result, bool)
+    elif result_type == "string":
+        return isinstance(result, str)
+    return False
+
+
+class EvalsResource:
+    """Handle evaluation-related API operations."""
+
+    def __init__(self, http: HttpClient, production: bool = False):
+        """Initialize evals resource.
+
+        Args:
+            http: HTTP client instance
+            production: Whether to suppress errors in production mode
+        """
+        self.http = http
+        self._production = production
+
+    def emit(
+        self,
+        result: Union[bool, int, float, str],
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        result_type: Optional[str] = None,
+        session_id: Optional[str] = None,
+    ) -> None:
+        """Fire-and-forget evaluation submission that returns instantly.
+
+        This function returns immediately while the actual evaluation
+        submission happens in a background thread. Perfect for non-blocking
+        evaluation logging.
+
+        Args:
+            result: The evaluation result. Can be bool, int, float, or str.
+            name: Optional name for the evaluation. If not provided, the backend
+                will generate a default name based on the result type.
+            description: Optional description of the evaluation.
+            result_type: Optional explicit result type ("boolean", "number", "string").
+                If not provided, it will be inferred from the result value.
+            session_id: Optional session ID. If not provided, uses the current
+                session from context.
+
+        Example:
+            # Basic usage - type inferred
+            client.evals.emit(result=True)
+            client.evals.emit(result=0.95)
+            client.evals.emit(result="excellent")
+
+            # With name and description
+            client.evals.emit(
+                result=True,
+                name="task_completed",
+                description="User task was successful"
+            )
+
+            # Explicit session_id
+            client.evals.emit(result=0.87, name="accuracy_score", session_id="abc-123")
+        """
+        from ...sdk.context import current_session_id
+
+        # Capture session from context if not provided
+        captured_session_id = session_id
+        if not captured_session_id:
+            captured_session_id = current_session_id.get(None)
+
+        if not captured_session_id:
+            logger.debug("[EvalsResource] No active session for emit()")
+            return
+
+        # Infer or validate result_type
+        try:
+            if result_type is None:
+                inferred_type = _infer_result_type(result)
+            else:
+                # Validate that result matches the explicit type
+                if not _validate_result_type(result, result_type):
+                    error_msg = (
+                        f"Result type mismatch: result is {type(result).__name__} "
+                        f"but result_type is '{result_type}'"
+                    )
+                    if self._production:
+                        logger.error(f"[EvalsResource] {error_msg}")
+                        return
+                    else:
+                        raise ValueError(error_msg)
+                inferred_type = result_type
+        except ValueError as e:
+            if self._production:
+                logger.error(f"[EvalsResource] {e}")
+                return
+            else:
+                raise
+
+        # Capture all data for background thread
+        captured_result = result
+        captured_name = name
+        captured_description = description
+        captured_type = inferred_type
+
+        def _background_emit():
+            try:
+                params: Dict[str, Any] = {
+                    "session_id": captured_session_id,
+                    "result": captured_result,
+                    "result_type": captured_type,
+                }
+                if captured_name is not None:
+                    params["name"] = captured_name
+                if captured_description is not None:
+                    params["description"] = captured_description
+
+                self._create_eval(params)
+            except Exception as e:
+                logger.debug(f"[EvalsResource] Background emit() failed: {e}")
+
+        # Start background thread
+        thread = threading.Thread(target=_background_emit, daemon=True)
+        thread.start()
+
+    def _create_eval(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Send evaluation to backend API.
+
+        Args:
+            params: Evaluation parameters including:
+                - session_id: Session ID
+                - result: Evaluation result value
+                - result_type: Type of result ("boolean", "number", "string")
+                - name: Optional evaluation name
+                - description: Optional description
+
+        Returns:
+            API response (typically empty for 201 Created)
+        """
+        session_id = params.get("session_id")
+        name = params.get("name")
+        result_type = params.get("result_type")
+        logger.debug(
+            f"[Evals] _create_eval() called - "
+            f"session_id={_truncate_id(session_id)}, name={name!r}, "
+            f"result_type={result_type!r}"
+        )
+
+        response = self.http.post("sdk/evals", params)
+
+        logger.debug(
+            f"[Evals] _create_eval() response - "
+            f"session_id={_truncate_id(session_id)}, "
+            f"response_keys={list(response.keys()) if response else 'None'}"
+        )
+        return response

lucidicai/client.py

@@ -30,6 +30,7 @@ from .api.resources.dataset import DatasetResource
 from .api.resources.experiment import ExperimentResource
 from .api.resources.prompt import PromptResource
 from .api.resources.feature_flag import FeatureFlagResource
+from .api.resources.evals import EvalsResource
 from .core.config import SDKConfig
 from .core.errors import LucidicError
 from .session_obj import Session
@@ -145,6 +146,7 @@ class LucidicAI:
             "experiments": ExperimentResource(self._http, self._config.agent_id, self._production),
             "prompts": PromptResource(self._http, self._production),
             "feature_flags": FeatureFlagResource(self._http, self._config.agent_id, self._production),
+            "evals": EvalsResource(self._http, self._production),
         }
 
         # Active sessions for this client
@@ -271,6 +273,17 @@ class LucidicAI:
         """
         return self._resources["datasets"]
 
+    @property
+    def evals(self) -> EvalsResource:
+        """Access evals resource for submitting evaluation results.
+
+        Example:
+            client.evals.emit(result=True, name="task_success")
+            client.evals.emit(result=0.95, name="accuracy")
+            client.evals.emit(result="excellent", name="quality")
+        """
+        return self._resources["evals"]
+
     # ==================== Decorators ====================
 
     def event(

lucidicai/sdk/decorators.py

@@ -51,7 +51,7 @@ def _emit_event_to_client(
             "session_id": session_id,
             **event_data,
         }
-        response = client._resources["events"].create_event(event_payload)
+        response = client._resources["events"].create(**event_payload)
         return response.get("event_id") if response else None
     except Exception as e:
         debug(f"[Decorator] Failed to emit event: {e}")
@@ -81,7 +81,7 @@ async def _aemit_event_to_client(
             "session_id": session_id,
             **event_data,
         }
-        response = await client._resources["events"].acreate_event(event_payload)
+        response = await client._resources["events"].acreate(**event_payload)
         return response.get("event_id") if response else None
     except Exception as e:
         debug(f"[Decorator] Failed to emit async event: {e}")

{lucidicai-3.0.0.dist-info → lucidicai-3.1.1.dist-info}/METADATA

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

{lucidicai-3.0.0.dist-info → lucidicai-3.1.1.dist-info}/RECORD

@@ -1,6 +1,6 @@
-lucidicai/__init__.py,sha256=2tzRM0UYAxeeYzqqMrxnKyINWqKtxg3gbX6beieIeFs,1180
+lucidicai/__init__.py,sha256=83k3iIyPlLhhZ_fRyy54x4Ry9WbRhNTK1bczhvHSj_A,1180
 lucidicai/action.py,sha256=sPRd1hTIVXDqnvG9ZXWEipUFh0bsXcE0Fm7RVqmVccM,237
-lucidicai/client.py,sha256=XxJ4NYfSi1mlgLC9XjLL9TmwpXpgvKMLzi7zzZazuRU,14180
+lucidicai/client.py,sha256=WnkUeo_Z0uP4xh66gNC6MJhYdyhRpjC61OBjHEJLHq4,14674
 lucidicai/constants.py,sha256=zN8O7TjoRHRlaGa9CZUWppS73rhzKGwaEkF9XMTV0Cg,1160
 lucidicai/context.py,sha256=ruEXAndSv0gQ-YEXLlC4Fx6NNbaylfp_dZxbpwmLZSA,4622
 lucidicai/dataset.py,sha256=wu25X02JyWkht_yQabgQpGZFfzbNTxG6tf5k9ol8Amo,4005
@@ -22,6 +22,7 @@ lucidicai/api/__init__.py,sha256=UOYuFZupG0TgzMAxbLNgpodDXhDRXBgMva8ZblgBN9Y,31
 lucidicai/api/client.py,sha256=0Ia5cXo5OKifhP-63TPAWPuy2bWCzR9VN4BpWIMo34w,13212
 lucidicai/api/resources/__init__.py,sha256=DDgviDW3Su-G1ofkZGlaJMc2pzYJqrbBnEruNg1whCM,416
 lucidicai/api/resources/dataset.py,sha256=I6g9ah4vaqEH1jyeouBn7xvC0oAuDNPeyl-bmtNj-T0,17400
+lucidicai/api/resources/evals.py,sha256=_3nLE6dMLht844mWw7kl_hctjv5JIuC6MP06YWUgLnI,7235
 lucidicai/api/resources/event.py,sha256=GTIU5sIbLNTWAHk4rB120xWTRkhnraz9JNfamEygyNo,14267
 lucidicai/api/resources/experiment.py,sha256=fOIKJ5d89bHJBVZ3wjbhY_6XF3kLHz9TE3BVPA5pNpA,3563
 lucidicai/api/resources/feature_flag.py,sha256=ii412DIkZCEAhrXdGydcpQKveqGlFq4NlgdmWQnU83c,2259
@@ -51,7 +52,7 @@ lucidicai/providers/universal_image_interceptor.py,sha256=7d-hw4xihRwvvA1AP8-vqY
 lucidicai/sdk/__init__.py,sha256=UrkV9FYbZkBxaX9qwxGbCJdXp-JqMpn0_u-huO9Y-ec,32
 lucidicai/sdk/bound_decorators.py,sha256=SzmNZwORhArXL9D8T8BpPltT-jQ-tVpy71t8bJWOIU0,12151
 lucidicai/sdk/context.py,sha256=y58_C9JlBML_xFPUbmAn6WuxsnM03bECJ2pKBWz0TuQ,10386
-lucidicai/sdk/decorators.py,sha256=-MBMCn-vED2x3ioWD3MYo0_FfMdr6LbfpekURH7Cpvw,15660
+lucidicai/sdk/decorators.py,sha256=FV0259ki6x26d2-YKZJwkUNzHain-QGghq94OzAk2Os,15652
 lucidicai/sdk/error_boundary.py,sha256=IPr5wS9rS7ZQNgEaBwK53UaixAm6L2rijKKFfxcxjUI,9190
 lucidicai/sdk/event.py,sha256=hpBJfqKteOuQKoZfhxQfbeVOrdmR8wCcQc8P6658VRo,22658
 lucidicai/sdk/event_builder.py,sha256=Z376RKlStM7IBcAm5LKgTDh3x_fjmcvkWltUrjZ6RAc,10304
@@ -90,7 +91,7 @@ lucidicai/utils/images.py,sha256=z8mlIKgFfrIbuk-l4L2rB62uw_uPO79sHPXPY7eLu2A,128
 lucidicai/utils/logger.py,sha256=R3B3gSee64F6UVHUrShihBq_O7W7bgfrBiVDXTO3Isg,4777
 lucidicai/utils/queue.py,sha256=8DQwnGw7pINEJ0dNSkB0PhdPW-iBQQ-YZg23poe4umE,17323
 lucidicai/utils/serialization.py,sha256=KdOREZd7XBxFBAZ86DePMfYPzSVyKr4RcgUa82aFxrs,820
-lucidicai-3.0.0.dist-info/METADATA,sha256=KY6XOzFlxTySIfjrzQvPa3SI50ecJp0_86qEq-Or4xw,902
-lucidicai-3.0.0.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
-lucidicai-3.0.0.dist-info/top_level.txt,sha256=vSSdM3lclF4I5tyVC0xxUk8eIRnnYXMe1hW-eO91HUo,10
-lucidicai-3.0.0.dist-info/RECORD,,
+lucidicai-3.1.1.dist-info/METADATA,sha256=OCfPUqhEyRmBCQWTOoKUwbw3hR7T6JNZY9XtxyUbXxE,902
+lucidicai-3.1.1.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
+lucidicai-3.1.1.dist-info/top_level.txt,sha256=vSSdM3lclF4I5tyVC0xxUk8eIRnnYXMe1hW-eO91HUo,10
+lucidicai-3.1.1.dist-info/RECORD,,