Clipador: Equipe de IA (papéis com IA própria), juiz de contexto e linha do tempo JSON

- 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 <noreply@anthropic.com>
This commit is contained in:
Mateuus
2026-11-18 04:36:25 -03:00
co-authored by Claude Opus 5.5
parent 5be6c09c16
commit cb8450399d
17 changed files with 2081 additions and 116 deletions
+197 -51
View File
@@ -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