lucidicai 1.3.1__tar.gz → 1.3.5__tar.gz

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

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

{lucidicai-1.3.1 → 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