@danhachuel/thunderbolt 0.2.33 → 0.2.34

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.33
+> **Versão deste manual:** 0.2.34
 > **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.33 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.34 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes @danhachuel/thunderbolt@0.2.33 install
+npx --yes @danhachuel/thunderbolt@0.2.34 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.
@@ -371,7 +371,7 @@ Após iniciar a aplicação, valide o seguinte percurso:
 2. **Blueprints:** coloque um JSON em `~/.thunderbolt/storage/blueprints/importados/` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT\storage\blueprints\importados\`) ou use o carregador da interface.
 3. **Brandings:** abra a subaba **Brandings** e confirme a listagem dos ficheiros JSON.
 4. **Canais:** em **Importar do YouTube**, use o método **Página pública — sem API Key** com um URL `/channel/UC...`, um handle ou uma subpágina `/videos`; o parser resolve o ID, consulta a página pública e tenta o RSS quando necessário. Confirme que o resultado abre o formulário de revisão sem Data API Key. Se o canal não existir ou não fornecer metadados, confirme a mensagem clara e que o formulário de uma pesquisa anterior desaparece. A Data API é opcional e fica separada; em **Cadastro manual**, preencha os dados sem qualquer consulta externa.
-5. **Niche Finder:** abra a página na sidebar e aguarde a preparação automática. Confirme que não aparece upload de CSV, botão de download de dataset ou selector de ficheiros. A análise inicial deve carregar directamente métricas, clusters, gráfico Plotly, regras de associação e dados analisados. Altere país, engagement, datas e tags e confirme que **Analisar Nichos** recalcula os resultados.
+5. **Niche Finder:** abra a página na sidebar, defina os parâmetros dentro do conteúdo principal e confirme que não há preparação automática. Antes do clique, não deve existir download de dataset nem análise. Clique em **Analisar Nichos** para iniciar a preparação dos dados e a análise; depois altere país, engagement, datas e tags e clique novamente para aplicar os novos parâmetros.
 6. **Pipeline > Criação de Vídeos:** teste primeiro o modo **Canal específico** e depois os modos de lote.
 7. **Criação de Vídeos > Vídeos:** verifique o estado `to_do` e os botões **Iniciar** e **Parar** dentro da subaba. Confirme também que **Criação de Músicas** mostra o mesmo fluxo com título próprio.
 8. **Upload:** configure o OAuth Client ID e Secret, autorize primeiro o **youtube-automation-agent** na própria aba, confirme o estado **pronto para publicar**, preencha título/descrição/tags e publique um MP4 real. O botão **Autorizar fallback OAuth** existe apenas para redundância; a Data API Key, se configurada, é exclusivamente para consultas oficiais públicas e nunca substitui OAuth.
@@ -389,11 +389,11 @@ Após iniciar a aplicação, valide o seguinte percurso:
 
 A página **Niche Finder** integra a lógica adaptada do projecto open source [johanfortus/Niche-Finder](https://github.com/johanfortus/Niche-Finder), cujo projecto original usa K-Means e FP-Growth sobre o dataset público [Trending Youtube Video Statistics (113 Countries)](https://www.kaggle.com/datasets/asaniczka/trending-youtube-videos-113-countries). No Thunderbolt não existe Flask, rota HTTP adicional, template HTML, JavaScript D3 ou segundo processo; toda a análise é síncrona no Streamlit.
 
-Ao abrir a página, o Thunderbolt prepara automaticamente os dados públicos através do KaggleHub e inicia a análise. O utilizador não precisa de baixar datasets, carregar CSVs, preparar planilhas ou escolher ficheiros. A interface apresenta directamente os parâmetros da busca e os resultados.
+Ao abrir a página, o Thunderbolt não prepara dados públicos, não descarrega o dataset e não inicia a análise. A instalação das dependências continua automática, mas a operação é manual: os parâmetros ficam dentro da própria aba e o utilizador deve clicar em **Analisar Nichos**. Só depois desse clique o KaggleHub prepara ou reutiliza a cache local; não há upload de CSV, botão de download manual ou selector de ficheiros.
 
-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.
+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 @danhachuel/thunderbolt@0.2.33 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.34 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

@@ -17,7 +17,7 @@ A primeira versão implementa a camada UI independente com:
 | Canais | Subabas de importação pública sem API Key, Data API opcional e cadastro manual independente |
 | Criação de Vídeos / Criação de Músicas | Subabas Criar vídeo e Vídeos; lotes; 51 rótulos de idioma; Pexels/Pixabay, full IA com Estilo IA e Apenas Música com agente musical; a segunda página reutiliza o mesmo fluxo com título próprio |
 | Automação | Lista de vídeos e canais, selectores editáveis de Blueprint/voz padrão, Automação ON, horário diário HH:MM e worker local baseado no relógio do computador |
-| Niche Finder | Preparação e análise automáticas, filtros, K-Means, FP-Growth, regras de associação, clusters e gráfico Plotly nativo |
+| Niche Finder | Parâmetros dentro da própria aba, início manual após clique, K-Means, FP-Growth, regras de associação, clusters e gráfico Plotly nativo |
 | 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 |
@@ -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.33
+## Navegação da UI 0.2.34
 
 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.
 
@@ -115,9 +115,9 @@ thunderbolt
 No Windows PowerShell, se `npx` for bloqueado por `npx.ps1`, use directamente `npx.cmd`:
 
 ```powershell
-npx.cmd --yes @danhachuel/thunderbolt@0.2.33 install
-npx.cmd --yes @danhachuel/thunderbolt@0.2.33 doctor
-npx.cmd --yes @danhachuel/thunderbolt@0.2.33
+npx.cmd --yes @danhachuel/thunderbolt@0.2.34 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.34 doctor
+npx.cmd --yes @danhachuel/thunderbolt@0.2.34
 ```
 
 Como alternativa, pode permitir scripts para o seu utilizador:
@@ -137,11 +137,11 @@ Após `install`, o launcher usa o ambiente virtual instalado em `~/.thunderbolt/
 
 ## Niche Finder
 
-A página **Niche Finder** integra a lógica do projecto open source [johanfortus/Niche-Finder](https://github.com/johanfortus/Niche-Finder) directamente no processo Streamlit. O Thunderbolt não inicia Flask, não abre uma porta adicional e não copia templates HTML ou D3. Ao abrir a página, o próprio Thunderbolt prepara automaticamente os dados públicos necessários através do KaggleHub, guarda a cache localmente e executa a análise; o utilizador não precisa de baixar datasets, carregar CSVs ou preparar planilhas.
+A página **Niche Finder** integra a lógica do projecto open source [johanfortus/Niche-Finder](https://github.com/johanfortus/Niche-Finder) directamente no processo Streamlit. O Thunderbolt não inicia Flask, não abre uma porta adicional e não copia templates HTML ou D3. Ao abrir a página, o Thunderbolt não descarrega dados, não prepara o dataset e não executa análises. A instalação das dependências continua automática, mas a operação é manual: o utilizador define os parâmetros dentro da própria aba e clica em **Analisar Nichos**. Só nesse momento o KaggleHub prepara ou reutiliza a cache local do dataset e a análise é executada.
 
-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.
+A interface apresenta dentro da aba 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 página permanece sem resultados até o primeiro clique em **Analisar Nichos**; depois, se os parâmetros forem alterados, mostra os resultados anteriores e pede novo clique para aplicar os filtros actuais. 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.31 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.34 install`; o instalador detecta e reutiliza componentes já válidos.
 
 ## Armazenamento local
 

package/app/main.py

@@ -21,7 +21,7 @@ from hermes_ui.domain import STAGES, create_batch, create_channel, create_tasks_
 from hermes_ui.automation_worker import load_worker_status
 from hermes_ui.storage import BLUEPRINTS, ensure_storage, list_blueprint_files, load_blueprint_file, now, read_json, write_json
 from app.modules.niche_finder.core import NicheAnalysisError, run_niche_analysis
-from app.modules.niche_finder.data_loader import DatasetError, download_kaggle_dataset, load_dataframe
+from app.modules.niche_finder.data_loader import DatasetError, download_kaggle_dataset
 from hermes_ui.blueprints import create_blueprint_from_link, list_branding_files, save_generated_blueprint
 from hermes_ui.metadata_cleaner import build_description, clean_video_metadata, list_edit_records, metadata_manifest, normalize_tags, save_edit_record, store_external_video
 from hermes_ui.mcp import detect_local_service, install_skill_locally, load_integrations, load_server_config, read_packaged_skill, save_server_config, update_integration
@@ -630,79 +630,56 @@ def render_music_creation():
     render_new_video(page_title="Criação de Músicas")
 
 
-@st.cache_data(show_spinner=False)
-def _cached_niche_dataset(path_str: str, modified_ns: int):
-    return load_dataframe(path_str)
-
-
 @st.cache_data(show_spinner=False)
 def _cached_niche_download():
+    """Download or reuse the dataset only after the user submits the form."""
     return str(download_kaggle_dataset())
 
 
-def _load_automatic_niche_dataset():
-    dataset_path = _cached_niche_download()
-    path = Path(dataset_path)
-    return dataset_path, _cached_niche_dataset(dataset_path, path.stat().st_mtime_ns)
-
-
-def _niche_tag_options(frame) -> list[str]:
-    tags: set[str] = set()
-    for value in frame.get("video_tags", []):
-        text = str(value or "").replace('"', "").replace("'", "")
-        for tag in re.split(r"[|,]", text.strip("[]")):
-            tag = re.sub(r"\s+", " ", tag).strip().lower()
-            if tag and tag not in {"nan", "none", "null"}:
-                tags.add(tag)
-    return sorted(tags)
-
-
-def _niche_date_bounds(frame):
-    dates = frame["publish_date"].dropna().astype(str)
-    if dates.empty:
-        return None, None
-    return dates.min(), dates.max()
-
-
 def render_niche_finder():
     st.title("Niche Finder")
-    st.caption("Busca automática de padrões, nichos e tags para orientar canais faceless.")
-    st.info("O Thunderbolt prepara e analisa automaticamente os dados necessários. Não é necessária configuração manual.")
+    st.caption("Busca de padrões, nichos e tags para orientar canais faceless.")
+    st.info("A instalação das dependências é automática. A operação não é: defina os parâmetros abaixo e clique em **Analisar Nichos** para iniciar.")
 
-    try:
-        with st.spinner("A preparar automaticamente o Niche Finder…"):
-            dataset_path, frame = _load_automatic_niche_dataset()
-    except (DatasetError, OSError) as exc:
-        st.error("Não foi possível preparar automaticamente o Niche Finder neste momento. Verifique a ligação à Internet e tente novamente.")
-        with st.expander("Detalhes técnicos"):
-            st.caption(str(exc))
-        return
-
-    signature = f"{dataset_path}:{Path(dataset_path).stat().st_mtime_ns}"
-    if st.session_state.get("niche_results_signature") != signature:
-        st.session_state.pop("niche_results", None)
-        st.session_state["niche_results_signature"] = signature
-
-    min_date, max_date = _niche_date_bounds(frame)
-    countries = ["Todos"] + sorted(str(value) for value in frame["country"].dropna().unique())
-    tag_options = _niche_tag_options(frame)
-    with st.sidebar:
+    default_start = date(2023, 9, 20)
+    default_end = date.today()
+    country_options = [
+        "Todos", "US", "BR", "GB", "CA", "AU", "DE", "FR", "ES", "IT", "JP", "KR", "IN", "MX", "AR", "PT",
+    ]
+    with st.container(border=True):
         st.subheader("Parâmetros da busca")
-        n_clusters = st.slider("Número de Clusters", 2, 10, 5, key="niche_n_clusters")
-        min_support = st.slider("Suporte Mínimo", 0.01, 0.5, 0.05, 0.01, format="%.2f", key="niche_min_support")
-        country = st.selectbox("País", countries, key="niche_country")
-        engagement = st.selectbox("Engagement", ["Todos", "High", "Moderate", "Low"], key="niche_engagement")
-        start_date = st.date_input("Data inicial", value=date.fromisoformat(min_date), min_value=date.fromisoformat(min_date), max_value=date.fromisoformat(max_date), key="niche_start_date") if min_date else None
-        end_date = st.date_input("Data final", value=date.fromisoformat(max_date), min_value=date.fromisoformat(min_date), max_value=date.fromisoformat(max_date), key="niche_end_date") if max_date else None
-        selected_tags = st.multiselect("Tags opcionais", tag_options, key="niche_tags")
-        analyse = st.button("Analisar Nichos", type="primary", use_container_width=True, key="niche_analyse")
-
+        st.caption("Estes controlos pertencem a esta aba. Nenhum dataset é descarregado e nenhuma análise é executada enquanto não clicar no botão.")
+        with st.form("niche_finder_parameters", clear_on_submit=False):
+            parameter_cols = st.columns(3)
+            with parameter_cols[0]:
+                n_clusters = st.slider("Número de Clusters", 2, 10, 5, key="niche_n_clusters")
+                min_support = st.slider("Suporte Mínimo", 0.01, 0.5, 0.05, 0.01, format="%.2f", key="niche_min_support")
+            with parameter_cols[1]:
+                country = st.selectbox("País", country_options, key="niche_country")
+                engagement = st.selectbox("Engagement", ["Todos", "High", "Moderate", "Low"], key="niche_engagement")
+            with parameter_cols[2]:
+                start_date = st.date_input("Data inicial", value=default_start, min_value=date(2020, 1, 1), max_value=default_end, key="niche_start_date")
+                end_date = st.date_input("Data final", value=default_end, min_value=date(2020, 1, 1), max_value=default_end, key="niche_end_date")
+            tags_text = st.text_input("Tags opcionais", key="niche_tags_text", placeholder="Ex.: history, facts, documentary")
+            analyse = st.form_submit_button("Analisar Nichos", type="primary", use_container_width=True)
+
+    current_parameters = {
+        "n_clusters": n_clusters,
+        "min_support": min_support,
+        "country": country,
+        "engagement": engagement,
+        "start_date": start_date.isoformat() if start_date else None,
+        "end_date": end_date.isoformat() if end_date else None,
+        "tags": [tag.strip() for tag in re.split(r"[,|]", tags_text) if tag.strip()],
+    }
     results = st.session_state.get("niche_results")
-    if results is None or analyse:
+    if analyse:
         try:
             if start_date and end_date and start_date > end_date:
                 raise NicheAnalysisError("A data inicial não pode ser posterior à data final.")
-            with st.spinner("A analisar nichos automaticamente…"):
+            with st.spinner("A preparar os dados apenas porque solicitou a análise…"):
+                dataset_path = _cached_niche_download()
+            with st.spinner("A executar a análise dos nichos…"):
                 results = run_niche_analysis(
                     str(dataset_path),
                     n_clusters=n_clusters,
@@ -711,15 +688,23 @@ def render_niche_finder():
                     end_date=end_date.isoformat() if end_date else None,
                     country=country,
                     engagement=engagement,
-                    tags=selected_tags,
+                    tags=current_parameters["tags"],
                 )
             st.session_state["niche_results"] = results
+            st.session_state["niche_last_parameters"] = current_parameters
+            st.success("Análise concluída.")
         except (NicheAnalysisError, DatasetError, OSError) as exc:
-            st.error("Não foi possível concluir a análise automática com os filtros actuais.")
+            st.error("Não foi possível concluir a análise solicitada com os parâmetros actuais.")
             with st.expander("Detalhes técnicos"):
                 st.caption(str(exc))
             return
 
+    if results is None:
+        st.caption("Ainda não existe uma análise nesta sessão. Ajuste os parâmetros e clique em **Analisar Nichos**.")
+        return
+    if st.session_state.get("niche_last_parameters") != current_parameters:
+        st.warning("Os resultados apresentados pertencem à última análise executada. Clique em **Analisar Nichos** para aplicar os parâmetros actuais.")
+
     summary = results.get("summary", {})
     metric_cols = st.columns(4)
     for col, (label, value) in zip(metric_cols, [("Registos analisados", summary.get("rows_filtered", 0)), ("Clusters", summary.get("cluster_count", 0)), ("Itemsets frequentes", summary.get("frequent_item_count", 0)), ("Regras de associação", summary.get("association_rule_count", 0))]):

package/app/modules/niche_finder/data_loader.py

@@ -103,7 +103,7 @@ def _download_with_kagglehub() -> Path | None:
 
 
 def download_kaggle_dataset() -> Path:
-    """Prepare and cache the public Niche-Finder dataset without user interaction."""
+    """Prepare and cache the public Niche-Finder dataset after an explicit user action."""
     ensure_data_dir()
     if _has_usable_cached_dataset():
         return DEFAULT_DATASET_PATH

package/package.json

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