Files
CenaForge/doc/clipador/EQUIPE-IA.md
T
MateuusandClaude Opus 5.5 76b722c499 Doc: Equipe de IA (doc/clipador/EQUIPE-IA.md) e contrato por papel em doc/ia.md
- EQUIPE-IA.md: papéis e configuração (judge.roles, migração), juiz de contexto e as regras
  de decisão pelo código, linha do tempo JSON + mosaico, medição (ai_calls, owner_label,
  GET /v1/judge/report) e o medido no corte 291 (analista −45%, varredura −38%, editor −20%;
  ≈ −29% por hora já com o juiz; 1 chamada real do juiz no Codex: 9.624 tokens de entrada).
- doc/ia.md: reserva por papel, codex exec --json e leitura de uso por CLI.
- README do Clipador: rotas /v1/judge e /v1/judge/report.
- judge.describe: uma checagem por provedor para todas as cadeias (o painel lê o status a
  cada poucos segundos); sem analista, o editor recebe as imagens no modo escolhido.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 04:44:56 -03:00

13 KiB
Raw Blame History

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. 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)

{
  "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.

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):

{"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. A v16 é um marcador sem efeito (SELECT 1), reservado às expressões do rosto (branch clipper/expressions); no merge, o conteúdo de lá entra na posição da v16.
  • 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).