@danhachuel/thunderbolt 0.3.45 → 0.3.46

package/MANUAL-INSTALACAO.md

@@ -2,7 +2,7 @@
 
 Este manual descreve a instalação local da UI Thunderbolt, baseada no MoneyPrinterTurbo, utilizando o pacote npm `@danhachuel/thunderbolt`. O fluxo recomendado instala automaticamente o ambiente Python, as dependências da aplicação, as dependências do MoneyPrinterTurbo, o Streamlit e o suporte FFmpeg através de `imageio-ffmpeg`.
 
-> **Versão deste manual:** 0.3.45
+> **Versão deste manual:** 0.3.46
 > **Pacote npm:** `@danhachuel/thunderbolt`
 > **Porta padrão da UI:** `localhost:3030`  
 > **Repositório:** [github.com/DanHachuel/thunderbolt](https://github.com/DanHachuel/thunderbolt)
@@ -100,13 +100,13 @@ Execute:
 Windows PowerShell ou MobaXterm:
 
 ```powershell
-npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.45 install
+npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.46 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes --prefer-online @danhachuel/thunderbolt@0.3.45 install
+npx --yes --prefer-online @danhachuel/thunderbolt@0.3.46 install
 ```
 
 A instalação normal é **segura para actualizações**: preserva `storage`, Blueprints, Brandings, configurações e artefactos do utilizador. Remove apenas `.venv`, o clone técnico do MoneyPrinterTurbo e dependências que serão recriadas. Uma pasta antiga sem dados do utilizador, como `C:\Users\<utilizador>\AppData\Local\hermes` da tentativa incompleta, pode ser removida; uma pasta antiga que contenha Blueprints, Brandings ou storage é preservada e apenas avisada no terminal. Feche processos Python, Node, Streamlit e MobaXterm que estejam a usar as pastas antes de executar.
@@ -114,7 +114,7 @@ A instalação normal é **segura para actualizações**: preserva `storage`, Bl
 Se quiser apagar absolutamente tudo de forma intencional, use o comando destrutivo separado:
 
 ```powershell
-npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.45 install --purge-data
+npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.46 install --purge-data
 ```
 
 O parâmetro `--purge-data` apaga Blueprints, Brandings, configurações, storage e artefactos locais. Não o use numa actualização normal.
@@ -363,11 +363,11 @@ Em **Configuração API > API Keys**, o expander **LLM — providers e modelos**
 
 O bloco **Limite LLM NVIDIA NIM** permite ligar **Activar limitador NVIDIA NIM — 40 RPM**. O valor padrão é 40 pedidos numa janela de 60 segundos. O contador é persistido localmente por cartão/chave e aplica-se à criação manual, aos workers e às automações. A opção vem desligada para não alterar instalações existentes; ligue-a quando o endpoint activo for NVIDIA NIM e a sua conta tiver esse limite.
 
-O expander **Imagem e Video** substitui o antigo bloco isolado da Nano Banana. Os cartões disponíveis são **Nano Banana**, **Pollinations.ai**, **Agnes AI**, **Hugging Face Inference API**, **Cloudflare Workers AI**, **InferencePort Proxy**, **阿里云 (Alibaba Cloud Model Studio)**, **KIE AI** e **FAL AI**. Em cada cartão, configure a API key/token, o modelo, a Base URL, o estado **Provider activo**, a participação no **Pool Imagem**, a participação no **Pool Vídeo** e a prioridade. O botão **Testar Chamada API** faz apenas uma verificação read-only; não inicia geração de imagem ou vídeo.
+O expander **Imagem e Video** substitui o antigo bloco isolado da Nano Banana. Os cartões disponíveis são **Nano Banana**, **Pollinations.ai**, **Agnes AI**, **Hugging Face Inference API**, **Cloudflare Workers AI**, **InferencePort Proxy**, **阿里云 (Alibaba Cloud Model Studio)**, **KIE AI** e **FAL AI**. Em cada cartão, configure a API key/token, o modelo, a Base URL, o estado **Provider activo**, a participação no **Pool Imagem**, a participação no **Pool Vídeo** e a prioridade. **Image Size** e **Aspect Ratio** não aparecem nos cartões e não são editáveis: são defaults internos aplicados automaticamente no prompt da geração. O botão **Testar Chamada API** faz apenas uma verificação read-only; não inicia geração de imagem ou vídeo.
 
 | Provider | Configuração mínima | Pool suportado |
 |---|---|---|
-| Nano Banana | API key, modelo Gemini e parâmetros da imagem | Imagem |
+| Nano Banana | API key e modelo Gemini; composição aplicada internamente | Imagem |
 | Pollinations.ai | API key/token, modelo e Base URL | Imagem e vídeo |
 | Agnes AI | API key, modelo e Base URL | Imagem e vídeo |
 | Hugging Face Inference API | Token, modelo e `https://router.huggingface.co/v1` | Imagem |
@@ -522,7 +522,7 @@ Ao abrir a página, o Thunderbolt não prepara dados públicos, não descarrega
 
 Os parâmetros da UI são número de clusters entre 2 e 10, suporte mínimo entre 0,01 e 0,50, país, engagement, intervalo de datas e tags, todos dentro da área principal da aba. O núcleo normaliza os dados, calcula engagement, aplica filtros, faz transformação logarítmica e standardização, executa K-Means e calcula itemsets/regras com FP-Growth. Não são apresentados resultados até ao primeiro clique em **Analisar Nichos**; o mesmo botão aplica alterações posteriores aos filtros. Os resultados são DataFrames de clusters, itemsets frequentes, regras de associação e dados analisados; o gráfico de dispersão é criado nativamente com Plotly.
 
-As dependências adicionais — `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub` — são instaladas pelo procedimento normal de `npx`. Em instalações existentes, execute novamente `npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.45 install`; o instalador detecta e reutiliza o que já estiver válido.
+As dependências adicionais — `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub` — são instaladas pelo procedimento normal de `npx`. Em instalações existentes, execute novamente `npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.46 install`; o instalador detecta e reutiliza o que já estiver válido.
 
 ### Niche Finder Apify
 

package/README.md

@@ -69,7 +69,7 @@ No topo da área principal da aplicação existe o menu nativo de idioma no padr
 
 A UI suporta os temas **Dark** e **Light** através do menu nativo de três pontos do Streamlit, no local original do toolbar. Não existe um selector Theme adicional dentro da página. A configuração distribuída em `.streamlit/config.toml` disponibiliza as variantes nomeadas **Dark** e **Light**, e o menu nativo continua responsável por alternar entre os modos, seguindo o padrão do [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo). O CSS próprio do Thunderbolt usa cores semânticas, `currentColor` e `color-mix` para acompanhar o tema activo, sem alterar a posição nem a funcionalidade do toolbar, do botão Deploy e do menu principal.
 
-## Navegação da UI 0.3.45
+## Navegação da UI 0.3.46
 
 A barra lateral mantém os níveis principais, nesta ordem: **Início**, **Niche Finder**, **Pipeline**, **Pipeline TikTok**, **Automação**, **Edição**, **AI Influencers** e **Configurações**. **Pipeline Vídeos** é expansível e contém **Criação de Vídeos**, **Backlog Vídeos**, **Roteiros**, **Thumbnails** e **Upload**. **Pipeline Música** é expansível e contém **Criação de Músicas** e **Upload Música**. **Automação** também é expansível e contém **Automação Youtube**. **Edição** é expansível e contém **Limpador de Metadados**, **Cortes**, **Editor Python** e **Download Mídia**, nessa ordem. **AI Influencers** é expansível e contém **Personagens**, **Redes Sociais**, **Tutorial Meta** e **Tutorial Supabase**, nessa ordem. **Niche Finder** é expansível e contém **Niche Finder Kaggle** e **Niche Finder Apify**. **Configurações** é expansível e contém **Canais Youtube**, **Blueprints Youtube**, **MCP**, **Contas Google**, **Notificações**, **Logs** e **Configuração API**, nessa ordem. O Início reúne o dashboard e as filas do Pipeline, sem botões de acções rápidas.
 
@@ -85,7 +85,7 @@ Em **Configuração API > API Keys**, a subaba **Fontes de materiais** segue o p
 
 A subaba **Serviços e modelos** mantém as credenciais de providers e serviços que não são fontes de materiais. A chave `gemini_image_api_key` da Nano Banana continua separada de `gemini_api_key` do LLM textual. `INNERTUBE_API_KEY` permanece exclusivamente em **Configurações > Contas Google**, no bloco de configuração global fora dos cartões, e não é duplicada em API Keys.
 
-O expander **Imagem e Video** reúne cartões independentes para **Nano Banana**, **Pollinations.ai**, **Agnes AI**, **Hugging Face Inference API**, **Cloudflare Workers AI**, **InferencePort Proxy**, **阿里云 (Alibaba Cloud Model Studio)**, **KIE AI** e **FAL AI**. Cada cartão permite configurar API key/token quando necessário, modelo, Base URL, activar o provider, escolher participação no **Pool Imagem** e/ou **Pool Vídeo**, definir prioridade e executar **Testar Chamada API**. O InferencePort usa por defeito `http://localhost:8080/v1` e não exige chave; o Cloudflare requer Account ID; os restantes providers devem ser preenchidos de acordo com a conta e endpoint disponibilizados pelo serviço.
+O expander **Imagem e Video** reúne cartões independentes para **Nano Banana**, **Pollinations.ai**, **Agnes AI**, **Hugging Face Inference API**, **Cloudflare Workers AI**, **InferencePort Proxy**, **阿里云 (Alibaba Cloud Model Studio)**, **KIE AI** e **FAL AI**. Cada cartão permite configurar API key/token quando necessário, modelo, Base URL, activar o provider, escolher participação no **Pool Imagem** e/ou **Pool Vídeo**, definir prioridade e executar **Testar Chamada API**. Os parâmetros técnicos de composição, como **Image Size** e **Aspect Ratio**, não são apresentados nem editáveis nos cartões: ficam como defaults internos e são acrescentados automaticamente ao prompt da geração de imagem e/ou vídeo. O InferencePort usa por defeito `http://localhost:8080/v1` e não exige chave; o Cloudflare requer Account ID; os restantes providers devem ser preenchidos de acordo com a conta e endpoint disponibilizados pelo serviço.
 
 O router mantém três pools independentes: **LLM textual**, **imagem** e **vídeo**. O failover só passa ao cartão seguinte em quota, timeout, erro de transporte ou HTTP transitório; erros de credencial, endpoint/modelo inexistente ou payload inválido ficam registados e não são mascarados por um provider diferente. O pool de vídeo externo é opcional: quando desligado, o worker continua a usar o motor local MoneyPrinterTurbo; quando ligado, usa apenas os cartões marcados para Pool Vídeo.
 

package/hermes_ui/media_generation.py

@@ -16,7 +16,14 @@ from urllib.parse import urljoin
 
 import requests
 
-from .media_providers import media_cards_for_pool, media_provider_definition
+from .media_providers import (
+    INTERNAL_IMAGE_ASPECT_RATIO,
+    INTERNAL_IMAGE_SIZE,
+    INTERNAL_VIDEO_ASPECT_RATIO,
+    INTERNAL_VIDEO_SIZE,
+    media_cards_for_pool,
+    media_provider_definition,
+)
 from .provider_routing import (
     POOL_IMAGE,
     POOL_VIDEO,
@@ -52,6 +59,28 @@ def _headers(card: Mapping[str, Any], *, fal: bool = False) -> dict[str, str]:
     return headers
 
 
+def _append_generation_constraints(
+    prompt: str,
+    *,
+    kind: str,
+    aspect_ratio: str = "",
+    size: str = "",
+) -> str:
+    """Append controlled rendering constraints without exposing editable UI fields."""
+    clean = str(prompt or "").strip()
+    if kind == "image":
+        ratio = str(aspect_ratio or INTERNAL_IMAGE_ASPECT_RATIO).strip()
+        resolution = str(size or INTERNAL_IMAGE_SIZE).strip()
+        constraints = f"Target image composition: {ratio} aspect ratio, {resolution} resolution."
+    else:
+        ratio = str(aspect_ratio or INTERNAL_VIDEO_ASPECT_RATIO).strip()
+        resolution = str(size or INTERNAL_VIDEO_SIZE).strip()
+        constraints = f"Target video composition: {ratio} aspect ratio, {resolution} resolution."
+    if not clean:
+        return constraints
+    return f"{clean}\n\n{constraints}"
+
+
 def _decode_data(value: Any) -> bytes | None:
     if not isinstance(value, str) or not value.strip():
         return None
@@ -142,14 +171,20 @@ def _image_request(card: dict[str, Any], prompt: str) -> Any:
     provider = str(card.get("provider") or "").strip().lower()
     style = str(card.get("api_style") or media_provider_definition(provider).api_style)
     endpoint = _image_endpoint(card)
+    constrained_prompt = _append_generation_constraints(
+        prompt,
+        kind="image",
+        aspect_ratio=str(card.get("aspect_ratio") or ""),
+        size=str(card.get("image_size") or ""),
+    )
     if style == "cloudflare":
-        return requests.post(endpoint, headers=_headers(card), json={"prompt": prompt}, timeout=180)
+        return requests.post(endpoint, headers=_headers(card), json={"prompt": constrained_prompt}, timeout=180)
     if style == "fal_queue":
-        return requests.post(endpoint, headers=_headers(card, fal=True), json={"prompt": prompt, "num_images": 1}, timeout=180)
+        return requests.post(endpoint, headers=_headers(card, fal=True), json={"prompt": constrained_prompt, "num_images": 1}, timeout=180)
     if style == "dashscope":
-        body = {"model": _model(card), "input": {"prompt": prompt}, "parameters": {"size": "1024*1024", "n": 1}}
+        body = {"model": _model(card), "input": {"prompt": constrained_prompt}, "parameters": {"n": 1}}
         return requests.post(endpoint, headers=_headers(card), json=body, timeout=180)
-    body = {"model": _model(card), "prompt": prompt, "n": 1, "response_format": "b64_json"}
+    body = {"model": _model(card), "prompt": constrained_prompt, "n": 1, "response_format": "b64_json"}
     return requests.post(endpoint, headers=_headers(card), json=body, timeout=180)
 
 
@@ -171,10 +206,17 @@ def generate_image_for_card(
         merged = dict(settings)
         merged["gemini_image_api_key"] = _api_key(card)
         merged["gemini_image_model"] = _model(card) or merged.get("gemini_image_model") or "gemini-3.1-flash-image"
+        merged["gemini_image_aspect_ratio"] = str(card.get("aspect_ratio") or INTERNAL_IMAGE_ASPECT_RATIO)
+        merged["gemini_image_size"] = str(card.get("image_size") or INTERNAL_IMAGE_SIZE)
         try:
             return generate_thumbnail_image(
                 merged,
-                prompt,
+                _append_generation_constraints(
+                    prompt,
+                    kind="image",
+                    aspect_ratio=str(card.get("aspect_ratio") or ""),
+                    size=str(card.get("image_size") or ""),
+                ),
                 topic=topic,
                 variant_index=variant_index,
                 lettering_text=lettering_text,
@@ -260,7 +302,15 @@ def _video_endpoint(card: Mapping[str, Any]) -> str:
 def _video_request(card: dict[str, Any], prompt: str, image_url: str = "") -> Any:
     style = str(card.get("api_style") or media_provider_definition(card.get("provider")).api_style)
     endpoint = _video_endpoint(card)
-    body: dict[str, Any] = {"model": _model(card), "prompt": prompt}
+    body: dict[str, Any] = {
+        "model": _model(card),
+        "prompt": _append_generation_constraints(
+            prompt,
+            kind="video",
+            aspect_ratio=str(card.get("aspect_ratio") or ""),
+            size=str(card.get("video_size") or ""),
+        ),
+    }
     if image_url:
         body["image_url"] = image_url
     if style == "fal_queue":

package/hermes_ui/media_providers.py

@@ -12,6 +12,12 @@ MEDIA_VIDEO_ACTIVE_CARD_KEY = "media_video_active_card_id"
 MEDIA_IMAGE_ACTIVE_PROVIDER_KEY = "media_image_provider"
 MEDIA_VIDEO_ACTIVE_PROVIDER_KEY = "media_video_provider"
 
+# Mantidos internamente para preservar compatibilidade e controlar o prompt dos providers.
+INTERNAL_IMAGE_ASPECT_RATIO = "16:9"
+INTERNAL_IMAGE_SIZE = "1K"
+INTERNAL_VIDEO_ASPECT_RATIO = "16:9"
+INTERNAL_VIDEO_SIZE = "1080p"
+
 
 @dataclass(frozen=True, slots=True)
 class MediaProviderDefinition:
@@ -35,7 +41,6 @@ MEDIA_PROVIDER_CATALOG: tuple[MediaProviderDefinition, ...] = (
         default_base_url="https://generativelanguage.googleapis.com/v1beta",
         supports_image=True,
         api_style="gemini_interactions",
-        extra_fields=("aspect_ratio", "image_size"),
         description="Geração de imagem nativa Gemini para thumbnails e artes.",
     ),
     MediaProviderDefinition(
@@ -170,6 +175,9 @@ def normalize_media_card(card: Any, index: int = 0) -> dict[str, Any]:
     }
     for field in definition.extra_fields:
         result[field] = str(source.get(field) or "").strip()
+    if provider == "nano_banana":
+        result["aspect_ratio"] = str(source.get("aspect_ratio") or INTERNAL_IMAGE_ASPECT_RATIO).strip()
+        result["image_size"] = str(source.get("image_size") or INTERNAL_IMAGE_SIZE).strip()
     test_result = source.get("test_result")
     if isinstance(test_result, Mapping) and str(test_result.get("status") or "") in {"success", "error"}:
         result["test_result"] = {
@@ -215,8 +223,8 @@ def ensure_media_provider_cards(settings: Mapping[str, Any]) -> tuple[dict[str,
                     "api_key": legacy_key,
                     "model": legacy_model,
                     "base_url": "https://generativelanguage.googleapis.com/v1beta",
-                    "aspect_ratio": str(result.get("gemini_image_aspect_ratio") or "16:9"),
-                    "image_size": str(result.get("gemini_image_size") or "1K"),
+                    "aspect_ratio": str(result.get("gemini_image_aspect_ratio") or INTERNAL_IMAGE_ASPECT_RATIO),
+                    "image_size": str(result.get("gemini_image_size") or INTERNAL_IMAGE_SIZE),
                     "enabled": True,
                 },
                 0,
@@ -267,8 +275,8 @@ def apply_media_provider_cards_to_settings(settings: Mapping[str, Any], cards: l
     if nano_card:
         result["gemini_image_api_key"] = str(nano_card.get("api_key") or "")
         result["gemini_image_model"] = str(nano_card.get("model") or "gemini-3.1-flash-image")
-        result["gemini_image_aspect_ratio"] = str(nano_card.get("aspect_ratio") or result.get("gemini_image_aspect_ratio") or "16:9")
-        result["gemini_image_size"] = str(nano_card.get("image_size") or result.get("gemini_image_size") or "1K")
+        result["gemini_image_aspect_ratio"] = str(nano_card.get("aspect_ratio") or result.get("gemini_image_aspect_ratio") or INTERNAL_IMAGE_ASPECT_RATIO)
+        result["gemini_image_size"] = str(nano_card.get("image_size") or result.get("gemini_image_size") or INTERNAL_IMAGE_SIZE)
     return result
 
 

package/hermes_ui/pipeline_worker.py

@@ -17,7 +17,7 @@ from hermes_ui.script_documents import save_script_document
 from hermes_ui.script_generation import generate_script_document
 from hermes_ui.storage import STORAGE, ensure_storage, read_json, write_json
 from hermes_ui.llm_providers import active_llm_card, provider_definition
-from hermes_ui.media_generation import MediaGenerationError, generate_image_from_pool, generate_video_from_pool
+from hermes_ui.media_generation import MediaGenerationError, _append_generation_constraints, generate_image_from_pool, generate_video_from_pool
 from hermes_ui.media_providers import media_cards_for_pool
 from hermes_ui.thumbnail_generation import ThumbnailGenerationError, generate_thumbnail_image
 
@@ -554,7 +554,10 @@ def _run_task(task: dict[str, Any]) -> dict[str, Any]:
     video_cards = media_cards_for_pool(settings, "video")
     if bool(settings.get("media_video_pool_enabled")) and video_cards:
         try:
-            video_prompt = f"Título: {title}\n\nRoteiro:\n{str(script.get('content') or '')[:12000]}"
+            video_prompt = _append_generation_constraints(
+                f"Título: {title}\n\nRoteiro:\n{str(script.get('content') or '')[:12000]}",
+                kind="video",
+            )
             video_path = generate_video_from_pool(settings, video_prompt)
         except MediaGenerationError as exc:
             raise PipelineError(f"Pool de vídeo externo: {exc}") from exc

package/package.json

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