De artículo a cuaderno
Guía a un agente para convertir un artículo en un cuaderno marimo ejecutable que ayude al lector a comprender dicho artículo. El cuaderno es una lección, no una página de resumen: explicaciones en lenguaje sencillo, widgets interactivos cuando sean útiles y verificaciones informales a lo largo del camino. La redacción debe ser inteligible y representativa del artículo, no una prosa genérica de IA.
Este archivo es un esqueleto. Muchos detalles se completarán más adelante. Los elementos marcados como PENDIENTE aún no están decididos o solo están esbozados.
Contrato
| Entrada | Un artículo en PDF, HTML o texto plano (LaTeX, Markdown, etc.). La ruta, URL o identificador es válido siempre que se pueda obtener el texto completo. |
| Salida | Un cuaderno marimo ejecutable (*.py) que el lector pueda abrir con uvx marimo edit --sandbox …. |
Entradas opcionales para solicitar si faltan (no bloquees si el usuario solo proporciona el artículo):
- Audiencia inicial o "adapta sobre la marcha". Suposición predeterminada: estudiante de licenciatura a posgrado, más profesionales en activo que se inicien en este artículo o campo, con conocimientos científicos generales. PENDIENTE: ajustar la suposición predeterminada.
- Contexto adicional: información complementaria, artículos citados u otras fuentes que el usuario quiera considerar como base (no solo conocimiento general).
- Profundidad: recorrido completo vs. métodos, resultados o una figura.
- Ruta de salida y restricciones de ejecución.
No trates esta habilidad como una herramienta para revisar una literatura extensa. Eso es otro trabajo.
Flujo de trabajo
1. Ingestar el artículo (PDF / HTML / texto plano)
2. Extraer estructura, términos, ecuaciones, figuras y lagunas
3. Planificar la ruta de aprendizaje
4. Generar el cuaderno marimo
5. Validar que se ejecute con `uv run`, y luego entregar
1. Ingestar el artículo
Obtén el texto completo, no solo un resumen. Ramifica según el tipo de entrada; coloca las notas específicas del formato en resources/ y cualquier ayuda en scripts/ (siempre con uv run, nunca con un pip install global).
- PDF: PENDIENTE: cómo obtener y analizar (texto, matemáticas, figuras, orden de lectura). Señala fallos en lugar de adivinar.
- HTML: PENDIENTE: cómo obtener y analizar (texto principal vs. navegación/barra, MathJax/MathML, figuras).
- Texto plano (LaTeX, Markdown, etc.): PENDIENTE: cómo seguir inclusiones, bibliografía y archivos de figuras; cómo mantener las etiquetas de ecuaciones y figuras.
Registra el título del artículo, autores, año y un enlace o identificador estable cuando esté disponible.
2. Extraer estructura, ecuaciones y figuras
Construye una imagen intermedia del artículo antes de escribir cualquier cuaderno. PENDIENTE: definir las formas de datos para este paso (ver también la idea de que las estructuras intermedias sólidas facilitan el resto).
Extrae al menos:
- Problema y contribución, en tus propias palabras.
- Perfil de prerrequisitos: qué sabe, qué no sabe y qué se le debe enseñar a un lector en cada nivel (consulta Explicar en múltiples niveles).
- Conceptos clave y términos que el artículo usa pero no define (metadatos centrales o términos del campo). Ejemplo planteado en la discusión de diseño: un artículo sobre ataques al corazón que nunca explica "infarto de miocardio".
- Ecuaciones clave, numeradas como en el artículo, con variables.
- Figuras clave: qué codifica cada una, cómo está etiquetada y si los datos subyacentes parecen estar disponibles.
- Puntos de riesgo para la generación: LaTeX pesado o matemáticas, etiquetas de figuras con letras griegas, otro texto no ASCII.
- Lagunas evidentes en métodos o informes. No inventes resultados experimentales faltantes.
Clasifica la madurez del campo (establecido, emergente, interdisciplinario o mixto) usando la rúbrica y la muestra ligera de literatura en resources/field-maturity.md. Registra la clase, la evidencia y qué componentes de incorporación de vocabulario del cuaderno son necesarios (glosario, desambiguación, terminología en evolución).
PENDIENTE: si clasificar el artículo como similar a un algoritmo (ejercicios de codificación, reconstrucción inversa del método) vs. similar a un concepto (widgets explicativos escritos por el agente). Ejemplos de química usados en la discusión: balance de masa, cinética de reacción, un nuevo modelo cinético.
3. Planificar la ruta de aprendizaje
Diseña una ruta que un humano pueda seguir en una sola sesión. PENDIENTE: duración objetivo.
No bloquees todo el cuaderno a un solo nivel de lectura. Planifica una explicación adaptativa: el lector debe poder obtener una versión más simple o más avanzada de un pasaje difícil. PENDIENTE: dirección predeterminada: empezar simple y añadir complejidad, o empezar avanzado y bajar de nivel cuando el lector esté confundido. Ambas se propusieron; ninguna se eligió. Los conceptos centrales reciben una escalera completa (consulta Explicar en múltiples niveles).
Estructura sugerida (ajusta según el artículo):
- Por qué este artículo es importante.
- Intuición o ejemplo sencillo antes de la notación pesada.
- Configuración: notación, suposiciones, términos e incorporación de vocabulario del campo (glosario; desambiguación o terminología en evolución cuando sea necesario; consulta
resources/field-maturity.md). - Idea central, vinculada a una ecuación o figura.
- Paso a paso alineado con el artículo.
- Verificaciones informales después de los segmentos, ajustadas al nivel de explicación: explicar, predecir, aplicar o criticar (no evaluación formal; la evaluación formal está fuera del alcance).
- Para lectores de posgrado y superiores: puntos de crítica: ¿el diseño experimental aborda la pregunta planteada? ¿El marco estadístico es una elección adecuada? ¿Qué falta? ¿Qué suposiciones está haciendo el lector?
- Resumen: limitaciones, qué leer a continuación, cita.
- Prueba final: cinco preguntas de opción múltiple sobre el artículo, siempre como última sección (consulta Prueba final).
PENDIENTE: hasta dónde llegan la crítica, el análisis de la sección de resultados y las indicaciones de interpretación de figuras en la primera versión, frente a un recorrido guiado simple.
Si el usuario proporcionó fuentes adicionales, planifica dónde se citarán en el cuaderno y cómo se distinguirá la evidencia con fuente del conocimiento general. PENDIENTE: el mecanismo para esa distinción, y si un mapa conceptual pequeño o una "wiki de conocimiento" pertenece aquí más adelante.
4. Generar el cuaderno marimo
Comienza desde una plantilla en assets/ cuando exista (PENDIENTE: añadir assets/notebook_template.py). Escribe un cuaderno marimo que se pueda abrir con uvx marimo edit --sandbox.
Sigue las habilidades de marimo instaladas en .agents/skills/ (una celda import marimo as mo; nombres únicos de nivel superior; widgets que impulsan la exploración, no la decoración):
marimo-notebook-patterns: leer antes de escribir o editar cualquier celda del cuaderno (reglas de importación y parámetros de celda, variables únicas, firmas de API de widgets, errores comunes).marimo: referencia más amplia de autoría, incluido el emparejamiento en vivo y la incrustación de cuadernos en la web.awesome-marimo-notebook: cómo hacer que un cuaderno explicativo de artículo o conjunto de datos sea atractivo y pulido.
Declara las dependencias en un bloque de metadatos de script en línea PEP 723 al principio del archivo (# /// script … # ///), listando marimo y cada paquete que importe el cuaderno, cada uno con una versión mínima (ej. numpy>=2.0). Esto permite que uv run y marimo edit --sandbox los instalen.
Termina el cuaderno con el cuestionario de cinco preguntas descrito en Prueba final.
Requisitos estrictos para la prosa:
- Inteligible y representativa de las ideas centrales del artículo.
- No es "basura de IA" genérica. Si una frase podría haberse escrito sobre cualquier artículo, reescríbela.
- Define símbolos y términos del campo cuando aparezcan por primera vez, o apunta a un glosario / tooltip / ayuda de resaltar para explicar. Sigue
resources/field-maturity.mdpara secciones de incorporación específicas de madurez. PENDIENTE: cuáles de esas ayudas al lector enviar primero. "Marimo Lens" se mencionó como posible opción para resaltar y explicar; confirma el nombre real de la función y la compatibilidad del anfitrión.
Otras reglas de generación:
- Ecuaciones: LaTeX en
mo.md; widgets sobre parámetros cuando eso genere intuición. - Figuras: reproduce o simplifica cuando los datos lo permitan; enlaza al número de figura del artículo. Si los datos no están disponibles, dilo; no inventes gráficos. PENDIENTE: hasta dónde llegar con estimaciones basadas en visión o interpretaciones de figuras escritas por el lector en v1.
- Recorridos de figuras: cuando una figura clave necesite un recorrido guiado paso a paso, lee
resources/dynamic_figure_annotation.md(FigureAnnotatorWidgetmás una ayuda de auditoría de coordenadas enscripts/). - Conceptos centrales (1–3 por cuaderno) reciben una escalera de explicación (Explicar en múltiples niveles).
- Verificaciones informales: preguntas cortas, no evaluación calificada. Usa el patrón
show_checkenresources/explanation-levels.md§9 (radio, una respuesta numérica con tolerancia, o una respuesta abierta con una respuesta modelo). - Modo de dominio del paso 2: ejercicios de codificación y reconstrucción de métodos para artículos similares a algoritmos; widgets explicativos/interactivos escritos por el agente para artículos similares a conceptos (por ejemplo, un mecanismo en una celda).
- Etiqueta cualquier cosa que vaya más allá del artículo ("Nuestra demo", "Suposición simplificada").
- Incluye metadatos del artículo y citas.
5. Validar y entregar
Mínimo (esqueleto v1): el cuaderno debe ejecutarse.
uv run scripts/validate_notebook.py ruta/al/cuaderno.py --run
Verifica la sintaxis de Python, ejecuta marimo check --strict y, con --run, ejecuta el cuaderno de principio a fin. Corrige cualquier problema reportado antes de la entrega.
Informa al usuario:
- Ruta al cuaderno y el comando para abrirlo (
uvx marimo edit --sandbox …). - Audiencia asumida y qué se simplificó.
- PENDIENTES y lagunas conocidas (incluyendo datos faltantes o términos indefinidos).
- Referencia del artículo (título, autores, año, enlace).
Validación planificada más allá de "se ejecuta" (no todo es necesario para un primer esbozo):
- La redacción es inteligible y representativa, no basura.
- Los conceptos centrales y términos de metadatos realmente se explican.
- No hay números o afirmaciones inventados.
- El cuaderno termina con el cuestionario de cinco preguntas, y sus preguntas tratan sobre las afirmaciones, hallazgos y limitaciones del artículo, no sobre sus detalles de implementación.
- Cada escalera explica el mismo mecanismo central en todos los niveles; cada simplificación en la escalera se corrige en un nivel posterior; se indica el límite de la analogía.
- Incorporación de vocabulario: para los casos de estudio establecido, emergente e interdisciplinario, verifica la cobertura del glosario y, cuando sea necesario, las secciones de desambiguación o terminología en evolución según
resources/field-maturity.md§8. - PENDIENTE: evaluaciones basadas en aserciones o preguntas de oro; ejecuciones con múltiples modelos (se ofrecieron modelos chinos de peso abierto y modelos Claude); LLM como juez solo como primer filtro más confiable para "esto es malo" que para "esto es bueno"; prueba humana con un artículo desconocido; revisión de experto en el dominio después de una prueba de humo en su propio campo.
- PENDIENTE: un conjunto de artículos de prueba compartido que cubra trabajo establecido, emergente e interdisciplinario, y subdominios, no solo un campo. Se ofreció un artículo sobre gripe de 2016 como un posible caso; la lista no está elegida.
Explicar en múltiples niveles
Las ideas centrales reciben una escalera de explicación: un mecanismo explicado en cinco niveles, cada uno escrito para un lector con prerrequisitos específicos. Está modelada en la serie 5 Niveles de WIRED. Los nombres de los niveles son abreviaturas. Lo que define un nivel es el conocimiento del tema y las matemáticas que el lector aporta, y la precisión que el nivel añade.
| Nivel (abreviatura) | Conocimiento del tema asumido | Matemáticas asumidas | Añade al mecanismo |
|---|---|---|---|
| 1 · Niño | Experiencia cotidiana | Contar y comparar | Causa y efecto, en términos cotidianos |
| 2 · Adolescente | Alfabetización científica general | Aritmética, porcentajes, gráficos simples | Un ejemplo sencillo con números reales pequeños |
| 3 · Licenciatura | Un curso introductorio en el campo | Herramientas introductorias del campo | La ecuación o algoritmo exacto, cada símbolo definido |
| 4 · Posgrado | Métodos estándar de un área adyacente | Sigue las derivaciones del artículo | Suposiciones, cuándo se cumple, qué falla y cómo se compara con el enfoque estándar |
| 5 · Experto | Literatura de este subcampo | Formalismo completo | Qué es nuevo, compensaciones, límites y preguntas abiertas |
Reglas:
-
Perfil de prerrequisitos por artículo (Fase 1): para cada nivel, qué sabe el lector, qué no sabe y qué debe enseñar el cuaderno. Mapea el contexto declarado del usuario (de las entradas opcionales del Contrato) a un nivel.
-
Un mecanismo en cada nivel. Escribe primero una columna vertebral del mecanismo de una oración; cada nivel añade precisión. Ningún nivel sustituye un mecanismo más vago o diferente.
-
Preciso en cada nivel. Simplifica omitiendo cosas, nunca diciendo algo falso. Registra cada simplificación en un libro de contabilidad y corrígela en un nivel posterior.
-
Mapea la analogía y declara su límite. Lleva un ancla hasta el Nivel 3, mapea sus partes en las partes del método y di dónde se rompe en el Nivel 3.
-
Verificaciones ajustadas al nivel:
- Niño: explicar.
- Adolescente: predecir.
- Licenciatura: aplicar.
- Posgrado: aplicar y criticar suposiciones.
- Experto: criticar.
Cada verificación tiene una respuesta esperada, el razonamiento y la ubicación en el artículo.
-
Las escaleras son para lo central: 1–3 conceptos por cuaderno.
-
Fundamentadas: cita ubicaciones del texto que leíste y nunca adivines. Marca las lagunas
[cita: …]durante el borrador y resuélvelas antes de enviar. -
Los números llevan sus condiciones: la tabla, cohorte, conjunto de características o rango van en la misma oración. En pruebas con artículos reales, ambas ideas erróneas que causaron las escaleras provinieron de un número despojado de su condición.
En el cuaderno: añade un selector de nivel cerca de la parte superior. Cada escalera recibe mo.ui.tabs que se abre en el nivel del lector, con su verificación debajo.
Leer antes de escribir: resources/explanation-levels.md tiene las plantillas de perfil y libro de contabilidad, un ejemplo trabajado, celdas de marimo probadas y trampas. resources/examples/ tiene dos escaleras más completas,
...
[truncado para traducción]