@loopman/langchain-sdk 1.0.9

package/README.md

@@ -0,0 +1,594 @@
+# Loopman SDK TypeScript
+
+A TypeScript SDK demonstrating AI agent development with LangChain v1.0 and Human-in-the-Loop (HITL) validation patterns.
+
+## 📋 Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Examples](#examples)
+- [Loopman Middleware](#loopman-middleware)
+- [Debugging](#debugging)
+- [Project Structure](#project-structure)
+- [API Reference](#api-reference)
+- [Development](#development)
+- [License](#license)
+
+---
+
+## 🎯 Overview
+
+This SDK provides a comprehensive demonstration of building AI agents with LangChain v1.0, featuring:
+
+- **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
+
+Perfect for learning agent patterns, HITL workflows, and building production-ready AI assistants.
+
+---
+
+## ✨ Features
+
+### 🤖 Agent Capabilities
+
+- ✅ **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
+- ✅ **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
+
+### 🔧 Developer Experience
+
+- ✅ **TypeScript**: Full type safety with TSDoc comments
+- ✅ **Debugging**: VSCode launch configurations
+- ✅ **Examples**: Three complete working examples
+- ✅ **Documentation**: Inline comments and guides
+
+---
+
+## 📦 Prerequisites
+
+- **Node.js**: 18+
+- **OpenAI API Key**: Required for model calls
+- **npm/yarn**: Package manager
+
+---
+
+## 🚀 Installation
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Configure Environment
+
+Create a `.env` file in the project root:
+
+```bash
+cp env.example .env
+```
+
+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
+```
+
+---
+
+## ⚡ Quick Start
+
+### Basic Agent
+
+```typescript
+import { createAgent, tool } from "langchain";
+import { MemorySaver } from "@langchain/langgraph";
+import * as z from "zod";
+
+// Define a tool
+const greetTool = tool(({ name }) => `Hello, ${name}!`, {
+  name: "greet",
+  description: "Greet a user by name",
+  schema: z.object({
+    name: z.string(),
+  }),
+});
+
+// Create agent
+const agent = createAgent({
+  model: "openai:gpt-4o-mini",
+  tools: [greetTool],
+  checkpointer: new MemorySaver(),
+});
+
+// Run agent
+const result = await agent.invoke(
+  {
+    messages: [{ role: "user", content: "Greet Alice" }],
+  },
+  { configurable: { thread_id: "demo" } }
+);
+```
+
+### 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
+
+```typescript
+import { loopmanMiddleware } from "./src/loopman-middleware";
+
+const agent = createAgent({
+  model: "openai:gpt-4o-mini",
+  tools: [sendEmail],
+  middleware: [
+    loopmanMiddleware({
+      apiKey: process.env.LOOPMAN_API_KEY!,
+      workflowId: "email-workflow",
+      interruptOn: {
+        send_email: true, // Requires validation
+        read_email: false, // Auto-approved
+      },
+      pollingInterval: 5000, // Poll every 5 seconds
+      timeout: 300000, // 5 minutes
+    }),
+  ],
+  checkpointer: new MemorySaver(),
+});
+
+// Usage - No manual interruption handling needed!
+const result = await agent.invoke(
+  {
+    messages: [{ role: "user", content: "Send email to alice" }],
+  },
+  { configurable: { thread_id: "demo" } }
+);
+// ✅ Middleware handles HITL transparently
+```
+
+---
+
+## 📚 Examples
+
+Comprehensive examples are organized in the `examples/` directory by complexity level:
+
+### Quick Start Examples
+
+**1. Basics** (`examples/1-basics/`)
+
+- `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/`)
+
+- `01-middleware-basic.ts` - Transparent HITL with Loopman middleware
+- `02-middleware-modes.ts` - Three operation modes (tool-validation, prompt-enhancement, full)
+- `03-loopman-agent.ts` - High-level Loopman agent API
+- `04-loopman-agent-and-tool-validation.ts` - Double validation layer
+
+**3. Real-World Examples** (`examples/3-real-world-examples/`)
+
+- `task-management/task-approval.ts` - CRUD operations with selective approval
+- `data-processing/data-validation.ts` - ETL with quality checks
+- `content-workflow/content-review.ts` - Draft/publish workflow
+- `content-workflow/reddit-news-writer.ts` - Automated news curation
+
+**4. Advanced Patterns** (`examples/4-advanced-patterns/`)
+
+- `conditional-hitl.ts` - Context-aware, intelligent validation
+
+### Running Examples
+
+```bash
+# Basics
+npx tsx examples/1-basics/01-simple-agent.ts
+npx tsx examples/1-basics/03-langchain-native-hitl.ts
+
+# Loopman Integration
+npx tsx examples/2-loopman-integration/01-middleware-basic.ts
+npx tsx examples/2-loopman-integration/03-loopman-agent.ts
+
+# Real-World
+npx tsx examples/3-real-world-examples/content-workflow/reddit-news-writer.ts
+npx tsx examples/3-real-world-examples/task-management/task-approval.ts
+
+# Advanced
+npx tsx examples/4-advanced-patterns/conditional-hitl.ts
+```
+
+See [Examples README](./examples/README.md) for detailed documentation and learning paths.
+
+---
+
+**Key Features Demonstrated:**
+
+- **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
+
+---
+
+## 🔌 Loopman Middleware
+
+Custom middleware for integrating with the Loopman Human-in-the-Loop platform.
+
+### Key Feature: Transparent Validation
+
+**The middleware handles everything automatically!** No need to manually check for interruptions or poll for decisions.
+
+```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)
+```
+
+### Configuration
+
+```typescript
+import { loopmanMiddleware } from "./src/loopman-middleware";
+
+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)
+
+### 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"
+}
+```
+
+---
+
+## 🐛 Debugging
+
+VSCode launch configurations are provided in `.vscode/launch.json`.
+
+### Available Configurations
+
+1. **Debug Current Example**: Debug the currently open TypeScript file
+2. **Debug Simple Agent**: Launch `examples/1-basics/01-simple-agent.ts`
+3. **Debug HITL Agent**: Launch `examples/1-basics/03-langchain-native-hitl.ts`
+4. **Debug Loopman Middleware**: Launch `examples/2-loopman-integration/01-middleware-basic.ts`
+
+### Usage
+
+1. Open an example file
+2. Press `F5` or click the debug icon
+3. Select a configuration
+4. Set breakpoints as needed
+
+---
+
+## 📁 Project Structure
+
+```
+loopman-langchain-sdk-typescript/
+├── src/
+│   ├── agents/
+│   │   └── loopman-agent.ts        # High-level Loopman agent API
+│   ├── client/
+│   │   └── loopman-api.ts          # Loopman API client
+│   ├── helpers/
+│   │   └── prompt-orchestrator.ts  # Prompt building utilities
+│   ├── mcp/
+│   │   ├── loopman-mcp-client.ts   # MCP client integration
+│   │   └── tool-registry.ts        # Tool registry for MCP
+│   ├── services/
+│   │   ├── loopman.service.ts      # Main Loopman service
+│   │   ├── polling.service.ts      # Polling logic
+│   │   └── logger.service.ts       # Logging service
+│   ├── loopman-middleware.ts       # Core middleware implementation
+│   ├── loopman-agent-wrapper.ts    # Wrapper helpers (invokeWithRetry)
+│   ├── index.ts                    # Main export entry point
+│   └── types.ts                    # TypeScript type definitions
+├── examples/
+│   ├── 1-basics/                   # LangChain fundamentals
+│   ├── 2-loopman-integration/      # Loopman HITL integration
+│   ├── 3-real-world-examples/      # Production use cases
+│   └── 4-advanced-patterns/       # Advanced HITL patterns
+├── docs/                           # Detailed documentation
+├── dist/                           # Compiled JavaScript (generated)
+├── .env                            # Environment variables (root)
+├── env.example                     # Example environment file
+├── package.json                    # Dependencies and scripts
+├── tsconfig.json                   # TypeScript configuration
+└── README.md                       # This file
+```
+
+---
+
+## 📖 API Reference
+
+### Loopman Middleware API
+
+#### `loopmanMiddleware(config)`
+
+Creates a LangChain middleware for Loopman integration.
+
+**Parameters:**
+
+- `config.apiKey` (string, required): Loopman API key
+- `config.workflowId` (string, required): Workflow identifier
+- `config.executionId` (string, optional): Execution ID
+- `config.channelId` (string, optional): Channel ID for task routing
+- `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.debug` (boolean, optional): Enable debug logging
+
+**Returns:** `AgentMiddleware`
+
+**Example:**
+
+```typescript
+const middleware = loopmanMiddleware({
+  apiKey: process.env.LOOPMAN_API_KEY!,
+  workflowId: "my-workflow",
+  interruptOn: { send_email: true },
+  debug: true,
+});
+```
+
+### Loopman Agent API
+
+#### `createLoopmanAgent(config)`
+
+Creates a complete Loopman agent with MCP integration and double validation layer.
+
+**Parameters:**
+
+- `config.apiKey` (string, required): Loopman API key
+- `config.workflowId` (string, required): Workflow identifier
+- `config.model` (string, required): Model identifier (e.g., `"openai:gpt-4o-mini"`)
+- `config.systemPrompt` (string, required): System prompt for the agent
+- `config.additionalTools` (array, optional): Custom tools to add
+- `config.category` (string, optional): Category for guidelines organization
+- `config.channelId` (string, optional): Channel ID for task routing
+- `config.language` (string, optional): Language for human review interface
+- `config.requireApprovalForTools` (array, optional): Tools requiring approval (`['*']` for all)
+- `config.manualExecutionMode` (boolean, optional): Manual execution mode
+- `config.pollingIntervalMs` (number, optional): Polling interval
+- `config.pollingTimeoutMs` (number, optional): Polling timeout
+- `config.debug` (boolean, optional): Enable debug logging
+
+**Returns:** `LoopmanAgent`
+
+**Example:**
+
+```typescript
+const agent = createLoopmanAgent({
+  apiKey: process.env.LOOPMAN_API_KEY!,
+  workflowId: "my-workflow",
+  model: "openai:gpt-4o-mini",
+  systemPrompt: "Your instructions...",
+  additionalTools: [myTool],
+  debug: true,
+});
+
+const result = await agent.processWithHumanValidation({
+  input: "Your task...",
+});
+```
+
+See [Loopman Agent Guide](./docs/LOOPMAN_AGENT.md) for complete API documentation.
+
+---
+
+## 🛠️ Development
+
+### Scripts
+
+```bash
+# Development
+npm run build            # Compile TypeScript to JavaScript
+npm run clean            # Remove dist/ folder
+
+# Examples (run directly with tsx)
+npx tsx examples/1-basics/01-simple-agent.ts
+npx tsx examples/2-loopman-integration/01-middleware-basic.ts
+npx tsx examples/3-real-world-examples/content-workflow/reddit-news-writer.ts
+```
+
+### Adding New Tools
+
+1. Define the tool with Zod schema:
+
+```typescript
+const myTool = tool(
+  ({ param }) => {
+    // Tool logic here
+    return "result";
+  },
+  {
+    name: "my_tool",
+    description: "What the tool does",
+    schema: z.object({
+      param: z.string().describe("Parameter description"),
+    }),
+  }
+);
+```
+
+2. Add to agent:
+
+```typescript
+const agent = createAgent({
+  model: "openai:gpt-4o-mini",
+  tools: [myTool, ...otherTools],
+  // ... other config
+});
+```
+
+### Extending Loopman Middleware
+
+The Loopman middleware is fully implemented with:
+
+- ✅ Real Loopman API integration via HTTP calls
+- ✅ Polling for decision responses with configurable intervals
+- ✅ Timeout and retry logic
+- ✅ Comprehensive error handling and logging
+- ✅ Support for multiple operation modes (tool-validation, prompt-enhancement, full)
+
+See `src/loopman-middleware.ts` for the complete implementation.
+
+---
+
+## 🔗 Related Resources
+
+### LangChain Documentation
+
+- [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)
+
+### 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
+
+---
+
+## 📄 License
+
+ISC
+
+---
+
+## 🤝 Contributing
+
+This is a demonstration project. For production use, see the [Loopman LangChain SDK](../loopman-langchain-sdk).
+
+---
+
+## 💡 Tips
+
+### Environment Variables
+
+- Keep `.env` files out of version control
+- Use `env.example` as a template
+- Store sensitive keys in environment variables
+
+### Debugging
+
+- Use VSCode debug configurations for step-through debugging
+- Enable `debug: true` in middleware for detailed logging
+- Check `console.log` output for tool execution details
+
+### Performance
+
+- Use `MemorySaver` for development only
+- Use persistent checkpointers (PostgreSQL) in production
+- Consider timeout values for HITL workflows
+
+### Best Practices
+
+- Always validate tool schemas with Zod
+- Handle errors gracefully in tools
+- Use descriptive tool names and descriptions
+- Test HITL workflows thoroughly
+
+---
+
+**Built with ❤️ using LangChain v1.0 and TypeScript**

package/dist/agents/loopman-agent.d.ts

@@ -0,0 +1,29 @@
+import { CreateLoopmanAgentParams, LoopmanAgentConfig, LoopmanAgentInput, LoopmanAgentOutput } from "../types";
+export declare class LoopmanAgent {
+    private readonly config;
+    private readonly hasFixedExecutionId;
+    private readonly baseExecutionId?;
+    private readonly maxRetries;
+    private readonly debug;
+    private readonly additionalTools;
+    private agent;
+    private mcpClient;
+    private toolRegistry;
+    private loopmanService;
+    private cachedTools;
+    private middlewareConfig;
+    constructor(config: LoopmanAgentConfig);
+    processWithHumanValidation(input: LoopmanAgentInput): Promise<LoopmanAgentOutput>;
+    disconnect(): Promise<void>;
+    private normalizeMessageContent;
+    private ensureAgent;
+    private buildMessages;
+    /**
+     * Build execution messages by continuing the conversation history
+     * This ensures the agent has full context of what was proposed and approved
+     */
+    private buildExecutionMessages;
+    private extractAgentOutput;
+}
+export declare function createLoopmanAgent(config: CreateLoopmanAgentParams): LoopmanAgent;
+//# sourceMappingURL=loopman-agent.d.ts.map

package/dist/agents/loopman-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopman-agent.d.ts","sourceRoot":"","sources":["../../src/agents/loopman-agent.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,UAAU,CAAC;AAElB,qBAAa,YAAY;IAcX,OAAO,CAAC,QAAQ,CAAC,MAAM;IAbnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAU;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IAExC,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,gBAAgB,CAAa;gBAER,MAAM,EAAE,kBAAkB;IAoBjD,0BAA0B,CAC9B,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,kBAAkB,CAAC;IAgTxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC,OAAO,CAAC,uBAAuB;YAwBjB,WAAW;IAkIzB,OAAO,CAAC,aAAa;IAkBrB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAsC9B,OAAO,CAAC,kBAAkB;CAW3B;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,wBAAwB,GAC/B,YAAY,CAWd"}