modelgrid/ts/interfaces/container.ts

/**
 * ModelGrid Container Interfaces
 *
 * Defines types for container management (Ollama, vLLM, TGI).
 */

/**
 * Container type
 */
export type TContainerType = 'ollama' | 'vllm' | 'tgi' | 'custom';

/**
 * Container health status
 */
export type TContainerHealth = 'healthy' | 'unhealthy' | 'starting' | 'unknown';

/**
 * Container run status
 */
export type TContainerRunStatus = 'running' | 'stopped' | 'starting' | 'stopping' | 'error';

/**
 * Container configuration
 */
export interface IContainerConfig {
  /** Unique identifier for this container */
  id: string;
  /** Container type */
  type: TContainerType;
  /** Friendly name for the container */
  name: string;
  /** Docker image to use */
  image: string;
  /** GPU IDs to assign to this container */
  gpuIds: string[];
  /** Internal port the container listens on */
  port: number;
  /** External port to expose (optional, uses internal port if not specified) */
  externalPort?: number;
  /** Models to pre-load in this container */
  models: string[];
  /** Environment variables */
  env?: Record<string, string>;
  /** Volume mounts (host:container format) */
  volumes?: string[];
  /** Whether to auto-start this container */
  autoStart: boolean;
  /** Restart policy */
  restartPolicy: 'no' | 'always' | 'on-failure' | 'unless-stopped';
  /** Maximum restart attempts (for on-failure policy) */
  maxRestarts?: number;
  /** Memory limit (e.g., "16g") */
  memoryLimit?: string;
  /** CPU limit (e.g., "4") */
  cpuLimit?: string;
  /** Custom command arguments */
  command?: string[];
}

/**
 * Container status information
 */
export interface IContainerStatus {
  /** Container ID */
  id: string;
  /** Docker container ID */
  dockerId?: string;
  /** Container name */
  name: string;
  /** Container type */
  type: TContainerType;
  /** Whether the container is running */
  running: boolean;
  /** Run status */
  runStatus: TContainerRunStatus;
  /** Health status */
  health: TContainerHealth;
  /** Health check message */
  healthMessage?: string;
  /** GPU utilization (if assigned) */
  gpuUtilization?: number;
  /** Memory usage in MB */
  memoryUsage?: number;
  /** CPU usage percentage */
  cpuUsage?: number;
  /** List of currently loaded models */
  loadedModels: string[];
  /** Container uptime in seconds */
  uptime?: number;
  /** Container start time */
  startTime?: number;
  /** Number of requests served */
  requestsServed?: number;
  /** Last error message (if any) */
  lastError?: string;
  /** Assigned GPU IDs */
  assignedGpus: string[];
  /** Internal endpoint URL */
  endpoint: string;
}

/**
 * Model loaded in a container
 */
export interface ILoadedModel {
  /** Model name */
  name: string;
  /** Model size in bytes */
  size: number;
  /** Model format/quantization */
  format?: string;
  /** Whether the model is currently loaded in memory */
  loaded: boolean;
  /** Last used timestamp */
  lastUsed?: number;
  /** Number of requests served by this model */
  requestCount: number;
}

/**
 * Container endpoint for API routing
 */
export interface IContainerEndpoint {
  /** Container ID */
  containerId: string;
  /** Container type */
  type: TContainerType;
  /** Endpoint URL */
  url: string;
  /** List of models available at this endpoint */
  models: string[];
  /** Whether the endpoint is healthy */
  healthy: boolean;
  /** Priority for load balancing (lower = higher priority) */
  priority: number;
}

/**
 * Container creation options
 */
export interface IContainerCreateOptions {
  /** Container type */
  type: TContainerType;
  /** Friendly name */
  name: string;
  /** GPU IDs to assign */
  gpuIds: string[];
  /** Models to pre-load */
  models?: string[];
  /** Custom image (optional, uses default for type) */
  image?: string;
  /** Custom port (optional, uses default for type) */
  port?: number;
  /** Environment variables */
  env?: Record<string, string>;
  /** Volume mounts */
  volumes?: string[];
  /** Auto-start on daemon startup */
  autoStart?: boolean;
}

/**
 * Container logs options
 */
export interface IContainerLogsOptions {
  /** Container ID */
  containerId: string;
  /** Number of lines to return (default: 100) */
  lines?: number;
  /** Follow logs in real-time */
  follow?: boolean;
  /** Include timestamps */
  timestamps?: boolean;
  /** Filter by log level */
  level?: 'all' | 'error' | 'warn' | 'info' | 'debug';
}