@umituz/web-ai-groq-provider 1.1.13 → 2.0.0

package/dist/domains/groq/index.d.ts

@@ -0,0 +1,561 @@
+import { G as GroqConfig, d as GroqChatRequest, e as GroqChatResponse, n as IGroqHttpClient, T as TextGenerationService, j as GroqGenerationConfig, C as CacheManager, b as CacheStats, k as GroqMessage, l as GroqMessageRole } from '../../text-generation.service-BP4Q_SH0.js';
+export { a as CacheOptions, c as GroqChatChunk, f as GroqChoice, g as GroqChunkChoice, h as GroqErrorResponse, i as GroqFinishReason, m as GroqUsage, I as IGroqChatService, S as StreamingCallbacks, o as StructuredGenerationOptions, p as TextGenerationOptions, q as cacheManager } from '../../text-generation.service-BP4Q_SH0.js';
+
+/**
+ * Groq Config Store
+ * @description Single source of truth for the active GroqConfig.
+ *              Delegates key validation → validators/api-key-validator.
+ */
+
+declare class GroqConfigStore {
+    private config;
+    /**
+     * Validate and persist the given config. Cancels any prior state
+     * by overwriting (callers that need atomicity should use `reset()` first).
+     *
+     * @throws GroqError with type `INVALID_API_KEY` if validation fails.
+     */
+    initialize(config: GroqConfig): GroqConfig;
+    /**
+     * Returns the active config or throws if not initialized.
+     *
+     * @throws GroqError with type `MISSING_CONFIG` when not initialized.
+     */
+    get(): GroqConfig;
+    getOrNull(): GroqConfig | null;
+    isInitialized(): boolean;
+    /**
+     * Replace the API key.
+     *
+     * @throws GroqError with type `MISSING_CONFIG` if not initialized,
+     *         or `INVALID_API_KEY` if the new key fails validation.
+     */
+    setApiKey(apiKey: string): void;
+    reset(): void;
+}
+
+/**
+ * Groq HTTP Transport
+ * @description Low-level transport. Delegates:
+ *              - error body parsing → extractors/response-error-message-extractor
+ *              - status classification → validators/http-status-classifier
+ */
+
+declare class GroqHttpTransport {
+    private readonly configStore;
+    private readonly pendingAbortControllers;
+    constructor(configStore: GroqConfigStore);
+    cancelPendingRequests(): void;
+    postChatCompletion(request: GroqChatRequest): Promise<GroqChatResponse>;
+    streamChatCompletion(request: GroqChatRequest): Promise<ReadableStream<Uint8Array>>;
+    private request;
+    private buildHeaders;
+    private throwFromErrorResponse;
+    private normalizeError;
+}
+
+/**
+ * Request Deduplicator Utility
+ * @description Prevents duplicate in-flight API calls for the same request
+ */
+declare class RequestDeduplicator {
+    private readonly pendingRequests;
+    private readonly ttl;
+    constructor(ttl?: number);
+    execute<T>(key: string, requestFn: () => Promise<T>): Promise<T>;
+    cancelAll(): void;
+    private cleanup;
+}
+declare const requestDeduplicator: RequestDeduplicator;
+
+/**
+ * Request Queue Manager Utility
+ * @description Manages concurrent requests with priority and limits
+ */
+interface QueueOptions {
+    readonly maxConcurrent?: number;
+    readonly defaultPriority?: number;
+    readonly requestTimeout?: number;
+}
+declare class RequestQueue {
+    private queue;
+    private readonly activeRequests;
+    private readonly maxConcurrent;
+    private readonly defaultPriority;
+    private readonly requestTimeout;
+    private requestIdCounter;
+    constructor(options?: QueueOptions);
+    add<T>(requestFn: () => Promise<T>, priority?: number): Promise<T>;
+    cancelAll(): void;
+    private sortQueue;
+    private process;
+    private executeRequest;
+}
+declare const requestQueue: RequestQueue;
+
+/**
+ * Retry Manager
+ * @description Orchestrates retry logic for failed requests. Delegates
+ *              the actual delay math → calculations/exponential-backoff
+ *              and the error classification → validators/error-classifier.
+ *              No hardcoded values; all rules are explicit parameters.
+ */
+interface RetryOptions {
+    readonly maxAttempts?: number;
+    readonly initialDelay?: number;
+    readonly maxDelay?: number;
+    readonly backoffMultiplier?: number;
+    readonly jitterFactor?: number;
+    /** Custom retry predicate; bypasses the default error-type classifier. */
+    readonly shouldRetry?: (error: Error) => boolean;
+}
+declare class RetryManager {
+    private readonly defaults;
+    constructor();
+    execute<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+    private shouldRetry;
+    private delay;
+}
+declare const retryManager: RetryManager;
+/** Convenience function: execute `fn` with the default retry manager. */
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+/**
+ * Groq HTTP Client
+ * @description Facade that wires the transport together with the
+ *              request executor strategies (retry, queue, deduplication).
+ */
+
+interface GroqHttpClientDeps {
+    readonly configStore?: GroqConfigStore;
+    readonly transport?: GroqHttpTransport;
+    readonly retryManager?: RetryManager;
+    readonly queue?: RequestQueue;
+    readonly deduplicator?: RequestDeduplicator;
+}
+declare class GroqHttpClient implements IGroqHttpClient {
+    private readonly configStore;
+    private readonly transport;
+    private readonly executor;
+    constructor(deps?: GroqHttpClientDeps);
+    initialize(config: GroqConfig): void;
+    cancelPendingRequests(): void;
+    isInitialized(): boolean;
+    getApiKey(): string;
+    setApiKey(apiKey: string): void;
+    postChatCompletion(request: GroqChatRequest): Promise<GroqChatResponse>;
+    streamChatCompletion(request: GroqChatRequest): Promise<ReadableStream<Uint8Array>>;
+    reset(): void;
+}
+
+/**
+ * useGroq Hook
+ * @description React hook for Groq text generation.
+ *              Each component instance owns its own AbortController
+ *              so unmounting one component does NOT cancel requests
+ *              issued by other consumers. Use `cancel()` to abort
+ *              an in-flight request from the same component.
+ *
+ * @example
+ * ```tsx
+ * import { useGroq, getProvider } from "@umituz/web-ai-groq-provider";
+ *
+ * function MyComponent() {
+ *   const { generate, isLoading, error, result, cancel } = useGroq(
+ *     { model: "llama-3.3-70b-versatile" },
+ *     { textGeneration: getProvider()!.textGeneration },
+ *   );
+ *   // ...
+ * }
+ * ```
+ */
+
+interface UseGroqOptions {
+    readonly model?: string;
+    readonly generationConfig?: GroqGenerationConfig;
+    readonly onStart?: () => void;
+    readonly onSuccess?: (result: string) => void;
+    readonly onError?: (error: string) => void;
+}
+interface UseGroqReturn {
+    readonly isLoading: boolean;
+    readonly error: string | null;
+    readonly result: string | null;
+    /** Generate a completion from a single prompt. */
+    generate: (prompt: string, options?: GroqGenerationConfig) => Promise<string | null>;
+    /** Generate a structured JSON completion. */
+    generateJSON: <T = Record<string, unknown>>(prompt: string, options?: GroqGenerationConfig & {
+        schema?: Record<string, unknown>;
+    }) => Promise<T | null>;
+    /** Stream a completion. Returns the full text. */
+    stream: (prompt: string, onChunk: (chunk: string) => void, options?: GroqGenerationConfig) => Promise<string | null>;
+    /** Cancel any in-flight request issued by this hook instance. */
+    cancel: () => void;
+    /** Reset the hook state to its initial values. Does not clear the cache. */
+    reset: () => void;
+    /** Clear the error state. */
+    clearError: () => void;
+}
+interface UseGroqDeps {
+    readonly textGeneration: TextGenerationService;
+}
+declare function useGroq(options?: UseGroqOptions, deps?: UseGroqDeps): UseGroqReturn;
+
+/**
+ * useCacheStats Hook
+ * @description React hook that exposes dynamic, real-time statistics
+ *              of the active CacheManager. The numbers are computed
+ *              on every interval tick — no value is hardcoded.
+ *
+ * @example
+ * ```tsx
+ * function CacheDebug() {
+ *   const stats = useCacheStats({ pollIntervalMs: 2000 });
+ *   return <pre>{JSON.stringify(stats, null, 2)}</pre>;
+ * }
+ * ```
+ */
+
+interface UseCacheStatsOptions {
+    /** Polling interval in milliseconds. Default 1000. */
+    readonly pollIntervalMs?: number;
+    /** When false, polling is paused and the last snapshot is returned. */
+    readonly enabled?: boolean;
+}
+declare function useCacheStats(cache: CacheManager, options?: UseCacheStatsOptions): CacheStats;
+
+/**
+ * Groq Constants
+ * @description Available models and default configurations
+ */
+/**
+ * Available Groq models
+ */
+declare const GROQ_MODELS: {
+    /** Llama 3.1 8B - Fast and efficient (560 T/s) */
+    readonly LLAMA_3_1_8B_INSTANT: "llama-3.1-8b-instant";
+    /** Llama 3.3 70B - Versatile and powerful (280 T/s) */
+    readonly LLAMA_3_3_70B_VERSATILE: "llama-3.3-70b-versatile";
+    /** Llama 3.1 70B - Versatile (280 T/s) */
+    readonly LLAMA_3_1_70B_VERSATILE: "llama-3.1-70b-versatile";
+    /** GPT-OSS 20B - Experimental (1000 T/s) */
+    readonly GPT_OSS_20B: "openai/gpt-oss-20b";
+    /** GPT-OSS 120B - Large experimental model */
+    readonly GPT_OSS_120B: "openai/gpt-oss-120b";
+    /** Mixtral 8x7b - MoE model */
+    readonly MIXTRAL_8X7B: "mixtral-8x7b-32768";
+    /** Gemma 2 9B - Google's model */
+    readonly GEMMA_2_9B: "gemma2-9b-it";
+    /** Llama 4 Scout 17B - New model (30K T/s) */
+    readonly LLAMA_4_SCOUT_17B: "meta-llama/llama-4-scout-17b-16e-instruct";
+    /** Kimi K2 - Moonshot AI model */
+    readonly KIMI_K2_INSTRUCT: "moonshotai/kimi-k2-instruct";
+    /** Qwen 3 32B - Alibaba's model */
+    readonly QWEN3_32B: "qwen/qwen3-32b";
+};
+/**
+ * Default models for different use cases
+ */
+declare const DEFAULT_MODELS: {
+    readonly TEXT: "llama-3.1-8b-instant";
+    readonly FAST: "llama-3.1-8b-instant";
+    readonly EXPERIMENTAL: "openai/gpt-oss-20b";
+};
+/**
+ * Default generation configuration
+ */
+declare const DEFAULT_GENERATION_CONFIG: {
+    readonly temperature: 0.7;
+    readonly maxTokens: 1024;
+    readonly topP: 1;
+};
+/**
+ * API endpoints
+ */
+declare const API_ENDPOINTS: {
+    readonly CHAT: "/chat/completions";
+};
+/**
+ * Default base URL
+ */
+declare const DEFAULT_BASE_URL: "https://api.groq.com/openai/v1";
+/**
+ * Default timeouts
+ */
+declare const TIMEOUTS: {
+    readonly DEFAULT: 30000;
+    readonly STREAMING: 60000;
+};
+
+/**
+ * Error Types
+ * @description Error type enum and user-friendly message table.
+ *              The classification logic (status → type, type → retryable, ...)
+ *              lives in the validators/ and resolvers/ folders; this file
+ *              only contains the enum and the message table.
+ */
+declare enum GroqErrorType {
+    INVALID_API_KEY = "INVALID_API_KEY",
+    MISSING_CONFIG = "MISSING_CONFIG",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    ABORT_ERROR = "ABORT_ERROR",
+    RATE_LIMIT_ERROR = "RATE_LIMIT_ERROR",
+    SERVER_ERROR = "SERVER_ERROR",
+    CLIENT_ERROR = "CLIENT_ERROR",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+declare const USER_FRIENDLY_ERROR_MESSAGES: Readonly<Record<GroqErrorType, string>>;
+
+/**
+ * Groq Request Builder
+ * @description Builder for constructing GroqChatRequest instances
+ *              from a domain intent (model + messages + generation config).
+ *              Implements the Builder pattern; each method is fluent.
+ */
+
+declare class GroqChatRequestBuilder {
+    private readonly model;
+    private messages;
+    private generationConfig;
+    private streamEnabled;
+    constructor(model: string);
+    static for(model: string): GroqChatRequestBuilder;
+    withMessages(messages: ReadonlyArray<GroqMessage>): this;
+    withConfig(config: GroqGenerationConfig | undefined): this;
+    withStream(stream: boolean): this;
+    build(): GroqChatRequest;
+}
+
+/**
+ * Structured Prompt Builder
+ * @description Builds user prompts that ask the model to emit JSON,
+ *              optionally constrained to a JSON Schema.
+ */
+declare class StructuredPromptBuilder {
+    private schema;
+    private request;
+    constructor(request: string);
+    static for(request: string): StructuredPromptBuilder;
+    withSchema(schema: Record<string, unknown> | undefined): this;
+    build(): string;
+}
+
+/**
+ * Streaming Response Parser
+ * @description Parses Server-Sent Events (SSE) from Groq streaming responses.
+ *              Delegates the line-level logic → parsers/sse-line-extractor.
+ */
+interface StreamingParserCallbacks {
+    readonly onChunk: (content: string) => void;
+}
+declare class StreamingResponseParser {
+    private readonly callbacks;
+    private readonly decoder;
+    constructor(callbacks: StreamingParserCallbacks);
+    parse(stream: ReadableStream<Uint8Array>): Promise<string>;
+}
+
+/**
+ * JSON Response Parser
+ * @description Parses JSON payloads extracted by parsers/json-content-extractor.
+ */
+declare class JsonResponseParser {
+    parse<T>(rawContent: string): T;
+}
+
+/**
+ * Request Executor Strategy
+ * @description Strategy contract for composing request execution behaviors
+ *              (retry, queue, deduplication, etc.).
+ *
+ * @example
+ * ```typescript
+ * const retryThenQueue = new CompositeExecutor([
+ *   new RetryExecutor(retryManager),
+ *   new QueueExecutor(queue, priority),
+ * ]);
+ * const result = await retryThenQueue.execute(fetchSomething, payload);
+ * ```
+ */
+interface IRequestExecutor<TArgs extends unknown[], TResult> {
+    /**
+     * Run `fn(...args)` through this executor's behavior. Implementations
+     * may add retries, queueing, dedup, etc.
+     */
+    execute(fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<TResult>;
+}
+
+/**
+ * Retry Executor Strategy
+ * @description Wraps a request function with retry logic.
+ *
+ * @example
+ * ```typescript
+ * const executor = new RetryExecutor(retryManager, { maxAttempts: 5 });
+ * await executor.execute(unreliableRequest, payload);
+ * ```
+ */
+
+declare class RetryExecutor<TArgs extends unknown[], TResult> implements IRequestExecutor<TArgs, TResult> {
+    private readonly retryManager;
+    private readonly options?;
+    constructor(retryManager: RetryManager, options?: RetryOptions | undefined);
+    execute(fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<TResult>;
+}
+
+/**
+ * Queue Executor Strategy
+ * @description Wraps a request function with a concurrency-limiting queue.
+ *
+ * @example
+ * ```typescript
+ * const executor = new QueueExecutor(queue, 10); // priority 10
+ * await executor.execute(someRequest, payload);
+ * ```
+ */
+
+declare class QueueExecutor<TArgs extends unknown[], TResult> implements IRequestExecutor<TArgs, TResult> {
+    private readonly queue;
+    private readonly priority;
+    constructor(queue: RequestQueue, priority: number);
+    execute(fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<TResult>;
+}
+
+/**
+ * Dedupe Executor Strategy
+ * @description Coalesces in-flight requests with the same key
+ */
+
+type KeyGenerator<TArgs extends unknown[]> = (...args: TArgs) => string;
+interface DedupeExecutorOptions<TArgs extends unknown[]> {
+    readonly generateKey: KeyGenerator<TArgs>;
+}
+declare class DedupeExecutor<TArgs extends unknown[], TResult> implements IRequestExecutor<TArgs, TResult> {
+    private readonly deduplicator;
+    private readonly options;
+    constructor(deduplicator: RequestDeduplicator, options: DedupeExecutorOptions<TArgs>);
+    execute(fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<TResult>;
+}
+
+/**
+ * Composite Executor Strategy
+ * @description Chains multiple IRequestExecutor instances.
+ *              Order matters: the OUTERMOST executor wraps the others.
+ *              Execution flows top-to-bottom on the way in,
+ *              bottom-to-top on the way out.
+ *
+ * Example with [Dedupe, Retry, Queue]:
+ *   Dedupe -> Retry -> Queue -> fn
+ */
+
+declare class CompositeExecutor<TArgs extends unknown[], TResult> implements IRequestExecutor<TArgs, TResult> {
+    private readonly executors;
+    constructor(executors: ReadonlyArray<IRequestExecutor<TArgs, TResult>>);
+    execute(fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<TResult>;
+    private compress;
+}
+
+/**
+ * Message Factory and Transformer
+ * @description Builders and converters for Groq messages
+ */
+
+declare const createUserMessage: (content: string) => GroqMessage;
+declare const createAssistantMessage: (content: string) => GroqMessage;
+declare const createSystemMessage: (content: string) => GroqMessage;
+declare const createMessage: (role: GroqMessageRole, content: string) => GroqMessage;
+declare const promptToMessages: (prompt: string) => GroqMessage[];
+declare const extractTextFromMessages: (messages: ReadonlyArray<GroqMessage>) => string;
+declare const formatMessagesForDisplay: (messages: ReadonlyArray<GroqMessage>) => string;
+
+/**
+ * User-Friendly Error Resolver
+ * @description Maps any thrown value (Error, GroqError, string, etc.)
+ *              to a user-facing string suitable for display. No I/O,
+ *              no hardcoded user-facing strings: the mapping table
+ *              is explicit and overridable.
+ *
+ * @example
+ * ```typescript
+ * resolveUserFriendlyErrorMessage(new GroqError(GroqErrorType.RATE_LIMIT_ERROR, "x"));
+ * // "You've reached the rate limit. Please wait a moment and try again."
+ * ```
+ */
+declare function resolveUserFriendlyErrorMessage(error: unknown): string;
+
+/**
+ * Groq Error
+ * @description Custom error class for Groq API operations.
+ */
+
+interface GroqErrorMetadata {
+    readonly status?: number;
+    readonly url?: string;
+    readonly [key: string]: unknown;
+}
+declare class GroqError extends Error {
+    readonly type: GroqErrorType;
+    readonly cause?: Error;
+    readonly metadata: GroqErrorMetadata;
+    constructor(type: GroqErrorType, message: string, cause?: Error, metadata?: GroqErrorMetadata);
+    toString(): string;
+    toJSON(): {
+        name: string;
+        type: GroqErrorType;
+        message: string;
+        metadata: GroqErrorMetadata;
+    };
+}
+
+/**
+ * Error Resolver
+ * @description Resolves any thrown value to a user-friendly message.
+ *              Delegates the actual classification → resolvers/user-friendly-error-resolver.
+ */
+
+declare const resolveUserFriendlyMessage: typeof resolveUserFriendlyErrorMessage;
+interface LoggedError {
+    readonly message: string;
+    readonly type: string;
+    readonly stack?: string;
+    readonly metadata?: GroqErrorMetadata;
+}
+declare function formatErrorForLogging(error: unknown): LoggedError;
+
+/**
+ * Debounce and Throttle
+ * @description Rate limiting utilities. Delegates timing math
+ *              → calculations/timing-window.
+ */
+interface DebounceOptions {
+    readonly delay?: number;
+    readonly leading?: boolean;
+    readonly trailing?: boolean;
+}
+interface ThrottleOptions {
+    readonly interval?: number;
+    readonly leading?: boolean;
+    readonly trailing?: boolean;
+}
+declare class DebounceManager {
+    private readonly timers;
+    private readonly lastArgs;
+    debounce<T extends (...args: never[]) => unknown>(fn: T, options?: DebounceOptions): T;
+    debounceByKey<T extends (...args: never[]) => unknown>(key: string, fn: T, delay?: number): T;
+    cancelDebounce(key: string): void;
+    flushDebounce<T extends (...args: never[]) => unknown>(key: string, fn: T): void;
+}
+declare class ThrottleManager {
+    private readonly timers;
+    private readonly lastArgs;
+    throttle<T extends (...args: never[]) => unknown>(fn: T, options?: ThrottleOptions): T;
+    throttleByKey<T extends (...args: never[]) => unknown>(key: string, fn: T, interval?: number): T;
+    cancelThrottle(key: string): void;
+    isThrottled(key: string): boolean;
+}
+declare const debounceManager: DebounceManager;
+declare const throttleManager: ThrottleManager;
+declare function debounce<T extends (...args: never[]) => unknown>(fn: T, delay?: number): T;
+declare function throttle<T extends (...args: never[]) => unknown>(fn: T, interval?: number): T;
+
+export { API_ENDPOINTS, CacheManager, CacheStats, CompositeExecutor, DEFAULT_BASE_URL, DEFAULT_GENERATION_CONFIG, DEFAULT_MODELS, type DebounceOptions, DedupeExecutor, type DedupeExecutorOptions, GROQ_MODELS, GroqChatRequest, GroqChatRequestBuilder, GroqChatResponse, GroqConfig, GroqConfigStore, GroqError, type GroqErrorMetadata, GroqErrorType, GroqGenerationConfig, GroqHttpClient, type GroqHttpClientDeps, GroqHttpTransport, GroqMessage, GroqMessageRole, IGroqHttpClient, type IRequestExecutor, JsonResponseParser, QueueExecutor, type QueueOptions, RequestDeduplicator, RequestQueue, RetryExecutor, RetryManager, type RetryOptions, type StreamingParserCallbacks, StreamingResponseParser, StructuredPromptBuilder, TIMEOUTS, TextGenerationService, type ThrottleOptions, USER_FRIENDLY_ERROR_MESSAGES, type UseCacheStatsOptions, type UseGroqDeps, type UseGroqOptions, type UseGroqReturn, createAssistantMessage, createMessage, createSystemMessage, createUserMessage, debounce, debounceManager, extractTextFromMessages, formatErrorForLogging, formatMessagesForDisplay, promptToMessages, requestDeduplicator, requestQueue, resolveUserFriendlyMessage, retryManager, throttle, throttleManager, useCacheStats, useGroq, withRetry };