lucidicai 3.0.0__tar.gz → 3.3.1__tar.gz

{lucidicai-3.0.0 → lucidicai-3.3.1}/PKG-INFO

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

{lucidicai-3.0.0 → lucidicai-3.3.1}/lucidicai/__init__.py

@@ -34,8 +34,11 @@ from .core.errors import (
     FeatureFlagError,
 )
 
+# Integrations
+from .integrations.livekit import setup_livekit
+
 # Version
-__version__ = "3.0.0"
+__version__ = "3.3.1"
 
 # All exports
 __all__ = [
@@ -50,6 +53,8 @@ __all__ = [
     "InvalidOperationError",
     "PromptError",
     "FeatureFlagError",
+    # Integrations
+    "setup_livekit",
     # Version
     "__version__",
 ]

lucidicai-3.3.1/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-3.3.1/lucidicai/api/resources/prompt.py

@@ -0,0 +1,140 @@
+"""Prompt resource API operations."""
+import logging
+import time
+from typing import Any, Dict, Optional, Tuple, TYPE_CHECKING
+
+from ..client import HttpClient
+
+if TYPE_CHECKING:
+    from ...core.config import SDKConfig
+
+logger = logging.getLogger("Lucidic")
+
+
+class PromptResource:
+    """Handle prompt-related API operations."""
+
+    def __init__(self, http: HttpClient, config: "SDKConfig", production: bool = False):
+        """Initialize prompt resource.
+
+        Args:
+            http: HTTP client instance
+            config: SDK configuration
+            production: Whether to suppress errors in production mode
+        """
+        self.http = http
+        self._config = config
+        self._production = production
+        self._cache: Dict[Tuple[str, str], Dict[str, Any]] = {}
+
+    def _is_cache_valid(self, cache_key: Tuple[str, str], cache_ttl: int) -> bool:
+        """Check if a cached prompt is still valid.
+
+        Args:
+            cache_key: The (prompt_name, label) tuple
+            cache_ttl: Cache TTL in seconds (-1 = indefinite, 0 = no cache)
+
+        Returns:
+            True if cache is valid, False otherwise
+        """
+        if cache_ttl == 0:
+            return False
+        if cache_key not in self._cache:
+            return False
+        if cache_ttl == -1:
+            return True
+        cached = self._cache[cache_key]
+        return (time.time() - cached["timestamp"]) < cache_ttl
+
+    def get(
+        self,
+        prompt_name: str,
+        variables: Optional[Dict[str, Any]] = None,
+        label: str = "production",
+        cache_ttl: int = 0,
+    ) -> str:
+        """Get a prompt from the prompt database.
+
+        Args:
+            prompt_name: Name of the prompt.
+            variables: Variables to interpolate into the prompt.
+            label: Prompt version label (default: "production").
+            cache_ttl: Cache TTL in seconds. 0 = no cache, -1 = cache indefinitely,
+                       positive value = seconds before refetching.
+
+        Returns:
+            The prompt content with variables interpolated.
+        """
+        try:
+            cache_key = (prompt_name, label)
+
+            # Check cache
+            if self._is_cache_valid(cache_key, cache_ttl):
+                prompt = self._cache[cache_key]["content"]
+            else:
+                response = self.http.get(
+                    "getprompt",
+                    {"prompt_name": prompt_name, "label": label, "agent_id": self._config.agent_id},
+                )
+                prompt = response.get("prompt_content", "")
+
+                # Store in cache if caching is enabled
+                if cache_ttl != 0:
+                    self._cache[cache_key] = {
+                        "content": prompt,
+                        "timestamp": time.time(),
+                    }
+
+            # Replace variables
+            if variables:
+                for key, value in variables.items():
+                    prompt = prompt.replace(f"{{{{{key}}}}}", str(value))
+
+            return prompt
+        except Exception as e:
+            if self._production:
+                logger.error(f"[PromptResource] Failed to get prompt: {e}")
+                return ""
+            raise
+
+    async def aget(
+        self,
+        prompt_name: str,
+        variables: Optional[Dict[str, Any]] = None,
+        label: str = "production",
+        cache_ttl: int = 0,
+    ) -> str:
+        """Get a prompt from the prompt database (asynchronous).
+
+        See get() for full documentation.
+        """
+        try:
+            cache_key = (prompt_name, label)
+
+            # Check cache
+            if self._is_cache_valid(cache_key, cache_ttl):
+                prompt = self._cache[cache_key]["content"]
+            else:
+                response = await self.http.aget(
+                    "getprompt",
+                    {"prompt_name": prompt_name, "label": label, "agent_id": self._config.agent_id},
+                )
+                prompt = response.get("prompt_content", "")
+
+                # Store in cache if caching is enabled
+                if cache_ttl != 0:
+                    self._cache[cache_key] = {
+                        "content": prompt,
+                        "timestamp": time.time(),
+                    }
+
+            if variables:
+                for key, value in variables.items():
+                    prompt = prompt.replace(f"{{{{{key}}}}}", str(value))
+
+            return prompt
+        except Exception as e:
+            if self._production:
+                logger.error(f"[PromptResource] Failed to get prompt: {e}")
+                return ""
+            raise

{lucidicai-3.0.0 → lucidicai-3.3.1}/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
@@ -63,6 +64,8 @@ class LucidicAI:
         auto_end: Whether sessions auto-end on context exit or process shutdown.
         production: If True, suppress SDK errors. If None, checks LUCIDIC_PRODUCTION env var.
         region: Deployment region ("us", "india"). Falls back to LUCIDIC_REGION env var.
+        base_url: Custom base URL for API requests. Takes precedence over region.
+                  Falls back to LUCIDIC_BASE_URL env var.
         **kwargs: Additional configuration options passed to SDKConfig.
 
     Raises:
@@ -92,6 +95,13 @@ class LucidicAI:
             agent_id="...",
             region="india"
         )
+
+        # Custom base URL (e.g., self-hosted deployment)
+        client = LucidicAI(
+            api_key="...",
+            agent_id="...",
+            base_url="https://custom.example.com/api"
+        )
     """
 
     def __init__(
@@ -102,6 +112,7 @@ class LucidicAI:
         auto_end: bool = True,
         production: Optional[bool] = None,
         region: Optional[str] = None,
+        base_url: Optional[str] = None,
         **kwargs,
     ):
         # Generate unique client ID for telemetry routing
@@ -118,6 +129,7 @@ class LucidicAI:
             agent_id=agent_id,
             auto_end=auto_end,
             region=region,
+            base_url=base_url,
             **kwargs,
         )
 
@@ -143,8 +155,9 @@ class LucidicAI:
             "events": EventResource(self._http, self._production),
             "datasets": DatasetResource(self._http, self._config.agent_id, self._production),
             "experiments": ExperimentResource(self._http, self._config.agent_id, self._production),
-            "prompts": PromptResource(self._http, self._production),
+            "prompts": PromptResource(self._http, self._config, 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 +284,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-3.0.0 → lucidicai-3.3.1}/lucidicai/core/config.py

@@ -53,16 +53,20 @@ class NetworkConfig:
     connection_pool_maxsize: int = 100
 
     @classmethod
-    def from_env(cls, region: Optional[str] = None, debug: bool = False) -> 'NetworkConfig':
+    def from_env(cls, region: Optional[str] = None, base_url: Optional[str] = None, debug: bool = False) -> 'NetworkConfig':
         """Load network configuration from environment variables.
 
-        Priority: debug > region argument > LUCIDIC_REGION env var > default
+        Priority: debug > base_url argument > LUCIDIC_BASE_URL > region argument > LUCIDIC_REGION > default
 
         Args:
             region: Region string override (e.g., "us", "india")
-            debug: If True, use localhost URL regardless of region
+            base_url: Custom base URL override (takes precedence over region)
+            debug: If True, use localhost URL regardless of other settings
         """
-        # If debug mode, use localhost (ignores region)
+        import logging
+        logger = logging.getLogger("Lucidic")
+
+        # If debug mode, use localhost (highest priority)
         if debug:
             return cls(
                 base_url=DEBUG_URL,
@@ -74,7 +78,28 @@ class NetworkConfig:
                 connection_pool_maxsize=int(os.getenv("LUCIDIC_CONNECTION_POOL_MAXSIZE", "100"))
             )
 
-        # Resolve region: argument > env var > default
+        # Resolve base_url: argument > env var
+        resolved_base_url = base_url or os.getenv("LUCIDIC_BASE_URL")
+
+        if resolved_base_url:
+            # base_url takes precedence over region
+            region_str = region or os.getenv("LUCIDIC_REGION")
+            if region_str:
+                logger.warning(
+                    f"[LucidicAI] Both base_url and region specified. "
+                    f"Using base_url '{resolved_base_url}', ignoring region '{region_str}'."
+                )
+            return cls(
+                base_url=resolved_base_url,
+                region=None,  # Custom deployment, no 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")),
+                connection_pool_size=int(os.getenv("LUCIDIC_CONNECTION_POOL_SIZE", "20")),
+                connection_pool_maxsize=int(os.getenv("LUCIDIC_CONNECTION_POOL_MAXSIZE", "100"))
+            )
+
+        # Fall back to region-based URL resolution
         region_str = region or os.getenv("LUCIDIC_REGION")
         resolved_region = Region.from_string(region_str) if region_str else DEFAULT_REGION
 
@@ -147,11 +172,13 @@ class SDKConfig:
     debug: bool = False
     
     @classmethod
-    def from_env(cls, region: Optional[str] = None, **overrides) -> 'SDKConfig':
+    def from_env(cls, region: Optional[str] = None, base_url: 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
+            base_url: Custom base URL override. Takes precedence over region.
+                      Falls back to LUCIDIC_BASE_URL env var.
             **overrides: Additional configuration overrides
         """
         from dotenv import load_dotenv
@@ -165,7 +192,7 @@ class SDKConfig:
             auto_end=os.getenv("LUCIDIC_AUTO_END", "true").lower() == "true",
             production_monitoring=False,
             blob_threshold=int(os.getenv("LUCIDIC_BLOB_THRESHOLD", "65536")),
-            network=NetworkConfig.from_env(region=region, debug=debug),
+            network=NetworkConfig.from_env(region=region, base_url=base_url, debug=debug),
             error_handling=ErrorHandlingConfig.from_env(),
             telemetry=TelemetryConfig.from_env(),
             environment=Environment.DEBUG if debug else Environment.PRODUCTION,

lucidicai-3.3.1/lucidicai/integrations/__init__.py

@@ -0,0 +1,9 @@
+"""Third-party integrations for Lucidic AI SDK.
+
+This module provides integrations with external platforms and frameworks
+that have their own OpenTelemetry instrumentation.
+"""
+
+from .livekit import setup_livekit, LucidicLiveKitExporter
+
+__all__ = ["setup_livekit", "LucidicLiveKitExporter"]

lucidicai-3.3.1/lucidicai/integrations/livekit.py

@@ -0,0 +1,409 @@
+"""LiveKit voice agent integration for Lucidic AI SDK.
+
+This module provides OpenTelemetry span export for LiveKit voice agents,
+converting LiveKit's internal spans into Lucidic events with full metadata
+support including latency diagnostics, EOU detection data, and tool context.
+
+Example:
+    from lucidicai import LucidicAI
+    from lucidicai.integrations.livekit import setup_livekit
+    from livekit.agents import AgentServer, JobContext, AgentSession, cli
+    from livekit.agents.telemetry import set_tracer_provider
+
+    client = LucidicAI(api_key="...", agent_id="...")
+    server = AgentServer()
+
+    @server.rtc_session()
+    async def entrypoint(ctx: JobContext):
+        trace_provider = setup_livekit(
+            client=client,
+            session_id=ctx.room.name,
+        )
+        set_tracer_provider(trace_provider)
+        # ... rest of agent setup
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence
+
+from opentelemetry import context as otel_context
+from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+from opentelemetry.trace import Span
+from opentelemetry.util.types import AttributeValue
+
+if TYPE_CHECKING:
+    from opentelemetry.sdk.trace import TracerProvider
+    from ..client import LucidicAI
+
+logger = logging.getLogger("lucidicai.integrations.livekit")
+
+
+class LucidicLiveKitExporter(SpanExporter):
+    """Custom OpenTelemetry exporter for LiveKit voice agent spans.
+
+    Converts LiveKit spans (llm_node, function_tool) into Lucidic events
+    with full metadata including latency diagnostics, EOU detection,
+    and tool context.
+    """
+
+    # livekit span names we care about
+    LIVEKIT_LLM_SPANS = {"llm_node", "function_tool"}
+
+    def __init__(self, client: "LucidicAI", session_id: str):
+        """Initialize the exporter.
+
+        Args:
+            client: Initialized LucidicAI client instance
+            session_id: Session ID for all events created by this exporter
+        """
+        self._client = client
+        self._session_id = session_id
+        self._shutdown = False
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        """Export spans to Lucidic as events.
+
+        Args:
+            spans: Sequence of completed OpenTelemetry spans
+
+        Returns:
+            SpanExportResult indicating success or failure
+        """
+        if self._shutdown:
+            return SpanExportResult.SUCCESS
+
+        try:
+            for span in spans:
+                if self._is_livekit_llm_span(span):
+                    self._process_span(span)
+            return SpanExportResult.SUCCESS
+        except Exception as e:
+            logger.error(f"[LiveKit] Failed to export spans: {e}")
+            return SpanExportResult.FAILURE
+
+    def _is_livekit_llm_span(self, span: ReadableSpan) -> bool:
+        """Check if span is a LiveKit LLM-related span we should process."""
+        return span.name in self.LIVEKIT_LLM_SPANS
+
+    def _process_span(self, span: ReadableSpan) -> None:
+        """Process a single LiveKit span and create corresponding Lucidic event."""
+        try:
+            if span.name == "llm_node":
+                event_data = self._convert_llm_span(span)
+                self._client.events.create(**event_data)
+                logger.debug(f"[LiveKit] Created llm_generation event for span {span.name}")
+            elif span.name == "function_tool":
+                event_data = self._convert_function_span(span)
+                self._client.events.create(**event_data)
+                logger.debug(f"[LiveKit] Created function_call event for span {span.name}")
+        except Exception as e:
+            logger.error(f"[LiveKit] Failed to process span {span.name}: {e}")
+
+    def _convert_llm_span(self, span: ReadableSpan) -> Dict[str, Any]:
+        """Convert an llm_node span to llm_generation event data."""
+        attrs = dict(span.attributes or {})
+
+        # extract messages from chat context
+        messages = self._parse_chat_context(attrs.get("lk.chat_ctx"))
+
+        # extract output text
+        output = attrs.get("lk.response.text", "")
+
+        # build metadata with diagnostics
+        metadata = self._build_metadata(attrs)
+
+        # calculate duration
+        duration = None
+        if span.start_time and span.end_time:
+            duration = (span.end_time - span.start_time) / 1e9
+
+        # extract timing for occurred_at
+        occurred_at = None
+        if span.start_time:
+            occurred_at = datetime.fromtimestamp(
+                span.start_time / 1e9, tz=timezone.utc
+            ).isoformat()
+
+        return {
+            "type": "llm_generation",
+            "session_id": self._session_id,
+            "model": attrs.get("gen_ai.request.model", "unknown"),
+            "messages": messages,
+            "output": output,
+            "input_tokens": attrs.get("gen_ai.usage.input_tokens"),
+            "output_tokens": attrs.get("gen_ai.usage.output_tokens"),
+            "duration": duration,
+            "occurred_at": occurred_at,
+            "metadata": metadata,
+        }
+
+    def _convert_function_span(self, span: ReadableSpan) -> Dict[str, Any]:
+        """Convert a function_tool span to function_call event data."""
+        attrs = dict(span.attributes or {})
+
+        # calculate duration
+        duration = None
+        if span.start_time and span.end_time:
+            duration = (span.end_time - span.start_time) / 1e9
+
+        # extract timing for occurred_at
+        occurred_at = None
+        if span.start_time:
+            occurred_at = datetime.fromtimestamp(
+                span.start_time / 1e9, tz=timezone.utc
+            ).isoformat()
+
+        # build metadata (subset for function calls)
+        metadata = {
+            "job_id": attrs.get("lk.job_id"),
+            "room_name": attrs.get("lk.room_name") or attrs.get("room_id"),
+            "agent_name": attrs.get("lk.agent_name"),
+            "generation_id": attrs.get("lk.generation_id"),
+            "tool_call_id": attrs.get("lk.function_tool.id"),
+        }
+        metadata = self._clean_none_values(metadata)
+
+        return {
+            "type": "function_call",
+            "session_id": self._session_id,
+            "function_name": attrs.get("lk.function_tool.name", "unknown"),
+            "arguments": attrs.get("lk.function_tool.arguments"),
+            "return_value": attrs.get("lk.function_tool.output"),
+            "duration": duration,
+            "occurred_at": occurred_at,
+            "metadata": metadata,
+        }
+
+    def _parse_chat_context(self, chat_ctx_json: Optional[str]) -> List[Dict[str, str]]:
+        """Parse LiveKit's lk.chat_ctx JSON into Lucidic messages format.
+
+        Args:
+            chat_ctx_json: JSON string of LiveKit chat context
+
+        Returns:
+            List of message dicts with role and content keys
+        """
+        if not chat_ctx_json:
+            return []
+
+        try:
+            chat_ctx = json.loads(chat_ctx_json)
+            messages = []
+
+            # livekit chat context has 'items' list
+            items = chat_ctx.get("items", [])
+            for item in items:
+                if item.get("type") == "message":
+                    role = item.get("role", "user")
+                    # livekit stores content in various ways
+                    content = item.get("text_content", "")
+                    if not content:
+                        # try content array
+                        content_list = item.get("content", [])
+                        if isinstance(content_list, list):
+                            text_parts = []
+                            for c in content_list:
+                                if isinstance(c, str):
+                                    text_parts.append(c)
+                                elif isinstance(c, dict) and c.get("type") == "text":
+                                    text_parts.append(c.get("text", ""))
+                            content = " ".join(text_parts)
+                        elif isinstance(content_list, str):
+                            content = content_list
+
+                    messages.append({"role": role, "content": content})
+
+            return messages
+        except (json.JSONDecodeError, TypeError) as e:
+            logger.debug(f"[LiveKit] Failed to parse chat context: {e}")
+            return []
+
+    def _build_metadata(self, attrs: Dict[str, Any]) -> Dict[str, Any]:
+        """Build metadata dict with diagnostics from span attributes.
+
+        Args:
+            attrs: Span attributes dictionary
+
+        Returns:
+            Cleaned metadata dict with nested diagnostics
+        """
+        metadata = {
+            # identity & tracking
+            "job_id": attrs.get("lk.job_id"),
+            "room_name": attrs.get("lk.room_name") or attrs.get("room_id"),
+            "agent_name": attrs.get("lk.agent_name"),
+            "participant_id": attrs.get("lk.participant_id"),
+            "generation_id": attrs.get("lk.generation_id"),
+            "parent_generation_id": attrs.get("lk.parent_generation_id"),
+            "speech_id": attrs.get("lk.speech_id"),
+            "interrupted": attrs.get("lk.interrupted"),
+            # diagnostics (nested)
+            "diagnostics": {
+                "latency": {
+                    "llm_ttft": attrs.get("llm_node_ttft"),
+                    "tts_ttfb": attrs.get("tts_node_ttfb"),
+                    "e2e_latency": attrs.get("e2e_latency"),
+                    "transcription_delay": attrs.get("lk.transcription_delay"),
+                    "end_of_turn_delay": attrs.get("lk.end_of_turn_delay"),
+                },
+                "eou": {
+                    "probability": attrs.get("lk.eou.probability"),
+                    "threshold": attrs.get("lk.eou.unlikely_threshold"),
+                    "delay": attrs.get("lk.eou.endpointing_delay"),
+                    "language": attrs.get("lk.eou.language"),
+                },
+                "tools": {
+                    "function_tools": attrs.get("lk.function_tools"),
+                    "provider_tools": attrs.get("lk.provider_tools"),
+                    "tool_sets": attrs.get("lk.tool_sets"),
+                },
+                "session_options": attrs.get("lk.session_options"),
+            },
+        }
+        return self._clean_none_values(metadata)
+
+    def _clean_none_values(self, d: Dict[str, Any]) -> Dict[str, Any]:
+        """Recursively remove None values and empty dicts.
+
+        Args:
+            d: Dictionary to clean
+
+        Returns:
+            Cleaned dictionary with no None values or empty nested dicts
+        """
+        cleaned = {}
+        for k, v in d.items():
+            if isinstance(v, dict):
+                nested = self._clean_none_values(v)
+                if nested:  # only include non-empty dicts
+                    cleaned[k] = nested
+            elif v is not None:
+                cleaned[k] = v
+        return cleaned
+
+    def shutdown(self) -> None:
+        """Shutdown the exporter."""
+        self._shutdown = True
+        logger.debug("[LiveKit] Exporter shutdown")
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        """Force flush pending exports.
+
+        Returns:
+            True (events are created synchronously)
+        """
+        return True
+
+
+class _MetadataSpanProcessor(SpanProcessor):
+    """Span processor that adds metadata to all spans.
+
+    This allows users to attach custom metadata (e.g., customer_id, environment)
+    that will be included on every span exported.
+    """
+
+    def __init__(self, metadata: Dict[str, AttributeValue]):
+        """Initialize with metadata to attach.
+
+        Args:
+            metadata: Dictionary of metadata key-value pairs
+        """
+        self._metadata = metadata
+
+    def on_start(
+        self, span: Span, parent_context: Optional[otel_context.Context] = None
+    ) -> None:
+        """Called when a span is started - attach metadata."""
+        span.set_attributes(self._metadata)
+
+    def on_end(self, span: ReadableSpan) -> None:
+        """Called when a span ends - no action needed."""
+        pass
+
+    def shutdown(self) -> None:
+        """Shutdown the processor."""
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        """Force flush - no buffering in this processor."""
+        return True
+
+
+def setup_livekit(
+    client: "LucidicAI",
+    session_id: str,
+    session_name: Optional[str] = None,
+    metadata: Optional[Dict[str, AttributeValue]] = None,
+) -> "TracerProvider":
+    """Set up Lucidic tracing for LiveKit voice agents.
+
+    Automatically creates a Lucidic session and configures OpenTelemetry
+    to export LiveKit spans as Lucidic events.
+
+    Args:
+        client: Initialized LucidicAI client instance
+        session_id: Session ID for all events (typically ctx.room.name)
+        session_name: Optional human-readable session name
+        metadata: Optional metadata to attach to all spans (e.g., customer_id)
+
+    Returns:
+        TracerProvider to pass to livekit's set_tracer_provider()
+
+    Example:
+        from lucidicai import LucidicAI
+        from lucidicai.integrations.livekit import setup_livekit
+        from livekit.agents import AgentServer, JobContext, AgentSession, cli
+        from livekit.agents.telemetry import set_tracer_provider
+
+        client = LucidicAI(api_key="...", agent_id="...")
+        server = AgentServer()
+
+        @server.rtc_session()
+        async def entrypoint(ctx: JobContext):
+            trace_provider = setup_livekit(
+                client=client,
+                session_id=ctx.room.name,
+                session_name=f"Voice Call - {ctx.room.name}",
+            )
+            set_tracer_provider(trace_provider)
+
+            async def cleanup():
+                trace_provider.force_flush()
+            ctx.add_shutdown_callback(cleanup)
+
+            session = AgentSession(...)
+            await session.start(agent=MyAgent(), room=ctx.room)
+
+        if __name__ == "__main__":
+            cli.run_app(server)
+    """
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    # auto-create Lucidic session
+    client.sessions.create(
+        session_id=session_id,
+        session_name=session_name or f"LiveKit Voice Session - {session_id}",
+    )
+    logger.info(f"[LiveKit] Created Lucidic session: {session_id}")
+
+    # create exporter
+    exporter = LucidicLiveKitExporter(client, session_id)
+
+    # create tracer provider
+    trace_provider = TracerProvider()
+
+    # add metadata processor if metadata provided
+    if metadata:
+        trace_provider.add_span_processor(_MetadataSpanProcessor(metadata))
+
+    # add exporter via batch processor
+    trace_provider.add_span_processor(BatchSpanProcessor(exporter))
+
+    logger.info("[LiveKit] Lucidic tracing configured")
+    return trace_provider

{lucidicai-3.0.0 → lucidicai-3.3.1}/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 → lucidicai-3.3.1}/lucidicai.egg-info/PKG-INFO

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

{lucidicai-3.0.0 → lucidicai-3.3.1}/lucidicai.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ lucidicai/api/__init__.py
 lucidicai/api/client.py
 lucidicai/api/resources/__init__.py
 lucidicai/api/resources/dataset.py
+lucidicai/api/resources/evals.py
 lucidicai/api/resources/event.py
 lucidicai/api/resources/experiment.py
 lucidicai/api/resources/feature_flag.py
@@ -21,6 +22,8 @@ lucidicai/core/__init__.py
 lucidicai/core/config.py
 lucidicai/core/errors.py
 lucidicai/core/types.py
+lucidicai/integrations/__init__.py
+lucidicai/integrations/livekit.py
 lucidicai/sdk/__init__.py
 lucidicai/sdk/context.py
 lucidicai/sdk/decorators.py

{lucidicai-3.0.0 → lucidicai-3.3.1}/setup.py

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

lucidicai-3.0.0/lucidicai/api/resources/prompt.py

@@ -1,84 +0,0 @@
-"""Prompt resource API operations."""
-import logging
-from typing import Any, Dict, Optional
-
-from ..client import HttpClient
-
-logger = logging.getLogger("Lucidic")
-
-
-class PromptResource:
-    """Handle prompt-related API operations."""
-
-    def __init__(self, http: HttpClient, production: bool = False):
-        """Initialize prompt resource.
-
-        Args:
-            http: HTTP client instance
-            production: Whether to suppress errors in production mode
-        """
-        self.http = http
-        self._production = production
-
-    def get(
-        self,
-        prompt_name: str,
-        variables: Optional[Dict[str, Any]] = None,
-        label: str = "production",
-    ) -> str:
-        """Get a prompt from the prompt database.
-
-        Args:
-            prompt_name: Name of the prompt.
-            variables: Variables to interpolate into the prompt.
-            label: Prompt version label (default: "production").
-
-        Returns:
-            The prompt content with variables interpolated.
-        """
-        try:
-            response = self.http.get(
-                "getprompt",
-                {"prompt_name": prompt_name, "label": label},
-            )
-            prompt = response.get("prompt_content", "")
-
-            # Replace variables
-            if variables:
-                for key, value in variables.items():
-                    prompt = prompt.replace(f"{{{key}}}", str(value))
-
-            return prompt
-        except Exception as e:
-            if self._production:
-                logger.error(f"[PromptResource] Failed to get prompt: {e}")
-                return ""
-            raise
-
-    async def aget(
-        self,
-        prompt_name: str,
-        variables: Optional[Dict[str, Any]] = None,
-        label: str = "production",
-    ) -> str:
-        """Get a prompt from the prompt database (asynchronous).
-
-        See get() for full documentation.
-        """
-        try:
-            response = await self.http.aget(
-                "getprompt",
-                {"prompt_name": prompt_name, "label": label},
-            )
-            prompt = response.get("prompt_content", "")
-
-            if variables:
-                for key, value in variables.items():
-                    prompt = prompt.replace(f"{{{key}}}", str(value))
-
-            return prompt
-        except Exception as e:
-            if self._production:
-                logger.error(f"[PromptResource] Failed to get prompt: {e}")
-                return ""
-            raise