Motor Gráfico — Parte 1: Pipeline, Agentes e Prompts¶

Como o conteúdo é gerado, passo a passo, do momento em que o cliente aprova uma ideia até o carrossel ficar pronto.

Visão Geral do Pipeline¶

O pipeline é a sequência de 7 etapas que transforma uma ideia de post em um carrossel pronto com imagens PNG, legenda e hashtags. Cada etapa é executada por um agente especializado — módulo Python que chama o LLM com um prompt específico.

Tempo total médio: 40-50 segundos. Arquivo principal: cadencia-workers/src/workers/orchestrator.py (454 linhas)

Fluxo de disparo¶

1. Cliente aprova uma ideia (swipe direito)
2. Frontend chama POST /api/v1/pipeline/run com idea_id
3. Backend cria registro em generation_queue com status "pending" e prioridade (1 pagos, 0 trial)
4. Pipeline inicia em thread separada — retorna 202 Accepted imediatamente
5. Cada etapa atualiza progresso em pipeline_status
6. Frontend faz polling a cada 3s em GET /api/v1/pipeline/status/{queue_id}
7. Quando termina: documento fica "ready" e aparece na aba Posts

As 7 etapas¶

Operações no banco durante o pipeline¶

Etapa 1 — Research Agent¶

Arquivo: cadencia-workers/src/workers/research_agent/__init__.py (117 linhas)

Propósito: Todos os outros agentes dependem deste documento. Sem ele, geram conteúdo genérico.

Fluxo: 1. Recebe: idea, editorial, dossier, config 2. Monta prompt com _build_prompt() 3. Envia ao LLM (max_tokens=1500) 4. Remove code fences, faz json.loads() 5. Valida via Pydantic (ResearchDocument) 6. Salva em research_documents

Prompt completo do Research Agent¶

Você é um pesquisador de conteúdo para Instagram.
Produza um Research Document completo para esta ideia de carrossel.

REGRAS:
- Tudo em pt-BR.
- Dados REAIS e verificáveis quando possível.
- Use o Método X/Y: X = problema superficial, Y = transformação real.
- O documento serve como base para um carrossel educativo/inspiracional.
- Seja específico ao nicho do profissional.

IDEIA:
- Título: {idea.title}
- Descrição: {idea.description}

EDITORIAL:
- Nome: {editorial.name}
- Função: {editorial.editorial_function}
- Tom: {editorial.tone}

CONTEXTO:
- Nicho: {config.nicho}
- Posicionamento: {dossier.posicionamento (truncado em 300 chars)}
- Público-alvo: {dossier.publico_alvo (truncado em 300 chars)}

Responda EXATAMENTE no formato JSON (sem markdown, sem code fences):
{
  "topic": "Tópico principal",
  "key_facts": ["Fato 1", "Fato 2", "Fato 3"],
  "audience_pain": "Dor principal que o conteúdo resolve",
  "audience_desire": "O que o público quer alcançar",
  "x_problem": "Problema superficial (X)",
  "y_meaning": "Transformação real (Y)",
  "hook_angle": "Ângulo do gancho emocional",
  "data_points": ["Dado 1", "Dado 2"]
}

Campos do output¶

Configurações editáveis¶

Etapa 2 — Model Selection¶

Arquivo: cadencia-workers/src/shared/model_config.py, linhas 126-158 e 253-294

Fase 1 — Classificação via LLM¶

Chama classify_idea() com max_tokens=400. Retorna JSON com 12 flags booleanas + content_type.

Fallback: se o LLM falhar, todas as flags assumem false e content_type assume "general". Pipeline não para.

As 12 flags de classificação¶

Fase 2 — Filtragem de modelos compatíveis¶

3 filtros em sequência: 1. compatible_nichos do modelo inclui o nicho do tenant (ou "all") 2. compatible_editorials inclui a função editorial do post (ou está vazia) 3. Modelo NÃO é um dos 3 últimos usados pelo tenant (anti-repetição)

Fase 3 — Scoring Engine¶

Para cada modelo que passou nos filtros: - Consulta FLAG_MODEL_AFFINITY para cada flag True → soma pontos - Consulta CONTENT_TYPE_AFFINITY para o content_type → soma pontos extras - Ordena por score decrescente - Version 0 → maior score; Version 1 → 2º; Version 2 → 3º

Tabela de afinidade Flag → Modelo → Pontos¶

Tabela de afinidade por Content Type (boost menor)¶

Etapa 3 — Headline Agent¶

Arquivo: cadencia-workers/src/workers/headline_agent/__init__.py (139 linhas)

Fluxo: Recebe ideia, research, editoria, config, version_index → monta prompt → LLM (max_tokens=500) → valida via Pydantic → salva em content_headlines

Prompt completo¶

Você é um copywriter especialista em Instagram.
Gere uma headline IMPACTANTE para este carrossel.

REGRAS:
- Headline: MÁXIMO 8 palavras. Curta, direta, impossível de ignorar.
- Subtitle: 1 frase complementar que expanda a headline.
- Hook type: escolha entre autoridade, curiosidade, dados, provocação,
  prova_social, medo, aspiração.
- Focus keyword: 1 palavra-chave principal.
- Highlighted words: 2-3 palavras do headline para destacar visualmente.
- Tudo em pt-BR.
- Siga a regra de headline da editoria.

{instrução especial de versão, se version_index > 0}

IDEIA: {idea.title} / {idea.description}
PESQUISA: dor={research.audience_pain}, gancho={research.hook_angle}, X={research.x_problem}
EDITORIAL: regra={editorial.headline_rule}, tom={editorial.tone}
NICHO: {nicho}

Os 7 tipos de gancho (hook_type)¶

Versões alternativas¶

Etapa 4 — Carousel Agent¶

Arquivo: cadencia-workers/src/workers/carousel_agent/__init__.py (151 linhas)

Fluxo: 1. Recebe 12 parâmetros: idea, research, headline, editorial, model, config, dossier, content_restrictions, profile_insights, cta_mode, cta_keyword 2. Carrega YAML do modelo via load_model(slug) (cacheado em memória) 3. Fallback para "lista" se modelo não encontrado 4. build_carousel_prompt() monta o prompt mais longo do sistema 5. LLM com max_tokens=3000 6. Parse JSON (aceita {"slides": [...]} ou bare [...]) 7. Valida: mínimo 3 slides, máximo 12 8. Salva em content_documents.slides_content

O framework AIDA¶

Níveis de personalização¶

As 7 regras globais de geração¶

CTA dinâmico¶

Etapa 5 — Caption Agent¶

Arquivo: cadencia-workers/src/workers/caption_agent/__init__.py (116 linhas) max_tokens: 1000

Estrutura P/R/Cr/Cp/CTA¶

Configurações: máximo 300 palavras, 2-3 emojis, parágrafos de 2-3 linhas, 10-15 hashtags.

Etapa 6 — Cover Generation¶

Arquivo: cadencia-workers/src/workers/cover_generation.py (431 linhas)

Geração de capa é não-fatal. Se falhar, pipeline continua com capa tipográfica.

Árvore de decisão¶

1. Categoria do modelo é "social" (meme, citação, motivacional)? → Pula a capa
2. cover_style == "person" E tenant tem ≥1 foto? → Modo Person (foto com rosto real)
3. cover_style == "thematic" OU sem fotos? → Modo Thematic (cena sem rosto)

Modo Person¶

1. Verifica se tenant tem physical_description salva
2. Se não: envia 1 foto ao Gemini 2.5 Flash e gera descrição física em 2-3 frases (custo único)
3. Seleciona cena aleatória das templates da editoria (3-4 opções)
4. Monta prompt com: Identity Lock + Camera Specs + Scene
5. Envia ao Gemini gemini-3.1-flash-image-preview com até 6 fotos de referência
6. Upload para content/{tenant_id}/{doc_id}/cover.png no Supabase Storage

Identity Lock prompt:

SUBJECT IDENTITY (must match ALL reference images exactly):
{physical_description}

CRITICAL FACE RULES:
- LEAN face with angular jawline — NOT round, NOT chubby.
- Do NOT make face rounder/fuller than references.
- Match EXACT facial proportions shown in references.
- Same eye shape, nose bridge contour, jawline angle, lip proportions.
- Same beard pattern, hair style, skin texture.

Camera Specs por editoria¶

Regras comuns: profundidade rasa, bokeh natural, leve grão, sem pele plástica. Formato 4:5 (1080x1350px). SEM texto, watermarks ou logos.

Modo Thematic¶

Prompt simplificado com camera specs + cena + regra "sem pessoas". Geração via Gemini, sem Identity Lock.

Notas Relacionadas¶

• Projetos/Cadencia/Docs/Motor-Grafico-Carrosseis-Doc-Tecnica
• Projetos/Cadencia/Docs/Motor-Parte2-Modelos-Templates-BD
• Projetos/Cadencia/Docs/PRD-Arquitetura-Tecnica