Abacus AI Image Generation Plugin for Hermes Agent

Version 2.1.1 —

⚡ Generate high-quality images directly in Hermes Agent using Abacus AI's RouteLLM API. Supports FLUX 2 Pro, Nano Banana Pro (up to 4K), DALL-E, MidJourney, and 20+ models.

Features

🎨 20+ Image Models — FLUX 2 Pro, FLUX Pro Ultra, Nano Banana Pro (4K), MidJourney, DALL-E, and more
⚡ Native image_gen Provider — Works as a first-class Hermes image generation backend
🖼️ Up to 4K Resolution — Nano Banana Pro supports 1080p, 2K, 4K
🔄 Text-to-Image & Image-to-Image — Generate from prompts or edit existing images
⏳ Background Generation — Run image generation asynchronously and poll for results
🛡️ Concurrency-Safe — Max 4 parallel API calls, exponential-backoff retry on 429/5xx
♻️ Self-Cleaning Jobs — Finished jobs auto-removed after 24h, stale jobs marked failed
💰 Cost-Effective — Uses your existing Abacus AI ChatLLM subscription credits
🎯 Multi-Platform — Works in Telegram, Discord, CLI, and all Hermes surfaces
📦 Modular Code — Clean separation into provider, config, models, utils, and background modules
✅ Tested — 74 unit tests covering provider, credentials, models, image validation, retries, and background jobs

Prerequisites

Hermes Agent installed and running
An Abacus AI account with ChatLLM subscription
Your RouteLLM API key from abacus.ai/app/route-llm-apis

Installation

Option 1: Install via Hermes Agent (recommended)

Copy and paste this prompt to your Hermes Agent (Telegram, Discord, or CLI). It will clone the repo, copy the files, configure everything, and restart the gateway automatically:

Install the Abacus AI image generation plugin v2.1.0 from the public GitHub repo https://github.com/ZoniBoy00/hermes-agent-abacus-ai. Clone the repo to /tmp, copy the abacus_ai/ directory to ~/.hermes/plugins/image_gen/abacus_ai/, enable image_gen/abacus_ai in plugins.enabled in config.yaml, set image_gen.provider to abacus_ai, configure custom_providers with name abacus-ai using my API key, then restart the gateway.

Make sure you have your Abacus AI RouteLLM API key ready — Hermes will ask for it during installation.

Option 2: Manual Install

Clone the repository:

git clone https://github.com/ZoniBoy00/hermes-agent-abacus-ai.git /tmp/hermes-agent-abacus-ai

Copy the abacus_ai/ directory to your Hermes image_gen plugins folder:

cp -r /tmp/hermes-agent-abacus-ai/abacus_ai ~/.hermes/plugins/image_gen/abacus_ai/

Enable the plugin in ~/.hermes/config.yaml:

plugins:
  enabled:
    - image_gen/abacus_ai

Set the image generation provider:

hermes config set image_gen.provider abacus_ai

Configure your Abacus AI API key:

custom_providers:
  - name: abacus-ai
    key_env: ABACUS_AI_API_KEY
    base_url: "https://routellm.abacus.ai/v1"

Restart the Hermes gateway:

systemctl --user restart hermes-gateway

Option 3: Install via pip

pip install git+https://github.com/ZoniBoy00/hermes-agent-abacus-ai.git

Then enable the plugin in ~/.hermes/config.yaml and restart.

Cleanup (optional)

rm -rf /tmp/hermes-agent-abacus-ai

Plugin Structure

abacus_ai/
├── __init__.py       # Plugin registration (register provider + background tools)
├── provider.py       # ImageGenProvider implementation (generate, extract)
├── config.py         # Credential and config resolution
├── models.py         # Model catalog and aspect ratio helpers
├── utils.py          # Image URL conversion and format detection
├── background.py     # Background image generation (async jobs)
└── plugin.yaml       # Plugin manifest (kind: backend)
tests/
├── __init__.py
├── conftest.py       # Test fixtures and mocks
├── test_utils.py     # Utility function tests
├── test_provider.py  # Model, credential, and aspect ratio tests
└── test_background.py # Background job tests

Background Generation

In addition to synchronous image generation, the plugin provides two background tools:

`image_generate_background`

Start an image generation job that runs in the background. Returns immediately with a job_id.

Supports single prompts and batch mode (multiple jobs via jobs array)
Batch items run in parallel (capped at 4 concurrent API calls overall, max 16 jobs per batch)
Each batch item supports prompt, aspect_ratio, model, quality, resolution, num_images, and rewrite_prompt
Job state is persisted to $HERMES_HOME/cache/abacus_ai_jobs/<job_id>/
Finished jobs are auto-removed after 24 hours; jobs stuck in running for over 30 minutes (e.g. after a gateway restart) are marked failed
API calls retry transient failures (429, 5xx) with exponential backoff

`image_generate_background_status`

Poll for the result of a background job:

Returns "status": "running" while the job is in progress
Returns "status": "completed" with the result when done
Returns "status": "failed" on error

Configuration

Environment Variables

Variable	Description	Default
`ABACUS_AI_API_KEY`	Your Abacus AI RouteLLM API key	—
`ABACUS_AI_BASE_URL`	API base URL	`https://routellm.abacus.ai/v1`
`ABACUS_AI_IMAGE_MODEL`	Default image model override	`flux2_pro`
`ABACUS_AI_TIMEOUT_SECONDS`	Per-request API timeout	`300`
`ABACUS_AI_MAX_RETRIES`	Maximum attempts for transient failures (1-6)	`3`

Config File

image_gen:
  provider: abacus_ai
  abacus_ai:
    model: flux2_pro  # default model

Available Models

Model ID	Display Name	Best For
`nano_banana_pro`	Nano Banana Pro	Highest resolution (up to 4K), Google DeepMind
`flux_pro_ultra`	FLUX Pro Ultra	Highest quality, photorealistic
`flux2_pro`	FLUX 2 Pro	High quality, photorealistic (default)
`flux2`	FLUX 2	Fast, good quality
`midjourney`	MidJourney	Artistic, stylistic
`dalle`	DALL-E	Creative, strong prompt adherence

Usage

Once installed and configured, Hermes will use the Abacus AI provider automatically when generating images. Simply ask Hermes to create an image — the image_generate tool will use this provider by default.

Telegram / Discord

Generate an image of a cyberpunk city at night, neon lights, futuristic
Make a photorealistic render of a wooden cabin in the mountains
Create a digital art portrait of a wolf with glowing eyes
Generate a 4K image of northern lights — use Nano Banana Pro

CLI

hermes chat -q "Generate a beautiful landscape painting of northern lights over a lake"

Supported Parameters

The provider supports these optional image_config parameters:

Parameter	Type	Description	Default
`num_images`	integer	Number of images to generate (1-4)	`1`
`quality`	string	Quality tier (`low`, `medium`, `high`)	model-dependent
`resolution`	string	Output resolution: `1080p`, `2K`, or `4K`. Only works with `nano_banana_pro` model. Leave unset for model's default resolution.	not set (model default)
`rewrite_prompt`	boolean	Auto-improve prompts for better results	`true`

Changelog

v2.1.1

Isolated tests from the host Hermes config so tests cannot use live Abacus credentials or make real API calls
Added environment-backed credentials via key_env and ${ENV_VAR} resolution
Restricted local reference files to validated image formats, safe names, and a 20 MB limit
Limited background batches to 16 jobs and prompts to 10,000 characters
Made the provider default model follow the configured model resolver
Added configurable timeout/retry limits, Retry-After support, and jittered backoff
Added development extras and Ruff CI checks

v2.1.0

Fixed crash when num_images is a non-numeric value (guarded conversion)
Added exponential-backoff retry for transient API failures (429, 5xx, network errors)
Background jobs: max 4 concurrent API calls, parallel batch execution, atomic status/result writes
Auto-cleanup: finished jobs removed after 24h, stale running jobs marked failed after 30min
job_id validation in status handler (blocks path traversal)
quality validated against low/medium/high; invalid values ignored
Correct file extension passed for content-fallback and inline_data image responses
Config load errors now logged instead of silently swallowed
Real generate() / _extract_image() test coverage (no more permanently skipped tests)

v2.0.0

Modular code structure (provider.py, config.py, models.py, utils.py, background.py)
Background image generation (image_generate_background + _status)
Nano Banana Pro support with up to 4K resolution
Unit test suite (37+ tests)
pip install support via pyproject.toml
Improved error handling and response parsing

v1.1.0

Rich requires_env format in plugin.yaml
Model-specific aspect ratio resolution
Image format detection (PNG, JPEG, WebP)

v1.0.0

Initial release with Abacus AI image generation
FLUX 2 Pro, DALL-E, MidJourney support

Credits & License

Built for Hermes Agent by ZoniBoy00.

Author: ZoniBoy00
License: MIT
Repository: ZoniBoy00/hermes-agent-abacus-ai

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
abacus_ai		abacus_ai
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Navigation Menu

Repository files navigation

Abacus AI Image Generation Plugin for Hermes Agent

Features

Prerequisites

Installation

Option 1: Install via Hermes Agent (recommended)

Option 2: Manual Install

Option 3: Install via pip

Cleanup (optional)

Plugin Structure

Background Generation

`image_generate_background`

`image_generate_background_status`

Configuration

Environment Variables

Config File

Available Models

Usage

Telegram / Discord

CLI

Supported Parameters

Changelog

v2.1.1

v2.1.0

v2.0.0

v1.1.0

v1.0.0

Credits & License

Support

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Abacus AI Image Generation Plugin for Hermes Agent

Features

Prerequisites

Installation

Option 1: Install via Hermes Agent (recommended)

Option 2: Manual Install

Option 3: Install via pip

Cleanup (optional)

Plugin Structure

Background Generation

image_generate_background

image_generate_background_status

Configuration

Environment Variables

Config File

Available Models

Usage

Telegram / Discord

CLI

Supported Parameters

Changelog

v2.1.1

v2.1.0

v2.0.0

v1.1.0

v1.0.0

Credits & License

Support

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`image_generate_background`

`image_generate_background_status`