lucidicai 1.3.2__tar.gz → 1.3.5__tar.gz

{lucidicai-1.3.2 → lucidicai-1.3.5}/PKG-INFO

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

{lucidicai-1.3.2 → lucidicai-1.3.5}/README.md

@@ -5,7 +5,7 @@ The official Python SDK for [Lucidic AI](https://lucidic.ai), providing comprehe
 ## Features
 
 - **Session & Step Tracking** - Track complex AI agent workflows with hierarchical session management
-- **Multi-Provider Support** - Automatic instrumentation for OpenAI, Anthropic, LangChain, and more
+- **Multi-Provider Support** - Automatic instrumentation for OpenAI, Anthropic, LangChain, Google Generative AI (Gemini), Vertex AI, AWS Bedrock, Cohere, Groq, and more
 - **Real-time Analytics** - Monitor costs, performance, and behavior of your AI applications
 - **Data Privacy** - Built-in masking functions to protect sensitive information
 - **Screenshot Support** - Capture and analyze visual context in your AI workflows
@@ -49,6 +49,21 @@ lai.end_step()
 lai.end_session(is_successful=True)
 ```
 
+### Quick Start (context manager)
+
+```python
+import lucidicai as lai
+from openai import OpenAI
+
+# All-in-one lifecycle: init → bind → run → auto-end at context exit
+with lai.session(session_name="My AI Assistant", providers=["openai"]):
+    client = OpenAI()
+    response = client.chat.completions.create(
+        model="gpt-5",
+        messages=[{"role": "user", "content": "Hello, how are you?"}]
+    )
+```
+
 ## Configuration
 
 ### Environment Variables
@@ -67,7 +82,7 @@ lai.init(
     session_name="My Session",              # Required: Name for this session
     api_key="...",                 # Optional: Override env var
     agent_id="...",                        # Optional: Override env var
-    providers=["openai", "anthropic"],     # Optional: LLM providers to track
+    providers=["openai", "anthropic", "google", "vertexai", "bedrock", "cohere", "groq"],     # Optional: LLM providers to track
     task="Process customer request",       # Optional: High-level task description
     production_monitoring=False,           # Optional: Production mode flag
     auto_end=True,                         # Optional: Auto-end session on exit (default: True)
@@ -100,6 +115,109 @@ lai.update_session(
 lai.end_session(is_successful=True, session_eval=0.9)
 ```
 
+### Session Context (async-safe)
+
+Lucidic uses Python contextvars to bind a session to the current execution context (threads/async tasks). This guarantees spans from concurrent requests are attributed to the correct session.
+
+There are three recommended patterns:
+
+1) Full lifecycle (auto-end on exit)
+
+```python
+import lucidicai as lai
+from openai import OpenAI
+
+with lai.session(session_name="order-flow", providers=["openai"]):
+    OpenAI().chat.completions.create(
+        model="gpt-5",
+        messages=[{"role":"user","content":"Place order"}]
+    )
+# Session automatically ends at context exit.
+# Note: any auto_end argument is ignored inside session(...).
+```
+
+Async variant:
+
+```python
+import lucidicai as lai
+from openai import AsyncOpenAI
+import asyncio
+
+async def main():
+    async with lai.session_async(session_name="async-flow", providers=["openai"]):
+        await AsyncOpenAI().chat.completions.create(
+            model="gpt-5",
+            messages=[{"role":"user","content":"Hello"}]
+        )
+
+asyncio.run(main())
+```
+
+2) Bind-only (does NOT end the session)
+
+```python
+import lucidicai as lai
+from openai import OpenAI
+
+sid = lai.init(session_name="request-123", providers=["openai"], auto_end=False)
+with lai.bind_session(sid):
+    OpenAI().chat.completions.create(
+        model="gpt-5",
+        messages=[{"role":"user","content":"..."}]
+    )
+# Session remains open. End explicitly when ready:
+lai.end_session()
+```
+
+Async variant:
+
+```python
+sid = lai.init(session_name="request-async", providers=["openai"], auto_end=False)
+
+async def run():
+    async with lai.bind_session_async(sid):
+        await AsyncOpenAI().chat.completions.create(
+            model="gpt-5",
+            messages=[{"role":"user","content":"..."}]
+        )
+
+asyncio.run(run())
+# End later
+lai.end_session()
+```
+
+3) Fully manual
+
+```python
+sid = lai.init(session_name="manual", providers=["openai"], auto_end=True)
+lai.set_active_session(sid)
+# ... your workflow ...
+lai.clear_active_session()
+# End now, or rely on auto_end at process exit
+lai.end_session()
+```
+
+Function wrappers are also provided:
+
+```python
+def do_work():
+    from openai import OpenAI
+    return OpenAI().chat.completions.create(model="gpt-5", messages=[{"role":"user","content":"wrapped"}])
+
+# Full lifecycle in one call
+result = lai.run_session(do_work, init_params={"session_name":"wrapped","providers":["openai"]})
+
+# Bind-only wrapper
+sid = lai.init(session_name="bound-only", providers=["openai"], auto_end=False)
+result = lai.run_in_session(sid, do_work)
+lai.end_session()
+```
+
+Notes:
+- The context managers are safe for threads and asyncio tasks.
+- `session(...)` always ends the session at context exit (ignores any provided auto_end).
+- Existing single-threaded usage (plain `init` + provider calls) remains supported.
+
 ### Automatic Session Management (auto_end)
 
 By default, Lucidic automatically ends your session when your process exits, ensuring no data is lost. This feature is enabled by default but can be controlled:
@@ -118,6 +236,8 @@ The auto_end feature:
 - Prevents data loss from forgotten `end_session()` calls
 - Can be disabled for cases where you need explicit control
 
+When using `session(...)` or `session_async(...)`, the session will end at context exit regardless of the `auto_end` setting. A debug warning is logged if `auto_end` is provided in that context.
+
 ### Steps
 Steps break down complex workflows into discrete, trackable units.
 
@@ -199,6 +319,65 @@ llm = ChatOpenAI(model="gpt-4")
 response = llm.invoke([HumanMessage(content="Hello!")])
 ```
 
+### Google Generative AI (Gemini)
+```python
+import google.generativeai as genai
+
+lai.init(session_name="Gemini Example", providers=["google"])  # or "google_generativeai"
+genai.configure(api_key=os.getenv("GOOGLE_API_KEY"))
+
+model = genai.GenerativeModel("gemini-1.5-flash")
+resp = model.generate_content("Write a haiku about clouds")
+```
+
+### Vertex AI
+```python
+from google.cloud import aiplatform
+from vertexai.generative_models import GenerativeModel
+
+lai.init(session_name="Vertex Example", providers=["vertexai"])  # or "vertex_ai"
+aiplatform.init(project=os.getenv("GCP_PROJECT"), location=os.getenv("GCP_REGION", "us-central1"))
+
+model = GenerativeModel("gemini-1.5-flash")
+resp = model.generate_content("Say hello")
+```
+
+### AWS Bedrock
+```python
+import boto3
+
+lai.init(session_name="Bedrock Example", providers=["bedrock"])  # or "aws_bedrock", "amazon_bedrock"
+client = boto3.client("bedrock-runtime", region_name=os.getenv("AWS_REGION", "us-east-1"))
+
+resp = client.invoke_model(
+    modelId=os.getenv("BEDROCK_MODEL_ID", "amazon.nova-lite-v1:0"),
+    body=b'{"inputText": "Hello from Bedrock"}',
+    contentType="application/json",
+    accept="application/json",
+)
+```
+
+### Cohere
+```python
+import cohere
+
+lai.init(session_name="Cohere Example", providers=["cohere"])
+co = cohere.ClientV2(api_key=os.getenv("COHERE_API_KEY"))
+resp = co.chat(model="command-r", messages=[{"role":"user","content":"Hello"}])
+```
+
+### Groq
+```python
+from groq import Groq
+
+lai.init(session_name="Groq Example", providers=["groq"])
+client = Groq(api_key=os.getenv("GROQ_API_KEY"))
+resp = client.chat.completions.create(
+    model="llama-3.1-8b-instant",
+    messages=[{"role":"user","content":"Hello from Groq"}],
+)
+```
+
 ## Advanced Features
 
 ### Decorators
@@ -399,6 +578,57 @@ except LucidicNotInitializedError:
     print("SDK not initialized - call lai.init() first")
 ```
 
+## Crash events on uncaught exceptions
+
+When the SDK is initialized, Lucidic will capture uncaught exceptions and create a final crash event before the process exits. This is enabled by default and requires no additional configuration.
+
+### Behavior
+
+- On an uncaught exception (main thread):
+  - A Lucidic event is created and linked to the active session.
+  - The event description contains the full Python traceback. If a `masking_function` was provided to `lai.init()`, it is applied; long descriptions are truncated to ~16K characters.
+  - The event result is set to: "process exited with code 1".
+  - The session is ended as unsuccessful with reason `uncaughtException` (independent of `auto_end`).
+  - The telemetry provider is best-effort flushed and shut down.
+  - Python’s default exit behavior is preserved (exit code 1 and default exception printing).
+
+- On signals (`SIGINT`, `SIGTERM`):
+  - A final event is created with a description that includes the signal name and a best-effort stack snapshot.
+  - The event result is set to: `"process exited with code <128+signum>"` (e.g., 130 for SIGINT, 143 for SIGTERM).
+  - Existing auto-end and telemetry cleanup run, and default signal semantics are preserved.
+
+### Configuration
+
+- Enabled by default after `lai.init(...)`. To opt out:
+
+```python
+import lucidicai as lai
+
+lai.init(
+    session_name="my-session",
+    capture_uncaught=False,  # disables crash event capture
+)
+```
+
+This behavior is independent of `auto_end`; even when `auto_end` is `False`, the SDK will end the session as unsuccessful in this fatal path.
+
+### Caveats and lifecycle notes
+
+- Multiple handlers and ordering:
+  - If other libraries register their own handlers, ordering can affect which path runs first. Lucidic guards against duplication, but if another handler exits the process earlier, the crash event may not complete.
+
+- Main-thread semantics:
+  - Only uncaught exceptions on the main thread are treated as process-ending. Exceptions in worker threads do not exit the process by default and are not recorded as crash events by this mechanism.
+
+- Best-effort transport:
+  - Network issues or abrupt termination (e.g., forced container kill, `os._exit`) can prevent event delivery despite best efforts.
+
+- Exit semantics:
+  - We do not call `sys.exit(1)` from the handler; Python already exits with code 1 for uncaught exceptions, and default printing is preserved by chaining to the original `sys.excepthook`.
+
+- Not intercepted:
+  - `SystemExit` raised explicitly (e.g., `sys.exit(...)`) and `os._exit(...)` calls are not treated as uncaught exceptions and will not produce a crash event.
+
 ## Best Practices
 
 1. **Initialize Once**: Call `lai.init()` at the start of your application or workflow

{lucidicai-1.3.2 → lucidicai-1.3.5}/lucidicai/__init__.py

@@ -2,6 +2,9 @@ import atexit
 import logging
 import os
 import signal
+import sys
+import traceback
+import threading
 from typing import List, Literal, Optional
 
 from .client import Client
@@ -25,8 +28,35 @@ from .telemetry.otel_init import LucidicTelemetry
 
 # Import decorators
 from .decorators import step, event
+from .context import (
+    set_active_session,
+    bind_session,
+    bind_session_async,
+    clear_active_session,
+    current_session_id,
+    session,
+    session_async,
+    run_session,
+    run_in_session,
+)
 
-ProviderType = Literal["openai", "anthropic", "langchain", "pydantic_ai", "openai_agents", "litellm"]
+ProviderType = Literal[
+    "openai",
+    "anthropic",
+    "langchain",
+    "pydantic_ai",
+    "openai_agents",
+    "litellm",
+    "bedrock",
+    "aws_bedrock",
+    "amazon_bedrock",
+    "google",
+    "google_generativeai",
+    "vertexai",
+    "vertex_ai",
+    "cohere",
+    "groq",
+]
 
 # Configure logging
 logger = logging.getLogger("Lucidic")
@@ -38,6 +68,137 @@ if not logger.handlers:
     logger.setLevel(logging.INFO)
 
 
+# Crash/exit capture configuration
+MAX_ERROR_DESCRIPTION_LENGTH = 16384
+_crash_handlers_installed = False
+_original_sys_excepthook = None
+_original_threading_excepthook = None
+_shutdown_lock = threading.Lock()
+_is_shutting_down = False
+
+
+def _mask_and_truncate(text: Optional[str]) -> Optional[str]:
+    """Apply masking and truncate to a safe length. Best effort; never raises."""
+    if text is None:
+        return text
+    try:
+        masked = Client().mask(text)
+    except Exception:
+        masked = text
+    if masked is None:
+        return masked
+    return masked[:MAX_ERROR_DESCRIPTION_LENGTH]
+
+
+def _post_fatal_event(exit_code: int, description: str, extra: Optional[dict] = None) -> None:
+    """Best-effort creation of a final Lucidic event on fatal paths.
+
+    - Idempotent using a process-wide shutdown flag to avoid duplicates when
+      multiple hooks fire (signal + excepthook).
+    - Swallows all exceptions to avoid interfering with shutdown.
+    """
+    global _is_shutting_down
+    with _shutdown_lock:
+        if _is_shutting_down:
+            return
+        _is_shutting_down = True
+    try:
+        client = Client()
+        session = getattr(client, 'session', None)
+        if not session or getattr(session, 'is_finished', False):
+            return
+        arguments = {"exit_code": exit_code}
+        if extra:
+            try:
+                arguments.update(extra)
+            except Exception:
+                pass
+
+        event_id = session.create_event(
+            description=_mask_and_truncate(description),
+            result=f"process exited with code {exit_code}",
+            function_name="__process_exit__",
+            arguments=arguments,
+        )
+        session.update_event(event_id=event_id, is_finished=True)
+    except Exception:
+        # Never raise during shutdown
+        pass
+
+
+def _install_crash_handlers() -> None:
+    """Install global uncaught exception handlers (idempotent)."""
+    global _crash_handlers_installed, _original_sys_excepthook, _original_threading_excepthook
+    if _crash_handlers_installed:
+        return
+
+    _original_sys_excepthook = sys.excepthook
+
+    def _sys_hook(exc_type, exc, tb):
+        try:
+            trace_str = ''.join(traceback.format_exception(exc_type, exc, tb))
+        except Exception:
+            trace_str = f"Uncaught exception: {getattr(exc_type, '__name__', str(exc_type))}: {exc}"
+
+        # Emit final event and end the session as unsuccessful
+        _post_fatal_event(1, trace_str, {
+            "exception_type": getattr(exc_type, "__name__", str(exc_type)),
+            "exception_message": str(exc),
+            "thread_name": threading.current_thread().name,
+        })
+        try:
+            # Prevent auto_end double work
+            client = Client()
+            try:
+                client.auto_end = False
+            except Exception:
+                pass
+            # End session explicitly as unsuccessful
+            end_session()
+        except Exception:
+            pass
+        # Best-effort force flush and shutdown telemetry
+        try:
+            telemetry = LucidicTelemetry()
+            if telemetry.is_initialized():
+                try:
+                    telemetry.force_flush()
+                except Exception:
+                    pass
+                try:
+                    telemetry.uninstrument_all()
+                except Exception:
+                    pass
+        except Exception:
+            pass
+        # Chain to original to preserve default printing/behavior
+        try:
+            _original_sys_excepthook(exc_type, exc, tb)
+        except Exception:
+            # Avoid recursion/errors in fatal path
+            pass
+
+    sys.excepthook = _sys_hook
+
+    # For Python 3.8+, only treat main-thread exceptions as fatal (process-exiting)
+    if hasattr(threading, 'excepthook'):
+        _original_threading_excepthook = threading.excepthook
+
+        def _thread_hook(args):
+            try:
+                if args.thread is threading.main_thread():
+                    _sys_hook(args.exc_type, args.exc_value, args.exc_traceback)
+            except Exception:
+                pass
+            try:
+                _original_threading_excepthook(args)
+            except Exception:
+                pass
+
+        threading.excepthook = _thread_hook
+
+    _crash_handlers_installed = True
+
 def _setup_providers(client: Client, providers: List[ProviderType]) -> None:
     """Set up providers for the client, avoiding duplication
     
@@ -81,6 +242,26 @@ def _setup_providers(client: Client, providers: List[ProviderType]) -> None:
         elif provider == "litellm":
             client.set_provider(OTelLiteLLMHandler())
             setup_providers.add("litellm")
+        elif provider in ("bedrock", "aws_bedrock", "amazon_bedrock"):
+            from .telemetry.otel_handlers import OTelBedrockHandler
+            client.set_provider(OTelBedrockHandler())
+            setup_providers.add("bedrock")
+        elif provider in ("google", "google_generativeai"):
+            from .telemetry.otel_handlers import OTelGoogleGenerativeAIHandler
+            client.set_provider(OTelGoogleGenerativeAIHandler())
+            setup_providers.add("google")
+        elif provider in ("vertexai", "vertex_ai"):
+            from .telemetry.otel_handlers import OTelVertexAIHandler
+            client.set_provider(OTelVertexAIHandler())
+            setup_providers.add("vertexai")
+        elif provider == "cohere":
+            from .telemetry.otel_handlers import OTelCohereHandler
+            client.set_provider(OTelCohereHandler())
+            setup_providers.add("cohere")
+        elif provider == "groq":
+            from .telemetry.otel_handlers import OTelGroqHandler
+            client.set_provider(OTelGroqHandler())
+            setup_providers.add("groq")
 
 __all__ = [
     'Client',
@@ -105,6 +286,14 @@ __all__ = [
     'InvalidOperationError',
     'step',
     'event',
+    'set_active_session',
+    'bind_session',
+    'bind_session_async',
+    'clear_active_session',
+    'session',
+    'session_async',
+    'run_session',
+    'run_in_session',
 ]
 
 
@@ -122,6 +311,7 @@ def init(
     tags: Optional[list] = None,
     masking_function = None,
     auto_end: Optional[bool] = True,
+    capture_uncaught: Optional[bool] = True,
 ) -> str:
     """
     Initialize the Lucidic client.
@@ -189,6 +379,17 @@ def init(
     
     # Set the auto_end flag on the client
     client.auto_end = auto_end
+    # Bind this session id to the current execution context for async-safety
+    try:
+        set_active_session(real_session_id)
+    except Exception:
+        pass
+    # Install crash handlers unless explicitly disabled
+    try:
+        if capture_uncaught:
+            _install_crash_handlers()
+    except Exception:
+        pass
     
     logger.info("Session initialized successfully")
     return real_session_id
@@ -232,6 +433,11 @@ def continue_session(
     client.auto_end = auto_end
     
     logger.info(f"Session {session_id} continuing...")
+    # Bind this session id to the current execution context for async-safety
+    try:
+        set_active_session(session_id)
+    except Exception:
+        pass
     return session_id  # For consistency
 
 
@@ -252,10 +458,20 @@ def update_session(
         is_successful: Whether the session was successful.
         is_successful_reason: Session success reason.
     """
+    # Prefer context-bound session over global active session
     client = Client()
-    if not client.session:
+    target_sid = None
+    try:
+        target_sid = current_session_id.get(None)
+    except Exception:
+        target_sid = None
+    if not target_sid and client.session:
+        target_sid = client.session.session_id
+    if not target_sid:
         return
-    client.session.update_session(**locals())
+    # Use ephemeral session facade to avoid mutating global state
+    session = client.session if (client.session and client.session.session_id == target_sid) else Session(agent_id=client.agent_id, session_id=target_sid)
+    session.update_session(**locals())
 
 
 def end_session(
@@ -274,17 +490,31 @@ def end_session(
         is_successful_reason: Session success reason.
     """
     client = Client()
-    if not client.session:
+    # Prefer context-bound session id
+    target_sid = None
+    try:
+        target_sid = current_session_id.get(None)
+    except Exception:
+        target_sid = None
+    if not target_sid and client.session:
+        target_sid = client.session.session_id
+    if not target_sid:
         return
-    
-    # Wait for any pending LiteLLM callbacks before ending session
-    for provider in client.providers:
-        if hasattr(provider, '_callback') and hasattr(provider._callback, 'wait_for_pending_callbacks'):
-            logger.info("Waiting for LiteLLM callbacks to complete before ending session...")
-            provider._callback.wait_for_pending_callbacks(timeout=5.0)
-    
-    client.session.update_session(is_finished=True, **locals())
-    client.clear()
+
+    # If ending the globally active session, keep existing cleanup behavior
+    if client.session and client.session.session_id == target_sid:
+        # Wait for any pending LiteLLM callbacks before ending session
+        for provider in client.providers:
+            if hasattr(provider, '_callback') and hasattr(provider._callback, 'wait_for_pending_callbacks'):
+                logger.info("Waiting for LiteLLM callbacks to complete before ending session...")
+                provider._callback.wait_for_pending_callbacks(timeout=5.0)
+        client.session.update_session(is_finished=True, **locals())
+        client.clear()
+        return
+
+    # Otherwise, end the specified session id without clearing global state
+    temp = Session(agent_id=client.agent_id, session_id=target_sid)
+    temp.update_session(is_finished=True, **locals())
 
 
 def reset_sdk() -> None:
@@ -330,6 +560,20 @@ def _auto_end_session():
 
 def _signal_handler(signum, frame):
     """Handle interruption signals"""
+    # Best-effort final event for signal exits
+    try:
+        try:
+            name = signal.Signals(signum).name
+        except Exception:
+            name = str(signum)
+        try:
+            stack_str = ''.join(traceback.format_stack(frame)) if frame else ''
+        except Exception:
+            stack_str = ''
+        desc = _mask_and_truncate(f"Received signal {name}\n{stack_str}")
+        _post_fatal_event(128 + signum, desc, {"signal": name, "signum": signum})
+    except Exception:
+        pass
     _auto_end_session()
     _cleanup_telemetry()
     # Re-raise the signal for default handling

{lucidicai-1.3.2 → lucidicai-1.3.5}/lucidicai/client.py

@@ -69,6 +69,10 @@ class Client:
 
     def set_provider(self, provider: BaseProvider) -> None:
         """Set the LLM provider to track"""
+        # Avoid duplicate provider registration of the same class
+        for existing in self.providers:
+            if type(existing) is type(provider):
+                return
         self.providers.append(provider)
         provider.override()
 
@@ -134,6 +138,16 @@ class Client:
         self.initialized = True
         return self.session.session_id
 
+    def create_event_for_session(self, session_id: str, **kwargs) -> str:
+        """Create an event for a specific session id without mutating global session.
+
+        This avoids cross-thread races by not switching the active session on
+        the singleton client. It constructs an ephemeral Session facade to send
+        requests under the provided session id.
+        """
+        temp_session = Session(agent_id=self.agent_id, session_id=session_id)
+        return temp_session.create_event(**kwargs)
+
     def continue_session(self, session_id: str):
         if session_id in self.custom_session_id_translations:
             session_id = self.custom_session_id_translations[session_id]
@@ -149,7 +163,8 @@ class Client:
             agent_id=self.agent_id,
             session_id=real_session_id
         )
-        logger.info(f"Session {data.get('session_name', '')} continuing...")
+        import logging as _logging
+        _logging.getLogger('Lucidic').info(f"Session {data.get('session_name', '')} continuing...")
         return self.session.session_id
 
     def init_mass_sim(self, **kwargs) -> str: