stepkeeper

O que stepkeeper faz?

<Propósito> Converte um vídeo tutorial do YouTube em um documento passo a passo onde cada instrução verbal vaga ("em pedaços pequenos", "até o molho reduzir", "dobre aqui") é respaldada pelo frame exato do vídeo que a mostra. Funciona em vários domínios (culinária, faça-você-mesmo/reparos, artesanato, beleza, fitness, tutoriais de software) por meio de perfis intercambiáveis. A saída é um documento portátil que pode ser exportado para Notion, Obsidian ou Goodnotes. </Propósito>

<Quando_Usar>

• O usuário compartilha uma URL de tutorial do YouTube e deseja um guia textual/visual limpo e fácil de seguir.
• O usuário reclama que as instruções faladas de um tutorial são ambíguas e deseja o frame "me mostre".
• O usuário deseja salvar uma receita/procedimento em um aplicativo de notas. </Quando_Usar>

<Não_Usar_Quando>

• O vídeo é uma palestra com foco na fala, vlog, resenha ou podcast sem ações visualmente resolvíveis.
• O conteúdo é crítico para a segurança (médico, eletricidade de rede, gás, máquinas pesadas) — requer um perfil revisado por especialistas. </Não_Usar_Quando>

<Pré-requisitos>

• O repositório stepkeeper no disco. Se estiver ausente, clone-o primeiro: git clone https://github.com/zlej123/stepkeeper e execute todos os comandos a partir desse diretório.
• Variável de ambiente GEMINI_API_KEY (chave do Google AI Studio). Se estiver faltando, peça uma ao usuário (gratuita em https://aistudio.google.com/apikey) — nunca prossiga sem ela.
• ffmpeg no PATH (captura de frames; não necessário para --links-only).
• pip install -e . a partir do repositório (instala dependências e o comando stepkeeper). </Pré-requisitos>

<Como_Executar> Um comando impulsiona analisar → capturar → escolher → renderizar → exportar. --language é o idioma do documento (BCP-47: en, ko, ja, …), não o idioma falado do vídeo. Vídeos tutoriais em inglês funcionam tanto com saída en quanto ko.

1. Totalmente automático (sem ffmpeg, links de timestamp em vez de capturas de tela):

   • Documento em coreano: stepkeeper <URL> --profile generic --language ko --links-only
   • Documento em inglês (usuários que falam inglês): stepkeeper <URL> --profile generic --language en --links-only

2. Totalmente automático com capturas de tela (Gemini escolhe o frame por guia): stepkeeper <URL> --profile recipe --language en --auto-pick --export goodnotes Revise o picker.html regenerado (escolhas da IA pré-selecionadas); se o usuário corrigir alguma, execute python -m stepkeeper.feedback add <semantic-evaluation.json> para registrá-la.

3. Seleção manual/de agente de frames:

   • stepkeeper <URL> --profile recipe --language en
   • Caminho do agente: leia os três frames candidatos em work/frames/… diretamente, escreva picks.json você mesmo (julgamento semântico) e execute novamente com --picks <picks.json> --export goodnotes (ou obsidian/bundle/notion).

A exportação para Notion precisa de NOTION_TOKEN e --parent <page-id>. Os artefatos vão para o diretório atual (STEPKEEPER_DATA substitui). </Como_Executar>

<Saídas>

• work/analyses/<id>/<profile>.<language>.json — análise validada.
• work/frames/<id>/<profile>.<language>/ — 3 candidatos por guia + picker.html.
• output/<id>/<profile>.<language>/document.md (+ imagens/).
• exports/<id>/<profile>.<language>/{bundle|goodnotes}/… — artefatos do aplicativo de notas. </Saídas>

<Verificação>

• python -m unittest discover -s tests — testes unitários de contrato/normalização/seleção/exportação.
• python tests/batch.py — regressão estrutural + semântica sobre o corpus de fixtures.
• python tests/batch.py --domain en_output --analyze — teste de fumaça para saída em inglês (tests/fixtures/urls.json → en_output, escreve work/analyses/<id>/*.<en>.json).
• Após a captura, salve o semantic-evaluation.json do picker como tests/evaluations/<id>.<profile>.en.json para que o batch possa relatar a taxa de acerto do top-3 para en.
• python tests/validate_fixtures.py --online — disponibilidade + estratificação das URLs das fixtures. </Verificação>