@danhachuel/thunderbolt 0.2.30 → 0.2.32

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.2.30
+> **Versão deste manual:** 0.2.31
 > **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 @danhachuel/thunderbolt@0.2.30 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.31 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes @danhachuel/thunderbolt@0.2.30 install
+npx --yes @danhachuel/thunderbolt@0.2.31 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.
@@ -351,8 +351,11 @@ Na primeira execução, a barra lateral apresenta **Início**, **Pipeline**, **A
 | YouTube upload principal | Lógica do `youtube-automation-agent` adaptada e executada dentro do Thunderbolt |
 | OAuth directo de redundância | Caminho alternativo accionado automaticamente se o agente falhar |
 | TikTok Client ID/Secret | Credenciais da aplicação; Redirect URI, scopes e autorização ficam no TikTok for Developers Playground |
+| Kaggle Username | Nome da conta Kaggle usada para publicar e executar a kernel remota |
+| Kaggle API Key | Chave da conta Kaggle, guardada mascarada apenas em `storage/state/settings.json` |
+| Slug da kernel Kaggle | Identificador da kernel remota, por padrão `thunderbolt-niche-finder` |
 
-As credenciais devem ser inseridas apenas na configuração local. A Data API Key, o OAuth Client ID e o OAuth Client Secret são valores diferentes; Client ID + Secret não geram uma API Key nem um token OAuth até a conta ser autorizada. Não coloque nenhum deles no GitHub, no `package.json`, em blueprints ou em ficheiros de estado versionados.
+As credenciais devem ser inseridas apenas na configuração local. A Kaggle API Key é usada somente pelo executor remoto para publicar a kernel, consultar o estado e obter os resultados pequenos; o dataset não é descarregado para `storage/data/niches`. A Data API Key, o OAuth Client ID e o OAuth Client Secret são valores diferentes; Client ID + Secret não geram uma API Key nem um token OAuth até a conta ser autorizada. Não coloque nenhum deles no GitHub, no `package.json`, em blueprints ou em ficheiros de estado versionados.
 
 ## 9. Testar as áreas principais
 
@@ -384,7 +387,7 @@ Ao abrir a página, o Thunderbolt prepara automaticamente os dados públicos atr
 
 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. 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. A análise inicial é automática; o botão **Analisar Nichos** recalcula os resultados depois de alterar os 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 @danhachuel/thunderbolt@0.2.30 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 @danhachuel/thunderbolt@0.2.31 install`; o instalador detecta e reutiliza o que já estiver válido.
 
 ## Pipeline: Criação de Vídeos, Criação de Músicas e Automação
 

package/README.md

@@ -21,12 +21,12 @@ A primeira versão implementa a camada UI independente com:
 | Upload | YouTube via `youtube-automation-agent` adaptado internamente, OAuth directo de redundância, Upload directo experimental, TikTok, Instagram e Facebook Pages no front end |
 | MCP | Catálogo local opcional de Short Video Maker, AutoVio, OpenMontage e OpenCut, com portas editáveis e activação |
 | Limpador de Metadados | Upload isolado de vídeos terceiros, limpeza FFmpeg, edição de título/descrição/tags e manifesto JSON |
-| Configurações Técnicas | Provedores LLM, TTS/voz, preview de vozes, Suno, materiais, Whisper, FFmpeg, OAuth YouTube, Data API Key opcional, Upload directo, TikTok Client ID/Secret e Upload-Post |
+| Configurações Técnicas | Provedores LLM, TTS/voz, preview de vozes, Suno, materiais, Whisper, FFmpeg, OAuth YouTube, Data API Key opcional, Kaggle Username/API Key, Upload directo, TikTok Client ID/Secret e Upload-Post |
 | Launcher | Execução via `npx`, instalação assistida, diagnóstico e preparação para distribuição |
 
 Os adaptadores do MoneyPrinterTurbo e de publicação nas plataformas são ligados pelas configurações locais e pelos pontos de integração em `integrations/`. A UI não inventa dados quando um serviço externo ou credencial não está disponível.
 
-## Navegação da UI 0.2.30
+## Navegação da UI 0.2.32
 
 A barra lateral mantém apenas os cinco níveis principais, nesta ordem: **Início**, **Pipeline**, **Automação**, **Niche Finder** e **Configurações**. **Pipeline** é expansível e contém **Criação de Vídeos**, **Criação de Músicas**, **Upload** e **Limpador de Metadados**. **Configurações** é expansível e contém **Canais**, **Blueprints**, **MCP** e **Configurações Técnicas**. O Início reúne o dashboard e as filas do Pipeline, sem botões de acções rápidas.
 
@@ -109,9 +109,9 @@ thunderbolt
 No Windows PowerShell, se `npx` for bloqueado por `npx.ps1`, use directamente `npx.cmd`:
 
 ```powershell
-npx.cmd --yes @danhachuel/thunderbolt@0.2.30 install
-npx.cmd --yes @danhachuel/thunderbolt@0.2.30 doctor
-npx.cmd --yes @danhachuel/thunderbolt@0.2.30
+npx.cmd --yes @danhachuel/thunderbolt@0.2.32 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.32 doctor
+npx.cmd --yes @danhachuel/thunderbolt@0.2.32
 ```
 
 Como alternativa, pode permitir scripts para o seu utilizador:
@@ -135,7 +135,7 @@ A página **Niche Finder** integra a lógica do projecto open source [johanfortu
 
 A interface apresenta directamente os parâmetros da busca: número de clusters entre 2 e 10, suporte mínimo entre 0,01 e 0,50, país, categoria de engagement, intervalo de datas e tags. A análise inicial é executada automaticamente e **Analisar Nichos** permite recalcular os resultados depois de alterar os filtros. O núcleo aplica normalização, filtros, `log1p`, `StandardScaler`, K-Means e FP-Growth. Os resultados aparecem em DataFrames para clusters, itemsets frequentes, regras de associação e dados analisados, acompanhados por uma visualização Plotly nativa e pesquisa de palavras nos clusters.
 
-As dependências adicionais são instaladas pelo fluxo normal do pacote: `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub`. Em instalações existentes, execute novamente `npx.cmd --yes @danhachuel/thunderbolt@0.2.30 install`; o instalador detecta e reutiliza componentes já válidos.
+As dependências adicionais são instaladas pelo fluxo normal do pacote: `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub`. Em instalações existentes, execute novamente `npx.cmd --yes @danhachuel/thunderbolt@0.2.31 install`; o instalador detecta e reutiliza componentes já válidos.
 
 ## Armazenamento local
 

package/app/main.py

@@ -1028,6 +1028,17 @@ def render_settings():
             youtube_client_id = text_setting("YouTube OAuth Client ID", "youtube_client_id", help_text="Client ID do OAuth 2.0 criado no Google Cloud. É usado para iniciar a autorização da conta YouTube.")
         with youtube_cols[1]:
             youtube_client_secret = text_setting("YouTube OAuth Client Secret", "youtube_client_secret", secret=True, help_text="Client Secret do mesmo cliente OAuth 2.0. Não é uma API Key.")
+
+        with st.expander("Niche Finder — execução remota no Kaggle", expanded=True):
+            st.caption("O dataset permanece no Kaggle. O Thunderbolt usa estas credenciais apenas para publicar/executar a kernel e obter os resultados pequenos da análise.")
+            kaggle_cols = st.columns(3)
+            with kaggle_cols[0]:
+                kaggle_username = text_setting("Kaggle Username", "kaggle_username", help_text="Nome de utilizador da sua conta Kaggle, sem @ e sem URL.")
+            with kaggle_cols[1]:
+                kaggle_api_key = text_setting("Kaggle API Key", "kaggle_api_key", secret=True, help_text="Chave criada em Kaggle > Settings > API. Nunca é incluída no notebook ou no GitHub.")
+            with kaggle_cols[2]:
+                kaggle_kernel_slug = text_setting("Slug da kernel", "kaggle_kernel_slug", help_text="Identificador da kernel remota, por exemplo thunderbolt-niche-finder.")
+
         with st.expander("Consulta oficial de métricas — opcional"):
             st.caption("A YouTube Data API Key é uma credencial Google Cloud separada do OAuth. Só é necessária se escolher o método YouTube Data API para consultar métricas oficiais. Não é necessária para Página pública — sem API Key, para autorizar OAuth ou para fazer upload.")
             youtube_api_key = text_setting("YouTube Data API Key (opcional)", "youtube_api_key", secret=True, help_text="Credencial separada, criada em Google Cloud > APIs e serviços > Credenciais > Chave de API. Não cole aqui o Client ID nem o Client Secret.")
@@ -1148,6 +1159,7 @@ def render_settings():
             settings.update({
                 "port": port, "moneyprinter_path": moneyprinter_path, "youtube_api_key": youtube_api_key,
                 "youtube_client_id": youtube_client_id, "youtube_client_secret": youtube_client_secret,
+                "kaggle_username": kaggle_username.strip(), "kaggle_api_key": kaggle_api_key.strip(), "kaggle_kernel_slug": kaggle_kernel_slug.strip() or "thunderbolt-niche-finder",
                 "direct_cookie_sid": direct_cookie_sid, "direct_cookie_ssid": direct_cookie_ssid, "direct_cookie_hsid": direct_cookie_hsid, "direct_cookie_apisid": direct_cookie_apisid, "direct_cookie_sapisid": direct_cookie_sapisid, "direct_session_info": direct_session_info, "direct_innertube_api_key": direct_innertube_api_key, "direct_chunk_size": direct_chunk_size,
                 "log_level": log_level, "listen_host": listen_host, "listen_port": listen_port, "video_source": video_source,
                 "endpoint": endpoint, "proxy_http": proxy_http, "proxy_https": proxy_https, "match_materials_to_script": match_materials_to_script,

package/app/modules/niche_finder/data_loader.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import shutil
+import tempfile
 from pathlib import Path
 
 import pandas as pd
@@ -61,26 +62,50 @@ def _copy_csv(source: Path, destination: Path) -> Path:
     return destination
 
 
+def _has_usable_cached_dataset() -> bool:
+    """Check only the header so a valid multi-gigabyte cache is not read twice."""
+    if not DEFAULT_DATASET_PATH.exists() or DEFAULT_DATASET_PATH.stat().st_size <= 0:
+        return False
+    try:
+        columns = set(pd.read_csv(DEFAULT_DATASET_PATH, nrows=0).columns)
+    except (OSError, UnicodeDecodeError, pd.errors.ParserError, pd.errors.EmptyDataError):
+        return False
+    return set(REQUIRED_COLUMNS).issubset(columns)
+
+
 def _download_with_kagglehub() -> Path | None:
     if kagglehub is None:
         return None
-    data_dir = ensure_data_dir()
-    try:
-        downloaded = kagglehub.dataset_download(DEFAULT_DATASET_SLUG, output_dir=str(data_dir))
-    except TypeError:
-        downloaded = kagglehub.dataset_download(DEFAULT_DATASET_SLUG)
-    except Exception as exc:  # pragma: no cover - depends on network/provider state
-        raise DatasetError(f"O Thunderbolt não conseguiu preparar os dados automáticos: {exc}") from exc
-    source = _find_csv(Path(downloaded))
-    if source is None:
-        raise DatasetError("A preparação automática terminou sem encontrar dados compatíveis.")
-    return _copy_csv(source, DEFAULT_DATASET_PATH)
+    ensure_data_dir()
+    # KaggleHub rejects a non-empty output_dir on Windows. Use a new temporary
+    # directory for every download, then copy only the validated CSV into the
+    # persistent Thunderbolt cache. This also isolates partial downloads.
+    with tempfile.TemporaryDirectory(prefix=".niche-kaggle-", dir=str(DATA_DIR.parent)) as temporary_root:
+        temporary_path = Path(temporary_root)
+        try:
+            try:
+                downloaded = kagglehub.dataset_download(
+                    DEFAULT_DATASET_SLUG,
+                    output_dir=str(temporary_path),
+                    force_download=True,
+                )
+            except TypeError:  # compatibility with older KaggleHub releases
+                downloaded = kagglehub.dataset_download(
+                    DEFAULT_DATASET_SLUG,
+                    output_dir=str(temporary_path),
+                )
+        except Exception as exc:  # pragma: no cover - depends on network/provider state
+            raise DatasetError(f"O Thunderbolt não conseguiu preparar os dados automáticos: {exc}") from exc
+        source = _find_csv(Path(downloaded))
+        if source is None:
+            raise DatasetError("A preparação automática terminou sem encontrar dados compatíveis.")
+        return _copy_csv(source, DEFAULT_DATASET_PATH)
 
 
 def download_kaggle_dataset() -> Path:
     """Prepare and cache the public Niche-Finder dataset without user interaction."""
     ensure_data_dir()
-    if DEFAULT_DATASET_PATH.exists() and DEFAULT_DATASET_PATH.stat().st_size > 0:
+    if _has_usable_cached_dataset():
         return DEFAULT_DATASET_PATH
     if kagglehub is None:
         raise DatasetError("O componente automático de dados não está disponível nesta instalação.")

package/hermes_ui/storage.py

@@ -81,6 +81,9 @@ DEFAULTS: dict[str, Any] = {
         "youtube_api_key": "",
         "youtube_client_id": "",
         "youtube_client_secret": "",
+        "kaggle_username": "",
+        "kaggle_api_key": "",
+        "kaggle_kernel_slug": "thunderbolt-niche-finder",
         "llm_provider": "moonshot",
         "moonshot_api_key": "",
         "moonshot_base_url": "",

package/package.json

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