@runanywhere/core 0.16.0

package/src/Foundation/DependencyInjection/ServiceContainer.ts

@@ -0,0 +1,154 @@
+/**
+ * ServiceContainer.ts
+ *
+ * Service container for managing SDK services.
+ * Simplified to work with native HTTP transport.
+ *
+ * Reference: sdk/runanywhere-swift/Sources/RunAnywhere/Foundation/DI/
+ */
+
+import { SDKLogger } from '../Logging/Logger/SDKLogger';
+import {
+  HTTPService,
+  SDKEnvironment,
+} from '../../services/Network';
+
+const logger = new SDKLogger('ServiceContainer');
+
+/**
+ * Service container for SDK dependency management
+ * Manages network configuration and service lifecycle
+ */
+export class ServiceContainer {
+  public static shared: ServiceContainer = new ServiceContainer();
+
+  private _apiKey?: string;
+  private _baseURL?: string;
+  private _environment: SDKEnvironment = SDKEnvironment.Development;
+  private _isInitialized: boolean = false;
+
+  public constructor() {}
+
+  // ==========================================================================
+  // API Configuration
+  // ==========================================================================
+
+  /**
+   * Store API configuration
+   *
+   * @param apiKey API key for authentication
+   * @param environment SDK environment
+   * @param baseURL Optional base URL for production/staging
+   */
+  public setAPIConfig(
+    apiKey: string,
+    environment: SDKEnvironment | string,
+    baseURL?: string
+  ): void {
+    this._apiKey = apiKey;
+    this._baseURL = baseURL;
+
+    // Convert string to enum if needed
+    if (typeof environment === 'string') {
+      this._environment = this.parseEnvironment(environment);
+    } else {
+      this._environment = environment;
+    }
+
+    logger.debug(`API config stored: env=${this.environmentString}`);
+  }
+
+  // ==========================================================================
+  // Service Access
+  // ==========================================================================
+
+  /**
+   * Get the HTTP service instance
+   * Note: HTTP is primarily handled by native layer
+   */
+  public get httpService(): HTTPService {
+    return HTTPService.shared;
+  }
+
+  // ==========================================================================
+  // Getters
+  // ==========================================================================
+
+  public get apiKey(): string | undefined {
+    return this._apiKey;
+  }
+
+  public get baseURL(): string | undefined {
+    return this._baseURL;
+  }
+
+  public get environment(): SDKEnvironment {
+    return this._environment;
+  }
+
+  public get environmentString(): string {
+    switch (this._environment) {
+      case SDKEnvironment.Development:
+        return 'development';
+      case SDKEnvironment.Staging:
+        return 'staging';
+      case SDKEnvironment.Production:
+        return 'production';
+      default:
+        return 'unknown';
+    }
+  }
+
+  public get isInitialized(): boolean {
+    return this._isInitialized;
+  }
+
+  // ==========================================================================
+  // Initialization
+  // ==========================================================================
+
+  /**
+   * Mark services as initialized
+   */
+  public markInitialized(): void {
+    this._isInitialized = true;
+    logger.debug('ServiceContainer marked as initialized');
+  }
+
+  /**
+   * Reset all services (for testing or SDK destruction)
+   */
+  public reset(): void {
+    this._apiKey = undefined;
+    this._baseURL = undefined;
+    this._environment = SDKEnvironment.Development;
+    this._isInitialized = false;
+
+    logger.debug('ServiceContainer reset');
+  }
+
+  // ==========================================================================
+  // Private Helpers
+  // ==========================================================================
+
+  private parseEnvironment(env: string): SDKEnvironment {
+    const normalized = env.toLowerCase();
+    switch (normalized) {
+      case 'development':
+      case 'dev':
+      case '0':
+        return SDKEnvironment.Development;
+      case 'staging':
+      case 'stage':
+      case '1':
+        return SDKEnvironment.Staging;
+      case 'production':
+      case 'prod':
+      case '2':
+        return SDKEnvironment.Production;
+      default:
+        logger.warning(`Unknown environment '${env}', defaulting to Development`);
+        return SDKEnvironment.Development;
+    }
+  }
+}

package/src/Foundation/DependencyInjection/ServiceRegistry.ts

@@ -0,0 +1,51 @@
+/**
+ * ServiceRegistry.ts
+ *
+ * Simplified service registry.
+ * Service registration is now handled by native commons.
+ */
+
+import { SDKLogger } from '../Logging/Logger/SDKLogger';
+
+const logger = new SDKLogger('ServiceRegistry');
+
+/**
+ * Minimal service registry
+ * Service registration is handled by native commons
+ */
+export class ServiceRegistry {
+  private static _instance: ServiceRegistry | null = null;
+  private initialized = false;
+
+  static get shared(): ServiceRegistry {
+    if (!ServiceRegistry._instance) {
+      ServiceRegistry._instance = new ServiceRegistry();
+    }
+    return ServiceRegistry._instance;
+  }
+
+  /**
+   * Initialize (signals native to register services)
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    logger.debug('Service registry initialized - services in native');
+    this.initialized = true;
+  }
+
+  /**
+   * Check if initialized
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Reset (for testing)
+   */
+  reset(): void {
+    this.initialized = false;
+    ServiceRegistry._instance = null;
+  }
+}

package/src/Foundation/DependencyInjection/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Dependency Injection exports
+ */
+
+export { ServiceContainer } from './ServiceContainer';
+export { ServiceRegistry } from './ServiceRegistry';

package/src/Foundation/ErrorTypes/ErrorCategory.ts

@@ -0,0 +1,184 @@
+/**
+ * ErrorCategory.ts
+ *
+ * Logical grouping for error filtering and analytics.
+ * Matches iOS SDK: Foundation/ErrorTypes/ErrorCategory.swift
+ */
+
+import { ErrorCode } from './ErrorCodes';
+
+export enum ErrorCategory {
+  /** SDK initialization errors */
+  Initialization = 'initialization',
+  /** Model loading and validation errors */
+  Model = 'model',
+  /** LLM/text generation errors */
+  Generation = 'generation',
+  /** Network and API errors */
+  Network = 'network',
+  /** File system and disk space errors */
+  Storage = 'storage',
+  /** Out-of-memory conditions */
+  Memory = 'memory',
+  /** Device compatibility issues */
+  Hardware = 'hardware',
+  /** Input validation failures */
+  Validation = 'validation',
+  /** Auth/API key errors */
+  Authentication = 'authentication',
+  /** Individual component failures */
+  Component = 'component',
+  /** Core framework errors */
+  Framework = 'framework',
+  /** Unclassified errors */
+  Unknown = 'unknown',
+}
+
+/**
+ * All error categories for iteration.
+ */
+export const allErrorCategories: ErrorCategory[] = Object.values(ErrorCategory);
+
+/**
+ * Infer error category from an error code.
+ */
+export function getCategoryFromCode(code: ErrorCode): ErrorCategory {
+  // General errors (1000-1099)
+  if (code >= 1000 && code < 1100) {
+    if (
+      code === ErrorCode.NotInitialized ||
+      code === ErrorCode.AlreadyInitialized
+    ) {
+      return ErrorCategory.Initialization;
+    }
+    if (code === ErrorCode.InvalidInput) {
+      return ErrorCategory.Validation;
+    }
+    return ErrorCategory.Framework;
+  }
+
+  // Model errors (1100-1199)
+  if (code >= 1100 && code < 1200) {
+    return ErrorCategory.Model;
+  }
+
+  // Network errors (1200-1299)
+  if (code >= 1200 && code < 1300) {
+    return ErrorCategory.Network;
+  }
+
+  // Storage errors (1300-1399)
+  if (code >= 1300 && code < 1400) {
+    return ErrorCategory.Storage;
+  }
+
+  // Hardware errors (1500-1599)
+  if (code >= 1500 && code < 1600) {
+    return ErrorCategory.Hardware;
+  }
+
+  // Authentication errors (1600-1699)
+  if (code >= 1600 && code < 1700) {
+    return ErrorCategory.Authentication;
+  }
+
+  // Generation errors (1700-1799)
+  if (code >= 1700 && code < 1800) {
+    return ErrorCategory.Generation;
+  }
+
+  return ErrorCategory.Unknown;
+}
+
+/**
+ * Infer error category from an error object by inspecting its properties.
+ * Used for automatic categorization of unknown error types.
+ */
+export function inferCategoryFromError(error: Error): ErrorCategory {
+  const message = error.message.toLowerCase();
+  const name = error.name.toLowerCase();
+
+  // Check for network-related errors
+  if (
+    name.includes('network') ||
+    name.includes('fetch') ||
+    message.includes('network') ||
+    message.includes('connection') ||
+    message.includes('timeout') ||
+    message.includes('offline')
+  ) {
+    return ErrorCategory.Network;
+  }
+
+  // Check for authentication errors
+  if (
+    message.includes('unauthorized') ||
+    message.includes('authentication') ||
+    message.includes('api key') ||
+    message.includes('token') ||
+    message.includes('401') ||
+    message.includes('403')
+  ) {
+    return ErrorCategory.Authentication;
+  }
+
+  // Check for storage/file errors
+  if (
+    message.includes('storage') ||
+    message.includes('disk') ||
+    message.includes('file') ||
+    message.includes('enoent') ||
+    message.includes('eacces') ||
+    message.includes('permission denied')
+  ) {
+    return ErrorCategory.Storage;
+  }
+
+  // Check for memory errors
+  if (
+    message.includes('memory') ||
+    message.includes('out of memory') ||
+    message.includes('heap')
+  ) {
+    return ErrorCategory.Memory;
+  }
+
+  // Check for model errors
+  if (
+    message.includes('model') ||
+    message.includes('inference') ||
+    message.includes('onnx') ||
+    message.includes('llama')
+  ) {
+    return ErrorCategory.Model;
+  }
+
+  // Check for generation errors
+  if (
+    message.includes('generation') ||
+    message.includes('token') ||
+    message.includes('context length')
+  ) {
+    return ErrorCategory.Generation;
+  }
+
+  // Check for validation errors
+  if (
+    message.includes('invalid') ||
+    message.includes('validation') ||
+    message.includes('required')
+  ) {
+    return ErrorCategory.Validation;
+  }
+
+  // Check for initialization errors
+  if (
+    message.includes('not initialized') ||
+    message.includes('already initialized') ||
+    message.includes('initialization')
+  ) {
+    return ErrorCategory.Initialization;
+  }
+
+  return ErrorCategory.Unknown;
+}

package/src/Foundation/ErrorTypes/ErrorCodes.ts

@@ -0,0 +1,151 @@
+/**
+ * ErrorCodes.ts
+ *
+ * Machine-readable error codes for SDK errors.
+ * Matches iOS SDK: Foundation/ErrorTypes/ErrorCodes.swift
+ *
+ * Error code ranges:
+ * - 1000-1099: General SDK state errors
+ * - 1100-1199: Model loading and validation
+ * - 1200-1299: Network and API communication
+ * - 1300-1399: File system and storage
+ * - 1500-1599: Hardware compatibility
+ * - 1600-1699: Authentication and authorization
+ * - 1700-1799: Text generation and token limits
+ */
+
+export enum ErrorCode {
+  // General errors (1000-1099)
+  Unknown = 1000,
+  InvalidInput = 1001,
+  NotInitialized = 1002,
+  AlreadyInitialized = 1003,
+  OperationCancelled = 1004,
+
+  // Model errors (1100-1199)
+  ModelNotFound = 1100,
+  ModelLoadFailed = 1101,
+  ModelValidationFailed = 1102,
+  ModelFormatUnsupported = 1103,
+  ModelCorrupted = 1104,
+  ModelIncompatible = 1105,
+
+  // Network errors (1200-1299)
+  NetworkUnavailable = 1200,
+  NetworkTimeout = 1201,
+  DownloadFailed = 1202,
+  UploadFailed = 1203,
+  ApiError = 1204,
+
+  // Storage errors (1300-1399)
+  InsufficientStorage = 1300,
+  StorageFull = 1301,
+  FileNotFound = 1302,
+  FileAccessDenied = 1303,
+  FileCorrupted = 1304,
+
+  // Hardware errors (1500-1599)
+  HardwareUnsupported = 1500,
+  HardwareUnavailable = 1501,
+
+  // Authentication errors (1600-1699)
+  AuthenticationFailed = 1600,
+  AuthenticationExpired = 1601,
+  AuthorizationDenied = 1602,
+  ApiKeyInvalid = 1603,
+
+  // Generation errors (1700-1799)
+  GenerationFailed = 1700,
+  GenerationTimeout = 1701,
+  TokenLimitExceeded = 1702,
+  CostLimitExceeded = 1703,
+  ContextTooLong = 1704,
+}
+
+/**
+ * Get a human-readable message for an error code.
+ */
+export function getErrorCodeMessage(code: ErrorCode): string {
+  switch (code) {
+    // General errors
+    case ErrorCode.Unknown:
+      return 'An unknown error occurred';
+    case ErrorCode.InvalidInput:
+      return 'Invalid input provided';
+    case ErrorCode.NotInitialized:
+      return 'SDK not initialized';
+    case ErrorCode.AlreadyInitialized:
+      return 'SDK already initialized';
+    case ErrorCode.OperationCancelled:
+      return 'Operation was cancelled';
+
+    // Model errors
+    case ErrorCode.ModelNotFound:
+      return 'Model not found';
+    case ErrorCode.ModelLoadFailed:
+      return 'Failed to load model';
+    case ErrorCode.ModelValidationFailed:
+      return 'Model validation failed';
+    case ErrorCode.ModelFormatUnsupported:
+      return 'Model format not supported';
+    case ErrorCode.ModelCorrupted:
+      return 'Model file is corrupted';
+    case ErrorCode.ModelIncompatible:
+      return 'Model is incompatible with current runtime';
+
+    // Network errors
+    case ErrorCode.NetworkUnavailable:
+      return 'Network is unavailable';
+    case ErrorCode.NetworkTimeout:
+      return 'Network request timed out';
+    case ErrorCode.DownloadFailed:
+      return 'Download failed';
+    case ErrorCode.UploadFailed:
+      return 'Upload failed';
+    case ErrorCode.ApiError:
+      return 'API request failed';
+
+    // Storage errors
+    case ErrorCode.InsufficientStorage:
+      return 'Insufficient storage space';
+    case ErrorCode.StorageFull:
+      return 'Storage is full';
+    case ErrorCode.FileNotFound:
+      return 'File not found';
+    case ErrorCode.FileAccessDenied:
+      return 'File access denied';
+    case ErrorCode.FileCorrupted:
+      return 'File is corrupted';
+
+    // Hardware errors
+    case ErrorCode.HardwareUnsupported:
+      return 'Hardware is not supported';
+    case ErrorCode.HardwareUnavailable:
+      return 'Hardware is unavailable';
+
+    // Authentication errors
+    case ErrorCode.AuthenticationFailed:
+      return 'Authentication failed';
+    case ErrorCode.AuthenticationExpired:
+      return 'Authentication has expired';
+    case ErrorCode.AuthorizationDenied:
+      return 'Authorization denied';
+    case ErrorCode.ApiKeyInvalid:
+      return 'API key is invalid';
+
+    // Generation errors
+    case ErrorCode.GenerationFailed:
+      return 'Text generation failed';
+    case ErrorCode.GenerationTimeout:
+      return 'Text generation timed out';
+    case ErrorCode.TokenLimitExceeded:
+      return 'Token limit exceeded';
+    case ErrorCode.CostLimitExceeded:
+      return 'Cost limit exceeded';
+    case ErrorCode.ContextTooLong:
+      return 'Context is too long';
+
+    default:
+      return 'An error occurred';
+  }
+}