@almadar/llm 1.0.0

package/dist/chunk-PV3G5PJS.js

@@ -0,0 +1,633 @@
+import {
+  parseJsonResponse
+} from "./chunk-WM7QVK2Z.js";
+import {
+  RateLimiter,
+  getGlobalRateLimiter,
+  getGlobalTokenTracker
+} from "./chunk-MJS33AAS.js";
+
+// src/client.ts
+import { ChatOpenAI } from "@langchain/openai";
+import {
+  ChatAnthropic
+} from "@langchain/anthropic";
+import Anthropic from "@anthropic-ai/sdk";
+var CachingChatAnthropic = class extends ChatAnthropic {
+  async invoke(input, options) {
+    let messages;
+    if (typeof input === "string") {
+      messages = [{ role: "user", content: input }];
+    } else {
+      messages = input;
+    }
+    const transformedMessages = messages.map((msg) => {
+      const msgType = msg._getType?.() || msg.role || "unknown";
+      const isSystem = msgType === "system";
+      if (!isSystem) return msg;
+      if (typeof msg.content === "string") {
+        return {
+          ...msg,
+          content: [
+            {
+              type: "text",
+              text: msg.content,
+              cache_control: { type: "ephemeral" }
+            }
+          ]
+        };
+      }
+      if (Array.isArray(msg.content)) {
+        const blocks = msg.content;
+        const hasAnyCacheControl = blocks.some((b) => b.cache_control);
+        if (!hasAnyCacheControl) {
+          const transformedBlocks = blocks.map((block, idx) => {
+            if (block.type === "text" && idx === blocks.length - 1) {
+              return {
+                ...block,
+                cache_control: { type: "ephemeral" }
+              };
+            }
+            return block;
+          });
+          return { ...msg, content: transformedBlocks };
+        }
+      }
+      return msg;
+    });
+    return super.invoke(transformedMessages, options);
+  }
+};
+var PROVIDER_CONFIGS = {
+  openai: () => {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "OPENAI_API_KEY environment variable is not set. Please set it in your .env file or environment."
+      );
+    }
+    return { apiKey, baseUrl: void 0, defaultModel: "gpt-4o" };
+  },
+  deepseek: () => {
+    const apiKey = process.env.DEEPSEEK_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "DEEPSEEK_API_KEY environment variable is not set. Please set it in your .env file or environment."
+      );
+    }
+    return {
+      apiKey,
+      baseUrl: "https://api.deepseek.com/v1",
+      defaultModel: "deepseek-chat"
+    };
+  },
+  anthropic: () => {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "ANTHROPIC_API_KEY environment variable is not set. Please set it in your .env file or environment."
+      );
+    }
+    return {
+      apiKey,
+      baseUrl: void 0,
+      defaultModel: "claude-sonnet-4-5-20250929"
+    };
+  },
+  kimi: () => {
+    const apiKey = process.env.KIMI_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "KIMI_API_KEY environment variable is not set. Please set it in your .env file or environment."
+      );
+    }
+    return {
+      apiKey,
+      baseUrl: "https://api.moonshot.cn/v1",
+      defaultModel: "kimi-k2.5"
+    };
+  }
+};
+var DEEPSEEK_MODELS = {
+  CHAT: "deepseek-chat",
+  CODER: "deepseek-coder",
+  REASONER: "deepseek-reasoner"
+};
+var OPENAI_MODELS = {
+  GPT4O: "gpt-4o",
+  GPT4O_MINI: "gpt-4o-mini",
+  GPT4_TURBO: "gpt-4-turbo",
+  GPT35_TURBO: "gpt-3.5-turbo",
+  GPT_5_1: "gpt-5.1"
+};
+var ANTHROPIC_MODELS = {
+  CLAUDE_SONNET_4_5: "claude-sonnet-4-5-20250929",
+  CLAUDE_SONNET_4: "claude-sonnet-4-20250514",
+  CLAUDE_OPUS_4_5: "claude-opus-4-5-20250929",
+  CLAUDE_3_5_HAIKU: "claude-3-5-haiku-20241022"
+};
+var KIMI_MODELS = {
+  K2_5: "kimi-k2.5"
+};
+var DEFAULT_TEMPERATURE = 0.3;
+var LLMClient = class {
+  constructor(options = {}) {
+    this.provider = options.provider || "openai";
+    this.temperature = options.temperature ?? DEFAULT_TEMPERATURE;
+    this.streaming = options.streaming ?? false;
+    this.providerConfig = PROVIDER_CONFIGS[this.provider]();
+    this.modelName = options.model || this.providerConfig.defaultModel;
+    const keyPreview = this.providerConfig.apiKey.slice(-4);
+    console.log(
+      `[LLMClient] Provider: ${this.provider}, Model: ${this.modelName}, Key: ****${keyPreview}`
+    );
+    if (this.providerConfig.baseUrl) {
+      console.log(
+        `[LLMClient] Using custom base URL: ${this.providerConfig.baseUrl}`
+      );
+    }
+    this.model = this.createModel();
+    this.rateLimiter = options.useGlobalRateLimiter !== false ? getGlobalRateLimiter(options.rateLimiter) : new RateLimiter(options.rateLimiter);
+    this.tokenTracker = options.trackTokens !== false ? getGlobalTokenTracker(this.modelName) : null;
+  }
+  usesMaxCompletionTokens() {
+    const model = this.modelName.toLowerCase();
+    return model.startsWith("o1") || model.startsWith("gpt-5") || model.includes("o1-") || model.includes("o3");
+  }
+  createModel(options) {
+    const maxTokens = options?.maxTokens;
+    const temperature = options?.temperature ?? this.temperature;
+    if (this.provider === "anthropic") {
+      return new CachingChatAnthropic({
+        anthropicApiKey: this.providerConfig.apiKey,
+        modelName: this.modelName,
+        temperature,
+        streaming: this.streaming,
+        maxTokens: maxTokens || 8192,
+        callbacks: [
+          {
+            handleLLMEnd: (output) => {
+              const generation = output.generations?.[0]?.[0];
+              const usage = generation?.message?.usage_metadata;
+              if (usage) {
+                const cacheCreated = usage.cache_creation_input_tokens ?? 0;
+                const cacheRead = usage.cache_read_input_tokens ?? 0;
+                const inputTokens = usage.input_tokens ?? 0;
+                const outputTokens = usage.output_tokens ?? 0;
+                if (cacheCreated > 0) {
+                  console.log(
+                    `[LLMClient:Anthropic] Cache WRITE: ${cacheCreated} tokens cached`
+                  );
+                }
+                if (cacheRead > 0) {
+                  const savingsPercent = Math.round(
+                    cacheRead / (cacheRead + inputTokens) * 100
+                  );
+                  console.log(
+                    `[LLMClient:Anthropic] Cache HIT: ${cacheRead} tokens (~${savingsPercent}% of prompt)`
+                  );
+                }
+                if (cacheCreated === 0 && cacheRead === 0 && inputTokens > 0) {
+                  if (inputTokens < 500) {
+                    console.log(
+                      `[LLMClient:Anthropic] ${inputTokens} input, ${outputTokens} output tokens (likely cached)`
+                    );
+                  } else {
+                    console.log(
+                      `[LLMClient:Anthropic] ${inputTokens} input, ${outputTokens} output tokens`
+                    );
+                  }
+                }
+              }
+            }
+          }
+        ]
+      });
+    }
+    const useCompletionTokens = this.usesMaxCompletionTokens();
+    const tokenConfig = maxTokens ? useCompletionTokens ? { modelKwargs: { max_completion_tokens: maxTokens } } : { maxTokens } : {};
+    const timeout = this.provider === "deepseek" ? 6e5 : void 0;
+    return new ChatOpenAI({
+      openAIApiKey: this.providerConfig.apiKey,
+      modelName: this.modelName,
+      temperature: useCompletionTokens ? void 0 : temperature,
+      streaming: this.streaming,
+      timeout,
+      ...tokenConfig,
+      configuration: {
+        apiKey: this.providerConfig.apiKey,
+        ...this.providerConfig.baseUrl ? { baseURL: this.providerConfig.baseUrl } : {}
+      }
+    });
+  }
+  getModelWithOptions(options) {
+    return this.createModel(options);
+  }
+  getProvider() {
+    return this.provider;
+  }
+  getModelName() {
+    return this.modelName;
+  }
+  getModel() {
+    return this.model;
+  }
+  getRateLimiterStatus() {
+    return this.rateLimiter.getStatus();
+  }
+  getTokenUsage() {
+    return this.tokenTracker?.getSummary() ?? null;
+  }
+  async call(options) {
+    const response = await this.callWithMetadata(options);
+    return response.data;
+  }
+  async callWithMetadata(options) {
+    const {
+      systemPrompt,
+      userPrompt,
+      schema,
+      maxRetries = 2,
+      retryWithContext = true,
+      maxTokens,
+      skipSchemaValidation = false,
+      temperature
+    } = options;
+    let currentPrompt = userPrompt;
+    let lastError = null;
+    console.log(
+      `[LLMClient:call] Starting call to ${this.provider}/${this.modelName}`
+    );
+    console.log(`[LLMClient:call] Prompt length: ${userPrompt.length} chars`);
+    if (maxTokens) {
+      console.log(`[LLMClient:call] Max tokens: ${maxTokens}`);
+    }
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        console.log(
+          `[LLMClient:call] Attempt ${attempt + 1}/${maxRetries + 1}...`
+        );
+        const attemptStartTime = Date.now();
+        const result = await this.rateLimiter.execute(async () => {
+          console.log(`[LLMClient:call] Invoking model...`);
+          const invokeStartTime = Date.now();
+          const modelToUse = maxTokens || temperature !== void 0 ? this.getModelWithOptions({ maxTokens, temperature }) : this.model;
+          const response = await modelToUse.invoke([
+            { role: "system", content: systemPrompt },
+            { role: "user", content: currentPrompt }
+          ]);
+          console.log(
+            `[LLMClient:call] Model responded in ${Date.now() - invokeStartTime}ms`
+          );
+          let usage = null;
+          if (response.usage_metadata) {
+            const usageMeta = response.usage_metadata;
+            usage = {
+              promptTokens: usageMeta.input_tokens || 0,
+              completionTokens: usageMeta.output_tokens || 0,
+              totalTokens: (usageMeta.input_tokens || 0) + (usageMeta.output_tokens || 0)
+            };
+            console.log(
+              `[LLMClient:call] Tokens used: ${usage.promptTokens} in, ${usage.completionTokens} out`
+            );
+            if (this.tokenTracker) {
+              this.tokenTracker.addUsage(
+                usage.promptTokens,
+                usage.completionTokens
+              );
+            }
+          }
+          const finishReason = this.extractFinishReason(response);
+          if (finishReason === "length") {
+            console.warn(
+              `[LLMClient:call] Response truncated (finish_reason=length)`
+            );
+          }
+          const content = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
+          console.log(
+            `[LLMClient:call] Response length: ${content.length} chars, finish_reason: ${finishReason}`
+          );
+          return { content, finishReason, usage };
+        });
+        console.log(
+          `[LLMClient:call] Attempt ${attempt + 1} completed in ${Date.now() - attemptStartTime}ms, parsing response...`
+        );
+        const parsed = skipSchemaValidation ? parseJsonResponse(result.content, void 0) : parseJsonResponse(result.content, schema);
+        console.log(
+          `[LLMClient:call] Response parsed successfully${skipSchemaValidation ? " (schema validation skipped)" : ""}`
+        );
+        return {
+          data: parsed,
+          raw: result.content,
+          finishReason: result.finishReason,
+          usage: result.usage
+        };
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        console.error(
+          `[LLMClient:call] Attempt ${attempt + 1} failed:`,
+          lastError.message
+        );
+        if (this.isRateLimitError(lastError)) {
+          console.error(`[LLMClient:call] Rate limit error, not retrying`);
+          throw lastError;
+        }
+        if (attempt < maxRetries && retryWithContext) {
+          console.log(`[LLMClient:call] Will retry with error context`);
+          currentPrompt = `${userPrompt}
+
+[Previous attempt failed with: ${lastError.message}]
+Please output valid JSON that matches the expected schema.`;
+        }
+      }
+    }
+    console.error(`[LLMClient:call] All attempts exhausted, throwing error`);
+    throw lastError;
+  }
+  extractFinishReason(response) {
+    const metadata = response.response_metadata;
+    if (metadata?.finish_reason) {
+      const reason = metadata.finish_reason;
+      if (reason === "stop" || reason === "length" || reason === "content_filter" || reason === "tool_calls") {
+        return reason;
+      }
+    }
+    return null;
+  }
+  async callRaw(options) {
+    const response = await this.callRawWithMetadata(options);
+    return response.raw;
+  }
+  async callRawWithMetadata(options) {
+    const { systemPrompt, userPrompt, maxTokens } = options;
+    return this.rateLimiter.execute(async () => {
+      const modelToUse = maxTokens ? this.getModelWithOptions({ maxTokens }) : this.model;
+      const response = await modelToUse.invoke([
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userPrompt }
+      ]);
+      let usage = null;
+      if (response.usage_metadata) {
+        const usageMeta = response.usage_metadata;
+        usage = {
+          promptTokens: usageMeta.input_tokens || 0,
+          completionTokens: usageMeta.output_tokens || 0,
+          totalTokens: (usageMeta.input_tokens || 0) + (usageMeta.output_tokens || 0)
+        };
+        if (this.tokenTracker) {
+          this.tokenTracker.addUsage(
+            usage.promptTokens,
+            usage.completionTokens
+          );
+        }
+      }
+      const finishReason = this.extractFinishReason(response);
+      const content = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
+      return { raw: content, finishReason, usage };
+    });
+  }
+  isRateLimitError(error) {
+    const message = error.message.toLowerCase();
+    return message.includes("rate limit") || message.includes("429") || message.includes("quota exceeded");
+  }
+  // ==========================================================================
+  // Anthropic Cache Control Support
+  // ==========================================================================
+  async callWithCache(options) {
+    const {
+      systemPrompt,
+      userPrompt,
+      systemBlocks,
+      userBlocks,
+      schema,
+      maxRetries = 2,
+      maxTokens,
+      skipSchemaValidation = false,
+      temperature,
+      rawText = false
+    } = options;
+    if (this.provider !== "anthropic") {
+      console.log(
+        `[LLMClient:callWithCache] Provider ${this.provider} doesn't support caching, using regular call`
+      );
+      return this.callWithMetadata(options);
+    }
+    const cacheableCount = (systemBlocks || []).filter((b) => b.cache_control).length + (userBlocks || []).filter((b) => b.cache_control).length;
+    console.log(
+      `[LLMClient:callWithCache] ${cacheableCount} cacheable block(s)`
+    );
+    let lastError = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        console.log(
+          `[LLMClient:callWithCache] Attempt ${attempt + 1}/${maxRetries + 1}...`
+        );
+        const result = await this.rateLimiter.execute(async () => {
+          const anthropic = new Anthropic();
+          const systemContent = systemBlocks && systemBlocks.length > 0 ? systemBlocks.map((b) => ({
+            type: "text",
+            text: b.text,
+            ...b.cache_control ? { cache_control: b.cache_control } : {}
+          })) : systemPrompt ? [{ type: "text", text: systemPrompt }] : [];
+          const userContent = userBlocks && userBlocks.length > 0 ? userBlocks.map((b) => ({
+            type: "text",
+            text: b.text,
+            ...b.cache_control ? { cache_control: b.cache_control } : {}
+          })) : userPrompt ? [{ type: "text", text: userPrompt }] : [];
+          const response = await anthropic.messages.create({
+            model: this.modelName,
+            max_tokens: maxTokens || 8192,
+            temperature: temperature ?? 0,
+            system: systemContent,
+            messages: [{ role: "user", content: userContent }]
+          });
+          const textContent = response.content.find((c) => c.type === "text");
+          const content = textContent && "text" in textContent ? textContent.text : "";
+          const apiUsage = response.usage;
+          const cacheRead = apiUsage.cache_read_input_tokens || 0;
+          const cacheCreation = apiUsage.cache_creation_input_tokens || 0;
+          if (cacheCreation > 0) {
+            console.log(
+              `[LLMClient:callWithCache] Cache WRITE: ${cacheCreation} tokens`
+            );
+          }
+          if (cacheRead > 0) {
+            const savingsPercent = Math.round(
+              cacheRead / (cacheRead + apiUsage.input_tokens) * 100
+            );
+            console.log(
+              `[LLMClient:callWithCache] Cache HIT: ${cacheRead} tokens (~${savingsPercent}% of prompt)`
+            );
+          }
+          if (cacheCreation === 0 && cacheRead === 0) {
+            console.log(
+              `[LLMClient:callWithCache] No caching: ${apiUsage.input_tokens} input tokens`
+            );
+          }
+          const usage = {
+            promptTokens: apiUsage.input_tokens,
+            completionTokens: apiUsage.output_tokens,
+            totalTokens: apiUsage.input_tokens + apiUsage.output_tokens
+          };
+          if (this.tokenTracker) {
+            this.tokenTracker.addUsage(
+              usage.promptTokens,
+              usage.completionTokens
+            );
+          }
+          const finishReason = response.stop_reason === "end_turn" ? "stop" : response.stop_reason;
+          return {
+            content,
+            finishReason,
+            usage
+          };
+        });
+        let parsed;
+        if (rawText) {
+          parsed = result.content;
+        } else if (skipSchemaValidation) {
+          parsed = parseJsonResponse(result.content, void 0);
+        } else {
+          parsed = parseJsonResponse(result.content, schema);
+        }
+        return {
+          data: parsed,
+          raw: result.content,
+          finishReason: result.finishReason,
+          usage: result.usage
+        };
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        console.error(
+          `[LLMClient:callWithCache] Attempt ${attempt + 1} failed:`,
+          lastError.message
+        );
+        if (this.isRateLimitError(lastError)) {
+          throw lastError;
+        }
+      }
+    }
+    throw lastError;
+  }
+  static cacheableBlock(text, cache = true) {
+    return cache ? { type: "text", text, cache_control: { type: "ephemeral" } } : { type: "text", text };
+  }
+};
+var sharedClients = {};
+function getSharedLLMClient(options) {
+  const provider = options?.provider || "openai";
+  if (!sharedClients[provider]) {
+    sharedClients[provider] = new LLMClient(options);
+  }
+  return sharedClients[provider];
+}
+function resetSharedLLMClient(provider) {
+  if (provider) {
+    delete sharedClients[provider];
+  } else {
+    for (const key of Object.keys(sharedClients)) {
+      delete sharedClients[key];
+    }
+  }
+}
+function getAvailableProvider() {
+  if (process.env.ANTHROPIC_API_KEY) return "anthropic";
+  if (process.env.DEEPSEEK_API_KEY) return "deepseek";
+  if (process.env.KIMI_API_KEY) return "kimi";
+  if (process.env.OPENAI_API_KEY) return "openai";
+  throw new Error(
+    "No LLM API key found. Please set ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, or KIMI_API_KEY."
+  );
+}
+function isProviderAvailable(provider) {
+  switch (provider) {
+    case "openai":
+      return !!process.env.OPENAI_API_KEY;
+    case "deepseek":
+      return !!process.env.DEEPSEEK_API_KEY;
+    case "anthropic":
+      return !!process.env.ANTHROPIC_API_KEY;
+    case "kimi":
+      return !!process.env.KIMI_API_KEY;
+    default:
+      return false;
+  }
+}
+function createRequirementsClient(options) {
+  const provider = options?.provider || getAvailableProvider();
+  const defaultModel = provider === "deepseek" ? DEEPSEEK_MODELS.CHAT : OPENAI_MODELS.GPT_5_1;
+  return new LLMClient({
+    provider,
+    model: defaultModel,
+    temperature: 0.3,
+    ...options
+  });
+}
+function createCreativeClient(options) {
+  const provider = options?.provider || getAvailableProvider();
+  const defaultModel = provider === "deepseek" ? DEEPSEEK_MODELS.REASONER : OPENAI_MODELS.GPT4O;
+  return new LLMClient({
+    provider,
+    model: defaultModel,
+    temperature: 0.7,
+    ...options
+  });
+}
+function createFixClient(options) {
+  const provider = options?.provider || getAvailableProvider();
+  const defaultModel = provider === "deepseek" ? DEEPSEEK_MODELS.CHAT : OPENAI_MODELS.GPT4O_MINI;
+  return new LLMClient({
+    provider,
+    model: defaultModel,
+    temperature: 0.2,
+    ...options
+  });
+}
+function createDeepSeekClient(options) {
+  return new LLMClient({
+    provider: "deepseek",
+    model: DEEPSEEK_MODELS.CHAT,
+    ...options
+  });
+}
+function createOpenAIClient(options) {
+  return new LLMClient({
+    provider: "openai",
+    model: OPENAI_MODELS.GPT4O,
+    ...options
+  });
+}
+function createAnthropicClient(options) {
+  return new LLMClient({
+    provider: "anthropic",
+    model: ANTHROPIC_MODELS.CLAUDE_SONNET_4_5,
+    ...options
+  });
+}
+function createKimiClient(options) {
+  return new LLMClient({
+    provider: "kimi",
+    model: KIMI_MODELS.K2_5,
+    ...options
+  });
+}
+
+export {
+  DEEPSEEK_MODELS,
+  OPENAI_MODELS,
+  ANTHROPIC_MODELS,
+  KIMI_MODELS,
+  LLMClient,
+  getSharedLLMClient,
+  resetSharedLLMClient,
+  getAvailableProvider,
+  isProviderAvailable,
+  createRequirementsClient,
+  createCreativeClient,
+  createFixClient,
+  createDeepSeekClient,
+  createOpenAIClient,
+  createAnthropicClient,
+  createKimiClient
+};
+//# sourceMappingURL=chunk-PV3G5PJS.js.map