​
Core Concepts

The Lucidic AI TypeScript SDK uses the same hierarchical structure as the Python SDK to track your AI workflows.

​
Hierarchy Overview

Session
├── Step 1
│   ├── Event 1 (LLM call)
│   └── Event 2 (LLM call)
├── Step 2
│   ├── Event 3 (LLM call)
│   └── Event 4 (LLM call)
└── Step 3
    └── Event 5 (LLM call)

​
Sessions

A Session represents a complete AI workflow or conversation. It’s the top-level container for all tracking data.

​
Creating Sessions

// Option 1: Auto-create during init (ESM)
import OpenAI from 'openai';
await lai.init({
  sessionName: 'Customer Support Chat',
  task: 'Help user reset password',
  instrumentModules: { OpenAI }
});

// Option 2: Continue an existing session by ID (ESM)
import OpenAI from 'openai';
await lai.init({ sessionId: 'existing-session-id', instrumentModules: { OpenAI } });

​
Session Properties

interface InitParams {
  sessionName?: string;    // Human-readable name
  sessionId?: string;      // Continue existing session
  task?: string;           // What the session aims to achieve
  massSimId?: string;      // Optional mass simulation id
  experimentId?: string;   // Optional experiment id
  rubrics?: string[];      // optional rubrics to run
  tags?: string[];         // optional tags
}

​
Managing Sessions

// Update session
await lai.updateSession({
  task: 'Updated task description',
  tags: ['priority:high', 'category:support'],
  isSuccessful: true,
  isSuccessfulReason: 'Successfully resolved issue'
});

// End session
await lai.endSession({ isSuccessful: true, isSuccessfulReason: 'Task completed successfully' });

// Sessions are managed internally; use session context helpers when needed

​
Steps

Steps represent logical units of work within a session.

​
Creating Steps

const step = await lai.createStep();

​
Step Properties

interface StepConfig {
  state?: string;          // Current state/context
  action?: string;         // What the agent is doing
  goal?: string;           // What the agent aims to achieve
  evalScore?: number;      // Performance score (0-100)
  evalDescription?: string; // Explanation of score
}

​
Managing Steps

// Update current step
await lai.updateStep({ stepId: step.stepId, evalScore: 85, evalDescription: 'Partially complete' });

// End current step
await lai.endStep({ evalScore: 95, evalDescription: 'Success' });

// Steps are identified via IDs returned from createStep

​
Automatic Step Creation

If you make an LLM call without an active step, one is created automatically: 
// No step created yet
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});
// Lucidic auto-creates a step for this call

​
Events

Events represent individual operations within steps - typically LLM API calls.

​
Automatic Event Creation

When using instrumented providers, events are created automatically: 
// This OpenAI call automatically creates an event
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Explain quantum computing' }]
});

// Event captures:
// - Input messages
// - Model used
// - Response content
// - Token usage
// - Cost
// - Timing

​
Manual Event Creation

For custom tracking or unsupported providers: 
const event = await lai.createEvent({
  description: 'Custom LLM call',
  result: 'Model response here',
  model: 'custom-model-v1',
  costAdded: 0.05
});

// Update event
await lai.updateEvent(
  event.eventId,
  'Updated response',
  true,   // isFinished
  0.02,   // additional cost
  'custom-model-v2'
);

​
Event Properties

interface EventConfig {
  description?: string;    // Event description/input
  result?: string;         // Output/response
  model?: string;          // Model name
  costAdded?: number;      // Cost in USD
}

​
Automatic Behaviors

The TypeScript SDK includes several automatic features:

​
1. Auto Session Ending

Sessions automatically end when the process exits: 
await lai.init({ providers: ['openai'] });
// Do work...
// No need to call endSession() - happens automatically

​
2. Auto Step Ending

Active steps are automatically ended when the session ends.

​
3. Auto Event Creation

LLM calls from instrumented providers create events automatically: 
// Just make the call - event is created automatically
await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

​
Best Practices

​
1. Prefer withLucidic for Self-Contained Workflows

Use withLucidic for one-shot tasks that should end when work finishes. See Session Context.

​
2. Consistent Evaluation

// Define clear scoring criteria
const score = calculateScore(results);
await lai.endStep(
  score,
  score >= 90 ? 'Excellent performance' :
  score >= 70 ? 'Good performance' :
  'Needs improvement'
);

​
3. Error Handling

try {
  await lai.createStep();
  // Do work...
  await lai.endStep({ evalScore: 100, evalDescription: 'Success' });
} catch (error) {
  await lai.endStep({ evalScore: 0, evalDescription: `Error: ${error.message}` });
  throw error;
}

​
Next Steps