@umituz/web-ai-groq-provider 1.0.1

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

@@ -0,0 +1,278 @@
+/**
+ * useGroq Hook
+ * @description Main React hook for Groq text generation
+ */
+
+import { useState, useCallback, useMemo } from "react";
+import type { GroqGenerationConfig } from "../../domain/interfaces";
+import type { TextGenerationOptions, StreamingCallbacks } from "../../domain/interfaces";
+import { textGenerationService } from "../../infrastructure/services/text-generation.service";
+import { groqHttpClient } from "../../infrastructure/services/http-client.service";
+import { GroqError } from "../../infrastructure/utils/groq-error.util";
+import { getUserFriendlyError } from "../../infrastructure/utils/error.util";
+import { DEFAULT_MODELS } from "../../infrastructure/constants/groq.constants";
+
+const isDevelopment = typeof process !== "undefined" && process.env?.NODE_ENV === "development";
+
+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
+ */
+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);
+
+  // Memoize options to prevent unnecessary callback recreations
+  const stableOptions = useMemo(
+    () => options,
+    [
+      options.model,
+      options.generationConfig?.temperature,
+      options.generationConfig?.maxTokens,
+      options.generationConfig?.topP,
+      options.onStart,
+      options.onSuccess,
+      options.onError,
+    ]
+  );
+
+  const generate = useCallback(
+    async (prompt: string, config?: GroqGenerationConfig): Promise<string> => {
+      setIsLoading(true);
+      setError(null);
+      setResult(null);
+
+      if (isDevelopment) {
+        console.log("[useGroq] generate called:", {
+          promptLength: prompt.length,
+        });
+      }
+
+      stableOptions.onStart?.();
+
+      try {
+        const response = await textGenerationService.generateCompletion(prompt, {
+          model: stableOptions.model,
+          generationConfig: {
+            ...stableOptions.generationConfig,
+            ...config,
+          },
+        });
+
+        setResult(response);
+        stableOptions.onSuccess?.(response);
+
+        if (isDevelopment) {
+          console.log("[useGroq] generate success:", {
+            responseLength: response.length,
+          });
+        }
+
+        return response;
+      } catch (err) {
+        const errorMessage = getUserFriendlyError(
+          err instanceof Error ? err : new Error("Unknown error")
+        );
+        setError(errorMessage);
+        stableOptions.onError?.(errorMessage);
+
+        if (isDevelopment) {
+          console.error("[useGroq] generate error:", { error: err });
+        }
+
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [stableOptions]
+  );
+
+  const generateJSON = useCallback(
+    async <T = Record<string, unknown>,>(
+      prompt: string,
+      config?: GroqGenerationConfig & { schema?: Record<string, unknown> }
+    ): Promise<T> => {
+      setIsLoading(true);
+      setError(null);
+      setResult(null);
+
+      if (isDevelopment) {
+        console.log("[useGroq] generateJSON called:", {
+          promptLength: prompt.length,
+        });
+      }
+
+      stableOptions.onStart?.();
+
+      try {
+        const response = await textGenerationService.generateStructured<T>(prompt, {
+          model: stableOptions.model,
+          generationConfig: {
+            ...stableOptions.generationConfig,
+            ...config,
+          },
+          schema: config?.schema,
+        });
+
+        const jsonString = JSON.stringify(response, null, 2);
+        setResult(jsonString);
+        stableOptions.onSuccess?.(jsonString);
+
+        if (isDevelopment) {
+          console.log("[useGroq] generateJSON success:", {
+            hasResponse: !!response,
+          });
+        }
+
+        return response;
+      } catch (err) {
+        const errorMessage = getUserFriendlyError(
+          err instanceof Error ? err : new Error("Unknown error")
+        );
+        setError(errorMessage);
+        stableOptions.onError?.(errorMessage);
+
+        if (isDevelopment) {
+          console.error("[useGroq] generateJSON error:", { error: err });
+        }
+
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [stableOptions]
+  );
+
+  const stream = useCallback(
+    async (
+      prompt: string,
+      onChunk: (chunk: string) => void,
+      config?: GroqGenerationConfig
+    ): Promise<void> => {
+      setIsLoading(true);
+      setError(null);
+      setResult(null);
+
+      let fullContent = "";
+
+      if (isDevelopment) {
+        console.log("[useGroq] stream called:", {
+          promptLength: prompt.length,
+        });
+      }
+
+      stableOptions.onStart?.();
+
+      try {
+        const callbacks: StreamingCallbacks = {
+          onChunk: (c) => {
+            fullContent += c;
+            onChunk(c);
+          },
+          onComplete: (text) => {
+            setResult(text);
+            stableOptions.onSuccess?.(text);
+          },
+        };
+
+        for await (const _ of textGenerationService.streamCompletion(
+          prompt,
+          callbacks,
+          {
+            model: stableOptions.model,
+            generationConfig: {
+              ...stableOptions.generationConfig,
+              ...config,
+            },
+          }
+        )) {
+          // Consume the async generator
+          void _;
+        }
+
+        if (isDevelopment) {
+          console.log("[useGroq] stream success:", {
+            contentLength: fullContent.length,
+          });
+        }
+      } catch (err) {
+        const errorMessage = getUserFriendlyError(
+          err instanceof Error ? err : new Error("Unknown error")
+        );
+        setError(errorMessage);
+        stableOptions.onError?.(errorMessage);
+
+        if (isDevelopment) {
+          console.error("[useGroq] stream error:", { error: err });
+        }
+
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [stableOptions]
+  );
+
+  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/streaming.ts

@@ -0,0 +1,194 @@
+/**
+ * Streaming Text Generation Service
+ * Handles streaming text generation using Groq API
+ */
+
+import type {
+  GroqChatRequest,
+  GroqMessage,
+  GroqGenerationConfig,
+  GroqChatChunk,
+} 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 StreamingOptions {
+  model?: string;
+  generationConfig?: GroqGenerationConfig;
+  callbacks?: StreamingCallbacks;
+}
+
+export interface StreamingCallbacks {
+  onChunk?: (chunk: string) => void;
+  onComplete?: (fullText: string) => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Stream text generation from a prompt
+ * Returns an async generator of text chunks
+ */
+export async function* streaming(
+  prompt: string,
+  options: StreamingOptions = {}
+): AsyncGenerator<string> {
+  const startTime = Date.now();
+  const model = options.model || DEFAULT_MODELS.TEXT;
+
+  if (isDevelopment) {
+    console.log("[Groq] streaming called:", {
+      model,
+      promptLength: prompt.length,
+      promptPreview: prompt.substring(0, 100) + "...",
+    });
+  }
+
+  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] Starting streaming request");
+  }
+
+  try {
+    let fullText = "";
+
+    for await (const chunk of groqHttpClient.chatCompletionStream(request)) {
+      const content = chunk.choices[0]?.delta?.content;
+
+      if (content) {
+        fullText += content;
+        options.callbacks?.onChunk?.(content);
+        yield content;
+      }
+
+      // Check if generation is complete
+      if (chunk.choices[0]?.finish_reason) {
+        if (isDevelopment) {
+          console.log("[Groq] Streaming complete:", {
+            finishReason: chunk.choices[0].finish_reason,
+            totalLength: fullText.length,
+          });
+        }
+        options.callbacks?.onComplete?.(fullText);
+        break;
+      }
+    }
+
+    const totalDuration = Date.now() - startTime;
+    if (isDevelopment) {
+      console.log("[Groq] streaming complete:", {
+        totalDuration: `${totalDuration}ms`,
+        totalLength: fullText.length,
+      });
+    }
+  } catch (error) {
+    if (isDevelopment) {
+      console.error("[Groq] streaming error:", {
+        error,
+        errorMessage: error instanceof Error ? error.message : String(error),
+      });
+    }
+
+    options.callbacks?.onError?.(error as Error);
+    throw error;
+  }
+}
+
+/**
+ * Stream chat generation from messages
+ * Returns an async generator of text chunks
+ */
+export async function* streamingChat(
+  messages: GroqMessage[],
+  options: StreamingOptions = {}
+): AsyncGenerator<string> {
+  const startTime = Date.now();
+  const model = options.model || DEFAULT_MODELS.TEXT;
+
+  if (isDevelopment) {
+    console.log("[Groq] streamingChat called:", {
+      model,
+      messageCount: messages.length,
+    });
+  }
+
+  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] Starting streaming chat request");
+  }
+
+  try {
+    let fullText = "";
+
+    for await (const chunk of groqHttpClient.chatCompletionStream(request)) {
+      const content = chunk.choices[0]?.delta?.content;
+
+      if (content) {
+        fullText += content;
+        options.callbacks?.onChunk?.(content);
+        yield content;
+      }
+
+      // Check if generation is complete
+      if (chunk.choices[0]?.finish_reason) {
+        if (isDevelopment) {
+          console.log("[Groq] Streaming chat complete:", {
+            finishReason: chunk.choices[0].finish_reason,
+            totalLength: fullText.length,
+          });
+        }
+        options.callbacks?.onComplete?.(fullText);
+        break;
+      }
+    }
+
+    const totalDuration = Date.now() - startTime;
+    if (isDevelopment) {
+      console.log("[Groq] streamingChat complete:", {
+        totalDuration: `${totalDuration}ms`,
+        totalLength: fullText.length,
+      });
+    }
+  } catch (error) {
+    if (isDevelopment) {
+      console.error("[Groq] streamingChat error:", {
+        error,
+        errorMessage: error instanceof Error ? error.message : String(error),
+      });
+    }
+
+    options.callbacks?.onError?.(error as Error);
+    throw error;
+  }
+}

package/src/structured-text.ts

@@ -0,0 +1,211 @@
+/**
+ * Structured Text Generation Service
+ * Handles JSON/structured output generation using Groq API
+ */
+
+import type {
+  GroqMessage,
+  GroqGenerationConfig,
+} from "./types";
+import { textGeneration } from "./text-generation";
+import { GroqError, GroqErrorType } from "./types";
+
+const isDevelopment = process.env.NODE_ENV === "development";
+
+export interface StructuredTextOptions<T = unknown> {
+  model?: string;
+  generationConfig?: GroqGenerationConfig;
+  schema?: Record<string, unknown>;
+}
+
+/**
+ * Generate structured JSON output from a prompt
+ */
+export async function structuredText<T = Record<string, unknown>>(
+  prompt: string,
+  options: StructuredTextOptions<T> = {}
+): Promise<T> {
+  const startTime = Date.now();
+
+  if (isDevelopment) {
+    console.log("[Groq] structuredText called:", {
+      model: options.model,
+      promptLength: prompt.length,
+      hasSchema: !!options.schema,
+    });
+  }
+
+  // Build a prompt that encourages JSON output
+  let enhancedPrompt = prompt;
+
+  if (options.schema) {
+    enhancedPrompt = `
+${prompt}
+
+Please respond with a JSON object that follows this schema:
+${JSON.stringify(options.schema, null, 2)}
+
+Your response must be valid JSON only, with no additional text or formatting.
+`;
+  } else {
+    enhancedPrompt = `
+${prompt}
+
+Please respond with a valid JSON object. Your response must be valid JSON only, with no additional text or formatting.
+`;
+  }
+
+  try {
+    // Generate text with lower temperature for more consistent structured output
+    const response = await textGeneration(enhancedPrompt, {
+      model: options.model,
+      generationConfig: {
+        temperature: 0.3, // Lower temperature for more deterministic output
+        maxTokens: 2048,
+        ...options.generationConfig,
+      },
+    });
+
+    if (isDevelopment) {
+      console.log("[Groq] structuredText response received:", {
+        responseLength: response.length,
+        responsePreview: response.substring(0, 200) + "...",
+      });
+    }
+
+    // Extract JSON from response (handle markdown code blocks)
+    let jsonStr = response.trim();
+
+    // Remove markdown code blocks if present
+    if (jsonStr.startsWith("```json")) {
+      jsonStr = jsonStr.slice(7);
+    } else if (jsonStr.startsWith("```")) {
+      jsonStr = jsonStr.slice(3);
+    }
+
+    if (jsonStr.endsWith("```")) {
+      jsonStr = jsonStr.slice(0, -3);
+    }
+
+    jsonStr = jsonStr.trim();
+
+    // Parse JSON
+    const parsed = JSON.parse(jsonStr) as T;
+
+    const totalDuration = Date.now() - startTime;
+    if (isDevelopment) {
+      console.log("[Groq] structuredText complete:", {
+        totalDuration: `${totalDuration}ms`,
+        parsed: !!parsed,
+      });
+    }
+
+    return parsed;
+  } catch (error) {
+    if (isDevelopment) {
+      console.error("[Groq] structuredText error:", {
+        error,
+        errorMessage: error instanceof Error ? error.message : String(error),
+      });
+    }
+
+    throw new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      `Failed to generate structured output: ${
+        error instanceof Error ? error.message : "Unknown error"
+      }`,
+      error as Error
+    );
+  }
+}
+
+/**
+ * Generate structured JSON output from chat messages
+ */
+export async function structuredChat<T = Record<string, unknown>>(
+  messages: GroqMessage[],
+  options: StructuredTextOptions<T> = {}
+): Promise<T> {
+  const startTime = Date.now();
+
+  if (isDevelopment) {
+    console.log("[Groq] structuredChat called:", {
+      model: options.model,
+      messageCount: messages.length,
+      hasSchema: !!options.schema,
+    });
+  }
+
+  // Add a system message requesting JSON output
+  const systemMessage: GroqMessage = {
+    role: "system",
+    content: options.schema
+      ? `You must respond with valid JSON that follows this schema:\n${JSON.stringify(options.schema, null, 2)}\n\nYour response must be valid JSON only, with no additional text or formatting.`
+      : "You must respond with valid JSON only. Your response must be valid JSON only, with no additional text or formatting.",
+  };
+
+  const enhancedMessages = [systemMessage, ...messages];
+
+  try {
+    const { chatGeneration } = await import("./text-generation");
+
+    // Generate with lower temperature for more deterministic output
+    const response = await chatGeneration(enhancedMessages, {
+      model: options.model,
+      generationConfig: {
+        temperature: 0.3,
+        maxTokens: 2048,
+        ...options.generationConfig,
+      },
+    });
+
+    if (isDevelopment) {
+      console.log("[Groq] structuredChat response received:", {
+        responseLength: response.length,
+      });
+    }
+
+    // Extract JSON from response
+    let jsonStr = response.trim();
+
+    // Remove markdown code blocks if present
+    if (jsonStr.startsWith("```json")) {
+      jsonStr = jsonStr.slice(7);
+    } else if (jsonStr.startsWith("```")) {
+      jsonStr = jsonStr.slice(3);
+    }
+
+    if (jsonStr.endsWith("```")) {
+      jsonStr = jsonStr.slice(0, -3);
+    }
+
+    jsonStr = jsonStr.trim();
+
+    // Parse JSON
+    const parsed = JSON.parse(jsonStr) as T;
+
+    const totalDuration = Date.now() - startTime;
+    if (isDevelopment) {
+      console.log("[Groq] structuredChat complete:", {
+        totalDuration: `${totalDuration}ms`,
+      });
+    }
+
+    return parsed;
+  } catch (error) {
+    if (isDevelopment) {
+      console.error("[Groq] structuredChat error:", {
+        error,
+        errorMessage: error instanceof Error ? error.message : String(error),
+      });
+    }
+
+    throw new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      `Failed to generate structured output: ${
+        error instanceof Error ? error.message : "Unknown error"
+      }`,
+      error as Error
+    );
+  }
+}