@restnfeel/agentc-starter-kit/src/lib/chatbot/types/api.ts

한국어 기업용 CMS 모듈 - Task Master AI와 함께 빠르게 웹사이트를 구현할 수 있는 재사용 가능한 컴포넌트 시스템

/**
 * @fileoverview API response type definitions for the RAG chatbot system
 * @module types/api
 */

/**
 * Standard API response wrapper
 */
export interface ApiResponse<T = any> {
  /** Whether the request was successful */
  success: boolean;
  /** Response data */
  data?: T;
  /** Error message if request failed */
  error?: string;
  /** Additional error details */
  details?: any;
  /** HTTP status code */
  status?: number;
  /** Response timestamp */
  timestamp?: string;
}

/**
 * Paginated response wrapper
 */
export interface PaginatedResponse<T> extends ApiResponse<T[]> {
  /** Pagination metadata */
  pagination: {
    /** Current page number (1-based) */
    page: number;
    /** Number of items per page */
    limit: number;
    /** Total number of items */
    total: number;
    /** Total number of pages */
    totalPages: number;
    /** Whether there is a next page */
    hasNext: boolean;
    /** Whether there is a previous page */
    hasPrev: boolean;
  };
}

/**
 * Options for system initialization
 */
export interface InitializationOptions {
  /** Skip vector store initialization */
  skipVectorStore?: boolean;
  /** Skip LLM initialization */
  skipLLM?: boolean;
  /** Skip storage initialization */
  skipStorage?: boolean;
  /** Retry on component failure */
  retryOnFailure?: boolean;
  /** Maximum retry attempts */
  maxRetries?: number;
  /** Retry delay in milliseconds */
  retryDelay?: number;
}

/**
 * Search options for document queries
 */
export interface SearchOptions {
  /** Maximum number of results to return */
  limit?: number;
  /** Similarity threshold (0-1) */
  threshold?: number;
  /** Include document content in results */
  includeContent?: boolean;
  /** Include metadata in results */
  includeMetadata?: boolean;
  /** Search method preference */
  method?: "vector" | "keyword" | "hybrid";
  /** Additional filters */
  filters?: Record<string, any>;
}

/**
 * File upload constraints
 */
export interface FileUploadConstraints {
  /** Maximum file size in bytes */
  maxSize: number;
  /** Allowed MIME types */
  allowedTypes?: string[];
  /** Maximum number of files per upload */
  maxFiles?: number;
  /** Require file validation */
  validateContent?: boolean;
}

/**
 * Upload progress information
 */
export interface UploadProgress {
  /** Percentage completed (0-100) */
  percentage: number;
  /** Bytes uploaded */
  uploaded: number;
  /** Total bytes to upload */
  total: number;
  /** Upload speed in bytes per second */
  speed?: number;
  /** Estimated time remaining in seconds */
  eta?: number;
  /** Current upload stage */
  stage: "uploading" | "processing" | "embedding" | "indexing" | "complete";
}

/**
 * Search result metadata
 */
export interface SearchMetadata {
  /** Search query that produced this result */
  query: string;
  /** Number of results found */
  totalResults: number;
  /** Time taken for search in milliseconds */
  searchTime: number;
  /** Search method used */
  method: "vector" | "keyword" | "hybrid";
  /** Filters applied */
  filters?: Record<string, any>;
}

/**
 * Document processing status
 */
export interface ProcessingStatus {
  /** Processing stage */
  stage:
    | "uploaded"
    | "text-extraction"
    | "chunking"
    | "embedding"
    | "indexing"
    | "complete"
    | "failed";
  /** Progress percentage (0-100) */
  progress: number;
  /** Status message */
  message?: string;
  /** Error details if failed */
  error?: string;
  /** Processing start time */
  startedAt: Date;
  /** Processing completion time */
  completedAt?: Date;
}

/**
 * Vector store health check response
 */
export interface VectorStoreHealth {
  /** Whether the vector store is healthy */
  healthy: boolean;
  /** Response time in milliseconds */
  responseTime: number;
  /** Number of documents indexed */
  documentCount: number;
  /** Available collections */
  collections: string[];
  /** Storage size in bytes */
  storageSize?: number;
  /** Last successful indexing time */
  lastIndexed?: Date;
  /** Error message if unhealthy */
  error?: string;
}

/**
 * LLM health check response
 */
export interface LLMHealth {
  /** Whether the LLM is healthy */
  healthy: boolean;
  /** Response time in milliseconds */
  responseTime: number;
  /** Model name/identifier */
  model: string;
  /** Provider name */
  provider: string;
  /** Available models */
  availableModels?: string[];
  /** Usage statistics */
  usage?: {
    /** Requests made today */
    requestsToday: number;
    /** Tokens used today */
    tokensToday: number;
    /** Rate limit information */
    rateLimit?: {
      /** Requests per minute limit */
      requestsPerMinute: number;
      /** Remaining requests */
      remaining: number;
      /** Reset time */
      resetAt: Date;
    };
  };
  /** Error message if unhealthy */
  error?: string;
}

/**
 * Storage health check response
 */
export interface StorageHealth {
  /** Whether storage is healthy */
  healthy: boolean;
  /** Response time in milliseconds */
  responseTime: number;
  /** Available storage in bytes */
  availableSpace: number;
  /** Used storage in bytes */
  usedSpace: number;
  /** Total number of files */
  fileCount: number;
  /** Available buckets/containers */
  buckets: string[];
  /** Error message if unhealthy */
  error?: string;
}

/**
 * System health check aggregated response
 */
export interface SystemHealth {
  /** Overall system health */
  healthy: boolean;
  /** Individual component health */
  components: {
    vectorStore: VectorStoreHealth;
    llm: LLMHealth;
    storage: StorageHealth;
  };
  /** System uptime in seconds */
  uptime: number;
  /** Last health check time */
  lastChecked: Date;
}