---

name: Report Generation description: Automated generation of technical and legal reports from electoral analysis data. Supports national consolidation and per-state breakdowns.

SKILL: Report Generation (Geração de Relatórios Técnicos)

Objetivo

Gerar relatórios técnicos profissionais (PDF/Docx) a partir dos dados do analysis_results.csv, com fundamentação jurídica fornecida pelo agente TSE Justice.

Estrutura de Relatórios

Tipos de Relatório

1. Relatório Nacional (Consolidado)

Escopo: Análise agregada de todos os estados (AC, AP, RR, TO, SE). Seções:

• Sumário Executivo
• Metodologia
• Resultados Agregados (500 Hipóteses)
• Anomalias Detectadas (Nacional)
• Parecer Jurídico Consolidado
• Recomendações Gerais

2. Relatório por UF

Escopo: Análise específica de um estado. Seções:

• Contexto Local (População, Seções, Comparecimento)
• Resultados Específicos da UF
• Comparação com Média Nacional
• Anomalias Locais
• Parecer Jurídico Estadual

Workflow de Geração

Fase 1: Coleta de Dados

# Pseudocódigo
df_results = pd.read_csv("analysis_results.csv")
df_temporal = query_db("SELECT * FROM temporal_metrics WHERE uf = ?")
df_logs = query_db("SELECT COUNT(*) FROM log_eventos WHERE source_file LIKE ?")

Fase 2: Análise e Agregação

# Métricas Nacionais
total_hipoteses = len(df_results)
cobertura = (df_results['Status'].isin(['PASS','INFO','FAIL']).sum() / 500) * 100
anomalias = df_results[df_results['Status'].str.contains('FAIL')].copy()

# Métricas por UF
for uf in ['AC', 'AP', 'RR', 'TO', 'SE']:
    uf_logs = query_uf_stats(uf)
    uf_anomalias = filter_anomalias_by_uf(anomalias, uf)

Fase 3: Fundamentação Jurídica

# Invocar TSE Justice Agent
parecer = tse_justice.gerar_parecer(
    anomalias=anomalias,
    nivel_gravidade='MEDIA',
    precedentes=['AC 060338495/2018']
)

Fase 4: Renderização

# Opção 1: PDF (via ReportLab ou WeasyPrint)
pdf = generate_pdf(template='relatorio_nacional.html', data=context)

# Opção 2: Docx (via python-docx)
doc = Document()
doc.add_heading('Relatório Técnico Brurna Analytics', 0)
# ... adicionar seções
doc.save('relatorio_nacional.docx')

Templates de Relatório

Template: Sumário Executivo

# SUMÁRIO EXECUTIVO

**Período de Análise**: [Data Inicial] a [Data Final]
**Estados Analisados**: AC, AP, RR, TO, SE
**Total de Seções**: [X]
**Total de Logs Processados**: [Y]

## Principais Achados
- ✅ **Cobertura**: [99.8%] das hipóteses validadas
- ⚠️ **Anomalias**: [N] seções com comportamento atípico
- 📊 **Conformidade**: [%] de conformidade com padrões esperados

## Conclusão Preliminar
[Texto gerado pelo TSE Justice Agent]

Template: Seção de Anomalias

## ANOMALIAS DETECTADAS

### Hipótese H464: Isolation Forest (Machine Learning)
**Status**: FAIL (Anomaly Detected)
**Descrição**: Detecção de anomalias via Isolation Forest não aponta fraude sistêmica.
**Observação**: Found 67 outliers > 3 sigma

**Fundamentação Jurídica**:
> Com fulcro no art. 5º da Resolução TSE 23.603/2019, a análise estatística via Machine Learning constitui indício de comportamento atípico, mas não prova material de irregularidade. Recomenda-se auditoria física das urnas identificadas.

**Seções Afetadas**:
| UF | Seção | Volume | Erros | Z-Score |
|---|---|---|---|---|
| AC | 0001 | 450 | 12 | 3.2 |
| ... | ... | ... | ... | ... |

**Recomendação**: Auditoria Complementar (Art. 103 do Código Eleitoral)

Ferramentas e Bibliotecas

Python Libraries

# Instalação
pip install reportlab python-docx jinja2 weasyprint

# Imports
from reportlab.lib.pagesizes import A4
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, Table
from docx import Document
from jinja2 import Template

Estrutura de Arquivos

src/
  reports/
    __init__.py
    generator.py          # Classe principal ReportGenerator
    templates/
      nacional.html       # Template HTML para PDF
      uf.html            # Template por estado
      parecer.html       # Template de parecer jurídico
    assets/
      logo_tse.png       # Logo oficial (se autorizado)
      styles.css         # Estilos para PDF

Implementação: ReportGenerator

Classe Principal

class ReportGenerator:
    def __init__(self, db_engine, tse_justice_agent):
        self.engine = db_engine
        self.justice = tse_justice_agent
        
    def generate_national_report(self, output_path='relatorio_nacional.pdf'):
        """Gera relatório consolidado nacional"""
        data = self._collect_national_data()
        parecer = self.justice.gerar_parecer(data['anomalias'])
        
        context = {
            'data': data,
            'parecer': parecer,
            'timestamp': datetime.now()
        }
        
        return self._render_pdf('nacional.html', context, output_path)
    
    def generate_uf_report(self, uf, output_path=None):
        """Gera relatório específico de UF"""
        if output_path is None:
            output_path = f'relatorio_{uf}.pdf'
            
        data = self._collect_uf_data(uf)
        parecer = self.justice.gerar_parecer_uf(uf, data['anomalias'])
        
        context = {
            'uf': uf,
            'data': data,
            'parecer': parecer,
            'comparacao_nacional': self._compare_to_national(uf, data)
        }
        
        return self._render_pdf('uf.html', context, output_path)

Casos de Uso

Uso 1: Relatório Rápido (CLI)

# Gerar relatório nacional
python -m src.reports.generator --tipo nacional --output relatorio.pdf

# Gerar relatório por UF
python -m src.reports.generator --tipo uf --uf AC --output relatorio_ac.pdf

Uso 2: Integração com Dashboard

# No Streamlit
if st.button("📄 Gerar Relatório Nacional"):
    generator = ReportGenerator(engine, tse_justice)
    pdf_path = generator.generate_national_report()
    
    with open(pdf_path, 'rb') as f:
        st.download_button(
            label="⬇️ Download PDF",
            data=f,
            file_name="relatorio_nacional.pdf",
            mime="application/pdf"
        )

Checklist de Qualidade

Antes de Gerar Relatório

• Ingestão de dados completa (5 estados)
• analysis_results.csv atualizado
• TSE Justice Agent configurado
• Templates HTML validados

Validação do Relatório

• Todas as seções preenchidas
• Gráficos renderizados corretamente
• Fundamentação jurídica presente
• Assinatura digital (se aplicável)
• Metadados (autor, data, versão)

Segurança e Compliance

Dados Sensíveis

• ❌ Não incluir dados de eleitores individuais
• ❌ Não incluir correlação voto-eleitor
• ✅ Apenas dados agregados por seção

Disclaimer Legal

Todo relatório deve incluir:

AVISO LEGAL: Este relatório é gerado por sistema automatizado de análise estatística 
e não substitui perícia oficial da Justiça Eleitoral. Os pareceres jurídicos são 
fundamentados em legislação vigente e jurisprudência, mas não constituem decisão 
judicial. Uso restrito para fins de auditoria interna e transparência.

Próximos Passos (Fase 9)

1. Implementar src/reports/generator.py
2. Criar templates HTML (nacional + UF)
3. Integrar com TSE Justice Agent
4. Adicionar botão no Dashboard
5. Testar geração com dados reais

---

Skill Owner: Backend Specialist + TSE Justice Dependencies: reportlab, python-docx, jinja2 Status: Ready for Implementation