07 · The sap: enrichment

Sap rises from the root to the leaves without anyone seeing it. Enrichment does the same with attachments: it pulls text out of PDFs, recognizes scanned pages, writes subtitles for speech — so that search can find things and people who can't hear can read.

Files to read

1. docs/baobaxia-enriquecimento.md — the complete design (read it first).
2. enriquecimento/servico.py — Enriquecedor: decide, run, write.
3. enriquecimento/procedencia.py — the record of "what was done to which file, by which engine, with which result" (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.

What is automatic and what must be requested

The request travels with sync: whoever asks can be a mucua without Whisper; the next mucua with the capability and the file does the work, and the subtitles return to everyone as an attachment (<file>.<language>.vtt, in the annex).

flowchart TD
    A[attachment in content] --> B{is there already a provenance record<br/>with the same hash?}
    B -- yes --> C{--forcar, or a better model here<br/>and output not reviewed by a person?}
    C -- no --> Z[skip]
    C -- yes --> D
    B -- no --> D[classify]
    D -->|audio/video| E{is it in data.transcrever?}
    E -- no --> Z
    E -- yes --> E2[ffmpeg 16 kHz → Whisper + VAD + vocabulary<br/>→ file.pt.vtt in the annex]
    D -->|PDF| F[pdftotext → local cache]
    F --> F2{pages without text?}
    F2 -- yes, no request --> F3[status: precisa_ocr]
    F2 -- yes, with data.ocr --> G[Tesseract → file.ocr.txt in the annex]
    D -->|image| H{is it in data.ocr?}
    H -- yes --> G
    H -- no --> Z
    D -->|docx/odt/txt/html| I[text → local cache]

The care the code takes

• Process lock (_TravaProcesso): only one round per machine; another one answers ja_em_andamento.
• Galaxy lock: waits for sync and requests to let go (ESPERA_TRAVA).
• Clean interruption (_SemInterrupcao): Ctrl-C in the middle of writing waits for the commit to finish, so the .bbx is never left half-written.
• Human review wins: foi_revisada compares the recorded hash with that of the current subtitles. If someone corrected the subtitles, the machine does not write over them.
• Limited attempts on error (MAX_TENTATIVAS), and an environment error (missing engine) does not use up an attempt.

Practice

1. Read test_enriquecimento_whisper.py::test_transcricao_so_dos_arquivos_marcados and explain why not every video gets transcribed.
2. With ffmpeg installed, make a short video, publish it, mark it in data.transcrever and run bbx enriquecer --saber <uuid>. Where do the subtitles appear on disk? And in the index?
3. In procedencia.py, follow precisa_processar. In which case does a larger model redo the subtitles?
4. Add place names from your community to a saber's vocabulary (data.vocabulario) and compare the transcription.

To talk about

• Machine-made subtitles in an Indigenous language or a quilombola way of speaking get things wrong. How does the system's design make room for corrections made by the community?