llm-fns 1.0.22 → 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.22",
+  "version": "1.0.23",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/readme.md

@@ -422,12 +422,12 @@ const poem = await llm.promptTextRetry({
 
 # Error Handling
 
-The library provides a structured error hierarchy that preserves the full context of failures across retry attempts.
+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 to signal that the current attempt failed but can be retried. The error message is sent back to the LLM.
+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';
@@ -449,23 +449,25 @@ import { SchemaValidationError } from './src';
 throw new SchemaValidationError("Age must be a positive number");
 ```
 
-### `LlmRetryAttemptError`
-Wraps each failed attempt with full context. These are chained together via `.cause`.
+### `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 LlmRetryAttemptError {
+interface LlmFatalError {
     message: string;
-    mode: 'main' | 'fallback';           // Which prompt was used
-    conversation: ChatCompletionMessageParam[];  // Full message history
-    attemptNumber: number;               // 0-indexed attempt number
-    error: Error;                        // The original error (LlmRetryError, etc.)
-    rawResponse?: string | null;         // The raw LLM response
-    cause?: LlmRetryAttemptError;        // Previous attempt's error (chain)
+    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 all retry attempts have been exhausted. Contains the full chain of attempt errors.
+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 {
@@ -474,15 +476,18 @@ interface LlmRetryExhaustedError {
 }
 ```
 
-### `LlmFatalError`
-Thrown for unrecoverable errors (e.g., 401 Unauthorized, 403 Forbidden). These bypass the retry loop entirely.
+### `LlmRetryAttemptError`
+Wraps a single failed attempt within the retry chain.
 
 ```typescript
-interface LlmFatalError {
+interface LlmRetryAttemptError {
     message: string;
-    cause?: any;                         // Original error
-    messages?: ChatCompletionMessageParam[];  // The messages that caused the error
-    rawResponse?: string | null;         // Raw response if available
+    mode: 'main' | 'fallback';
+    conversation: ChatCompletionMessageParam[];
+    attemptNumber: number;
+    error: Error;
+    rawResponse?: string | null;
+    cause?: LlmRetryAttemptError;        // Previous attempt's error
 }
 ```
 
@@ -497,14 +502,7 @@ LlmRetryExhaustedError
         ├── conversation: [...] (full message history)
         ├── rawResponse: '{"age": "wrong3"}'
         └── cause: LlmRetryAttemptError (Attempt 2)
-              ├── error: LlmRetryError
-              ├── conversation: [...]
-              ├── rawResponse: '{"age": "wrong2"}'
-              └── cause: LlmRetryAttemptError (Attempt 1)
-                    ├── error: LlmRetryError
-                    ├── conversation: [...]
-                    ├── rawResponse: '{"age": "wrong1"}'
-                    └── cause: undefined
+              ├── ...
 ```
 
 ## Handling Errors
@@ -512,7 +510,6 @@ LlmRetryExhaustedError
 ```typescript
 import { 
     LlmRetryExhaustedError, 
-    LlmRetryAttemptError,
     LlmFatalError 
 } from './src';
 
@@ -520,24 +517,18 @@ try {
     const result = await llm.promptZod(MySchema);
 } catch (error) {
     if (error instanceof LlmRetryExhaustedError) {
-        console.log('All retries failed');
-        
-        // Walk the error chain
-        let attempt = error.cause;
-        while (attempt) {
-            console.log(`Attempt ${attempt.attemptNumber + 1}:`);
-            console.log(`  Mode: ${attempt.mode}`);
-            console.log(`  Error: ${attempt.error.message}`);
-            console.log(`  Raw Response: ${attempt.rawResponse}`);
-            console.log(`  Conversation length: ${attempt.conversation.length}`);
-            
-            attempt = attempt.cause as LlmRetryAttemptError | undefined;
-        }
+        console.log('All retries failed.');
+        // Access the last response
+        console.log('Last LLM response:', error.cause.rawResponse);
     }
     
     if (error instanceof LlmFatalError) {
-        console.log('Fatal error (no retry):', error.message);
-        console.log('Original messages:', error.messages);
+        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);
     }
 }
 ```