modelgrid/ts/interfaces/api.ts

/**
 * ModelGrid API Interfaces
 *
 * OpenAI-compatible API types for the ModelGrid gateway.
 */

/**
 * Chat message role
 */
export type TChatRole = 'system' | 'user' | 'assistant' | 'tool';

/**
 * Chat message
 */
export interface IChatMessage {
  /** Message role */
  role: TChatRole;
  /** Message content */
  content: string;
  /** Name of the participant (optional) */
  name?: string;
  /** Tool calls made by the assistant (optional) */
  tool_calls?: IToolCall[];
  /** Tool call ID (for tool response messages) */
  tool_call_id?: string;
}

/**
 * Tool call from assistant
 */
export interface IToolCall {
  /** Unique ID for this tool call */
  id: string;
  /** Type of tool call */
  type: 'function';
  /** Function call details */
  function: {
    /** Function name */
    name: string;
    /** Function arguments as JSON string */
    arguments: string;
  };
}

/**
 * Tool definition for function calling
 */
export interface ITool {
  /** Tool type */
  type: 'function';
  /** Function definition */
  function: {
    /** Function name */
    name: string;
    /** Function description */
    description: string;
    /** Function parameters (JSON Schema) */
    parameters: Record<string, unknown>;
  };
}

/**
 * Chat completion request (OpenAI-compatible)
 */
export interface IChatCompletionRequest {
  /** Model to use */
  model: string;
  /** Messages in the conversation */
  messages: IChatMessage[];
  /** Maximum tokens to generate */
  max_tokens?: number;
  /** Sampling temperature (0-2) */
  temperature?: number;
  /** Top-p sampling */
  top_p?: number;
  /** Number of completions to generate */
  n?: number;
  /** Whether to stream the response */
  stream?: boolean;
  /** Stop sequences */
  stop?: string | string[];
  /** Presence penalty (-2 to 2) */
  presence_penalty?: number;
  /** Frequency penalty (-2 to 2) */
  frequency_penalty?: number;
  /** User identifier */
  user?: string;
  /** Tools available for function calling */
  tools?: ITool[];
  /** Tool choice preference */
  tool_choice?: 'none' | 'auto' | { type: 'function'; function: { name: string } };
}

/**
 * Chat completion choice
 */
export interface IChatCompletionChoice {
  /** Choice index */
  index: number;
  /** Generated message */
  message: IChatMessage;
  /** Finish reason */
  finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
}

/**
 * Token usage information
 */
export interface IUsage {
  /** Number of tokens in the prompt */
  prompt_tokens: number;
  /** Number of tokens in the completion */
  completion_tokens: number;
  /** Total tokens used */
  total_tokens: number;
}

/**
 * Chat completion response (OpenAI-compatible)
 */
export interface IChatCompletionResponse {
  /** Unique ID for this completion */
  id: string;
  /** Object type */
  object: 'chat.completion';
  /** Creation timestamp */
  created: number;
  /** Model used */
  model: string;
  /** System fingerprint */
  system_fingerprint?: string;
  /** Generated choices */
  choices: IChatCompletionChoice[];
  /** Token usage */
  usage: IUsage;
}

/**
 * Chat completion chunk for streaming
 */
export interface IChatCompletionChunk {
  /** Unique ID for this completion */
  id: string;
  /** Object type */
  object: 'chat.completion.chunk';
  /** Creation timestamp */
  created: number;
  /** Model used */
  model: string;
  /** System fingerprint */
  system_fingerprint?: string;
  /** Delta choices */
  choices: IChatCompletionChunkChoice[];
}

/**
 * Streaming choice delta
 */
export interface IChatCompletionChunkChoice {
  /** Choice index */
  index: number;
  /** Delta content */
  delta: Partial<IChatMessage>;
  /** Finish reason */
  finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
}

/**
 * Text completion request (legacy endpoint)
 */
export interface ICompletionRequest {
  /** Model to use */
  model: string;
  /** Prompt text */
  prompt: string | string[];
  /** Maximum tokens to generate */
  max_tokens?: number;
  /** Sampling temperature */
  temperature?: number;
  /** Top-p sampling */
  top_p?: number;
  /** Number of completions */
  n?: number;
  /** Whether to stream */
  stream?: boolean;
  /** Stop sequences */
  stop?: string | string[];
  /** Echo prompt in response */
  echo?: boolean;
}

/**
 * Text completion response
 */
export interface ICompletionResponse {
  /** Unique ID */
  id: string;
  /** Object type */
  object: 'text_completion';
  /** Creation timestamp */
  created: number;
  /** Model used */
  model: string;
  /** Generated choices */
  choices: ICompletionChoice[];
  /** Token usage */
  usage: IUsage;
}

/**
 * Text completion choice
 */
export interface ICompletionChoice {
  /** Generated text */
  text: string;
  /** Choice index */
  index: number;
  /** Finish reason */
  finish_reason: 'stop' | 'length' | null;
}

/**
 * Embeddings request
 */
export interface IEmbeddingsRequest {
  /** Model to use */
  model: string;
  /** Input text(s) */
  input: string | string[];
  /** User identifier */
  user?: string;
  /** Encoding format */
  encoding_format?: 'float' | 'base64';
}

/**
 * Embeddings response
 */
export interface IEmbeddingsResponse {
  /** Object type */
  object: 'list';
  /** Embedding data */
  data: IEmbeddingData[];
  /** Model used */
  model: string;
  /** Token usage */
  usage: {
    prompt_tokens: number;
    total_tokens: number;
  };
}

/**
 * Single embedding data
 */
export interface IEmbeddingData {
  /** Object type */
  object: 'embedding';
  /** Embedding vector */
  embedding: number[];
  /** Index in the input array */
  index: number;
}

/**
 * Model information (OpenAI-compatible)
 */
export interface IModelInfo {
  /** Model ID */
  id: string;
  /** Object type */
  object: 'model';
  /** Creation timestamp */
  created: number;
  /** Model owner/organization */
  owned_by: string;
}

/**
 * List models response
 */
export interface IListModelsResponse {
  /** Object type */
  object: 'list';
  /** Available models */
  data: IModelInfo[];
}

/**
 * API error response
 */
export interface IApiError {
  /** Error details */
  error: {
    /** Error message */
    message: string;
    /** Error type */
    type: string;
    /** Parameter that caused the error */
    param?: string;
    /** Error code */
    code?: string;
  };
}

/**
 * Health check response
 */
export interface IHealthResponse {
  /** Status */
  status: 'ok' | 'degraded' | 'error';
  /** Version */
  version: string;
  /** Uptime in seconds */
  uptime: number;
  /** Number of active containers */
  containers: number;
  /** Number of available models */
  models: number;
  /** Number of available GPUs */
  gpus: number;
  /** Detailed status */
  details?: {
    /** Container health */
    containers: Record<string, 'healthy' | 'unhealthy'>;
    /** GPU status */
    gpus: Record<string, 'available' | 'in_use' | 'error'>;
  };
}