@od-oneapp/ai-platform 0.1.0

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

@@ -0,0 +1,275 @@
+/**
+ * @fileoverview Proof map loop execution
+ *
+ * Implements the multi-model proof loop:
+ * 1. Sonnet 4.5 drafts reasoning + claims
+ * 2. GPT-4 Turbo verifies via semantic deltas
+ * 3. Apply safe edits and re-verify if needed
+ *
+ * Features:
+ * - 2-iteration fix loop (conservative error correction)
+ * - Safe-edit policy with constraints
+ * - Gated verification (critical claims must pass)
+ *
+ * @module @od-oneapp/ai-platform/proof-map/loop
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import { logError, logWarn } from '@repo/shared/logs';
+import { z } from 'zod';
+
+import { anthropic, openai, generateText } from '../../shared';
+
+import { applyPatch, validateSafeEdits } from './applyPatch';
+import { chainSchema, claimSchema, criticalClaimsPass, hasFailingChecks } from './schema';
+
+import type { ProofMap } from './schema';
+
+/**
+ * Options for running the proof loop.
+ */
+export interface ProofLoopOptions {
+  /** Prompt/question to generate proof for. */
+  prompt: string;
+  /**
+   * Maximum number of fix iterations.
+   * @default 2
+   */
+  maxIterations?: number;
+  /**
+   * Whether to auto-apply safe edits from verifier.
+   * @default true
+   */
+  autoApplySafeEdits?: boolean;
+  /**
+   * Optional metadata to attach to the proof.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Runs the multi-model proof loop.
+ * Executes draft → verify → fix cycle up to maxIterations times.
+ *
+ * Flow:
+ * 1. Sonnet 4.5 drafts reasoning + claims
+ * 2. GPT-4 Turbo verifies via semantic deltas
+ * 3. Apply safe edits and re-verify if needed
+ *
+ * @param options - Proof loop options.
+ * @param options.prompt - Prompt/question to generate proof for.
+ * @param options.maxIterations - Maximum fix iterations (defaults to 2).
+ * @param options.autoApplySafeEdits - Whether to auto-apply safe edits (defaults to true).
+ * @param options.metadata - Optional metadata to attach.
+ * @returns Proof map with status ('verified', 'needs_fixes', or 'rejected').
+ * @remarks Draft phase only runs on first iteration.
+ * Verification phase runs every iteration.
+ * Proof is verified if: no failing checks AND all critical claims pass.
+ * Safe edits are automatically applied if enabled and available.
+ * Returns 'rejected' status if draft or verification phase fails.
+ * @example
+ * ```ts
+ * const proof = await runProofLoop({
+ *   prompt: 'Calculate the ROI for this investment',
+ *   maxIterations: 2
+ * });
+ *
+ * if (proof.status === 'verified') {
+ *   console.log('Proof verified:', proof.draft.answer);
+ * }
+ * ```
+ */
+export const runProofLoop = async (options: ProofLoopOptions): Promise<ProofMap> => {
+  const { prompt, maxIterations = 2, autoApplySafeEdits = true, metadata = {} } = options;
+
+  let proof: ProofMap = {
+    task_id: randomUUID(),
+    inputs: { prompt, ...metadata },
+    draft: { answer: '', chains: [], claims: [] },
+    verifications: [],
+    status: 'needs_fixes',
+    created_at: new Date().toISOString(),
+  };
+
+  let iteration = 0;
+
+  while (iteration < maxIterations) {
+    iteration++;
+
+    // Phase 1: Draft (Sonnet 4.5)
+    if (iteration === 1) {
+      const draftSchema = z.object({
+        answer: z.string(),
+        chains: z.array(chainSchema),
+        claims: z.array(claimSchema),
+      });
+
+      try {
+        const draftResult = await generateText({
+          model: anthropic('claude-3-5-sonnet-20241022'),
+          system: `You are a reasoning assistant. Output JSON with:
+- answer: a clear answer to the user's question
+- chains: array of reasoning chains, each with id and steps (premise/deduction/calc)
+- claims: array of factual claims with id, text, and tags (e.g. ["fact", "finance"])
+
+For calculations, use steps like: {"i":1,"kind":"calc","expr":"(12*8)/3","result":32}
+Tag critical claims with: ["critical", "finance", "safety", "hipaa"] as appropriate.`,
+          prompt,
+          maxRetries: 2,
+        });
+
+        const parsed = JSON.parse(draftResult.text);
+        proof.draft = draftSchema.parse(parsed);
+      } catch (error) {
+        logError('[ProofLoop] Draft phase failed', { error });
+        proof.status = 'rejected';
+        return proof;
+      }
+    }
+
+    // Phase 2: Verify (GPT-4 Turbo as GPT-5 placeholder)
+    const verifySchema = z.object({
+      checks: z.array(
+        z.object({
+          target: z.string(),
+          status: z.enum(['pass', 'fail']),
+          note: z.string().optional(),
+        }),
+      ),
+      suggested_edits: z
+        .array(
+          z.object({
+            op: z.enum(['replace', 'remove', 'add']),
+            path: z.array(z.union([z.string(), z.number()])),
+
+            value: z.unknown().optional(),
+          }),
+        )
+        .optional(),
+    });
+
+    try {
+      const verifyResult = await generateText({
+        model: openai('gpt-4-turbo'),
+        system: `You are a verification assistant. Review the proof map and:
+1. Recompute all calculations
+2. Check factual consistency
+3. Verify reasoning steps
+4. Return JSON with:
+   - checks: array of {target, status, note}
+   - suggested_edits: array of safe edits to fix issues
+
+For target, use format like "calc:c1:3" or "claim:k1".
+Only suggest edits that are factually correct and low-risk (scalar replacements).`,
+        prompt: JSON.stringify(proof, null, 2),
+        maxRetries: 2,
+      });
+
+      const parsed = JSON.parse(verifyResult.text);
+      const verifyData = verifySchema.parse(parsed);
+
+      proof.verifications.push({
+        by: 'gpt-4-turbo',
+        method: 'semantic-delta',
+        checks: verifyData.checks,
+        suggested_edits: verifyData.suggested_edits,
+        timestamp: new Date().toISOString(),
+      });
+    } catch (error) {
+      logError('[ProofLoop] Verify phase failed', { error });
+      proof.status = 'rejected';
+      return proof;
+    }
+
+    // Phase 3: Gate + apply edits
+    const failed = hasFailingChecks(proof);
+    const criticalPass = criticalClaimsPass(proof);
+
+    if (!failed && criticalPass) {
+      proof.status = 'verified';
+      proof.updated_at = new Date().toISOString();
+      return proof;
+    }
+
+    // Apply safe edits if enabled
+    if (autoApplySafeEdits && iteration < maxIterations) {
+      const lastVerification = proof.verifications[proof.verifications.length - 1];
+      const edits = lastVerification?.suggested_edits ?? [];
+
+      if (edits.length > 0) {
+        const { safe } = validateSafeEdits(edits);
+        if (safe.length > 0) {
+          proof = applyPatch(proof, safe);
+          logWarn('[ProofLoop] Applied safe edits', { count: safe.length });
+          continue; // Re-verify with edits
+        }
+      }
+    }
+
+    // No more iterations or no safe edits to apply
+    break;
+  }
+
+  proof.status = 'needs_fixes';
+  proof.updated_at = new Date().toISOString();
+  return proof;
+};
+
+/**
+ * Simplified single-pass verification (no fix loop).
+ * Verifies a proof map once without applying edits or re-verifying.
+ *
+ * @param proof - Proof map to verify.
+ * @returns Updated proof map with verification results and status.
+ * @remarks Does not apply edits or re-verify. Single verification pass only.
+ * Status is set to 'verified' if no failing checks and critical claims pass,
+ * otherwise 'needs_fixes'. Returns 'rejected' if verification fails.
+ * @example
+ * ```ts
+ * const verified = await verifyProof(proof);
+ * console.log('Status:', verified.status);
+ * ```
+ */
+export const verifyProof = async (proof: ProofMap): Promise<ProofMap> => {
+  const verifySchema = z.object({
+    checks: z.array(
+      z.object({
+        target: z.string(),
+        status: z.enum(['pass', 'fail']),
+        note: z.string().optional(),
+      }),
+    ),
+  });
+
+  try {
+    const verifyResult = await generateText({
+      model: openai('gpt-4-turbo'),
+      system: 'Verify the proof map. Return JSON with checks array.',
+      prompt: JSON.stringify(proof, null, 2),
+      maxRetries: 2,
+    });
+
+    const parsed = JSON.parse(verifyResult.text);
+    const verifyData = verifySchema.parse(parsed);
+
+    const updated = { ...proof };
+    updated.verifications.push({
+      by: 'gpt-4-turbo',
+      method: 'semantic-delta',
+      checks: verifyData.checks,
+      timestamp: new Date().toISOString(),
+    });
+
+    const failed = hasFailingChecks(updated);
+    const criticalPass = criticalClaimsPass(updated);
+
+    updated.status = !failed && criticalPass ? 'verified' : 'needs_fixes';
+    updated.updated_at = new Date().toISOString();
+
+    return updated;
+  } catch (error) {
+    logError('[verifyProof] Failed', { error });
+    return { ...proof, status: 'rejected', updated_at: new Date().toISOString() };
+  }
+};

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

@@ -0,0 +1,217 @@
+/**
+ * @fileoverview Proof map schema definitions
+ *
+ * Defines Zod schemas for proof maps, a hierarchical verification framework
+ * for AI-generated content. Supports chains, steps, claims, checks, and edits.
+ *
+ * @module @od-oneapp/ai-platform/proof-map/schema
+ */
+
+import { z } from 'zod';
+
+/** Check status values ('pass' or 'fail'). */
+export const checkStatus = z.enum(['pass', 'fail']);
+/** Proof status values ('needs_fixes', 'verified', or 'rejected'). */
+export const proofStatus = z.enum(['needs_fixes', 'verified', 'rejected']);
+
+/**
+ * Step schema (discriminated union by kind).
+ * Supports premise, quote, deduction, and calculation steps.
+ */
+export const stepSchema = z.discriminatedUnion('kind', [
+  z.object({
+    i: z.number(),
+    kind: z.literal('premise'),
+    text: z.string(),
+    source: z.enum(['user', 'doc', 'web']),
+  }),
+  z.object({
+    i: z.number(),
+    kind: z.literal('quote'),
+    text: z.string(),
+    source: z.enum(['user', 'doc', 'web']),
+  }),
+  z.object({
+    i: z.number(),
+    kind: z.literal('deduction'),
+    text: z.string(),
+  }),
+  z.object({
+    i: z.number(),
+    kind: z.literal('calc'),
+    expr: z.string(),
+    result: z.number(),
+  }),
+]);
+
+/**
+ * Chain schema (reasoning chain with steps).
+ */
+export const chainSchema = z.object({
+  /** Chain identifier. */
+  id: z.string(),
+  /** Array of reasoning steps. */
+  steps: z.array(stepSchema),
+});
+
+/**
+ * Claim schema (factual claim with tags).
+ */
+export const claimSchema = z.object({
+  /** Claim identifier. */
+  id: z.string(),
+  /** Claim text. */
+  text: z.string(),
+  /** Tags for categorization (e.g., ['critical', 'finance']). */
+  tags: z.array(z.string()),
+});
+
+/**
+ * Check schema (verification check result).
+ */
+export const checkSchema = z.object({
+  /** Target identifier (e.g., 'calc:c1:3' or 'claim:k1'). */
+  target: z.string(),
+  /** Check status ('pass' or 'fail'). */
+  status: checkStatus,
+  /** Optional note explaining the check result. */
+  note: z.string().optional(),
+});
+
+/**
+ * Edit schema (JSON-Patch-like edit operation).
+ */
+export const editSchema = z.object({
+  /** Edit operation ('replace', 'remove', or 'add'). */
+  op: z.enum(['replace', 'remove', 'add']),
+  /** Path to the target (array of strings/numbers). */
+  path: z.array(z.union([z.string(), z.number()])),
+  /** Optional value for replace/add operations. */
+
+  value: z.unknown().optional(),
+});
+
+/**
+ * Verification schema (verification result with checks and edits).
+ */
+export const verificationSchema = z.object({
+  /** Verifier identifier (model name). */
+  by: z.string(),
+  /** Verification method (e.g., 'semantic-delta'). */
+  method: z.string(),
+  /** Array of verification checks. */
+  checks: z.array(checkSchema),
+  /** Optional suggested edits to fix issues. */
+  suggested_edits: z.array(editSchema).optional(),
+  /** Optional ISO timestamp. */
+  timestamp: z.string().optional(),
+});
+
+/**
+ * Proof map schema (complete proof structure).
+ */
+export const proofMapSchema = z.object({
+  /** Task identifier. */
+  task_id: z.string(),
+  /** Input parameters. */
+
+  inputs: z.record(z.string(), z.unknown()),
+  /** Draft answer with chains and claims. */
+  draft: z.object({
+    /** Answer text. */
+    answer: z.string(),
+    /** Reasoning chains. */
+    chains: z.array(chainSchema),
+    /** Factual claims. */
+    claims: z.array(claimSchema),
+  }),
+  /** Array of verifications. */
+  verifications: z.array(verificationSchema),
+  /** Proof status. */
+  status: proofStatus,
+  /** Optional creation timestamp. */
+  created_at: z.string().optional(),
+  /** Optional update timestamp. */
+  updated_at: z.string().optional(),
+});
+
+/** Check status type. */
+export type CheckStatus = z.infer<typeof checkStatus>;
+/** Proof status type. */
+export type ProofStatus = z.infer<typeof proofStatus>;
+/** Step type. */
+export type Step = z.infer<typeof stepSchema>;
+/** Chain type. */
+export type Chain = z.infer<typeof chainSchema>;
+/** Claim type. */
+export type Claim = z.infer<typeof claimSchema>;
+/** Check type. */
+export type Check = z.infer<typeof checkSchema>;
+/** Edit type. */
+export type Edit = z.infer<typeof editSchema>;
+/** Verification type. */
+export type Verification = z.infer<typeof verificationSchema>;
+/** Proof map type. */
+export type ProofMap = z.infer<typeof proofMapSchema>;
+
+/**
+ * Checks if a proof has any failing checks.
+ *
+ * @param proof - Proof map to check.
+ * @returns `true` if any verification has failing checks, `false` otherwise.
+ * @example
+ * ```ts
+ * if (hasFailingChecks(proof)) {
+ *   console.log('Proof has issues');
+ * }
+ * ```
+ */
+export const hasFailingChecks = (proof: ProofMap): boolean =>
+  proof.verifications.some(verification =>
+    verification.checks.some(check => check.status === 'fail'),
+  );
+
+/**
+ * Gets critical claims from a proof map.
+ * Critical claims are tagged with: 'critical', 'finance', 'safety', 'hipaa', or 'compliance'.
+ *
+ * @param proof - Proof map to extract claims from.
+ * @returns Array of critical claims.
+ * @example
+ * ```ts
+ * const critical = getCriticalClaims(proof);
+ * console.log(`Found ${critical.length} critical claims`);
+ * ```
+ */
+export const getCriticalClaims = (proof: ProofMap): Claim[] => {
+  const criticalTags = new Set(['critical', 'finance', 'safety', 'hipaa', 'compliance']);
+  return proof.draft.claims.filter(claim =>
+    claim.tags.some(tag => criticalTags.has(tag.toLowerCase())),
+  );
+};
+
+/**
+ * Checks if all critical claims have passing checks.
+ * Returns `true` if there are no critical claims or all critical claims pass.
+ *
+ * @param proof - Proof map to check.
+ * @returns `true` if all critical claims pass, `false` otherwise.
+ * @example
+ * ```ts
+ * if (criticalClaimsPass(proof)) {
+ *   console.log('All critical claims verified');
+ * }
+ * ```
+ */
+export const criticalClaimsPass = (proof: ProofMap): boolean => {
+  const critical = getCriticalClaims(proof);
+  if (critical.length === 0) return true;
+
+  const criticalIds = new Set(critical.map(claim => claim.id));
+  const allChecks = proof.verifications.flatMap(verification => verification.checks);
+  const criticalChecks = allChecks.filter(check =>
+    [...criticalIds].some(id => check.target.includes(id)),
+  );
+
+  return criticalChecks.length > 0 && criticalChecks.every(c => c.status === 'pass');
+};