relatório-de-lote/grahama1970/batch-report

Habilidade de Relatório de Lote

Gere relatórios de análise abrangentes para trabalhos de processamento em lote concluídos.

Funcionalidades

• Análise de manifesto - Conte sucessos, falhas, conclusões parciais
• Detalhamento de tempo - Análise de latência por etapa, identifique gargalos
• Padrões de falha - Categorize e resuma modos de falha
• Métricas de qualidade - Amostras de saída para avaliação de qualidade
• Relatório Markdown - Resumo legível por humanos
• Integração com agent-inbox - Envio automático para a caixa de entrada do projeto

Início Rápido

cd .pi/skills/batch-report

# Gera relatório para lote do extrator (detecta formato automaticamente)
uv run python report.py analyze /caminho/para/saida/do/lote

# Gera e envia para agent-inbox
uv run python report.py analyze /caminho/para/saida/do/lote --send-to extrator

# Apenas mostra estatísticas resumidas
uv run python report.py summary /caminho/para/saida/do/lote

# Analisa um arquivo de estado independente
uv run python report.py state /caminho/para/.batch_state.json

# Saída JSON para pipe
uv run python report.py summary /caminho/para/saida --json | jq .success_rate

Comandos

analyze - Relatório de análise completo

uv run python report.py analyze /caminho/para/saida \
    --output relatorio.md \
    --send-to extrator \
    --priority alta

Opções:

Opção	Abreviada	Descrição
--output	-o	Caminho do arquivo de saída (padrão: stdout)
--send-to	-s	Envia relatório para o projeto agent-inbox
--priority	-p	Prioridade para agent-inbox (baixa/normal/alta/crítica)
--sample	-n	Número de amostras a incluir (padrão: 5)
--format	-f	Formato do lote: extrator, youtube, generico, auto (padrão: auto)
--json	-j	Saída como JSON para pipe para outras ferramentas

summary - Apenas estatísticas rápidas

uv run python report.py summary /caminho/para/saida
uv run python report.py summary /caminho/para/saida --json

Saída:

Lote: run-2025-12-18_144426-2eb428c
Total: 230 | Sucesso: 180 | Falha: 35 | Parcial: 15
Taxa de sucesso: 78,3%
Tempo médio: 4,2 min | Mais lento: 09_section_summarizer (45%)

Saída JSON:

{
  "batch": "run-2025-12-18_144426-2eb428c",
  "format": "extrator",
  "total": 230,
  "successful": 180,
  "partial": 15,
  "failed": 35,
  "success_rate": 78.3,
  "avg_time_min": 4.2
}

state - Analisar arquivos de estado independentes

uv run python report.py state /caminho/para/.batch_state.json
uv run python report.py state /caminho/para/.batch_state.json --json

Funciona com qualquer arquivo .batch_state.json de qualquer trabalho em lote.

failures - Listar falhas com motivos

uv run python report.py failures /caminho/para/saida
uv run python report.py failures /caminho/para/saida --json

Formato do Relatório

# Relatório de Lote: run-2025-12-18_144426-2eb428c

## Resumo
- **Total de itens:** 230
- **Bem-sucedidos:** 180 (78,3%)
- **Falhos:** 35 (15,2%)
- **Parciais:** 15 (6,5%)

## Análise de Tempo
| Etapa | Média (s) | Máx (s) | % do Total |
|------|---------|---------|------------|
| 09_section_summarizer | 120,5 | 341,0 | 45,2% |
| 05_table_extractor | 65,3 | 105,0 | 24,5% |
...

## Padrões de Falha
| Padrão | Contagem | Exemplo |
|---------|-------|---------|
| text_content vazio | 12 | 047ca6ef... |
| CUDA OOM | 5 | 9497a4e5... |
...

## Recomendações
1. Considere o modo --text-only para extração de conhecimento
2. Adicione limite de confiança da tabela antes do VLM
...

Visualização

Após gerar relatórios (especialmente com --json), ofereça visualizar via /create-figure:

# Cascata de tempo por etapa do pipeline
create-figure metrics --input batch.json --output timing.png --type hbar --title "Tempo por Etapa"

# Distribuição de sucesso/falha
create-figure metrics --input batch.json --output results.png --type pie --title "Resultados do Lote"

# Detalhamento de padrões de falha
create-figure metrics --input batch.json --output failures.png --type bar --title "Padrões de Falha"

Quando oferecer: Após apresentar a análise do lote, pergunte: "Quer que eu visualize o detalhamento de tempo?"

Formatos de Lote Suportados

A flag --format aceita: extrator, youtube, generico, ou auto (padrão).

Lógica de detecção automática:

1. Se */manifest.json e */timings_summary.json existirem → extrator
2. Se .batch_state.json tiver "transcript" na descrição → youtube
3. Se .batch_state.json existir → generico

Lotes do Extrator

Espera:

• */manifest.json - Manifestos por item
• */timings_summary.json - Dados de tempo
• */14_report_generator/json_output/final_report.json - Métricas de qualidade
• failed_urls.txt - Lista de itens falhos

Lotes de Transcrição do YouTube

Espera:

• .batch_state.json - Arquivo de estado com descrição relacionada à transcrição

Lotes Genéricos

Espera:

• .batch_state.json - Arquivo de estado com contagens de concluídos/falhos
• Arquivos *.log para análise de falhas (opcional)

Integração com agent-inbox

# Envia relatório como bug
uv run python report.py analyze /caminho/para/saida \
    --send-to extrator \
    --priority alta

# Mensagem enviada: extrator_abc123

Dependências

dependencies = [
    "typer",
    "rich",
]