Files
CenaForge/doc/clipador/EQUIPE-IA.md
T

179 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.<papel>.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.<papel>.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`).