@od-oneapp/ai-platform 0.1.0

package/src/grounding/hallucination/index.ts

@@ -0,0 +1,223 @@
+/**
+ * Hallucination detection
+ * @module @od-oneapp/ai-platform/grounding/hallucination
+ *
+ * Provides utilities for detecting claims that are not supported
+ * by the provided source documents.
+ */
+
+import type { GroundingSource } from '../types';
+
+export interface Claim {
+  text: string;
+  startIndex: number;
+  endIndex: number;
+}
+
+export interface ClaimVerificationResult {
+  claim: Claim;
+  isSupported: boolean;
+  confidence: number;
+  supportingSources: string[];
+  explanation?: string;
+}
+
+export interface HallucinationResult {
+  isHallucinated: boolean;
+  confidence: number;
+  unsupportedClaims: Claim[];
+  supportedClaims: Claim[];
+  verificationResults: ClaimVerificationResult[];
+  summary: string;
+}
+
+export interface HallucinationDetectorOptions {
+  /** Minimum confidence threshold for considering a claim supported */
+  supportThreshold?: number;
+  /** Whether to extract and check individual claims */
+  extractClaims?: boolean;
+  /** Custom claim extractor */
+  claimExtractor?: (text: string) => Claim[];
+  /** Custom similarity function */
+  similarityFn?: (claim: string, source: string) => number;
+}
+
+/**
+ * Extract factual claims from text using simple heuristics
+ */
+export function extractClaims(text: string): Claim[] {
+  const claims: Claim[] = [];
+
+  // Split by sentences
+  const sentencePattern = /[^.!?]+[.!?]+/g;
+  let match;
+
+  while ((match = sentencePattern.exec(text)) !== null) {
+    const sentence = match[0].trim();
+
+    // Skip questions, opinions, and hedged statements
+    if (
+      sentence.endsWith('?') ||
+      /\b(I think|I believe|maybe|perhaps|might|could be|seems like)\b/i.test(sentence)
+    ) {
+      continue;
+    }
+
+    // Look for factual patterns (contains numbers, dates, names, or definitive statements)
+    if (
+      /\b\d+\b/.test(sentence) || // Contains numbers
+      /\b(is|are|was|were|has|have|will)\b/i.test(sentence) || // Contains factual verbs
+      /\b[A-Z][a-z]+\s[A-Z][a-z]+\b/.test(sentence) // Contains proper nouns
+    ) {
+      claims.push({
+        text: sentence,
+        startIndex: match.index,
+        endIndex: match.index + sentence.length,
+      });
+    }
+  }
+
+  return claims;
+}
+
+/**
+ * Calculate text similarity using Jaccard index
+ */
+export function calculateJaccardSimilarity(text1: string, text2: string): number {
+  const normalize = (s: string) =>
+    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
+ */
+export function verifyClaim(
+  claim: Claim,
+  sources: GroundingSource[],
+  options: { threshold?: number; similarityFn?: (a: string, b: string) => number } = {},
+): ClaimVerificationResult {
+  const { threshold = 0.3, similarityFn = calculateJaccardSimilarity } = options;
+
+  const supportingSources: string[] = [];
+  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);
+ * }
+ * ```
+ */
+export async function detectHallucinations(
+  text: string,
+  sources: GroundingSource[],
+  options: HallucinationDetectorOptions = {},
+): Promise<HallucinationResult> {
+  const {
+    supportThreshold = 0.3,
+    extractClaims: shouldExtract = true,
+    claimExtractor = extractClaims,
+    similarityFn = calculateJaccardSimilarity,
+  } = options;
+
+  // Extract claims from text
+  const claims = shouldExtract
+    ? claimExtractor(text)
+    : [{ text, startIndex: 0, endIndex: text.length }];
+
+  if (claims.length === 0) {
+    return {
+      isHallucinated: false,
+      confidence: 1.0,
+      unsupportedClaims: [],
+      supportedClaims: [],
+      verificationResults: [],
+      summary: 'No factual claims detected in text',
+    };
+  }
+
+  // Verify each claim
+  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;
+  const supportedRatio = supportedClaims.length / claims.length;
+
+  return {
+    isHallucinated,
+    confidence: supportedRatio,
+    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
+ */
+export function createHallucinationDetector(options: HallucinationDetectorOptions = {}) {
+  return {
+    detect: (text: string, sources: GroundingSource[]) =>
+      detectHallucinations(text, sources, options),
+    extractClaims: options.claimExtractor ?? extractClaims,
+    verifyClaim: (claim: Claim, sources: GroundingSource[]) =>
+      verifyClaim(claim, sources, {
+        threshold: options.supportThreshold,
+        similarityFn: options.similarityFn,
+      }),
+  };
+}

package/src/grounding/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Grounding Module
+ * @module @od-oneapp/ai-platform/grounding
+ *
+ * RAG, embeddings, and response verification:
+ * - Embeddings and vector stores
+ * - RAG pipelines with reranking
+ * - Context engineering
+ * - Hallucination detection
+ * - Citation generation
+ * - Source attribution
+ *
+ * @module grounding
+ */
+
+// Types
+export type {
+  GroundingSource,
+  Citation,
+  GroundedResponse,
+  RetrievalConfig,
+  GroundingConfig,
+  Retriever,
+  VectorStore,
+} from './types';
+
+// Embeddings and RAG
+export * from "./embed";
+
+// Retrieval
+export { InMemoryVectorStore } from './retrieval/in-memory-store';
+
+// Citation generation
+export {
+  generateCitations,
+  formatAsFootnotes,
+  verifyClaims,
+  type CitationFormat,
+  type CitationGeneratorOptions,
+} from './citation/citation-generator';
+
+// Hallucination detection
+export {
+  type Claim,
+  type ClaimVerificationResult,
+  type HallucinationResult,
+  type HallucinationDetectorOptions,
+  extractClaims,
+  calculateJaccardSimilarity,
+  verifyClaim,
+  createHallucinationDetector,
+} from "./hallucination";
+
+// Source verification
+export * from "./verification";
+
+// Sources management
+export * from "./sources";
+
+// Attribution reporting
+export {
+  type AttributionSource,
+  type Claim as AttributionClaim,
+  type AttributionEntry,
+  type AttributionReport,
+  type AttributionTrackerConfig,
+  type AttributionTracker,
+  createAttributionTracker,
+  generateAttributionReport,
+} from "./attribution";
+
+// Context engineering
+export * from "./context-engineering";
+
+// Identity and request context management
+export * as context from "./context";
+
+// Multi-model research pipeline (Perplexity → Sonnet → GPT)
+export * as rag from "./rag";
+
+// Proof map loop and patch utilities
+export * as proofMap from "./proof-map";

package/src/grounding/proof-map/applyPatch.ts

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview JSON-Patch operations for proof maps
+ *
+ * Provides utilities for applying edits to proof maps safely.
+ * Supports replace, add, and remove operations with validation.
+ *
+ * Note: This module is exported as "./proof-map/patch" in package.json for API clarity.
+ * The export name "patch" is more descriptive of the module's purpose than "applyPatch".
+ *
+ * @module @od-oneapp/ai-platform/proof-map/patch
+ */
+
+import { logWarn } from '@repo/shared/logs';
+
+import type { Edit } from './schema';
+
+/**
+ * Applies edits to a proof map using JSON-Patch-like operations.
+ * Supports replace, add, and remove operations.
+ * Deep clones the object to avoid mutation.
+ *
+ * @param obj - Object to apply edits to.
+ * @param edits - Array of edit operations (defaults to empty array).
+ * @returns New object with edits applied.
+ * @remarks Deep clones input object to prevent mutation.
+ * Invalid paths are logged as warnings and skipped.
+ * Array indices are validated before access.
+ * For 'add' operations on arrays, appends if index is out of bounds.
+ * @example
+ * ```ts
+ * const updated = applyPatch(proof, [
+ *   { op: 'replace', path: ['draft', 'answer'], value: 'Updated answer' },
+ *   { op: 'remove', path: ['draft', 'claims', 0] }
+ * ]);
+ * ```
+ */
+export const applyPatch = <T extends Record<string, unknown>>(obj: T, edits: Edit[] = []): T => {
+  // Deep clone to avoid mutation
+  const result = JSON.parse(JSON.stringify(obj)) as T;
+
+  for (const edit of edits) {
+    if (edit.path.length === 0) continue;
+
+    // Navigate to the parent object
+    const parentPath = edit.path.slice(0, -1);
+    const lastKey = edit.path.at(-1);
+
+    if (lastKey === undefined) continue;
+
+    let target: Record<string, unknown> | unknown[] | null = result;
+    let pathInvalid = false;
+    for (const key of parentPath) {
+      if (target === null || typeof target !== 'object') {
+        logWarn('[applyPatch] Invalid path', { path: edit.path.join('.') });
+        pathInvalid = true;
+        break;
+      }
+      if (Array.isArray(target)) {
+        const index = typeof key === 'number' ? key : Number.parseInt(String(key), 10);
+        if (Number.isNaN(index) || index < 0 || index >= target.length) {
+          logWarn('[applyPatch] Invalid array index', { key });
+          pathInvalid = true;
+          break;
+        }
+        target = target[index] as Record<string, unknown> | unknown[] | null;
+      } else {
+        target = target[key] as Record<string, unknown> | unknown[] | null;
+      }
+    }
+
+    if (pathInvalid || target === null || typeof target !== 'object') {
+      logWarn('[applyPatch] Cannot apply edit to non-object', { path: parentPath.join('.') });
+      continue;
+    }
+
+    switch (edit.op) {
+      case 'replace':
+        if (Array.isArray(target)) {
+          const index =
+            typeof lastKey === 'number' ? lastKey : Number.parseInt(String(lastKey), 10);
+          if (!Number.isNaN(index) && index >= 0 && index < target.length) {
+            target[index] = edit.value;
+          }
+        } else {
+          target[lastKey] = edit.value;
+        }
+        break;
+
+      case 'add':
+        if (Array.isArray(target)) {
+          const index =
+            typeof lastKey === 'number' ? lastKey : Number.parseInt(String(lastKey), 10);
+          if (!Number.isNaN(index) && index >= 0 && index < target.length) {
+            const existingValue = target[index];
+            if (Array.isArray(existingValue)) {
+              existingValue.push(edit.value);
+            } else {
+              target[index] = edit.value;
+            }
+          } else {
+            target.push(edit.value);
+          }
+        } else {
+          const existingValue = target[lastKey];
+          if (Array.isArray(existingValue)) {
+            existingValue.push(edit.value);
+          } else {
+            target[lastKey] = edit.value;
+          }
+        }
+        break;
+
+      case 'remove':
+        if (Array.isArray(target)) {
+          const index =
+            typeof lastKey === 'number' ? lastKey : Number.parseInt(String(lastKey), 10);
+          if (!Number.isNaN(index) && index >= 0 && index < target.length) {
+            target.splice(index, 1);
+          }
+        } else {
+          delete target[lastKey];
+        }
+        break;
+
+      default:
+        logWarn('[applyPatch] Unknown operation', {
+          op: 'op' in edit ? String(edit.op) : 'unknown',
+        });
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Validates that suggested edits are "safe" (low-risk).
+ * Only allows scalar replacements (string, number, boolean) for safety.
+ * More complex edits are marked as unsafe.
+ *
+ * @param edits - Array of edits to validate.
+ * @returns Object containing safe and unsafe edit arrays:
+ * - `safe` - Edits that are safe to auto-apply (scalar replacements only)
+ * - `unsafe` - Edits that require manual review (non-scalar or non-replace operations)
+ * @remarks Only 'replace' operations with scalar values (string, number, boolean) are considered safe.
+ * 'add' and 'remove' operations are always marked unsafe.
+ * Non-scalar values (objects, arrays) are marked unsafe even for 'replace' operations.
+ * @example
+ * ```ts
+ * const { safe, unsafe } = validateSafeEdits(edits);
+ * const updated = applyPatch(proof, safe);
+ * ```
+ */
+export const validateSafeEdits = (edits: Edit[]): { safe: Edit[]; unsafe: Edit[] } => {
+  const safe: Edit[] = [];
+  const unsafe: Edit[] = [];
+
+  for (const edit of edits) {
+    const isSafe =
+      edit.op === 'replace' &&
+      (typeof edit.value === 'string' ||
+        typeof edit.value === 'number' ||
+        typeof edit.value === 'boolean');
+
+    if (isSafe) {
+      safe.push(edit);
+    } else {
+      unsafe.push(edit);
+    }
+  }
+
+  return { safe, unsafe };
+};

package/src/grounding/proof-map/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Proof Map Module.
+ *
+ * Exports proof map utilities for multi-model proof loops, patch application,
+ * and schema definitions for proof map data structures.
+ *
+ * @module @od-oneapp/ai-platform/proof-map
+ * @example
+ * ```ts
+ * import { createProofLoop } from "@od-oneapp/ai-platform/proof-map";
+ *
+ * const loop = createProofLoop({ maxDepth: 2 });
+ * ```
+ */
+
+/**
+ * Patch application utilities for proof maps.
+ * @example
+ * ```ts
+ * import { applyPatch } from "@od-oneapp/ai-platform/proof-map";
+ * ```
+ */
+export * from './applyPatch';
+
+/**
+ * Proof loop executor and helpers.
+ * @example
+ * ```ts
+ * import { createProofLoop } from "@od-oneapp/ai-platform/proof-map";
+ * ```
+ */
+export * from './loop';
+
+/**
+ * Proof-map schema definitions.
+ * @example
+ * ```ts
+ * import { proofMapSchema } from "@od-oneapp/ai-platform/proof-map";
+ * ```
+ */
+export * from './schema';