@providerprotocol/ai 0.0.11 → 0.0.12

package/src/core/provider.ts

@@ -1,92 +0,0 @@
-import type {
-  Provider,
-  ModelReference,
-  LLMHandler,
-  EmbeddingHandler,
-  ImageHandler,
-  LLMProvider,
-  EmbeddingProvider,
-  ImageProvider,
-} from '../types/provider.ts';
-
-/**
- * Options for creating a provider
- */
-export interface CreateProviderOptions {
-  name: string;
-  version: string;
-  modalities: {
-    llm?: LLMHandler;
-    embedding?: EmbeddingHandler;
-    image?: ImageHandler;
-  };
-}
-
-/**
- * Create a provider factory function
- *
- * @typeParam TOptions - Provider-specific options type (defaults to unknown)
- * @param options - Provider configuration
- * @returns Provider function with modalities attached
- *
- * @example
- * ```ts
- * // Basic provider without options
- * const anthropic = createProvider({
- *   name: 'anthropic',
- *   version: '1.0.0',
- *   modalities: { llm: createLLMHandler() },
- * });
- *
- * // Provider with custom options (typically needs custom factory)
- * interface MyProviderOptions { api?: 'v1' | 'v2' }
- * const myProvider = createProvider<MyProviderOptions>({
- *   name: 'my-provider',
- *   version: '1.0.0',
- *   modalities: { llm: createLLMHandler() },
- * });
- * ```
- */
-export function createProvider<TOptions = unknown>(
-  options: CreateProviderOptions
-): Provider<TOptions> {
-  // Create the base function that accepts optional provider-specific options
-  const fn = function (modelId: string, _options?: TOptions): ModelReference<TOptions> {
-    return { modelId, provider };
-  };
-
-  // Define properties, including overriding the read-only 'name' property
-  Object.defineProperties(fn, {
-    name: {
-      value: options.name,
-      writable: false,
-      configurable: true,
-    },
-    version: {
-      value: options.version,
-      writable: false,
-      configurable: true,
-    },
-    modalities: {
-      value: options.modalities,
-      writable: false,
-      configurable: true,
-    },
-  });
-
-  const provider = fn as Provider<TOptions>;
-
-  // Inject provider reference into handlers so bind() can return
-  // models with the correct provider reference (spec compliance)
-  if (options.modalities.llm?._setProvider) {
-    options.modalities.llm._setProvider(provider as unknown as LLMProvider);
-  }
-  if (options.modalities.embedding?._setProvider) {
-    options.modalities.embedding._setProvider(provider as unknown as EmbeddingProvider);
-  }
-  if (options.modalities.image?._setProvider) {
-    options.modalities.image._setProvider(provider as unknown as ImageProvider);
-  }
-
-  return provider;
-}

package/src/google/index.ts

@@ -1,3 +0,0 @@
-// Re-export from providers/google
-export { google } from '../providers/google/index.ts';
-export type { GoogleLLMParams } from '../providers/google/index.ts';

package/src/http/errors.ts

@@ -1,112 +0,0 @@
-import { UPPError, type ErrorCode, type Modality } from '../types/errors.ts';
-
-/**
- * Map HTTP status codes to UPP error codes
- */
-export function statusToErrorCode(status: number): ErrorCode {
-  switch (status) {
-    case 400:
-      return 'INVALID_REQUEST';
-    case 401:
-    case 403:
-      return 'AUTHENTICATION_FAILED';
-    case 404:
-      return 'MODEL_NOT_FOUND';
-    case 408:
-      return 'TIMEOUT';
-    case 413:
-      return 'CONTEXT_LENGTH_EXCEEDED';
-    case 429:
-      return 'RATE_LIMITED';
-    case 500:
-    case 502:
-    case 503:
-    case 504:
-      return 'PROVIDER_ERROR';
-    default:
-      return 'PROVIDER_ERROR';
-  }
-}
-
-/**
- * Normalize HTTP error responses to UPPError
- * Maps HTTP status codes to appropriate ErrorCode values
- * Extracts error message from response body when available
- */
-export async function normalizeHttpError(
-  response: Response,
-  provider: string,
-  modality: Modality
-): Promise<UPPError> {
-  const code = statusToErrorCode(response.status);
-  let message = `HTTP ${response.status}: ${response.statusText}`;
-
-  try {
-    const body = await response.text();
-    if (body) {
-      try {
-        const json = JSON.parse(body);
-        // Common error message locations across providers
-        const extractedMessage =
-          json.error?.message ||
-          json.message ||
-          json.error?.error?.message ||
-          json.detail;
-
-        if (extractedMessage) {
-          message = extractedMessage;
-        }
-      } catch {
-        // Body is not JSON, use raw text if short
-        if (body.length < 200) {
-          message = body;
-        }
-      }
-    }
-  } catch {
-    // Failed to read body, use default message
-  }
-
-  return new UPPError(message, code, provider, modality, response.status);
-}
-
-/**
- * Create a network error
- */
-export function networkError(
-  error: Error,
-  provider: string,
-  modality: Modality
-): UPPError {
-  return new UPPError(
-    `Network error: ${error.message}`,
-    'NETWORK_ERROR',
-    provider,
-    modality,
-    undefined,
-    error
-  );
-}
-
-/**
- * Create a timeout error
- */
-export function timeoutError(
-  timeout: number,
-  provider: string,
-  modality: Modality
-): UPPError {
-  return new UPPError(
-    `Request timed out after ${timeout}ms`,
-    'TIMEOUT',
-    provider,
-    modality
-  );
-}
-
-/**
- * Create a cancelled error
- */
-export function cancelledError(provider: string, modality: Modality): UPPError {
-  return new UPPError('Request was cancelled', 'CANCELLED', provider, modality);
-}

package/src/http/fetch.ts

@@ -1,210 +0,0 @@
-import type { ProviderConfig } from '../types/provider.ts';
-import type { Modality } from '../types/errors.ts';
-import { UPPError } from '../types/errors.ts';
-import {
-  normalizeHttpError,
-  networkError,
-  timeoutError,
-  cancelledError,
-} from './errors.ts';
-
-/**
- * Default timeout in milliseconds
- */
-const DEFAULT_TIMEOUT = 120000; // 2 minutes
-
-/**
- * Execute fetch with retry, timeout, and error normalization
- *
- * @param url - Request URL
- * @param init - Fetch init options
- * @param config - Provider config
- * @param provider - Provider name for error messages
- * @param modality - Modality for error messages
- */
-export async function doFetch(
-  url: string,
-  init: RequestInit,
-  config: ProviderConfig,
-  provider: string,
-  modality: Modality
-): Promise<Response> {
-  const fetchFn = config.fetch ?? fetch;
-  const timeout = config.timeout ?? DEFAULT_TIMEOUT;
-  const strategy = config.retryStrategy;
-
-  // Pre-request delay (e.g., token bucket)
-  if (strategy?.beforeRequest) {
-    const delay = await strategy.beforeRequest();
-    if (delay > 0) {
-      await sleep(delay);
-    }
-  }
-
-  let lastError: UPPError | undefined;
-  let attempt = 0;
-
-  while (true) {
-    attempt++;
-
-    try {
-      const response = await fetchWithTimeout(
-        fetchFn,
-        url,
-        init,
-        timeout,
-        provider,
-        modality
-      );
-
-      // Check for HTTP errors
-      if (!response.ok) {
-        const error = await normalizeHttpError(response, provider, modality);
-
-        // Check for Retry-After header
-        const retryAfter = response.headers.get('Retry-After');
-        if (retryAfter && strategy) {
-          const seconds = parseInt(retryAfter, 10);
-          if (!isNaN(seconds) && 'setRetryAfter' in strategy) {
-            (strategy as { setRetryAfter: (s: number) => void }).setRetryAfter(
-              seconds
-            );
-          }
-        }
-
-        // Try to retry
-        if (strategy) {
-          const delay = await strategy.onRetry(error, attempt);
-          if (delay !== null) {
-            await sleep(delay);
-            lastError = error;
-            continue;
-          }
-        }
-
-        throw error;
-      }
-
-      // Success - reset strategy state
-      strategy?.reset?.();
-
-      return response;
-    } catch (error) {
-      // Already a UPPError, handle retry
-      if (error instanceof UPPError) {
-        if (strategy) {
-          const delay = await strategy.onRetry(error, attempt);
-          if (delay !== null) {
-            await sleep(delay);
-            lastError = error;
-            continue;
-          }
-        }
-        throw error;
-      }
-
-      // Network error
-      const uppError = networkError(error as Error, provider, modality);
-
-      if (strategy) {
-        const delay = await strategy.onRetry(uppError, attempt);
-        if (delay !== null) {
-          await sleep(delay);
-          lastError = uppError;
-          continue;
-        }
-      }
-
-      throw uppError;
-    }
-  }
-}
-
-/**
- * Fetch with timeout
- */
-async function fetchWithTimeout(
-  fetchFn: typeof fetch,
-  url: string,
-  init: RequestInit,
-  timeout: number,
-  provider: string,
-  modality: Modality
-): Promise<Response> {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), timeout);
-
-  // Merge abort signals if one was provided
-  const existingSignal = init.signal;
-  if (existingSignal) {
-    existingSignal.addEventListener('abort', () => controller.abort());
-  }
-
-  try {
-    const response = await fetchFn(url, {
-      ...init,
-      signal: controller.signal,
-    });
-    return response;
-  } catch (error) {
-    if ((error as Error).name === 'AbortError') {
-      // Check if it was the user's signal or our timeout
-      if (existingSignal?.aborted) {
-        throw cancelledError(provider, modality);
-      }
-      throw timeoutError(timeout, provider, modality);
-    }
-    throw error;
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
-
-/**
- * Sleep for a given number of milliseconds
- */
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * Streaming fetch - returns response without checking ok status
- * Used when we need to read the stream for SSE
- */
-export async function doStreamFetch(
-  url: string,
-  init: RequestInit,
-  config: ProviderConfig,
-  provider: string,
-  modality: Modality
-): Promise<Response> {
-  const fetchFn = config.fetch ?? fetch;
-  const timeout = config.timeout ?? DEFAULT_TIMEOUT;
-  const strategy = config.retryStrategy;
-
-  // Pre-request delay
-  if (strategy?.beforeRequest) {
-    const delay = await strategy.beforeRequest();
-    if (delay > 0) {
-      await sleep(delay);
-    }
-  }
-
-  // For streaming, we don't retry - the consumer handles errors
-  try {
-    const response = await fetchWithTimeout(
-      fetchFn,
-      url,
-      init,
-      timeout,
-      provider,
-      modality
-    );
-    return response;
-  } catch (error) {
-    if (error instanceof UPPError) {
-      throw error;
-    }
-    throw networkError(error as Error, provider, modality);
-  }
-}

package/src/http/index.ts

@@ -1,31 +0,0 @@
-// Key management
-export {
-  resolveApiKey,
-  RoundRobinKeys,
-  WeightedKeys,
-  DynamicKey,
-} from './keys.ts';
-
-// Retry strategies
-export {
-  ExponentialBackoff,
-  LinearBackoff,
-  NoRetry,
-  TokenBucket,
-  RetryAfterStrategy,
-} from './retry.ts';
-
-// HTTP fetch
-export { doFetch, doStreamFetch } from './fetch.ts';
-
-// SSE parsing
-export { parseSSEStream, parseSimpleTextStream } from './sse.ts';
-
-// Error utilities
-export {
-  normalizeHttpError,
-  networkError,
-  timeoutError,
-  cancelledError,
-  statusToErrorCode,
-} from './errors.ts';

package/src/http/keys.ts

@@ -1,136 +0,0 @@
-import type { ProviderConfig, KeyStrategy } from '../types/provider.ts';
-import { UPPError, type Modality } from '../types/errors.ts';
-
-/**
- * Round-robin through a list of API keys
- */
-export class RoundRobinKeys implements KeyStrategy {
-  private keys: string[];
-  private index = 0;
-
-  constructor(keys: string[]) {
-    if (keys.length === 0) {
-      throw new Error('RoundRobinKeys requires at least one key');
-    }
-    this.keys = keys;
-  }
-
-  getKey(): string {
-    const key = this.keys[this.index]!;
-    this.index = (this.index + 1) % this.keys.length;
-    return key;
-  }
-}
-
-/**
- * Weighted random selection of API keys
- */
-export class WeightedKeys implements KeyStrategy {
-  private entries: Array<{ key: string; weight: number }>;
-  private totalWeight: number;
-
-  constructor(keys: Array<{ key: string; weight: number }>) {
-    if (keys.length === 0) {
-      throw new Error('WeightedKeys requires at least one key');
-    }
-    this.entries = keys;
-    this.totalWeight = keys.reduce((sum, k) => sum + k.weight, 0);
-  }
-
-  getKey(): string {
-    const random = Math.random() * this.totalWeight;
-    let cumulative = 0;
-
-    for (const entry of this.entries) {
-      cumulative += entry.weight;
-      if (random <= cumulative) {
-        return entry.key;
-      }
-    }
-
-    // Fallback to last key (shouldn't happen)
-    return this.entries[this.entries.length - 1]!.key;
-  }
-}
-
-/**
- * Dynamic key selection based on custom logic
- */
-export class DynamicKey implements KeyStrategy {
-  private selector: () => string | Promise<string>;
-
-  constructor(selector: () => string | Promise<string>) {
-    this.selector = selector;
-  }
-
-  async getKey(): Promise<string> {
-    return this.selector();
-  }
-}
-
-/**
- * Check if a value is a KeyStrategy
- */
-function isKeyStrategy(value: unknown): value is KeyStrategy {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'getKey' in value &&
-    typeof (value as KeyStrategy).getKey === 'function'
-  );
-}
-
-/**
- * Resolve API key from ProviderConfig
- * Falls back to environment variable if provided and config.apiKey is not set
- * Throws UPPError with AUTHENTICATION_FAILED if no key is available
- *
- * @param config - Provider configuration
- * @param envVar - Environment variable name to check as fallback
- * @param provider - Provider name for error messages
- * @param modality - Modality for error messages
- */
-export async function resolveApiKey(
-  config: ProviderConfig,
-  envVar?: string,
-  provider = 'unknown',
-  modality: Modality = 'llm'
-): Promise<string> {
-  const { apiKey } = config;
-
-  // If apiKey is provided in config
-  if (apiKey !== undefined) {
-    // String
-    if (typeof apiKey === 'string') {
-      return apiKey;
-    }
-
-    // Function
-    if (typeof apiKey === 'function') {
-      return apiKey();
-    }
-
-    // KeyStrategy
-    if (isKeyStrategy(apiKey)) {
-      return apiKey.getKey();
-    }
-  }
-
-  // Try environment variable
-  if (envVar) {
-    const envValue = process.env[envVar];
-    if (envValue) {
-      return envValue;
-    }
-  }
-
-  // No key found
-  throw new UPPError(
-    envVar
-      ? `API key not found. Set ${envVar} environment variable or provide apiKey in config.`
-      : 'API key not found. Provide apiKey in config.',
-    'AUTHENTICATION_FAILED',
-    provider,
-    modality
-  );
-}