@loopstack/claude-module 0.21.0

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@loopstack/claude-module",
+  "displayName": "Loopstack Claude Module",
+  "description": "A collection of tools for performing AI actions using the Anthropic Claude API directly via the official SDK",
+  "keywords": [
+    "ai",
+    "anthropic",
+    "claude",
+    "llm",
+    "loopstack",
+    "tool"
+  ],
+  "version": "0.21.0",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Jakob Klippel",
+    "url": "https://www.linkedin.com/in/jakob-klippel/"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./src/*": "./src/*"
+  },
+  "scripts": {
+    "build": "nest build",
+    "compile": "tsc --noEmit",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "test": "jest --passWithNoTests",
+    "watch": "nest build --watch"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@loopstack/common": "^0.23.0",
+    "@loopstack/core-ui-module": "^0.20.6",
+    "@nestjs/common": "^11.1.14",
+    "@nestjs/config": "^4.0.3",
+    "@nestjs/core": "^11.1.14",
+    "zod": "^4.3.6"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.ts$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node",
+    "maxWorkers": 1
+  },
+  "loopstack": {
+    "modules": [
+      {
+        "path": "src/claude.module.ts",
+        "className": "ClaudeModule"
+      }
+    ],
+    "installModes": [
+      "add",
+      "install"
+    ]
+  }
+}

package/src/claude.module.ts

@@ -0,0 +1,32 @@
+import { Module } from '@nestjs/common';
+import { CoreUiModule } from '@loopstack/core-ui-module';
+import { ClaudeMessageDocument } from './documents';
+import { ClaudeClientService, ClaudeMessagesHelperService, ClaudeToolsHelperService } from './services';
+import { ClaudeDelegateToolCall, ClaudeGenerateDocument, ClaudeGenerateObject, ClaudeGenerateText } from './tools';
+
+@Module({
+  imports: [CoreUiModule],
+  providers: [
+    // services
+    ClaudeClientService,
+    ClaudeMessagesHelperService,
+    ClaudeToolsHelperService,
+
+    // tools
+    ClaudeGenerateText,
+    ClaudeGenerateObject,
+    ClaudeGenerateDocument,
+    ClaudeDelegateToolCall,
+
+    // documents
+    ClaudeMessageDocument,
+  ],
+  exports: [
+    ClaudeGenerateText,
+    ClaudeGenerateObject,
+    ClaudeGenerateDocument,
+    ClaudeDelegateToolCall,
+    ClaudeMessageDocument,
+  ],
+})
+export class ClaudeModule {}

package/src/documents/claude-message-document.ts

@@ -0,0 +1,26 @@
+import { Injectable } from '@nestjs/common';
+import { z } from 'zod';
+import { Document, Input } from '@loopstack/common';
+
+export const ClaudeMessageDocumentSchema = z.object({
+  role: z.enum(['user', 'assistant']),
+  content: z.union([z.string(), z.array(z.any())]),
+  toolResults: z.array(z.any()).optional(),
+});
+
+export type ClaudeMessageDocumentContentType = z.infer<typeof ClaudeMessageDocumentSchema>;
+
+@Injectable()
+@Document({
+  config: {
+    type: 'document',
+    description: 'Claude Message Document. Stores messages in Anthropic native format.',
+  },
+  configFile: __dirname + '/claude-message-document.yaml',
+})
+export class ClaudeMessageDocument {
+  @Input({
+    schema: ClaudeMessageDocumentSchema,
+  })
+  content: z.infer<typeof ClaudeMessageDocumentSchema>;
+}

package/src/documents/claude-message-document.yaml

@@ -0,0 +1,5 @@
+tags:
+  - message
+ui:
+  form:
+    widget: claude-message

package/src/documents/index.ts

@@ -0,0 +1 @@
+export * from './claude-message-document';

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './claude.module';
+export * from './tools';
+export * from './documents';

package/src/schemas/claude-generate-tool-base.schema.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+export const ClaudeGenerateToolBaseSchema = z.object({
+  claude: z
+    .object({
+      model: z.string().optional(),
+      envApiKey: z.string().optional(),
+      maxTokens: z.number().optional(),
+      cache: z.boolean().optional(),
+    })
+    .optional(),
+  messages: z
+    .array(
+      z.object({
+        role: z.enum(['user', 'assistant']),
+        content: z.union([z.string(), z.array(z.any())]),
+      }),
+    )
+    .optional(),
+  system: z.string().optional(),
+  prompt: z.string().optional(),
+  messagesSearchTag: z.string().optional(),
+});

package/src/services/claude-client.service.ts

@@ -0,0 +1,34 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { Injectable } from '@nestjs/common';
+import { ClaudeModelConfig } from '../types';
+
+@Injectable()
+export class ClaudeClientService {
+  private getApiKey(envApiKey?: string): string {
+    const envVar = envApiKey ?? 'ANTHROPIC_API_KEY';
+    const apiKey = process.env[envVar];
+
+    if (!apiKey) {
+      throw new Error(`No API key found! Please make sure to provide "${envVar}" in your .env file.`);
+    }
+
+    return apiKey;
+  }
+
+  getClient(config?: ClaudeModelConfig): Anthropic {
+    const apiKey = this.getApiKey(config?.envApiKey);
+    return new Anthropic({ apiKey });
+  }
+
+  getModel(config?: ClaudeModelConfig): string {
+    const model = config?.model ?? process.env['CLAUDE_MODEL'];
+
+    if (!model) {
+      throw new Error(
+        'No model defined. Please provide CLAUDE_MODEL env var or set the claude.model parameter in the tool args.',
+      );
+    }
+
+    return model;
+  }
+}

package/src/services/claude-messages-helper.service.ts

@@ -0,0 +1,41 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { Injectable } from '@nestjs/common';
+import { DocumentEntity } from '@loopstack/common';
+
+@Injectable()
+export class ClaudeMessagesHelperService {
+  private searchMessages(documents: DocumentEntity[], tag: string): Anthropic.MessageParam[] {
+    return documents
+      .filter((document) => !document.isInvalidated && document.tags?.includes(tag))
+      .sort((a, b) => a.index - b.index)
+      .flatMap((document) => {
+        const content = document.content as {
+          role: 'user' | 'assistant';
+          content: string | Anthropic.ContentBlockParam[];
+          toolResults?: Anthropic.ToolResultBlockParam[];
+        };
+
+        // Combined document: expand into assistant message + user tool_result message
+        if (content.toolResults?.length) {
+          return [
+            { role: content.role, content: content.content } as Anthropic.MessageParam,
+            { role: 'user' as const, content: content.toolResults } as Anthropic.MessageParam,
+          ];
+        }
+
+        return [{ role: content.role, content: content.content } as Anthropic.MessageParam];
+      });
+  }
+
+  getMessages(
+    documents: DocumentEntity[],
+    args: { messages?: Anthropic.MessageParam[]; messagesSearchTag?: string },
+  ): Anthropic.MessageParam[] {
+    let messages: Anthropic.MessageParam[] | undefined = args.messages;
+    if (!messages?.length) {
+      messages = this.searchMessages(documents, args.messagesSearchTag ?? 'message');
+    }
+
+    return messages;
+  }
+}

package/src/services/claude-tools-helper.service.ts

@@ -0,0 +1,38 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { Injectable } from '@nestjs/common';
+import { toJSONSchema } from 'zod';
+import { ToolInterface, WorkflowInterface, getBlockArgsSchema, getBlockConfig } from '@loopstack/common';
+import { getBlockTool } from '@loopstack/common';
+import { WorkflowType } from '@loopstack/contracts/dist/types';
+
+@Injectable()
+export class ClaudeToolsHelperService {
+  getTools(tools: string[], parent: WorkflowInterface): Anthropic.Tool[] | undefined {
+    const toolDefinitions: Anthropic.Tool[] = [];
+
+    for (const toolName of tools) {
+      const tool = getBlockTool<ToolInterface>(parent, toolName);
+      if (!tool) {
+        throw new Error(`Tool with name ${toolName} not available in Workflow context.`);
+      }
+
+      const inputSchema = getBlockArgsSchema(tool);
+      const config = getBlockConfig<WorkflowType>(tool);
+      if (!config) {
+        throw new Error(`Block ${tool.constructor.name} is missing @BlockConfig decorator`);
+      }
+
+      if (inputSchema) {
+        const jsonSchema = toJSONSchema(inputSchema);
+
+        toolDefinitions.push({
+          name: toolName,
+          description: config.description ?? '',
+          input_schema: jsonSchema as Anthropic.Tool['input_schema'],
+        });
+      }
+    }
+
+    return toolDefinitions.length ? toolDefinitions : undefined;
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,3 @@
+export * from './claude-client.service';
+export * from './claude-messages-helper.service';
+export * from './claude-tools-helper.service';

package/src/tools/claude-delegate-tool-call.tool.ts

@@ -0,0 +1,125 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { Logger } from '@nestjs/common';
+import { z } from 'zod';
+import {
+  Input,
+  RunContext,
+  Tool,
+  ToolInterface,
+  ToolResult,
+  WorkflowInterface,
+  WorkflowMetadataInterface,
+  getBlockTool,
+} from '@loopstack/common';
+
+const ClaudeDelegateToolCallSchema = z.object({
+  message: z.object({
+    id: z.string().optional(),
+    content: z.array(z.any()),
+  }),
+  document: z.string().optional(),
+  skipResponseMessage: z.boolean().optional(),
+});
+
+type ClaudeDelegateToolCallArgs = z.infer<typeof ClaudeDelegateToolCallSchema>;
+
+@Tool({
+  config: {
+    description: 'Delegate tool calls from a Claude response.',
+  },
+})
+export class ClaudeDelegateToolCall implements ToolInterface<ClaudeDelegateToolCallArgs> {
+  private readonly logger = new Logger(ClaudeDelegateToolCall.name);
+
+  @Input({
+    schema: ClaudeDelegateToolCallSchema,
+  })
+  args: ClaudeDelegateToolCallArgs;
+
+  async execute(
+    args: ClaudeDelegateToolCallArgs,
+    ctx: RunContext,
+    parent: WorkflowInterface,
+    runtime: WorkflowMetadataInterface,
+  ): Promise<ToolResult> {
+    const contentBlocks = args.message.content as Anthropic.ContentBlock[];
+    const toolResults: Anthropic.ToolResultBlockParam[] = [];
+
+    for (const block of contentBlocks) {
+      if (block.type !== 'tool_use') {
+        continue;
+      }
+
+      const tool = getBlockTool<ToolInterface>(parent, block.name);
+
+      if (!tool) {
+        throw new Error(`Tool ${block.name} not found.`);
+      }
+
+      try {
+        const result: ToolResult = await tool.execute(block.input as Record<string, unknown>, ctx, parent, runtime);
+
+        toolResults.push({
+          type: 'tool_result',
+          tool_use_id: block.id,
+          content: JSON.stringify(result.data, null, 2),
+        });
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.logger.error(`Tool "${block.name}" failed: ${errorMessage}`);
+
+        toolResults.push({
+          type: 'tool_result',
+          tool_use_id: block.id,
+          content: errorMessage,
+          is_error: true,
+        });
+      }
+    }
+
+    const resultData = { toolResults };
+
+    if (args.document && !args.skipResponseMessage) {
+      const docResult = await this.createResponseMessage(args, toolResults, ctx, parent, runtime);
+
+      return {
+        data: resultData,
+        effects: docResult.effects,
+      };
+    }
+
+    return {
+      data: resultData,
+    };
+  }
+
+  private async createResponseMessage(
+    args: ClaudeDelegateToolCallArgs,
+    toolResults: Anthropic.ToolResultBlockParam[],
+    ctx: RunContext,
+    parent: WorkflowInterface,
+    runtime: WorkflowMetadataInterface,
+  ): Promise<ToolResult> {
+    const createDocumentTool = getBlockTool<ToolInterface>(parent, 'createDocument');
+    if (!createDocumentTool) {
+      throw new Error('createDocument tool not found in parent context.');
+    }
+
+    return createDocumentTool.execute(
+      {
+        id: args.message.id,
+        document: args.document,
+        update: {
+          content: {
+            role: 'assistant',
+            content: args.message.content,
+            toolResults,
+          },
+        },
+      },
+      ctx,
+      parent,
+      runtime,
+    );
+  }
+}

package/src/tools/claude-generate-document.tool.ts

@@ -0,0 +1,66 @@
+import {
+  InjectTool,
+  Input,
+  RunContext,
+  Tool,
+  ToolInterface,
+  ToolResult,
+  WorkflowInterface,
+  WorkflowMetadataInterface,
+  getBlockTool,
+} from '@loopstack/common';
+import { CreateDocument } from '@loopstack/core-ui-module';
+import {
+  ClaudeGenerateObject,
+  ClaudeGenerateObjectArgsType,
+  ClaudeGenerateObjectSchema,
+} from './claude-generate-object.tool';
+
+@Tool({
+  config: {
+    description: 'Generates a structured object using the Anthropic Claude API and creates it as a document',
+  },
+})
+export class ClaudeGenerateDocument implements ToolInterface<ClaudeGenerateObjectArgsType> {
+  @InjectTool() private claudeGenerateObject!: ClaudeGenerateObject;
+  @InjectTool() private createDocument!: CreateDocument;
+
+  @Input({
+    schema: ClaudeGenerateObjectSchema,
+  })
+  args: ClaudeGenerateObjectArgsType;
+
+  private getRequiredTool(name: string): ToolInterface {
+    const tool = getBlockTool<ToolInterface>(this, name);
+    if (tool === undefined) {
+      throw new Error(`Tool "${name}" is not available`);
+    }
+    return tool;
+  }
+
+  async execute(
+    args: ClaudeGenerateObjectArgsType,
+    ctx: RunContext,
+    parent: WorkflowInterface,
+    metadata: WorkflowMetadataInterface,
+  ): Promise<ToolResult> {
+    const generateResult = await this.getRequiredTool('claudeGenerateObject').execute(args, ctx, parent, metadata);
+    const documentResult = await this.getRequiredTool('createDocument').execute(
+      {
+        id: args.response.id,
+        document: args.response.document,
+        update: {
+          content: generateResult.data as unknown,
+        },
+      },
+      ctx,
+      parent,
+      metadata,
+    );
+
+    return {
+      ...documentResult,
+      metadata: generateResult.metadata,
+    };
+  }
+}

package/src/tools/claude-generate-object.tool.ts

@@ -0,0 +1,151 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { Inject } from '@nestjs/common';
+import { toJSONSchema, z } from 'zod';
+import {
+  DocumentInterface,
+  Input,
+  RunContext,
+  Tool,
+  ToolInterface,
+  ToolResult,
+  WorkflowInterface,
+  WorkflowMetadataInterface,
+  getBlockArgsSchema,
+  getBlockDocument,
+} from '@loopstack/common';
+import { ClaudeGenerateToolBaseSchema } from '../schemas/claude-generate-tool-base.schema';
+import { ClaudeClientService } from '../services';
+import { ClaudeMessagesHelperService } from '../services';
+import { applyCacheBreakpoints } from '../utils/cache.utils';
+
+export const ClaudeGenerateObjectSchema = ClaudeGenerateToolBaseSchema.extend({
+  response: z.object({
+    id: z.string().optional(),
+    document: z.string(),
+  }),
+}).strict();
+
+export type ClaudeGenerateObjectArgsType = z.infer<typeof ClaudeGenerateObjectSchema>;
+
+const STRUCTURED_OUTPUT_TOOL_NAME = 'structured_output';
+
+@Tool({
+  config: {
+    description: 'Generates a structured object using the Anthropic Claude API',
+  },
+})
+export class ClaudeGenerateObject implements ToolInterface<ClaudeGenerateObjectArgsType> {
+  @Inject()
+  private readonly claudeClientService: ClaudeClientService;
+  @Inject()
+  private readonly claudeMessagesHelperService: ClaudeMessagesHelperService;
+
+  @Input({
+    schema: ClaudeGenerateObjectSchema,
+  })
+  args: ClaudeGenerateObjectArgsType;
+
+  async execute(
+    args: ClaudeGenerateObjectArgsType,
+    ctx: RunContext,
+    parent: WorkflowInterface,
+    metadata: WorkflowMetadataInterface,
+  ): Promise<ToolResult> {
+    const client = this.claudeClientService.getClient(args.claude);
+    const model = this.claudeClientService.getModel(args.claude);
+
+    const messages: Anthropic.MessageParam[] = [];
+
+    if (args.prompt) {
+      messages.push({ role: 'user', content: args.prompt });
+    } else {
+      const resolved = this.claudeMessagesHelperService.getMessages(metadata.documents, {
+        messages: args.messages as Anthropic.MessageParam[],
+        messagesSearchTag: args.messagesSearchTag,
+      });
+      messages.push(...resolved);
+    }
+
+    const document = getBlockDocument<DocumentInterface>(parent, args.response.document);
+    if (!document) {
+      throw new Error(`Document with name "${args.response.document}" not found in tool execution context.`);
+    }
+
+    const responseSchema = getBlockArgsSchema(document);
+    if (!responseSchema) {
+      throw new Error('Claude object generation source document must have a schema.');
+    }
+
+    const jsonSchema = toJSONSchema(responseSchema);
+
+    const response = await this.handleGenerateObject(client, {
+      model,
+      messages,
+      system: args.system,
+      maxTokens: args.claude?.maxTokens,
+      inputSchema: jsonSchema as Anthropic.Tool['input_schema'],
+      cache: args.claude?.cache,
+    });
+
+    return {
+      data: response.data,
+      metadata: {
+        usage: {
+          inputTokens: response.usage.input_tokens,
+          outputTokens: response.usage.output_tokens,
+          cacheCreationInputTokens: response.usage.cache_creation_input_tokens ?? 0,
+          cacheReadInputTokens: response.usage.cache_read_input_tokens ?? 0,
+        },
+      },
+    };
+  }
+
+  private async handleGenerateObject(
+    client: Anthropic,
+    options: {
+      model: string;
+      messages: Anthropic.MessageParam[];
+      system?: string;
+      maxTokens?: number;
+      inputSchema: Anthropic.Tool['input_schema'];
+      cache?: boolean;
+    },
+  ): Promise<{ data: unknown; usage: Anthropic.Usage }> {
+    const baseTool: Anthropic.Tool = {
+      name: STRUCTURED_OUTPUT_TOOL_NAME,
+      description: 'Return the structured output matching the schema.',
+      input_schema: options.inputSchema,
+    };
+
+    const { system, tools, messages } = options.cache
+      ? applyCacheBreakpoints({ system: options.system, tools: [baseTool], messages: options.messages })
+      : { system: options.system, tools: [baseTool], messages: options.messages };
+
+    const startTime = performance.now();
+    try {
+      const response = await client.messages.create({
+        model: options.model,
+        messages,
+        max_tokens: options.maxTokens ?? 4096,
+        ...(system ? { system } : {}),
+        tools: tools!,
+        tool_choice: { type: 'tool', name: STRUCTURED_OUTPUT_TOOL_NAME },
+      });
+
+      const toolUseBlock = response.content.find((block): block is Anthropic.ToolUseBlock => block.type === 'tool_use');
+
+      if (!toolUseBlock) {
+        throw new Error('Claude did not return a tool_use block for structured output.');
+      }
+
+      return {
+        data: toolUseBlock.input,
+        usage: response.usage,
+      };
+    } catch (error) {
+      const errorResponseTime = performance.now() - startTime;
+      console.error(`Request failed after ${errorResponseTime}ms:`, error);
+      throw error;
+    }
+  }
+}