multi-dim-manager

Una habilidad autocontenida que ordena el estado de experimentos computacionales multidimensionales de larga duración. Tu plugin de cómputo realiza las matemáticas; esta habilidad gestiona el caos circundante: iteración, instantáneas, auditoría y retroceso.

La habilidad solo orquesta. Nunca calcula un resultado por sí misma; cada número proviene de tu plugin.

Cuándo usarla

Un flujo de trabajo ejecuta muchas rondas sobre un espacio de parámetros (una rejilla cartesiana de dimensiones) y necesita registrar el estado de cada ronda.
Se requieren instantáneas por ronda de los archivos críticos declarados antes y después de cada ronda.
Debe existir un registro de auditoría completo (parámetros, hashes, marcas de tiempo, estado) para cada ronda.
El usuario debe poder retroceder a cualquier ronda pasada, de forma no destructiva.
Formas típicas: estudios longitudinales, barridos de parámetros o recorridos simbólicos/numéricos que invocan solvers externos (Mathematica, GAP, SymPy, scripts personalizados).

FLUJO DE TRABAJO OBLIGATORIO

Inicialización de dependencias (ejecutar la primera vez)

Antes de la primera ejecución, verifica las dependencias en tiempo de ejecución de esta habilidad:

Central: biblioteca estándar pura: no requiere instalación.
Opcional: PyYAML (solo cuando la configuración es un .yaml; las configuraciones JSON funcionan solo con la biblioteca estándar).

Si falta PyYAML y la configuración del usuario es YAML, indícaselo y pregúntale si desea pip install pyyaml; instala solo después de que lo confirme explícitamente. Nunca instales en el entorno global sin consentimiento explícito.

Sigue estos pasos en orden cada vez que el usuario solicite ejecutar, inspeccionar o recuperar un experimento multidimensional.

Cargar la configuración. Lee el archivo de configuración del experimento (config.example.yaml es la plantilla). Confirma que param_space.dimensions, critical_paths y plugin.command estén presentes. Si se usa YAML, PyYAML debe estar instalado; de lo contrario, usa JSON.
Expandir el espacio. Enumera el producto cartesiano de todas las dimensiones. Informa al usuario el número total de rondas antes de ejecutar.
Preferir una ejecución en seco. Ejecuta python scripts/run.py dryrun --config <cfg> para que el usuario vea el plan completo (cada combinación de parámetros) sin efectos secundarios. Solo procede a la ejecución después de su confirmación.
Ejecutar el barrido. Ejecuta python scripts/run.py run --config <cfg>. Para cada ronda, en orden: toma una instantánea de las rutas críticas declaradas antes, invoca el plugin, toma una instantánea después y agrega un registro de auditoría.
Reaccionar correctamente a fallos. Si el plugin de una ronda sale con código distinto de cero, registra su estado (failed/error). Cuando auto_rollback está activado, recupera el estado posterior de la última ronda exitosa en el directorio de trabajo para que las rondas posteriores comiencen limpias; esta recuperación también se audita. No detengas todo el barrido por una sola combinación mala.
Resumir. Después del barrido, la habilidad escribe results_summary.csv, results_summary.md, report_draft.md y run_metadata.json en el directorio de salida. Señala al usuario estos archivos.
Recuperar a solicitud. Para restaurar una ronda pasada, ejecuta python scripts/run.py rollback --config <cfg> --round <N>. Por defecto restaura en un directorio NUEVO; solo agrega --force cuando el usuario quiera explícitamente sobrescribir el directorio de trabajo activo.

Restricciones estrictas

Nunca calcules el resultado tú mismo. Todas las matemáticas de dominio pertenecen al plugin del usuario. La habilidad solo lo invoca y registra el resultado del contrato.
Solo toma instantáneas de rutas críticas declaradas. Nunca se realiza una copia completa del directorio de trabajo; el contenido se almacena direccionado por hash, por lo que los archivos sin cambios no cuestan nada adicional.
El retroceso es no destructivo por defecto. Sin --force, el directorio de trabajo activo nunca se modifica; el estado restaurado se coloca en un nuevo directorio. Cada retroceso (manual o automático) se escribe en el registro de auditoría.
El determinismo es promesa del usuario. La habilidad garantiza que la orquestación sea reproducible (mismos parámetros -> mismo plan registrado, mismos hashes). No puede hacer que un plugin no determinista sea determinista; consulta Limitaciones.

Ejemplos de uso

# Imprime el plan completo de rondas sin efectos secundarios (haz esto siempre primero).
python scripts/run.py dryrun --config config.example.yaml

# Ejecuta el barrido.
python scripts/run.py run --config config.example.yaml

# Restaura una ronda pasada (en un directorio NUEVO a menos que se use --force).
python scripts/run.py rollback --config config.example.yaml --round 7

# Regenera los resúmenes, o verifica el resultado de una ronda.
python scripts/run.py summary --config config.example.yaml
python scripts/run.py verify --config config.example.yaml --round 7

Contrato del plugin

El gestor ejecuta exactamente un comando de shell por ronda:

python your_plugin.py --params {PARAMS} --out {OUT}

{PARAMS} - ruta a un archivo JSON con la combinación de parámetros de esta ronda.
{OUT} - ruta donde el plugin DEBE escribir su JSON de resultado.
Códigos de salida: 0 éxito, 1 fallo de aserción / comprobación fallida, 2 error o omitido.

Cualquier solver externo (Mathematica, GAP, un script Python de LMM) se envuelve para honrar este contrato: lee el archivo de parámetros y escribe un archivo de resultado. A la habilidad no le importa qué se calcula.

Manejo de fallos

Una ronda cuyo plugin sale con 1 se marca como failed; salida 2 es error. Ambos se mantienen en el registro de auditoría; el barrido continúa.
Errores de config (espacio faltante, YAML incorrecto, falta {OUT}) abortan antes de cualquier efecto secundario e imprimen un mensaje claro (código de salida 2).
rollback a una ronda que nunca se registró, o que no tiene instantánea posterior, falla con un error claro en lugar de corromper el estado.

Limitaciones

El determinismo es solo a nivel de orquestación. El gestor registra hashes y reproduce el mismo plan para los mismos parámetros, pero no puede asegurar que el plugin sea determinista. Si el plugin toca la red, usa semillas aleatorias o lee el reloj del sistema, las mismas entradas pueden dar diferentes salidas. Declara dicha no determinismo en el plugin tú mismo.
Las rutas críticas deben declararse de antemano. Los archivos no listados en critical_paths nunca se instantanean y, por lo tanto, no se pueden retroceder.
La verificación de salida dorada es v0.2. El verificador actual solo comprueba el contrato del plugin (salida 0 + archivo de resultado presente). La comparación con una salida esperada conocida está planificada pero aún no implementada.
Las configuraciones YAML necesitan PyYAML. Las configuraciones JSON funcionan solo con la biblioteca estándar.

JiamingShi-JsPhys/agent-skills

¿Qué es agent-skills?

Preguntar en tu IA favorita

Documentación