@khaveeai/core

Core types, interfaces, and utilities for the KhaveeAI SDK. This package provides the foundational TypeScript definitions used across all KhaveeAI packages.

Installation

npm install @khaveeai/core

Features

• 📝 TypeScript Types - Complete type definitions for all SDK features
• 🎭 Provider Interfaces - Standard interfaces for LLM, TTS, and Realtime providers
• 🎬 Animation Types - Type-safe animation configuration
• 💬 Conversation Types - Structured conversation and message types
• 🔊 Audio Types - Phoneme, mouth state, and lip sync types

API Reference

Core Types

Audio & Lip Sync

import type { 
  PhonemeData,
  MouthState,
  AudioProvider 
} from '@khaveeai/core';

// Detected phoneme from audio analysis
interface PhonemeData {
  phoneme: 'aa' | 'ee' | 'ih' | 'ou' | 'oh' | 'sil'; // Detected sound
  intensity: number;        // 0-1 strength
  timestamp: number;        // Detection time
  duration: number;         // Phoneme duration (ms)
}

// VRM mouth shape state
interface MouthState {
  aa: number;  // Open mouth (0-1)
  ih: number;  // Smile (0-1)
  ou: number;  // Pucker (0-1)
  ee: number;  // Half open (0-1)
  oh: number;  // Round (0-1)
}

Conversation

import type { 
  Conversation,
  ChatStatus 
} from '@khaveeai/core';

// Message in conversation history
interface Conversation {
  id: string;
  role: 'user' | 'assistant' | 'system';
  text: string;
  timestamp: string;
  isFinal: boolean;
  status: 'speaking' | 'final' | 'thinking';
}

// Current chat state
type ChatStatus = 'stopped' | 'ready' | 'listening' | 'thinking' | 'speaking';

Realtime Provider

import type { 
  RealtimeProvider,
  RealtimeTool,
  RealtimeConfig 
} from '@khaveeai/core';

// Configuration for realtime voice providers
interface RealtimeConfig {
  apiKey: string;
  model?: string;
  voice?: string;
  instructions?: string;
  temperature?: number;
  tools?: RealtimeTool[];
  language?: string;
  turnServers?: RTCIceServer[];
}

// Custom function/tool for AI
interface RealtimeTool {
  name: string;
  description: string;
  parameters: Record<string, any>;
  execute: (args: any) => Promise<any>;
}

Provider Interfaces

import type { 
  LLMProvider,
  TTSProvider,
  VoiceProvider 
} from '@khaveeai/core';

// Base provider interfaces for extensibility
interface LLMProvider {
  generateResponse(prompt: string): Promise<string>;
}

interface TTSProvider {
  synthesize(text: string): Promise<AudioBuffer>;
}

interface VoiceProvider {
  startListening(): void;
  stopListening(): void;
}

Animation Types

import type { AnimationConfig } from '@khaveeai/core';

// Animation configuration for VRM avatars
type AnimationConfig = Record<string, string>;

// Example usage
const animations: AnimationConfig = {
  idle: '/animations/idle.fbx',
  walk: '/animations/walk.fbx',
  talking: '/animations/talking.fbx'
};

Usage

This package is typically used indirectly through other KhaveeAI packages, but you can import types directly:

import type { 
  PhonemeData,
  MouthState,
  Conversation,
  ChatStatus,
  RealtimeProvider,
  RealtimeTool
} from '@khaveeai/core';

// Use types for type-safe development
function handlePhoneme(phoneme: PhonemeData) {
  console.log(`Detected ${phoneme.phoneme} at ${phoneme.intensity}`);
}

function handleMessage(message: Conversation) {
  console.log(`${message.role}: ${message.text}`);
}

Package Structure

@khaveeai/core/
├── src/
│   ├── index.ts           # Main exports
│   ├── types/
│   │   ├── audio.ts       # Audio & lip sync types
│   │   ├── conversation.ts # Chat & message types
│   │   ├── providers.ts   # Provider interfaces
│   │   ├── realtime.ts    # Realtime API types
│   │   ├── qdrant.ts      # Vector DB types
│   │   └── index.ts       # Type exports
│   └── tools/
│       └── animate.ts     # Animation utilities

Dependencies

This is a types-only package with minimal dependencies:

{
  "peerDependencies": {
    "typescript": ">=4.5.0"
  }
}

TypeScript Configuration

For best experience, use these TypeScript settings:

{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "node"
  }
}

Contributing

We welcome contributions! Please see our Contributing Guide.

License

MIT © KhaveeAI