@umituz/web-ai-groq-provider 1.0.1

package/README.md

@@ -0,0 +1,200 @@
+# @umituz/react-ai-groq-provider
+
+Groq AI text generation provider for React web applications. This package provides a clean, type-safe interface to Groq's ultra-fast LLM API.
+
+## Features
+
+- 🚀 **Ultra-fast inference** - Groq delivers up to 1000 tokens/second
+- 💰 **Affordable pricing** - Starting from $0.05 per 1M tokens
+- 🎯 **Multiple models** - Llama 3.1 8B, Llama 3.3 70B, GPT-OSS, and more
+- 🔄 **Streaming support** - Real-time streaming responses
+- 📦 **Structured output** - Generate JSON with schema validation
+- 💬 **Chat sessions** - Multi-turn conversation management
+- 🔒 **Type-safe** - Full TypeScript support
+- 🪝 **React Hooks** - Easy integration with React
+
+## Installation
+
+```bash
+npm install @umituz/react-ai-groq-provider
+# or
+yarn add @umituz/react-ai-groq-provider
+# or
+pnpm add @umituz/react-ai-groq-provider
+```
+
+## Getting Started
+
+### 1. Get a Groq API Key
+
+Sign up at [console.groq.com](https://console.groq.com) and get your API key.
+
+### 2. Initialize the Provider
+
+```typescript
+import { configureProvider } from "@umituz/react-ai-groq-provider";
+
+// Initialize with your API key
+configureProvider({
+  apiKey: "your-groq-api-key",
+  defaultModel: "llama-3.3-70b-versatile", // Optional
+});
+```
+
+### 3. Use the useGroq Hook
+
+```typescript
+import { useGroq } from "@umituz/react-ai-groq-provider";
+
+function MyComponent() {
+  const { generate, isLoading, error, result } = useGroq();
+
+  const handleGenerate = async () => {
+    try {
+      const response = await generate("Write a short poem about coding");
+      console.log(response);
+    } catch (err) {
+      console.error(err);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleGenerate} disabled={isLoading}>
+        Generate
+      </button>
+      {isLoading && <p>Loading...</p>}
+      {error && <p>Error: {error}</p>}
+      {result && <p>{result}</p>}
+    </div>
+  );
+}
+```
+
+## Usage Examples
+
+### Basic Text Generation
+
+```typescript
+import { textGeneration } from "@umituz/react-ai-groq-provider";
+
+const result = await textGeneration("Explain quantum computing in simple terms");
+```
+
+### Chat Conversation
+
+```typescript
+import { chatGeneration } from "@umituz/react-ai-groq-provider";
+
+const messages = [
+  { role: "user", content: "What is React?" },
+  { role: "assistant", content: "React is..." },
+  { role: "user", content: "How does it differ from Vue?" },
+];
+
+const response = await chatGeneration(messages);
+```
+
+### Structured JSON Output
+
+```typescript
+import { structuredText } from "@umituz/react-ai-groq-provider";
+
+interface TodoItem {
+  title: string;
+  priority: "high" | "medium" | "low";
+  completed: boolean;
+}
+
+const todos = await structuredText<TodoItem>(
+  "Create a todo item for learning Groq API",
+  {
+    schema: {
+      type: "object",
+      properties: {
+        title: { type: "string" },
+        priority: { type: "string", enum: ["high", "medium", "low"] },
+        completed: { type: "boolean" },
+      },
+    },
+  }
+);
+```
+
+### Streaming Responses
+
+```typescript
+import { useGroq } from "@umituz/react-ai-groq-provider";
+
+function StreamingComponent() {
+  const { stream } = useGroq();
+
+  const handleStream = async () => {
+    let fullText = "";
+    await stream(
+      "Tell me a story",
+      (chunk) => {
+        fullText += chunk;
+        console.log("Received chunk:", chunk);
+        // Update UI with chunk
+      }
+    );
+  };
+
+  return <button onClick={handleStream}>Stream Story</button>;
+}
+```
+
+## Available Models
+
+| Model | Speed | Context | Best For |
+|-------|-------|---------|----------|
+| `llama-3.1-8b-instant` | 560 T/s | 128K | Fast responses, simple tasks |
+| `llama-3.3-70b-versatile` | 280 T/s | 128K | General purpose, complex tasks |
+| `llama-3.1-70b-versatile` | 280 T/s | 128K | General purpose |
+| `openai/gpt-oss-20b` | 1000 T/s | 128K | Experimental, fastest |
+| `openai/gpt-oss-120b` | 400 T/s | 128K | Large tasks |
+| `mixtral-8x7b-32768` | 250 T/s | 32K | MoE model |
+| `gemma2-9b-it` | 450 T/s | 128K | Google's model |
+
+## Configuration
+
+### Provider Configuration
+
+```typescript
+import { configureProvider } from "@umituz/react-ai-groq-provider";
+
+configureProvider({
+  apiKey: "your-api-key",
+  baseUrl: "https://api.groq.com/openai/v1", // Optional, default
+  timeoutMs: 60000, // Optional, default 60s
+  defaultModel: "llama-3.3-70b-versatile", // Optional
+});
+```
+
+### Generation Configuration
+
+```typescript
+import { GenerationConfigBuilder } from "@umituz/react-ai-groq-provider";
+
+const config = GenerationConfigBuilder.create()
+  .withTemperature(0.7)
+  .withMaxTokens(1024)
+  .withTopP(0.9)
+  .build();
+
+await textGeneration("Your prompt", { generationConfig: config });
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Groq Documentation](https://console.groq.com/docs)
+- [Groq Models](https://console.groq.com/docs/models)
+
+## Author
+
+umituz

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@umituz/web-ai-groq-provider",
+  "version": "1.0.1",
+  "description": "Groq AI text generation provider for React web applications",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./domain": "./src/domain/index.ts",
+    "./services": "./src/infrastructure/services/index.ts",
+    "./hooks": "./src/presentation/hooks/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'Lint passed'",
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean --external react",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch --external react",
+    "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'"
+  },
+  "keywords": [
+    "groq",
+    "ai",
+    "llm",
+    "text-generation",
+    "react",
+    "web",
+    "streaming",
+    "llama"
+  ],
+  "author": "umituz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/umituz/web-ai-groq-provider"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.2.0",
+    "react": "18.3.1",
+    "tsup": "^8.0.0",
+    "typescript": "~5.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,357 @@
+/**
+ * Groq HTTP Client
+ * Handles all HTTP communication with Groq API
+ */
+
+import type {
+  GroqConfig,
+  GroqChatRequest,
+  GroqChatResponse,
+  GroqChatChunk,
+} from "./types";
+import {
+  GroqError,
+  GroqErrorType,
+  mapHttpStatusToErrorType,
+} from "./types";
+
+const DEFAULT_BASE_URL = "https://api.groq.com/openai/v1";
+const DEFAULT_TIMEOUT = 60000; // 60 seconds
+const CHAT_COMPLETIONS_ENDPOINT = "/chat/completions";
+
+const isDevelopment = process.env.NODE_ENV === "development";
+
+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 (isDevelopment) {
+      console.log("[GroqClient] Initializing:", {
+        hasApiKey: !!apiKey,
+        keyLength: apiKey?.length,
+        keyPrefix: apiKey ? apiKey.substring(0, 10) + "..." : "",
+        baseUrl: config.baseUrl || DEFAULT_BASE_URL,
+        timeoutMs: config.timeoutMs || DEFAULT_TIMEOUT,
+        textModel: config.textModel,
+      });
+    }
+
+    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;
+
+    if (isDevelopment) {
+      console.log("[GroqClient] Initialization complete:", {
+        initialized: this.initialized,
+        baseUrl: this.config.baseUrl,
+      });
+    }
+  }
+
+  /**
+   * 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;
+
+    if (isDevelopment) {
+      console.log("[GroqClient] API Request:", {
+        url,
+        endpoint,
+        method: "POST",
+        timeout: `${timeout}ms`,
+        hasBody: !!body,
+        bodyKeys: body ? Object.keys(body) : [],
+      });
+    }
+
+    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 fetchStartTime = Date.now();
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      const fetchDuration = Date.now() - fetchStartTime;
+      clearTimeout(timeoutId);
+
+      if (isDevelopment) {
+        console.log("[GroqClient] API Response:", {
+          status: response.status,
+          ok: response.ok,
+          fetchDuration: `${fetchDuration}ms`,
+          contentType: response.headers.get("content-type"),
+        });
+      }
+
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+
+      const jsonStart = Date.now();
+      const jsonData = (await response.json()) as T;
+      const parseDuration = Date.now() - jsonStart;
+
+      if (isDevelopment) {
+        console.log("[GroqClient] JSON parsed:", {
+          parseDuration: `${parseDuration}ms`,
+          hasData: !!jsonData,
+          dataKeys: jsonData ? Object.keys(jsonData) : [],
+        });
+      }
+
+      return jsonData;
+    } catch (error) {
+      if (isDevelopment) {
+        console.error("[GroqClient] Request error:", {
+          error,
+          errorMessage: error instanceof Error ? error.message : String(error),
+          errorName: error instanceof Error ? error.name : undefined,
+        });
+      }
+
+      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, undefined, {
+      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 as 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 = "";
+      const MAX_BUFFER_SIZE = 1024 * 1024; // 1MB max buffer
+
+      while (true) {
+        const { done, value } = await reader.read();
+
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+
+        // Prevent unlimited buffer growth
+        if (buffer.length > MAX_BUFFER_SIZE) {
+          buffer = buffer.slice(-MAX_BUFFER_SIZE);
+        }
+
+        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) {
+              if (isDevelopment) {
+                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();