lazier

README.md (14160B)

---

 # Lazier
 
 Sistema CLI e Web para **transcrição** e **sumarização** de áudios, vídeos, textos e PDFs usando os modelos mais recentes da OpenAI (família GPT-5 + `gpt-4o-mini-transcribe`/`whisper-1`). Além de transcrição/sumário tradicionais, gera **sumário inteligente** estruturado (TL;DR, pontos-chave, decisões, *action items*, tópicos e citações) e **capítulos com timestamps** para áudio/vídeo. Suporta upload de arquivos, URLs do YouTube e de centenas de outros sites (via yt-dlp), e páginas web. Exporta em DOCX, TXT, Markdown, JSON e PDF.
 
 ## Requisitos
 
 - **OpenAI API Key** (Whisper para transcrição, GPT para sumário)
 - **Redis** (opcional, para cache de transcrições/sumários)
 - **ffmpeg** e **yt-dlp** (instalados automaticamente no Docker; em instalação local, instale manualmente)
 
 ## Configuração (.env)
 
 Copie o exemplo e preencha:
 
 ```bash
 cp .env.example .env
 ```
 
 | Variável | Obrigatório | Descrição |
 |----------|-------------|-----------|
 | `OPENAI_API_KEY` | Sim | Chave da API OpenAI ([obter aqui](https://platform.openai.com/api-keys)) |
 | `SESSION_SECRET_KEY` | Sim (Web) | Chave para sessões. Gere com: `openssl rand -hex 32` |
 | `ADMIN_USER` / `ADMIN_PASSWORD` | Não | Usuário admin da WebGUI (criado na primeira execução se definidos) |
 
 ### Modelos e inteligência (opcionais)
 
 Defaults seguros já vêm configurados; sobrescreva apenas se quiser mudar.
 
 | Variável | Default | Descrição |
 |----------|---------|-----------|
 | `OPENAI_CHAT_MODEL` | `gpt-4o-mini` | Modelo de chat usado para sumário, conversão para PT-BR, detecção de tipo e capítulos. Alternativas: `gpt-5-mini`, `gpt-5-nano`, `gpt-4.1-mini`. |
 | `OPENAI_TRANSCRIBE_MODEL` | `gpt-4o-mini-transcribe` | Modelo padrão de transcrição (saída em texto). Alternativas: `gpt-4o-transcribe`, `whisper-1`. |
 | `OPENAI_TRANSCRIBE_TIMESTAMPS_MODEL` | `whisper-1` | Modelo usado quando precisamos de `verbose_json` para gerar capítulos. Atualmente `whisper-1` é o mais confiável para retornar `start`/`end`. |
 | `OPENAI_ENABLE_SMART_SUMMARY` | `true` | Liga/desliga o sumário estruturado (TL;DR, pontos-chave, decisões, ações, tópicos, citações, perguntas em aberto). Quando `false`, mantém o sumário textual legado. |
 | `OPENAI_ENABLE_CHAPTERS` | `false` | Capítulos com timestamps (exige STT `verbose_json`, mais lento). |
 | `OPENAI_REASONING_EFFORT` | `minimal` | Esforço de raciocínio para modelos da família `gpt-5`/`o-series`. Valores: `minimal`, `low`, `medium`, `high`. |
 | `LAZIER_QUALITY_PRESET` | `economico` | Preset global `economico` / `equilibrado` / `maximo` → defaults de chat, transcrição e `reasoning`. |
 | `LAZIER_SUMMARY_HIERARCHICAL` | `true` | Acima de `LAZIER_SUMMARY_DIRECT_MAX_CHARS`, o sumário inteligente usa map-reduce com chunks e overlap em vez de um único passe sobre o texto completo. |
 | `LAZIER_SUMMARY_DIRECT_MAX_CHARS` | `48000` | Limiar (caracteres) para ativar sumarização hierárquica. |
 | `LAZIER_SUMMARY_MAP_CHUNK_CHARS` | `16000` | Tamanho alvo de cada chunk no map. |
 | `LAZIER_SUMMARY_CHUNK_OVERLAP_CHARS` | `800` | Sobreposição entre chunks consecutivos. |
 | `LAZIER_ENABLE_PT_POLISH` | `false` | Revisão ortográfica extra após PT-BR (mais chamadas chat). |
 | `LAZIER_DETECT_CONTENT_TYPE` | `false` | Classificador de tipo antes do sumário (1 chamada chat). |
 | `LAZIER_STT_PARALLEL_WORKERS` | `3` | Transcrição paralela de chunks de áudio. |
 | `LAZIER_SUMMARY_PARALLEL_WORKERS` | `3` | Sumário inteligente paralelo por chunk. |
 | `LAZIER_ALT_STT_ENABLED` | `false` | Reserva para spike de segundo STT ou diarização. |
 | `LAZIER_ALWAYS_SUMMARY` | `false` | Se `true`, força geração de sumário mesmo quando o modo pedido é só `transcribe` (override de instalação). |
 | `LAZIER_DIARIZATION_PROVIDER` | `none` | Diarização opcional de falantes (`none`, ou provedores futuros). |
 
 Opcional: `YOUTUBE_PO_TOKEN` para melhor suporte a alguns vídeos do YouTube ([guia](https://github.com/yt-dlp/yt-dlp/wiki/PO-Token-Guide)).
 
 **Segredos:** nunca commite ficheiros `.env` com valores reais, chaves API ou passwords. Mantenha apenas `.env.example` no Git; use variáveis de ambiente no host ou *secrets* do CI/CD (GitHub Actions, etc.).
 
 ## Instalação Rápida
 
 ### Docker (Recomendado)
 
 ```bash
 # 1. Clone o repositório
 git clone <repo-url>
 cd lazier
 
 # 2. Configure o .env (OPENAI_API_KEY, SESSION_SECRET_KEY e opcionalmente ADMIN_USER/ADMIN_PASSWORD)
 cp .env.example .env
 # Edite .env com suas chaves
 
 # 3. Inicie os serviços (a partir da pasta do projeto)
 docker compose -f docker/docker-compose.yml up -d --build
 ```
 
 Ou, a partir da pasta `docker/`:
 
 ```bash
 cd docker
 docker compose up -d --build
 ```
 
 Acesse: **http://localhost:19283**
 
 Arquivos gerados são salvos em `outputs/` na raiz do projeto.
 
 ### Instalação Local
 
 ```bash
 pip install -r requirements.txt
 cp .env.example .env
 # Preencha OPENAI_API_KEY e SESSION_SECRET_KEY no .env
 
 # Redis (opcional, para cache)
 docker run -d -p 52847:6379 redis:7-alpine
 
 lazier web
 ```
 
 Acesse **http://localhost:19283** (ou use `--port` para outra porta).
 
 ## Uso
 
 ### CLI
 
 ```bash
 # Só transcrição (texto completo em PT-BR — default, mais económico)
 lazier transcribe audio.mp3
 lazier transcribe video.mp4
 lazier transcribe "https://www.youtube.com/watch?v=VIDEO_ID"
 
 # Só sumário (STT/extração internos; exporta apenas o sumário)
 lazier summarize document.pdf
 lazier summarize "https://example.com/artigo" --format md
 lazier summarize aula.mp3 --gpt-model gpt-5 --reasoning high
 
 # Transcrição + sumário (dois artefactos; maior consumo de tokens)
 lazier process aula.mp3 --format md
 
 # Desligar features opcionais
 lazier summarize aula.mp3 --no-smart --no-chapters
 
 # Outras opções
 lazier summarize video.mp4 --format json     # docx, txt, md, json, pdf
 lazier config                                 # mostra a config corrente
 lazier web                                    # inicia servidor web
 lazier cache clear                            # limpa cache
 ```
 
 Flags principais:
 
 - `--model` sobrescreve `OPENAI_TRANSCRIBE_MODEL` para esse comando.
 - `--gpt-model` sobrescreve `OPENAI_CHAT_MODEL`.
 - `--smart/--no-smart` força ligar/desligar o sumário estruturado.
 - `--chapters/--no-chapters` força ligar/desligar capítulos com timestamps.
 - `--reasoning {minimal,low,medium,high}` ajusta o esforço de raciocínio para modelos `gpt-5`/`o-series`.
 
 O pacote custo/qualidade (`economico` / `equilibrado` / `maximo`) vem só de `LAZIER_QUALITY_PRESET` no `.env` (`lazier config` mostra o valor atual).
 
 ### Economia de tokens
 
 | Modo | O que gera | Notas |
 |------|------------|-------|
 | `transcribe` | Transcrição PT-BR | Não chama sumário inteligente nem detecção de tipo de conteúdo. |
 | `summarize` | Sumário PT-BR | Áudio/vídeo ainda passam por STT; transcrição completa não é exportada. |
 | `process` | Transcrição + sumário | Dois ficheiros na WebGUI; custo total de chat. |
 
 Na WebGUI escolha **Transcrição**, **Sumário** ou **Ambos**. Na API, omitir `mode` equivale a `transcribe`. Use `"mode": "process"` ou `transcribe: true, summarize: true` para os dois.
 
 ### Velocidade e custo (defaults)
 
 O perfil **económico** shipado prioriza latência e preço:
 
 - **`gpt-4o-mini`** para chat (conversão PT-BR e sumário).
 - **Capítulos desligados** — evita STT com `whisper-1` + geração de capítulos.
 - **Sem polish nem detecção de tipo** — poupa 1–3 chamadas chat por job.
 - **Áudio normalizado** mono 16 kHz antes do STT (ficheiros menores).
 - **Chunks STT/sumário em paralelo** (até 3 workers).
 
 Para máxima qualidade: `LAZIER_QUALITY_PRESET=maximo`, `OPENAI_ENABLE_CHAPTERS=true`, `LAZIER_ENABLE_PT_POLISH=true`.
 
 ### WebGUI
 
 Acesse http://localhost:19283 após iniciar com `lazier web` ou Docker. Na primeira vez, faça login com o usuário e senha definidos em `ADMIN_USER` e `ADMIN_PASSWORD` no `.env` (se configurados).
 
 ### API HTTP
 
 `POST /api/process` e `POST /api/upload` aceitam, além dos campos clássicos, overrides por requisição:
 
 ```json
 {
   "url": "https://example.com/aula.mp3",
   "format": "md",
   "mode": "summarize"
 }
 ```
 
 Modos: `transcribe` (default), `summarize`, `process` (ambos). Overrides opcionais:
 
 ```json
 {
   "url": "https://example.com/aula.mp3",
   "format": "md",
   "mode": "process",
   "chat_model": "gpt-5",
   "transcribe_model": "gpt-4o-transcribe",
   "smart": true,
   "chapters": true
 }
 ```
 
 Os campos `chat_model`, `transcribe_model`, `smart` e `chapters` são opcionais e sobrescrevem os defaults definidos no `.env` apenas para esse job. `GET /api/jobs/{id}/details` passa a devolver `smart_summary`, `chapters` e `content_type` quando disponíveis.
 
 ## Inteligência
 
 ### Sumário estruturado
 
 Quando `OPENAI_ENABLE_SMART_SUMMARY=true` (default), o Lazier gera um objeto `SmartSummary` validado por Pydantic com Structured Outputs. Cada saída inclui:
 
 - `tldr`: resumo de 1-3 frases
 - `key_points`: pontos principais em ordem lógica
 - `decisions`: decisões explícitas tomadas no conteúdo
 - `action_items`: lista de `{owner, task, due_hint}`
 - `topics`: temas curtos
 - `quotes`: trechos literais marcantes
 - `open_questions`: perguntas em aberto
 
 O caminho legado (`summarize_text` em texto livre) ainda é usado como fallback se o modelo não suportar Structured Outputs ou se `OPENAI_ENABLE_SMART_SUMMARY=false`.
 
 ### Detecção de tipo de conteúdo
 
 Antes de gerar o sumário, o sistema chama um classificador curto que escolhe entre `lecture`, `podcast`, `interview`, `news`, `tutorial`, `meeting`, `tech_doc` ou `other`. O tipo detectado é exibido na CLI/API e usado para ajustar o prompt do sumário (ex.: reuniões enfatizam `decisions`/`action_items`; palestras enfatizam conceitos e exemplos).
 
 ### Capítulos com timestamps
 
 Para áudio/vídeo, quando `OPENAI_ENABLE_CHAPTERS=true`, o Lazier:
 
 1. Pede ao modelo de transcrição (`whisper-1` por padrão para timestamps) saída em `verbose_json` com `segments`.
 2. Envia esses segmentos ao modelo de chat, que devolve uma lista de capítulos com título, resumo e índices inicial/final.
 3. Materializa cada capítulo com `start`, `end` e `start_hms`/`end_hms`.
 
 Os capítulos aparecem nos exports DOCX/Markdown/PDF/TXT e no JSON cru.
 
 Os ficheiros exportados usam o **título do vídeo ou do conteúdo** (sanitizado) como nome e como cabeçalho do documento. Quando há transcrição e sumário em ficheiros separados, os sufixos `- transcricao` e `- sumario` distinguem cada artefato.
 
 ## Sites suportados (vídeo/áudio)
 
 Além do YouTube, você pode colar URLs de vídeo ou áudio de **centenas de sites**. O Lazier usa o [yt-dlp](https://github.com/yt-dlp/yt-dlp) para extrair o áudio; se a URL não for um vídeo, o sistema tenta extrair o texto da página e sumarizar.
 
 **Exemplos de sites que você pode processar:**
 
 | | | |
 |---|---|---|
 | YouTube | TED | Reddit |
 | Vimeo | Twitter / X | TikTok |
 | Instagram | Facebook | Twitch |
 | Dailymotion | BBC, CNN, NBC | NPR, PBS |
 | Arte, France TV, RTVE | Khan Academy | Coursera, Udemy |
 | LinkedIn Learning | Loom | Streamable |
 | BitChute, Odysee | Rumble | PeerTube |
 | archive.org | Patreon | Substack |
 | Wistia | Niconico | Bilibili |
 | Kick, Floatplane | Nebula | CuriosityStream |
 | C-SPAN | Al Jazeera | DW, Reuters |
 | ESPN, Fox Sports | Formula 1 | Olympics |
 | NYTimes | Washington Post | The Guardian |
 
 E muitos outros. **Lista completa** mantida pelo yt-dlp: [Supported sites](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md).
 
 **Importante:** Conteúdo cujo **tema é música** (categoria Music no YouTube, tags de clipe oficial, domínios só de música) **não é processado** pelo Lazier. Vídeos com **música de fundo** (vlogs, palestras, tutoriais) continuam sendo processados normalmente.
 
 ## Docker
 
 ```bash
 # A partir da raiz do projeto
 docker compose -f docker/docker-compose.yml up -d --build   # Iniciar (com rebuild)
 docker compose -f docker/docker-compose.yml logs -f         # Ver logs
 docker compose -f docker/docker-compose.yml down            # Parar
 docker compose -f docker/docker-compose.yml down -v         # Parar e limpar volumes
 ```
 
 Ou entre na pasta `docker/` e use `docker compose up -d` (sem o `-f`).
 
 ## Cache Redis
 
 Cache automático de transcrições e sumários (TTL: 7 dias).
 
 ```bash
 lazier cache clear    # Limpar cache
 lazier cache stats    # Estatísticas
 ```
 
 
 **Nota:** ffmpeg e yt-dlp são instalados automaticamente no container Docker.
 
 ## Troubleshooting
 
 - **"OPENAI_API_KEY não encontrada"**: Crie/edite o `.env` com `OPENAI_API_KEY=sua_chave`
 - **"SESSION_SECRET_KEY não configurada"**: Necessária para a WebGUI. Gere com `openssl rand -hex 32` e adicione ao `.env`
 - **"Redis não disponível"**: O sistema funciona sem cache. Para usar cache: `docker run -d -p 52847:6379 redis:7-alpine` (no host use `REDIS_PORT=52847` no `.env` se conectar ao Redis local)
 - **Arquivo muito grande**: A API Whisper tem limite de 25 MB. Divida arquivos grandes ou use a divisão automática do Lazier
 - **Conteúdo detectado como música**: URLs de música (ex.: categoria Music no YouTube) não são processadas; use apenas vídeos/podcasts
 
 ## Segurança e repositório público
 
 Antes de tornar o repositório público no GitHub:
 
 1. **Secret scanning** — Em *Settings* → *Code security and analysis*, ative **Secret scanning** (e, se disponível, *push protection*) para alertas sobre segredos no código.
 2. **Rever o histórico** — Com o remoto atualizado (`git fetch --all`), confirme que nunca houve `.env` ou chaves no histórico, por exemplo:
    - `git log --all --full-history -p -- .env`
    - `git log --all -S "sk-" --oneline -- "*.py" "*.md"`
 3. **Se algum segredo já foi commitado** — Revogue ou regenere imediatamente essa chave na respetiva plataforma (OpenAI, etc.). Limpar o ficheiro no último commit **não** remove o segredo do histórico; use ferramentas como [`git-filter-repo`](https://github.com/newren/git-filter-repo) ou BFG Repo-Cleaner e faça *force push* com consciência do impacto em colaboradores.
 
 ## Contato
 
 Pablo Murad - pablomurad@pm.me