From 76b722c499434382e65805cbdd980f6035473978 Mon Sep 17 00:00:00 2001 From: Mateuus <5893666+Mateuus@users.noreply.github.com> Date: Wed, 18 Nov 2026 04:44:56 -0300 Subject: [PATCH] Doc: Equipe de IA (doc/clipador/EQUIPE-IA.md) e contrato por papel em doc/ia.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- clipper/README.md | 3 +- clipper/app/judge.py | 25 +++--- clipper/app/worker.py | 4 +- doc/clipador/EQUIPE-IA.md | 178 ++++++++++++++++++++++++++++++++++++++ doc/ia.md | 19 +++- 5 files changed, 213 insertions(+), 16 deletions(-) create mode 100644 doc/clipador/EQUIPE-IA.md diff --git a/clipper/README.md b/clipper/README.md index 4a6efe8..c1263b8 100644 --- a/clipper/README.md +++ b/clipper/README.md @@ -441,7 +441,8 @@ chave `clipper--`; num banco novo as sessões recomeçam do 1 e |---|---| | `GET /health` | sem chave | | `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 /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 | diff --git a/clipper/app/judge.py b/clipper/app/judge.py index a819d02..ec6cf91 100644 --- a/clipper/app/judge.py +++ b/clipper/app/judge.py @@ -1233,13 +1233,13 @@ class Judge: elif self.roles["analyst"]["model"] and provider != self.roles["analyst"]["provider"]: self.roles["analyst"]["model"] = "" - def roles_view(self) -> dict: - """Papéis para o painel: a configuração + instruções padrão (só leitura) e a cadeia de reserva de cada um.""" + def roles_view(self, skip: dict[str, str | None] | None = None) -> dict: + """Papéis para o painel: a configuração + o modelo efetivo e a cadeia de reserva de cada um.""" out = {} for name in roles_module.ROLES: conf = dict(self.roles[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 return out @@ -1299,11 +1299,12 @@ class Judge: return "modo chave de API sem chave no cofre" 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` 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. - 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: return [] primary = primary if primary in AI_ENABLED else self.provider @@ -1311,7 +1312,8 @@ class Judge: candidates = [primary] if settings["fallback"]["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"]: return ready paused = self.pauses() @@ -1323,7 +1325,9 @@ class Judge: def describe(self) -> dict: cmd = self.command() if self.enabled else None 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, "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, @@ -1332,13 +1336,12 @@ class Judge: "authMode": settings["providers"].get(self.provider, {}).get("authMode") if self.enabled else None, "fallback": {"enabled": settings["fallback"]["enabled"], "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"), "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). - "roles": self.roles_view(), - "providers": {p: {"ready": self._skip_reason(p, settings) is None, - "reason": self._skip_reason(p, settings), + "roles": self.roles_view(skip), + "providers": {p: {"ready": skip[p] is None, "reason": skip[p], "enabled": bool((settings["providers"].get(p) or {}).get("enabled"))} for p in AI_ENABLED}} diff --git a/clipper/app/worker.py b/clipper/app/worker.py index 4f1bfd0..c0a5770 100644 --- a/clipper/app/worker.py +++ b/clipper/app/worker.py @@ -940,8 +940,8 @@ class Engine: # Linha do tempo JSON (novo) ou transcrição + chat + frames soltos (antigo, `timelineJson` desligado). use_timeline = bool(self.intel.opts.get("timelineJson", True)) analyst_on = self.judge.role_enabled("analyst") - image_mode = (self.judge.roles["analyst"].get("images", "mosaic") if analyst_on else "frames") \ - if use_timeline else "frames" + # Imagens como escolhido no analista (sem analista, o editor recebe as mesmas); formato antigo = soltos. + 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. # 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) diff --git a/doc/clipador/EQUIPE-IA.md b/doc/clipador/EQUIPE-IA.md new file mode 100644 index 0000000..93cdf6d --- /dev/null +++ b/doc/clipador/EQUIPE-IA.md @@ -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..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**. 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`). diff --git a/doc/ia.md b/doc/ia.md index 44768b2..a44a397 100644 --- a/doc/ia.md +++ b/doc/ia.md @@ -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 > **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`). -A configuração fica no painel em **Configurações → IA** (`/settings/ai`). +Quem usa: os **agentes do painel** (`panel/src/lib/agents.ts`) e a **Equipe de IA do Clipador** +(`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) @@ -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. +## 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) Falha que não é culpa do pedido: limite de uso ou cota (`rate limit`, `429`, `quota`, `usage limit`,