@danhachuel/thunderbolt 0.3.62 → 0.3.64

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.62
+> **Versão deste manual:** 0.3.64
 > **Pacote npm:** `@danhachuel/thunderbolt`
 > **Porta padrão da UI:** `localhost:3030`  
 > **Repositório:** [github.com/DanHachuel/thunderbolt](https://github.com/DanHachuel/thunderbolt)
@@ -53,7 +53,7 @@ A execução segue sempre **Tema → Script → Título → Keywords (opcional)
 | Full IA | Pool de vídeo limitado a FAL AI, KIE AI e Agnes AI | MP4 gerado pelo provider activo |
 | Apenas Música | Áudio local/Suno já preparado | Ficheiro musical pronto para um upload de música; não gera MP4, thumbnail nem upload YouTube |
 
-Antes de iniciar a rota stock, confirme em **Configurações > Configuração API > Fontes de materiais** que existe pelo menos uma API key para a fonte efectiva. Sem uma key Pexels/Pixabay, o erro é apresentado como configuração da fonte, em vez de uma falha genérica de vídeo. **Google Lyria não é apresentado como implementado nesta release**; a rota Apenas Música aceita áudio local e a integração Suno existente.
+Antes de iniciar a rota stock, confirme em **Configurações > Configuração API > Fontes de materiais** que existe pelo menos uma API key para a fonte efectiva. Sem uma key Pexels/Pixabay, o erro é apresentado como configuração da fonte, em vez de uma falha genérica de vídeo. Se o MoneyPrinterTurbo devolver `MPT_NEEDS_INPUT`, o Thunderbolt lê `LLM_PROVIDER`, `MISSING` e `INVALID` e mostra no erro todas as APIs afectadas, como **OpenAI / NVIDIA NIM API + Pexels API**, incluindo os campos que faltam. **Google Lyria não é apresentado como implementado nesta release**; a rota Apenas Música aceita áudio local e a integração Suno existente.
 
 ## 2. Pré-requisitos
 
@@ -128,13 +128,13 @@ Execute:
 Windows PowerShell ou MobaXterm:
 
 ```powershell
-npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.62 install
+npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.64 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes --prefer-online @danhachuel/thunderbolt@0.3.62 install
+npx --yes --prefer-online @danhachuel/thunderbolt@0.3.64 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.
@@ -142,7 +142,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.62 install --purge-data
+npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.64 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.
@@ -538,7 +538,7 @@ O cartão mostra o nicho imediatamente abaixo do nome. Os quatro blocos compacto
 
 A secção **Últimos 10 vídeos publicados** fica abaixo das configurações do canal, dentro de um expander fechado por defeito, e não dentro de Criação de Vídeos. Clique no expander e depois em **Actualizar últimos 10 vídeos** para consultar o feed RSS público do YouTube sem Data API Key. Os resultados são guardados em `storage/state/channel_videos.json`. A única vista disponível é **Lista**, que apresenta título, data, URL, estado e botão **Editar vídeo**. A edição local permite alterar título, estado, data, URL e notas. Essas alterações são overrides de gestão local e não publicam automaticamente no YouTube.
 
-A página **Configurações > Logs** aparece no menu entre **Notificações** e **Configuração API**. Mostra uma projecção unificada das tarefas e notificações persistentes, com filtro livre por operação, filtros por operação e estado e as colunas mínimas **Operação**, **Estado**, **Data** e **Hora**. A tabela também mostra **Registo**, **Origem**, **Progresso** e **Detalhes**; estados como pendente, em execução, concluído, publicado, falha, cancelado e bloqueado são apresentados quando existirem no storage local.
+A página **Configurações > Logs** aparece no menu entre **Notificações** e **Configuração API**. Mostra uma projecção unificada das tarefas e notificações persistentes, com filtro livre por operação, filtros por operação e estado e as colunas mínimas **Operação**, **Estado**, **Data** e **Hora**. A tabela também mostra **Registo**, **Origem**, **Progresso**, **API/Provider** e **Detalhes**; em qualquer falha nova, **API/Provider** identifica a API ou o pool responsável, o serviço, a rota e os campos de configuração em falta. Registos anteriores sem essa metadata aparecem explicitamente como falhas históricas cuja API não pôde ser identificada. Estados como pendente, em execução, concluído, publicado, falha, cancelado e bloqueado são apresentados quando existirem no storage local.
 
 ## Canais em lote por conta Google/YouTube
 
@@ -556,7 +556,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.62 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.64 install`; o instalador detecta e reutiliza o que já estiver válido.
 
 ### Niche Finder Apify
 

package/README.md

@@ -44,6 +44,8 @@ Em **Pipeline Vídeos > Criação de Vídeos** e **Automação Youtube**, a opç
 
 A ordem persistida da criação é **Tema → Script → Título → Keywords opcional → Vídeo → Prompt Thumbnail em JSON → Thumbnail → Upload**. O vídeo é materializado antes do prompt e da imagem da thumbnail; uma falha posterior de thumbnail não invalida um MP4 já pronto. **Full IA** é uma rota separada e usa exclusivamente os cartões activos FAL AI, KIE AI e Agnes AI do pool de vídeo. **Apenas Música** não chama a pipeline de vídeo nem tenta gerar thumbnail: reutiliza o áudio local/Suno já descarregado e deixa-o pronto para a integração de upload musical.
 
+Quando uma etapa falha, a tarefa, a notificação e a página **Configurações > Logs** guardam e mostram sempre a coluna **API/Provider**, o serviço, a rota e, quando aplicável, os campos de configuração em falta. No caso do MoneyPrinterTurbo, os marcadores `LLM_PROVIDER`, `MISSING` e `INVALID` são convertidos em attribution legível; por exemplo, um erro pode indicar simultaneamente **OpenAI / NVIDIA NIM API** e **Pexels API**, em vez de apresentar apenas a mensagem genérica de credenciais adicionais. O worker invoca o helper com `--` antes das flags MoneyPrinterTurbo, porque `mpt_agent.py` reserva esses argumentos para a CLI filha. Registos históricos sem metadata são identificados explicitamente como anteriores à attribution estruturada.
+
 ## Upload-Post — publicação para múltiplas plataformas
 
 A página **Upload** contém quatro subabas: **Upload convencional**, **Upload directo**, **Postiz** e **Upload-Post**. A quarta alternativa usa a API oficial do [Upload-Post](https://docs.upload-post.com/) para enviar um vídeo local para uma ou mais plataformas ligadas ao perfil configurado. Seleccione as plataformas na própria subaba, confirme o título e a descrição e clique em **Enviar vídeo pelo Upload-Post**.
@@ -85,7 +87,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.62
+## Navegação da UI 0.3.64
 
 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**, **Geração de Conteúdo IA**, **Redes Sociais**, **Tutorial Meta** e **Tutorial Supabase**, nessa ordem. A página Geração de Conteúdo IA divide-se em **Imagens**, **Vídeos** e **Motion Control**; a subaba Motion Control permanece vazia nesta release.
  **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.

package/app/main.py

@@ -5862,10 +5862,11 @@ def render_logs():
             "Registo": st.column_config.TextColumn("Registo", width=280),
             "Origem": st.column_config.TextColumn("Origem", width=130),
             "Progresso": st.column_config.TextColumn("Progresso", width=100),
+            "API/Provider": st.column_config.TextColumn("API/Provider", width=220),
             "Detalhes": st.column_config.TextColumn("Detalhes", width=760),
         },
     )
-    st.caption("Quando a tabela exceder a largura disponível, utilize a barra de rolagem horizontal na parte inferior para consultar todo o conteúdo das células.")
+    st.caption("A coluna API/Provider identifica a API responsável por cada falha; quando o registo é anterior a esta correcção, o sistema assinala que a API não pôde ser identificada. Quando a tabela exceder a largura disponível, utilize a barra de rolagem horizontal na parte inferior para consultar todo o conteúdo das células.")
 
 
 def render_notifications():

package/hermes_ui/domain.py

@@ -221,11 +221,22 @@ def _notify_task_completion(task: dict[str, Any], previous_state: str = "") -> N
     title = str(task.get("title") or task.get("topic") or "Actividade")
     channel = str(task.get("channel_name") or "Canal")
     if current_state == "failed":
+        failure_api = str(task.get("failure_api") or "API não identificada (falha anterior)").strip()
         record_notification(
             "activity_failed",
             f"Actividade falhou: {title}",
-            f"A actividade de {channel} terminou com erro.",
-            metadata={"task_id": task_id, "channel_name": channel, "error": task.get("error") or ""},
+            f"A actividade de {channel} terminou com erro. API/provider: {failure_api}.",
+            metadata={
+                "task_id": task_id,
+                "channel_name": channel,
+                "error": task.get("error") or "",
+                "failure_api": task.get("failure_api") or "API não identificada (falha anterior)",
+                "failure_provider": task.get("failure_provider") or "unknown",
+                "failure_service": task.get("failure_service") or "Thunderbolt",
+                "failure_route": task.get("failure_route") or "",
+                "failure_config_fields": task.get("failure_config_fields") or "",
+                "failure_stage": task.get("failure_stage") or task.get("failed_stage") or task.get("stage") or "pipeline",
+            },
             dedupe_key=f"task:{task_id}:failed",
         )
         return

package/hermes_ui/logs.py

@@ -76,6 +76,29 @@ def _operation_label(operation_code: str, fallback: str = "Operação") -> str:
     return str(event.get("label") if event else fallback or operation_code or "Operação")
 
 
+def _fallback_task_failure_api(task: dict[str, Any]) -> str:
+    """Infer a safe API label for legacy failed tasks without structured metadata."""
+    route = str(task.get("material_source") or task.get("style_wide") or "").strip().casefold()
+    if "pexels" in route and "pixabay" in route:
+        return "Pexels/Pixabay API (fonte efectiva não registada)"
+    if "pixabay" in route:
+        return "Pixabay API"
+    if "pexels" in route or "stock" in route:
+        return "Pexels/Pixabay API (fonte efectiva não registada)"
+    if route in {"full_ia", "full ia", "ia"}:
+        return "FAL AI / KIE AI / Agnes AI"
+    if route in {"music", "musica", "música"} or bool(task.get("music_mode")):
+        return "Suno / Ficheiro local"
+    stage = str(task.get("stage") or task.get("failed_stage") or "").strip().casefold()
+    if stage in {"topic", "script", "title", "keywords", "thumbnail_prompt"}:
+        return "LLM textual API (provider não registado)"
+    if stage == "thumbnail":
+        return "Pool de imagem API (provider não registado)"
+    if stage == "upload":
+        return "YouTube Upload API"
+    return "API não identificada (falha anterior)"
+
+
 def _task_log(task: dict[str, Any]) -> dict[str, Any] | None:
     task_id = str(task.get("id") or "").strip()
     if not task_id:
@@ -100,6 +123,20 @@ def _task_log(task: dict[str, Any]) -> dict[str, Any] | None:
     if progress_value is not None:
         details.append(f"Progresso: {progress_value}%")
     error = str(task.get("error") or "").strip()
+    failure_api = str(task.get("failure_api") or "").strip()
+    failure_provider = str(task.get("failure_provider") or "").strip()
+    failure_service = str(task.get("failure_service") or "").strip()
+    failure_fields = str(task.get("failure_config_fields") or "").strip()
+    api_provider = failure_api
+    if state in {"failed", "error"}:
+        api_provider = api_provider or _fallback_task_failure_api(task)
+        details.append(f"API/provider: {api_provider}")
+        if failure_provider:
+            details.append(f"Provider: {failure_provider}")
+        if failure_service:
+            details.append(f"Serviço: {failure_service}")
+        if failure_fields:
+            details.append(f"Configuração: {failure_fields}")
     if error:
         details.append(error[:500])
     return {
@@ -114,6 +151,7 @@ def _task_log(task: dict[str, Any]) -> dict[str, Any] | None:
         "source": "Tarefas",
         "record": title,
         "details": " · ".join(details),
+        "api_provider": api_provider or "",
         "progress": progress_value,
         "task_id": task_id,
     }
@@ -141,6 +179,9 @@ def _notification_log(entry: dict[str, Any]) -> dict[str, Any] | None:
     date, time = format_log_date_time(occurred_at)
     metadata = entry.get("metadata") if isinstance(entry.get("metadata"), dict) else {}
     public_metadata = [f"{key}: {value}" for key, value in metadata.items() if value not in (None, "")]
+    api_provider = str(metadata.get("failure_api") or metadata.get("api_provider") or "").strip()
+    if status_code in {"failed", "error"}:
+        api_provider = api_provider or "API não identificada (falha anterior)"
     return {
         "id": f"notification:{entry_id}",
         "operation_code": event_type,
@@ -153,6 +194,7 @@ def _notification_log(entry: dict[str, Any]) -> dict[str, Any] | None:
         "source": "Notificações",
         "record": str(entry.get("title") or entry.get("label") or "Notificação"),
         "details": " · ".join([str(entry.get("message") or "").strip(), *public_metadata]).strip(" ·")[:1000],
+        "api_provider": api_provider,
         "progress": None,
         "task_id": str(metadata.get("task_id") or ""),
     }
@@ -227,6 +269,7 @@ def logs_to_rows(records: list[dict[str, Any]]) -> list[dict[str, Any]]:
             "Registo": item.get("record") or "—",
             "Origem": item.get("source") or "—",
             "Progresso": f"{item['progress']}%" if item.get("progress") is not None else "—",
+            "API/Provider": item.get("api_provider") or "—",
             "Detalhes": item.get("details") or "—",
         }
         for item in records

package/hermes_ui/notifications.py

@@ -236,7 +236,24 @@ def _task_notifications() -> int:
         title = str(task.get("title") or task.get("topic") or "Actividade")
         channel = str(task.get("channel_name") or "Canal")
         if state == "failed":
-            if record_notification("activity_failed", f"Actividade falhou: {title}", f"A actividade de {channel} terminou com erro.", metadata={"task_id": task_id, "channel_name": channel}, dedupe_key=f"task:{task_id}:failed"):
+            failure_api = str(task.get("failure_api") or "API não identificada (falha anterior)").strip()
+            if record_notification(
+                "activity_failed",
+                f"Actividade falhou: {title}",
+                f"A actividade de {channel} terminou com erro. API/provider: {failure_api}.",
+                metadata={
+                    "task_id": task_id,
+                    "channel_name": channel,
+                    "error": task.get("error") or "",
+                    "failure_api": task.get("failure_api") or "API não identificada (falha anterior)",
+                    "failure_provider": task.get("failure_provider") or "unknown",
+                    "failure_service": task.get("failure_service") or "Thunderbolt",
+                    "failure_route": task.get("failure_route") or "",
+                    "failure_config_fields": task.get("failure_config_fields") or "",
+                    "failure_stage": task.get("failure_stage") or task.get("failed_stage") or task.get("stage") or "pipeline",
+                },
+                dedupe_key=f"task:{task_id}:failed",
+            ):
                 created += 1
             continue
         if state != "done":

package/hermes_ui/pipeline_worker.py

@@ -33,6 +33,10 @@ WORKER_HEARTBEAT_TIMEOUT_SECONDS = 15
 class PipelineError(RuntimeError):
     """Raised when a pipeline stage cannot complete with an actionable error."""
 
+    def __init__(self, message: str, *, failure_metadata: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.failure_metadata = dict(failure_metadata or {})
+
 
 class PipelineStopped(PipelineError):
     """Raised when the user stops a task while the worker is processing it."""
@@ -187,7 +191,9 @@ def _recover_stale_tasks() -> list[str]:
             f"A tarefa ficou sem heartbeat durante mais de {STALE_TASK_SECONDS // 60} minutos. "
             "Foi marcada como falhada para evitar execução eterna; reveja o log do worker."
         )
-        update_task(task_id, {"state": "failed", "error": message, "failed_stage": task.get("stage") or "pipeline"})
+        failed_stage = str(task.get("stage") or "pipeline")
+        metadata = _failure_attribution(task, _settings(), failed_stage, error=message)
+        update_task(task_id, {"state": "failed", "error": _failure_message(message, metadata), "failed_stage": failed_stage, **metadata})
         recovered.append(task_id)
     return recovered
 
@@ -276,13 +282,160 @@ def _helper_output_value(output: str, key: str) -> str:
 
 
 def _redact_helper_output(text: str) -> str:
-    for key in ("MPT_LLM_API_KEY", "MPT_PEXELS_API_KEY"):
+    for key in ("MPT_LLM_API_KEY", "MPT_PEXELS_API_KEY", "MPT_PIXABAY_API_KEY"):
         secret = os.environ.get(key, "").strip()
         if secret:
             text = text.replace(secret, "[redacted]")
     return text
 
 
+def _helper_failure_markers(output: str) -> dict[str, Any]:
+    missing = [item.strip() for item in re.findall(r"(?m)^MISSING=(.+)$", output) if item.strip()]
+    invalid = [item.strip() for item in re.findall(r"(?m)^INVALID=(.+)$", output) if item.strip()]
+    return {
+        "helper_provider": _helper_output_value(output, "LLM_PROVIDER"),
+        "missing_fields": list(dict.fromkeys(missing)),
+        "invalid_fields": list(dict.fromkeys(invalid)),
+    }
+
+
+def _provider_api_label(provider: str) -> str:
+    code = str(provider or "").strip().casefold()
+    if code in {"pexels", "pixabay"}:
+        return f"{code.capitalize()} API"
+    if code in {"local", "local_storage"}:
+        return "Ficheiro local"
+    return f"{provider_definition(code).label} API"
+
+
+def _failure_attribution(
+    task: dict[str, Any],
+    settings: dict[str, Any],
+    stage: str,
+    *,
+    error: str = "",
+    output: str = "",
+) -> dict[str, Any]:
+    """Return safe, human-readable API attribution for every pipeline failure."""
+    route = _normalise_video_route(task, settings)
+    markers = _helper_failure_markers(output)
+    missing = list(markers["missing_fields"])
+    invalid = list(markers["invalid_fields"])
+    provider_code = str(markers["helper_provider"] or "").strip().casefold()
+    combined = f"{output} {error}".casefold()
+
+    if stage == "video" and missing:
+        api_labels: list[str] = []
+        provider_values: list[str] = []
+        for field in [*missing, *invalid]:
+            if field.endswith("_api_keys"):
+                source = field.removesuffix("_api_keys")
+                label = _provider_api_label(source)
+                provider_values.append(source)
+            elif field.endswith("_api_key"):
+                source = field.removesuffix("_api_key")
+                label = _provider_api_label(source)
+                provider_values.append(source)
+            else:
+                label = field
+            if label not in api_labels:
+                api_labels.append(label)
+        return {
+            "failure_api": " + ".join(api_labels) or _provider_api_label(route),
+            "failure_provider": ", ".join(dict.fromkeys(provider_values or ([provider_code] if provider_code else [route]))),
+            "failure_service": "MoneyPrinterTurbo",
+            "failure_route": route,
+            "failure_config_fields": ", ".join(dict.fromkeys([*missing, *invalid])),
+            "failure_stage": stage,
+        }
+
+    if stage == "video" and route in {"pexels", "pixabay"}:
+        return {
+            "failure_api": _provider_api_label(route),
+            "failure_provider": route,
+            "failure_service": "MoneyPrinterTurbo",
+            "failure_route": route,
+            "failure_config_fields": f"{route}_api_keys",
+            "failure_stage": stage,
+        }
+    if stage == "video" and route == "full_ia":
+        providers = [("fal_ai", "FAL AI"), ("kie_ai", "KIE AI"), ("agnes", "Agnes AI")]
+        found = [label for code, label in providers if code in combined or label.casefold() in combined]
+        labels = found or [label for _, label in providers]
+        codes = [code for code, label in providers if label in labels] or [code for code, _ in providers]
+        return {
+            "failure_api": " / ".join(f"{label} API" for label in labels),
+            "failure_provider": ", ".join(codes),
+            "failure_service": "Pool de vídeo Full IA",
+            "failure_route": route,
+            "failure_config_fields": "",
+            "failure_stage": stage,
+        }
+    if stage in {"topic", "script", "title", "keywords", "thumbnail_prompt"}:
+        card = active_llm_card(settings)
+        provider = str(card.get("provider") or provider_code or "openai").strip()
+        return {
+            "failure_api": _provider_api_label(provider),
+            "failure_provider": provider,
+            "failure_service": "LLM textual",
+            "failure_route": route,
+            "failure_config_fields": "",
+            "failure_stage": stage,
+        }
+    if stage == "thumbnail":
+        cards = media_cards_for_pool(settings, "image")
+        labels = []
+        codes = []
+        for card in cards:
+            code = str(card.get("provider") or "").strip().casefold()
+            if not code:
+                continue
+            label = _provider_api_label(code)
+            if code in combined or label.casefold() in combined or len(cards) == 1:
+                labels.append(label)
+                codes.append(code)
+        if not labels:
+            labels = [_provider_api_label(str(card.get("provider") or "imagem")) for card in cards] or ["Pool Imagem API"]
+            codes = [str(card.get("provider") or "").strip() for card in cards if card.get("provider")] or ["image_pool"]
+        return {
+            "failure_api": " / ".join(labels),
+            "failure_provider": ", ".join(codes),
+            "failure_service": "Pool de imagem",
+            "failure_route": route,
+            "failure_config_fields": "",
+            "failure_stage": stage,
+        }
+    if stage == "upload":
+        return {
+            "failure_api": "YouTube Upload API",
+            "failure_provider": "youtube_upload",
+            "failure_service": "Upload",
+            "failure_route": route,
+            "failure_config_fields": "",
+            "failure_stage": stage,
+        }
+    return {
+        "failure_api": "API não identificada (falha anterior)",
+        "failure_provider": provider_code or "unknown",
+        "failure_service": "Thunderbolt",
+        "failure_route": route,
+        "failure_config_fields": ", ".join(dict.fromkeys([*missing, *invalid])),
+        "failure_stage": stage or "pipeline",
+    }
+
+
+def _failure_message(message: str, metadata: dict[str, Any]) -> str:
+    api = str(metadata.get("failure_api") or "API não identificada").strip()
+    provider = str(metadata.get("failure_provider") or "").strip()
+    fields = str(metadata.get("failure_config_fields") or "").strip()
+    suffix = f" API/provider: {api}"
+    if provider and provider.casefold() not in api.casefold():
+        suffix += f" (provider: {provider})"
+    if fields:
+        suffix += f"; configuração: {fields}"
+    return f"{message.rstrip('.')} —{suffix}."
+
+
 def _persist_video_diagnostics(task: dict[str, Any], output: str) -> dict[str, str]:
     """Persist only bounded helper diagnostics and return its declared file paths."""
     task_id = str(task.get("id") or "").strip()
@@ -291,11 +444,15 @@ def _persist_video_diagnostics(task: dict[str, Any], output: str) -> dict[str, s
     log_file = _helper_output_value(output, "LOG_FILE")
     result_file = _helper_output_value(output, "RESULT_FILE")
     try:
+        markers = _helper_failure_markers(output)
         payload: dict[str, Any] = {
             "captured_at": _now(),
             "log_file": log_file,
             "result_file": result_file,
             "output_tail": _redact_helper_output(output[-6000:]),
+            "helper_provider": markers["helper_provider"],
+            "missing_fields": markers["missing_fields"],
+            "invalid_fields": markers["invalid_fields"],
         }
         artifact_path = _save_json_artifact(task_id, "video-diagnostics", payload)
         current = _task_by_id(task_id) or task
@@ -497,9 +654,9 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
     source_keys = material_api_keys(settings, route) if route in {"pexels", "pixabay"} else []
     if route in {"pexels", "pixabay"} and not source_keys:
         source_label = "Pexels" if route == "pexels" else "Pixabay"
-        raise PipelineError(
-            f"Configure pelo menos uma API key de {source_label} em Configurações > Configuração API > Fontes de materiais."
-        )
+        message = f"Configure pelo menos uma API key de {source_label} em Configurações > Configuração API > Fontes de materiais."
+        metadata = _failure_attribution(task, settings, "video", error=message)
+        raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata)
     if configured_root:
         try:
             sync_moneyprinter_config(settings, str(configured_root))
@@ -521,13 +678,16 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
     command = ["uv", "run", "--no-project", "--python", "3.11", "python", "mpt_agent.py"]
     if configured_root:
         command.extend(["--root", str(configured_root)])
-    command.extend(["--subject", subject])
+    command.extend(["--subject", subject, "--"])
     generation_settings = task.get("generation_settings") if isinstance(task.get("generation_settings"), dict) else {}
     command.extend(_moneyprinter_cli_args(task, route))
     if str(generation_settings.get("voiceover_mode") or "").strip().casefold() == "upload":
         voiceover_file = Path(str(generation_settings.get("voiceover_file") or "").strip()).expanduser()
         if not str(voiceover_file) or not voiceover_file.is_file() or voiceover_file.stat().st_size <= 0:
-            raise PipelineError("O modo Upload foi seleccionado, mas não existe um ficheiro de narração válido. Carregue o áudio em Configurações de áudio.")
+            message = "O modo Upload foi seleccionado, mas não existe um ficheiro de narração válido. Carregue o áudio em Configurações de áudio."
+            metadata = _failure_attribution(task, settings, "video", error=message)
+            metadata.update({"failure_api": "Ficheiro local", "failure_provider": "local_storage", "failure_service": "Áudio de narração", "failure_config_fields": "voiceover_file"})
+            raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata)
         command.extend(["--custom-audio-file", str(voiceover_file.resolve())])
     output_lines: list[str] = []
     line_queue: queue.Queue[str | None] = queue.Queue()
@@ -554,7 +714,10 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
             bufsize=1,
         )
     except FileNotFoundError as exc:
-        raise PipelineError("O comando uv não está instalado; não foi possível iniciar a geração de vídeo.") from exc
+        message = "O comando uv não está instalado; não foi possível iniciar a geração de vídeo."
+        metadata = _failure_attribution(task, settings, "video", error=message)
+        metadata.update({"failure_service": "Runtime MoneyPrinterTurbo"})
+        raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata) from exc
 
     reader = threading.Thread(target=_read_output, name=f"mpt-output-{task.get('id', 'video')}", daemon=True)
     reader.start()
@@ -597,7 +760,9 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
                 break
             if elapsed >= VIDEO_TIMEOUT_SECONDS:
                 _stop_process(process)
-                raise PipelineError(f"A etapa Vídeo excedeu o limite de {VIDEO_TIMEOUT_SECONDS // 60} minutos e foi encerrada.")
+                message = f"A etapa Vídeo excedeu o limite de {VIDEO_TIMEOUT_SECONDS // 60} minutos e foi encerrada."
+                metadata = _failure_attribution(task, settings, "video", error=message)
+                raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata)
     finally:
         reader.join(timeout=2)
         _persist_video_diagnostics(task, "\n".join(output_lines))
@@ -607,10 +772,14 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
     output = "\n".join(output_lines)
     _persist_video_diagnostics(task, output)
     if result_code == 10:
-        raise PipelineError("A geração de vídeo precisa de credenciais adicionais do MoneyPrinterTurbo.")
+        metadata = _failure_attribution(task, settings, "video", output=output)
+        message = "A geração de vídeo precisa de credenciais adicionais do MoneyPrinterTurbo"
+        raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata)
     if result_code != 0:
         detail = _redact_helper_output(output[-1200:]).strip() or "erro sem detalhes devolvidos pelo helper"
-        raise PipelineError(f"MoneyPrinterTurbo falhou na etapa Vídeo: {detail}")
+        metadata = _failure_attribution(task, settings, "video", error=detail, output=output)
+        message = f"MoneyPrinterTurbo falhou na etapa Vídeo: {detail}"
+        raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata)
     match = re.search(r"(?m)^VIDEO_FILE=(.+)$", output)
     video_path = Path(match.group(1).strip()).expanduser() if match else None
     if not video_path or not video_path.is_file() or video_path.stat().st_size <= 0:
@@ -623,7 +792,9 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
             except (OSError, json.JSONDecodeError):
                 video_path = None
     if not video_path or not video_path.is_file() or video_path.stat().st_size <= 0:
-        raise PipelineError("MoneyPrinterTurbo terminou sem devolver um MP4 válido.")
+        message = "MoneyPrinterTurbo terminou sem devolver um MP4 válido."
+        metadata = _failure_attribution(task, settings, "video", error=message, output=output)
+        raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata)
     return video_path
 
 
@@ -835,8 +1006,11 @@ def _run_task(task: dict[str, Any]) -> dict[str, Any]:
                 })
         except MediaGenerationError as exc:
             if route == "full_ia":
-                raise PipelineError(f"Pool Full IA (FAL/KIE AI/Agnes AI): {exc}") from exc
-            raise PipelineError(f"Pipeline MoneyPrinterTurbo ({route}): {exc}") from exc
+                message = f"Pool Full IA (FAL/KIE AI/Agnes AI): {exc}"
+            else:
+                message = f"Pipeline MoneyPrinterTurbo ({route}): {exc}"
+            metadata = _failure_attribution(task, settings, "video", error=str(exc))
+            raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata) from exc
         current_after_video = _task_by_id(task_id) or {}
         artifacts = dict(current_after_video.get("artifacts") or artifacts)
         artifacts["video"] = str(video_path)
@@ -972,9 +1146,22 @@ def run_once() -> dict[str, Any]:
             message = str(exc)[:2000]
             from hermes_ui.domain import update_task
             current_task = _task_by_id(task_id) or candidate
-            update_task(task_id, {"state": "failed", "error": message, "failed_stage": current_task.get("stage") or "pipeline"})
-            _worker_heartbeat(status="failed", last_error=message, stage=str(current_task.get("stage") or "pipeline"), progress=int(current_task.get("progress") or 0), task_id=task_id)
-            return {"ok": False, "task_id": task_id, "error": message, "recovered_task_ids": recovered}
+            failed_stage = str(current_task.get("stage") or "pipeline")
+            settings = _settings()
+            failure_metadata = dict(getattr(exc, "failure_metadata", {}) or {})
+            if not failure_metadata:
+                failure_metadata = _failure_attribution(current_task, settings, failed_stage, error=message)
+            if "API/provider:" not in message:
+                message = _failure_message(message, failure_metadata)[:2000]
+            failure_updates = {
+                "state": "failed",
+                "error": message,
+                "failed_stage": failed_stage,
+                **failure_metadata,
+            }
+            update_task(task_id, failure_updates)
+            _worker_heartbeat(status="failed", last_error=message, stage=failed_stage, progress=int(current_task.get("progress") or 0), task_id=task_id)
+            return {"ok": False, "task_id": task_id, "error": message, "failure_metadata": failure_metadata, "recovered_task_ids": recovered}
     finally:
         try:
             lock.unlink()

package/package.json

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