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

1. Clone the repository:

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

1. 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/

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

plugins:
  enabled:
    - image_gen/abacus_ai

1. Set the image generation provider:

hermes config set image_gen.provider abacus_ai

1. Configure your Abacus AI API key:

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

1. 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

Config File

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

Available Models

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:

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

Support

• Abacus AI RouteLLM Docs
• Hermes Agent Docs
• Abacus AI API Keys