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 accountauth.signIn(credentials)- Authenticate existing userauth.refreshToken(refreshToken)- Refresh access tokenauth.signOut()- Sign out current user
Chat Methods#
chat(request)- Send chat message (non-streaming)streamChat(request)- Send chat message (streaming)getThreadHistory(threadId)- Retrieve conversation historycreateThread(options)- Create new conversation thread
Content Generation Methods#
generateLecture(request)- Generate educational lecturegenerateMeditation(request)- Generate guided meditationsynthesizeSpeech(request)- Convert text to speechstreamSynthesizeSpeech(request)- Streaming text-to-speech
Utility Methods#
getVoices()- List available TTS voicesgetPersonas()- List available AI personasgetUsageStats()- Get API usage statistics
Streaming Events#
Chat Stream Events#
token- Individual response tokencitations- Citation informationaudio- Audio metadata (if applicable)done- Stream completionerror- Error information
TTS Stream Events#
audio_chunk- Audio data chunkmetadata- Audio metadatacomplete- Generation completeerror- 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
fetchAPI - 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#
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- 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.