/**
 * GFS RAG System — Type Definitions
 * 
 * Types for the Retrieval-Augmented Generation system that grounds
 * all agent decisions in verified business knowledge.
 */

export interface RAGDocument {
  id: string;
  /** Source file path or identifier */
  source: string;
  /** Document category for filtering */
  category: RAGDocumentCategory;
  /** Human-readable title */
  title: string;
  /** Full text content (pre-chunked) */
  content: string;
  /** Metadata tags for search boosting */
  tags: string[];
  /** When the document was ingested */
  ingestedAt: Date;
  /** Hash for change detection */
  contentHash: string;
}

export type RAGDocumentCategory =
  | 'sop'           // Standard operating procedures
  | 'standing_order' // Standing orders / rules
  | 'risk_register' // Risk register entries
  | 'product_spec'  // Product specifications
  | 'architecture'  // Architecture documentation
  | 'policy'        // Customer data / security policies
  | 'decision_log'  // Past decisions and rationale
  | 'business_model' // Business model documentation
  | 'agent_guide'   // Agent behavior guides
  | 'general';      // Uncategorized

export interface RAGChunk {
  id: string;
  documentId: string;
  /** The chunk text */
  content: string;
  /** Chunk index within the document */
  chunkIndex: number;
  /** Simple TF-IDF style term vector (key=term, value=frequency) */
  termVector: Record<string, number>;
  /** Source metadata for citation */
  source: string;
  category: RAGDocumentCategory;
  title: string;
  tags: string[];
}

export interface RAGSearchResult {
  chunk: RAGChunk;
  score: number;
  /** Why this chunk was retrieved */
  matchReason: string;
}

export interface RAGContext {
  /** Retrieved chunks formatted for prompt injection */
  contextText: string;
  /** Source citations */
  citations: { source: string; title: string; category: string }[];
  /** Number of chunks retrieved */
  chunkCount: number;
  /** Search query used */
  query: string;
  /** Retrieval timestamp */
  retrievedAt: string;
}

export interface RAGConfig {
  /** Max chunks to return per query */
  maxChunks: number;
  /** Minimum relevance score (0-1) to include a chunk */
  minScore: number;
  /** Target chunk size in characters */
  chunkSize: number;
  /** Overlap between chunks in characters */
  chunkOverlap: number;
  /** Categories to exclude from retrieval */
  excludeCategories?: RAGDocumentCategory[];
  /** Categories to prioritize */
  boostCategories?: RAGDocumentCategory[];
}

export const DEFAULT_RAG_CONFIG: RAGConfig = {
  maxChunks: 5,
  minScore: 0.1,
  chunkSize: 1500,
  chunkOverlap: 200,
  boostCategories: ['standing_order', 'sop', 'policy'],
};

/** Safety filter — categories that may contain sensitive content */
export const SENSITIVE_CATEGORIES: RAGDocumentCategory[] = [
  'policy',
  'risk_register',
];
