@od-oneapp/ai-platform 0.1.0

package/src/observability/tracing/provenance.ts

@@ -0,0 +1,769 @@
+/**
+ * Provenance Tracking Module
+ *
+ * Tracks the origin, lineage, and transformation history of AI-generated content.
+ * Enables audit trails, attribution, and content verification.
+ *
+ * @module @od-oneapp/ai-platform/observability/tracing/provenance
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Source types for provenance
+ */
+export type SourceType =
+  | 'user_input'
+  | 'system_prompt'
+  | 'tool_result'
+  | 'rag_retrieval'
+  | 'web_search'
+  | 'database'
+  | 'api'
+  | 'file'
+  | 'generated'
+  | 'cached'
+  | 'external';
+
+/**
+ * A source contributing to the output
+ */
+export interface ProvenanceSource {
+  /** Unique source ID */
+  id: string;
+  /** Type of source */
+  type: SourceType;
+  /** Human-readable name */
+  name: string;
+  /** URL or path if applicable */
+  uri?: string;
+  /** Content snippet or reference */
+  content?: string;
+  /** Confidence/relevance score (0-1) */
+  confidence?: number;
+  /** When the source was accessed */
+  accessedAt: Date;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * A transformation applied to content
+ */
+export interface ProvenanceTransformation {
+  /** Transformation ID */
+  id: string;
+  /** Type of transformation */
+  type:
+    | 'llm_generation'
+    | 'summarization'
+    | 'translation'
+    | 'extraction'
+    | 'aggregation'
+    | 'custom';
+  /** Model or tool that performed it */
+  agent: string;
+  /** Input source IDs */
+  inputSourceIds: string[];
+  /** Output source ID (becomes new source) */
+  outputSourceId: string;
+  /** When transformation occurred */
+  timestamp: Date;
+  /** Token usage if LLM */
+  tokenUsage?: {
+    input: number;
+    output: number;
+  };
+  /** Duration in ms */
+  durationMs?: number;
+  /** Parameters used */
+  parameters?: Record<string, unknown>;
+}
+
+/**
+ * Complete provenance record for an output
+ */
+export interface ProvenanceRecord {
+  /** Unique record ID */
+  id: string;
+  /** The final output/content */
+  outputId: string;
+  /** All sources that contributed */
+  sources: ProvenanceSource[];
+  /** All transformations applied */
+  transformations: ProvenanceTransformation[];
+  /** Root source IDs (original inputs) */
+  rootSourceIds: string[];
+  /** Final output source ID */
+  finalSourceId: string;
+  /** When record was created */
+  createdAt: Date;
+  /** Session/conversation ID */
+  sessionId?: string;
+  /** User ID if applicable */
+  userId?: string;
+  /** Request ID for tracing */
+  requestId?: string;
+  /** Verification hash */
+  contentHash?: string;
+}
+
+export interface ProvenanceTracker {
+  addSource(
+    params: Omit<ProvenanceSource, 'id' | 'accessedAt'> & { accessedAt?: Date },
+  ): ProvenanceSource;
+  addTransformation(
+    params: Omit<ProvenanceTransformation, 'id' | 'outputSourceId' | 'timestamp'> & {
+      outputName?: string;
+      outputContent?: string;
+      timestamp?: Date;
+    },
+  ): ProvenanceSource;
+  getSource(id: string): ProvenanceSource | undefined;
+  getSources(): ProvenanceSource[];
+  getTransformations(): ProvenanceTransformation[];
+  getLineage(sourceId: string): {
+    sources: ProvenanceSource[];
+    transformations: ProvenanceTransformation[];
+  };
+  getRecord(outputId?: string): ProvenanceRecord;
+  reset(): void;
+  merge(other: ProvenanceTracker): void;
+}
+
+/**
+ * Provenance query options
+ */
+export interface ProvenanceQueryOptions {
+  /** Filter by source type */
+  sourceTypes?: SourceType[];
+  /** Filter by date range */
+  after?: Date;
+  before?: Date;
+  /** Filter by session */
+  sessionId?: string;
+  /** Include full content */
+  includeContent?: boolean;
+  /** Maximum results */
+  limit?: number;
+}
+
+// ============================================================================
+// Schemas
+// ============================================================================
+
+export const SourceTypeSchema = z.enum([
+  'user_input',
+  'system_prompt',
+  'tool_result',
+  'rag_retrieval',
+  'web_search',
+  'database',
+  'api',
+  'file',
+  'generated',
+  'cached',
+  'external',
+]);
+
+export const ProvenanceSourceSchema = z.object({
+  id: z.string(),
+  type: SourceTypeSchema,
+  name: z.string(),
+  uri: z.string().optional(),
+  content: z.string().optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  accessedAt: z.date(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const ProvenanceTransformationSchema = z.object({
+  id: z.string(),
+  type: z.enum([
+    'llm_generation',
+    'summarization',
+    'translation',
+    'extraction',
+    'aggregation',
+    'custom',
+  ]),
+  agent: z.string(),
+  inputSourceIds: z.array(z.string()),
+  outputSourceId: z.string(),
+  timestamp: z.date(),
+  tokenUsage: z
+    .object({
+      input: z.number(),
+      output: z.number(),
+    })
+    .optional(),
+  durationMs: z.number().optional(),
+  parameters: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const ProvenanceRecordSchema = z.object({
+  id: z.string(),
+  outputId: z.string(),
+  sources: z.array(ProvenanceSourceSchema),
+  transformations: z.array(ProvenanceTransformationSchema),
+  rootSourceIds: z.array(z.string()),
+  finalSourceId: z.string(),
+  createdAt: z.date(),
+  sessionId: z.string().optional(),
+  userId: z.string().optional(),
+  requestId: z.string().optional(),
+  contentHash: z.string().optional(),
+});
+
+// ============================================================================
+// Provenance Tracker
+// ============================================================================
+
+/**
+ * Create a provenance tracker
+ *
+ * @example
+ * ```typescript
+ * const tracker = createProvenanceTracker({ sessionId: 'session_123' });
+ *
+ * // Track user input
+ * const userSource = tracker.addSource({
+ *   type: 'user_input',
+ *   name: 'User Query',
+ *   content: 'What is machine learning?',
+ * });
+ *
+ * // Track RAG retrieval
+ * const ragSources = documents.map(doc => tracker.addSource({
+ *   type: 'rag_retrieval',
+ *   name: doc.title,
+ *   uri: doc.url,
+ *   content: doc.content,
+ *   confidence: doc.score,
+ * }));
+ *
+ * // Track LLM generation
+ * const outputSource = tracker.addTransformation({
+ *   type: 'llm_generation',
+ *   agent: 'gpt-4',
+ *   inputSourceIds: [userSource.id, ...ragSources.map(s => s.id)],
+ *   tokenUsage: { input: 1500, output: 500 },
+ * });
+ *
+ * // Get provenance record
+ * const record = tracker.getRecord();
+ * ```
+ */
+export function createProvenanceTracker(
+  options: {
+    sessionId?: string;
+    userId?: string;
+    requestId?: string;
+  } = {},
+): ProvenanceTracker {
+  const sources = new Map<string, ProvenanceSource>();
+  const transformations: ProvenanceTransformation[] = [];
+  const rootSourceIds: string[] = [];
+  let finalSourceId: string | null = null;
+
+  function generateId(prefix: string): string {
+    return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+  }
+
+  return {
+    /**
+     * Add a source
+     */
+    addSource(
+      params: Omit<ProvenanceSource, 'id' | 'accessedAt'> & { accessedAt?: Date },
+    ): ProvenanceSource {
+      const source: ProvenanceSource = {
+        ...params,
+        id: generateId('src'),
+        accessedAt: params.accessedAt || new Date(),
+      };
+
+      sources.set(source.id, source);
+
+      // Root sources are those not created by transformations
+      if (!transformations.some(t => t.outputSourceId === source.id)) {
+        rootSourceIds.push(source.id);
+      }
+
+      return source;
+    },
+
+    /**
+     * Add a transformation and create output source
+     */
+    addTransformation(
+      params: Omit<ProvenanceTransformation, 'id' | 'outputSourceId' | 'timestamp'> & {
+        outputName?: string;
+        outputContent?: string;
+        timestamp?: Date;
+      },
+    ): ProvenanceSource {
+      const outputSourceId = generateId('src');
+      const transformation: ProvenanceTransformation = {
+        ...params,
+        id: generateId('txn'),
+        outputSourceId,
+        timestamp: params.timestamp || new Date(),
+      };
+
+      transformations.push(transformation);
+
+      // Create output source
+      const outputSource: ProvenanceSource = {
+        id: outputSourceId,
+        type: 'generated',
+        name: params.outputName || `${params.type} output`,
+        content: params.outputContent,
+        accessedAt: transformation.timestamp,
+        metadata: {
+          transformationId: transformation.id,
+          agent: params.agent,
+        },
+      };
+
+      sources.set(outputSourceId, outputSource);
+      finalSourceId = outputSourceId;
+
+      return outputSource;
+    },
+
+    /**
+     * Get a source by ID
+     */
+    getSource(id: string): ProvenanceSource | undefined {
+      return sources.get(id);
+    },
+
+    /**
+     * Get all sources
+     */
+    getSources(): ProvenanceSource[] {
+      return Array.from(sources.values());
+    },
+
+    /**
+     * Get all transformations
+     */
+    getTransformations(): ProvenanceTransformation[] {
+      return [...transformations];
+    },
+
+    /**
+     * Get lineage for a source (trace back to roots)
+     */
+    getLineage(sourceId: string): {
+      sources: ProvenanceSource[];
+      transformations: ProvenanceTransformation[];
+    } {
+      const lineageSources = new Set<string>();
+      const lineageTransformations = new Set<string>();
+
+      function trace(id: string): void {
+        lineageSources.add(id);
+
+        // Find transformation that created this source
+        const transformation = transformations.find(t => t.outputSourceId === id);
+        if (transformation) {
+          lineageTransformations.add(transformation.id);
+          // Trace all inputs
+          for (const inputId of transformation.inputSourceIds) {
+            if (!lineageSources.has(inputId)) {
+              trace(inputId);
+            }
+          }
+        }
+      }
+
+      trace(sourceId);
+
+      return {
+        sources: Array.from(lineageSources)
+          .map(id => sources.get(id))
+          .filter((s): s is ProvenanceSource => s !== undefined),
+        transformations: transformations.filter(t => lineageTransformations.has(t.id)),
+      };
+    },
+
+    /**
+     * Get complete provenance record
+     */
+    getRecord(outputId?: string): ProvenanceRecord {
+      const contentHash = finalSourceId
+        ? hashContent(sources.get(finalSourceId)?.content || '')
+        : undefined;
+
+      return {
+        id: generateId('prov'),
+        outputId: outputId || generateId('out'),
+        sources: Array.from(sources.values()),
+        transformations: [...transformations],
+        rootSourceIds: [...rootSourceIds],
+        finalSourceId: finalSourceId || '',
+        createdAt: new Date(),
+        sessionId: options.sessionId,
+        userId: options.userId,
+        requestId: options.requestId,
+        contentHash,
+      };
+    },
+
+    /**
+     * Reset the tracker
+     */
+    reset(): void {
+      sources.clear();
+      transformations.length = 0;
+      rootSourceIds.length = 0;
+      finalSourceId = null;
+    },
+
+    /**
+     * Merge another tracker's data
+     */
+    merge(other: ProvenanceTracker): void {
+      for (const source of other.getSources()) {
+        sources.set(source.id, source);
+      }
+      transformations.push(...other.getTransformations());
+    },
+  };
+}
+
+// ============================================================================
+// Provenance Store
+// ============================================================================
+
+/**
+ * In-memory provenance store
+ */
+export function createMemoryProvenanceStore() {
+  const records = new Map<string, ProvenanceRecord>();
+  const bySession = new Map<string, Set<string>>();
+  const byOutput = new Map<string, string>();
+
+  return {
+    async save(record: ProvenanceRecord): Promise<void> {
+      records.set(record.id, record);
+      byOutput.set(record.outputId, record.id);
+
+      if (record.sessionId) {
+        let sessionSet = bySession.get(record.sessionId);
+        if (!sessionSet) {
+          sessionSet = new Set();
+          bySession.set(record.sessionId, sessionSet);
+        }
+        sessionSet.add(record.id);
+      }
+    },
+
+    async load(id: string): Promise<ProvenanceRecord | null> {
+      return records.get(id) || null;
+    },
+
+    async loadByOutput(outputId: string): Promise<ProvenanceRecord | null> {
+      const recordId = byOutput.get(outputId);
+      return recordId ? records.get(recordId) || null : null;
+    },
+
+    async query(options: ProvenanceQueryOptions = {}): Promise<ProvenanceRecord[]> {
+      let results = Array.from(records.values());
+      const { after, before, sourceTypes, includeContent, limit } = options;
+
+      if (options.sessionId) {
+        const sessionRecords = bySession.get(options.sessionId);
+        if (!sessionRecords) return [];
+        results = results.filter(r => sessionRecords.has(r.id));
+      }
+
+      if (after) {
+        results = results.filter(r => r.createdAt >= after);
+      }
+
+      if (before) {
+        results = results.filter(r => r.createdAt <= before);
+      }
+
+      if (sourceTypes && sourceTypes.length > 0) {
+        results = results.filter(r => r.sources.some(s => sourceTypes.includes(s.type)));
+      }
+
+      results.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+
+      if (limit) {
+        results = results.slice(0, limit);
+      }
+
+      if (!includeContent) {
+        results = results.map(r => ({
+          ...r,
+          sources: r.sources.map(s => ({ ...s, content: undefined })),
+        }));
+      }
+
+      return results;
+    },
+
+    async delete(id: string): Promise<void> {
+      const record = records.get(id);
+      if (record) {
+        records.delete(id);
+        byOutput.delete(record.outputId);
+        if (record.sessionId) {
+          bySession.get(record.sessionId)?.delete(id);
+        }
+      }
+    },
+
+    async deleteBySession(sessionId: string): Promise<void> {
+      const recordIds = bySession.get(sessionId);
+      if (recordIds) {
+        for (const id of recordIds) {
+          const record = records.get(id);
+          if (record) {
+            byOutput.delete(record.outputId);
+          }
+          records.delete(id);
+        }
+        bySession.delete(sessionId);
+      }
+    },
+  };
+}
+
+/**
+ * Redis-backed provenance store
+ */
+export function createRedisProvenanceStore(
+  redis: {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: { ex?: number }): Promise<unknown>;
+    del(key: string | string[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    sadd(key: string, ...members: string[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    srem(key: string, ...members: string[]): Promise<number>;
+  },
+  options: {
+    prefix?: string;
+    defaultTTL?: number;
+  } = {},
+) {
+  const { prefix = 'provenance:', defaultTTL = 86400 * 30 } = options; // 30 days default
+
+  function recordKey(id: string): string {
+    return `${prefix}record:${id}`;
+  }
+
+  function outputKey(outputId: string): string {
+    return `${prefix}output:${outputId}`;
+  }
+
+  function sessionKey(sessionId: string): string {
+    return `${prefix}session:${sessionId}`;
+  }
+
+  return {
+    async save(record: ProvenanceRecord, ttl?: number): Promise<void> {
+      const effectiveTTL = ttl || defaultTTL;
+      const serialized = JSON.stringify({
+        ...record,
+        createdAt: record.createdAt.toISOString(),
+        sources: record.sources.map(s => ({
+          ...s,
+          accessedAt: s.accessedAt.toISOString(),
+        })),
+        transformations: record.transformations.map(t => ({
+          ...t,
+          timestamp: t.timestamp.toISOString(),
+        })),
+      });
+
+      await redis.set(recordKey(record.id), serialized, { ex: effectiveTTL });
+      await redis.set(outputKey(record.outputId), record.id, { ex: effectiveTTL });
+
+      if (record.sessionId) {
+        await redis.sadd(sessionKey(record.sessionId), record.id);
+      }
+    },
+
+    async load(id: string): Promise<ProvenanceRecord | null> {
+      const data = await redis.get(recordKey(id));
+      if (!data) return null;
+
+      const parsed = JSON.parse(data);
+      return {
+        ...parsed,
+        createdAt: new Date(parsed.createdAt),
+        sources: parsed.sources.map((s: Record<string, unknown>) => ({
+          ...s,
+          accessedAt: new Date(s.accessedAt as string),
+        })),
+        transformations: parsed.transformations.map((t: Record<string, unknown>) => ({
+          ...t,
+          timestamp: new Date(t.timestamp as string),
+        })),
+      };
+    },
+
+    async loadByOutput(outputId: string): Promise<ProvenanceRecord | null> {
+      const recordId = await redis.get(outputKey(outputId));
+      return recordId ? this.load(recordId) : null;
+    },
+
+    async query(options: ProvenanceQueryOptions = {}): Promise<ProvenanceRecord[]> {
+      let recordIds: string[];
+
+      if (options.sessionId) {
+        recordIds = await redis.smembers(sessionKey(options.sessionId));
+      } else {
+        const keys = await redis.keys(`${prefix}record:*`);
+        recordIds = keys.map(k => k.replace(`${prefix}record:`, ''));
+      }
+
+      const records: ProvenanceRecord[] = [];
+      for (const id of recordIds) {
+        const record = await this.load(id);
+        if (record) {
+          records.push(record);
+        }
+      }
+
+      // Apply filters
+      let results = records;
+      const { after, before, sourceTypes, limit, includeContent } = options;
+
+      if (after) {
+        results = results.filter(r => r.createdAt >= after);
+      }
+
+      if (before) {
+        results = results.filter(r => r.createdAt <= before);
+      }
+
+      if (sourceTypes && sourceTypes.length > 0) {
+        results = results.filter(r => r.sources.some(s => sourceTypes.includes(s.type)));
+      }
+
+      results.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+
+      if (limit) {
+        results = results.slice(0, limit);
+      }
+
+      if (!includeContent) {
+        results = results.map(r => ({
+          ...r,
+          sources: r.sources.map(s => ({ ...s, content: undefined })),
+        }));
+      }
+
+      return results;
+    },
+
+    async delete(id: string): Promise<void> {
+      const record = await this.load(id);
+      if (record) {
+        await redis.del([recordKey(id), outputKey(record.outputId)]);
+        if (record.sessionId) {
+          await redis.srem(sessionKey(record.sessionId), id);
+        }
+      }
+    },
+
+    async deleteBySession(sessionId: string): Promise<void> {
+      const recordIds = await redis.smembers(sessionKey(sessionId));
+      for (const id of recordIds) {
+        const record = await this.load(id);
+        if (record) {
+          await redis.del([recordKey(id), outputKey(record.outputId)]);
+        }
+      }
+      await redis.del(sessionKey(sessionId));
+    },
+  };
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Simple content hash for verification
+ */
+function hashContent(content: string): string {
+  let hash = 0;
+  for (let i = 0; i < content.length; i++) {
+    const char = content.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash; // Convert to 32-bit integer
+  }
+  return Math.abs(hash).toString(16).padStart(8, '0');
+}
+
+/**
+ * Generate a citation from a provenance source
+ */
+export function generateCitation(source: ProvenanceSource): string {
+  const parts: string[] = [];
+
+  if (source.name) {
+    parts.push(source.name);
+  }
+
+  if (source.uri) {
+    parts.push(`(${source.uri})`);
+  }
+
+  if (source.accessedAt) {
+    parts.push(`[accessed ${source.accessedAt.toISOString().split('T')[0]}]`);
+  }
+
+  return parts.join(' ');
+}
+
+/**
+ * Generate a source attribution list
+ */
+export function generateAttributions(record: ProvenanceRecord): string[] {
+  return record.sources
+    .filter(s => s.type !== 'generated' && s.type !== 'system_prompt')
+    .map(s => generateCitation(s));
+}
+
+/**
+ * Verify content hasn't changed
+ */
+export function verifyContent(record: ProvenanceRecord, content: string): boolean {
+  if (!record.contentHash) return true;
+  return hashContent(content) === record.contentHash;
+}
+
+/**
+ * Calculate provenance depth (max transformation chain length)
+ */
+export function calculateProvenanceDepth(record: ProvenanceRecord): number {
+  const depths = new Map<string, number>();
+
+  // Root sources have depth 0
+  for (const rootId of record.rootSourceIds) {
+    depths.set(rootId, 0);
+  }
+
+  // Calculate depth for each transformation
+  for (const transformation of record.transformations) {
+    const inputDepths = transformation.inputSourceIds.map(id => depths.get(id) || 0);
+    const maxInputDepth = Math.max(...inputDepths, 0);
+    depths.set(transformation.outputSourceId, maxInputDepth + 1);
+  }
+
+  return Math.max(...Array.from(depths.values()), 0);
+}