@llmrtc/llmrtc-core 1.0.0

package/dist/tools.js

@@ -0,0 +1,157 @@
+/**
+ * Tool Types and Registry for LLM Tool Calling
+ *
+ * Provides provider-agnostic tool definitions that can be adapted
+ * to any LLM provider's tool calling format.
+ */
+// =============================================================================
+// Tool Registry
+// =============================================================================
+/**
+ * Registry for managing tool definitions and handlers
+ * Provides lookup by name and bulk operations
+ */
+export class ToolRegistry {
+    constructor() {
+        Object.defineProperty(this, "tools", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    /**
+     * Register a tool with its handler
+     * @throws Error if a tool with the same name is already registered
+     */
+    register(tool) {
+        const name = tool.definition.name;
+        if (this.tools.has(name)) {
+            throw new Error(`Tool '${name}' is already registered`);
+        }
+        this.tools.set(name, tool);
+        return this;
+    }
+    /**
+     * Register multiple tools at once
+     * @throws Error if any tool name conflicts
+     */
+    registerAll(tools) {
+        for (const tool of tools) {
+            this.register(tool);
+        }
+        return this;
+    }
+    /**
+     * Unregister a tool by name
+     * @returns true if the tool was found and removed
+     */
+    unregister(name) {
+        return this.tools.delete(name);
+    }
+    /**
+     * Get a tool by name
+     * @returns The tool or undefined if not found
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Check if a tool is registered
+     */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /**
+     * Get all registered tool names
+     */
+    names() {
+        return Array.from(this.tools.keys());
+    }
+    /**
+     * Get tool definitions for a subset of tools
+     * Useful for providing stage-specific tool lists
+     * @param names - Optional filter; if omitted, returns all definitions
+     */
+    getDefinitions(names) {
+        if (names) {
+            return names
+                .map(name => this.tools.get(name)?.definition)
+                .filter((def) => def !== undefined);
+        }
+        return Array.from(this.tools.values()).map(t => t.definition);
+    }
+    /**
+     * Get all registered tools
+     */
+    getAll() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * Clear all registered tools
+     */
+    clear() {
+        this.tools.clear();
+    }
+    /**
+     * Number of registered tools
+     */
+    get size() {
+        return this.tools.size;
+    }
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Create a tool definition with a handler
+ * Type-safe helper for defining tools
+ */
+export function defineTool(definition, handler) {
+    return { definition, handler };
+}
+/**
+ * Validate that arguments match a tool's parameter schema
+ * Basic validation - providers typically do this, but useful for testing
+ */
+export function validateToolArguments(definition, args) {
+    const errors = [];
+    const { properties, required = [] } = definition.parameters;
+    // Check required parameters
+    for (const name of required) {
+        if (!(name in args)) {
+            errors.push(`Missing required parameter: ${name}`);
+        }
+    }
+    // Check property types
+    for (const [name, value] of Object.entries(args)) {
+        const schema = properties[name];
+        if (!schema) {
+            if (definition.parameters.additionalProperties === false) {
+                errors.push(`Unknown parameter: ${name}`);
+            }
+            continue;
+        }
+        // Basic type checking
+        const valueType = Array.isArray(value) ? 'array' : typeof value;
+        if (value === null) {
+            if (schema.type !== 'null') {
+                errors.push(`Parameter '${name}' cannot be null`);
+            }
+        }
+        else if (schema.type === 'integer') {
+            if (typeof value !== 'number' || !Number.isInteger(value)) {
+                errors.push(`Parameter '${name}' must be an integer`);
+            }
+        }
+        else if (valueType !== schema.type) {
+            errors.push(`Parameter '${name}' must be of type ${schema.type}, got ${valueType}`);
+        }
+        // Enum validation
+        if (schema.enum && !schema.enum.includes(value)) {
+            errors.push(`Parameter '${name}' must be one of: ${schema.enum.join(', ')}`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,213 @@
+import type { ToolDefinition, ToolCallRequest, ToolChoice } from './tools.js';
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+export interface VisionAttachment {
+    /** base64-encoded image (data URI) or remote URL depending on provider */
+    data: string;
+    mimeType?: string;
+    alt?: string;
+}
+export interface Message {
+    role: Role;
+    content: string;
+    attachments?: VisionAttachment[];
+    /** Tool call ID (for role='tool' messages containing tool results) */
+    toolCallId?: string;
+    /** Tool name (for role='tool' messages) */
+    toolName?: string;
+    /** Tool calls made by assistant (for role='assistant' messages that called tools) */
+    toolCalls?: ToolCallRequest[];
+}
+export interface SessionConfig {
+    systemPrompt?: string;
+    historyLimit?: number;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+}
+export interface LLMRequest {
+    messages: Message[];
+    config?: SessionConfig;
+    stream?: boolean;
+    /** Tool definitions available for this request */
+    tools?: ToolDefinition[];
+    /** How the LLM should choose tools */
+    toolChoice?: ToolChoice;
+}
+export interface LLMChunk {
+    content: string;
+    done: boolean;
+    raw?: unknown;
+    /** Tool calls (only in final chunk when done=true and stopReason='tool_use') */
+    toolCalls?: ToolCallRequest[];
+    /** Stop reason (only in final chunk when done=true) */
+    stopReason?: StopReason;
+}
+/** Why the LLM stopped generating */
+export type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence';
+export interface LLMResult {
+    fullText: string;
+    raw?: unknown;
+    /** Tool calls requested by the LLM (if stopReason is 'tool_use') */
+    toolCalls?: ToolCallRequest[];
+    /** Why generation stopped */
+    stopReason?: StopReason;
+}
+export interface LLMProvider {
+    name: string;
+    init?(): Promise<void> | void;
+    complete(request: LLMRequest): Promise<LLMResult>;
+    stream?(request: LLMRequest): AsyncIterable<LLMChunk>;
+}
+export interface STTConfig {
+    language?: string;
+    interimResults?: boolean;
+    model?: string;
+}
+export interface STTResult {
+    text: string;
+    isFinal: boolean;
+    confidence?: number;
+    raw?: unknown;
+}
+export interface STTProvider {
+    name: string;
+    init?(): Promise<void> | void;
+    /** One-shot transcription */
+    transcribe(audio: Buffer, config?: STTConfig): Promise<STTResult>;
+    /** Streaming partials/finals */
+    transcribeStream?(audio: AsyncIterable<Buffer>, config?: STTConfig): AsyncIterable<STTResult>;
+}
+export interface TTSConfig {
+    voice?: string;
+    format?: 'mp3' | 'ogg' | 'wav' | 'pcm';
+    model?: string;
+}
+export interface TTSResult {
+    audio: Buffer;
+    format: TTSConfig['format'];
+    raw?: unknown;
+}
+export interface TTSProvider {
+    name: string;
+    init?(): Promise<void> | void;
+    speak(text: string, config?: TTSConfig): Promise<TTSResult>;
+    speakStream?(text: string, config?: TTSConfig): AsyncIterable<Buffer>;
+}
+export interface VisionRequest {
+    prompt: string;
+    attachments: VisionAttachment[];
+    stream?: boolean;
+}
+export interface VisionChunk {
+    content: string;
+    done: boolean;
+    raw?: unknown;
+}
+export interface VisionResult {
+    content: string;
+    raw?: unknown;
+}
+export interface VisionProvider {
+    name: string;
+    init?(): Promise<void> | void;
+    describe(request: VisionRequest): Promise<VisionResult>;
+    stream?(request: VisionRequest): AsyncIterable<VisionChunk>;
+}
+export interface TurnCredentials {
+    urls: string[];
+    username?: string;
+    credential?: string;
+}
+export interface SignallingMessage {
+    type: 'offer' | 'answer' | 'ice' | 'bye' | 'ping' | 'pong';
+    payload?: unknown;
+}
+export interface Logger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+export interface TransportEvents {
+    onTranscript?: (result: STTResult) => void;
+    onLLMChunk?: (chunk: LLMChunk) => void;
+    onLLMResult?: (result: LLMResult) => void;
+    onTTS?: (audio: TTSResult) => void;
+}
+export interface ConversationProviders {
+    llm: LLMProvider;
+    stt: STTProvider;
+    tts: TTSProvider;
+    vision?: VisionProvider;
+}
+export interface ConversationOrchestratorConfig extends SessionConfig {
+    providers: ConversationProviders;
+    logger?: Logger;
+    /** Enable streaming TTS with sentence-boundary detection (default: true) */
+    streamingTTS?: boolean;
+    /** Optional session ID for hook context */
+    sessionId?: string;
+}
+/**
+ * Signal types for coordinating audio capture between client and server
+ * when using MediaStreamTrack-based audio transport
+ */
+export type AudioSignalType = 'audio-start' | 'audio-stop' | 'audio-process';
+/**
+ * Sent when VAD detects speech start - server begins buffering audio
+ */
+export interface AudioStartSignal {
+    type: 'audio-start';
+    timestamp: number;
+}
+/**
+ * Sent when VAD detects speech end - server stops buffering (without processing)
+ */
+export interface AudioStopSignal {
+    type: 'audio-stop';
+    timestamp: number;
+}
+/**
+ * Sent when VAD detects speech end and audio should be processed
+ * Includes any vision attachments captured during speech
+ */
+export interface AudioProcessSignal {
+    type: 'audio-process';
+    timestamp: number;
+    attachments: VisionAttachment[];
+}
+/**
+ * Union type for all audio signals
+ */
+export type AudioSignal = AudioStartSignal | AudioStopSignal | AudioProcessSignal;
+/**
+ * A chunk of TTS audio data during streaming
+ * Yielded by orchestrator as audio becomes available
+ */
+export interface TTSChunk {
+    type: 'tts-chunk';
+    /** Raw audio data (PCM or compressed) */
+    audio: Buffer;
+    /** Audio format: 'pcm' for raw 16-bit samples, or 'mp3'/'ogg' for compressed */
+    format: 'pcm' | 'mp3' | 'ogg' | 'wav';
+    /** Sample rate in Hz (e.g., 24000 for OpenAI PCM, 48000 for WebRTC) */
+    sampleRate?: number;
+    /** The sentence/text this chunk corresponds to */
+    sentence?: string;
+}
+/**
+ * Signal that all TTS audio has been sent
+ */
+export interface TTSComplete {
+    type: 'tts-complete';
+}
+/**
+ * Signal that TTS streaming is starting
+ */
+export interface TTSStart {
+    type: 'tts-start';
+}
+/**
+ * Union type for all orchestrator yield values during a conversation turn
+ */
+export type OrchestratorYield = STTResult | LLMChunk | LLMResult | TTSResult | TTSChunk | TTSStart | TTSComplete;

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@llmrtc/llmrtc-core",
+  "version": "1.0.0",
+  "description": "Core contracts and orchestrators for @llmrtc/LLMRTC",
+  "homepage": "https://www.llmrtc.org",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/llmrtc/llmrtc.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/llmrtc/llmrtc/issues",
+    "email": "contact@llmrtc.org"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}