@loopman/langchain-sdk 1.8.0 → 1.12.1

package/examples/templates/langchain-full-review/README.md

@@ -0,0 +1,165 @@
+# Loopman LangChain - Full Human Review Mode
+
+This project demonstrates how to integrate Loopman with LangChain using **Full Human Review Process** mode.
+
+## About Full Human Review Mode
+
+In this mode, the Loopman Agent handles the entire workflow including:
+- Creating validation tasks
+- Waiting for human approval
+- Handling feedback and retries
+- Managing the complete lifecycle
+
+This is useful when:
+- You want a complete HITL (Human-In-The-Loop) solution
+- The agent should wait for human decisions before proceeding
+- You need full control over the validation workflow
+
+## Setup
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Copy .env.example to .env and configure your keys:
+```bash
+cp .env.example .env
+```
+
+Edit the .env file and replace the placeholders with your actual values:
+- `OPENAI_API_KEY`: Your OpenAI API key
+- `LOOPMAN_API_KEY`: Your Loopman API key
+- `LOOPMAN_WORKFLOW_ID`: Your workflow ID from Loopman
+
+3. Run the example:
+```bash
+npm start
+```
+
+## How It Works
+
+### 1. Define Tools
+
+```typescript
+const sayHello = tool(
+  ({ name }) => {
+    console.log(`Hello, ${name}!`);
+    return `Hello, ${name}! Welcome to Loopman.`;
+  },
+  {
+    name: "say_hello",
+    description: "Say hello to someone",
+    schema: z.object({
+      name: z.string().describe("The name of the person to greet"),
+    }),
+  }
+);
+```
+
+### 2. Create Loopman Agent
+
+```typescript
+const agent = createLoopmanAgent({
+  apiKey: process.env.LOOPMAN_API_KEY!,
+  workflowId: process.env.LOOPMAN_WORKFLOW_ID!,
+  model: "openai:gpt-4o-mini",
+  systemPrompt: "You are a helpful assistant that greets people.",
+  category: "hello-world",
+  additionalTools: [sayHello],
+  requireApprovalForTools: ["say_hello"],
+  debug: true,
+});
+```
+
+### 3. Process with Human Validation
+
+```typescript
+const result = await agent.processWithHumanValidation({
+  input: "Say hello to Alice",
+});
+
+console.log("Agent response:", result.response);
+if (result.decision) {
+  console.log("Decision status:", result.decision.status);
+  console.log("Human feedback:", result.decision.feedback);
+}
+```
+
+## Key Features
+
+- **Complete HITL Workflow**: Agent manages the entire validation lifecycle
+- **Automatic Polling**: Waits for human decisions
+- **Feedback Handling**: Processes human feedback and retries if needed
+- **Category Support**: Organize validations by category
+- **Debug Mode**: Verbose logging for development
+
+## Workflow
+
+```
+1. User sends message
+   ↓
+2. Agent processes with LLM
+   ↓
+3. Agent generates tool call
+   ↓
+4. Creates Loopman validation task
+   ↓
+5. Polls for human decision
+   ↓
+6. If approved → Execute and return result
+   If rejected → Process feedback and retry
+   If timeout → Handle timeout
+```
+
+## Configuration Options
+
+### requireApprovalForTools
+
+Specify which tools require validation:
+
+```typescript
+requireApprovalForTools: ["say_hello", "send_email"]
+// Only these tools will require human approval
+```
+
+### category
+
+Organize validations by category:
+
+```typescript
+category: "hello-world"
+// Helps filter and organize validation tasks
+```
+
+### debug
+
+Enable/disable verbose logging:
+
+```typescript
+debug: true  // Show detailed logs
+debug: false // Production mode
+```
+
+## Response Structure
+
+The `processWithHumanValidation` method returns:
+
+```typescript
+{
+  response: string,           // Final agent response
+  decision?: {
+    status: "APPROVED" | "REJECTED" | "NEEDS_CHANGES",
+    feedback?: string,        // Human feedback if provided
+    createdAt: Date,
+    updatedAt: Date,
+  }
+}
+```
+
+## Learn More
+
+- [Loopman Agent Documentation](https://github.com/loopman/loopman-langchain-sdk/blob/main/docs/LOOPMAN_AGENT.md)
+- [LangChain Documentation](https://js.langchain.com/docs)
+- [Loopman Documentation](https://loopman.dev/docs)
+

package/examples/templates/langchain-full-review/index.ts

@@ -0,0 +1,54 @@
+import { config } from "dotenv";
+import { tool } from "langchain";
+import * as z from "zod";
+import { createLoopmanAgent } from "@loopman/langchain-sdk";
+
+// Load environment variables
+config();
+
+// Simple hello world tool
+const sayHello = tool(
+  ({ name }) => {
+    console.log(`Hello, ${name}!`);
+    return `Hello, ${name}! Welcome to Loopman.`;
+  },
+  {
+    name: "say_hello",
+    description: "Say hello to someone",
+    schema: z.object({
+      name: z.string().describe("The name of the person to greet"),
+    }),
+  }
+);
+
+// Create Loopman agent with full human review process
+const agent = createLoopmanAgent({
+  apiKey: process.env.LOOPMAN_API_KEY!,
+  workflowId: process.env.LOOPMAN_WORKFLOW_ID!,
+  model: "openai:gpt-4o-mini",
+  systemPrompt: "You are a helpful assistant that greets people.",
+  category: "hello-world",
+  additionalTools: [sayHello],
+  requireApprovalForTools: ["say_hello"], // Requires validation
+  debug: true,
+});
+
+// Run the agent
+async function main() {
+  const result = await agent.processWithHumanValidation({
+    input: "Say hello to Alice",
+  });
+
+  console.log("Agent response:", result.response);
+  if (result.decision) {
+    console.log("Decision status:", result.decision.status);
+    if (result.decision.feedback) {
+      console.log("Human feedback:", result.decision.feedback);
+    }
+  }
+
+  await agent.disconnect();
+}
+
+main().catch(console.error);
+

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

@@ -0,0 +1,29 @@
+{
+  "name": "loopman-langchain-full-review",
+  "version": "1.0.0",
+  "description": "Loopman LangChain Full Human Review Example",
+  "main": "index.ts",
+  "type": "module",
+  "scripts": {
+    "start": "tsx index.ts",
+    "dev": "tsx index.ts",
+    "build": "tsc",
+    "run": "node dist/index.js"
+  },
+  "dependencies": {
+    "@langchain/core": "^1.0.2",
+    "@langchain/mcp-adapters": "^1.0.0",
+    "@langchain/langgraph": "^1.0.1",
+    "@langchain/openai": "^1.0.0",
+    "@loopman/langchain-sdk": "^1.12.1",
+    "dotenv": "^17.2.3",
+    "langchain": "^1.0.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.2"
+  }
+}
+

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

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "outDir": "./dist",
+    "rootDir": "./",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+

package/examples/templates/langchain-tool-validation/.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

package/examples/templates/langchain-tool-validation/README.md

@@ -0,0 +1,137 @@
+# Loopman LangChain - Tool Validation Mode
+
+This project demonstrates how to integrate Loopman with LangChain using **Tool Validation** mode.
+
+## About Tool Validation Mode
+
+In this mode, Loopman middleware intercepts specific tool calls and requires human validation before execution. This is useful when:
+- Certain actions need human approval (e.g., sending emails, making payments)
+- You want to validate AI decisions before they affect real systems
+- Compliance requires human oversight for specific operations
+
+## Setup
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Copy .env.example to .env and configure your keys:
+```bash
+cp .env.example .env
+```
+
+Edit the .env file and replace the placeholders with your actual values:
+- `OPENAI_API_KEY`: Your OpenAI API key
+- `LOOPMAN_API_KEY`: Your Loopman API key
+- `LOOPMAN_WORKFLOW_ID`: Your workflow ID from Loopman
+
+3. Run the example:
+```bash
+npm start
+```
+
+## How It Works
+
+### 1. Define Tools
+
+```typescript
+const sayHello = tool(
+  ({ name }) => {
+    console.log(`Hello, ${name}!`);
+    return `Hello, ${name}! Welcome to Loopman.`;
+  },
+  {
+    name: "say_hello",
+    description: "Say hello to someone",
+    schema: z.object({
+      name: z.string().describe("The name of the person to greet"),
+    }),
+  }
+);
+```
+
+### 2. Add Loopman Middleware
+
+```typescript
+const agent = createAgent({
+  model: "openai:gpt-4o-mini",
+  tools: [sayHello],
+  middleware: [
+    loopmanMiddleware({
+      apiKey: process.env.LOOPMAN_API_KEY!,
+      workflowId: process.env.LOOPMAN_WORKFLOW_ID!,
+      interruptOn: {
+        say_hello: true, // Requires human validation
+      },
+      debug: true,
+    }),
+  ],
+  checkpointer,
+});
+```
+
+### 3. Run the Agent
+
+```typescript
+const result = await agent.invoke(
+  {
+    messages: [{ role: "user", content: "Say hello to Alice" }],
+  },
+  config
+);
+```
+
+## Key Features
+
+- **Selective Validation**: Only specified tools require approval
+- **Automatic Interception**: Middleware handles validation workflow
+- **Stateful**: Uses checkpointer to maintain conversation state
+- **Debug Mode**: Verbose logging for development
+
+## Workflow
+
+```
+1. User sends message
+   ↓
+2. Agent generates tool call (say_hello)
+   ↓
+3. Loopman middleware intercepts
+   ↓
+4. Creates validation task
+   ↓
+5. Waits for human decision
+   ↓
+6. If approved → Execute tool
+   If rejected → Return to agent with feedback
+```
+
+## Configuration Options
+
+### interruptOn
+
+Specify which tools require validation:
+
+```typescript
+interruptOn: {
+  say_hello: true,        // Always validate
+  send_email: true,       // Always validate
+  get_weather: false,     // Never validate (auto-execute)
+}
+```
+
+### debug
+
+Enable/disable verbose logging:
+
+```typescript
+debug: true  // Show detailed logs
+debug: false // Production mode
+```
+
+## Learn More
+
+- [Loopman Middleware Documentation](https://github.com/loopman/loopman-langchain-sdk/blob/main/docs/TOOL_VALIDATION_MODE.md)
+- [LangChain Agent Documentation](https://js.langchain.com/docs/how_to/agent_executor)
+- [Loopman Documentation](https://loopman.dev/docs)
+

package/examples/templates/langchain-tool-validation/index.ts

@@ -0,0 +1,65 @@
+import { MemorySaver } from "@langchain/langgraph";
+import { config } from "dotenv";
+import { createAgent, tool } from "langchain";
+import * as z from "zod";
+import { loopmanMiddleware } from "@loopman/langchain-sdk";
+
+// Load environment variables
+config();
+
+// Simple hello world tool
+const sayHello = tool(
+  ({ name }) => {
+    console.log(`Hello, ${name}!`);
+    return `Hello, ${name}! Welcome to Loopman.`;
+  },
+  {
+    name: "say_hello",
+    description: "Say hello to someone",
+    schema: z.object({
+      name: z.string().describe("The name of the person to greet"),
+    }),
+  }
+);
+
+// Create agent with Loopman middleware
+const checkpointer = new MemorySaver();
+
+const agent = createAgent({
+  model: "openai:gpt-4o-mini",
+  systemPrompt: "You are a helpful assistant that greets people.",
+  tools: [sayHello],
+  middleware: [
+    loopmanMiddleware({
+      apiKey: process.env.LOOPMAN_API_KEY!,
+      workflowId: process.env.LOOPMAN_WORKFLOW_ID!,
+      interruptOn: {
+        say_hello: true, // Requires human validation
+      },
+      debug: true,
+    }),
+  ],
+  checkpointer,
+});
+
+// Run the agent
+async function main() {
+  const config = { configurable: { thread_id: "hello-world-thread" } };
+
+  const result = await agent.invoke(
+    {
+      messages: [
+        {
+          role: "user",
+          content: "Say hello to Alice",
+        },
+      ],
+    },
+    config
+  );
+
+  console.log("Agent response:", result.messages[result.messages.length - 1].content);
+}
+
+main().catch(console.error);
+

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

@@ -0,0 +1,29 @@
+{
+  "name": "loopman-langchain-tool-validation",
+  "version": "1.0.0",
+  "description": "Loopman LangChain Tool Validation Example",
+  "main": "index.ts",
+  "type": "module",
+  "scripts": {
+    "start": "tsx index.ts",
+    "dev": "tsx index.ts",
+    "build": "tsc",
+    "run": "node dist/index.js"
+  },
+  "dependencies": {
+    "@langchain/core": "^1.0.2",
+    "@langchain/mcp-adapters": "^1.0.0",
+    "@langchain/langgraph": "^1.0.1",
+    "@langchain/openai": "^1.0.0",
+    "@loopman/langchain-sdk": "^1.12.1",
+    "dotenv": "^17.2.3",
+    "langchain": "^1.0.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.2"
+  }
+}
+

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

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "outDir": "./dist",
+    "rootDir": "./",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+

package/examples/templates/langgraph-hello-world/.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

package/examples/templates/langgraph-hello-world/README.md

@@ -0,0 +1,71 @@
+# Loopman LangGraph Hello World
+
+This project demonstrates how to integrate Loopman with LangGraph using Context Enrichment / Feedback Loop mode.
+
+## About LangGraph
+
+LangGraph is LangChain's official framework for building stateful, multi-actor applications with LLMs. It provides:
+
+- **Stateful workflows**: Explicit state management across nodes
+- **Conditional routing**: Dynamic edges based on state
+- **Streaming support**: Real-time updates during execution
+- **Visual debugging**: Graph visualization and inspection
+
+## Setup
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Copy .env.example to .env and configure your keys:
+```bash
+cp .env.example .env
+```
+
+Edit the .env file and replace the placeholders with your actual values:
+- `OPENAI_API_KEY`: Your OpenAI API key
+- `LOOPMAN_API_KEY`: Your Loopman API key
+- `LOOPMAN_WORKFLOW_ID`: Your workflow ID from Loopman
+
+3. Run the example:
+```bash
+npm start
+```
+
+## Graph Architecture
+
+The workflow follows this pattern:
+
+```
+START
+  ↓
+load_context (load guidelines and decision history)
+  ↓
+agent (LLM decides action)
+  ↓
+loopman_validation (create task + poll)
+  ↓
+[conditional edge based on status]
+  ↓
+├─→ tools (APPROVED: execute)
+├─→ agent (NEEDS_CHANGES: retry)
+└─→ END (REJECTED/TIMEOUT/ERROR: end)
+  ↓
+END
+```
+
+## Key Features
+
+- **Context Enrichment**: Loads validation guidelines and historical decisions
+- **Prompt Enhancement**: Automatically enriches system prompts with context
+- **Learning from History**: Agent learns from past human decisions
+- **Category Filtering**: Guidelines filtered by category for relevance
+- **Feedback Loop**: Human feedback is stored and used to improve future decisions
+
+## Learn More
+
+- [LangGraph Documentation](https://js.langchain.com/docs/langgraph/)
+- [Loopman LangGraph Integration Guide](https://github.com/loopman/loopman-langchain-sdk/blob/main/docs/LANGGRAPH_INTEGRATION.md)
+- [Loopman Documentation](https://loopman.dev/docs)
+