@od-oneapp/ai-platform 0.1.0

package/src/grounding/attribution/index.ts

@@ -0,0 +1,424 @@
+/**
+ * Source Attribution
+ *
+ * Tracks and reports how AI outputs are attributed to source documents,
+ * enabling transparency and auditability of AI-generated content.
+ *
+ * @module @od-oneapp/ai-platform/grounding/attribution
+ *
+ * @example
+ * ```typescript
+ * import { createAttributionTracker } from '@od-oneapp/ai-platform/grounding/attribution';
+ *
+ * const tracker = createAttributionTracker();
+ *
+ * // Register sources
+ * tracker.addSource({ id: 'doc-1', content: 'Climate change affects...' });
+ *
+ * // Analyze text for attribution
+ * const report = await tracker.generateReport(
+ *   'Climate change affects weather patterns significantly.',
+ *   ['doc-1']
+ * );
+ * ```
+ */
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+/** Source document for attribution */
+export interface AttributionSource {
+  readonly id: string;
+  readonly content: string;
+  readonly metadata?: {
+    title?: string;
+    url?: string;
+    author?: string;
+    date?: Date;
+    reliability?: number; // 0-1 score
+  };
+}
+
+/** A specific claim extracted from text */
+export interface Claim {
+  readonly id: string;
+  readonly text: string;
+  readonly startOffset: number;
+  readonly endOffset: number;
+  readonly type: 'factual' | 'opinion' | 'inference' | 'unknown';
+}
+
+/** Attribution entry linking a source to claims */
+export interface AttributionEntry {
+  readonly sourceId: string;
+  readonly contributionScore: number; // 0-1, how much this source contributed
+  readonly claimIds: string[];
+  readonly matchedSegments: Array<{
+    sourceSpan: { start: number; end: number };
+    claimSpan: { start: number; end: number };
+    similarity: number;
+  }>;
+}
+
+/** Complete attribution report */
+export interface AttributionReport {
+  readonly totalSources: number;
+  readonly totalClaims: number;
+  readonly attributions: AttributionEntry[];
+  readonly unattributedClaims: string[];
+  readonly attributionCoverage: number; // 0-1, % of text with sources
+  readonly generatedAt: Date;
+  readonly metadata?: Record<string, unknown>;
+}
+
+/** Tracker configuration */
+export interface AttributionTrackerConfig {
+  readonly minSimilarityThreshold?: number;
+  readonly maxClaimsPerSource?: number;
+  readonly extractClaims?: boolean;
+  readonly computeContribution?: boolean;
+}
+
+/** Attribution tracker interface */
+export interface AttributionTracker {
+  addSource(source: AttributionSource): void;
+  removeSource(sourceId: string): void;
+  getSources(): AttributionSource[];
+  extractClaims(text: string): Claim[];
+  generateReport(text: string, sourceIds?: string[]): Promise<AttributionReport>;
+  getConfig(): AttributionTrackerConfig;
+}
+
+// -----------------------------------------------------------------------------
+// Implementation
+// -----------------------------------------------------------------------------
+
+/**
+ * Creates an attribution tracker for source attribution analysis.
+ *
+ * @example
+ * ```typescript
+ * const tracker = createAttributionTracker({
+ *   minSimilarityThreshold: 0.6,
+ *   extractClaims: true
+ * });
+ *
+ * tracker.addSource({
+ *   id: 'wiki-climate',
+ *   content: 'Global warming is the long-term rise in temperature...',
+ *   metadata: { url: 'https://example.com/climate' }
+ * });
+ *
+ * const report = await tracker.generateReport(
+ *   'Global warming causes temperature rise worldwide.'
+ * );
+ * console.log(`Coverage: ${report.attributionCoverage * 100}%`);
+ * ```
+ */
+export function createAttributionTracker(
+  config: AttributionTrackerConfig = {},
+): AttributionTracker {
+  const {
+    minSimilarityThreshold = 0.5,
+    maxClaimsPerSource = 50,
+    extractClaims: shouldExtractClaims = true,
+    computeContribution = true,
+  } = config;
+
+  const sources = new Map<string, AttributionSource>();
+
+  function addSource(source: AttributionSource): void {
+    sources.set(source.id, source);
+  }
+
+  function removeSource(sourceId: string): void {
+    sources.delete(sourceId);
+  }
+
+  function getSources(): AttributionSource[] {
+    return Array.from(sources.values());
+  }
+
+  /**
+   * Extract claims from text using simple sentence-based extraction.
+   */
+  function extractClaims(text: string): Claim[] {
+    if (!shouldExtractClaims) return [];
+
+    const claims: Claim[] = [];
+    // Simple sentence splitter - split on . ! ? followed by space or end
+    const sentences = text.match(/[^.!?]+[.!?]+/g) ?? [text];
+
+    let offset = 0;
+    for (const sentence of sentences) {
+      const trimmed = sentence.trim();
+      if (trimmed.length < 10) {
+        offset += sentence.length;
+        continue;
+      }
+
+      const startOffset = text.indexOf(trimmed, offset);
+      const claim: Claim = {
+        id: generateClaimId(),
+        text: trimmed,
+        startOffset,
+        endOffset: startOffset + trimmed.length,
+        type: classifyClaimType(trimmed),
+      };
+
+      claims.push(claim);
+      offset = startOffset + trimmed.length;
+    }
+
+    return claims;
+  }
+
+  /**
+   * Generate attribution report analyzing how text relates to sources.
+   */
+  async function generateReport(text: string, sourceIds?: string[]): Promise<AttributionReport> {
+    // Get sources to analyze
+    const sourcesToCheck = sourceIds
+      ? sourceIds.map(id => sources.get(id)).filter((s): s is AttributionSource => s !== undefined)
+      : Array.from(sources.values());
+
+    // Extract claims from text
+    const claims = extractClaims(text);
+    // Build attributions
+    const attributions: AttributionEntry[] = [];
+    const attributedClaimIds = new Set<string>();
+
+    for (const source of sourcesToCheck) {
+      const matchedClaims: string[] = [];
+      const matchedSegments: AttributionEntry['matchedSegments'] = [];
+
+      // Compare each claim to source
+      for (const claim of claims) {
+        if (matchedClaims.length >= maxClaimsPerSource) break;
+
+        const similarity = computeSimilarity(claim.text, source.content);
+
+        if (similarity >= minSimilarityThreshold) {
+          matchedClaims.push(claim.id);
+          attributedClaimIds.add(claim.id);
+
+          // Find best matching segment in source
+          const sourceMatch = findBestMatch(claim.text, source.content);
+          if (sourceMatch) {
+            matchedSegments.push({
+              sourceSpan: sourceMatch.span,
+              claimSpan: { start: claim.startOffset, end: claim.endOffset },
+              similarity,
+            });
+          }
+        }
+      }
+
+      if (matchedClaims.length > 0) {
+        const contributionScore = computeContribution
+          ? matchedClaims.length / claims.length
+          : matchedClaims.length / Math.max(claims.length, 1);
+
+        attributions.push({
+          sourceId: source.id,
+          contributionScore,
+          claimIds: matchedClaims,
+          matchedSegments,
+        });
+      }
+    }
+
+    // Find unattributed claims
+    const unattributedClaims = claims.filter(c => !attributedClaimIds.has(c.id)).map(c => c.id);
+
+    // Calculate coverage
+    const attributionCoverage = claims.length > 0 ? attributedClaimIds.size / claims.length : 0;
+
+    return {
+      totalSources: sourcesToCheck.length,
+      totalClaims: claims.length,
+      attributions,
+      unattributedClaims,
+      attributionCoverage,
+      generatedAt: new Date(),
+    };
+  }
+
+  function getConfig(): AttributionTrackerConfig {
+    return {
+      minSimilarityThreshold,
+      maxClaimsPerSource,
+      extractClaims: shouldExtractClaims,
+      computeContribution,
+    };
+  }
+
+  return {
+    addSource,
+    removeSource,
+    getSources,
+    extractClaims,
+    generateReport,
+    getConfig,
+  };
+}
+
+// -----------------------------------------------------------------------------
+// Legacy API (for backwards compatibility)
+// -----------------------------------------------------------------------------
+
+/**
+ * Generate an attribution report for text against sources.
+ * @deprecated Use createAttributionTracker() instead
+ */
+export function generateAttributionReport(
+  text: string,
+  sources: AttributionSource[],
+): AttributionReport {
+  const tracker = createAttributionTracker();
+  for (const source of sources) {
+    tracker.addSource(source);
+  }
+
+  // Synchronous wrapper - extracts claims and matches
+  const claims = tracker.extractClaims(text);
+  const attributions: AttributionEntry[] = [];
+  const attributedClaimIds = new Set<string>();
+
+  for (const source of sources) {
+    const matchedClaims: string[] = [];
+    const matchedSegments: AttributionEntry['matchedSegments'] = [];
+
+    for (const claim of claims) {
+      const similarity = computeSimilarity(claim.text, source.content);
+      if (similarity >= 0.5) {
+        matchedClaims.push(claim.id);
+        attributedClaimIds.add(claim.id);
+        matchedSegments.push({
+          sourceSpan: { start: 0, end: Math.min(100, source.content.length) },
+          claimSpan: { start: claim.startOffset, end: claim.endOffset },
+          similarity,
+        });
+      }
+    }
+
+    if (matchedClaims.length > 0) {
+      attributions.push({
+        sourceId: source.id,
+        contributionScore: matchedClaims.length / Math.max(claims.length, 1),
+        claimIds: matchedClaims,
+        matchedSegments,
+      });
+    }
+  }
+
+  return {
+    totalSources: sources.length,
+    totalClaims: claims.length,
+    attributions,
+    unattributedClaims: claims.filter(c => !attributedClaimIds.has(c.id)).map(c => c.id),
+    attributionCoverage: claims.length > 0 ? attributedClaimIds.size / claims.length : 0,
+    generatedAt: new Date(),
+  };
+}
+
+// -----------------------------------------------------------------------------
+// Utilities
+// -----------------------------------------------------------------------------
+
+function generateClaimId(): string {
+  return `claim-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+}
+
+/**
+ * Classify a claim as factual, opinion, inference, or unknown.
+ */
+function classifyClaimType(text: string): Claim['type'] {
+  const lower = text.toLowerCase();
+
+  // Opinion indicators
+  const opinionWords = ['believe', 'think', 'feel', 'opinion', 'suggest', 'might', 'could', 'may'];
+  if (opinionWords.some(w => lower.includes(w))) {
+    return 'opinion';
+  }
+
+  // Inference indicators
+  const inferenceWords = ['therefore', 'thus', 'hence', 'implies', 'suggests that', 'indicates'];
+  if (inferenceWords.some(w => lower.includes(w))) {
+    return 'inference';
+  }
+
+  // Factual indicators (numbers, dates, proper nouns pattern)
+  const hasNumbers = /\d+/.test(text);
+  const tokens = text.split(/\s+/).filter(Boolean);
+  const hasProperNouns = tokens.some(token => {
+    const first = token[0];
+    if (!first) return false;
+    const rest = token.slice(1);
+    return first === first.toUpperCase() && rest === rest.toLowerCase();
+  });
+  if (hasNumbers || hasProperNouns) {
+    return 'factual';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Compute text similarity using word overlap (Jaccard-like).
+ */
+function computeSimilarity(text1: string, text2: string): number {
+  const words1 = new Set(tokenize(text1));
+  const words2 = new Set(tokenize(text2));
+
+  if (words1.size === 0 || words2.size === 0) return 0;
+
+  let intersection = 0;
+  for (const word of words1) {
+    if (words2.has(word)) intersection++;
+  }
+
+  // Jaccard similarity
+  const union = words1.size + words2.size - intersection;
+  return union > 0 ? intersection / union : 0;
+}
+
+/**
+ * Tokenize text into lowercase words.
+ */
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 2); // Skip very short words
+}
+
+/**
+ * Find the best matching segment in source for a claim.
+ */
+function findBestMatch(
+  claim: string,
+  source: string,
+): { span: { start: number; end: number }; similarity: number } | null {
+  const claimWords = tokenize(claim);
+  if (claimWords.length === 0) return null;
+
+  // Sliding window over source
+  const windowSize = Math.min(claim.length * 2, 200);
+  let bestSimilarity = 0;
+  let bestSpan = { start: 0, end: windowSize };
+
+  for (let i = 0; i < source.length - 50; i += 20) {
+    const segment = source.slice(i, i + windowSize);
+    const similarity = computeSimilarity(claim, segment);
+
+    if (similarity > bestSimilarity) {
+      bestSimilarity = similarity;
+      bestSpan = { start: i, end: Math.min(i + windowSize, source.length) };
+    }
+  }
+
+  return bestSimilarity > 0 ? { span: bestSpan, similarity: bestSimilarity } : null;
+}

package/src/grounding/citation/citation-generator.ts

@@ -0,0 +1,174 @@
+/**
+ * Citation generation utilities
+ */
+
+import type { Citation, GroundingSource } from '../types';
+
+/**
+ * Citation format options
+ */
+export type CitationFormat = 'inline' | 'footnote' | 'endnote';
+
+/**
+ * Citation generator options
+ */
+export interface CitationGeneratorOptions {
+  /** Citation format */
+  format?: CitationFormat;
+  /** Whether to include source URLs */
+  includeUrls?: boolean;
+  /** Custom citation template */
+  template?: (source: GroundingSource, index: number) => string;
+}
+
+/**
+ * Generate citations for grounded text
+ *
+ * @example
+ * ```ts
+ * const citations = generateCitations(
+ *   "AI is powerful [1]. It transforms industries [2].",
+ *   sources,
+ *   { format: "footnote" }
+ * );
+ * ```
+ */
+export function generateCitations(
+  text: string,
+  sources: GroundingSource[],
+  options: CitationGeneratorOptions = {},
+): Citation[] {
+  const format = options.format ?? 'inline';
+  const citations: Citation[] = [];
+
+  // Find citation markers [1], [2], etc.
+  const markerPattern = /\[(\d+)\]/g;
+  let match;
+
+  while ((match = markerPattern.exec(text)) !== null) {
+    const token = match[1];
+    if (!token) {
+      continue;
+    }
+    const index = parseInt(token, 10) - 1;
+    if (index >= 0 && index < sources.length) {
+      const source = sources[index];
+      if (!source) {
+        continue;
+      }
+
+      // Find the text being cited (preceding sentence or clause)
+      const citedText = extractCitedText(text, match.index);
+
+      citations.push({
+        id: `cite-${citations.length + 1}`,
+        sourceId: source.id,
+        citedText,
+        position: {
+          start: match.index,
+          end: match.index + match[0].length,
+        },
+      });
+    }
+  }
+
+  if (citations.length === 0 && format !== 'inline' && sources.length > 0) {
+    const endPosition = text.length;
+    const citedText = extractCitedText(text, endPosition);
+
+    sources.forEach((source, index) => {
+      citations.push({
+        id: `cite-${index + 1}`,
+        sourceId: source.id,
+        citedText,
+        position: {
+          start: endPosition,
+          end: endPosition,
+        },
+      });
+    });
+  }
+
+  return citations;
+}
+
+/**
+ * Extract the text being cited (preceding content)
+ */
+function extractCitedText(text: string, citationPos: number): string {
+  // Look back for sentence boundary
+  const beforeCitation = text.slice(0, citationPos);
+  const sentenceMatch = beforeCitation.match(/[.!?]\s*([^.!?]+)$/);
+
+  if (sentenceMatch?.[1]) {
+    return sentenceMatch[1].trim();
+  }
+
+  // If no sentence boundary, take last 100 characters
+  return beforeCitation.slice(-100).trim();
+}
+
+/**
+ * Format citations as footnotes
+ */
+export function formatAsFootnotes(
+  text: string,
+  sources: GroundingSource[],
+  options: CitationGeneratorOptions = {},
+): string {
+  const { includeUrls = true, template } = options;
+
+  let footnotes = '\n\n---\n';
+
+  sources.forEach((source, index) => {
+    const num = index + 1;
+    if (template) {
+      footnotes += `[${num}] ${template(source, index)}\n`;
+    } else {
+      let citation = `[${num}] ${source.title || source.id}`;
+      if (includeUrls && source.url) {
+        citation += ` - ${source.url}`;
+      }
+      footnotes += `${citation}\n`;
+    }
+  });
+
+  return text + footnotes;
+}
+
+/**
+ * Verify that all claims in text are grounded in sources
+ */
+export function verifyClaims(
+  text: string,
+  sources: GroundingSource[],
+): { verified: boolean; ungroundedClaims: string[] } {
+  // Simple heuristic: check if key phrases appear in sources
+  const sentences = text.split(/[.!?]+/).filter(s => s.trim());
+  const ungroundedClaims: string[] = [];
+
+  const sourceText = sources.map(s => s.content.toLowerCase()).join(' ');
+
+  for (const sentence of sentences) {
+    const trimmed = sentence.trim();
+    if (trimmed.length < 20) continue; // Skip short fragments
+
+    // Extract key phrases (nouns and noun phrases)
+    const words = trimmed.toLowerCase().split(/\s+/);
+    const keyPhrases = words.filter(w => w.length > 4);
+
+    // Check if at least half of key phrases appear in sources
+    const matchCount = keyPhrases.filter(phrase => sourceText.includes(phrase)).length;
+
+    const matchRatio = keyPhrases.length > 0 ? matchCount / keyPhrases.length : 0;
+
+    if (matchRatio < 0.3) {
+      ungroundedClaims.push(trimmed);
+    }
+  }
+
+  return {
+    verified: ungroundedClaims.length === 0,
+    ungroundedClaims,
+  };
+}

package/src/grounding/citation/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Citation generation
+ * @module @od-oneapp/ai-platform/grounding/citation
+ */
+
+export {
+  generateCitations,
+  formatAsFootnotes,
+  verifyClaims,
+  type CitationFormat,
+  type CitationGeneratorOptions,
+} from './citation-generator';

package/src/grounding/context/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Context module for identity and request context management.
+ * @module @od-oneapp/ai-platform/context
+ *
+ * @example
+ * ```ts
+ * import { getSafeIdentityContext, hasPermission } from '@od-oneapp/ai-platform/context';
+ *
+ * const ctx = getSafeIdentityContext(rawInput);
+ * if (hasPermission(ctx, 'documents:write')) {
+ *   // Allow operation
+ * }
+ * ```
+ */
+
+export {
+  IdentityContextSchema,
+  RequestContextSchema,
+  MinimalContextSchema,
+  type IdentityContext,
+  type RequestContext,
+  type MinimalContext,
+} from './types';
+
+export {
+  getSafeIdentityContext,
+  getSafeRequestContext,
+  createRequestContext,
+  hasPermission,
+  hasAnyPermission,
+  hasAllPermissions,
+} from './safe-context';