agentic-json-repair 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,105 @@
+# agentic-json-repair
+
+[![npm version](https://badge.fury.io/js/agentic-json-repair.svg)](https://www.npmjs.com/package/agentic-json-repair)
+
+Repair and validate AI-generated JSON with auto-generated retry prompts. Perfect for building reliable AI agents and LLM pipelines.
+
+## Features
+
+- 🔧 **Auto-repair** malformed JSON (missing quotes, trailing commas, etc.)
+- 📝 **Extract JSON** from markdown code blocks or mixed prose
+- ✅ **Validate** against Zod schemas with full type inference
+- 🔄 **Auto-generate retry prompts** when validation fails
+
+## Installation
+
+```bash
+npm install agentic-json-repair zod
+```
+
+## Usage
+
+```typescript
+import { safeParseAI } from 'agentic-json-repair';
+import { z } from 'zod';
+
+// Define your expected schema
+const UserSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+});
+
+// Parse messy AI output
+const aiOutput = `
+  Sure! Here is the user data:
+  \`\`\`json
+  {
+    name: "Alice",
+    age: 30,
+  }
+  \`\`\`
+`;
+
+const result = safeParseAI(aiOutput, UserSchema);
+
+if (result.success) {
+  console.log(result.data); // { name: "Alice", age: 30 } - fully typed!
+} else {
+  // Use retry prompt to ask the AI to fix the output
+  console.log(result.retryPrompt);
+}
+```
+
+## API
+
+### `safeParseAI<T>(aiOutput: string, schema: ZodType<T>): AgenticParseResult<T>`
+
+Attempts to extract, repair, and validate JSON from an AI's text output.
+
+**Returns:**
+
+```typescript
+// On success
+{ success: true; data: T }
+
+// On failure
+{ success: false; error: string; retryPrompt: string }
+```
+
+## What it handles
+
+| Problem | Example | Fixed |
+|---------|---------|-------|
+| Markdown code blocks | `` ```json {...} ``` `` | ✅ |
+| Surrounding prose | "Here's the JSON: {...}" | ✅ |
+| Unquoted keys | `{ name: "Alice" }` | ✅ |
+| Trailing commas | `{ "a": 1, }` | ✅ |
+| Schema mismatches | Wrong types, missing fields | ✅ (retry prompt) |
+
+## Agentic Loop Example
+
+```typescript
+async function getStructuredData(prompt: string, schema: z.ZodType) {
+  let attempts = 0;
+  let currentPrompt = prompt;
+  
+  while (attempts < 3) {
+    const aiOutput = await callLLM(currentPrompt);
+    const result = safeParseAI(aiOutput, schema);
+    
+    if (result.success) {
+      return result.data;
+    }
+    
+    // Use the auto-generated retry prompt
+    currentPrompt = result.retryPrompt;
+    attempts++;
+  }
+  
+  throw new Error('Failed to get valid structured data');
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-json-repair",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Repair and validate AI-generated JSON with auto-generated retry prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -12,6 +12,10 @@
       "require": "./dist/index.js"
     }
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "test": "vitest run",

package/.vscode/extensions.json

@@ -1,3 +0,0 @@
-{
-  "recommendations": ["henrikdev.ag-quota"]
-}

package/src/index.test.ts

@@ -1,35 +0,0 @@
-import { expect, test } from 'vitest';
-import { safeParseAI } from './index';
-import { z } from 'zod';
-
-test('fixes broken AI output', () => {
-    const brokenAiOutput = `
-    Sure! Here is the user:
-    \`\`\`json
-    {
-      name: "Alice",
-      age: 30,
-    }
-    \`\`\`
-  `;
-
-    const UserSchema = z.object({ name: z.string(), age: z.number() });
-    const result = safeParseAI(brokenAiOutput, UserSchema);
-
-    expect(result.success).toBe(true);
-    if (result.success) {
-        expect(result.data.name).toBe("Alice");
-    }
-});
-
-test('generates retry prompt on wrong schema', () => {
-    const wrongTypeOutput = `{"age": "thirty"}`; // string instead of number
-    const Schema = z.object({ age: z.number() });
-
-    const result = safeParseAI(wrongTypeOutput, Schema);
-
-    expect(result.success).toBe(false);
-    if (!result.success) {
-        expect(result.retryPrompt).toContain("expected number, received string");
-    }
-});

package/src/index.ts

@@ -1,128 +0,0 @@
-import { jsonrepair } from 'jsonrepair';
-import { z } from 'zod';
-
-export type AgenticParseResult<T> =
-    | { success: true; data: T }
-    | { success: false; error: string; retryPrompt: string };
-
-/**
- * Attempts to extract, repair, and validate JSON from an AI's text output.
- * * @param aiOutput The raw string from the LLM (e.g., "Here is the data: ```json ...")
- * @param schema The Zod schema to validate against
- */
-/**
- * Extracts JSON content from AI output that may contain markdown code blocks or prose.
- */
-function extractJsonContent(aiOutput: string): string {
-    // First, try to extract from markdown code blocks
-    const codeBlockMatch = aiOutput.match(/```(?:json)?\s*([\s\S]*?)```/);
-    if (codeBlockMatch) {
-        return codeBlockMatch[1].trim();
-    }
-
-    // Otherwise, try to find the first JSON object or array
-    const firstBrace = aiOutput.indexOf('{');
-    const firstBracket = aiOutput.indexOf('[');
-
-    let startChar: '{' | '[';
-    let endChar: '}' | ']';
-    let startIndex: number;
-
-    if (firstBrace === -1 && firstBracket === -1) {
-        // No JSON structure found, return as-is for jsonrepair to handle
-        return aiOutput.trim();
-    } else if (firstBrace === -1) {
-        startChar = '[';
-        endChar = ']';
-        startIndex = firstBracket;
-    } else if (firstBracket === -1) {
-        startChar = '{';
-        endChar = '}';
-        startIndex = firstBrace;
-    } else {
-        // Both found, use whichever comes first
-        if (firstBrace < firstBracket) {
-            startChar = '{';
-            endChar = '}';
-            startIndex = firstBrace;
-        } else {
-            startChar = '[';
-            endChar = ']';
-            startIndex = firstBracket;
-        }
-    }
-
-    // Find the matching closing bracket/brace
-    let depth = 0;
-    let inString = false;
-    let escapeNext = false;
-
-    for (let i = startIndex; i < aiOutput.length; i++) {
-        const char = aiOutput[i];
-
-        if (escapeNext) {
-            escapeNext = false;
-            continue;
-        }
-
-        if (char === '\\' && inString) {
-            escapeNext = true;
-            continue;
-        }
-
-        if (char === '"') {
-            inString = !inString;
-            continue;
-        }
-
-        if (!inString) {
-            if (char === startChar) {
-                depth++;
-            } else if (char === endChar) {
-                depth--;
-                if (depth === 0) {
-                    return aiOutput.slice(startIndex, i + 1);
-                }
-            }
-        }
-    }
-
-    // If we couldn't find matching brackets, return from startIndex to end
-    return aiOutput.slice(startIndex).trim();
-}
-
-export function safeParseAI<T>(aiOutput: string, schema: z.ZodType<T>): AgenticParseResult<T> {
-    try {
-        // 1. Extract JSON: Find the JSON content within the AI output
-        const cleanOutput = extractJsonContent(aiOutput);
-
-        // 2. Repair JSON: Fixes missing quotes, trailing commas, etc.
-        const repairedJson = jsonrepair(cleanOutput);
-
-        // 3. Parse JSON
-        const parsedObject = JSON.parse(repairedJson);
-
-        // 4. Validate Schema
-        const validation = schema.safeParse(parsedObject);
-
-        if (validation.success) {
-            return { success: true, data: validation.data };
-        } else {
-            // 5. Generate a "Self-Correction" prompt for the AI
-            const issues = validation.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join(', ');
-            return {
-                success: false,
-                error: "Validation Failed",
-                retryPrompt: `The JSON was parsed but failed validation. Fix these issues: [${issues}] and return ONLY the JSON.`
-            };
-        }
-
-    } catch (error) {
-        // 6. Handle Syntax Errors that jsonrepair couldn't fix
-        return {
-            success: false,
-            error: "JSON Syntax Error",
-            retryPrompt: `The output was not valid JSON. Error: ${(error as Error).message}. Return ONLY valid JSON.`
-        };
-    }
-}

package/tsconfig.json

@@ -1,14 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "esModuleInterop": true,
-    "strict": true,
-    "declaration": true,
-    "outDir": "dist",
-    "skipLibCheck": true
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist"]
-}