grahama1970/batch-report

Batch Report Skill

Genera informes de análisis completos para trabajos de procesamiento por lotes finalizados.

Características

• Análisis de manifiestos - Cuenta éxitos, fallos y completaciones parciales
• Desglose de tiempos - Análisis de latencia por paso, identificación de cuellos de botella
• Patrones de fallo - Categoriza y resume modos de fallo
• Métricas de calidad - Muestras de salida para evaluación de calidad
• Informe Markdown - Resumen legible para humanos
• Integración con agent-inbox - Envío automático al inbox del proyecto

Inicio Rápido

cd .pi/skills/batch-report

# Generar informe para un lote de extractor (detección automática de formato)
uv run python report.py analyze /ruta/a/salida/lote

# Generar y enviar al agent-inbox
uv run python report.py analyze /ruta/a/salida/lote --send-to extractor

# Solo mostrar estadísticas resumidas
uv run python report.py summary /ruta/a/salida/lote

# Analizar un archivo de estado independiente
uv run python report.py state /ruta/a/.batch_state.json

# Salida JSON para tuberías
uv run python report.py summary /ruta/a/salida --json | jq .success_rate

Comandos

analyze - Informe de análisis completo

uv run python report.py analyze /ruta/a/salida \
    --output report.md \
    --send-to extractor \
    --priority high

Opciones:

Opción	Corta	Descripción
--output	-o	Ruta del archivo de salida (por defecto: stdout)
--send-to	-s	Enviar informe al proyecto agent-inbox
--priority	-p	Prioridad para agent-inbox (low/normal/high/critical)
--sample	-n	Número de muestras a incluir (por defecto: 5)
--format	-f	Formato del lote: extractor, youtube, generic, auto (por defecto: auto)
--json	-j	Salida en JSON para tuberías a otras herramientas

summary - Solo estadísticas rápidas

uv run python report.py summary /ruta/a/salida
uv run python report.py summary /ruta/a/salida --json

Salida:

Lote: run-2025-12-18_144426-2eb428c
Total: 230 | Éxito: 180 | Fallo: 35 | Parcial: 15
Tasa de éxito: 78.3%
Tiempo medio: 4.2 min | Más lento: 09_section_summarizer (45%)

Salida JSON:

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

state - Analizar archivos de estado independientes

uv run python report.py state /ruta/a/.batch_state.json
uv run python report.py state /ruta/a/.batch_state.json --json

Funciona con cualquier archivo .batch_state.json de cualquier trabajo por lotes.

failures - Listar fallos con razones

uv run python report.py failures /ruta/a/salida
uv run python report.py failures /ruta/a/salida --json

Formato del Informe

# Informe de Lote: run-2025-12-18_144426-2eb428c

## Resumen
- **Total de elementos:** 230
- **Exitosos:** 180 (78.3%)
- **Fallidos:** 35 (15.2%)
- **Parciales:** 15 (6.5%)

## Análisis de Tiempos
| Paso | Media (s) | Máx (s) | % del Total |
|------|-----------|---------|-------------|
| 09_section_summarizer | 120.5 | 341.0 | 45.2% |
| 05_table_extractor | 65.3 | 105.0 | 24.5% |
...

## Patrones de Fallo
| Patrón | Conteo | Ejemplo |
|--------|--------|---------|
| text_content vacío | 12 | 047ca6ef... |
| CUDA OOM | 5 | 9497a4e5... |
...

## Recomendaciones
1. Considerar modo --text-only para extracción de conocimiento
2. Agregar umbral de confianza de tabla antes de VLM
...

Visualización

Después de generar informes (especialmente con --json), ofrecer visualizar mediante /create-figure:

# Cascada de tiempos por paso del pipeline
create-figure metrics --input batch.json --output timing.png --type hbar --title "Tiempos por Paso"

# Distribución de éxito/fallo
create-figure metrics --input batch.json --output results.png --type pie --title "Resultados del Lote"

# Desglose de patrones de fallo
create-figure metrics --input batch.json --output failures.png --type bar --title "Patrones de Fallo"

Cuándo ofrecer: Después de presentar el análisis del lote, preguntar: "¿Quieres que visualice el desglose de tiempos?"

Formatos de Lote Soportados

La bandera --format acepta: extractor, youtube, generic o auto (por defecto).

Lógica de detección automática:

1. Si existen */manifest.json y */timings_summary.json → extractor
2. Si .batch_state.json tiene "transcript" en la descripción → youtube
3. Si existe .batch_state.json → generic

Lotes de extractor

Espera:

• */manifest.json - Manifiestos por elemento
• */timings_summary.json - Datos de tiempos
• */14_report_generator/json_output/final_report.json - Métricas de calidad
• failed_urls.txt - Lista de elementos fallidos

Lotes de transcripción de YouTube

Espera:

• .batch_state.json - Archivo de estado con descripción relacionada con transcripción

Lotes genéricos

Espera:

• .batch_state.json - Archivo de estado con conteos de completados/fallidos
• Archivos *.log para análisis de fallos (opcional)

Integración con agent-inbox

# Enviar informe como error
uv run python report.py analyze /ruta/a/salida \
    --send-to extractor \
    --priority high

# Mensaje enviado: extractor_abc123

Dependencias

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