From cb8450399d243e156787b3232429e3c806ada11f Mon Sep 17 00:00:00 2001
From: Mateuus <5893666+Mateuus@users.noreply.github.com>
Date: Wed, 18 Nov 2026 04:36:25 -0300
Subject: [PATCH 1/7] =?UTF-8?q?Clipador:=20Equipe=20de=20IA=20(pap=C3=A9is?=
=?UTF-8?q?=20com=20IA=20pr=C3=B3pria),=20juiz=20de=20contexto=20e=20linha?=
=?UTF-8?q?=20do=20tempo=20JSON?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- roles.py: varredura, analista, editor e juiz, cada um com provedor, modelo, raciocínio
(Codex), liga/desliga (o editor não desliga) e instruções do administrador somadas às
padrão; gravado em settings `judge.roles`, com migração automática da configuração antiga
(provedor/modelo único vira o de todos; o modelo do analista é respeitado). A reserva vale
por papel.
- Juiz de contexto (só texto): vê só o que vai no corte (+20 s antes/15 s depois marcados
out=1), escreve o que um espectador frio entende e responde sim/não; context_judge.decide
decide pelo código: aprova, ajusta o trecho e confere uma vez de novo, frase de contexto
na tela (vira o texto de abertura do projeto) ou descarta com motivo em português
(forçável). Corte manual só recebe aviso.
- timeline.py: linha do tempo JSON curta (fala com falante, chat, rosto, volume e a frase
de tela que a varredura/analista escrevem ao ver os quadros, em scene_notes); mosaico 4x2
(media.mosaic) no lugar dos quadros soltos; perfil do jogo enxuto. O formato antigo fica
atrás da opção timelineJson.
- Medição (F0): ai_calls por chamada (papel, IA, tamanho do prompt/imagens, tokens quando a
CLI informa: codex --json, claude e gemini), avaliação do dono (owner_label: bom/ruim/sem
contexto) e GET /v1/judge/report (taxa de aprovação, decisões do juiz, concordância).
- Banco v17 (v16 fica reservada às expressões, como marcador sem efeito).
- Testes: test_roles.py e test_context_judge.py; os testes bloqueiam qualquer CLI de IA real.
Co-Authored-By: Claude Opus 5.5
---
clipper/app/context_judge.py | 116 ++++++
clipper/app/db.py | 45 +++
clipper/app/editor_api.py | 13 +-
clipper/app/intel.py | 75 +++-
clipper/app/judge.py | 527 +++++++++++++++++++++++---
clipper/app/main.py | 32 +-
clipper/app/media.py | 37 ++
clipper/app/report.py | 145 +++++++
clipper/app/roles.py | 127 +++++++
clipper/app/timeline.py | 298 +++++++++++++++
clipper/app/worker.py | 248 +++++++++---
clipper/tests/conftest.py | 21 +
clipper/tests/test_context_judge.py | 257 +++++++++++++
clipper/tests/test_english_source.py | 6 +-
clipper/tests/test_roles.py | 244 ++++++++++++
clipper/tests/test_sources_and_api.py | 3 +
clipper/tests/test_speakers.py | 3 +-
17 files changed, 2081 insertions(+), 116 deletions(-)
create mode 100644 clipper/app/context_judge.py
create mode 100644 clipper/app/report.py
create mode 100644 clipper/app/roles.py
create mode 100644 clipper/app/timeline.py
create mode 100644 clipper/tests/test_context_judge.py
create mode 100644 clipper/tests/test_roles.py
diff --git a/clipper/app/context_judge.py b/clipper/app/context_judge.py
new file mode 100644
index 0000000..b492858
--- /dev/null
+++ b/clipper/app/context_judge.py
@@ -0,0 +1,116 @@
+"""Decisão do JUIZ de contexto pelo código (doc/clipador/EQUIPE-IA.md).
+
+O juiz (IA, só texto) responde perguntas sim/não sobre o corte; quem decide é esta função, com regras fixas e
+calibráveis no painel (papel `judge` em `judge.roles`):
+
+- checagem **crítica** que falhou (padrão: começo, desfecho, funciona sozinho) + ajuste de trecho dentro dos limites
+ → **ajusta** (o trecho é recalculado com `fit_window`) e o juiz confere UMA vez de novo; falhou de novo → descarta;
+- crítica que falhou sem ajuste possível → **descarta** com o motivo em português;
+- "funciona sozinho" (e "quem/o quê") falho + frase de contexto → a frase resolve: vai na tela no começo do corte;
+- checagem não crítica que falhou só **baixa a nota** (`penalty` por checagem); abaixo da nota mínima → descarta;
+- corte manual ("cortar agora"): o juiz só **avisa**, nunca descarta nem mexe no trecho.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .roles import CHECK_NAMES, CHECKS, DEFAULT_CRITICAL, DEFAULT_PENALTY
+from .scoring import fit_window
+
+MIN_SHIFT_S = 1.0 # ajuste menor que isso não muda nada: conta como "sem ajuste"
+CONTEXT_LINE_MAX_WORDS = 10
+CONTEXT_LINE_MAX_CHARS = 60
+OUT_BEFORE_S = 20.0 # o juiz vê 20 s antes do corte, marcados out=1 (o espectador não vê)…
+OUT_AFTER_S = 15.0 # …e 15 s depois (para notar o desfecho que ficou de fora)
+# O que a frase de contexto resolve (ela dá ao espectador frio quem/o quê e o pano de fundo).
+SOLVED_BY_LINE = ("standalone", "who_what")
+
+
+@dataclass
+class Decision:
+ action: str # approve | adjust | discard | warn
+ failed: list[str] = field(default_factory=list) # todas as checagens que falharam
+ failed_critical: list[str] = field(default_factory=list) # críticas que falharam e a frase não resolveu
+ solved_by_line: list[str] = field(default_factory=list)
+ window: tuple[float, float] | None = None # trecho novo (só em adjust)
+ context_line: str = ""
+ score_after: float | None = None
+ reason_pt: str = ""
+
+
+def usable_line(text: str) -> str:
+ """Frase de contexto que cabe na tela no começo do corte (curta); senão vazia."""
+ text = " ".join((text or "").split())
+ if not text or len(text) > CONTEXT_LINE_MAX_CHARS or len(text.split()) > CONTEXT_LINE_MAX_WORDS:
+ return ""
+ return text
+
+
+def _names(checks: list[str]) -> str:
+ names = [CHECK_NAMES.get(c, c) for c in checks]
+ return names[0] if len(names) == 1 else ", ".join(names[:-1]) + " e " + names[-1]
+
+
+def decide(result: dict, *, start_s: float, end_s: float, lo: float, hi: float, min_s: float, max_s: float,
+ conf: dict | None = None, score: float | None = None, min_score: float | None = None,
+ manual: bool = False, allow_fix: bool | None = None) -> Decision:
+ """Ação pelo resultado do juiz (`judge.clean_context`). `conf` = papel `judge` da Equipe de IA.
+ `allow_fix=False` força a 2ª rodada (sem novo ajuste)."""
+ conf = conf or {}
+ critical = [c for c in conf.get("critical", DEFAULT_CRITICAL) if c in CHECKS]
+ penalty = float(conf.get("penalty", DEFAULT_PENALTY))
+ can_fix = conf.get("allowFix", True) if allow_fix is None else (allow_fix and conf.get("allowFix", True))
+ checks = result.get("checks") or {}
+ failed = [c for c in CHECKS if not (checks.get(c) or {}).get("ok", True)]
+ fix = result.get("fix") or {}
+ line = usable_line(fix.get("context_line", "")) if conf.get("allowContextLine", True) else ""
+ solved = [c for c in failed if c in SOLVED_BY_LINE] if line else []
+ failed_critical = [c for c in failed if c in critical and c not in solved]
+ others = [c for c in failed if c not in critical and c not in solved]
+ score_after = None if score is None else round(max(0.0, score - penalty * len(others)), 2)
+ why_pt = (result.get("pt") or {}).get("reason") or result.get("reason") or ""
+ d = Decision("approve", failed, failed_critical, solved, None, line, score_after)
+
+ if manual:
+ d.action = "warn" if failed else "approve"
+ d.reason_pt = (f"Aviso do juiz: falhou em {_names(failed)}. {why_pt}".strip() if failed else "")
+ return d
+ if failed_critical:
+ new = None
+ if can_fix and (fix.get("start_s") is not None or fix.get("end_s") is not None):
+ ns = fix["start_s"] if fix.get("start_s") is not None else start_s
+ ne = fix["end_s"] if fix.get("end_s") is not None else end_s
+ # Recuar o início (faltou o começo) mantém o início; estender o fim (faltou o desfecho) mantém o fim.
+ keep = "start" if "setup" in failed_critical or ns < start_s - MIN_SHIFT_S else "end"
+ ns, ne = fit_window(ns, ne, lo, hi, min_s, max_s, keep=keep)
+ if ne - ns >= min(min_s, 10.0) and (abs(ns - start_s) >= MIN_SHIFT_S or abs(ne - end_s) >= MIN_SHIFT_S):
+ new = (ns, ne)
+ if new:
+ d.action, d.window = "adjust", new
+ d.reason_pt = (f"Juiz ajustou o trecho para {new[0]:.0f}–{new[1]:.0f}s: faltava {_names(failed_critical)}. "
+ f"{why_pt}").strip()
+ else:
+ d.action = "discard"
+ d.reason_pt = f"Descartado pelo juiz: sem {_names(failed_critical)}. {why_pt}".strip()
+ return d
+ if score_after is not None and min_score is not None and others and score_after < min_score:
+ d.action = "discard"
+ d.reason_pt = (f"Descartado pelo juiz: a nota caiu para {score_after:.1f} (falhou em {_names(others)}). "
+ f"{why_pt}").strip()
+ return d
+ d.reason_pt = (f"Juiz aprovou{' com frase de contexto' if line and solved else ''}"
+ + (f" (falhou em {_names(others)}, nota {score_after:.1f})" if others and score_after is not None else "")
+ + (f". {why_pt}" if why_pt else "."))
+ return d
+
+
+def view(result: dict, decision: Decision, model: str) -> dict:
+ """O que vai em `judge_json.context` (o painel mostra em português)."""
+ return {"model": model, "viewerSummary": result.get("viewer_summary", ""), "checks": result.get("checks", {}),
+ "fix": result.get("fix", {}), "confidence": result.get("confidence"), "reason": result.get("reason", ""),
+ "pt": result.get("pt") or {}, "decision": decision.action, "failed": decision.failed,
+ "failedCritical": decision.failed_critical, "solvedByLine": decision.solved_by_line,
+ "contextLine": decision.context_line if decision.action in ("approve", "adjust", "warn") else "",
+ "scoreAfter": decision.score_after, "reasonPt": decision.reason_pt,
+ **({"window": [round(decision.window[0], 2), round(decision.window[1], 2)]} if decision.window else {})}
diff --git a/clipper/app/db.py b/clipper/app/db.py
index 05fae67..a1b38dd 100644
--- a/clipper/app/db.py
+++ b/clipper/app/db.py
@@ -243,6 +243,51 @@ SCHEMA = [
PRIMARY KEY (session_id, idx)
);
""",
+ # v16: RESERVADA para as expressões do rosto (branch clipper/expressions). Aqui é só um marcador sem efeito para a
+ # numeração andar; no merge, o conteúdo de lá entra NESTA posição (a v17 abaixo não depende dela).
+ """
+ SELECT 1;
+ """,
+ # v17: Equipe de IA (doc/clipador/EQUIPE-IA.md).
+ # - `ai_calls`: cada chamada de IA (papel, IA, tamanho do prompt e das imagens, tokens quando a CLI informa, tempo)
+ # para comparar custo por hora (F0). Sem FK para a sessão: a medição fica depois de apagar a sessão.
+ # - `scene_notes`: frase curta do que está na tela num instante (escrita pela varredura/analista ao ver os quadros);
+ # vira o campo `v` da linha do tempo JSON.
+ # - `clips.owner_label`/`owner_note`: avaliação do dono (bom / ruim / sem contexto) para o conjunto de avaliação.
+ """
+ CREATE TABLE IF NOT EXISTS ai_calls (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ at TEXT NOT NULL,
+ role TEXT NOT NULL,
+ purpose TEXT NOT NULL,
+ provider TEXT NOT NULL,
+ model TEXT NOT NULL,
+ ok INTEGER NOT NULL,
+ error TEXT,
+ ms INTEGER,
+ system_chars INTEGER,
+ prompt_chars INTEGER,
+ images INTEGER,
+ image_bytes INTEGER,
+ tokens_in INTEGER,
+ tokens_out INTEGER,
+ tokens_cached INTEGER,
+ session_id INTEGER,
+ clip_id INTEGER,
+ mode TEXT
+ );
+ CREATE INDEX IF NOT EXISTS ai_calls_at ON ai_calls (at);
+ CREATE TABLE IF NOT EXISTS scene_notes (
+ session_id INTEGER NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+ t REAL NOT NULL,
+ source TEXT NOT NULL,
+ text TEXT NOT NULL,
+ created_at TEXT NOT NULL,
+ PRIMARY KEY (session_id, t, source)
+ );
+ ALTER TABLE clips ADD COLUMN owner_label TEXT CHECK (owner_label IN ('good', 'bad', 'no_context'));
+ ALTER TABLE clips ADD COLUMN owner_note TEXT;
+ """,
]
diff --git a/clipper/app/editor_api.py b/clipper/app/editor_api.py
index fcaae0a..42fcb4b 100644
--- a/clipper/app/editor_api.py
+++ b/clipper/app/editor_api.py
@@ -172,7 +172,18 @@ def auto_for(engine, clip: dict, session: dict) -> dict:
lo, hi = editor.default_window(clip, session["duration_s"])
words = engine.words_between(clip["session_id"], lo, hi) # já com quem fala cada palavra (FALANTES.md)
loudness = engine.load_timeline(clip["session_id"], max(0.0, lo - 5))["loudness"]
- return editor.auto_project(clip, judge.get("analysis"), words, loudness, session["duration_s"],
+ analysis = judge.get("analysis")
+ context = judge.get("context") if isinstance(judge.get("context"), dict) else {}
+ if context.get("decision") in ("approve", "adjust", "warn") and (context.get("contextLine") or context.get("window")):
+ analysis = dict(analysis or {})
+ # Juiz de contexto (EQUIPE-IA.md): a frase de contexto vira o texto do começo do corte (no lugar do gancho)…
+ if context.get("contextLine"):
+ analysis["hook"] = context["contextLine"]
+ # …e, se ele ajustou o trecho, o início/fim do analista não desfaz o ajuste (ex.: recuou para pegar o começo).
+ if context.get("window"):
+ analysis.pop("action_start_s", None)
+ analysis.pop("reaction_end_s", None)
+ return editor.auto_project(clip, analysis, words, loudness, session["duration_s"],
engine.intel.settings_for(session), model=judge.get("model") or "", generated_at=now())
diff --git a/clipper/app/intel.py b/clipper/app/intel.py
index 52a15b9..380c2c3 100644
--- a/clipper/app/intel.py
+++ b/clipper/app/intel.py
@@ -18,12 +18,13 @@ import time
from pathlib import Path
from typing import TYPE_CHECKING
-from . import clip_delete, layout
+from . import clip_delete, layout, media, timeline
from .db import loads, now
from .emotes import EmoteCatalog, extract, learn_delta, message_bonus
from .face import FaceError, FaceUnavailable
from .hashtags import fold, to_tag
-from .judge import JudgeError, build_scan_prompt, game_context, lang_key, output_language_note
+from .judge import (JudgeError, build_scan_prompt, build_scan_timeline_prompt, game_context, lang_key, lean_profile,
+ output_language_note)
from .scoring import fit_window
from .sources import parse_source
@@ -33,12 +34,17 @@ if TYPE_CHECKING: # pragma: no cover
log = logging.getLogger("cenaforge_clipper.intel")
# faceTrack: rastreio do rosto do streamer (face.py) — reforça/cria cortes e vai em texto para o analista.
-OPTION_DEFAULTS = {"scanEnabled": True, "scanIntervalS": 180, "vision": True, "camDetect": True, "faceTrack": True}
+# timelineJson: a IA lê o vídeo como linha do tempo JSON curta (timeline.py); desligado = transcrição + chat + frames
+# soltos como antes (para comparar custo e qualidade — doc/clipador/EQUIPE-IA.md).
+OPTION_DEFAULTS = {"scanEnabled": True, "scanIntervalS": 180, "vision": True, "camDetect": True, "faceTrack": True,
+ "timelineJson": True}
CAM_RETRY_S = 300 # câmera não achada enquanto grava: nova tentativa depois de mais 5 min de gravação
CAM_MAX_ATTEMPTS = 6 # falha sem rosto decidido (poucos quadros legíveis): no máximo isto de tentativas
GAME_CHECK_S = 600 # rechecar a categoria da live a cada 10 min (o streamer troca de jogo)
SCAN_FRAME_EVERY_S = 30
SCAN_MAX_FRAMES = 7
+SCAN_MOSAIC_TILES = 8 # mosaico 4×2: 1 imagem por janela de varredura
+SCAN_TIMELINE_CHARS = 9000
MEMORY_KEEP = 6
SCAN_MAX_MOMENTS = 2
SCAN_MIN_PROPOSAL = 4 # proposta da varredura abaixo disso nem vai aos juízes (economia)
@@ -474,10 +480,13 @@ class Intel:
"""'en' = fonte em inglês (juízes em inglês, tradução para o painel); 'pt' = o resto."""
return lang_key(session.get("language") or self.e.settings.language)
- def context(self, session: dict) -> str:
+ def context(self, session: dict, lean: bool = False) -> str:
+ """Contexto do jogo para os prompts. `lean` (linha do tempo JSON): perfil enxuto (judge.lean_profile)."""
memory = loads(session.get("memory_json"), [])
confirmed = session.get("game_source") == "user" and bool(session.get("game"))
profile = self.profile(session.get("game", "")) or (None if confirmed else self.profile(session.get("screen_game", "")))
+ if lean:
+ profile = lean_profile(profile)
text = game_context(session.get("game", ""), session.get("screen_game", ""), profile, session.get("title", ""),
" | ".join(m["summary"] for m in memory[-3:] if m.get("summary")), confirmed=confirmed,
lang=self.lang(session))
@@ -486,7 +495,7 @@ class Intel:
return f"{text}\n{note}" if note else text
# ---------------------------------------------------------------- frames
- def frames(self, session: dict, times: list[float], tag: str) -> list[tuple[float, Path]]:
+ def frames(self, session: dict, times: list[float], tag: str, width: int = 768) -> list[tuple[float, Path]]:
if not self.opts["vision"]:
return []
segments = [(self.e.repo_path(s["file"]), s["start_s"], s["end_s"])
@@ -495,11 +504,31 @@ class Intel:
frames = []
for t in times:
try:
- frames.append((t, self.e.grab_frame(segments, t, out_dir / f"{tag}-{int(t)}.jpg")))
+ frames.append((t, self.e.grab_frame(segments, t, out_dir / f"{tag}-{int(t)}.jpg", width)))
except Exception as exc: # noqa: BLE001 - sem frame a IA decide só pelo texto
log.info("frame %.0fs indisponível: %s", t, exc)
return frames
+ def visual(self, session: dict, times: list[float], tag: str, mode: str) -> tuple[list[Path], list[float], bool]:
+ """Imagens para a IA: (arquivos, instante de cada quadro, é mosaico?). `mode`: "mosaic" = os quadros numa
+ grade 4×2 numa imagem só (384×216 cada); "frames" = soltos em 768 px (o antigo); "none" = nenhuma.
+ Mosaico que falha cai para os quadros soltos (a IA não fica sem ver a tela)."""
+ if mode == "none" or not self.opts["vision"] or not times:
+ return [], [], False
+ if mode != "mosaic":
+ frames = self.frames(session, times, tag)
+ return [p for _, p in frames], [t for t, _ in frames], False
+ frames = self.frames(session, times, f"{tag}m", width=media.MOSAIC_TILE_W)
+ if not frames:
+ return [], [], False
+ out = self.e.repo_path(session["dir"]) / "frames" / f"{tag}-mosaic-{int(frames[0][0])}.jpg"
+ try:
+ media.mosaic(self.e.settings.ffmpeg or "ffmpeg", [p for _, p in frames], out)
+ except Exception as exc: # noqa: BLE001 - sem mosaico, vão os quadros (pequenos) soltos
+ log.info("mosaico %s indisponível: %s", tag, exc)
+ return [p for _, p in frames], [t for t, _ in frames], False
+ return [out], [t for t, _ in frames], True
+
# ---------------------------------------------------------------- webcam
def maybe_detect_cam(self, session: dict) -> None:
"""Acha a câmera no início da sessão. A detecção local (YuNet) não precisa de IA, visão nem juiz ligados."""
@@ -633,19 +662,39 @@ class Intel:
cfg = self.settings_for(session)
dur = cfg["duration"]
back_lo = max(0.0, lo - dur["backtrackS"])
- step = max(SCAN_FRAME_EVERY_S, (hi - lo) / SCAN_MAX_FRAMES)
- times = [lo + step / 2 + i * step for i in range(int((hi - lo) // step) or 1)][:SCAN_MAX_FRAMES]
- frames = self.frames(session, times, "scan")
+ use_timeline = bool(self.opts.get("timelineJson", True))
+ mode = self.e.judge.roles["scan"].get("images", "mosaic") if use_timeline else "frames"
+ if mode == "mosaic": # 8 quadros por igual na janela, numa imagem só
+ step = (hi - lo) / SCAN_MOSAIC_TILES
+ times = [lo + step / 2 + i * step for i in range(SCAN_MOSAIC_TILES)]
+ else:
+ step = max(SCAN_FRAME_EVERY_S, (hi - lo) / SCAN_MAX_FRAMES)
+ times = [lo + step / 2 + i * step for i in range(int((hi - lo) // step) or 1)][:SCAN_MAX_FRAMES]
+ images, tiles, mosaic = self.visual(session, times, "scan", mode)
existing = [(c["start_s"], c["end_s"], c["title"]) for c in self.e.db.all(
"SELECT start_s, end_s, title FROM clips WHERE session_id = ? AND end_s > ? AND start_s < ?", session["id"], back_lo, hi)]
existing += clip_delete.mark_spans(self.e.db, session["id"], back_lo, hi) # apagados não voltam pela varredura
- prompt = build_scan_prompt(self.e.streamer_name(session), session["platform"], lo, hi, back_lo, tl["words"],
- tl["chat"], self.context(session), frames, existing, dur["minS"], dur["maxS"],
- lang=self.lang(session))
+ lang = self.lang(session)
+ if use_timeline:
+ # A "volta" (antes da janela) vai resumida: já foi vista na janela anterior.
+ ev = timeline.collect(self.e, session, tl, back_lo, hi)
+ text = timeline.build(ev, back_lo, hi, {"win": [int(lo), int(hi)], "back": int(back_lo), "src": lang},
+ budget_chars=SCAN_TIMELINE_CHARS, coarse_until=lo)
+ prompt = build_scan_timeline_prompt(self.e.streamer_name(session), session["platform"], lo, hi, back_lo,
+ self.context(session, lean=True), text, tiles, mosaic, existing, dur["minS"],
+ dur["maxS"], lang=lang)
+ else:
+ prompt = build_scan_prompt(self.e.streamer_name(session), session["platform"], lo, hi, back_lo, tl["words"],
+ tl["chat"], self.context(session), list(zip(tiles, images)), existing,
+ dur["minS"], dur["maxS"], lang=lang)
created = 0
try:
- data = self.e.judge.scan(prompt, [p for _, p in frames], lang=self.lang(session))
+ run_mode = ("timeline" if use_timeline else "legacy") + f"+{'mosaic' if mosaic else mode}"
+ with self.e.judge.scope(session_id=session["id"], mode=run_mode):
+ data = self.e.judge.scan(prompt, images, lang=lang)
self.last_scan_error = None
+ # O que a varredura viu em cada quadro vira o `v` da linha do tempo (analista, editor e juiz reaproveitam).
+ timeline.save_scene_lines(self.e, session["id"], "scan", data.get("lines"), tiles)
except (JudgeError, json.JSONDecodeError) as exc:
# Avança mesmo assim: repetir a mesma janela com a CLI quebrada só gastaria cota.
self.last_scan_error = str(exc)[:300]
diff --git a/clipper/app/judge.py b/clipper/app/judge.py
index 2785905..a819d02 100644
--- a/clipper/app/judge.py
+++ b/clipper/app/judge.py
@@ -30,11 +30,13 @@ import sys
import tempfile
import threading
import time
+from contextlib import contextmanager
from dataclasses import dataclass, field
from datetime import datetime, timezone
from pathlib import Path
from . import layout
+from . import roles as roles_module
from .ai_settings import AiConfig
from .scoring import ChatMessage, Word, fit_window
@@ -111,6 +113,14 @@ CHAT_GLOSSARY = """Gírias comuns do chat (interprete pelo contexto):
"clipa/clip it" → pedido de corte; "hack/hackudo" → suspeita de trapaça; "gg" → fim de partida.
- Emotes próprios do canal (prefixo do streamer, ex.: skpPog) carregam a mesma reação do emote original."""
+# Frase curta do que está na tela em cada quadro/ladrilho do mosaico (`n` = nº do quadro, 1 = primeiro). Vira o
+# campo `v` da linha do tempo (app/timeline.py), guardado em `scene_notes` e reaproveitado por editor e juiz.
+SCENE_LINES = {
+ "type": "array",
+ "items": {"type": "object", "properties": {"n": {"type": "integer"}, "v": {"type": "string"}},
+ "required": ["n", "v"], "additionalProperties": False},
+}
+
SITUATIONS = ("lag_ou_bug", "jogada", "falha_engracada", "morte", "susto", "treta", "conversa_engracada",
"historia", "informacao_do_jogo", "reacao", "outro")
@@ -126,11 +136,14 @@ ANALYSIS_SCHEMA = {
"action_start_s": {"type": "number"},
"reaction_end_s": {"type": "number"},
"hook": {"type": "string"},
+ "lines": SCENE_LINES,
},
"required": ["situation", "what_happened", "screen", "speech", "chat_meaning", "confidence",
- "action_start_s", "reaction_end_s", "hook"],
+ "action_start_s", "reaction_end_s", "hook", "lines"],
"additionalProperties": False,
}
+# Campos que a resposta pode não trazer (modelo antigo/cache): a análise segue sem eles.
+ANALYSIS_OPTIONAL = ("lines",)
ANALYST_SYSTEM = """Você é o ANALISTA de uma equipe de cortes de live. Não escreve título: descreve com fidelidade
O QUE ACONTECEU no trecho, para o editor decidir. Recebe contexto do jogo, transcrição com tempos, FRAMES da tela
@@ -152,6 +165,8 @@ Campos:
- action_start_s: instante (s da gravação) em que começa a AÇÃO que gerou a reação (pode ser antes da fala).
- reaction_end_s: instante em que a reação/pagamento termina.
- hook: o que prenderia alguém nos 2 primeiros segundos do corte.
+- lines: para cada frame/quadro do mosaico anexado (n = o número dele), v = o que está na tela em até 12 palavras,
+ factual (ação, lugar, texto grande do jogo). Sem imagem anexada: lista vazia.
Não use ferramentas além do que foi entregue. Responda só com o JSON pedido."""
VERDICT_SCHEMA = {
@@ -184,8 +199,9 @@ SCAN_SCHEMA = {
"has_webcam": {"type": "boolean"},
"summary": {"type": "string"},
"moments": {"type": "array", "items": _MOMENT},
+ "lines": SCENE_LINES,
},
- "required": ["screen_game", "has_webcam", "summary", "moments"],
+ "required": ["screen_game", "has_webcam", "summary", "moments", "lines"],
"additionalProperties": False,
}
_MISSION = {
@@ -271,6 +287,8 @@ moments=[] (é o normal na maior parte do tempo — não force). Não repita um
- screen_game: o jogo que aparece na tela (ou "desconhecido"); has_webcam: há câmera do streamer no quadro?
- summary: 1 frase do que está acontecendo na janela (vira memória para as próximas janelas).
- title/caption/reason como um editor faria (título ≤ 70 caracteres, verdadeiro; hashtags só do que há aqui).
+- lines: para cada frame/quadro do mosaico (n = o número dele), v = o que está na tela em até 12 palavras, factual.
+ Sem imagem anexada: lista vazia.
Não use ferramentas além do que foi entregue. Responda só com o JSON pedido."""
# Perfil do jogo em INGLÊS (doc/clipador/JOGOS.md): é o que vai nos prompts; a tradução para português é só para o
@@ -454,6 +472,8 @@ Fields (in English):
- action_start_s: second of the recording where the ACTION that caused the reaction starts (may be before the speech).
- reaction_end_s: second where the reaction/payoff ends.
- hook: what would hook someone in the first 2 seconds of the clip (English, it goes on screen).
+- lines: for each attached frame/mosaic tile (n = its number), v = what is on screen in up to 12 words, factual
+ (action, place, big on-screen game text), in English. No image attached: empty list.
- pt: what_happened, screen, speech, chat_meaning and hook translated. """ + PT_NOTE + """
Do not use tools beyond what was given. Answer only with the requested JSON."""
@@ -500,6 +520,8 @@ moments=[] (that's normal most of the time — don't force it). Don't repeat a c
- screen_game: the game on screen (or "unknown"); has_webcam: is there a streamer camera in the frame?
- summary: 1 sentence of what's going on in the window (becomes memory for the next windows).
- title/caption/reason in English like an editor would write (title ≤ 70 characters, true).
+- lines: for each frame/mosaic tile (n = its number), v = what is on screen in up to 12 words, factual, in English.
+ No image attached: empty list.
- summary_pt and each moment's pt (title, reason): translated. """ + PT_NOTE + """
Do not use tools beyond what was given. Answer only with the requested JSON."""
@@ -535,6 +557,213 @@ names; translate the slang's meaning, e.g. "he's cooked" -> "ele tá ferrado").
as is. Answer only with the requested JSON."""
+# ---------------------------------------------------------------- JUIZ de contexto (doc/clipador/EQUIPE-IA.md)
+# Pedido do dono (18/11/2026): "não trazer corte sem sentido, principalmente em inglês". O juiz vê SÓ o que vai no
+# corte final (linha do tempo do trecho + 20 s antes marcados out=1), escreve primeiro o que um espectador frio
+# entenderia e depois responde sim/não. Quem decide pelas respostas é o código (context_judge.decide), não uma nota.
+CONTEXT_CHECKS = roles_module.CHECKS
+_CHECK = {"type": "object",
+ "properties": {"ok": {"type": "boolean"}, "t": {"type": ["number", "null"]}, "why": {"type": "string"}},
+ "required": ["ok", "t", "why"], "additionalProperties": False}
+CONTEXT_SCHEMA = {
+ "type": "object",
+ "properties": {
+ "viewer_summary": {"type": "string"},
+ "checks": {"type": "object", "properties": {c: _CHECK for c in CONTEXT_CHECKS}, "required": list(CONTEXT_CHECKS),
+ "additionalProperties": False},
+ "fix": {"type": "object",
+ "properties": {"start_s": {"type": ["number", "null"]}, "end_s": {"type": ["number", "null"]},
+ "context_line": {"type": "string"}},
+ "required": ["start_s", "end_s", "context_line"], "additionalProperties": False},
+ "confidence": {"type": "number"},
+ "reason": {"type": "string"},
+ },
+ "required": ["viewer_summary", "checks", "fix", "confidence", "reason"],
+ "additionalProperties": False,
+}
+CONTEXT_SCHEMA_EN = _with(CONTEXT_SCHEMA, pt={
+ "type": "object",
+ "properties": {"viewer_summary": {"type": "string"}, "reason": {"type": "string"}, "context_line": {"type": "string"},
+ "checks": _pt_block(*CONTEXT_CHECKS)},
+ "required": ["viewer_summary", "reason", "context_line", "checks"], "additionalProperties": False})
+
+CONTEXT_SYSTEM_EN = """You are the CONTEXT JUDGE of a live-stream clipping team. The editor already picked the segment and
+wrote the title. You check ONE thing: will someone who has NEVER seen this stream understand the clip and feel it makes
+sense on its own? You only get what the viewer will see: the clip's timeline (entries with out=1 are just BEFORE or AFTER
+the clip — the viewer does NOT see them; use them only to notice a missing setup or payoff), the title, caption and opening on-screen text, the
+intended story (from the analyst) and one line about the game.
+
+First write viewer_summary: what a cold viewer understands from the clip alone (1–2 sentences) — BEFORE the checks.
+Then answer every check with ok (true/false), t (second of the recording that is the evidence, or null) and why
+(up to 15 words):
+- setup: the clip includes the start of the situation the moment depends on. Fails if the key setup is only in the
+ out=1 entries before the clip (or earlier).
+- payoff: the clip includes the outcome/punchline/result (of the fight, escape, mission, joke). Fails if it ends before
+ (e.g. the result is only in the out=1 entries after the clip).
+- who_what: it is clear who is involved and what is happening.
+- standalone: it works without knowing earlier events of the stream, the channel's lore or inside jokes.
+- intelligible: the key line is in the transcript; fails if the important line is a teammate's/other player's that is
+ missing, or the streamer only reacts to something we never hear.
+- faithful: title/caption only claim what the clip shows ("caught a hacker" when he only accuses him = false).
+- strong_open: the first ~3 s already hook (not calm chatter).
+Red flags in English streams: references to things outside the clip ("that guy", "again", "like I said", "remember
+when", names never introduced), callbacks to donations/raids/subs, chat or channel inside jokes. Irony/slang ("he's
+cooked", "Clueless", "W") only counts if the screen confirms it.
+fix — only when a check fails and the timeline shows the answer: start_s (earlier, to include the setup) and/or end_s
+(later, to include the payoff; or earlier, to drop a tail that depends on other context), seconds of the recording,
+within the limits given; null when not needed. context_line: on-screen text for the first seconds (up to 8 words, in
+English) that gives a cold viewer the missing context (e.g. "Tfue tries to talk his way out of a robbery"); "" when not
+needed. Never invent facts.
+confidence: 0–1. reason: one sentence.
+pt: viewer_summary, reason, context_line and every check's why, translated. """ + PT_NOTE + """
+Do not use tools. Answer only with the requested JSON."""
+
+CONTEXT_SYSTEM = """Você é o JUIZ DE CONTEXTO de uma equipe de cortes de live. O editor já escolheu o trecho e escreveu o
+título. Você confere UMA coisa: alguém que NUNCA viu esta live entende o corte e sente que ele faz sentido sozinho?
+Você recebe só o que o espectador vai ver: a linha do tempo do corte (entradas com out=1 vêm logo ANTES ou DEPOIS do
+corte — o espectador NÃO as vê; use só para notar o começo ou o desfecho que faltam), título, legenda e texto de abertura na tela, a história
+pretendida (do analista) e uma linha sobre o jogo.
+
+Escreva primeiro viewer_summary: o que um espectador frio entende só com o corte (1–2 frases) — ANTES das checagens.
+Depois responda cada checagem com ok (true/false), t (segundo da gravação que é a evidência, ou null) e why (até 15
+palavras):
+- setup: o corte inclui o começo da situação de que o momento depende. Falha se o começo importante só está nas
+ entradas out=1 (ou antes).
+- payoff: o corte inclui o desfecho/resultado/piada (da treta, da fuga, da missão). Falha se termina antes (ex.: o
+ resultado só aparece nas entradas out=1 depois do corte).
+- who_what: dá para entender quem está envolvido e o que está acontecendo.
+- standalone: funciona sem saber o que aconteceu antes na live, a história do canal ou piadas internas.
+- intelligible: a fala principal está na transcrição; falha se ela é de um colega/outro jogador que não aparece, ou se
+ o streamer só reage a algo que não se ouve.
+- faithful: título/legenda só afirmam o que o corte mostra ("pegou um hacker" quando ele só acusa = falso).
+- strong_open: os ~3 primeiros segundos já prendem (não é conversa morna).
+Sinais de alerta: referência a algo fora do corte ("aquele cara", "de novo", "como eu falei", "lembra quando", nome
+nunca apresentado), menção a doação/raid/sub, piada interna do chat ou do canal. Ironia/gíria só vale se a tela
+confirma.
+fix — só quando uma checagem falha e a linha do tempo mostra a resposta: start_s (mais cedo, para incluir o começo) e/ou
+end_s (mais tarde, para incluir o desfecho; ou mais cedo, para tirar uma cauda que depende de outro contexto), em
+segundos da gravação, dentro dos limites informados; null quando não precisa. context_line: texto na tela para os
+primeiros segundos (até 8 palavras, no idioma do corte) que dá ao espectador frio o contexto que falta; "" se não
+precisa. Nunca invente fatos.
+confidence: 0–1. reason: uma frase.
+Não use ferramentas. Responda só com o JSON pedido."""
+
+
+def clean_context(data: dict) -> dict:
+ """Resposta do juiz normalizada: checagem ausente/inválida conta como "não respondida" (ok=True, sem motivo) —
+ o código não descarta por falta de resposta. Sem `checks` nem `viewer_summary` é erro de conteúdo."""
+ if not isinstance(data, dict) or not isinstance(data.get("checks"), dict) or "viewer_summary" not in data:
+ raise JudgeError("juiz sem viewer_summary/checks", unavailable=False)
+ checks = {}
+ for name in CONTEXT_CHECKS:
+ raw = data["checks"].get(name)
+ raw = raw if isinstance(raw, dict) else {}
+ t = raw.get("t")
+ checks[name] = {"ok": raw.get("ok") is not False,
+ "t": float(t) if isinstance(t, (int, float)) and not isinstance(t, bool) else None,
+ "why": str(raw.get("why") or "").strip()[:200]}
+ fix = data.get("fix") if isinstance(data.get("fix"), dict) else {}
+
+ def num(value):
+ return float(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else None
+
+ pt = data.get("pt") if isinstance(data.get("pt"), dict) else {}
+ pt_checks = pt.get("checks") if isinstance(pt.get("checks"), dict) else {}
+ try:
+ confidence = max(0.0, min(1.0, float(data.get("confidence", 0.5))))
+ except (TypeError, ValueError):
+ confidence = 0.5
+ out_pt = {k: str(pt.get(k) or "").strip()[:600] for k in ("viewer_summary", "reason", "context_line") if pt.get(k)}
+ if pt_checks:
+ out_pt["checks"] = {c: str(pt_checks.get(c) or "").strip()[:200] for c in CONTEXT_CHECKS if pt_checks.get(c)}
+ return {
+ "viewer_summary": str(data.get("viewer_summary") or "").strip()[:600],
+ "checks": checks,
+ "fix": {"start_s": num(fix.get("start_s")), "end_s": num(fix.get("end_s")),
+ "context_line": " ".join(str(fix.get("context_line") or "").split())[:80]},
+ "confidence": confidence,
+ "reason": str(data.get("reason") or "").strip()[:300],
+ "pt": out_pt,
+ }
+
+
+# ---------------------------------------------------------------- prompts com a linha do tempo (v1)
+def images_block(tiles: list[float], mosaic: bool, lang: str = "pt") -> str:
+ """O que vai anexado. `tiles` = instante de cada quadro (no mosaico, da esquerda para a direita, de cima para
+ baixo). As frases `lines[].n` da resposta se referem a esses números."""
+ if not tiles:
+ return "Images: none." if lang == "en" else "Imagens: nenhuma."
+ numbered = ", ".join(f"#{i + 1}={t:.0f}s" for i, t in enumerate(tiles))
+ if mosaic:
+ return (f"Attached: ONE mosaic image with {len(tiles)} frames in a grid (left→right, top→bottom): {numbered}."
+ if lang == "en" else
+ f"Anexo: UMA imagem em mosaico com {len(tiles)} quadros em grade (esquerda→direita, cima→baixo): {numbered}.")
+ return (f"Attached frames, in order: {numbered}." if lang == "en" else f"Frames anexados, em ordem: {numbered}.")
+
+
+def timeline_section(timeline_text: str, lang: str, streamer: str) -> str:
+ """Legenda das chaves + (se há fala de outra pessoa) a nota de quem fala + a linha do tempo."""
+ from .timeline import legend
+
+ me = (streamer or "streamer").replace("[", "(").replace("]", ")")
+ note = ""
+ if "[other" in timeline_text: # fala de outra pessoa no trecho (FALANTES.md): sem marca = o streamer
+ note = "\n" + SPEAKER_NOTE["en" if lang == "en" else "pt"].format(s=me).replace(f"[{me}]", "no tag")
+ return f"{legend(lang)}{note}\n{timeline_text}"
+
+
+def build_timeline_prompt(streamer: str, platform: str, start_s: float, end_s: float, peak_s: float,
+ heuristic: dict, *, context: str, timeline_text: str, tiles: list[float], mosaic: bool,
+ lo: float, hi: float, min_s: float, max_s: float, lang: str = "pt",
+ analysis: dict | None = None) -> str:
+ """Prompt do ANALISTA e do EDITOR no formato novo: cabeçalho + imagens + linha do tempo JSON (no lugar da
+ transcrição, do chat e da linha do rosto, que já estão dentro dela)."""
+ L, to = LABELS[lang], ("to" if lang == "en" else "a")
+ signals = {k: v for k, v in heuristic.items() if k not in ("topMessages", "face", "emotes")}
+ text = (f"{L['channel']}: {streamer} ({platform})\n{context}\n\n"
+ f"{L['window']}: {lo:.0f}s {to} {hi:.0f}s. {L['candidate']}: {start_s:.0f}s {to} {end_s:.0f}s; "
+ f"{L['peak']} {peak_s:.0f}s. {L['duration']}: {min_s:.0f} {to} {max_s:.0f} s.\n"
+ f"{L['signals']}: {json.dumps(signals, ensure_ascii=False, separators=(',', ':'))}\n"
+ f"{images_block(tiles, mosaic, lang)}\n\n{timeline_section(timeline_text, lang, streamer)}")
+ if analysis:
+ text += "\n\n" + analysis_block(analysis, lang)
+ return text
+
+
+def build_scan_timeline_prompt(streamer: str, platform: str, lo: float, hi: float, back_lo: float, context: str,
+ timeline_text: str, tiles: list[float], mosaic: bool,
+ existing: list[tuple[float, float, str]], min_s: float, max_s: float,
+ lang: str = "pt") -> str:
+ L, to = LABELS[lang], ("to" if lang == "en" else "a")
+ done = "; ".join(f"{a:.0f}–{b:.0f}s ({t[:40]})" for a, b, t in existing) or L["none"]
+ return (f"{L['channel']}: {streamer} ({platform})\n{context}\n\n"
+ f"{L['new_window']}: {lo:.0f}s {to} {hi:.0f}s ({L['back_to'].format(s=f'{back_lo:.0f}')}).\n"
+ f"{L['duration']}: {min_s:.0f} {to} {max_s:.0f} s. {L['done']}: {done}\n"
+ f"{images_block(tiles, mosaic, lang)}\n\n{timeline_section(timeline_text, lang, streamer)}")
+
+
+def build_context_prompt(*, streamer: str, game: str, game_line: str, start_s: float, end_s: float, title: str,
+ caption: str, opening: str, story: str, timeline_text: str, lo: float, hi: float,
+ min_s: float, max_s: float, lang: str = "pt") -> str:
+ """Prompt do JUIZ: só o que o espectador verá (e 20 s antes / 15 s depois, marcados out=1) + limites do ajuste."""
+ if lang == "en":
+ lines = [f"Game: {game or 'unknown'}" + (f" — {game_line}" if game_line else ""),
+ f"Streamer: {streamer}",
+ f"Clip the viewer will see: {start_s:.0f}s to {end_s:.0f}s ({end_s - start_s:.0f} s).",
+ f"Title: {title}", f"Caption: {caption or '(none)'}", f"Opening on-screen text: {opening or '(none)'}",
+ f"Intended story (analyst): {story or '(not available)'}",
+ f"Limits for a fix: start back to {lo:.0f}s at most, end up to {hi:.0f}s; duration {min_s:.0f} to {max_s:.0f} s."]
+ else:
+ lines = [f"Jogo: {game or 'desconhecido'}" + (f" — {game_line}" if game_line else ""),
+ f"Streamer: {streamer}",
+ f"Corte que o espectador verá: {start_s:.0f}s a {end_s:.0f}s ({end_s - start_s:.0f} s).",
+ f"Título: {title}", f"Legenda: {caption or '(nenhuma)'}", f"Texto de abertura na tela: {opening or '(nenhum)'}",
+ f"História pretendida (analista): {story or '(não disponível)'}",
+ f"Limites para o ajuste: início até {lo:.0f}s no máximo para trás, fim até {hi:.0f}s; duração de "
+ f"{min_s:.0f} a {max_s:.0f} s."]
+ return "\n".join(lines) + f"\n\n{timeline_section(timeline_text, lang, streamer)}"
+
+
def lang_key(language: str | None) -> str:
"""'en' para fonte em inglês (juízes em inglês); 'pt' para o resto (prompts em português + nota de saída)."""
return "en" if (language or "").strip().lower().startswith("en") else "pt"
@@ -611,6 +840,23 @@ def mission_lines(profile: dict, lang: str = "pt") -> list[str]:
return lines
+LEAN_LIMITS = {"clip_worthy": 6, "avoid": 4, "mechanics": 6, "jargon": 10, "news": 2}
+LEAN_ITEM_CHARS = 100
+
+
+def lean_profile(profile: dict | None) -> dict | None:
+ """Perfil enxuto para os prompts da linha do tempo (o perfil completo ia inteiro em TODA chamada: ~1.000
+ tokens no ROB RUN). Resumo em 2 frases, listas menores e itens curtos; missões seguem com o teto de sempre."""
+ if not profile:
+ return profile
+ out = dict(profile)
+ summary = str(profile.get("summary") or "")
+ out["summary"] = ". ".join(summary.split(". ")[:2]).strip()
+ for key, limit in LEAN_LIMITS.items():
+ out[key] = [str(item)[:LEAN_ITEM_CHARS] for item in (profile.get(key) or [])[:limit]]
+ return out
+
+
def game_context(game: str, screen_game: str, profile: dict | None, live_title: str, history: str = "",
confirmed: bool = False, lang: str = "pt") -> str:
if lang == "en":
@@ -852,14 +1098,70 @@ def codex_models(cache: Path | None = None) -> list[dict]:
return out or [{"id": DEFAULT_MODELS["codex"], "label": DEFAULT_MODELS["codex"]}]
+# ---------------------------------------------------------------- uso de tokens (F0: medir antes de otimizar)
+def _int(value) -> int | None:
+ try:
+ return int(value) if value is not None else None
+ except (TypeError, ValueError):
+ return None
+
+
+def codex_usage(stdout: str) -> dict | None:
+ """Uso do `codex exec --json` (eventos JSONL): o último evento com `usage` (`turn.completed`). None = não veio."""
+ found = None
+ for line in (stdout or "").splitlines():
+ line = line.strip()
+ if not line.startswith("{") or "input_tokens" not in line:
+ continue
+ try:
+ event = json.loads(line)
+ except json.JSONDecodeError:
+ continue
+ usage = event.get("usage") if isinstance(event, dict) else None
+ if not isinstance(usage, dict): # formato antigo: {"msg": {"type": "token_count", "info": {...}}}
+ info = ((event.get("msg") or {}).get("info") or {}) if isinstance(event, dict) else {}
+ usage = info.get("total_token_usage") or info.get("last_token_usage")
+ if isinstance(usage, dict) and "input_tokens" in usage:
+ found = {"in": _int(usage.get("input_tokens")), "out": _int(usage.get("output_tokens")),
+ "cached": _int(usage.get("cached_input_tokens"))}
+ return found
+
+
+def claude_usage(envelope: dict) -> dict | None:
+ """Uso do envelope `claude -p --output-format json`: entrada = nova + criação de cache + leitura de cache."""
+ usage = envelope.get("usage") if isinstance(envelope, dict) else None
+ if not isinstance(usage, dict):
+ return None
+ parts = [_int(usage.get(k)) or 0 for k in ("input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens")]
+ return {"in": sum(parts), "out": _int(usage.get("output_tokens")), "cached": _int(usage.get("cache_read_input_tokens"))}
+
+
+def gemini_usage(envelope: dict) -> dict | None:
+ """Uso do `gemini -o json` (`stats.models..tokens`), somado entre os modelos que a CLI usou."""
+ models = ((envelope or {}).get("stats") or {}).get("models") if isinstance(envelope, dict) else None
+ if not isinstance(models, dict) or not models:
+ return None
+ total = {"in": 0, "out": 0, "cached": 0}
+ for data in models.values():
+ tokens = (data or {}).get("tokens") or {}
+ total["in"] += _int(tokens.get("prompt")) or 0
+ total["out"] += (_int(tokens.get("candidates")) or 0) + (_int(tokens.get("thoughts")) or 0)
+ total["cached"] += _int(tokens.get("cached")) or 0
+ return total
+
+
# ---------------------------------------------------------------- IA
class Judge:
+ """As IAs da equipe (doc/clipador/EQUIPE-IA.md). Cada papel (varredura, analista, editor, juiz) tem provedor e
+ modelo próprios (`roles`); `provider`/`model` continuam existindo como a IA do EDITOR — a "principal", que também
+ faz os serviços gerais (pesquisa de jogo, tradução, câmera). `provider == "off"` desliga a equipe inteira."""
+
def __init__(self, provider: str, model: str, workdir: Path, analyst_model: str = "",
- ai: AiConfig | None = None, clock=time.time):
- self.provider = provider if provider in PROVIDERS else "codex"
- self.model = model or DEFAULT_MODELS.get(self.provider, "")
- # Modelo do ANALISTA (1º juiz, vê os frames). Vazio = o mesmo do editor.
- self.analyst_model = analyst_model
+ ai: AiConfig | None = None, clock=time.time, roles: dict | None = None):
+ legacy = provider if provider in PROVIDERS else "codex"
+ self._master = "off" if legacy == "off" else "on"
+ base = roles_module.default_roles(legacy if legacy != "off" else "codex", model, analyst_model)
+ self.roles = roles_module.normalize_roles(roles, base)
self.workdir = workdir
# Configurações → IA do painel (data/ai): login/chave por provedor e ordem da reserva.
self.ai = ai or AiConfig()
@@ -869,14 +1171,85 @@ class Judge:
self._pause_lock = threading.Lock()
# Quem respondeu a última chamada DESTA thread ("provedor:modelo"): o juiz roda em várias threads.
self._local = threading.local()
+ # Medição (F0): o motor liga isto para gravar cada chamada em `ai_calls`. None = não mede.
+ self.meter = None
- def configure(self, provider: str, model: str, analyst_model: str | None = None) -> None:
+ # ---------- papéis
+ @property
+ def provider(self) -> str:
+ return "off" if self._master == "off" else self.roles["editor"]["provider"]
+
+ @provider.setter
+ def provider(self, value: str) -> None:
+ """Compatível com o jeito antigo (um provedor só): "off" desliga a equipe; outro vale para todos os papéis."""
+ if value == "off":
+ self._master = "off"
+ return
+ if value not in AI_ENABLED:
+ raise JudgeError(f"provedor precisa ser um de {', '.join(PROVIDERS)}")
+ self._master = "on"
+ for role in self.roles.values():
+ if role["provider"] != value:
+ role["provider"], role["model"] = value, ""
+
+ @property
+ def model(self) -> str:
+ return self.role_model("editor")
+
+ @property
+ def analyst_model(self) -> str:
+ return self.roles["analyst"]["model"]
+
+ def role_model(self, role: str) -> str:
+ conf = self.roles[role]
+ return conf["model"] or DEFAULT_MODELS.get(conf["provider"], "")
+
+ def role_enabled(self, role: str) -> bool:
+ return self.enabled and bool(self.roles[role]["enabled"])
+
+ def system_for(self, role: str, base: str, lang: str = "pt") -> str:
+ """Instruções padrão do papel + as do administrador (somadas, nunca no lugar)."""
+ return base + roles_module.admin_notes(self.roles.get(role) or {}, lang)
+
+ def configure(self, provider: str, model: str, analyst_model: str | None = None, roles: dict | None = None) -> None:
+ """`roles` = configuração por papel (painel novo). Sem ela (painel antigo): `provider`/`model` valem para
+ todos os papéis e `analyst_model` para o analista. `provider == "off"` desliga a equipe."""
if provider not in PROVIDERS:
raise JudgeError(f"provedor precisa ser um de {', '.join(PROVIDERS)}")
- self.provider = provider
- self.model = model.strip() or DEFAULT_MODELS.get(provider, "")
+ if roles is not None:
+ self.roles = roles_module.normalize_roles(roles, self.roles)
+ self._master = "off" if provider == "off" else "on"
+ return
+ if provider == "off":
+ self._master = "off"
+ return
+ self._master = "on"
+ model = model.strip()
+ for name, role in self.roles.items():
+ role["provider"] = provider
+ role["model"] = "" if model == DEFAULT_MODELS.get(provider) else model
if analyst_model is not None:
- self.analyst_model = analyst_model.strip()
+ self.roles["analyst"]["model"] = analyst_model.strip()
+ 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."""
+ 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 []
+ out[name] = conf
+ return out
+
+ @staticmethod
+ def default_instructions() -> dict:
+ """Texto padrão de cada papel nos dois idiomas (o painel mostra só para leitura)."""
+ return {"scan": {"pt": SCAN_SYSTEM, "en": SCAN_SYSTEM_EN},
+ "analyst": {"pt": ANALYST_SYSTEM, "en": ANALYST_SYSTEM_EN},
+ "editor": {"pt": JUDGE_SYSTEM, "en": JUDGE_SYSTEM_EN},
+ "judge": {"pt": CONTEXT_SYSTEM, "en": CONTEXT_SYSTEM_EN}}
@property
def enabled(self) -> bool:
@@ -889,6 +1262,16 @@ class Judge:
""""provedor:modelo" de quem respondeu a última chamada desta thread (a reserva pode ter respondido)."""
return getattr(self._local, "responder", None) or f"{self.provider}:{self.model}"
+ @contextmanager
+ def scope(self, **context):
+ """Contexto das chamadas desta thread para a medição (`session_id`, `clip_id`, `mode`)."""
+ previous = getattr(self._local, "scope", None) or {}
+ self._local.scope = {**previous, **context}
+ try:
+ yield
+ finally:
+ self._local.scope = previous
+
# ---------- reserva
def pauses(self) -> dict[str, tuple[float, str]]:
"""Pausas ainda valendo (as vencidas saem)."""
@@ -916,17 +1299,18 @@ class Judge:
return "modo chave de API sem chave no cofre"
return None
- def fallback_chain(self) -> list[str]:
- """Ordem em que `ask` tenta as IAs: a escolhida no juiz 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.
+ def fallback_chain(self, primary: str | 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)."""
if not self.enabled:
return []
+ primary = primary if primary in AI_ENABLED else self.provider
settings = self.ai.settings()
- candidates = [self.provider]
+ candidates = [primary]
if settings["fallback"]["enabled"]:
- candidates += [p for p in settings["order"] if p != self.provider 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]
if not settings["fallback"]["enabled"]:
return ready
@@ -941,7 +1325,7 @@ class Judge:
settings = self.ai.settings()
primary_skip = self._skip_reason(self.provider, settings) if self.enabled else None
return {"provider": self.provider, "model": self.model if self.enabled else None,
- "analystModel": (self.analyst_model or 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,
# Por que a escolhida não roda (desligada no painel, sem CLI, sem chave); None = pronta.
"unavailableReason": primary_skip,
@@ -950,18 +1334,24 @@ class Judge:
"cooldownMin": settings["fallback"]["cooldownMin"],
"chain": self.fallback_chain()},
"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).
+ "roles": self.roles_view(),
+ "providers": {p: {"ready": self._skip_reason(p, settings) is None,
+ "reason": self._skip_reason(p, settings),
+ "enabled": bool((settings["providers"].get(p) or {}).get("enabled"))}
+ for p in AI_ENABLED}}
def models(self) -> dict:
return {"codex": codex_models(), "claude": CLAUDE_MODELS, "gemini": GEMINI_MODELS, "defaults": DEFAULT_MODELS}
# ---------- usos
def analyze(self, prompt: str, images: list[Path], lang: str = "pt") -> dict:
- """1º juiz (ANALISTA): o que aconteceu, cruzando tela + fala + chat. Não decide nem escreve título.
+ """ANALISTA: o que aconteceu, cruzando tela + fala + chat. Não decide nem escreve título.
`lang="en"`: prompt em inglês e bloco `pt` (tradução para o painel) na mesma resposta."""
system, schema = (ANALYST_SYSTEM_EN, ANALYSIS_SCHEMA_EN) if lang == "en" else (ANALYST_SYSTEM, ANALYSIS_SCHEMA)
- data = self.ask(system, prompt, schema, images, model=self.analyst_model or self.model)
- missing = [k for k in ANALYSIS_SCHEMA["required"] if k not in data]
+ data = self.ask(self.system_for("analyst", system, lang), prompt, schema, images, role="analyst")
+ missing = [k for k in ANALYSIS_SCHEMA["required"] if k not in data and k not in ANALYSIS_OPTIONAL]
if missing:
raise JudgeError(f"análise sem os campos {missing}")
data["confidence"] = max(0.0, min(1.0, float(data["confidence"])))
@@ -970,18 +1360,26 @@ class Judge:
def judge(self, prompt: str, start_s: float, end_s: float, images: list[Path] | None = None, *,
lo: float | None = None, hi: float | None = None, min_s: float = DEFAULT_MIN_S,
max_s: float = DEFAULT_MAX_S, lang: str = "pt") -> Verdict:
+ """EDITOR: decide se vira corte, o trecho, título, legenda e hashtags."""
system, schema = (JUDGE_SYSTEM_EN, VERDICT_SCHEMA_EN) if lang == "en" else (JUDGE_SYSTEM, VERDICT_SCHEMA)
- data = self.ask(system, prompt, schema, images or [])
+ data = self.ask(self.system_for("editor", system, lang), prompt, schema, images or [], role="editor")
# Modelo de quem DE FATO respondeu (a reserva pode ter entrado no lugar da escolhida).
return _clean(data, start_s, end_s, self.responder(), lo, hi, min_s, max_s)
+ def check_context(self, prompt: str, lang: str = "pt") -> dict:
+ """JUIZ de contexto (só texto): o que um espectador frio entende + as checagens sim/não. Quem decide pelas
+ respostas é o código (`context_judge.decide`)."""
+ system, schema = (CONTEXT_SYSTEM_EN, CONTEXT_SCHEMA_EN) if lang == "en" else (CONTEXT_SYSTEM, CONTEXT_SCHEMA)
+ data = self.ask(self.system_for("judge", system, lang), prompt, schema, [], role="judge")
+ return clean_context(data)
+
def translate_lines(self, lines: list[str]) -> list[str]:
"""Fala de um corte (frases em ordem) → português, mesma quantidade. Para o painel e a legenda de
desenvolvimento; o vídeo publicado continua no idioma da fonte."""
if not lines:
return []
prompt = "\n".join(f"{i + 1}. {text}" for i, text in enumerate(lines))
- data = self.ask(LINES_SYSTEM, prompt, LINES_SCHEMA, [])
+ data = self.ask(LINES_SYSTEM, prompt, LINES_SCHEMA, [], purpose="translate")
out = [str(x).strip() for x in (data.get("lines") or [])]
if len(out) != len(lines):
raise JudgeError(f"tradução com {len(out)} linhas para {len(lines)} frases", unavailable=False)
@@ -989,7 +1387,7 @@ class Judge:
def scan(self, prompt: str, images: list[Path], lang: str = "pt") -> dict:
system, schema = (SCAN_SYSTEM_EN, SCAN_SCHEMA_EN) if lang == "en" else (SCAN_SYSTEM, SCAN_SCHEMA)
- data = self.ask(system, prompt, schema, images)
+ data = self.ask(self.system_for("scan", system, lang), prompt, schema, images, role="scan")
if not isinstance(data.get("moments"), list):
raise JudgeError("varredura sem a lista de momentos")
return data
@@ -999,7 +1397,8 @@ class Judge:
if notes:
prompt += "User requests (respect them; may be in Portuguese):\n" + "\n".join(f"- {n}" for n in notes) + "\n"
prompt += "Research and return the game profile in English."
- return self.ask(PROFILE_SYSTEM, prompt, PROFILE_SCHEMA, [], search=True, timeout=RESEARCH_TIMEOUT_S)
+ return self.ask(PROFILE_SYSTEM, prompt, PROFILE_SCHEMA, [], search=True, timeout=RESEARCH_TIMEOUT_S,
+ purpose="research")
def refine_game(self, name: str, profile: dict, instruction: str, search: bool = True, section: str = "",
history: list[dict] | None = None) -> dict:
@@ -1013,39 +1412,48 @@ class Judge:
f"{'User' if h.get('role') == 'user' else 'AI'}: {str(h.get('text', ''))[:400]}" for h in history[-8:]) + "\n"
prompt += f"User REQUEST:\n{instruction}\n\nReturn the complete updated profile (English) and the reply (Portuguese)."
return self.ask(REFINE_SYSTEM, prompt, REFINE_SCHEMA, [], search=search,
- timeout=RESEARCH_TIMEOUT_S if search else TIMEOUT_S)
+ timeout=RESEARCH_TIMEOUT_S if search else TIMEOUT_S, purpose="research")
def translate_game(self, profile: dict, target: str) -> dict:
"""Traduz o perfil inteiro (pt-BR <-> en-US), mesmo formato, sem busca. Nomes oficiais e hashtags ficam."""
language = TRANSLATE_TARGETS.get(target, target)
prompt = (f"Target language: {language}\nProfile JSON:\n{json.dumps(profile, ensure_ascii=False, indent=1)}\n\n"
"Return the translated profile.")
- return self.ask(TRANSLATE_SYSTEM, prompt, PROFILE_SCHEMA, [], timeout=RESEARCH_TIMEOUT_S)
+ return self.ask(TRANSLATE_SYSTEM, prompt, PROFILE_SCHEMA, [], timeout=RESEARCH_TIMEOUT_S, purpose="translate")
def detect_cam(self, images: list[Path]) -> dict:
- return self.ask(CAM_SYSTEM, "Analise os frames anexados (mesma live, instantes diferentes).", CAM_SCHEMA, images)
+ return self.ask(CAM_SYSTEM, "Analise os frames anexados (mesma live, instantes diferentes).", CAM_SCHEMA, images,
+ purpose="cam")
# ---------- execução
def ask(self, system: str, prompt: str, schema: dict, images: list[Path], *, search: bool = False,
- timeout: int = TIMEOUT_S, model: str | None = None) -> dict:
- """Chama a IA escolhida; se ela falhar por indisponibilidade, a próxima da cadeia de reserva (com o modelo
- padrão DELA) e a que falhou fica em pausa. Erro de conteúdo (JSON inválido, campos faltando) não troca."""
+ timeout: int = TIMEOUT_S, model: str | None = None, role: str = "editor", purpose: str | None = None) -> dict:
+ """Chama a IA do papel `role`; se ela falhar por indisponibilidade, a próxima da cadeia de reserva (com o
+ modelo padrão DELA) e a que falhou fica em pausa. Erro de conteúdo (JSON inválido, campos faltando) não troca.
+ Cada tentativa é medida (`meter`), com o papel, a IA, o tamanho do prompt e das imagens e os tokens."""
if not self.enabled:
raise JudgeError("IA desligada", unavailable=False)
- chain = self.fallback_chain()
+ conf = self.roles.get(role) or self.roles["editor"]
+ primary = conf["provider"]
+ chain = self.fallback_chain(primary)
if not chain:
- why = self._skip_reason(self.provider, self.ai.settings()) or "nenhuma IA pronta"
- raise JudgeError(f"{PROVIDER_NAMES[self.provider]} indisponível: {why} (veja Configurações → IA)",
+ why = self._skip_reason(primary, self.ai.settings()) or "nenhuma IA pronta"
+ raise JudgeError(f"{PROVIDER_NAMES.get(primary, primary)} indisponível: {why} (veja Configurações → IA)",
unavailable=True)
fallback_on = self.ai.settings()["fallback"]["enabled"]
attempts: list[str] = []
for provider in chain:
- use_model = (model or self.model) if provider == self.provider else DEFAULT_MODELS[provider]
+ use_model = (model or self.role_model(role if role in self.roles else "editor")) if provider == primary \
+ else DEFAULT_MODELS[provider]
+ effort = conf.get("effort", "") if provider == primary else ""
+ self._local.usage = None
+ started = time.monotonic()
try:
- data = self._call(provider, system, prompt, schema, images, search, timeout, use_model)
+ data = self._call(provider, system, prompt, schema, images, search, timeout, use_model, effort)
except JudgeError as exc:
text = str(exc)
unavailable = exc.unavailable if exc.unavailable is not None else is_availability_error(text)
+ self._measure(role, purpose, provider, use_model, system, prompt, images, started, text)
attempts.append(f"{provider}:{use_model}: {text}")
if not unavailable:
# Erro de conteúdo: a IA respondeu, o pedido é que não deu certo. Não troca de IA.
@@ -1055,16 +1463,38 @@ class Judge:
log.warning("IA %s indisponível (%s); tentando a reserva", provider, text[:160])
continue
raise JudgeError(text, unavailable=True) from exc
+ self._measure(role, purpose, provider, use_model, system, prompt, images, started, None)
self._local.responder = f"{provider}:{use_model}"
- if provider != self.provider:
+ if provider != primary:
log.info("respondido pela reserva %s:%s", provider, use_model)
return data
raise JudgeError("nenhuma IA respondeu — " + " · ".join(attempts)[:900], unavailable=True)
+ def _measure(self, role: str, purpose: str | None, provider: str, model: str, system: str, prompt: str,
+ images: list[Path], started: float, error: str | None) -> None:
+ if self.meter is None:
+ return
+ image_bytes = 0
+ for img in images:
+ try:
+ image_bytes += Path(img).stat().st_size
+ except OSError:
+ pass
+ usage = getattr(self._local, "usage", None) or {}
+ record = {"role": role, "purpose": purpose or role, "provider": provider, "model": model, "ok": error is None,
+ "error": (error or "")[:300] or None, "ms": int((time.monotonic() - started) * 1000),
+ "systemChars": len(system), "promptChars": len(prompt), "images": len(images),
+ "imageBytes": image_bytes, "tokensIn": usage.get("in"), "tokensOut": usage.get("out"),
+ "tokensCached": usage.get("cached"), **(getattr(self._local, "scope", None) or {})}
+ try:
+ self.meter(record)
+ except Exception as exc: # noqa: BLE001 - medir nunca derruba a chamada
+ log.debug("medição da chamada falhou: %s", exc)
+
def _call(self, provider: str, system: str, prompt: str, schema: dict, images: list[Path], search: bool,
- timeout: int, model: str) -> dict:
+ timeout: int, model: str, effort: str = "") -> dict:
if provider == "codex":
- return self._codex(system, prompt, schema, images, search, timeout, model)
+ return self._codex(system, prompt, schema, images, search, timeout, model, effort)
if provider == "claude":
return self._claude(system, prompt, schema, images, search, timeout, model)
if provider == "gemini":
@@ -1090,7 +1520,7 @@ class Judge:
return result
def _codex(self, system: str, prompt: str, schema: dict, images: list[Path], search: bool, timeout: int,
- model: str) -> dict:
+ model: str, effort: str = "") -> dict:
cmd = find_codex()
if not cmd:
raise JudgeError("Codex CLI não encontrado (npm install -g @openai/codex; codex login)", unavailable=True)
@@ -1109,12 +1539,16 @@ class Judge:
instructions.write_text(system, encoding="utf-8")
lean += ["-c", f"model_instructions_file='{instructions}'"]
stdin = prompt
+ # Esforço de raciocínio por papel (Equipe de IA); padrão = low, o de sempre.
+ reasoning = effort if effort in ("low", "medium", "high") else "low"
# `--search` é opção global (antes de `exec`). Cada imagem com seu `-i`; o "-" (prompt pela entrada
# padrão) vem depois de uma opção de valor único para não ser lido como mais uma imagem.
+ # `--json`: eventos JSONL na saída padrão — o `turn.completed` traz o uso de tokens (medição F0).
args = [*cmd, *(["--search"] if search else []), "exec", "--skip-git-repo-check", "--ephemeral",
- "--sandbox", "read-only", "-c", 'model_reasoning_effort="low"', *lean, "-m", model, *image_args,
- "--output-schema", str(schema_file), "-o", str(out), "-C", tmp, "-"]
- self._run(args, stdin, Path(tmp), timeout, "codex")
+ "--sandbox", "read-only", "--json", "-c", f'model_reasoning_effort="{reasoning}"', *lean,
+ "-m", model, *image_args, "--output-schema", str(schema_file), "-o", str(out), "-C", tmp, "-"]
+ result = self._run(args, stdin, Path(tmp), timeout, "codex")
+ self._local.usage = codex_usage(result.stdout.decode("utf-8", errors="replace"))
try:
return json.loads(out.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as exc:
@@ -1144,6 +1578,7 @@ class Judge:
envelope = json.loads(result.stdout.decode("utf-8", errors="replace"))
except json.JSONDecodeError as exc:
raise JudgeError("o Claude não devolveu JSON", unavailable=False) from exc
+ self._local.usage = claude_usage(envelope)
if envelope.get("is_error"):
# Pode ser cota/login ("Credit balance is too low", "Not logged in"): o texto decide (unavailable=None).
raise JudgeError(f"o Claude terminou com erro: {str(envelope.get('result'))[:200]}")
@@ -1190,7 +1625,9 @@ class Judge:
short += " Frames anexados, na ordem: " + " ".join(refs)
args = [*cmd, "-p", short, "-o", "json", "--approval-mode", "plan", "--skip-trust", "-m", model]
result = self._run(args, stdin, Path(tmp), timeout, "gemini")
- return parse_gemini_output(result.stdout.decode("utf-8", errors="replace"))
+ stdout = result.stdout.decode("utf-8", errors="replace")
+ self._local.usage = gemini_usage(extract_json_object(stdout, fences=False) or {})
+ return parse_gemini_output(stdout)
def parse_gemini_output(stdout: str) -> dict:
diff --git a/clipper/app/main.py b/clipper/app/main.py
index d265fc1..70e1c55 100644
--- a/clipper/app/main.py
+++ b/clipper/app/main.py
@@ -25,7 +25,7 @@ from .scoring import Word
from .sources import SourceError, parse_source
from .subtitles import build_ass
from .worker import Engine
-from . import clip_delete, editor_api
+from . import clip_delete, editor_api, report
VERSION = "1.0.0"
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
@@ -96,6 +96,12 @@ class JudgeIn(BaseModel):
camDetect: bool | None = None
# Rastreio do rosto do streamer (face.py): reforça/cria cortes e vai em texto para o analista.
faceTrack: bool | None = None
+ # A IA lê o vídeo como linha do tempo JSON curta (novo); False = transcrição + chat + frames soltos (antigo).
+ timelineJson: bool | None = None
+ # Equipe de IA (doc/clipador/EQUIPE-IA.md): {scan|analyst|editor|judge: {enabled, provider, model, effort, extra,
+ # images, critical, allowFix, allowContextLine, penalty}}. None = não mexer (painel antigo: provider/model valem
+ # para todos os papéis). Validado campo a campo em roles.normalize_roles.
+ roles: dict | None = None
class GameIn(BaseModel):
@@ -152,6 +158,10 @@ class PreviewIn(BaseModel):
class ClipPatch(BaseModel):
status: Literal["approved", "rejected", "ready", "published"] | None = None
+ # Avaliação do dono (conjunto de avaliação do juiz): bom / ruim / sem contexto; "" limpa. Rejeitar com
+ # label "no_context" = "rejeitado: sem contexto".
+ label: Literal["good", "bad", "no_context", ""] | None = None
+ labelNote: str | None = Field(default=None, max_length=300)
title: str | None = Field(default=None, max_length=100)
caption: str | None = Field(default=None, max_length=2200)
startS: float | None = Field(default=None, ge=0)
@@ -194,6 +204,8 @@ def clip_view(row: dict) -> dict:
# e nos cortes de antes da migração v8, vale o padrão `vertical`.
"aspect": row.get("aspect") or "vertical",
"createdAt": row["created_at"], "updatedAt": row["updated_at"],
+ # Avaliação do dono (bom / ruim / sem contexto) para medir o juiz; None = não marcou.
+ "ownerLabel": row.get("owner_label"), "ownerNote": row.get("owner_note"),
"channelId": row.get("channel_id"), "platform": row.get("platform"), "sessionUrl": row.get("url"),
# Idioma da sessão (resolvido no SELECT: o da sessão ou o padrão do serviço). Ausente só em consultas antigas.
"language": row.get("language"),
@@ -306,18 +318,25 @@ def create_app(settings: Settings | None = None, engine: Engine | None = None, s
# ---------- juiz (IA pela CLI: Codex/GPT ou Claude)
@app.get("/v1/judge")
def get_judge():
- return engine.judge_config() | {"models": engine.judge.models()}
+ return engine.judge_config(full=True) | {"models": engine.judge.models()}
@app.put("/v1/judge")
def put_judge(body: JudgeIn):
try:
engine.intel.set_options({"scanEnabled": body.scanEnabled, "scanIntervalS": body.scanIntervalS,
- "vision": body.vision, "camDetect": body.camDetect, "faceTrack": body.faceTrack})
- return engine.set_judge_config(body.provider, body.model, body.minScore, body.analystModel) | {
+ "vision": body.vision, "camDetect": body.camDetect, "faceTrack": body.faceTrack,
+ "timelineJson": body.timelineJson})
+ return engine.set_judge_config(body.provider, body.model, body.minScore, body.analystModel, body.roles) | {
"models": engine.judge.models()}
except JudgeError as exc:
raise UserError(str(exc)) from exc
+ @app.get("/v1/judge/report")
+ def judge_report(days: float = Query(default=7, gt=0, le=365), session: int | None = None):
+ """Medição da Equipe de IA (F0): chamadas e tokens por papel/IA, por hora de live; taxa de aprovação; o que o
+ juiz de contexto decidiu; e a concordância juiz × dono nos cortes que você avaliou."""
+ return report.build(db, days=days, session_id=session)
+
# ---------- configuração do corte (layout, câmera, legenda, crédito, duração)
def _settings_payload(own: dict, channel_layer: dict | None, session_layer: dict | None) -> dict:
return {"own": own, "effective": layout.merge(channel_layer, session_layer), "defaults": layout.DEFAULTS,
@@ -763,6 +782,11 @@ def create_app(settings: Settings | None = None, engine: Engine | None = None, s
status = body.status or row["status"]
if body.status in ("approved", "published") and row["status"] not in ("ready", "approved", "published"):
raise UserError("Só dá para aprovar um corte já renderizado.")
+ if body.label is not None or body.labelNote is not None:
+ # Avaliação do dono: vale para qualquer corte (inclusive antigos e descartados), sem mexer no estado.
+ label = row.get("owner_label") if body.label is None else (body.label or None)
+ note = row.get("owner_note") if body.labelNote is None else (body.labelNote.strip() or None)
+ db.run("UPDATE clips SET owner_label = ?, owner_note = ? WHERE id = ?", label, note, clip_id)
if retime:
status = "pending" # novo trecho → renderiza de novo
db.run("UPDATE clips SET title = ?, caption = ?, start_s = ?, end_s = ?, status = ?, updated_at = ? WHERE id = ?",
diff --git a/clipper/app/media.py b/clipper/app/media.py
index 26e0d87..ba6b3db 100644
--- a/clipper/app/media.py
+++ b/clipper/app/media.py
@@ -153,6 +153,43 @@ def grab_frame(ffmpeg: str, segments: list[tuple[Path, float, float]], t: float,
return out_file
+MOSAIC_TILE_W, MOSAIC_TILE_H = 384, 216
+MOSAIC_COLS, MOSAIC_ROWS = 4, 2
+
+
+def mosaic(ffmpeg: str, images: list[Path], out_file: Path, cols: int = MOSAIC_COLS, rows: int = MOSAIC_ROWS,
+ tile_w: int = MOSAIC_TILE_W, tile_h: int = MOSAIC_TILE_H) -> Path:
+ """Vários quadros numa imagem só (grade `cols`×`rows`, da esquerda para a direita e de cima para baixo), cada um
+ em `tile_w`×`tile_h` (barras pretas se o quadro não for 16:9). Com menos quadros que a grade, a grade encolhe
+ (até 4 → uma linha só). Para a IA: 1 imagem no lugar de 8 (Claude = 1 leitura; Gemini cobra por imagem)."""
+ images = [Path(p) for p in images][: cols * rows]
+ if not images:
+ raise MediaError("mosaico sem quadros")
+ n = len(images)
+ if n <= cols:
+ cols, rows = n, 1
+ else:
+ rows = math.ceil(n / cols)
+ out_file.parent.mkdir(parents=True, exist_ok=True)
+ inputs = [arg for img in images for arg in ("-i", str(img))]
+ fit = (f"scale={tile_w}:{tile_h}:force_original_aspect_ratio=decrease,"
+ f"pad={tile_w}:{tile_h}:(ow-iw)/2:(oh-ih)/2,setsar=1")
+ chains = [f"[{i}:v]{fit}[t{i}]" for i in range(n)]
+ # Grade incompleta (ex.: 6 quadros em 4×2): completa com quadro preto do mesmo tamanho.
+ pads = cols * rows - n
+ for k in range(pads):
+ chains.append(f"color=c=black:s={tile_w}x{tile_h}:d=1[p{k}]")
+ labels = [f"[t{i}]" for i in range(n)] + [f"[p{k}]" for k in range(pads)]
+ layout_cells = "|".join(f"{(i % cols) * tile_w}_{(i // cols) * tile_h}" for i in range(cols * rows))
+ if cols * rows == 1:
+ graph = chains[0].replace("[t0]", "[out]")
+ else:
+ graph = ";".join(chains) + ";" + "".join(labels) + f"xstack=inputs={cols * rows}:layout={layout_cells}[out]"
+ run([ffmpeg, "-y", "-v", "error", *inputs, "-filter_complex", graph, "-map", "[out]", "-frames:v", "1",
+ "-q:v", "4", str(out_file)], 60)
+ return out_file
+
+
def preview_still(ffmpeg: str, frame_file: Path, settings: dict, ass_text: str, out_file: Path, reframe=None) -> Path:
"""Prévia do layout num quadro só (imagem no formato do corte com câmera, jogo, legenda e crédito de exemplo).
`reframe` = reenquadramento parado do jogo (capa de um corte com keyframes; ver `reframe.static_reframe`)."""
diff --git a/clipper/app/report.py b/clipper/app/report.py
new file mode 100644
index 0000000..d231aae
--- /dev/null
+++ b/clipper/app/report.py
@@ -0,0 +1,145 @@
+"""Relatório da Equipe de IA (F0 — medir antes de otimizar; doc/clipador/EQUIPE-IA.md).
+
+`GET /v1/judge/report?days=7[&session=N]`:
+- `calls`: por papel × IA × modelo × modo (linha do tempo/antigo, mosaico/frames): chamadas, falhas, tamanho médio do
+ prompt, imagens, tokens (quando a CLI informa) e tempo médio;
+- `perHour`: chamadas e tokens por hora de live gravada no período (por papel);
+- `clips`: cortes do período por estado e a taxa de aprovação do dono;
+- `judge`: o que o juiz de contexto decidiu (aprovou, ajustou, descartou, avisou, erro, frase de contexto);
+- `agreement`: concordância juiz × dono (e editor × dono) nos cortes que o dono avaliou.
+
+Veredito do dono: `owner_label` (bom / ruim / sem contexto) quando marcado; senão aprovado/publicado = bom e
+rejeitado = ruim. Veredito do juiz: aprovou/ajustou/avisou = mantém; descartou = descarta.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from .db import Database, loads
+
+KEEP_DECISIONS = ("approve", "adjust", "warn")
+
+
+def _since(days: float) -> str:
+ return (datetime.now(timezone.utc) - timedelta(days=days)).isoformat(timespec="seconds")
+
+
+def owner_verdict(row: dict) -> str | None:
+ """good | bad | no_context | None (o dono ainda não disse)."""
+ if row.get("owner_label"):
+ return row["owner_label"]
+ if row["status"] in ("approved", "published"):
+ return "good"
+ if row["status"] == "rejected":
+ return "bad"
+ return None
+
+
+def judge_verdict(judge: dict) -> str | None:
+ """keep | discard | None (juiz não rodou ou falhou)."""
+ context = (judge or {}).get("context") if isinstance(judge, dict) else None
+ if not isinstance(context, dict) or context.get("error"):
+ return None
+ decision = context.get("decision")
+ if decision in KEEP_DECISIONS:
+ return "keep"
+ return "discard" if decision == "discard" else None
+
+
+def editor_verdict(judge: dict) -> str | None:
+ if not isinstance(judge, dict) or "keep" not in judge:
+ return None
+ return "keep" if judge.get("keep") else "discard"
+
+
+def agreement(pairs: list[tuple[str, str]]) -> dict:
+ """Concordância (e kappa de Cohen) entre "mantém/descarta" da IA e "bom/ruim" do dono ("sem contexto" = ruim)."""
+ matrix = {"keep": {"good": 0, "bad": 0, "no_context": 0}, "discard": {"good": 0, "bad": 0, "no_context": 0}}
+ for ai, owner in pairs:
+ matrix[ai][owner] += 1
+ n = len(pairs)
+ if not n:
+ return {"pairs": 0, "agree": 0, "rate": None, "kappa": None, "matrix": matrix}
+ agree = matrix["keep"]["good"] + matrix["discard"]["bad"] + matrix["discard"]["no_context"]
+ p_keep = (sum(matrix["keep"].values())) / n
+ p_good = (matrix["keep"]["good"] + matrix["discard"]["good"]) / n
+ pe = p_keep * p_good + (1 - p_keep) * (1 - p_good)
+ po = agree / n
+ kappa = None if pe >= 1 else round((po - pe) / (1 - pe), 3)
+ return {"pairs": n, "agree": agree, "rate": round(po, 3), "kappa": kappa, "matrix": matrix}
+
+
+def build(db: Database, days: float = 7, session_id: int | None = None) -> dict:
+ since = _since(days)
+ call_where, call_args = ("session_id = ?", [session_id]) if session_id else ("at >= ?", [since])
+ rows = db.all(
+ "SELECT role, purpose, provider, model, COALESCE(mode, '') AS mode, COUNT(*) AS calls, SUM(ok) AS ok,"
+ " AVG(COALESCE(system_chars, 0) + COALESCE(prompt_chars, 0)) AS avg_chars, AVG(images) AS avg_images,"
+ " SUM(COALESCE(image_bytes, 0)) AS image_bytes, SUM(tokens_in) AS tokens_in, SUM(tokens_out) AS tokens_out,"
+ " SUM(tokens_cached) AS tokens_cached, SUM(CASE WHEN tokens_in IS NOT NULL THEN 1 ELSE 0 END) AS with_usage,"
+ " AVG(ms) AS avg_ms FROM ai_calls WHERE " + call_where +
+ " GROUP BY role, purpose, provider, model, mode ORDER BY role, calls DESC", *call_args)
+ calls = [{"role": r["role"], "purpose": r["purpose"], "provider": r["provider"], "model": r["model"],
+ "mode": r["mode"], "calls": r["calls"], "failures": r["calls"] - (r["ok"] or 0),
+ "avgChars": round(r["avg_chars"] or 0), "avgImages": round(r["avg_images"] or 0, 2),
+ "imageKB": round((r["image_bytes"] or 0) / 1024), "tokensIn": r["tokens_in"], "tokensOut": r["tokens_out"],
+ "tokensCached": r["tokens_cached"], "withUsage": r["with_usage"], "avgMs": round(r["avg_ms"] or 0)}
+ for r in rows]
+
+ session_where, session_args = ("id = ?", [session_id]) if session_id else ("started_at >= ?", [since])
+ live_s = db.get(f"SELECT COALESCE(SUM(duration_s), 0) AS s FROM sessions WHERE {session_where}", *session_args)["s"]
+ hours = live_s / 3600
+ per_role: dict[str, dict] = {}
+ for c in calls:
+ item = per_role.setdefault(c["role"], {"calls": 0, "tokensIn": 0, "tokensOut": 0, "withUsage": 0, "chars": 0})
+ item["calls"] += c["calls"]
+ item["tokensIn"] += c["tokensIn"] or 0
+ item["tokensOut"] += c["tokensOut"] or 0
+ item["withUsage"] += c["withUsage"]
+ item["chars"] += c["avgChars"] * c["calls"]
+ per_hour = {role: {"calls": round(v["calls"] / hours, 1) if hours else None,
+ "tokensIn": round(v["tokensIn"] / hours) if hours and v["withUsage"] else None,
+ "tokensOut": round(v["tokensOut"] / hours) if hours and v["withUsage"] else None,
+ # Estimativa pelo tamanho do texto (~4 caracteres por token), para quando a CLI não informa.
+ "estTokensIn": round(v["chars"] / 4 / hours) if hours else None}
+ for role, v in per_role.items()}
+
+ clip_where, clip_args = ("session_id = ?", [session_id]) if session_id else ("created_at >= ?", [since])
+ clips = db.all(f"SELECT id, status, judge_json, owner_label FROM clips WHERE {clip_where}", *clip_args)
+ by_status: dict[str, int] = {}
+ decisions = {"approve": 0, "adjust": 0, "discard": 0, "warn": 0, "error": 0, "contextLine": 0}
+ judge_pairs: list[tuple[str, str]] = []
+ editor_pairs: list[tuple[str, str]] = []
+ labeled = 0
+ for row in clips:
+ by_status[row["status"]] = by_status.get(row["status"], 0) + 1
+ judge = loads(row["judge_json"], None)
+ context = judge.get("context") if isinstance(judge, dict) else None
+ if isinstance(context, dict):
+ if context.get("error"):
+ decisions["error"] += 1
+ elif context.get("decision") in decisions:
+ decisions[context["decision"]] += 1
+ if context.get("contextLine"):
+ decisions["contextLine"] += 1
+ owner = owner_verdict(row)
+ labeled += owner is not None
+ if owner:
+ if (jv := judge_verdict(judge)) is not None:
+ judge_pairs.append((jv, owner))
+ if (ev := editor_verdict(judge)) is not None:
+ editor_pairs.append((ev, owner))
+ approved = by_status.get("approved", 0) + by_status.get("published", 0)
+ decided = approved + by_status.get("rejected", 0)
+ no_context = sum(1 for r in clips if r.get("owner_label") == "no_context")
+ return {
+ "window": {"days": days, "since": since if not session_id else None, "sessionId": session_id,
+ "liveHours": round(hours, 2)},
+ "calls": calls,
+ "perHour": per_hour,
+ "clips": {"total": len(clips), "byStatus": by_status, "approvalRate": round(approved / decided, 3) if decided else None,
+ "labeled": labeled, "noContext": no_context},
+ "judge": decisions,
+ "agreement": {"judge": agreement(judge_pairs), "editor": agreement(editor_pairs)},
+ }
diff --git a/clipper/app/roles.py b/clipper/app/roles.py
new file mode 100644
index 0000000..1972eed
--- /dev/null
+++ b/clipper/app/roles.py
@@ -0,0 +1,127 @@
+"""Equipe de IA do Clipador (doc/clipador/EQUIPE-IA.md): quatro papéis, cada um com a sua IA.
+
+- **varredura** (`scan`): assiste a live por janelas e propõe momentos (e descreve a tela para a linha do tempo);
+- **analista** (`analyst`): diz O QUE aconteceu no trecho candidato (cruza tela, fala e chat);
+- **editor** (`editor`): decide se vira corte, escolhe o trecho e escreve título/legenda — não pode ser desligado;
+- **juiz** (`judge`): só texto, vê só o que vai no corte final e confere se ele tem CONTEXTO (começo, desfecho,
+ funciona sozinho). Quem decide pelas respostas é o código (`context_judge.decide`).
+
+Cada papel tem provedor + modelo (+ esforço de raciocínio no Codex), liga/desliga e as **instruções do
+administrador** (texto extra somado às instruções padrão, que continuam no código). Gravado na tabela `settings`
+com a chave `judge.roles` (JSON). Sem essa chave (banco de antes), a configuração antiga vira a de todos os papéis:
+o provedor/modelo único de hoje vale para todos e o "modelo do analista" que já existia é respeitado.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+
+SETTINGS_KEY = "judge.roles"
+ROLES = ("scan", "analyst", "editor", "judge")
+ROLE_NAMES = {"scan": "Varredura", "analyst": "Analista", "editor": "Editor", "judge": "Juiz"}
+ROLE_PROVIDERS = ("codex", "claude", "gemini")
+# Esforço de raciocínio: só o Codex aceita (`model_reasoning_effort`). "" = padrão (low, o de sempre).
+EFFORTS = ("", "low", "medium", "high")
+# Imagens da varredura e do analista: mosaico 4×2 numa imagem só (novo), frames soltos (antigo) ou nenhuma.
+IMAGE_MODES = ("mosaic", "frames", "none")
+IMAGE_ROLES = ("scan", "analyst")
+EXTRA_MAX = 2000
+# Perguntas sim/não do juiz (doc/clipador/PESQUISA-JUIZ.md §6). As críticas decidem; as outras só baixam a nota.
+CHECKS = ("setup", "payoff", "who_what", "standalone", "intelligible", "faithful", "strong_open")
+CHECK_NAMES = {"setup": "começo (setup)", "payoff": "desfecho", "who_what": "quem/o quê", "standalone": "funciona sozinho",
+ "intelligible": "fala clara", "faithful": "título fiel", "strong_open": "abertura forte"}
+DEFAULT_CRITICAL = ("setup", "payoff", "standalone")
+DEFAULT_PENALTY = 0.5
+
+
+def _role(provider: str, model: str = "", effort: str = "", enabled: bool = True) -> dict:
+ return {"enabled": enabled, "provider": provider, "model": model, "effort": effort, "extra": ""}
+
+
+def default_roles(provider: str = "codex", model: str = "", analyst_model: str = "") -> dict:
+ """Configuração de partida: todos os papéis na mesma IA (como era antes). O juiz pensa um pouco mais
+ (esforço médio no Codex), como a pesquisa recomenda; os outros continuam no esforço baixo de sempre."""
+ provider = provider if provider in ROLE_PROVIDERS else "codex"
+ roles = {
+ "scan": _role(provider, model),
+ "analyst": _role(provider, analyst_model or model),
+ "editor": _role(provider, model),
+ "judge": _role(provider, model, "medium" if provider == "codex" else ""),
+ }
+ roles["scan"]["images"] = "mosaic"
+ roles["analyst"]["images"] = "mosaic"
+ roles["judge"] |= {"critical": list(DEFAULT_CRITICAL), "allowFix": True, "allowContextLine": True,
+ "penalty": DEFAULT_PENALTY}
+ return roles
+
+
+def _text(value: object, limit: int) -> str:
+ return str(value or "").replace("\r\n", "\n").strip()[:limit]
+
+
+def normalize_roles(raw: object, base: dict | None = None) -> dict:
+ """Valida campo a campo sobre `base` (padrão: `default_roles()`). O que vier errado fica como estava.
+ O editor nunca desliga (é quem decide se vira corte)."""
+ roles = copy.deepcopy(base or default_roles())
+ if not isinstance(raw, dict):
+ return roles
+ for name in ROLES:
+ item = raw.get(name)
+ if not isinstance(item, dict):
+ continue
+ role = roles[name]
+ if isinstance(item.get("enabled"), bool):
+ role["enabled"] = item["enabled"]
+ if item.get("provider") in ROLE_PROVIDERS:
+ if item["provider"] != role["provider"] and "model" not in item:
+ role["model"] = "" # trocou de provedor sem dizer o modelo: o padrão do provedor novo
+ role["provider"] = item["provider"]
+ if isinstance(item.get("model"), str):
+ model = item["model"].strip()[:80]
+ if all(c.isalnum() or c in "._:-" for c in model):
+ role["model"] = model
+ if item.get("effort") in EFFORTS:
+ role["effort"] = item["effort"]
+ if "extra" in item:
+ role["extra"] = _text(item.get("extra"), EXTRA_MAX)
+ if name in IMAGE_ROLES and item.get("images") in IMAGE_MODES:
+ role["images"] = item["images"]
+ if name == "judge":
+ critical = item.get("critical")
+ if isinstance(critical, list):
+ role["critical"] = [c for c in CHECKS if c in critical]
+ for key in ("allowFix", "allowContextLine"):
+ if isinstance(item.get(key), bool):
+ role[key] = item[key]
+ penalty = item.get("penalty")
+ if isinstance(penalty, (int, float)) and not isinstance(penalty, bool) and 0 <= penalty <= 3:
+ role["penalty"] = float(penalty)
+ roles["editor"]["enabled"] = True
+ return roles
+
+
+def from_settings(saved: dict[str, str], provider: str, model: str) -> dict:
+ """Papéis gravados (`judge.roles`) ou, sem eles, a MIGRAÇÃO da configuração antiga: `judge_provider`/
+ `judge_model` viram os de todos os papéis e `judge_analyst_model` (se havia) fica com o analista.
+ `provider`/`model` = os valores iniciais do .env, para quando nem a antiga existe."""
+ legacy_provider = saved.get("judge_provider", provider)
+ legacy_model = saved.get("judge_model", model) or ""
+ base = default_roles(legacy_provider, legacy_model, saved.get("judge_analyst_model", "") or "")
+ raw = saved.get(SETTINGS_KEY)
+ if not raw:
+ return base
+ try:
+ return normalize_roles(json.loads(raw), base)
+ except ValueError:
+ return base
+
+
+def admin_notes(role: dict, lang: str = "pt") -> str:
+ """Bloco que vai DEPOIS das instruções padrão. Os juízes em inglês entendem português: o dono escreve como quiser."""
+ extra = (role or {}).get("extra", "").strip()
+ if not extra:
+ return ""
+ title = ("Admin notes (may be written in Portuguese; when they conflict with the rules above, they win):"
+ if lang == "en" else "Instruções do administrador (quando conflitarem com as regras acima, valem estas):")
+ return f"\n\n{title}\n{extra}"
diff --git a/clipper/app/timeline.py b/clipper/app/timeline.py
new file mode 100644
index 0000000..57cec8b
--- /dev/null
+++ b/clipper/app/timeline.py
@@ -0,0 +1,298 @@
+"""Linha do tempo em JSON curto (v1): o vídeo "lido" como texto barato para a IA (doc/clipador/EQUIPE-IA.md).
+
+Uma linha JSON por instante (JSON Lines), chaves curtas — a legenda das chaves vai uma vez no prompt —, segundos
+inteiros da gravação e campos vazios omitidos. Só com o que já existe (nenhum modelo novo):
+
+| chave | conteúdo | de onde vem |
+| --- | --- | --- |
+| `t`, `d` | início e duração da entrada | pausas da fala, troca de falante ou no máximo 8 s |
+| `v` | o que está na tela (frase curta) | a IA que já vê os frames (varredura/analista), guardada em `scene_notes` |
+| `sp` | fala literal (até ~25 palavras); `[other1] …` = outra pessoa | Whisper + falantes |
+| `face` | expressão do streamer + intensidade 0–9 (`laugh.7`) | série do rosto (face.FaceService.dense + reaction) |
+| `lvl` | volume relativo ao normal da live, 0–9 (3 = normal) | dBFS por segundo já medido |
+| `chat` | `"mensagens\\|emote×n\\|frase mais repetida"` | chat da sessão |
+| `out` | 1 = fora do corte (o espectador NÃO vê) — só no prompt do juiz | — |
+
+Comportamento antigo (transcrição + chat + frames soltos) continua atrás da opção `timelineJson` (intel.opts).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import statistics
+from collections import Counter
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .scoring import ChatMessage, Word
+
+if TYPE_CHECKING: # pragma: no cover
+ from .worker import Engine
+
+log = logging.getLogger("cenaforge_clipper.timeline")
+
+STEP_MAX_S = 8.0 # uma entrada nunca passa disso (gameplay contínuo quase não tem corte de plano)
+COARSE_STEP_S = 20.0 # trecho de "volta" da varredura: resumido
+PAUSE_S = 1.2 # pausa na fala que fecha a entrada (se ela já tem MIN_ENTRY_S)
+MIN_ENTRY_S = 4.0
+FACE_MIN = 3 # expressão abaixo disso (z do rosto) é ruído: fica de fora
+LOUD_LVL, QUIET_LVL = 6, 1 # volume só aparece quando foge do normal (alto ou silêncio)
+PHRASE_CHARS = 32
+SP_WORDS = 25
+COARSE_SP_WORDS = 12
+NORMAL_LVL = 3
+# Rótulos do rosto (reaction.label) → token curto em inglês (as chaves e valores da linha do tempo são em inglês).
+FACE_TOKENS = {"risada": "laugh", "grito": "shout", "susto": "scare", "choque": "shock", "confuso": "confused",
+ "raiva": "anger"}
+
+LEGEND = {
+ "en": ("Timeline (JSON Lines; one entry per moment; seconds of the recording). Keys: t=start, d=duration, "
+ "v=what is on screen (short), sp=speech, literal ([other1] = someone else talking, not the streamer), "
+ "face=streamer expression.intensity 0-9, lvl=loudness vs. the stream's normal 0-9 (3=normal), "
+ "chat=messages|top emote×count|most repeated message, out=1 → OUTSIDE the clip (the viewer does NOT see it). "
+ "Missing key = nothing notable."),
+ "pt": ("Linha do tempo (JSON Lines; uma entrada por instante; segundos da gravação). Chaves: t=início, d=duração, "
+ "v=o que está na tela (curto), sp=fala literal ([other1] = outra pessoa falando, não o streamer), "
+ "face=expressão do streamer.intensidade 0-9, lvl=volume em relação ao normal da live 0-9 (3=normal), "
+ "chat=mensagens|emote mais usado×vezes|mensagem mais repetida, out=1 → FORA do corte (o espectador NÃO vê). "
+ "Chave ausente = nada a notar."),
+}
+
+
+@dataclass
+class Evidence:
+ """Tudo que a linha do tempo de uma janela usa. `face` = (segundo, token, intensidade z); `scenes` = (t, texto)."""
+ words: list[Word]
+ chat: list[ChatMessage]
+ loudness: list[float | None]
+ face: list[tuple[int, str, float]] = field(default_factory=list)
+ scenes: list[tuple[float, str]] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------- coleta (motor → Evidence)
+def face_marks(engine: "Engine", session: dict, lo: float, hi: float) -> list[tuple[int, str, float]]:
+ """Expressões do streamer por segundo em [lo, hi], pelo que o rastreio já gravou (sem rodar nada novo).
+ Sem câmera, rastreio desligado ou plano B sem expressões: lista vazia."""
+ try:
+ from . import reaction
+ from .face import OpenSeeFaceTracker
+
+ face = engine.face
+ if not face.enabled or not face.has_cam(session):
+ return []
+ if face.session_backend(session["id"]) == OpenSeeFaceTracker.name:
+ return []
+ seconds = face.dense(session["id"], max(0.0, lo - 240), hi)
+ if not any(s.smile is not None for s in seconds if lo <= s.t <= hi):
+ return []
+ zs = reaction.channel_z(seconds, face.params)
+ signal = reaction.reaction_signal(seconds, params=face.params)
+ marks = []
+ for second, z, value in zip(seconds, zs, signal):
+ if not lo <= second.t <= hi or z is None:
+ continue
+ label = reaction.label(second, z, face.params)
+ if label and label != "neutro":
+ marks.append((int(second.t), FACE_TOKENS.get(label, label), float(value or 0.0)))
+ return marks
+ except Exception as exc: # noqa: BLE001 - sem rosto a linha do tempo segue sem `face`
+ log.info("rosto para a linha do tempo indisponível: %s", exc)
+ return []
+
+
+def scene_lines(engine: "Engine", session_id: int, lo: float, hi: float) -> list[tuple[float, str]]:
+ """Frases de tela guardadas (varredura e analista). Do analista primeiro quando os dois descreveram o mesmo t."""
+ rows = engine.db.all("SELECT t, source, text FROM scene_notes WHERE session_id = ? AND t >= ? AND t <= ? ORDER BY t",
+ session_id, lo, hi)
+ rows.sort(key=lambda r: (r["t"], r["source"] != "analyst"))
+ return [(float(r["t"]), r["text"]) for r in rows]
+
+
+def save_scene_lines(engine: "Engine", session_id: int, source: str, lines: object,
+ tiles: list[float]) -> int:
+ """Grava as frases `v` que a IA escreveu para cada quadro (`n` = nº do quadro, 1 = primeiro). Devolve quantas."""
+ if not isinstance(lines, list) or not tiles:
+ return 0
+ rows = []
+ for item in lines:
+ if not isinstance(item, dict):
+ continue
+ try:
+ n = int(item.get("n"))
+ except (TypeError, ValueError):
+ continue
+ text = " ".join(str(item.get("v") or "").split())[:120]
+ if 1 <= n <= len(tiles) and text:
+ rows.append((session_id, round(tiles[n - 1], 1), source, text, _now()))
+ if rows:
+ engine.db.many("INSERT INTO scene_notes (session_id, t, source, text, created_at) VALUES (?, ?, ?, ?, ?)"
+ " ON CONFLICT (session_id, t, source) DO UPDATE SET text = excluded.text", rows)
+ return len(rows)
+
+
+def _now() -> str:
+ from .db import now
+
+ return now()
+
+
+def collect(engine: "Engine", session: dict, tl: dict, lo: float, hi: float) -> Evidence:
+ """Evidência da janela [lo, hi] a partir da linha do tempo já carregada (`Engine.load_timeline`)."""
+ return Evidence(words=[w for w in tl["words"] if lo - 1 <= w.start <= hi + 1],
+ chat=[m for m in tl["chat"] if lo - 1 <= m.t <= hi + 1],
+ loudness=tl["loudness"], face=face_marks(engine, session, lo, hi),
+ scenes=scene_lines(engine, session["id"], lo, hi))
+
+
+# ---------------------------------------------------------------- entradas
+def boundaries(words: list[Word], lo: float, hi: float, step: float = STEP_MAX_S, split_speech: bool = True) -> list[float]:
+ """Onde cada entrada começa: pausa na fala, troca de quem fala ou no máximo `step` segundos.
+ `split_speech=False` (resumo): só pelo passo."""
+ cuts = [lo]
+ last_end: float | None = None
+ last_sp: str | None = None
+ for w in sorted((w for w in words if lo <= w.start < hi), key=lambda w: w.start):
+ while w.start - cuts[-1] > step:
+ cuts.append(cuts[-1] + step)
+ cur = cuts[-1]
+ speaker = w.speaker or "streamer"
+ new_speaker = last_sp is not None and speaker != last_sp
+ pause = last_end is not None and w.start - last_end > PAUSE_S and w.start - cur >= MIN_ENTRY_S
+ if ((split_speech and (new_speaker or pause)) or w.start - cur >= step) and w.start > cur + 0.5:
+ cuts.append(w.start)
+ last_end, last_sp = w.end, speaker
+ while hi - cuts[-1] > step:
+ cuts.append(cuts[-1] + step)
+ if hi - cuts[-1] < 0.5 and len(cuts) > 1:
+ cuts.pop()
+ return cuts + [hi]
+
+
+def _speech(words: list[Word], limit: int) -> str:
+ parts: list[str] = []
+ current = None
+ count = 0
+ for w in words:
+ speaker = w.speaker or "streamer"
+ if speaker != current:
+ if speaker != "streamer":
+ parts.append(f"[{speaker}]")
+ elif current is not None:
+ parts.append("[streamer]")
+ current = speaker
+ parts.append(w.word.strip())
+ count += 1
+ if count >= limit:
+ parts.append("…")
+ break
+ return " ".join(p for p in parts if p)
+
+
+def _chat(messages: list[ChatMessage], coarse: bool) -> str:
+ if not messages:
+ return ""
+ emotes = Counter(e for m in messages for e in set(m.emotes))
+ top = ""
+ if emotes:
+ name, n = emotes.most_common(1)[0]
+ top = f"{name}×{n}"
+ phrase = ""
+ if not coarse:
+ # Só o que o chat REPETE (reação coletiva); resposta a alguém (@) e comando (!) não contam.
+ texts = Counter(re.sub(r"\s+", " ", m.text.strip().lower())[:PHRASE_CHARS] for m in messages
+ if m.text.strip() and not m.text.lstrip().startswith(("@", "!")))
+ if texts:
+ text, n = texts.most_common(1)[0]
+ if n >= 2:
+ phrase = text
+ return "|".join((str(len(messages)), top, phrase)).rstrip("|")
+
+
+def _level(loudness: list[float | None], a: float, b: float, normal: float | None) -> int | None:
+ values = [v for v in loudness[max(0, int(a)): max(int(a) + 1, int(b))] if v is not None]
+ if not values or normal is None:
+ return None
+ return max(0, min(9, round(NORMAL_LVL + (max(values) - normal) / 4)))
+
+
+def normal_level(loudness: list[float | None], lo: float, hi: float) -> float | None:
+ """Volume "normal" da live em volta da janela (mediana dos segundos com som)."""
+ values = [v for v in loudness[max(0, int(lo) - 120): int(hi) + 1] if v is not None and v > -60]
+ return statistics.median(values) if values else None
+
+
+def entries(ev: Evidence, lo: float, hi: float, *, coarse: bool = False, clip: tuple[float, float] | None = None,
+ sp_words: int | None = None) -> list[dict]:
+ """Entradas da janela. `coarse` = resumo (passo maior, fala curta, sem rosto/volume baixos). `clip` = (início,
+ fim) do corte: as entradas fora dele saem marcadas `out: 1` (prompt do juiz: o espectador não vê) e nenhuma
+ entrada atravessa o início ou o fim do corte."""
+ if clip is not None:
+ start, end = clip
+ out_items: list[dict] = []
+ for a, b, outside in ((lo, min(start, hi), True), (max(lo, start), min(end, hi), False), (max(lo, end), hi, True)):
+ if b - a < 0.3:
+ continue
+ for item in entries(ev, a, b, coarse=coarse, sp_words=sp_words):
+ out_items.append({"t": item.pop("t"), "d": item.pop("d"), **({"out": 1} if outside else {}), **item})
+ return out_items
+ step = COARSE_STEP_S if coarse else STEP_MAX_S
+ limit = sp_words or (COARSE_SP_WORDS if coarse else SP_WORDS)
+ cuts = boundaries(ev.words, lo, hi, step, split_speech=not coarse)
+ normal = normal_level(ev.loudness, lo, hi)
+ out: list[dict] = []
+ used_scenes: set[int] = set()
+ for a, b in zip(cuts, cuts[1:]):
+ if b - a < 0.3:
+ continue
+ item: dict = {"t": int(round(a)), "d": max(1, int(round(b - a)))}
+ scenes = [(i, text) for i, (t, text) in enumerate(ev.scenes) if a <= t < b and i not in used_scenes]
+ if scenes:
+ used_scenes.update(i for i, _ in scenes[:2])
+ item["v"] = " / ".join(dict.fromkeys(text for _, text in scenes[:2]))
+ words = [w for w in ev.words if a <= w.start < b]
+ if words:
+ item["sp"] = _speech(words, limit)
+ marks = [m for m in ev.face if a <= m[0] < b]
+ if marks:
+ _t, token, value = max(marks, key=lambda m: m[2])
+ intensity = max(0, min(9, round(value)))
+ if intensity >= (FACE_MIN + 1 if coarse else FACE_MIN):
+ item["face"] = f"{token}.{intensity}"
+ level = _level(ev.loudness, a, b, normal)
+ if level is not None and (level >= LOUD_LVL or level <= QUIET_LVL):
+ item["lvl"] = level
+ chat = _chat([m for m in ev.chat if a <= m.t < b], coarse)
+ if chat:
+ item["chat"] = chat
+ out.append(item)
+ return out
+
+
+def render(header: dict, items: list[dict]) -> str:
+ dump = lambda obj: json.dumps(obj, ensure_ascii=False, separators=(",", ":")) # noqa: E731
+ return "\n".join([dump(header), *(dump(i) for i in items)])
+
+
+def build(ev: Evidence, lo: float, hi: float, header: dict, *, budget_chars: int = 9000,
+ coarse_until: float | None = None, clip: tuple[float, float] | None = None) -> str:
+ """JSONL da janela dentro do orçamento de caracteres: se passar, a fala de cada entrada encurta (25 → 12 → 6
+ palavras) e, por último, o trecho mais antigo vira resumo. `coarse_until` = a parte [lo, coarse_until) já sai
+ resumida (a "volta" da varredura)."""
+ for sp_words in (SP_WORDS, COARSE_SP_WORDS, 6):
+ items: list[dict] = []
+ split = coarse_until if coarse_until is not None and lo < coarse_until < hi else None
+ if split is not None:
+ items += entries(ev, lo, split, coarse=True, clip=clip)
+ items += entries(ev, split, hi, clip=clip, sp_words=sp_words)
+ else:
+ items += entries(ev, lo, hi, clip=clip, sp_words=sp_words)
+ text = render(header, items)
+ if len(text) <= budget_chars:
+ return text
+ return text[:budget_chars].rsplit("\n", 1)[0]
+
+
+def legend(lang: str) -> str:
+ return LEGEND["en" if lang == "en" else "pt"]
diff --git a/clipper/app/worker.py b/clipper/app/worker.py
index d620ac0..4f1bfd0 100644
--- a/clipper/app/worker.py
+++ b/clipper/app/worker.py
@@ -29,7 +29,8 @@ from pathlib import Path
import httpx
from . import capture as capture_quality
-from . import clip_delete, layout, media
+from . import clip_delete, context_judge, layout, media, timeline
+from . import roles as roles_module
from .chat import ChatReader
from .config import REPO_ROOT, Settings
from .db import Database, loads, now
@@ -37,7 +38,7 @@ from .face import FaceService
from .hashtags import build_caption, split_hashtags
from .hashtags import compose as compose_hashtags
from .intel import Intel
-from .judge import Judge, JudgeError, analysis_block, build_prompt
+from .judge import (Judge, JudgeError, analysis_block, build_context_prompt, build_prompt, build_timeline_prompt)
from .scoring import ChatMessage, Params, Word, find_moments, overlaps
from .sources import Source, parse_source
from .speakers import SpeakerService, dump_words, parse_words
@@ -45,6 +46,10 @@ from .subtitles import build_ass, phrases
log = logging.getLogger("cenaforge_clipper")
LIVE_WINDOW_S = 900 # ao vivo, pontua só os últimos 15 min (o que veio antes já foi decidido)
+# Orçamento de caracteres da linha do tempo JSON por papel (~4 caracteres por token).
+ANALYST_TIMELINE_CHARS = 9000
+EDITOR_TIMELINE_CHARS = 7000
+JUDGE_TIMELINE_CHARS = 6000
def rel(path: Path) -> str:
@@ -339,9 +344,18 @@ class Engine:
def __init__(self, settings: Settings, db: Database, judge: Judge | None = None, voice: VoiceClient | None = None):
self.settings, self.db = settings, db
saved = {r["key"]: r["value"] for r in db.all("SELECT key, value FROM settings")}
- self.judge = judge or Judge(saved.get("judge_provider", settings.judge_provider),
- saved.get("judge_model", settings.judge_model), settings.data_dir / "judge",
- saved.get("judge_analyst_model", ""))
+ if judge is None:
+ # Equipe de IA: papéis gravados em `judge.roles`; sem eles, a configuração antiga vira a de todos os papéis
+ # (migração automática, gravada já na subida para ficar explícita no banco).
+ roles = roles_module.from_settings(saved, settings.judge_provider, settings.judge_model)
+ judge = Judge(saved.get("judge_provider", settings.judge_provider),
+ saved.get("judge_model", settings.judge_model), settings.data_dir / "judge",
+ saved.get("judge_analyst_model", ""), roles=roles)
+ if roles_module.SETTINGS_KEY not in saved:
+ db.run("INSERT INTO settings (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value",
+ roles_module.SETTINGS_KEY, json.dumps(judge.roles, ensure_ascii=False))
+ self.judge = judge
+ self.judge.meter = self.record_ai_call # medição por chamada (F0): tabela ai_calls
self.min_score = float(saved.get("judge_min_score", settings.judge_min_score))
self.voice = voice or VoiceClient(settings.voice_url, settings.voice_key, settings.language)
self.params = Params()
@@ -513,19 +527,44 @@ class Engine:
self.stop_event.wait(10)
# ---------- juiz (configurável pelo painel, sem reiniciar)
- def judge_config(self) -> dict:
- return self.judge.describe() | {"minScore": self.min_score, "options": dict(self.intel.opts),
- "lastScanError": self.intel.last_scan_error}
+ def judge_config(self, full: bool = False) -> dict:
+ """Configuração da Equipe de IA. `full` (GET /v1/judge) acrescenta as instruções padrão de cada papel (texto
+ grande, só leitura no painel) e os nomes das checagens do juiz."""
+ out = self.judge.describe() | {"minScore": self.min_score, "options": dict(self.intel.opts),
+ "lastScanError": self.intel.last_scan_error}
+ if isinstance(out.get("roles"), dict) and "scan" in out["roles"]:
+ out["roles"]["scan"]["enabled"] = bool(self.intel.opts.get("scanEnabled", True)) # liga/desliga = varredura
+ if full:
+ out["roleDefaults"] = self.judge.default_instructions()
+ out["checks"] = [{"id": c, "label": roles_module.CHECK_NAMES[c]} for c in roles_module.CHECKS]
+ return out
- def set_judge_config(self, provider: str, model: str, min_score: float, analyst_model: str | None = None) -> dict:
+ def set_judge_config(self, provider: str, model: str, min_score: float, analyst_model: str | None = None,
+ roles: dict | None = None) -> dict:
if not 0 <= min_score <= 10:
raise JudgeError("a nota mínima vai de 0 a 10")
- self.judge.configure(provider, model, analyst_model)
+ self.judge.configure(provider, model, analyst_model, roles)
+ scan = (roles or {}).get("scan") if isinstance(roles, dict) else None
+ if isinstance(scan, dict) and isinstance(scan.get("enabled"), bool):
+ self.intel.set_options({"scanEnabled": scan["enabled"]}) # o cartão da varredura liga/desliga a varredura
self.min_score = float(min_score)
rows = [("judge_provider", self.judge.provider), ("judge_model", self.judge.model), ("judge_min_score", str(self.min_score)),
- ("judge_analyst_model", self.judge.analyst_model)]
+ ("judge_analyst_model", self.judge.analyst_model),
+ (roles_module.SETTINGS_KEY, json.dumps(self.judge.roles, ensure_ascii=False))]
self.db.many("INSERT INTO settings (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value", rows)
- return self.judge_config()
+ return self.judge_config(full=True)
+
+ def record_ai_call(self, record: dict) -> None:
+ """Uma linha em `ai_calls` por tentativa de chamada de IA (medição F0; relatório em GET /v1/judge/report)."""
+ self.db.run(
+ "INSERT INTO ai_calls (at, role, purpose, provider, model, ok, error, ms, system_chars, prompt_chars, images,"
+ " image_bytes, tokens_in, tokens_out, tokens_cached, session_id, clip_id, mode)"
+ " VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+ now(), record.get("role", ""), record.get("purpose", ""), record.get("provider", ""), record.get("model", ""),
+ int(bool(record.get("ok"))), record.get("error"), record.get("ms"), record.get("systemChars"),
+ record.get("promptChars"), record.get("images"), record.get("imageBytes"), record.get("tokensIn"),
+ record.get("tokensOut"), record.get("tokensCached"), record.get("session_id"), record.get("clip_id"),
+ record.get("mode"))
# ---------- sessões
def start_session(self, url: str, channel_id: str | None = None, language: str | None = None) -> int:
@@ -723,8 +762,8 @@ class Engine:
def rel(path: Path) -> str:
return rel(path)
- def grab_frame(self, segments: list[tuple[Path, float, float]], t: float, out_file: Path) -> Path:
- return media.grab_frame(self.settings.ffmpeg or "ffmpeg", segments, t, out_file)
+ def grab_frame(self, segments: list[tuple[Path, float, float]], t: float, out_file: Path, width: int = 768) -> Path:
+ return media.grab_frame(self.settings.ffmpeg or "ffmpeg", segments, t, out_file, width)
# ---------- análise dos blocos (volume + transcrição)
def _analysis_loop(self) -> None:
@@ -896,48 +935,83 @@ class Engine:
# A ação vem antes do comentário: a IA vê `backtrackS` para trás (transcrição + frames) e pode recuar.
lo = max(0.0, clip["start_s"] - dur["backtrackS"])
hi = min(tl["duration"], clip["end_s"] + 15)
+ # Fonte em inglês: os juízes trabalham em inglês e devolvem também o português do painel (IDIOMAS.md).
+ lang = self.intel.lang(session)
+ # 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"
# 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)
- n_frames = 8 if hi - f_lo > 80 else 6
+ n_frames = 8 if hi - f_lo > 80 or image_mode == "mosaic" else 6
times = [f_lo + (hi - f_lo) * k / (n_frames - 1) for k in range(n_frames)]
- frames = self.intel.frames(session, times, f"clip{clip['id']}")
- # Fonte em inglês: os juízes trabalham em inglês e devolvem também o português do painel (IDIOMAS.md).
- lang = self.intel.lang(session)
- prompt = build_prompt(streamer, session["platform"], clip["start_s"], clip["end_s"], clip["peak_s"],
- tl["words"], tl["chat"], heuristic, session["title"], context=self.intel.context(session),
- frames=frames, backtrack_s=dur["backtrackS"], min_s=dur["minS"], max_s=dur["maxS"],
- face=self.face.summary(session, lo, hi), lang=lang)
- analysis = None
- try:
- # Dois juízes: o ANALISTA (vê os frames) diz o que aconteceu; o EDITOR decide e escreve a partir disso.
+ images, tiles, mosaic = self.intel.visual(session, times, f"clip{clip['id']}", image_mode)
+ mode = ("timeline" if use_timeline else "legacy") + f"+{'mosaic' if mosaic else image_mode}"
+ min_len = layout.min_target({"duration": dur})
+ with self.judge.scope(session_id=session["id"], clip_id=clip["id"], mode=mode):
+ if use_timeline:
+ prompt = build_timeline_prompt(
+ streamer, session["platform"], clip["start_s"], clip["end_s"], clip["peak_s"], heuristic,
+ context=self.intel.context(session, lean=True), timeline_text=self._timeline_text(session, tl, lo, hi),
+ tiles=tiles, mosaic=mosaic, lo=lo, hi=hi, min_s=dur["minS"], max_s=dur["maxS"], lang=lang)
+ else:
+ prompt = build_prompt(streamer, session["platform"], clip["start_s"], clip["end_s"], clip["peak_s"],
+ tl["words"], tl["chat"], heuristic, session["title"],
+ context=self.intel.context(session), frames=list(zip(tiles, images)),
+ backtrack_s=dur["backtrackS"], min_s=dur["minS"], max_s=dur["maxS"],
+ face=self.face.summary(session, lo, hi), lang=lang)
+ analysis = None
try:
- analysis = self.judge.analyze(prompt, [p for _, p in frames], lang=lang)
+ # ANALISTA (vê a tela) diz o que aconteceu; o EDITOR decide e escreve a partir disso.
+ if analyst_on:
+ try:
+ analysis = self.judge.analyze(prompt, images, lang=lang)
+ except (JudgeError, json.JSONDecodeError, KeyError, ValueError) as exc:
+ log.warning("analista falhou no corte %s: %s (editor segue sozinho)", clip["id"], exc)
+ if analysis:
+ # O que o analista viu em cada quadro vira o `v` da linha do tempo (editor e juiz reaproveitam).
+ timeline.save_scene_lines(self, session["id"], "analyst", analysis.pop("lines", None), tiles)
+ if use_timeline and analysis:
+ # Editor: só texto, linha do tempo do trecho (da ação, se o analista a viu antes) até o fim.
+ try:
+ act = float(analysis.get("action_start_s"))
+ except (TypeError, ValueError):
+ act = clip["start_s"]
+ e_lo = max(lo, min(clip["start_s"], act if lo <= act <= hi else clip["start_s"]) - 15)
+ editor_prompt = build_timeline_prompt(
+ streamer, session["platform"], clip["start_s"], clip["end_s"], clip["peak_s"], heuristic,
+ context=self.intel.context(session, lean=True),
+ timeline_text=self._timeline_text(session, tl, e_lo, hi, EDITOR_TIMELINE_CHARS),
+ tiles=[], mosaic=False, lo=lo, hi=hi, min_s=dur["minS"], max_s=dur["maxS"], lang=lang,
+ analysis=analysis)
+ else:
+ editor_prompt = prompt + ("\n\n" + analysis_block(analysis, lang) if analysis else "")
+ # Sem análise, o editor recebe as imagens; com análise, só texto (mais barato, a tela já foi lida).
+ verdict = self.judge.judge(editor_prompt, clip["start_s"], clip["end_s"], [] if analysis else images,
+ lo=lo, hi=hi, min_s=min_len, max_s=dur["maxS"], lang=lang)
+ # Corte manual: quem decidiu foi você; o juiz só escreve título e legenda (e não mexe no trecho).
+ manual = clip["source"] == "manual"
+ keep = manual or (verdict.keep and verdict.score >= self.min_score)
+ if manual:
+ verdict = verdict.__class__(**{**verdict.__dict__, "start_s": clip["start_s"], "end_s": clip["end_s"]})
+ update |= {"title": verdict.title or update["title"], "caption": verdict.caption,
+ "hashtags": list(verdict.hashtags),
+ "status": "pending" if keep else "discarded",
+ "start_s": verdict.start_s, "end_s": verdict.end_s,
+ "judge": {"model": verdict.model, "keep": verdict.keep, "score": verdict.score,
+ "reason": verdict.reason, "analysis": analysis,
+ # Fonte em inglês: título/legenda/motivo em português (só o painel lê).
+ **({"pt": verdict.pt} if verdict.pt else {}),
+ "analystModel": self.judge.role_model("analyst") if analysis else None}}
+ if keep and self.judge.role_enabled("judge"):
+ # JUIZ de contexto: o corte faz sentido sozinho? (só texto, só o que vai no corte final)
+ self._context_check(session, clip, tl, update, verdict.score, analysis, lo, hi, min_len,
+ float(dur["maxS"]), lang, manual)
except (JudgeError, json.JSONDecodeError, KeyError, ValueError) as exc:
- log.warning("analista falhou no corte %s: %s (editor segue sozinho)", clip["id"], exc)
- editor_prompt = prompt + ("\n\n" + analysis_block(analysis, lang) if analysis else "")
- # Sem análise, o editor recebe os frames; com análise, só texto (mais barato, a tela já foi lida).
- verdict = self.judge.judge(editor_prompt, clip["start_s"], clip["end_s"],
- [] if analysis else [p for _, p in frames],
- lo=lo, hi=hi, min_s=layout.min_target({"duration": dur}), max_s=dur["maxS"],
- lang=lang)
- # Corte manual: quem decidiu foi você; o juiz só escreve título e legenda (e não mexe no trecho).
- manual = clip["source"] == "manual"
- keep = manual or (verdict.keep and verdict.score >= self.min_score)
- if manual:
- verdict = verdict.__class__(**{**verdict.__dict__, "start_s": clip["start_s"], "end_s": clip["end_s"]})
- update |= {"title": verdict.title or update["title"], "caption": verdict.caption,
- "hashtags": list(verdict.hashtags),
- "status": "pending" if keep else "discarded",
- "start_s": verdict.start_s, "end_s": verdict.end_s,
- "judge": {"model": verdict.model, "keep": verdict.keep, "score": verdict.score,
- "reason": verdict.reason, "analysis": analysis,
- # Fonte em inglês: título/legenda/motivo em português (só o painel lê).
- **({"pt": verdict.pt} if verdict.pt else {}),
- "analystModel": (self.judge.analyst_model or self.judge.model) if analysis else None}}
- except (JudgeError, json.JSONDecodeError, KeyError, ValueError) as exc:
- # Falha do juiz não perde o momento: segue com a heurística e registra o motivo.
- update["judge"] = {"error": str(exc)[:300]}
+ # Falha do juiz não perde o momento: segue com a heurística e registra o motivo.
+ update["judge"] = {"error": str(exc)[:300]}
if update["status"] == "pending":
# O juiz pode ter recuado o trecho para cima de um corte já mantido: confere de novo (todas as origens).
kept = self.db.all(f"SELECT id, session_id, status, peak_s, start_s, end_s FROM clips WHERE session_id = ? "
@@ -973,7 +1047,8 @@ class Engine:
# Novo veredito: o projeto que a IA tinha gerado é refeito no render (o que você editou fica).
self.db.run("DELETE FROM edits WHERE clip_id = ? AND origin = 'ai'", clip["id"])
# Fonte em inglês: a fala do corte em português para o painel (falha não segura o corte).
- self.translate_clip(clip["id"], update["start_s"], update["end_s"])
+ with self.judge.scope(session_id=session["id"], clip_id=clip["id"]):
+ self.translate_clip(clip["id"], update["start_s"], update["end_s"])
verdict_info = update["judge"] or {}
if clip["source"] != "manual" and "score" in verdict_info:
# Aprendizado fraco pela IA (o forte vem da sua aprovação/rejeição no painel).
@@ -982,6 +1057,77 @@ class Engine:
elif verdict_info["score"] >= 7:
self.intel.learn_from_clip(clip, positive=True, factor=0.5)
+ def _timeline_text(self, session: dict, tl: dict, lo: float, hi: float, budget: int = ANALYST_TIMELINE_CHARS,
+ clip: tuple[float, float] | None = None, header: dict | None = None) -> str:
+ """Linha do tempo JSON de [lo, hi] (app/timeline.py) com o que já existe: fala+falante, chat, rosto, volume
+ e as frases de tela guardadas."""
+ ev = timeline.collect(self, session, tl, lo, hi)
+ head = header or {"win": [int(lo), int(hi)], "src": self.intel.lang(session)}
+ return timeline.build(ev, lo, hi, head, budget_chars=budget, clip=clip)
+
+ def _context_check(self, session: dict, clip: dict, tl: dict, update: dict, score: float, analysis: dict | None,
+ lo: float, hi: float, min_len: float, max_len: float, lang: str, manual: bool) -> None:
+ """JUIZ de contexto sobre o corte que o editor manteve. O código decide pelas respostas (context_judge.decide):
+ aprova (talvez com frase de contexto na tela), ajusta o trecho e confere UMA vez de novo, ou descarta com o
+ motivo em português. Falha da IA aqui não muda a decisão do editor (só registra o erro)."""
+ from .editor import pick_hook
+
+ conf = self.judge.roles["judge"]
+ game, profile = self.intel.session_game(session)
+ summary = str((profile or {}).get("summary") or "")
+ game_line = (summary.split(". ")[0] if summary else "")[:160]
+ story = str((analysis or {}).get("what_happened") or "")
+ opening, _ = pick_hook((analysis or {}).get("hook"), update["title"])
+ streamer = self.streamer_name(session)
+
+ def ask(start: float, end: float) -> tuple[dict, str]:
+ # O corte + 20 s antes e 15 s depois (marcados out=1): o juiz nota o começo ou o desfecho que ficaram de fora.
+ t_lo = max(0.0, start - context_judge.OUT_BEFORE_S)
+ t_hi = min(tl["duration"], end + context_judge.OUT_AFTER_S)
+ text = self._timeline_text(session, tl, t_lo, t_hi, JUDGE_TIMELINE_CHARS, clip=(start, end),
+ header={"clip": [int(start), int(end)], "src": lang})
+ prompt = build_context_prompt(streamer=streamer, game=game, game_line=game_line, start_s=start, end_s=end,
+ title=update["title"], caption=update["caption"], opening=opening, story=story,
+ timeline_text=text, lo=lo, hi=hi, min_s=min_len, max_s=max_len, lang=lang)
+ result = self.judge.check_context(prompt, lang=lang)
+ return result, self.judge.responder()
+
+ judge_info = update["judge"]
+ start, end = update["start_s"], update["end_s"]
+ limits = {"lo": lo, "hi": hi, "min_s": min_len, "max_s": max_len, "conf": conf, "score": score,
+ "min_score": self.min_score, "manual": manual}
+ try:
+ result, model = ask(start, end)
+ decision = context_judge.decide(result, start_s=start, end_s=end, **limits)
+ info = context_judge.view(result, decision, model)
+ if decision.action == "adjust" and decision.window:
+ # Trecho novo dentro dos limites: o juiz confere UMA vez de novo (sem novo ajuste).
+ ns, ne = decision.window
+ result2, model2 = ask(ns, ne)
+ second = context_judge.decide(result2, start_s=ns, end_s=ne, allow_fix=False, **limits)
+ first = info
+ info = context_judge.view(result2, second, model2)
+ info["first"] = {k: first[k] for k in ("viewerSummary", "checks", "failedCritical", "reasonPt", "pt")}
+ info["window"] = [round(ns, 2), round(ne, 2)]
+ if second.action == "approve":
+ info["decision"] = "adjust"
+ info["contextLine"] = second.context_line or decision.context_line
+ info["reasonPt"] = f"{decision.reason_pt} Conferido de novo: aprovado."
+ update["start_s"], update["end_s"] = round(ns, 2), round(ne, 2)
+ else:
+ info["decision"] = "discard"
+ info["contextLine"] = ""
+ info["reasonPt"] = (f"Descartado pelo juiz depois do ajuste para {ns:.0f}–{ne:.0f}s: "
+ f"{second.reason_pt.removeprefix('Descartado pelo juiz: ')}")
+ if info["decision"] == "discard":
+ update["status"] = "discarded"
+ judge_info["discardedBy"] = "context"
+ judge_info["context"] = info
+ log.info("juiz de contexto no corte %s: %s (%s)", clip["id"], info["decision"], info["reasonPt"][:160])
+ except (JudgeError, json.JSONDecodeError, KeyError, ValueError, TypeError) as exc:
+ judge_info["context"] = {"error": str(exc)[:300]}
+ log.warning("juiz de contexto falhou no corte %s: %s (fica a decisão do editor)", clip["id"], exc)
+
def translate_clip(self, clip_id: int, lo: float | None = None, hi: float | None = None,
force: bool = False) -> dict | None:
"""Fonte em inglês (doc/clipador/IDIOMAS.md): a fala de [lo, hi] (padrão: o trecho do corte) em frases com
diff --git a/clipper/tests/conftest.py b/clipper/tests/conftest.py
index db5b1cb..97df794 100644
--- a/clipper/tests/conftest.py
+++ b/clipper/tests/conftest.py
@@ -1,8 +1,29 @@
"""Configuração comum dos testes do Clipador."""
+import subprocess
+
import pytest
import app.ai_settings as ai_settings_module
import app.intel as intel_module
+import app.judge as judge_module
+
+
+class _NoRealCli:
+ """`subprocess` do juiz nos testes: igual ao de verdade, mas `run` recusa (nenhuma CLI de IA roda e gasta a cota
+ do dono — juízes falsos que não cobrem um papel, como o juiz de contexto, caem no caminho de falha da IA).
+ Quem testa as CLIs (test_ai_fallback) troca `run` por um falso."""
+
+ def __getattr__(self, name):
+ return getattr(subprocess, name)
+
+ @staticmethod
+ def run(*_args, **_kwargs):
+ raise OSError("CLI de IA bloqueada nos testes")
+
+
+@pytest.fixture(autouse=True)
+def _no_real_ai_cli(monkeypatch):
+ monkeypatch.setattr(judge_module, "subprocess", _NoRealCli())
@pytest.fixture(autouse=True)
diff --git a/clipper/tests/test_context_judge.py b/clipper/tests/test_context_judge.py
new file mode 100644
index 0000000..e227589
--- /dev/null
+++ b/clipper/tests/test_context_judge.py
@@ -0,0 +1,257 @@
+"""JUIZ de contexto (doc/clipador/EQUIPE-IA.md): decisão pelo código (aprovar / ajustar e conferir uma vez / frase de
+contexto / descartar), o fluxo no motor, a linha do tempo JSON dentro do orçamento e o mosaico de quadros."""
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from app import context_judge, editor_api, media, timeline
+from app import roles as roles_module
+from app.judge import Judge, Verdict
+from app.scoring import ChatMessage, Word
+
+from .test_render_and_duplicates import add_clip
+from .test_sources_and_api import auth, env, seed_session # noqa: F401 - fixture reaproveitada
+
+FFMPEG = shutil.which("ffmpeg")
+FFPROBE = shutil.which("ffprobe")
+
+
+def result(failed=(), fix=None, line="", reason="motivo"):
+ return {"viewer_summary": "resumo", "confidence": 0.8, "reason": reason, "pt": {"reason": reason},
+ "checks": {c: {"ok": c not in failed, "t": None, "why": ""} for c in roles_module.CHECKS},
+ "fix": {"start_s": None, "end_s": None, "context_line": line, **(fix or {})}}
+
+
+LIMITS = {"start_s": 200.0, "end_s": 265.0, "lo": 80.0, "hi": 280.0, "min_s": 61.0, "max_s": 90.0}
+CONF = roles_module.default_roles()["judge"]
+
+
+# ---------------------------------------------------------------- decisão pelo código
+def test_all_checks_ok_approves():
+ d = context_judge.decide(result(), conf=CONF, score=8, min_score=6, **LIMITS)
+ assert d.action == "approve" and d.failed == [] and d.window is None and d.score_after == 8
+
+
+def test_missing_setup_with_fix_adjusts_inside_the_limits():
+ d = context_judge.decide(result(["setup"], {"start_s": 150}), conf=CONF, score=8, **LIMITS)
+ assert d.action == "adjust" and d.failed_critical == ["setup"]
+ # Recuou o início para pegar o começo; com máximo de 90 s o fim encolhe (fit_window mantém o início).
+ assert d.window == (150.0, 240.0) and "começo (setup)" in d.reason_pt
+
+
+def test_fix_outside_the_window_is_clamped_and_no_change_means_discard():
+ d = context_judge.decide(result(["payoff"], {"end_s": 999}), conf=CONF, **LIMITS)
+ assert d.action == "adjust" and d.window[1] == 280.0 # nunca passa do limite
+ same = context_judge.decide(result(["payoff"], {"end_s": 265.2}), conf=CONF, **LIMITS)
+ assert same.action == "discard" # "ajuste" que não muda nada
+
+
+def test_critical_failure_without_fix_discards_with_portuguese_reason():
+ d = context_judge.decide(result(["payoff"], reason="ends before the fight is resolved"), conf=CONF, **LIMITS)
+ assert d.action == "discard" and d.reason_pt.startswith("Descartado pelo juiz: sem desfecho.")
+ no_fix = context_judge.decide(result(["setup"], {"start_s": 150}), conf={**CONF, "allowFix": False}, **LIMITS)
+ assert no_fix.action == "discard"
+
+
+def test_context_line_solves_standalone():
+ d = context_judge.decide(result(["standalone"], line="Tfue tries to talk his way out of a robbery"), conf=CONF,
+ score=8, min_score=6, **LIMITS)
+ assert d.action == "approve" and d.solved_by_line == ["standalone"] and d.context_line.startswith("Tfue")
+ off = context_judge.decide(result(["standalone"], line="Tfue tries"), conf={**CONF, "allowContextLine": False},
+ **LIMITS)
+ assert off.action == "discard"
+ too_long = context_judge.decide(result(["standalone"], line=" ".join(["word"] * 14)), conf=CONF, **LIMITS)
+ assert too_long.action == "discard"
+
+
+def test_non_critical_failures_only_lower_the_score():
+ d = context_judge.decide(result(["strong_open"]), conf=CONF, score=7, min_score=6, **LIMITS)
+ assert d.action == "approve" and d.score_after == 6.5
+ low = context_judge.decide(result(["strong_open", "faithful", "intelligible"]), conf=CONF, score=7, min_score=6,
+ **LIMITS)
+ assert low.action == "discard" and low.score_after == 5.5 and "nota caiu" in low.reason_pt
+ custom = context_judge.decide(result(["strong_open"]), conf={**CONF, "critical": ["strong_open"]}, **LIMITS)
+ assert custom.action == "discard" # as críticas são calibráveis no painel
+
+
+def test_manual_clip_only_warns():
+ d = context_judge.decide(result(["payoff"], {"end_s": 280}), conf=CONF, manual=True, **LIMITS)
+ assert d.action == "warn" and d.window is None and d.reason_pt.startswith("Aviso do juiz")
+
+
+# ---------------------------------------------------------------- fluxo no motor
+class ContextFakeJudge(Judge):
+ """Analista, editor e juiz falsos (nunca chama CLI). `answers` = respostas do juiz, em ordem."""
+
+ def __init__(self, answers, keep=True, score=8.0):
+ super().__init__("codex", "fake", Path("."))
+ self.answers = list(answers)
+ self.keep, self.score_value = keep, score
+ self.context_prompts: list[str] = []
+ self.editor_prompt = ""
+
+ def analyze(self, prompt, images, lang="pt"):
+ return {"situation": "treta", "what_happened": "Ele tenta negociar e leva um tiro.", "screen": "", "speech": "",
+ "chat_meaning": "", "confidence": 0.9, "action_start_s": 270, "reaction_end_s": 330, "hook": "",
+ "lines": [{"n": 1, "v": "streamer aponta rifle para mascarado"}]}
+
+ def judge(self, prompt, start_s, end_s, images=None, lang="pt", **_limits):
+ self.editor_prompt = prompt
+ return Verdict(self.keep, self.score_value, 270.0, 340.0, "Tentou negociar e levou tiro", "c", "r", "fake")
+
+ def check_context(self, prompt, lang="pt"):
+ self.context_prompts.append(prompt)
+ answer = self.answers.pop(0)
+ if isinstance(answer, Exception):
+ raise answer
+ return answer
+
+
+def run_clip(engine, judge, source="chat"):
+ engine.judge = judge
+ # Sem ffmpeg nos blocos falsos: um "mosaico" de um quadro só (em 275 s), que o analista descreve.
+ engine.intel.visual = lambda *_a, **_k: ([Path("mosaico-falso.jpg")], [275.0], True)
+ sid = seed_session(engine)
+ cid = (engine.db.get("SELECT MAX(id) AS n FROM clips")["n"] or 0) + 1
+ add_clip(engine, sid, cid, "candidate", 300, 280, 345, source=source)
+ engine.judge_clip(engine.db.get("SELECT * FROM clips WHERE id = ?", cid))
+ row = engine.db.get("SELECT * FROM clips WHERE id = ?", cid)
+ return row, json.loads(row["judge_json"])
+
+
+def test_engine_approves_and_records_the_context(env): # noqa: F811
+ _client, engine = env
+ row, info = run_clip(engine, ContextFakeJudge([result(line="Tenta negociar com o assaltante")]))
+ assert row["status"] == "pending" and info["context"]["decision"] == "approve"
+ assert info["context"]["contextLine"] == "Tenta negociar com o assaltante"
+ prompt = engine.judge.context_prompts[0]
+ # O juiz vê só o que vai no corte: o trecho e os 20 s antes marcados out=1.
+ assert "Corte que o espectador verá: 270s a 340s" in prompt and '"out":1' in prompt
+ assert "História pretendida (analista): Ele tenta negociar e leva um tiro." in prompt
+ # O que o analista viu no quadro virou o `v` da linha do tempo do editor.
+ assert '"v":"streamer aponta rifle para mascarado"' in engine.judge.editor_prompt
+
+
+def test_engine_adjusts_once_then_approves(env): # noqa: F811
+ _client, engine = env
+ row, info = run_clip(engine, ContextFakeJudge([result(["setup"], {"start_s": 250}), result()]))
+ assert row["status"] == "pending" and (row["start_s"], row["end_s"]) == (250.0, 340.0)
+ ctx = info["context"]
+ assert ctx["decision"] == "adjust" and ctx["window"] == [250.0, 340.0] and ctx["first"]["failedCritical"] == ["setup"]
+ assert len(engine.judge.context_prompts) == 2 and "250s a 340s" in engine.judge.context_prompts[1]
+
+
+def test_engine_adjusts_then_discards_when_still_failing(env): # noqa: F811
+ client, engine = env
+ row, info = run_clip(engine, ContextFakeJudge([result(["payoff"], {"end_s": 355}),
+ result(["payoff"], {"end_s": 360})]))
+ assert row["status"] == "discarded" and info["discardedBy"] == "context"
+ assert info["context"]["decision"] == "discard" and "depois do ajuste" in info["context"]["reasonPt"]
+ assert len(engine.judge.context_prompts) == 2 # confere UMA vez de novo, nunca mais
+ # Descartado pelo juiz fica visível e dá para forçar o render, como o descarte de hoje.
+ forced = client.post("/v1/clips/1/render", headers=auth()).json()
+ assert forced["status"] == "pending" and forced["judge"]["context"]["decision"] == "discard"
+
+
+def test_engine_discard_without_fix_and_judge_failure_keeps_editor(env): # noqa: F811
+ _client, engine = env
+ row, info = run_clip(engine, ContextFakeJudge([result(["standalone"])]))
+ assert row["status"] == "discarded" and info["context"]["failedCritical"] == ["standalone"]
+ from app.judge import JudgeError
+
+ row, info = run_clip(engine, ContextFakeJudge([JudgeError("cota")]))
+ assert row["status"] == "pending" and info["context"] == {"error": "cota"}
+
+
+def test_judge_role_off_and_editor_discard_skip_the_judge(env): # noqa: F811
+ _client, engine = env
+ judge = ContextFakeJudge([result(["payoff"])])
+ judge.roles["judge"]["enabled"] = False
+ row, info = run_clip(engine, judge)
+ assert row["status"] == "pending" and "context" not in info and judge.context_prompts == []
+ kept_out = ContextFakeJudge([result()], keep=False)
+ row, info = run_clip(engine, kept_out)
+ assert row["status"] == "discarded" and kept_out.context_prompts == [] # o editor já descartou
+
+
+def test_manual_clip_is_never_discarded_by_the_judge(env): # noqa: F811
+ _client, engine = env
+ row, info = run_clip(engine, ContextFakeJudge([result(["payoff"], {"end_s": 360})]), source="manual")
+ assert row["status"] == "pending" and info["context"]["decision"] == "warn"
+ assert (row["start_s"], row["end_s"]) == (280.0, 345.0)
+
+
+def test_context_line_becomes_the_opening_text_of_the_edit(env): # noqa: F811
+ _client, engine = env
+ row, _info = run_clip(engine, ContextFakeJudge([result(["setup"], {"start_s": 250}),
+ result(line="Ele tenta negociar com o assaltante")]))
+ session = engine.db.get("SELECT * FROM sessions WHERE id = ?", row["session_id"])
+ project = editor_api.auto_for(engine, row, session)
+ hook = next(o for o in project["overlays"] if o["kind"] == "hook")
+ assert hook["text"] == "Ele tenta negociar com o assaltante"
+ # O ajuste do juiz não é desfeito pelo início da ação do analista (270 s).
+ assert project["cuts"][0]["start"] <= 250.5
+
+
+# ---------------------------------------------------------------- linha do tempo JSON
+def _evidence(seconds=240):
+ words, chat = [], []
+ for t in range(0, seconds, 2):
+ words.append(Word(float(t), t + 1.5, f"palavra{t}", "other1" if 60 <= t < 64 else ""))
+ for t in range(0, seconds, 3):
+ chat.append(ChatMessage(float(t), "KEKW que isso" if t % 2 else "lol", emotes=("KEKW",) if t % 2 else ()))
+ loudness = [-30.0] * seconds
+ loudness[100] = -10.0
+ return timeline.Evidence(words=words, chat=chat, loudness=loudness, face=[(101, "laugh", 6.4)],
+ scenes=[(100.0, "explosão na garagem")])
+
+
+def test_timeline_entries_are_short_split_by_speaker_and_marked():
+ ev = _evidence()
+ items = timeline.entries(ev, 40, 130, clip=(60, 120))
+ assert all(i["d"] <= 8 for i in items) and items[0]["t"] == 40
+ assert any(i.get("sp", "").startswith("[other1]") for i in items) # troca de falante abre entrada nova
+ # Fora do corte (antes e depois) sai marcado; nenhuma entrada atravessa o início ou o fim do corte.
+ assert all(i.get("out") == 1 for i in items if i["t"] < 60 or i["t"] >= 120)
+ assert not any("out" in i for i in items if 60 <= i["t"] < 120)
+ assert {60, 120} <= {i["t"] for i in items} and all(i["t"] + i["d"] <= 60 for i in items if i["t"] < 60)
+ hit = next(i for i in items if i["t"] <= 100 < i["t"] + i["d"])
+ assert hit["v"] == "explosão na garagem" and hit["face"] == "laugh.6" and hit["lvl"] > 3
+ assert hit["chat"].split("|")[0].isdigit() and "KEKW×" in hit["chat"]
+
+
+def test_timeline_fits_the_budget():
+ ev = _evidence(600)
+ full = timeline.build(ev, 0, 600, {"win": [0, 600]}, budget_chars=100_000)
+ small = timeline.build(ev, 0, 600, {"win": [0, 600]}, budget_chars=6000)
+ assert len(small) <= 6000 < len(full)
+ assert all(json.loads(line) for line in small.splitlines()) # cada linha continua JSON válido
+ coarse = timeline.build(ev, 0, 600, {"win": [480, 600]}, budget_chars=100_000, coarse_until=480)
+ first = json.loads(coarse.splitlines()[1])
+ assert first["d"] == 20 and "face" not in first # a "volta" da varredura vai resumida
+
+
+def test_scene_lines_are_saved_by_tile_number(env): # noqa: F811
+ _client, engine = env
+ sid = seed_session(engine)
+ n = timeline.save_scene_lines(engine, sid, "scan", [{"n": 2, "v": " carro capotando "}, {"n": 9, "v": "x"},
+ {"n": "a"}], [10.0, 40.0, 70.0])
+ assert n == 1 and timeline.scene_lines(engine, sid, 0, 100) == [(40.0, "carro capotando")]
+
+
+@pytest.mark.skipif(not (FFMPEG and FFPROBE), reason="FFmpeg não instalado")
+@pytest.mark.parametrize("count,size", [(8, "1536x432"), (6, "1536x432"), (3, "1152x216")])
+def test_mosaic_puts_frames_in_one_image(tmp_path, count, size):
+ frames = []
+ for i in range(count):
+ out = tmp_path / f"f{i}.jpg"
+ subprocess.run([FFMPEG, "-y", "-v", "error", "-f", "lavfi", "-i", f"color=c=0x{i * 30:02x}4080:s=768x432",
+ "-frames:v", "1", str(out)], check=True)
+ frames.append(out)
+ target = media.mosaic(FFMPEG, frames, tmp_path / "m.jpg")
+ probe = subprocess.run([FFPROBE, "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height",
+ "-of", "csv=s=x:p=0", str(target)], capture_output=True, text=True, check=True)
+ assert probe.stdout.strip() == size
diff --git a/clipper/tests/test_english_source.py b/clipper/tests/test_english_source.py
index 3d6a8e7..05a8ebf 100644
--- a/clipper/tests/test_english_source.py
+++ b/clipper/tests/test_english_source.py
@@ -97,7 +97,10 @@ def test_english_session_judges_in_english_and_stores_portuguese(env): # noqa:
add_clip(engine, sid, 1, "candidate", 285, 270, 340)
engine.judge_clip(engine.db.get("SELECT * FROM clips WHERE id = 1"))
assert engine.judge.seen["analyze"][0] == "en" and engine.judge.seen["judge"][0] == "en"
- assert "Transcript:" in engine.judge.seen["judge"][1] and "ANALYST's analysis" in engine.judge.seen["judge"][1]
+ # Linha do tempo JSON (padrão desde a Equipe de IA, EQUIPE-IA.md): legenda das chaves e a fala dentro dela.
+ editor_prompt = engine.judge.seen["judge"][1]
+ assert "Timeline (JSON Lines" in editor_prompt and "ANALYST's analysis" in editor_prompt
+ assert '"sp":"No way bro.' in editor_prompt
clip = client.get("/v1/clips/1", headers=_auth()).json()
assert clip["title"] == "He robbed the bank solo" # o vídeo/publicação: inglês
assert clip["judge"]["pt"]["title"] == "Ele roubou o banco sozinho" # o painel: português
@@ -115,6 +118,7 @@ def test_portuguese_session_has_no_translation(env): # noqa: F811
engine.judge = EnglishJudge()
sid = seed_session(engine)
add_clip(engine, sid, 1, "candidate", 300, 280, 350)
+ engine.intel.opts["timelineJson"] = False # formato antigo (transcrição + chat) continua atrás da opção
engine.judge_clip(engine.db.get("SELECT * FROM clips WHERE id = 1"))
assert engine.judge.seen["judge"][0] == "pt" and "Transcrição:" in engine.judge.seen["judge"][1]
assert client.get("/v1/clips/1", headers=_auth()).json()["translation"] is None
diff --git a/clipper/tests/test_roles.py b/clipper/tests/test_roles.py
new file mode 100644
index 0000000..f1e4647
--- /dev/null
+++ b/clipper/tests/test_roles.py
@@ -0,0 +1,244 @@
+"""Equipe de IA (doc/clipador/EQUIPE-IA.md): papéis com IA própria, migração da configuração antiga, instruções do
+administrador, esforço por papel, medição por chamada (F0) e o relatório. Nenhuma CLI de verdade roda aqui."""
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from app import judge as judge_module
+from app import roles as roles_module
+from app.ai_settings import AiConfig
+from app.config import Settings
+from app.db import Database
+from app.judge import Judge, claude_usage, codex_usage, gemini_usage
+from app.worker import Engine
+
+from .test_sources_and_api import KEY, auth, env, seed_session # noqa: F401 - fixture reaproveitada
+
+ANALYSIS = {"situation": "jogada", "what_happened": "Ele roubou o banco.", "screen": "", "speech": "", "chat_meaning": "",
+ "confidence": 0.9, "action_start_s": 100, "reaction_end_s": 160, "hook": "Assalto solo", "lines": []}
+VERDICT = {"keep": True, "score": 8, "start_s": 100, "end_s": 170, "title": "Virada", "caption": "c", "hashtags": [],
+ "reason": "r"}
+CONTEXT_OK = {"viewer_summary": "Ele rouba o banco sozinho.", "fix": {"start_s": None, "end_s": None, "context_line": ""},
+ "checks": {c: {"ok": True, "t": None, "why": ""} for c in roles_module.CHECKS}, "confidence": 0.9,
+ "reason": "ok"}
+SCAN = {"screen_game": "GTA", "has_webcam": False, "summary": "s", "moments": [], "lines": []}
+
+
+def answer_for(schema: dict) -> dict:
+ props = schema["properties"]
+ if "viewer_summary" in props:
+ return CONTEXT_OK
+ if "situation" in props:
+ return ANALYSIS
+ if "moments" in props:
+ return SCAN
+ if list(props) == ["lines"]:
+ return {"lines": ["oi"]}
+ return VERDICT
+
+
+@pytest.fixture
+def team(tmp_path, monkeypatch):
+ """Juiz de verdade com as CLIs trocadas por um registro: cada chamada guarda provedor, modelo, esforço e sistema."""
+ calls: list[dict] = []
+
+ def fake_call(self, provider, system, prompt, schema, images, search, timeout, model, effort=""):
+ calls.append({"provider": provider, "model": model, "effort": effort, "system": system, "prompt": prompt})
+ return answer_for(schema)
+
+ monkeypatch.setattr(Judge, "_call", fake_call)
+ for name in ("codex", "claude", "gemini"):
+ monkeypatch.setattr(judge_module, f"find_{name}", (lambda n=name: [n]))
+ return calls
+
+
+def make_engine(tmp_path, saved: dict[str, str] | None = None) -> Engine:
+ settings = Settings.load(env_file=tmp_path / "none.env", service_key=KEY, data_dir=tmp_path / "data",
+ clips_dir=tmp_path / "clips", judge_provider="codex", voice_url=None, voice_key=None)
+ db = Database(settings.data_dir / "clipper.db")
+ if saved:
+ db.many("INSERT INTO settings (key, value) VALUES (?, ?)", list(saved.items()))
+ return Engine(settings, db)
+
+
+# ---------------------------------------------------------------- migração
+def test_old_single_provider_becomes_every_role_and_analyst_model_is_kept(tmp_path):
+ engine = make_engine(tmp_path, {"judge_provider": "claude", "judge_model": "sonnet", "judge_analyst_model": "haiku"})
+ roles = engine.judge.roles
+ assert {r["provider"] for r in roles.values()} == {"claude"}
+ assert roles["editor"]["model"] == "sonnet" and roles["scan"]["model"] == "sonnet" and roles["judge"]["model"] == "sonnet"
+ assert roles["analyst"]["model"] == "haiku" # o "modelo do analista" que já existia é respeitado
+ assert roles["judge"]["enabled"] and roles["judge"]["critical"] == ["setup", "payoff", "standalone"]
+ # A migração fica gravada (explícita no banco); a próxima subida lê `judge.roles`.
+ saved = json.loads(engine.db.get("SELECT value FROM settings WHERE key = 'judge.roles'")["value"])
+ assert saved["analyst"]["model"] == "haiku"
+ again = Engine(engine.settings, engine.db)
+ assert again.judge.roles == roles
+
+
+def test_off_master_switch_is_kept_and_roles_still_migrate(tmp_path):
+ engine = make_engine(tmp_path, {"judge_provider": "off", "judge_model": ""})
+ assert not engine.judge.enabled and engine.judge.provider == "off"
+ assert {r["provider"] for r in engine.judge.roles.values()} == {"codex"}
+
+
+def test_normalize_roles_field_by_field():
+ base = roles_module.default_roles("codex", "gpt-6-luna")
+ out = roles_module.normalize_roles({
+ "editor": {"enabled": False, "provider": "claude"}, # editor nunca desliga; trocou de provedor → modelo padrão
+ "judge": {"effort": "turbo", "critical": ["payoff", "inventado"], "penalty": 9, "extra": " x "},
+ "scan": {"images": "frames", "model": "bad model;"},
+ }, base)
+ assert out["editor"]["enabled"] is True and out["editor"]["provider"] == "claude" and out["editor"]["model"] == ""
+ assert out["judge"]["effort"] == "medium" and out["judge"]["critical"] == ["payoff"]
+ assert out["judge"]["penalty"] == 0.5 and out["judge"]["extra"] == "x"
+ assert out["scan"]["images"] == "frames" and out["scan"]["model"] == "gpt-6-luna"
+
+
+# ---------------------------------------------------------------- cada papel chama a sua IA
+def test_each_role_calls_its_own_provider_model_and_effort(tmp_path, team):
+ roles = roles_module.default_roles("codex")
+ roles["scan"] |= {"provider": "codex", "model": "gpt-6-luna", "effort": "low"}
+ roles["analyst"] |= {"provider": "claude", "model": "haiku"}
+ roles["editor"] |= {"provider": "codex", "model": ""}
+ roles["judge"] |= {"provider": "claude", "model": "sonnet", "effort": ""}
+ judge = Judge("codex", "", tmp_path / "j", ai=AiConfig(tmp_path / "ai"), roles=roles)
+ judge.scan("p", [], lang="en")
+ judge.analyze("p", [], lang="en")
+ judge.judge("p", 100, 170, [], lang="en")
+ judge.check_context("p", lang="en")
+ got = [(c["provider"], c["model"], c["effort"]) for c in team]
+ assert got == [("codex", "gpt-6-luna", "low"), ("claude", "haiku", ""), ("codex", "gpt-6-luna", ""),
+ ("claude", "sonnet", "")]
+ # O que não é dos quatro papéis (tradução, pesquisa) usa a IA do editor.
+ judge.translate_lines(["oi"])
+ assert team[-1]["provider"] == "codex"
+ assert judge.fallback_chain("claude")[0] == "claude" and judge.fallback_chain()[0] == "codex"
+
+
+def test_admin_instructions_are_added_after_the_default_text(tmp_path, team):
+ roles = roles_module.default_roles("codex")
+ roles["judge"]["extra"] = "Não aprove corte que termina antes do resultado da treta."
+ roles["analyst"]["extra"] = "Lag conta como jogada."
+ judge = Judge("codex", "", tmp_path / "j", ai=AiConfig(tmp_path / "ai"), roles=roles)
+ judge.check_context("p", lang="en")
+ judge.analyze("p", [], lang="pt")
+ judge.judge("p", 100, 170, [], lang="pt")
+ context_system, analyst_system, editor_system = (c["system"] for c in team)
+ assert context_system.startswith(judge_module.CONTEXT_SYSTEM_EN) # o padrão continua inteiro, no começo
+ assert context_system.endswith("Admin notes (may be written in Portuguese; when they conflict with the rules above, "
+ "they win):\nNão aprove corte que termina antes do resultado da treta.")
+ assert analyst_system.endswith("valem estas):\nLag conta como jogada.")
+ assert "Instruções do administrador" not in editor_system # o editor não tem extra
+
+
+def test_codex_effort_goes_to_the_command_line(tmp_path, monkeypatch):
+ seen: list[list[str]] = []
+
+ def run(args, input=None, capture_output=True, timeout=None, cwd=None, creationflags=0, env=None):
+ seen.append(list(args))
+ Path(args[args.index("-o") + 1]).write_text(json.dumps(CONTEXT_OK), encoding="utf-8")
+ events = '{"type":"thread.started"}\n{"type":"turn.completed","usage":{"input_tokens":1234,"cached_input_tokens":200,"output_tokens":56}}\n'
+ return subprocess.CompletedProcess(args, 0, events.encode(), b"")
+
+ monkeypatch.setattr(judge_module.subprocess, "run", run)
+ monkeypatch.setattr(judge_module, "find_codex", lambda: ["codex"])
+ monkeypatch.setattr(judge_module, "find_claude", lambda: None)
+ records = []
+ judge = Judge("codex", "", tmp_path / "j", ai=AiConfig(tmp_path / "ai"))
+ judge.meter = records.append
+ with judge.scope(clip_id=7, session_id=3, mode="timeline+mosaic"):
+ judge.check_context("prompt de teste", lang="pt")
+ assert 'model_reasoning_effort="medium"' in seen[0] and "--json" in seen[0] # juiz: esforço médio por padrão
+ rec = records[0]
+ assert rec["role"] == "judge" and rec["provider"] == "codex" and rec["ok"] is True
+ assert (rec["tokensIn"], rec["tokensOut"], rec["tokensCached"]) == (1234, 56, 200)
+ assert rec["clip_id"] == 7 and rec["mode"] == "timeline+mosaic" and rec["promptChars"] == len("prompt de teste")
+
+
+def test_usage_parsers():
+ assert codex_usage("lixo\n{\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":10,\"output_tokens\":2}}") == \
+ {"in": 10, "out": 2, "cached": None}
+ assert codex_usage("") is None
+ assert claude_usage({"usage": {"input_tokens": 5, "cache_creation_input_tokens": 100, "cache_read_input_tokens": 2000,
+ "output_tokens": 40}}) == {"in": 2105, "out": 40, "cached": 2000}
+ assert gemini_usage({"stats": {"models": {"gemini-3.5-flash": {"tokens": {"prompt": 900, "candidates": 50,
+ "thoughts": 10, "cached": 0}}}}}) == \
+ {"in": 900, "out": 60, "cached": 0}
+ assert gemini_usage({"response": "x"}) is None
+
+
+# ---------------------------------------------------------------- API e medição
+def test_put_roles_and_read_defaults(env): # noqa: F811
+ client, engine = env
+ roles = {"scan": {"enabled": False, "provider": "codex", "images": "frames"},
+ "analyst": {"provider": "claude", "model": "haiku", "extra": "Olhe o HUD."},
+ "editor": {"enabled": False, "provider": "codex"},
+ "judge": {"enabled": True, "provider": "claude", "model": "sonnet", "critical": ["setup", "payoff"],
+ "allowContextLine": False}}
+ r = client.put("/v1/judge", json={"provider": "codex", "model": "", "minScore": 6, "roles": roles}, headers=auth())
+ assert r.status_code == 200
+ data = r.json()
+ assert data["roles"]["analyst"]["provider"] == "claude" and data["roles"]["analyst"]["extra"] == "Olhe o HUD."
+ assert data["roles"]["editor"]["enabled"] is True # o editor não desliga
+ assert data["roles"]["judge"]["critical"] == ["setup", "payoff"] and data["roles"]["judge"]["allowContextLine"] is False
+ # O cartão da varredura liga/desliga a varredura de verdade.
+ assert data["roles"]["scan"]["enabled"] is False and engine.intel.opts["scanEnabled"] is False
+ got = client.get("/v1/judge", headers=auth()).json()
+ assert set(got["roleDefaults"]) == {"scan", "analyst", "editor", "judge"}
+ assert got["roleDefaults"]["judge"]["en"].startswith("You are the CONTEXT JUDGE")
+ assert [c["id"] for c in got["checks"]][:3] == ["setup", "payoff", "who_what"]
+ assert "roleDefaults" not in client.get("/v1/status", headers=auth()).json()["judge"] # status fica leve
+ # A opção da linha do tempo (comparar com o formato antigo) também se troca pela mesma rota.
+ client.put("/v1/judge", json={"provider": "codex", "model": "", "minScore": 6, "timelineJson": False}, headers=auth())
+ assert engine.intel.opts["timelineJson"] is False
+
+
+def test_owner_label_and_report(env): # noqa: F811
+ client, engine = env
+ sid = seed_session(engine)
+ db = engine.db
+
+ def clip(cid, status, decision, keep=True, label=None):
+ judge = {"keep": keep, "score": 7}
+ if decision:
+ judge["context"] = {"decision": decision, "contextLine": "x" if decision == "approve" else ""}
+ db.run("INSERT INTO clips (id, session_id, peak_s, start_s, end_s, score, source, status, judge_json, created_at,"
+ " updated_at, owner_label) VALUES (?, ?, 1, 0, 60, 5, 'chat', ?, ?, ?, ?, ?)",
+ cid, sid, status, json.dumps(judge), engine_now(), engine_now(), label)
+
+ clip(1, "approved", "approve") # juiz mantém, dono bom → concorda
+ clip(2, "rejected", "approve") # juiz mantém, dono ruim → discorda
+ clip(3, "discarded", "discard", label="no_context") # juiz descarta, dono "sem contexto" → concorda
+ clip(4, "ready", "adjust") # dono não avaliou
+ clip(5, "approved", "discard") # juiz descartou, dono forçou e aprovou → falso negativo
+ # Rejeitar com "sem contexto" pela rota (o rótulo vale também para corte antigo/descartado).
+ r = client.patch("/v1/clips/4", json={"label": "no_context", "labelNote": "não dá pra entender"}, headers=auth())
+ assert r.json()["ownerLabel"] == "no_context" and r.json()["ownerNote"] == "não dá pra entender"
+ assert r.json()["status"] == "ready" # avaliar não muda o estado
+ engine.record_ai_call({"role": "judge", "purpose": "judge", "provider": "codex", "model": "gpt-6-luna", "ok": True,
+ "ms": 1200, "systemChars": 2700, "promptChars": 3000, "images": 0, "imageBytes": 0,
+ "tokensIn": 1500, "tokensOut": 200, "session_id": sid, "mode": "timeline+mosaic"})
+ engine.record_ai_call({"role": "analyst", "purpose": "analyst", "provider": "codex", "model": "gpt-6-luna",
+ "ok": False, "error": "cota", "systemChars": 3000, "promptChars": 5000, "images": 1,
+ "imageBytes": 60_000, "session_id": sid})
+ rep = client.get(f"/v1/judge/report?session={sid}", headers=auth()).json()
+ assert rep["window"]["liveHours"] == round(600 / 3600, 2)
+ judge_row = next(c for c in rep["calls"] if c["role"] == "judge")
+ assert judge_row["tokensIn"] == 1500 and judge_row["withUsage"] == 1 and judge_row["mode"] == "timeline+mosaic"
+ assert next(c for c in rep["calls"] if c["role"] == "analyst")["failures"] == 1
+ assert rep["perHour"]["judge"]["calls"] == pytest.approx(6.0)
+ assert rep["judge"]["approve"] == 2 and rep["judge"]["discard"] == 2 and rep["judge"]["adjust"] == 1
+ assert rep["clips"]["approvalRate"] == round(2 / 3, 3) and rep["clips"]["noContext"] == 2
+ agreement = rep["agreement"]["judge"]
+ # pares: (keep, good) (keep, bad) (discard, no_context) (keep, no_context) (discard, good) → concordam 2 de 5
+ assert agreement["pairs"] == 5 and agreement["agree"] == 2
+ assert agreement["matrix"]["discard"]["good"] == 1 and agreement["matrix"]["keep"]["no_context"] == 1
+
+
+def engine_now() -> str:
+ from app.db import now
+
+ return now()
diff --git a/clipper/tests/test_sources_and_api.py b/clipper/tests/test_sources_and_api.py
index cce0e17..81f1b83 100644
--- a/clipper/tests/test_sources_and_api.py
+++ b/clipper/tests/test_sources_and_api.py
@@ -165,6 +165,9 @@ def test_judge_config_persists(env, tmp_path):
assert client.put("/v1/judge", json={"provider": "gpt", "model": ""}, headers=auth()).status_code == 422
assert client.put("/v1/judge", json={"provider": "codex", "model": "x; rm -rf"}, headers=auth()).status_code == 422
saved = {r["key"]: r["value"] for r in engine.db.all("SELECT * FROM settings")}
+ # Equipe de IA (EQUIPE-IA.md): o painel antigo (um provedor só) troca a IA de todos os papéis.
+ roles = json.loads(saved.pop("judge.roles"))
+ assert {r["provider"] for r in roles.values()} == {"claude"}
assert saved == {"judge_provider": "claude", "judge_model": "haiku", "judge_min_score": "7.0", "judge_analyst_model": ""}
diff --git a/clipper/tests/test_speakers.py b/clipper/tests/test_speakers.py
index 7c00f8b..f6d89d2 100644
--- a/clipper/tests/test_speakers.py
+++ b/clipper/tests/test_speakers.py
@@ -352,7 +352,8 @@ def test_translation_lines_get_speaker(env): # noqa: F811
assert [(x["text"], x["speaker"]) for x in lines] == [("No way bro.", "streamer"), ("Told you.", "other1")]
# O juiz viu quem fala.
prompt = engine.judge.seen["judge"][1]
- assert "] No way bro." in prompt and "[other1] Told you." in prompt and "Never attribute to" in prompt
+ # Linha do tempo JSON (EQUIPE-IA.md): cada entrada é de um falante só; a de outra pessoa vem marcada.
+ assert '"sp":"No way bro."' in prompt and '"sp":"[other1] Told you."' in prompt and "Never attribute to" in prompt
# Tradução antiga (sem `speaker`) é refeita na próxima vez.
engine.db.run("UPDATE clips SET translation_json = ? WHERE id = 1",
json.dumps({"startS": 0, "endS": 1e6, "lines": [{"s": 1, "e": 2, "text": "x", "pt": "y"}]}))
From 26c9afa13a4eebc7ca04751aa87fbf8a90686735 Mon Sep 17 00:00:00 2001
From: Mateuus <5893666+Mateuus@users.noreply.github.com>
Date: Wed, 18 Nov 2026 04:38:34 -0300
Subject: [PATCH 2/7] =?UTF-8?q?Painel:=20Equipe=20de=20IA=20no=20lugar=20d?=
=?UTF-8?q?o=20provedor=20=C3=BAnico,=20juiz=20de=20contexto=20no=20modal?=
=?UTF-8?q?=20e=20medi=C3=A7=C3=A3o?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- Ajustes → Juiz: "Usar IA" + um cartão por papel (varredura, analista, editor, juiz) com
provedor, modelo do provedor escolhido, raciocínio (Codex), imagens (mosaico/quadros/nenhuma),
liga/desliga (o editor não desliga), instruções padrão só leitura (fonte PT/EN) e instruções
do administrador; regras do juiz (checagens críticas, ajustar trecho, frase de contexto,
desconto por checagem). Opção "Linha do tempo em JSON" para comparar com o formato antigo.
- Cartão de medição (GET judge/report, liberado no proxy): chamadas e tokens por hora por
papel, aprovação, descartes do juiz e concordância juiz x dono.
- Modal do corte: veredito do juiz de contexto em português (decisão, o que um espectador
frio entende, frase de contexto, checagens) e "Sua avaliação" (bom/ruim/sem contexto);
botão "Sem contexto" ao rejeitar; lista marca "descartado pelo juiz".
Co-Authored-By: Claude Opus 5.5
---
panel/src/components/clipper-ai-team.tsx | 285 ++++++++++++++++++
panel/src/components/clipper-client.ts | 121 +++++++-
panel/src/components/clipper-clip-dialog.tsx | 4 +-
panel/src/components/clipper-clip-parts.tsx | 112 ++++++-
panel/src/components/clipper-clip-table.tsx | 6 +-
panel/src/components/clipper-judge.tsx | 232 +++++++-------
.../src/components/clipper-settings-page.tsx | 4 +-
panel/src/lib/clipper.ts | 4 +-
8 files changed, 629 insertions(+), 139 deletions(-)
create mode 100644 panel/src/components/clipper-ai-team.tsx
diff --git a/panel/src/components/clipper-ai-team.tsx b/panel/src/components/clipper-ai-team.tsx
new file mode 100644
index 0000000..dba5e78
--- /dev/null
+++ b/panel/src/components/clipper-ai-team.tsx
@@ -0,0 +1,285 @@
+"use client";
+// Equipe de IA do Clipador (doc/clipador/EQUIPE-IA.md): um cartão por papel — varredura, analista, editor e juiz —
+// com provedor, modelo (lista do provedor escolhido), raciocínio (só Codex), imagens, liga/desliga (o editor não
+// desliga), as instruções padrão (só leitura) e as instruções do administrador (somadas às padrão). E o relatório
+// de medição: chamadas e tokens por papel, decisões do juiz e a concordância dele com você.
+import { useCallback, useEffect, useState } from "react";
+import {
+ CHECK_LABEL, PROVIDER_LABEL, ROLE_INFO, ROLE_ORDER, clipperCall, formatScore,
+ type AiEffort, type AiImages, type AiReport, type AiRole, type AiRoleId, type AiRoleProvider, type AiRoles,
+ type ContextCheckId, type JudgeConfig,
+} from "./clipper-client";
+import { DescribedSelect } from "./forms";
+import { AlertIcon, RefreshIcon, SparkIcon } from "./icons";
+import { Badge, Button, Card, Select, Spinner, Switch, Textarea, cx } from "./ui";
+
+const EXTRA_MAX = 2000;
+const EFFORT_LABEL: Record = { "": "padrão (baixo)", low: "baixo", medium: "médio", high: "alto" };
+const IMAGES_LABEL: Record = {
+ mosaic: { label: "Mosaico (1 imagem com 8 quadros)", description: "Os quadros numa grade 4×2: a IA vê a sequência pagando por 1 imagem (4–8× menos que quadros soltos)." },
+ frames: { label: "Quadros soltos (antigo)", description: "Cada quadro em uma imagem, em 768 px. Mais detalhe, bem mais caro." },
+ none: { label: "Nenhuma", description: "Só texto (fala, chat, rosto e o que a varredura já descreveu da tela)." },
+};
+const ALL_CHECKS = Object.keys(CHECK_LABEL) as ContextCheckId[];
+
+/** Provedores que dá para escolher: Codex e Claude sempre; Gemini só se estiver ligado em Configurações → IA. */
+function providerOptions(judge: JudgeConfig, current: AiRoleProvider): AiRoleProvider[] {
+ const list: AiRoleProvider[] = ["codex", "claude"];
+ if (judge.providers?.gemini?.enabled || current === "gemini") list.push("gemini");
+ return list;
+}
+
+export function AiTeam({ judge, roles, onChange, disabled }: {
+ judge: JudgeConfig; roles: AiRoles; onChange: (next: AiRoles) => void; disabled: boolean;
+}) {
+ const set = (id: AiRoleId, values: Partial) => onChange({ ...roles, [id]: { ...roles[id], ...values } });
+ return (
+
+
+
Equipe de IA
+
+ Cada papel roda na IA que você escolher. A varredura e o analista veem a tela;
+ o editor decide se vira corte; o juiz confere se o corte faz sentido para quem nunca viu a live.
+ Se a IA de um papel cair, a reserva de Configurações → IA assume para aquele papel.
+
+ );
+}
diff --git a/panel/src/components/clipper-client.ts b/panel/src/components/clipper-client.ts
index f1fdf80..bf2dd0b 100644
--- a/panel/src/components/clipper-client.ts
+++ b/panel/src/components/clipper-client.ts
@@ -18,8 +18,40 @@ export type ClipperStatus = {
};
export type JudgeModel = { id: string; label: string; description?: string };
-/** `faceTrack` é opcional: o serviço antigo (antes do rastreio de reação) não manda. */
-export type JudgeOptions = { scanEnabled: boolean; scanIntervalS: number; vision: boolean; camDetect: boolean; faceTrack?: boolean };
+/** `faceTrack` e `timelineJson` são opcionais: o serviço antigo não manda. `timelineJson` = a IA lê o vídeo como
+ * linha do tempo JSON curta (novo); false = transcrição + chat + frames soltos (antigo, para comparar). */
+export type JudgeOptions = {
+ scanEnabled: boolean; scanIntervalS: number; vision: boolean; camDetect: boolean; faceTrack?: boolean; timelineJson?: boolean;
+};
+
+/** Equipe de IA (doc/clipador/EQUIPE-IA.md): quatro papéis, cada um com a sua IA. */
+export type AiRoleId = "scan" | "analyst" | "editor" | "judge";
+export type AiRoleProvider = Exclude;
+export type AiEffort = "" | "low" | "medium" | "high";
+export type AiImages = "mosaic" | "frames" | "none";
+export type ContextCheckId = "setup" | "payoff" | "who_what" | "standalone" | "intelligible" | "faithful" | "strong_open";
+export type AiRole = {
+ enabled: boolean;
+ provider: AiRoleProvider;
+ /** "" = padrão do provedor. */
+ model: string;
+ /** Raciocínio (só Codex); "" = padrão (baixo). */
+ effort: AiEffort;
+ /** Instruções do administrador, somadas às padrão (podem ser em português). */
+ extra: string;
+ /** Só varredura e analista. */
+ images?: AiImages;
+ // Só o juiz: checagens críticas, se pode ajustar o trecho e pôr frase de contexto, e quanto cada checagem
+ // não crítica tira da nota.
+ critical?: ContextCheckId[];
+ allowFix?: boolean;
+ allowContextLine?: boolean;
+ penalty?: number;
+ /** Só leitura (o serviço calcula): modelo efetivo e a ordem de tentativa (reserva) deste papel. */
+ resolvedModel?: string;
+ chain?: AiRoleProvider[];
+};
+export type AiRoles = Record;
export type JudgeConfig = {
provider: JudgeProvider;
/** Modelo do EDITOR (2º juiz). null com o juiz desligado. */
@@ -41,8 +73,37 @@ export type JudgeConfig = {
fallback?: { enabled: boolean; cooldownMin: number; chain: Exclude[] };
/** IAs em pausa depois de falha de indisponibilidade (`until` em ISO, UTC). */
pauses?: JudgePause[];
+ /** Equipe de IA (serviço novo): cada papel com a sua IA. Ausente = serviço antigo (um provedor só). */
+ roles?: AiRoles;
+ /** Instruções padrão de cada papel nos dois idiomas (só leitura). Só em GET/PUT /judge. */
+ roleDefaults?: Record;
+ /** Checagens do juiz de contexto (id + nome em português). */
+ checks?: { id: ContextCheckId; label: string }[];
+ /** Situação de cada IA (Configurações → IA): ligada, pronta e por que não. */
+ providers?: Partial>;
};
+/** GET /judge/report: medição da Equipe de IA (F0) — chamadas e tokens por papel, decisões do juiz e concordância com você. */
+export type AiReport = {
+ window: { days: number; since: string | null; sessionId: number | null; liveHours: number };
+ calls: {
+ role: string; purpose: string; provider: string; model: string; mode: string; calls: number; failures: number;
+ avgChars: number; avgImages: number; imageKB: number; tokensIn: number | null; tokensOut: number | null;
+ tokensCached: number | null; withUsage: number; avgMs: number;
+ }[];
+ perHour: Record;
+ clips: { total: number; byStatus: Partial>; approvalRate: number | null; labeled: number; noContext: number };
+ judge: { approve: number; adjust: number; discard: number; warn: number; error: number; contextLine: number };
+ agreement: Record<"judge" | "editor", AiAgreement>;
+};
+export type AiAgreement = {
+ pairs: number; agree: number; rate: number | null; kappa: number | null;
+ matrix: Record<"keep" | "discard", Record>;
+};
+
+/** Sua avaliação do corte (conjunto de avaliação do juiz). */
+export type OwnerLabel = "good" | "bad" | "no_context";
+
export type JudgePause = { provider: Exclude; until: string; reason: string };
export type ClipperChannel = {
@@ -150,9 +211,42 @@ export type ClipJudge = null
model: string; keep: boolean; score: number; reason: string; analysis?: ClipAnalysis | null; analystModel?: string;
/** Fonte em inglês: título, legenda e motivo em português (só para ler; o post sai em inglês). */
pt?: { title?: string; caption?: string; reason?: string };
+ /** Juiz de contexto (EQUIPE-IA.md). Ausente = juiz desligado, editor descartou ou corte de antes. */
+ context?: ClipContext;
+ /** "context" = quem descartou foi o juiz de contexto (dá para forçar o render). */
+ discardedBy?: "context";
}
| { error: string };
+export type ContextCheck = { ok: boolean; t: number | null; why: string };
+export type ClipContext =
+ | { error: string }
+ | {
+ model: string;
+ /** O que um espectador que nunca viu a live entende (escrito antes das checagens). */
+ viewerSummary: string;
+ checks: Partial>;
+ fix: { start_s: number | null; end_s: number | null; context_line: string };
+ confidence: number;
+ reason: string;
+ /** Fonte em inglês: resumo, motivo, frase e o porquê de cada checagem em português. */
+ pt?: { viewer_summary?: string; reason?: string; context_line?: string; checks?: Partial> };
+ /** O que o código decidiu pelas respostas. */
+ decision: "approve" | "adjust" | "discard" | "warn";
+ failed: ContextCheckId[];
+ failedCritical: ContextCheckId[];
+ solvedByLine: ContextCheckId[];
+ /** Frase de contexto que vai na tela no começo do corte ("" = nenhuma). */
+ contextLine: string;
+ scoreAfter: number | null;
+ /** Motivo da decisão, em português (montado pelo código). */
+ reasonPt: string;
+ /** Trecho novo quando o juiz ajustou. */
+ window?: [number, number];
+ /** 1ª rodada, quando houve ajuste (o juiz conferiu de novo). */
+ first?: { viewerSummary: string; checks: Partial>; failedCritical: ContextCheckId[]; reasonPt: string };
+ };
+
export type ClipTags = { risada?: number; susto?: number; hype?: number; clip?: number };
export type Clip = {
@@ -204,6 +298,9 @@ export type Clip = {
final?: ClipFinal | null;
/** O único arquivo que vai para as redes: o final pronto. null = ainda não (a publicação espera). */
publishFile?: string | null;
+ /** Sua avaliação (bom / ruim / sem contexto) para medir o juiz. Opcional: o serviço antigo não manda. */
+ ownerLabel?: OwnerLabel | null;
+ ownerNote?: string | null;
};
export type ClipFinal = {
@@ -495,6 +592,26 @@ export const TAG_LABEL: Record = { risada: "risada", sus
export const PROVIDER_LABEL: Record = { codex: "Codex (GPT)", claude: "Claude", gemini: "Gemini", off: "Desligado" };
+/** Equipe de IA: nome e o que cada papel faz (cartões da configuração). */
+export const ROLE_INFO: Record = {
+ scan: { label: "Varredura", does: "Assiste a live por janelas e propõe momentos mesmo sem pico de chat; descreve a tela para a linha do tempo." },
+ analyst: { label: "Analista", does: "Olha tela, fala e chat do trecho e diz o que aconteceu (lag, jogada, treta…). Não decide." },
+ editor: { label: "Editor", does: "Decide se vira corte, escolhe o trecho e escreve título, legenda e hashtags." },
+ judge: { label: "Juiz", does: "Só texto: vê o que vai no corte e confere se quem nunca viu a live entende — começo, desfecho, funciona sozinho." },
+};
+export const ROLE_ORDER: AiRoleId[] = ["scan", "analyst", "editor", "judge"];
+export const CHECK_LABEL: Record = {
+ setup: "começo (setup)", payoff: "desfecho", who_what: "quem/o quê", standalone: "funciona sozinho",
+ intelligible: "fala clara", faithful: "título fiel", strong_open: "abertura forte",
+};
+export const OWNER_LABEL: Record = {
+ good: { label: "Bom", tone: "success" }, bad: { label: "Ruim", tone: "danger" }, no_context: { label: "Sem contexto", tone: "warning" },
+};
+export const CONTEXT_DECISION: Record<"approve" | "adjust" | "discard" | "warn", { label: string; tone: Tone }> = {
+ approve: { label: "aprovou", tone: "success" }, adjust: { label: "ajustou o trecho", tone: "info" },
+ discard: { label: "descartou", tone: "danger" }, warn: { label: "avisou", tone: "warning" },
+};
+
/** Sessões que ainda mudam sozinhas (vale consultar de novo). */
export const ACTIVE_SESSION: SessionStatus[] = ["starting", "recording", "processing"];
/** Cortes que ainda mudam sozinhos (IA ou render). */
diff --git a/panel/src/components/clipper-clip-dialog.tsx b/panel/src/components/clipper-clip-dialog.tsx
index ecce948..e7e003c 100644
--- a/panel/src/components/clipper-clip-dialog.tsx
+++ b/panel/src/components/clipper-clip-dialog.tsx
@@ -6,7 +6,8 @@
import { useEffect, useState } from "react";
import { CLIP_STATUS, SOURCE_LABEL, clipperCall, formatClock, formatDuration, languageLabel, useClipperAction, type Clip, type ClipperSession } from "./clipper-client";
import {
- ChatSignals, ClipActions, ClipMedia, ClipVideoState, DeleteControl, FaceSignal, JudgeVerdict, TrimControl, situationLabel, type DeleteClip,
+ ChatSignals, ClipActions, ClipMedia, ClipVideoState, DeleteControl, FaceSignal, JudgeVerdict, OwnerLabelControl, TrimControl, situationLabel,
+ type DeleteClip,
} from "./clipper-clip-parts";
import { isOther, speakerLabel } from "./clip-editor-model";
import { Dialog } from "./dialog";
@@ -117,6 +118,7 @@ function ClipBody({ clip, onChanged, publishJobs }: { clip: Clip; onChanged: ()
+
{clip.status === "error" && clip.error && (
diff --git a/panel/src/components/clipper-clip-parts.tsx b/panel/src/components/clipper-clip-parts.tsx
index 6baf796..d71ad87 100644
--- a/panel/src/components/clipper-clip-parts.tsx
+++ b/panel/src/components/clipper-clip-parts.tsx
@@ -5,9 +5,9 @@
// confirmação curta no lugar. Nada aqui busca dados: tudo vem por props; cada ação chama `run` (useClipperAction).
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
- ACTIVE_CLIP, CLIP_STATUS, DEV_LAYER_LABEL, FACE_LABEL, SITUATION_LABEL, TAG_LABEL, UNDELETABLE_CLIP, aspectOf, clipperCall, formatClock, formatDuration, formatScore,
- reviewHasDevLayers,
- type Clip, type ClipAnalysis, type ClipTags, type Situation, type useClipperAction,
+ ACTIVE_CLIP, CHECK_LABEL, CLIP_STATUS, CONTEXT_DECISION, DEV_LAYER_LABEL, FACE_LABEL, OWNER_LABEL, SITUATION_LABEL, TAG_LABEL, UNDELETABLE_CLIP, aspectOf,
+ clipperCall, formatClock, formatDuration, formatScore, reviewHasDevLayers,
+ type Clip, type ClipAnalysis, type ClipContext, type ClipTags, type ContextCheckId, type OwnerLabel, type Situation, type useClipperAction,
} from "./clipper-client";
import { ClipPublishButton } from "./clip-publish";
import { AlertIcon, CheckIcon, EyeIcon, RefreshIcon, ScissorsIcon, SparkIcon, TrashIcon, UndoIcon, XIcon } from "./icons";
@@ -250,10 +250,107 @@ export function JudgeVerdict({ clip }: { clip: Clip }) {
{(judge.pt?.reason || judge.reason) &&
{judge.pt?.reason || judge.reason}
}
+ {judge.context && }
>
);
}
+/** O JUIZ de contexto (EQUIPE-IA.md): o que um espectador frio entende, as checagens e o que o código decidiu. */
+export function ContextVerdict({ context }: { context: ClipContext }) {
+ if ("error" in context) {
+ return (
+
+
+ O juiz não conseguiu conferir o contexto (ficou a decisão do editor): {context.error}
+