@providerprotocol/ai 0.0.33 → 0.0.35

package/dist/groq/index.d.ts

@@ -0,0 +1,410 @@
+import { d as Provider } from '../llm-DwbUK7un.js';
+import '../stream-CecfVCPO.js';
+
+/**
+ * @fileoverview Groq Provider Type Definitions
+ *
+ * This module contains all TypeScript type definitions for the Groq provider,
+ * including types for the Chat Completions API (OpenAI-compatible).
+ *
+ * @module providers/groq/types
+ */
+/**
+ * Parameters for the Groq Chat Completions API.
+ *
+ * These parameters are passed directly to the `/openai/v1/chat/completions` endpoint.
+ * Groq's API is largely OpenAI-compatible with some differences noted below.
+ *
+ * @example
+ * ```typescript
+ * const params: GroqLLMParams = {
+ *   temperature: 0.7,
+ *   max_tokens: 1000,
+ *   top_p: 0.9
+ * };
+ * ```
+ */
+interface GroqLLMParams {
+    /** Maximum number of tokens to generate */
+    max_tokens?: number;
+    /** Maximum completion tokens (alias for max_tokens) */
+    max_completion_tokens?: number;
+    /** Temperature for randomness (0.0 to 2.0). Note: Groq's API converts 0 to 1e-8 internally. */
+    temperature?: number;
+    /** Top-p (nucleus) sampling (0.0 - 1.0) */
+    top_p?: number;
+    /** Custom stop sequences */
+    stop?: string | string[];
+    /** Frequency penalty (-2.0 - 2.0) */
+    frequency_penalty?: number;
+    /** Presence penalty (-2.0 - 2.0) */
+    presence_penalty?: number;
+    /** Whether to enable parallel tool calls */
+    parallel_tool_calls?: boolean;
+    /** Seed for deterministic sampling */
+    seed?: number;
+    /** User identifier for rate limit tracking */
+    user?: string;
+    /** Response format for structured output */
+    response_format?: GroqResponseFormat;
+    /** Service tier selection */
+    service_tier?: 'on_demand' | 'flex';
+    /** Enable log probabilities output */
+    logprobs?: boolean;
+    /** Number of top log probabilities to return (0-20) */
+    top_logprobs?: number;
+    /** Reasoning effort for reasoning-capable models */
+    reasoning_effort?: 'none' | 'low' | 'medium' | 'high';
+    /** Reasoning format for reasoning-capable models */
+    reasoning_format?: 'parsed' | 'raw' | 'hidden';
+    /** Web search settings for search-enabled models */
+    search_settings?: GroqSearchSettings;
+    /** Documents for RAG (retrieval-augmented generation) */
+    documents?: GroqDocument[];
+    /** Citation options for document-based responses */
+    citation_options?: GroqCitationOptions;
+}
+/**
+ * Web search configuration for Groq's search-enabled models.
+ */
+interface GroqSearchSettings {
+    /** Search mode: 'auto' lets the model decide, 'on' forces search, 'off' disables */
+    mode?: 'auto' | 'on' | 'off';
+}
+/**
+ * Document for RAG (retrieval-augmented generation).
+ */
+interface GroqDocument {
+    /** Document content */
+    content: string;
+    /** Optional document ID for citation */
+    id?: string;
+    /** Optional document title */
+    title?: string;
+}
+/**
+ * Citation options for document-based responses.
+ */
+interface GroqCitationOptions {
+    /** Enable inline citations in the response */
+    enabled?: boolean;
+}
+/**
+ * Response format options for structured output.
+ */
+type GroqResponseFormat = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    json_schema: {
+        name: string;
+        description?: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+    };
+};
+/**
+ * Request body for the Groq Chat Completions API.
+ */
+interface GroqRequest {
+    model: string;
+    messages: GroqMessage[];
+    temperature?: number;
+    top_p?: number;
+    stream?: boolean;
+    stream_options?: {
+        include_usage?: boolean;
+    };
+    stop?: string | string[];
+    max_tokens?: number;
+    max_completion_tokens?: number;
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    user?: string;
+    seed?: number;
+    tools?: GroqTool[];
+    tool_choice?: GroqToolChoice;
+    parallel_tool_calls?: boolean;
+    response_format?: GroqResponseFormat;
+    service_tier?: string;
+    logprobs?: boolean;
+    top_logprobs?: number;
+    reasoning_effort?: string;
+    reasoning_format?: string;
+    search_settings?: GroqSearchSettings;
+    documents?: GroqDocument[];
+    citation_options?: GroqCitationOptions;
+}
+/**
+ * Union type for all message types in the Groq API.
+ */
+type GroqMessage = GroqSystemMessage | GroqUserMessage | GroqAssistantMessage | GroqToolMessage;
+/** System message for setting context and instructions */
+interface GroqSystemMessage {
+    role: 'system';
+    content: string;
+}
+/** User message with text or multimodal content */
+interface GroqUserMessage {
+    role: 'user';
+    content: string | GroqUserContent[];
+}
+/** Assistant message containing the model's response */
+interface GroqAssistantMessage {
+    role: 'assistant';
+    content?: string | null;
+    tool_calls?: GroqToolCall[];
+}
+/** Tool result message providing output from a function call */
+interface GroqToolMessage {
+    role: 'tool';
+    content: string;
+    tool_call_id: string;
+}
+/**
+ * Union type for user content parts (text or image).
+ */
+type GroqUserContent = GroqTextContent | GroqImageContent;
+/** Text content part */
+interface GroqTextContent {
+    type: 'text';
+    text: string;
+}
+/** Image content part with URL reference (for vision models only) */
+interface GroqImageContent {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+/**
+ * Tool call structure in assistant messages.
+ */
+interface GroqToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * Tool definition for the Groq API.
+ */
+interface GroqTool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: 'object';
+            properties: Record<string, unknown>;
+            required?: string[];
+            additionalProperties?: boolean;
+        };
+        strict?: boolean;
+    };
+}
+/**
+ * Tool choice options for controlling function calling behavior.
+ */
+type GroqToolChoice = 'none' | 'auto' | 'required' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+};
+/**
+ * Response structure from the Groq Chat Completions API.
+ */
+interface GroqResponse {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: GroqChoice[];
+    usage: GroqUsage;
+    system_fingerprint?: string;
+    x_groq?: {
+        id?: string;
+    };
+}
+/** A single choice from a completion response */
+interface GroqChoice {
+    index: number;
+    message: GroqAssistantMessage;
+    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
+    logprobs?: GroqLogprobs | null;
+}
+/** Log probability information for tokens */
+interface GroqLogprobs {
+    content?: Array<{
+        token: string;
+        logprob: number;
+        bytes?: number[];
+        top_logprobs?: Array<{
+            token: string;
+            logprob: number;
+            bytes?: number[];
+        }>;
+    }>;
+}
+/** Token usage statistics from the API response */
+interface GroqUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    queue_time?: number;
+    prompt_time?: number;
+    completion_time?: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
+}
+/**
+ * Streaming chunk structure from the Groq API.
+ */
+interface GroqStreamChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: GroqStreamChoice[];
+    usage?: GroqUsage | null;
+    system_fingerprint?: string;
+    x_groq?: {
+        id?: string;
+        usage?: GroqUsage;
+    };
+}
+/** A streaming choice containing incremental content */
+interface GroqStreamChoice {
+    index: number;
+    delta: GroqStreamDelta;
+    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
+    logprobs?: GroqLogprobs | null;
+}
+/** Incremental content delta in a streaming chunk */
+interface GroqStreamDelta {
+    role?: 'assistant';
+    content?: string | null;
+    tool_calls?: GroqStreamToolCall[];
+}
+/** Incremental tool call data in a streaming chunk */
+interface GroqStreamToolCall {
+    index: number;
+    id?: string;
+    type?: 'function';
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+}
+/**
+ * Groq-specific HTTP headers for API requests.
+ *
+ * @example
+ * ```typescript
+ * const headers: GroqHeaders = {
+ *   'X-Request-Id': 'my-request-id',
+ * };
+ * ```
+ */
+interface GroqHeaders {
+    /** Client-generated request ID for tracing */
+    'X-Request-Id'?: string;
+    [key: string]: string | undefined;
+}
+
+/**
+ * @fileoverview Groq Provider Factory
+ *
+ * This module provides the main Groq provider implementation for the
+ * OpenAI-compatible Chat Completions API.
+ *
+ * @module providers/groq
+ */
+/**
+ * Configuration options for the Groq provider.
+ *
+ * Currently Groq only supports one API endpoint (Chat Completions),
+ * so no additional options are needed.
+ */
+interface GroqProviderOptions {
+}
+/**
+ * The Groq provider instance.
+ *
+ * Use this provider to create model references for Groq models like
+ * Llama 3.3, Llama 3.1, Gemma 2, and other models available on Groq.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { groq } from './providers/groq';
+ * import { llm } from './core/llm';
+ *
+ * const model = llm({
+ *   model: groq('llama-3.3-70b-versatile'),
+ *   params: { max_tokens: 1000 }
+ * });
+ *
+ * const turn = await model.generate('Hello!');
+ * console.log(turn.response.text);
+ * ```
+ *
+ * @example With streaming
+ * ```typescript
+ * const stream = model.stream('Tell me a story');
+ *
+ * for await (const event of stream) {
+ *   if (event.type === StreamEventType.TextDelta) {
+ *     process.stdout.write(event.delta.text ?? '');
+ *   }
+ * }
+ *
+ * const turn = await stream.turn;
+ * console.log('Tokens used:', turn.usage.totalTokens);
+ * ```
+ *
+ * @example With tools
+ * ```typescript
+ * const calculator = {
+ *   name: 'calculate',
+ *   description: 'Calculate a math expression',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: {
+ *       expression: { type: 'string' }
+ *     },
+ *     required: ['expression']
+ *   },
+ *   run: async (params: { expression: string }) => {
+ *     return eval(params.expression);
+ *   }
+ * };
+ *
+ * const model = llm({
+ *   model: groq('llama-3.3-70b-versatile'),
+ *   tools: [calculator]
+ * });
+ *
+ * const turn = await model.generate('What is 15 + 27?');
+ * ```
+ *
+ * @example Available models
+ * Production models:
+ * - `llama-3.3-70b-versatile` - Versatile model with tool use support
+ * - `llama-3.1-8b-instant` - Fast, efficient model
+ * - `llama-guard-4-12b` - Content moderation model
+ * - `gemma2-9b-it` - Google's Gemma 2 model
+ *
+ * Preview models:
+ * - `meta-llama/llama-4-scout-17b-16e-instruct` - Vision + tool use
+ * - `qwen/qwen3-32b` - Qwen 3 model
+ */
+declare const groq: Provider<GroqProviderOptions>;
+
+export { type GroqCitationOptions, type GroqDocument, type GroqHeaders, type GroqLLMParams, type GroqMessage, type GroqProviderOptions, type GroqRequest, type GroqResponse, type GroqResponseFormat, type GroqSearchSettings, type GroqStreamChunk, type GroqTool, type GroqToolCall, type GroqToolChoice, type GroqUsage, groq };