"use client" import { useCallback, useMemo, useRef, useState } from "react" import { AnimatePresence, motion } from "motion/react" // ============================================================================ // TYPES // ============================================================================ export interface ValidationResult { success: boolean data: unknown originalOutput: string repairedOutput?: string wasRepaired: boolean repairs: RepairAction[] validationErrors: ValidationError[] attempts: number totalLatencyMs: number } export interface RepairAction { type: RepairType description: string position?: { start: number; end: number } before: string after: string } export type RepairType = | "fix_truncation" | "fix_trailing_comma" | "fix_single_quotes" | "fix_unquoted_keys" | "fix_missing_brackets" | "fix_code_block" | "fix_extra_content" | "strip_markdown" export interface ValidationError { path: string message: string expected?: string received?: string } export interface ValidatorConfig { maxRetries?: number enableAutoRepair?: boolean enableCorrectivePrompting?: boolean strictMode?: boolean timeout?: number } export interface SchemaField { name: string type: string required: boolean description?: string } // ============================================================================ // JSON REPAIR ENGINE // ============================================================================ export function repairJSON(input: string): { output: string repairs: RepairAction[] } { const repairs: RepairAction[] = [] let output = input.trim() // 1. Strip markdown code blocks const codeBlockMatch = output.match(/```(?:json)?\s*([\s\S]*?)```/) if (codeBlockMatch) { repairs.push({ type: "fix_code_block", description: "Removed markdown code block wrapper", before: output.slice(0, 20) + "...", after: codeBlockMatch[1].slice(0, 20) + "...", }) output = codeBlockMatch[1].trim() } // 2. Strip leading text before JSON const jsonStartMatch = output.match(/^[^{\[]*?([\{\[])/) if (jsonStartMatch && jsonStartMatch.index && jsonStartMatch.index > 0) { const leadingText = output.slice(0, jsonStartMatch.index) repairs.push({ type: "strip_markdown", description: "Removed leading text before JSON", before: leadingText.slice(0, 30), after: "", }) output = output.slice(jsonStartMatch.index) } // 3. Strip trailing text after JSON let depth = 0 let inString = false let escape = false let jsonEnd = -1 for (let i = 0; i < output.length; i++) { const char = output[i] if (escape) { escape = false continue } if (char === "\\") { escape = true continue } if (char === '"' && !escape) { inString = !inString continue } if (!inString) { if (char === "{" || char === "[") depth++ if (char === "}" || char === "]") { depth-- if (depth === 0) { jsonEnd = i + 1 break } } } } if (jsonEnd > 0 && jsonEnd < output.length) { const trailing = output.slice(jsonEnd) if (trailing.trim()) { repairs.push({ type: "fix_extra_content", description: "Removed trailing content after JSON", before: trailing.slice(0, 30), after: "", }) output = output.slice(0, jsonEnd) } } // 4. Fix single quotes to double quotes (outside of strings) const singleQuotePattern = /'/g if (singleQuotePattern.test(output) && !output.includes('"')) { repairs.push({ type: "fix_single_quotes", description: "Replaced single quotes with double quotes", before: "'key'", after: '"key"', }) output = output.replace(/'/g, '"') } // 5. Fix unquoted keys const unquotedKeyPattern = /(\{|,)\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*:/g if (unquotedKeyPattern.test(output)) { const before = output.match(unquotedKeyPattern)?.[0] || "" output = output.replace(unquotedKeyPattern, '$1"$2":') repairs.push({ type: "fix_unquoted_keys", description: "Added quotes to unquoted object keys", before, after: before.replace(/([a-zA-Z_][a-zA-Z0-9_]*)/, '"$1"'), }) } // 6. Fix trailing commas const trailingCommaPattern = /,(\s*[}\]])/g if (trailingCommaPattern.test(output)) { repairs.push({ type: "fix_trailing_comma", description: "Removed trailing comma before closing bracket", before: ",}", after: "}", }) output = output.replace(trailingCommaPattern, "$1") } // 7. Fix missing closing brackets (truncation) try { JSON.parse(output) } catch { // Count brackets let openBraces = 0 let openBrackets = 0 inString = false escape = false for (const char of output) { if (escape) { escape = false continue } if (char === "\\") { escape = true continue } if (char === '"' && !escape) { inString = !inString continue } if (!inString) { if (char === "{") openBraces++ if (char === "}") openBraces-- if (char === "[") openBrackets++ if (char === "]") openBrackets-- } } // Close unclosed strings if in string if (inString) { output += '"' repairs.push({ type: "fix_truncation", description: "Closed unclosed string", before: "...", after: '..."', }) } // Add missing closing brackets const closings: string[] = [] for (let i = 0; i < openBrackets; i++) closings.push("]") for (let i = 0; i < openBraces; i++) closings.push("}") if (closings.length > 0) { repairs.push({ type: "fix_missing_brackets", description: `Added ${closings.length} missing closing bracket(s)`, before: output.slice(-10), after: output.slice(-10) + closings.join(""), }) output += closings.join("") } } return { output, repairs } } // ============================================================================ // SIMPLE SCHEMA VALIDATOR // ============================================================================ export function validateSchema( data: unknown, schema: SchemaField[] ): ValidationError[] { const errors: ValidationError[] = [] if (typeof data !== "object" || data === null) { errors.push({ path: "$", message: "Expected object, received " + typeof data, expected: "object", received: typeof data, }) return errors } const obj = data as Record for (const field of schema) { const value = obj[field.name] if (field.required && (value === undefined || value === null)) { errors.push({ path: field.name, message: `Required field "${field.name}" is missing`, expected: field.type, received: "undefined", }) continue } if (value !== undefined && value !== null) { const actualType = Array.isArray(value) ? "array" : typeof value const expectedTypes = field.type .toLowerCase() .split("|") .map((t) => t.trim()) if (!expectedTypes.includes(actualType)) { errors.push({ path: field.name, message: `Field "${field.name}" has wrong type`, expected: field.type, received: actualType, }) } } } return errors } // ============================================================================ // HOOK: useStructuredOutput // ============================================================================ interface UseStructuredOutputOptions extends ValidatorConfig { schema?: SchemaField[] onValidationSuccess?: (result: ValidationResult) => void onValidationFailure?: (result: ValidationResult) => void onRepair?: (repairs: RepairAction[]) => void } export function useStructuredOutput(options: UseStructuredOutputOptions = {}) { const { maxRetries = 3, enableAutoRepair = true, enableCorrectivePrompting = true, strictMode = false, schema = [], onValidationSuccess, onValidationFailure, onRepair, } = options const [lastResult, setLastResult] = useState(null) const [isValidating, setIsValidating] = useState(false) const [stats, setStats] = useState({ totalValidations: 0, successCount: 0, repairCount: 0, failureCount: 0, }) // Validate and optionally repair JSON output const validateOutput = useCallback( async ( rawOutput: string, retryFn?: (feedback: string) => Promise ): Promise => { setIsValidating(true) const startTime = performance.now() let attempts = 0 let currentOutput = rawOutput const allRepairs: RepairAction[] = [] try { while (attempts < maxRetries) { attempts++ // Step 1: Try to parse as-is let parsed: unknown let parseError: Error | null = null try { parsed = JSON.parse(currentOutput) } catch (e) { parseError = e as Error } // Step 2: If parse failed and auto-repair enabled, try repair if (parseError && enableAutoRepair) { const { output: repairedOutput, repairs } = repairJSON(currentOutput) if (repairs.length > 0) { allRepairs.push(...repairs) onRepair?.(repairs) try { parsed = JSON.parse(repairedOutput) currentOutput = repairedOutput parseError = null } catch { // Repair didn't fully fix it } } } // Step 3: If still failed and corrective prompting enabled, retry if ( parseError && enableCorrectivePrompting && retryFn && attempts < maxRetries ) { const feedback = `Your previous response was not valid JSON. Error: ${parseError.message}. Please respond with ONLY valid JSON, no markdown or explanation.` currentOutput = await retryFn(feedback) continue } // Step 4: If we have valid JSON, validate against schema if (!parseError && parsed !== undefined) { const schemaErrors = schema.length > 0 ? validateSchema(parsed, schema) : [] if (schemaErrors.length === 0 || !strictMode) { const result: ValidationResult = { success: schemaErrors.length === 0, data: parsed, originalOutput: rawOutput, repairedOutput: allRepairs.length > 0 ? currentOutput : undefined, wasRepaired: allRepairs.length > 0, repairs: allRepairs, validationErrors: schemaErrors, attempts, totalLatencyMs: performance.now() - startTime, } setLastResult(result) setStats((prev) => ({ ...prev, totalValidations: prev.totalValidations + 1, successCount: prev.successCount + 1, repairCount: prev.repairCount + (allRepairs.length > 0 ? 1 : 0), })) onValidationSuccess?.(result) return result } // Schema validation failed, try corrective prompting if (enableCorrectivePrompting && retryFn && attempts < maxRetries) { const feedback = `Your JSON is valid but doesn't match the expected schema. Errors: ${schemaErrors.map((e) => e.message).join(", ")}. Please fix these issues.` currentOutput = await retryFn(feedback) continue } } // If we get here without success, break the loop if (parseError) { break } } // All retries exhausted const result: ValidationResult = { success: false, data: null, originalOutput: rawOutput, repairedOutput: allRepairs.length > 0 ? currentOutput : undefined, wasRepaired: allRepairs.length > 0, repairs: allRepairs, validationErrors: [ { path: "$", message: "Failed to parse valid JSON after all retries", }, ], attempts, totalLatencyMs: performance.now() - startTime, } setLastResult(result) setStats((prev) => ({ ...prev, totalValidations: prev.totalValidations + 1, failureCount: prev.failureCount + 1, })) onValidationFailure?.(result) return result } finally { setIsValidating(false) } }, [ maxRetries, enableAutoRepair, enableCorrectivePrompting, strictMode, schema, onValidationSuccess, onValidationFailure, onRepair, ] ) // Quick parse without retries const quickParse = useCallback( ( rawOutput: string ): { success: boolean; data: unknown; error?: string } => { try { const { output } = enableAutoRepair ? repairJSON(rawOutput) : { output: rawOutput } const data = JSON.parse(output) return { success: true, data } } catch (e) { return { success: false, data: null, error: (e as Error).message } } }, [enableAutoRepair] ) return { validateOutput, quickParse, lastResult, isValidating, stats, } } // ============================================================================ // VALIDATION STATUS BADGE // ============================================================================ interface ValidationStatusBadgeProps { result: ValidationResult | null size?: "sm" | "md" } export function ValidationStatusBadge({ result, size = "md", }: ValidationStatusBadgeProps) { if (!result) return null const sizeClasses = size === "sm" ? "px-2 py-0.5 text-[10px]" : "px-3 py-1.5 text-xs" return ( {result.success ? ( ) : ( )} {result.success ? "VALID" : "INVALID"} {result.wasRepaired && ( Repaired )} {result.attempts} attempt{result.attempts > 1 ? "s" : ""} {result.totalLatencyMs.toFixed(0)}ms ) } // ============================================================================ // REPAIR LOG // ============================================================================ interface RepairLogProps { repairs: RepairAction[] } export function RepairLog({ repairs }: RepairLogProps) { if (repairs.length === 0) { return (

No repairs needed

) } const repairTypeConfig: Record< RepairType, { icon: React.ReactNode; color: string } > = { fix_truncation: { icon: , color: "text-red-500", }, fix_trailing_comma: { icon: , color: "text-amber-500", }, fix_single_quotes: { icon: , color: "text-blue-500", }, fix_unquoted_keys: { icon: , color: "text-purple-500", }, fix_missing_brackets: { icon: , color: "text-orange-500", }, fix_code_block: { icon: , color: "text-cyan-500", }, fix_extra_content: { icon: , color: "text-pink-500", }, strip_markdown: { icon: , color: "text-emerald-500", }, } return (

{repairs.length} repair{repairs.length > 1 ? "s" : ""} applied

{repairs.map((repair, index) => { const config = repairTypeConfig[repair.type] return (

{config.icon}

{repair.description}

-{" "} {repair.before || "(empty)"}

+{" "} {repair.after || "(empty)"}

) })}

) } // ============================================================================ // VALIDATION ERRORS LIST // ============================================================================ interface ValidationErrorsListProps { errors: ValidationError[] } export function ValidationErrorsList({ errors }: ValidationErrorsListProps) { if (errors.length === 0) { return (

All validations passed

) } return (

{errors.length} validation error{errors.length > 1 ? "s" : ""}

{errors.map((error, index) => (


                {error.path}

{error.message}

{(error.expected || error.received) && (

{error.expected && (

Expected:{" "} {error.expected}

)} {error.received && (

Received:{" "} {error.received}

)}

)} ))}

) } // ============================================================================ // VALIDATOR STATS PANEL // ============================================================================ interface ValidatorStatsPanelProps { stats: { totalValidations: number successCount: number repairCount: number failureCount: number } } export function ValidatorStatsPanel({ stats }: ValidatorStatsPanelProps) { const successRate = stats.totalValidations > 0 ? (stats.successCount / stats.totalValidations) * 100 : 0 const repairRate = stats.totalValidations > 0 ? (stats.repairCount / stats.totalValidations) * 100 : 0 return (

Validation Statistics

} color="zinc" /> } color="emerald" /> } color="amber" /> } color="red" />

{/* Success/Failure bar */} {stats.totalValidations > 0 && (

Success: {successRate.toFixed(0)}% Repaired: {repairRate.toFixed(0)}%

)}

) } function StatCard({ label, value, icon, color, }: { label: string value: string icon: React.ReactNode color: "emerald" | "amber" | "red" | "zinc" }) { const colorClasses = { emerald: "bg-emerald-500/10 text-emerald-600 dark:text-emerald-400", amber: "bg-amber-500/10 text-amber-600 dark:text-amber-400", red: "bg-red-500/10 text-red-600 dark:text-red-400", zinc: "bg-zinc-500/10 text-zinc-600 dark:text-zinc-400", } return (

{icon}

{value}

{label}

) } // ============================================================================ // JSON DIFF VIEWER // ============================================================================ interface JSONDiffViewerProps { original: string repaired: string } export function JSONDiffViewer({ original, repaired }: JSONDiffViewerProps) { const formatJSON = (str: string): string => { try { return JSON.stringify(JSON.parse(str), null, 2) } catch { return str } } return (

Original

          {formatJSON(original)}

Repaired

          {formatJSON(repaired)}

) } // ============================================================================ // SCHEMA EDITOR // ============================================================================ interface SchemaEditorProps { schema: SchemaField[] onChange: (schema: SchemaField[]) => void } export function SchemaEditor({ schema, onChange }: SchemaEditorProps) { const addField = () => { onChange([...schema, { name: "", type: "string", required: true }]) } const updateField = (index: number, updates: Partial) => { const newSchema = [...schema] newSchema[index] = { ...newSchema[index], ...updates } onChange(newSchema) } const removeField = (index: number) => { onChange(schema.filter((_, i) => i !== index)) } return (

Expected Schema

{schema.length === 0 ? (

No schema defined. Add fields to enable validation.

) : (

{schema.map((field, index) => (

updateField(index, { name: e.target.value })} placeholder="Field name" className="flex-1 rounded border border-border bg-background px-2 py-1 text-xs focus:outline-none focus:ring-1 focus:ring-ring" /> updateField(index, { required: e.target.checked }) } className="rounded" /> Required

))}

)}

) } // ============================================================================ // ICONS // ============================================================================ function CheckCircleIcon({ className }: { className?: string }) { return ( ) } function XCircleIcon({ className }: { className?: string }) { return ( ) } function WrenchIcon({ className }: { className?: string }) { return ( ) } function AlertTriangleIcon({ className }: { className?: string }) { return ( ) } function LayersIcon({ className }: { className?: string }) { return ( ) } function ArrowRightIcon({ className }: { className?: string }) { return ( ) } function ScissorsIcon({ className }: { className?: string }) { return ( ) } function CommaIcon({ className }: { className?: string }) { return ( ) } function QuoteIcon({ className }: { className?: string }) { return ( ) } function KeyIcon({ className }: { className?: string }) { return ( ) } function BracketsIcon({ className }: { className?: string }) { return ( ) } function CodeIcon({ className }: { className?: string }) { return ( ) } function TrashIcon({ className }: { className?: string }) { return ( ) } function FileTextIcon({ className }: { className?: string }) { return ( ) } function XIcon({ className }: { className?: string }) { return ( ) }

structured-output-validator