llm-fns 1.0.7 → 1.0.9

package/dist/createJsonSchemaLlmClient.d.ts

@@ -23,7 +23,7 @@ export interface CreateJsonSchemaLlmClientParams {
     disableJsonFixer?: boolean;
 }
 export declare function createJsonSchemaLlmClient(params: CreateJsonSchemaLlmClientParams): {
-    promptJson: <T>(messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], schema: Record<string, any>, validator: (data: any) => T, options?: JsonSchemaLlmClientOptions) => Promise<T>;
+    promptJson: <T>(messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], schema: Record<string, any>, options?: JsonSchemaLlmClientOptions) => Promise<T>;
     isPromptJsonCached: (messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], schema: Record<string, any>, options?: JsonSchemaLlmClientOptions) => Promise<boolean>;
 };
 export type JsonSchemaClient = ReturnType<typeof createJsonSchemaLlmClient>;

package/dist/createJsonSchemaLlmClient.js

@@ -1,10 +1,15 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createJsonSchemaLlmClient = createJsonSchemaLlmClient;
+const ajv_1 = __importDefault(require("ajv"));
 const createLlmRetryClient_js_1 = require("./createLlmRetryClient.js");
 function createJsonSchemaLlmClient(params) {
     const { prompt, isPromptCached, fallbackPrompt, disableJsonFixer = false } = params;
     const llmRetryClient = (0, createLlmRetryClient_js_1.createLlmRetryClient)({ prompt, fallbackPrompt });
+    const ajv = new ajv_1.default({ strict: false }); // Initialize AJV
     async function _tryToFixJson(brokenResponse, schemaJsonString, errorDetails, options) {
         const fixupPrompt = `
 An attempt to generate a JSON object resulted in the following output, which is either not valid JSON or does not conform to the required schema.
@@ -140,7 +145,17 @@ ${schemaJsonString}`;
             : undefined;
         return { finalMessages, schemaJsonString, response_format };
     }
-    async function promptJson(messages, schema, validator, options) {
+    async function promptJson(messages, schema, options) {
+        // Always validate against the schema using AJV
+        const ajvValidator = (data) => {
+            const validate = ajv.compile(schema);
+            const valid = validate(data);
+            if (!valid) {
+                const errors = validate.errors?.map(e => `${e.instancePath} ${e.message}`).join(', ');
+                throw new Error(`AJV Validation Error: ${errors}`);
+            }
+            return data;
+        };
         const { finalMessages, schemaJsonString, response_format } = _getJsonPromptConfig(messages, schema, options);
         const processResponse = async (llmResponseString) => {
             let jsonData;
@@ -155,7 +170,7 @@ The response provided was not valid JSON. Please correct it.`;
                 throw new createLlmRetryClient_js_1.LlmRetryError(errorMessage, 'JSON_PARSE_ERROR', undefined, llmResponseString);
             }
             try {
-                const validatedData = await _validateOrFix(jsonData, validator, schemaJsonString, options);
+                const validatedData = await _validateOrFix(jsonData, ajvValidator, schemaJsonString, options);
                 return validatedData;
             }
             catch (validationError) {

package/dist/createZodLlmClient.js

@@ -36,7 +36,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeZodArgs = normalizeZodArgs;
 exports.createZodLlmClient = createZodLlmClient;
 const z = __importStar(require("zod"));
-const zod_1 = require("zod");
 function isZodSchema(obj) {
     return (typeof obj === 'object' &&
         obj !== null &&
@@ -94,19 +93,11 @@ function createZodLlmClient(params) {
         const schema = z.toJSONSchema(dataExtractionSchema, {
             unrepresentable: 'any'
         });
-        const validator = (data) => {
-            try {
-                return dataExtractionSchema.parse(data);
-            }
-            catch (error) {
-                if (error instanceof zod_1.ZodError) {
-                    // Format the error nicely for the LLM
-                    throw new Error(JSON.stringify(error.format(), null, 2));
-                }
-                throw error;
-            }
-        };
-        return jsonSchemaClient.promptJson(messages, schema, validator, options);
+        const result = await jsonSchemaClient.promptJson(messages, schema, options);
+        // We still parse with Zod to ensure the types are correct and to apply any transformations/refinements
+        // that JSON Schema might not capture perfectly, or just to get the typed return.
+        // Note: If this fails, it won't trigger a retry in promptJson anymore, because promptJson only retries on AJV errors.
+        return dataExtractionSchema.parse(result);
     }
     async function isPromptZodCached(arg1, arg2, arg3, arg4) {
         const { messages, dataExtractionSchema, options } = normalizeZodArgs(arg1, arg2, arg3, arg4);

package/dist/llmFactory.d.ts

@@ -14,7 +14,7 @@ export declare function createLlm(params: CreateLlmFactoryParams): {
         <T extends import("zod").ZodType>(prompt: string, schema: T, options?: import("./createZodLlmClient.js").ZodLlmClientOptions): Promise<boolean>;
         <T extends import("zod").ZodType>(mainInstruction: string, userMessagePayload: string | import("openai/resources/index.js").ChatCompletionContentPart[], dataExtractionSchema: T, options?: import("./createZodLlmClient.js").ZodLlmClientOptions): Promise<boolean>;
     };
-    promptJson: <T>(messages: import("openai/resources/index.js").ChatCompletionMessageParam[], schema: Record<string, any>, validator: (data: any) => T, options?: import("./createJsonSchemaLlmClient.js").JsonSchemaLlmClientOptions) => Promise<T>;
+    promptJson: <T>(messages: import("openai/resources/index.js").ChatCompletionMessageParam[], schema: Record<string, any>, options?: import("./createJsonSchemaLlmClient.js").JsonSchemaLlmClientOptions) => Promise<T>;
     isPromptJsonCached: (messages: import("openai/resources/index.js").ChatCompletionMessageParam[], schema: Record<string, any>, options?: import("./createJsonSchemaLlmClient.js").JsonSchemaLlmClientOptions) => Promise<boolean>;
     promptRetry: {
         <T = import("openai/resources/index.js").ChatCompletion>(content: string, options?: Omit<import("./createLlmRetryClient.js").LlmRetryOptions<T>, "messages">): Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-fns",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,6 +11,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "ajv": "^8.17.1",
     "openai": "^6.9.1",
     "zod": "^4.1.13"
   },

package/readme.md

@@ -7,7 +7,7 @@ Designed for power users who need to switch between simple string prompts and co
 ## Installation
 
 ```bash
-npm install openai zod cache-manager p-queue
+npm install openai zod cache-manager p-queue ajv
 ```
 
 ## Quick Start (Factory)
@@ -115,47 +115,49 @@ const buffer2 = await llm.promptImage({
 
 ---
 
-# Use Case 3: Structured Data (`llm.promptZod`)
+# Use Case 3: Structured Data (`llm.promptJson` & `llm.promptZod`)
 
-This is a high-level wrapper that employs a **Re-asking Loop**. If the LLM outputs invalid JSON or data that fails the Zod schema validation, the client automatically feeds the error back to the LLM and asks it to fix it (up to `maxRetries`).
+This is a high-level wrapper that employs a **Re-asking Loop**. If the LLM outputs invalid JSON or data that fails the schema validation, the client automatically feeds the error back to the LLM and asks it to fix it (up to `maxRetries`).
 
-**Return Type:** `Promise<z.infer<typeof Schema>>`
+**Return Type:** `Promise<T>`
 
-### Level 1: Generation (Schema Only)
-The client "hallucinates" data matching the shape.
+### Level 1: Raw JSON Schema (`promptJson`)
+Use this if you have a standard JSON Schema object (e.g. from another library or API) and don't want to use Zod. It uses **AJV** internally to validate the response against the schema.
 
 ```typescript
-import { z } from 'zod';
-const UserSchema = z.object({ name: z.string(), age: z.number() });
+const MySchema = {
+    type: "object",
+    properties: {
+        sentiment: { type: "string", enum: ["positive", "negative"] },
+        score: { type: "number" }
+    },
+    required: ["sentiment", "score"],
+    additionalProperties: false
+};
 
-// Input: Schema only
-const user = await llm.promptZod(UserSchema);
-// Output: { name: "Alice", age: 32 }
+const result = await llm.promptJson(
+    [{ role: "user", content: "I love this!" }],
+    MySchema
+);
 ```
 
-### Level 2: Extraction (Injection Shortcuts)
-Pass context alongside the schema. This automates the "System Prompt JSON Injection".
+### Level 2: Zod Wrapper (`promptZod`)
+This is syntactic sugar over `promptJson`. It converts your Zod schema to JSON Schema and automatically sets up the validator to throw formatted Zod errors for the retry loop.
 
-```typescript
-// 1. Extract from String
-const email = "Meeting at 2 PM with Bob.";
-const event = await llm.promptZod(email, z.object({ time: z.string(), who: z.string() }));
+**Return Type:** `Promise<z.infer<typeof Schema>>`
 
-// 2. Strict Separation (System, User, Schema)
-// Useful for auditing code or translations where instructions must not bleed into data.
-const analysis = await llm.promptZod(
-    "You are a security auditor.", // Arg 1: System
-    "function dangerous() {}",     // Arg 2: User Data
-    SecuritySchema                 // Arg 3: Schema
-);
-```
+```typescript
+import { z } from 'zod';
+const UserSchema = z.object({ name: z.string(), age: z.number() });
 
-### Level 3: State & Options (History + Config)
-Process full chat history into state, and use the **Options Object (4th Argument)** to control the internals (Models, Retries, Caching).
+// 1. Schema Only (Hallucinate data)
+const user = await llm.promptZod(UserSchema);
 
-**Input Type:** `ZodLlmClientOptions`
+// 2. Extraction (Context + Schema)
+const email = "Meeting at 2 PM with Bob.";
+const event = await llm.promptZod(email, z.object({ time: z.string(), who: z.string() }));
 
-```typescript
+// 3. Full Control (History + Schema + Options)
 const history = [
     { role: "user", content: "I cast Fireball." },
     { role: "assistant", content: "It misses." }
@@ -173,12 +175,12 @@ const gameState = await llm.promptZod(
 );
 ```
 
-### Level 4: Hooks & Pre-processing
-Sometimes LLMs output data that is *almost* correct (e.g., strings for numbers). You can sanitize data before Zod validation runs.
+### Level 3: Hooks & Pre-processing
+Sometimes LLMs output data that is *almost* correct (e.g., strings for numbers). You can sanitize data before validation runs.
 
 ```typescript
 const result = await llm.promptZod(MySchema, {
-    // Transform JSON before Zod validation runs
+    // Transform JSON before validation runs
     beforeValidation: (data) => {
         if (data.price && typeof data.price === 'string') {
             return { ...data, price: parseFloat(data.price) };
@@ -187,7 +189,6 @@ const result = await llm.promptZod(MySchema, {
     },
     
     // Toggle usage of 'response_format: { type: "json_object" }'
-    // Sometimes strict JSON mode is too restrictive for creative tasks
     useResponseFormat: false 
 });
 ```