llm-fns 1.0.21 → 1.0.23

package/dist/createLlmRetryClient.js

@@ -79,11 +79,15 @@ function createLlmRetryClient(params) {
             const currentPrompt = useFallback ? fallbackPrompt : prompt;
             const mode = useFallback ? 'fallback' : 'main';
             const currentMessages = constructLlmMessages(initialMessages, attempt, lastError);
+            // Capture raw response for error context
+            let rawResponseForError = null;
             try {
                 const completion = await currentPrompt({
                     messages: currentMessages,
                     ...restOptions,
                 });
+                // Extract raw content immediately
+                rawResponseForError = completion.choices[0]?.message?.content || null;
                 const assistantMessage = completion.choices[0]?.message;
                 let dataToProcess = completion;
                 if (responseType === 'text') {
@@ -132,19 +136,26 @@ function createLlmRetryClient(params) {
                 return dataToProcess;
             }
             catch (error) {
-                if (error instanceof createLlmClient_js_1.LlmFatalError) {
-                    const fatalAttemptError = new LlmRetryAttemptError(`Fatal error on attempt ${attempt + 1}: ${error.message}`, mode, currentMessages, attempt, error, error.rawResponse, { cause: lastError });
-                    throw new LlmRetryExhaustedError(`Operation failed with fatal error on attempt ${attempt + 1}.`, { cause: fatalAttemptError });
-                }
                 if (error instanceof LlmRetryError) {
                     const conversationForError = [...currentMessages];
                     if (error.rawResponse) {
                         conversationForError.push({ role: 'assistant', content: error.rawResponse });
                     }
-                    lastError = new LlmRetryAttemptError(`Attempt ${attempt + 1} failed: ${error.message}`, mode, conversationForError, attempt, error, error.rawResponse, { cause: lastError });
+                    else if (rawResponseForError) {
+                        conversationForError.push({ role: 'assistant', content: rawResponseForError });
+                    }
+                    lastError = new LlmRetryAttemptError(`Attempt ${attempt + 1} failed: ${error.message}`, mode, conversationForError, attempt, error, error.rawResponse || rawResponseForError, { cause: lastError });
                 }
                 else {
-                    throw error;
+                    // For any other error (ZodError, SchemaValidationError that wasn't fixed, network error, etc.)
+                    // We wrap it in LlmFatalError to ensure context is preserved.
+                    const fatalMessage = error.message || 'An unexpected error occurred during LLM execution';
+                    // If it's already a fatal error, use its cause, otherwise use the error itself
+                    const cause = error instanceof createLlmClient_js_1.LlmFatalError ? error.cause : error;
+                    // Use the raw response we captured, or if the error has one (e.g. LlmFatalError from lower client)
+                    const responseContent = rawResponseForError || error.rawResponse || null;
+                    throw new createLlmClient_js_1.LlmFatalError(fatalMessage, cause, currentMessages, // This contains the full history of retries
+                    responseContent);
                 }
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-fns",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/readme.md

@@ -328,6 +328,68 @@ const result = await llm.promptZod(MySchema, {
 });
 ```
 
+### Level 4: Retryable Errors in Zod Transforms
+
+You can throw `SchemaValidationError` inside Zod `.transform()` or `.refine()` to trigger the retry loop. This is useful for complex validation logic that can't be expressed in the schema itself.
+
+```typescript
+import { z } from 'zod';
+import { SchemaValidationError } from './src';
+
+const ProductSchema = z.object({
+    name: z.string(),
+    price: z.number(),
+    currency: z.string()
+}).transform((data) => {
+    // Custom validation that triggers retry
+    if (data.price < 0) {
+        throw new SchemaValidationError(
+            `Price cannot be negative. Got: ${data.price}. Please provide a valid positive price.`
+        );
+    }
+    
+    // Normalize currency
+    const validCurrencies = ['USD', 'EUR', 'GBP'];
+    if (!validCurrencies.includes(data.currency.toUpperCase())) {
+        throw new SchemaValidationError(
+            `Invalid currency "${data.currency}". Must be one of: ${validCurrencies.join(', ')}`
+        );
+    }
+    
+    return {
+        ...data,
+        currency: data.currency.toUpperCase()
+    };
+});
+
+// If the LLM returns { price: -10, ... }, the error message is sent back
+// and the LLM gets another chance to fix it
+const product = await llm.promptZod("Extract product info from: ...", ProductSchema);
+```
+
+**Important:** Only `SchemaValidationError` triggers the retry loop. Other errors (like `TypeError`, database errors, etc.) will bubble up immediately without retry. This prevents infinite loops when there's a bug in your transform logic.
+
+```typescript
+const SafeSchema = z.object({
+    userId: z.string()
+}).transform(async (data) => {
+    // This error WILL trigger retry (user can fix the input)
+    if (!data.userId.match(/^[a-z0-9]+$/)) {
+        throw new SchemaValidationError(
+            `Invalid userId format "${data.userId}". Must be lowercase alphanumeric.`
+        );
+    }
+    
+    // This error will NOT trigger retry (it's a system error)
+    const user = await db.findUser(data.userId);
+    if (!user) {
+        throw new Error(`User not found: ${data.userId}`); // Bubbles up immediately
+    }
+    
+    return { ...data, user };
+});
+```
+
 ---
 
 # Use Case 4: Agentic Retry Loops (`llm.promptTextRetry`)
@@ -358,6 +420,143 @@ const poem = await llm.promptTextRetry({
 
 ---
 
+# Error Handling
+
+The library provides a structured error hierarchy that preserves the full context of failures, whether they happen during a retry loop or cause an immediate crash.
+
+## Error Types
+
+### `LlmRetryError`
+Thrown by your validation logic to signal that the current attempt failed but can be retried. The error message is sent back to the LLM as feedback.
+
+```typescript
+import { LlmRetryError } from './src';
+
+throw new LlmRetryError(
+    "The response must include a title field.",  // Message sent to LLM
+    'CUSTOM_ERROR',                               // Type: 'JSON_PARSE_ERROR' | 'CUSTOM_ERROR'
+    { field: 'title' },                           // Optional details
+    '{"name": "test"}'                            // Optional raw response
+);
+```
+
+### `SchemaValidationError`
+A specialized error for schema validation failures. Use this in Zod transforms to trigger retries.
+
+```typescript
+import { SchemaValidationError } from './src';
+
+throw new SchemaValidationError("Age must be a positive number");
+```
+
+### `LlmFatalError`
+Thrown for **unrecoverable errors**. This includes:
+1. API Errors (401 Unauthorized, 403 Forbidden, Context Length Exceeded).
+2. Runtime errors in your validation logic (e.g., `TypeError`, database connection failed).
+3. Validation errors when `maxRetries` is 0 or `disableJsonFixer` is true.
+
+Crucially, `LlmFatalError` wraps the original error and attaches the **full conversation context** and **raw response** (if available), so you can debug what the LLM generated that caused the crash.
+
+```typescript
+interface LlmFatalError {
+    message: string;
+    cause?: any;                              // The original error (e.g. ZodError, TypeError)
+    messages?: ChatCompletionMessageParam[];  // The full conversation history including retries
+    rawResponse?: string | null;              // The raw text generated by the LLM before the crash
+}
+```
+
+### `LlmRetryExhaustedError`
+Thrown when the maximum number of retries is reached. It contains the full chain of attempt errors, allowing you to trace the evolution of the conversation.
+
+```typescript
+interface LlmRetryExhaustedError {
+    message: string;
+    cause: LlmRetryAttemptError;  // The last attempt error (with chain to previous)
+}
+```
+
+### `LlmRetryAttemptError`
+Wraps a single failed attempt within the retry chain.
+
+```typescript
+interface LlmRetryAttemptError {
+    message: string;
+    mode: 'main' | 'fallback';
+    conversation: ChatCompletionMessageParam[];
+    attemptNumber: number;
+    error: Error;
+    rawResponse?: string | null;
+    cause?: LlmRetryAttemptError;        // Previous attempt's error
+}
+```
+
+## Error Chain Structure
+
+When retries are exhausted, the error chain looks like this:
+
+```
+LlmRetryExhaustedError
+  └── cause: LlmRetryAttemptError (Attempt 3)
+        ├── error: LlmRetryError (the validation error)
+        ├── conversation: [...] (full message history)
+        ├── rawResponse: '{"age": "wrong3"}'
+        └── cause: LlmRetryAttemptError (Attempt 2)
+              ├── ...
+```
+
+## Handling Errors
+
+```typescript
+import { 
+    LlmRetryExhaustedError, 
+    LlmFatalError 
+} from './src';
+
+try {
+    const result = await llm.promptZod(MySchema);
+} catch (error) {
+    if (error instanceof LlmRetryExhaustedError) {
+        console.log('All retries failed.');
+        // Access the last response
+        console.log('Last LLM response:', error.cause.rawResponse);
+    }
+    
+    if (error instanceof LlmFatalError) {
+        console.log('Crash or Fatal API Error:', error.message);
+        console.log('Original Cause:', error.cause);
+        
+        // You always have access to what the LLM said, even if your code crashed!
+        console.log('LLM Response that caused crash:', error.rawResponse);
+        console.log('Conversation History:', error.messages);
+    }
+}
+```
+
+## Extracting the Last Response
+
+A common pattern is to extract the last LLM response from a failed operation:
+
+```typescript
+function getLastResponse(error: LlmRetryExhaustedError): string | null {
+    return error.cause?.rawResponse ?? null;
+}
+
+function getAllResponses(error: LlmRetryExhaustedError): string[] {
+    const responses: string[] = [];
+    let attempt = error.cause;
+    while (attempt) {
+        if (attempt.rawResponse) {
+            responses.unshift(attempt.rawResponse); // Add to front (chronological order)
+        }
+        attempt = attempt.cause as LlmRetryAttemptError | undefined;
+    }
+    return responses;
+}
+```
+
+---
+
 # Use Case 5: Architecture & Composition
 
 How to build the client manually to enable **Fallback Chains** and **Smart Routing**.