07 · A seiva: enriquecimento

A seiva sobe da raiz às folhas sem ninguém ver. O enriquecimento faz isso com os anexos: tira texto de PDFs, reconhece páginas escaneadas, escreve legendas das falas — para a busca encontrar e para quem não ouve poder ler.

Arquivos para ler

1. docs/baobaxia-enriquecimento.md — o desenho completo (leia antes).
2. enriquecimento/servico.py — Enriquecedor: decidir, executar, gravar.
3. enriquecimento/procedencia.py — o registro de "o que foi feito com qual arquivo, por qual motor, com qual resultado" (data.enriquecimento).
4. enriquecimento/classificar.py, textos.py, ocr.py, transcricao.py, legendas.py, vocabulario.py.
5. infra/previa_video.py, infra/thumbnails.py, infra/mosaico.py.

O que é automático e o que é pedido

O pedido viaja pelo sync: quem pede pode ser uma mucua sem Whisper; a próxima mucua com a capacidade e com o arquivo faz o trabalho, e a legenda volta para todas como anexo (<arquivo>.<idioma>.vtt, no annex).

flowchart TD
    A[anexo em content] --> B{já há registro de procedência<br/>com o mesmo hash?}
    B -- sim --> C{--forcar, ou modelo daqui melhor<br/>e saída não revisada por gente?}
    C -- não --> Z[pula]
    C -- sim --> D
    B -- não --> D[classificar]
    D -->|áudio/vídeo| E{está em data.transcrever?}
    E -- não --> Z
    E -- sim --> E2[ffmpeg 16 kHz → Whisper + VAD + vocabulário<br/>→ arquivo.pt.vtt no annex]
    D -->|PDF| F[pdftotext → cache local]
    F --> F2{páginas sem texto?}
    F2 -- sim, sem pedido --> F3[status: precisa_ocr]
    F2 -- sim, com data.ocr --> G[Tesseract → arquivo.ocr.txt no annex]
    D -->|imagem| H{está em data.ocr?}
    H -- sim --> G
    H -- não --> Z
    D -->|docx/odt/txt/html| I[texto → cache local]

Cuidados que o código tem

• Trava de processo (_TravaProcesso): só uma rodada por máquina; outra responde ja_em_andamento.
• Trava da galáxia: espera o sync e os pedidos soltarem (ESPERA_TRAVA).
• Interrupção limpa (_SemInterrupcao): Ctrl-C no meio da gravação espera terminar o commit, para não deixar o .bbx pela metade.
• Revisão humana vence: foi_revisada compara o hash registrado com o da legenda atual. Se alguém corrigiu a legenda, a máquina não escreve por cima.
• Tentativas limitadas para erro (MAX_TENTATIVAS), e erro de ambiente (motor ausente) não queima tentativa.

Práticas

1. Leia test_enriquecimento_whisper.py::test_transcricao_so_dos_arquivos_marcados e explique por que nem todo vídeo é transcrito.
2. Com ffmpeg instalado, gere um vídeo curto, publique, marque em data.transcrever e rode bbx enriquecer --saber <uuid>. Onde a legenda aparece no disco? E no índice?
3. Em procedencia.py, siga precisa_processar. Em que caso um modelo maior refaz a legenda?
4. Adicione nomes de lugares da sua comunidade ao vocabulário de um saber (data.vocabulario) e compare a transcrição.

Para conversar

• Legenda feita por máquina numa língua indígena ou num falar quilombola erra. Como o desenho do sistema dá lugar à correção feita pela comunidade?