# How generate_image_with_retry_smartgen Works: Mechanism and Customization Guide

> Explore the generate_image_with_retry_smartgen mechanism in Heurist Agent Framework. Learn to customize model selection, image parameters, and retry logic for effective image generation.

- Repository: [Heurist/heurist-agent-framework](https://github.com/heurist-network/heurist-agent-framework)
- Tags: deep-dive
- Published: 2026-03-03

---

**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](https://github.com/heurist-network/heurist-agent-framework) repository. Located in [`core/imgen.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/core/imgen.py) | Random selection from `AVAILABLE_IMAGE_MODELS` |
| **Resolution & Guidance** | Adjust `IMAGE_SETTINGS` dictionary in [`core/imgen.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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

```python
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

```python
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

```python
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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/core/imgen.py) | Contains `generate_image_with_retry_smartgen` and `generate_image_smartgen` wrappers, retry logic, and model selection constants. | [core/imgen.py](https://github.com/heurist-network/heurist-agent-framework/blob/main/core/imgen.py) |
| [`core/heurist_image/SmartGen.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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](https://github.com/heurist-network/heurist-agent-framework/blob/main/core/heurist_image/SmartGen.py) |
| [`core/heurist_image/ImageGen.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/core/heurist_image/ImageGen.py) | Legacy synchronous image generation via the Sequencer `POST /submit_job` endpoint. | [core/heurist_image/ImageGen.py](https://github.com/heurist-network/heurist-agent-framework/blob/main/core/heurist_image/ImageGen.py) |
| [`core/components/media_handler.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/core/imgen.py).
- The function delegates actual generation to the `SmartGen` class in [`core/heurist_image/SmartGen.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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.