Knowledge Base

// ============================================
// ENUMS & CONSTANTS
// ============================================

/** Knowledge base lifecycle status */
type KnowledgeBaseStatus = 'active' | 'archived';

/**
 * Document processing status.
 * Transitions: uploading -> processing -> ready | failed
 */
type DocumentStatus = 'uploading' | 'processing' | 'ready' | 'failed';

/**
 * Granular processing step within 'processing' status.
 * Shows exactly where the document is in the ingestion pipeline.
 * Transitions: null -> parsing -> chunking -> embedding -> upserting -> null (ready)
 * On failure: step is preserved to show where the pipeline broke.
 */
type ProcessingStep = 'parsing' | 'chunking' | 'embedding' | 'upserting' | null;

/** Supported file types for document upload */
type SupportedFileType = 'txt' | 'md' | 'pdf';

/** Chunking strategy for document splitting */
type ChunkStrategy = 'recursive' | 'sliding_window';

type SortOrder = 'asc' | 'desc';

// ============================================
// KNOWLEDGE BASE CONFIGURATION
// ============================================

/**
 * Chunk configuration for document splitting.
 * Set when creating a knowledge base. All documents in the KB
 * use the same chunk config.
 *
 * All fields are optional in the request (defaults are applied server-side).
 * In responses, all fields will always be present.
 */
interface ChunkConfig {
  /** Splitting strategy. Default: 'recursive' */
  strategy?: ChunkStrategy;
  /** Chunk size in characters. Default: 512 */
  size?: number;
  /** Overlap between chunks in characters. Default: 50 */
  overlap?: number;
}

// ============================================
// REQUEST TYPES
// ============================================

interface CreateKnowledgeBaseRequest {
  /** Knowledge base name (1-128 chars) */
  name: string;
  /** Knowledge base description */
  description?: string;
  /**
   * Embedding model in "provider/model-name" format.
   * Default: 'openai/text-embedding-3-small'
   * Vector dimension: 1536
   */
  embeddingModel?: string;
  /** Chunk configuration. Defaults: strategy='recursive', size=512, overlap=50 */
  chunkConfig?: ChunkConfig;
}

interface UpdateKnowledgeBaseRequest {
  name?: string;
  description?: string;
  /** Update KB status (e.g., to 'archived') */
  status?: KnowledgeBaseStatus;
}

// ============================================
// QUERY PARAMETERS
// ============================================

interface KnowledgeBaseQueryParams {
  /** Page number (default: 1) */
  page?: number;
  /** Items per page (default: 20, max: 100) */
  limit?: number;
  /** Search by name or description (case-insensitive, max 100 chars) */
  search?: string;
  /** Sort field */
  sortBy?: 'name' | 'createdAt' | 'updatedAt' | 'status' | 'documentCount';
  /** Sort order (default: 'desc') */
  sortOrder?: SortOrder;
  /** Filter by status */
  status?: KnowledgeBaseStatus;
}

interface DocumentQueryParams {
  /** Page number (default: 1) */
  page?: number;
  /** Items per page (default: 20, max: 100) */
  limit?: number;
  /** Search by file name (partial match, max 100 chars) */
  search?: string;
  /** Sort field */
  sortBy?: 'fileName' | 'createdAt' | 'updatedAt' | 'status' | 'chunkCount';
  /** Sort order (default: 'desc') */
  sortOrder?: SortOrder;
  /** Filter by document group */
  documentGroup?: string;
  /** Filter by processing status */
  status?: DocumentStatus;
}

// ============================================
// RESPONSE TYPES
// ============================================

interface KnowledgeBaseResponse {
  /** Knowledge base UUID */
  id: string;
  /** Organization UUID */
  organizationId: string;
  /** Display name */
  name: string;
  /** Description */
  description: string | null;
  /** Current status */
  status: KnowledgeBaseStatus;
  /**
   * Embedding model used for this KB.
   * Cannot be changed after creation (would require re-embedding all documents).
   */
  embeddingModel: string;
  /** Chunk configuration used for all documents in this KB (always set for new KBs) */
  chunkConfig: ChunkConfig | null;
  /** Number of documents (excluding deleted) */
  documentCount: number;
  /** ISO 8601 timestamp */
  createdAt: string;
  /** ISO 8601 timestamp */
  updatedAt: string;
  /** UUID of the user who created the KB */
  createdBy: string | null;
}

interface KnowledgeBaseListResponse {
  data: KnowledgeBaseResponse[];
  meta: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  };
}

interface DocumentResponse {
  /** Document UUID */
  id: string;
  /** Parent knowledge base UUID */
  knowledgeBaseId: string;
  /** Original file name (e.g., "product-guide.pdf") */
  fileName: string;
  /** File type */
  fileType: SupportedFileType;
  /** File size in bytes (null if not available) */
  fileSize: number | null;
  /**
   * Document group tag for filtering.
   * Agents can be configured to only query specific groups.
   * Default: 'default'
   */
  documentGroup: string;
  /** Current processing status */
  status: DocumentStatus;
  /**
   * Current processing step within 'processing' status.
   * null when status is 'uploading', 'ready', or 'failed' (preserved on failure).
   *
   * Use this to show a progress indicator:
   * parsing -> chunking -> embedding -> upserting
   */
  processingStep: ProcessingStep;
  /** Number of chunks created (0 until processing completes) */
  chunkCount: number;
  /** Error message (only set when status is 'failed') */
  errorMessage: string | null;
  /** ISO 8601 timestamp */
  createdAt: string;
  /** ISO 8601 timestamp */
  updatedAt: string;
}

interface DocumentListResponse {
  data: DocumentResponse[];
  meta: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  };
}

// ============================================
// AGENT KNOWLEDGE BASE CONFIGURATION
// ============================================

/**
 * Configuration linking an agent to a knowledge base.
 * Set via PATCH /agents/:id { knowledgeBaseConfig: { ... } }
 * See agents.md for the full agent update API.
 */
interface AgentKnowledgeBaseConfig {
  /** UUID of the knowledge base to query */
  knowledgeBaseId: string;

  /**
   * Document groups to include in retrieval.
   * null/undefined = all groups in the KB.
   * Example: ['product-docs', 'faqs']
   */
  documentGroups?: string[];

  /**
   * Number of document chunks to retrieve per query.
   * Default: 5
   */
  topK?: number;

  /**
   * Minimum cosine similarity score (0-1).
   * Chunks below this threshold are excluded.
   * Default: 0.7
   */
  similarityThreshold?: number;
}