@loopstack/claude-module 0.21.0

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

@@ -0,0 +1,120 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { Inject } from '@nestjs/common';
+import { z } from 'zod';
+import {
+  Input,
+  RunContext,
+  Tool,
+  ToolInterface,
+  ToolResult,
+  WorkflowInterface,
+  WorkflowMetadataInterface,
+} from '@loopstack/common';
+import { ClaudeGenerateToolBaseSchema } from '../schemas/claude-generate-tool-base.schema';
+import { ClaudeClientService } from '../services';
+import { ClaudeMessagesHelperService } from '../services';
+import { ClaudeToolsHelperService } from '../services';
+import { applyCacheBreakpoints } from '../utils/cache.utils';
+
+export const ClaudeGenerateTextSchema = ClaudeGenerateToolBaseSchema.extend({
+  tools: z.array(z.string()).optional(),
+}).strict();
+
+type ClaudeGenerateTextArgsType = z.infer<typeof ClaudeGenerateTextSchema>;
+
+@Tool({
+  config: {
+    description: 'Generates text using the Anthropic Claude API',
+  },
+})
+export class ClaudeGenerateText implements ToolInterface<ClaudeGenerateTextArgsType> {
+  @Inject()
+  private readonly claudeClientService: ClaudeClientService;
+  @Inject()
+  private readonly claudeMessagesHelperService: ClaudeMessagesHelperService;
+  @Inject()
+  private readonly claudeToolsHelperService: ClaudeToolsHelperService;
+
+  @Input({
+    schema: ClaudeGenerateTextSchema,
+  })
+  args: ClaudeGenerateTextArgsType;
+
+  async execute(
+    args: ClaudeGenerateTextArgsType,
+    ctx: RunContext,
+    parent: WorkflowInterface,
+    runtime: 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(runtime.documents, {
+        messages: args.messages as Anthropic.MessageParam[],
+        messagesSearchTag: args.messagesSearchTag,
+      });
+      messages.push(...resolved);
+    }
+
+    const tools = args.tools ? this.claudeToolsHelperService.getTools(args.tools, parent) : undefined;
+
+    const response = await this.handleGenerateText(client, {
+      model,
+      messages,
+      system: args.system,
+      maxTokens: args.claude?.maxTokens,
+      tools,
+      cache: args.claude?.cache,
+    });
+
+    return {
+      data: response,
+      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 handleGenerateText(
+    client: Anthropic,
+    options: {
+      model: string;
+      messages: Anthropic.MessageParam[];
+      system?: string;
+      maxTokens?: number;
+      tools?: Anthropic.Tool[];
+      cache?: boolean;
+    },
+  ): Promise<Anthropic.Message> {
+    const { system, tools, messages } = options.cache
+      ? applyCacheBreakpoints({ system: options.system, tools: options.tools, messages: options.messages })
+      : { system: options.system, tools: options.tools, messages: options.messages };
+
+    const startTime = performance.now();
+    try {
+      const stream = client.messages.stream({
+        model: options.model,
+        messages,
+        max_tokens: options.maxTokens ?? 4096,
+        ...(system ? { system } : {}),
+        ...(tools ? { tools } : {}),
+      });
+
+      return await stream.finalMessage();
+    } catch (error) {
+      const errorResponseTime = performance.now() - startTime;
+      console.error(`Request failed after ${errorResponseTime}ms:`, error);
+      throw error;
+    }
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,4 @@
+export * from './claude-generate-text.tool';
+export * from './claude-generate-object.tool';
+export * from './claude-generate-document.tool';
+export * from './claude-delegate-tool-call.tool';

package/src/types/claude.types.ts

@@ -0,0 +1,34 @@
+import Anthropic from '@anthropic-ai/sdk';
+
+/**
+ * Configuration for creating a Claude client and selecting a model.
+ */
+export interface ClaudeModelConfig {
+  /** Model name (e.g. 'claude-sonnet-4-20250514'). Falls back to CLAUDE_MODEL env var. */
+  model?: string;
+  /** Environment variable name containing the API key. Falls back to ANTHROPIC_API_KEY. */
+  envApiKey?: string;
+}
+
+/**
+ * Options for a Claude messages API call.
+ */
+export interface ClaudeGenerateOptions {
+  messages: Anthropic.MessageParam[];
+  system?: string;
+  tools?: Anthropic.Tool[];
+  maxTokens?: number;
+  toolChoice?: Anthropic.MessageCreateParams['tool_choice'];
+}
+
+/**
+ * A tool definition in Anthropic's native format.
+ */
+export interface ClaudeToolDefinition {
+  name: string;
+  description: string;
+  input_schema: Anthropic.Tool['input_schema'];
+}
+
+// Re-export Anthropic namespace for consumer convenience
+export { default as Anthropic } from '@anthropic-ai/sdk';

package/src/types/index.ts

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

package/src/utils/cache.utils.ts

@@ -0,0 +1,59 @@
+import Anthropic from '@anthropic-ai/sdk';
+
+const CACHE_CONTROL: Anthropic.CacheControlEphemeral = { type: 'ephemeral' };
+
+/**
+ * Returns a copy of the API call options with prompt caching breakpoints applied.
+ *
+ * Breakpoints are placed on:
+ * 1. The system prompt (stable across turns)
+ * 2. The last tool definition (stable across turns)
+ * 3. The last content block of the last message (covers growing conversation)
+ *
+ * Does not mutate the input — returns new objects with cache_control markers.
+ */
+export function applyCacheBreakpoints(options: {
+  system?: string | Anthropic.TextBlockParam[];
+  tools?: Anthropic.Tool[];
+  messages: Anthropic.MessageParam[];
+}): {
+  system?: string | Anthropic.TextBlockParam[];
+  tools?: Anthropic.Tool[];
+  messages: Anthropic.MessageParam[];
+} {
+  // 1. System prompt → convert string to block array with cache_control
+  let system: string | Anthropic.TextBlockParam[] | undefined = options.system;
+  if (system && typeof system === 'string') {
+    system = [{ type: 'text', text: system, cache_control: CACHE_CONTROL }];
+  }
+
+  // 2. Last tool definition — shallow-clone the array and mark the last entry
+  let tools = options.tools;
+  if (tools?.length) {
+    tools = [...tools];
+    const last = tools.length - 1;
+    tools[last] = { ...tools[last], cache_control: CACHE_CONTROL };
+  }
+
+  // 3. Last message — clone only the last message and mark its last content block
+  let messages = options.messages;
+  if (messages.length > 0) {
+    messages = [...messages];
+    const lastIdx = messages.length - 1;
+    const lastMsg = messages[lastIdx];
+
+    if (typeof lastMsg.content === 'string') {
+      messages[lastIdx] = {
+        ...lastMsg,
+        content: [{ type: 'text', text: lastMsg.content, cache_control: CACHE_CONTROL }],
+      };
+    } else if (Array.isArray(lastMsg.content) && lastMsg.content.length > 0) {
+      const blocks: Anthropic.ContentBlockParam[] = [...lastMsg.content];
+      const lastBlockIdx = blocks.length - 1;
+      blocks[lastBlockIdx] = { ...blocks[lastBlockIdx], cache_control: CACHE_CONTROL } as Anthropic.ContentBlockParam;
+      messages[lastIdx] = { ...lastMsg, content: blocks };
+    }
+  }
+
+  return { system, tools, messages };
+}