​
Installation & Setup

This guide will walk you through installing and configuring the Lucidic AI TypeScript SDK.

​
Prerequisites

  • Node.js version 18 or higher
  • TypeScript version 5.x (recommended)
  • A Lucidic account with API key and Agent ID — see Dashboard setup
Please refer to Dashboard Setup to create your account and API key

​
Install the SDK

​
Using npm

npm install lucidicai

​
Using yarn

yarn add lucidicai

​
Configuration

​
Environment Variables

Create a .env file in your project root: 
LUCIDIC_API_KEY=your-api-key
LUCIDIC_AGENT_ID=your-agent-id

​
TypeScript Configuration

If using TypeScript, ensure your tsconfig.json includes: 
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

​
Basic Setup

​
TypeScript/ES Modules

import * as lai from 'lucidicai';
import OpenAI from 'openai';
import { Anthropic } from '@anthropic-ai/sdk';

async function main() {
  // Initialize with manual instrumentation (ESM-friendly)
  await lai.init({
    instrumentModules: { OpenAI, Anthropic },
  });

  const openai = new OpenAI();
  // Your code here...
}

main().catch(console.error);

​
CommonJS

const lai = require('lucidicai');

async function main() {
  // Dynamically import provider modules first
  const { default: OpenAI } = await import('openai');
  const { Anthropic } = await import('@anthropic-ai/sdk');

  // Initialize and pass module references for instrumentation
  await lai.init({
    apiKey: 'your-api-key',
    agentId: 'your-agent-id',
    sessionName: 'My Session',
    instrumentModules: { OpenAI, Anthropic }
  });

  const openai = new OpenAI();
  // Your code here...
}

main().catch(console.error);

​
Initialization Options

interface InitParams {
  // Authentication
  apiKey?: string;           // Defaults to LUCIDIC_API_KEY env var
  agentId?: string;          // Defaults to LUCIDIC_AGENT_ID env var

  // Session Configuration
  sessionName?: string;      // Auto-create session with this name
  sessionId?: string;        // Continue existing session
  task?: string;             // Session task description
  massSimId?: string;        // Optional mass simulation association
  experimentId?: string;     // Optional experiment association
  rubrics?: string[];
  tags?: string[];

  // Provider Configuration
  providers?: Array<'openai'|'anthropic'|'langchain'>;
  instrumentModules?: Record<string, any>; // ESM manual modules: { OpenAI, Anthropic, LangChain }

  // Advanced Options
  maskingFunction?: (text: string) => string;  // Data masking
  autoEnd?: boolean;                           // Default true (env overridable)
  useSpanProcessor?: boolean;                  // Force simple span processor (unbatched)
}

​
Minimal Setup

The absolute minimum setup requires just 2 lines: 
import * as lai from 'lucidicai';
import OpenAI from 'openai';
await lai.init({ instrumentModules: { OpenAI } });

// That's it! All OpenAI calls are now tracked

​
Provider Setup

​
OpenAI

import OpenAI from 'openai';
await lai.init({ instrumentModules: { OpenAI } });

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

​
Anthropic

import { Anthropic } from '@anthropic-ai/sdk';
await lai.init({ instrumentModules: { anthropic: Anthropic } });

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});

​
Verify Installation

Run this test script to verify everything is working: 
import * as lai from 'lucidicai';

async function verifyInstallation() {
  try {
    // Initialize SDK
    const sessionId = await lai.init({ sessionName: 'Installation Test' });
    
    console.log('SDK initialized successfully');
    console.log(`Session ID: ${sessionId}`);
    
    // Import OpenAI
    import OpenAI from 'openai';
    const openai = new OpenAI();
    
    // Create a step
    await lai.createStep({
      state: 'Testing',
      goal: 'Verify installation'
    });
    
    // Make a test call
    const response = await openai.chat.completions.create({
      model: 'gpt-3.5-turbo',
      messages: [{ role: 'user', content: 'Say "Installation successful!"' }]
    });
    
    console.log('OpenAI call tracked successfully');
    console.log(`Response: ${response.choices[0].message.content}`);
    
    // End session
    await lai.endSession({ isSuccessful: true, isSuccessfulReason: 'Installation verified' });
    console.log('Installation verification complete!');
    
  } catch (error) {
    console.error('Installation verification failed:', error);
  }
}

verifyInstallation();

​
Next Steps