@almadar/llm 2.0.0 → 2.0.1

package/dist/client.d.ts

@@ -0,0 +1,142 @@
+import { a as RateLimiterOptions, b as TokenUsage } from './rate-limiter-9XAWfHwe.js';
+import { ChatOpenAI } from '@langchain/openai';
+import { ChatAnthropic } from '@langchain/anthropic';
+import { z } from 'zod';
+
+type ChatModel = ChatOpenAI | ChatAnthropic;
+type LLMProvider = 'openai' | 'deepseek' | 'anthropic' | 'kimi' | 'openrouter';
+interface ProviderConfig {
+    apiKey: string;
+    baseUrl?: string;
+    defaultModel: string;
+}
+interface LLMClientOptions {
+    provider?: LLMProvider;
+    model?: string;
+    temperature?: number;
+    streaming?: boolean;
+    rateLimiter?: RateLimiterOptions;
+    useGlobalRateLimiter?: boolean;
+    trackTokens?: boolean;
+}
+interface LLMCallOptions<T = unknown> {
+    systemPrompt: string;
+    userPrompt: string;
+    schema?: z.ZodSchema<T>;
+    maxRetries?: number;
+    retryWithContext?: boolean;
+    maxTokens?: number;
+    skipSchemaValidation?: boolean;
+    temperature?: number;
+}
+interface CacheableBlock {
+    type: 'text';
+    text: string;
+    cache_control?: {
+        type: 'ephemeral';
+    };
+}
+interface CacheAwareLLMCallOptions<T = unknown> extends LLMCallOptions<T> {
+    systemBlocks?: CacheableBlock[];
+    userBlocks?: CacheableBlock[];
+    rawText?: boolean;
+}
+interface LLMUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+type LLMFinishReason = 'stop' | 'length' | 'content_filter' | 'tool_calls' | null;
+interface LLMResponse<T> {
+    data: T;
+    raw: string;
+    finishReason: LLMFinishReason;
+    usage: LLMUsage | null;
+}
+declare const DEEPSEEK_MODELS: {
+    readonly CHAT: "deepseek-chat";
+    readonly CODER: "deepseek-coder";
+    readonly REASONER: "deepseek-reasoner";
+};
+declare const OPENAI_MODELS: {
+    readonly GPT4O: "gpt-4o";
+    readonly GPT4O_MINI: "gpt-4o-mini";
+    readonly GPT4_TURBO: "gpt-4-turbo";
+    readonly GPT35_TURBO: "gpt-3.5-turbo";
+    readonly GPT_5_1: "gpt-5.1";
+};
+declare const ANTHROPIC_MODELS: {
+    readonly CLAUDE_SONNET_4_5: "claude-sonnet-4-5-20250929";
+    readonly CLAUDE_SONNET_4: "claude-sonnet-4-20250514";
+    readonly CLAUDE_OPUS_4_5: "claude-opus-4-5-20250929";
+    readonly CLAUDE_3_5_HAIKU: "claude-3-5-haiku-20241022";
+};
+declare const KIMI_MODELS: {
+    readonly K2_5: "kimi-k2.5";
+};
+declare const OPENROUTER_MODELS: {
+    readonly QWEN_2_5_72B: "qwen/qwen-2.5-72b-instruct";
+    readonly QWEN_2_5_CODER_32B: "qwen/qwen-2.5-coder-32b-instruct";
+    readonly QWEN_3_235B: "qwen/qwen3-235b-a22b";
+    readonly LLAMA_3_3_70B: "meta-llama/llama-3.3-70b-instruct";
+    readonly LLAMA_3_1_405B: "meta-llama/llama-3.1-405b-instruct";
+    readonly LLAMA_4_MAVERICK: "meta-llama/llama-4-maverick";
+    readonly LLAMA_4_SCOUT: "meta-llama/llama-4-scout";
+};
+declare class LLMClient {
+    private model;
+    private rateLimiter;
+    private tokenTracker;
+    private modelName;
+    private provider;
+    private providerConfig;
+    private temperature;
+    private streaming;
+    constructor(options?: LLMClientOptions);
+    private usesMaxCompletionTokens;
+    private createModel;
+    private getModelWithOptions;
+    getProvider(): LLMProvider;
+    getModelName(): string;
+    getModel(): ChatModel;
+    getRateLimiterStatus(): {
+        queueLength: number;
+        activeRequests: number;
+        minuteTokens: number;
+        secondTokens: number;
+        backoffMs: number;
+    };
+    getTokenUsage(): TokenUsage | null;
+    call<T>(options: LLMCallOptions<T>): Promise<T>;
+    callWithMetadata<T>(options: LLMCallOptions<T>): Promise<LLMResponse<T>>;
+    private extractFinishReason;
+    callRaw(options: {
+        systemPrompt: string;
+        userPrompt: string;
+        maxTokens?: number;
+    }): Promise<string>;
+    callRawWithMetadata(options: {
+        systemPrompt: string;
+        userPrompt: string;
+        maxTokens?: number;
+    }): Promise<Omit<LLMResponse<string>, 'data'> & {
+        raw: string;
+    }>;
+    private isRateLimitError;
+    callWithCache<T>(options: CacheAwareLLMCallOptions<T>): Promise<LLMResponse<T>>;
+    static cacheableBlock(text: string, cache?: boolean): CacheableBlock;
+}
+declare function getSharedLLMClient(options?: LLMClientOptions): LLMClient;
+declare function resetSharedLLMClient(provider?: LLMProvider): void;
+declare function getAvailableProvider(): LLMProvider;
+declare function isProviderAvailable(provider: LLMProvider): boolean;
+declare function createRequirementsClient(options?: Partial<LLMClientOptions>): LLMClient;
+declare function createCreativeClient(options?: Partial<LLMClientOptions>): LLMClient;
+declare function createFixClient(options?: Partial<LLMClientOptions>): LLMClient;
+declare function createDeepSeekClient(options?: Partial<Omit<LLMClientOptions, 'provider'>>): LLMClient;
+declare function createOpenAIClient(options?: Partial<Omit<LLMClientOptions, 'provider'>>): LLMClient;
+declare function createAnthropicClient(options?: Partial<Omit<LLMClientOptions, 'provider'>>): LLMClient;
+declare function createKimiClient(options?: Partial<Omit<LLMClientOptions, 'provider'>>): LLMClient;
+declare function createOpenRouterClient(options?: Partial<Omit<LLMClientOptions, 'provider'>>): LLMClient;
+
+export { ANTHROPIC_MODELS, type CacheAwareLLMCallOptions, type CacheableBlock, DEEPSEEK_MODELS, KIMI_MODELS, type LLMCallOptions, LLMClient, type LLMClientOptions, type LLMFinishReason, type LLMProvider, type LLMResponse, type LLMUsage, OPENAI_MODELS, OPENROUTER_MODELS, type ProviderConfig, createAnthropicClient, createCreativeClient, createDeepSeekClient, createFixClient, createKimiClient, createOpenAIClient, createOpenRouterClient, createRequirementsClient, getAvailableProvider, getSharedLLMClient, isProviderAvailable, resetSharedLLMClient };

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import { LLMFinishReason, LLMClient } from './client.js';
+export { ANTHROPIC_MODELS, CacheAwareLLMCallOptions, CacheableBlock, DEEPSEEK_MODELS, KIMI_MODELS, LLMCallOptions, LLMClientOptions, LLMProvider, LLMResponse, LLMUsage, OPENAI_MODELS, OPENROUTER_MODELS, ProviderConfig, createAnthropicClient, createCreativeClient, createDeepSeekClient, createFixClient, createKimiClient, createOpenAIClient, createOpenRouterClient, createRequirementsClient, getAvailableProvider, getSharedLLMClient, isProviderAvailable, resetSharedLLMClient } from './client.js';
+export { R as RateLimiter, a as RateLimiterOptions, T as TokenTracker, b as TokenUsage, g as getGlobalRateLimiter, c as getGlobalTokenTracker, r as resetGlobalRateLimiter, d as resetGlobalTokenTracker } from './rate-limiter-9XAWfHwe.js';
+export { autoCloseJson, extractJsonFromText, isValidJson, parseJsonResponse, safeParseJson } from './json-parser.js';
+import { z } from 'zod';
+export { JsonSchema, STRUCTURED_OUTPUT_MODELS, StructuredGenerationOptions, StructuredGenerationResult, StructuredOutputClient, StructuredOutputOptions, getStructuredOutputClient, isStructuredOutputAvailable, resetStructuredOutputClient } from './structured-output.js';
+import '@langchain/openai';
+import '@langchain/anthropic';
+
+/**
+ * Truncation Detector
+ *
+ * Utilities for detecting when LLM output has been truncated and
+ * extracting usable content from partial responses.
+ *
+ * @packageDocumentation
+ */
+
+type TruncationReason = 'finish_reason' | 'json_incomplete' | 'bracket_mismatch' | 'none';
+interface TruncationResult {
+    isTruncated: boolean;
+    reason: TruncationReason;
+    partialContent?: string;
+    lastCompleteElement?: unknown;
+    missingCloseBrackets?: number;
+    missingCloseBraces?: number;
+}
+declare function detectTruncation(response: string, finishReason: LLMFinishReason): TruncationResult;
+declare function findLastCompleteElement(json: string): unknown | null;
+declare function isLikelyTruncated(content: string): boolean;
+
+/**
+ * LLM Continuation Utility
+ *
+ * Handles truncated LLM responses with automatic continuation.
+ * - Detects truncation via finish_reason and JSON structure
+ * - Automatically continues with full context
+ * - Merges partial and continuation responses
+ * - Salvages partial data if max continuations reached
+ *
+ * @packageDocumentation
+ */
+
+interface ContinuationOptions<T> {
+    client: LLMClient;
+    systemPrompt: string;
+    userPrompt: string;
+    schema?: z.ZodSchema<T>;
+    maxTokens?: number;
+    maxContinuations?: number;
+    maxRetries?: number;
+    buildContinuationPrompt: (partialResponse: string, attempt: number) => string;
+    continuationSystemPrompt?: string;
+}
+interface ContinuationResult<T> {
+    data: T;
+    raw: string;
+    continuationCount: number;
+    warnings: string[];
+    wasSalvaged: boolean;
+}
+declare function mergeResponses(previous: string, continuation: string): string;
+declare function salvagePartialResponse<T>(rawResponse: string): T | null;
+declare function callWithContinuation<T>(options: ContinuationOptions<T>): Promise<ContinuationResult<T>>;
+declare function buildGenericContinuationPrompt(context: string, partialResponse: string, attempt: number, maxAttempts?: number): string;
+
+export { type ContinuationOptions, type ContinuationResult, LLMClient, LLMFinishReason, type TruncationReason, type TruncationResult, buildGenericContinuationPrompt, callWithContinuation, detectTruncation, findLastCompleteElement, isLikelyTruncated, mergeResponses, salvagePartialResponse };

package/dist/json-parser.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+/**
+ * JSON Parser Utilities
+ *
+ * Robust JSON parsing for LLM responses that may contain:
+ * - Markdown code blocks
+ * - Extra text before/after JSON
+ * - Minor formatting issues
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract JSON from LLM response text.
+ *
+ * Handles markdown code blocks, raw JSON objects/arrays, and primitive values.
+ */
+declare function extractJsonFromText(text: string): string | null;
+/**
+ * Parse JSON from LLM response with optional Zod schema validation.
+ */
+declare function parseJsonResponse<T>(response: string, schema?: z.ZodSchema<T>): T;
+/**
+ * Safely parse JSON without throwing.
+ */
+declare function safeParseJson<T>(response: string, schema?: z.ZodSchema<T>): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: Error;
+};
+/**
+ * Check if a string is valid JSON.
+ */
+declare function isValidJson(str: string): boolean;
+/**
+ * Attempt to auto-close unclosed JSON brackets.
+ */
+declare function autoCloseJson(json: string): string;
+
+export { autoCloseJson, extractJsonFromText, isValidJson, parseJsonResponse, safeParseJson };

package/dist/rate-limiter-9XAWfHwe.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Token Tracker for LLM Usage
+ *
+ * Tracks token usage across multiple LLM calls for:
+ * - Cost estimation
+ * - Usage monitoring
+ * - Quota management
+ *
+ * @packageDocumentation
+ */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    callCount: number;
+}
+declare class TokenTracker {
+    private model;
+    private usage;
+    constructor(model?: string);
+    addUsage(promptTokens: number, completionTokens: number): void;
+    getSummary(): TokenUsage;
+    getEstimatedCost(): number;
+    getFormattedCost(): string;
+    getReport(): string;
+    reset(): void;
+    setModel(model: string): void;
+}
+declare function getGlobalTokenTracker(model?: string): TokenTracker;
+declare function resetGlobalTokenTracker(): void;
+
+/**
+ * Rate Limiter for LLM API Calls
+ *
+ * Implements token bucket algorithm with:
+ * - Configurable requests per minute/second
+ * - Automatic backoff on 429 errors
+ * - Queue for pending requests
+ *
+ * @packageDocumentation
+ */
+interface RateLimiterOptions {
+    /** Maximum requests per minute (default: 60) */
+    requestsPerMinute?: number;
+    /** Maximum requests per second (default: 3) */
+    requestsPerSecond?: number;
+    /** Maximum concurrent requests (default: 5) */
+    maxConcurrent?: number;
+    /** Base delay for exponential backoff in ms (default: 1000) */
+    baseBackoffMs?: number;
+    /** Maximum backoff delay in ms (default: 60000) */
+    maxBackoffMs?: number;
+}
+/**
+ * Rate limiter for LLM API calls using token bucket algorithm.
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter({ requestsPerMinute: 30 });
+ * const result = await limiter.execute(() => llm.invoke(messages));
+ * ```
+ */
+declare class RateLimiter {
+    private requestsPerMinute;
+    private requestsPerSecond;
+    private maxConcurrent;
+    private baseBackoffMs;
+    private maxBackoffMs;
+    private minuteTokens;
+    private secondTokens;
+    private activeRequests;
+    private queue;
+    private lastMinuteReset;
+    private lastSecondReset;
+    private processing;
+    private currentBackoffMs;
+    constructor(options?: RateLimiterOptions);
+    execute<T>(fn: () => Promise<T>, _maxRetries?: number): Promise<T>;
+    getStatus(): {
+        queueLength: number;
+        activeRequests: number;
+        minuteTokens: number;
+        secondTokens: number;
+        backoffMs: number;
+    };
+    reset(): void;
+    private processQueue;
+    private refillTokens;
+    private canMakeRequest;
+    private consumeTokens;
+    private getWaitTime;
+    private isRateLimitError;
+    private sleep;
+}
+declare function getGlobalRateLimiter(options?: RateLimiterOptions): RateLimiter;
+declare function resetGlobalRateLimiter(): void;
+
+export { RateLimiter as R, TokenTracker as T, type RateLimiterOptions as a, type TokenUsage as b, getGlobalTokenTracker as c, resetGlobalTokenTracker as d, getGlobalRateLimiter as g, resetGlobalRateLimiter as r };

package/dist/structured-output.d.ts

@@ -0,0 +1,113 @@
+import { a as RateLimiterOptions, b as TokenUsage } from './rate-limiter-9XAWfHwe.js';
+import { z } from 'zod';
+
+/**
+ * JSON Schema type used for OpenAI structured outputs.
+ */
+interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: unknown[];
+    const?: unknown;
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    $ref?: string;
+    $defs?: Record<string, JsonSchema>;
+    definitions?: Record<string, JsonSchema>;
+    additionalProperties?: boolean | JsonSchema;
+    description?: string;
+    default?: unknown;
+    minItems?: number;
+    maxItems?: number;
+    minLength?: number;
+}
+interface StructuredOutputOptions {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    rateLimiter?: RateLimiterOptions;
+    useGlobalRateLimiter?: boolean;
+    trackTokens?: boolean;
+}
+interface StructuredGenerationOptions {
+    /** User's natural language request */
+    userRequest: string;
+    /** Model to use (overrides client default) */
+    model?: string;
+    /** Temperature (overrides client default) */
+    temperature?: number;
+    /** Maximum tokens (overrides client default) */
+    maxTokens?: number;
+    /** JSON Schema for structured output */
+    jsonSchema?: JsonSchema;
+    /** Schema name for the json_schema response format */
+    schemaName?: string;
+    /** System prompt override */
+    systemPrompt?: string;
+    /** System prompt builder function (called dynamically) */
+    buildSystemPrompt?: () => string;
+    /** Additional system prompt instructions */
+    additionalInstructions?: string;
+    /** Existing context for updates (e.g., existing schema JSON) */
+    existingContext?: string;
+    /** Skip post-generation validation (default: false) */
+    skipValidation?: boolean;
+}
+interface StructuredGenerationResult<T = unknown> {
+    /** Generated data (guaranteed to match JSON Schema structure) */
+    data: T;
+    /** Raw JSON string from API */
+    raw: string;
+    /** Token usage statistics */
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** Generation latency in milliseconds */
+    latencyMs: number;
+    /** Model used for generation */
+    model: string;
+    /** Zod validation result (if not skipped) */
+    zodValidation?: {
+        success: boolean;
+        errors?: z.ZodError['errors'];
+    };
+}
+declare const STRUCTURED_OUTPUT_MODELS: {
+    readonly GPT5_MINI: "gpt-5-mini";
+    readonly GPT4O_MINI: "gpt-4o-mini";
+    readonly GPT4O: "gpt-4o";
+    readonly GPT4O_2024_08_06: "gpt-4o-2024-08-06";
+};
+declare class StructuredOutputClient {
+    private openai;
+    private rateLimiter;
+    private tokenTracker;
+    private defaultModel;
+    private defaultTemperature;
+    private defaultMaxTokens;
+    constructor(options?: StructuredOutputOptions);
+    private usesMaxCompletionTokens;
+    /**
+     * Generate structured output with guaranteed JSON Schema compliance.
+     */
+    generate<T = unknown>(options: StructuredGenerationOptions): Promise<StructuredGenerationResult<T>>;
+    getModel(): string;
+    getRateLimiterStatus(): {
+        queueLength: number;
+        activeRequests: number;
+        minuteTokens: number;
+        secondTokens: number;
+        backoffMs: number;
+    };
+    getTokenUsage(): TokenUsage | null;
+}
+declare function getStructuredOutputClient(options?: StructuredOutputOptions): StructuredOutputClient;
+declare function resetStructuredOutputClient(): void;
+declare function isStructuredOutputAvailable(): boolean;
+
+export { type JsonSchema, STRUCTURED_OUTPUT_MODELS, type StructuredGenerationOptions, type StructuredGenerationResult, StructuredOutputClient, type StructuredOutputOptions, getStructuredOutputClient, isStructuredOutputAvailable, resetStructuredOutputClient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/llm",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Multi-provider LLM client with rate limiting, token tracking, structured outputs, and continuation handling",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,7 +32,8 @@
     "@langchain/anthropic": "^1.3.16",
     "@langchain/openai": "^1.2.6",
     "openai": "^6.18.0",
-    "zod": "^3.22.0"
+    "zod": "^3.22.0",
+    "@langchain/core": "^0.3.0"
   },
   "peerDependencies": {
     "@almadar/core": ">=2.0.0"
@@ -44,7 +45,8 @@
   },
   "devDependencies": {
     "tsup": "^8.0.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "@types/node": "^22.0.0"
   },
   "repository": {
     "type": "git",