@wengine-ai/llms 2.3.231 → 2.3.232

package/dist/services/active-probe.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Active health/quota probing service for providers
+ * Runs periodic probes to refresh health and quota info without waiting for real traffic
+ */
+import type { LLMProvider } from '../types/llm';
+/**
+ * Configuration for active probing behavior
+ */
+export interface ActiveProbeConfig {
+    /** Enable active probing (default: true) */
+    enabled?: boolean;
+    /** Interval in minutes for periodic quota probes (default: 10) */
+    quotaProbeIntervalMinutes?: number;
+    /** Timeout in milliseconds for probe requests (default: 15000) */
+    probeTimeoutMs?: number;
+    /** Initial delay before starting first probe (default: 5000) */
+    initialDelayMs?: number;
+    /** Providers to exclude from active probing (e.g., providers without models endpoint) */
+    excludeProviders?: string[];
+}
+/**
+ * Active probe scheduler
+ */
+export declare class ActiveProbeService {
+    private config;
+    private quotaProbeTimer?;
+    private healthProbeTimer?;
+    private wakeupTimer?;
+    private rateLimitProbeTimer?;
+    private lastWakeupDate;
+    private getProviders;
+    private resolveProxyUrl?;
+    private logger?;
+    private getConfig?;
+    private running;
+    constructor(getProviders: () => LLMProvider[], config?: ActiveProbeConfig, resolveProxyUrl?: (provider: LLMProvider) => string | undefined, logger?: any, getConfig?: (key: string) => any);
+    /**
+     * Start the active probe loop
+     */
+    start(): void;
+    /**
+     * Stop all probe timers
+     */
+    stop(): void;
+    /**
+     * Run quota probes for configured providers.
+     * Provider-specific adapters actively query official quota APIs, while the
+     * Kimi/Moonshot models probe continues to capture header-based limits.
+     * When quota is exhausted, marks provider as unhealthy in health store.
+     */
+    private runQuotaProbe;
+    /**
+     * Run health probe for all providers
+     * Probes every configured provider to detect reachability issues early,
+     * not just providers already in the fail pool.
+     */
+    private runHealthProbe;
+    /**
+     * Run independent probe for rate-limited models.
+     * Sends real chat requests (max_tokens:1) to test if the rate limit has cleared.
+     * Rate-limited models are NOT probed by runHealthProbe — they have a separate timer
+     * so they can be checked more frequently (every 2 minutes) without affecting normal probes.
+     */
+    private runRateLimitProbe;
+    /**
+     * Run scheduled wake-up for configured providers
+     */
+    private runScheduledWakeup;
+    private isWakeupGloballyEnabled;
+    /**
+     * Check if the wake-up has already fired for this provider today.
+     * Returns true if already fired, so the caller can skip.
+     * If not yet fired, atomically marks it as fired.
+     */
+    private hasWakeupFiredToday;
+    /**
+     * Trigger a manual probe for a specific provider
+     */
+    probeProviderManually(providerName: string): Promise<boolean>;
+}
+/**
+ * Initialize and get the active probe service
+ */
+export declare function getActiveProbeService(getProviders: () => LLMProvider[], config?: ActiveProbeConfig, resolveProxyUrl?: (provider: LLMProvider) => string | undefined, logger?: any, getConfig?: (key: string) => any): ActiveProbeService;
+/**
+ * Start the active probe service (convenience function)
+ */
+export declare function startActiveProbe(getProviders: () => LLMProvider[], config?: ActiveProbeConfig, resolveProxyUrl?: (provider: LLMProvider) => string | undefined, logger?: any, getConfig?: (key: string) => any): ActiveProbeService;
+/**
+ * Stop the active probe service
+ */
+export declare function stopActiveProbe(): void;
+/**
+ * Reset the active probe service (for testing)
+ */
+export declare function resetActiveProbeService(): void;

package/dist/services/config.d.ts

@@ -0,0 +1,30 @@
+export interface ConfigOptions {
+    envPath?: string;
+    jsonPath?: string;
+    useEnvFile?: boolean;
+    useJsonFile?: boolean;
+    useEnvironmentVariables?: boolean;
+    initialConfig?: AppConfig;
+}
+export interface AppConfig {
+    [key: string]: any;
+}
+export declare class ConfigService {
+    private config;
+    private options;
+    constructor(options?: ConfigOptions);
+    private loadConfig;
+    private loadJsonConfig;
+    private loadEnvConfig;
+    private loadEnvironmentVariables;
+    private parseEnvConfig;
+    private isAbsolutePath;
+    get<T = any>(key: keyof AppConfig): T | undefined;
+    get<T = any>(key: keyof AppConfig, defaultValue: T): T;
+    getAll(): AppConfig;
+    getHttpsProxy(): string | undefined;
+    has(key: keyof AppConfig): boolean;
+    set(key: keyof AppConfig, value: any): void;
+    reload(): void;
+    getConfigSummary(): string;
+}

package/dist/services/provider-health.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Provider health state for circuit breaker pattern
+ */
+export interface ProviderHealthState {
+    provider: string;
+    model: string;
+    status: 'closed' | 'open' | 'half-open';
+    failureCount: number;
+    successCount: number;
+    lastFailureTime: number;
+    lastProbeTime: number;
+    lastError?: string;
+    /** Epoch ms before which a rate-limited model should NOT be probed or used.
+     *  Set by markRateLimited(); cleared on expiry (auto-recover) or on explicit recovery. */
+    rateLimitUntil?: number;
+}
+/**
+ * Configuration for health pool behavior
+ */
+export interface HealthPoolConfig {
+    enabled?: boolean;
+    failureThreshold?: number;
+    probeIntervalMinutes?: number;
+    halfOpenSuccessThreshold?: number;
+}
+/**
+ * Provider health store implementing circuit breaker pattern
+ * Tracks provider/model health and manages state transitions
+ */
+export declare class ProviderHealthStore {
+    private states;
+    private config;
+    private probeTimer?;
+    constructor(config?: HealthPoolConfig);
+    /**
+     * Build the composite key used to index provider/model state.
+     * Returns null when either part is empty, which signals the caller to
+     * short-circuit (skip the operation) instead of creating a bogus entry like
+     * ",model" or "provider," that would pollute the health pool.
+     */
+    private getKey;
+    /**
+     * Record a successful request
+     * Transitions: open -> half-open (if probe), half-open -> closed (if threshold reached)
+     */
+    recordSuccess(provider: string, model: string): void;
+    /**
+     * Clear fallback promotions when a primary model recovers to healthy state
+     * Uses dynamic import to avoid circular dependency
+     */
+    private clearPromotionsForPrimary;
+    /**
+     * Record a failed request
+     * Transitions: closed -> open (if threshold), half-open -> open (immediate)
+     */
+    recordFailure(provider: string, model: string, error?: string): void;
+    /**
+     * Get current health state for a provider/model
+     */
+    getState(provider: string, model: string): ProviderHealthState | undefined;
+    /**
+     * Check if a provider/model is available for routing
+     * closed = available, half-open = available (lower priority), open = unavailable
+     */
+    isAvailable(provider: string, model: string): boolean;
+    /**
+     * Get health status priority for sorting
+     * Returns: 0 = closed (best), 1 = half-open (ok), 2 = open (worst)
+     */
+    getPriority(provider: string, model: string): number;
+    /**
+     * Get all models that are healthy (closed status)
+     */
+    getHealthyModels(): string[];
+    /**
+     * Get all models in fail pool (open status)
+     */
+    getFailPoolModels(): string[];
+    /**
+     * Get all models in half-open state
+     */
+    getHalfOpenModels(): string[];
+    /**
+     * Immediately mark a provider/model as open (unavailable)
+     * Used when fallback succeeds to prevent further requests to a failing primary
+     */
+    forceOpen(provider: string, model: string, error?: string): void;
+    /**
+     * Immediately mark a provider/model as rate-limited (unavailable).
+     * Sets a rateLimitUntil timestamp after which the model auto-recovers.
+     * Does NOT increment failureCount so the generic circuit-breaker threshold
+     * (used for network / unreachable failures) is preserved separately.
+     */
+    markRateLimited(provider: string, model: string, retryAfterSeconds?: number, error?: string): void;
+    /**
+     * Get all models currently in rate-limited state.
+     * Returns keys in "provider,model" format.
+     */
+    getRateLimitedModels(): string[];
+    /**
+     * Check if probe is needed for an open state
+     * Returns true if probeInterval has elapsed since last probe
+     */
+    needsProbe(state: ProviderHealthState): boolean;
+    /**
+     * Mark that a probe attempt has been made
+     */
+    markProbeAttempt(provider: string, model: string): void;
+    /**
+     * Clear all health state (for testing or manual reset)
+     */
+    clear(): void;
+    /**
+     * Recover a provider/model from health fail pool
+     */
+    recover(provider: string, model: string): void;
+    /**
+     * Get all states for debugging/monitoring
+     */
+    getAllStates(): ProviderHealthState[];
+    /**
+     * Restore a previously persisted health state.
+     */
+    restore(state: ProviderHealthState): void;
+    /**
+     * Stop probe timer
+     */
+    stopProbeTimer(): void;
+}
+/**
+ * Initialize persistence: load from disk and set up periodic save.
+ */
+export declare function initProviderHealthPersistence(): void;
+export declare function getHealthStore(config?: HealthPoolConfig): ProviderHealthStore;
+export declare function resetHealthStore(): void;

package/dist/services/provider.d.ts

@@ -0,0 +1,32 @@
+import { LLMProvider, RegisterProviderRequest, ModelRoute, RequestRouteInfo } from "../types/llm";
+import { ConfigService } from "./config";
+import { TransformerService } from "./transformer";
+export declare class ProviderService {
+    private readonly configService;
+    private readonly transformerService;
+    private readonly logger;
+    private providers;
+    private modelRoutes;
+    constructor(configService: ConfigService, transformerService: TransformerService, logger: any);
+    private initializeCustomProviders;
+    private initializeFromProvidersArray;
+    registerProvider(request: RegisterProviderRequest): LLMProvider;
+    getProviders(): LLMProvider[];
+    getProvider(name: string): LLMProvider | undefined;
+    updateProvider(id: string, updates: Partial<LLMProvider>): LLMProvider | null;
+    deleteProvider(id: string): boolean;
+    toggleProvider(name: string, enabled: boolean): boolean;
+    resolveModelRoute(modelName: string): RequestRouteInfo | null;
+    getAvailableModelNames(): string[];
+    getModelRoutes(): ModelRoute[];
+    private parseTransformerConfig;
+    getAvailableModels(): Promise<{
+        object: string;
+        data: Array<{
+            id: string;
+            object: string;
+            owned_by: string;
+            provider: string;
+        }>;
+    }>;
+}

package/dist/services/proxy.d.ts

@@ -0,0 +1,58 @@
+import { ProxyAgent } from "undici";
+import type { ConfigService } from "./config";
+export interface ProxyAwareProvider {
+    proxyEnabled?: boolean;
+    proxy_enabled?: boolean;
+}
+export declare const PROXY_URL_KEYS: readonly ["HTTPS_PROXY", "https_proxy", "httpsProxy", "PROXY_URL"];
+export type ProxyUrlValidation = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validate a proxy URL config value *before* it is persisted.
+ *
+ * Acceptance rules:
+ *   1. Empty / whitespace-only value is allowed (means "no proxy").
+ *   2. Values containing an env-var placeholder ($VAR / ${VAR}) are allowed —
+ *      they are raw config that gets interpolated at runtime; the final URL is
+ *      still subject to normalizeProxyUrl's http(s)-only check at request time.
+ *   3. Otherwise the value must parse as a URL with protocol http: or https:.
+ *
+ * This does NOT replace the runtime contract: getProxyDispatcher still throws
+ * TypeError for unsupported protocols when a request actually uses the proxy.
+ */
+export declare function validateProxyUrl(rawUrl: unknown): ProxyUrlValidation;
+/**
+ * Scan a config object for any proxy-related keys (PROXY_URL plus the
+ * compatibility aliases) and return a list of human-readable validation
+ * errors. Returns an empty array when every value is valid.
+ */
+export declare function findInvalidProxyUrls(config: Record<string, unknown>): Array<{
+    key: string;
+    error: string;
+}>;
+/**
+ * Resolve the configured proxy URL using the compatibility key priority.
+ */
+export declare function getConfiguredProxyUrl(configService: Pick<ConfigService, "get">): string | undefined;
+/**
+ * Interpret the global proxy policy. Missing values keep the legacy behavior
+ * where a configured proxy applies to every provider. Unknown values use
+ * normal JavaScript truthiness after strings are trimmed.
+ */
+export declare function isGlobalProxyEnabled(value: unknown): boolean;
+/**
+ * Resolve whether a provider-specific request should use the configured proxy.
+ */
+export declare function resolveProviderProxyUrl(configService: Pick<ConfigService, "get">, provider?: ProxyAwareProvider): string | undefined;
+/**
+ * Return a cached dispatcher for a normalized HTTP(S) proxy URL.
+ */
+export declare function getProxyDispatcher(proxyUrl: string): ProxyAgent;
+/**
+ * Close and clear all cached proxy dispatchers.
+ */
+export declare function closeProxyDispatchers(): Promise<void>;

package/dist/services/quota-adapters.d.ts

@@ -0,0 +1,16 @@
+import type { LLMProvider } from "../types/llm";
+export interface ProviderQuotaResult {
+    totalBalance?: number;
+    usedBalance?: number;
+    remainingBalance?: number;
+    usedDailyBalance?: number;
+    /** Explicit limit for the short-window (5h) rate limit, if available */
+    limitDaily?: number;
+    currency?: string;
+    resetTime?: string;
+    resetTime7d?: string;
+}
+export interface QuotaAdapter {
+    queryQuota(provider: LLMProvider, timeoutMs: number, proxyUrl?: string): Promise<ProviderQuotaResult | null>;
+}
+export declare function getQuotaAdapter(baseUrl: string): QuotaAdapter | null;

package/dist/services/quota-store.d.ts

@@ -0,0 +1,12 @@
+import type { ProviderQuotaResult } from "./quota-adapters";
+export interface StoredQuotaResult extends ProviderQuotaResult {
+    provider: string;
+    capturedAt: number;
+}
+export declare function storeQuotaResult(providerName: string, result: ProviderQuotaResult): void;
+export declare function getQuotaResult(providerName: string): StoredQuotaResult | undefined;
+export declare function getAllQuotaResults(): StoredQuotaResult[];
+/**
+ * Initialize persistence: load from disk and set up periodic save.
+ */
+export declare function initQuotaStorePersistence(): void;

package/dist/services/rate-limit.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Rate limit info captured from upstream provider response headers
+ */
+export interface RateLimitInfo {
+    provider: string;
+    remaining: number | null;
+    limit: number | null;
+    reset: number | null;
+    capturedAt: number;
+}
+/**
+ * Capture rate limit headers from an upstream response.
+ */
+export declare function captureRateLimitHeaders(providerName: string, apiBaseUrl: string, headers: Headers | Record<string, string>): void;
+/**
+ * Get cached rate limit info for a provider
+ */
+export declare function getRateLimitInfo(providerName: string): RateLimitInfo | undefined;
+/**
+ * Get all cached rate limit info
+ */
+export declare function getAllRateLimitInfo(): RateLimitInfo[];
+/**
+ * Initialize persistence: load from disk and set up periodic save.
+ */
+export declare function initRateLimitPersistence(): void;

package/dist/services/tokenizer.d.ts

@@ -0,0 +1,45 @@
+import { ConfigService } from "./config";
+import { ITokenizer, TokenizeRequest, TokenizerConfig, TokenizerResult, TokenizerOptions } from "../types/tokenizer";
+/**
+ * TokenizerService - Manages tokenization for different model types
+ *
+ * Supports three types of tokenizers:
+ * - tiktoken: Fast, OpenAI-compatible tokenizer (default)
+ * - huggingface: Local model-based tokenizer for open-source models
+ * - api: API-based tokenizer for closed-source models
+ *
+ * Features:
+ * - Automatic fallback to tiktoken on errors
+ * - Config-driven tokenizer selection
+ * - Per-provider and per-model configuration
+ */
+export declare class TokenizerService {
+    private tokenizers;
+    private configService;
+    private logger;
+    private options;
+    private fallbackTokenizer?;
+    constructor(configService: ConfigService, logger: any, options?: TokenizerOptions);
+    initialize(): Promise<void>;
+    /**
+     * Get or create a tokenizer for specific configuration
+     */
+    getTokenizer(config: TokenizerConfig, providerName?: string): Promise<ITokenizer>;
+    /**
+     * Count tokens for a request using the specified tokenizer configuration
+     */
+    countTokens(request: TokenizeRequest, config?: TokenizerConfig, providerName?: string): Promise<TokenizerResult>;
+    /**
+     * Get tokenizer configuration for a specific model/provider
+     */
+    getTokenizerConfigForModel(providerName: string, modelName: string): TokenizerConfig | undefined;
+    /**
+     * Dispose all tokenizers
+     */
+    dispose(): void;
+    /**
+     * Generate cache key from tokenizer config
+     */
+    private getCacheKey;
+    private getRawProvider;
+}

package/dist/services/transformer.d.ts

@@ -0,0 +1,28 @@
+import { Transformer, TransformerConstructor } from "../types/transformer";
+import { ConfigService } from "./config";
+export declare class TransformerService {
+    private readonly configService;
+    private readonly logger;
+    private transformers;
+    constructor(configService: ConfigService, logger: any);
+    registerTransformer(name: string, transformer: Transformer): void;
+    getTransformer(name: string): Transformer | TransformerConstructor | undefined;
+    getAllTransformers(): Map<string, Transformer | TransformerConstructor>;
+    getTransformersWithEndpoint(): {
+        name: string;
+        transformer: Transformer;
+    }[];
+    getTransformersWithoutEndpoint(): {
+        name: string;
+        transformer: Transformer;
+    }[];
+    removeTransformer(name: string): boolean;
+    hasTransformer(name: string): boolean;
+    registerTransformerFromConfig(config: {
+        path?: string;
+        options?: any;
+    }): Promise<boolean>;
+    initialize(): Promise<void>;
+    private registerDefaultTransformersInternal;
+    private loadFromConfig;
+}

package/dist/tokenizer/api-tokenizer.d.ts

@@ -0,0 +1,46 @@
+import { ITokenizer, TokenizeRequest, TokenizerConfig } from "../types/tokenizer";
+/**
+ * Options for API tokenizer
+ */
+interface ApiTokenizerOptions {
+    timeout?: number;
+    resolveProxyUrl?: () => string | undefined;
+}
+/**
+ * API-based tokenizer implementation
+ * Calls provider's tokenization API to get token counts
+ * Supports flexible configuration for different API formats
+ */
+export declare class ApiTokenizer implements ITokenizer {
+    readonly type = "api";
+    readonly name: string;
+    private config;
+    private logger;
+    private options;
+    constructor(config: TokenizerConfig, logger: any, options?: ApiTokenizerOptions);
+    initialize(): Promise<void>;
+    countTokens(request: TokenizeRequest): Promise<number>;
+    isInitialized(): boolean;
+    dispose(): void;
+    /**
+     * Format request body based on requestFormat
+     */
+    private formatRequestBody;
+    /**
+     * Extract messages in OpenAI format
+     */
+    private extractMessagesAsOpenAIFormat;
+    /**
+     * Extract text from a message
+     */
+    private extractTextFromMessage;
+    /**
+     * Extract all text from request
+     */
+    private extractConcatenatedText;
+    /**
+     * Extract token count from response using the configured field path
+     */
+    private extractTokenCount;
+}
+export {};

package/dist/tokenizer/huggingface-tokenizer.d.ts

@@ -0,0 +1,52 @@
+import { ITokenizer, TokenizeRequest } from "../types/tokenizer";
+/**
+ * Options for HuggingFace tokenizer
+ */
+interface HFTokenizerOptions {
+    timeout?: number;
+    cacheDir?: string;
+}
+/**
+ * HuggingFace tokenizer implementation
+ * Uses @huggingface/tokenizers library for lightweight tokenization
+ */
+export declare class HuggingFaceTokenizer implements ITokenizer {
+    readonly type = "huggingface";
+    readonly name: string;
+    private readonly modelId;
+    private readonly logger;
+    private readonly options;
+    private tokenizer;
+    private readonly cacheDir;
+    private readonly safeModelName;
+    constructor(modelId: string, logger: any, options?: HFTokenizerOptions);
+    /**
+     * Get cache file paths for tokenizer files
+     */
+    private getCachePaths;
+    /**
+     * Ensure directory exists
+     */
+    private ensureDir;
+    /**
+     * Load tokenizer files from local cache
+     */
+    private loadFromCache;
+    /**
+     * Download tokenizer files from Hugging Face Hub and save to cache
+     */
+    private downloadAndCache;
+    initialize(): Promise<void>;
+    countTokens(request: TokenizeRequest): Promise<number>;
+    isInitialized(): boolean;
+    /**
+     * Encode text to tokens (for simple text tokenization)
+     */
+    encodeText(text: string): number[];
+    dispose(): void;
+    /**
+     * Extract text from tokenize request
+     */
+    private extractTextFromRequest;
+}
+export {};

package/dist/tokenizer/tiktoken-tokenizer.d.ts

@@ -0,0 +1,20 @@
+import { TiktokenEncoding } from "tiktoken";
+import type { ITokenizer, TokenizeRequest } from "../types/tokenizer";
+/**
+ * Tiktoken-based tokenizer implementation
+ * Uses tiktoken library for fast token counting (OpenAI compatible)
+ */
+export declare class TiktokenTokenizer implements ITokenizer {
+    readonly type = "tiktoken";
+    readonly name: string;
+    private encoding?;
+    constructor(encodingName?: TiktokenEncoding);
+    initialize(): Promise<void>;
+    countTokens(request: TokenizeRequest): Promise<number>;
+    isInitialized(): boolean;
+    /**
+     * Encode text to tokens (for simple text tokenization)
+     */
+    encodeText(text: string): number[];
+    dispose(): void;
+}

package/dist/transformer/anthropic.transformer.d.ts

@@ -0,0 +1,18 @@
+import { LLMProvider, UnifiedChatRequest } from "../types/llm";
+import { Transformer, TransformerContext, TransformerOptions } from "../types/transformer";
+export declare class AnthropicTransformer implements Transformer {
+    private readonly options?;
+    name: string;
+    endPoint: string;
+    private useBearer;
+    logger?: any;
+    constructor(options?: TransformerOptions | undefined);
+    auth(request: any, provider: LLMProvider): Promise<any>;
+    transformRequestOut(request: Record<string, any>): Promise<UnifiedChatRequest>;
+    transformRequestIn(request: UnifiedChatRequest, provider: LLMProvider, context: TransformerContext): Promise<any>;
+    private isAnthropicMessagesEndpoint;
+    transformResponseIn(response: Response, context?: TransformerContext): Promise<Response>;
+    private convertAnthropicToolsToUnified;
+    private convertOpenAIStreamToAnthropic;
+    private convertOpenAIResponseToAnthropic;
+}

package/dist/transformer/cerebras.transformer.d.ts

@@ -0,0 +1,16 @@
+import { LLMProvider, UnifiedChatRequest } from "../types/llm";
+import { Transformer } from "../types/transformer";
+/**
+ * Transformer class for Cerebras
+ */
+export declare class CerebrasTransformer implements Transformer {
+    name: string;
+    /**
+     * Transform the request from Claude Code format to Cerebras format
+     * @param request - The incoming request
+     * @param provider - The LLM provider information
+     * @returns The transformed request
+     */
+    transformRequestIn(request: UnifiedChatRequest, provider: LLMProvider): Promise<Record<string, unknown>>;
+    transformResponseOut(response: Response): Promise<Response>;
+}

package/dist/transformer/cleancache.transformer.d.ts

@@ -0,0 +1,6 @@
+import { UnifiedChatRequest } from "../types/llm";
+import { Transformer } from "../types/transformer";
+export declare class CleancacheTransformer implements Transformer {
+    name: string;
+    transformRequestIn(request: UnifiedChatRequest): Promise<UnifiedChatRequest>;
+}