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

package/src/domains/groq/constants/groq.constants.ts

@@ -1,68 +0,0 @@
-/**
- * Groq Constants
- * @description Available models and default configurations
- */
-
-/**
- * Available Groq models
- */
-export const GROQ_MODELS = {
-  /** Llama 3.1 8B - Fast and efficient (560 T/s) */
-  LLAMA_3_1_8B_INSTANT: "llama-3.1-8b-instant",
-  /** Llama 3.3 70B - Versatile and powerful (280 T/s) */
-  LLAMA_3_3_70B_VERSATILE: "llama-3.3-70b-versatile",
-  /** Llama 3.1 70B - Versatile (280 T/s) */
-  LLAMA_3_1_70B_VERSATILE: "llama-3.1-70b-versatile",
-  /** GPT-OSS 20B - Experimental (1000 T/s) */
-  GPT_OSS_20B: "openai/gpt-oss-20b",
-  /** GPT-OSS 120B - Large experimental model */
-  GPT_OSS_120B: "openai/gpt-oss-120b",
-  /** Mixtral 8x7b - MoE model */
-  MIXTRAL_8X7B: "mixtral-8x7b-32768",
-  /** Gemma 2 9B - Google's model */
-  GEMMA_2_9B: "gemma2-9b-it",
-  /** Llama 4 Scout 17B - New model (30K T/s) */
-  LLAMA_4_SCOUT_17B: "meta-llama/llama-4-scout-17b-16e-instruct",
-  /** Kimi K2 - Moonshot AI model */
-  KIMI_K2_INSTRUCT: "moonshotai/kimi-k2-instruct",
-  /** Qwen 3 32B - Alibaba's model */
-  QWEN3_32B: "qwen/qwen3-32b",
-} as const;
-
-/**
- * Default models for different use cases
- */
-export const DEFAULT_MODELS = {
-  TEXT: GROQ_MODELS.LLAMA_3_1_8B_INSTANT,
-  FAST: GROQ_MODELS.LLAMA_3_1_8B_INSTANT,
-  EXPERIMENTAL: GROQ_MODELS.GPT_OSS_20B,
-} as const;
-
-/**
- * Default generation configuration
- */
-export const DEFAULT_GENERATION_CONFIG = {
-  temperature: 0.7,
-  maxTokens: 1024,
-  topP: 1.0,
-} as const;
-
-/**
- * API endpoints
- */
-export const API_ENDPOINTS = {
-  CHAT: "/chat/completions",
-} as const;
-
-/**
- * Default base URL
- */
-export const DEFAULT_BASE_URL = "https://api.groq.com/openai/v1" as const;
-
-/**
- * Default timeouts
- */
-export const TIMEOUTS = {
-  DEFAULT: 30000, // 30 seconds
-  STREAMING: 60000, // 60 seconds
-} as const;

package/src/domains/groq/constants/index.ts

@@ -1,20 +0,0 @@
-/**
- * Infrastructure Constants Index
- * Subpath: @umituz/web-ai-groq-provider/services
- */
-
-export {
-  GROQ_MODELS,
-  DEFAULT_MODELS,
-  DEFAULT_GENERATION_CONFIG,
-  API_ENDPOINTS,
-  DEFAULT_BASE_URL,
-  TIMEOUTS,
-} from "./groq.constants";
-
-export {
-  GroqErrorType,
-  mapHttpStatusToErrorType,
-  isRetryableError,
-  isAuthError,
-} from "./error.constants";

package/src/domains/groq/entities/groq.entities.ts

@@ -1,196 +0,0 @@
-/**
- * Groq Domain Entities
- * @description Core type definitions for Groq AI provider
- */
-
-/**
- * Configuration for Groq client initialization
- */
-export interface GroqConfig {
-  /** API key for authentication */
-  readonly apiKey: string;
-  /** Base URL for API requests (default: https://api.groq.com/openai/v1) */
-  readonly baseUrl?: string;
-  /** Default timeout in milliseconds */
-  readonly timeoutMs?: number;
-  /** Default model to use for text generation */
-  readonly textModel?: string;
-}
-
-/**
- * Generation configuration for AI requests
- */
-export interface GroqGenerationConfig {
-  /** Controls randomness (0.0 - 2.0, default: 0.7) */
-  readonly temperature?: number;
-  /** Maximum number of tokens to generate */
-  readonly maxTokens?: number;
-  /** Nucleus sampling threshold (0.0 - 1.0) */
-  readonly topP?: number;
-  /** Number of completions to generate */
-  readonly n?: number;
-  /** Stop sequences */
-  readonly stop?: string[];
-  /** Frequency penalty (-2.0 to 2.0) */
-  readonly frequencyPenalty?: number;
-  /** Presence penalty (-2.0 to 2.0) */
-  readonly presencePenalty?: number;
-}
-
-/**
- * Message role in chat conversation
- */
-export type GroqMessageRole = "system" | "user" | "assistant";
-
-/**
- * Chat message structure
- */
-export interface GroqMessage {
-  /** Role of the message sender */
-  readonly role: GroqMessageRole;
-  /** Content of the message */
-  readonly content: string;
-}
-
-/**
- * Chat completion request
- */
-export interface GroqChatRequest {
-  /** Model to use for generation */
-  readonly model: string;
-  /** Array of messages in the conversation */
-  readonly messages: GroqMessage[];
-  /** Generation configuration */
-  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;
-  /** Enable streaming response */
-  readonly stream?: boolean;
-}
-
-/**
- * Individual completion choice
- */
-export interface GroqChoice {
-  /** Index of the choice */
-  readonly index: number;
-  /** Generated message */
-  readonly message: {
-    readonly role: "assistant";
-    readonly content: string;
-  };
-  /** Reason for finish (stop, length, etc.) */
-  readonly finish_reason: GroqFinishReason;
-  /** Logprobs (optional) */
-  readonly logprobs: null | object;
-}
-
-/**
- * Finish reason types
- */
-export type GroqFinishReason = "stop" | "length" | "content_filter";
-
-/**
- * Token usage information
- */
-export interface GroqUsage {
-  /** Number of tokens in the prompt */
-  readonly prompt_tokens: number;
-  /** Number of tokens in the completion */
-  readonly completion_tokens: number;
-  /** Total number of tokens used */
-  readonly total_tokens: number;
-  /** Prompt time (Groq specific) */
-  readonly prompt_time?: number;
-  /** Completion time (Groq specific) */
-  readonly completion_time?: number;
-  /** Total time (Groq specific) */
-  readonly total_time?: number;
-}
-
-/**
- * Chat completion response
- */
-export interface GroqChatResponse {
-  /** Unique identifier for the response */
-  readonly id: string;
-  /** Object type (chat.completion) */
-  readonly object: string;
-  /** Timestamp of creation */
-  readonly created: number;
-  /** Model used for generation */
-  readonly model: string;
-  /** Array of completion choices */
-  readonly choices: GroqChoice[];
-  /** Token usage information */
-  readonly usage: GroqUsage;
-  /** System fingerprint (Groq specific) */
-  readonly system_fingerprint?: string;
-  /** X Groq (Groq specific) */
-  readonly x_groq?: {
-    readonly id?: string;
-  };
-}
-
-/**
- * Individual chunk choice for streaming
- */
-export interface GroqChunkChoice {
-  /** Index of the choice */
-  readonly index: number;
-  /** Delta message (partial content) */
-  readonly delta: {
-    readonly role?: "assistant";
-    readonly content?: string;
-  };
-  /** Reason for finish (null if not finished) */
-  readonly finish_reason: GroqFinishReason | null;
-  /** Logprobs (optional) */
-  readonly logprobs: null | object;
-}
-
-/**
- * Streaming chunk response
- */
-export interface GroqChatChunk {
-  /** Unique identifier for the response */
-  readonly id: string;
-  /** Object type (chat.completion.chunk) */
-  readonly object: string;
-  /** Timestamp of creation */
-  readonly created: number;
-  /** Model used for generation */
-  readonly model: string;
-  /** Array of completion choices */
-  readonly choices: GroqChunkChoice[];
-  /** System fingerprint (Groq specific) */
-  readonly system_fingerprint?: string;
-  /** X Groq (Groq specific) */
-  readonly x_groq?: {
-    readonly id?: string;
-  };
-}
-
-/**
- * API error response
- */
-export interface GroqErrorResponse {
-  /** Error type */
-  readonly error: {
-    /** Error message */
-    readonly message: string;
-    /** Error type */
-    readonly type: string;
-    /** Error code */
-    readonly code?: string;
-  };
-}
-
-/**
- * Input types for mutations
- */
-export type GroqMessageCreateInput = Omit<GroqMessage, 'content'> & { content: string };

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

@@ -1,20 +0,0 @@
-/**
- * Domain Entities Index
- * Subpath: @umituz/web-ai-groq-provider/domain
- */
-
-export type {
-  GroqConfig,
-  GroqGenerationConfig,
-  GroqMessageRole,
-  GroqMessage,
-  GroqChatRequest,
-  GroqChoice,
-  GroqFinishReason,
-  GroqUsage,
-  GroqChatResponse,
-  GroqChunkChoice,
-  GroqChatChunk,
-  GroqErrorResponse,
-  GroqMessageCreateInput,
-} from "./groq.entities";

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

@@ -1,7 +0,0 @@
-/**
- * Presentation Hooks Index
- * Subpath: @umituz/web-ai-groq-provider/hooks
- */
-
-export { useGroq } from "./use-groq.hook";
-export type { UseGroqOptions, UseGroqReturn } from "./use-groq.hook";

package/src/domains/groq/hooks/use-groq.hook.ts

@@ -1,232 +0,0 @@
-/**
- * useGroq Hook
- * @description Main React hook for Groq text generation with performance optimizations
- */
-
-import { useState, useCallback, useMemo, useRef, useEffect } from "react";
-import type { GroqGenerationConfig } from "../interfaces";
-import type { StreamingCallbacks } from "../interfaces";
-import { textGenerationService } from "../services";
-import { getUserFriendlyError } from "../utils/error.util";
-import { groqHttpClient } from "../services/http-client.service";
-
-export interface UseGroqOptions {
-  /** Initial model to use */
-  readonly model?: string;
-  /** Default generation config */
-  readonly generationConfig?: GroqGenerationConfig;
-  /** Callback when generation starts */
-  readonly onStart?: () => void;
-  /** Callback when generation completes */
-  readonly onSuccess?: (result: string) => void;
-  /** Callback when generation fails */
-  readonly onError?: (error: string) => void;
-}
-
-export interface UseGroqReturn {
-  /** Loading state */
-  readonly isLoading: boolean;
-  /** Error message */
-  readonly error: string | null;
-  /** Generated result */
-  readonly result: string | null;
-  /** Generate text from a prompt */
-  generate: (prompt: string, options?: GroqGenerationConfig) => Promise<string>;
-  /** Generate structured JSON output */
-  generateJSON: <T = Record<string, unknown>>(
-    prompt: string,
-    options?: GroqGenerationConfig & { schema?: Record<string, unknown> }
-  ) => Promise<T>;
-  /** Stream text generation */
-  stream: (
-    prompt: string,
-    onChunk: (chunk: string) => void,
-    options?: GroqGenerationConfig
-  ) => Promise<void>;
-  /** Reset state */
-  reset: () => void;
-  /** Clear error */
-  clearError: () => void;
-}
-
-/**
- * Hook for Groq text generation with performance optimizations
- */
-export function useGroq(options: UseGroqOptions = {}): UseGroqReturn {
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [result, setResult] = useState<string | null>(null);
-
-  // Use ref for callbacks to avoid stale closures and unstable references
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-
-  // Memoize only the stable configuration values (not callbacks)
-  const stableConfig = useMemo(
-    () => ({
-      model: options.model,
-      generationConfig: options.generationConfig,
-    }),
-    [options.model, options.generationConfig?.temperature, options.generationConfig?.maxTokens, options.generationConfig?.topP]
-  );
-
-  // Cleanup pending requests on unmount
-  useEffect(() => {
-    return () => {
-      groqHttpClient.cancelPendingRequests();
-    };
-  }, []);
-
-  const generate = useCallback(
-    async (prompt: string, config?: GroqGenerationConfig): Promise<string> => {
-      setIsLoading(true);
-      setError(null);
-      setResult(null);
-
-      // Use ref to get latest callbacks without adding to dependencies
-      const currentOptions = optionsRef.current;
-      currentOptions.onStart?.();
-
-      try {
-        const response = await textGenerationService.generateCompletion(prompt, {
-          model: stableConfig.model,
-          generationConfig: {
-            ...stableConfig.generationConfig,
-            ...config,
-          },
-        });
-
-        setResult(response);
-        currentOptions.onSuccess?.(response);
-
-        return response;
-      } catch (err) {
-        const errorMessage = getUserFriendlyError(
-          err instanceof Error ? err : new Error("Unknown error")
-        );
-        setError(errorMessage);
-        currentOptions.onError?.(errorMessage);
-
-        throw err;
-      } finally {
-        setIsLoading(false);
-      }
-    },
-    [stableConfig]
-  );
-
-  const generateJSON = useCallback(
-    async <T = Record<string, unknown>,>(
-      prompt: string,
-      config?: GroqGenerationConfig & { schema?: Record<string, unknown> }
-    ): Promise<T> => {
-      setIsLoading(true);
-      setError(null);
-      setResult(null);
-
-      const currentOptions = optionsRef.current;
-      currentOptions.onStart?.();
-
-      try {
-        const response = await textGenerationService.generateStructured<T>(prompt, {
-          model: stableConfig.model,
-          generationConfig: {
-            ...stableConfig.generationConfig,
-            ...config,
-          },
-          schema: config?.schema,
-        });
-
-        const jsonString = JSON.stringify(response, null, 2);
-        setResult(jsonString);
-        currentOptions.onSuccess?.(jsonString);
-
-        return response;
-      } catch (err) {
-        const errorMessage = getUserFriendlyError(
-          err instanceof Error ? err : new Error("Unknown error")
-        );
-        setError(errorMessage);
-        currentOptions.onError?.(errorMessage);
-
-        throw err;
-      } finally {
-        setIsLoading(false);
-      }
-    },
-    [stableConfig]
-  );
-
-  const stream = useCallback(
-    async (
-      prompt: string,
-      onChunk: (chunk: string) => void,
-      config?: GroqGenerationConfig
-    ): Promise<void> => {
-      setIsLoading(true);
-      setError(null);
-      setResult(null);
-
-      const contentChunks: string[] = [];
-      const currentOptions = optionsRef.current;
-      currentOptions.onStart?.();
-
-      try {
-        const callbacks: StreamingCallbacks = {
-          onChunk: (c) => {
-            contentChunks.push(c); // Use array accumulation
-            onChunk(c);
-          },
-          onComplete: (text) => {
-            setResult(text);
-            currentOptions.onSuccess?.(text);
-          },
-        };
-
-        await textGenerationService.streamCompletion(
-          prompt,
-          callbacks,
-          {
-            model: stableConfig.model,
-            generationConfig: {
-              ...stableConfig.generationConfig,
-              ...config,
-            },
-          }
-        );
-      } catch (err) {
-        const errorMessage = getUserFriendlyError(
-          err instanceof Error ? err : new Error("Unknown error")
-        );
-        setError(errorMessage);
-        currentOptions.onError?.(errorMessage);
-
-        throw err;
-      } finally {
-        setIsLoading(false);
-      }
-    },
-    [stableConfig]
-  );
-
-  const reset = useCallback(() => {
-    setIsLoading(false);
-    setError(null);
-    setResult(null);
-  }, []);
-
-  const clearError = useCallback(() => {
-    setError(null);
-  }, []);
-
-  return {
-    isLoading,
-    error,
-    result,
-    generate,
-    generateJSON,
-    stream,
-    reset,
-    clearError,
-  };
-}

package/src/domains/groq/index.ts

@@ -1,72 +0,0 @@
-/**
- * Groq Domain
- * @description Groq API client and text generation
- * Subpath: @umituz/web-ai-groq-provider/groq
- */
-
-// Entities
-export type {
-  GroqMessageRole,
-  GroqMessage,
-  GroqChatRequest,
-  GroqChoice,
-  GroqFinishReason,
-  GroqUsage,
-  GroqChatResponse,
-  GroqChunkChoice,
-  GroqChatChunk,
-  GroqErrorResponse,
-} from "./entities";
-
-export type {
-  GroqConfig,
-  GroqGenerationConfig,
-} from "./entities";
-
-// Interfaces
-export type {
-  TextGenerationOptions,
-  StreamingCallbacks,
-  StructuredGenerationOptions,
-} from "./interfaces";
-
-export type { IGroqChatService, IGroqHttpClient } from "./interfaces";
-
-// Services
-export { textGenerationService, groqHttpClient } from "./services";
-
-// Hooks
-export { useGroq } from "./hooks";
-export type { UseGroqOptions, UseGroqReturn } from "./hooks";
-
-// Constants
-export {
-  GROQ_MODELS,
-  DEFAULT_MODELS,
-  DEFAULT_GENERATION_CONFIG,
-  API_ENDPOINTS,
-  DEFAULT_BASE_URL,
-  TIMEOUTS,
-} from "./constants";
-
-export {
-  GroqErrorType,
-  mapHttpStatusToErrorType,
-  isRetryableError,
-  isAuthError,
-} from "./constants";
-
-// Utils
-export {
-  createUserMessage,
-  createAssistantMessage,
-  createSystemMessage,
-  createTextMessage,
-  promptToMessages,
-  extractTextFromMessages,
-  formatMessagesForDisplay,
-} from "./utils";
-
-export { getUserFriendlyError, formatErrorForLogging } from "./utils";
-
-export { GroqError } from "./utils";

package/src/domains/groq/interfaces/groq.interface.ts

@@ -1,77 +0,0 @@
-/**
- * Groq Service Interfaces
- * @description Contracts for Groq AI services
- */
-
-import type {
-  GroqMessage,
-  GroqChatResponse,
-  GroqChatRequest,
-  GroqGenerationConfig,
-} from "../entities";
-
-/**
- * Text generation options
- */
-export interface TextGenerationOptions {
-  /** Model to use */
-  readonly model?: string;
-  /** Generation configuration */
-  readonly generationConfig?: GroqGenerationConfig;
-}
-
-/**
- * Streaming callbacks
- */
-export interface StreamingCallbacks {
-  /** Called for each chunk */
-  readonly onChunk?: (chunk: string) => void;
-  /** Called on completion */
-  readonly onComplete?: (fullText: string) => void;
-  /** Called on error */
-  readonly onError?: (error: Error) => void;
-}
-
-/**
- * Structured text generation options
- */
-export interface StructuredGenerationOptions {
-  /** Model to use */
-  readonly model?: string;
-  /** Generation configuration */
-  readonly generationConfig?: GroqGenerationConfig;
-  /** JSON schema for validation */
-  readonly schema?: Record<string, unknown>;
-}
-
-/**
- * Chat completion service interface
- */
-export interface IGroqChatService {
-  /** Generate completion from prompt */
-  generateCompletion(prompt: string, options?: TextGenerationOptions): Promise<string>;
-  /** Generate completion from messages */
-  generateChatCompletion(messages: GroqMessage[], options?: TextGenerationOptions): Promise<string>;
-  /** Generate structured JSON output */
-  generateStructured<T>(prompt: string, options?: StructuredGenerationOptions): Promise<T>;
-  /** Stream completion */
-  streamCompletion(
-    prompt: string,
-    callbacks: StreamingCallbacks,
-    options?: TextGenerationOptions
-  ): Promise<void>;
-}
-
-/**
- * HTTP client interface
- */
-export interface IGroqHttpClient {
-  /** Send chat completion request */
-  postChatCompletion(request: GroqChatRequest): Promise<GroqChatResponse>;
-  /** Send streaming request */
-  streamChatCompletion(request: GroqChatRequest): Promise<ReadableStream>;
-  /** Get API key */
-  getApiKey(): string;
-  /** Set API key */
-  setApiKey(apiKey: string): void;
-}