​
Overview

The Lucidic Python SDK provides a comprehensive set of functions to track, monitor, and analyze AI agent workflows. These functions handle session management, step tracking, event logging, and integration with various LLM providers.

​
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()

​
Session Management

init

Initialize a new Lucidic session

continue_session

Continue an existing session

end_session

End the current session

update_session

Update session metadata

reset_sdk

Reset SDK to initial state

​
Step Management

create_step

Create a new step in the workflow

update_step

Update an existing step

end_step

End the current step

​
Event Management

create_event

Create a new event within a step

update_event

Update an existing event

end_event

End an event

​
Advanced Features

get_prompt

Retrieve prompts from the database

create_mass_sim

Create a mass simulation

​
Decorators

@step

Automatically wrap functions with step tracking

@event

Create events from function calls

​
Function Categories

​
Session Lifecycle

  1. Initialization: Use init() to start a new session or continue_session() to resume
  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()

​
Decorators

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

​
Provider Support

The SDK automatically instruments these providers when specified in init():
  • OpenAI - providers=["openai"]
  • Anthropic - providers=["anthropic"]
  • LangChain - providers=["langchain"]
  • PydanticAI - providers=["pydantic_ai"]
  • OpenAI Agents - providers=["openai_agents"]

​
Best Practices

  1. Always Initialize: Start with lai.init() before any other operations
  2. Proper Cleanup: End sessions and steps properly for accurate tracking
  3. Error Handling: Use try-finally blocks to ensure cleanup on errors
  4. Meaningful Metadata: Provide descriptive states, actions, and goals
  5. Evaluation Tracking: Include eval_score and descriptions for manual analysis if neeeded

​
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