@umituz/web-ai-groq-provider 1.0.1

package/src/text-generation.ts

@@ -0,0 +1,165 @@
+/**
+ * Text Generation Service
+ * Handles basic text generation using Groq API
+ */
+
+import type {
+  GroqChatRequest,
+  GroqMessage,
+  GroqGenerationConfig,
+} from "./types";
+import { groqHttpClient } from "./client";
+import { DEFAULT_MODELS } from "./types";
+import { GroqError, GroqErrorType } from "./types";
+
+const isDevelopment = process.env.NODE_ENV === "development";
+
+export interface TextGenerationOptions {
+  model?: string;
+  generationConfig?: GroqGenerationConfig;
+}
+
+/**
+ * Generate text from a simple prompt
+ */
+export async function textGeneration(
+  prompt: string,
+  options: TextGenerationOptions = {}
+): Promise<string> {
+  const startTime = Date.now();
+  const model = options.model || DEFAULT_MODELS.TEXT;
+
+  if (isDevelopment) {
+    console.log("[Groq] textGeneration called:", {
+      model,
+      promptLength: prompt.length,
+      promptPreview: prompt.substring(0, 100) + "...",
+      options: options.generationConfig,
+    });
+  }
+
+  const messages: GroqMessage[] = [
+    {
+      role: "user",
+      content: prompt,
+    },
+  ];
+
+  const request: GroqChatRequest = {
+    model,
+    messages,
+    temperature: options.generationConfig?.temperature || 0.7,
+    max_tokens: options.generationConfig?.maxTokens || 1024,
+    top_p: options.generationConfig?.topP,
+    n: options.generationConfig?.n,
+    stop: options.generationConfig?.stop,
+    frequency_penalty: options.generationConfig?.frequencyPenalty,
+    presence_penalty: options.generationConfig?.presencePenalty,
+  };
+
+  if (isDevelopment) {
+    console.log("[Groq] Sending request to API:", {
+      endpoint: "/v1/chat/completions",
+      requestBody: {
+        model: request.model,
+        messageCount: request.messages.length,
+        temperature: request.temperature,
+        max_tokens: request.max_tokens,
+      },
+    });
+  }
+
+  const apiStartTime = Date.now();
+  const response = await groqHttpClient.chatCompletion(request);
+  const apiDuration = Date.now() - apiStartTime;
+
+  if (isDevelopment) {
+    console.log("[Groq] API response received:", {
+      apiDuration: `${apiDuration}ms`,
+      hasChoices: !!response.choices?.length,
+      choiceCount: response.choices?.length || 0,
+      usage: response.usage,
+      finishReason: response.choices?.[0]?.finish_reason,
+    });
+  }
+
+  const content = response.choices[0]?.message?.content;
+  if (!content) {
+    throw new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      "No content generated from Groq API"
+    );
+  }
+
+  const totalDuration = Date.now() - startTime;
+  if (isDevelopment) {
+    console.log("[Groq] textGeneration complete:", {
+      totalDuration: `${totalDuration}ms`,
+      responseLength: content.length,
+      responsePreview: content.substring(0, 200) + "...",
+    });
+  }
+
+  return content;
+}
+
+/**
+ * Generate text from an array of messages
+ */
+export async function chatGeneration(
+  messages: GroqMessage[],
+  options: TextGenerationOptions = {}
+): Promise<string> {
+  const startTime = Date.now();
+  const model = options.model || DEFAULT_MODELS.TEXT;
+
+  if (isDevelopment) {
+    console.log("[Groq] chatGeneration called:", {
+      model,
+      messageCount: messages.length,
+      options: options.generationConfig,
+    });
+  }
+
+  const request: GroqChatRequest = {
+    model,
+    messages,
+    temperature: options.generationConfig?.temperature || 0.7,
+    max_tokens: options.generationConfig?.maxTokens || 1024,
+    top_p: options.generationConfig?.topP,
+    n: options.generationConfig?.n,
+    stop: options.generationConfig?.stop,
+    frequency_penalty: options.generationConfig?.frequencyPenalty,
+    presence_penalty: options.generationConfig?.presencePenalty,
+  };
+
+  const apiStartTime = Date.now();
+  const response = await groqHttpClient.chatCompletion(request);
+  const apiDuration = Date.now() - apiStartTime;
+
+  if (isDevelopment) {
+    console.log("[Groq] chatGeneration API response:", {
+      apiDuration: `${apiDuration}ms`,
+      usage: response.usage,
+      finishReason: response.choices?.[0]?.finish_reason,
+    });
+  }
+
+  const content = response.choices[0]?.message?.content;
+  if (!content) {
+    throw new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      "No content generated from Groq API"
+    );
+  }
+
+  const totalDuration = Date.now() - startTime;
+  if (isDevelopment) {
+    console.log("[Groq] chatGeneration complete:", {
+      totalDuration: `${totalDuration}ms`,
+      responseLength: content.length,
+    });
+  }
+
+  return content;
+}

package/src/types.ts

@@ -0,0 +1,264 @@
+/**
+ * Groq API Types
+ */
+
+/**
+ * Configuration for Groq client initialization
+ */
+export interface GroqConfig {
+  /** API key for authentication */
+  apiKey: string;
+  /** Base URL for API requests (default: https://api.groq.com/openai/v1) */
+  baseUrl?: string;
+  /** Default timeout in milliseconds */
+  timeoutMs?: number;
+  /** Default model to use for text generation */
+  textModel?: string;
+}
+
+/**
+ * Generation configuration for AI requests
+ */
+export interface GroqGenerationConfig {
+  /** Controls randomness (0.0 - 2.0, default: 0.7) */
+  temperature?: number;
+  /** Maximum number of tokens to generate */
+  maxTokens?: number;
+  /** Nucleus sampling threshold (0.0 - 1.0) */
+  topP?: number;
+  /** Number of completions to generate */
+  n?: number;
+  /** Stop sequences */
+  stop?: string[];
+  /** Frequency penalty (-2.0 to 2.0) */
+  frequencyPenalty?: number;
+  /** Presence penalty (-2.0 to 2.0) */
+  presencePenalty?: number;
+}
+
+/**
+ * Message role in chat conversation
+ */
+export type GroqMessageRole = "system" | "user" | "assistant";
+
+/**
+ * Chat message structure
+ */
+export interface GroqMessage {
+  /** Role of the message sender */
+  role: GroqMessageRole;
+  /** Content of the message */
+  content: string;
+}
+
+/**
+ * Chat completion request
+ */
+export interface GroqChatRequest {
+  /** Model to use for generation */
+  model: string;
+  /** Array of messages in the conversation */
+  messages: GroqMessage[];
+  /** Generation configuration */
+  temperature?: number;
+  max_tokens?: number;
+  top_p?: number;
+  n?: number;
+  stop?: string[];
+  frequency_penalty?: number;
+  presence_penalty?: number;
+  /** Enable streaming response */
+  stream?: boolean;
+}
+
+/**
+ * Chat completion response
+ */
+export interface GroqChatResponse {
+  /** Unique identifier for the response */
+  id: string;
+  /** Object type (chat.completion) */
+  object: string;
+  /** Timestamp of creation */
+  created: number;
+  /** Model used for generation */
+  model: string;
+  /** Array of completion choices */
+  choices: GroqChoice[];
+  /** Token usage information */
+  usage: GroqUsage;
+  /** System fingerprint (Groq specific) */
+  system_fingerprint?: string;
+  /** X Groq (Groq specific) */
+  x_groq?: {
+    id?: string;
+  };
+}
+
+/**
+ * Individual completion choice
+ */
+export interface GroqChoice {
+  /** Index of the choice */
+  index: number;
+  /** Generated message */
+  message: {
+    role: "assistant";
+    content: string;
+  };
+  /** Reason for finish (stop, length, etc.) */
+  finish_reason: GroqFinishReason;
+  /** Logprobs (optional) */
+  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 */
+  prompt_tokens: number;
+  /** Number of tokens in the completion */
+  completion_tokens: number;
+  /** Total number of tokens used */
+  total_tokens: number;
+  /** Prompt time (Groq specific) */
+  prompt_time?: number;
+  /** Completion time (Groq specific) */
+  completion_time?: number;
+  /** Total time (Groq specific) */
+  total_time?: number;
+}
+
+/**
+ * Streaming chunk response
+ */
+export interface GroqChatChunk {
+  /** Unique identifier for the response */
+  id: string;
+  /** Object type (chat.completion.chunk) */
+  object: string;
+  /** Timestamp of creation */
+  created: number;
+  /** Model used for generation */
+  model: string;
+  /** Array of completion choices */
+  choices: GroqChunkChoice[];
+  /** System fingerprint (Groq specific) */
+  system_fingerprint?: string;
+  /** X Groq (Groq specific) */
+  x_groq?: {
+    id?: string;
+  };
+}
+
+/**
+ * Individual chunk choice for streaming
+ */
+export interface GroqChunkChoice {
+  /** Index of the choice */
+  index: number;
+  /** Delta message (partial content) */
+  delta: {
+    role?: "assistant";
+    content?: string;
+  };
+  /** Reason for finish (null if not finished) */
+  finish_reason: GroqFinishReason | null;
+  /** Logprobs (optional) */
+  logprobs: null | object;
+}
+
+/**
+ * API error response
+ */
+export interface GroqErrorResponse {
+  /** Error type */
+  error: {
+    /** Error message */
+    message: string;
+    /** Error type */
+    type: string;
+    /** Error code */
+    code?: string;
+  };
+}
+
+/**
+ * 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;
+
+/**
+ * Error types
+ */
+export 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",
+  UNKNOWN_ERROR = "UNKNOWN_ERROR",
+}
+
+/**
+ * Custom error class for Groq API errors
+ */
+export class GroqError extends Error {
+  constructor(
+    public type: GroqErrorType,
+    message: string,
+    public cause?: Error,
+    public metadata?: { status?: number; url?: string }
+  ) {
+    super(message);
+    this.name = "GroqError";
+  }
+}
+
+/**
+ * Map HTTP status to error type
+ */
+export function mapHttpStatusToErrorType(status: number): GroqErrorType {
+  if (status === 401 || status === 403) return GroqErrorType.INVALID_API_KEY;
+  if (status === 429) return GroqErrorType.RATE_LIMIT_ERROR;
+  if (status >= 500) return GroqErrorType.SERVER_ERROR;
+  if (status >= 400) return GroqErrorType.INVALID_API_KEY;
+  return GroqErrorType.UNKNOWN_ERROR;
+}

package/src/utils.ts

@@ -0,0 +1,140 @@
+/**
+ * Utility functions for error handling and content mapping
+ */
+
+import { GroqError, GroqErrorType } from "./types";
+import type { GroqMessage } from "./types";
+
+/**
+ * Get user-friendly error message
+ */
+export function getUserFriendlyError(error: unknown): string {
+  if (error instanceof GroqError) {
+    switch (error.type) {
+      case GroqErrorType.INVALID_API_KEY:
+        return "Invalid API key. Please check your Groq API key.";
+      case GroqErrorType.MISSING_CONFIG:
+        return "Groq provider not initialized. Please call configureProvider() first.";
+      case GroqErrorType.NETWORK_ERROR:
+        return "Network error. Please check your internet connection.";
+      case GroqErrorType.ABORT_ERROR:
+        return "Request was cancelled.";
+      case GroqErrorType.RATE_LIMIT_ERROR:
+        return "Rate limit exceeded. Please try again later.";
+      case GroqErrorType.SERVER_ERROR:
+        return "Groq API server error. Please try again later.";
+      default:
+        return error.message || "An unknown error occurred.";
+    }
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return "An unknown error occurred.";
+}
+
+/**
+ * Check if error is retryable
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (error instanceof GroqError) {
+    return (
+      error.type === GroqErrorType.NETWORK_ERROR ||
+      error.type === GroqErrorType.SERVER_ERROR ||
+      error.type === GroqErrorType.RATE_LIMIT_ERROR
+    );
+  }
+  return false;
+}
+
+/**
+ * Check if error is auth-related
+ */
+export function isAuthError(error: unknown): boolean {
+  if (error instanceof GroqError) {
+    return error.type === GroqErrorType.INVALID_API_KEY;
+  }
+  return false;
+}
+
+/**
+ * Format error for logging
+ */
+export function formatErrorForLogging(error: unknown): string {
+  if (error instanceof GroqError) {
+    return JSON.stringify({
+      type: error.type,
+      message: error.message,
+      metadata: error.metadata,
+    });
+  }
+
+  if (error instanceof Error) {
+    return JSON.stringify({
+      name: error.name,
+      message: error.message,
+      stack: error.stack,
+    });
+  }
+
+  return String(error);
+}
+
+/**
+ * Create a user message
+ */
+export function createUserMessage(content: string): GroqMessage {
+  return { role: "user", content };
+}
+
+/**
+ * Create an assistant message
+ */
+export function createAssistantMessage(content: string): GroqMessage {
+  return { role: "assistant", content };
+}
+
+/**
+ * Create a system message
+ */
+export function createSystemMessage(content: string): GroqMessage {
+  return { role: "system", content };
+}
+
+/**
+ * Create a text message (defaults to user role)
+ */
+export function createTextMessage(
+  content: string,
+  role: GroqMessage["role"] = "user"
+): GroqMessage {
+  return { role, content };
+}
+
+/**
+ * Convert a prompt to messages array
+ */
+export function promptToMessages(prompt: string): GroqMessage[] {
+  return [createUserMessage(prompt)];
+}
+
+/**
+ * Extract text content from messages
+ */
+export function extractTextFromMessages(messages: GroqMessage[]): string {
+  return messages.map((m) => `[${m.role}]: ${m.content}`).join("\n");
+}
+
+/**
+ * Format messages for display
+ */
+export function formatMessagesForDisplay(messages: GroqMessage[]): string {
+  return messages
+    .map(
+      (m) =>
+        `${m.role.charAt(0).toUpperCase() + m.role.slice(1)}: ${m.content}`
+    )
+    .join("\n\n");
+}