How generate_image_with_retry_smartgen Works: Mechanism and Customization Guide

The generate_image_with_retry_smartgen function in the Heurist Agent Framework combines an asynchronous SmartGen client with a configurable retry loop to generate images via the Heurist Sequencer API, allowing customization of model selection, image parameters, and retry behavior.

The generate_image_with_retry_smartgen function serves as the primary entry point for AI image generation in the heurist-network/heurist-agent-framework repository. Located in core/imgen.py, this utility orchestrates asynchronous calls to the Heurist Sequencer API while providing robust error handling through automatic retries. Understanding its internal mechanism reveals how to customize everything from the underlying diffusion model to the resilience of your image generation pipeline.

Core Architecture of generate_image_with_retry_smartgen

The function implements a dual-layer architecture that separates the API communication logic from the resilience strategy. This design lives across two primary files in the codebase.

Component	Implementation	Source File
SmartGen Integration	An asynchronous context manager that constructs job payloads and communicates with the Heurist Sequencer API endpoint /submit_job. The actual generation is delegated to the external model specified by IMAGE_MODEL_ID.	core/heurist_image/SmartGen.py
Retry Logic	A for loop with configurable max_retries (default 3) and delay (default 2 seconds) that catches exceptions and API failures, logging warnings before subsequent attempts.	core/imgen.py (lines 68-82)

Step-by-Step Execution Flow

Tracing the execution path from prompt to image URL reveals the precise sequence of operations within generate_image_with_retry_smartgen.

1. Prompt Ingestion: The function receives a text prompt and optional keyword arguments (width, height, stylization_level, etc.).

2. Retry Loop Initialization: A for loop iterates up to max_retries times (default 3), entering a try block for each attempt.

3. SmartGen Context Entry: Inside generate_image_smartgen, the code executes async with SmartGen(api_key=HEURIST_API_KEY) as generator:, which invokes __aenter__ in SmartGen.py to initialize an aiohttp session.

4. Job Construction: SmartGen.generate_image generates a unique job ID formatted as sdk-image-<hex>, then constructs a payload containing the description (prompt) and any non-None parameters (width, height, stylization_level, detail_level, color_level, lighting_level, quality). These parameters are only added to the payload when not None.

5. API Submission: The method POSTs to {base_url}/submit_job. On HTTP 200, it extracts the image URL from the response body and returns {"url": url, "parameters": model_input}. Any failure raises APIError.

6. Retry Handling: If the call raises an exception or returns a falsy value, generate_image_with_retry_smartgen catches it, logs a warning, executes time.sleep(delay) (default 2 seconds), and continues the loop. After exhausting retries, it logs an error and returns None.

Customization Points

The framework exposes multiple configuration layers, allowing modification of model selection, generation parameters, and resilience behavior.

Customization Target	Configuration Method	Default Value
Image Model	Set IMAGE_MODEL_ID environment variable or modify the constant in core/imgen.py	Random selection from AVAILABLE_IMAGE_MODELS
Resolution & Guidance	Adjust IMAGE_SETTINGS dictionary in core/imgen.py (width, height, guidance_scale, etc.)	Model-specific defaults
SmartGen Parameters (stylization, detail, colour, lighting, quality)	Pass keyword arguments to generate_image_smartgen: stylization_level, detail_level, color_level, lighting_level, quality	None (omitted from payload)
Retry Behavior	Pass max_retries and delay to generate_image_with_retry_smartgen	max_retries=3, delay=2
API Endpoint	Set HEURIST_SEQUENCER_URL environment variable or pass to SmartGen constructor	Default Heurist Sequencer URL
Logging	Configure Python's standard logging module to adjust verbosity of INFO, WARNING, and ERROR messages	Root logger level

Practical Implementation Examples

The following examples demonstrate concrete usage patterns from basic calls to advanced parameter tuning.

Basic Usage with Default Settings

from core.imgen import generate_image_with_retry_smartgen

async def create_image():
    prompt = "A futuristic city skyline at sunset, cinematic lighting"
    image_url = await generate_image_with_retry_smartgen(prompt)
    return image_url

This implementation uses the default model selection, standard resolution, and the built-in retry mechanism with 3 attempts.

Custom Model and Extended Retry Policy

import os
from core.imgen import generate_image_with_retry_smartgen

async def generate_with_custom_settings():
    # Configure specific model via environment

    os.environ["IMAGE_MODEL_ID"] = "AnimagineXL"
    
    prompt = "A hyper-realistic portrait of a cyber-punk fox, neon glow"
    
    # Override retry behavior for unreliable network conditions

    image_url = await generate_image_with_retry_smartgen(
        prompt,
        max_retries=5,
        delay=4  # Wait 4 seconds between attempts

    )
    return image_url

Direct SmartGen Access for Fine-Grained Control

from core.imgen import generate_image_smartgen

async def advanced_generation():
    prompt = "Epic battle scene on a volcanic planet, dramatic shadows"
    
    # Bypass retry wrapper for direct parameter control

    result = await generate_image_smartgen(
        prompt,
        image_model="BrainDance",
        width=2048,
        height=2048,
        stylization_level=8,
        detail_level=9,
        color_level=7,
        lighting_level=6,
        quality="ultra"
    )
    
    return result["url"]

This approach exposes all SmartGen parameters including stylization levels, detail density, and quality presets while bypassing the automatic retry logic.

Key Source Files

Understanding the codebase structure helps navigate the implementation details.

File	Purpose	Location
core/imgen.py	Contains generate_image_with_retry_smartgen and generate_image_smartgen wrappers, retry logic, and model selection constants.	core/imgen.py
core/heurist_image/SmartGen.py	Implements the SmartGen async context manager, job payload construction, and direct API communication with the Heurist Sequencer.	core/heurist_image/SmartGen.py
core/heurist_image/ImageGen.py	Legacy synchronous image generation via the Sequencer POST /submit_job endpoint.	core/heurist_image/ImageGen.py
core/components/media_handler.py	High-level component orchestrating when to invoke image generation based on tweet content and context.	core/components/media_handler.py

Summary

• generate_image_with_retry_smartgen combines asynchronous SmartGen API calls with configurable retry logic to ensure reliable image generation in core/imgen.py.
• The function delegates actual generation to the SmartGen class in core/heurist_image/SmartGen.py, which constructs job payloads and communicates with the Heurist Sequencer API at /submit_job.
• Customization options include model selection via IMAGE_MODEL_ID, generation parameters (stylization, detail, quality), and retry behavior (max_retries, delay).
• For advanced use cases, calling generate_image_smartgen directly bypasses the retry wrapper and exposes all SmartGen parameters including resolution and aesthetic controls.

Frequently Asked Questions

What is the default retry behavior in generate_image_with_retry_smartgen?

The function implements a linear retry mechanism with a default of three attempts (max_retries=3) and a two-second delay (delay=2) between each attempt. If the Heurist Sequencer API returns an error or the SmartGen call raises an exception, the wrapper logs a warning, sleeps for the specified duration, and retries. After exhausting all retries, it logs an error and returns None.

How do I change the image model used by generate_image_with_retry_smartgen?

Model selection is controlled by the IMAGE_MODEL_ID constant in core/imgen.py, which reads from the environment variable of the same name. Set os.environ["IMAGE_MODEL_ID"] = "AnimagineXL" before importing or calling the function, or modify the fallback logic in imgen.py which defaults to a random selection from AVAILABLE_IMAGE_MODELS.

Can I use generate_image_with_retry_smartgen without the retry wrapper?

Yes, by calling generate_image_smartgen directly from core/imgen.py, you bypass the retry loop entirely. This direct call accepts the same prompt and SmartGen parameters (stylization_level, detail_level, quality, etc.) but returns immediately upon API success or failure without automatic retry logic, giving you full control over error handling.

What is the difference between SmartGen and the legacy ImageGen implementation?

SmartGen (in core/heurist_image/SmartGen.py) is the modern asynchronous implementation using aiohttp and context managers for efficient session handling, supporting advanced parameters like stylization and quality levels. The legacy ImageGen (in core/heurist_image/ImageGen.py) provides synchronous generation via direct HTTP requests without the async context manager pattern or the granular aesthetic controls available in SmartGen. The retry wrapper specifically targets the SmartGen implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}