@loopman/langchain-sdk 1.7.0 → 1.12.0

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

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.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-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)
+