@danhachuel/thunderbolt 0.2.30 → 0.2.31

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.
@@ -384,7 +384,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

@@ -26,7 +26,7 @@ A primeira versão implementa a camada UI independente com:
 
 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.31
 
 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.31 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.31 doctor
+npx.cmd --yes @danhachuel/thunderbolt@0.2.31
 ```
 
 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/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/package.json

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