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>
This commit is contained in:
Mateuus
2026-11-18 04:44:56 -03:00
co-authored by Claude Opus 5.5
parent 26c9afa13a
commit 76b722c499
5 changed files with 213 additions and 16 deletions
+2 -1
View File
@@ -441,7 +441,8 @@ chave `clipper-<sessão>-<bloco>`; num banco novo as sessões recomeçam do 1 e
|---|---| |---|---|
| `GET /health` | sem chave | | `GET /health` | sem chave |
| `GET /v1/status` | ferramentas, voz, juiz, gravações ativas | | `GET /v1/status` | ferramentas, voz, juiz, gravações ativas |
| `GET/PUT /v1/judge` | provedor, modelos (editor/analista), nota mínima, varredura, visão, câmera (+ lista de modelos) | | `GET/PUT /v1/judge` | Equipe de IA (`roles`: varredura, analista, editor, juiz — provedor, modelo, esforço, liga/desliga, instruções do administrador; `roleDefaults` = instruções padrão), nota mínima, varredura, visão, câmera, `timelineJson` (+ lista de modelos) — doc/clipador/EQUIPE-IA.md |
| `GET /v1/judge/report?days=&session=` | medição: chamadas e tokens por papel/IA por hora de live, aprovação, decisões do juiz de contexto, concordância juiz × dono |
| `GET/PUT /v1/channels/{id}/settings` · `GET/PUT /v1/sessions/{id}/settings` | configuração do corte: `own`, `effective`, `defaults` (com `format`, `duration` e `hook`), `modes`, `fonts`, `fontFiles` (`{família: "assets/fonts/…ttf"}` das empacotadas, relativo à raiz do repositório), `hookStyles`, `hookAnims`, `aspects`, `frames` (`{vertical, horizontal: {width, height, canvasWidth, canvasHeight}}`, para o painel desenhar a prévia) e `captureQualities` (`[{id, label, maxHeight, gbPerHour, gbPerHourMax, hint}]`) | | `GET/PUT /v1/channels/{id}/settings` · `GET/PUT /v1/sessions/{id}/settings` | configuração do corte: `own`, `effective`, `defaults` (com `format`, `duration` e `hook`), `modes`, `fonts`, `fontFiles` (`{família: "assets/fonts/…ttf"}` das empacotadas, relativo à raiz do repositório), `hookStyles`, `hookAnims`, `aspects`, `frames` (`{vertical, horizontal: {width, height, canvasWidth, canvasHeight}}`, para o painel desenhar a prévia) e `captureQualities` (`[{id, label, maxHeight, gbPerHour, gbPerHourMax, hint}]`) |
| `GET /v1/sessions/{id}/frame?t=` · `POST …/preview` · `POST …/detect-cam[?ai=true]` | quadro para o editor, prévia do layout, achar webcam (local primeiro) | | `GET /v1/sessions/{id}/frame?t=` · `POST …/preview` · `POST …/detect-cam[?ai=true]` | quadro para o editor, prévia do layout, achar webcam (local primeiro) |
| `GET /v1/sessions/{id}/face?from=&to=` · `POST …/face/reset` | série por segundo do rosto (cx/cy/size no quadro inteiro, expressões, `signal`) e picos; refazer o rastreio | | `GET /v1/sessions/{id}/face?from=&to=` · `POST …/face/reset` | série por segundo do rosto (cx/cy/size no quadro inteiro, expressões, `signal`) e picos; refazer o rastreio |
+14 -11
View File
@@ -1233,13 +1233,13 @@ class Judge:
elif self.roles["analyst"]["model"] and provider != self.roles["analyst"]["provider"]: elif self.roles["analyst"]["model"] and provider != self.roles["analyst"]["provider"]:
self.roles["analyst"]["model"] = "" self.roles["analyst"]["model"] = ""
def roles_view(self) -> dict: def roles_view(self, skip: dict[str, str | None] | None = None) -> dict:
"""Papéis para o painel: a configuração + instruções padrão (só leitura) e a cadeia de reserva de cada um.""" """Papéis para o painel: a configuração + o modelo efetivo e a cadeia de reserva de cada um."""
out = {} out = {}
for name in roles_module.ROLES: for name in roles_module.ROLES:
conf = dict(self.roles[name]) conf = dict(self.roles[name])
conf["resolvedModel"] = self.role_model(name) conf["resolvedModel"] = self.role_model(name)
conf["chain"] = self.fallback_chain(conf["provider"]) if self.enabled else [] conf["chain"] = self.fallback_chain(conf["provider"], skip) if self.enabled else []
out[name] = conf out[name] = conf
return out return out
@@ -1299,11 +1299,12 @@ class Judge:
return "modo chave de API sem chave no cofre" return "modo chave de API sem chave no cofre"
return None return None
def fallback_chain(self, primary: str | None = None) -> list[str]: def fallback_chain(self, primary: str | None = None, skip: dict[str, str | None] | None = None) -> list[str]:
"""Ordem em que `ask` tenta as IAs: a do papel (`primary`; padrão = a do editor) primeiro, depois a `order` """Ordem em que `ask` tenta as IAs: a do papel (`primary`; padrão = a do editor) primeiro, depois a `order`
do painel, só as ligadas, com CLI e (no modo chave) com chave; as em pausa são puladas e as perto do limite do painel, só as ligadas, com CLI e (no modo chave) com chave; as em pausa são puladas e as perto do limite
de uso vão para o fim. Reserva desligada: só a escolhida. de uso vão para o fim. Reserva desligada: só a escolhida.
Se TODAS as prontas estiverem em pausa, elas voltam como último recurso (melhor tentar do que parar).""" Se TODAS as prontas estiverem em pausa, elas voltam como último recurso (melhor tentar do que parar).
`skip` = `_skip_reason` já calculado por provedor (o `describe` monta a cadeia de cada papel de uma vez)."""
if not self.enabled: if not self.enabled:
return [] return []
primary = primary if primary in AI_ENABLED else self.provider primary = primary if primary in AI_ENABLED else self.provider
@@ -1311,7 +1312,8 @@ class Judge:
candidates = [primary] candidates = [primary]
if settings["fallback"]["enabled"]: if settings["fallback"]["enabled"]:
candidates += [p for p in settings["order"] if p != primary and p in AI_ENABLED] candidates += [p for p in settings["order"] if p != primary and p in AI_ENABLED]
ready = [p for p in candidates if self._skip_reason(p, settings) is None] ready = [p for p in candidates
if (skip[p] if skip is not None and p in skip else self._skip_reason(p, settings)) is None]
if not settings["fallback"]["enabled"]: if not settings["fallback"]["enabled"]:
return ready return ready
paused = self.pauses() paused = self.pauses()
@@ -1323,7 +1325,9 @@ class Judge:
def describe(self) -> dict: def describe(self) -> dict:
cmd = self.command() if self.enabled else None cmd = self.command() if self.enabled else None
settings = self.ai.settings() settings = self.ai.settings()
primary_skip = self._skip_reason(self.provider, settings) if self.enabled else None # Uma checagem por provedor (CLI no PATH, ligada, chave) para todas as cadeias: o painel lê isto a cada poucos s.
skip = {p: self._skip_reason(p, settings) for p in AI_ENABLED}
primary_skip = skip.get(self.provider) if self.enabled else None
return {"provider": self.provider, "model": self.model if self.enabled else None, return {"provider": self.provider, "model": self.model if self.enabled else None,
"analystModel": self.role_model("analyst") if self.enabled else None, "analystModel": self.role_model("analyst") if self.enabled else None,
"available": bool(cmd) if self.enabled else None, "path": cmd[-1] if cmd else None, "available": bool(cmd) if self.enabled else None, "path": cmd[-1] if cmd else None,
@@ -1332,13 +1336,12 @@ class Judge:
"authMode": settings["providers"].get(self.provider, {}).get("authMode") if self.enabled else None, "authMode": settings["providers"].get(self.provider, {}).get("authMode") if self.enabled else None,
"fallback": {"enabled": settings["fallback"]["enabled"], "fallback": {"enabled": settings["fallback"]["enabled"],
"cooldownMin": settings["fallback"]["cooldownMin"], "cooldownMin": settings["fallback"]["cooldownMin"],
"chain": self.fallback_chain()}, "chain": self.fallback_chain(skip=skip)},
"pauses": [{"provider": p, "until": datetime.fromtimestamp(until, timezone.utc).isoformat(timespec="seconds"), "pauses": [{"provider": p, "until": datetime.fromtimestamp(until, timezone.utc).isoformat(timespec="seconds"),
"reason": reason} for p, (until, reason) in sorted(self.pauses().items())], "reason": reason} for p, (until, reason) in sorted(self.pauses().items())],
# Equipe de IA: cada papel com a sua IA (doc/clipador/EQUIPE-IA.md). # Equipe de IA: cada papel com a sua IA (doc/clipador/EQUIPE-IA.md).
"roles": self.roles_view(), "roles": self.roles_view(skip),
"providers": {p: {"ready": self._skip_reason(p, settings) is None, "providers": {p: {"ready": skip[p] is None, "reason": skip[p],
"reason": self._skip_reason(p, settings),
"enabled": bool((settings["providers"].get(p) or {}).get("enabled"))} "enabled": bool((settings["providers"].get(p) or {}).get("enabled"))}
for p in AI_ENABLED}} for p in AI_ENABLED}}
+2 -2
View File
@@ -940,8 +940,8 @@ class Engine:
# Linha do tempo JSON (novo) ou transcrição + chat + frames soltos (antigo, `timelineJson` desligado). # Linha do tempo JSON (novo) ou transcrição + chat + frames soltos (antigo, `timelineJson` desligado).
use_timeline = bool(self.intel.opts.get("timelineJson", True)) use_timeline = bool(self.intel.opts.get("timelineJson", True))
analyst_on = self.judge.role_enabled("analyst") analyst_on = self.judge.role_enabled("analyst")
image_mode = (self.judge.roles["analyst"].get("images", "mosaic") if analyst_on else "frames") \ # Imagens como escolhido no analista (sem analista, o editor recebe as mesmas); formato antigo = soltos.
if use_timeline else "frames" image_mode = self.judge.roles["analyst"].get("images", "mosaic") if use_timeline else "frames"
# Quadros espalhados de um pouco antes do candidato até o fim da reação: o analista vê a sequência. # Quadros espalhados de um pouco antes do candidato até o fim da reação: o analista vê a sequência.
# 6 quadros; 8 quando o trecho passa de 80 s (cortes de 60–90 s), para não ficar > 20 s entre quadros. # 6 quadros; 8 quando o trecho passa de 80 s (cortes de 60–90 s), para não ficar > 20 s entre quadros.
f_lo = max(lo, clip["start_s"] - 20) f_lo = max(lo, clip["start_s"] - 20)
+178
View File
@@ -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`).
+17 -2
View File
@@ -19,8 +19,10 @@ Três IAs, sempre pela **CLI oficial** instalada no PC (nunca SDK/HTTP direto):
> OAuth só funciona com plano elegível (Code Assist Standard/Enterprise, Workspace). Para conta pessoal, use a > OAuth só funciona com plano elegível (Code Assist Standard/Enterprise, Workspace). Para conta pessoal, use a
> **chave de API** do Google AI Studio. > **chave de API** do Google AI Studio.
Quem usa: os **agentes do painel** (`panel/src/lib/agents.ts`) e o **juiz do Clipador** (`clipper/app/judge.py`). Quem usa: os **agentes do painel** (`panel/src/lib/agents.ts`) e a **Equipe de IA do Clipador**
A configuração fica no painel em **Configurações → IA** (`/settings/ai`). (`clipper/app/judge.py`: varredura, analista, editor e juiz, cada papel com o seu provedor/modelo —
[`clipador/EQUIPE-IA.md`](clipador/EQUIPE-IA.md)). A configuração das IAs (login, chave, reserva) fica no painel em
**Configurações → IA** (`/settings/ai`); qual IA cada papel usa, em Clipador → Ajustes → Juiz.
## Arquivos compartilhados (contrato painel ↔ Clipador) ## Arquivos compartilhados (contrato painel ↔ Clipador)
@@ -68,6 +70,19 @@ Montado a partir do ambiente do processo, por provedor:
Assim o login global de cada CLI não é tocado: o modo chave só vale para a chamada. Assim o login global de cada CLI não é tocado: o modo chave só vale para a chamada.
## Clipador: uma IA por papel (18/11/2026)
- Cada papel do Clipador (`scan`, `analyst`, `editor`, `judge`) tem `provider` + `model` (+ `effort` no Codex) em
`judge.roles` (banco do Clipador). A **reserva vale por papel**: a cadeia começa na IA do papel e segue a `order`
deste arquivo, com as mesmas regras (ligada, CLI, chave, pausa, perto do limite). Serviços gerais (tradução da fala,
pesquisa de jogo, câmera) usam a IA do editor.
- `codex exec` do Clipador roda com `--json` (eventos JSONL na saída padrão; a resposta continua em `-o`) e
`model_reasoning_effort` do papel (padrão `low`; o juiz começa em `medium`).
- Uso de tokens por chamada vai para `ai_calls` (Clipador): Codex = `turn.completed.usage` do `--json`; Claude =
`usage` do envelope `--output-format json` (entrada = nova + criação + leitura de cache); Gemini =
`stats.models.*.tokens`. Medido 18/11/2026: o Codex cobra ≈ 8 mil tokens fixos por chamada pela CLI (juiz com
≈ 1.450 de conteúdo → 9.624 de entrada).
## O que conta como "indisponível" (dispara a reserva) ## O que conta como "indisponível" (dispara a reserva)
Falha que não é culpa do pedido: limite de uso ou cota (`rate limit`, `429`, `quota`, `usage limit`, Falha que não é culpa do pedido: limite de uso ou cota (`rate limit`, `429`, `quota`, `usage limit`,