@loopman/langchain-sdk 1.8.0 → 1.12.0

package/dist/templates.json

@@ -0,0 +1,20 @@
+{
+  "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.0\",\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.0\",\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.0\",\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/README.md

@@ -0,0 +1,346 @@
+# Examples - Loopman LangChain SDK
+
+A comprehensive collection of examples demonstrating LangChain v1.0 agent patterns and Loopman's Human-in-the-Loop (HITL) integration, from basics to production-ready patterns.
+
+## 📚 Structure
+
+```
+examples/
+├── 1-basics/                    # LangChain fundamentals (no Loopman)
+├── 2-loopman-integration/       # Loopman HITL core features
+├── 3-real-world-examples/       # Production use cases
+└── 4-advanced-patterns/         # Sophisticated HITL patterns
+```
+
+---
+
+## 🎓 Learning Path
+
+### For Beginners
+Start with the basics and progress through each level:
+
+1. **[1-basics/](1-basics/README.md)** - Learn LangChain agent fundamentals
+   - Simple agents with tools
+   - Conversational memory
+   - Native HITL middleware
+
+2. **[2-loopman-integration/](2-loopman-integration/README.md)** - Add Loopman HITL
+   - Transparent validation
+   - Middleware modes
+   - MCP integration
+
+3. **[3-real-world-examples/](3-real-world-examples/README.md)** - Apply to real scenarios
+   - Task management
+   - Data processing
+   - Content workflows
+
+4. **[4-advanced-patterns/](4-advanced-patterns/README.md)** - Master advanced techniques
+   - Conditional HITL
+   - Context-aware validation
+   - Risk-based approval
+
+### For Experienced Developers
+Jump directly to relevant sections:
+
+- **Need HITL fast?** → [2-loopman-integration/01-middleware-basic.ts](2-loopman-integration/01-middleware-basic.ts)
+- **Building a workflow?** → [3-real-world-examples/](3-real-world-examples/README.md)
+- **Need conditional approval?** → [4-advanced-patterns/conditional-hitl.ts](4-advanced-patterns/conditional-hitl.ts)
+- **Want the complete agent API?** → [2-loopman-integration/03-loopman-agent.ts](2-loopman-integration/03-loopman-agent.ts)
+- **Review LangChain basics** → [1-basics/](1-basics/README.md)
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+```bash
+# Install dependencies
+npm install
+
+# Configure environment
+cp ../env.example .env
+# Edit .env and add your API keys
+```
+
+### Run Your First Example
+
+```bash
+# 1. Basic agent (no HITL)
+npx tsx 1-basics/01-simple-agent.ts
+
+# 2. Loopman transparent HITL
+npx tsx 2-loopman-integration/01-middleware-basic.ts
+
+# 3. Real-world use case
+npx tsx 3-real-world-examples/task-management/task-approval.ts
+
+# 4. Advanced pattern
+npx tsx 4-advanced-patterns/conditional-hitl.ts
+```
+
+---
+
+## 📂 Detailed Breakdown
+
+### 1️⃣ Basics - LangChain Fundamentals
+**Path:** `1-basics/`
+
+Learn core LangChain concepts without Loopman complexity:
+
+| Example | Concept | Key Learning |
+|---------|---------|--------------|
+| `01-simple-agent.ts` | Basic agent | Tools, memory, invoke |
+| `02-memory-and-context.ts` | Conversational memory | Checkpointers, thread IDs, context |
+| `03-langchain-native-hitl.ts` | Native HITL | Interruptions, Command.resume() |
+
+**Who should start here:**
+- New to LangChain v1.0
+- Want to understand agent fundamentals
+- Need reference for vanilla LangChain patterns
+
+[👉 Full documentation](1-basics/README.md)
+
+---
+
+### 2️⃣ Loopman Integration - Core HITL Features
+**Path:** `2-loopman-integration/`
+
+Loopman's transparent HITL middleware and agent patterns:
+
+| Example | Concept | Key Feature |
+|---------|---------|-------------|
+| `01-middleware-basic.ts` | Transparent HITL | No interrupt handling needed! |
+| `02-middleware-modes.ts` | Three operation modes | tool-validation, prompt-enhancement, full |
+| `03-loopman-agent.ts` | High-level Loopman API | All-in-one solution (recommended) |
+
+**Key differences from native HITL:**
+
+```typescript
+// ❌ Native LangChain - manual interrupt handling
+if (result.__interrupt__) {
+  const decision = await waitForHuman();
+  await agent.invoke(new Command({ resume: decision }));
+}
+
+// ✅ Loopman - completely transparent!
+const result = await agent.invoke(...);
+// Human validation already handled ✨
+```
+
+[👉 Full documentation](2-loopman-integration/README.md)
+
+---
+
+### 3️⃣ Real-World Examples - Production Use Cases
+**Path:** `3-real-world-examples/`
+
+Complete, domain-specific implementations:
+
+| Domain | Example | Scenario |
+|--------|---------|----------|
+| **Task Management** | `task-management/task-approval.ts` | CRUD ops with selective approval |
+| **Data Processing** | `data-processing/data-validation.ts` | ETL with quality checks and fixes |
+| **Content Workflow** | `content-workflow/content-review.ts` | Draft/publish with editorial review |
+
+**Pattern:** Safe operations auto-approved, destructive operations require approval
+
+```typescript
+interruptOn: {
+  read_data: false,    // ✅ Auto-approved
+  create_draft: false, // ✅ Auto-approved
+  publish: true,       // ⚠️ Requires approval
+  delete: true         // ⚠️ Requires approval
+}
+```
+
+[👉 Full documentation](3-real-world-examples/README.md)
+
+---
+
+### 4️⃣ Advanced Patterns - Sophisticated HITL
+**Path:** `4-advanced-patterns/`
+
+Context-aware, intelligent validation:
+
+| Pattern | Example | Use Case |
+|---------|---------|----------|
+| **Conditional HITL** | `conditional-hitl.ts` | Amount-based, risk-based, time-based rules |
+
+**Example:** Auto-approve small payments, require approval for large ones
+
+```typescript
+const needsApproval =
+  amount > userApprovalLimit ||
+  isHighRiskCountry(country) ||
+  !isBusinessHours();
+```
+
+[👉 Full documentation](4-advanced-patterns/README.md)
+
+---
+
+## 🔧 Environment Configuration
+
+Create a `.env` file in the examples directory:
+
+```env
+# Required
+OPENAI_API_KEY=sk-your-openai-api-key
+
+# Optional (for Loopman examples)
+LOOPMAN_API_KEY=your-loopman-api-key
+LOOPMAN_CHANNEL_ID=your-channel-id
+```
+
+---
+
+## 💡 Common Patterns
+
+### Pattern 1: Safe vs. Sensitive Operations
+
+Categorize operations by risk level:
+
+```typescript
+// ✅ Always safe - read operations
+list_items: false
+get_item: false
+analyze_data: false
+
+// ✅ Usually safe - create/update
+create_draft: false
+update_task: false
+
+// ⚠️ Requires approval - destructive/public
+delete_item: true
+publish_content: true
+send_email: true
+bulk_operations: true
+```
+
+### Pattern 2: Transparent HITL with Loopman
+
+Add middleware and forget about interruptions:
+
+```typescript
+const agent = createAgent({
+  model: "openai:gpt-4o-mini",
+  tools: [myTool],
+  middleware: [
+    loopmanMiddleware({
+      apiKey: process.env.LOOPMAN_API_KEY!,
+      workflowId: "my-workflow",
+      interruptOn: { my_tool: true },
+    }),
+  ],
+});
+
+// Just invoke - HITL happens automatically!
+const result = await agent.invoke({ messages: [...] }, config);
+```
+
+### Pattern 3: Auto-Retry on Feedback
+
+Use `invokeWithRetry()` for automatic retry on human corrections:
+
+```typescript
+import { invokeWithRetry } from "../src/loopman-agent-wrapper";
+
+const result = await invokeWithRetry(
+  agent,
+  { messages: [...] },
+  config,
+  { maxRetries: 5, debug: true }
+);
+// Handles NEEDS_CHANGES and auto-retries ✨
+```
+
+### Pattern 4: Conditional Approval
+
+Tools decide if approval needed based on context:
+
+```typescript
+const myTool = tool(({ amount, user }) => {
+  if (amount > user.approvalLimit) {
+    // Create pending task for approval
+    return createPendingTask(amount);
+  }
+  // Auto-approve
+  return executeImmediately(amount);
+});
+```
+
+---
+
+## 🎯 Choose Your Path
+
+### I want to learn LangChain basics
+👉 Start with [1-basics/01-simple-agent.ts](1-basics/01-simple-agent.ts)
+
+### I need to add HITL to my agent
+👉 Jump to [2-loopman-integration/01-middleware-basic.ts](2-loopman-integration/01-middleware-basic.ts)
+
+### I'm building a specific feature
+👉 Browse [3-real-world-examples/](3-real-world-examples/README.md) for your domain
+
+### I need advanced validation logic
+👉 Study [4-advanced-patterns/conditional-hitl.ts](4-advanced-patterns/conditional-hitl.ts)
+
+---
+
+## 📖 Additional Resources
+
+### Documentation
+- [Main README](../README.md) - SDK overview and API reference
+- [Double Validation Layer](../docs/DOUBLE_VALIDATION_LAYER.md)
+- [Auto-Correction with Feedback](../docs/AUTO_CORRECTION_WITH_FEEDBACK.md)
+- [Middleware Modes](../docs/TOOL_VALIDATION_MODE.md)
+- [Loopman Agent Guide](../docs/LOOPMAN_AGENT.md)
+
+### LangChain Resources
+- [LangChain v1.0 Quickstart](https://docs.langchain.com/oss/javascript/langchain/quickstart)
+- [Human-in-the-Loop Guide](https://docs.langchain.com/oss/javascript/langchain/human-in-the-loop)
+- [Tools Documentation](https://docs.langchain.com/oss/javascript/langchain/tools)
+
+---
+
+## 🛠️ Development Tips
+
+### Debugging
+- Enable `debug: true` in middleware config
+- Use VSCode debug configurations (`.vscode/launch.json`)
+- Check console output for detailed logs
+
+### Testing
+- Use short timeouts during development (30s instead of 5min)
+- Mock API responses to avoid rate limits
+- Test with different `thread_id` values for isolated conversations
+
+### Production
+- Replace `MemorySaver` with `PostgresSaver` or `RedisSaver`
+- Set appropriate timeouts based on expected human response times
+- Monitor approval rates and tune thresholds
+
+---
+
+## 🤝 Contributing
+
+Found a bug or have an improvement?
+
+1. Check existing examples for similar patterns
+2. Follow the established structure (1-basics, 2-loopman, etc.)
+3. Add comprehensive comments and documentation
+4. Update this README with your example
+5. Test thoroughly before submitting
+
+---
+
+## 📄 License
+
+MPL-2.0 - See [LICENSE](../LICENSE) for details
+
+---
+
+**Happy coding! 🚀**
+
+For questions or support, check the [main documentation](../README.md) or open an issue on GitHub.

package/examples/templates/README.md

@@ -0,0 +1,285 @@
+# LangChain SDK Templates
+
+This directory contains working example projects that serve as templates for users integrating Loopman with their LangChain applications.
+
+## Overview
+
+These are **not** template files - they are **real, functional examples** that:
+- Can be run independently (`npm install && npm start`)
+- Are tested to ensure they work correctly
+- Are exported during build for use by the web application
+- Serve as a single source of truth for starter projects
+
+## Available Templates
+
+### `langgraph-hello-world/`
+
+A complete **LangGraph** integration example demonstrating:
+- Context Enrichment mode (loading guidelines and decision history)
+- Validation with human-in-the-loop
+- Tool execution after approval
+- Retry mechanism for rejected actions
+
+**Best for:** Complex stateful workflows with conditional routing
+
+**How to run:**
+```bash
+cd langgraph-hello-world
+cp .env.example .env
+# Edit .env with your API keys
+npm install
+npm start
+```
+
+### `langchain-tool-validation/`
+
+A **LangChain middleware** integration demonstrating:
+- Selective tool validation (only specific tools require approval)
+- Automatic interception of tool calls
+- Lightweight integration with existing agents
+- Stateful conversation with checkpointer
+
+**Best for:** Adding validation to existing LangChain agents
+
+**How to run:**
+```bash
+cd langchain-tool-validation
+cp .env.example .env
+# Edit .env with your API keys
+npm install
+npm start
+```
+
+### `langchain-full-review/`
+
+A **Loopman Agent** integration demonstrating:
+- Complete HITL (Human-In-The-Loop) workflow
+- Automatic polling for human decisions
+- Feedback handling and retry mechanism
+- Full lifecycle management
+
+**Best for:** Complete turnkey HITL solution
+
+**How to run:**
+```bash
+cd langchain-full-review
+cp .env.example .env
+# Edit .env with your API keys
+npm install
+npm start
+```
+
+## How Templates Work
+
+### 1. Development & Testing
+
+Templates are maintained as working examples in this directory. When you update a template:
+
+```bash
+cd langgraph-hello-world
+# Make changes to index.ts, README.md, etc.
+npm start  # Test your changes
+```
+
+### 2. Export to JSON
+
+During SDK build, templates are exported to `dist/templates.json`:
+
+```bash
+npm run build
+# Runs: tsc && node scripts/export-templates.js
+```
+
+This creates a JSON file with all template contents:
+
+```json
+{
+  "langgraph-hello-world": {
+    "index.ts": "... full file contents ...",
+    "package.json": "... full file contents ...",
+    ...
+  }
+}
+```
+
+### 3. Web Application Usage
+
+The web application imports this JSON and generates customized starter projects:
+
+```typescript
+import sdkTemplates from './sdk-templates.json';
+
+// Customize template with user's workflow ID and API key
+const files = processTemplate(sdkTemplates['langgraph-hello-world'], {
+  workflowId: 'user-workflow-123',
+  apiKey: 'user-api-key-xyz',
+});
+
+// Generate downloadable zip
+createZipFromFiles(files);
+```
+
+## Adding a New Template
+
+1. **Create the template directory:**
+   ```bash
+   mkdir -p examples/templates/my-new-template
+   cd examples/templates/my-new-template
+   ```
+
+2. **Add required files:**
+   - `index.ts` - Main code example
+   - `package.json` - Dependencies and scripts
+   - `tsconfig.json` - TypeScript configuration
+   - `README.md` - Usage instructions
+   - `.env.example` - Environment variable template
+
+3. **Test it works:**
+   ```bash
+   npm install
+   npm start
+   ```
+
+4. **Update export script:**
+   Edit `scripts/export-templates.js` to include your new template.
+
+5. **Build and commit:**
+   ```bash
+   cd ../../../
+   npm run build
+   git add examples/templates/my-new-template
+   git add dist/templates.json
+   git commit -m "feat(templates): add my-new-template example"
+   ```
+
+## Design Principles
+
+### ✅ DO
+
+- **Use environment variables** for dynamic values
+  ```typescript
+  workflowId: process.env.LOOPMAN_WORKFLOW_ID!
+  ```
+
+- **Keep examples simple** and focused on one concept
+
+- **Include detailed comments** explaining key concepts
+
+- **Test before committing** - ensure it runs successfully
+
+- **Document prerequisites** in the template's README
+
+### ❌ DON'T
+
+- **Use template placeholders** in the code
+  ```typescript
+  // ❌ Bad
+  workflowId: "{{WORKFLOW_ID}}"
+  
+  // ✅ Good
+  workflowId: process.env.LOOPMAN_WORKFLOW_ID!
+  ```
+
+- **Add non-working code** - everything should be executable
+
+- **Hardcode credentials** - always use .env files
+
+- **Include node_modules** or build artifacts
+
+## Template Structure
+
+Each template should follow this structure:
+
+```
+template-name/
+├── index.ts          # Main entry point
+├── package.json      # NPM dependencies and scripts
+├── tsconfig.json     # TypeScript configuration
+├── README.md         # Template-specific documentation
+└── .env.example      # Environment variables (no secrets!)
+```
+
+### Required Scripts in package.json
+
+```json
+{
+  "scripts": {
+    "start": "tsx index.ts",
+    "dev": "tsx index.ts",
+    "build": "tsc",
+    "run": "node dist/index.js"
+  }
+}
+```
+
+### Required Environment Variables
+
+At minimum, include:
+
+```bash
+OPENAI_API_KEY=your-openai-api-key-here
+LOOPMAN_API_KEY=your-loopman-api-key-here
+LOOPMAN_WORKFLOW_ID=your-workflow-id-here
+```
+
+## Updating Templates
+
+When you update a template:
+
+1. **Make changes** in the template directory
+2. **Test locally** to ensure it still works
+3. **Build SDK** to regenerate `templates.json`
+4. **Commit both** the template files and `dist/templates.json`
+5. **Release SDK** to make updates available to web app
+
+## Testing
+
+### Manual Testing
+
+```bash
+cd examples/templates/langgraph-hello-world
+npm install
+npm start
+```
+
+### Automated Testing (Future)
+
+We plan to add:
+- E2E tests for each template
+- Validation of template structure
+- Dependency version checks
+- README completeness checks
+
+## Publishing
+
+Templates are included in the npm package:
+
+```json
+{
+  "files": [
+    "dist",
+    "examples/templates",
+    "README.md",
+    "LICENSE"
+  ]
+}
+```
+
+This ensures users can:
+- Reference the source code
+- Copy templates directly if needed
+- See the latest working examples
+
+## Related Documentation
+
+- [Templates System Guide](../../docs/TEMPLATES.md) - Detailed architecture
+- [LangGraph Integration](../../docs/LANGGRAPH_INTEGRATION.md) - Integration patterns
+- [SDK README](../../README.md) - Main documentation
+
+## Questions?
+
+If you have questions about templates:
+- Check [Templates System Guide](../../docs/TEMPLATES.md)
+- Open an issue on GitHub
+- Contact the Loopman team
+

package/examples/templates/langchain-full-review/.env.example

@@ -0,0 +1,3 @@
+OPENAI_API_KEY=your-openai-api-key-here
+LOOPMAN_API_KEY=your-loopman-api-key-here
+LOOPMAN_WORKFLOW_ID=your-workflow-id-here