@minded-ai/mindedjs 1.0.0-ec2-beta-1

package/README.md

@@ -0,0 +1,6 @@
+# MindedJS – Agent SDK
+
+Compose, run, and extend AI-first workflows with a few lines of TypeScript.
+
+---
+[Documentation](https://docs.minded.com)

package/dist/agent.d.ts

@@ -0,0 +1,256 @@
+import { Flow, Node } from './types/Flows.types';
+import { Tool } from './types/Tools.types';
+import { BaseLanguageModel } from '@langchain/core/language_models/base';
+import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { CompiledGraph, State, stateAnnotation } from './types/LangGraph.types';
+import { AgentEventRequestPayloads, AgentEventResponsePayloads } from './events/AgentEvents';
+import { z } from 'zod';
+import { AgentInvokeParams, MindedSDKConfig } from './types/Agent.types';
+import { InterruptSessionManager } from './interrupts/BaseInterruptSessionManager';
+import { VoiceSession } from './voice/voiceSession';
+import { PIIGatewayInstance } from './platform/piiGateway';
+import { Playbook } from './playbooks/playbooks';
+import { ToolExecutionRequest, ToolExecutionResponse } from './platform/toolExecutor';
+import { Document } from '@langchain/core/documents';
+type CreateAgentParams<Memory> = {
+    memorySchema: z.ZodSchema;
+    config: MindedSDKConfig;
+    tools: Tool<any, Memory>[];
+    platformToken?: string;
+    memorySaver?: BaseCheckpointSaver;
+    interruptSessionManager?: InterruptSessionManager;
+    parseSessionIdFromTrigger?: (trigger: any) => string;
+};
+/**
+ * The main Agent class that orchestrates flows, tools, and integrations with the Minded platform.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   memorySchema: z.object({
+ *     userName: z.string().optional(),
+ *     preferences: z.record(z.any()).optional()
+ *   }),
+ *   config: {
+ *     flows: ['./src/flows'],
+ *     llm: { provider: 'openai', model: 'gpt-4' }
+ *   },
+ *   tools: [myCustomTool]
+ * });
+ * ```
+ */
+export declare class Agent {
+    private memorySchema;
+    private stateAnnotation;
+    flows: Flow[];
+    tools: Tool<any, any>[];
+    /**
+     * Internal tools
+     */
+    llm: BaseLanguageModel;
+    private checkpointer;
+    interruptSessionManager: InterruptSessionManager;
+    compiledGraph: CompiledGraph;
+    private secretsCache;
+    config: MindedSDKConfig;
+    private _piiGateway;
+    playbooks: Playbook[];
+    private toolExecutor;
+    get piiGateway(): PIIGatewayInstance;
+    private eventHandlers;
+    private initialized;
+    private initPromise;
+    private startingNodeId;
+    voiceSessions: Map<string, VoiceSession>;
+    parseSessionIdFromTrigger?: (trigger: any, triggerName: string) => string;
+    /**
+     * Create a new Agent instance.
+     *
+     * @param params - Configuration parameters for the agent containing:
+     *   - memorySchema: Zod schema defining the structure of the agent's memory
+     *   - config: SDK configuration including flows directory and LLM settings
+     *   - tools: Array of custom tools to be available to the agent
+     *   - platformToken: Optional token for platform authentication
+     *   - memorySaver: Optional custom checkpoint saver for conversation memory
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   memorySchema: z.object({
+     *     userName: z.string().optional(),
+     *     conversationHistory: z.array(z.string()).optional()
+     *   }),
+     *   config: {
+     *     flows: ['./src/flows'],
+     *     llm: {
+     *       provider: 'openai',
+     *       model: 'gpt-4-turbo'
+     *     }
+     *   },
+     *   tools: [
+     *     weatherTool,
+     *     databaseTool
+     *   ]
+     * });
+     * ```
+     */
+    constructor(params: CreateAgentParams<z.infer<typeof this.memorySchema>>);
+    private init;
+    private validate;
+    private waitForInitialization;
+    private initializeGraph;
+    /**
+     * Invoke a trigger to start agent execution with the specified parameters.
+     *
+     * This method processes triggers from external systems or applications, allowing the agent
+     * to respond to events and execute the appropriate flows based on the trigger type.
+     *
+     * @param params - The trigger invocation parameters containing:
+     *   - triggerBody: The payload/data associated with the trigger
+     *   - triggerName: The name/type of the trigger being invoked
+     *   - sessionId: Optional session identifier for conversation continuity
+     *   - appName: Optional name of the application triggering the agent in case of an app trigger
+     *
+     * @returns Promise that resolves with the agent's execution result
+     *
+     * @throws {Error} When the agent is not properly initialized
+     *
+     * @example
+     * ```typescript
+     * // Manual invoke with a message trigger
+     * const result = await agent.invoke({
+     *   triggerName: 'minded.message.in.conversation',
+     *   triggerBody: {
+     *     text: 'Hello, how can you help me?',
+     *   },
+     *   sessionId: 'user-123-session'
+     * });
+     * ```
+     */
+    invoke({ triggerBody, triggerName, appName, bypassSessionCheck }: AgentInvokeParams): Promise<any>;
+    /**
+     * Register an event handler for agent events. Multiple handlers can be registered for the same event.
+     *
+     * ## Available Events
+     *
+     * ### INIT
+     * Fired when a new session starts.
+     * - **Input:** `{ state: AgentState }` - Initial agent state with empty messages/history
+     * - **Output:** `void`
+     * - **Use for:** Session logging, resource initialization, analytics
+     *
+     * ### AI_MESSAGE
+     * Fired when AI generates a message for the user.
+     * - **Input:** `{ message: string, state: AgentState }` - AI message and current state
+     * - **Output:** `void`
+     * - **Use for:** Sending to UI, logging responses, notifications
+     *
+     * ### TRIGGER_EVENT
+     * Fired when a trigger executes. Allows qualifying/transforming trigger inputs.
+     * - **Input:** `{ triggerName: string, triggerBody: any }`
+     * - **Output Options:**
+     *   - `{ messages?, memory?, sessionId? }` - Provide initial state
+     *   - `false` - Disqualify the trigger
+     *   - `void` - Qualify without initial state
+     * - **Use for:** Input validation, data transformation, access control
+     *
+     * @template E - The event type
+     * @param event - Event name to listen for
+     * @param handler - Function to call when event fires
+     *
+     * @example
+     * ```typescript
+     * // Session initialization
+     * agent.on('INIT', async ({ state }) => {
+     *   logger.info({ msg: 'Session started', sessionId: state.sessionId });
+     *   await initializeResources(state.sessionId);
+     * });
+     *
+     * // Handle AI messages
+     * agent.on('AI_MESSAGE', async ({ message, state }) => {
+     *   await sendToUI(message, state.sessionId);
+     * });
+     *
+     * // Validate and transform triggers
+     * agent.on('TRIGGER_EVENT', async ({ triggerName, triggerBody }) => {
+     *   if (!isValid(triggerBody)) return false;
+     *
+     *   return {
+     *     memory: { validated: true },
+     *     messages: [new HumanMessage('Request received')],
+     *     sessionId: triggerBody.userId
+     *   };
+     * });
+     * ```
+     */
+    on<E extends keyof AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>>(event: E, handler: (payload: AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>[E]) => Promise<AgentEventResponsePayloads[E] | void>): void;
+    emit<E extends keyof AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>>(event: E, payload: AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>[E]): Promise<AgentEventResponsePayloads[E][]>;
+    private initAppActionsRunnerTools;
+    private loadSecrets;
+    getLangraphConfig(sessionId: string, checkpointId?: string): {
+        configurable: {
+            thread_id: string;
+            recursionLimit: number;
+            checkpoint_id: string | undefined;
+        };
+    };
+    private setupVoice;
+    updateState({ sessionId, state }: {
+        sessionId: string;
+        state: Partial<typeof stateAnnotation.State>;
+    }): Promise<void>;
+    getState(sessionId: string): Promise<State<z.infer<typeof this.memorySchema>>>;
+    startVoiceSession(params: {
+        sessionId: string;
+        metadata?: Record<string, any>;
+    }): Promise<VoiceSession>;
+    timerTrigger(params: {
+        sessionId: string;
+        timerName: string;
+        eventArgs: Record<string, any>;
+    }): Promise<void>;
+    restoreCheckpoint(sessionId: string, checkpointId: string): Promise<void>;
+    /**
+     * Execute a tool by name with given parameters
+     * This is used for standalone tool execution (e.g., from browser-use)
+     */
+    executeTool(request: ToolExecutionRequest): Promise<ToolExecutionResponse>;
+    getCurrentNode(sessionId: string): Promise<Node | null | undefined>;
+    /**
+     * Query an Vector Store collection for relevant documents.
+     *
+     * This method sends a query to the backend vector store service to retrieve documents
+     * from a specified collection that match the given query.
+     *
+     * @param collectionName - The name of the vector store collection to query
+     * @param query - The search query string
+     * @param options - Optional parameters for the query
+     * @param options.filter - Optional filter to apply to the search
+     * @param options.numChunks - Number of document chunks to return (default: from vector store config)
+     * @param options.minScore - Minimum similarity score threshold (default: no minimum)
+     *
+     * @returns Promise that resolves with an array of documents containing pageContent and metadata
+     *
+     * @throws {Error} When not connected to the Minded platform
+     * @throws {Error} When the vector store query fails
+     *
+     */
+    getDocumentsFromDB(collectionName: string, query: string, options?: {
+        filter?: any;
+        numChunks?: number;
+        minScore?: number;
+    }, timeoutMs?: number): Promise<Document[]>;
+    onEnd(): void;
+    /**
+     * Process any queued messages for a session.
+     * If a message is found, it will be processed recursively.
+     * If no messages are found, checks if the graph was interrupted and resumes if needed.
+     * Only releases the lock when there's nothing left to process.
+     *
+     * @param sessionId - The session ID to check for queued messages
+     * @returns The result of processing the next message or resuming the graph, or undefined if nothing to process
+     */
+    private processQueuedMessages;
+}
+export {};
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

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