Interactive Testing

For rapid prototyping and visual experimentation, Udility Diffuser is best experienced through a Jupyter Notebook or Google Colab environment. This allows you to generate, render, and refine educational illustrations in an iterative workflow.

Using the Google Colab Notebook

The easiest way to start testing is by using the pre-configured Colab environment. This environment handles all system dependencies (like Cairo) automatically.

Open the Udility Diffuser Colab Notebook.
Add your OPENROUTER_API_KEY to the environment variables or the designated setup cell.
Run the cells sequentially to initialize the diffuser module.

Local Notebook Testing

If you are testing locally using Udility.ipynb or your own notebook, ensure you have the necessary system libraries installed for SVG rendering (e.g., libcairo2 on Linux or cairo via Homebrew on macOS).

1. Setup Environment

First, install the package and configure your API credentials within a notebook cell:

!pip install Udility

import os
# Replace with your actual key
os.environ['OPENROUTER_API_KEY'] = 'your_api_key_here'

2. Rapid Prototyping Workflow

The diffuser module provides a high-level function generate_image_from_text() that handles the entire pipeline: text analysis, SVG generation, conversion, and inline display using matplotlib.

from Udility import diffuser

# Test with a specific educational prompt
diffuser.generate_image_from_text("A diagram showing the parts of a plant cell.")

3. Granular Testing

For more control during testing, you can break down the process into individual steps. This is useful for debugging the logic of the generated SVG before it is rendered.

Example of step-by-step testing:

from Udility import diffuser

prompt = "Phases of the moon diagram"

# 1. Inspect the logic
instructions = diffuser.get_detailed_instructions(prompt)
print(f"Instructions: {instructions}")

# 2. Inspect the raw SVG
svg_code = diffuser.generate_svg_from_instructions(instructions)
print(f"Raw SVG: {svg_code}")

# 3. Render and Display
diffuser.svg_to_png(svg_code, 'test_output.png')
diffuser.display_image('test_output.png')

Tips for Effective Testing

Prompt Specificity: Since Udility Diffuser uses SVG scripting, prompts that describe spatial relationships (e.g., "A graph with X and Y axes") yield the most accurate results.
API Limits: Interactive testing relies on OpenRouter. Ensure your API key is active and has sufficient credits (though many Llama 3.5 models are available for free through specific providers).
Kernel Restarts: If you update the Udility package, remember to restart your notebook kernel to load the latest changes.