Handling Optional Data in AI-Generated Responses

Ever been tripped up by AI that sometimes forgets to include a key piece of information in its response? It's a common problem when integrating AI services into your applications.

Recently, while working on the devlog-ist/landing project, which helps developers easily create blog posts, we encountered an issue with the AI-powered post generation service. The AI structured response was occasionally omitting the mermaid_diagram key, leading to errors in the application.

The Problem

The PostGenerationServiceV2 expected a mermaid_diagram key in the AI's response. However, the AI, in its infinite wisdom, didn't always provide it. This resulted in an "undefined array key" error, disrupting the post generation process.

The Solution

Instead of directly accessing the array key, we implemented a more robust approach to handle the optional data:

1. Updated PHPDoc: Marked the mermaid_diagram key in the PHPDoc array shape as optional. This clearly documents that the key might not always be present.
2. Safe Local Variables: Ensured the use of already-safe local variables in logging instead of directly accessing the array key. This prevents the error from occurring even if the key is missing.

Here's a simplified example of how the fix looks like:

/**
 * @param array{title: string, content: string, tags: array<string>, mermaid_diagram?: string} $aiResponse
 */
function processAIResponse(array $aiResponse): void {
    $diagram = $aiResponse['mermaid_diagram'] ?? '';

    if (empty($diagram)) {
        // Log the missing diagram safely
        error_log('Mermaid diagram missing from AI response.');
    }
    // ... rest of the logic
}

This code snippet demonstrates how to safely access the mermaid_diagram key using the null coalescing operator (??). If the key is missing, it defaults to an empty string, preventing the "undefined array key" error.

The Takeaway

When working with AI-generated responses, always anticipate that certain data might be optional. Use defensive programming techniques like PHPDoc annotations and null coalescing to gracefully handle missing data and prevent unexpected errors in your application. This approach not only makes your code more resilient but also improves the overall user experience.