Telex BR

Pipeline que coleta, classifica e cura notícias brasileiras a cada 12 horas. A cota de equilíbrio editorial (4 direita · 4 esquerda · 4 centro · 8 técnica/neutra) é aplicada por tópico de conteúdo — política, macroeconomia e manchetes — então o ciclo sai com até 20 itens em cada um dos três (60 no total), sempre destacando a notícia de maior audiência (proxy) e a de maior repercussão (proxy) do ciclo. Implementação do blueprint técnico publicado em claude.ai/code/artifact/7735ea40-7bab-4654-b95c-c0fe597cda31.

Painel ao vivo

telex-br.vercel.app — lê data/cycles/latest.json direto do GitHub no navegador de quem abrir, então sempre mostra o ciclo mais recente. Site 100% estático (dashboard-live.html + vercel.json), sem servidor próprio nem build — a Vercel só serve o HTML. O mesmo arquivo também responde em https://telex-br-trigger.onrender.com/dashboard (espelho, servido pelo Render — ver seção de gatilho abaixo).

Rodando agora, em 2 minutos

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -r requirements.txt
python -m src.pipeline --demo

Isso roda o pipeline inteiro (coleta → classificação → pontuação → curadoria → exportação) sobre data/sample/sample_items.json — 30 itens de amostra cobrindo os quatro buckets editoriais — sem nenhuma chamada de rede. Gera data/cycles/latest.json e data/cycles/latest.csv e imprime um resumo no terminal.

Rodar os testes (mesma base, sem rede, é o que roda no CI):

pip install -r requirements.txt
pytest -q

Antes de rodar de verdade (python -m src.pipeline, sem --demo)

config/sources.json já vem com 30 fontes ativas em direita/esquerda/ centro (10/14/6) — pesquisadas e testadas de verdade, cada uma com note citando de onde veio a classificação: Monitor do Debate Político no Meio Digital (USP/CEBRAP) e/ou o artigo acadêmico "Classificação ideológica de fontes informacionais..." (Opinião Pública/Unicamp-Cesop, 2024, SciELO) — ver docs/pesquisa-classificacao-editorial.md pro detalhe completo, inclusive os avisos de tier mais fraco (fonte "amplamente caracterizada" mas não citada academicamente, ou "extensão por analogia" pro bucket centro, o mais contestado dos quatro). Não atribuímos linha editorial a veículo nenhum por conta própria — é uma chamada contestável e muda com o tempo (ver o blueprint, seção b).

Pra adicionar mais uma fonte a qualquer bucket:

1. Escolha o veículo, validando contra observatório de mídia reconhecido (não só impressão pessoal) — ou reaproveite um candidato já listado em docs/pesquisa-classificacao-editorial.md que não entrou por falta de RSS funcional na época.
2. Teste o RSS de verdade contra a rede antes de adicionar (feeds mudam de URL, saem do ar, viram 404 — não confie sem testar).
3. Adicione um objeto { "id", "name", "rss", "status": "active", "note" } no bucket certo.

tecnica_neutra (8 fontes) já vem preenchido com fontes factuais/institucionais (agências públicas, dados oficiais, imprensa econômica, checagem) — essa é uma classificação factual, não política, então não carrega o mesmo aviso de metodologia. Se algum bucket ficar sem fonte suficiente pra fechar a cota de 20 num tópico, curate.py roda normalmente com o que tiver — a lacuna fica registrada em quota_status no JSON de saída, por tópico e por linha editorial, não escondida.

Estrutura

src/
  collect.py    01 · RSS (feedparser) + indicadores BCB/IBGE
  classify.py   02 · linha editorial (do bucket da fonte) + categoria (por palavra-chave)
  score.py      03 · cluster de cobertura + proxies opcionais (Trends, Reddit)
  curate.py     04 · seleciona até 20 por tópico (política/macro/manchete) respeitando 4·4·4·8, marca top view/réplica
  export.py     05 · grava JSON + CSV do ciclo
  pipeline.py   orquestra as 5 etapas, CLI (--demo, --window)
config/
  sources.json  tabela de fontes (editável, ver acima)
  keywords.json taxonomia de categoria (política/macroeconomia/manchete)
data/
  sample/       fixture usada pelo --demo
  cycles/       saída real (latest.json, latest.csv, histórico com timestamp)
tests/          smoke test em cima do modo --demo
web/
  app.py         endpoint HTTP que roda o pipeline (gatilho via Render)
  github_sync.py commita latest.json/latest.csv de volta no repo via API
dashboard-live.html   painel público (fetch client-side do latest.json — ver "Painel ao vivo")
render.yaml     blueprint do Render (deploy do web/app.py) + buildFilter (ver seção de gatilho)
vercel.json     serve dashboard-live.html como site estático na Vercel
.github/workflows/cycle.yml   disparo manual (cron original, hoje pausado — ver seção de gatilho)

Proxies de impacto — o que é real e o que é estimado

Pageviews e contagens de compartilhamento reais não são públicos por fonte no Brasil (e o CrowdTangle, caminho gratuito padrão pra isso, foi descontinuado pela Meta em agosto de 2024). score.py compõe dois índices a partir de sinais que são abertos:

Sinal	Sempre disponível?	Como ligar
Tamanho do cluster de cobertura (quantas fontes do próprio ciclo publicaram algo parecido)	Sim — não depende de nenhuma credencial	já ligado
Google Trends (interesse de busca)	Não — precisa de pip install -r requirements-optional.txt	automático se o pacote estiver instalado
Menções no Reddit (r/brasil)	Não — precisa de credenciais	preencha REDDIT_CLIENT_ID/REDDIT_CLIENT_SECRET no .env (copie de .env.example)

Sem os dois opcionais, view_score e engagement_proxy_index caem só no cluster — funciona, mas dois itens do mesmo cluster empatam com mais frequência. Vale a pena ligar pelo menos o Reddit (é grátis, só precisa de um app tipo "script" em reddit.com/prefs/apps).

Ligar ao Power BI (grátis)

1. O gatilho de 12h (ver abaixo) mantém data/cycles/latest.csv sempre atualizado no repositório.
2. No Power BI Desktop: Obter Dados → Web → cole a URL "raw" do arquivo no GitHub: https://raw.githubusercontent.com/Hardcastro/telex-br/main/data/cycles/latest.csv.
3. Publique no Power BI Service. Free tier: até 8 atualizações/dia em "Minha área de trabalho" — sobra folga para os 2 refreshes/dia do ciclo de 12h. Compartilhar exige Publicar na Web (público, sem login) — é a única forma de compartilhar sem licença Pro.
4. Se a atualização agendada do Service recusar o Web connector por detecção de fonte dinâmica, troque a URL no editor Power Query para uma string estática fixa (sem parâmetros) — normalmente resolve.

Looker Studio segue a mesma lógica (Conectar → URL) e não tem o limite de 8 atualizações/dia, se isso virar um problema no futuro.

Gatilho de 12h — via Render (grátis, é o que está ativo hoje)

O GitHub Actions da conta ficou bloqueado por faturamento, então o "relógio" de 12h saiu de dentro do GitHub: web/app.py sobe um endpoint HTTP minúsculo no Render (free, sem cartão de crédito) que roda o pipeline quando chamado, e um cron externo gratuito — cron-job.org — bate nesse endpoint duas vezes por dia. O resultado volta pro GitHub via API (web/github_sync.py), porque o disco do Render free não é persistente.

Duas contas grátis pra criar (não dá pra automatizar isso por você — as duas exigem confirmar login/e-mail no navegador):

1. Render — subir o serviço

1. Crie conta em render.com (dá pra entrar direto com a conta do GitHub).
2. New → Blueprint, conecte o repositório telex-br. O Render lê o render.yaml do repo sozinho e propõe o serviço telex-br-trigger.
3. Preencha as duas env vars que o blueprint deixa em aberto:
   • RUN_TOKEN — invente uma string aleatória qualquer (é a "senha" do endpoint — sem ela, qualquer um que ache a URL consome suas horas grátis do Render disparando ciclos à toa).
   • GITHUB_TOKEN — um personal access token (fine-grained, só no repo telex-br, permissão Contents: Read and write) — é o que deixa o serviço commitar latest.json/latest.csv de volta.
4. Deploy. Quando subir, teste na mão: https://telex-br-trigger.onrender.com/run-cycle?token=SEU_RUN_TOKEN — deve responder {"ok": true, ...} e, minutos depois, aparecer um novo commit em data/cycles/ no GitHub.

2. cron-job.org — o relógio

1. Crie conta grátis em cron-job.org.
2. Novo cronjob → URL: https://telex-br-trigger.onrender.com/run-cycle?token=SEU_RUN_TOKEN, método POST, horário: 0 e 12 (duas vezes ao dia — o serviço já assume janela de 12h por padrão, então basta rodar a cada 12h; não precisa bater exatamente 00:00/12:00 BRT).
3. Pronto — isso é literalmente o gatilho de 12h rodando.

O serviço do Render "dorme" depois de 15min sem uso e leva ~1min pra acordar na chamada seguinte — sem problema aqui, já que só é chamado 2x/dia.

Pegadinha real que já aconteceu: web/github_sync.py commita data/cycles/latest.{json,csv} de volta no repo a cada ciclo, e por padrão o Render redeploya o serviço inteiro a cada push no main — ou seja, 2 redeploys completos a cada ciclo (json + csv = 2 commits), só por causa de um arquivo de dados, sem nenhuma mudança de código. Isso deixou o gatilho automático falhando silenciosamente por 3 dias (o cron-job.org batia no serviço bem no meio de um redeploy e recebia x-render-routing: no-deploy do Render, sem nem chegar no Flask). render.yaml já vem com buildFilter.ignoredPaths: ["data/cycles/**"] pra evitar isso — se algum dia parecer que o gatilho parou de novo, o primeiro lugar pra olhar é Render → Deploys: se tiver um deploy novo por ciclo, o filtro não está valendo (confere se o serviço ainda está "Blueprint managed" e se o render.yaml do repo bate com o que está configurado no painel).

Se resolver o problema de faturamento do GitHub depois: o workflow .github/workflows/cycle.yml continua no repo, só sem o schedule: (fica só como disparo manual pela aba Actions). Para voltar a usá-lo como cron, é só devolver o bloco:

schedule:
  - cron: "0 3,15 * * *"

e pode desligar o Render/cron-job.org se preferir manter tudo dentro do GitHub.

100% gratuito nos dois desenhos: RSS + BCB/IBGE (coleta), Render + cron-job.org ou GitHub Actions (gatilho), Power BI free (visualização). Nenhuma peça paga é necessária para o ciclo de 12h funcionar de ponta a ponta.

Publicar o painel na Vercel

Já está publicado em telex-br.vercel.app — isto aqui é só o passo a passo caso precise recriar:

1. vercel.com/new → Import Git Repository → Hardcastro/telex-br.
2. Application Preset: Other (não deixa cair em "Python" — o preset errado tenta buildar o pipeline como app, e aqui é só um HTML estático).
3. Zero variáveis de ambiente — apague qualquer uma que a Vercel sugerir (ela escaneia .env.example e sugere as chaves de lá, mas dashboard-live.html não usa nenhuma; são só do lado do pipeline).
4. Deploy. vercel.json já redireciona toda rota pra dashboard-live.html.

Sem build step: é puro HTML/CSS/JS buscando latest.json direto do GitHub no navegador. Um push no repo só atualiza a Vercel se mudar dashboard-live.html ou vercel.json — os commits de ciclo (data/cycles/**) não disparam rebuild aqui por padrão (a Vercel só redeploya em mudança de arquivo servido), mas o painel mostra dado novo de qualquer forma, já que o fetch é em tempo de carregamento, não em build.

Limitações conhecidas / próximos passos

• IBGE (PIB, desemprego): collect.py::fetch_ibge_indicator está pronta mas não vem com código de tabela SIDRA pré-preenchido — não íamos inventar um número de tabela sem confirmar contra sidra.ibge.gov.br. Preencha IBGE_PIB_TABLE etc. no .env depois de checar a tabela certa.
• Categoria por palavra-chave (config/keywords.json) é simples de propósito. Se começar a classificar muita coisa errado, o próximo passo natural é trocar por NLP (spaCy pt_core_news) — a interface de classify_category() não muda, só a implementação interna.
• GDELT, NewsData.io, Currents (citados no blueprint como fontes adicionais) ainda não estão integrados em collect.py — hoje a coleta é só RSS + BCB/IBGE. RSS cobre a curadoria toda; os outros valem a pena principalmente se a lista de fontes RSS não for suficiente.
• Perguntas de alinhamento do blueprint (seção f) — várias ainda valem a pena fechar com o time antes de considerar isso "em produção": quem valida a tabela de classificação, se há orçamento para upgrades pagos, se o dashboard guarda histórico de ciclos, etc.