@radaros/core 0.3.6 → 0.3.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +454 -13
- package/dist/index.js +1607 -271
- package/dist/tools/sandbox-worker.d.ts +2 -0
- package/dist/tools/sandbox-worker.js +21 -0
- package/package.json +3 -3
package/dist/index.d.ts
CHANGED
|
@@ -151,6 +151,23 @@ interface ToolCacheConfig {
|
|
|
151
151
|
/** Time-to-live in milliseconds. Cached results expire after this duration. */
|
|
152
152
|
ttl: number;
|
|
153
153
|
}
|
|
154
|
+
interface SandboxConfig {
|
|
155
|
+
/** Explicit on/off toggle. Defaults to true when config object is provided. */
|
|
156
|
+
enabled?: boolean;
|
|
157
|
+
/** Execution timeout in milliseconds. Default: 30000 (30s). */
|
|
158
|
+
timeout?: number;
|
|
159
|
+
/** Maximum heap memory in MB. Default: 256. */
|
|
160
|
+
maxMemoryMB?: number;
|
|
161
|
+
/** Allow outbound network from the sandbox. Default: false. */
|
|
162
|
+
allowNetwork?: boolean;
|
|
163
|
+
/** Allow filesystem access. Default: false. */
|
|
164
|
+
allowFS?: boolean | {
|
|
165
|
+
readOnly?: string[];
|
|
166
|
+
readWrite?: string[];
|
|
167
|
+
};
|
|
168
|
+
/** Whitelisted environment variables forwarded to the sandbox. */
|
|
169
|
+
env?: Record<string, string>;
|
|
170
|
+
}
|
|
154
171
|
interface ToolDef {
|
|
155
172
|
name: string;
|
|
156
173
|
description: string;
|
|
@@ -160,6 +177,10 @@ interface ToolDef {
|
|
|
160
177
|
rawJsonSchema?: Record<string, unknown>;
|
|
161
178
|
/** Enable result caching for this tool. */
|
|
162
179
|
cache?: ToolCacheConfig;
|
|
180
|
+
/** Run this tool in a sandboxed subprocess. Off by default. */
|
|
181
|
+
sandbox?: boolean | SandboxConfig;
|
|
182
|
+
/** Require human approval before executing this tool. */
|
|
183
|
+
requiresApproval?: boolean | ((args: Record<string, unknown>) => boolean);
|
|
163
184
|
}
|
|
164
185
|
interface ToolCallResult {
|
|
165
186
|
toolCallId: string;
|
|
@@ -181,8 +202,10 @@ interface StorageDriver {
|
|
|
181
202
|
|
|
182
203
|
interface MemoryConfig {
|
|
183
204
|
storage?: StorageDriver;
|
|
184
|
-
|
|
185
|
-
|
|
205
|
+
/** LLM used to generate conversation summaries from overflow messages. */
|
|
206
|
+
model?: ModelProvider;
|
|
207
|
+
/** Maximum number of summaries kept per session (oldest dropped first). Default 20. */
|
|
208
|
+
maxSummaries?: number;
|
|
186
209
|
}
|
|
187
210
|
interface MemoryEntry {
|
|
188
211
|
key: string;
|
|
@@ -190,16 +213,33 @@ interface MemoryEntry {
|
|
|
190
213
|
createdAt: Date;
|
|
191
214
|
}
|
|
192
215
|
|
|
216
|
+
/**
|
|
217
|
+
* Long-term conversation memory.
|
|
218
|
+
*
|
|
219
|
+
* Memory stores LLM-generated summaries of past conversation segments.
|
|
220
|
+
* It does NOT store raw messages — that's Session's job.
|
|
221
|
+
*
|
|
222
|
+
* Flow: Session overflows → Agent passes overflow to Memory.summarize() →
|
|
223
|
+
* Memory generates an LLM summary and persists it.
|
|
224
|
+
* On the next run, Memory.getContextString() provides past summaries as context.
|
|
225
|
+
*/
|
|
193
226
|
declare class Memory {
|
|
194
227
|
private storage;
|
|
195
|
-
private
|
|
196
|
-
private
|
|
228
|
+
private model?;
|
|
229
|
+
private maxSummaries;
|
|
230
|
+
private initPromise;
|
|
197
231
|
constructor(config?: MemoryConfig);
|
|
198
|
-
|
|
199
|
-
|
|
232
|
+
private ensureInitialized;
|
|
233
|
+
/**
|
|
234
|
+
* Summarize overflow messages and store the summary.
|
|
235
|
+
* Uses the configured LLM model; falls back to basic concatenation if no model.
|
|
236
|
+
*/
|
|
237
|
+
summarize(sessionId: string, messages: ChatMessage[], fallbackModel?: ModelProvider): Promise<void>;
|
|
238
|
+
/** Get all stored summaries for a session. */
|
|
200
239
|
getSummaries(sessionId: string): Promise<string[]>;
|
|
240
|
+
/** Get summaries formatted as a context string for injection into the system prompt. */
|
|
201
241
|
getContextString(sessionId: string): Promise<string>;
|
|
202
|
-
|
|
242
|
+
/** Clear all summaries for a session. */
|
|
203
243
|
clear(sessionId: string): Promise<void>;
|
|
204
244
|
}
|
|
205
245
|
|
|
@@ -285,6 +325,44 @@ interface RetryConfig {
|
|
|
285
325
|
}
|
|
286
326
|
declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>): Promise<T>;
|
|
287
327
|
|
|
328
|
+
interface ApprovalRequest {
|
|
329
|
+
requestId: string;
|
|
330
|
+
toolName: string;
|
|
331
|
+
args: unknown;
|
|
332
|
+
agentName: string;
|
|
333
|
+
runId: string;
|
|
334
|
+
}
|
|
335
|
+
interface ApprovalDecision {
|
|
336
|
+
approved: boolean;
|
|
337
|
+
reason?: string;
|
|
338
|
+
}
|
|
339
|
+
interface ApprovalConfig {
|
|
340
|
+
/** Which tools require approval: "none" (default), "all", or an array of tool names. */
|
|
341
|
+
policy: "none" | "all" | string[];
|
|
342
|
+
/** Callback invoked when approval is needed. Return a decision. */
|
|
343
|
+
onApproval?: (request: ApprovalRequest) => Promise<ApprovalDecision>;
|
|
344
|
+
/** Timeout in ms for waiting on human response. Default: 300000 (5 min). Auto-deny on timeout. */
|
|
345
|
+
timeout?: number;
|
|
346
|
+
}
|
|
347
|
+
declare class ApprovalManager {
|
|
348
|
+
private policy;
|
|
349
|
+
private onApproval?;
|
|
350
|
+
private timeout;
|
|
351
|
+
private eventBus?;
|
|
352
|
+
private pending;
|
|
353
|
+
constructor(config: ApprovalConfig & {
|
|
354
|
+
eventBus?: EventBus;
|
|
355
|
+
});
|
|
356
|
+
needsApproval(toolName: string, args: Record<string, unknown>, toolRequiresApproval?: boolean | ((args: Record<string, unknown>) => boolean)): boolean;
|
|
357
|
+
check(toolName: string, args: unknown, ctx: RunContext, agentName: string): Promise<ApprovalDecision>;
|
|
358
|
+
/** Externally approve a pending request (for event-driven mode). */
|
|
359
|
+
approve(requestId: string, reason?: string): void;
|
|
360
|
+
/** Externally deny a pending request (for event-driven mode). */
|
|
361
|
+
deny(requestId: string, reason?: string): void;
|
|
362
|
+
private callbackMode;
|
|
363
|
+
private eventMode;
|
|
364
|
+
}
|
|
365
|
+
|
|
288
366
|
interface AgentConfig {
|
|
289
367
|
name: string;
|
|
290
368
|
model: ModelProvider;
|
|
@@ -315,6 +393,10 @@ interface AgentConfig {
|
|
|
315
393
|
retry?: Partial<RetryConfig>;
|
|
316
394
|
/** Maximum context window tokens. History is auto-trimmed to fit. */
|
|
317
395
|
maxContextTokens?: number;
|
|
396
|
+
/** Default sandbox config applied to ALL tools unless the tool explicitly sets sandbox: false. Off by default. */
|
|
397
|
+
sandbox?: boolean | SandboxConfig;
|
|
398
|
+
/** Human-in-the-loop approval configuration for tool calls. */
|
|
399
|
+
approval?: ApprovalConfig;
|
|
318
400
|
}
|
|
319
401
|
interface RunOpts {
|
|
320
402
|
sessionId?: string;
|
|
@@ -392,6 +474,67 @@ type AgentEventMap = {
|
|
|
392
474
|
stepName: string;
|
|
393
475
|
status: "start" | "done" | "error";
|
|
394
476
|
};
|
|
477
|
+
"voice.connected": {
|
|
478
|
+
agentName: string;
|
|
479
|
+
};
|
|
480
|
+
"voice.audio": {
|
|
481
|
+
agentName: string;
|
|
482
|
+
data: Buffer;
|
|
483
|
+
};
|
|
484
|
+
"voice.transcript": {
|
|
485
|
+
agentName: string;
|
|
486
|
+
text: string;
|
|
487
|
+
role: "user" | "assistant";
|
|
488
|
+
};
|
|
489
|
+
"voice.tool.call": {
|
|
490
|
+
agentName: string;
|
|
491
|
+
toolName: string;
|
|
492
|
+
args: unknown;
|
|
493
|
+
};
|
|
494
|
+
"voice.tool.result": {
|
|
495
|
+
agentName: string;
|
|
496
|
+
toolName: string;
|
|
497
|
+
result: string;
|
|
498
|
+
};
|
|
499
|
+
"voice.error": {
|
|
500
|
+
agentName: string;
|
|
501
|
+
error: Error;
|
|
502
|
+
};
|
|
503
|
+
"voice.disconnected": {
|
|
504
|
+
agentName: string;
|
|
505
|
+
};
|
|
506
|
+
"browser.screenshot": {
|
|
507
|
+
data: Buffer;
|
|
508
|
+
};
|
|
509
|
+
"browser.action": {
|
|
510
|
+
action: unknown;
|
|
511
|
+
};
|
|
512
|
+
"browser.step": {
|
|
513
|
+
index: number;
|
|
514
|
+
action: unknown;
|
|
515
|
+
pageUrl: string;
|
|
516
|
+
screenshot: Buffer;
|
|
517
|
+
};
|
|
518
|
+
"browser.done": {
|
|
519
|
+
result: string;
|
|
520
|
+
success: boolean;
|
|
521
|
+
steps: unknown[];
|
|
522
|
+
};
|
|
523
|
+
"browser.error": {
|
|
524
|
+
error: Error;
|
|
525
|
+
};
|
|
526
|
+
"tool.approval.request": {
|
|
527
|
+
requestId: string;
|
|
528
|
+
toolName: string;
|
|
529
|
+
args: unknown;
|
|
530
|
+
agentName: string;
|
|
531
|
+
runId: string;
|
|
532
|
+
};
|
|
533
|
+
"tool.approval.response": {
|
|
534
|
+
requestId: string;
|
|
535
|
+
approved: boolean;
|
|
536
|
+
reason?: string;
|
|
537
|
+
};
|
|
395
538
|
};
|
|
396
539
|
|
|
397
540
|
type EventKey = keyof AgentEventMap;
|
|
@@ -414,10 +557,12 @@ declare class Agent {
|
|
|
414
557
|
private llmLoop;
|
|
415
558
|
private logger;
|
|
416
559
|
private storageInitPromise;
|
|
560
|
+
private _toolExecutor;
|
|
417
561
|
get tools(): ToolDef[];
|
|
418
562
|
get modelId(): string;
|
|
419
563
|
get providerId(): string;
|
|
420
564
|
get hasStructuredOutput(): boolean;
|
|
565
|
+
get approvalManager(): ApprovalManager | null;
|
|
421
566
|
get structuredOutputSchema(): zod.ZodSchema | undefined;
|
|
422
567
|
constructor(config: AgentConfig);
|
|
423
568
|
run(input: MessageContent, opts?: RunOpts): Promise<RunOutput>;
|
|
@@ -427,12 +572,24 @@ declare class Agent {
|
|
|
427
572
|
private trimHistoryByTokens;
|
|
428
573
|
}
|
|
429
574
|
|
|
575
|
+
interface ToolExecutorConfig {
|
|
576
|
+
concurrency?: number;
|
|
577
|
+
sandbox?: boolean | SandboxConfig;
|
|
578
|
+
approval?: ApprovalConfig & {
|
|
579
|
+
eventBus?: EventBus;
|
|
580
|
+
};
|
|
581
|
+
agentName?: string;
|
|
582
|
+
}
|
|
430
583
|
declare class ToolExecutor {
|
|
431
584
|
private tools;
|
|
432
585
|
private concurrency;
|
|
433
586
|
private cache;
|
|
434
587
|
private cachedDefs;
|
|
435
|
-
|
|
588
|
+
private agentSandbox?;
|
|
589
|
+
private approvalManager?;
|
|
590
|
+
private agentName;
|
|
591
|
+
constructor(tools: ToolDef[], configOrConcurrency?: number | ToolExecutorConfig);
|
|
592
|
+
getApprovalManager(): ApprovalManager | undefined;
|
|
436
593
|
clearCache(): void;
|
|
437
594
|
private getCacheKey;
|
|
438
595
|
private getCached;
|
|
@@ -561,6 +718,135 @@ declare class Workflow<TState extends Record<string, unknown> = Record<string, u
|
|
|
561
718
|
}): Promise<WorkflowResult<TState>>;
|
|
562
719
|
}
|
|
563
720
|
|
|
721
|
+
type AudioFormat = "pcm16" | "g711_ulaw" | "g711_alaw";
|
|
722
|
+
interface TurnDetectionConfig {
|
|
723
|
+
/** Server-side VAD type. */
|
|
724
|
+
type: "server_vad";
|
|
725
|
+
/** Activation threshold (0-1). Lower = more sensitive. */
|
|
726
|
+
threshold?: number;
|
|
727
|
+
/** Duration of speech (ms) required to open the turn. */
|
|
728
|
+
prefixPaddingMs?: number;
|
|
729
|
+
/** Duration of silence (ms) required to close the turn. */
|
|
730
|
+
silenceDurationMs?: number;
|
|
731
|
+
}
|
|
732
|
+
interface RealtimeSessionConfig {
|
|
733
|
+
instructions?: string;
|
|
734
|
+
voice?: string;
|
|
735
|
+
tools?: ToolDefinition[];
|
|
736
|
+
inputAudioFormat?: AudioFormat;
|
|
737
|
+
outputAudioFormat?: AudioFormat;
|
|
738
|
+
turnDetection?: TurnDetectionConfig | null;
|
|
739
|
+
temperature?: number;
|
|
740
|
+
maxResponseOutputTokens?: number | "inf";
|
|
741
|
+
apiKey?: string;
|
|
742
|
+
}
|
|
743
|
+
interface RealtimeToolCall {
|
|
744
|
+
id: string;
|
|
745
|
+
name: string;
|
|
746
|
+
arguments: string;
|
|
747
|
+
}
|
|
748
|
+
type RealtimeEventMap = {
|
|
749
|
+
audio: {
|
|
750
|
+
data: Buffer;
|
|
751
|
+
mimeType?: string;
|
|
752
|
+
};
|
|
753
|
+
text: {
|
|
754
|
+
text: string;
|
|
755
|
+
};
|
|
756
|
+
transcript: {
|
|
757
|
+
text: string;
|
|
758
|
+
role: "user" | "assistant";
|
|
759
|
+
};
|
|
760
|
+
tool_call: RealtimeToolCall;
|
|
761
|
+
interrupted: {};
|
|
762
|
+
error: {
|
|
763
|
+
error: Error;
|
|
764
|
+
};
|
|
765
|
+
connected: {};
|
|
766
|
+
disconnected: {};
|
|
767
|
+
};
|
|
768
|
+
type RealtimeEvent = keyof RealtimeEventMap;
|
|
769
|
+
interface RealtimeConnection {
|
|
770
|
+
sendAudio(data: Buffer): void;
|
|
771
|
+
sendText(text: string): void;
|
|
772
|
+
sendToolResult(callId: string, result: string): void;
|
|
773
|
+
interrupt(): void;
|
|
774
|
+
close(): Promise<void>;
|
|
775
|
+
on<K extends RealtimeEvent>(event: K, handler: (data: RealtimeEventMap[K]) => void): void;
|
|
776
|
+
off<K extends RealtimeEvent>(event: K, handler: (data: RealtimeEventMap[K]) => void): void;
|
|
777
|
+
}
|
|
778
|
+
interface RealtimeProvider {
|
|
779
|
+
readonly providerId: string;
|
|
780
|
+
readonly modelId: string;
|
|
781
|
+
connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
|
|
782
|
+
}
|
|
783
|
+
interface VoiceAgentConfig {
|
|
784
|
+
name: string;
|
|
785
|
+
provider: RealtimeProvider;
|
|
786
|
+
instructions?: string;
|
|
787
|
+
tools?: ToolDef[];
|
|
788
|
+
voice?: string;
|
|
789
|
+
turnDetection?: TurnDetectionConfig | null;
|
|
790
|
+
inputAudioFormat?: AudioFormat;
|
|
791
|
+
outputAudioFormat?: AudioFormat;
|
|
792
|
+
temperature?: number;
|
|
793
|
+
maxResponseOutputTokens?: number | "inf";
|
|
794
|
+
eventBus?: EventBus;
|
|
795
|
+
logLevel?: LogLevel;
|
|
796
|
+
/** User-scoped memory — persists facts about a user across sessions. */
|
|
797
|
+
userMemory?: UserMemory;
|
|
798
|
+
/** LLM model used for auto-extracting user facts from transcripts (required if userMemory is set). */
|
|
799
|
+
model?: ModelProvider;
|
|
800
|
+
/** Default session ID (can be overridden per connect()). */
|
|
801
|
+
sessionId?: string;
|
|
802
|
+
/** Default user ID (can be overridden per connect()). */
|
|
803
|
+
userId?: string;
|
|
804
|
+
}
|
|
805
|
+
type VoiceSessionEventMap = RealtimeEventMap & {
|
|
806
|
+
tool_call_start: {
|
|
807
|
+
name: string;
|
|
808
|
+
args: unknown;
|
|
809
|
+
};
|
|
810
|
+
tool_result: {
|
|
811
|
+
name: string;
|
|
812
|
+
result: string;
|
|
813
|
+
};
|
|
814
|
+
};
|
|
815
|
+
type VoiceSessionEvent = keyof VoiceSessionEventMap;
|
|
816
|
+
interface VoiceSession {
|
|
817
|
+
sendAudio(data: Buffer): void;
|
|
818
|
+
sendText(text: string): void;
|
|
819
|
+
interrupt(): void;
|
|
820
|
+
close(): Promise<void>;
|
|
821
|
+
on<K extends VoiceSessionEvent>(event: K, handler: (data: VoiceSessionEventMap[K]) => void): void;
|
|
822
|
+
off<K extends VoiceSessionEvent>(event: K, handler: (data: VoiceSessionEventMap[K]) => void): void;
|
|
823
|
+
}
|
|
824
|
+
|
|
825
|
+
interface OpenAIRealtimeConfig {
|
|
826
|
+
apiKey?: string;
|
|
827
|
+
baseURL?: string;
|
|
828
|
+
}
|
|
829
|
+
declare class OpenAIRealtimeProvider implements RealtimeProvider {
|
|
830
|
+
readonly providerId = "openai-realtime";
|
|
831
|
+
readonly modelId: string;
|
|
832
|
+
private apiKey?;
|
|
833
|
+
private baseURL?;
|
|
834
|
+
constructor(modelId?: string, config?: OpenAIRealtimeConfig);
|
|
835
|
+
connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
|
|
836
|
+
private buildSessionPayload;
|
|
837
|
+
}
|
|
838
|
+
|
|
839
|
+
interface GoogleLiveConfig {
|
|
840
|
+
apiKey?: string;
|
|
841
|
+
}
|
|
842
|
+
declare class GoogleLiveProvider implements RealtimeProvider {
|
|
843
|
+
readonly providerId = "google-live";
|
|
844
|
+
readonly modelId: string;
|
|
845
|
+
private apiKey?;
|
|
846
|
+
constructor(modelId?: string, config?: GoogleLiveConfig);
|
|
847
|
+
connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
|
|
848
|
+
}
|
|
849
|
+
|
|
564
850
|
type ProviderFactory = (modelId: string, config?: Record<string, unknown>) => ModelProvider;
|
|
565
851
|
declare class ModelRegistry {
|
|
566
852
|
private factories;
|
|
@@ -587,6 +873,24 @@ declare function vertex(modelId: string, config?: {
|
|
|
587
873
|
location?: string;
|
|
588
874
|
credentials?: string;
|
|
589
875
|
}): ModelProvider;
|
|
876
|
+
/**
|
|
877
|
+
* Shorthand for `new OpenAIRealtimeProvider(modelId, config)`.
|
|
878
|
+
*
|
|
879
|
+
* @example
|
|
880
|
+
* const agent = new VoiceAgent({
|
|
881
|
+
* provider: openaiRealtime("gpt-4o-realtime-preview"),
|
|
882
|
+
* });
|
|
883
|
+
*/
|
|
884
|
+
declare function openaiRealtime(modelId?: string, config?: OpenAIRealtimeConfig): RealtimeProvider;
|
|
885
|
+
/**
|
|
886
|
+
* Shorthand for `new GoogleLiveProvider(modelId, config)`.
|
|
887
|
+
*
|
|
888
|
+
* @example
|
|
889
|
+
* const agent = new VoiceAgent({
|
|
890
|
+
* provider: googleLive(),
|
|
891
|
+
* });
|
|
892
|
+
*/
|
|
893
|
+
declare function googleLive(modelId?: string, config?: GoogleLiveConfig): RealtimeProvider;
|
|
590
894
|
|
|
591
895
|
interface OpenAIConfig {
|
|
592
896
|
apiKey?: string;
|
|
@@ -722,8 +1026,18 @@ declare function defineTool<T extends z.ZodObject<any>>(config: {
|
|
|
722
1026
|
parameters: T;
|
|
723
1027
|
execute: (args: z.infer<T>, ctx: RunContext) => Promise<string | ToolResult>;
|
|
724
1028
|
cache?: ToolCacheConfig;
|
|
1029
|
+
sandbox?: boolean | SandboxConfig;
|
|
1030
|
+
requiresApproval?: boolean | ((args: Record<string, unknown>) => boolean);
|
|
725
1031
|
}): ToolDef;
|
|
726
1032
|
|
|
1033
|
+
declare function resolveSandboxConfig(toolLevel?: boolean | SandboxConfig, agentLevel?: boolean | SandboxConfig): SandboxConfig | null;
|
|
1034
|
+
declare class Sandbox {
|
|
1035
|
+
private config;
|
|
1036
|
+
constructor(config: SandboxConfig);
|
|
1037
|
+
execute(toolExecuteFn: (args: Record<string, unknown>, ctx: RunContext) => Promise<string | ToolResult>, args: Record<string, unknown>, ctx: RunContext): Promise<string | ToolResult>;
|
|
1038
|
+
private getWorkerPath;
|
|
1039
|
+
}
|
|
1040
|
+
|
|
727
1041
|
declare class InMemoryStorage implements StorageDriver {
|
|
728
1042
|
private store;
|
|
729
1043
|
private makeKey;
|
|
@@ -954,6 +1268,15 @@ declare class GoogleEmbedding implements EmbeddingProvider {
|
|
|
954
1268
|
embedBatch(texts: string[]): Promise<number[][]>;
|
|
955
1269
|
}
|
|
956
1270
|
|
|
1271
|
+
type SearchMode = "vector" | "keyword" | "hybrid";
|
|
1272
|
+
interface HybridSearchConfig {
|
|
1273
|
+
/** Weight for vector (semantic) results in RRF. Default 1.0. */
|
|
1274
|
+
vectorWeight?: number;
|
|
1275
|
+
/** Weight for keyword (BM25) results in RRF. Default 1.0. */
|
|
1276
|
+
keywordWeight?: number;
|
|
1277
|
+
/** RRF constant k. Higher = less rank-sensitive. Default 60. */
|
|
1278
|
+
rrfK?: number;
|
|
1279
|
+
}
|
|
957
1280
|
interface KnowledgeBaseConfig {
|
|
958
1281
|
/** Display name used in tool description auto-generation. */
|
|
959
1282
|
name: string;
|
|
@@ -961,6 +1284,15 @@ interface KnowledgeBaseConfig {
|
|
|
961
1284
|
vectorStore: VectorStore;
|
|
962
1285
|
/** Collection/index name inside the vector store. */
|
|
963
1286
|
collection?: string;
|
|
1287
|
+
/**
|
|
1288
|
+
* Default search mode.
|
|
1289
|
+
* - `"vector"` — pure semantic (embedding) search (default, backward-compatible)
|
|
1290
|
+
* - `"keyword"` — pure BM25 keyword search
|
|
1291
|
+
* - `"hybrid"` — combines vector + keyword via Reciprocal Rank Fusion
|
|
1292
|
+
*/
|
|
1293
|
+
searchMode?: SearchMode;
|
|
1294
|
+
/** Fine-tune hybrid search behavior. */
|
|
1295
|
+
hybridConfig?: HybridSearchConfig;
|
|
964
1296
|
}
|
|
965
1297
|
interface KnowledgeBaseToolConfig {
|
|
966
1298
|
/** Tool name exposed to the LLM. Defaults to `search_<collection>`. */
|
|
@@ -973,6 +1305,8 @@ interface KnowledgeBaseToolConfig {
|
|
|
973
1305
|
minScore?: number;
|
|
974
1306
|
/** Metadata filter applied to every search. */
|
|
975
1307
|
filter?: Record<string, unknown>;
|
|
1308
|
+
/** Override the search mode for this tool. Inherits from KB config if not set. */
|
|
1309
|
+
searchMode?: SearchMode;
|
|
976
1310
|
/** Custom formatter for search results. Defaults to numbered list with scores. */
|
|
977
1311
|
formatResults?: (results: VectorSearchResult[]) => string;
|
|
978
1312
|
}
|
|
@@ -981,11 +1315,16 @@ declare class KnowledgeBase {
|
|
|
981
1315
|
readonly collection: string;
|
|
982
1316
|
private store;
|
|
983
1317
|
private initialized;
|
|
1318
|
+
private bm25;
|
|
1319
|
+
private defaultSearchMode;
|
|
1320
|
+
private hybridConfig;
|
|
984
1321
|
constructor(config: KnowledgeBaseConfig);
|
|
985
1322
|
initialize(): Promise<void>;
|
|
986
1323
|
add(doc: VectorDocument): Promise<void>;
|
|
987
1324
|
addDocuments(docs: VectorDocument[]): Promise<void>;
|
|
988
|
-
search(query: string, options?: VectorSearchOptions
|
|
1325
|
+
search(query: string, options?: VectorSearchOptions & {
|
|
1326
|
+
searchMode?: SearchMode;
|
|
1327
|
+
}): Promise<VectorSearchResult[]>;
|
|
989
1328
|
get(id: string): Promise<VectorDocument | null>;
|
|
990
1329
|
delete(id: string): Promise<void>;
|
|
991
1330
|
clear(): Promise<void>;
|
|
@@ -995,9 +1334,79 @@ declare class KnowledgeBase {
|
|
|
995
1334
|
* Plug the result directly into `Agent({ tools: [kb.asTool()] })`.
|
|
996
1335
|
*/
|
|
997
1336
|
asTool(config?: KnowledgeBaseToolConfig): ToolDef;
|
|
1337
|
+
private keywordSearch;
|
|
1338
|
+
private hybridSearch;
|
|
998
1339
|
private ensureInit;
|
|
999
1340
|
}
|
|
1000
1341
|
|
|
1342
|
+
/**
|
|
1343
|
+
* Lightweight BM25 (Okapi BM25) implementation for keyword search.
|
|
1344
|
+
* Maintains an in-memory inverted index for fast full-text scoring.
|
|
1345
|
+
*/
|
|
1346
|
+
interface BM25Document {
|
|
1347
|
+
id: string;
|
|
1348
|
+
content: string;
|
|
1349
|
+
metadata?: Record<string, unknown>;
|
|
1350
|
+
}
|
|
1351
|
+
interface BM25Result {
|
|
1352
|
+
id: string;
|
|
1353
|
+
content: string;
|
|
1354
|
+
score: number;
|
|
1355
|
+
metadata?: Record<string, unknown>;
|
|
1356
|
+
}
|
|
1357
|
+
declare class BM25Index {
|
|
1358
|
+
private docs;
|
|
1359
|
+
private docFreqs;
|
|
1360
|
+
private avgDocLength;
|
|
1361
|
+
/** BM25 free parameter: term frequency saturation. */
|
|
1362
|
+
private k1;
|
|
1363
|
+
/** BM25 free parameter: document length normalization. */
|
|
1364
|
+
private b;
|
|
1365
|
+
constructor(opts?: {
|
|
1366
|
+
k1?: number;
|
|
1367
|
+
b?: number;
|
|
1368
|
+
});
|
|
1369
|
+
get size(): number;
|
|
1370
|
+
add(doc: BM25Document): void;
|
|
1371
|
+
addBatch(docs: BM25Document[]): void;
|
|
1372
|
+
remove(id: string): void;
|
|
1373
|
+
clear(): void;
|
|
1374
|
+
search(query: string, opts?: {
|
|
1375
|
+
topK?: number;
|
|
1376
|
+
minScore?: number;
|
|
1377
|
+
filter?: Record<string, unknown>;
|
|
1378
|
+
}): BM25Result[];
|
|
1379
|
+
private recomputeAvgLength;
|
|
1380
|
+
}
|
|
1381
|
+
|
|
1382
|
+
/**
|
|
1383
|
+
* Reciprocal Rank Fusion (RRF) — merges ranked result lists from different
|
|
1384
|
+
* retrieval methods into a single fused ranking.
|
|
1385
|
+
*
|
|
1386
|
+
* RRF score for document d = sum over all lists L of: 1 / (k + rank_L(d))
|
|
1387
|
+
* where k is a constant (default 60) that mitigates the impact of high
|
|
1388
|
+
* rankings by outlier systems.
|
|
1389
|
+
*
|
|
1390
|
+
* Reference: Cormack, Clarke & Buettcher (2009)
|
|
1391
|
+
*/
|
|
1392
|
+
interface RankedItem {
|
|
1393
|
+
id: string;
|
|
1394
|
+
content: string;
|
|
1395
|
+
score: number;
|
|
1396
|
+
metadata?: Record<string, unknown>;
|
|
1397
|
+
}
|
|
1398
|
+
interface RRFOptions {
|
|
1399
|
+
/** Fusion constant. Higher values dampen the effect of rank differences. Default 60. */
|
|
1400
|
+
k?: number;
|
|
1401
|
+
/** Maximum results to return. */
|
|
1402
|
+
topK?: number;
|
|
1403
|
+
/** Minimum fused score to include. */
|
|
1404
|
+
minScore?: number;
|
|
1405
|
+
/** Weight per ranked list. Defaults to equal weighting (1.0 each). */
|
|
1406
|
+
weights?: number[];
|
|
1407
|
+
}
|
|
1408
|
+
declare function reciprocalRankFusion(rankedLists: RankedItem[][], options?: RRFOptions): RankedItem[];
|
|
1409
|
+
|
|
1001
1410
|
interface Session {
|
|
1002
1411
|
sessionId: string;
|
|
1003
1412
|
userId?: string;
|
|
@@ -1007,12 +1416,21 @@ interface Session {
|
|
|
1007
1416
|
updatedAt: Date;
|
|
1008
1417
|
}
|
|
1009
1418
|
|
|
1419
|
+
interface SessionManagerConfig {
|
|
1420
|
+
/** Maximum messages kept in session history. Oldest are trimmed first. Default: unlimited. */
|
|
1421
|
+
maxMessages?: number;
|
|
1422
|
+
}
|
|
1423
|
+
interface AppendResult {
|
|
1424
|
+
/** Messages that were trimmed from the session because maxMessages was exceeded. */
|
|
1425
|
+
overflow: ChatMessage[];
|
|
1426
|
+
}
|
|
1010
1427
|
declare class SessionManager {
|
|
1011
1428
|
private storage;
|
|
1012
|
-
|
|
1429
|
+
private maxMessages?;
|
|
1430
|
+
constructor(storage: StorageDriver, config?: SessionManagerConfig);
|
|
1013
1431
|
getOrCreate(sessionId: string, userId?: string): Promise<Session>;
|
|
1014
|
-
appendMessage(sessionId: string, msg: ChatMessage): Promise<
|
|
1015
|
-
appendMessages(sessionId: string, msgs: ChatMessage[]): Promise<
|
|
1432
|
+
appendMessage(sessionId: string, msg: ChatMessage): Promise<AppendResult>;
|
|
1433
|
+
appendMessages(sessionId: string, msgs: ChatMessage[]): Promise<AppendResult>;
|
|
1016
1434
|
getHistory(sessionId: string, limit?: number): Promise<ChatMessage[]>;
|
|
1017
1435
|
updateState(sessionId: string, patch: Record<string, unknown>): Promise<void>;
|
|
1018
1436
|
getState(sessionId: string): Promise<Record<string, unknown>>;
|
|
@@ -1240,6 +1658,29 @@ declare class A2ARemoteAgent {
|
|
|
1240
1658
|
private partsToText;
|
|
1241
1659
|
}
|
|
1242
1660
|
|
|
1661
|
+
declare class VoiceAgent {
|
|
1662
|
+
readonly name: string;
|
|
1663
|
+
private config;
|
|
1664
|
+
private eventBus;
|
|
1665
|
+
private logger;
|
|
1666
|
+
private toolExecutor;
|
|
1667
|
+
constructor(config: VoiceAgentConfig);
|
|
1668
|
+
connect(opts?: {
|
|
1669
|
+
apiKey?: string;
|
|
1670
|
+
sessionId?: string;
|
|
1671
|
+
userId?: string;
|
|
1672
|
+
}): Promise<VoiceSession>;
|
|
1673
|
+
/**
|
|
1674
|
+
* Consolidate transcript deltas into full messages.
|
|
1675
|
+
* Voice transcripts arrive as many small chunks (one per word/syllable).
|
|
1676
|
+
* Consecutive entries with the same role are merged into a single message.
|
|
1677
|
+
*/
|
|
1678
|
+
private consolidateTranscripts;
|
|
1679
|
+
private persistSession;
|
|
1680
|
+
private wireEvents;
|
|
1681
|
+
private handleToolCall;
|
|
1682
|
+
}
|
|
1683
|
+
|
|
1243
1684
|
/**
|
|
1244
1685
|
* Base class for all RadarOS Toolkits.
|
|
1245
1686
|
* A Toolkit is a collection of related tools that share configuration.
|
|
@@ -1404,4 +1845,4 @@ declare class DuckDuckGoToolkit extends Toolkit {
|
|
|
1404
1845
|
private searchNews;
|
|
1405
1846
|
}
|
|
1406
1847
|
|
|
1407
|
-
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 };
|
|
1848
|
+
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 ApprovalConfig, type ApprovalDecision, ApprovalManager, type ApprovalRequest, 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, Sandbox, type SandboxConfig, 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, googleLive, isMultiModal, ollama, openai, openaiRealtime, reciprocalRankFusion, registry, resolveSandboxConfig, vertex, withRetry };
|