{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![Abrir en Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/flizamar/entrenamiento-ioai-web/blob/gh-pages/plantillas/template.ipynb)\n",
    "\n",
    "# Plantilla de trabajo · IOAI\n",
    "\n",
    "**Tarea**: · **Ronda**: · **Métrica**: · **Límite de ejecución**:\n",
    "\n",
    "**Baseline local**: · **Split**: · **Referencia oficial y su split**:\n",
    "\n",
    "**Archivos exigidos**: · **Modelos permitidos**: · **Datos/etiquetas autorizados**:\n",
    "\n",
    "El plan, en este orden y sin saltarse pasos:\n",
    "\n",
    "1. **Mirar los datos** antes de modelar.\n",
    "2. **Baseline**: el primer envío, que asegura el formato de salida.\n",
    "3. **Modelo**: una mejora barata primero, profundizar solo si sobra tiempo.\n",
    "4. **Evaluar** con la métrica oficial, sobre una validación honesta.\n",
    "5. **Restart & Run all** antes de enviar.\n",
    "\n",
    "Y la regla que ordena todo lo demás: en la IOAI **empatar el baseline vale\n",
    "cero**, así que lo primero es despegarse de él — no resolver la tarea."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 0. Preparación y ensayo offline\n",
    "\n",
    "Primero instala el entorno de estudio y prepara los datos y pesos según el\n",
    "contrato de la tarea. Ver `referencia/Entorno de estudio.md`. Esa preparación se\n",
    "hace antes de activar el modo offline. Registra fuente, versión y archivos.\n",
    "\n",
    "La plantilla arranca en aprendizaje. Activa `SIMULAR_COMPETENCIA` cuando hayas\n",
    "comprobado los activos y quieras ensayar una ejecución sin descargas. Las\n",
    "banderas de Hugging Face pueden leer archivos de caché mediante un ID; no\n",
    "comprueban por sí mismas qué modelo está permitido. Si el enunciado exige rutas\n",
    "locales, úsalo así.\n",
    "\n",
    "Estas ayudas bloquean algunos comandos de instalación y miden bloques. No\n",
    "constituyen el aislamiento ni el límite estricto del juez. Ensaya también la\n",
    "carga, entrenamiento, inferencia y escritura desde un kernel nuevo.\n",
    "\n",
    "> Es código **generado** desde la receta «Modo competencia» del vault, que se\n",
    "> ejecuta contra sus pruebas en cada publicación. No lo edites acá: edita la\n",
    "> receta y regenera con `python3 herramientas/generar_plantilla.py`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import re\n",
    "import time\n",
    "\n",
    "PATRON_INSTALACION = re.compile(\n",
    "    r\"^\\s*[!%]\\s*(pip3?|conda|mamba|uv|apt|apt-get)\\b.*\\binstall\\b\", re.I)\n",
    "\n",
    "\n",
    "def rechazar_instalacion(codigo):\n",
    "    \"\"\"Si el código intenta instalar un paquete, devuelve el motivo; si no, None.\n",
    "\n",
    "    En la IOAI **está prohibido instalar paquetes**: lo que hay en la máquina es\n",
    "    lo que hay. Entrenar donde `!pip install` funciona construye justo el\n",
    "    reflejo que falla el día de la prueba.\n",
    "    \"\"\"\n",
    "    for linea in codigo.splitlines():\n",
    "        if PATRON_INSTALACION.match(linea):\n",
    "            return (\"prohibido instalar paquetes: %r. En la competencia no se \"\n",
    "                    \"puede, así que resuélvelo con lo que ya está instalado.\"\n",
    "                    % linea.strip())\n",
    "    return None\n",
    "\n",
    "\n",
    "def activar_offline():\n",
    "    \"\"\"Pone el ecosistema HuggingFace en modo offline y devuelve qué cambió.\n",
    "\n",
    "    Actívalo ANTES de importar las librerías de HuggingFace. Evita sus\n",
    "    consultas HTTP; un id del Hub puede funcionar si está completo en caché.\n",
    "    No comprueba qué modelos permite la tarea ni desconecta toda la red.\n",
    "    Prepara primero los archivos locales y usa las rutas del enunciado.\n",
    "    \"\"\"\n",
    "    banderas = {\"HF_HUB_OFFLINE\": \"1\", \"TRANSFORMERS_OFFLINE\": \"1\",\n",
    "                \"HF_DATASETS_OFFLINE\": \"1\"}\n",
    "    os.environ.update(banderas)\n",
    "    return banderas\n",
    "\n",
    "\n",
    "def solo_de_train(ruta):\n",
    "    \"\"\"Guarda opcional para ejercicios que SOLO permiten etiquetas de train.\n",
    "\n",
    "    Comprueba el nombre de la ruta, no su contenido ni sus permisos. Adapta\n",
    "    esta política al enunciado: tareas adversariales como Double Agent Dilemma\n",
    "    sí entregan y permiten etiquetas de test para construir el ataque.\n",
    "    \"\"\"\n",
    "    partes = re.split(r\"[/\\\\]\", str(ruta))\n",
    "    if not any(p.lower().startswith(\"train\") for p in partes):\n",
    "        raise ValueError(\n",
    "            \"esta guarda exige una ruta de train/, y %r no lo es. Comprueba \"\n",
    "            \"si esa política corresponde al enunciado antes de usarla.\"\n",
    "            % str(ruta))\n",
    "    return ruta\n",
    "\n",
    "\n",
    "class Presupuesto:\n",
    "    \"\"\"Cronómetro del límite de ejecución de una tarea.\n",
    "\n",
    "        with Presupuesto(minutos=10, nombre=\"Ghost of the Machine\") as p:\n",
    "            entrenar(...)\n",
    "            print(\"%.0f s de margen\" % p.restante())\n",
    "\n",
    "    Al salir informa cuánto se usó; si se pasó del límite levanta TimeoutError,\n",
    "    y si pasó del 60% avisa. Ese margen no es paranoia: el límite cubre también\n",
    "    la re-ejecución del notebook sobre los datos ocultos, en una máquina que no\n",
    "    es la tuya.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, minutos=10.0, nombre=\"la tarea\", margen=0.6):\n",
    "        self.limite = minutos * 60.0\n",
    "        self.nombre = nombre\n",
    "        self.margen = margen\n",
    "        self.inicio = None\n",
    "        self.usado = None\n",
    "\n",
    "    def __enter__(self):\n",
    "        self.inicio = time.perf_counter()\n",
    "        return self\n",
    "\n",
    "    def transcurrido(self):\n",
    "        return time.perf_counter() - self.inicio\n",
    "\n",
    "    def restante(self):\n",
    "        return self.limite - self.transcurrido()\n",
    "\n",
    "    def __exit__(self, tipo, valor, traza):\n",
    "        self.usado = self.transcurrido()\n",
    "        pct = (100.0 * self.usado / self.limite) if self.limite else 0.0\n",
    "        print(\"⏱️  %s: %.1f s de %.0f s (%.0f%% del límite)\"\n",
    "              % (self.nombre, self.usado, self.limite, pct))\n",
    "        if tipo is not None:\n",
    "            return False                    # ya hay un error: no lo tapamos\n",
    "        if self.usado > self.limite:\n",
    "            raise TimeoutError(\n",
    "                \"%s se pasó del límite: %.1f s de %.0f s permitidos.\"\n",
    "                % (self.nombre, self.usado, self.limite))\n",
    "        if self.usado > self.limite * self.margen:\n",
    "            print(\"⚠️  usaste más del %.0f%% del límite. El juez re-ejecuta el \"\n",
    "                  \"notebook sobre los datos ocultos: deja margen.\"\n",
    "                  % (self.margen * 100))\n",
    "        return False\n",
    "\n",
    "\n",
    "def modo_competencia(offline=True, bloquear_instalaciones=True):\n",
    "    \"\"\"Activa ayudas de simulacro y devuelve cuáles pudo activar.\n",
    "\n",
    "    Debe ejecutarse tras preparar activos y antes de importar HuggingFace.\n",
    "    No crea un sandbox ni impone todas las reglas de la plataforma oficial.\n",
    "    \"\"\"\n",
    "    activado = {}\n",
    "    if offline:\n",
    "        activado[\"offline\"] = activar_offline()\n",
    "    if bloquear_instalaciones:\n",
    "        try:\n",
    "            ip = get_ipython()              # noqa: F821  (existe en Jupyter)\n",
    "        except NameError:\n",
    "            ip = None\n",
    "        if ip is None:\n",
    "            activado[\"instalaciones\"] = \"sin bloquear (fuera de IPython)\"\n",
    "        else:\n",
    "            def guardia_instalaciones(lineas):\n",
    "                motivo = rechazar_instalacion(\"\".join(lineas))\n",
    "                if motivo:\n",
    "                    raise RuntimeError(motivo)\n",
    "                return lineas\n",
    "\n",
    "            previos = [t for t in ip.input_transformers_cleanup\n",
    "                       if getattr(t, \"__name__\", \"\") == \"guardia_instalaciones\"]\n",
    "            for t in previos:                # idempotente: no acumula guardias\n",
    "                ip.input_transformers_cleanup.remove(t)\n",
    "            ip.input_transformers_cleanup.append(guardia_instalaciones)\n",
    "            activado[\"instalaciones\"] = \"bloqueadas\"\n",
    "    return activado"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "LIMITE_MINUTOS = 10           # sustituye por el contrato de la tarea\n",
    "SIMULAR_COMPETENCIA = False  # activar después de preparar y comprobar activos\n",
    "ACTIVOS_REQUERIDOS = []      # rutas a datos y pesos que TU solución realmente usa\n",
    "\n",
    "faltantes = [str(p) for p in ACTIVOS_REQUERIDOS if not Path(p).exists()]\n",
    "if faltantes:\n",
    "    raise FileNotFoundError(\"Prepara estos activos antes del ensayo: \" + \", \".join(faltantes))\n",
    "if SIMULAR_COMPETENCIA:\n",
    "    print(modo_competencia())\n",
    "else:\n",
    "    print(\"Aprendizaje: prepara el contrato, los datos y los modelos antes del ensayo offline.\")\n",
    "if not ACTIVOS_REQUERIDOS:\n",
    "    print(\"La lista de activos está vacía: complétala al implementar tu solución.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Semillas y dispositivo\n",
    "\n",
    "Sin semilla fija, dos corridas dan números distintos y no sabes si tu mejora fue\n",
    "real o fue suerte. Y el `device` con su `if` para que el mismo notebook corra en\n",
    "tu máquina sin GPU y en la de la competencia con una."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import random\n",
    "\n",
    "import numpy as np\n",
    "import torch\n",
    "\n",
    "SEMILLA = 42\n",
    "random.seed(SEMILLA)\n",
    "np.random.seed(SEMILLA)\n",
    "torch.manual_seed(SEMILLA)\n",
    "torch.cuda.manual_seed_all(SEMILLA)\n",
    "\n",
    "dispositivo = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n",
    "print(\"dispositivo:\", dispositivo)\n",
    "if dispositivo == \"cuda\":\n",
    "    print(\"VRAM: %.1f GB\" % (torch.cuda.get_device_properties(0).total_memory / 1e9))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Los datos — mirar antes de modelar\n",
    "\n",
    "El ritual de apertura: tamaño, tipos, nulos, balance de clases, y **de dónde\n",
    "viene cada fila** (si varias comparten origen, el split va por grupo).\n",
    "\n",
    "Lee únicamente las etiquetas autorizadas por el enunciado. La mayoría de tareas\n",
    "supervisadas reserva las del test, pero existen excepciones explícitas como\n",
    "Double Agent Dilemma. `solo_de_train()` es una guarda opcional para cargas de\n",
    "entrenamiento; comprobar el nombre de una ruta no demuestra ausencia de fuga."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# datos = json.load(open(solo_de_train(\"dataset/train/answers.json\")))\n",
    "# print(len(datos))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Baseline\n",
    "\n",
    "El primer envío. No busca puntaje: busca **verificar que el formato de salida es\n",
    "correcto** y dejar anotado tu cero."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Modelo\n",
    "\n",
    "Mide el coste completo, incluida carga de activos, entrenamiento, inferencia y\n",
    "escritura. Reservar un 40% para otras fases es una heurística inicial, no una\n",
    "regla del juez. Este cronómetro informa al salir del bloque; no interrumpe\n",
    "un entrenamiento que se excede. En GPU sincroniza antes de medir cada fase."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with Presupuesto(minutos=LIMITE_MINUTOS, nombre=\"entrenamiento\") as p:\n",
    "    pass  # entrenar acá\n",
    "    print(\"margen: %.0f s\" % p.restante())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Evaluación y salida\n",
    "\n",
    "Con la **misma métrica** de la competencia, sobre tu validación. Y el archivo de\n",
    "salida con el nombre, la forma y las claves exactas que pide el enunciado."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. Ensayo de entrega\n",
    "\n",
    "Reinicia el kernel y ejecuta todo con los activos permitidos. Comprueba que\n",
    "aparecen los archivos que exige el enunciado, con sus nombres, tamaños y formas.\n",
    "La ejecución completa debe caber en el límite, en el hardware correspondiente.\n",
    "Una métrica local y una estimación del score oficial son resultados distintos."
   ]
  }
 ],
 "metadata": {
  "colab": {
   "provenance": [],
   "toc_visible": true
  },
  "kernelspec": {
   "display_name": "Python 3",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
