@loopman/langchain-sdk 1.7.0 → 1.12.0

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.0",
+    "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)
+

package/examples/templates/langgraph-hello-world/index.ts

@@ -0,0 +1,147 @@
+import { HumanMessage, ToolMessage } from "@langchain/core/messages";
+import { END, MemorySaver, START, StateGraph } from "@langchain/langgraph";
+import { ChatOpenAI } from "@langchain/openai";
+import { config } from "dotenv";
+import { tool } from "langchain";
+import * as z from "zod";
+
+import {
+  LoopmanGraphState,
+  createLoopmanConditionalEdge,
+  createLoopmanContextNode,
+  createLoopmanValidationNode,
+  enrichSystemPrompt,
+} from "@loopman/langchain-sdk";
+
+config();
+
+// Define your tools
+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"),
+    }),
+  }
+);
+
+// Agent node with context enrichment
+async function agentNode(state: any) {
+  const { messages, guidelines, decisionContext } = state;
+
+  // Enrich system prompt with guidelines and decision history
+  const systemPrompt = enrichSystemPrompt(
+    "You are a helpful assistant that greets people ....",
+    { guidelines, decisionContext },
+    { maxDecisions: 3 }
+  );
+
+  const model = new ChatOpenAI({ model: "gpt-4o-mini" });
+  const modelWithTools = model.bindTools([sayHello]);
+
+  const messagesWithContext =
+    (guidelines && guidelines.length > 0) ||
+    (decisionContext && decisionContext.length > 0)
+      ? [{ role: "system", content: systemPrompt }, ...messages]
+      : messages;
+
+  const response = await modelWithTools.invoke(messagesWithContext);
+
+  return {
+    messages: [response],
+    requiresValidation: response.tool_calls && response.tool_calls.length > 0,
+  };
+}
+
+// Tool execution node
+async function toolNode(state: any) {
+  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 sayHello.invoke(toolCall.args);
+
+  return {
+    messages: [
+      new ToolMessage({
+        content: result,
+        tool_call_id: toolCall.id,
+      }),
+    ],
+  };
+}
+
+// Build the graph with context loading
+const workflow = new StateGraph(LoopmanGraphState)
+  .addNode(
+    "load_context",
+    createLoopmanContextNode({
+      apiKey: process.env.LOOPMAN_API_KEY!,
+      workflowId: process.env.LOOPMAN_WORKFLOW_ID!,
+      category: "hello-world",
+      debug: true,
+    })
+  )
+  .addNode("agent", agentNode)
+  .addNode(
+    "loopman_validation",
+    createLoopmanValidationNode({
+      apiKey: process.env.LOOPMAN_API_KEY!,
+      workflowId: process.env.LOOPMAN_WORKFLOW_ID!,
+      debug: true,
+    })
+  )
+  .addNode("tools", toolNode)
+  .addEdge(START, "load_context")
+  .addEdge("load_context", "agent")
+  .addEdge("agent", "loopman_validation")
+  .addConditionalEdges(
+    "loopman_validation",
+    createLoopmanConditionalEdge({ debug: true }),
+    {
+      execute: "tools",
+      rejected: END,
+      retry: "agent",
+      timeout: END,
+      error: END,
+    }
+  )
+  .addEdge("tools", END);
+
+// Compile and run
+const checkpointer = new MemorySaver();
+const app = workflow.compile({ checkpointer });
+
+async function main() {
+  const config = { configurable: { thread_id: "hello-world-thread" } };
+  const inputs = {
+    messages: [new HumanMessage("Say hello to Alice")],
+  };
+
+  console.log("Starting LangGraph workflow with context enrichment...");
+
+  for await (const output of await app.stream(inputs, config)) {
+    const nodeName = Object.keys(output)[0];
+    console.log(`Step: ${nodeName}`);
+  }
+
+  const finalState = await app.getState(config);
+  console.log("Final status:", finalState.values.loopmanTaskStatus);
+  console.log("Guidelines loaded:", finalState.values.guidelines?.length || 0);
+  console.log(
+    "Decision context loaded:",
+    finalState.values.decisionContext?.length || 0
+  );
+  console.log("Workflow completed!");
+}
+
+main().catch(console.error);

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

@@ -0,0 +1,27 @@
+{
+  "name": "loopman-langgraph-hello-world",
+  "version": "1.0.0",
+  "description": "Loopman LangGraph Hello World 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/langgraph": "^1.0.1",
+    "@langchain/openai": "^1.0.0",
+    "@loopman/langchain-sdk": "^1.12.0",
+    "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/langgraph-hello-world/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/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@loopman/langchain-sdk",
-  "version": "1.7.0",
+  "version": "1.12.0",
   "description": "LangChain TypeScript SDK - Human-in-the-Loop validation via Loopman platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsc",
+    "build": "npm run export-templates && tsc",
     "clean": "rm -rf dist",
-    "release": "./scripts/release.sh"
+    "release": "./scripts/release.sh",
+    "export-templates": "mkdir -p dist && node scripts/export-templates.js",
+    "example:langgraph-full-state": "tsx examples/5-langgraph-integration/full-state-example.ts"
   },
   "keywords": [
     "langchain",
@@ -41,18 +43,21 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "examples/templates"
   ],
   "dependencies": {
     "@langchain/core": "^1.0.2",
     "@langchain/mcp-adapters": "^1.0.0",
     "@langchain/langgraph": "^1.0.1",
     "@langchain/openai": "^1.0.0",
+    "langchain": "^1.0.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
     "@types/node": "^24.9.2",
     "dotenv": "^17.2.3",
-    "langchain": "^1.0.2",
     "tsx": "^4.20.6",
-    "typescript": "^5.9.3",
-    "zod": "^3.25.76"
+    "typescript": "^5.9.3"
   }
 }