feat: Sistema CBCFacil completo con cola secuencial
- Implementa ProcessingMonitor singleton para procesamiento secuencial de archivos - Agrega AI summary service con soporte para MiniMax API - Agrega PDF generator para resúmenes - Agrega watchers para monitoreo de carpeta remota - Mejora sistema de notificaciones Telegram - Implementa gestión de VRAM para GPU - Configuración mediante variables de entorno (sin hardcoded secrets) - .env y transcriptions/ agregados a .gitignore Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
renato97
436
codex.md
Normal file
436
codex.md
Normal file
@@ -0,0 +1,436 @@
|
||||
# CODEX.md
|
||||
|
||||
Guia maestra para producir resúmenes académicos de alta calidad en HTML/PDF con coherencia conceptual, densidad útil y gráficos claros.
|
||||
|
||||
Esta guía está diseñada para cualquier materia:
|
||||
- economía
|
||||
- física
|
||||
- historia
|
||||
- biología
|
||||
- derecho
|
||||
- ingeniería
|
||||
- filosofía
|
||||
- otras
|
||||
|
||||
Objetivo: que cualquier IA pueda replicar un estándar profesional de resumen de estudio, no solo “texto lindo”.
|
||||
|
||||
## 1) Principios de diseño (no negociables)
|
||||
|
||||
1. Claridad causal
|
||||
- Cada afirmación importante debe responder: qué cambia, por qué cambia y qué consecuencia produce.
|
||||
- Evitar listas de definiciones sin mecanismo.
|
||||
|
||||
2. Legibilidad real para estudiar
|
||||
- El documento debe poder leerse en bloques de 15-25 minutos.
|
||||
- Los títulos deben guiar la estrategia de estudio, no solo “decorar”.
|
||||
|
||||
3. Densidad informativa sana
|
||||
- Evitar páginas vacías o con 2 líneas.
|
||||
- Evitar “paredes de texto” sin respiración visual.
|
||||
|
||||
4. Coherencia visual
|
||||
- Mismo sistema de colores, etiquetas y jerarquía tipográfica en todo el documento.
|
||||
- En gráficos, usar siempre convenciones constantes (ejes, colores, flechas, leyendas).
|
||||
|
||||
5. Verificación pre y post PDF
|
||||
- Revisar HTML antes de exportar.
|
||||
- Revisar PDF final (paginado, cortes, legibilidad, textos residuales tipo `file://`).
|
||||
|
||||
## 2) Flujo de trabajo general (end-to-end)
|
||||
|
||||
1. Ingesta de fuentes
|
||||
- Reunir transcripción (`.txt`), material bibliográfico (`.pdf`) y guía de cátedra si existe.
|
||||
- Detectar ruido de transcripción: muletillas, repetición, errores de OCR.
|
||||
|
||||
2. Extracción semántica
|
||||
- Separar: conceptos núcleo, definiciones, procedimientos, ejemplos de clase, errores típicos de examen.
|
||||
- Marcar explícitamente qué partes son “base” y cuáles son “expansión didáctica”.
|
||||
|
||||
3. Diseño de estructura
|
||||
- Construir índice con progresión lógica (de fundamentos a aplicación).
|
||||
- Incluir sí o sí: casos resueltos, checklist, autoevaluación.
|
||||
|
||||
4. Redacción por capas
|
||||
- Capa 1: idea central de sección en 1-2 párrafos.
|
||||
- Capa 2: tabla o esquema operativo.
|
||||
- Capa 3: caja de “importante” o “error frecuente”.
|
||||
- Capa 4: caso aplicado.
|
||||
|
||||
5. Maquetación HTML
|
||||
- Usar componentes consistentes: portada, secciones, tablas, cajas, gráficos SVG, banco de casos.
|
||||
- Preparar para impresión A4 desde el inicio.
|
||||
|
||||
6. Exportación PDF
|
||||
- Exportar con motor headless estable (Chromium recomendado).
|
||||
- Desactivar headers/footers automáticos del navegador.
|
||||
|
||||
7. QA final
|
||||
- Verificar páginas “casi vacías”.
|
||||
- Verificar cortes feos (tabla partida, título huérfano, caja cortada).
|
||||
- Verificar coherencia de gráficos y legibilidad de flechas/etiquetas.
|
||||
|
||||
## 3) Estructura recomendada del resumen (plantilla universal)
|
||||
|
||||
1. Portada
|
||||
- Materia + clase + tema central.
|
||||
- Objetivo de estudio de esa clase.
|
||||
- Mapa rápido (ruta de lectura en una línea).
|
||||
|
||||
2. Índice
|
||||
- 6 a 12 bloques como máximo por clase regular.
|
||||
- Nombres de sección orientados a acción.
|
||||
|
||||
3. Desarrollo conceptual
|
||||
- Definiciones esenciales.
|
||||
- Mecanismos principales.
|
||||
- Tabla de términos operativos.
|
||||
|
||||
4. Aplicación
|
||||
- Casos simples.
|
||||
- Casos combinados o ambiguos.
|
||||
- Errores frecuentes.
|
||||
|
||||
5. Entrenamiento examen
|
||||
- Simulación de parcial (preguntas).
|
||||
- Respuestas modelo cortas.
|
||||
- Preguntas de desarrollo.
|
||||
|
||||
6. Cierre
|
||||
- Checklist final.
|
||||
- Tarjetas de repaso.
|
||||
- Mini glosario.
|
||||
|
||||
## 4) Reglas de redacción (para cualquier disciplina)
|
||||
|
||||
1. Escribir en modo operativo
|
||||
- En vez de “la elasticidad es importante”, escribir: “si |E| > 1, un aumento de precio reduce recaudación”.
|
||||
|
||||
2. Separar descripción de inferencia
|
||||
- `Descripción`: qué se observa.
|
||||
- `Inferencia`: qué significa y bajo qué condiciones.
|
||||
|
||||
3. Evitar ambigüedad de sujeto
|
||||
- No usar “esto cambia aquello” sin especificar variable.
|
||||
|
||||
4. Definir límites
|
||||
- Toda regla importante debe incluir cuándo no aplica.
|
||||
|
||||
5. Frases de cierre por sección
|
||||
- Cerrar sección con una frase “si te preguntan X, responde Y con Z mecanismo”.
|
||||
|
||||
## 5) Componentes visuales y semánticos
|
||||
|
||||
### 5.1 Cajas semánticas
|
||||
|
||||
- `.definicion`
|
||||
- Uso: concepto técnico o regla formal.
|
||||
- Debe responder “qué es”.
|
||||
|
||||
- `.importante`
|
||||
- Uso: advertencia, límite, error típico.
|
||||
- Debe responder “qué no confundir”.
|
||||
|
||||
- `.ejemplo`
|
||||
- Uso: traducción a caso concreto.
|
||||
- Debe responder “cómo se aplica”.
|
||||
|
||||
### 5.2 Tablas
|
||||
|
||||
Usar tablas para:
|
||||
- comparaciones (A vs B)
|
||||
- pasos de procedimiento
|
||||
- matriz de cambios
|
||||
|
||||
Reglas:
|
||||
- encabezado corto y explícito
|
||||
- 3-5 columnas máximo
|
||||
- celdas con frases breves, no párrafos largos
|
||||
|
||||
### 5.3 Gráficos (estándar universal)
|
||||
|
||||
Principio: todo gráfico debe poder leerse en 10 segundos.
|
||||
|
||||
Checklist mínimo por gráfico:
|
||||
- ejes rotulados
|
||||
- elementos con nombres visibles
|
||||
- leyenda de colores
|
||||
- flecha/sentido de cambio claro
|
||||
- caption con interpretación
|
||||
- bloque “Lectura del gráfico” con mecanismo en texto
|
||||
|
||||
## 6) Guía técnica de gráficos por tipo de materia
|
||||
|
||||
### 6.1 Economía
|
||||
|
||||
Formato base:
|
||||
- Eje vertical: precio/salario/tasa
|
||||
- Eje horizontal: cantidad/trabajo/fondos
|
||||
- Curva inicial: gris
|
||||
- Curva nueva: color principal (rojo demanda, verde oferta)
|
||||
- Flecha: azul oscuro gruesa
|
||||
- Resultado: texto final con dirección de equilibrio
|
||||
|
||||
Lectura mínima obligatoria:
|
||||
- `Curva implicada`
|
||||
- `Mecanismo`
|
||||
- `Resultado`
|
||||
|
||||
### 6.2 Física
|
||||
|
||||
Gráficos típicos:
|
||||
- posición-tiempo, velocidad-tiempo, aceleración-tiempo
|
||||
- energía potencial vs coordenada
|
||||
- circuitos (I-V)
|
||||
|
||||
Reglas:
|
||||
- incluir unidades SI en ejes
|
||||
- marcar pendiente/área cuando tenga significado físico
|
||||
- incluir condición inicial/final
|
||||
- indicar régimen (lineal/no lineal)
|
||||
|
||||
### 6.3 Historia
|
||||
|
||||
Gráficos útiles:
|
||||
- línea de tiempo con hitos
|
||||
- mapa de actores (Estado, grupos, alianzas)
|
||||
- matriz causa-evento-consecuencia
|
||||
|
||||
Reglas:
|
||||
- separar causas estructurales de detonantes
|
||||
- distinguir corto vs largo plazo
|
||||
- marcar continuidad vs ruptura
|
||||
|
||||
### 6.4 Biología
|
||||
|
||||
Gráficos útiles:
|
||||
- rutas (metabólicas, señalización)
|
||||
- taxonomías jerárquicas
|
||||
- tablas comparativas de procesos
|
||||
|
||||
Reglas:
|
||||
- nombrar niveles de organización
|
||||
- explicitar entrada/salida de cada proceso
|
||||
- marcar regulación positiva/negativa
|
||||
|
||||
### 6.5 Derecho
|
||||
|
||||
Diagramas útiles:
|
||||
- flujo procedimental
|
||||
- jerarquía normativa
|
||||
- mapa de requisitos y excepciones
|
||||
|
||||
Reglas:
|
||||
- identificar fuente normativa
|
||||
- separar regla general y excepción
|
||||
- incluir condición de aplicación
|
||||
|
||||
## 7) Estándar CSS recomendado (impresión A4)
|
||||
|
||||
Reglas de impresión:
|
||||
- `@page size: A4`
|
||||
- márgenes 1.5 a 2.0 cm
|
||||
- tipografía serif para cuerpo (Georgia/Times)
|
||||
- tamaño base 10.8-11.2 pt
|
||||
|
||||
Control de cortes:
|
||||
- evitar `break-inside: avoid` global indiscriminado
|
||||
- aplicar `break-inside: avoid` solo en:
|
||||
- tablas
|
||||
- cajas críticas
|
||||
- tarjetas de casos
|
||||
|
||||
Evitar páginas en blanco:
|
||||
- no forzar `page-break-before` salvo secciones pesadas (ej: banco de casos)
|
||||
- si un título queda solo al final de página, ajustar bloques previos o mover sección completa
|
||||
|
||||
## 8) Exportación PDF robusta
|
||||
|
||||
Comando recomendado:
|
||||
|
||||
```bash
|
||||
chromium \
|
||||
--headless \
|
||||
--disable-gpu \
|
||||
--no-sandbox \
|
||||
--no-pdf-header-footer \
|
||||
--print-to-pdf="salida.pdf" \
|
||||
"file:///ruta/entrada.html"
|
||||
```
|
||||
|
||||
Notas:
|
||||
- `--no-pdf-header-footer` evita contaminación con `file://` en pie.
|
||||
- Si aparecen rutas en PDF, revisar opciones de impresión primero.
|
||||
|
||||
## 9) QA automático mínimo
|
||||
|
||||
Herramientas:
|
||||
- `pdfinfo`: cantidad de páginas
|
||||
- `pdftotext`: extracción y búsqueda de basura textual
|
||||
- `rg`: detección rápida de patrones no deseados
|
||||
|
||||
Controles:
|
||||
1. Páginas casi vacías
|
||||
- detectar páginas con bajo conteo de caracteres
|
||||
|
||||
2. Referencias no deseadas
|
||||
- buscar `file://`, `.txt`, `.pdf` si el usuario pidió ocultarlas
|
||||
|
||||
3. Coherencia semántica
|
||||
- cada gráfico debe tener caption y lectura textual
|
||||
|
||||
4. Integridad visual
|
||||
- no cortar tablas ni cajas
|
||||
- no superponer flechas con etiquetas principales
|
||||
|
||||
## 10) Criterios de calidad (rúbrica 0-5)
|
||||
|
||||
1. Precisión conceptual
|
||||
- 0: errores de concepto graves
|
||||
- 5: conceptos correctos y bien delimitados
|
||||
|
||||
2. Coherencia causal
|
||||
- 0: listado sin lógica
|
||||
- 5: mecanismo explícito en cada bloque
|
||||
|
||||
3. Utilidad para examen
|
||||
- 0: no entrenable
|
||||
- 5: casos + respuestas + checklist
|
||||
|
||||
4. Calidad visual
|
||||
- 0: ilegible o inconsistente
|
||||
- 5: limpio, consistente, imprimible
|
||||
|
||||
5. Control técnico
|
||||
- 0: PDF defectuoso
|
||||
- 5: sin residuos, sin páginas vacías, sin cortes feos
|
||||
|
||||
## 11) Reglas para banco de casos
|
||||
|
||||
Cada tarjeta de caso debe contener:
|
||||
- título del caso
|
||||
- por qué cambia
|
||||
- curva/variable implicada
|
||||
- mecanismo causal
|
||||
- gráfico coherente
|
||||
- resultado final
|
||||
|
||||
No aceptar tarjetas con:
|
||||
- solo flechas
|
||||
- gráfico sin explicación
|
||||
- explicación sin variable concreta
|
||||
|
||||
## 12) Reglas para materias cuantitativas
|
||||
|
||||
Agregar siempre:
|
||||
- fórmula núcleo
|
||||
- interpretación económica/física/estadística de cada término
|
||||
- ejemplo numérico mínimo
|
||||
- error típico de cálculo
|
||||
|
||||
Cuando haya derivaciones:
|
||||
- no mostrar álgebra larga si no agrega aprendizaje
|
||||
- priorizar: qué representa, cuándo usarla, cómo interpretar signo/magnitud
|
||||
|
||||
## 13) Reglas para materias cualitativas
|
||||
|
||||
Agregar siempre:
|
||||
- periodización o estructura argumental
|
||||
- actores, intereses, instituciones
|
||||
- relación causa-contexto-consecuencia
|
||||
- contraste entre 2 interpretaciones
|
||||
|
||||
Evitar:
|
||||
- relato cronológico sin tesis
|
||||
- opiniones sin anclaje conceptual
|
||||
|
||||
## 14) Estrategia anti-ruido de transcripción
|
||||
|
||||
Cuando la fuente es clase oral transcripta:
|
||||
- limpiar muletillas y repeticiones
|
||||
- preservar ejemplos de cátedra que aclaren examen
|
||||
- reconstruir frases incompletas manteniendo sentido
|
||||
- marcar inferencias cuando la transcripción es ambigua
|
||||
|
||||
## 15) Política de trazabilidad (sin contaminar el PDF)
|
||||
|
||||
Internamente:
|
||||
- guardar scripts de generación y QA
|
||||
- versionar cambios de estructura y estilo
|
||||
|
||||
En PDF final:
|
||||
- no imprimir rutas locales
|
||||
- no imprimir referencias de archivos si el usuario lo pidió
|
||||
- no insertar notas técnicas irrelevantes para estudio
|
||||
|
||||
## 16) Plantilla de prompts para IA (genérica)
|
||||
|
||||
Prompt base:
|
||||
- “Construye un resumen extendido de [materia/tema], orientado a examen, en formato HTML imprimible A4, con:
|
||||
- índice
|
||||
- desarrollo conceptual
|
||||
- tablas operativas
|
||||
- banco de casos con gráficos SVG claros
|
||||
- simulación de examen
|
||||
- checklist final
|
||||
- sin referencias a rutas de archivos en el PDF.”
|
||||
|
||||
Prompt de QA:
|
||||
- “Audita este HTML/PDF buscando:
|
||||
- páginas con bajo contenido
|
||||
- títulos huérfanos
|
||||
- gráficos sin contexto
|
||||
- etiquetas ilegibles
|
||||
- texto basura (file://, rutas)
|
||||
y propone correcciones puntuales.”
|
||||
|
||||
## 17) Errores frecuentes de IA y correcciones
|
||||
|
||||
1. Error: demasiado resumen, poca utilidad
|
||||
- Corrección: añadir banco de casos y respuestas modelo.
|
||||
|
||||
2. Error: gráficos bonitos pero ambiguos
|
||||
- Corrección: incluir leyenda, curva implicada y mecanismo textual.
|
||||
|
||||
3. Error: demasiados saltos de página
|
||||
- Corrección: reducir `page-break` forzado y reequilibrar bloques.
|
||||
|
||||
4. Error: repite teoría del libro sin foco de examen
|
||||
- Corrección: priorizar preguntas-tipo y decisiones de resolución.
|
||||
|
||||
5. Error: no distingue hechos de inferencias
|
||||
- Corrección: separar “dato/definición” de “interpretación/aplicación”.
|
||||
|
||||
## 18) Checklist final antes de entregar
|
||||
|
||||
Checklist editorial:
|
||||
- índice consistente con secciones
|
||||
- numeración correcta
|
||||
- no hay contradicciones internas
|
||||
|
||||
Checklist visual:
|
||||
- gráficos legibles al 100%
|
||||
- flechas claras
|
||||
- etiquetas no montadas
|
||||
|
||||
Checklist técnico:
|
||||
- PDF abre y pagina bien
|
||||
- no hay `file://`
|
||||
- no hay páginas casi vacías
|
||||
|
||||
Checklist pedagógico:
|
||||
- hay práctica de examen
|
||||
- hay respuestas modelo
|
||||
- hay errores frecuentes
|
||||
- hay cierre operativo
|
||||
|
||||
## 19) Meta-estándar esperado
|
||||
|
||||
Un resumen de “nivel alto” no es el más largo.
|
||||
Es el que logra simultáneamente:
|
||||
- comprensión conceptual
|
||||
- capacidad de resolver ejercicios
|
||||
- lectura rápida y confiable antes del examen
|
||||
- salida PDF limpia y estable
|
||||
|
||||
Si falta uno de esos cuatro, el resumen está incompleto.
|
||||
|
||||
Reference in New Issue
Block a user