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

package/dist/text-generation.service-BP4Q_SH0.d.cts

@@ -0,0 +1,252 @@
+/**
+ * Groq Domain Entities
+ * @description Core type definitions for the Groq AI provider.
+ *              Readonly everywhere: consumers must not mutate in-flight.
+ */
+interface GroqConfig {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+    readonly timeoutMs?: number;
+    readonly textModel?: string;
+}
+interface GroqGenerationConfig {
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly topP?: number;
+    readonly n?: number;
+    readonly stop?: string[];
+    readonly frequencyPenalty?: number;
+    readonly presencePenalty?: number;
+}
+type GroqMessageRole = "system" | "user" | "assistant";
+interface GroqMessage {
+    readonly role: GroqMessageRole;
+    readonly content: string;
+}
+interface GroqChatRequest {
+    readonly model: string;
+    readonly messages: GroqMessage[];
+    readonly temperature?: number;
+    readonly max_tokens?: number;
+    readonly top_p?: number;
+    readonly n?: number;
+    readonly stop?: string[];
+    readonly frequency_penalty?: number;
+    readonly presence_penalty?: number;
+    readonly stream?: boolean;
+}
+type GroqFinishReason = "stop" | "length" | "content_filter";
+interface GroqChoice {
+    readonly index: number;
+    readonly message: {
+        readonly role: "assistant";
+        readonly content: string;
+    };
+    readonly finish_reason: GroqFinishReason;
+    readonly logprobs: null | object;
+}
+interface GroqUsage {
+    readonly prompt_tokens: number;
+    readonly completion_tokens: number;
+    readonly total_tokens: number;
+    readonly prompt_time?: number;
+    readonly completion_time?: number;
+    readonly total_time?: number;
+}
+interface GroqChatResponse {
+    readonly id: string;
+    readonly object: string;
+    readonly created: number;
+    readonly model: string;
+    readonly choices: GroqChoice[];
+    readonly usage: GroqUsage;
+    readonly system_fingerprint?: string;
+    readonly x_groq?: {
+        readonly id?: string;
+    };
+}
+interface GroqChunkChoice {
+    readonly index: number;
+    readonly delta: {
+        readonly role?: "assistant";
+        readonly content?: string;
+    };
+    readonly finish_reason: GroqFinishReason | null;
+    readonly logprobs: null | object;
+}
+interface GroqChatChunk {
+    readonly id: string;
+    readonly object: string;
+    readonly created: number;
+    readonly model: string;
+    readonly choices: GroqChunkChoice[];
+    readonly system_fingerprint?: string;
+    readonly x_groq?: {
+        readonly id?: string;
+    };
+}
+interface GroqErrorResponse {
+    readonly error: {
+        readonly message: string;
+        readonly type: string;
+        readonly code?: string;
+    };
+}
+
+/**
+ * Groq Service Interfaces
+ * @description Contracts for Groq AI services
+ */
+
+/**
+ * Options for a single text or chat generation call.
+ */
+interface TextGenerationOptions {
+    /** Override the default model for this call. */
+    readonly model?: string;
+    /** Sampling/limits configuration. */
+    readonly generationConfig?: GroqGenerationConfig;
+}
+/**
+ * Callbacks for streaming responses.
+ * - `onChunk` is called for each content fragment.
+ * - `onComplete` is called once the full text is available.
+ * - `onError` is called when the stream fails (the same error is also thrown).
+ */
+interface StreamingCallbacks {
+    readonly onChunk?: (chunk: string) => void;
+    readonly onComplete?: (fullText: string) => void;
+    readonly onError?: (error: Error) => void;
+}
+/**
+ * Options for structured (JSON) generation.
+ * Pass a JSON Schema in `schema` to constrain the model's output.
+ */
+interface StructuredGenerationOptions {
+    readonly model?: string;
+    readonly generationConfig?: GroqGenerationConfig;
+    readonly schema?: Record<string, unknown>;
+}
+/**
+ * Contract for the high-level chat service.
+ */
+interface IGroqChatService {
+    /** Generate a completion from a single prompt string. */
+    generateCompletion(prompt: string, options?: TextGenerationOptions): Promise<string>;
+    /** Generate a completion from a message history. */
+    generateChatCompletion(messages: ReadonlyArray<GroqMessage>, options?: TextGenerationOptions): Promise<string>;
+    /** Generate and parse a JSON output matching the optional schema. */
+    generateStructured<T>(prompt: string, options?: StructuredGenerationOptions): Promise<T>;
+    /** Stream a completion from a single prompt. Returns the full text. */
+    streamCompletion(prompt: string, callbacks: StreamingCallbacks, options?: TextGenerationOptions): Promise<string>;
+    /** Stream a chat completion from a message history. Returns full text. */
+    streamChatCompletion(messages: ReadonlyArray<GroqMessage>, callbacks: StreamingCallbacks, options?: TextGenerationOptions): Promise<string>;
+    /** Clear the in-memory response cache. */
+    clearCache(): void;
+}
+/**
+ * Contract for the low-level HTTP client.
+ * The strategy pipeline (retry / queue / dedupe) is wired around
+ * `postChatCompletion`; the streaming endpoint intentionally bypasses it
+ * because responses cannot be deduplicated.
+ */
+interface IGroqHttpClient {
+    postChatCompletion(request: GroqChatRequest): Promise<GroqChatResponse>;
+    streamChatCompletion(request: GroqChatRequest): Promise<ReadableStream<Uint8Array>>;
+    getApiKey(): string;
+    setApiKey(apiKey: string): void;
+    initialize(config: Readonly<{
+        apiKey: string;
+        baseUrl?: string;
+        timeoutMs?: number;
+        textModel?: string;
+    }>): void;
+    isInitialized(): boolean;
+    cancelPendingRequests(): void;
+    reset(): void;
+}
+
+/**
+ * Cache Manager
+ * @description LRU cache for API responses with TTL. Delegates:
+ *              - LRU key selection → calculations/lru-key-selector
+ *              - Cache key construction → builders/cache-key-builder
+ *              - Hit rate calculation → calculations/cache-hit-rate
+ */
+interface CacheOptions {
+    /** Maximum number of entries. Default 100. */
+    readonly maxSize?: number;
+    /** Time-to-live in milliseconds. Default 5 minutes. */
+    readonly ttl?: number;
+}
+declare class CacheManager {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly ttl;
+    constructor(options?: CacheOptions);
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    /** Build a stable cache key from a parameter object. */
+    generateKey(params: Readonly<Record<string, unknown>>): string;
+    /**
+     * Dynamic cache statistics. All numbers are computed at call time
+     * from the current state; nothing is hardcoded.
+     */
+    getStats(): CacheStats;
+    private isExpired;
+}
+interface CacheStats {
+    readonly size: number;
+    readonly maxSize: number;
+    readonly hitRate: number;
+    readonly entries: ReadonlyArray<{
+        readonly key: string;
+        readonly accessCount: number;
+        readonly ageMs: number;
+    }>;
+}
+declare const cacheManager: CacheManager;
+
+/**
+ * Text Generation Service
+ * @description High-level text generation orchestrator. Coordinates:
+ *              - cache lookup/store
+ *              - request building
+ *              - HTTP transport
+ *              - response parsing (text / structured / streaming)
+ *
+ *              No longer owns prompt construction (delegated to builder)
+ *              or JSON parsing (delegated to JsonResponseParser).
+ */
+
+declare class TextGenerationService implements IGroqChatService {
+    private readonly httpClient;
+    private readonly cache;
+    private readonly jsonParser;
+    constructor(httpClient: IGroqHttpClient, cache?: CacheManager);
+    generateCompletion(prompt: string, options?: TextGenerationOptions): Promise<string>;
+    generateChatCompletion(messages: ReadonlyArray<GroqMessage>, options?: TextGenerationOptions): Promise<string>;
+    generateStructured<T>(prompt: string, options?: StructuredGenerationOptions): Promise<T>;
+    streamCompletion(prompt: string, callbacks: StreamingCallbacks, options?: TextGenerationOptions): Promise<string>;
+    /**
+     * Stream a chat completion given an existing message history.
+     * Resolves with the accumulated full text once the stream completes.
+     *
+     * @param messages - The full conversation history.
+     * @param callbacks - Streaming callbacks (`onChunk`, `onComplete`, `onError`).
+     * @param options - Generation options.
+     * @returns The full accumulated text.
+     */
+    streamChatCompletion(messages: ReadonlyArray<GroqMessage>, callbacks: StreamingCallbacks, options?: TextGenerationOptions): Promise<string>;
+    /**
+     * Clear the response cache (used by long-running services to free memory).
+     */
+    clearCache(): void;
+    private executeWithCache;
+    private extractContent;
+}
+
+export { CacheManager as C, type GroqConfig as G, type IGroqChatService as I, type StreamingCallbacks as S, TextGenerationService as T, type CacheOptions as a, type CacheStats as b, type GroqChatChunk as c, type GroqChatRequest as d, type GroqChatResponse as e, type GroqChoice as f, type GroqChunkChoice as g, type GroqErrorResponse as h, type GroqFinishReason as i, type GroqGenerationConfig as j, type GroqMessage as k, type GroqMessageRole as l, type GroqUsage as m, type IGroqHttpClient as n, type StructuredGenerationOptions as o, type TextGenerationOptions as p, cacheManager as q };

package/dist/text-generation.service-BP4Q_SH0.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Groq Domain Entities
+ * @description Core type definitions for the Groq AI provider.
+ *              Readonly everywhere: consumers must not mutate in-flight.
+ */
+interface GroqConfig {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+    readonly timeoutMs?: number;
+    readonly textModel?: string;
+}
+interface GroqGenerationConfig {
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly topP?: number;
+    readonly n?: number;
+    readonly stop?: string[];
+    readonly frequencyPenalty?: number;
+    readonly presencePenalty?: number;
+}
+type GroqMessageRole = "system" | "user" | "assistant";
+interface GroqMessage {
+    readonly role: GroqMessageRole;
+    readonly content: string;
+}
+interface GroqChatRequest {
+    readonly model: string;
+    readonly messages: GroqMessage[];
+    readonly temperature?: number;
+    readonly max_tokens?: number;
+    readonly top_p?: number;
+    readonly n?: number;
+    readonly stop?: string[];
+    readonly frequency_penalty?: number;
+    readonly presence_penalty?: number;
+    readonly stream?: boolean;
+}
+type GroqFinishReason = "stop" | "length" | "content_filter";
+interface GroqChoice {
+    readonly index: number;
+    readonly message: {
+        readonly role: "assistant";
+        readonly content: string;
+    };
+    readonly finish_reason: GroqFinishReason;
+    readonly logprobs: null | object;
+}
+interface GroqUsage {
+    readonly prompt_tokens: number;
+    readonly completion_tokens: number;
+    readonly total_tokens: number;
+    readonly prompt_time?: number;
+    readonly completion_time?: number;
+    readonly total_time?: number;
+}
+interface GroqChatResponse {
+    readonly id: string;
+    readonly object: string;
+    readonly created: number;
+    readonly model: string;
+    readonly choices: GroqChoice[];
+    readonly usage: GroqUsage;
+    readonly system_fingerprint?: string;
+    readonly x_groq?: {
+        readonly id?: string;
+    };
+}
+interface GroqChunkChoice {
+    readonly index: number;
+    readonly delta: {
+        readonly role?: "assistant";
+        readonly content?: string;
+    };
+    readonly finish_reason: GroqFinishReason | null;
+    readonly logprobs: null | object;
+}
+interface GroqChatChunk {
+    readonly id: string;
+    readonly object: string;
+    readonly created: number;
+    readonly model: string;
+    readonly choices: GroqChunkChoice[];
+    readonly system_fingerprint?: string;
+    readonly x_groq?: {
+        readonly id?: string;
+    };
+}
+interface GroqErrorResponse {
+    readonly error: {
+        readonly message: string;
+        readonly type: string;
+        readonly code?: string;
+    };
+}
+
+/**
+ * Groq Service Interfaces
+ * @description Contracts for Groq AI services
+ */
+
+/**
+ * Options for a single text or chat generation call.
+ */
+interface TextGenerationOptions {
+    /** Override the default model for this call. */
+    readonly model?: string;
+    /** Sampling/limits configuration. */
+    readonly generationConfig?: GroqGenerationConfig;
+}
+/**
+ * Callbacks for streaming responses.
+ * - `onChunk` is called for each content fragment.
+ * - `onComplete` is called once the full text is available.
+ * - `onError` is called when the stream fails (the same error is also thrown).
+ */
+interface StreamingCallbacks {
+    readonly onChunk?: (chunk: string) => void;
+    readonly onComplete?: (fullText: string) => void;
+    readonly onError?: (error: Error) => void;
+}
+/**
+ * Options for structured (JSON) generation.
+ * Pass a JSON Schema in `schema` to constrain the model's output.
+ */
+interface StructuredGenerationOptions {
+    readonly model?: string;
+    readonly generationConfig?: GroqGenerationConfig;
+    readonly schema?: Record<string, unknown>;
+}
+/**
+ * Contract for the high-level chat service.
+ */
+interface IGroqChatService {
+    /** Generate a completion from a single prompt string. */
+    generateCompletion(prompt: string, options?: TextGenerationOptions): Promise<string>;
+    /** Generate a completion from a message history. */
+    generateChatCompletion(messages: ReadonlyArray<GroqMessage>, options?: TextGenerationOptions): Promise<string>;
+    /** Generate and parse a JSON output matching the optional schema. */
+    generateStructured<T>(prompt: string, options?: StructuredGenerationOptions): Promise<T>;
+    /** Stream a completion from a single prompt. Returns the full text. */
+    streamCompletion(prompt: string, callbacks: StreamingCallbacks, options?: TextGenerationOptions): Promise<string>;
+    /** Stream a chat completion from a message history. Returns full text. */
+    streamChatCompletion(messages: ReadonlyArray<GroqMessage>, callbacks: StreamingCallbacks, options?: TextGenerationOptions): Promise<string>;
+    /** Clear the in-memory response cache. */
+    clearCache(): void;
+}
+/**
+ * Contract for the low-level HTTP client.
+ * The strategy pipeline (retry / queue / dedupe) is wired around
+ * `postChatCompletion`; the streaming endpoint intentionally bypasses it
+ * because responses cannot be deduplicated.
+ */
+interface IGroqHttpClient {
+    postChatCompletion(request: GroqChatRequest): Promise<GroqChatResponse>;
+    streamChatCompletion(request: GroqChatRequest): Promise<ReadableStream<Uint8Array>>;
+    getApiKey(): string;
+    setApiKey(apiKey: string): void;
+    initialize(config: Readonly<{
+        apiKey: string;
+        baseUrl?: string;
+        timeoutMs?: number;
+        textModel?: string;
+    }>): void;
+    isInitialized(): boolean;
+    cancelPendingRequests(): void;
+    reset(): void;
+}
+
+/**
+ * Cache Manager
+ * @description LRU cache for API responses with TTL. Delegates:
+ *              - LRU key selection → calculations/lru-key-selector
+ *              - Cache key construction → builders/cache-key-builder
+ *              - Hit rate calculation → calculations/cache-hit-rate
+ */
+interface CacheOptions {
+    /** Maximum number of entries. Default 100. */
+    readonly maxSize?: number;
+    /** Time-to-live in milliseconds. Default 5 minutes. */
+    readonly ttl?: number;
+}
+declare class CacheManager {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly ttl;
+    constructor(options?: CacheOptions);
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    /** Build a stable cache key from a parameter object. */
+    generateKey(params: Readonly<Record<string, unknown>>): string;
+    /**
+     * Dynamic cache statistics. All numbers are computed at call time
+     * from the current state; nothing is hardcoded.
+     */
+    getStats(): CacheStats;
+    private isExpired;
+}
+interface CacheStats {
+    readonly size: number;
+    readonly maxSize: number;
+    readonly hitRate: number;
+    readonly entries: ReadonlyArray<{
+        readonly key: string;
+        readonly accessCount: number;
+        readonly ageMs: number;
+    }>;
+}
+declare const cacheManager: CacheManager;
+
+/**
+ * Text Generation Service
+ * @description High-level text generation orchestrator. Coordinates:
+ *              - cache lookup/store
+ *              - request building
+ *              - HTTP transport
+ *              - response parsing (text / structured / streaming)
+ *
+ *              No longer owns prompt construction (delegated to builder)
+ *              or JSON parsing (delegated to JsonResponseParser).
+ */
+
+declare class TextGenerationService implements IGroqChatService {
+    private readonly httpClient;
+    private readonly cache;
+    private readonly jsonParser;
+    constructor(httpClient: IGroqHttpClient, cache?: CacheManager);
+    generateCompletion(prompt: string, options?: TextGenerationOptions): Promise<string>;
+    generateChatCompletion(messages: ReadonlyArray<GroqMessage>, options?: TextGenerationOptions): Promise<string>;
+    generateStructured<T>(prompt: string, options?: StructuredGenerationOptions): Promise<T>;
+    streamCompletion(prompt: string, callbacks: StreamingCallbacks, options?: TextGenerationOptions): Promise<string>;
+    /**
+     * Stream a chat completion given an existing message history.
+     * Resolves with the accumulated full text once the stream completes.
+     *
+     * @param messages - The full conversation history.
+     * @param callbacks - Streaming callbacks (`onChunk`, `onComplete`, `onError`).
+     * @param options - Generation options.
+     * @returns The full accumulated text.
+     */
+    streamChatCompletion(messages: ReadonlyArray<GroqMessage>, callbacks: StreamingCallbacks, options?: TextGenerationOptions): Promise<string>;
+    /**
+     * Clear the response cache (used by long-running services to free memory).
+     */
+    clearCache(): void;
+    private executeWithCache;
+    private extractContent;
+}
+
+export { CacheManager as C, type GroqConfig as G, type IGroqChatService as I, type StreamingCallbacks as S, TextGenerationService as T, type CacheOptions as a, type CacheStats as b, type GroqChatChunk as c, type GroqChatRequest as d, type GroqChatResponse as e, type GroqChoice as f, type GroqChunkChoice as g, type GroqErrorResponse as h, type GroqFinishReason as i, type GroqGenerationConfig as j, type GroqMessage as k, type GroqMessageRole as l, type GroqUsage as m, type IGroqHttpClient as n, type StructuredGenerationOptions as o, type TextGenerationOptions as p, cacheManager as q };

package/package.json

@@ -1,22 +1,36 @@
 {
   "name": "@umituz/web-ai-groq-provider",
-  "version": "1.1.13",
-  "description": "Groq AI text generation provider for React web applications",
+  "version": "2.0.0",
+  "description": "Groq AI text generation and chat provider for React web applications",
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./groq": "./src/domains/groq/index.ts",
-    "./chat": "./src/domains/chat/index.ts",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./groq": {
+      "types": "./dist/domains/groq/index.d.ts",
+      "import": "./dist/domains/groq/index.js",
+      "require": "./dist/domains/groq/index.cjs"
+    },
+    "./chat": {
+      "types": "./dist/domains/chat/index.d.ts",
+      "import": "./dist/domains/chat/index.js",
+      "require": "./dist/domains/chat/index.cjs"
+    },
     "./package.json": "./package.json"
   },
+  "sideEffects": false,
   "scripts": {
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean --external react",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch --external react",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test:scenarios": "echo 'See TEST_SCENARIOS.md for manual test scenarios'",
     "version:patch": "npm version patch -m 'chore: release v%s'",
     "version:minor": "npm version minor -m 'chore: release v%s'",
     "version:major": "npm version major -m 'chore: release v%s'"
@@ -54,7 +68,7 @@
     "access": "public"
   },
   "files": [
-    "src",
+    "dist",
     "README.md",
     "LICENSE"
   ]

package/src/domains/chat/entities/chat.entities.ts

@@ -1,113 +0,0 @@
-/**
- * Chat Domain Entities
- * @description Core chat message and conversation types
- */
-
-/**
- * Message sender type
- */
-export type ChatMessageSender = "user" | "assistant" | "system";
-
-/**
- * Message content types
- */
-export type ChatMessageType = "text" | "image" | "audio" | "sticker";
-
-/**
- * Chat message structure
- */
-export interface ChatMessage {
-  /** Unique message identifier */
-  readonly id: string;
-  /** Sender of the message */
-  readonly sender: ChatMessageSender;
-  /** Message content */
-  readonly content: string;
-  /** Timestamp in ISO format */
-  readonly timestamp: string;
-  /** Message type */
-  readonly type?: ChatMessageType;
-  /** Image URL for image messages */
-  readonly imageUrl?: string;
-  /** Reaction emoji */
-  readonly reaction?: string;
-  /** Metadata */
-  readonly metadata?: Record<string, unknown>;
-}
-
-/**
- * Conversation/session metadata
- */
-export interface ChatConversation {
-  /** Unique conversation identifier */
-  readonly id: string;
-  /** Companion/character identifier */
-  readonly companionId: string;
-  /** Companion name */
-  readonly companionName: string;
-  /** Last message */
-  readonly lastMessage?: ChatMessage;
-  /** Message count */
-  readonly messageCount: number;
-  /** Updated timestamp */
-  readonly updatedAt: string;
-  /** Is pinned */
-  readonly pinned?: boolean;
-  /** Is archived */
-  readonly archived?: boolean;
-}
-
-/**
- * Send message input
- */
-export interface SendMessageInput {
-  /** Companion identifier */
-  readonly companionId: string;
-  /** Message text */
-  readonly text: string;
-  /** Message type */
-  readonly type?: ChatMessageType;
-  /** Image URL */
-  readonly imageUrl?: string;
-}
-
-/**
- * Send message result
- */
-export interface SendMessageResult {
-  /** User message */
-  readonly userMessage: ChatMessage;
-  /** AI response (if generated) */
-  readonly aiResponse?: ChatMessage;
-}
-
-/**
- * Chat configuration
- */
-export interface ChatConfig {
-  /** System prompt for AI personality */
-  readonly systemPrompt?: string;
-  /** Temperature for randomness */
-  readonly temperature?: number;
-  /** Maximum tokens */
-  readonly maxTokens?: number;
-  /** Include timestamp in messages */
-  readonly includeTimestamp?: boolean;
-  /** Language code (e.g., 'tr', 'en') */
-  readonly language?: string;
-}
-
-/**
- * Storage interface for persisting messages
- * Implementations should be provided by the application
- */
-export interface IChatStorage {
-  /** Save message to storage */
-  saveMessage(conversationId: string, message: ChatMessage): Promise<void>;
-  /** Get messages for conversation */
-  getMessages(conversationId: string): Promise<ChatMessage[]>;
-  /** Update message */
-  updateMessage(messageId: string, updates: Partial<ChatMessage>): Promise<void>;
-  /** Delete message */
-  deleteMessage(messageId: string): Promise<void>;
-}

package/src/domains/chat/entities/index.ts

@@ -1,14 +0,0 @@
-/**
- * Chat Entities
- */
-
-export type {
-  ChatMessageSender,
-  ChatMessageType,
-  ChatMessage,
-  ChatConversation,
-  SendMessageInput,
-  SendMessageResult,
-  ChatConfig,
-  IChatStorage,
-} from "./chat.entities";

package/src/domains/chat/hooks/index.ts

@@ -1,5 +0,0 @@
-/**
- * Chat Hooks
- */
-
-export { useChat } from "./use-chat.hook";