Eve library

@lilith/sdk

Other

Revision 1

On this page

A comprehensive TypeScript SDK for the Lilith AI Wisdom Platform. Works in browsers, Node.js 18+, and edge runtime environments with native fetch support.

Features#

  • πŸ” Authentication - JWT token management and secure API communication
  • πŸ’¬ Real-time Chat - Streaming and non-streaming chat with AI personas
  • 🎡 Text-to-Speech - High-quality voice synthesis with multiple voices
  • πŸ“š Lecture Generation - AI-powered content creation with citations
  • πŸ”„ Streaming Support - Server-Sent Events (SSE) for real-time responses
  • πŸ“¦ Type Safety - Full TypeScript support with comprehensive type definitions
  • 🌐 Universal - Works in browsers, Node.js, and edge environments
  • 🎯 Lightweight - Minimal dependencies with tree-shaking support

Installation#

Local Development (Current)#

This package is scaffolded in-repo; for local development:

bash
# Install dependencies
npm install

# Build the SDK
npm run build

# Use via relative path or npm link
import { APIClient } from './dist/index.js';

Future Published Package (TBD)#

bash
npm install @lilith/sdk

Quick Start#

Basic Setup#

typescript
import { APIClient } from '@lilith/sdk';

// Initialize the client
const api = new APIClient({
  baseUrl: 'https://api.lilith.ai',
  token: 'your-jwt-token-here',
});

Authentication#

typescript
import { APIClient } from '@lilith/sdk';

const api = new APIClient({
  baseUrl: 'https://api.lilith.ai',
});

// Sign up
const user = await api.auth.signUp({
  email: 'user@example.com',
  password: 'securePassword123',
  firstName: 'John',
  lastName: 'Doe',
});

// Sign in
const authResponse = await api.auth.signIn({
  email: 'user@example.com',
  password: 'securePassword123',
});

// Use the token for future requests
const authenticatedApi = new APIClient({
  baseUrl: 'https://api.lilith.ai',
  token: authResponse.access_token,
});

Chat Interactions#

Non-Streaming Chat#

typescript
const response = await api.chat({
  persona: 'zen_master',
  input: { text: 'How do I work with anger?' },
  mode: 'text',
  options: {
    stream: false,
    cite: true,
    temperature: 0.7,
    max_tokens: 1000,
  },
});

console.log(response.text);
console.log(response.citations); // Array of citations if requested

Streaming Chat (SSE)#

typescript
const chatStream = api.streamChat({
  persona: 'stoic_mentor',
  input: { text: 'A brief meditation practice, please.' },
  mode: 'text',
  options: {
    temperature: 0.8,
    stream: true,
  },
});

// Process streaming response
for await (const event of chatStream) {
  switch (event.event) {
    case 'token':
      // Individual token from the AI response
      process.stdout.write(event.data?.text ?? '');
      break;

    case 'citations':
      // Citations for the response
      console.log('Citations:', event.data);
      break;

    case 'audio':
      // Audio metadata (if audio generation enabled)
      console.log('Audio stream:', event.data);
      break;

    case 'done':
      // Streaming complete
      console.log('Response complete');
      break;

    case 'error':
      // Error occurred
      console.error('Error:', event.data);
      break;
  }
}

Voice Input#

typescript
// For voice input, you'll need to first convert speech to text
// Then send the text to chat
const voiceChatResponse = await api.chat({
  persona: 'meditation_guide',
  input: {
    text: transcribedText,
    audio_url: 'https://example.com/audio.wav', // Optional audio reference
  },
  mode: 'voice', // Enable voice-specific responses
  options: {
    stream: true,
    voice: 'calm_female_01',
  },
});

Content Generation#

Generate Lectures#

typescript
const lecture = await api.generateLecture({
  topic: 'Introduction to Mindfulness',
  duration_min: 10,
  tradition: ['Buddhism', 'Secular'],
  lang: 'en',
  voice: 'calm_male_01',
  outline_level: 'introductory',
  include_citations: true,
  target_audience: 'beginners',
});

console.log('Lecture generated:', lecture);
console.log('Audio stream URL:', lecture.stream_url);
console.log('Transcript:', lecture.transcript);

Generate Meditations#

typescript
const meditation = await api.generateMeditation({
  type: 'guided_meditation',
  duration_min: 5,
  tradition: 'vipassana',
  focus_area: 'breath_awareness',
  voice: 'calm_female_01',
  background_music: 'ambient_nature',
  include_affirmations: true,
});

console.log('Meditation script:', meditation.script);
console.log('Audio URL:', meditation.audio_url);

Text-to-Speech#

Basic TTS#

typescript
const ttsResponse = await api.synthesizeSpeech({
  text: 'Welcome to your meditation practice',
  voice: 'calm_female_01',
  format: 'mp3',
  speed: 1.0,
  pitch: 1.0,
});

console.log('Audio URL:', ttsResponse.audio_url);

Streaming TTS#

typescript
const ttsStream = api.streamSynthesizeSpeech({
  text: 'This is a longer text that will be streamed as audio',
  voice: 'calm_male_01',
  format: 'mp3',
});

// Process streaming audio chunks
for await (const event of ttsStream) {
  switch (event.event) {
    case 'audio_chunk':
      // Handle audio chunk data
      await playAudioChunk(event.data);
      break;
    case 'metadata':
      console.log('Audio metadata:', event.data);
      break;
    case 'complete':
      console.log('TTS generation complete');
      break;
    case 'error':
      console.error('TTS error:', event.data);
      break;
  }
}

Advanced Usage#

Custom Configuration#

typescript
const api = new APIClient({
  baseUrl: 'https://api.lilith.ai',
  token: 'your-jwt-token',
  timeout: 30000, // 30 seconds timeout
  retries: 3, // Number of retry attempts
  headers: {
    'X-Custom-Header': 'custom-value',
  },
});

Error Handling#

typescript
try {
  const response = await api.chat({
    persona: 'zen_master',
    input: { text: 'Your question here' },
  });
} catch (error) {
  if (error instanceof LilithAPIError) {
    switch (error.type) {
      case 'AuthenticationError':
        console.log('Please check your credentials');
        break;
      case 'RateLimitError':
        console.log('Rate limit exceeded. Please try again later.');
        break;
      case 'ValidationError':
        console.log('Invalid request:', error.details);
        break;
      case 'NetworkError':
        console.log('Network issue:', error.message);
        break;
      default:
        console.log('Unexpected error:', error.message);
    }
  }
}

Working with Different Personas#

typescript
// Available personas
const personas = [
  'zen_master',
  'stoic_mentor',
  'buddhist_monk',
  'yoga_instructor',
  'mindfulness_coach',
  'philosophy_professor',
];

// Use different personas for specific needs
const philosophicalResponse = await api.chat({
  persona: 'philosophy_professor',
  input: { text: 'What is the meaning of life according to existentialism?' },
});

const meditationGuidance = await api.chat({
  persona: 'mindfulness_coach',
  input: { text: "I'm having trouble staying focused during meditation" },
});

Content Customization#

typescript
const customizedLecture = await api.generateLecture({
  topic: 'The Four Noble Truths',
  duration_min: 15,
  tradition: ['Buddhism'],
  lang: 'en',
  voice: 'calm_female_01',
  outline_level: 'intermediate',
  include_citations: true,
  target_audience: 'intermediate',
  additional_context: {
    focus_areas: ['suffering', 'origin', 'cessation', 'path'],
    practical_applications: true,
    historical_context: false,
  },
});

API Reference#

Authentication Methods#

  • auth.signUp(userData) - Create new user account
  • auth.signIn(credentials) - Authenticate existing user
  • auth.refreshToken(refreshToken) - Refresh access token
  • auth.signOut() - Sign out current user

Chat Methods#

  • chat(request) - Send chat message (non-streaming)
  • streamChat(request) - Send chat message (streaming)
  • getThreadHistory(threadId) - Retrieve conversation history
  • createThread(options) - Create new conversation thread

Content Generation Methods#

  • generateLecture(request) - Generate educational lecture
  • generateMeditation(request) - Generate guided meditation
  • synthesizeSpeech(request) - Convert text to speech
  • streamSynthesizeSpeech(request) - Streaming text-to-speech

Utility Methods#

  • getVoices() - List available TTS voices
  • getPersonas() - List available AI personas
  • getUsageStats() - Get API usage statistics

Streaming Events#

Chat Stream Events#

  • token - Individual response token
  • citations - Citation information
  • audio - Audio metadata (if applicable)
  • done - Stream completion
  • error - Error information

TTS Stream Events#

  • audio_chunk - Audio data chunk
  • metadata - Audio metadata
  • complete - Generation complete
  • error - Error information

TypeScript Support#

The SDK includes comprehensive TypeScript types:

typescript
interface ChatRequest {
  persona: string;
  input: {
    text: string;
    audio_url?: string;
  };
  mode: 'text' | 'voice';
  options?: {
    stream?: boolean;
    cite?: boolean;
    temperature?: number;
    max_tokens?: number;
    voice?: string;
  };
}

interface ChatResponse {
  text: string;
  citations?: Citation[];
  metadata?: Record<string, any>;
}

interface Citation {
  source: string;
  title: string;
  url?: string;
  relevance_score: number;
}

Browser Support#

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Node.js Support#

  • Node.js 18.0+
  • Uses native fetch API
  • Compatible with CommonJS and ES modules

Environment Variables#

bash
# Optional environment variables
LILITH_API_BASE_URL=https://api.lilith.ai
LILITH_API_TIMEOUT=30000
LILITH_DEBUG=true

Examples#

See the examples/ directory for complete examples:

  • Basic chat application
  • Voice integration example
  • Lecture generation demo
  • Meditation guide application

Contributing#

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Submit a pull request

License#

This SDK is licensed under the MIT License.

Support#

  • GitHub Issues: https://github.com/lilith-ai/lilith-ts-sdk/issues
  • Documentation: https://docs.lilith.ai
  • Email: sdk-support@lilith.ai

Lilith Development Team Building the future of AI-powered wisdom and wellness.