PromptEnhancer

Accepts a raw user prompt and processes it through a full-precision transformer-based LLM (7B or 32B parameters) using chain-of-thought reasoning to decompose and restructure the prompt into a semantically richer, more detailed version suitable for image generation. The system preserves all key semantic elements (subject, action, style, layout, attributes) while expanding ambiguous descriptions into explicit, structured language that downstream image generators can better interpret. Uses multi-level fallback parsing to extract the enhanced prompt even when LLM output formatting is inconsistent.

Implements a memory-efficient variant of text-to-image prompt enhancement using GGUF quantized models (4-bit, 8-bit) that run on consumer-grade hardware with 8-16GB VRAM instead of requiring 40GB+ for full-precision models. Uses llama.cpp backend for CPU-optimized inference with optional GPU acceleration, trading ~10-15% quality degradation for 4-6x memory reduction and 2-3x faster inference. Maintains the same chain-of-thought rewriting logic as the full-precision variant through quantization-aware model conversion.

Accepts both an image and a text editing instruction, processes them through a vision-language model (VLM) that analyzes the visual content and instruction semantics together, then generates a refined editing instruction that is more explicit about spatial relationships, visual context, and desired modifications. The VLM grounds the editing instruction in the actual image content, reducing ambiguity and enabling more precise image-to-image editing. Uses multi-modal chain-of-thought reasoning to decompose visual analysis and instruction refinement into explicit steps.

Implements a cascading fallback mechanism for extracting enhanced prompts from LLM/VLM outputs that may have inconsistent formatting or parsing failures. Uses multiple extraction strategies in sequence: (1) structured JSON parsing if LLM outputs valid JSON, (2) regex-based pattern matching for common delimiters (e.g., 'Enhanced Prompt:'), (3) heuristic-based sentence extraction if patterns fail, (4) fallback to original prompt if all extraction attempts fail. Ensures the system always produces usable output even when LLM formatting is unpredictable, critical for production reliability.

Allows users to inject custom system prompts that control how the LLM/VLM approaches prompt enhancement, enabling fine-grained control over enhancement style, detail level, and semantic focus. System prompts can specify enhancement priorities (e.g., 'prioritize visual style over composition'), constraint rules (e.g., 'keep enhanced prompt under 100 tokens'), or domain-specific guidance (e.g., 'optimize for photorealistic rendering'). The custom system prompt is prepended to the LLM context before processing, directly influencing the chain-of-thought reasoning and output structure without requiring model retraining.

Provides infrastructure for processing multiple prompts or image+instruction pairs in batches with optimizations for production deployments: (1) batch inference to amortize model loading overhead, (2) configurable batch sizes to balance memory usage and throughput, (3) optional GPU memory management (gradient checkpointing, mixed precision) to fit larger batches on constrained hardware, (4) progress tracking and error logging for monitoring batch jobs. Enables efficient processing of hundreds or thousands of prompts without reloading the model between each inference.

Provides guidance and automated selection of appropriate model variants (7B vs 32B full-precision, GGUF quantized, VLM) based on available hardware (VRAM, CPU cores, GPU type) and performance requirements (latency, throughput, quality). Includes documentation of hardware requirements for each variant and scaling recommendations for production deployments. Enables users to make informed decisions about model selection without trial-and-error, and provides pathways for scaling from development to production.

Implements semantic analysis and restructuring logic that decomposes user prompts into constituent semantic elements (subject, action, style, composition, attributes, lighting, etc.), analyzes each element for clarity and completeness, then restructures them into a more explicit and detailed prompt that preserves the original intent while improving clarity. Uses LLM chain-of-thought reasoning to make decomposition and restructuring steps explicit and interpretable. The restructured prompt maintains semantic equivalence to the original while being more suitable for image generation models.

Provides a unified Python API that abstracts over four distinct model variants (HunyuanPromptEnhancer for full-precision T2I, PromptEnhancerGGUF for quantized T2I, PromptEnhancerImg2Img for vision-language I2I, PromptEnhancerV2 for alternative VLM), allowing users to switch between variants without changing application code. Each variant implements the same core interface (initialization, prediction) but with different backend implementations and performance characteristics. Enables flexible deployment where the same application code can run on different hardware or use different models.