@umituz/web-ai-groq-provider 1.0.1

package/src/config.ts

@@ -0,0 +1,149 @@
+/**
+ * Configuration Builders
+ * Builder pattern for Groq configuration
+ */
+
+import type { GroqGenerationConfig } from "./types";
+
+/**
+ * Provider configuration options
+ */
+export interface ProviderConfig {
+  apiKey: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  defaultModel?: string;
+}
+
+/**
+ * Config Builder for Provider Configuration
+ */
+export class ConfigBuilder {
+  private config: Partial<ProviderConfig> = {};
+
+  /**
+   * Create a new config builder
+   */
+  static create(): ConfigBuilder {
+    return new ConfigBuilder();
+  }
+
+  /**
+   * Set API key
+   */
+  withApiKey(apiKey: string): ConfigBuilder {
+    this.config.apiKey = apiKey;
+    return this;
+  }
+
+  /**
+   * Set base URL
+   */
+  withBaseUrl(baseUrl: string): ConfigBuilder {
+    this.config.baseUrl = baseUrl;
+    return this;
+  }
+
+  /**
+   * Set timeout
+   */
+  withTimeout(timeoutMs: number): ConfigBuilder {
+    this.config.timeoutMs = timeoutMs;
+    return this;
+  }
+
+  /**
+   * Set default model
+   */
+  withDefaultModel(model: string): ConfigBuilder {
+    this.config.defaultModel = model;
+    return this;
+  }
+
+  /**
+   * Build the configuration
+   */
+  build(): ProviderConfig {
+    if (!this.config.apiKey) {
+      throw new Error("API key is required");
+    }
+    return this.config as ProviderConfig;
+  }
+}
+
+/**
+ * Generation Config Builder
+ */
+export class GenerationConfigBuilder {
+  private config: Partial<GroqGenerationConfig> = {};
+
+  /**
+   * Create a new generation config builder
+   */
+  static create(): GenerationConfigBuilder {
+    return new GenerationConfigBuilder();
+  }
+
+  /**
+   * Set temperature (0.0 - 2.0)
+   */
+  withTemperature(temperature: number): GenerationConfigBuilder {
+    this.config.temperature = Math.max(0, Math.min(2, temperature));
+    return this;
+  }
+
+  /**
+   * Set max tokens
+   */
+  withMaxTokens(maxTokens: number): GenerationConfigBuilder {
+    this.config.maxTokens = Math.max(1, maxTokens);
+    return this;
+  }
+
+  /**
+   * Set top P (0.0 - 1.0)
+   */
+  withTopP(topP: number): GenerationConfigBuilder {
+    this.config.topP = Math.max(0, Math.min(1, topP));
+    return this;
+  }
+
+  /**
+   * Set number of completions
+   */
+  withN(n: number): GenerationConfigBuilder {
+    this.config.n = Math.max(1, n);
+    return this;
+  }
+
+  /**
+   * Set stop sequences
+   */
+  withStop(stop: string[]): GenerationConfigBuilder {
+    this.config.stop = stop;
+    return this;
+  }
+
+  /**
+   * Set frequency penalty (-2.0 to 2.0)
+   */
+  withFrequencyPenalty(penalty: number): GenerationConfigBuilder {
+    this.config.frequencyPenalty = Math.max(-2, Math.min(2, penalty));
+    return this;
+  }
+
+  /**
+   * Set presence penalty (-2.0 to 2.0)
+   */
+  withPresencePenalty(penalty: number): GenerationConfigBuilder {
+    this.config.presencePenalty = Math.max(-2, Math.min(2, penalty));
+    return this;
+  }
+
+  /**
+   * Build the configuration
+   */
+  build(): GroqGenerationConfig {
+    return this.config as GroqGenerationConfig;
+  }
+}

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

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

package/src/domain/entities/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Domain Entities Index
+ * Subpath: @umituz/web-ai-groq-provider/domain
+ */
+
+export type {
+  GroqConfig,
+  GroqGenerationConfig,
+  GroqMessageRole,
+  GroqMessage,
+  GroqChatRequest,
+  GroqChoice,
+  GroqFinishReason,
+  GroqUsage,
+  GroqChatResponse,
+  GroqChunkChoice,
+  GroqChatChunk,
+  GroqErrorResponse,
+  GroqMessageCreateInput,
+} from "./groq.entities";

package/src/domain/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Domain Layer Index
+ * Subpath: @umituz/web-ai-groq-provider/domain
+ *
+ * Exports all entities and interfaces
+ */
+
+// Entities
+export type {
+  GroqMessageRole,
+  GroqMessage,
+  GroqChatRequest,
+  GroqChoice,
+  GroqFinishReason,
+  GroqUsage,
+  GroqChatResponse,
+  GroqChunkChoice,
+  GroqChatChunk,
+  GroqErrorResponse,
+  GroqMessageCreateInput,
+} from "./entities";
+
+// Interfaces
+export type {
+  GroqConfig,
+  GroqGenerationConfig,
+  TextGenerationOptions,
+  StreamingCallbacks,
+  StructuredGenerationOptions,
+  IGroqChatService,
+  IGroqHttpClient,
+} from "./interfaces";

package/src/domain/interfaces/groq.interface.ts

@@ -0,0 +1,79 @@
+/**
+ * Groq Service Interfaces
+ * @description Contracts for Groq AI services
+ */
+
+import type {
+  GroqMessage,
+  GroqChatResponse,
+  GroqChatChunk,
+  GroqChatRequest,
+  GroqConfig,
+  GroqGenerationConfig,
+} from "../entities";
+
+/**
+ * Text generation options
+ */
+export interface TextGenerationOptions {
+  /** Model to use */
+  readonly model?: string;
+  /** Generation configuration */
+  readonly generationConfig?: GroqGenerationConfig;
+}
+
+/**
+ * Streaming callbacks
+ */
+export interface StreamingCallbacks {
+  /** Called for each chunk */
+  readonly onChunk?: (chunk: string) => void;
+  /** Called on completion */
+  readonly onComplete?: (fullText: string) => void;
+  /** Called on error */
+  readonly onError?: (error: Error) => void;
+}
+
+/**
+ * Structured text generation options
+ */
+export interface StructuredGenerationOptions<T = unknown> {
+  /** Model to use */
+  readonly model?: string;
+  /** Generation configuration */
+  readonly generationConfig?: GroqGenerationConfig;
+  /** JSON schema for validation */
+  readonly schema?: Record<string, unknown>;
+}
+
+/**
+ * Chat completion service interface
+ */
+export interface IGroqChatService {
+  /** Generate completion from prompt */
+  generateCompletion(prompt: string, options?: TextGenerationOptions): Promise<string>;
+  /** Generate completion from messages */
+  generateChatCompletion(messages: GroqMessage[], options?: TextGenerationOptions): Promise<string>;
+  /** Generate structured JSON output */
+  generateStructured<T>(prompt: string, options?: StructuredGenerationOptions<T>): Promise<T>;
+  /** Stream completion */
+  streamCompletion(
+    prompt: string,
+    callbacks: StreamingCallbacks,
+    options?: TextGenerationOptions
+  ): AsyncGenerator<void, void, unknown>;
+}
+
+/**
+ * HTTP client interface
+ */
+export interface IGroqHttpClient {
+  /** Send chat completion request */
+  postChatCompletion(request: GroqChatRequest): Promise<GroqChatResponse>;
+  /** Send streaming request */
+  streamChatCompletion(request: GroqChatRequest): Promise<ReadableStream>;
+  /** Get API key */
+  getApiKey(): string;
+  /** Set API key */
+  setApiKey(apiKey: string): void;
+}

package/src/domain/interfaces/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Domain Interfaces Index
+ * Subpath: @umituz/web-ai-groq-provider/domain
+ */
+
+export type {
+  TextGenerationOptions,
+  StreamingCallbacks,
+  StructuredGenerationOptions,
+} from "./groq.interface";
+
+export type { IGroqChatService, IGroqHttpClient } from "./groq.interface";
+
+// Re-export from entities for convenience
+export type {
+  GroqConfig,
+  GroqGenerationConfig,
+  GroqMessage,
+  GroqChatRequest,
+  GroqChatResponse,
+  GroqChatChunk,
+} from "../entities";

package/src/factory.ts

@@ -0,0 +1,92 @@
+/**
+ * Provider Factory
+ * Factory for creating configured Groq provider instances
+ */
+
+import { groqHttpClient } from "./client";
+import type { ProviderConfig } from "./config";
+
+/**
+ * Initialize Groq provider with configuration
+ */
+export function initializeProvider(config: ProviderConfig): void {
+  groqHttpClient.initialize({
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl,
+    timeoutMs: config.timeoutMs,
+    textModel: config.defaultModel,
+  });
+}
+
+/**
+ * Provider factory - creates configured provider instances
+ */
+export const providerFactory = {
+  /**
+   * Create a new provider instance
+   */
+  create(config: ProviderConfig): void {
+    initializeProvider(config);
+  },
+
+  /**
+   * Create provider from environment variables
+   */
+  fromEnv(): void {
+    const apiKey =
+      (typeof process !== "undefined" && process.env?.GROQ_API_KEY) ||
+      (typeof window !== "undefined" &&
+        (window as unknown as Record<string, unknown>).__GROQ_API_KEY__
+        ? String(
+            (window as unknown as Record<string, unknown>).__GROQ_API_KEY__
+          )
+        : "");
+
+    if (!apiKey) {
+      throw new Error("GROQ_API_KEY environment variable is not set");
+    }
+
+    initializeProvider({
+      apiKey,
+      baseUrl:
+        (typeof process !== "undefined" && process.env?.GROQ_BASE_URL) ||
+        undefined,
+      timeoutMs:
+        typeof process !== "undefined" && process.env?.GROQ_TIMEOUT_MS
+          ? parseInt(process.env.GROQ_TIMEOUT_MS)
+          : undefined,
+    });
+  },
+
+  /**
+   * Reset provider (clear configuration)
+   */
+  reset(): void {
+    groqHttpClient.reset();
+  },
+
+  /**
+   * Check if provider is initialized
+   */
+  isInitialized(): boolean {
+    return groqHttpClient.isInitialized();
+  },
+};
+
+/**
+ * Convenience function to initialize provider
+ */
+export function configureProvider(config: ProviderConfig): void {
+  providerFactory.create(config);
+}
+
+/**
+ * Convenience function to reset provider
+ */
+export function resetProvider(): void {
+  providerFactory.reset();
+}
+
+// Re-export builders
+export { ConfigBuilder, GenerationConfigBuilder } from "./config";
+export type { ProviderConfig } from "./config";