@danhachuel/thunderbolt 0.3.25 → 0.3.26

package/app/main.py

@@ -2152,7 +2152,16 @@ def render_new_video(page_title: str = "Criação de Vídeos", prefix: str = "ne
                             thumbnail_path = str(variant.get("image_path") or payload.get("thumbnail_path") or "").strip()
                             if st.button("Gerar imagem com Nano Banana", key=f"{prefix}_general_generate_thumbnail_{channel['id']}", use_container_width=True):
                                 try:
-                                    thumbnail_path = str(generate_thumbnail_image(read_json("settings.json", {}), variant.get("image_prompt", ""), topic=str(payload.get("topic") or ""), variant_index=variant_index))
+                                    thumbnail_path = str(
+                                        generate_thumbnail_image(
+                                            read_json("settings.json", {}),
+                                            variant.get("image_prompt", ""),
+                                            topic=str(payload.get("topic") or ""),
+                                            variant_index=variant_index,
+                                            lettering_text=str(variant.get("overlay_text") or payload.get("thumbnail_text") or ""),
+                                            lettering_prompt=str(variant.get("lettering_prompt") or ""),
+                                        )
+                                    )
                                     variant["image_path"] = thumbnail_path
                                     payload["thumbnail_path"] = thumbnail_path
                                     payload["thumbnail_status"] = "generated"
@@ -2216,7 +2225,16 @@ def render_new_video(page_title: str = "Criação de Vídeos", prefix: str = "ne
                         thumbnail_path = str(variant.get("image_path") or payload.get("thumbnail_path") or "").strip()
                         if st.button("Gerar imagem da thumbnail com Nano Banana", key=f"{prefix}_generate_thumbnail_image", use_container_width=True):
                             try:
-                                thumbnail_path = str(generate_thumbnail_image(read_json("settings.json", {}), variant.get("image_prompt", ""), topic=str(payload.get("topic") or ""), variant_index=variant_index))
+                                thumbnail_path = str(
+                                    generate_thumbnail_image(
+                                        read_json("settings.json", {}),
+                                        variant.get("image_prompt", ""),
+                                        topic=str(payload.get("topic") or ""),
+                                        variant_index=variant_index,
+                                        lettering_text=str(variant.get("overlay_text") or payload.get("thumbnail_text") or ""),
+                                        lettering_prompt=str(variant.get("lettering_prompt") or ""),
+                                    )
+                                )
                                 variant["image_path"] = thumbnail_path
                                 payload["thumbnail_path"] = thumbnail_path
                                 payload["thumbnail_status"] = "generated"

package/hermes_ui/creative_generation.py

@@ -266,7 +266,7 @@ def generate_thumbnail_prompt(
         "És um director de arte de thumbnails para YouTube. Refaz um prompt de imagem forte e específico "
         "para o tópico fornecido, mantendo a intenção visual quando já existir um prompt. "
         "Separa rigorosamente a imagem sem texto do lettering: image_prompt nunca deve pedir texto renderizado, "
-        "enquanto overlay_text deve ser curto, legível e ter no máximo quatro palavras. "
+        "enquanto overlay_text é obrigatório, deve ser curto, legível e ter entre três e quatro palavras. "
         "Responde apenas com JSON válido nas chaves concept, overlay_text, composition, color_palette, subject, "
         "image_prompt, title_synergy e lettering_prompt."
     )
@@ -279,8 +279,8 @@ def generate_thumbnail_prompt(
             "reference_rules": reference_bundle(),
             "requirements": {
                 "image_prompt": "cinematic visual direction, no words, letters, logos or watermarks rendered in the image",
-                "overlay_text": "maximum 4 words, emotionally strong, not the full title",
-                "lettering_prompt": "instructions for changing only the lettering after the base image exists",
+                "overlay_text": "required, 3 to 4 words, emotionally strong, not the full title",
+                "lettering_prompt": "required instructions for rendering the exact overlay_text after the base image exists",
             },
         },
         ensure_ascii=False,
@@ -289,7 +289,11 @@ def generate_thumbnail_prompt(
     image_prompt = str(result.get("image_prompt") or "").strip()
     if not image_prompt:
         raise CreativeGenerationError("O provider não devolveu um prompt de imagem válido.")
-    overlay_text = _short_overlay(result.get("overlay_text"))
+    overlay_text = _short_overlay(result.get("overlay_text")) or _short_overlay(topic) or "WATCH NOW"
+    lettering_prompt = str(result.get("lettering_prompt") or "").strip() or (
+        "Render the exact overlay_text as bold, readable, high-contrast sans-serif lettering with an outline or shadow, "
+        "inside a safe zone and away from the main face or subject."
+    )
     return {
         "concept": str(result.get("concept") or "Thumbnail renovada").strip(),
         "overlay_text": overlay_text,
@@ -298,7 +302,7 @@ def generate_thumbnail_prompt(
         "subject": str(result.get("subject") or topic).strip(),
         "image_prompt": image_prompt,
         "title_synergy": str(result.get("title_synergy") or "").strip(),
-        "lettering_prompt": str(result.get("lettering_prompt") or "").strip(),
+        "lettering_prompt": lettering_prompt,
         "status": "prompt_ready",
     }
 
@@ -317,7 +321,7 @@ def generate_creative_package(
         "És director editorial e de thumbnails para YouTube. Cria um pacote coerente de título e thumbnail "
         "para o tópico fornecido. Gera exactamente pelo menos 20 títulos candidatos e entre 3 e 5 variantes de thumbnail. "
         "O título deve carregar keywords no início, ter curiosidade, especificidade e emoção, sem clickbait falso. "
-        "A thumbnail deve ter no máximo três elementos, alto contraste, uma composição clara, texto opcional de até 4 palavras, "
+        "A thumbnail deve ter no máximo três elementos, alto contraste, uma composição clara e lettering obrigatório de 3 a 4 palavras, "
         "safe zones e leitura em 120px. O texto da thumbnail não pode repetir o título integralmente. Remove AI tells. "
         "Responde apenas com JSON válido nas chaves selected_title, title_candidates, keywords e thumbnail_variants."
     )
@@ -337,12 +341,13 @@ def generate_creative_package(
             },
             "thumbnail_variant_schema": {
                 "concept": "string",
-                "overlay_text": "string, maximum 4 words",
+                "overlay_text": "required string, 3 to 4 words",
                 "composition": "string",
                 "color_palette": "string",
                 "subject": "string",
-                "image_prompt": "string, no text rendered in the image",
+                "image_prompt": "string describing the clean image base, without rendered text; lettering is specified separately",
                 "title_synergy": "string",
+                "lettering_prompt": "string describing how to render the exact overlay_text",
             },
         },
         ensure_ascii=False,
@@ -384,15 +389,21 @@ def generate_creative_package(
             continue
         if not str(item.get("concept") or "").strip() or not str(item.get("image_prompt") or "").strip():
             continue
+        overlay_text = _short_overlay(item.get("overlay_text")) or _short_overlay(topic) or "WATCH NOW"
+        lettering_prompt = str(item.get("lettering_prompt") or "").strip() or (
+            "Render the exact overlay_text as bold, readable, high-contrast sans-serif lettering with an outline or shadow, "
+            "inside a safe zone and away from the main face or subject."
+        )
         variants.append(
             {
                 "concept": str(item.get("concept") or "").strip(),
-                "overlay_text": _short_overlay(item.get("overlay_text")),
+                "overlay_text": overlay_text,
                 "composition": str(item.get("composition") or "").strip(),
                 "color_palette": str(item.get("color_palette") or "").strip(),
                 "subject": str(item.get("subject") or "").strip(),
                 "image_prompt": str(item.get("image_prompt") or "").strip(),
                 "title_synergy": str(item.get("title_synergy") or "").strip(),
+                "lettering_prompt": lettering_prompt,
                 "status": "prompt_ready",
             }
         )

package/hermes_ui/pipeline_worker.py

@@ -223,12 +223,33 @@ def _run_task(task: dict[str, Any]) -> dict[str, Any]:
 
     _update(task_id, stage="keywords", state="doing", progress=48)
     variant = creative.get("thumbnail_variant") if isinstance(creative.get("thumbnail_variant"), dict) else {}
-    prompt_payload = {"topic": topic, "title": title, "keywords": keywords, "thumbnail": variant, "requirements": {"aspect_ratio": "16:9", "resolution": "1920x1080", "max_elements": 3, "max_overlay_words": 4}}
+    prompt_payload = {
+        "topic": topic,
+        "title": title,
+        "keywords": keywords,
+        "thumbnail": variant,
+        "requirements": {
+            "aspect_ratio": "16:9",
+            "resolution": "1920x1080",
+            "max_elements": 3,
+            "max_overlay_words": 4,
+            "lettering_required": True,
+            "lettering_text": str(variant.get("overlay_text") or ""),
+            "lettering_prompt": str(variant.get("lettering_prompt") or ""),
+        },
+    }
     prompt_artifact = _save_json_artifact(task_id, "thumbnail-prompt", prompt_payload)
     artifacts = {**artifacts, "thumbnail_prompt_json": prompt_artifact}
     _update(task_id, stage="thumbnail_prompt", state="doing", progress=52, thumbnail_prompt=str(variant.get("image_prompt") or ""), thumbnail_text=str(variant.get("overlay_text") or ""), thumbnail_status="prompt_ready", artifacts=artifacts)
     _update(task_id, stage="thumbnail", state="doing", progress=56, thumbnail_prompt=str(variant.get("image_prompt") or ""), thumbnail_text=str(variant.get("overlay_text") or ""), thumbnail_status="prompt_ready", artifacts=artifacts)
-    thumbnail_path = generate_thumbnail_image(settings, str(variant.get("image_prompt") or ""), topic=topic, variant_index=0)
+    thumbnail_path = generate_thumbnail_image(
+        settings,
+        str(variant.get("image_prompt") or ""),
+        topic=topic,
+        variant_index=0,
+        lettering_text=str(variant.get("overlay_text") or ""),
+        lettering_prompt=str(variant.get("lettering_prompt") or ""),
+    )
     artifacts["thumbnail"] = str(thumbnail_path)
     _update(task_id, artifacts=artifacts, thumbnail_status="generated", progress=62)
 

package/hermes_ui/thumbnail_generation.py

@@ -4,6 +4,7 @@ import hashlib
 import mimetypes
 import json
 import os
+import re
 import tempfile
 from pathlib import Path
 from typing import Any
@@ -30,6 +31,51 @@ def _clean_detail(value: Any, api_key: str) -> str:
     return detail.replace(api_key, "[REDACTED]") if api_key else detail
 
 
+def _fallback_lettering(topic: str) -> str:
+    """Return a short headline when an older task has no overlay_text."""
+    words = re.findall(r"[\wÀ-ÿ$%'-]+", str(topic or ""), flags=re.UNICODE)
+    headline = " ".join(words[:4]).strip()
+    return headline.upper() if headline else "WATCH NOW"
+
+
+def _normalise_lettering_text(value: Any, topic: str) -> str:
+    """Keep the required thumbnail headline concise and never empty."""
+    words = re.findall(r"[\wÀ-ÿ$%'-]+", str(value or ""), flags=re.UNICODE)
+    if not words:
+        return _fallback_lettering(topic)
+    return " ".join(words[:4]).strip()
+
+
+def _compose_thumbnail_prompt(
+    base_prompt: str,
+    *,
+    topic: str = "",
+    lettering_text: str = "",
+    lettering_prompt: str = "",
+) -> tuple[str, str]:
+    """Combine the visual base and a mandatory, model-readable lettering layer."""
+    headline = _normalise_lettering_text(lettering_text, topic)
+    lettering_guidance = str(lettering_prompt or "").strip() or (
+        "Use a bold sans-serif headline with high contrast, a thick outline or shadow, "
+        "safe margins and placement that does not cover the face or main subject."
+    )
+    effective_prompt = (
+        "IMAGE BASE LAYER — create the requested cinematic YouTube thumbnail composition, subject, "
+        "lighting, colour palette and visual hierarchy. Keep the base image clean and uncluttered.\n"
+        f"{str(base_prompt or '').strip()}\n\n"
+        "MANDATORY LETTERING LAYER — the final image MUST visibly contain readable lettering. "
+        "If the image-base description says no text, no words or no lettering, that restriction is overridden "
+        "by this layer. Render the exact headline between the delimiters below; do not omit it, paraphrase it, "
+        "translate it, replace it with placeholder text or hide it.\n"
+        f"EXACT HEADLINE TO RENDER: <<<{headline}>>>\n"
+        f"LETTERING DESIGN: {lettering_guidance}\n"
+        "Use no more than three or four words, bold sans-serif typography, strong contrast, outline/shadow, "
+        "a safe-zone margin and a position that does not cover the face or main object. Do not add unrelated text, "
+        "logos or watermarks. The thumbnail must not be delivered without the exact headline visible."
+    )
+    return effective_prompt, headline
+
+
 def _decode_image_data(value: Any) -> bytes | None:
     if not isinstance(value, str) or not value.strip():
         return None
@@ -105,6 +151,8 @@ def generate_thumbnail_image(
     topic: str = "",
     variant_index: int = 0,
     reference_image: str | Path | None = None,
+    lettering_text: str = "",
+    lettering_prompt: str = "",
 ) -> Path:
     api_key = str(settings.get("gemini_image_api_key") or "").strip()
     if not api_key:
@@ -112,14 +160,20 @@ def generate_thumbnail_image(
     clean_prompt = str(prompt or "").strip()
     if not clean_prompt:
         raise ThumbnailGenerationError("A thumbnail não tem um prompt de imagem para gerar.")
+    effective_prompt, headline = _compose_thumbnail_prompt(
+        clean_prompt,
+        topic=topic,
+        lettering_text=lettering_text,
+        lettering_prompt=lettering_prompt,
+    )
 
     model = str(settings.get("gemini_image_model") or DEFAULT_GEMINI_IMAGE_MODEL).strip()
     aspect_ratio = str(settings.get("gemini_image_aspect_ratio") or DEFAULT_ASPECT_RATIO).strip()
     image_size = str(settings.get("gemini_image_size") or DEFAULT_IMAGE_SIZE).strip()
-    request_input: str | list[dict[str, str]] = clean_prompt
+    request_input: str | list[dict[str, str]] = effective_prompt
     if reference_image:
         request_input = [
-            {"type": "text", "text": clean_prompt},
+            {"type": "text", "text": effective_prompt},
             _image_input(Path(reference_image)),
         ]
     body = {
@@ -161,7 +215,12 @@ def generate_thumbnail_image(
     ensure_storage()
     output_dir = STORAGE / "thumbnails"
     output_dir.mkdir(parents=True, exist_ok=True)
-    destination = output_dir / _thumbnail_filename(clean_prompt, topic, variant_index, model)
+    destination = output_dir / _thumbnail_filename(
+        f"{effective_prompt}\nEXACT HEADLINE TO RENDER: {headline}",
+        topic,
+        variant_index,
+        model,
+    )
     fd, temp_name = tempfile.mkstemp(prefix=f".{destination.name}.", dir=output_dir)
     try:
         with os.fdopen(fd, "wb") as handle:

package/hermes_ui/thumbnails.py

@@ -205,6 +205,8 @@ def generate_thumbnail_for_task(task_id: str, settings: dict[str, Any]) -> tuple
         record["prompt"],
         topic=record["title"] or record["topic"],
         variant_index=record["variant_index"],
+        lettering_text=record.get("thumbnail_text") or "",
+        lettering_prompt=record.get("lettering_prompt") or "",
     )
     _persist_thumbnail_result(tasks, task, record, image_path)
     write_json("tasks.json", tasks)
@@ -258,6 +260,8 @@ def regenerate_thumbnail_prompt_and_image(
         prompt,
         topic=record["title"] or record["topic"],
         variant_index=record["variant_index"],
+        lettering_text=str((variant or {}).get("overlay_text") or ""),
+        lettering_prompt=str((variant or {}).get("lettering_prompt") or ""),
     )
     _persist_thumbnail_result(tasks, task, record, image_path, variant=variant, source="prompt_regenerated")
     write_json("tasks.json", tasks)
@@ -298,6 +302,7 @@ def regenerate_thumbnail_lettering(
         topic=record["title"] or record["topic"],
         variant_index=record["variant_index"],
         reference_image=previous_image,
+        lettering_prompt=edit_prompt,
     )
     variant = _variant_for_record(record)
     variant["image_prompt"] = base_prompt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.3.25",
+  "version": "0.3.26",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "license": "MIT",
   "main": "scripts/cli.mjs",