@umituz/react-native-ai-groq-provider 1.0.0

package/src/infrastructure/services/GroqClient.ts

@@ -0,0 +1,280 @@
+/**
+ * Groq HTTP Client
+ * Handles all HTTP communication with Groq API
+ */
+
+import type {
+  GroqConfig,
+  GroqChatRequest,
+  GroqChatResponse,
+  GroqChatChunk,
+} from "../../domain/entities";
+import { GroqError, GroqErrorType, mapHttpStatusToErrorType } from "../../domain/entities/error.types";
+
+const DEFAULT_BASE_URL = "https://api.groq.com/openai/v1";
+const DEFAULT_TIMEOUT = 60000; // 60 seconds
+const CHAT_COMPLETIONS_ENDPOINT = "/chat/completions";
+
+class GroqHttpClient {
+  private config: GroqConfig | null = null;
+  private initialized = false;
+
+  /**
+   * Initialize the client with configuration
+   */
+  initialize(config: GroqConfig): void {
+    const apiKey = config.apiKey?.trim();
+
+    if (!apiKey || apiKey.length < 10) {
+      throw new GroqError(
+        GroqErrorType.INVALID_API_KEY,
+        "API key is required and must be at least 10 characters"
+      );
+    }
+
+    this.config = {
+      apiKey,
+      baseUrl: config.baseUrl || DEFAULT_BASE_URL,
+      timeoutMs: config.timeoutMs || DEFAULT_TIMEOUT,
+      textModel: config.textModel,
+    };
+    this.initialized = true;
+  }
+
+  /**
+   * Check if client is initialized
+   */
+  isInitialized(): boolean {
+    return this.initialized && this.config !== null;
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): GroqConfig {
+    if (!this.config || !this.initialized) {
+      throw new GroqError(
+        GroqErrorType.MISSING_CONFIG,
+        "Client not initialized. Call initialize() first."
+      );
+    }
+    return this.config;
+  }
+
+  /**
+   * Make an HTTP request to Groq API
+   */
+  private async request<T>(
+    endpoint: string,
+    body: unknown,
+    signal?: AbortSignal
+  ): Promise<T> {
+    if (!this.config || !this.initialized) {
+      throw new GroqError(
+        GroqErrorType.MISSING_CONFIG,
+        "Client not initialized. Call initialize() first."
+      );
+    }
+
+    const url = `${this.config.baseUrl}${endpoint}`;
+    const timeout = this.config.timeoutMs || DEFAULT_TIMEOUT;
+
+    try {
+      // Create AbortController for timeout
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      // Use provided signal if available
+      if (signal) {
+        signal.addEventListener("abort", () => controller.abort());
+      }
+
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.config.apiKey}`,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+
+      return (await response.json()) as T;
+    } catch (error) {
+      throw this.handleRequestError(error);
+    }
+  }
+
+  /**
+   * Handle HTTP error responses
+   */
+  private async handleErrorResponse(response: Response): Promise<never> {
+    let errorMessage = `HTTP ${response.status}`;
+    let errorType = mapHttpStatusToErrorType(response.status);
+
+    try {
+      const errorData = (await response.json()) as { error?: { message?: string } };
+      if (errorData.error?.message) {
+        errorMessage = errorData.error.message;
+      }
+    } catch {
+      // If parsing fails, use default message
+    }
+
+    throw new GroqError(errorType, errorMessage, {
+      status: response.status,
+      url: response.url,
+    });
+  }
+
+  /**
+   * Handle request errors (network, timeout, abort)
+   */
+  private handleRequestError(error: unknown): GroqError {
+    if (error instanceof GroqError) {
+      return error;
+    }
+
+    if (error instanceof Error) {
+      if (error.name === "AbortError") {
+        return new GroqError(
+          GroqErrorType.ABORT_ERROR,
+          "Request was aborted by the client",
+          error
+        );
+      }
+
+      if (error.name === "TypeError" && error.message.includes("network")) {
+        return new GroqError(
+          GroqErrorType.NETWORK_ERROR,
+          "Network error: Unable to connect to Groq API",
+          error
+        );
+      }
+    }
+
+    return new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      error instanceof Error ? error.message : "Unknown error occurred",
+      error
+    );
+  }
+
+  /**
+   * Send chat completion request (non-streaming)
+   */
+  async chatCompletion(
+    request: GroqChatRequest,
+    signal?: AbortSignal
+  ): Promise<GroqChatResponse> {
+    return this.request<GroqChatResponse>(
+      CHAT_COMPLETIONS_ENDPOINT,
+      { ...request, stream: false },
+      signal
+    );
+  }
+
+  /**
+   * Send chat completion request (streaming)
+   * Returns an async generator of chunks
+   */
+  async *chatCompletionStream(
+    request: GroqChatRequest,
+    signal?: AbortSignal
+  ): AsyncGenerator<GroqChatChunk> {
+    if (!this.config || !this.initialized) {
+      throw new GroqError(
+        GroqErrorType.MISSING_CONFIG,
+        "Client not initialized. Call initialize() first."
+      );
+    }
+
+    const url = `${this.config.baseUrl}${CHAT_COMPLETIONS_ENDPOINT}`;
+    const timeout = this.config.timeoutMs || DEFAULT_TIMEOUT;
+
+    // Create AbortController for timeout
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    // Use provided signal if available
+    if (signal) {
+      signal.addEventListener("abort", () => controller.abort());
+    }
+
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.config.apiKey}`,
+        },
+        body: JSON.stringify({ ...request, stream: true }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+
+      if (!response.body) {
+        throw new GroqError(
+          GroqErrorType.NETWORK_ERROR,
+          "Response body is null"
+        );
+      }
+
+      // Read and parse Server-Sent Events
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+
+      while (true) {
+        const { done, value } = await reader.read();
+
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || trimmed === "data: [DONE]") continue;
+
+          if (trimmed.startsWith("data: ")) {
+            const jsonStr = trimmed.slice(6);
+            try {
+              const chunk = JSON.parse(jsonStr) as GroqChatChunk;
+              yield chunk;
+            } catch (error) {
+              console.error("Failed to parse SSE chunk:", error);
+            }
+          }
+        }
+      }
+    } catch (error) {
+      throw this.handleRequestError(error);
+    }
+  }
+
+  /**
+   * Reset the client
+   */
+  reset(): void {
+    this.config = null;
+    this.initialized = false;
+  }
+}
+
+/**
+ * Singleton instance
+ */
+export const groqHttpClient = new GroqHttpClient();

package/src/infrastructure/services/Streaming.ts

@@ -0,0 +1,114 @@
+/**
+ * Streaming Service
+ * Handles streaming responses from Groq API
+ */
+
+import type {
+  GroqChatRequest,
+  GroqMessage,
+  GroqGenerationConfig,
+} from "../../domain/entities";
+import { groqHttpClient } from "./GroqClient";
+import { DEFAULT_MODELS } from "../../domain/entities";
+
+export interface StreamingCallbacks {
+  /** Called when new content chunk is received */
+  onChunk?: (chunk: string) => void;
+  /** Called when streaming completes */
+  onComplete?: (fullContent: string) => void;
+  /** Called when an error occurs */
+  onError?: (error: Error) => void;
+}
+
+export interface StreamingOptions {
+  model?: string;
+  generationConfig?: GroqGenerationConfig;
+  callbacks?: StreamingCallbacks;
+}
+
+/**
+ * Stream text generation from a prompt
+ */
+export async function* streaming(
+  prompt: string,
+  options: StreamingOptions = {}
+): AsyncGenerator<string> {
+  const model = options.model || DEFAULT_MODELS.TEXT;
+
+  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,
+  };
+
+  try {
+    for await (const chunk of groqHttpClient.chatCompletionStream(request)) {
+      const content = chunk.choices[0]?.delta?.content;
+      if (content) {
+        options.callbacks?.onChunk?.(content);
+        yield content;
+      }
+    }
+    options.callbacks?.onComplete?.(await collectStreamContent(request));
+  } catch (error) {
+    options.callbacks?.onError?.(error as Error);
+    throw error;
+  }
+}
+
+/**
+ * Stream chat generation from messages
+ */
+export async function* streamingChat(
+  messages: GroqMessage[],
+  options: StreamingOptions = {}
+): AsyncGenerator<string> {
+  const model = options.model || DEFAULT_MODELS.TEXT;
+
+  const request: GroqChatRequest = {
+    model,
+    messages,
+    temperature: options.generationConfig?.temperature || 0.7,
+    max_tokens: options.generationConfig?.maxTokens || 1024,
+    top_p: options.generationConfig?.topP,
+  };
+
+  try {
+    for await (const chunk of groqHttpClient.chatCompletionStream(request)) {
+      const content = chunk.choices[0]?.delta?.content;
+      if (content) {
+        options.callbacks?.onChunk?.(content);
+        yield content;
+      }
+    }
+    options.callbacks?.onComplete?.(await collectStreamContent(request));
+  } catch (error) {
+    options.callbacks?.onError?.(error as Error);
+    throw error;
+  }
+}
+
+/**
+ * Collect full content from streaming (for onComplete callback)
+ */
+async function collectStreamContent(request: GroqChatRequest): Promise<string> {
+  let fullContent = "";
+
+  for await (const chunk of groqHttpClient.chatCompletionStream(request)) {
+    const content = chunk.choices[0]?.delta?.content;
+    if (content) {
+      fullContent += content;
+    }
+  }
+
+  return fullContent;
+}

package/src/infrastructure/services/StructuredText.ts

@@ -0,0 +1,171 @@
+/**
+ * Structured Text Generation Service
+ * Generates structured JSON output from Groq API
+ */
+
+import type {
+  GroqChatRequest,
+  GroqMessage,
+  GroqGenerationConfig,
+} from "../../domain/entities";
+import { groqHttpClient } from "./GroqClient";
+import { DEFAULT_MODELS } from "../../domain/entities";
+import { GroqError, GroqErrorType } from "../../domain/entities/error.types";
+
+export interface StructuredTextOptions<T> {
+  model?: string;
+  generationConfig?: GroqGenerationConfig;
+  schema?: Record<string, unknown>;
+  example?: T;
+}
+
+/**
+ * Generate structured JSON output from a prompt
+ */
+export async function structuredText<T = Record<string, unknown>>(
+  prompt: string,
+  options: StructuredTextOptions<T> = {}
+): Promise<T> {
+  const model = options.model || DEFAULT_MODELS.TEXT;
+
+  let systemPrompt = "You are a helpful assistant that generates valid JSON output.";
+
+  if (options.schema) {
+    systemPrompt += `\n\nResponse must conform to this JSON schema:\n${JSON.stringify(options.schema, null, 2)}`;
+  }
+
+  if (options.example) {
+    systemPrompt += `\n\nExample response format:\n${JSON.stringify(options.example, null, 2)}`;
+  }
+
+  systemPrompt += "\n\nIMPORTANT: Respond ONLY with valid JSON. No markdown, no code blocks, no explanations.";
+
+  const messages: GroqMessage[] = [
+    {
+      role: "system",
+      content: systemPrompt,
+    },
+    {
+      role: "user",
+      content: prompt,
+    },
+  ];
+
+  const request: GroqChatRequest = {
+    model,
+    messages,
+    temperature: options.generationConfig?.temperature || 0.3,
+    max_tokens: options.generationConfig?.maxTokens || 2048,
+    top_p: options.generationConfig?.topP || 0.9,
+  };
+
+  const response = await groqHttpClient.chatCompletion(request);
+
+  let content = response.choices[0]?.message?.content;
+  if (!content) {
+    throw new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      "No content generated from Groq API"
+    );
+  }
+
+  // Clean up the response: remove markdown code blocks if present
+  content = content.trim();
+  if (content.startsWith("```json")) {
+    content = content.slice(7);
+  } else if (content.startsWith("```")) {
+    content = content.slice(3);
+  }
+  if (content.endsWith("```")) {
+    content = content.slice(0, -3);
+  }
+  content = content.trim();
+
+  try {
+    return JSON.parse(content) as T;
+  } catch (error) {
+    throw new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      `Failed to parse JSON response: ${content}`,
+      error
+    );
+  }
+}
+
+/**
+ * Generate structured JSON output from messages
+ */
+export async function structuredChat<T = Record<string, unknown>>(
+  messages: GroqMessage[],
+  options: StructuredTextOptions<T> = {}
+): Promise<T> {
+  const model = options.model || DEFAULT_MODELS.TEXT;
+
+  let systemMessage: GroqMessage | null = null;
+
+  // Check if there's already a system message
+  const hasSystemMessage = messages.some((m) => m.role === "system");
+
+  if (!hasSystemMessage) {
+    let systemPrompt = "You are a helpful assistant that generates valid JSON output.";
+
+    if (options.schema) {
+      systemPrompt += `\n\nResponse must conform to this JSON schema:\n${JSON.stringify(options.schema, null, 2)}`;
+    }
+
+    if (options.example) {
+      systemPrompt += `\n\nExample response format:\n${JSON.stringify(options.example, null, 2)}`;
+    }
+
+    systemPrompt += "\n\nIMPORTANT: Respond ONLY with valid JSON. No markdown, no code blocks, no explanations.";
+
+    systemMessage = {
+      role: "system",
+      content: systemPrompt,
+    };
+  }
+
+  const requestMessages = systemMessage
+    ? [systemMessage, ...messages]
+    : messages;
+
+  const request: GroqChatRequest = {
+    model,
+    messages: requestMessages,
+    temperature: options.generationConfig?.temperature || 0.3,
+    max_tokens: options.generationConfig?.maxTokens || 2048,
+    top_p: options.generationConfig?.topP || 0.9,
+  };
+
+  const response = await groqHttpClient.chatCompletion(request);
+
+  let content = response.choices[0]?.message?.content;
+  if (!content) {
+    throw new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      "No content generated from Groq API"
+    );
+  }
+
+  // Clean up the response: remove markdown code blocks if present
+  content = content.trim();
+  if (content.startsWith("```json")) {
+    content = content.slice(7);
+  } else if (content.startsWith("```")) {
+    content = content.slice(3);
+  }
+  if (content.endsWith("```")) {
+    content = content.slice(0, -3);
+  }
+  content = content.trim();
+
+  try {
+    return JSON.parse(content) as T;
+  } catch (error) {
+    throw new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      `Failed to parse JSON response: ${content}`,
+      error
+    );
+  }
+}

package/src/infrastructure/services/TextGeneration.ts

@@ -0,0 +1,94 @@
+/**
+ * Text Generation Service
+ * Handles basic text generation using Groq API
+ */
+
+import type {
+  GroqChatRequest,
+  GroqChatResponse,
+  GroqMessage,
+  GroqGenerationConfig,
+} from "../../domain/entities";
+import { groqHttpClient } from "./GroqClient";
+import { DEFAULT_MODELS } from "../../domain/entities";
+import { GroqError, GroqErrorType } from "../../domain/entities/error.types";
+
+export interface TextGenerationOptions {
+  model?: string;
+  generationConfig?: GroqGenerationConfig;
+}
+
+/**
+ * Generate text from a simple prompt
+ */
+export async function textGeneration(
+  prompt: string,
+  options: TextGenerationOptions = {}
+): Promise<string> {
+  const model = options.model || DEFAULT_MODELS.TEXT;
+
+  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,
+  };
+
+  const response = await groqHttpClient.chatCompletion(request);
+
+  const content = response.choices[0]?.message?.content;
+  if (!content) {
+    throw new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      "No content generated from Groq API"
+    );
+  }
+
+  return content;
+}
+
+/**
+ * Generate text from an array of messages
+ */
+export async function chatGeneration(
+  messages: GroqMessage[],
+  options: TextGenerationOptions = {}
+): Promise<string> {
+  const model = options.model || DEFAULT_MODELS.TEXT;
+
+  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 response = await groqHttpClient.chatCompletion(request);
+
+  const content = response.choices[0]?.message?.content;
+  if (!content) {
+    throw new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      "No content generated from Groq API"
+    );
+  }
+
+  return content;
+}

package/src/infrastructure/services/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Infrastructure Services
+ */
+
+export { groqHttpClient } from "./GroqClient";
+export { textGeneration, chatGeneration } from "./TextGeneration";
+export { structuredText, structuredChat } from "./StructuredText";
+export { streaming, streamingChat, type StreamingCallbacks, type StreamingOptions } from "./Streaming";
+export {
+  chatSessionService,
+  createChatSession,
+  sendChatMessage,
+  buildChatHistory,
+  trimChatHistory,
+  type ChatSession,
+  type SendChatMessageOptions,
+  type ChatSendResult,
+  type ChatHistoryMessage,
+} from "./ChatSession";