FluxImageGenerationAgentSystem — FLUX.1 Text-to-Image Agent

FluxImageGenerationAgentSystem is a Python FLUX.1 text-to-image agent that orchestrates local diffusion generation for developers with NVIDIA GPUs.

It pairs Black Forest Labs' FLUX.1 diffusion models with an LLM agent that interprets requests, crafts prompts, and orchestrates the image pipeline through Hugging Face Diffusers and CUDA.

Note: an experiment from September 2024 exploring agentic image-generation systems (the text models have since been updated).

Quickstart

After installing Conda, create the environment and install the project dependencies:

conda create --name fluxgen python=3.12.4 -y
conda activate fluxgen
pip install --no-cache-dir -r requirements.txt

Configure OPENAI_API_KEY, install a compatible NVIDIA driver and CUDA toolkit, request access to the gated FLUX.1-dev model, then run python3 main.py.

For a single test generation, run the agent once and list the saved PNG result:

python3 main.py --count 1
find output -type f -name '*.png' -print

FLUX.1 Text-to-Image Agent Features

• Agent-driven prompting — an LLM agent turns natural-language requests into optimized FLUX prompts (capped for concise, focused generations).
• FLUX.1-dev image generation — local inference through Hugging Face Diffusers with GPU acceleration.
• Tool-using agent architecture — modular agent factory, tools, memory management, and inference pipeline.
• Automatic output management — generated images are saved and organized on disk.

Architecture

• config/ — configuration modules: image_config.py, image_models_config.py, and program_config.py.
• scripts/ — core system: AgentFactory.py / AgentSystemInitiator.py (agent setup), ModelFactory.py / InferencePipeline.py (FLUX model loading and generation), ToolFunctions.py / FileTools.py (agent tools), MemoryManager.py (conversation memory), and ImageSaver.py / OutputManager.py (saving output).
• main.py — application entry point.

Contents

• Quickstart
• FLUX.1 Text-to-Image Agent Features
• Architecture
• Prerequisites
• Environment Setup
• Installation
• Model Access Configuration
• Running the FLUX.1 Text-to-Image Agent

---

Prerequisites

Before getting started, ensure you have the following:

1. OpenAI API Key

• Get your API key from OpenAI Platform
• Set up the OPENAI_API_KEY environment variable

2. CUDA Toolkit (Required for GPU acceleration)

• Download and install CUDA 12.4.0 from NVIDIA Developer
• Ensure your system has compatible NVIDIA GPU drivers

3. Conda Package Manager

• Download and install Miniconda from Anaconda
• This will be used to manage Python environments and dependencies

---

Environment Setup

1. Open Terminal

• Windows: Open the Anaconda Prompt terminal
• macOS/Linux: Use your terminal with conda configured

2. Navigate to Project Directory

cd path/to/FluxImageGenerationAgentSystem

3. Create Conda Environment

conda create --name fluxgen python=3.12.4 -y

4. Activate Environment

conda activate fluxgen

---

Installation

Install all required dependencies using pip:

pip install --no-cache-dir -r requirements.txt

---

Model Access Configuration

Accessing the Gated Model: black-forest-labs/FLUX.1-dev on Hugging Face

To use this model, follow these steps:

1. Request Access

• Visit the FLUX.1-dev model page on Hugging Face
• Click the "Request Access" button (if available)
• Wait for approval from the model owner

2. Log In to Hugging Face

• If you don't have an account, sign up here
• Log in to your Hugging Face account

3. Get Your Access Token

• Go to your Hugging Face settings
• Click "New token" to generate a token (choose "Read" access)
• Copy the generated token

4. Authenticate in Your Environment

Using the CLI

huggingface-cli login

Paste your token when prompted.

---

Running the FLUX.1 Text-to-Image Agent

Once all setup steps are complete, start the application:

python3 main.py

Note: Make sure your system meets all hardware requirements for running FLUX models, including sufficient GPU memory and CUDA compatibility.

Configuration

Set OPENAI_API_KEY in the active Conda environment. The application starts with the image topic defined in config/image_config.py; --count N limits the number of agent iterations, while omitting it keeps the loop running until interrupted.

FLUX.1 Text-to-Image Agent FAQ

What does FluxImageGenerationAgentSystem generate?

It generates images with the FLUX.1-dev diffusion model after an OpenAI-powered agent turns the initial topic into a focused image prompt. The output manager writes generated files under the ignored output/ directory.

Do I need an NVIDIA GPU?

Yes for the documented local FLUX workflow. The project is configured for CUDA inference and does not promise a CPU-only fallback.

Why must I request access to FLUX.1-dev?

The Hugging Face model is gated. Your account must be approved and authenticated with huggingface-cli login before Diffusers can download the model weights.

Which command starts the agent system?

Run python3 main.py after the API key, CUDA environment, and model access are configured. Add --count 1 to run one iteration and exit.

Is this the official FLUX inference repository?

No. It is an independent experiment that combines an LLM prompt agent with a local FLUX.1 Diffusers pipeline; the official model repositories remain the authoritative source for model weights and licensing.

Contributing

Document hardware or dependency assumptions with reproducible commands, keep API keys out of commits, and include a short validation note with changes. Because generation requires a gated model and CUDA hardware, contributors should state when a check could only be performed by inspection.

License

See LICENSE.md for the repository's license and third-party model terms.