@danhachuel/thunderbolt 0.2.28 → 0.2.29

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.28
+> **Versão deste manual:** 0.2.29
 > **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.28 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.29 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes @danhachuel/thunderbolt@0.2.28 install
+npx --yes @danhachuel/thunderbolt@0.2.29 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.
@@ -362,18 +362,29 @@ 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. **Pipeline > Criação de Vídeos:** teste primeiro o modo **Canal específico** e depois os modos de lote.
-6. **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.
-7. **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.
-8. **Pipeline > Limpador de Metadados:** suba um vídeo de terceiro, preencha título, preview, links, timestamps e tags, aplique a limpeza e descarregue a cópia limpa e o manifesto JSON. O original fica preservado e vídeos das páginas de criação não são aceites nesta área.
-9. **Configurações > Configurações Técnicas:** confirme que os caminhos e credenciais estão locais e não aparecem no Git.
-10. **Criação de Vídeos:** confirme que `Pexels/Pixabay` substitui o label antigo, que `Estilo IA` aparece apenas em `full_ia` e que `Apenas Música` exige áudio e guarda `background_mode=none`.
-11. **Automação:** no cartão de cada canal, escolha o **Blueprint padrão** e a **Voz padrão**, clique em `Guardar` e confirme que o resumo do cartão se actualiza. Configure também **Automação ON** e um horário `HH:MM`; confirme a lista de vídeos cadastrados. Os mesmos defaults aparecem em **Canais** e são usados em novas tarefas. A UI não inicia jobs em segundo plano nesta entrega.
-12. **Configurações > Configurações Técnicas > Teste de vozes:** teste Edge/Azure ou provider configurado e confirme reprodução/download sem criação de tarefa.
-13. **Upload directo:** configure manualmente cookies, sessionInfo e INNERTUBE_API_KEY, atribua o `DELEGATED_SESSION_ID` no canal e teste apenas com um vídeo de validação. O método envia chunks de 256 KiB e não extrai cookies do navegador.
-14. **Configurações > MCP > Client MCP:** confirme que Short Video Maker, AutoVio, OpenMontage e OpenCut aparecem com as portas padrão editáveis. O estado **Activo** é uma preferência local; a detecção deve indicar **Não detectado** quando os serviços externos não estiverem instalados ou iniciados.
-15. **Configurações > MCP > Servidor MCP:** abra a subaba, mantenha o host `127.0.0.1`, active **Servidor MCP ON** e clique em **Guardar e iniciar Servidor MCP**. Confirme o endpoint `/mcp` e o health endpoint `/health`. Mantenha **Permitir ferramentas de escrita** desactivado até precisar que um agente crie lotes.
-16. **Configurações > MCP > Skill:** clique em **Guardar skill localmente** e confirme o ficheiro em `storage/skills/moneyprinterturbo-video.md`; opcionalmente use **Descarregar skill .md** para obter a cópia através do navegador.
+5. **Niche Finder:** abra a página na sidebar, clique em **Baixar Dataset Kaggle** ou carregue um CSV próprio e confirme o ficheiro em `storage/data/niches/`. Com um CSV que contenha `title`, `publish_date`, `country`, `view_count`, `like_count` e `comment_count`, clique em **Usar CSV carregado**, escolha 3 clusters e suporte 0,05 e execute **Analisar Nichos**. Confirme as métricas, a tabela de clusters, o gráfico Plotly, as regras de associação e os dados filtrados. Altere país, engagement, datas e tags e confirme que a análise é recalculada.
+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.
+9. **Pipeline > Limpador de Metadados:** suba um vídeo de terceiro, preencha título, preview, links, timestamps e tags, aplique a limpeza e descarregue a cópia limpa e o manifesto JSON. O original fica preservado e vídeos das páginas de criação não são aceites nesta área.
+10. **Configurações > Configurações Técnicas:** confirme que os caminhos e credenciais estão locais e não aparecem no Git.
+11. **Criação de Vídeos:** confirme que `Pexels/Pixabay` substitui o label antigo, que `Estilo IA` aparece apenas em `full_ia` e que `Apenas Música` exige áudio e guarda `background_mode=none`.
+12. **Automação:** no cartão de cada canal, escolha o **Blueprint padrão** e a **Voz padrão**, clique em `Guardar` e confirme que o resumo do cartão se actualiza. Configure também **Automação ON** e um horário `HH:MM`; confirme a lista de vídeos cadastrados. Os mesmos defaults aparecem em **Canais** e são usados em novas tarefas. A UI não inicia jobs em segundo plano nesta entrega.
+13. **Configurações > Configurações Técnicas > Teste de vozes:** teste Edge/Azure ou provider configurado e confirme reprodução/download sem criação de tarefa.
+14. **Upload directo:** configure manualmente cookies, sessionInfo e INNERTUBE_API_KEY, atribua o `DELEGATED_SESSION_ID` no canal e teste apenas com um vídeo de validação. O método envia chunks de 256 KiB e não extrai cookies do navegador.
+15. **Configurações > MCP > Client MCP:** confirme que Short Video Maker, AutoVio, OpenMontage e OpenCut aparecem com as portas padrão editáveis. O estado **Activo** é uma preferência local; a detecção deve indicar **Não detectado** quando os serviços externos não estiverem instalados ou iniciados.
+16. **Configurações > MCP > Servidor MCP:** abra a subaba, mantenha o host `127.0.0.1`, active **Servidor MCP ON** e clique em **Guardar e iniciar Servidor MCP**. Confirme o endpoint `/mcp` e o health endpoint `/health`. Mantenha **Permitir ferramentas de escrita** desactivado até precisar que um agente crie lotes.
+17. **Configurações > MCP > Skill:** clique em **Guardar skill localmente** e confirme o ficheiro em `storage/skills/moneyprinterturbo-video.md`; opcionalmente use **Descarregar skill .md** para obter a cópia através do navegador.
+
+## Niche Finder
+
+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.
+
+O botão **Baixar Dataset Kaggle** guarda a cópia em `storage/data/niches/`. O carregador usa KaggleHub para obter o dataset público; não existem credenciais hardcoded. Também é possível carregar um CSV próprio e clicar em **Usar CSV carregado**. O esquema mínimo é `title`, `publish_date`, `country`, `view_count`, `like_count` e `comment_count`; `video_tags` é opcional para obter itemsets e regras de associação. A cache utiliza `st.cache_data` para evitar leituras repetidas do mesmo ficheiro.
+
+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. Os resultados são DataFrames de clusters, itemsets frequentes, regras de associação e dados filtrados; o gráfico de dispersão é criado nativamente com Plotly. A cache de dados e os CSVs locais são ignorados pelo Git.
+
+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.29 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,6 +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 e horário diário HH:MM; UI configurável sem worker em segundo plano |
+| Niche Finder | Dataset Kaggle ou CSV próprio, cache local, filtros, 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 |
@@ -25,9 +26,9 @@ 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.28
+## Navegação da UI 0.2.29
 
-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. Niche Finder permanece como placeholder vazio nesta versão.
+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.
 
 ## Instalação
 
@@ -108,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.28 install
-npx.cmd --yes @danhachuel/thunderbolt@0.2.28 doctor
-npx.cmd --yes @danhachuel/thunderbolt@0.2.28
+npx.cmd --yes @danhachuel/thunderbolt@0.2.29 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.29 doctor
+npx.cmd --yes @danhachuel/thunderbolt@0.2.29
 ```
 
 Como alternativa, pode permitir scripts para o seu utilizador:
@@ -128,6 +129,16 @@ Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
 Após `install`, o launcher usa o ambiente virtual instalado em `~/.thunderbolt/.venv` — no Windows, `%LOCALAPPDATA%\\THUNDERBOLT\\.venv` — e inicia a UI em `localhost:3030`. No Windows, a raiz é `%LOCALAPPDATA%\\THUNDERBOLT`; no computador indicado, o caminho será `C:\\Users\\danha\\AppData\\Local\\THUNDERBOLT`. Isto evita a redirecção de `HOME` que pode ocorrer no MobaXterm.
  O instalador não instala drivers de GPU, Docker, chaves de API, modelos Whisper ou credenciais de plataformas; esses componentes continuam dependentes do sistema e da configuração do utilizador. Para desenvolvimento a partir do clone, continue a usar `node scripts/cli.mjs`.
 
+## 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. A análise usa o dataset público [Trending Youtube Video Statistics (113 Countries)](https://www.kaggle.com/datasets/asaniczka/trending-youtube-videos-113-countries), mas também aceita um CSV próprio.
+
+Na sidebar da página, use **Baixar Dataset Kaggle** para descarregar e guardar o dataset em `storage/data/niches/`, ou carregue um CSV e clique em **Usar CSV carregado**. A cache é mantida localmente e o carregador valida as colunas mínimas `title`, `publish_date`, `country`, `view_count`, `like_count` e `comment_count`. Não são necessárias credenciais Kaggle hardcoded: o KaggleHub obtém o dataset público e guarda o resultado na cache local.
+
+O painel permite seleccionar 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. **Analisar Nichos** 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 filtrados, acompanhados por uma visualização Plotly nativa e pesquisa de palavras nos clusters. O download/cache dos dados é feito de forma lazy e os CSVs não são versionados pelo Git.
+
+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.29 install`; o instalador detecta e reutiliza componentes já válidos.
+
 ## Armazenamento local
 
 O sistema cria automaticamente:
@@ -146,6 +157,8 @@ storage/
 │   └── settings.json
 ├── music/             # músicas locais para o modo Apenas Música
 ├── voice_previews/    # amostras isoladas do teste de vozes
+├── data/
+│   └── niches/        # dataset Kaggle cacheado e CSVs enviados ao Niche Finder
 ├── skills/            # skill MoneyPrinterTurbo guardada pelo utilizador
 ├── metadata_cleaner/
 │   ├── originals/    # cópias dos vídeos terceiros enviados

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+## Niche-Finder
+
+Thunderbolt adapts the data-analysis ideas and parts of the clustering/tag-association logic from [johanfortus/Niche-Finder](https://github.com/johanfortus/Niche-Finder), Copyright (c) 2024 Johan Fortus and Vincent Milland. The original project is licensed under the MIT License. Thunderbolt does not include the original Flask server, HTML templates, JavaScript/D3 visualizations or route layer; the functionality was adapted to the existing Streamlit process.
+
+> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/app/main.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import re
+from datetime import date
 import sys
 from pathlib import Path
 
@@ -18,6 +19,8 @@ except (OSError, json.JSONDecodeError):
 
 from hermes_ui.domain import STAGES, create_batch, create_channel, create_tasks_for_batch, delete_channel, pipeline_summary, set_channel_defaults, transition_task, update_channel
 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, list_cached_datasets, load_dataframe, save_uploaded_csv
 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
@@ -626,9 +629,164 @@ 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():
+    return str(download_kaggle_dataset())
+
+
+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.info("Esta área está reservada para o Niche Finder e será implementada numa próxima etapa.")
+    st.caption("Busca de nichos baseada no projecto open source Niche-Finder, integrada no processo Streamlit do Thunderbolt.")
+    st.info("A análise é executada localmente, sem Flask ou segundo servidor. O dataset padrão é guardado em `storage/data/niches/` e pode ser substituído por um CSV próprio.")
+
+    with st.sidebar:
+        st.subheader("Fonte de dados")
+        uploaded_file = st.file_uploader("Carregar CSV próprio", type=["csv"], key="niche_uploaded_csv")
+        if st.button("Baixar Dataset Kaggle", use_container_width=True, key="niche_download_dataset"):
+            try:
+                downloaded = _cached_niche_download()
+                st.session_state["niche_dataset_path"] = downloaded
+                st.success("Dataset Kaggle guardado no storage local.")
+                st.rerun()
+            except DatasetError as exc:
+                st.error(str(exc))
+        cached = list_cached_datasets()
+        if cached:
+            labels = {str(path): path.relative_to(path.parents[2]).as_posix() if len(path.parents) > 2 else path.name for path in cached}
+            current_path = st.session_state.get("niche_dataset_path", str(cached[0]))
+            if current_path not in labels:
+                current_path = str(cached[0])
+            selected_path = st.selectbox("Dataset local", list(labels), index=list(labels).index(current_path), format_func=lambda item: labels[item], key="niche_dataset_selector")
+            if selected_path != st.session_state.get("niche_dataset_path"):
+                st.session_state["niche_dataset_path"] = selected_path
+                st.session_state.pop("niche_results", None)
+                st.rerun()
+        if uploaded_file is not None and st.button("Usar CSV carregado", use_container_width=True, key="niche_use_uploaded"):
+            try:
+                uploaded_path = save_uploaded_csv(uploaded_file.getvalue(), uploaded_file.name)
+                st.session_state["niche_dataset_path"] = str(uploaded_path)
+                st.session_state.pop("niche_results", None)
+                st.success(f"CSV guardado em `{uploaded_path}`.")
+                st.rerun()
+            except DatasetError as exc:
+                st.error(str(exc))
+
+    dataset_path = st.session_state.get("niche_dataset_path")
+    frame = None
+    if dataset_path:
+        path = Path(dataset_path)
+        if path.exists():
+            try:
+                frame = _cached_niche_dataset(str(path), path.stat().st_mtime_ns)
+            except (DatasetError, OSError) as exc:
+                st.error(str(exc))
+        else:
+            st.warning("O dataset seleccionado já não existe no storage local. Baixe-o novamente ou carregue um CSV.")
+    if frame is None:
+        st.subheader("Começar uma análise")
+        st.write("Baixe o dataset público do Kaggle ou carregue um CSV com as colunas `title`, `publish_date`, `country`, `view_count`, `like_count` e `comment_count`.")
+        return
+
+    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:
+        st.subheader("Parâmetros")
+        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")
+
+    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 clusters e associações…"):
+                results = run_niche_analysis(
+                    str(dataset_path),
+                    n_clusters=n_clusters,
+                    min_support=min_support,
+                    start_date=start_date.isoformat() if start_date else None,
+                    end_date=end_date.isoformat() if end_date else None,
+                    country=country,
+                    engagement=engagement,
+                    tags=selected_tags,
+                )
+            st.session_state["niche_results"] = results
+        except (NicheAnalysisError, DatasetError, OSError) as exc:
+            st.error(str(exc))
+
+    results = st.session_state.get("niche_results")
+    if not results:
+        st.subheader("Dataset carregado")
+        st.dataframe(frame.head(100), use_container_width=True, hide_index=True)
+        st.caption(f"{len(frame):,} registos válidos carregados. Ajuste os parâmetros na barra lateral e clique em Analisar Nichos.")
+        return
+
+    summary = results.get("summary", {})
+    metric_cols = st.columns(4)
+    for col, (label, value) in zip(metric_cols, [("Registos filtrados", summary.get("rows_filtered", 0)), ("Clusters", summary.get("cluster_count", 0)), ("Itemsets frequentes", summary.get("frequent_item_count", 0)), ("Regras", summary.get("association_rule_count", 0))]):
+        with col:
+            card(label, value)
+
+    cluster_table = results["clusters"]
+    rules_table = results["association_rules"]
+    items_table = results["frequent_items"]
+    points = results["cluster_points"].copy()
+    keyword = st.text_input("Filtrar palavras-chave nos clusters", key="niche_cluster_keyword", placeholder="Ex.: música, gaming, receitas")
+    if keyword.strip():
+        cluster_table = cluster_table[cluster_table["palavras"].str.contains(keyword.strip(), case=False, na=False)]
+    tab_clusters, tab_rules, tab_data = st.tabs(["Clusters encontrados", "Regras de associação", "Dados filtrados"])
+    with tab_clusters:
+        st.dataframe(cluster_table, use_container_width=True, hide_index=True)
+        if not points.empty:
+            try:
+                import plotly.express as px
+                points["cluster"] = points["cluster_id"].astype(str)
+                hover = [column for column in ["title", "channel_name", "country", "view_count", "engagement_rate"] if column in points.columns]
+                figure = px.scatter(points, x="x", y="y", color="cluster", hover_data=hover, title="Distribuição dos clusters")
+                figure.update_layout(legend_title_text="Cluster")
+                st.plotly_chart(figure, use_container_width=True)
+            except ImportError:
+                st.warning("A visualização Plotly não está instalada. Execute a instalação incremental do Thunderbolt.")
+    with tab_rules:
+        if rules_table.empty:
+            st.info("Não foram encontradas regras com o suporte e lift actuais. Reduza o suporte mínimo ou escolha outro filtro.")
+        else:
+            st.dataframe(rules_table, use_container_width=True, hide_index=True)
+        if not items_table.empty:
+            st.subheader("Itemsets frequentes")
+            st.dataframe(items_table, use_container_width=True, hide_index=True)
+    with tab_data:
+        st.dataframe(results["raw_data"], use_container_width=True, hide_index=True)
+
 
 
 def render_videos():

package/app/modules/__init__.py

@@ -0,0 +1 @@
+"""Reusable Streamlit modules bundled with Thunderbolt."""

package/app/modules/niche_finder/__init__.py

@@ -0,0 +1,14 @@
+"""Streamlit-native Niche Finder integration for Thunderbolt."""
+
+from .core import NicheAnalysisError, run_niche_analysis
+from .data_loader import DATA_DIR, DatasetError, download_kaggle_dataset, list_cached_datasets, save_uploaded_csv
+
+__all__ = [
+    "DATA_DIR",
+    "DatasetError",
+    "NicheAnalysisError",
+    "download_kaggle_dataset",
+    "list_cached_datasets",
+    "run_niche_analysis",
+    "save_uploaded_csv",
+]

package/app/modules/niche_finder/core.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+import ast
+import json
+import re
+from collections import Counter
+from typing import Any, Iterable
+
+import numpy as np
+import pandas as pd
+
+from .data_loader import DatasetError, download_kaggle_dataset, load_dataframe
+from .models import NicheAnalysisResult
+
+
+EMPTY_CLUSTER_COLUMNS = [
+    "cluster_id",
+    "palavras",
+    "tamanho",
+    "media_visualizacoes",
+    "media_engagement",
+]
+EMPTY_ITEM_COLUMNS = ["itemsets", "support", "item_count"]
+EMPTY_RULE_COLUMNS = ["antecedents", "consequents", "support", "confidence", "lift"]
+
+
+class NicheAnalysisError(ValueError):
+    """Raised when a valid dataset cannot produce a meaningful analysis."""
+
+
+def _parse_tags(value: Any) -> list[str]:
+    if value is None or (isinstance(value, float) and np.isnan(value)):
+        return []
+    if isinstance(value, (list, tuple, set)):
+        raw_items = value
+    else:
+        text = str(value).strip()
+        if not text or text.lower() in {"nan", "none", "null", "[]"}:
+            return []
+        raw_items: Iterable[Any]
+        if text.startswith("[") and text.endswith("]"):
+            try:
+                parsed = json.loads(text)
+            except json.JSONDecodeError:
+                try:
+                    parsed = ast.literal_eval(text)
+                except (ValueError, SyntaxError):
+                    parsed = None
+            raw_items = parsed if isinstance(parsed, (list, tuple, set)) else re.split(r"[|,]", text.strip("[]"))
+        else:
+            raw_items = re.split(r"[|,]", text)
+    tags: list[str] = []
+    for item in raw_items:
+        tag = re.sub(r"\s+", " ", str(item).replace('"', "").replace("'", "")).strip().lower()
+        if tag and tag not in {"nan", "none", "null"}:
+            tags.append(tag)
+    return list(dict.fromkeys(tags))
+
+
+def _engagement_label(value: str | int | None) -> str:
+    if value is None or str(value).strip().lower() in {"", "todos", "all"}:
+        return "Todos"
+    if isinstance(value, str) and value in {"High", "Moderate", "Low"}:
+        return value
+    try:
+        numeric = int(value)
+    except (TypeError, ValueError):
+        return "Todos"
+    if numeric >= 67:
+        return "High"
+    if numeric >= 33:
+        return "Moderate"
+    return "Low"
+
+
+def _filter_frame(
+    frame: pd.DataFrame,
+    *,
+    start_date: str | None,
+    end_date: str | None,
+    country: str | None,
+    engagement: str | int | None,
+    tags: Iterable[str] | None,
+) -> pd.DataFrame:
+    filtered = frame.copy()
+    if start_date:
+        filtered = filtered[filtered["publish_date"] >= str(start_date)]
+    if end_date:
+        filtered = filtered[filtered["publish_date"] <= str(end_date)]
+    if country and str(country).strip().lower() not in {"", "todos", "all"}:
+        filtered = filtered[filtered["country"].str.casefold() == str(country).strip().casefold()]
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        filtered["engagement_rate"] = np.where(
+            filtered["view_count"] > 0,
+            ((filtered["like_count"] + filtered["comment_count"]) / filtered["view_count"]) * 100,
+            0.0,
+        )
+    filtered["engagement_rate"] = filtered["engagement_rate"].replace([np.inf, -np.inf], np.nan).fillna(0.0)
+    label = _engagement_label(engagement)
+    if label == "High":
+        filtered = filtered[filtered["engagement_rate"] >= 7]
+    elif label == "Moderate":
+        filtered = filtered[(filtered["engagement_rate"] >= 3) & (filtered["engagement_rate"] < 7)]
+    elif label == "Low":
+        filtered = filtered[filtered["engagement_rate"] < 3]
+
+    selected_tags = {str(tag).strip().casefold() for tag in (tags or []) if str(tag).strip()}
+    if selected_tags:
+        filtered = filtered[filtered["video_tags"].map(lambda value: bool(selected_tags.intersection(_parse_tags(value))))]
+    return filtered.drop_duplicates(subset="title", keep="first").reset_index(drop=True)
+
+
+def _empty_frame(columns: list[str]) -> pd.DataFrame:
+    return pd.DataFrame(columns=columns)
+
+
+def _cluster_analysis(frame: pd.DataFrame, requested_clusters: int) -> tuple[pd.DataFrame, pd.DataFrame]:
+    if frame.empty:
+        return _empty_frame(EMPTY_CLUSTER_COLUMNS), pd.DataFrame()
+    from sklearn.cluster import KMeans
+    from sklearn.decomposition import PCA
+    from sklearn.preprocessing import StandardScaler
+
+    features = frame[["view_count", "like_count"]].clip(lower=0).astype(float)
+    transformed = np.log1p(features)
+    scaled = StandardScaler().fit_transform(transformed)
+    n_clusters = max(1, min(int(requested_clusters), len(frame)))
+    if n_clusters == 1:
+        labels = np.zeros(len(frame), dtype=int)
+    else:
+        labels = KMeans(n_clusters=n_clusters, random_state=42, n_init=10).fit_predict(scaled)
+    points = frame.copy()
+    points["cluster_id"] = labels.astype(int)
+    if len(points) >= 2:
+        coordinates = PCA(n_components=2, random_state=42).fit_transform(scaled)
+    else:
+        coordinates = np.column_stack([scaled[:, 0], np.zeros(len(points))])
+    points["x"] = coordinates[:, 0]
+    points["y"] = coordinates[:, 1]
+
+    summaries: list[dict[str, Any]] = []
+    for cluster_id, group in points.groupby("cluster_id", sort=True):
+        counter = Counter(tag for value in group["video_tags"] for tag in _parse_tags(value))
+        words = ", ".join(tag for tag, _ in counter.most_common(8))
+        summaries.append(
+            {
+                "cluster_id": int(cluster_id),
+                "palavras": words,
+                "tamanho": int(len(group)),
+                "media_visualizacoes": round(float(group["view_count"].mean()), 2),
+                "media_engagement": round(float(group["engagement_rate"].mean()), 2),
+            }
+        )
+    return pd.DataFrame(summaries, columns=EMPTY_CLUSTER_COLUMNS), points
+
+
+def _frequent_item_analysis(frame: pd.DataFrame, min_support: float) -> tuple[pd.DataFrame, pd.DataFrame]:
+    if frame.empty:
+        return _empty_frame(EMPTY_ITEM_COLUMNS), _empty_frame(EMPTY_RULE_COLUMNS)
+    from mlxtend.frequent_patterns import association_rules, fpgrowth
+
+    tag_lists = frame["video_tags"].map(_parse_tags)
+    tag_counts = Counter(tag for tags in tag_lists for tag in tags)
+    if not tag_counts:
+        return _empty_frame(EMPTY_ITEM_COLUMNS), _empty_frame(EMPTY_RULE_COLUMNS)
+    frequent_tags = {tag for tag, count in tag_counts.items() if count > len(frame) * 0.5}
+    tag_lists = tag_lists.map(lambda tags: [tag for tag in tags if tag not in frequent_tags])
+    all_tags = sorted({tag for tags in tag_lists for tag in tags})
+    if not all_tags:
+        return _empty_frame(EMPTY_ITEM_COLUMNS), _empty_frame(EMPTY_RULE_COLUMNS)
+    matrix = pd.DataFrame(
+        [{tag: tag in tags for tag in all_tags} for tags in tag_lists],
+        columns=all_tags,
+    ).astype(bool)
+    itemsets = fpgrowth(matrix, min_support=float(min_support), use_colnames=True, max_len=3)
+    if itemsets.empty:
+        return _empty_frame(EMPTY_ITEM_COLUMNS), _empty_frame(EMPTY_RULE_COLUMNS)
+    itemsets = itemsets.copy()
+    itemsets["item_count"] = itemsets["itemsets"].map(len)
+    itemsets["itemsets"] = itemsets["itemsets"].map(lambda values: ", ".join(sorted(values)))
+    itemsets = itemsets[["itemsets", "support", "item_count"]].sort_values(["support", "item_count"], ascending=[False, True]).reset_index(drop=True)
+
+    raw_itemsets = fpgrowth(matrix, min_support=float(min_support), use_colnames=True, max_len=3)
+    try:
+        rules = association_rules(raw_itemsets, metric="confidence", min_threshold=0.5)
+    except TypeError:  # mlxtend compatibility across versions
+        rules = association_rules(raw_itemsets, num_itemsets=len(matrix), metric="confidence", min_threshold=0.5)
+    if rules.empty:
+        return itemsets, _empty_frame(EMPTY_RULE_COLUMNS)
+    rules = rules[rules["lift"] > 1.0].copy()
+    if rules.empty:
+        return itemsets, _empty_frame(EMPTY_RULE_COLUMNS)
+    for column in ("antecedents", "consequents"):
+        rules[column] = rules[column].map(lambda values: ", ".join(sorted(values)))
+    wanted = [column for column in EMPTY_RULE_COLUMNS if column in rules.columns]
+    rules = rules[wanted].sort_values(["lift", "confidence"], ascending=False).reset_index(drop=True)
+    return itemsets, rules
+
+
+def run_niche_analysis(
+    dataset_path: str | None = None,
+    n_clusters: int = 5,
+    min_support: float = 0.01,
+    *,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    country: str | None = None,
+    engagement: str | int | None = None,
+    tags: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Run the adapted Niche-Finder analysis synchronously in the caller process.
+
+    The first three parameters preserve the integration contract described in
+    ``exemplo.md``. Additional keyword-only filters retain the original project's
+    date, country, engagement and tag controls for the Thunderbolt UI.
+    """
+    if not 2 <= int(n_clusters) <= 10:
+        raise NicheAnalysisError("O número de clusters deve estar entre 2 e 10.")
+    if not 0.001 <= float(min_support) <= 0.5:
+        raise NicheAnalysisError("O suporte mínimo deve estar entre 0,001 e 0,5.")
+    path = download_kaggle_dataset() if dataset_path is None else dataset_path
+    try:
+        frame = load_dataframe(path)
+    except DatasetError as exc:
+        raise NicheAnalysisError(str(exc)) from exc
+    filtered = _filter_frame(
+        frame,
+        start_date=start_date,
+        end_date=end_date,
+        country=country,
+        engagement=engagement,
+        tags=tags,
+    )
+    if filtered.empty:
+        raise NicheAnalysisError("Nenhum vídeo corresponde aos filtros seleccionados.")
+    clusters, points = _cluster_analysis(filtered, int(n_clusters))
+    frequent_items, rules = _frequent_item_analysis(filtered, float(min_support))
+    result = NicheAnalysisResult(
+        clusters=clusters,
+        frequent_items=frequent_items,
+        association_rules=rules,
+        raw_data=filtered,
+        cluster_points=points,
+        summary={
+            "rows_input": int(len(frame)),
+            "rows_filtered": int(len(filtered)),
+            "cluster_count": int(len(clusters)),
+            "frequent_item_count": int(len(frequent_items)),
+            "association_rule_count": int(len(rules)),
+            "top_tags": [str(value) for value in frequent_items["itemsets"].head(10).tolist()] if not frequent_items.empty else [],
+        },
+    )
+    return result.as_dict()

package/app/modules/niche_finder/data_loader.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import io
+import re
+import shutil
+from pathlib import Path
+from typing import BinaryIO
+
+import pandas as pd
+
+from hermes_ui.storage import STORAGE
+
+try:
+    import kagglehub
+except ImportError:  # pragma: no cover - exercised in installations before the extra dependency is installed
+    kagglehub = None
+
+
+DATA_DIR = STORAGE / "data" / "niches"
+DEFAULT_DATASET_SLUG = "asaniczka/trending-youtube-videos-113-countries"
+DEFAULT_DATASET_FILENAME = "trending_yt_videos_113_countries.csv"
+DEFAULT_DATASET_PATH = DATA_DIR / DEFAULT_DATASET_FILENAME
+
+REQUIRED_COLUMNS = (
+    "title",
+    "publish_date",
+    "country",
+    "view_count",
+    "like_count",
+    "comment_count",
+)
+OPTIONAL_COLUMNS = (
+    "video_tags",
+    "channel_name",
+    "thumbnail_url",
+    "video_id",
+    "channel_id",
+)
+
+
+class DatasetError(RuntimeError):
+    """Raised when a Niche Finder dataset cannot be read or validated."""
+
+
+def ensure_data_dir() -> Path:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    (DATA_DIR / "uploads").mkdir(parents=True, exist_ok=True)
+    return DATA_DIR
+
+
+def _safe_filename(name: str) -> str:
+    stem = re.sub(r"[^A-Za-z0-9._-]+", "-", Path(name or "dataset.csv").name).strip(".-")
+    if not stem:
+        stem = "dataset.csv"
+    if not stem.lower().endswith(".csv"):
+        stem += ".csv"
+    return stem
+
+
+def _find_csv(root: Path) -> Path | None:
+    candidates = sorted(root.rglob("*.csv"))
+    if not candidates:
+        return None
+    for candidate in candidates:
+        if candidate.name.lower() == DEFAULT_DATASET_FILENAME.lower():
+            return candidate
+    return candidates[0]
+
+
+def _copy_csv(source: Path, destination: Path) -> Path:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    if source.resolve() != destination.resolve():
+        shutil.copy2(source, destination)
+    return destination
+
+
+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 KaggleHub não conseguiu descarregar o dataset: {exc}") from exc
+    source = _find_csv(Path(downloaded))
+    if source is None:
+        raise DatasetError("O download KaggleHub terminou sem encontrar um ficheiro CSV.")
+    return _copy_csv(source, DEFAULT_DATASET_PATH)
+
+
+def download_kaggle_dataset() -> Path:
+    """Download and cache the public Niche-Finder dataset in Thunderbolt storage."""
+    ensure_data_dir()
+    if DEFAULT_DATASET_PATH.exists() and DEFAULT_DATASET_PATH.stat().st_size > 0:
+        return DEFAULT_DATASET_PATH
+    if kagglehub is None:
+        raise DatasetError("A dependência kagglehub não está instalada. Execute novamente a instalação do Thunderbolt.")
+    downloaded = _download_with_kagglehub()
+    if downloaded is None:
+        raise DatasetError("O KaggleHub não devolveu um caminho de dataset válido.")
+    return downloaded
+
+
+def save_uploaded_csv(payload: bytes | BinaryIO, filename: str) -> Path:
+    """Validate and persist an uploaded CSV under the user's local data directory."""
+    ensure_data_dir()
+    raw = payload.read() if hasattr(payload, "read") else payload
+    if not isinstance(raw, (bytes, bytearray)) or not raw:
+        raise DatasetError("O ficheiro CSV enviado está vazio.")
+    try:
+        frame = pd.read_csv(io.BytesIO(raw))
+        validate_dataset(frame)
+    except (OSError, UnicodeDecodeError, pd.errors.ParserError, pd.errors.EmptyDataError) as exc:
+        raise DatasetError(f"Não foi possível ler o CSV enviado: {exc}") from exc
+    destination = DATA_DIR / "uploads" / _safe_filename(filename)
+    destination.write_bytes(raw)
+    return destination
+
+
+def validate_dataset(frame: pd.DataFrame) -> pd.DataFrame:
+    """Validate the minimal schema and return a normalised copy."""
+    if frame is None or frame.empty:
+        raise DatasetError("O dataset não contém linhas.")
+    cleaned = frame.copy()
+    cleaned.columns = [str(column).strip() for column in cleaned.columns]
+    missing = [column for column in REQUIRED_COLUMNS if column not in cleaned.columns]
+    if missing:
+        raise DatasetError("O CSV precisa das colunas: " + ", ".join(missing) + ".")
+    if "video_tags" not in cleaned.columns:
+        cleaned["video_tags"] = ""
+    for column in ("view_count", "like_count", "comment_count"):
+        cleaned[column] = pd.to_numeric(cleaned[column], errors="coerce")
+    cleaned["publish_date"] = pd.to_datetime(cleaned["publish_date"], errors="coerce").dt.strftime("%Y-%m-%d")
+    cleaned["country"] = cleaned["country"].astype("string").str.strip()
+    cleaned["title"] = cleaned["title"].astype("string").fillna("").str.strip()
+    cleaned = cleaned.dropna(subset=["publish_date", "view_count", "like_count", "comment_count"])
+    cleaned = cleaned[cleaned["title"] != ""].copy()
+    if cleaned.empty:
+        raise DatasetError("O dataset não contém linhas válidas depois da normalização.")
+    return cleaned.reset_index(drop=True)
+
+
+def load_dataframe(path: str | Path) -> pd.DataFrame:
+    try:
+        frame = pd.read_csv(path)
+    except (OSError, UnicodeDecodeError, pd.errors.ParserError, pd.errors.EmptyDataError) as exc:
+        raise DatasetError(f"Não foi possível ler o dataset: {exc}") from exc
+    return validate_dataset(frame)
+
+
+def list_cached_datasets() -> list[Path]:
+    ensure_data_dir()
+    return sorted(DATA_DIR.glob("**/*.csv"))

package/app/modules/niche_finder/models.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class DatasetInfo:
+    """Metadata about a cached or uploaded Niche Finder dataset."""
+
+    path: Path
+    source: str
+    rows: int
+    columns: tuple[str, ...]
+
+
+@dataclass
+class NicheAnalysisResult:
+    """Structured result returned by ``run_niche_analysis``.
+
+    The dictionaries are intentionally DataFrame-based so the Streamlit renderer
+    can display, filter and export each result without depending on Flask or HTML.
+    """
+
+    clusters: pd.DataFrame
+    frequent_items: pd.DataFrame
+    association_rules: pd.DataFrame
+    raw_data: pd.DataFrame
+    cluster_points: pd.DataFrame
+    summary: dict[str, Any]
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "clusters": self.clusters,
+            "frequent_items": self.frequent_items,
+            "association_rules": self.association_rules,
+            "raw_data": self.raw_data,
+            "cluster_points": self.cluster_points,
+            "summary": self.summary,
+        }

package/hermes_ui/storage.py

@@ -12,6 +12,7 @@ ROOT = Path(__file__).resolve().parents[1]
 STORAGE = Path(os.getenv("THUNDERBOLT_STORAGE_DIR") or ROOT / "storage")
 STATE = STORAGE / "state"
 BLUEPRINTS = STORAGE / "blueprints"
+NICHES_DATA = STORAGE / "data" / "niches"
 SEED_BLUEPRINTS = ROOT / "seed" / "blueprints"
 
 DEFAULTS: dict[str, Any] = {
@@ -218,7 +219,7 @@ def seed_blueprints() -> None:
 
 
 def ensure_storage() -> None:
-    for path in [STATE, BLUEPRINTS / "canais", BLUEPRINTS / "nichos", BLUEPRINTS / "importados", BLUEPRINTS / "brandings", STORAGE / "brand", STORAGE / "scripts", STORAGE / "thumbnails", STORAGE / "videos", STORAGE / "artifacts", STORAGE / "skills", STORAGE / "metadata_cleaner", STORAGE / "metadata_cleaner" / "outputs", STORAGE / "music", STORAGE / "voice_previews"]:
+    for path in [STATE, BLUEPRINTS / "canais", BLUEPRINTS / "nichos", BLUEPRINTS / "importados", BLUEPRINTS / "brandings", STORAGE / "brand", STORAGE / "scripts", STORAGE / "thumbnails", STORAGE / "videos", STORAGE / "artifacts", STORAGE / "skills", STORAGE / "metadata_cleaner", STORAGE / "metadata_cleaner" / "outputs", STORAGE / "music", STORAGE / "voice_previews", NICHES_DATA, NICHES_DATA / "uploads"]:
         path.mkdir(parents=True, exist_ok=True)
     seed_blueprints()
     for filename, default in DEFAULTS.items():

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.2.28",
+  "version": "0.2.29",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "main": "scripts/cli.mjs",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "files": [
     "app/main.py",
+    "app/modules/**/*.py",
     "hermes_ui/*.py",
     "integrations/*.py",
     "integrations/data/*.json",
@@ -18,6 +19,7 @@
     "seed/skills/*.md",
     "README.md",
     "MANUAL-INSTALACAO.md",
+    "THIRD-PARTY-NOTICES.md",
     "requirements.txt",
     "package.json"
   ],

package/requirements.txt

@@ -7,3 +7,9 @@ google-auth>=2.29,<3
 google-auth-oauthlib>=1.2,<2
 google-api-python-client>=2.120,<3
 edge-tts>=7.0,<8
+scikit-learn>=1.3,<2
+mlxtend>=0.23,<1
+plotly>=5.18,<7
+seaborn>=0.13,<1
+matplotlib>=3.7,<4
+kagglehub>=0.3,<1

package/scripts/cli.mjs

@@ -79,6 +79,9 @@ function ensureRuntimeStorage() {
     join(storageRoot, "skills"),
     join(storageRoot, "music"),
     join(storageRoot, "voice_previews"),
+    join(storageRoot, "data"),
+    join(storageRoot, "data", "niches"),
+    join(storageRoot, "data", "niches", "uploads"),
   ];
   for (const directory of directories) mkdirSync(directory, { recursive: true });
   const seedRoot = resolve(root, "seed", "blueprints");
@@ -98,7 +101,7 @@ function check() {
     console.error(`Python não encontrado. Execute: npx.cmd --yes @danhachuel/thunderbolt install`);
     process.exit(1);
   }
-  const requiredModules = ["streamlit", "requests", "pandas", "toml", "imageio_ffmpeg", "edge_tts"];
+  const requiredModules = ["streamlit", "requests", "pandas", "toml", "imageio_ffmpeg", "edge_tts", "sklearn", "mlxtend", "plotly", "seaborn", "kagglehub"];
   const missing = requiredModules.filter((moduleName) => !moduleAvailable(moduleName));
   const ffmpeg = moduleAvailable("imageio_ffmpeg");
   const mptPath = configuredMoneyPrinterPath();

package/scripts/install.mjs

@@ -110,6 +110,9 @@ function ensureDirs() {
     join(storageRoot, "skills"),
     join(storageRoot, "music"),
     join(storageRoot, "voice_previews"),
+    join(storageRoot, "data"),
+    join(storageRoot, "data", "niches"),
+    join(storageRoot, "data", "niches", "uploads"),
   ];
   for (const directory of directories) mkdirSync(directory, { recursive: true });
   copySeedBlueprints(storageRoot);