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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 umituz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# @umituz/react-native-ai-groq-provider
+
+Groq text generation provider for React Native 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/React Native
+
+## Installation
+
+```bash
+npm install @umituz/react-native-ai-groq-provider
+# or
+yarn add @umituz/react-native-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-native-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-native-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 (
+    <View>
+      <Button onPress={handleGenerate} disabled={isLoading} />
+      {isLoading && <Text>Loading...</Text>}
+      {error && <Text>Error: {error}</Text>}
+      {result && <Text>{result}</Text>}
+    </View>
+  );
+}
+```
+
+## Usage Examples
+
+### Basic Text Generation
+
+```typescript
+import { textGeneration } from "@umituz/react-native-ai-groq-provider";
+
+const result = await textGeneration("Explain quantum computing in simple terms");
+```
+
+### Chat Conversation
+
+```typescript
+import { chatGeneration } from "@umituz/react-native-ai-groq-provider";
+
+const messages = [
+  { role: "user", content: "What is React Native?" },
+  { role: "assistant", content: "React Native is..." },
+  { role: "user", content: "How does it differ from React?" },
+];
+
+const response = await chatGeneration(messages);
+```
+
+### Structured JSON Output
+
+```typescript
+import { structuredText } from "@umituz/react-native-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-native-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 onPress={handleStream} />;
+}
+```
+
+### Chat Sessions
+
+```typescript
+import {
+  createChatSession,
+  sendChatMessage,
+} from "@umituz/react-native-ai-groq-provider";
+
+// Create a chat session
+const session = createChatSession({
+  model: "llama-3.3-70b-versatile",
+  systemInstruction: "You are a helpful assistant.",
+});
+
+// Send messages
+const result1 = await sendChatMessage(session.id, "Hello!");
+console.log(result1.response);
+
+const result2 = await sendChatMessage(session.id, "How are you?");
+console.log(result2.response);
+```
+
+## 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-native-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-native-ai-groq-provider";
+
+const config = GenerationConfigBuilder.create()
+  .withTemperature(0.7)
+  .withMaxTokens(1024)
+  .withTopP(0.9)
+  .build();
+
+await textGeneration("Your prompt", { generationConfig: config });
+```
+
+## Error Handling
+
+```typescript
+import {
+  getUserFriendlyError,
+  isRetryableError,
+  isAuthError,
+} from "@umituz/react-native-ai-groq-provider";
+
+try {
+  const result = await textGeneration("Your prompt");
+} catch (error) {
+  const friendlyMessage = getUserFriendlyError(error);
+  console.log(friendlyMessage);
+
+  if (isRetryableError(error)) {
+    // Retry the request
+  }
+
+  if (isAuthError(error)) {
+    // Check API key
+  }
+}
+```
+
+## API Reference
+
+### Hooks
+
+- `useGroq(options?)` - Main hook for text generation
+- `useOperationManager()` - Manage async operations
+
+### Services
+
+- `textGeneration(prompt, options?)` - Generate text from prompt
+- `chatGeneration(messages, options?)` - Generate from chat history
+- `structuredText<T>(prompt, options?)` - Generate structured JSON
+- `streaming(prompt, options?)` - Stream text generation
+- `createChatSession(config?)` - Create chat session
+- `sendChatMessage(sessionId, content, options?)` - Send message in session
+
+### Utilities
+
+- `ConfigBuilder` - Build provider configuration
+- `GenerationConfigBuilder` - Build generation configuration
+- `providerFactory` - Factory for provider instances
+
+## License
+
+MIT
+
+## Links
+
+- [Groq Documentation](https://console.groq.com/docs)
+- [Groq Models](https://console.groq.com/docs/models)
+- [GitHub](https://github.com/umituz/react-native-ai-groq-provider)
+
+## Author
+
+umituz

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@umituz/react-native-ai-groq-provider",
+  "version": "1.0.0",
+  "description": "Groq text generation provider for React Native applications",
+  "main": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx --max-warnings 0",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix",
+    "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": [
+    "react-native",
+    "ai",
+    "groq",
+    "llama",
+    "text-generation",
+    "llm",
+    "openai-compatible"
+  ],
+  "author": "umituz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/umituz/react-native-ai-groq-provider"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-native": ">=0.74.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@expo/vector-icons": "^15.0.3",
+    "@react-native-async-storage/async-storage": "^2.2.0",
+    "@react-native-community/slider": "^5.1.1",
+    "@react-navigation/bottom-tabs": "^7.9.0",
+    "@react-navigation/native": "^7.1.26",
+    "@react-navigation/stack": "^7.6.13",
+    "@tanstack/react-query": "^5.90.16",
+    "@types/react": "~19.1.10",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "@umituz/react-native-design-system": "*",
+    "eslint": "^8.57.0",
+    "expo-apple-authentication": "^8.0.8",
+    "expo-application": "^7.0.8",
+    "expo-auth-session": "^7.0.10",
+    "expo-clipboard": "^8.0.8",
+    "expo-crypto": "^15.0.8",
+    "expo-device": "^8.0.10",
+    "expo-file-system": "^19.0.21",
+    "expo-font": "^14.0.10",
+    "expo-haptics": "^15.0.8",
+    "expo-image": "^3.0.11",
+    "expo-image-manipulator": "^14.0.8",
+    "expo-localization": "^17.0.8",
+    "expo-media-library": "^18.2.1",
+    "expo-modules-core": "^3.0.29",
+    "expo-network": "^8.0.8",
+    "expo-secure-store": "^15.0.8",
+    "expo-sharing": "^14.0.8",
+    "expo-video": "^3.0.15",
+    "expo-web-browser": "^15.0.10",
+    "firebase": "^12.7.0",
+    "i18next": "^25.7.4",
+    "react": "19.1.0",
+    "react-i18next": "^16.5.1",
+    "react-native": "0.81.5",
+    "react-native-gesture-handler": "^2.30.0",
+    "react-native-safe-area-context": "^5.6.2",
+    "react-native-svg": "^15.15.1",
+    "typescript": "^5.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/domain/entities/error.types.ts

@@ -0,0 +1,54 @@
+/**
+ * Custom error class for Groq operations
+ */
+export class GroqError extends Error {
+  constructor(
+    public type: GroqErrorType,
+    message: string,
+    public cause?: unknown
+  ) {
+    super(message);
+    this.name = "GroqError";
+  }
+}
+
+/**
+ * Error types for Groq operations
+ */
+export enum GroqErrorType {
+  /** API key is missing or invalid */
+  INVALID_API_KEY = "INVALID_API_KEY",
+  /** Configuration is missing or invalid */
+  MISSING_CONFIG = "MISSING_CONFIG",
+  /** Network error occurred */
+  NETWORK_ERROR = "NETWORK_ERROR",
+  /** Request was aborted */
+  ABORT_ERROR = "ABORT_ERROR",
+  /** Rate limit exceeded */
+  RATE_LIMIT_ERROR = "RATE_LIMIT_ERROR",
+  /** Insufficient quota */
+  QUOTA_EXCEEDED = "QUOTA_EXCEEDED",
+  /** Server error */
+  SERVER_ERROR = "SERVER_ERROR",
+  /** Unknown error occurred */
+  UNKNOWN_ERROR = "UNKNOWN_ERROR",
+}
+
+/**
+ * Map HTTP status codes to error types
+ */
+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 && status < 600) {
+    return GroqErrorType.SERVER_ERROR;
+  }
+  if (status >= 400 && status < 500) {
+    return GroqErrorType.INVALID_API_KEY;
+  }
+  return GroqErrorType.UNKNOWN_ERROR;
+}

package/src/domain/entities/groq.types.ts

@@ -0,0 +1,235 @@
+/**
+ * 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;
+  };
+}
+
+/**
+ * Configuration for a chat session
+ */
+export interface GroqChatConfig {
+  /** Model name override */
+  model?: string;
+  /** System instruction for the model */
+  systemInstruction?: string;
+  /** Generation config (temperature, maxTokens, etc.) */
+  generationConfig?: GroqGenerationConfig;
+  /** Initial conversation history */
+  history?: GroqMessage[];
+}
+
+/**
+ * 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;

package/src/domain/entities/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Domain Entities
+ */
+
+export * from "./groq.types";
+export * from "./models";
+export * from "./error.types";