@od-oneapp/ai-platform 0.1.0

package/dist/grounding-embed.mjs

@@ -0,0 +1,417 @@
+import { H as embedMany, S as cosineSimilarity$1, V as embed } from "./ai-runtime-CDzQztTt.mjs";
+import { a as createRerankPipeline, i as createCrossEncoderReranker, n as calculateNDCG, o as reciprocalRankFusion, r as createCohereReranker, s as vectorResultsToDocuments, t as calculateMRR } from "./reranking-Ck8aKZW7.mjs";
+
+//#region src/grounding/embed/index.ts
+/**
+* Creates a text chunker with configurable strategy.
+*
+* @example
+* ```typescript
+* const chunker = createChunker({
+*   strategy: 'paragraph',
+*   chunkSize: 500,
+*   chunkOverlap: 50
+* });
+*
+* const chunks = chunker.chunk(longText, { sourceId: 'doc-1' });
+* ```
+*/
+function createChunker(config) {
+	const { strategy, chunkSize, chunkOverlap, minChunkSize = 50 } = config;
+	function chunk(text, metadata) {
+		const chunks = [];
+		let segments;
+		switch (strategy) {
+			case "sentence":
+				segments = splitBySentence(text);
+				break;
+			case "paragraph":
+				segments = splitByParagraph(text);
+				break;
+			case "semantic":
+				segments = splitSemantic(text, chunkSize);
+				break;
+			case "fixed":
+				segments = splitFixed(text, chunkSize, chunkOverlap);
+				break;
+			default: {
+				const exhaustiveCheck = strategy;
+				throw new Error(`Unsupported chunking strategy: ${exhaustiveCheck}`);
+			}
+		}
+		let currentChunk = "";
+		let startIndex = 0;
+		let chunkIndex = 0;
+		for (let i = 0; i < segments.length; i++) {
+			const segment = segments[i] ?? "";
+			if (currentChunk.length + segment.length <= chunkSize) currentChunk += (currentChunk ? " " : "") + segment;
+			else {
+				if (currentChunk.length >= minChunkSize) {
+					chunks.push(createChunk(currentChunk, chunkIndex++, startIndex, metadata));
+					startIndex += currentChunk.length;
+				}
+				if (segment.length > chunkSize) {
+					const subChunks = splitFixed(segment, chunkSize, chunkOverlap);
+					for (const sub of subChunks) if (sub.length >= minChunkSize) {
+						chunks.push(createChunk(sub, chunkIndex++, startIndex, metadata));
+						startIndex += sub.length;
+					}
+					currentChunk = "";
+				} else currentChunk = segment;
+			}
+		}
+		if (currentChunk.length >= minChunkSize) chunks.push(createChunk(currentChunk, chunkIndex++, startIndex, metadata));
+		const totalChunks = chunks.length;
+		return chunks.map((c) => ({
+			...c,
+			metadata: {
+				...c.metadata,
+				totalChunks
+			}
+		}));
+	}
+	function createChunk(content, chunkIndex, startIndex, metadata) {
+		const uniqueSuffix = Math.random().toString(36).slice(2, 8);
+		return {
+			id: `chunk-${Date.now()}-${chunkIndex}-${uniqueSuffix}`,
+			content: content.trim(),
+			metadata: {
+				...metadata,
+				chunkIndex,
+				startIndex,
+				endIndex: startIndex + content.length
+			}
+		};
+	}
+	return {
+		chunk,
+		config
+	};
+}
+function splitFixed(text, size, overlap) {
+	const chunks = [];
+	const effectiveOverlap = Math.min(overlap, size - 1);
+	const step = Math.max(1, size - effectiveOverlap);
+	if (size <= 0) return text ? [text] : [];
+	let start = 0;
+	while (start < text.length) {
+		chunks.push(text.slice(start, start + size));
+		start += step;
+	}
+	return chunks;
+}
+function splitBySentence(text) {
+	return text.split(/(?<=[.!?])\s+/).filter((s) => s.trim().length > 0);
+}
+function splitByParagraph(text) {
+	return text.split(/\n\n+/).filter((p) => p.trim().length > 0);
+}
+function splitSemantic(text, targetSize) {
+	const sentences = splitBySentence(text);
+	const result = [];
+	let current = "";
+	for (const sentence of sentences) if (current.length + sentence.length <= targetSize * 1.2) current += (current ? " " : "") + sentence;
+	else {
+		if (current) result.push(current);
+		current = sentence;
+	}
+	if (current) result.push(current);
+	return result;
+}
+/**
+* Creates an embedding generator wrapper.
+*
+* @example
+* ```typescript
+* const embedder = createEmbedder({
+*   model: openaiEmbedding,
+*   batchSize: 100,
+*   cache: embeddingCache
+* });
+*
+* const chunks = await embedder.embedChunks(textChunks);
+* ```
+*/
+function createEmbedder(options) {
+	const { model, batchSize = 100, cache, onProgress } = options;
+	async function embed(text) {
+		const cacheKey = hashText(text);
+		const cached = cache?.get(cacheKey);
+		if (cached) return cached;
+		const embedding = await model.embed(text);
+		if (cache) cache.set(cacheKey, embedding);
+		return embedding;
+	}
+	async function embedBatch(texts) {
+		const results = new Array(texts.length);
+		const toEmbed = [];
+		texts.forEach((text, index) => {
+			const cacheKey = hashText(text);
+			const cached = cache?.get(cacheKey);
+			if (cached) results[index] = cached;
+			else toEmbed.push({
+				index,
+				text
+			});
+		});
+		for (let i = 0; i < toEmbed.length; i += batchSize) {
+			const batch = toEmbed.slice(i, i + batchSize);
+			const embeddings = await model.embedBatch(batch.map((b) => b.text));
+			batch.forEach((item, j) => {
+				const embedding = embeddings[j];
+				if (embedding) {
+					results[item.index] = embedding;
+					if (cache) cache.set(hashText(item.text), embedding);
+				}
+			});
+			onProgress?.(Math.min(i + batchSize, toEmbed.length), toEmbed.length);
+		}
+		for (let i = 0; i < results.length; i++) if (!results[i]) throw new Error(`Embedding failed for text at index ${i}: incomplete batch response`);
+		return results;
+	}
+	async function embedChunks(chunks) {
+		const embeddings = await embedBatch(chunks.map((c) => c.content));
+		return chunks.map((chunk, i) => ({
+			...chunk,
+			embedding: embeddings[i]
+		}));
+	}
+	return {
+		embed,
+		embedBatch,
+		embedChunks,
+		dimensions: model.dimensions,
+		modelId: model.modelId
+	};
+}
+/**
+* Simple djb2-style hash for cache keys.
+* Note: For production caches with millions of entries, consider using
+* a stronger hash (SHA-256) to reduce collision probability.
+*/
+function hashText(text) {
+	let hash = 0;
+	for (let i = 0; i < text.length; i++) {
+		const char = text.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+		hash = hash & hash;
+	}
+	return `embed-${hash}`;
+}
+/**
+* Calculates cosine similarity between two vectors.
+*/
+function cosineSimilarity(a, b) {
+	if (a.length !== b.length) throw new Error("Vectors must have same dimensions");
+	let dotProduct = 0;
+	let normA = 0;
+	let normB = 0;
+	for (let i = 0; i < a.length; i++) {
+		const aVal = a[i] ?? 0;
+		const bVal = b[i] ?? 0;
+		dotProduct += aVal * bVal;
+		normA += aVal * aVal;
+		normB += bVal * bVal;
+	}
+	if (normA === 0 || normB === 0) return 0;
+	return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+/**
+* Creates an in-memory vector store.
+*
+* @example
+* ```typescript
+* const store = createInMemoryVectorStore();
+*
+* await store.upsert(embeddedChunks);
+* const results = await store.search(queryEmbedding, { topK: 5 });
+* ```
+*/
+function createInMemoryVectorStore() {
+	const chunks = /* @__PURE__ */ new Map();
+	async function upsert(newChunks) {
+		for (const chunk of newChunks) chunks.set(chunk.id, chunk);
+	}
+	async function search(embedding, options) {
+		const { topK = 10, minScore = 0 } = options ?? {};
+		const results = [];
+		for (const chunk of chunks.values()) {
+			if (!chunk.embedding) continue;
+			const score = cosineSimilarity(embedding, chunk.embedding);
+			if (score >= minScore) results.push({
+				chunk,
+				score,
+				rank: 0
+			});
+		}
+		results.sort((a, b) => b.score - a.score);
+		return results.slice(0, topK).map((r, i) => ({
+			...r,
+			rank: i + 1
+		}));
+	}
+	async function deleteChunks(ids) {
+		for (const id of ids) chunks.delete(id);
+	}
+	async function clear() {
+		chunks.clear();
+	}
+	return {
+		upsert,
+		search,
+		delete: deleteChunks,
+		clear
+	};
+}
+/**
+* Creates a RAG pipeline for retrieval-augmented generation.
+*
+* @example
+* ```typescript
+* const rag = createRAGPipeline({
+*   embedder,
+*   vectorStore,
+*   topK: 5,
+*   maxTokens: 2000
+* });
+*
+* const context = await rag.retrieve('What is the capital of France?');
+* const prompt = rag.buildPrompt(context, 'Answer the question based on context.');
+* ```
+*/
+function createRAGPipeline(options) {
+	const { embedder, vectorStore, topK = 5, maxTokens = 2e3, minScore = .5 } = options;
+	async function ingest(documents, chunker) {
+		const allChunks = [];
+		for (const doc of documents) {
+			const chunks = chunker.chunk(doc.content, {
+				sourceId: doc.id,
+				...doc.metadata
+			});
+			allChunks.push(...chunks);
+		}
+		const embeddedChunks = await embedder.embedChunks(allChunks);
+		await vectorStore.upsert(embeddedChunks);
+	}
+	async function retrieve(query) {
+		const queryEmbedding = await embedder.embed(query);
+		const results = await vectorStore.search(queryEmbedding, {
+			topK,
+			minScore
+		});
+		let formattedContext = "";
+		let totalTokens = 0;
+		const estimateTokens = (text) => Math.ceil(text.length / 4);
+		for (const result of results) {
+			const chunkText = result.chunk.content;
+			const chunkTokens = estimateTokens(chunkText);
+			if (totalTokens + chunkTokens > maxTokens) break;
+			formattedContext += `[Source: ${result.chunk.metadata.sourceId ?? "unknown"}, Relevance: ${result.score.toFixed(2)}]\n${chunkText}\n\n`;
+			totalTokens += chunkTokens;
+		}
+		return {
+			query,
+			results,
+			totalTokens,
+			formattedContext: formattedContext.trim()
+		};
+	}
+	function buildPrompt(context, systemPrompt) {
+		return `${systemPrompt ?? "Answer the question based on the provided context."}
+
+Context:
+${context.formattedContext}
+
+Question: ${context.query}
+
+Answer:`;
+	}
+	return {
+		ingest,
+		retrieve,
+		buildPrompt
+	};
+}
+/**
+* Quick single-text embedding using AI SDK's embed function.
+*
+* @param model - AI SDK embedding model instance
+* @param value - Text to embed
+* @param options - Optional configuration
+* @returns Embed result from AI SDK
+*
+* @example
+* ```ts
+* import { openai } from '@ai-sdk/openai';
+* import { embedText } from '@od-oneapp/ai-platform/grounding/embed';
+*
+* const result = await embedText(
+*   openai.embedding('text-embedding-3-small'),
+*   'Hello world',
+* );
+* console.log(result.embedding); // number[]
+* ```
+*/
+async function embedText(model, value, options) {
+	return embed({
+		model,
+		value,
+		maxRetries: options?.maxRetries ?? 2
+	});
+}
+/**
+* Quick batch embedding using AI SDK's embedMany function.
+*
+* @param model - AI SDK embedding model instance
+* @param values - Array of texts to embed
+* @param options - Optional configuration
+* @returns EmbedMany result from AI SDK
+*
+* @example
+* ```ts
+* import { openai } from '@ai-sdk/openai';
+* import { embedBatch } from '@od-oneapp/ai-platform/grounding/embed';
+*
+* const result = await embedBatch(
+*   openai.embedding('text-embedding-3-small'),
+*   ['Hello', 'World'],
+* );
+* console.log(result.embeddings); // number[][]
+* ```
+*/
+async function embedBatch(model, values, options) {
+	return embedMany({
+		model,
+		values,
+		maxParallelCalls: options?.maxParallelCalls ?? 2
+	});
+}
+/**
+* Calculate similarity between two texts by embedding them and computing cosine similarity.
+*
+* @param model - AI SDK embedding model instance
+* @param text1 - First text
+* @param text2 - Second text
+* @returns Cosine similarity score between -1 and 1
+*
+* @example
+* ```ts
+* import { openai } from '@ai-sdk/openai';
+* import { calculateTextSimilarity } from '@od-oneapp/ai-platform/grounding/embed';
+*
+* const score = await calculateTextSimilarity(
+*   openai.embedding('text-embedding-3-small'),
+*   'The cat sat on the mat',
+*   'A feline rested on a rug',
+* );
+* console.log(score); // 0.85 (high similarity)
+* ```
+*/
+async function calculateTextSimilarity(model, text1, text2) {
+	const [{ embedding: e1 }, { embedding: e2 }] = await Promise.all([embedText(model, text1), embedText(model, text2)]);
+	return cosineSimilarity$1(e1, e2);
+}
+
+//#endregion
+export { calculateMRR, calculateNDCG, calculateTextSimilarity, cosineSimilarity, createChunker, createCohereReranker, createCrossEncoderReranker, createEmbedder, createInMemoryVectorStore, createRAGPipeline, createRerankPipeline, embedBatch, embedText, reciprocalRankFusion, vectorResultsToDocuments };
+//# sourceMappingURL=grounding-embed.mjs.map

package/dist/grounding-embed.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding-embed.mjs","names":["sdkEmbed","sdkEmbedMany","sdkCosineSimilarity"],"sources":["../src/grounding/embed/index.ts"],"sourcesContent":["/**\n * Embeddings & RAG Module\n *\n * Retrieval-Augmented Generation patterns:\n * - Text chunking strategies\n * - Embedding generation\n * - Similarity search\n * - RAG pipeline orchestration\n *\n * @module embeddings\n */\n\n// -----------------------------------------------------------------------------\n// Types\n// -----------------------------------------------------------------------------\n\n/** Text chunk with metadata */\nexport interface TextChunk {\n  readonly id: string;\n  readonly content: string;\n  readonly metadata: ChunkMetadata;\n  embedding?: number[];\n}\n\n/** Chunk metadata */\nexport interface ChunkMetadata {\n  readonly sourceId?: string;\n  readonly sourceName?: string;\n  readonly startIndex?: number;\n  readonly endIndex?: number;\n  readonly chunkIndex?: number;\n  readonly totalChunks?: number;\n  readonly [key: string]: unknown;\n}\n\n/** Chunking strategy */\nexport type ChunkingStrategy = 'fixed' | 'sentence' | 'paragraph' | 'semantic';\n\n/** Chunking configuration */\nexport interface ChunkingConfig {\n  readonly strategy: ChunkingStrategy;\n  readonly chunkSize: number;\n  readonly chunkOverlap: number;\n  readonly minChunkSize?: number;\n}\n\n/** Embedding model interface */\nexport interface EmbeddingModel {\n  embed: (text: string) => Promise<number[]>;\n  embedBatch: (texts: string[]) => Promise<number[][]>;\n  readonly dimensions: number;\n  readonly modelId: string;\n}\n\n/** Search result */\nexport interface SearchResult {\n  readonly chunk: TextChunk;\n  readonly score: number;\n  readonly rank: number;\n}\n\n/** RAG context */\nexport interface RAGContext {\n  readonly query: string;\n  readonly results: SearchResult[];\n  readonly totalTokens: number;\n  formattedContext: string;\n}\n\n/** Vector store interface */\nexport interface VectorStore {\n  upsert: (chunks: TextChunk[]) => Promise<void>;\n  search: (embedding: number[], options?: SearchOptions) => Promise<SearchResult[]>;\n  delete: (ids: string[]) => Promise<void>;\n  clear: () => Promise<void>;\n}\n\n/** Search options */\nexport interface SearchOptions {\n  readonly topK?: number;\n  readonly minScore?: number;\n  readonly filter?: Record<string, unknown>;\n}\n\n// -----------------------------------------------------------------------------\n// Text Chunking\n// -----------------------------------------------------------------------------\n\n/**\n * Creates a text chunker with configurable strategy.\n *\n * @example\n * ```typescript\n * const chunker = createChunker({\n *   strategy: 'paragraph',\n *   chunkSize: 500,\n *   chunkOverlap: 50\n * });\n *\n * const chunks = chunker.chunk(longText, { sourceId: 'doc-1' });\n * ```\n */\nexport function createChunker(config: ChunkingConfig): Chunker {\n  const { strategy, chunkSize, chunkOverlap, minChunkSize = 50 } = config;\n\n  function chunk(text: string, metadata?: Partial<ChunkMetadata>): TextChunk[] {\n    const chunks: TextChunk[] = [];\n    let segments: string[];\n\n    switch (strategy) {\n      case 'sentence':\n        segments = splitBySentence(text);\n        break;\n      case 'paragraph':\n        segments = splitByParagraph(text);\n        break;\n      case 'semantic':\n        segments = splitSemantic(text, chunkSize);\n        break;\n      case 'fixed':\n        segments = splitFixed(text, chunkSize, chunkOverlap);\n        break;\n      default: {\n        const exhaustiveCheck: never = strategy;\n        throw new Error(`Unsupported chunking strategy: ${exhaustiveCheck}`);\n      }\n    }\n\n    // Combine small segments and split large ones\n    let currentChunk = '';\n    let startIndex = 0;\n    let chunkIndex = 0;\n\n    for (let i = 0; i < segments.length; i++) {\n      const segment = segments[i] ?? '';\n\n      if (currentChunk.length + segment.length <= chunkSize) {\n        currentChunk += (currentChunk ? ' ' : '') + segment;\n      } else {\n        if (currentChunk.length >= minChunkSize) {\n          chunks.push(createChunk(currentChunk, chunkIndex++, startIndex, metadata));\n          startIndex += currentChunk.length;\n        }\n\n        // Handle segments larger than chunkSize\n        if (segment.length > chunkSize) {\n          const subChunks = splitFixed(segment, chunkSize, chunkOverlap);\n          for (const sub of subChunks) {\n            if (sub.length >= minChunkSize) {\n              chunks.push(createChunk(sub, chunkIndex++, startIndex, metadata));\n              startIndex += sub.length;\n            }\n          }\n          currentChunk = '';\n        } else {\n          currentChunk = segment;\n        }\n      }\n    }\n\n    // Add remaining chunk\n    if (currentChunk.length >= minChunkSize) {\n      chunks.push(createChunk(currentChunk, chunkIndex++, startIndex, metadata));\n    }\n\n    // Update total chunks\n    const totalChunks = chunks.length;\n    return chunks.map(c => ({\n      ...c,\n      metadata: { ...c.metadata, totalChunks },\n    }));\n  }\n\n  function createChunk(\n    content: string,\n    chunkIndex: number,\n    startIndex: number,\n    metadata?: Partial<ChunkMetadata>,\n  ): TextChunk {\n    // Add randomness to prevent ID collisions across concurrent calls\n    const uniqueSuffix = Math.random().toString(36).slice(2, 8);\n    return {\n      id: `chunk-${Date.now()}-${chunkIndex}-${uniqueSuffix}`,\n      content: content.trim(),\n      metadata: {\n        ...metadata,\n        chunkIndex,\n        startIndex,\n        endIndex: startIndex + content.length,\n      },\n    };\n  }\n\n  return { chunk, config };\n}\n\nexport interface Chunker {\n  chunk: (text: string, metadata?: Partial<ChunkMetadata>) => TextChunk[];\n  config: ChunkingConfig;\n}\n\n// Chunking helpers\nfunction splitFixed(text: string, size: number, overlap: number): string[] {\n  const chunks: string[] = [];\n\n  // Guard against invalid overlap that would cause infinite loop\n  const effectiveOverlap = Math.min(overlap, size - 1);\n  const step = Math.max(1, size - effectiveOverlap);\n\n  if (size <= 0) {\n    return text ? [text] : [];\n  }\n\n  let start = 0;\n\n  while (start < text.length) {\n    chunks.push(text.slice(start, start + size));\n    start += step;\n  }\n\n  return chunks;\n}\n\nfunction splitBySentence(text: string): string[] {\n  return text.split(/(?<=[.!?])\\s+/).filter(s => s.trim().length > 0);\n}\n\nfunction splitByParagraph(text: string): string[] {\n  return text.split(/\\n\\n+/).filter(p => p.trim().length > 0);\n}\n\nfunction splitSemantic(text: string, targetSize: number): string[] {\n  // Simplified semantic splitting - prefer sentence boundaries within target size\n  const sentences = splitBySentence(text);\n  const result: string[] = [];\n  let current = '';\n\n  for (const sentence of sentences) {\n    if (current.length + sentence.length <= targetSize * 1.2) {\n      current += (current ? ' ' : '') + sentence;\n    } else {\n      if (current) result.push(current);\n      current = sentence;\n    }\n  }\n\n  if (current) result.push(current);\n  return result;\n}\n\n// -----------------------------------------------------------------------------\n// Embedding Generator\n// -----------------------------------------------------------------------------\n\n/**\n * Creates an embedding generator wrapper.\n *\n * @example\n * ```typescript\n * const embedder = createEmbedder({\n *   model: openaiEmbedding,\n *   batchSize: 100,\n *   cache: embeddingCache\n * });\n *\n * const chunks = await embedder.embedChunks(textChunks);\n * ```\n */\nexport function createEmbedder(options: {\n  model: EmbeddingModel;\n  batchSize?: number;\n  cache?: Map<string, number[]>;\n  onProgress?: (processed: number, total: number) => void;\n}): Embedder {\n  const { model, batchSize = 100, cache, onProgress } = options;\n\n  async function embed(text: string): Promise<number[]> {\n    const cacheKey = hashText(text);\n\n    const cached = cache?.get(cacheKey);\n    if (cached) {\n      return cached;\n    }\n\n    const embedding = await model.embed(text);\n\n    if (cache) {\n      cache.set(cacheKey, embedding);\n    }\n\n    return embedding;\n  }\n\n  async function embedBatch(texts: string[]): Promise<number[][]> {\n    const results: number[][] = new Array(texts.length);\n    const toEmbed: { index: number; text: string }[] = [];\n\n    // Check cache first\n    texts.forEach((text, index) => {\n      const cacheKey = hashText(text);\n      const cached = cache?.get(cacheKey);\n      if (cached) {\n        results[index] = cached;\n      } else {\n        toEmbed.push({ index, text });\n      }\n    });\n\n    // Embed uncached in batches\n    for (let i = 0; i < toEmbed.length; i += batchSize) {\n      const batch = toEmbed.slice(i, i + batchSize);\n      const embeddings = await model.embedBatch(batch.map(b => b.text));\n\n      batch.forEach((item, j) => {\n        const embedding = embeddings[j];\n        if (embedding) {\n          results[item.index] = embedding;\n          if (cache) {\n            cache.set(hashText(item.text), embedding);\n          }\n        }\n      });\n\n      onProgress?.(Math.min(i + batchSize, toEmbed.length), toEmbed.length);\n    }\n\n    // Validate all embeddings were populated (no sparse array holes)\n    for (let i = 0; i < results.length; i++) {\n      if (!results[i]) {\n        throw new Error(`Embedding failed for text at index ${i}: incomplete batch response`);\n      }\n    }\n\n    return results;\n  }\n\n  async function embedChunks(chunks: TextChunk[]): Promise<TextChunk[]> {\n    const texts = chunks.map(c => c.content);\n    const embeddings = await embedBatch(texts);\n\n    return chunks.map((chunk, i) => ({\n      ...chunk,\n      embedding: embeddings[i],\n    }));\n  }\n\n  return {\n    embed,\n    embedBatch,\n    embedChunks,\n    dimensions: model.dimensions,\n    modelId: model.modelId,\n  };\n}\n\nexport interface Embedder {\n  embed: (text: string) => Promise<number[]>;\n  embedBatch: (texts: string[]) => Promise<number[][]>;\n  embedChunks: (chunks: TextChunk[]) => Promise<TextChunk[]>;\n  readonly dimensions: number;\n  readonly modelId: string;\n}\n\n/**\n * Simple djb2-style hash for cache keys.\n * Note: For production caches with millions of entries, consider using\n * a stronger hash (SHA-256) to reduce collision probability.\n */\nfunction hashText(text: string): string {\n  let hash = 0;\n  for (let i = 0; i < text.length; i++) {\n    const char = text.charCodeAt(i);\n    hash = (hash << 5) - hash + char;\n    hash = hash & hash;\n  }\n  return `embed-${hash}`;\n}\n\n// -----------------------------------------------------------------------------\n// Similarity Search\n// -----------------------------------------------------------------------------\n\n/**\n * Calculates cosine similarity between two vectors.\n */\nexport function cosineSimilarity(a: number[], b: number[]): number {\n  if (a.length !== b.length) {\n    throw new Error('Vectors must have same dimensions');\n  }\n\n  let dotProduct = 0;\n  let normA = 0;\n  let normB = 0;\n\n  for (let i = 0; i < a.length; i++) {\n    const aVal = a[i] ?? 0;\n    const bVal = b[i] ?? 0;\n    dotProduct += aVal * bVal;\n    normA += aVal * aVal;\n    normB += bVal * bVal;\n  }\n\n  if (normA === 0 || normB === 0) return 0;\n  return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));\n}\n\n/**\n * Creates an in-memory vector store.\n *\n * @example\n * ```typescript\n * const store = createInMemoryVectorStore();\n *\n * await store.upsert(embeddedChunks);\n * const results = await store.search(queryEmbedding, { topK: 5 });\n * ```\n */\nexport function createInMemoryVectorStore(): VectorStore {\n  const chunks = new Map<string, TextChunk>();\n\n  async function upsert(newChunks: TextChunk[]): Promise<void> {\n    for (const chunk of newChunks) {\n      chunks.set(chunk.id, chunk);\n    }\n  }\n\n  async function search(embedding: number[], options?: SearchOptions): Promise<SearchResult[]> {\n    const { topK = 10, minScore = 0 } = options ?? {};\n\n    const results: SearchResult[] = [];\n\n    for (const chunk of chunks.values()) {\n      if (!chunk.embedding) continue;\n\n      const score = cosineSimilarity(embedding, chunk.embedding);\n\n      if (score >= minScore) {\n        results.push({ chunk, score, rank: 0 });\n      }\n    }\n\n    // Sort by score descending\n    results.sort((a, b) => b.score - a.score);\n\n    // Take top K and assign ranks\n    return results.slice(0, topK).map((r, i) => ({ ...r, rank: i + 1 }));\n  }\n\n  async function deleteChunks(ids: string[]): Promise<void> {\n    for (const id of ids) {\n      chunks.delete(id);\n    }\n  }\n\n  async function clear(): Promise<void> {\n    chunks.clear();\n  }\n\n  return {\n    upsert,\n    search,\n    delete: deleteChunks,\n    clear,\n  };\n}\n\n// -----------------------------------------------------------------------------\n// RAG Pipeline\n// -----------------------------------------------------------------------------\n\n/**\n * Creates a RAG pipeline for retrieval-augmented generation.\n *\n * @example\n * ```typescript\n * const rag = createRAGPipeline({\n *   embedder,\n *   vectorStore,\n *   topK: 5,\n *   maxTokens: 2000\n * });\n *\n * const context = await rag.retrieve('What is the capital of France?');\n * const prompt = rag.buildPrompt(context, 'Answer the question based on context.');\n * ```\n */\nexport function createRAGPipeline(options: {\n  embedder: Embedder;\n  vectorStore: VectorStore;\n  topK?: number;\n  maxTokens?: number;\n  minScore?: number;\n}): RAGPipeline {\n  const { embedder, vectorStore, topK = 5, maxTokens = 2000, minScore = 0.5 } = options;\n\n  async function ingest(\n    documents: { id: string; content: string; metadata?: Record<string, unknown> }[],\n    chunker: Chunker,\n  ): Promise<void> {\n    const allChunks: TextChunk[] = [];\n\n    for (const doc of documents) {\n      const chunks = chunker.chunk(doc.content, {\n        sourceId: doc.id,\n        ...doc.metadata,\n      });\n      allChunks.push(...chunks);\n    }\n\n    const embeddedChunks = await embedder.embedChunks(allChunks);\n    await vectorStore.upsert(embeddedChunks);\n  }\n\n  async function retrieve(query: string): Promise<RAGContext> {\n    const queryEmbedding = await embedder.embed(query);\n    const results = await vectorStore.search(queryEmbedding, { topK, minScore });\n\n    // Build formatted context\n    let formattedContext = '';\n    let totalTokens = 0;\n    const estimateTokens = (text: string) => Math.ceil(text.length / 4);\n\n    for (const result of results) {\n      const chunkText = result.chunk.content;\n      const chunkTokens = estimateTokens(chunkText);\n\n      if (totalTokens + chunkTokens > maxTokens) break;\n\n      formattedContext +=\n        `[Source: ${result.chunk.metadata.sourceId ?? 'unknown'}, ` +\n        `Relevance: ${result.score.toFixed(2)}]\\n` +\n        `${chunkText}\\n\\n`;\n      totalTokens += chunkTokens;\n    }\n\n    return {\n      query,\n      results,\n      totalTokens,\n      formattedContext: formattedContext.trim(),\n    };\n  }\n\n  function buildPrompt(context: RAGContext, systemPrompt?: string): string {\n    const system = systemPrompt ?? 'Answer the question based on the provided context.';\n\n    return `${system}\n\nContext:\n${context.formattedContext}\n\nQuestion: ${context.query}\n\nAnswer:`;\n  }\n\n  return {\n    ingest,\n    retrieve,\n    buildPrompt,\n  };\n}\n\nexport interface RAGPipeline {\n  ingest: (\n    documents: { id: string; content: string; metadata?: Record<string, unknown> }[],\n    chunker: Chunker,\n  ) => Promise<void>;\n  retrieve: (query: string) => Promise<RAGContext>;\n  buildPrompt: (context: RAGContext, systemPrompt?: string) => string;\n}\n\n// -----------------------------------------------------------------------------\n// Reranking\n// -----------------------------------------------------------------------------\n\nexport {\n  // Reranker factories\n  createCohereReranker,\n  createCrossEncoderReranker,\n  // Pipelines and utilities\n  createRerankPipeline,\n  reciprocalRankFusion,\n  vectorResultsToDocuments,\n  calculateNDCG,\n  calculateMRR,\n  // Types\n  type RerankDocument,\n  type RerankResult,\n  type RerankOptions,\n  type RerankProvider,\n  type CohereRerankConfig,\n  type CrossEncoderConfig,\n  type RerankPipelineConfig,\n} from './reranking';\n\n// -----------------------------------------------------------------------------\n// AI SDK Quick Embed Helpers (migrated from @repo/ai)\n// -----------------------------------------------------------------------------\n\nimport {\n  embed as sdkEmbed,\n  embedMany as sdkEmbedMany,\n  cosineSimilarity as sdkCosineSimilarity,\n} from '../../shared';\n\nimport type { SDKEmbeddingModel } from '../../shared';\n\n/**\n * Quick single-text embedding using AI SDK's embed function.\n *\n * @param model - AI SDK embedding model instance\n * @param value - Text to embed\n * @param options - Optional configuration\n * @returns Embed result from AI SDK\n *\n * @example\n * ```ts\n * import { openai } from '@ai-sdk/openai';\n * import { embedText } from '@od-oneapp/ai-platform/grounding/embed';\n *\n * const result = await embedText(\n *   openai.embedding('text-embedding-3-small'),\n *   'Hello world',\n * );\n * console.log(result.embedding); // number[]\n * ```\n */\nexport async function embedText(\n  model: SDKEmbeddingModel,\n  value: string,\n  options?: { maxRetries?: number },\n) {\n  return sdkEmbed({\n    model,\n    value,\n    maxRetries: options?.maxRetries ?? 2,\n  });\n}\n\n/**\n * Quick batch embedding using AI SDK's embedMany function.\n *\n * @param model - AI SDK embedding model instance\n * @param values - Array of texts to embed\n * @param options - Optional configuration\n * @returns EmbedMany result from AI SDK\n *\n * @example\n * ```ts\n * import { openai } from '@ai-sdk/openai';\n * import { embedBatch } from '@od-oneapp/ai-platform/grounding/embed';\n *\n * const result = await embedBatch(\n *   openai.embedding('text-embedding-3-small'),\n *   ['Hello', 'World'],\n * );\n * console.log(result.embeddings); // number[][]\n * ```\n */\nexport async function embedBatch(\n  model: SDKEmbeddingModel,\n  values: string[],\n  options?: { maxParallelCalls?: number },\n) {\n  return sdkEmbedMany({\n    model,\n    values,\n    maxParallelCalls: options?.maxParallelCalls ?? 2,\n  });\n}\n\n/**\n * Calculate similarity between two texts by embedding them and computing cosine similarity.\n *\n * @param model - AI SDK embedding model instance\n * @param text1 - First text\n * @param text2 - Second text\n * @returns Cosine similarity score between -1 and 1\n *\n * @example\n * ```ts\n * import { openai } from '@ai-sdk/openai';\n * import { calculateTextSimilarity } from '@od-oneapp/ai-platform/grounding/embed';\n *\n * const score = await calculateTextSimilarity(\n *   openai.embedding('text-embedding-3-small'),\n *   'The cat sat on the mat',\n *   'A feline rested on a rug',\n * );\n * console.log(score); // 0.85 (high similarity)\n * ```\n */\nexport async function calculateTextSimilarity(\n  model: SDKEmbeddingModel,\n  text1: string,\n  text2: string,\n): Promise<number> {\n  const [{ embedding: e1 }, { embedding: e2 }] = await Promise.all([\n    embedText(model, text1),\n    embedText(model, text2),\n  ]);\n  return sdkCosineSimilarity(e1, e2);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAsGA,SAAgB,cAAc,QAAiC;CAC7D,MAAM,EAAE,UAAU,WAAW,cAAc,eAAe,OAAO;CAEjE,SAAS,MAAM,MAAc,UAAgD;EAC3E,MAAM,SAAsB,EAAE;EAC9B,IAAI;AAEJ,UAAQ,UAAR;GACE,KAAK;AACH,eAAW,gBAAgB,KAAK;AAChC;GACF,KAAK;AACH,eAAW,iBAAiB,KAAK;AACjC;GACF,KAAK;AACH,eAAW,cAAc,MAAM,UAAU;AACzC;GACF,KAAK;AACH,eAAW,WAAW,MAAM,WAAW,aAAa;AACpD;GACF,SAAS;IACP,MAAM,kBAAyB;AAC/B,UAAM,IAAI,MAAM,kCAAkC,kBAAkB;;;EAKxE,IAAI,eAAe;EACnB,IAAI,aAAa;EACjB,IAAI,aAAa;AAEjB,OAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK;GACxC,MAAM,UAAU,SAAS,MAAM;AAE/B,OAAI,aAAa,SAAS,QAAQ,UAAU,UAC1C,kBAAiB,eAAe,MAAM,MAAM;QACvC;AACL,QAAI,aAAa,UAAU,cAAc;AACvC,YAAO,KAAK,YAAY,cAAc,cAAc,YAAY,SAAS,CAAC;AAC1E,mBAAc,aAAa;;AAI7B,QAAI,QAAQ,SAAS,WAAW;KAC9B,MAAM,YAAY,WAAW,SAAS,WAAW,aAAa;AAC9D,UAAK,MAAM,OAAO,UAChB,KAAI,IAAI,UAAU,cAAc;AAC9B,aAAO,KAAK,YAAY,KAAK,cAAc,YAAY,SAAS,CAAC;AACjE,oBAAc,IAAI;;AAGtB,oBAAe;UAEf,gBAAe;;;AAMrB,MAAI,aAAa,UAAU,aACzB,QAAO,KAAK,YAAY,cAAc,cAAc,YAAY,SAAS,CAAC;EAI5E,MAAM,cAAc,OAAO;AAC3B,SAAO,OAAO,KAAI,OAAM;GACtB,GAAG;GACH,UAAU;IAAE,GAAG,EAAE;IAAU;IAAa;GACzC,EAAE;;CAGL,SAAS,YACP,SACA,YACA,YACA,UACW;EAEX,MAAM,eAAe,KAAK,QAAQ,CAAC,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE;AAC3D,SAAO;GACL,IAAI,SAAS,KAAK,KAAK,CAAC,GAAG,WAAW,GAAG;GACzC,SAAS,QAAQ,MAAM;GACvB,UAAU;IACR,GAAG;IACH;IACA;IACA,UAAU,aAAa,QAAQ;IAChC;GACF;;AAGH,QAAO;EAAE;EAAO;EAAQ;;AAS1B,SAAS,WAAW,MAAc,MAAc,SAA2B;CACzE,MAAM,SAAmB,EAAE;CAG3B,MAAM,mBAAmB,KAAK,IAAI,SAAS,OAAO,EAAE;CACpD,MAAM,OAAO,KAAK,IAAI,GAAG,OAAO,iBAAiB;AAEjD,KAAI,QAAQ,EACV,QAAO,OAAO,CAAC,KAAK,GAAG,EAAE;CAG3B,IAAI,QAAQ;AAEZ,QAAO,QAAQ,KAAK,QAAQ;AAC1B,SAAO,KAAK,KAAK,MAAM,OAAO,QAAQ,KAAK,CAAC;AAC5C,WAAS;;AAGX,QAAO;;AAGT,SAAS,gBAAgB,MAAwB;AAC/C,QAAO,KAAK,MAAM,gBAAgB,CAAC,QAAO,MAAK,EAAE,MAAM,CAAC,SAAS,EAAE;;AAGrE,SAAS,iBAAiB,MAAwB;AAChD,QAAO,KAAK,MAAM,QAAQ,CAAC,QAAO,MAAK,EAAE,MAAM,CAAC,SAAS,EAAE;;AAG7D,SAAS,cAAc,MAAc,YAA8B;CAEjE,MAAM,YAAY,gBAAgB,KAAK;CACvC,MAAM,SAAmB,EAAE;CAC3B,IAAI,UAAU;AAEd,MAAK,MAAM,YAAY,UACrB,KAAI,QAAQ,SAAS,SAAS,UAAU,aAAa,IACnD,aAAY,UAAU,MAAM,MAAM;MAC7B;AACL,MAAI,QAAS,QAAO,KAAK,QAAQ;AACjC,YAAU;;AAId,KAAI,QAAS,QAAO,KAAK,QAAQ;AACjC,QAAO;;;;;;;;;;;;;;;;AAqBT,SAAgB,eAAe,SAKlB;CACX,MAAM,EAAE,OAAO,YAAY,KAAK,OAAO,eAAe;CAEtD,eAAe,MAAM,MAAiC;EACpD,MAAM,WAAW,SAAS,KAAK;EAE/B,MAAM,SAAS,OAAO,IAAI,SAAS;AACnC,MAAI,OACF,QAAO;EAGT,MAAM,YAAY,MAAM,MAAM,MAAM,KAAK;AAEzC,MAAI,MACF,OAAM,IAAI,UAAU,UAAU;AAGhC,SAAO;;CAGT,eAAe,WAAW,OAAsC;EAC9D,MAAM,UAAsB,IAAI,MAAM,MAAM,OAAO;EACnD,MAAM,UAA6C,EAAE;AAGrD,QAAM,SAAS,MAAM,UAAU;GAC7B,MAAM,WAAW,SAAS,KAAK;GAC/B,MAAM,SAAS,OAAO,IAAI,SAAS;AACnC,OAAI,OACF,SAAQ,SAAS;OAEjB,SAAQ,KAAK;IAAE;IAAO;IAAM,CAAC;IAE/B;AAGF,OAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK,WAAW;GAClD,MAAM,QAAQ,QAAQ,MAAM,GAAG,IAAI,UAAU;GAC7C,MAAM,aAAa,MAAM,MAAM,WAAW,MAAM,KAAI,MAAK,EAAE,KAAK,CAAC;AAEjE,SAAM,SAAS,MAAM,MAAM;IACzB,MAAM,YAAY,WAAW;AAC7B,QAAI,WAAW;AACb,aAAQ,KAAK,SAAS;AACtB,SAAI,MACF,OAAM,IAAI,SAAS,KAAK,KAAK,EAAE,UAAU;;KAG7C;AAEF,gBAAa,KAAK,IAAI,IAAI,WAAW,QAAQ,OAAO,EAAE,QAAQ,OAAO;;AAIvE,OAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,IAClC,KAAI,CAAC,QAAQ,GACX,OAAM,IAAI,MAAM,sCAAsC,EAAE,6BAA6B;AAIzF,SAAO;;CAGT,eAAe,YAAY,QAA2C;EAEpE,MAAM,aAAa,MAAM,WADX,OAAO,KAAI,MAAK,EAAE,QAAQ,CACE;AAE1C,SAAO,OAAO,KAAK,OAAO,OAAO;GAC/B,GAAG;GACH,WAAW,WAAW;GACvB,EAAE;;AAGL,QAAO;EACL;EACA;EACA;EACA,YAAY,MAAM;EAClB,SAAS,MAAM;EAChB;;;;;;;AAgBH,SAAS,SAAS,MAAsB;CACtC,IAAI,OAAO;AACX,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACpC,MAAM,OAAO,KAAK,WAAW,EAAE;AAC/B,UAAQ,QAAQ,KAAK,OAAO;AAC5B,SAAO,OAAO;;AAEhB,QAAO,SAAS;;;;;AAUlB,SAAgB,iBAAiB,GAAa,GAAqB;AACjE,KAAI,EAAE,WAAW,EAAE,OACjB,OAAM,IAAI,MAAM,oCAAoC;CAGtD,IAAI,aAAa;CACjB,IAAI,QAAQ;CACZ,IAAI,QAAQ;AAEZ,MAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;EACjC,MAAM,OAAO,EAAE,MAAM;EACrB,MAAM,OAAO,EAAE,MAAM;AACrB,gBAAc,OAAO;AACrB,WAAS,OAAO;AAChB,WAAS,OAAO;;AAGlB,KAAI,UAAU,KAAK,UAAU,EAAG,QAAO;AACvC,QAAO,cAAc,KAAK,KAAK,MAAM,GAAG,KAAK,KAAK,MAAM;;;;;;;;;;;;;AAc1D,SAAgB,4BAAyC;CACvD,MAAM,yBAAS,IAAI,KAAwB;CAE3C,eAAe,OAAO,WAAuC;AAC3D,OAAK,MAAM,SAAS,UAClB,QAAO,IAAI,MAAM,IAAI,MAAM;;CAI/B,eAAe,OAAO,WAAqB,SAAkD;EAC3F,MAAM,EAAE,OAAO,IAAI,WAAW,MAAM,WAAW,EAAE;EAEjD,MAAM,UAA0B,EAAE;AAElC,OAAK,MAAM,SAAS,OAAO,QAAQ,EAAE;AACnC,OAAI,CAAC,MAAM,UAAW;GAEtB,MAAM,QAAQ,iBAAiB,WAAW,MAAM,UAAU;AAE1D,OAAI,SAAS,SACX,SAAQ,KAAK;IAAE;IAAO;IAAO,MAAM;IAAG,CAAC;;AAK3C,UAAQ,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM;AAGzC,SAAO,QAAQ,MAAM,GAAG,KAAK,CAAC,KAAK,GAAG,OAAO;GAAE,GAAG;GAAG,MAAM,IAAI;GAAG,EAAE;;CAGtE,eAAe,aAAa,KAA8B;AACxD,OAAK,MAAM,MAAM,IACf,QAAO,OAAO,GAAG;;CAIrB,eAAe,QAAuB;AACpC,SAAO,OAAO;;AAGhB,QAAO;EACL;EACA;EACA,QAAQ;EACR;EACD;;;;;;;;;;;;;;;;;;AAuBH,SAAgB,kBAAkB,SAMlB;CACd,MAAM,EAAE,UAAU,aAAa,OAAO,GAAG,YAAY,KAAM,WAAW,OAAQ;CAE9E,eAAe,OACb,WACA,SACe;EACf,MAAM,YAAyB,EAAE;AAEjC,OAAK,MAAM,OAAO,WAAW;GAC3B,MAAM,SAAS,QAAQ,MAAM,IAAI,SAAS;IACxC,UAAU,IAAI;IACd,GAAG,IAAI;IACR,CAAC;AACF,aAAU,KAAK,GAAG,OAAO;;EAG3B,MAAM,iBAAiB,MAAM,SAAS,YAAY,UAAU;AAC5D,QAAM,YAAY,OAAO,eAAe;;CAG1C,eAAe,SAAS,OAAoC;EAC1D,MAAM,iBAAiB,MAAM,SAAS,MAAM,MAAM;EAClD,MAAM,UAAU,MAAM,YAAY,OAAO,gBAAgB;GAAE;GAAM;GAAU,CAAC;EAG5E,IAAI,mBAAmB;EACvB,IAAI,cAAc;EAClB,MAAM,kBAAkB,SAAiB,KAAK,KAAK,KAAK,SAAS,EAAE;AAEnE,OAAK,MAAM,UAAU,SAAS;GAC5B,MAAM,YAAY,OAAO,MAAM;GAC/B,MAAM,cAAc,eAAe,UAAU;AAE7C,OAAI,cAAc,cAAc,UAAW;AAE3C,uBACE,YAAY,OAAO,MAAM,SAAS,YAAY,UAAU,eAC1C,OAAO,MAAM,QAAQ,EAAE,CAAC,KACnC,UAAU;AACf,kBAAe;;AAGjB,SAAO;GACL;GACA;GACA;GACA,kBAAkB,iBAAiB,MAAM;GAC1C;;CAGH,SAAS,YAAY,SAAqB,cAA+B;AAGvE,SAAO,GAFQ,gBAAgB,qDAEd;;;EAGnB,QAAQ,iBAAiB;;YAEf,QAAQ,MAAM;;;;AAKxB,QAAO;EACL;EACA;EACA;EACD;;;;;;;;;;;;;;;;;;;;;;AAoEH,eAAsB,UACpB,OACA,OACA,SACA;AACA,QAAOA,MAAS;EACd;EACA;EACA,YAAY,SAAS,cAAc;EACpC,CAAC;;;;;;;;;;;;;;;;;;;;;;AAuBJ,eAAsB,WACpB,OACA,QACA,SACA;AACA,QAAOC,UAAa;EAClB;EACA;EACA,kBAAkB,SAAS,oBAAoB;EAChD,CAAC;;;;;;;;;;;;;;;;;;;;;;;AAwBJ,eAAsB,wBACpB,OACA,OACA,OACiB;CACjB,MAAM,CAAC,EAAE,WAAW,MAAM,EAAE,WAAW,QAAQ,MAAM,QAAQ,IAAI,CAC/D,UAAU,OAAO,MAAM,EACvB,UAAU,OAAO,MAAM,CACxB,CAAC;AACF,QAAOC,mBAAoB,IAAI,GAAG"}

package/dist/grounding-hallucination.d.mts

@@ -0,0 +1,44 @@
+import { i as GroundingSource } from "./types-D3zJb59_.mjs";
+
+//#region src/grounding/hallucination/index.d.ts
+interface Claim {
+  text: string;
+  startIndex: number;
+  endIndex: number;
+}
+interface ClaimVerificationResult {
+  claim: Claim;
+  isSupported: boolean;
+  confidence: number;
+  supportingSources: string[];
+  explanation?: string;
+}
+interface HallucinationResult {
+  isHallucinated: boolean;
+  confidence: number;
+  unsupportedClaims: Claim[];
+  supportedClaims: Claim[];
+  verificationResults: ClaimVerificationResult[];
+  summary: string;
+}
+interface HallucinationDetectorOptions {
+  supportThreshold?: number;
+  extractClaims?: boolean;
+  claimExtractor?: (text: string) => Claim[];
+  similarityFn?: (claim: string, source: string) => number;
+}
+declare function extractClaims(text: string): Claim[];
+declare function calculateJaccardSimilarity(text1: string, text2: string): number;
+declare function verifyClaim(claim: Claim, sources: GroundingSource[], options?: {
+  threshold?: number;
+  similarityFn?: (a: string, b: string) => number;
+}): ClaimVerificationResult;
+declare function detectHallucinations(text: string, sources: GroundingSource[], options?: HallucinationDetectorOptions): Promise<HallucinationResult>;
+declare function createHallucinationDetector(options?: HallucinationDetectorOptions): {
+  detect: (text: string, sources: GroundingSource[]) => Promise<HallucinationResult>;
+  extractClaims: (text: string) => Claim[];
+  verifyClaim: (claim: Claim, sources: GroundingSource[]) => ClaimVerificationResult;
+};
+//#endregion
+export { Claim, ClaimVerificationResult, HallucinationDetectorOptions, HallucinationResult, calculateJaccardSimilarity, createHallucinationDetector, detectHallucinations, extractClaims, verifyClaim };
+//# sourceMappingURL=grounding-hallucination.d.mts.map

package/dist/grounding-hallucination.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding-hallucination.d.mts","names":[],"sources":["../src/grounding/hallucination/index.ts"],"mappings":";;;UAUiB,KAAA;EACf,IAAA;EACA,UAAA;EACA,QAAA;AAAA;AAAA,UAGe,uBAAA;EACf,KAAA,EAAO,KAAA;EACP,WAAA;EACA,UAAA;EACA,iBAAA;EACA,WAAA;AAAA;AAAA,UAGe,mBAAA;EACf,cAAA;EACA,UAAA;EACA,iBAAA,EAAmB,KAAA;EACnB,eAAA,EAAiB,KAAA;EACjB,mBAAA,EAAqB,uBAAA;EACrB,OAAA;AAAA;AAAA,UAGe,4BAAA;EAEf,gBAAA;EAEA,aAAA;EAEA,cAAA,IAAkB,IAAA,aAAiB,KAAA;EAEnC,YAAA,IAAgB,KAAA,UAAe,MAAA;AAAA;AAAA,iBAMjB,aAAA,CAAc,IAAA,WAAe,KAAA;AAAA,iBAsC7B,0BAAA,CAA2B,KAAA,UAAe,KAAA;AAAA,iBAsB1C,WAAA,CACd,KAAA,EAAO,KAAA,EACP,OAAA,EAAS,eAAA,IACT,OAAA;EAAW,SAAA;EAAoB,YAAA,IAAgB,CAAA,UAAW,CAAA;AAAA,IACzD,uBAAA;AAAA,iBA8CmB,oBAAA,CACpB,IAAA,UACA,OAAA,EAAS,eAAA,IACT,OAAA,GAAS,4BAAA,GACR,OAAA,CAAQ,mBAAA;AAAA,iBAkDK,2BAAA,CAA4B,OAAA,GAAS,4BAAA;yBAE5B,OAAA,EAAW,eAAA,OAAiB,OAAA,CAAA,mBAAA;mCA9KhB,KAAA;uBAiLZ,KAAA,EAAK,OAAA,EAAW,eAAA,OAAiB,uBAAA;AAAA"}

package/dist/grounding-hallucination.mjs

@@ -0,0 +1,115 @@
+//#region src/grounding/hallucination/index.ts
+/**
+* Extract factual claims from text using simple heuristics
+*/
+function extractClaims(text) {
+	const claims = [];
+	const sentencePattern = /[^.!?]+[.!?]+/g;
+	let match;
+	while ((match = sentencePattern.exec(text)) !== null) {
+		const sentence = match[0].trim();
+		if (sentence.endsWith("?") || /\b(I think|I believe|maybe|perhaps|might|could be|seems like)\b/i.test(sentence)) continue;
+		if (/\b\d+\b/.test(sentence) || /\b(is|are|was|were|has|have|will)\b/i.test(sentence) || /\b[A-Z][a-z]+\s[A-Z][a-z]+\b/.test(sentence)) claims.push({
+			text: sentence,
+			startIndex: match.index,
+			endIndex: match.index + sentence.length
+		});
+	}
+	return claims;
+}
+/**
+* Calculate text similarity using Jaccard index
+*/
+function calculateJaccardSimilarity(text1, text2) {
+	const normalize = (s) => s.toLowerCase().replace(/[^\w\s]/g, "").split(/\s+/).filter((w) => w.length > 2);
+	const words1 = new Set(normalize(text1));
+	const words2 = new Set(normalize(text2));
+	if (words1.size === 0 || words2.size === 0) return 0;
+	const intersection = new Set([...words1].filter((w) => words2.has(w)));
+	const union = new Set([...words1, ...words2]);
+	return intersection.size / union.size;
+}
+/**
+* Verify a single claim against sources
+*/
+function verifyClaim(claim, sources, options = {}) {
+	const { threshold = .3, similarityFn = calculateJaccardSimilarity } = options;
+	const supportingSources = [];
+	let maxSimilarity = 0;
+	for (const source of sources) {
+		const similarity = similarityFn(claim.text, source.content);
+		if (similarity > maxSimilarity) maxSimilarity = similarity;
+		if (similarity >= threshold) supportingSources.push(source.id);
+	}
+	const isSupported = supportingSources.length > 0;
+	return {
+		claim,
+		isSupported,
+		confidence: maxSimilarity,
+		supportingSources,
+		explanation: isSupported ? `Claim is supported by ${supportingSources.length} source(s)` : "No supporting evidence found in sources"
+	};
+}
+/**
+* Detect hallucinations in generated text by comparing against sources
+*
+* @example
+* ```ts
+* const result = await detectHallucinations(
+*   "The company was founded in 2020 and has 500 employees.",
+*   [{ id: "1", content: "Founded in 2019 with initial team of 10 people." }]
+* );
+*
+* if (result.isHallucinated) {
+*   console.log("Unsupported claims:", result.unsupportedClaims);
+* }
+* ```
+*/
+async function detectHallucinations(text, sources, options = {}) {
+	const { supportThreshold = .3, extractClaims: shouldExtract = true, claimExtractor = extractClaims, similarityFn = calculateJaccardSimilarity } = options;
+	const claims = shouldExtract ? claimExtractor(text) : [{
+		text,
+		startIndex: 0,
+		endIndex: text.length
+	}];
+	if (claims.length === 0) return {
+		isHallucinated: false,
+		confidence: 1,
+		unsupportedClaims: [],
+		supportedClaims: [],
+		verificationResults: [],
+		summary: "No factual claims detected in text"
+	};
+	const verificationResults = claims.map((claim) => verifyClaim(claim, sources, {
+		threshold: supportThreshold,
+		similarityFn
+	}));
+	const supportedClaims = verificationResults.filter((r) => r.isSupported).map((r) => r.claim);
+	const unsupportedClaims = verificationResults.filter((r) => !r.isSupported).map((r) => r.claim);
+	const isHallucinated = unsupportedClaims.length > 0;
+	return {
+		isHallucinated,
+		confidence: supportedClaims.length / claims.length,
+		unsupportedClaims,
+		supportedClaims,
+		verificationResults,
+		summary: isHallucinated ? `Found ${unsupportedClaims.length} unsupported claim(s) out of ${claims.length} total` : `All ${claims.length} claim(s) are supported by sources`
+	};
+}
+/**
+* Create a hallucination detector with custom configuration
+*/
+function createHallucinationDetector(options = {}) {
+	return {
+		detect: (text, sources) => detectHallucinations(text, sources, options),
+		extractClaims: options.claimExtractor ?? extractClaims,
+		verifyClaim: (claim, sources) => verifyClaim(claim, sources, {
+			threshold: options.supportThreshold,
+			similarityFn: options.similarityFn
+		})
+	};
+}
+
+//#endregion
+export { calculateJaccardSimilarity, createHallucinationDetector, detectHallucinations, extractClaims, verifyClaim };
+//# sourceMappingURL=grounding-hallucination.mjs.map

package/dist/grounding-hallucination.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding-hallucination.mjs","names":[],"sources":["../src/grounding/hallucination/index.ts"],"sourcesContent":["/**\n * Hallucination detection\n * @module @od-oneapp/ai-platform/grounding/hallucination\n *\n * Provides utilities for detecting claims that are not supported\n * by the provided source documents.\n */\n\nimport type { GroundingSource } from '../types';\n\nexport interface Claim {\n  text: string;\n  startIndex: number;\n  endIndex: number;\n}\n\nexport interface ClaimVerificationResult {\n  claim: Claim;\n  isSupported: boolean;\n  confidence: number;\n  supportingSources: string[];\n  explanation?: string;\n}\n\nexport interface HallucinationResult {\n  isHallucinated: boolean;\n  confidence: number;\n  unsupportedClaims: Claim[];\n  supportedClaims: Claim[];\n  verificationResults: ClaimVerificationResult[];\n  summary: string;\n}\n\nexport interface HallucinationDetectorOptions {\n  /** Minimum confidence threshold for considering a claim supported */\n  supportThreshold?: number;\n  /** Whether to extract and check individual claims */\n  extractClaims?: boolean;\n  /** Custom claim extractor */\n  claimExtractor?: (text: string) => Claim[];\n  /** Custom similarity function */\n  similarityFn?: (claim: string, source: string) => number;\n}\n\n/**\n * Extract factual claims from text using simple heuristics\n */\nexport function extractClaims(text: string): Claim[] {\n  const claims: Claim[] = [];\n\n  // Split by sentences\n  const sentencePattern = /[^.!?]+[.!?]+/g;\n  let match;\n\n  while ((match = sentencePattern.exec(text)) !== null) {\n    const sentence = match[0].trim();\n\n    // Skip questions, opinions, and hedged statements\n    if (\n      sentence.endsWith('?') ||\n      /\\b(I think|I believe|maybe|perhaps|might|could be|seems like)\\b/i.test(sentence)\n    ) {\n      continue;\n    }\n\n    // Look for factual patterns (contains numbers, dates, names, or definitive statements)\n    if (\n      /\\b\\d+\\b/.test(sentence) || // Contains numbers\n      /\\b(is|are|was|were|has|have|will)\\b/i.test(sentence) || // Contains factual verbs\n      /\\b[A-Z][a-z]+\\s[A-Z][a-z]+\\b/.test(sentence) // Contains proper nouns\n    ) {\n      claims.push({\n        text: sentence,\n        startIndex: match.index,\n        endIndex: match.index + sentence.length,\n      });\n    }\n  }\n\n  return claims;\n}\n\n/**\n * Calculate text similarity using Jaccard index\n */\nexport function calculateJaccardSimilarity(text1: string, text2: string): number {\n  const normalize = (s: string) =>\n    s\n      .toLowerCase()\n      .replace(/[^\\w\\s]/g, '')\n      .split(/\\s+/)\n      .filter(w => w.length > 2);\n\n  const words1 = new Set(normalize(text1));\n  const words2 = new Set(normalize(text2));\n\n  if (words1.size === 0 || words2.size === 0) return 0;\n\n  const intersection = new Set([...words1].filter(w => words2.has(w)));\n  const union = new Set([...words1, ...words2]);\n\n  return intersection.size / union.size;\n}\n\n/**\n * Verify a single claim against sources\n */\nexport function verifyClaim(\n  claim: Claim,\n  sources: GroundingSource[],\n  options: { threshold?: number; similarityFn?: (a: string, b: string) => number } = {},\n): ClaimVerificationResult {\n  const { threshold = 0.3, similarityFn = calculateJaccardSimilarity } = options;\n\n  const supportingSources: string[] = [];\n  let maxSimilarity = 0;\n\n  for (const source of sources) {\n    const similarity = similarityFn(claim.text, source.content);\n\n    if (similarity > maxSimilarity) {\n      maxSimilarity = similarity;\n    }\n\n    if (similarity >= threshold) {\n      supportingSources.push(source.id);\n    }\n  }\n\n  const isSupported = supportingSources.length > 0;\n\n  return {\n    claim,\n    isSupported,\n    confidence: maxSimilarity,\n    supportingSources,\n    explanation: isSupported\n      ? `Claim is supported by ${supportingSources.length} source(s)`\n      : 'No supporting evidence found in sources',\n  };\n}\n\n/**\n * Detect hallucinations in generated text by comparing against sources\n *\n * @example\n * ```ts\n * const result = await detectHallucinations(\n *   \"The company was founded in 2020 and has 500 employees.\",\n *   [{ id: \"1\", content: \"Founded in 2019 with initial team of 10 people.\" }]\n * );\n *\n * if (result.isHallucinated) {\n *   console.log(\"Unsupported claims:\", result.unsupportedClaims);\n * }\n * ```\n */\nexport async function detectHallucinations(\n  text: string,\n  sources: GroundingSource[],\n  options: HallucinationDetectorOptions = {},\n): Promise<HallucinationResult> {\n  const {\n    supportThreshold = 0.3,\n    extractClaims: shouldExtract = true,\n    claimExtractor = extractClaims,\n    similarityFn = calculateJaccardSimilarity,\n  } = options;\n\n  // Extract claims from text\n  const claims = shouldExtract\n    ? claimExtractor(text)\n    : [{ text, startIndex: 0, endIndex: text.length }];\n\n  if (claims.length === 0) {\n    return {\n      isHallucinated: false,\n      confidence: 1.0,\n      unsupportedClaims: [],\n      supportedClaims: [],\n      verificationResults: [],\n      summary: 'No factual claims detected in text',\n    };\n  }\n\n  // Verify each claim\n  const verificationResults = claims.map(claim =>\n    verifyClaim(claim, sources, { threshold: supportThreshold, similarityFn }),\n  );\n\n  const supportedClaims = verificationResults.filter(r => r.isSupported).map(r => r.claim);\n  const unsupportedClaims = verificationResults.filter(r => !r.isSupported).map(r => r.claim);\n\n  const isHallucinated = unsupportedClaims.length > 0;\n  const supportedRatio = supportedClaims.length / claims.length;\n\n  return {\n    isHallucinated,\n    confidence: supportedRatio,\n    unsupportedClaims,\n    supportedClaims,\n    verificationResults,\n    summary: isHallucinated\n      ? `Found ${unsupportedClaims.length} unsupported claim(s) out of ${claims.length} total`\n      : `All ${claims.length} claim(s) are supported by sources`,\n  };\n}\n\n/**\n * Create a hallucination detector with custom configuration\n */\nexport function createHallucinationDetector(options: HallucinationDetectorOptions = {}) {\n  return {\n    detect: (text: string, sources: GroundingSource[]) =>\n      detectHallucinations(text, sources, options),\n    extractClaims: options.claimExtractor ?? extractClaims,\n    verifyClaim: (claim: Claim, sources: GroundingSource[]) =>\n      verifyClaim(claim, sources, {\n        threshold: options.supportThreshold,\n        similarityFn: options.similarityFn,\n      }),\n  };\n}\n"],"mappings":"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"}

package/dist/grounding-proof-map.d.mts

@@ -0,0 +1,9 @@
+import { C as proofMapSchema, E as verificationSchema, S as hasFailingChecks, T as stepSchema, _ as checkStatus, a as validateSafeEdits, b as editSchema, c as CheckStatus, d as ProofMap, f as ProofStatus, g as checkSchema, h as chainSchema, i as applyPatch, l as Claim, m as Verification, n as runProofLoop, o as Chain, p as Step, r as verifyProof, s as Check, t as ProofLoopOptions, u as Edit, v as claimSchema, w as proofStatus, x as getCriticalClaims, y as criticalClaimsPass } from "./loop-C-tBBOqi.mjs";
+
+//#region src/grounding/proof-map/index.d.ts
+declare namespace index_d_exports {
+  export { Chain, Check, CheckStatus, Claim, Edit, ProofLoopOptions, ProofMap, ProofStatus, Step, Verification, applyPatch, chainSchema, checkSchema, checkStatus, claimSchema, criticalClaimsPass, editSchema, getCriticalClaims, hasFailingChecks, proofMapSchema, proofStatus, runProofLoop, stepSchema, validateSafeEdits, verificationSchema, verifyProof };
+}
+//#endregion
+export { Chain, Check, CheckStatus, Claim, Edit, ProofLoopOptions, ProofMap, ProofStatus, Step, Verification, applyPatch, chainSchema, checkSchema, checkStatus, claimSchema, criticalClaimsPass, editSchema, getCriticalClaims, hasFailingChecks, proofMapSchema, proofStatus, runProofLoop, stepSchema, index_d_exports as t, validateSafeEdits, verificationSchema, verifyProof };
+//# sourceMappingURL=grounding-proof-map.d.mts.map

package/dist/grounding-proof-map.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding-proof-map.d.mts","names":[],"sources":["../src/grounding/proof-map/index.ts"],"mappings":""}