Python SDK Functions

​

Overview

​

Installation

pip install lucidicai

​

Quick Start

import lucidicai as lai

# Initialize a session
lai.init(session_name="My AI Agent", providers=["openai"])

# Create a step
lai.create_step(state="Processing", action="Generate response")

# Your AI operations are automatically tracked
# ...

# End the step and session
lai.end_step()
lai.end_session()

# Recommended: self-contained session using a context manager
with lai.session(session_name="My AI Agent 2", providers=["openai"]):
    # Your AI operations are automatically tracked
    lai.create_step()
    # ... your logic ...
    lai.end_step()

​

Session Management

​

Step Management

​

Event Management

​

Advanced Features

​

Decorators

​

Context Managers

​

Function Categories

​

Session Lifecycle

1. Initialization: Use init() to start a new session or resume with init(session_id=...)
2. Updates: Modify session data with update_session()
3. Completion: End with end_session() including final evaluation

​

Step Management

1. Creation: Use create_step() to begin tracking a unit of work
2. Progress: Update step data with update_step()
3. Completion: Finish with end_step() including evaluation
4. Decorators: Use @step decorator for automatic management

​

Event Tracking

1. Automatic: LLM calls through instrumented providers create events automatically
2. Manual: Use create_event() for custom events
3. Updates: Modify events with update_event() and end_event()
4. Decorators: Use @event decorator for function-level tracking

​

Utilities

1. Prompts: Centralized prompt management with get_prompt()
2. Mass Simulations: Batch operations with create_mass_sim()

​

Context Managers

• session(...) — full lifecycle within a context
• session_async(...) — async variant
• bind_session(session_id) — bind only (no end)
• bind_session_async(session_id) — async variant
• run_session(fn, init_params, ...) — run a function within a new session
• run_in_session(session_id, fn, ...) — run a function in an existing session
• set_active_session(session_id) / clear_active_session() — manual control

​

Decorators

1. @step: Wrap functions with automatic step tracking
2. @event: Create events from function calls automatically

​

Provider Support

• OpenAI - providers=["openai"]
• Anthropic - providers=["anthropic"]
• LangChain - providers=["langchain"]
• PydanticAI - providers=["pydantic_ai"]
• OpenAI Agents - providers=["openai_agents"]
• LiteLLM - providers=["litellm"] (tracks many providers via LiteLLM)

​

Integration Guides

• LiteLLM — bridge LiteLLM to Lucidic events

​

Best Practices

1. Prefer Context Managers: Use with lai.session(...) for self-sufficient workflows that start and end within one block
2. Bind Existing Sessions: Use with lai.bind_session(session_id) to attribute work to an existing session without ending it
3. Concurrent Safety: Rely on context-bound sessions instead of globals in multi-threaded/async code
4. Ensure Cleanup: Context managers handle cleanup; otherwise call lai.end_session() explicitly when not using contexts
5. Evaluation Tracking: Use eval_score and eval_description on steps where helpful; avoid manual overrides at scale

​

Error Handling

from lucidicai.errors import (
    APIKeyVerificationError,
    InvalidOperationError,
    LucidicNotInitializedError,
    PromptError
)

try:
    lai.init(session_name="My Session")
except APIKeyVerificationError:
    print("Check your API credentials")
except InvalidOperationError:
    print("Session already active")

​

Environment Variables

• LUCIDIC_API_KEY - Your API key for authentication
• LUCIDIC_AGENT_ID - Your agent identifier
• LUCIDIC_PRODUCTION_MONITORING - Enable production mode
• LUCIDIC_AUTO_END - Control automatic session ending

​

See Also

• Getting Started Guide
• Core Concepts
• Integration Examples