Runtime Error Handling

Udility Diffuser relies on external API connectivity and local rendering engines. When using Udility.diffuser, your application should be prepared to handle exceptions related to environment configuration, network connectivity, and SVG processing.

The library primarily utilizes two types of exceptions:

EnvironmentError: Raised during initialization if required configuration is missing.
RuntimeError: Raised during the execution of image generation or rendering tasks.

Missing API Configuration

The most common error occurs when the OPENROUTER_API_KEY is not found in the system environment. The library checks for this key upon import.

Error: EnvironmentError: The OpenRouter API key is not set. Please set it as an environment variable.

Solution: Ensure the environment variable is set before calling any library functions:

import os
os.environ['OPENROUTER_API_KEY'] = 'your_api_key_here'

# Now import the diffuser
from Udility import diffuser

API and Connectivity Issues

Since Udility Diffuser communicates with Meta Llama-3.5 via OpenRouter, calls to generate_image_from_text may fail due to network instability, API rate limits, or service outages.

Failure to get instructions: Occurs if the first LLM pass (logical mapping) fails.
Failure to generate SVG code: Occurs if the second LLM pass (code generation) fails.

Handling Example:

from Udility import diffuser

try:
    diffuser.generate_image_from_text("A diagram of a plant cell")
except RuntimeError as e:
    print(f"API Communication Error: {e}")

SVG Malformation and Rendering

The model generates SVG code dynamically. In rare cases, the generated XML may be malformed or contain tags that cairosvg cannot process, leading to a rendering error.

Error: RuntimeError: Failed to convert SVG to PNG: [details]

This error typically triggers if:

The LLM output contains non-SVG text (though the prompt is designed to prevent this).
The SVG structure is incomplete.
The local system is missing required binary dependencies for cairocffi or cairosvg.

Display Failures

If you are running Udility in a non-GUI environment (like a headless server) without a backend for matplotlib, the display_image function may raise an error.

Error: RuntimeError: Failed to display image: [details]

Recommendation: If you only need to save the file and not display it, you may want to handle individual steps or ensure your environment supports matplotlib rendering.

Implementation Pattern

For production-grade implementations, it is recommended to wrap the generation call in a comprehensive try-except block to manage the end-to-end lifecycle:

from Udility import diffuser
import sys

def create_illustration(prompt, filename="output.png"):
    try:
        # High-level entry point that orchestrates 
        # instruction generation, SVG creation, and rendering
        diffuser.generate_image_from_text(prompt, output_filename=filename)
        print(f"Successfully generated {filename}")
        
    except EnvironmentError as env_err:
        print(f"Configuration Error: {env_err}")
        
    except RuntimeError as run_err:
        # This covers API failures, malformed SVG, and rendering issues
        print(f"Generation failed: {run_err}")
        
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

# Usage
create_illustration("The lifecycle of a butterfly")

Summary of Exceptions