# Clipador — Equipe de IA: papéis, juiz de contexto, linha do tempo JSON e medição (18/11/2026) Implementa as fases **F0** (medir) e **F1** (três papéis + linha do tempo v1) de [`PESQUISA-JUIZ.md`](PESQUISA-JUIZ.md). F2 (OCR do HUD, eventos de áudio) e F3 (modelo local de cena) **não** entraram. Pedido do dono: "temos o analista, o editor e vamos criar o JUIZ — três partes, cada uma com a sua IA (provedor e modelo); nós, como administrador, editamos o que cada um faz. O editor decide se vira corte. O juiz verifica se tem contexto. A IA lê o vídeo em JSON curto para não gastar token de entrada. Para não trazer corte sem sentido, principalmente em inglês." ## 1. Papéis | Papel (`id`) | O que faz | Vê imagem? | Pode desligar? | | --- | --- | --- | --- | | Varredura (`scan`) | assiste a live por janelas e propõe momentos; descreve cada quadro do mosaico (`lines`) | mosaico 4×2 (padrão), quadros soltos ou nenhuma | sim (é a opção `scanEnabled`) | | Analista (`analyst`) | diz O QUE aconteceu no trecho candidato; também descreve os quadros (`lines`) | mosaico (padrão), quadros soltos ou nenhuma | sim (o editor passa a receber as imagens) | | Editor (`editor`) | decide se vira corte, trecho, título, legenda, hashtags | só quando o analista falhou/está desligado | **não** | | Juiz (`judge`) | só texto: o corte faz sentido para quem nunca viu a live? | nunca | sim | Tradução da fala, pesquisa/edição de perfil de jogo e câmera pela IA usam a IA do **editor** (é a "principal"; o `provider`/`model` de `GET /v1/judge` continuam sendo os dele). ### Configuração (`settings`, chave `judge.roles`) ```jsonc { "scan": {"enabled": true, "provider": "codex", "model": "", "effort": "", "extra": "", "images": "mosaic"}, "analyst": {"enabled": true, "provider": "codex", "model": "", "effort": "", "extra": "", "images": "mosaic"}, "editor": {"enabled": true, "provider": "codex", "model": "", "effort": "", "extra": ""}, "judge": {"enabled": true, "provider": "codex", "model": "", "effort": "medium", "extra": "", "critical": ["setup", "payoff", "standalone"], "allowFix": true, "allowContextLine": true, "penalty": 0.5} } ``` - `model: ""` = padrão do provedor (`DEFAULT_MODELS`). `effort` só vale no Codex (`model_reasoning_effort`; "" = low, como sempre foi). O juiz começa em `medium` (recomendação da pesquisa). - `extra` = **instruções do administrador** (até 2.000 caracteres). Vão DEPOIS das instruções padrão, que continuam no código, com o rótulo "Admin notes (may be written in Portuguese; when they conflict with the rules above, they win)" (fonte em inglês) ou "Instruções do administrador…" (fonte em português). O painel mostra as padrão só para leitura (`GET /v1/judge` → `roleDefaults..pt|en`). - Validação campo a campo em `roles.normalize_roles`; o editor é sempre `enabled: true`. - **Migração automática**: banco sem `judge.roles` → o provedor/modelo único de hoje (`judge_provider`/`judge_model`) vira o de todos os papéis e o `judge_analyst_model` que existia fica com o analista. A migração é gravada na subida. `judge_provider = "off"` continua sendo o "IA desligada" (só heurística) — a equipe inteira. - Painel antigo (sem `roles` no `PUT`): `provider`/`model` valem para todos os papéis (como antes). - **Reserva por papel**: a cadeia (`fallback_chain(primary)`) começa na IA do papel e segue a ordem de Configurações → IA; cada papel mostra a sua (`roles..chain`). ## 2. Juiz de contexto Roda depois que o editor MANTEVE o corte (nota ≥ mínima). Vê só o que vai no corte final: a linha do tempo do trecho mais 20 s antes e 15 s depois marcados `out=1` (o espectador não vê), título, legenda, texto de abertura, a "história pretendida" (`what_happened` do analista) e uma linha do jogo. Escreve primeiro `viewer_summary` (o que um espectador frio entende) e depois responde sim/não a 7 checagens: | Checagem | Pergunta | Crítica por padrão | | --- | --- | --- | | `setup` | o corte tem o começo da situação? | sim | | `payoff` | tem o desfecho/resultado/piada? | sim | | `standalone` | funciona sem saber o que veio antes na live / lore do canal? | sim | | `who_what` | dá para entender quem e o quê? | — | | `intelligible` | a fala-chave está na transcrição (não é de um colega que não se ouve)? | — | | `faithful` | título/legenda só dizem o que o corte mostra? | — | | `strong_open` | os 3 primeiros segundos prendem? | — | Schema: `CONTEXT_SCHEMA` (`viewer_summary`, `checks.{c}.{ok,t,why}`, `fix.{start_s,end_s,context_line}`, `confidence`, `reason`); fonte em inglês: `CONTEXT_SCHEMA_EN` com o bloco `pt` (`viewer_summary`, `reason`, `context_line`, `checks.{c}`), como em [`IDIOMAS.md`](IDIOMAS.md). ### Quem decide é o código (`context_judge.decide`) 1. Crítica que falhou **e** o juiz propôs `fix` (e `allowFix`) → o trecho é recalculado com `fit_window` dentro dos limites (volta até `backtrackS`, duração mínima+1 s e máxima). Mudou ≥ 1 s → **ajusta** e o juiz confere **uma** vez de novo, sem novo ajuste: passou → fica o trecho novo; falhou → **descarta** ("Descartado pelo juiz depois do ajuste…"). 2. Crítica que falhou sem ajuste possível → **descarta** com o motivo em português ("Descartado pelo juiz: sem desfecho. …"). 3. `standalone`/`who_what` falhos + `context_line` curta (≤ 10 palavras, ≤ 60 caracteres, `allowContextLine`) → a frase resolve: o corte é aprovado e a frase vira o **texto de abertura** do projeto de edição (no lugar do gancho do analista, `editor_api.auto_for`). Com ajuste de trecho, o início/fim do analista não desfaz o ajuste. 4. Não críticas falhas só tiram `penalty` (0,5) cada da nota do editor (`scoreAfter`); abaixo da nota mínima → descarta. 5. Corte manual ("cortar agora"): só **avisa** (`decision: "warn"`), nunca descarta nem mexe no trecho. 6. Falha da IA do juiz → fica a decisão do editor (`context: {error}`). Gravado em `judge_json.context` (`decision`: approve | adjust | discard | warn, `checks`, `failed`, `failedCritical`, `solvedByLine`, `contextLine`, `scoreAfter`, `reasonPt`, `window`, `first` = 1ª rodada quando ajustou). Descartado pelo juiz: `status = discarded` + `judge_json.discardedBy = "context"`; aparece em "Descartados" e **Forçar render** funciona como sempre. O modal do corte mostra tudo em português. Fora do F1 (da pesquisa): 2ª opinião com outro provedor quando a confiança é baixa, exemplos do dono como few-shot e "testar nos últimos 10 cortes". ## 3. Linha do tempo JSON (v1) e mosaico `app/timeline.py` monta, só com o que já existe, uma linha JSON por instante (chaves curtas; a legenda vai uma vez no prompt): ```jsonl {"win":[4401,4626],"src":"en"} {"t":4529,"d":8,"v":"Tfue on foot near beach house, aims rifle at masked player","sp":"That's my friend… Can be friends?"} {"t":4417,"d":5,"sp":"is that tech","face":"laugh.8","lvl":7,"chat":"9|freckPepeLaff×1"} ``` - Entradas: nova a cada pausa > 1,2 s (se a atual já tem 4 s), troca de falante ou no máximo 8 s; nenhuma atravessa o início/fim do corte. - `sp` = fala literal (até 25 palavras; `[other1]` = outra pessoa, FALANTES.md); `face` = expressão do streamer (`reaction.label` sobre a série do rosto já gravada) com intensidade ≥ 3; `lvl` só quando foge do normal (≥ 6 ou ≤ 1); `chat` = `mensagens|emote×n|frase repetida` (só o que o chat repete; @resposta e !comando não contam). - `v` = o que está na tela: a varredura e o analista já veem os quadros e agora devolvem `lines: [{n, v}]` (até 12 palavras por quadro); fica em `scene_notes` e é reaproveitado por analista, editor e juiz. - Orçamento de caracteres por papel (analista 9.000, editor 7.000, juiz 6.000, varredura 9.000): passou, a fala encurta (25 → 12 → 6 palavras). A "volta" da varredura vai resumida (passo de 20 s). - Perfil do jogo **enxuto** nos prompts da linha do tempo (`judge.lean_profile`: resumo em 2 frases, listas menores). - Imagens: `media.mosaic` junta os quadros (384×216 cada) numa grade 4×2 = 1 imagem 1536×432; a varredura usa 8 quadros por janela. Falhou o mosaico → quadros pequenos soltos. - **Comparar com o antigo**: opção `timelineJson` (`PUT /v1/judge`, interruptor no painel). Desligada = exatamente o formato anterior (transcrição + chat + quadros soltos de 768 px). Cada chamada grava o modo em `ai_calls.mode` (`timeline+mosaic`, `legacy+frames`…). ### Medido no corte 291 (sessão 15, tfue/ROB RUN, fonte em inglês), 18/11/2026 Cópia do banco (`?mode=ro` + backup) e dos blocos numa pasta temporária; IA falsa que só guarda o prompt. Texto ≈ caracteres/4; imagens pelas fórmulas da pesquisa (Codex 1,2 × patches de 32 px; Claude patches de 28 px; Gemini 1.120 por imagem). | Chamada | Antes (texto + imagens, Codex) | Depois | Gemini antes → depois | | --- | --- | --- | --- | | Analista (8 quadros → 1 mosaico) | 2.414 + 3.224 = **5.638** | 2.298 + 806 = **3.104** (−45%) | 11.374 → 3.418 (−70%) | | Editor (só texto) | **2.795** | **2.250** (−20%) | igual | | Varredura (6 quadros → mosaico de 8) | 2.912 + 2.418 = **5.330** | 2.505 + 806 = **3.311** (−38%) | 9.632 → 3.625 (−62%) | | Juiz (novo, só nos mantidos) | — | **≈ 1.420** | — | Por hora (tfue: ~20 varreduras, ~25 candidatos, ~13 mantidos): antes ≈ 317 mil tokens de conteúdo; depois ≈ 224 mil **com** o juiz (−29%). Em bytes de imagem: analista 361 KB → 121 KB por corte. Chamada real (UMA, Codex `gpt-6-luna`, papel juiz, esforço médio, 18/11/2026): schema com `null` aceito, bloco `pt` completo, **9.624 tokens de entrada / 1.400 de saída, 27 s**. Como o conteúdo era ≈ 1.450 tokens, o **fixo do Codex pela CLI ≈ 8 mil tokens por chamada** — hoje é o maior item; o próximo passo de economia é ele (medir pelo relatório). ## 4. Medição (F0) - `ai_calls` (banco v17): uma linha por tentativa de chamada — `role`, `purpose` (translate, research, cam…), `provider`, `model`, `ok`/`error`, `ms`, `system_chars`, `prompt_chars`, `images`, `image_bytes`, `tokens_in`, `tokens_out`, `tokens_cached` (quando a CLI informa: `codex exec --json` → `turn.completed.usage`; `claude --output-format json` → `usage`; `gemini -o json` → `stats.models.*.tokens`), `session_id`, `clip_id`, `mode`. - Avaliação do dono: `clips.owner_label` (`good` | `bad` | `no_context`) + `owner_note`. `PATCH /v1/clips/{id}` com `{"label": "no_context"}` (vale para qualquer corte, inclusive antigos e descartados; não muda o estado) ou `{"status": "rejected", "label": "no_context"}` (botão **Sem contexto** no modal). Sem rótulo: aprovado/publicado = bom, rejeitado = ruim. - `GET /v1/judge/report?days=7` (ou `?session=N`): `calls` por papel × IA × modo, `perHour` (chamadas e tokens por hora de live; `estTokensIn` = caracteres/4 quando a CLI não informou), `clips` (por estado, taxa de aprovação, "sem contexto"), `judge` (aprovou/ajustou/descartou/avisou/erro/com frase) e `agreement.judge|editor` (pares, concordância, κ de Cohen, matriz mantém/descarta × bom/ruim/sem contexto). O painel mostra em Ajustes → Juiz → Medição. ## 5. Onde está cada coisa - `clipper/app/roles.py` — papéis, padrão, validação, migração, instruções do administrador. - `clipper/app/judge.py` — `Judge.ask(role=…)`, `check_context`, `CONTEXT_*`, `build_timeline_prompt`, `build_scan_timeline_prompt`, `build_context_prompt`, `lean_profile`, leitura de uso (`codex_usage`, `claude_usage`, `gemini_usage`), `scope(...)` para a medição. - `clipper/app/context_judge.py` — `decide` e `view`. - `clipper/app/timeline.py` — evidência, entradas, orçamento, `scene_notes`. - `clipper/app/worker.py` — `judge_clip` (analista → editor → juiz), `_context_check`, `record_ai_call`. - `clipper/app/intel.py` — `visual` (mosaico/quadros), varredura com a linha do tempo, opção `timelineJson`. - `clipper/app/report.py` — relatório. - Painel: `clipper-ai-team.tsx` (cartões e medição), `clipper-judge.tsx`, `clipper-clip-parts.tsx` (`ContextVerdict`, `OwnerLabelControl`, botão "Sem contexto"). - Testes: `clipper/tests/test_roles.py`, `clipper/tests/test_context_judge.py`. Os testes bloqueiam qualquer CLI de IA de verdade (`conftest._no_real_ai_cli`). ## 6. Pontos de integração - Banco: **v17** (`ai_calls`, `scene_notes`). A v16 é a detecção do jogo (`game_status`, `game_detect_json`); as expressões do rosto não precisaram de migração. - O rosto é lido por `face.FaceService.dense` + `reaction.channel_z/reaction_signal/label` (sem mudar `face.py` nem `reaction.py`); rótulos novos de expressão passam como vierem (o mapa para inglês está em `timeline.FACE_TOKENS`). - `codex exec` agora roda com `--json` (os eventos vão para a saída padrão; a resposta continua em `-o`).