src/types.ts

// A document loaded into the demo
export interface Document {
  id: string; // filename-based
  title: string; // extracted from H1 or filename
  body: string; // full text content
  filepath: string; // e.g. "api-design-principles.md"
}

// A chunk of a document
export interface Chunk {
  docId: string;
  chunkIndex: number;
  text: string;
  startChar: number; // offset in original doc
  title: string; // parent doc title
}

// A chunk with its embedding vector
export interface EmbeddedChunk extends Chunk {
  embedding: Float32Array;
}

// Search result from BM25 or vector search
export interface ScoredChunk {
  chunk: Chunk;
  score: number;
  source: "bm25" | "vector";
}

// Result after RRF fusion
export interface RRFResult {
  docId: string;
  filepath: string;
  title: string;
  bestChunk: string;
  score: number;
  contributions: RRFContribution[];
}

export interface RRFContribution {
  source: "bm25" | "vector";
  queryType: "original" | "lex" | "vec" | "hyde";
  query: string;
  rank: number;
  weight: number;
  rrfContribution: number;
}

// Result after reranking
export interface RerankedResult extends RRFResult {
  rerankScore: number;
  blendedScore: number;
}

// Final result
export interface FinalResult {
  filepath: string;
  title: string;
  bestChunk: string;
  score: number; // blended score
  docId: string;
}

// Query expansion output
export interface ExpandedQuery {
  hyde: string; // hypothetical document snippet
  vec: string[]; // dense retrieval sentences
  lex: string; // BM25 keywords
  source?: "model" | "fallback" | "strong-signal";
  note?: string;
}

// Pipeline events for React UI
export type PipelineStage = "expansion" | "search" | "rrf" | "rerank" | "blend";
export type PipelineStatus = "idle" | "running" | "done" | "error";

export type PipelineEvent =
  | { stage: "expansion"; status: "running" }
  | { stage: "expansion"; status: "done"; data: ExpandedQuery }
  | { stage: "expansion"; status: "error"; error: string }
  | { stage: "search"; status: "running" }
  | {
      stage: "search";
      status: "done";
      data: { bm25Hits: ScoredChunk[]; vectorHits: ScoredChunk[] };
    }
  | { stage: "rrf"; status: "done"; data: { merged: RRFResult[] } }
  | { stage: "rerank"; status: "running" }
  | {
      stage: "rerank";
      status: "done";
      data: { before: RRFResult[]; after: RerankedResult[] };
    }
  | { stage: "blend"; status: "done"; data: { finalResults: FinalResult[] } };

// Model loading state
export interface ModelState {
  name: string;
  status: "pending" | "downloading" | "loading" | "ready" | "error";
  progress: number; // 0-1
  error?: string;
}