@loopman/langchain-sdk 1.12.1 → 1.12.3

package/README.md

@@ -1,65 +1,99 @@
-# Loopman SDK TypeScript
+# Loopman LangChain SDK
 
-A TypeScript SDK demonstrating AI agent development with LangChain v1.0 and Human-in-the-Loop (HITL) validation patterns.
+Official TypeScript SDK for integrating Human-in-the-Loop (HITL) validation into LangChain AI agents via the [Loopman platform](https://loopman.ai).
 
 ## 📋 Table of Contents
 
 - [Overview](#overview)
+- [What is Loopman?](#what-is-loopman)
 - [Features](#features)
 - [Prerequisites](#prerequisites)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Examples](#examples)
-- [Loopman Middleware](#loopman-middleware)
+- [LangGraph Integration](#langgraph-integration)
 - [Debugging](#debugging)
 - [Project Structure](#project-structure)
 - [API Reference](#api-reference)
 - [Development](#development)
+- [Related Resources](#related-resources)
 - [License](#license)
 
 ---
 
 ## 🎯 Overview
 
-This SDK provides a comprehensive demonstration of building AI agents with LangChain v1.0, featuring:
+The Loopman LangChain SDK enables you to add human validation and oversight to your AI agents built with LangChain v1.0+. It provides seamless integration with the [Loopman platform](https://app.loopman.ai), allowing humans to approve, modify, or reject AI decisions in real-time through a modern mobile and web interface.
 
-- **Simple Agent Pattern**: Basic tool usage with conversational memory
-- **Human-in-the-Loop Validation**: Using LangChain's native `humanInTheLoopMiddleware`
-- **Loopman Integration**: Custom middleware for Loopman platform integration
+---
+
+## 🤖 What is Loopman?
+
+**[Loopman](https://loopman.ai)** is a Human-in-the-Loop platform that bridges AI agent orchestrators (LangChain, n8n, Zapier, Make) with human users for real-time validation, correction, or rejection of AI decisions.
+
+**Key capabilities:**
 
-Perfect for learning agent patterns, HITL workflows, and building production-ready AI assistants.
+- 📱 Mobile-first interface for rapid decision-making on-the-go
+- 💻 Web dashboard for detailed review and oversight
+- 🔔 Real-time push notifications when AI agents need approval
+- 🔄 **Feedback loop**: Humans can reject decisions with feedback, enabling agents to learn and auto-correct
+- 📊 Decision history and audit trails
+- 🎯 Context-aware guidelines for consistent decision-making
+
+**Use cases:** Email approval workflows, financial transaction validation, content moderation, data modification approval, critical operation oversight, compliance checkpoints.
 
 ---
 
 ## ✨ Features
 
+### 🛡️ Human-in-the-Loop Validation
+
+- ✅ **Transparent Integration**: Middleware handles validation automatically
+- ✅ **Selective Interruption**: Configure which tools require approval
+- ✅ **Multiple Decision Types**: Approve, Edit with modifications, or Reject with feedback
+- ✅ **Automatic Polling**: Real-time decision retrieval with configurable intervals
+- ✅ **Timeout Handling**: Built-in timeout and retry logic
+- ✅ **Context Enrichment**: Automatic guidelines and decision history integration
+
+### 🔄 Feedback Loop - Learn from Human Decisions
+
+- ✅ **Human Rejection with Feedback**: When humans reject a decision, they can provide detailed feedback explaining why
+- ✅ **Automatic Agent Retry**: The agent receives the feedback and automatically retries with corrections
+- ✅ **Context Learning**: Feedback is stored in decision history and injected into future agent prompts
+- ✅ **Iterative Refinement**: Agents learn from past mistakes and improve over time
+- ✅ **Workflow Routing**: LangGraph conditional edges automatically route to retry logic on `NEEDS_CHANGES` status
+
+**Example workflow:**
+
+1. Agent proposes to send an email with incorrect tone
+2. Human rejects with feedback: "Use a more professional tone"
+3. Agent receives feedback and retries with corrected tone
+4. Human approves the refined version
+5. Future similar tasks benefit from this learned context
+
+### 🔗 LangGraph Support
+
+- ✅ **Validation Nodes**: Reusable nodes for human approval workflows
+- ✅ **Conditional Routing**: Route based on human decisions (approve/reject/retry)
+- ✅ **Context Loading**: Automatic guidelines and decision history retrieval
+- ✅ **State Management**: Full integration with LangGraph state
+- ✅ **Helper Functions**: `enrichSystemPrompt()` for context injection
+
 ### 🤖 Agent Capabilities
 
+- ✅ **High-Level Agent API**: `createLoopmanAgent()` for quick setup
 - ✅ **Tool Calling**: Dynamic tool execution with Zod validation
 - ✅ **Conversational Memory**: Stateful conversations with checkpointers
-- ✅ **Multi-turn Interactions**: Context-aware dialogue management
-- ✅ **Streaming Support**: Real-time response streaming
-
-### 🛡️ Human-in-the-Loop
-
-- ✅ **Native HITL Middleware**: LangChain's `humanInTheLoopMiddleware`
-- ✅ **Custom Loopman Middleware**: Platform-specific integration
-- ✅ **LangGraph Integration**: Reusable validation nodes with conditional routing
-- ✅ **Full State Sharing**: Send complete agent state to human reviewers
-- ✅ **Business Context**: Define context, proposed decisions, and reasoning
-- ✅ **Context Enrichment**: Automatic guidelines and decision history integration
-- ✅ **Helper Functions**: `enrichSystemPrompt()` for simplified agent integration
-- ✅ **Decision Types**: Approve, Edit, Reject workflows
-- ✅ **Selective Interruption**: Per-tool configuration
-- ✅ **Double Validation Layer**: Global MCP validation + tool-specific validation
-- ✅ **Flexible Execution Modes**: Auto-execution or manual control after approval
+- ✅ **MCP Integration**: Model Context Protocol support for advanced workflows
+- ✅ **Double Validation Layer**: Global + tool-specific validation
 
 ### 🔧 Developer Experience
 
-- ✅ **TypeScript**: Full type safety with TSDoc comments
+- ✅ **TypeScript**: Full type safety with comprehensive types
+- ✅ **Multiple Integration Patterns**: Middleware, Agent API, LangGraph nodes
 - ✅ **Debugging**: VSCode launch configurations
-- ✅ **Examples**: Three complete working examples
-- ✅ **Documentation**: Inline comments and guides
+- ✅ **Real-World Examples**: Production-ready code samples
+- ✅ **Comprehensive Documentation**: Inline comments and guides
 
 ---
 
@@ -67,6 +101,7 @@ Perfect for learning agent patterns, HITL workflows, and building production-rea
 
 - **Node.js**: 18+
 - **OpenAI API Key**: Required for model calls
+- **Loopman Account**: Sign up at [https://app.loopman.ai](https://app.loopman.ai) to get your API key
 - **npm/yarn**: Package manager
 
 ---
@@ -91,7 +126,7 @@ Edit `.env` and add your API keys:
 
 ```env
 OPENAI_API_KEY=sk-your-openai-api-key-here
-LOOPMAN_API_KEY=your-loopman-api-key-here  # Optional
+LOOPMAN_API_KEY=your-loopman-api-key-here  # Get your API key at https://app.loopman.ai
 ```
 
 ---
@@ -130,46 +165,29 @@ const result = await agent.invoke(
 );
 ```
 
-### Human-in-the-Loop Agent
-
-```typescript
-import { humanInTheLoopMiddleware } from "langchain";
-
-const agent = createAgent({
-  model: "openai:gpt-4o-mini",
-  tools: [sendEmail],
-  middleware: [
-    humanInTheLoopMiddleware({
-      interruptOn: {
-        send_email: {
-          allowedDecisions: ["approve", "edit", "reject"],
-          description: "⚠️ Email requires approval",
-        },
-      },
-    }),
-  ],
-  checkpointer: new MemorySaver(),
-});
-```
-
-### Loopman Platform Integration
+### Middleware Integration (Standard HITL Process)
 
 ```typescript
-import { loopmanMiddleware } from "./src/loopman-middleware";
+import { createAgent } from "langchain";
+import { loopmanMiddleware } from "@loopman/langchain-sdk";
+import { MemorySaver } from "@langchain/langgraph";
 
+// Create agent with Loopman middleware
 const agent = createAgent({
   model: "openai:gpt-4o-mini",
-  tools: [sendEmail],
+  tools: [sendEmail, readEmail],
   middleware: [
     loopmanMiddleware({
       apiKey: process.env.LOOPMAN_API_KEY!,
       workflowId: "email-workflow",
+      mode: "tool-validation", // or "prompt-enhancement" or "full"
       interruptOn: {
         send_email: true, // Requires validation
         read_email: false, // Auto-approved
       },
+      timeout: 5 * 60 * 1000, // 5 minutes
       pollingInterval: 5000, // Poll every 5 seconds
-      timeout: 300000, // 5 minutes
+      debug: true,
     }),
   ],
   checkpointer: new MemorySaver(),
@@ -185,49 +203,157 @@ const result = await agent.invoke(
 // ✅ Middleware handles HITL transparently
 ```
 
-### LangGraph with Context Enrichment
+### Loopman Agent (Complete Solution - Ready to Use)
+
+**What's the difference with Middleware?**
+
+The **Middleware** requires you to build and configure your own agent, then add validation on top.
+
+The **Loopman Agent** is a **ready-to-use agent** that includes everything:
+
+- ✅ Pre-built agent with validation already integrated
+- ✅ Automatic loading of guidelines and past decisions (feedback loop)
+- ✅ Simple API: just call `processWithHumanValidation()`
+- ✅ No manual configuration needed
+
+**Perfect for:** Quick start, prototyping, or when you want a complete solution out-of-the-box.
+
+```typescript
+import { createLoopmanAgent } from "@loopman/langchain-sdk";
+
+const agent = createLoopmanAgent({
+  apiKey: process.env.LOOPMAN_API_KEY!,
+  workflowId: "email-workflow",
+  model: "openai:gpt-4o-mini",
+  systemPrompt: "You are a helpful email assistant",
+  additionalTools: [sendEmail, readEmail],
+  requireApprovalForTools: ["send_email"], // Only email sending requires approval
+  debug: true,
+});
+
+// Usage - Simple and transparent!
+const result = await agent.processWithHumanValidation({
+  input: "Send email to alice@example.com about the meeting",
+});
+// ✅ Agent automatically handles validation via Loopman platform (https://app.loopman.ai)
+```
+
+### LangGraph Integration (Recommended)
 
 ```typescript
 import {
   LoopmanGraphState,
   createLoopmanContextNode,
+  createLoopmanValidationNode,
+  createLoopmanConditionalEdge,
   enrichSystemPrompt,
-} from "loopman-langchain-sdk";
-import { StateGraph } from "@langchain/langgraph";
+} from "@loopman/langchain-sdk";
+import { StateGraph, START, END } from "@langchain/langgraph";
+import { ChatOpenAI } from "@langchain/openai";
 
 // 1. Create context node to load guidelines and decision history
 const contextNode = createLoopmanContextNode({
   apiKey: process.env.LOOPMAN_API_KEY!,
   workflowId: "my-workflow",
   category: "email",
+  debug: true,
 });
 
-// 2. Use context in agent with one-liner
+// 2. Create validation node for human approval
+const validationNode = createLoopmanValidationNode({
+  apiKey: process.env.LOOPMAN_API_KEY!,
+  workflowId: "my-workflow",
+  debug: true,
+});
+
+// 3. Agent node with context-enriched prompts
 async function agentNode(state: typeof LoopmanGraphState.State) {
   const { messages, guidelines, decisionContext } = state;
 
   // ✨ Automatically enrich system prompt with Loopman context
-  const systemPrompt = enrichSystemPrompt("You are a helpful assistant.", {
-    guidelines,
-    decisionContext,
-  });
+  const systemPrompt = enrichSystemPrompt(
+    "You are a helpful email assistant.",
+    { guidelines, decisionContext },
+    { maxDecisions: 3 } // Show last 3 decisions
+  );
+
+  const model = new ChatOpenAI({ model: "gpt-4o-mini" });
+  const modelWithTools = model.bindTools([sendEmail]);
 
-  const response = await model.invoke([
+  const messagesWithContext = [
     { role: "system", content: systemPrompt },
     ...messages,
-  ]);
+  ];
 
-  return { messages: [response] };
+  const response = await modelWithTools.invoke(messagesWithContext);
+
+  return {
+    messages: [response],
+    requiresValidation: response.tool_calls && response.tool_calls.length > 0,
+  };
 }
 
-// 3. Build workflow
+// 4. Tool execution node
+async function toolNode(state: typeof LoopmanGraphState.State) {
+  const { messages } = state;
+  const lastMessage = messages[messages.length - 1];
+
+  if (!lastMessage.tool_calls || lastMessage.tool_calls.length === 0) {
+    return {};
+  }
+
+  const toolCall = lastMessage.tool_calls[0];
+  const result = await sendEmail.invoke(toolCall.args);
+
+  return {
+    messages: [
+      new ToolMessage({
+        content: typeof result === "string" ? result : JSON.stringify(result),
+        tool_call_id: toolCall.id,
+      }),
+    ],
+    requiresValidation: false,
+  };
+}
+
+// 5. Build workflow with validation and conditional routing
 const workflow = new StateGraph(LoopmanGraphState)
   .addNode("load_context", contextNode)
   .addNode("agent", agentNode)
+  .addNode("loopman_validation", validationNode)
+  .addNode("tools", toolNode)
+
   .addEdge(START, "load_context")
-  .addEdge("load_context", "agent");
+  .addEdge("load_context", "agent")
+  .addEdge("agent", "loopman_validation")
+  .addConditionalEdges(
+    "loopman_validation",
+    createLoopmanConditionalEdge({ debug: true }),
+    {
+      execute: "tools", // APPROVED → execute tool
+      rejected: END, // REJECTED → end workflow
+      retry: "agent", // NEEDS_CHANGES with feedback → retry agent (FEEDBACK LOOP!)
+      timeout: END, // TIMEOUT → end workflow
+      error: END, // ERROR → end workflow
+    }
+  )
+  .addEdge("tools", END);
+
+const app = workflow.compile({ checkpointer: new MemorySaver() });
 ```
 
+**🔄 Feedback Loop in Action:**
+
+When a human rejects a decision with status `NEEDS_CHANGES`:
+
+1. The validation node stores the human's feedback in `decisionContext`
+2. The conditional edge routes to `retry: "agent"` instead of ending
+3. The agent node receives the feedback via `enrichSystemPrompt()`
+4. The agent corrects its decision based on human feedback
+5. The workflow loops back to validation until approved
+
+This creates a **continuous learning cycle** where agents improve through human guidance.
+
 ---
 
 ## 📚 Examples
@@ -240,7 +366,6 @@ Comprehensive examples are organized in the `examples/` directory by complexity
 
 - `01-simple-agent.ts` - Basic agent with tools and memory
 - `02-memory-and-context.ts` - Conversational memory deep dive
-- `03-langchain-native-hitl.ts` - LangChain's native HITL middleware
 
 **2. Loopman Integration** (`examples/2-loopman-integration/`)
 
@@ -270,7 +395,7 @@ Comprehensive examples are organized in the `examples/` directory by complexity
 ```bash
 # Basics
 npx tsx examples/1-basics/01-simple-agent.ts
-npx tsx examples/1-basics/03-langchain-native-hitl.ts
+npx tsx examples/1-basics/02-memory-and-context.ts
 
 # Loopman Integration
 npx tsx examples/2-loopman-integration/01-middleware-basic.ts
@@ -290,112 +415,39 @@ npm run example:langgraph-full-state
 
 See [Examples README](./examples/README.md) for detailed documentation and learning paths.
 
-**New:** 
-- Check out the [LangGraph Integration Guide](./docs/LANGGRAPH_INTEGRATION.md) for building stateful workflows with Loopman validation nodes
-- See [Full State Integration Guide](./docs/LANGGRAPH_FULL_STATE.md) for sharing complete agent state with human reviewers
-
 ---
 
-**Key Features Demonstrated:**
+## 🔀 LangGraph Integration
 
-- **Transparent validation**: No manual interruption handling
-- **Automatic polling**: Middleware polls for decisions
-- **Timeout handling**: Built-in timeout and retry logic
-- **Fallback mechanism**: Auto-approval on API errors
-- **Clean code**: Simple invoke() calls, HITL happens behind the scenes
-- Debug logging for development
+The SDK provides complete LangGraph support with reusable nodes for building stateful validation workflows.
 
----
+### Key Components
 
-## 🔌 Loopman Middleware
+1. **Context Node** (`createLoopmanContextNode`): Loads guidelines and decision history
+2. **Validation Node** (`createLoopmanValidationNode`): Sends actions for human approval and polls for decisions
+3. **Conditional Edge** (`createLoopmanConditionalEdge`): Routes workflow based on human decisions
+4. **Helper Functions** (`enrichSystemPrompt`): Injects context into agent prompts
 
-Custom middleware for integrating with the Loopman Human-in-the-Loop platform.
+### Complete Workflow Example
 
-### Key Feature: Transparent Validation
+See the [Quick Start](#quick-start) section above for a complete LangGraph workflow example with validation nodes and conditional routing.
 
-**The middleware handles everything automatically!** No need to manually check for interruptions or poll for decisions.
+### Decision Routing & Feedback Loop
 
-```typescript
-// Just invoke the agent - HITL happens transparently!
-const result = await agent.invoke(
-  {
-    messages: [{ role: "user", content: "Send email to alice" }],
-  },
-  config
-);
-// ✅ Decision already validated by human (if required)
-```
+The conditional edge routes your workflow based on human decisions:
 
-### Configuration
+- **`execute`**: Human approved → Continue to tool execution
+- **`rejected`**: Human rejected → End workflow
+- **`retry`**: Human requested changes → **Retry agent with feedback (FEEDBACK LOOP)** 🔄
+- **`timeout`**: No decision within timeout → End workflow (or fallback)
+- **`error`**: API error → End workflow (or fallback)
 
-```typescript
-import { loopmanMiddleware } from "./src/loopman-middleware";
+**The `retry` route enables the feedback loop:** When a human rejects with status `NEEDS_CHANGES` and provides feedback (e.g., "Use a more professional tone"), the workflow automatically routes back to the agent node. The feedback is injected into the agent's context via `enrichSystemPrompt()`, allowing the agent to learn and correct its decision. This creates an iterative refinement cycle that improves agent performance over time.
 
-loopmanMiddleware({
-  // Required
-  apiKey: "your-loopman-api-key",
-  workflowId: "email-workflow",
-
-  // Optional
-  executionId: "custom-execution-id", // Auto-generated if not provided
-  apiBaseUrl: "https://api.loopman.io", // Default
-  timeout: 5 * 60 * 1000, // 5 minutes
-  pollingInterval: 5000, // Poll every 5 seconds
-  debug: true, // Enable logging
-
-  // Tool configuration
-  interruptOn: {
-    send_email: true, // Requires validation
-    read_email: false, // Auto-approved
-  },
-});
-```
-
-### Decision Flow (Automatic)
-
-```mermaid
-graph TD
-    A[Agent calls tool] --> B{Requires validation?}
-    B -->|No| C[Execute immediately]
-    B -->|Yes| D[Middleware sends to Loopman API]
-    D --> E[Middleware polls for decision]
-    E --> F[Notify user via mobile/web]
-    F --> G{Human decision}
-    G -->|Approve| H[Middleware executes as-is]
-    G -->|Edit| I[Middleware executes with modifications]
-    G -->|Reject| J[Middleware returns error message]
-    H --> K[Return result to application]
-    I --> K
-    J --> K
-    style D fill:#90EE90
-    style E fill:#90EE90
-    style H fill:#90EE90
-    style I fill:#90EE90
-    style J fill:#90EE90
-```
-
-**Note:** Green boxes = Handled by middleware (transparent to your code)
+### Running the Example
 
-### Response Types
-
-```typescript
-// Approve
-{ type: "approve" }
-
-// Edit/Modify
-{
-  type: "edit",
-  editedAction: {
-    name: "send_email",
-    args: { to: "alice@example.com", subject: "Modified" }
-  }
-}
-
-// Reject
-{
-  type: "reject",
-  message: "Reason for rejection"
-}
+```bash
+npx tsx examples/5-langgraph-integration/loopman-validation-graph.ts
 ```
 
 ---
@@ -460,35 +512,57 @@ loopman-langchain-sdk-typescript/
 
 ## 📖 API Reference
 
-### Loopman Middleware API
+### LangGraph API
 
-#### `loopmanMiddleware(config)`
+#### `createLoopmanContextNode(config)`
 
-Creates a LangChain middleware for Loopman integration.
+Creates a LangGraph node that loads guidelines and decision history.
 
 **Parameters:**
 
 - `config.apiKey` (string, required): Loopman API key
 - `config.workflowId` (string, required): Workflow identifier
-- `config.executionId` (string, optional): Execution ID
-- `config.mode` (string, optional): Operation mode (`tool-validation`, `prompt-enhancement`, `full`)
-- `config.interruptOn` (Record<string, boolean>, optional): Tool validation config
-- `config.timeout` (number, optional): Decision timeout in ms
-- `config.pollingInterval` (number, optional): Polling interval in ms
+- `config.category` (string, optional): Category filter for guidelines
 - `config.debug` (boolean, optional): Enable debug logging
 
-**Returns:** `AgentMiddleware`
+**Returns:** LangGraph node function
 
-**Example:**
+#### `createLoopmanValidationNode(config)`
 
-```typescript
-const middleware = loopmanMiddleware({
-  apiKey: process.env.LOOPMAN_API_KEY!,
-  workflowId: "my-workflow",
-  interruptOn: { send_email: true },
-  debug: true,
-});
-```
+Creates a LangGraph node that handles human validation.
+
+**Parameters:**
+
+- `config.apiKey` (string, required): Loopman API key
+- `config.workflowId` (string, required): Workflow identifier
+- `config.timeout` (number, optional): Decision timeout in ms (default: 5 minutes)
+- `config.pollingInterval` (number, optional): Polling interval in ms (default: 5 seconds)
+- `config.debug` (boolean, optional): Enable debug logging
+
+**Returns:** LangGraph node function
+
+#### `createLoopmanConditionalEdge(config)`
+
+Creates a conditional edge for routing based on validation results.
+
+**Parameters:**
+
+- `config.debug` (boolean, optional): Enable debug logging
+
+**Returns:** Conditional edge function
+
+#### `enrichSystemPrompt(basePrompt, context, options)`
+
+Enriches a system prompt with Loopman context.
+
+**Parameters:**
+
+- `basePrompt` (string): Base system prompt
+- `context.guidelines` (array, optional): Guidelines to inject
+- `context.decisionContext` (array, optional): Decision history to inject
+- `options.maxDecisions` (number, optional): Max number of decisions to include
+
+**Returns:** Enriched system prompt string
 
 ### Loopman Agent API
 
@@ -530,8 +604,6 @@ const result = await agent.processWithHumanValidation({
 });
 ```
 
-See [Loopman Agent Guide](./docs/LOOPMAN_AGENT.md) for complete API documentation.
-
 ---
 
 ## 🛠️ Development
@@ -595,19 +667,6 @@ See `src/loopman-middleware.ts` for the complete implementation.
 
 ## 🔗 Related Resources
 
-### SDK Documentation
-
-- [LangGraph Integration Guide](./docs/LANGGRAPH_INTEGRATION.md) - Build stateful workflows with validation nodes
-- [LangGraph Context Enrichment](./docs/LANGGRAPH_CONTEXT_ENRICHMENT.md) - Load guidelines and decision history
-- [LangGraph Helper Functions](./docs/LANGGRAPH_HELPERS.md) - Utility functions for context integration
-- [LangGraph Custom State](./docs/LANGGRAPH_CUSTOM_STATE.md) - Use Loopman with your own state schema
-- [requiresValidation Mechanism](./docs/REQUIRES_VALIDATION_MECHANISM.md) - How validation triggering works
-- [Validation Node Context Enrichment](./docs/VALIDATION_NODE_CONTEXT_ENRICHMENT.md) - Auto context loading after validation ⭐ New
-- [Loopman Agent Guide](./docs/LOOPMAN_AGENT.md) - Full agent implementation with MCP
-- [Tool Validation Mode](./docs/TOOL_VALIDATION_MODE.md) - Middleware tool validation
-- [Auto-Correction with Feedback](./docs/AUTO_CORRECTION_WITH_FEEDBACK.md) - Agent retry patterns
-- [Evolution to LangGraph](./docs/EVOLUTION_TO_LANGGRAPH.md) - Migration roadmap
-
 ### LangChain Documentation
 
 - [LangChain v1.0 Quickstart](https://docs.langchain.com/oss/javascript/langchain/quickstart)
@@ -617,9 +676,9 @@ See `src/loopman-middleware.ts` for the complete implementation.
 
 ### Loopman Platform
 
-- [Loopman LangChain SDK](../loopman-langchain-sdk) - Production HITL SDK
-- [Loopman Web App](../loopman-web) - Web interface
-- [Loopman Mobile App](../loopman-application) - Flutter mobile app
+- [Loopman Website](https://loopman.ai) - Official website and documentation
+- [Loopman Web App](https://app.loopman.ai) - Web interface for managing workflows
+- Loopman Mobile App - Available on iOS and Android app stores
 
 ---
 
@@ -631,7 +690,7 @@ MPL-2.0 (Mozilla Public License 2.0). See `LICENSE`.
 
 ## 🤝 Contributing
 
-This is a demonstration project. For production use, see the [Loopman LangChain SDK](../loopman-langchain-sdk).
+Contributions are welcome! Please feel free to submit issues and pull requests on our [GitHub repository](https://github.com/Loopman-AI/loopman-langchain-sdk-typescript).
 
 ---
 

package/dist/templates.json

@@ -1,19 +1,19 @@
 {
   "langgraph-hello-world": {
     "index.ts": "import { HumanMessage, ToolMessage } from \"@langchain/core/messages\";\nimport { END, MemorySaver, START, StateGraph } from \"@langchain/langgraph\";\nimport { ChatOpenAI } from \"@langchain/openai\";\nimport { config } from \"dotenv\";\nimport { tool } from \"langchain\";\nimport * as z from \"zod\";\n\nimport {\n  LoopmanGraphState,\n  createLoopmanConditionalEdge,\n  createLoopmanContextNode,\n  createLoopmanValidationNode,\n  enrichSystemPrompt,\n} from \"@loopman/langchain-sdk\";\n\nconfig();\n\n// Define your tools\nconst sayHello = tool(\n  ({ name }) => {\n    console.log(`Hello, ${name}!`);\n    return `Hello, ${name}! Welcome to Loopman.`;\n  },\n  {\n    name: \"say_hello\",\n    description: \"Say hello to someone\",\n    schema: z.object({\n      name: z.string().describe(\"The name of the person to greet\"),\n    }),\n  }\n);\n\n// Agent node with context enrichment\nasync function agentNode(state: any) {\n  const { messages, guidelines, decisionContext } = state;\n\n  // Enrich system prompt with guidelines and decision history\n  const systemPrompt = enrichSystemPrompt(\n    \"You are a helpful assistant that greets people ....\",\n    { guidelines, decisionContext },\n    { maxDecisions: 3 }\n  );\n\n  const model = new ChatOpenAI({ model: \"gpt-4o-mini\" });\n  const modelWithTools = model.bindTools([sayHello]);\n\n  const messagesWithContext =\n    (guidelines && guidelines.length > 0) ||\n    (decisionContext && decisionContext.length > 0)\n      ? [{ role: \"system\", content: systemPrompt }, ...messages]\n      : messages;\n\n  const response = await modelWithTools.invoke(messagesWithContext);\n\n  return {\n    messages: [response],\n    requiresValidation: response.tool_calls && response.tool_calls.length > 0,\n  };\n}\n\n// Tool execution node\nasync function toolNode(state: any) {\n  const { messages } = state;\n  const lastMessage = messages[messages.length - 1];\n\n  if (!lastMessage.tool_calls || lastMessage.tool_calls.length === 0) {\n    return {};\n  }\n\n  const toolCall = lastMessage.tool_calls[0];\n  const result = await sayHello.invoke(toolCall.args);\n\n  return {\n    messages: [\n      new ToolMessage({\n        content: result,\n        tool_call_id: toolCall.id,\n      }),\n    ],\n  };\n}\n\n// Build the graph with context loading\nconst workflow = new StateGraph(LoopmanGraphState)\n  .addNode(\n    \"load_context\",\n    createLoopmanContextNode({\n      apiKey: process.env.LOOPMAN_API_KEY!,\n      workflowId: process.env.LOOPMAN_WORKFLOW_ID!,\n      category: \"hello-world\",\n      debug: true,\n    })\n  )\n  .addNode(\"agent\", agentNode)\n  .addNode(\n    \"loopman_validation\",\n    createLoopmanValidationNode({\n      apiKey: process.env.LOOPMAN_API_KEY!,\n      workflowId: process.env.LOOPMAN_WORKFLOW_ID!,\n      debug: true,\n    })\n  )\n  .addNode(\"tools\", toolNode)\n  .addEdge(START, \"load_context\")\n  .addEdge(\"load_context\", \"agent\")\n  .addEdge(\"agent\", \"loopman_validation\")\n  .addConditionalEdges(\n    \"loopman_validation\",\n    createLoopmanConditionalEdge({ debug: true }),\n    {\n      execute: \"tools\",\n      rejected: END,\n      retry: \"agent\",\n      timeout: END,\n      error: END,\n    }\n  )\n  .addEdge(\"tools\", END);\n\n// Compile and run\nconst checkpointer = new MemorySaver();\nconst app = workflow.compile({ checkpointer });\n\nasync function main() {\n  const config = { configurable: { thread_id: \"hello-world-thread\" } };\n  const inputs = {\n    messages: [new HumanMessage(\"Say hello to Alice\")],\n  };\n\n  console.log(\"Starting LangGraph workflow with context enrichment...\");\n\n  for await (const output of await app.stream(inputs, config)) {\n    const nodeName = Object.keys(output)[0];\n    console.log(`Step: ${nodeName}`);\n  }\n\n  const finalState = await app.getState(config);\n  console.log(\"Final status:\", finalState.values.loopmanTaskStatus);\n  console.log(\"Guidelines loaded:\", finalState.values.guidelines?.length || 0);\n  console.log(\n    \"Decision context loaded:\",\n    finalState.values.decisionContext?.length || 0\n  );\n  console.log(\"Workflow completed!\");\n}\n\nmain().catch(console.error);\n",
-    "package.json": "{\n  \"name\": \"loopman-langgraph-hello-world\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Loopman LangGraph Hello World Example\",\n  \"main\": \"index.ts\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"start\": \"tsx index.ts\",\n    \"dev\": \"tsx index.ts\",\n    \"build\": \"tsc\",\n    \"run\": \"node dist/index.js\"\n  },\n  \"dependencies\": {\n    \"@langchain/core\": \"^1.0.2\",\n    \"@langchain/langgraph\": \"^1.0.1\",\n    \"@langchain/openai\": \"^1.0.0\",\n    \"@loopman/langchain-sdk\": \"^1.12.1\",\n    \"dotenv\": \"^17.2.3\",\n    \"langchain\": \"^1.0.2\",\n    \"tsx\": \"^4.20.6\",\n    \"typescript\": \"^5.9.3\",\n    \"zod\": \"^3.25.76\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^24.9.2\"\n  }\n}\n",
+    "package.json": "{\n  \"name\": \"loopman-langgraph-hello-world\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Loopman LangGraph Hello World Example\",\n  \"main\": \"index.ts\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"start\": \"tsx index.ts\",\n    \"dev\": \"tsx index.ts\",\n    \"build\": \"tsc\",\n    \"run\": \"node dist/index.js\"\n  },\n  \"dependencies\": {\n    \"@langchain/core\": \"^1.0.2\",\n    \"@langchain/langgraph\": \"^1.0.1\",\n    \"@langchain/openai\": \"^1.0.0\",\n    \"@loopman/langchain-sdk\": \"^1.12.3\",\n    \"dotenv\": \"^17.2.3\",\n    \"langchain\": \"^1.0.2\",\n    \"tsx\": \"^4.20.6\",\n    \"typescript\": \"^5.9.3\",\n    \"zod\": \"^3.25.76\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^24.9.2\"\n  }\n}\n",
     "tsconfig.json": "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"ES2022\",\n    \"lib\": [\"ES2022\"],\n    \"moduleResolution\": \"bundler\",\n    \"resolveJsonModule\": true,\n    \"allowJs\": true,\n    \"outDir\": \"./dist\",\n    \"rootDir\": \"./\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"declaration\": true,\n    \"declarationMap\": true,\n    \"sourceMap\": true\n  },\n  \"include\": [\"**/*.ts\"],\n  \"exclude\": [\"node_modules\", \"dist\"]\n}\n\n",
     "README.md": "# Loopman LangGraph Hello World\n\nThis project demonstrates how to integrate Loopman with LangGraph using Context Enrichment / Feedback Loop mode.\n\n## About LangGraph\n\nLangGraph is LangChain's official framework for building stateful, multi-actor applications with LLMs. It provides:\n\n- **Stateful workflows**: Explicit state management across nodes\n- **Conditional routing**: Dynamic edges based on state\n- **Streaming support**: Real-time updates during execution\n- **Visual debugging**: Graph visualization and inspection\n\n## Setup\n\n1. Install dependencies:\n```bash\nnpm install\n```\n\n2. Copy .env.example to .env and configure your keys:\n```bash\ncp .env.example .env\n```\n\nEdit the .env file and replace the placeholders with your actual values:\n- `OPENAI_API_KEY`: Your OpenAI API key\n- `LOOPMAN_API_KEY`: Your Loopman API key\n- `LOOPMAN_WORKFLOW_ID`: Your workflow ID from Loopman\n\n3. Run the example:\n```bash\nnpm start\n```\n\n## Graph Architecture\n\nThe workflow follows this pattern:\n\n```\nSTART\n  ↓\nload_context (load guidelines and decision history)\n  ↓\nagent (LLM decides action)\n  ↓\nloopman_validation (create task + poll)\n  ↓\n[conditional edge based on status]\n  ↓\n├─→ tools (APPROVED: execute)\n├─→ agent (NEEDS_CHANGES: retry)\n└─→ END (REJECTED/TIMEOUT/ERROR: end)\n  ↓\nEND\n```\n\n## Key Features\n\n- **Context Enrichment**: Loads validation guidelines and historical decisions\n- **Prompt Enhancement**: Automatically enriches system prompts with context\n- **Learning from History**: Agent learns from past human decisions\n- **Category Filtering**: Guidelines filtered by category for relevance\n- **Feedback Loop**: Human feedback is stored and used to improve future decisions\n\n## Learn More\n\n- [LangGraph Documentation](https://js.langchain.com/docs/langgraph/)\n- [Loopman LangGraph Integration Guide](https://github.com/loopman/loopman-langchain-sdk/blob/main/docs/LANGGRAPH_INTEGRATION.md)\n- [Loopman Documentation](https://loopman.dev/docs)\n\n"
   },
   "langchain-tool-validation": {
     "index.ts": "import { MemorySaver } from \"@langchain/langgraph\";\nimport { config } from \"dotenv\";\nimport { createAgent, tool } from \"langchain\";\nimport * as z from \"zod\";\nimport { loopmanMiddleware } from \"@loopman/langchain-sdk\";\n\n// Load environment variables\nconfig();\n\n// Simple hello world tool\nconst sayHello = tool(\n  ({ name }) => {\n    console.log(`Hello, ${name}!`);\n    return `Hello, ${name}! Welcome to Loopman.`;\n  },\n  {\n    name: \"say_hello\",\n    description: \"Say hello to someone\",\n    schema: z.object({\n      name: z.string().describe(\"The name of the person to greet\"),\n    }),\n  }\n);\n\n// Create agent with Loopman middleware\nconst checkpointer = new MemorySaver();\n\nconst agent = createAgent({\n  model: \"openai:gpt-4o-mini\",\n  systemPrompt: \"You are a helpful assistant that greets people.\",\n  tools: [sayHello],\n  middleware: [\n    loopmanMiddleware({\n      apiKey: process.env.LOOPMAN_API_KEY!,\n      workflowId: process.env.LOOPMAN_WORKFLOW_ID!,\n      interruptOn: {\n        say_hello: true, // Requires human validation\n      },\n      debug: true,\n    }),\n  ],\n  checkpointer,\n});\n\n// Run the agent\nasync function main() {\n  const config = { configurable: { thread_id: \"hello-world-thread\" } };\n\n  const result = await agent.invoke(\n    {\n      messages: [\n        {\n          role: \"user\",\n          content: \"Say hello to Alice\",\n        },\n      ],\n    },\n    config\n  );\n\n  console.log(\"Agent response:\", result.messages[result.messages.length - 1].content);\n}\n\nmain().catch(console.error);\n\n",
-    "package.json": "{\n  \"name\": \"loopman-langchain-tool-validation\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Loopman LangChain Tool Validation Example\",\n  \"main\": \"index.ts\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"start\": \"tsx index.ts\",\n    \"dev\": \"tsx index.ts\",\n    \"build\": \"tsc\",\n    \"run\": \"node dist/index.js\"\n  },\n  \"dependencies\": {\n    \"@langchain/core\": \"^1.0.2\",\n    \"@langchain/mcp-adapters\": \"^1.0.0\",\n    \"@langchain/langgraph\": \"^1.0.1\",\n    \"@langchain/openai\": \"^1.0.0\",\n    \"@loopman/langchain-sdk\": \"^1.12.1\",\n    \"dotenv\": \"^17.2.3\",\n    \"langchain\": \"^1.0.2\",\n    \"tsx\": \"^4.20.6\",\n    \"typescript\": \"^5.9.3\",\n    \"zod\": \"^3.25.76\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^24.9.2\"\n  }\n}\n\n",
+    "package.json": "{\n  \"name\": \"loopman-langchain-tool-validation\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Loopman LangChain Tool Validation Example\",\n  \"main\": \"index.ts\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"start\": \"tsx index.ts\",\n    \"dev\": \"tsx index.ts\",\n    \"build\": \"tsc\",\n    \"run\": \"node dist/index.js\"\n  },\n  \"dependencies\": {\n    \"@langchain/core\": \"^1.0.2\",\n    \"@langchain/mcp-adapters\": \"^1.0.0\",\n    \"@langchain/langgraph\": \"^1.0.1\",\n    \"@langchain/openai\": \"^1.0.0\",\n    \"@loopman/langchain-sdk\": \"^1.12.3\",\n    \"dotenv\": \"^17.2.3\",\n    \"langchain\": \"^1.0.2\",\n    \"tsx\": \"^4.20.6\",\n    \"typescript\": \"^5.9.3\",\n    \"zod\": \"^3.25.76\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^24.9.2\"\n  }\n}\n\n",
     "tsconfig.json": "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"ES2022\",\n    \"lib\": [\"ES2022\"],\n    \"moduleResolution\": \"bundler\",\n    \"resolveJsonModule\": true,\n    \"allowJs\": true,\n    \"outDir\": \"./dist\",\n    \"rootDir\": \"./\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"declaration\": true,\n    \"declarationMap\": true,\n    \"sourceMap\": true\n  },\n  \"include\": [\"**/*.ts\"],\n  \"exclude\": [\"node_modules\", \"dist\"]\n}\n\n",
     "README.md": "# Loopman LangChain - Tool Validation Mode\n\nThis project demonstrates how to integrate Loopman with LangChain using **Tool Validation** mode.\n\n## About Tool Validation Mode\n\nIn this mode, Loopman middleware intercepts specific tool calls and requires human validation before execution. This is useful when:\n- Certain actions need human approval (e.g., sending emails, making payments)\n- You want to validate AI decisions before they affect real systems\n- Compliance requires human oversight for specific operations\n\n## Setup\n\n1. Install dependencies:\n```bash\nnpm install\n```\n\n2. Copy .env.example to .env and configure your keys:\n```bash\ncp .env.example .env\n```\n\nEdit the .env file and replace the placeholders with your actual values:\n- `OPENAI_API_KEY`: Your OpenAI API key\n- `LOOPMAN_API_KEY`: Your Loopman API key\n- `LOOPMAN_WORKFLOW_ID`: Your workflow ID from Loopman\n\n3. Run the example:\n```bash\nnpm start\n```\n\n## How It Works\n\n### 1. Define Tools\n\n```typescript\nconst sayHello = tool(\n  ({ name }) => {\n    console.log(`Hello, ${name}!`);\n    return `Hello, ${name}! Welcome to Loopman.`;\n  },\n  {\n    name: \"say_hello\",\n    description: \"Say hello to someone\",\n    schema: z.object({\n      name: z.string().describe(\"The name of the person to greet\"),\n    }),\n  }\n);\n```\n\n### 2. Add Loopman Middleware\n\n```typescript\nconst agent = createAgent({\n  model: \"openai:gpt-4o-mini\",\n  tools: [sayHello],\n  middleware: [\n    loopmanMiddleware({\n      apiKey: process.env.LOOPMAN_API_KEY!,\n      workflowId: process.env.LOOPMAN_WORKFLOW_ID!,\n      interruptOn: {\n        say_hello: true, // Requires human validation\n      },\n      debug: true,\n    }),\n  ],\n  checkpointer,\n});\n```\n\n### 3. Run the Agent\n\n```typescript\nconst result = await agent.invoke(\n  {\n    messages: [{ role: \"user\", content: \"Say hello to Alice\" }],\n  },\n  config\n);\n```\n\n## Key Features\n\n- **Selective Validation**: Only specified tools require approval\n- **Automatic Interception**: Middleware handles validation workflow\n- **Stateful**: Uses checkpointer to maintain conversation state\n- **Debug Mode**: Verbose logging for development\n\n## Workflow\n\n```\n1. User sends message\n   ↓\n2. Agent generates tool call (say_hello)\n   ↓\n3. Loopman middleware intercepts\n   ↓\n4. Creates validation task\n   ↓\n5. Waits for human decision\n   ↓\n6. If approved → Execute tool\n   If rejected → Return to agent with feedback\n```\n\n## Configuration Options\n\n### interruptOn\n\nSpecify which tools require validation:\n\n```typescript\ninterruptOn: {\n  say_hello: true,        // Always validate\n  send_email: true,       // Always validate\n  get_weather: false,     // Never validate (auto-execute)\n}\n```\n\n### debug\n\nEnable/disable verbose logging:\n\n```typescript\ndebug: true  // Show detailed logs\ndebug: false // Production mode\n```\n\n## Learn More\n\n- [Loopman Middleware Documentation](https://github.com/loopman/loopman-langchain-sdk/blob/main/docs/TOOL_VALIDATION_MODE.md)\n- [LangChain Agent Documentation](https://js.langchain.com/docs/how_to/agent_executor)\n- [Loopman Documentation](https://loopman.dev/docs)\n\n"
   },
   "langchain-full-review": {
     "index.ts": "import { config } from \"dotenv\";\nimport { tool } from \"langchain\";\nimport * as z from \"zod\";\nimport { createLoopmanAgent } from \"@loopman/langchain-sdk\";\n\n// Load environment variables\nconfig();\n\n// Simple hello world tool\nconst sayHello = tool(\n  ({ name }) => {\n    console.log(`Hello, ${name}!`);\n    return `Hello, ${name}! Welcome to Loopman.`;\n  },\n  {\n    name: \"say_hello\",\n    description: \"Say hello to someone\",\n    schema: z.object({\n      name: z.string().describe(\"The name of the person to greet\"),\n    }),\n  }\n);\n\n// Create Loopman agent with full human review process\nconst agent = createLoopmanAgent({\n  apiKey: process.env.LOOPMAN_API_KEY!,\n  workflowId: process.env.LOOPMAN_WORKFLOW_ID!,\n  model: \"openai:gpt-4o-mini\",\n  systemPrompt: \"You are a helpful assistant that greets people.\",\n  category: \"hello-world\",\n  additionalTools: [sayHello],\n  requireApprovalForTools: [\"say_hello\"], // Requires validation\n  debug: true,\n});\n\n// Run the agent\nasync function main() {\n  const result = await agent.processWithHumanValidation({\n    input: \"Say hello to Alice\",\n  });\n\n  console.log(\"Agent response:\", result.response);\n  if (result.decision) {\n    console.log(\"Decision status:\", result.decision.status);\n    if (result.decision.feedback) {\n      console.log(\"Human feedback:\", result.decision.feedback);\n    }\n  }\n\n  await agent.disconnect();\n}\n\nmain().catch(console.error);\n\n",
-    "package.json": "{\n  \"name\": \"loopman-langchain-full-review\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Loopman LangChain Full Human Review Example\",\n  \"main\": \"index.ts\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"start\": \"tsx index.ts\",\n    \"dev\": \"tsx index.ts\",\n    \"build\": \"tsc\",\n    \"run\": \"node dist/index.js\"\n  },\n  \"dependencies\": {\n    \"@langchain/core\": \"^1.0.2\",\n    \"@langchain/mcp-adapters\": \"^1.0.0\",\n    \"@langchain/langgraph\": \"^1.0.1\",\n    \"@langchain/openai\": \"^1.0.0\",\n    \"@loopman/langchain-sdk\": \"^1.12.1\",\n    \"dotenv\": \"^17.2.3\",\n    \"langchain\": \"^1.0.2\",\n    \"tsx\": \"^4.20.6\",\n    \"typescript\": \"^5.9.3\",\n    \"zod\": \"^3.25.76\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^24.9.2\"\n  }\n}\n\n",
+    "package.json": "{\n  \"name\": \"loopman-langchain-full-review\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Loopman LangChain Full Human Review Example\",\n  \"main\": \"index.ts\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"start\": \"tsx index.ts\",\n    \"dev\": \"tsx index.ts\",\n    \"build\": \"tsc\",\n    \"run\": \"node dist/index.js\"\n  },\n  \"dependencies\": {\n    \"@langchain/core\": \"^1.0.2\",\n    \"@langchain/mcp-adapters\": \"^1.0.0\",\n    \"@langchain/langgraph\": \"^1.0.1\",\n    \"@langchain/openai\": \"^1.0.0\",\n    \"@loopman/langchain-sdk\": \"^1.12.3\",\n    \"dotenv\": \"^17.2.3\",\n    \"langchain\": \"^1.0.2\",\n    \"tsx\": \"^4.20.6\",\n    \"typescript\": \"^5.9.3\",\n    \"zod\": \"^3.25.76\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^24.9.2\"\n  }\n}\n\n",
     "tsconfig.json": "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"ES2022\",\n    \"lib\": [\"ES2022\"],\n    \"moduleResolution\": \"bundler\",\n    \"resolveJsonModule\": true,\n    \"allowJs\": true,\n    \"outDir\": \"./dist\",\n    \"rootDir\": \"./\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"declaration\": true,\n    \"declarationMap\": true,\n    \"sourceMap\": true\n  },\n  \"include\": [\"**/*.ts\"],\n  \"exclude\": [\"node_modules\", \"dist\"]\n}\n\n",
     "README.md": "# Loopman LangChain - Full Human Review Mode\n\nThis project demonstrates how to integrate Loopman with LangChain using **Full Human Review Process** mode.\n\n## About Full Human Review Mode\n\nIn this mode, the Loopman Agent handles the entire workflow including:\n- Creating validation tasks\n- Waiting for human approval\n- Handling feedback and retries\n- Managing the complete lifecycle\n\nThis is useful when:\n- You want a complete HITL (Human-In-The-Loop) solution\n- The agent should wait for human decisions before proceeding\n- You need full control over the validation workflow\n\n## Setup\n\n1. Install dependencies:\n```bash\nnpm install\n```\n\n2. Copy .env.example to .env and configure your keys:\n```bash\ncp .env.example .env\n```\n\nEdit the .env file and replace the placeholders with your actual values:\n- `OPENAI_API_KEY`: Your OpenAI API key\n- `LOOPMAN_API_KEY`: Your Loopman API key\n- `LOOPMAN_WORKFLOW_ID`: Your workflow ID from Loopman\n\n3. Run the example:\n```bash\nnpm start\n```\n\n## How It Works\n\n### 1. Define Tools\n\n```typescript\nconst sayHello = tool(\n  ({ name }) => {\n    console.log(`Hello, ${name}!`);\n    return `Hello, ${name}! Welcome to Loopman.`;\n  },\n  {\n    name: \"say_hello\",\n    description: \"Say hello to someone\",\n    schema: z.object({\n      name: z.string().describe(\"The name of the person to greet\"),\n    }),\n  }\n);\n```\n\n### 2. Create Loopman Agent\n\n```typescript\nconst agent = createLoopmanAgent({\n  apiKey: process.env.LOOPMAN_API_KEY!,\n  workflowId: process.env.LOOPMAN_WORKFLOW_ID!,\n  model: \"openai:gpt-4o-mini\",\n  systemPrompt: \"You are a helpful assistant that greets people.\",\n  category: \"hello-world\",\n  additionalTools: [sayHello],\n  requireApprovalForTools: [\"say_hello\"],\n  debug: true,\n});\n```\n\n### 3. Process with Human Validation\n\n```typescript\nconst result = await agent.processWithHumanValidation({\n  input: \"Say hello to Alice\",\n});\n\nconsole.log(\"Agent response:\", result.response);\nif (result.decision) {\n  console.log(\"Decision status:\", result.decision.status);\n  console.log(\"Human feedback:\", result.decision.feedback);\n}\n```\n\n## Key Features\n\n- **Complete HITL Workflow**: Agent manages the entire validation lifecycle\n- **Automatic Polling**: Waits for human decisions\n- **Feedback Handling**: Processes human feedback and retries if needed\n- **Category Support**: Organize validations by category\n- **Debug Mode**: Verbose logging for development\n\n## Workflow\n\n```\n1. User sends message\n   ↓\n2. Agent processes with LLM\n   ↓\n3. Agent generates tool call\n   ↓\n4. Creates Loopman validation task\n   ↓\n5. Polls for human decision\n   ↓\n6. If approved → Execute and return result\n   If rejected → Process feedback and retry\n   If timeout → Handle timeout\n```\n\n## Configuration Options\n\n### requireApprovalForTools\n\nSpecify which tools require validation:\n\n```typescript\nrequireApprovalForTools: [\"say_hello\", \"send_email\"]\n// Only these tools will require human approval\n```\n\n### category\n\nOrganize validations by category:\n\n```typescript\ncategory: \"hello-world\"\n// Helps filter and organize validation tasks\n```\n\n### debug\n\nEnable/disable verbose logging:\n\n```typescript\ndebug: true  // Show detailed logs\ndebug: false // Production mode\n```\n\n## Response Structure\n\nThe `processWithHumanValidation` method returns:\n\n```typescript\n{\n  response: string,           // Final agent response\n  decision?: {\n    status: \"APPROVED\" | \"REJECTED\" | \"NEEDS_CHANGES\",\n    feedback?: string,        // Human feedback if provided\n    createdAt: Date,\n    updatedAt: Date,\n  }\n}\n```\n\n## Learn More\n\n- [Loopman Agent Documentation](https://github.com/loopman/loopman-langchain-sdk/blob/main/docs/LOOPMAN_AGENT.md)\n- [LangChain Documentation](https://js.langchain.com/docs)\n- [Loopman Documentation](https://loopman.dev/docs)\n\n"
   }

package/examples/templates/langchain-full-review/package.json

@@ -15,7 +15,7 @@
     "@langchain/mcp-adapters": "^1.0.0",
     "@langchain/langgraph": "^1.0.1",
     "@langchain/openai": "^1.0.0",
-    "@loopman/langchain-sdk": "^1.12.1",
+    "@loopman/langchain-sdk": "^1.12.3",
     "dotenv": "^17.2.3",
     "langchain": "^1.0.2",
     "tsx": "^4.20.6",

package/examples/templates/langchain-tool-validation/package.json

@@ -15,7 +15,7 @@
     "@langchain/mcp-adapters": "^1.0.0",
     "@langchain/langgraph": "^1.0.1",
     "@langchain/openai": "^1.0.0",
-    "@loopman/langchain-sdk": "^1.12.1",
+    "@loopman/langchain-sdk": "^1.12.3",
     "dotenv": "^17.2.3",
     "langchain": "^1.0.2",
     "tsx": "^4.20.6",

package/examples/templates/langgraph-hello-world/package.json

@@ -14,7 +14,7 @@
     "@langchain/core": "^1.0.2",
     "@langchain/langgraph": "^1.0.1",
     "@langchain/openai": "^1.0.0",
-    "@loopman/langchain-sdk": "^1.12.1",
+    "@loopman/langchain-sdk": "^1.12.3",
     "dotenv": "^17.2.3",
     "langchain": "^1.0.2",
     "tsx": "^4.20.6",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopman/langchain-sdk",
-  "version": "1.12.1",
+  "version": "1.12.3",
   "description": "LangChain TypeScript SDK - Human-in-the-Loop validation via Loopman platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",