Módulo data_platform.typesense ausente no Cloud Composer

[mauriciomendonca]

User Story

Como operador da plataforma DGB,
Quero que os jobs de Typesense (clusters, trending, engagement) consigam importar o módulo data_platform.typesense no Cloud Composer,
Para que a indexação de busca, cálculo de trending e agregação de engagement voltem a funcionar.

Contexto

As DAGs compute_clusters, compute_trending e aggregate_engagement estão falhando com ModuleNotFoundError desde pelo menos 03/03/2026 (~9 falhas/dia combinadas).

Causa raiz

O código dos jobs em src/data_platform/jobs/typesense/collection_ops.py:10 faz:

from data_platform.typesense import (
    get_client,
    delete_collection,
    list_collections,
    COLLECTION_NAME,
)

Este código é deployado como plugin do Airflow em /home/airflow/gcs/plugins/data_platform/jobs/typesense/collection_ops.py. Porém, o módulo data_platform.typesense não está disponível no ambiente do Composer.

Pacotes instalados no Composer (nenhum inclui data_platform)

pypiPackages:
  apache-airflow-providers-google: '>=10.14.0'
  apache-airflow-providers-postgres: '>=5.10.2'
  boto3: '>=1.35.0'
  psycopg2-binary: '>=2.9.9'
  requests: '>=2.31.0'
  sqlalchemy: '>=1.4.52'

O módulo existe localmente

O módulo data_platform/typesense/ existe em src/data_platform/typesense/ com os arquivos:

• __init__.py — re-exports de client, collection, indexer, utils
• client.py — conexão com Typesense (get_client, wait_for_typesense)
• collection.py — schema da collection (COLLECTION_NAME, create_collection)
• indexer.py — indexação de documentos
• utils.py — utilitários (calculate_published_week)

Erro completo

File "/home/airflow/gcs/plugins/data_platform/jobs/typesense/collection_ops.py", line 10, in <module>
    from data_platform.typesense import (
ModuleNotFoundError: No module named 'data_platform.typesense'

DAGs afetadas

DAG	Task	Falhas/dia
compute_clusters	find_and_store_clusters	~4
compute_trending	compute_and_sync_trending	~3
aggregate_engagement	aggregate_and_sync	~2

Impacto

• Busca no portal pode estar com dados desatualizados (Typesense não sendo sincronizado)
• Trending e clusters não estão sendo calculados
• Agregação de engagement parada

Critérios de Aceite

• O módulo data_platform.typesense está disponível no ambiente do Cloud Composer
• As 3 DAGs afetadas executam com sucesso
• Escolher abordagem: (a) instalar data_platform como PyPI package no Composer, OU (b) garantir que o deploy de plugins inclui o módulo typesense/ com __init__.py correto, OU (c) refatorar imports para não depender do pacote instalado
• Dependências do Typesense (ex: typesense Python client) também devem estar nos PyPI packages do Composer

Arquivos relevantes

• src/data_platform/jobs/typesense/collection_ops.py — import que falha
• src/data_platform/jobs/typesense/sync_job.py — outro arquivo com mesma dependência
• src/data_platform/typesense/ — módulo que precisa estar disponível
• Terraform/config do Composer — onde PyPI packages são definidos

Dependências

• Pode depender de configuração Terraform no repo infra (PyPI packages do Composer)

[mauriciomendonca]

Verificação automática - 2026-04-01

O ModuleNotFoundError: No module named 'data_platform.typesense' foi resolvido:

• compute_clusters: 10 runs consecutivas com sucesso (desde 2026-03-23)
• compute_trending: runs bem-sucedidas múltiplas vezes ao dia

aggregate_engagement ainda está falhando, mas por um erro diferente (FK violation), não mais pelo problema de módulo descrito nesta issue. Foi aberta nova issue para rastrear esse problema: ver #107.

Encerrando esta issue como resolvida.

[mauriciomendonca]

Correção: a nova issue para o ForeignKeyViolation no aggregate_engagement foi criada como #121 (não #107 como mencionado acima).

[miguellsfilho]

Reabrindo - Diagnóstico Incorreto

A issue foi fechada em 2026-04-01 com a afirmação de que compute_clusters, compute_trending e aggregate_engagement estavam funcionando.

Análise Corrigida

DAGs mencionadas originalmente NÃO usam Typesense:

• ✅ compute_clusters - funcionando (usa apenas PG/pgvector)
• ✅ compute_trending - funcionando (usa apenas BigQuery/PG)
• ❌ aggregate_engagement - falhando com FK violation (issue ForeignKeyViolation em aggregate_engagement ao fazer upsert em news_features #121, não relacionado a Typesense)

Problema Real Identificado

A DAG que realmente usa Typesense e está falhando é:

verify_news_integrity (deployada em 2026-04-01, PR #104)

Erro confirmado via Cloud Logging:

ModuleNotFoundError: No module named 'data_platform.jobs.integrity'
Local: verify_news_integrity.py linha 57

Causa Raiz (confirmada via logs e inspeção GCS):

1. ❌ Módulo data_platform/jobs/integrity/ não deployado no Composer
2. ❌ Módulo data_platform/typesense/ não deployado no Composer
3. ❌ Pacote PyPI typesense não instalado em composer.tf
4. ❌ Bug de import: linha 116 usa get_typesense_client (deveria ser get_client)

Frequência: Falhando a cada 30 minutos desde deploy às 14:16 UTC.

Correções Necessárias

3 arquivos, ~5 linhas modificadas:

1. verify_news_integrity.py (2 linhas):

   • Linha 116: trocar get_typesense_client por get_client
   • Linha 126: trocar get_typesense_client() por get_client()

2. composer-deploy-dags.yaml (~4 linhas adicionadas):

   • Adicionar deploy de data_platform/jobs/integrity/
   • Adicionar deploy de data_platform/typesense/

3. composer.tf (1 linha):

   • Adicionar "typesense" = ">=1.3.0" em pypi_packages

Ordem de Implementação

1. PRIMEIRO: Terraform (adicionar pacote typesense)
2. DEPOIS: Código (fix import + adicionar módulos ao workflow)
3. VERIFICAR: Aguardar próxima execução da DAG (30 min)

Referências

• Cloud Logging: 18+ falhas desde 2026-04-01 13:00 UTC
• GCS bucket: módulos integrity/ e typesense/ confirmados ausentes
• Issue ForeignKeyViolation em aggregate_engagement ao fazer upsert em news_features #121: FK violation em aggregate_engagement (problema separado)

[miguellsfilho]

@nitaibezerra - atualização sobre a implementação:

✅ Progresso

Foram criados 2 PRs para resolver esta issue:

1. PR infra#168 (Terraform)

Status: ⏳ Aguardando merge

Adiciona ao Cloud Composer:

• Pacote PyPI typesense>=1.3.0
• Env var TYPESENSE_PORT=8108

2. PR #126 (Código)

Status: ⏳ Aguardando review

Correções aplicadas:

• Bug fix: verify_news_integrity.py linhas 116 e 126 (import corrigido)
• Integração: client.py agora suporta Airflow Variables para API key
• Deploy: Workflow atualizado para deployar módulos integrity/ e typesense/

⏸️ Bloqueador: Fase 2 - Credenciais (requer permissões GCP)

A DAG precisa de um Airflow Variable com a API key do Typesense. Este secret precisa ser criado no Secret Manager:

Comandos necessários:

# 1. Obter API key atual do Typesense
# Fonte: Relatório de Pentest CPQD (pág. 18) ou secret existente typesense-write-conn
API_KEY="<valor-da-api-key-aqui>"

# 2. Criar Airflow Variable no Secret Manager
echo "$API_KEY" | gcloud secrets create airflow-variables-typesense_api_key \
  --project=inspire-7-finep \
  --replication-policy="automatic" \
  --data-file=-

# 3. Grant access ao Composer
gcloud secrets add-iam-policy-binding airflow-variables-typesense_api_key \
  --project=inspire-7-finep \
  --member="serviceAccount:destaquesgovbr-composer@inspire-7-finep.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

# 4. Verificar
gcloud secrets describe airflow-variables-typesense_api_key --project=inspire-7-finep

Nota sobre API key:

• ⚠️ A chave atual está exposta no GitHub (themes#2, CVSS 9.4) e será revogada em breve
• ✅ A solução implementada suporta rotação automática (zero downtime)
• Quando nova key for gerada: apenas atualizar o secret, DAG usa automaticamente

🚀 Ordem de Execução

Para desbloquear a DAG:

1. Merge PR infra#168

   • Aguardar Terraform apply (~2-3 min)
   • Aguardar instalação do pacote (~5-10 min)

2. Criar secret (comandos acima)

3. Merge PR fix: resolver issue #105 - módulo typesense ausente no Composer #126

   • GitHub Actions fará deploy automático

4. Verificar: Aguardar próxima execução da DAG (30 min)

Timeline estimada: ~1-2 horas total

📋 Preparado para Rotação (themes#2)

Quando a API key for rotacionada:

# Atualizar secret (apenas 1 comando)
echo "$NEW_API_KEY" | gcloud secrets versions add airflow-variables-typesense_api_key \
  --project=inspire-7-finep \
  --data-file=-

A DAG usará automaticamente a nova key na próxima execução (1-2 min), sem restart do Composer.

---

Resumo: 2 PRs criados, aguardando apenas criação do secret para completar a resolução da issue.

[nitaibezerra]

Atualização — progresso na resolução

✅ Infra completa

1. PR infra#168 — mergeado. Pacote typesense>=1.3.0,<2.0.0 + env var TYPESENSE_PORT instalados no Composer.

2. PR infra#170 — mergeado. Criação do secret airflow-variables-typesense_api_key e IAM binding via Terraform (seguindo o padrão existente para secrets com valor gerido manualmente).

3. Secret populado — o valor da API key foi copiado do secret typesense-api-key existente para o novo airflow-variables-typesense_api_key. O Composer já consegue ler como Airflow Variable.

⏳ Código — PR #126

Aprovado com uma sugestão de ajuste: refinar o except Exception: pass em client.py para capturar apenas ImportError (fora do Airflow), deixando erros reais do backend visíveis. Detalhes no review do PR.

Após o ajuste e merge do #126, a DAG verify_news_integrity deve voltar a funcionar na próxima execução (~30 min).