@danhachuel/thunderbolt 0.2.27 → 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.27
+> **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.27 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.29 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes @danhachuel/thunderbolt@0.2.27 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.
@@ -339,7 +339,7 @@ Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
 
 ## 8. Configuração inicial da UI
 
-Na primeira execução, abra **Configurações** e reveja. Para YouTube, preencha primeiro o par **OAuth Client ID + OAuth Client Secret** se pretende autorizar uploads. A **YouTube Data API Key** é uma credencial Google Cloud diferente e fica numa área opcional, apenas para o método oficial de métricas; Client ID + Client Secret não formam uma API Key.
+Na primeira execução, a barra lateral apresenta **Início**, **Pipeline**, **Automação**, **Niche Finder** e **Configurações**. Abra **Configurações > Configurações Técnicas** e reveja. O menu **Pipeline** contém **Criação de Vídeos**, **Criação de Músicas**, **Upload** e **Limpador de Metadados**. O menu **Configurações** contém **Canais**, **Blueprints**, **MCP** e **Configurações Técnicas**. Para YouTube, preencha primeiro o par **OAuth Client ID + OAuth Client Secret** se pretende autorizar uploads. A **YouTube Data API Key** é uma credencial Google Cloud diferente e fica numa área opcional, apenas para o método oficial de métricas; Client ID + Client Secret não formam uma API Key.
 
 | Configuração | Finalidade |
 |---|---|
@@ -358,30 +358,41 @@ As credenciais devem ser inseridas apenas na configuração local. A Data API Ke
 
 Após iniciar a aplicação, valide o seguinte percurso:
 
-1. **Dashboard:** confirme que a UI abre e mostra o estado local.
+1. **Início:** confirme que a UI abre, mostra o estado local, as métricas e os cards das filas do Pipeline, sem botões de acções rápidas.
 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. **Novo vídeo:** teste primeiro o modo **Canal específico** e depois os modos de lote.
-6. **Novo vídeo > Vídeos:** verifique o estado `to_do` e os botões **Iniciar** e **Parar** dentro da subaba.
-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. **Limpador de metadado:** 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 da aba Novo vídeo não são aceites nesta área.
-9. **Configurações:** confirme que os caminhos e credenciais estão locais e não aparecem no Git.
-10. **Novo vídeo:** 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. **Teste de vozes:** em Configurações, 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. **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. **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. **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.
-
-## Novo vídeo, Automação e música
+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
 
 O modo `Pexels/Pixabay` representa materiais de stock. Ao seleccionar `full_ia`, o selector `Estilo IA` apresenta os 12 estilos disponíveis. Ao seleccionar `Apenas Música`, a UI obriga a escolher uma música existente, carregar um ficheiro ou solicitar uma música a um endpoint Suno configurado. O vídeo recebe `background_mode=none`, sem fundo Pexels/Pixabay ou IA.
 
 A aba **Automação** lista os canais e vídeos, permite escolher e guardar **Blueprint padrão** e **Voz padrão** por canal, guarda **Automação ON** e valida horários diários no formato `HH:MM`. Os valores ficam sincronizados com o editor existente no cartão da aba **Canais** e são copiados para novas tarefas. É apenas uma camada de UI nesta versão, sem execução de worker.
 
-A área **Teste de vozes**, dentro de Configurações, é isolada da pipeline. O preview pode ser reproduzido e descarregado de `storage/voice_previews/`. Caminhos vazios, directórios, ficheiros vazios e previews sem permissões de leitura são ignorados com uma mensagem clara, sem traceback. Se uma instalação antiga mostrar que `edge-tts` está em falta, execute `npx.cmd --yes @danhachuel/thunderbolt install`; o detector reinstala apenas a dependência ausente.
+A área **Teste de vozes**, dentro de **Configurações > Configurações Técnicas**, é isolada da pipeline. O preview pode ser reproduzido e descarregado de `storage/voice_previews/`. Caminhos vazios, directórios, ficheiros vazios e previews sem permissões de leitura são ignorados com uma mensagem clara, sem traceback. Se uma instalação antiga mostrar que `edge-tts` está em falta, execute `npx.cmd --yes @danhachuel/thunderbolt install`; o detector reinstala apenas a dependência ausente.
 
 ## Upload directo
 
@@ -389,19 +400,19 @@ A subaba **Upload directo** adapta o [YouTube-Video-Upload-Frontend-Api](https:/
 
 ## MCP e integrações externas
 
-A subaba **Client MCP** é um configurador local de quatro serviços opcionais. As portas iniciais são `3123` para Short Video Maker, `3001` para AutoVio, `8000` como referência editável para OpenMontage e `8787` para a API do OpenCut. A página consulta apenas `http://127.0.0.1:<porta>/` com timeout curto; não clona, instala ou inicia processos externos.
+A subaba **Client MCP**, em **Configurações > MCP**, é um configurador local de quatro serviços opcionais. As portas iniciais são `3123` para Short Video Maker, `3001` para AutoVio, `8000` como referência editável para OpenMontage e `8787` para a API do OpenCut. A página consulta apenas `http://127.0.0.1:<porta>/` com timeout curto; não clona, instala ou inicia processos externos.
 
-A subaba **Servidor MCP** disponibiliza, após activação explícita, `http://127.0.0.1:3031/mcp` por JSON-RPC sobre HTTP POST. Para configurar um agente compatível, use esse URL como endpoint MCP. Se o host for alterado para uma interface externa, preencha primeiro um token e trate-o como segredo. O servidor disponibiliza ferramentas de leitura por padrão; a criação de lotes só é exposta quando **Permitir ferramentas de escrita** está activado.
+A subaba **Servidor MCP**, em **Configurações > MCP**, disponibiliza, após activação explícita, `http://127.0.0.1:3031/mcp` por JSON-RPC sobre HTTP POST. Para configurar um agente compatível, use esse URL como endpoint MCP. Se o host for alterado para uma interface externa, preencha primeiro um token e trate-o como segredo. O servidor disponibiliza ferramentas de leitura por padrão; a criação de lotes só é exposta quando **Permitir ferramentas de escrita** está activado.
 
-A subaba **Skill** contém as acções para guardar a skill anexada em `storage/skills/` ou descarregá-la como Markdown. Esta pasta fica fora dos estados JSON e é criada pelo instalador e pelo launcher. Os quatro repositórios continuam fora do pacote npm.
+A subaba **Skill**, em **Configurações > MCP**, contém as acções para guardar a skill anexada em `storage/skills/` ou descarregá-la como Markdown. Esta pasta fica fora dos estados JSON e é criada pelo instalador e pelo launcher. Os quatro repositórios continuam fora do pacote npm.
 
-## 12. Limpador de metadado
+## 12. Limpador de Metadados
 
-A aba **Limpador de metadado** recebe somente vídeos externos já prontos. O ficheiro enviado é copiado para `storage/metadata_cleaner/originals/`; a aplicação não altera o original. Ao aplicar a operação, o FFmpeg remove os metadados existentes do contentor e cria uma nova versão em `storage/metadata_cleaner/outputs/` com o título, descrição, tags, idioma e outros campos preenchidos.
+A aba **Limpador de Metadados** recebe somente vídeos externos já prontos. O ficheiro enviado é copiado para `storage/metadata_cleaner/originals/`; a aplicação não altera o original. Ao aplicar a operação, o FFmpeg remove os metadados existentes do contentor e cria uma nova versão em `storage/metadata_cleaner/outputs/` com o título, descrição, tags, idioma e outros campos preenchidos.
 
 A descrição combina **Preview**, **Links** e **Timestamps**, seguindo a estrutura do workflow `YTBMetadataGenerator.json`. O preview recomendado tem entre 100 e 200 caracteres; os capítulos devem começar por `00:00`. O manifesto JSON descarregado contém os campos para um fluxo posterior de upload. Esta adaptação local não faz scraping automático via RSS/Apify nem publica directamente no YouTube.
 
-Se a limpeza falhar, confirme a disponibilidade do FFmpeg em **Configurações > Caminho FFmpeg** ou execute `doctor`. O processo usa `-map_metadata -1` para remover os metadados existentes e `-c copy` para evitar uma re-encodificação desnecessária sempre que o contentor permitir.
+Se a limpeza falhar, confirme a disponibilidade do FFmpeg em **Configurações > Configurações Técnicas > Caminho FFmpeg** ou execute `doctor`. O processo usa `-map_metadata -1` para remover os metadados existentes e `-c copy` para evitar uma re-encodificação desnecessária sempre que o contentor permitir.
 
 ## 11. Problemas frequentes
 

package/README.md

@@ -10,21 +10,26 @@ A primeira versão implementa a camada UI independente com:
 
 | Área | Incluído |
 |---|---|
-| Dashboard | Resumo de canais, tarefas, backlog, execução e falhas |
-| Pipeline | Filas por etapa |
+| Início | Resumo de canais, tarefas, backlog, execução e falhas, com as filas do Pipeline inline |
+| Pipeline | Menu expansível com Criação de Vídeos, Criação de Músicas, Upload e Limpador de Metadados |
 | Blueprints | Leitura da pasta `storage/blueprints/`, upload/validação de JSON e criação a partir de link YouTube |
 | Brandings | Subaba própria dentro de Blueprints, upload/listagem de Brandings e criação conjunta com Blueprint |
 | Canais | Subabas de importação pública sem API Key, Data API opcional e cadastro manual independente |
-| Novo vídeo | 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 |
+| 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 metadado | Upload isolado de vídeos terceiros, limpeza FFmpeg, edição de título/descrição/tags e manifesto JSON |
-| Configurações | 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 |
+| 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 |
 | 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.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.
+
 ## Instalação
 
 Recomenda-se Python 3.11 ou superior e Node.js 18 ou superior.
@@ -104,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.27 install
-npx.cmd --yes @danhachuel/thunderbolt@0.2.27 doctor
-npx.cmd --yes @danhachuel/thunderbolt@0.2.27
+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:
@@ -124,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:
@@ -142,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
@@ -159,9 +176,9 @@ A mesma aba possui a subaba **Brandings**. No formulário **Criar blueprint a pa
 
 O fluxo foi modelado a partir do blueprint de clonagem com Branding anexado, incluindo a distinção entre entrada de canal/vídeo, normalização do link, metadados de nicho/idioma, perfil do canal, estratégia de conteúdo, pesquisa, identidade visual e brand pack. Placeholders de serviços externos são tratados como configuração local; chaves presentes em workflows importados não devem ser commitadas.
 
-## Limpador de metadado
+## Limpador de Metadados
 
-A aba **Limpador de metadado** foi adaptada do workflow `YTBMetadataGenerator.json`. Ela recebe apenas um vídeo externo já pronto, guarda uma cópia original separada, remove os metadados do contentor com FFmpeg e grava uma nova cópia com título, descrição, links, timestamps, tags e outros campos opcionais. O original nunca é alterado e os vídeos produzidos pela aba **Novo vídeo** não aparecem nesta área.
+A aba **Limpador de Metadados** foi adaptada do workflow `YTBMetadataGenerator.json`. Ela recebe apenas um vídeo externo já pronto, guarda uma cópia original separada, remove os metadados do contentor com FFmpeg e grava uma nova cópia com título, descrição, links, timestamps, tags e outros campos opcionais. O original nunca é alterado e os vídeos produzidos pelas páginas **Criação de Vídeos** e **Criação de Músicas** não aparecem nesta área.
 
 A descrição segue a composição do workflow de referência: preview, secção de links e capítulos/timestamps. O resultado inclui um manifesto JSON para utilizar os metadados num fluxo posterior de upload. A versão local não usa o trigger RSS, o Apify ou a actualização automática de um vídeo YouTube; em vez disso, o utilizador fornece directamente o vídeo terceiro e controla a edição antes de publicar.
 
@@ -181,15 +198,16 @@ Use **Autorizar fallback OAuth** apenas se precisar de uma autorização separad
 
 A subaba **Upload directo** adapta o [YouTube-Video-Upload-Frontend-Api](https://github.com/Nojus10/YouTube-Video-Upload-Frontend-Api). Ela usa cookies, `sessionInfo`, `INNERTUBE_API_KEY` e `DELEGATED_SESSION_ID` fornecidos manualmente pelo utilizador, cria o vídeo através do endpoint interno e envia o ficheiro em chunks de 256 KiB. Este caminho é experimental, não extrai cookies automaticamente e fica separado do agente YouTube principal.
 
-## Novo vídeo, Automação e música
+## Pipeline: Criação de Vídeos, Criação de Músicas e Automação
 
-Em **Novo vídeo**, o estilo visual `Pexels/Pixabay` é o modo de materiais, `full_ia` abre o selector **Estilo IA** com os 12 estilos solicitados e **Apenas Música** exige um áudio local, um upload musical ou um pedido ao endpoint Suno configurado. Neste último modo, a task fica com `background_mode=none`: não são gerados fundos Pexels/Pixabay nem fundos IA.
+Em **Criação de Vídeos**, o estilo visual `Pexels/Pixabay` é o modo de materiais, `full_ia` abre o selector **Estilo IA** com os 12 estilos solicitados e **Apenas Música** exige um áudio local, um upload musical ou um pedido ao endpoint Suno configurado. **Criação de Músicas** reutiliza o mesmo conteúdo e formulário com título próprio. Neste último modo, a task fica com `background_mode=none`: não são gerados fundos Pexels/Pixabay nem fundos IA.
 
 O agente musical guarda os ficheiros em `storage/music/`, aceita formatos de áudio comuns e pode descarregar uma URL de áudio devolvida por um endpoint Suno compatível. Em **Canais**, abra **Definir Blueprint e voz padrão** no cartão do canal para guardar os defaults; em **Automação**, os mesmos dois selectores aparecem no cartão e são sincronizados. Esses valores são usados automaticamente em novas tarefas criadas para o canal. A aba **Automação** também guarda `Automação ON` e um horário diário `HH:MM` por canal e lista os vídeos cadastrados; por definição, esta entrega não executa workers de fundo.
 
 ## Teste de vozes
 
-A área **Configurações > Teste de vozes** é isolada da pipeline. Permite escolher Edge/Azure Speech ou um provider HTTP configurado, seleccionar voz/ID, alterar a velocidade, sintetizar uma amostra, reproduzi-la e descarregá-la. O áudio é guardado em `storage/voice_previews/` e nunca altera vídeos ou tarefas. Se uma instalação antiga não tiver `edge-tts`, execute `npx.cmd --yes @danhachuel/thunderbolt install`; o instalador detecta a dependência em falta sem reinstalar componentes válidos.
+A área **Configurações > Configurações Técnicas > Teste de vozes** é isolada da pipeline.
+ Permite escolher Edge/Azure Speech ou um provider HTTP configurado, seleccionar voz/ID, alterar a velocidade, sintetizar uma amostra, reproduzi-la e descarregá-la. O áudio é guardado em `storage/voice_previews/` e nunca altera vídeos ou tarefas. Se uma instalação antiga não tiver `edge-tts`, execute `npx.cmd --yes @danhachuel/thunderbolt install`; o instalador detecta a dependência em falta sem reinstalar componentes válidos.
 
 ## MCP e integrações externas opcionais
 
@@ -204,9 +222,10 @@ As portas iniciais são `3123` para Short Video Maker, `3001` para a API backend
 
 ## TikTok
 
-A subaba **Vídeos**, dentro de **Novo vídeo**, mostra o backlog e permite iniciar/parar tarefas; deixou de existir como botão principal na barra lateral.
+A subaba **Vídeos**, dentro de **Criação de Vídeos** ou **Criação de Músicas**, mostra o backlog e permite iniciar/parar tarefas; deixou de existir como botão principal na barra lateral.
 
-A aba **Configurações** contém apenas o TikTok Client ID e o TikTok Client Secret para TikTok. Para YouTube, o bloco principal pede o OAuth Client ID e Client Secret; a Data API Key, se usada, fica numa área opcional separada. Client ID + Client Secret não formam uma Data API Key nem um token OAuth.
+A página **Configurações Técnicas** contém apenas o TikTok Client ID e o TikTok Client Secret para TikTok.
+ Para YouTube, o bloco principal pede o OAuth Client ID e Client Secret; a Data API Key, se usada, fica numa área opcional separada. Client ID + Client Secret não formam uma Data API Key nem um token OAuth.
  Redirect URI, scopes, autorização OAuth e tokens são geridos no TikTok for Developers Playground. O adaptador rejeita o upload quando faltam credenciais ou OAuth, em vez de indicar sucesso falso.
 
 ## Segurança

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
@@ -125,6 +128,13 @@ st.markdown("""
 [data-testid="stSidebar"] [data-testid="stBaseButton-primary"]:hover { background:#343434; color:#ffffff; }
 [data-testid="stSidebar"] [data-testid="stBaseButton-primary"] span { color:#ffffff; }
 [data-testid="stSidebar"] [data-testid="stBaseButton-secondary"] span { color:#e7edf2; }
+[data-testid="stSidebar"] [data-testid="stExpander"] { border:0 !important; background:transparent !important; margin:0.02rem 0 !important; }
+[data-testid="stSidebar"] [data-testid="stExpander"] details { border:0 !important; background:transparent !important; }
+[data-testid="stSidebar"] [data-testid="stExpander"] summary { min-height:1.72rem; padding:0.10rem 0.52rem !important; border-radius:7px; color:#e7edf2; font-size:0.86rem; font-weight:650; }
+[data-testid="stSidebar"] [data-testid="stExpander"] summary:hover { background:#1c252e; }
+[data-testid="stSidebar"] [data-testid="stExpander"] summary p { margin:0; line-height:1; }
+[data-testid="stSidebar"] [data-testid="stExpander"] > div { padding:0 0 0 0.42rem !important; }
+[data-testid="stSidebar"] [data-testid="stExpander"] > div [data-testid="stButton"] button { padding-left:0.92rem; font-size:0.83rem; min-height:1.62rem; height:1.62rem; }
 .content-card { padding: 1rem 1.1rem; border:1px solid #20384d; border-radius:14px; background:rgba(18,27,38,.92); min-height:110px; }
 .content-label { color:#8ba6bb; font-size:.8rem; text-transform:uppercase; letter-spacing:.07em; }
 .content-value { color:#f4f8fb; font-size:1.8rem; font-weight:700; margin-top:.3rem; }
@@ -212,27 +222,18 @@ def render_dashboard():
         with col:
             card(label, value, note)
     st.divider()
-    left, right = st.columns([1.5, 1])
-    with left:
-        st.subheader("Pipeline")
-        tasks = read_json("tasks.json", [])
-        counts = {stage: sum(1 for t in tasks if t.get("stage") == stage and t.get("state") not in {"done", "cancelled"}) for stage in STAGES}
-        for stage in STAGES:
-            st.markdown(f'<div class="stage"><strong>{stage.title()}</strong> <span class="small-muted">{counts[stage]} tarefa(s)</span></div>', unsafe_allow_html=True)
-    with right:
-        st.subheader("Acções rápidas")
-        if st.button("Criar novo vídeo", use_container_width=True):
-            st.session_state["page"] = "Novo vídeo"
-            st.rerun()
-        if st.button("Importar canal", use_container_width=True):
-            st.session_state["page"] = "Canais"
-            st.rerun()
-        if st.button("Abrir Blueprints", use_container_width=True):
-            st.session_state["page"] = "Blueprints"
-            st.rerun()
-        if st.button("Abrir Upload", use_container_width=True):
-            st.session_state["page"] = "Upload"
-            st.rerun()
+    st.subheader("Pipeline")
+    st.caption("Filas locais e dependências da cascata")
+    queues = read_json("queues.json", {})
+    blueprint_count = len(list_blueprint_files())
+    for row_start in range(0, len(STAGES), 3):
+        queue_cols = st.columns(3)
+        for col, stage in zip(queue_cols, STAGES[row_start:row_start + 3]):
+            with col:
+                if stage == "blueprint":
+                    card("Blueprints", blueprint_count, f"na biblioteca · {len(queues.get(stage, []))} tarefa(s) na fila")
+                else:
+                    card(stage.title(), len(queues.get(stage, [])), "fila")
 
 
 def render_blueprints():
@@ -537,8 +538,8 @@ def render_channels():
                     st.rerun()
 
 
-def render_new_video():
-    st.title("Novo vídeo")
+def render_new_video(page_title: str = "Criação de Vídeos"):
+    st.title(page_title)
     create_tab, videos_tab = st.tabs(["Criar vídeo", "Vídeos"])
     with create_tab:
         channels = channel_options()
@@ -623,6 +624,171 @@ def render_new_video():
         render_videos()
 
 
+def render_music_creation():
+    """Expose the complete video-creation UI under the music-oriented navigation entry without changing the original page."""
+    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.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():
     st.subheader("Vídeos e backlog")
     st.caption("Acompanhamento dos vídeos criados, estados da pipeline e controlos de execução.")
@@ -870,7 +1036,7 @@ def render_upload_conventional():
 
 
 def render_settings():
-    st.title("Configurações do Thunderbolt")
+    st.title("Configurações Técnicas")
     st.caption("Configuração do motor de vídeo e dos serviços usados pelo Thunderbolt. As credenciais ficam no storage local e não são enviadas para o GitHub.")
     settings = read_json("settings.json", {})
 
@@ -1216,7 +1382,7 @@ def render_mcp():
 
 
 def render_metadata_cleaner():
-    st.title("Limpador de metadado")
+    st.title("Limpador de Metadados")
     st.caption("Limpeza e edição de metadados para vídeos de terceiros que já estão prontos.")
     st.warning("Esta área aceita exclusivamente vídeos externos. Vídeos criados na aba Novo vídeo não são listados nem processados aqui.")
 
@@ -1344,43 +1510,74 @@ def render_pipeline():
 
 
 def main():
-    pages = [
-        ("Dashboard", ":material/home:", "Início"),
-        ("Pipeline", ":material/account_tree:", "Pipeline"),
-        ("Blueprints", ":material/library_books:", "Blueprints"),
-        ("Canais", ":material/ondemand_video:", "Canais"),
-        ("Novo vídeo", ":material/add_circle:", "Novo vídeo"),
-        ("Automação", ":material/schedule:", "Automação"),
+    pipeline_items = [
+        ("Criação de Vídeos", ":material/add_circle:", "Criação de Vídeos"),
+        ("Criação de Músicas", ":material/music_note:", "Criação de Músicas"),
         ("Upload", ":material/cloud_upload:", "Upload"),
+        ("Limpador de Metadados", ":material/edit_note:", "Limpador de Metadados"),
+    ]
+    settings_items = [
+        ("Canais", ":material/ondemand_video:", "Canais"),
+        ("Blueprints", ":material/library_books:", "Blueprints"),
         ("MCP", ":material/hub:", "MCP"),
-        ("Limpador de metadado", ":material/edit_note:", "Limpador de metadado"),
+        ("Configurações Técnicas", ":material/settings:", "Configurações Técnicas"),
+    ]
+    top_pages = [
+        ("Início", ":material/home:", "Início"),
+        ("Pipeline", ":material/account_tree:", "Pipeline"),
+        ("Automação", ":material/schedule:", "Automação"),
+        ("Niche Finder", ":material/search:", "Niche Finder"),
         ("Configurações", ":material/settings:", "Configurações"),
     ]
-    current_page = st.session_state.get("page", "Dashboard")
-    if current_page == "Vídeos":
-        current_page = "Novo vídeo"
-        st.session_state["page"] = current_page
+    aliases = {
+        "Dashboard": "Início",
+        "Novo vídeo": "Criação de Vídeos",
+        "Vídeos": "Criação de Vídeos",
+        "Limpador de metadado": "Limpador de Metadados",
+        "Configurações Técnicas": "Configurações Técnicas",
+    }
+    current_page = aliases.get(st.session_state.get("page", "Início"), st.session_state.get("page", "Início"))
+    if current_page not in {item[0] for item in top_pages + pipeline_items + settings_items}:
+        current_page = "Início"
+    st.session_state["page"] = current_page
+
+    def navigate(target: str):
+        st.session_state["page"] = target
+        st.rerun()
+
+    def render_nav_button(target: str, icon: str, label: str, *, child: bool = False):
+        if st.button(label, key=f"nav_{target}", icon=icon, use_container_width=True, type="primary" if current_page == target else "secondary"):
+            navigate(target)
+
     with st.sidebar:
         version_markup = f'<span class="tb-brand-version">{APP_VERSION}</span>' if APP_VERSION else ""
         st.markdown(f'<div class="tb-brand"><span class="tb-brand-name">Thunderbolt</span>{version_markup}</div>', unsafe_allow_html=True)
-        for target, icon, label in pages:
-            if st.button(label, key=f"nav_{target}", icon=icon, use_container_width=True, type="primary" if current_page == target else "secondary"):
-                st.session_state["page"] = target
-                st.rerun()
+        for target, icon, label in top_pages:
+            if target == "Pipeline":
+                with st.expander("Pipeline", expanded=current_page in {item[0] for item in pipeline_items}, icon=":material/account_tree:"):
+                    for child_target, child_icon, child_label in pipeline_items:
+                        render_nav_button(child_target, child_icon, child_label, child=True)
+            elif target == "Configurações":
+                with st.expander("Configurações", expanded=current_page in {item[0] for item in settings_items}, icon=":material/settings:"):
+                    for child_target, child_icon, child_label in settings_items:
+                        render_nav_button(child_target, child_icon, child_label, child=True)
+            else:
+                render_nav_button(target, icon, label)
+
     renderers = {
-        "Dashboard": render_dashboard,
-        "Pipeline": render_pipeline,
-        "Blueprints": render_blueprints,
-        "Canais": render_channels,
-        "Novo vídeo": render_new_video,
+        "Início": render_dashboard,
+        "Criação de Vídeos": render_new_video,
+        "Criação de Músicas": render_music_creation,
         "Automação": render_automation,
+        "Niche Finder": render_niche_finder,
         "Upload": render_upload,
+        "Limpador de Metadados": render_metadata_cleaner,
+        "Canais": render_channels,
+        "Blueprints": render_blueprints,
         "MCP": render_mcp,
-        "Limpador de metadado": render_metadata_cleaner,
-        "Configurações": render_settings,
+        "Configurações Técnicas": render_settings,
     }
     renderers.get(current_page, render_dashboard)()
 
-
 if __name__ == "__main__":
     main()

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.27",
+  "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);