@providerprotocol/ai 0.0.1

package/src/providers/google/types.ts

@@ -0,0 +1,214 @@
+/**
+ * Google Gemini-specific LLM parameters
+ */
+export interface GoogleLLMParams {
+  /** Maximum number of tokens to generate */
+  maxOutputTokens?: number;
+
+  /** Temperature for randomness (0.0 - 2.0) */
+  temperature?: number;
+
+  /** Top-p (nucleus) sampling */
+  topP?: number;
+
+  /** Top-k sampling */
+  topK?: number;
+
+  /** Stop sequences */
+  stopSequences?: string[];
+
+  /** Number of candidates to generate */
+  candidateCount?: number;
+
+  /** Response MIME type */
+  responseMimeType?: 'text/plain' | 'application/json';
+
+  /** Response schema for structured output */
+  responseSchema?: Record<string, unknown>;
+
+  /**
+   * Presence penalty for new topics
+   * Positive values encourage discussing new topics
+   */
+  presencePenalty?: number;
+
+  /**
+   * Frequency penalty for repeated tokens
+   * Positive values discourage repetition
+   */
+  frequencyPenalty?: number;
+
+  /**
+   * Seed for deterministic sampling
+   * Same seed with same parameters should produce same results
+   */
+  seed?: number;
+
+  /**
+   * Whether to return log probabilities in response
+   */
+  responseLogprobs?: boolean;
+
+  /**
+   * Number of log probabilities to return (requires responseLogprobs: true)
+   */
+  logprobs?: number;
+
+  /**
+   * Whether to include audio timestamps in response
+   */
+  audioTimestamp?: boolean;
+
+  /**
+   * Thinking/reasoning configuration for Gemini 3+ models
+   */
+  thinkingConfig?: GoogleThinkingConfig;
+}
+
+/**
+ * Thinking configuration for Gemini 3+ models
+ */
+export interface GoogleThinkingConfig {
+  /** Whether thinking is enabled */
+  thinkingBudget?: number;
+}
+
+/**
+ * Google API request body
+ */
+export interface GoogleRequest {
+  contents: GoogleContent[];
+  systemInstruction?: {
+    parts: GooglePart[];
+  };
+  generationConfig?: {
+    maxOutputTokens?: number;
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    stopSequences?: string[];
+    candidateCount?: number;
+    responseMimeType?: string;
+    responseSchema?: Record<string, unknown>;
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+    seed?: number;
+    responseLogprobs?: boolean;
+    logprobs?: number;
+    audioTimestamp?: boolean;
+    thinkingConfig?: GoogleThinkingConfig;
+  };
+  tools?: GoogleTool[];
+  safetySettings?: GoogleSafetySetting[];
+}
+
+/**
+ * Google content (message) format
+ */
+export interface GoogleContent {
+  role: 'user' | 'model';
+  parts: GooglePart[];
+}
+
+/**
+ * Google content part types
+ */
+export type GooglePart =
+  | GoogleTextPart
+  | GoogleImagePart
+  | GoogleFunctionCallPart
+  | GoogleFunctionResponsePart;
+
+export interface GoogleTextPart {
+  text: string;
+}
+
+export interface GoogleImagePart {
+  inlineData: {
+    mimeType: string;
+    data: string;
+  };
+}
+
+export interface GoogleFunctionCallPart {
+  functionCall: {
+    name: string;
+    args: Record<string, unknown>;
+  };
+  /** Gemini 3+ thought signature for multi-turn tool calls */
+  thoughtSignature?: string;
+}
+
+export interface GoogleFunctionResponsePart {
+  functionResponse: {
+    name: string;
+    response: Record<string, unknown>;
+  };
+}
+
+/**
+ * Google tool format
+ */
+export interface GoogleTool {
+  functionDeclarations: GoogleFunctionDeclaration[];
+}
+
+export interface GoogleFunctionDeclaration {
+  name: string;
+  description: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+/**
+ * Google safety setting
+ */
+export interface GoogleSafetySetting {
+  category: string;
+  threshold: string;
+}
+
+/**
+ * Google response format
+ */
+export interface GoogleResponse {
+  candidates: GoogleCandidate[];
+  usageMetadata?: {
+    promptTokenCount: number;
+    candidatesTokenCount: number;
+    totalTokenCount: number;
+  };
+}
+
+export interface GoogleCandidate {
+  content: {
+    role: 'model';
+    parts: GoogleResponsePart[];
+  };
+  finishReason: 'STOP' | 'MAX_TOKENS' | 'SAFETY' | 'RECITATION' | 'OTHER' | 'TOOL_USE' | null;
+  index: number;
+  safetyRatings?: GoogleSafetyRating[];
+}
+
+export type GoogleResponsePart = GoogleTextPart | GoogleFunctionCallPart;
+
+export interface GoogleSafetyRating {
+  category: string;
+  probability: string;
+}
+
+/**
+ * Google streaming response chunk
+ * Same structure as regular response but may be partial
+ */
+export interface GoogleStreamChunk {
+  candidates?: GoogleCandidate[];
+  usageMetadata?: {
+    promptTokenCount: number;
+    candidatesTokenCount: number;
+    totalTokenCount: number;
+  };
+}

package/src/providers/openai/index.ts

@@ -0,0 +1,151 @@
+import type {
+  Provider,
+  ModelReference,
+  LLMHandler,
+  LLMProvider,
+} from '../../types/provider.ts';
+import { createCompletionsLLMHandler } from './llm.completions.ts';
+import { createResponsesLLMHandler } from './llm.responses.ts';
+import type { OpenAILLMParams, OpenAIConfig } from './types.ts';
+
+/**
+ * OpenAI provider options
+ */
+export interface OpenAIProviderOptions {
+  /**
+   * Which API to use:
+   * - 'responses': Modern Responses API (default, recommended)
+   * - 'completions': Legacy Chat Completions API
+   */
+  api?: 'responses' | 'completions';
+}
+
+/**
+ * OpenAI provider with configurable API mode
+ *
+ * @example
+ * // Using the modern Responses API (default)
+ * const model = openai('gpt-4o');
+ *
+ * @example
+ * // Using the legacy Chat Completions API
+ * const model = openai('gpt-4o', { api: 'completions' });
+ *
+ * @example
+ * // Explicit Responses API
+ * const model = openai('gpt-4o', { api: 'responses' });
+ */
+export interface OpenAIProvider extends Provider<OpenAIProviderOptions> {
+  /**
+   * Create a model reference
+   * @param modelId - The model identifier (e.g., 'gpt-4o', 'gpt-4-turbo', 'o1-preview')
+   * @param options - Provider options including API selection
+   */
+  (modelId: string, options?: OpenAIProviderOptions): ModelReference<OpenAIProviderOptions>;
+
+  /** Provider name */
+  readonly name: 'openai';
+
+  /** Provider version */
+  readonly version: string;
+
+  /** Supported modalities */
+  readonly modalities: {
+    llm: LLMHandler<OpenAILLMParams>;
+  };
+}
+
+/**
+ * Create the OpenAI provider
+ */
+function createOpenAIProvider(): OpenAIProvider {
+  // Track which API mode is currently active for the modalities
+  let currentApiMode: 'responses' | 'completions' = 'responses';
+
+  // Create handlers eagerly so we can inject provider reference
+  const responsesHandler = createResponsesLLMHandler();
+  const completionsHandler = createCompletionsLLMHandler();
+
+  const fn = function (
+    modelId: string,
+    options?: OpenAIProviderOptions
+  ): ModelReference<OpenAIProviderOptions> {
+    const apiMode = options?.api ?? 'responses';
+    currentApiMode = apiMode;
+    return { modelId, provider };
+  };
+
+  // Create a dynamic modalities object that returns the correct handler
+  const modalities = {
+    get llm(): LLMHandler<OpenAILLMParams> {
+      return currentApiMode === 'completions'
+        ? completionsHandler
+        : responsesHandler;
+    },
+  };
+
+  // Define properties
+  Object.defineProperties(fn, {
+    name: {
+      value: 'openai',
+      writable: false,
+      configurable: true,
+    },
+    version: {
+      value: '1.0.0',
+      writable: false,
+      configurable: true,
+    },
+    modalities: {
+      value: modalities,
+      writable: false,
+      configurable: true,
+    },
+  });
+
+  const provider = fn as OpenAIProvider;
+
+  // Inject provider reference into both handlers (spec compliance)
+  responsesHandler._setProvider?.(provider as unknown as LLMProvider<OpenAILLMParams>);
+  completionsHandler._setProvider?.(provider as unknown as LLMProvider<OpenAILLMParams>);
+
+  return provider;
+}
+
+/**
+ * OpenAI provider
+ *
+ * Supports both the modern Responses API (default) and legacy Chat Completions API.
+ *
+ * @example
+ * ```ts
+ * import { openai } from './providers/openai';
+ * import { llm } from './core/llm';
+ *
+ * // Using Responses API (default, modern, recommended)
+ * const model = llm({
+ *   model: openai('gpt-4o'),
+ *   params: { max_tokens: 1000 }
+ * });
+ *
+ * // Using Chat Completions API (legacy)
+ * const legacyModel = llm({
+ *   model: openai('gpt-4o', { api: 'completions' }),
+ *   params: { max_tokens: 1000 }
+ * });
+ *
+ * // Generate
+ * const turn = await model.generate('Hello!');
+ * console.log(turn.response.text);
+ * ```
+ */
+export const openai = createOpenAIProvider();
+
+// Re-export types
+export type {
+  OpenAILLMParams,
+  OpenAIConfig,
+  OpenAIAPIMode,
+  OpenAIModelOptions,
+  OpenAIModelReference,
+} from './types.ts';

package/src/providers/openai/llm.completions.ts

@@ -0,0 +1,201 @@
+import type { LLMHandler, BoundLLMModel, LLMRequest, LLMResponse, LLMStreamResult, LLMCapabilities } from '../../types/llm.ts';
+import type { StreamEvent } from '../../types/stream.ts';
+import type { LLMProvider } from '../../types/provider.ts';
+import { UPPError } from '../../types/errors.ts';
+import { resolveApiKey } from '../../http/keys.ts';
+import { doFetch, doStreamFetch } from '../../http/fetch.ts';
+import { parseSSEStream } from '../../http/sse.ts';
+import { normalizeHttpError } from '../../http/errors.ts';
+import type { OpenAILLMParams, OpenAICompletionsResponse, OpenAICompletionsStreamChunk } from './types.ts';
+import {
+  transformRequest,
+  transformResponse,
+  transformStreamEvent,
+  createStreamState,
+  buildResponseFromState,
+} from './transform.completions.ts';
+
+const OPENAI_API_URL = 'https://api.openai.com/v1/chat/completions';
+
+/**
+ * OpenAI API capabilities
+ */
+const OPENAI_CAPABILITIES: LLMCapabilities = {
+  streaming: true,
+  tools: true,
+  structuredOutput: true,
+  imageInput: true,
+  videoInput: false,
+  audioInput: false,
+};
+
+/**
+ * Create OpenAI Chat Completions LLM handler
+ */
+export function createCompletionsLLMHandler(): LLMHandler<OpenAILLMParams> {
+  // Provider reference injected by createProvider() or OpenAI's custom factory
+  let providerRef: LLMProvider<OpenAILLMParams> | null = null;
+
+  return {
+    _setProvider(provider: LLMProvider<OpenAILLMParams>) {
+      providerRef = provider;
+    },
+
+    bind(modelId: string): BoundLLMModel<OpenAILLMParams> {
+      // Use the injected provider reference
+      if (!providerRef) {
+        throw new UPPError(
+          'Provider reference not set. Handler must be used with createProvider() or have _setProvider called.',
+          'INVALID_REQUEST',
+          'openai',
+          'llm'
+        );
+      }
+
+      const model: BoundLLMModel<OpenAILLMParams> = {
+        modelId,
+        capabilities: OPENAI_CAPABILITIES,
+
+        get provider(): LLMProvider<OpenAILLMParams> {
+          return providerRef!;
+        },
+
+        async complete(request: LLMRequest<OpenAILLMParams>): Promise<LLMResponse> {
+          const apiKey = await resolveApiKey(
+            request.config,
+            'OPENAI_API_KEY',
+            'openai',
+            'llm'
+          );
+
+          const baseUrl = request.config.baseUrl ?? OPENAI_API_URL;
+          const body = transformRequest(request, modelId);
+
+          const response = await doFetch(
+            baseUrl,
+            {
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+              },
+              body: JSON.stringify(body),
+              signal: request.signal,
+            },
+            request.config,
+            'openai',
+            'llm'
+          );
+
+          const data = (await response.json()) as OpenAICompletionsResponse;
+          return transformResponse(data);
+        },
+
+        stream(request: LLMRequest<OpenAILLMParams>): LLMStreamResult {
+          const state = createStreamState();
+          let responseResolve: (value: LLMResponse) => void;
+          let responseReject: (error: Error) => void;
+
+          const responsePromise = new Promise<LLMResponse>((resolve, reject) => {
+            responseResolve = resolve;
+            responseReject = reject;
+          });
+
+          async function* generateEvents(): AsyncGenerator<StreamEvent, void, unknown> {
+            try {
+              const apiKey = await resolveApiKey(
+                request.config,
+                'OPENAI_API_KEY',
+                'openai',
+                'llm'
+              );
+
+              const baseUrl = request.config.baseUrl ?? OPENAI_API_URL;
+              const body = transformRequest(request, modelId);
+              body.stream = true;
+              body.stream_options = { include_usage: true };
+
+              const response = await doStreamFetch(
+                baseUrl,
+                {
+                  method: 'POST',
+                  headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`,
+                  },
+                  body: JSON.stringify(body),
+                  signal: request.signal,
+                },
+                request.config,
+                'openai',
+                'llm'
+              );
+
+              if (!response.ok) {
+                const error = await normalizeHttpError(response, 'openai', 'llm');
+                responseReject(error);
+                throw error;
+              }
+
+              if (!response.body) {
+                const error = new UPPError(
+                  'No response body for streaming request',
+                  'PROVIDER_ERROR',
+                  'openai',
+                  'llm'
+                );
+                responseReject(error);
+                throw error;
+              }
+
+              for await (const data of parseSSEStream(response.body)) {
+                // Skip [DONE] marker
+                if (data === '[DONE]') {
+                  continue;
+                }
+
+                // Check for OpenAI error event
+                if (typeof data === 'object' && data !== null) {
+                  const chunk = data as OpenAICompletionsStreamChunk;
+
+                  // Check for error in chunk
+                  if ('error' in chunk && chunk.error) {
+                    const errorData = chunk.error as { message?: string; type?: string };
+                    const error = new UPPError(
+                      errorData.message ?? 'Unknown error',
+                      'PROVIDER_ERROR',
+                      'openai',
+                      'llm'
+                    );
+                    responseReject(error);
+                    throw error;
+                  }
+
+                  const uppEvents = transformStreamEvent(chunk, state);
+                  for (const event of uppEvents) {
+                    yield event;
+                  }
+                }
+              }
+
+              // Build final response
+              responseResolve(buildResponseFromState(state));
+            } catch (error) {
+              responseReject(error as Error);
+              throw error;
+            }
+          }
+
+          return {
+            [Symbol.asyncIterator]() {
+              return generateEvents();
+            },
+            response: responsePromise,
+          };
+        },
+      };
+
+      return model;
+    },
+  };
+}