@radaros/core 0.3.6 → 0.3.7

package/dist/index.d.ts

@@ -181,8 +181,10 @@ interface StorageDriver {
 
 interface MemoryConfig {
     storage?: StorageDriver;
-    maxShortTermMessages?: number;
-    enableLongTerm?: boolean;
+    /** LLM used to generate conversation summaries from overflow messages. */
+    model?: ModelProvider;
+    /** Maximum number of summaries kept per session (oldest dropped first). Default 20. */
+    maxSummaries?: number;
 }
 interface MemoryEntry {
     key: string;
@@ -190,16 +192,33 @@ interface MemoryEntry {
     createdAt: Date;
 }
 
+/**
+ * Long-term conversation memory.
+ *
+ * Memory stores LLM-generated summaries of past conversation segments.
+ * It does NOT store raw messages — that's Session's job.
+ *
+ * Flow: Session overflows → Agent passes overflow to Memory.summarize() →
+ * Memory generates an LLM summary and persists it.
+ * On the next run, Memory.getContextString() provides past summaries as context.
+ */
 declare class Memory {
     private storage;
-    private maxShortTermMessages;
-    private enableLongTerm;
+    private model?;
+    private maxSummaries;
+    private initPromise;
     constructor(config?: MemoryConfig);
-    addMessages(sessionId: string, messages: ChatMessage[]): Promise<void>;
-    getMessages(sessionId: string): Promise<ChatMessage[]>;
+    private ensureInitialized;
+    /**
+     * Summarize overflow messages and store the summary.
+     * Uses the configured LLM model; falls back to basic concatenation if no model.
+     */
+    summarize(sessionId: string, messages: ChatMessage[], fallbackModel?: ModelProvider): Promise<void>;
+    /** Get all stored summaries for a session. */
     getSummaries(sessionId: string): Promise<string[]>;
+    /** Get summaries formatted as a context string for injection into the system prompt. */
     getContextString(sessionId: string): Promise<string>;
-    private summarizeAndStore;
+    /** Clear all summaries for a session. */
     clear(sessionId: string): Promise<void>;
 }
 
@@ -392,6 +411,35 @@ type AgentEventMap = {
         stepName: string;
         status: "start" | "done" | "error";
     };
+    "voice.connected": {
+        agentName: string;
+    };
+    "voice.audio": {
+        agentName: string;
+        data: Buffer;
+    };
+    "voice.transcript": {
+        agentName: string;
+        text: string;
+        role: "user" | "assistant";
+    };
+    "voice.tool.call": {
+        agentName: string;
+        toolName: string;
+        args: unknown;
+    };
+    "voice.tool.result": {
+        agentName: string;
+        toolName: string;
+        result: string;
+    };
+    "voice.error": {
+        agentName: string;
+        error: Error;
+    };
+    "voice.disconnected": {
+        agentName: string;
+    };
 };
 
 type EventKey = keyof AgentEventMap;
@@ -954,6 +1002,15 @@ declare class GoogleEmbedding implements EmbeddingProvider {
     embedBatch(texts: string[]): Promise<number[][]>;
 }
 
+type SearchMode = "vector" | "keyword" | "hybrid";
+interface HybridSearchConfig {
+    /** Weight for vector (semantic) results in RRF. Default 1.0. */
+    vectorWeight?: number;
+    /** Weight for keyword (BM25) results in RRF. Default 1.0. */
+    keywordWeight?: number;
+    /** RRF constant k. Higher = less rank-sensitive. Default 60. */
+    rrfK?: number;
+}
 interface KnowledgeBaseConfig {
     /** Display name used in tool description auto-generation. */
     name: string;
@@ -961,6 +1018,15 @@ interface KnowledgeBaseConfig {
     vectorStore: VectorStore;
     /** Collection/index name inside the vector store. */
     collection?: string;
+    /**
+     * Default search mode.
+     * - `"vector"` — pure semantic (embedding) search (default, backward-compatible)
+     * - `"keyword"` — pure BM25 keyword search
+     * - `"hybrid"` — combines vector + keyword via Reciprocal Rank Fusion
+     */
+    searchMode?: SearchMode;
+    /** Fine-tune hybrid search behavior. */
+    hybridConfig?: HybridSearchConfig;
 }
 interface KnowledgeBaseToolConfig {
     /** Tool name exposed to the LLM. Defaults to `search_<collection>`. */
@@ -973,6 +1039,8 @@ interface KnowledgeBaseToolConfig {
     minScore?: number;
     /** Metadata filter applied to every search. */
     filter?: Record<string, unknown>;
+    /** Override the search mode for this tool. Inherits from KB config if not set. */
+    searchMode?: SearchMode;
     /** Custom formatter for search results. Defaults to numbered list with scores. */
     formatResults?: (results: VectorSearchResult[]) => string;
 }
@@ -981,11 +1049,16 @@ declare class KnowledgeBase {
     readonly collection: string;
     private store;
     private initialized;
+    private bm25;
+    private defaultSearchMode;
+    private hybridConfig;
     constructor(config: KnowledgeBaseConfig);
     initialize(): Promise<void>;
     add(doc: VectorDocument): Promise<void>;
     addDocuments(docs: VectorDocument[]): Promise<void>;
-    search(query: string, options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    search(query: string, options?: VectorSearchOptions & {
+        searchMode?: SearchMode;
+    }): Promise<VectorSearchResult[]>;
     get(id: string): Promise<VectorDocument | null>;
     delete(id: string): Promise<void>;
     clear(): Promise<void>;
@@ -995,9 +1068,79 @@ declare class KnowledgeBase {
      * Plug the result directly into `Agent({ tools: [kb.asTool()] })`.
      */
     asTool(config?: KnowledgeBaseToolConfig): ToolDef;
+    private keywordSearch;
+    private hybridSearch;
     private ensureInit;
 }
 
+/**
+ * Lightweight BM25 (Okapi BM25) implementation for keyword search.
+ * Maintains an in-memory inverted index for fast full-text scoring.
+ */
+interface BM25Document {
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+interface BM25Result {
+    id: string;
+    content: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+}
+declare class BM25Index {
+    private docs;
+    private docFreqs;
+    private avgDocLength;
+    /** BM25 free parameter: term frequency saturation. */
+    private k1;
+    /** BM25 free parameter: document length normalization. */
+    private b;
+    constructor(opts?: {
+        k1?: number;
+        b?: number;
+    });
+    get size(): number;
+    add(doc: BM25Document): void;
+    addBatch(docs: BM25Document[]): void;
+    remove(id: string): void;
+    clear(): void;
+    search(query: string, opts?: {
+        topK?: number;
+        minScore?: number;
+        filter?: Record<string, unknown>;
+    }): BM25Result[];
+    private recomputeAvgLength;
+}
+
+/**
+ * Reciprocal Rank Fusion (RRF) — merges ranked result lists from different
+ * retrieval methods into a single fused ranking.
+ *
+ * RRF score for document d = sum over all lists L of: 1 / (k + rank_L(d))
+ * where k is a constant (default 60) that mitigates the impact of high
+ * rankings by outlier systems.
+ *
+ * Reference: Cormack, Clarke & Buettcher (2009)
+ */
+interface RankedItem {
+    id: string;
+    content: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+}
+interface RRFOptions {
+    /** Fusion constant. Higher values dampen the effect of rank differences. Default 60. */
+    k?: number;
+    /** Maximum results to return. */
+    topK?: number;
+    /** Minimum fused score to include. */
+    minScore?: number;
+    /** Weight per ranked list. Defaults to equal weighting (1.0 each). */
+    weights?: number[];
+}
+declare function reciprocalRankFusion(rankedLists: RankedItem[][], options?: RRFOptions): RankedItem[];
+
 interface Session {
     sessionId: string;
     userId?: string;
@@ -1007,12 +1150,21 @@ interface Session {
     updatedAt: Date;
 }
 
+interface SessionManagerConfig {
+    /** Maximum messages kept in session history. Oldest are trimmed first. Default: unlimited. */
+    maxMessages?: number;
+}
+interface AppendResult {
+    /** Messages that were trimmed from the session because maxMessages was exceeded. */
+    overflow: ChatMessage[];
+}
 declare class SessionManager {
     private storage;
-    constructor(storage: StorageDriver);
+    private maxMessages?;
+    constructor(storage: StorageDriver, config?: SessionManagerConfig);
     getOrCreate(sessionId: string, userId?: string): Promise<Session>;
-    appendMessage(sessionId: string, msg: ChatMessage): Promise<void>;
-    appendMessages(sessionId: string, msgs: ChatMessage[]): Promise<void>;
+    appendMessage(sessionId: string, msg: ChatMessage): Promise<AppendResult>;
+    appendMessages(sessionId: string, msgs: ChatMessage[]): Promise<AppendResult>;
     getHistory(sessionId: string, limit?: number): Promise<ChatMessage[]>;
     updateState(sessionId: string, patch: Record<string, unknown>): Promise<void>;
     getState(sessionId: string): Promise<Record<string, unknown>>;
@@ -1240,6 +1392,158 @@ declare class A2ARemoteAgent {
     private partsToText;
 }
 
+type AudioFormat = "pcm16" | "g711_ulaw" | "g711_alaw";
+interface TurnDetectionConfig {
+    /** Server-side VAD type. */
+    type: "server_vad";
+    /** Activation threshold (0-1). Lower = more sensitive. */
+    threshold?: number;
+    /** Duration of speech (ms) required to open the turn. */
+    prefixPaddingMs?: number;
+    /** Duration of silence (ms) required to close the turn. */
+    silenceDurationMs?: number;
+}
+interface RealtimeSessionConfig {
+    instructions?: string;
+    voice?: string;
+    tools?: ToolDefinition[];
+    inputAudioFormat?: AudioFormat;
+    outputAudioFormat?: AudioFormat;
+    turnDetection?: TurnDetectionConfig | null;
+    temperature?: number;
+    maxResponseOutputTokens?: number | "inf";
+    apiKey?: string;
+}
+interface RealtimeToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+type RealtimeEventMap = {
+    audio: {
+        data: Buffer;
+        mimeType?: string;
+    };
+    text: {
+        text: string;
+    };
+    transcript: {
+        text: string;
+        role: "user" | "assistant";
+    };
+    tool_call: RealtimeToolCall;
+    interrupted: {};
+    error: {
+        error: Error;
+    };
+    connected: {};
+    disconnected: {};
+};
+type RealtimeEvent = keyof RealtimeEventMap;
+interface RealtimeConnection {
+    sendAudio(data: Buffer): void;
+    sendText(text: string): void;
+    sendToolResult(callId: string, result: string): void;
+    interrupt(): void;
+    close(): Promise<void>;
+    on<K extends RealtimeEvent>(event: K, handler: (data: RealtimeEventMap[K]) => void): void;
+    off<K extends RealtimeEvent>(event: K, handler: (data: RealtimeEventMap[K]) => void): void;
+}
+interface RealtimeProvider {
+    readonly providerId: string;
+    readonly modelId: string;
+    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
+}
+interface VoiceAgentConfig {
+    name: string;
+    provider: RealtimeProvider;
+    instructions?: string;
+    tools?: ToolDef[];
+    voice?: string;
+    turnDetection?: TurnDetectionConfig | null;
+    inputAudioFormat?: AudioFormat;
+    outputAudioFormat?: AudioFormat;
+    temperature?: number;
+    maxResponseOutputTokens?: number | "inf";
+    eventBus?: EventBus;
+    logLevel?: LogLevel;
+    /** User-scoped memory — persists facts about a user across sessions. */
+    userMemory?: UserMemory;
+    /** LLM model used for auto-extracting user facts from transcripts (required if userMemory is set). */
+    model?: ModelProvider;
+    /** Default session ID (can be overridden per connect()). */
+    sessionId?: string;
+    /** Default user ID (can be overridden per connect()). */
+    userId?: string;
+}
+type VoiceSessionEventMap = RealtimeEventMap & {
+    tool_call_start: {
+        name: string;
+        args: unknown;
+    };
+    tool_result: {
+        name: string;
+        result: string;
+    };
+};
+type VoiceSessionEvent = keyof VoiceSessionEventMap;
+interface VoiceSession {
+    sendAudio(data: Buffer): void;
+    sendText(text: string): void;
+    interrupt(): void;
+    close(): Promise<void>;
+    on<K extends VoiceSessionEvent>(event: K, handler: (data: VoiceSessionEventMap[K]) => void): void;
+    off<K extends VoiceSessionEvent>(event: K, handler: (data: VoiceSessionEventMap[K]) => void): void;
+}
+
+declare class VoiceAgent {
+    readonly name: string;
+    private config;
+    private eventBus;
+    private logger;
+    private toolExecutor;
+    constructor(config: VoiceAgentConfig);
+    connect(opts?: {
+        apiKey?: string;
+        sessionId?: string;
+        userId?: string;
+    }): Promise<VoiceSession>;
+    /**
+     * Consolidate transcript deltas into full messages.
+     * Voice transcripts arrive as many small chunks (one per word/syllable).
+     * Consecutive entries with the same role are merged into a single message.
+     */
+    private consolidateTranscripts;
+    private persistSession;
+    private wireEvents;
+    private handleToolCall;
+}
+
+interface OpenAIRealtimeConfig {
+    apiKey?: string;
+    baseURL?: string;
+}
+declare class OpenAIRealtimeProvider implements RealtimeProvider {
+    readonly providerId = "openai-realtime";
+    readonly modelId: string;
+    private apiKey?;
+    private baseURL?;
+    constructor(modelId?: string, config?: OpenAIRealtimeConfig);
+    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
+    private buildSessionPayload;
+}
+
+interface GoogleLiveConfig {
+    apiKey?: string;
+}
+declare class GoogleLiveProvider implements RealtimeProvider {
+    readonly providerId = "google-live";
+    readonly modelId: string;
+    private apiKey?;
+    constructor(modelId?: string, config?: GoogleLiveConfig);
+    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
+}
+
 /**
  * Base class for all RadarOS Toolkits.
  * A Toolkit is a collection of related tools that share configuration.
@@ -1404,4 +1708,4 @@ declare class DuckDuckGoToolkit extends Toolkit {
     private searchNews;
 }
 
-export { type A2AAgentCard, type A2AArtifact, type A2ADataPart, type A2AFilePart, type A2AJsonRpcRequest, type A2AJsonRpcResponse, type A2AMessage, type A2APart, A2ARemoteAgent, type A2ARemoteAgentConfig, type A2ASendParams, type A2ASkill, type A2ATask, type A2ATaskQueryParams, type A2ATaskState, type A2ATextPart, Agent, type AgentConfig, type AgentEventMap, type AgentHooks, type AgentStep, AnthropicProvider, type Artifact, type AudioPart, BaseVectorStore, type ChatMessage, type ConditionStep, type ContentPart, type DuckDuckGoConfig, DuckDuckGoToolkit, type EmbeddingProvider, EventBus, type FilePart, type FunctionStep, type GmailConfig, GmailToolkit, GoogleEmbedding, type GoogleEmbeddingConfig, GoogleProvider, type GuardrailResult, type HackerNewsConfig, HackerNewsToolkit, type ImagePart, InMemoryStorage, InMemoryVectorStore, type InputGuardrail, KnowledgeBase, type KnowledgeBaseConfig, type KnowledgeBaseToolConfig, LLMLoop, type LogLevel, Logger, type LoggerConfig, MCPToolProvider, type MCPToolProviderConfig, Memory, type MemoryConfig, type MemoryEntry, type MessageContent, type MessageRole, type ModelConfig, type ModelProvider, ModelRegistry, type ModelResponse, MongoDBStorage, type MongoDBVectorConfig, MongoDBVectorStore, OllamaProvider, OpenAIEmbedding, type OpenAIEmbeddingConfig, OpenAIProvider, type OutputGuardrail, type ParallelStep, type PgVectorConfig, PgVectorStore, PostgresStorage, type QdrantConfig, QdrantVectorStore, type ReasoningConfig, type RetryConfig, RunContext, type RunOpts, type RunOutput, type Session, SessionManager, SqliteStorage, type StepDef, type StepResult, type StorageDriver, type StreamChunk, Team, type TeamConfig, TeamMode, type TextPart, type TokenUsage, type ToolCacheConfig, type ToolCall, type ToolCallResult, type ToolDef, type ToolDefinition, ToolExecutor, type ToolResult, Toolkit, type UserFact, UserMemory, type UserMemoryConfig, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, type VectorStore, type VertexAIConfig, VertexAIProvider, type WebSearchConfig, WebSearchToolkit, type WhatsAppConfig, WhatsAppToolkit, Workflow, type WorkflowConfig, type WorkflowResult, anthropic, defineTool, getTextContent, google, isMultiModal, ollama, openai, registry, vertex, withRetry };
+export { type A2AAgentCard, type A2AArtifact, type A2ADataPart, type A2AFilePart, type A2AJsonRpcRequest, type A2AJsonRpcResponse, type A2AMessage, type A2APart, A2ARemoteAgent, type A2ARemoteAgentConfig, type A2ASendParams, type A2ASkill, type A2ATask, type A2ATaskQueryParams, type A2ATaskState, type A2ATextPart, Agent, type AgentConfig, type AgentEventMap, type AgentHooks, type AgentStep, AnthropicProvider, type AppendResult, type Artifact, type AudioFormat, type AudioPart, type BM25Document, BM25Index, type BM25Result, BaseVectorStore, type ChatMessage, type ConditionStep, type ContentPart, type DuckDuckGoConfig, DuckDuckGoToolkit, type EmbeddingProvider, EventBus, type FilePart, type FunctionStep, type GmailConfig, GmailToolkit, GoogleEmbedding, type GoogleEmbeddingConfig, type GoogleLiveConfig, GoogleLiveProvider, GoogleProvider, type GuardrailResult, type HackerNewsConfig, HackerNewsToolkit, type HybridSearchConfig, type ImagePart, InMemoryStorage, InMemoryVectorStore, type InputGuardrail, KnowledgeBase, type KnowledgeBaseConfig, type KnowledgeBaseToolConfig, LLMLoop, type LogLevel, Logger, type LoggerConfig, MCPToolProvider, type MCPToolProviderConfig, Memory, type MemoryConfig, type MemoryEntry, type MessageContent, type MessageRole, type ModelConfig, type ModelProvider, ModelRegistry, type ModelResponse, MongoDBStorage, type MongoDBVectorConfig, MongoDBVectorStore, OllamaProvider, OpenAIEmbedding, type OpenAIEmbeddingConfig, OpenAIProvider, type OpenAIRealtimeConfig, OpenAIRealtimeProvider, type OutputGuardrail, type ParallelStep, type PgVectorConfig, PgVectorStore, PostgresStorage, type QdrantConfig, QdrantVectorStore, type RRFOptions, type RankedItem, type RealtimeConnection, type RealtimeEvent, type RealtimeEventMap, type RealtimeProvider, type RealtimeSessionConfig, type RealtimeToolCall, type ReasoningConfig, type RetryConfig, RunContext, type RunOpts, type RunOutput, type SearchMode, type Session, SessionManager, type SessionManagerConfig, SqliteStorage, type StepDef, type StepResult, type StorageDriver, type StreamChunk, Team, type TeamConfig, TeamMode, type TextPart, type TokenUsage, type ToolCacheConfig, type ToolCall, type ToolCallResult, type ToolDef, type ToolDefinition, ToolExecutor, type ToolResult, Toolkit, type TurnDetectionConfig, type UserFact, UserMemory, type UserMemoryConfig, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, type VectorStore, type VertexAIConfig, VertexAIProvider, VoiceAgent, type VoiceAgentConfig, type VoiceSession, type VoiceSessionEvent, type VoiceSessionEventMap, type WebSearchConfig, WebSearchToolkit, type WhatsAppConfig, WhatsAppToolkit, Workflow, type WorkflowConfig, type WorkflowResult, anthropic, defineTool, getTextContent, google, isMultiModal, ollama, openai, reciprocalRankFusion, registry, vertex, withRetry };