Merge branch 'clipper/roles' into clipper/integ
This commit is contained in:
@@ -0,0 +1,178 @@
|
||||
# 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**. 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`).
|
||||
Reference in New Issue
Block a user