@threaded/ai 1.0.1 → 1.0.3

package/dist/index.d.ts

@@ -32,7 +32,7 @@ interface ToolDefinition {
 interface ToolConfig {
     name: string;
     description: string;
-    schema: Record<string, SchemaProperty>;
+    schema: Record<string, SchemaProperty> | StandardSchema;
     execute: (args: any) => Promise<any> | any;
     _maxCalls?: number;
 }
@@ -45,11 +45,32 @@ interface SchemaProperty {
     properties?: Record<string, SchemaProperty>;
 }
 interface ToolExecutionConfig {
+    /** require user approval before executing tools */
     requireApproval?: boolean;
+    /**
+     * custom callback to handle tool approval, return true to approve
+     *
+     * @example
+     * // simple callback
+     * approvalCallback: (call) => call.function.name !== 'dangerousTool'
+     *
+     * @example
+     * // event-driven (SSE): server sends approval request, waits for client POST
+     * approvalCallback: (call) => new Promise((resolve) => {
+     *   pendingApprovals.set(call.id, resolve);
+     *   res.write(`data: ${JSON.stringify({ type: 'approval_needed', call })}\n\n`);
+     * })
+     * // then: app.post('/approve/:id', (req) => pendingApprovals.get(id)(req.body.approved))
+     */
     approvalCallback?: (call: ToolCall) => boolean | Promise<boolean>;
+    /** execute tools in parallel instead of sequentially */
     parallel?: boolean;
+    /** number of times to retry failed tool executions */
     retryCount?: number;
+    /** identifier for approval requests, useful for managing multiple approval flows */
     approvalId?: string;
+    /** execute tools immediately upon approval instead of waiting for all approvals (default: false, only applies when requireApproval is true) */
+    executeOnApproval?: boolean;
 }
 type StreamEvent = {
     type: 'content';
@@ -100,20 +121,17 @@ interface ScopeConfig {
     system?: string;
     silent?: boolean;
     until?: (ctx: ConversationContext) => boolean;
+    stream?: (event: StreamEvent) => void;
 }
 type StepFunction = (ctx: ConversationContext) => Promise<ConversationContext>;
-type ComposedFunction = (ctxOrMessage?: ConversationContext | string) => Promise<ConversationContext>;
+type ComposedFunction = (ctxOrMessage: ConversationContext | string) => Promise<ConversationContext>;
 interface JsonSchema {
     name: string;
-    schema: {
-        type: string;
-        properties: Record<string, any>;
-        required?: string[];
-        additionalProperties?: boolean;
-    };
+    schema: Record<string, any>;
 }
 interface StandardSchema {
     "~standard": any;
+    [key: string]: any;
 }
 interface ProviderConfig {
     model: string;
@@ -152,12 +170,49 @@ declare const setKeys: (keys: ApiKeys) => void;
 declare const getKey: (provider: string) => string;
 declare const maxCalls: (toolConfig: ToolConfig, maxCalls: number) => ToolConfig;
 
+/**
+ * generates embeddings for text using openai or huggingface models
+ *
+ * openai models use the prefix "openai/" (e.g., "openai/text-embedding-3-small")
+ * all other models use huggingface transformers
+ *
+ * @example
+ * const vector = await embed("openai/text-embedding-3-small", "hello world");
+ * const vector2 = await embed("Xenova/all-MiniLM-L6-v2", "hello world");
+ */
+declare const embed: (model: string, text: string, config?: {
+    dimensions?: number;
+}) => Promise<number[]>;
+
+/**
+ * @example
+ * // in-memory (default)
+ * const thread = getOrCreateThread('user-123');
+ *
+ * @example
+ * // sqlite
+ * const thread = getOrCreateThread('user-123', {
+ *   async get(id) {
+ *     const row = await db.get('SELECT messages FROM threads WHERE id = ?', id);
+ *     return row ? JSON.parse(row.messages) : [];
+ *   },
+ *   async set(id, messages) {
+ *     await db.run(
+ *       'INSERT OR REPLACE INTO threads (id, messages, updated_at) VALUES (?, ?, ?)',
+ *       id,
+ *       JSON.stringify(messages),
+ *       Date.now()
+ *     );
+ *   }
+ * });
+ */
 declare const getOrCreateThread: (id: string, store?: ThreadStore) => Thread;
 
 declare const isStandardSchema: (schema: any) => schema is StandardSchema;
 declare const convertStandardSchemaToJsonSchema: (standardSchema: StandardSchema, name?: string) => JsonSchema;
 declare const convertMCPSchemaToToolSchema: (mcpSchema: any) => Record<string, SchemaProperty>;
 declare function normalizeSchema(schema: JsonSchema | StandardSchema, name?: string): JsonSchema;
+declare const convertStandardSchemaToSchemaProperties: (standardSchema: StandardSchema) => Record<string, SchemaProperty>;
 
 /**
  * scope({ until: noToolsCalled() })
@@ -198,8 +253,8 @@ declare const when: (condition: (ctx: ConversationContext) => boolean, action: S
 
 declare const model: ({ model, schema, }?: {
     model?: string;
-    schema?: any;
-}) => StepFunction;
+    schema?: JsonSchema | StandardSchema;
+}) => ComposedFunction;
 
 /**
  * scope({}, retry({ times: 2 }, model(...)))
@@ -208,6 +263,32 @@ declare const retry: ({ times }: RetryOptions | undefined, step: StepFunction) =
 
 declare const scope: (config: ScopeConfig, ...steps: StepFunction[]) => StepFunction;
 
+type RateLimitConfig = {
+    rps: number;
+    burst: number;
+    concurrency: number;
+};
+/**
+ * creates a rate limiter that wraps async functions with burst, rate, and concurrency controls
+ *
+ * @param config - rate limit configuration
+ * @param config.rps - maximum requests per second
+ * @param config.burst - maximum burst size (initial token bucket capacity)
+ * @param config.concurrency - maximum concurrent in-flight requests
+ *
+ * @example
+ * const limiter = rateLimited({ rps: 10, burst: 20, concurrency: 5 });
+ *
+ * const workflow = limiter(
+ *   compose(
+ *     scope({ tools: [searchTool] }, model())
+ *   )
+ * );
+ *
+ * await workflow("hello");
+ */
+declare const rateLimited: (config: RateLimitConfig) => <T extends (...args: any[]) => Promise<any>>(fn: T) => T;
+
 declare const compose: (...steps: StepFunction[]) => ComposedFunction;
 
-export { type ApiKeys, type ApprovalRequest, type ApprovalResponse, type ComposedFunction, type ConversationContext, Inherit, type JsonSchema, type Message, type ParsedModel, type ProviderConfig, type RetryOptions, type SchemaProperty, type ScopeConfig, type StandardSchema, type StepFunction, type StreamEvent, type Thread, type ThreadStore, type ToolCall, type ToolCallResult, type ToolConfig, type ToolDefinition, type ToolExecutionConfig, appendToLastRequest, compose, convertMCPSchemaToToolSchema, convertStandardSchemaToJsonSchema, createMCPTools, everyNMessages, everyNTokens, generateApprovalToken, getKey, getOrCreateThread, isStandardSchema, maxCalls, model, noToolsCalled, normalizeSchema, onApprovalRequested, onApprovalResolved, parseModelName, removeApprovalListener, requestApproval, resolveApproval, retry, scope, setKeys, tap, toolConfigToToolDefinition, toolNotUsedInNTurns, toolWasCalled, when };
+export { type ApiKeys, type ApprovalRequest, type ApprovalResponse, type ComposedFunction, type ConversationContext, Inherit, type JsonSchema, type Message, type ParsedModel, type ProviderConfig, type RetryOptions, type SchemaProperty, type ScopeConfig, type StandardSchema, type StepFunction, type StreamEvent, type Thread, type ThreadStore, type ToolCall, type ToolCallResult, type ToolConfig, type ToolDefinition, type ToolExecutionConfig, appendToLastRequest, compose, convertMCPSchemaToToolSchema, convertStandardSchemaToJsonSchema, convertStandardSchemaToSchemaProperties, createMCPTools, embed, everyNMessages, everyNTokens, generateApprovalToken, getKey, getOrCreateThread, isStandardSchema, maxCalls, model, noToolsCalled, normalizeSchema, onApprovalRequested, onApprovalResolved, parseModelName, rateLimited, removeApprovalListener, requestApproval, resolveApproval, retry, scope, setKeys, tap, toolConfigToToolDefinition, toolNotUsedInNTurns, toolWasCalled, when };