@loopman/langchain-sdk 1.7.0 → 1.12.0

package/dist/langgraph/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * LangGraph Integration for Loopman
+ *
+ * This module provides LangGraph nodes and utilities for integrating
+ * Human-in-the-Loop validation into your workflows.
+ */
+export { LoopmanGraphState } from "./types";
+export type { LoopmanGuideline, LoopmanDecision } from "./types";
+export { createLoopmanValidationNode } from "./loopman-validation-node";
+export type { LoopmanValidationNodeConfig } from "./loopman-validation-node";
+export { createLoopmanConditionalEdge } from "./loopman-conditional-edge";
+export { createLoopmanContextNode } from "./loopman-context-node";
+export type { LoopmanContextNodeConfig } from "./loopman-context-node";
+export { enrichSystemPrompt, formatGuidelines, formatDecisionContext, hasLoopmanContext, getCriticalGuidelines, getLatestDecision, } from "./helpers";
+export type { EnrichSystemPromptOptions } from "./helpers";
+//# sourceMappingURL=index.d.ts.map

package/dist/langgraph/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/langgraph/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGjE,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,YAAY,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAG7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAC;AAG1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,YAAY,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAGvE,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC"}

package/dist/langgraph/index.js

@@ -0,0 +1,17 @@
+/**
+ * LangGraph Integration for Loopman
+ *
+ * This module provides LangGraph nodes and utilities for integrating
+ * Human-in-the-Loop validation into your workflows.
+ */
+// Export types and state
+export { LoopmanGraphState } from "./types";
+// Export validation node
+export { createLoopmanValidationNode } from "./loopman-validation-node";
+// Export conditional edge
+export { createLoopmanConditionalEdge } from "./loopman-conditional-edge";
+// Export context node
+export { createLoopmanContextNode } from "./loopman-context-node";
+// Export helper functions
+export { enrichSystemPrompt, formatGuidelines, formatDecisionContext, hasLoopmanContext, getCriticalGuidelines, getLatestDecision, } from "./helpers";
+//# sourceMappingURL=index.js.map

package/dist/langgraph/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/langgraph/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yBAAyB;AACzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAG5C,yBAAyB;AACzB,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAGxE,0BAA0B;AAC1B,OAAO,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAC;AAE1E,sBAAsB;AACtB,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAGlE,0BAA0B;AAC1B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,WAAW,CAAC"}

package/dist/langgraph/loopman-conditional-edge.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Loopman Conditional Edge for LangGraph
+ *
+ * This conditional edge routes the workflow based on the Loopman task status
+ * after human validation.
+ */
+/**
+ * Creates a conditional edge function for routing based on Loopman task status
+ *
+ * **Works with any state**: This function only reads `loopmanTaskStatus` from
+ * the state. You can use it with any custom state that includes this field.
+ *
+ * @param options - Optional configuration
+ * @param options.debug - Enable debug logging
+ * @returns Function that routes based on loopmanTaskStatus
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createLoopmanConditionalEdge } from "loopman-langchain-sdk";
+ * import { StateGraph, END } from "@langchain/langgraph";
+ *
+ * const workflow = new StateGraph(LoopmanGraphState)
+ *   .addNode("agent", agentNode)
+ *   .addNode("validation", validationNode)
+ *   .addNode("tools", toolNode)
+ *   .addConditionalEdges(
+ *     "validation",
+ *     createLoopmanConditionalEdge({ debug: true }),
+ *     {
+ *       execute: "tools",     // APPROVED → execute tool
+ *       rejected: END,        // REJECTED → end workflow
+ *       retry: "agent",       // NEEDS_CHANGES → retry with feedback
+ *       timeout: END,         // TIMEOUT → end workflow
+ *       error: END            // ERROR → end workflow
+ *     }
+ *   );
+ * ```
+ *
+ * @example Custom routing
+ * ```typescript
+ * const workflow = new StateGraph(MyState)
+ *   .addConditionalEdges(
+ *     "validation",
+ *     createLoopmanConditionalEdge(),
+ *     {
+ *       execute: "execute_action",
+ *       rejected: "notify_rejection",
+ *       retry: "agent_with_context",
+ *       timeout: "handle_timeout",
+ *       error: "handle_error",
+ *     }
+ *   );
+ * ```
+ */
+export declare function createLoopmanConditionalEdge(options?: {
+    debug?: boolean;
+}): (state: any) => string;
+//# sourceMappingURL=loopman-conditional-edge.d.ts.map

package/dist/langgraph/loopman-conditional-edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopman-conditional-edge.d.ts","sourceRoot":"","sources":["../../src/langgraph/loopman-conditional-edge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,IAChE,OAAO,GAAG,KAAG,MAAM,CA0B5B"}

package/dist/langgraph/loopman-conditional-edge.js

@@ -0,0 +1,77 @@
+/**
+ * Loopman Conditional Edge for LangGraph
+ *
+ * This conditional edge routes the workflow based on the Loopman task status
+ * after human validation.
+ */
+/**
+ * Creates a conditional edge function for routing based on Loopman task status
+ *
+ * **Works with any state**: This function only reads `loopmanTaskStatus` from
+ * the state. You can use it with any custom state that includes this field.
+ *
+ * @param options - Optional configuration
+ * @param options.debug - Enable debug logging
+ * @returns Function that routes based on loopmanTaskStatus
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createLoopmanConditionalEdge } from "loopman-langchain-sdk";
+ * import { StateGraph, END } from "@langchain/langgraph";
+ *
+ * const workflow = new StateGraph(LoopmanGraphState)
+ *   .addNode("agent", agentNode)
+ *   .addNode("validation", validationNode)
+ *   .addNode("tools", toolNode)
+ *   .addConditionalEdges(
+ *     "validation",
+ *     createLoopmanConditionalEdge({ debug: true }),
+ *     {
+ *       execute: "tools",     // APPROVED → execute tool
+ *       rejected: END,        // REJECTED → end workflow
+ *       retry: "agent",       // NEEDS_CHANGES → retry with feedback
+ *       timeout: END,         // TIMEOUT → end workflow
+ *       error: END            // ERROR → end workflow
+ *     }
+ *   );
+ * ```
+ *
+ * @example Custom routing
+ * ```typescript
+ * const workflow = new StateGraph(MyState)
+ *   .addConditionalEdges(
+ *     "validation",
+ *     createLoopmanConditionalEdge(),
+ *     {
+ *       execute: "execute_action",
+ *       rejected: "notify_rejection",
+ *       retry: "agent_with_context",
+ *       timeout: "handle_timeout",
+ *       error: "handle_error",
+ *     }
+ *   );
+ * ```
+ */
+export function createLoopmanConditionalEdge(options) {
+    return (state) => {
+        const { loopmanTaskStatus } = state;
+        void options; // Debug logging intentionally omitted (library is silent by default)
+        switch (loopmanTaskStatus) {
+            case "APPROVED":
+                return "execute"; // Proceed to tool execution
+            case "REJECTED":
+                return "rejected"; // End workflow
+            case "NEEDS_CHANGES":
+                return "retry"; // Loop back to agent for correction
+            case "TIMEOUT":
+                return "timeout"; // Handle timeout case
+            case "PENDING":
+                // Should not happen after polling completes, but handle gracefully
+                return "timeout";
+            case "ERROR":
+            default:
+                return "error"; // Handle errors
+        }
+    };
+}
+//# sourceMappingURL=loopman-conditional-edge.js.map

package/dist/langgraph/loopman-conditional-edge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopman-conditional-edge.js","sourceRoot":"","sources":["../../src/langgraph/loopman-conditional-edge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,UAAU,4BAA4B,CAAC,OAA6B;IACxE,OAAO,CAAC,KAAU,EAAU,EAAE;QAC5B,MAAM,EAAE,iBAAiB,EAAE,GAAG,KAAK,CAAC;QACpC,KAAK,OAAO,CAAC,CAAC,qEAAqE;QAEnF,QAAQ,iBAAiB,EAAE,CAAC;YAC1B,KAAK,UAAU;gBACb,OAAO,SAAS,CAAC,CAAC,4BAA4B;YAEhD,KAAK,UAAU;gBACb,OAAO,UAAU,CAAC,CAAC,eAAe;YAEpC,KAAK,eAAe;gBAClB,OAAO,OAAO,CAAC,CAAC,oCAAoC;YAEtD,KAAK,SAAS;gBACZ,OAAO,SAAS,CAAC,CAAC,sBAAsB;YAE1C,KAAK,SAAS;gBACZ,mEAAmE;gBACnE,OAAO,SAAS,CAAC;YAEnB,KAAK,OAAO,CAAC;YACb;gBACE,OAAO,OAAO,CAAC,CAAC,gBAAgB;QACpC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/langgraph/loopman-context-node.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Loopman Context Enrichment Node for LangGraph
+ *
+ * This node fetches validation guidelines and historical decision context
+ * from Loopman API and adds them to the graph state.
+ */
+/**
+ * Configuration for the Loopman context enrichment node
+ */
+export interface LoopmanContextNodeConfig {
+    /** Loopman API key for authentication */
+    apiKey: string;
+    /** Workflow identifier */
+    workflowId: string;
+    /** Execution identifier (auto-generated if not provided) */
+    executionId?: string;
+    /** Category to filter guidelines (optional, use "none" for all) */
+    category?: string;
+    /** Whether to fetch guidelines (default: true) */
+    includeGuidelines?: boolean;
+    /** Whether to fetch decision history (default: true) */
+    includeDecisionHistory?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Factory function to create a Loopman context enrichment node
+ *
+ * This node fetches validation guidelines and historical decision context
+ * from Loopman API and adds them to the graph state. This enriched context
+ * can then be used by agents to make better-informed decisions.
+ *
+ * **Works with any state**: This node only adds `guidelines` and `decisionContext`
+ * to your state. It doesn't require `LoopmanGraphState` - you can use your own
+ * custom state with any fields you want!
+ *
+ * @example With LoopmanGraphState
+ * ```typescript
+ * import { createLoopmanContextNode, LoopmanGraphState } from "loopman-langchain-sdk";
+ *
+ * const contextNode = createLoopmanContextNode({
+ *   apiKey: process.env.LOOPMAN_API_KEY!,
+ *   workflowId: "my-workflow",
+ *   category: "email", // Optional category filter
+ * });
+ *
+ * const workflow = new StateGraph(LoopmanGraphState)
+ *   .addNode("load_context", contextNode)
+ *   .addNode("agent", agentNode)
+ *   .addEdge(START, "load_context")
+ *   .addEdge("load_context", "agent");
+ * ```
+ *
+ * @example With custom state
+ * ```typescript
+ * const MyCustomState = Annotation.Root({
+ *   messages: Annotation<BaseMessage[]>({ ... }),
+ *   myCustomField: Annotation<string>({ ... }),
+ *   guidelines: Annotation<LoopmanGuideline[]>({ ... }), // Add Loopman fields
+ *   decisionContext: Annotation<LoopmanDecision[]>({ ... }), // to your state
+ * });
+ *
+ * const contextNode = createLoopmanContextNode({
+ *   apiKey: process.env.LOOPMAN_API_KEY!,
+ *   workflowId: "my-workflow",
+ * });
+ *
+ * const workflow = new StateGraph(MyCustomState)
+ *   .addNode("load_context", contextNode) // Works with custom state!
+ *   .addNode("agent", agentNode);
+ * ```
+ */
+export declare function createLoopmanContextNode(config: LoopmanContextNodeConfig): (state: any) => Promise<any>;
+//# sourceMappingURL=loopman-context-node.d.ts.map

package/dist/langgraph/loopman-context-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopman-context-node.d.ts","sourceRoot":"","sources":["../../src/langgraph/loopman-context-node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wDAAwD;IACxD,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,IAczD,OAAO,GAAG,KAAG,OAAO,CAAC,GAAG,CAAC,CAiHxC"}

package/dist/langgraph/loopman-context-node.js

@@ -0,0 +1,143 @@
+/**
+ * Loopman Context Enrichment Node for LangGraph
+ *
+ * This node fetches validation guidelines and historical decision context
+ * from Loopman API and adds them to the graph state.
+ */
+import { LoopmanService } from "../services/loopman.service";
+/**
+ * Factory function to create a Loopman context enrichment node
+ *
+ * This node fetches validation guidelines and historical decision context
+ * from Loopman API and adds them to the graph state. This enriched context
+ * can then be used by agents to make better-informed decisions.
+ *
+ * **Works with any state**: This node only adds `guidelines` and `decisionContext`
+ * to your state. It doesn't require `LoopmanGraphState` - you can use your own
+ * custom state with any fields you want!
+ *
+ * @example With LoopmanGraphState
+ * ```typescript
+ * import { createLoopmanContextNode, LoopmanGraphState } from "loopman-langchain-sdk";
+ *
+ * const contextNode = createLoopmanContextNode({
+ *   apiKey: process.env.LOOPMAN_API_KEY!,
+ *   workflowId: "my-workflow",
+ *   category: "email", // Optional category filter
+ * });
+ *
+ * const workflow = new StateGraph(LoopmanGraphState)
+ *   .addNode("load_context", contextNode)
+ *   .addNode("agent", agentNode)
+ *   .addEdge(START, "load_context")
+ *   .addEdge("load_context", "agent");
+ * ```
+ *
+ * @example With custom state
+ * ```typescript
+ * const MyCustomState = Annotation.Root({
+ *   messages: Annotation<BaseMessage[]>({ ... }),
+ *   myCustomField: Annotation<string>({ ... }),
+ *   guidelines: Annotation<LoopmanGuideline[]>({ ... }), // Add Loopman fields
+ *   decisionContext: Annotation<LoopmanDecision[]>({ ... }), // to your state
+ * });
+ *
+ * const contextNode = createLoopmanContextNode({
+ *   apiKey: process.env.LOOPMAN_API_KEY!,
+ *   workflowId: "my-workflow",
+ * });
+ *
+ * const workflow = new StateGraph(MyCustomState)
+ *   .addNode("load_context", contextNode) // Works with custom state!
+ *   .addNode("agent", agentNode);
+ * ```
+ */
+export function createLoopmanContextNode(config) {
+    const loopmanService = new LoopmanService({
+        apiKey: config.apiKey,
+        workflowId: config.workflowId,
+        executionId: config.executionId || `exec-${Date.now()}`,
+        debug: config.debug,
+    });
+    const includeGuidelines = config.includeGuidelines ?? true;
+    const includeDecisionHistory = config.includeDecisionHistory ?? true;
+    const debug = config.debug ?? false;
+    const logger = loopmanService.logger;
+    const executionId = config.executionId || `exec-${Date.now()}`;
+    return async (state) => {
+        logger.debug("[LoopmanContextNode] Loading context...");
+        const updates = {};
+        // Fetch guidelines if requested
+        if (includeGuidelines) {
+            try {
+                logger.debug(`[LoopmanContextNode] Fetching guidelines via API (category: ${config.category || "all"})`);
+                const response = await loopmanService.getGuidelines(config.category || undefined);
+                // Convert API response to graph state format (lowercase severity)
+                updates.guidelines = response.guidelines.map((g) => ({
+                    ruleId: g.ruleId,
+                    description: g.description,
+                    category: g.category,
+                    severity: g.severity.toLowerCase(),
+                }));
+                logger.debug(`[LoopmanContextNode] Loaded ${response.guidelines.length} guideline(s) via API`, {
+                    severities: response.guidelines.length > 0
+                        ? response.guidelines.map((g) => g.severity)
+                        : [],
+                });
+            }
+            catch (error) {
+                if (debug) {
+                    logger.error(`[LoopmanContextNode] Failed to fetch guidelines via API: ${error.message}`);
+                }
+                // Continue execution with empty guidelines
+                updates.guidelines = [];
+            }
+        }
+        // Fetch decision context if requested
+        if (includeDecisionHistory) {
+            // Check if state contains a taskId - if so, we need to fetch from the task directly
+            const taskId = state.taskId;
+            if (taskId) {
+                logger.debug(`[LoopmanContextNode] TaskId found in state (${taskId}) - fetching task-specific decisions`);
+                try {
+                    const task = await loopmanService.getTask(taskId);
+                    const response = loopmanService.getDecisionContextFromTask(task);
+                    updates.decisionContext = response.decisions;
+                    logger.debug(`[LoopmanContextNode] Loaded ${response.decisions.length} decision(s) from task ${taskId}`, {
+                        latest: response.decisions.length > 0
+                            ? response.decisions[response.decisions.length - 1]
+                            : null,
+                    });
+                }
+                catch (error) {
+                    if (debug) {
+                        logger.error(`[LoopmanContextNode] Failed to fetch decisions from task: ${error.message}`);
+                    }
+                    updates.decisionContext = [];
+                }
+            }
+            else {
+                // No taskId: fetch execution-level decisions
+                try {
+                    logger.debug(`[LoopmanContextNode] Fetching execution-level decisions (executionId: ${executionId})`);
+                    const response = await loopmanService.getDecisionContext(executionId);
+                    updates.decisionContext = response.decisions;
+                    logger.debug(`[LoopmanContextNode] Loaded ${response.decisions.length} decision(s) for execution`, {
+                        latest: response.decisions.length > 0
+                            ? response.decisions[response.decisions.length - 1]
+                            : null,
+                    });
+                }
+                catch (error) {
+                    if (debug) {
+                        logger.error(`[LoopmanContextNode] Failed to fetch decision context: ${error.message}`);
+                    }
+                    updates.decisionContext = [];
+                }
+            }
+        }
+        logger.debug("[LoopmanContextNode] Context loaded successfully");
+        return updates;
+    };
+}
+//# sourceMappingURL=loopman-context-node.js.map

package/dist/langgraph/loopman-context-node.js.map

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

package/dist/langgraph/loopman-validation-node.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Loopman Validation Node for LangGraph
+ *
+ * This node handles human-in-the-loop validation by:
+ * 1. Extracting tool calls from agent messages
+ * 2. Creating validation tasks in Loopman
+ * 3. Polling for human decisions
+ * 4. Enriching state with guidelines and decision context
+ */
+import { TaskInformation } from "../types";
+/**
+ * Configuration for Loopman validation node
+ */
+export interface LoopmanValidationNodeConfig {
+    /** Loopman API key for authentication */
+    apiKey: string;
+    /** Workflow identifier */
+    workflowId: string;
+    /** Execution identifier (auto-generated if not provided) */
+    executionId?: string;
+    /** Category to filter guidelines (optional) */
+    category?: string;
+    /** Polling timeout in milliseconds (default: 5 minutes) */
+    timeout?: number;
+    /** Polling interval in milliseconds (default: 5 seconds) */
+    pollingInterval?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom title for the task (default: "Tool validation") */
+    taskTitle?: string;
+    /** Custom message/description to display when creating task */
+    taskMessage?: string;
+    /** Custom function to extract tool call from message */
+    extractToolCall?: (messages: any[]) => {
+        name: string;
+        args: any;
+        id: string;
+    } | null;
+    /** Business context to include in the task (or function to extract from state) */
+    businessContext?: string | ((state: any) => string);
+    /** Proposed decision to include in the task (or function to extract from state) */
+    proposedDecision?: string | ((state: any) => string);
+    /** Decision reasoning to include in the task (or function to extract from state) */
+    decisionReasoning?: string | ((state: any) => string);
+    /** Whether to include full state in task information (default: false) */
+    includeFullState?: boolean;
+    /** Custom function to format state for task information (if not provided, uses JSON.stringify) */
+    formatState?: (state: any) => TaskInformation[];
+}
+/**
+ * Creates a Loopman validation node for LangGraph
+ *
+ * This node:
+ * 1. Extracts the tool call from the last AI message
+ * 2. Creates a Loopman task for human validation
+ * 3. Polls until human decision is received
+ * 4. Automatically enriches state with guidelines and decisionContext
+ *
+ * **Works with any state**: This node reads `messages` and `requiresValidation`
+ * from the state, and updates it with `loopmanTaskId`, `loopmanTaskStatus`,
+ * `guidelines`, and `decisionContext`. You can use your own custom state schema!
+ *
+ * **Context Enrichment**: After validation, this node automatically fetches
+ * and adds `guidelines` and `decisionContext` to the state, making them
+ * available for the agent on retry (NEEDS_CHANGES) or subsequent executions.
+ *
+ * **State Inclusion**: You can include the full agent state in the task information
+ * by setting `includeFullState: true`. This helps human reviewers understand the
+ * complete context of the decision. You can also provide custom formatters.
+ *
+ * **Decision Context**: You can provide business context, proposed decisions, and
+ * reasoning either as static strings or as functions that extract from the state.
+ *
+ * @example Basic usage with LoopmanGraphState
+ * ```typescript
+ * import { createLoopmanValidationNode, LoopmanGraphState } from "loopman-langchain-sdk";
+ *
+ * const loopmanNode = createLoopmanValidationNode({
+ *   apiKey: process.env.LOOPMAN_API_KEY!,
+ *   workflowId: "my-workflow",
+ *   executionId: `exec-${Date.now()}`,
+ *   timeout: 5 * 60 * 1000,
+ *   pollingInterval: 5000,
+ *   debug: true,
+ *   taskTitle: "Email Validation", // Custom title
+ *   taskMessage: "Please review this action" // Custom description
+ * });
+ *
+ * workflow.addNode("loopman_validation", loopmanNode);
+ * ```
+ *
+ * @example With full state and decision context
+ * ```typescript
+ * const loopmanNode = createLoopmanValidationNode({
+ *   apiKey: process.env.LOOPMAN_API_KEY!,
+ *   workflowId: "my-workflow",
+ *   includeFullState: true, // Include all state in task information
+ *   businessContext: (state) => `Processing user request: ${state.userQuery}`,
+ *   proposedDecision: (state) => `Execute ${state.currentAction} on ${state.targetResource}`,
+ *   decisionReasoning: (state) => state.reasoning || "No specific reasoning provided",
+ * });
+ * ```
+ *
+ * @example With custom state formatter
+ * ```typescript
+ * const loopmanNode = createLoopmanValidationNode({
+ *   apiKey: process.env.LOOPMAN_API_KEY!,
+ *   workflowId: "my-workflow",
+ *   includeFullState: true,
+ *   formatState: (state) => [
+ *     { type: "text", label: "User", value: state.userId },
+ *     { type: "text", label: "Action", value: state.action },
+ *     { type: "bulletPoints", label: "Parameters", value: Object.keys(state.params) },
+ *   ],
+ * });
+ * ```
+ */
+export declare function createLoopmanValidationNode(config: LoopmanValidationNodeConfig): (state: any) => Promise<any>;
+//# sourceMappingURL=loopman-validation-node.d.ts.map

package/dist/langgraph/loopman-validation-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopman-validation-node.d.ts","sourceRoot":"","sources":["../../src/langgraph/loopman-validation-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG3C;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK;QACrC,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,GAAG,CAAC;QACV,EAAE,EAAE,MAAM,CAAC;KACZ,GAAG,IAAI,CAAC;IACT,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,CAAC,CAAC;IACpD,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,CAAC,CAAC;IACrD,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,CAAC,CAAC;IACtD,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kGAAkG;IAClG,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,eAAe,EAAE,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,2BAA2B,IAerB,OAAO,GAAG,kBAmNzB"}