/ C01 · 2
← Clasificación de imágenes C01 · Estación 2 de 12

Versionado y linaje

¿Cómo sabes, meses después, con qué datos exactos se entrenó un modelo?

Estás aquí2 · Versionado y linaje

Arranca en 3 pasos

lo vital

Necesitas: Docker Desktop corriendo, con ≈ 400 MB libres para la imagen de RustFS · Python 3.11 o más nuevo (se probó con 3.14.3) y ≈ 300 MB para el entorno virtual · git (con tu nombre y correo configurados) · Los puertos 9300 y 9301 libres en tu Mac

2

Levanta el mundo

Terminalarranque
unzip c01-versionado.zip && cd c01-versionado
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
docker compose up -d --wait
python mundo/crear.py
git init && git add -A && git commit -m "kit recién descomprimido"
dvc init && git commit -m "dvc init"
3

Verifica

Terminal
python verificar.py mundo
Listo cuando: verificar.py mundo en verde. Ya puedes practicar.
¿Algo falló al levantar?
Ojo: Si el 9300 está ocupado, lsof -nP -iTCP:9300 -sTCP:LISTEN te dice quién. La consola web de RustFS está en http://localhost:9301 (usuario taller, contraseña taller-secreto): ahí ves los dos buckets.

python3 -m venv .venv && source .venv/bin/activate · Tarda ≈ 1 minuto la primera vez. Desde aquí, cada terminal nueva necesita source .venv/bin/activate.

SalidaSalida real · python3 -m venv .venv && source .venv/bin/activate
Python 3.14.3
SalidaSalida real · docker compose up -d --wait
 Container taller-c01-versionado-s3-1 Waiting 
 Container taller-c01-versionado-s3-1 Healthy
  buckets: fotos (el producto) y ml-datos (con versiones)
  s3://fotos: 3120 fotos, 7.3 MB
  entrada/: 3120 publicaciones, 3908 eventos de labels, golden de 280 huellas
  s3://ml-datos/datasets/ds-2026-08-01/: 2013 filas (1882 train · 131 val)
  entrada/borrados.csv: 14 huellas de s-217 (fotos borradas del bucket el 15 de septiembre)
  corridas/run-20260901-061500.json: modelo-2026-09-01 ← ds-2026-08-01 (accuracy_val 0.7481)
✓ mundo listo

git init && git add -A && git commit -m "kit recién descomprimido" · Los ids de commit cambian en cada máquina.

SalidaSalida real · git init && git add -A && git commit -m "kit recién descomprimido"
6087a76 dvc init
c038d9d kit recién descomprimido
SalidaSalida real · python verificar.py mundo
✓ mundo          S3 local con fotos (1000+) y ml-datos (ds-2026-08-01 publicado) · entrada/ completa · git y DVC 3.67.1

1/1 en verde

¿Ya está corriendo? Elige cómo practicar

las cuatro rondas

Cada ronda se trabaja en una sesión de Claude Code abierta en la carpeta del kit. Copia el prompt de la ronda y pégalo; el enlace de cada tarjeta te lleva a su sección en esta página. El CLAUDE.md del kit pone las reglas de fondo.

ConstruirRomper Con ayuda
1 · Construir con ayudaCon el Guiado de abajo: construyen juntos los pasos 1 a 8. Empieza aquí.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 2 de C01, «Versionado y linaje», ronda **Construir con ayuda**.

Lee primero `CLAUDE.md` y `GUION.md` de esta carpeta. Vamos a escribir juntos, siguiendo los pasos 0 a 8 de `GUION.md`, el pipeline que convierte los labels del mes en el snapshot `ds-2026-09-01`: los labels al corte, el manifest, el split estable, el contrato de datos, la publicación inmutable con su tarjeta, el pipeline como DAG con DVC, el entrenamiento que deja los punteros del linaje y la búsqueda al revés (de una foto a sus snapshots y modelos).

Entre el paso 0 y el 1, `GUION.md` trae los «Precálculos»: las cuentas de servilleta de la estación. Pídeme que haga cada cuenta yo primero, corrígeme y después corre el comando que la comprueba (o dime en qué paso se va a confirmar).

En cada paso:
1. Dime el objetivo en una línea y explícame los conceptos que usa, rápido, con una analogía y con el término en inglés.
2. Escribe conmigo el archivo del paso, línea por línea y con el porqué de cada una. No me pegues el archivo entero de golpe. El contrato de arriba de cada archivo manda.
3. Dime qué comando correr y espera a que te pegue la salida. Los que cambian algo (`pipeline/5_publicar.py`, `dvc repro`, `pipeline/6_entrenar.py`, `git commit`, `mundo/s3.py borrar-version`) no los corras tú sin decírmelo antes.
4. Corre `python verificar.py <check del paso>` y explícame el resultado.
5. Anota el paso en la bitácora (sección «Bitácora» de `CLAUDE.md`) con lo que hice, lo que medí y lo que sigue.

Si algo falla, no lo arregles en silencio: muéstrame el error, dime tu hipótesis y arreglémoslo juntos. Al final, corre `python verificar.py` completo y cierra la ronda en `taller/progreso.json`.
Ir al Guiado ↓
3 · Romper con ayudaUna falla real; Claude te guía con preguntas.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 2 de C01, «Versionado y linaje», ronda **Romper con ayuda**.

Lee `CLAUDE.md`. Todo pasa `python verificar.py`. Ahora:

1. Corre `python romper.py --mostrar` (o `--mostrar --falla <id>` si te digo cuál). El script mete la falla en el mundo, la configuración o la infraestructura, nunca en mi pipeline ni en mi `dvc.yaml`, y te dice cuál fue. **A mí no me la digas.** Solo cuéntame la «historia»: qué notó alguien en el equipo.
2. Corre `python verificar.py` y pregúntame qué veo.
3. Guíame con preguntas en este orden: síntoma → hipótesis (pídeme al menos dos) → el comando que confirma o descarta cada una (`dvc status`, `git status`, `python mundo/s3.py versiones …`, `python mundo/s3.py versionado …`, `python pipeline/7_linaje.py …`) → el arreglo. Si me atoro más de dos veces en el mismo punto, dame una pista concreta y anótala.
4. Cuando lo arregle, corre `python romper.py --verificar`. Ahí sí explícame qué era, el concepto detrás y cómo se vería en C01 de verdad (Amazon S3, la política del bucket, el orquestador, MLflow).
5. Anota en la bitácora la falla, cuánto tardé, cuántas pistas usé y qué aprendí.

Repetimos con otra falla hasta que te diga que paremos. Para volver al estado sano entre fallas: `python romper.py --restaurar`.
Ir a Romper ↓
Solo
2 · Construir soloRehaces todo desde el esqueleto, solo con los objetivos de Solo.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 2 de C01, «Versionado y linaje», ronda **Construir solo**.

Lee `CLAUDE.md`. **No leas `GUION.md`** ni `mundo/comun.py`, y no me des código: esta ronda la escribo yo desde el esqueleto, con `OBJETIVOS.md` y los contratos de cada archivo como única guía.

Tu papel:
- Primero corre `python mundo/reiniciar.py --pipeline`: respalda mis archivos en `.respaldo/`, pone el esqueleto (pipeline/, `dvc.yaml` vacío y `params.yaml` de fábrica), borra `data/`, mis corridas y los snapshots que publiqué (deja el de agosto). Confírmame qué se borró y haz conmigo el commit del esqueleto.
- Cuando te lo pida, corre `python verificar.py` (o un check suelto) y dime qué objetivo pasa y cuál no, con el mensaje exacto.
- Si te pregunto algo, contéstame con una pregunta que me acerque o con el concepto, nunca con el código ni con el arreglo. Si te digo «me rindo en este objetivo», ahí sí explícamelo, y anótalo en la bitácora como pista usada.
- Anota en la bitácora cada objetivo cuando pase: cuánto tardé y qué me costó.

Al final, con `python verificar.py` en verde, cierra la ronda en `taller/progreso.json`.
Ir a Solo ↓
4 · Romper soloUna falla escondida; nadie te da pistas.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 2 de C01, «Versionado y linaje», ronda **Romper solo**.

Lee `CLAUDE.md`. Todo pasa `python verificar.py`.

1. Corre `python romper.py` **sin** `--mostrar`. El script elige una falla al azar y la esconde; tú tampoco sabes cuál es, así que no intentes averiguarla leyendo `romper.py`, `.taller/` ni lo que cambió.
2. Dime solo la «historia» que imprime y la hora de inicio. Desde ahí trabajo yo solo: no me des pistas ni hipótesis. Si te pido correr un comando, córrelo y pégame la salida tal cual, sin interpretarla.
3. Cuando te diga «listo», corre `python romper.py --verificar`. Dime si quedó arreglado, cuál era la falla y cuánto tardé. Si no quedó, dime solo que no y sigo.
4. Si te digo «me rindo», corre `python romper.py --revelar` y explícame la falla completa.
5. Anota en la bitácora la falla, el tiempo, si me rendí y qué haría distinto.
Ir a Romper ↓

Lleva la cuenta en tu tablero: el kit anota tu avance en taller/progreso.json y ahí lo importas.

Guiado

paso a paso

¿Aún no levantas el ambiente? Ve al arranque.

El código que ves es el de la solución de referencia, y cada salida es la que salió al correr el kit en una carpeta limpia.

Precálculos. Antes de escribir el pipeline, las cuentas de servilleta del versionado: cuánto pesa un snapshot que cita en vez de copiar, cuánto cuesta guardar un año, cuánto cuesta comprobar cada huella al leer, qué pasa si el split se sortea cada mes y cuántas filas son normales. Cada cuenta va en las dos escalas: C01 y el dojo. Cada uno está dentro del paso donde se usa.

1Labels al cortePara cada foto, el label vigente al 1 de octubre a las 00:00 UTC.

Los labels llegan como eventos: quien vende elige una categoría al publicar, moderación corrige días después y la cola de etiquetado de la estación 1 agrega labels humanos. Nada se edita. El snapshot de septiembre es una consulta: de los eventos de antes del corte, el más reciente de cada foto. Encima va la regla de la estación 1: una elección de quien vende cuenta solo si ya tiene 30 días sin que nadie la corrija.

Pythonpipeline/1_labels.py
"""Paso 1 · Labels al corte.

Entra:  entrada/labels-eventos.parquet   los labels como eventos (nunca se editan: corregir es agregar otro)
        params.yaml                       snapshot.corte y labels.dias_maduracion
Sale:   data/labels.parquet               una fila por foto con el label vigente al corte:
        image_key, label_id, label_source, guia_version, label_ts
Reglas: solo cuentan los eventos con ts antes del corte; de cada foto gana el más reciente (si empatan, el event_id
        mayor); si el que gana es de quien vende ("vendedor"), cuenta solo si ya tiene dias_maduracion días al corte.
"""
from datetime import timedelta

import pandas as pd
from _comun import DATA, ENTRADA, params, utc

p = params()
corte = utc(p["snapshot"]["corte"])
dias = p["labels"]["dias_maduracion"]

ev = pd.read_parquet(ENTRADA / "labels-eventos.parquet")
antes = ev[ev["ts"] < corte]                                  # point-in-time: solo lo que ya existía
vigente = antes.sort_values(["ts", "event_id"]).groupby("image_key").tail(1)   # el más reciente gana
madura = (vigente["label_source"] != "vendedor") | (vigente["ts"] <= corte - timedelta(days=dias))
labels = vigente[madura].rename(columns={"ts": "label_ts"})
labels = labels[["image_key", "label_id", "label_source", "guia_version", "label_ts"]].sort_values("image_key")
labels.to_parquet(DATA / "labels.parquet", index=False)

print(f"eventos: {len(ev)} · antes del corte {corte:%Y-%m-%d %H:%M} UTC: {len(antes)} · después (se ignoran): {len(ev) - len(antes)}")
print(f"fotos con label vigente: {len(vigente)} · sin madurar (quien vende, < {dias} días): {(~madura).sum()}")
print(f"data/labels.parquet: {len(labels)} labels · {labels['label_source'].value_counts().to_dict()}")

utc() de _comun.py rechaza una fecha sin zona: nunca adivina.

Terminal
python pipeline/1_labels.py
Salida
eventos: 3908 · antes del corte 2026-10-01 00:00 UTC: 3796 · después (se ignoran): 112
fotos con label vigente: 3120 · sin madurar (quien vende, < 30 días): 507
data/labels.parquet: 2613 labels · {'vendedor': 1966, 'humano': 465, 'moderador': 182}
Terminal
python -c "import pandas as pd; print(pd.read_parquet('data/labels.parquet').head(3).to_string(index=False))"

guia_version es nulo cuando el label lo puso quien vende o moderación: la guía es del etiquetado humano.

Salida
              image_key  label_id label_source guia_version                         label_ts
2026/04/01/p-000001.jpg         4     vendedor          NaN 2026-04-01 02:44:43.000000+00:00
2026/04/01/p-000002.jpg         7       humano      guia-v1 2026-05-04 03:45:08.965946+00:00
2026/04/01/p-000003.jpg         9     vendedor          NaN 2026-04-01 04:55:05.000000+00:00
Terminal
python verificar.py labels
Salida
✓ labels         2613 labels vigentes al 2026-10-01T00:00:00Z · {'vendedor': 1966, 'humano': 465, 'moderador': 182}

1/1 en verde
Listo cuando: 2,613 labels: ninguno de después del corte y ninguna elección de quien vende con menos de 30 días.
Ojo: 112 eventos son de después del corte: si entran, el snapshot cambia según el día en que lo corras. Y el orden importa: ordena por hora antes de quedarte con el último.
Conceptos de este paso
Labels como eventosappend-only label eventsCada label es una fila nueva que nunca se edita, con su fuente, su guía y su hora. Corregir es agregar otro evento más nuevo.Analogía, por qué importa y la trampa

AnalogíaEl historial de un expediente médico: el diagnóstico nuevo no borra el viejo, se escribe abajo con fecha.

Por qué importaCon eso, un snapshot es una consulta: «para cada foto, el label más reciente que ya existía a tal hora». Nada se pierde y se puede explicar por qué el modelo de agosto aprendió lo que aprendió.

TrampaSi la tabla guarda una fila por foto y la corrección la reescribe, ya no sabes qué label había el día del corte.

Corte (point-in-time)point-in-time cutoffLa hora, en UTC, hasta la que cuenta lo que existe: un snapshot solo ve eventos de antes del corte.Analogía, por qué importa y la trampa

AnalogíaEl cierre de una votación: los votos que llegan después cuentan para la siguiente.

Por qué importaHace que el snapshot sea reproducible: correrlo hoy o en un año da lo mismo, aunque sigan llegando eventos. También el registro de borrados se lee al corte.

TrampaUn corte sin zona horaria (2026-10-01 00:00) se interpreta en la hora de la máquina: en México son 6 horas de diferencia y se cuelan eventos.

2El manifestUna fila por label, con la llave y la huella de su foto.

El manifest no copia fotos: las cita por llave y por huella. La huella la calculó el producto al subir la foto y viene en publicaciones.parquet; el entrenamiento la vuelve a calcular al leer (paso 7). validate="one_to_one" hace que pandas truene si una llave aparece dos veces: un join que duplica filas es el error clásico que infla el volumen.

Pythonpipeline/2_manifest.py
"""Paso 2 · El manifest: una fila por foto, con su huella.

Entra:  data/labels.parquet               del paso 1
        entrada/publicaciones.parquet     quién vende, cuándo, la llave y el sha256 de cada foto (lo calcula el producto al subirla)
Sale:   data/manifest.parquet             una fila por label: image_key, image_sha256, seller_id, label_id, label_source,
        guia_version, label_ts, created_at, bytes. Las fotos no se copian: se citan por llave + huella.
"""
import pandas as pd
from _comun import DATA, ENTRADA

labels = pd.read_parquet(DATA / "labels.parquet")
pubs = pd.read_parquet(ENTRADA / "publicaciones.parquet")
m = labels.merge(pubs[["image_key", "image_sha256", "seller_id", "created_at", "bytes"]],
                 on="image_key", how="left", validate="one_to_one")   # una publicación por llave; si no, truena
huerfanas = m["image_sha256"].isna().sum()
if huerfanas:
    raise SystemExit(f"✗ {huerfanas} labels de fotos que no están en publicaciones.parquet")
m = m[["image_key", "image_sha256", "seller_id", "label_id", "label_source", "guia_version", "label_ts", "created_at", "bytes"]]
m.sort_values("image_key").to_parquet(DATA / "manifest.parquet", index=False)

print(f"data/manifest.parquet: {len(m)} filas · {m['image_sha256'].nunique()} huellas distintas · {m['seller_id'].nunique()} vendedores")
print(f"fotos citadas: {m['bytes'].sum() / 1e6:.1f} MB · manifest: {(DATA / 'manifest.parquet').stat().st_size / 1e3:.0f} kB")
Terminal
python pipeline/2_manifest.py

2,613 filas pero 2,499 huellas: hay fotos repetidas en varias publicaciones. Se resuelve en el paso 3.

Salida
data/manifest.parquet: 2613 filas · 2499 huellas distintas · 300 vendedores
fotos citadas: 6.1 MB · manifest: 246 kB
Terminal
python verificar.py manifest
Salida
✓ manifest       2613 filas, cada una con su llave y su huella · manifest 246 kB · cita 6.1 MB de fotos

1/1 en verde
Listo cuando: Una fila por label, sin huecos, y cada huella igual a la de publicaciones.parquet.
Ojo: 246 kB para citar 6.1 MB: ≈ 4 %. En C01, con fotos de 200 KB, es ≈ 0.1 % (el precálculo «peso»).
Conceptos de este paso
Snapshot inmutableimmutable dataset snapshotUna versión del dataset con id propio (ds-2026-09-01) que, una vez escrita, nadie cambia: ni se borra, ni se reemplaza, ni se le agregan filas.Analogía, por qué importa y la trampa

AnalogíaLa foto de grupo de fin de año: si alguien llega tarde, sale en la del año siguiente; no se retoca la de este año.

Por qué importaEs lo que hace que «el modelo de octubre se entrenó con ds-2026-09-01» sea verdad para siempre. Si el contenido cambia, es otro snapshot con otro id.

TrampaInmutable «por acuerdo» no sirve: un script que corre dos veces o alguien que «arregla» una fila lo rompe sin dar error. Tiene que ser por diseño.

ManifestmanifestUn archivo (aquí, Parquet) con una fila por foto: su llave, su huella, quién la vende, su label, de dónde salió el label y su split.Analogía, por qué importa y la trampa

AnalogíaLa lista de invitados con foto de cada uno, en vez de meter a los invitados en la caja.

Por qué importaCita las fotos en vez de copiarlas: un snapshot pesa ≈ 0.1 % de las imágenes en C01 y se puede guardar uno por mes para siempre.

TrampaSi una foto se borra o cambia bajo la misma llave, la fila apunta a otra cosa. Por eso lleva la huella, y por eso se comprueba al leer.

Huella sha256content hash (SHA-256)64 caracteres hexadecimales que salen de los bytes de un archivo: el mismo contenido da siempre la misma huella; un byte distinto, otra.Analogía, por qué importa y la trampa

AnalogíaUna huella digital: no dice cómo es la persona, pero dice si es la misma.

Por qué importaHay dos: image_sha256 (cada foto) y rows_sha256 (el manifest entero, en la tarjeta). La segunda la guarda cada modelo: si alguien cambia una sola etiqueta, se nota.

TrampaLa huella no impide nada: delata. Y depende de los bytes: el mismo contenido escrito en otro orden da otra huella, por eso las filas se ordenan antes de escribir.

Precálculo
1

¿Cuánto pesa el manifest comparado con las fotos que cita?

manifest = filas × bytes por fila; fotos = filas × bytes por foto; la fracción es bytes por fila ÷ bytes por foto
Ver la cuenta
En C011,932,628 filas × ≈ 200 B = ≈ 387 MB sin comprimir, contra 1,932,628 × ≈ 200 KB = ≈ 387 GB de fotos≈ 0.1 % (y ≈ 97 MB ya en Parquet)
En el dojo≈ 2,600 filas × ≈ 200 B = ≈ 0.5 MB, contra 3,120 fotos de ≈ 2.3 kB (7.3 MB)≈ 9 % sin comprimir: las fotos de juguete son 100 veces más chicas que las de C01

Qué decides con esto. Un snapshot cita, no copia: guardar uno cada mes cuesta casi nada. La proporción depende solo de cuánto pesa cada foto, no de cuántas hay.

Terminalterminal · compruébalo en el kit
python -c "import pandas as pd; p = pd.read_parquet('entrada/publicaciones.parquet'); print(f'{len(p)} publicaciones · {p.bytes.sum() / 1e6:.1f} MB de fotos · {p.bytes.mean() / 1e3:.1f} kB por foto en promedio')"
Salida
3120 publicaciones · 7.3 MB de fotos · 2.3 kB por foto en promedio

Lo confirmas en el paso 2: el manifest real pesa 246 kB en Parquet y cita 6.1 MB de fotos (≈ 4 %).

3Las filas y el split estableSin borrados, sin duplicados, sin golden, y cada vendedor del mismo lado que en agosto.

Tres filtros y una regla. El registro de borrados también se lee al corte: lo que se borró antes del 1 de octubre ya no entra. De cada huella repetida queda la publicación más vieja, que no cambia mes con mes. El golden set nunca entra a entrenar. Y el split no se sortea: la cubeta del vendedor es su sha256 mod 100, el mismo número hoy y dentro de diez años.

Pythonpipeline/3_split.py
"""Paso 3 · Las filas del snapshot: sin borrados, sin duplicados, sin el golden set y con el split estable.

Entra:  data/manifest.parquet             del paso 2
        entrada/borrados.csv              el registro de borrados (image_sha256, fecha, motivo)
        entrada/golden.parquet            las huellas del golden set: nunca entran a entrenar
        params.yaml                       snapshot.corte y split.umbral
Sale:   data/rows.parquet                 las columnas del manifest + split ("train" o "val"), ordenado por image_key
Reglas: fuera las fotos del registro de borrados con fecha antes del corte (el registro también se lee al corte);
        de cada huella repetida queda una fila, la de la publicación más vieja (created_at, y si empatan, image_key);
        fuera las huellas del golden set; split = "train" si sha256(seller_id) mod 100 < split.umbral, si no "val".
"""
import hashlib

import pandas as pd
from _comun import DATA, ENTRADA, params, utc

p = params()
corte = utc(p["snapshot"]["corte"])
umbral = p["split"]["umbral"]

m = pd.read_parquet(DATA / "manifest.parquet")
borr = pd.read_csv(ENTRADA / "borrados.csv")
borr = borr[pd.to_datetime(borr["fecha"], utc=True) < corte]          # el registro también se lee al corte
golden = set(pd.read_parquet(ENTRADA / "golden.parquet")["image_sha256"])

n0 = len(m)
m = m[~m["image_sha256"].isin(set(borr["image_sha256"]))]
n_borr = n0 - len(m)
m = m.sort_values(["created_at", "image_key"]).drop_duplicates("image_sha256", keep="first")  # la publicación más vieja
n_dup = n0 - n_borr - len(m)
n_gold = m["image_sha256"].isin(golden).sum()
m = m[~m["image_sha256"].isin(golden)]


def cubeta(seller_id: str) -> int:
    return int(hashlib.sha256(seller_id.encode()).hexdigest(), 16) % 100   # el mismo número hoy y en diez años


m = m.assign(split=["train" if cubeta(s) < umbral else "val" for s in m["seller_id"]]).sort_values("image_key")
m.to_parquet(DATA / "rows.parquet", index=False)

print(f"manifest: {n0} · borradas antes del corte: {n_borr} · duplicadas por huella: {n_dup} · del golden set: {n_gold}")
print(f"data/rows.parquet: {len(m)} filas · {m['split'].value_counts().to_dict()} · vendedores en val: {m.loc[m['split'] == 'val', 'seller_id'].nunique()}")
Terminal
python pipeline/3_split.py
Salida
manifest: 2613 · borradas antes del corte: 13 · duplicadas por huella: 114 · del golden set: 19
data/rows.parquet: 2467 filas · {'train': 2309, 'val': 158} · vendedores en val: 17
Terminal
python -c "
import hashlib
for s in ['s-001', 's-002', 's-007', 's-001']:
    c = int(hashlib.sha256(s.encode()).hexdigest(), 16) % 100
    print(s, c, 'train' if c < 90 else 'val')"

El mismo vendedor, la misma cubeta, siempre.

Salida
s-001 69 train
s-002 72 train
s-007 8 train
s-001 69 train
Terminal
python verificar.py split split-estable
Salida
✓ split          2467 filas: sin duplicados, sin golden, sin borrados · {'train': 2309, 'val': 158} por vendedor
✓ split-estable  298 vendedores en los dos snapshots, 0 cambiaron de lado · ninguna foto de val del padre en train

2/2 en verde
Listo cuando: 2,467 filas, un solo lado por vendedor y 0 vendedores que cambiaron de lado contra ds-2026-08-01.
Ojo: Deduplicar por image_key no quita nada: cada publicación tiene su llave. Lo que se repite son los bytes. Y ordena por image_key antes de escribir: el mismo contenido tiene que dar la misma huella.
Conceptos de este paso
Duplicados por huellahash-based deduplicationLa misma foto subida en varias publicaciones cuenta una sola vez: de cada huella queda la fila de la publicación más vieja.Analogía, por qué importa y la trampa

AnalogíaTres copias del mismo examen con distinto nombre en la portada: se califica una.

Por qué importaSi la misma foto cayera en train y en val, la validación premiaría memorizar. Pasa con vendedores que republican y con fotos de catálogo que usan dos tiendas.

TrampaDeduplicar por llave no sirve: cada publicación tiene su llave. Lo que se repite son los bytes, o sea la huella.

Registro de borradosdeletion log (tombstones)Una lista de solo agregar con la huella de cada foto que se borró, la fecha y el motivo.Analogía, por qué importa y la trampa

AnalogíaLa lista de bajas de un club: no se arranca la hoja del acta vieja, se anota la baja con fecha.

Por qué importaRespeta el derecho al borrado sin romper la historia: los snapshots viejos no se reescriben, el siguiente ya no la incluye y el entrenamiento la salta al leer.

TrampaBorrar la foto del bucket sin anotarlo deja filas que apuntan a nada y un entrenamiento que truena; anotarlo sin borrar no cumple la solicitud.

Split establestable split (hash-based)Cada vendedor cae en train o en val por el hash de su seller_id (cubeta = sha256 mod 100) y se queda ahí en todas las versiones.Analogía, por qué importa y la trampa

AnalogíaEl número de lista en la escuela: el mismo alumno tiene el mismo número todo el año, aunque entren alumnos nuevos.

Por qué importaComparar el modelo nuevo contra el viejo solo es justo si ninguno vio el examen del otro. Los vendedores nuevos caen donde les toque, sin mover a nadie.

TrampaSortear otra vez, o mover el umbral «para tener más validación», manda a val vendedores con los que el modelo anterior ya entrenó.

Precálculo
4

Si el split se sorteara otra vez cada mes, ¿cuántas fotos de validación pasarían a train?

se mueven = fotos de validación del padre × fracción que va a train
Ver la cuenta
En C0192,417 × 0.95≈ 87,796 fotos con que se validó el modelo de octubre entrenarían al de noviembre
En el dojo131 fotos de validación en ds-2026-08-01 × 0.90≈ 118 de 131

Qué decides con esto. El split no se sortea: se calcula con el hash del vendedor, y así se mueven cero. Cambiar el umbral también mueve gente: el umbral se fija una vez y no se toca.

Terminalterminal · compruébalo en el kit
python -c "import json, sys; sys.path.insert(0, '.'); from mundo.comun import s3; t = json.loads(s3().get_object(Bucket='ml-datos', Key='datasets/ds-2026-08-01/snapshot.json')['Body'].read()); print('ds-2026-08-01:', t['counts'], '· split:', t['split']['rule'])"
Salida
ds-2026-08-01: {'train': 1882, 'val': 131, 'total': 2013} · split: sha256(seller_id) mod 100 < 90 -> train
4El contrato de datosAuditar las filas antes de publicar: 8 reglas, y si una falla, el pipeline se detiene.

Es el «auditar» de escribir, auditar, publicar. Ya escribiste aparte (en data/); ahora se comprueba todo contra reglas fijas. El padre se lee y se comprueba con su huella antes de usarlo: si alguien lo reescribió, la validación del split estable compararía contra algo falso. El código de salida 1 es lo que hace que DVC se detenga.

Pythonpipeline/4_validar.py
"""Paso 4 · El contrato de datos: auditar antes de publicar (write-audit-publish).

Entra:  data/rows.parquet                 del paso 3
        entrada/categorias.json, entrada/golden.parquet
        s3://ml-datos/datasets/<padre>/   el snapshot anterior (su tarjeta y sus filas)
        params.yaml                       snapshot.id, snapshot.padre y validar.*
Sale:   data/validation.json              {"snapshot_id", "padre", "status": "passed" | "failed", "checks": {nombre: "ok" | motivo}}
        con los checks esquema, categorias, duplicados, golden, split_vendedor, split_estable, volumen y vendedor.
        Si alguno falla, sale con código 1: el pipeline se detiene y no se publica nada.
"""
import io
import json
import sys

import pandas as pd
from _comun import DATA, DATOS, ENTRADA, params, s3, sha256

p = params()
v = p["validar"]
rows = pd.read_parquet(DATA / "rows.parquet")
COLUMNAS = ["image_key", "image_sha256", "seller_id", "label_id", "label_source", "guia_version",
            "label_ts", "created_at", "bytes", "split"]

# el padre, comprobado con su huella antes de usarlo
cliente = s3()
tarjeta = json.loads(cliente.get_object(Bucket=DATOS, Key=f"datasets/{p['snapshot']['padre']}/snapshot.json")["Body"].read())
crudo = cliente.get_object(Bucket=DATOS, Key=f"datasets/{p['snapshot']['padre']}/rows.parquet")["Body"].read()
if sha256(crudo) != tarjeta["rows_sha256"]:
    sys.exit(f"✗ el padre {p['snapshot']['padre']} no coincide con su tarjeta: alguien lo reescribió")
padre = pd.read_parquet(io.BytesIO(crudo))

lado_padre = padre.drop_duplicates("seller_id").set_index("seller_id")["split"]
lado = rows.drop_duplicates("seller_id").set_index("seller_id")["split"]
comunes = lado.index.intersection(lado_padre.index)
movidos = (lado[comunes] != lado_padre[comunes]).sum()
validas = {int(k) for k in json.loads((ENTRADA / "categorias.json").read_text())}
golden = set(pd.read_parquet(ENTRADA / "golden.parquet")["image_sha256"])
razon = len(rows) / len(padre)
f_vend = (rows["label_source"] == "vendedor").mean()

checks = {
    "esquema": "ok" if list(rows.columns) == COLUMNAS else f"columnas {list(rows.columns)}",
    "categorias": "ok" if rows["label_id"].isin(validas).all() else f"{(~rows['label_id'].isin(validas)).sum()} labels fuera de las categorías",
    "duplicados": "ok" if rows["image_sha256"].is_unique else f"{rows['image_sha256'].duplicated().sum()} huellas repetidas",
    "golden": "ok" if not rows["image_sha256"].isin(golden).any() else f"{rows['image_sha256'].isin(golden).sum()} fotos del golden set",
    "split_vendedor": "ok" if rows.groupby("seller_id")["split"].nunique().max() == 1 else "hay vendedores en train y en val",
    "split_estable": "ok" if movidos == 0 else f"{movidos} de {len(comunes)} vendedores cambiaron de lado contra {p['snapshot']['padre']}",
    "volumen": "ok" if v["volumen_min"] <= razon <= v["volumen_max"] else f"{razon:.2f} veces el padre (rango {v['volumen_min']}–{v['volumen_max']})",
    "vendedor": "ok" if f_vend <= v["max_vendedor"] else f"{f_vend:.0%} de labels de quien vende (máximo {v['max_vendedor']:.0%})",
}
status = "passed" if all(x == "ok" for x in checks.values()) else "failed"
(DATA / "validation.json").write_text(json.dumps({"snapshot_id": p["snapshot"]["id"], "padre": p["snapshot"]["padre"],
                                                  "status": status, "checks": checks}, ensure_ascii=False, indent=2) + "\n")
for k, x in checks.items():
    print(f"  {'✓' if x == 'ok' else '✗'} {k:<15} {x}")
print(f"{status}: {len(rows)} filas = {razon:.2f} × las {len(padre)} del padre · quien vende {f_vend:.1%} · {len(comunes)} vendedores en los dos, {movidos} movidos")
sys.exit(0 if status == "passed" else 1)
Terminal
python pipeline/4_validar.py
Salida
  ✓ esquema         ok
  ✓ categorias      ok
  ✓ duplicados      ok
  ✓ golden          ok
  ✓ split_vendedor  ok
  ✓ split_estable   ok
  ✓ volumen         ok
  ✓ vendedor        ok
passed: 2467 filas = 1.23 × las 2013 del padre · quien vende 75.6% · 298 vendedores en los dos, 0 movidos
Terminal
python verificar.py validacion
Salida
✓ validacion     passed: esquema, categorias, duplicados, golden, split_vendedor, split_estable, volumen, vendedor

1/1 en verde
Listo cuando: data/validation.json con status: passed y las 8 reglas.
Ojo: Un contrato que imprime un aviso y deja seguir no detiene nada. Cada regla viene de un error real: si dudas de una, pregúntate qué falla real atrapa.
Concepto de este paso
Contrato de datosdata contractLas reglas que los datos cumplen antes de entrenar: esquema exacto, categorías válidas, cero duplicados, cero golden, split por vendedor y estable, volumen en rango y tope de labels débiles.Analogía, por qué importa y la trampa

AnalogíaLa revisión de un avión antes de despegar: una lista fija, la misma cada vez, y si un punto falla no se despega.

Por qué importaDetiene el pipeline antes de gastar GPU. Cada regla viene de un error real: un join que duplica, el golden en train, un split que se movió.

TrampaUn contrato que solo avisa y deja seguir no es contrato: el paso de validar tiene que fallar (código de salida 1) para que nada se publique.

Precálculo
5

¿Cuántas filas son normales para el snapshot nuevo, y cuándo es sospechoso?

razón = filas nuevas ÷ filas del padre; el contrato acepta entre 0.8 y 1.5
Ver la cuenta
En C01con 1,932,628 filas, el padre tendría que estar entre 1,932,628 ÷ 1.5 y 1,932,628 ÷ 0.8entre ≈ 1.29 M y ≈ 2.42 M filas
En el dojopadre de 2,013 filas × 0.8 y × 1.5entre 1,610 y 3,020 filas; esperas ≈ 2,013 + las de agosto que maduraron

Qué decides con esto. Un volumen fuera de rango casi nunca es «el negocio creció»: es un join que duplicó, un corte en la zona horaria equivocada o un filtro que se comió medio mes. El pipeline se detiene antes de gastar GPU.

Lo confirmas en el paso 4: 2,467 filas = 1.23 × las 2,013 del padre.

5Publicar sin pisarEl snapshot en s3://ml-datos/datasets/ds-2026-09-01/, escrito una sola vez, con la tarjeta al final.

Tres defensas. Cada PUT lleva IfNoneMatch="*": si la llave existe, S3 responde 412 y no toca nada. Si ya está con el mismo contenido, el paso sigue: correrlo dos veces deja lo mismo (idempotente). La tarjeta va al final: un snapshot sin tarjeta no existe. Y el bucket guarda versiones, así que cualquier reescritura deja rastro. Antes de publicar, tu código va en un commit: la tarjeta guarda ese commit.

Pythonpipeline/5_publicar.py
"""Paso 5 · Publicar el snapshot: inmutable, con la tarjeta al final.

Entra:  data/rows.parquet, data/validation.json   de los pasos 3 y 4
        params.yaml                                snapshot.id, snapshot.padre, snapshot.corte, split.umbral
Sale:   s3://ml-datos/datasets/<id>/rows.parquet, validation.json y, al final, snapshot.json (la tarjeta)
        data/publicado.json                        el recibo: id, rows_sha256 y la version_id de cada llave
Reglas: solo publica si la validación pasó y tu código está en un commit (la tarjeta guarda ese commit).
        Toda escritura lleva If-None-Match: * (no pisa nada). Si la llave ya existe con el mismo contenido, sigue
        (correrlo dos veces deja lo mismo); si existe con otro contenido, se detiene: un contenido nuevo lleva un id nuevo.
"""
import json
import re
import subprocess
import sys
from datetime import datetime, timezone

import pandas as pd
from botocore.exceptions import ClientError
from _comun import DATA, DATOS, RAIZ, params, s3, sha256

p = params()
sid = p["snapshot"]["id"]
if not re.fullmatch(r"ds-\d{4}-\d{2}-\d{2}(-r\d+)?", sid):
    sys.exit(f"✗ «{sid}» no es un id de snapshot (ds-AAAA-MM-DD, o ds-AAAA-MM-DD-rN si se reemite)")
val = json.loads((DATA / "validation.json").read_text())
if val["status"] != "passed" or val["snapshot_id"] != sid:
    sys.exit("✗ la validación no pasó (o es de otro id): no se publica nada")
git = lambda *a: subprocess.run(["git", *a], cwd=RAIZ, capture_output=True, text=True).stdout.strip()  # noqa: E731
commit = git("rev-parse", "HEAD")
if not commit or git("status", "--porcelain", "--", "pipeline", "dvc.yaml"):
    sys.exit("✗ tu código tiene cambios sin commit: la tarjeta no podría decir con qué código se armó. git commit primero")

rows_b = (DATA / "rows.parquet").read_bytes()
huella = sha256(rows_b)
rows = pd.read_parquet(DATA / "rows.parquet")
cliente, base = s3(), f"datasets/{sid}"


def poner(nombre: str, cuerpo: bytes) -> str:
    """PUT condicional: escribe solo si la llave no existe. Devuelve la version_id de lo que quedó."""
    key = f"{base}/{nombre}"
    try:
        return cliente.put_object(Bucket=DATOS, Key=key, Body=cuerpo, IfNoneMatch="*")["VersionId"]
    except ClientError as e:
        if e.response["Error"]["Code"] != "PreconditionFailed":
            raise
    ya = cliente.get_object(Bucket=DATOS, Key=key)
    if sha256(ya["Body"].read()) != sha256(cuerpo):
        sys.exit(f"✗ {key} ya existe con otro contenido (412 Precondition Failed). Un snapshot publicado no se reescribe: "
                 "si el contenido cambió, usa un id nuevo en params.yaml")
    print(f"  {nombre}: ya estaba, mismo contenido")
    return ya["VersionId"]


versiones = {"rows.parquet": poner("rows.parquet", rows_b),
             "validation.json": poner("validation.json", (DATA / "validation.json").read_bytes())}
tarjeta = {
    "snapshot_id": sid, "parent": p["snapshot"]["padre"], "corte": p["snapshot"]["corte"],
    "created_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
    "rows_path": f"s3://{DATOS}/{base}/rows.parquet", "rows_sha256": huella,
    "counts": {"train": int((rows["split"] == "train").sum()), "val": int((rows["split"] == "val").sum()), "total": len(rows)},
    "label_sources": {k: round(float(x), 3) for k, x in rows["label_source"].value_counts(normalize=True).sort_index().items()},
    "split": {"by": "seller_id", "rule": f"sha256(seller_id) mod 100 < {p['split']['umbral']} -> train"},
    "code": {"repo": "c01-versionado", "commit": commit},
    "validation": {"status": val["status"], "report": f"s3://{DATOS}/{base}/validation.json"},
}
try:   # la tarjeta va al final: un snapshot sin tarjeta no existe
    versiones["snapshot.json"] = cliente.put_object(Bucket=DATOS, Key=f"{base}/snapshot.json", IfNoneMatch="*",
                                                    Body=json.dumps(tarjeta, ensure_ascii=False, indent=2).encode())["VersionId"]
except ClientError as e:
    if e.response["Error"]["Code"] != "PreconditionFailed":
        raise
    ya = json.loads(cliente.get_object(Bucket=DATOS, Key=f"{base}/snapshot.json")["Body"].read())
    if ya["rows_sha256"] != huella:
        sys.exit(f"✗ {base}/snapshot.json ya existe y describe otras filas: usa un id nuevo")
    tarjeta = ya
    versiones["snapshot.json"] = cliente.head_object(Bucket=DATOS, Key=f"{base}/snapshot.json")["VersionId"]
    print("  snapshot.json: ya estaba, describe las mismas filas")
(DATA / "publicado.json").write_text(json.dumps({"snapshot_id": sid, "rows_sha256": huella, "versiones": versiones}, indent=2) + "\n")
print(f"publicado s3://{DATOS}/{base}/ · rows_sha256 {huella[:12]}… · {tarjeta['counts']} · commit {tarjeta['code']['commit'][:7]}")
Terminal
python pipeline/5_publicar.py

Primero sin commit: se niega.

Salida
✗ tu código tiene cambios sin commit: la tarjeta no podría decir con qué código se armó. git commit primero
[código 1]
Terminal
git add -A && git commit -m "pipeline: pasos 1 a 5"
python pipeline/5_publicar.py
Salida
publicado s3://ml-datos/datasets/ds-2026-09-01/ · rows_sha256 a023a080132a… · {'train': 2309, 'val': 158, 'total': 2467} · commit 1782106
Terminal
python pipeline/5_publicar.py

Otra vez: mismo contenido, nada cambia.

Salida
  rows.parquet: ya estaba, mismo contenido
  validation.json: ya estaba, mismo contenido
  snapshot.json: ya estaba, describe las mismas filas
publicado s3://ml-datos/datasets/ds-2026-09-01/ · rows_sha256 a023a080132a… · {'train': 2309, 'val': 158, 'total': 2467} · commit 1782106
Terminal
python -c "
import sys; sys.path.insert(0, 'pipeline')
from _comun import s3
try:
    s3().put_object(Bucket='ml-datos', Key='datasets/ds-2026-09-01/rows.parquet', Body=b'otra cosa', IfNoneMatch='*')
except Exception as e:
    print(type(e).__name__, '·', e)"

Lo que pasa si alguien intenta pisarlo con otro contenido.

Salida
ClientError · An error occurred (PreconditionFailed) when calling the PutObject operation: At least one of the pre-conditions you specified did not hold
Terminal
python mundo/s3.py versiones ml-datos datasets/ds-2026-09-01/

Una versión por llave: nadie lo reescribió.

Salida
datasets/ds-2026-09-01/rows.parquet
    2026-11-16 01:39:51 UTC  vigente     241680 B  sha256 a023a080132a…  version 201a0b4b-7153-4886-a6e5-69e800581691
datasets/ds-2026-09-01/snapshot.json
    2026-11-16 01:39:51 UTC  vigente        778 B  sha256 bb923cb10179…  version 0307e2fc-bf1a-47c0-b1fd-cb93dec18205
datasets/ds-2026-09-01/validation.json
    2026-11-16 01:39:51 UTC  vigente        292 B  sha256 493b19c2da1f…  version a1e0544f-10f6-43d2-8539-46dd467f1c7f
Terminal
python -c "import sys; sys.path.insert(0, 'pipeline'); from _comun import s3; print(s3().get_object(Bucket='ml-datos', Key='datasets/ds-2026-09-01/snapshot.json')['Body'].read().decode())"

La tarjeta: el commit y la hora cambian en tu máquina.

Salida
{
  "snapshot_id": "ds-2026-09-01",
  "parent": "ds-2026-08-01",
  "corte": "2026-10-01T00:00:00Z",
  "created_at": "2026-11-16T01:39:51+00:00",
  "rows_path": "s3://ml-datos/datasets/ds-2026-09-01/rows.parquet",
  "rows_sha256": "a023a080132a6c59104e91ff1f946043d1461b30f5a55b8b04cf330dd5c0e2ac",
  "counts": {
    "train": 2309,
    "val": 158,
    "total": 2467
  },
  "label_sources": {
    "humano": 0.175,
    "moderador": 0.069,
    "vendedor": 0.756
  },
  "split": {
    "by": "seller_id",
    "rule": "sha256(seller_id) mod 100 < 90 -> train"
  },
  "code": {
    "repo": "c01-versionado",
    "commit": "1782106f906bed93c53e10b3af26b862a2614091"
  },
  "validation": {
    "status": "passed",
    "report": "s3://ml-datos/datasets/ds-2026-09-01/validation.json"
  }
}
Terminal
python verificar.py snapshot inmutable
Salida
✓ snapshot       ds-2026-09-01: 2467 filas (2309 train · 158 val) · rows_sha256 a023a080132a… · parent ds-2026-08-01 · commit 1782106
✓ inmutable      versionado Enabled · 2 snapshots (ds-2026-08-01, ds-2026-09-01): cada llave escrita una sola vez y cada uno igual a su tarjeta

2/2 en verde
Listo cuando: La tarjeta, el manifest y el reporte en S3, una versión por llave, y rows_sha256 igual al de tu data/rows.parquet.
Ojo: La tarjeta es lo último que se escribe y lo primero que se lee. Compárala con la de agosto (el mismo comando con ds-2026-08-01): mismo formato, otro parent, otro corte y otro commit. Y en la consola web (http://localhost:9301) puedes ver las versiones de cada llave.
Conceptos de este paso
Escribir, auditar, publicarwrite-audit-publishEl snapshot se arma aparte, se audita con el contrato y solo si pasa se publica, con la tarjeta al final.Analogía, por qué importa y la trampa

AnalogíaImprimir el periódico de prueba, revisarlo y solo entonces mandarlo a todos los puestos.

Por qué importaUn job que se cae a medias no deja un snapshot «a medias» que alguien pueda usar: sin tarjeta no existe. En el dojo, «aparte» es data/ en tu Mac; en C01, un prefijo staging/.

TrampaPublicar la tarjeta primero (o en medio) abre la puerta a entrenar con algo que nadie revisó.

Escritura condicionalconditional write (If-None-Match: *)Un PUT que solo se cumple si la llave no existe. Si ya existe, S3 responde 412 Precondition Failed y no toca nada.Analogía, por qué importa y la trampa

AnalogíaUn buzón con candado: puedes dejar una carta nueva, pero no cambiar la que ya está adentro.

Por qué importaSin ella, un PUT a una llave que existe reemplaza el objeto en silencio: gana el último. Con ella, reescribir un snapshot es un error ruidoso.

TrampaEl header lo pone quien escribe: un script que no lo pone escribe igual. En AWS se vuelve obligatorio con la política del bucket; RustFS no tiene esa condición, así que aquí depende de tu código. Y con versiones solo mira la versión vigente: si es una marca de borrado, el PUT pasa.

Versionado del bucketS3 Versioning y delete markersCon el versionado prendido, un PUT a una llave existente guarda una versión nueva sin destruir la vieja, y un DELETE solo pone una marca de borrado encima.Analogía, por qué importa y la trampa

AnalogíaUn documento con historial de cambios: puedes volver a cualquier versión, y borrar es tachar, no quemar.

Por qué importaEs la red de seguridad: lo que se pisó o se borró por error se recupera borrando la versión mala o la marca. Y deja rastro de cada reescritura.

TrampaProtege versiones, no llaves: el PUT nuevo pasa y es lo que se lee. Y para un borrado por ley hay que borrar cada versión, no solo poner la marca.

Tarjeta del snapshotdataset cardUn JSON chico junto al manifest (snapshot.json): id, padre, corte, conteos, mezcla de fuentes, regla del split, commit del código, rows_sha256 y resultado de la validación.Analogía, por qué importa y la trampa

AnalogíaLa etiqueta de un frasco de laboratorio: qué hay, de qué lote salió, quién lo preparó y cuándo.

Por qué importaEl manifest dice qué hay; la tarjeta, de dónde salió y cómo comprobarlo. Se escribe al final: un snapshot sin tarjeta no existe.

TrampaEl commit de la tarjeta es el del código que armó el snapshot, no el que entrena. Cada artefacto apunta a su propio código.

Precálculo
2

¿Cuánto cuesta guardar un año de snapshots citando, contra copiar las fotos cada mes?

citar = snapshots × manifest comprimido × precio; copiar = snapshots × fotos × precio
Ver la cuenta
En C0112 × 97 MB = 1.16 GB × US$0.023 por GB al mes, contra 12 × 387 GB × 0.023 (S3 Standard, us-east-1)≈ US$0.03 al mes contra ≈ US$107 al mes, y copiar crece cada mes
En el dojo12 × 242 kB ≈ 2.9 MB, contra 12 × 6.1 MB ≈ 73 MBen tu Mac cuesta cero, pero la proporción es la misma idea

Qué decides con esto. Un snapshot por mes, para siempre, cabe en el presupuesto. Lo caro es copiar. El precio escondido: si el producto borra una foto, la fila apunta a nada; por eso se comprueba al leer y se anota cada borrado.

Lo confirmas en el paso 5: mundo/s3.py versiones muestra rows.parquet de 241,680 B.

6El pipeline como DAGLos pasos 1 a 5 en dvc.yaml: dvc repro corre solo lo que cambió.

Cada stage dice qué corre, qué lee (deps), qué parámetros de params.yaml usa (params) y qué deja (outs). DVC hashea todo eso y lo guarda en dvc.lock; la próxima vez solo corre un stage si algo de su llave cambió. Es la caché de pasos de un orquestador, en tu Mac. Por eso cada parámetro que lee un script va declarado en su stage, y el snapshot se pide por id.

YAMLdvc.yaml
# El pipeline mensual como DAG: cada paso dice qué lee (deps), qué parámetros usa (params) y qué deja (outs).
# DVC hashea todo eso; si nada cambió, no vuelve a correr el paso. Por eso cada parámetro que lee un script va aquí.
stages:
  labels:
    cmd: python pipeline/1_labels.py
    deps: [pipeline/1_labels.py, pipeline/_comun.py, entrada/labels-eventos.parquet]
    params: [snapshot.corte, labels.dias_maduracion]
    outs: [data/labels.parquet]
  manifest:
    cmd: python pipeline/2_manifest.py
    deps: [pipeline/2_manifest.py, data/labels.parquet, entrada/publicaciones.parquet]
    outs: [data/manifest.parquet]
  split:
    cmd: python pipeline/3_split.py
    deps: [pipeline/3_split.py, data/manifest.parquet, entrada/borrados.csv, entrada/golden.parquet]
    params: [snapshot.corte, split.umbral]
    outs: [data/rows.parquet]
  validar:
    cmd: python pipeline/4_validar.py
    deps: [pipeline/4_validar.py, data/rows.parquet, entrada/categorias.json, entrada/golden.parquet]
    params: [snapshot.id, snapshot.padre, validar]
    outs: [data/validation.json]
  publicar:
    cmd: python pipeline/5_publicar.py
    deps: [pipeline/5_publicar.py, data/rows.parquet, data/validation.json]
    params: [snapshot.id, snapshot.padre, snapshot.corte, split.umbral]
    outs: [data/publicado.json]

Las fotos del bucket no son una dependencia de DVC: si una cambia bajo la misma llave, DVC no se entera. Por eso el entrenamiento comprueba cada huella (paso 7).

Terminal
git add -A && git commit -m "el pipeline como DAG"
dvc repro

La primera vez no hay dvc.lock: corre todo. Publicar es idempotente, así que no pasa nada en S3.

Salida
Running stage 'labels':
> python pipeline/1_labels.py
eventos: 3908 · antes del corte 2026-10-01 00:00 UTC: 3796 · después (se ignoran): 112
fotos con label vigente: 3120 · sin madurar (quien vende, < 30 días): 507
data/labels.parquet: 2613 labels · {'vendedor': 1966, 'humano': 465, 'moderador': 182}
Running stage 'manifest':
> python pipeline/2_manifest.py
data/manifest.parquet: 2613 filas · 2499 huellas distintas · 300 vendedores
fotos citadas: 6.1 MB · manifest: 246 kB
Running stage 'split':
> python pipeline/3_split.py
manifest: 2613 · borradas antes del corte: 13 · duplicadas por huella: 114 · del golden set: 19
data/rows.parquet: 2467 filas · {'train': 2309, 'val': 158} · vendedores en val: 17
Running stage 'validar':
> python pipeline/4_validar.py
passed: 2467 filas = 1.23 × las 2013 del padre · quien vende 75.6% · 298 vendedores en los dos, 0 movidos
Running stage 'publicar':
> python pipeline/5_publicar.py
  rows.parquet: ya estaba, mismo contenido
  validation.json: ya estaba, mismo contenido
  snapshot.json: ya estaba, describe las mismas filas
publicado s3://ml-datos/datasets/ds-2026-09-01/ · rows_sha256 a023a080132a… · {'train': 2309, 'val': 158, 'total': 2467} · commit 1782106
Terminal
dvc repro

La segunda: nada cambió, nada corre.

Salida
Stage 'labels' didn't change, skipping
Stage 'manifest' didn't change, skipping
Stage 'split' didn't change, skipping
Stage 'validar' didn't change, skipping
Stage 'publicar' didn't change, skipping
Data and pipelines are up to date.
Terminal
dvc dag
Salida
          +--------+       
          | labels |       
          +--------+       
                *          
                *          
                *          
          +----------+     
          | manifest |     
          +----------+     
                *          
                *          
                *          
           +-------+       
           | split |       
           +-------+       
          **        **     
        **            **   
       *                ** 
+---------+               *
| validar |             ** 
+---------+           **   
          **        **     
            **    **       
              *  *         
          +----------+     
          | publicar |     
          +----------+
Terminal
sed -n '1,22p' dvc.lock

Las huellas (md5) de cada entrada y los valores de los parámetros que usó cada stage: también es linaje.

Salida
schema: '2.0'
stages:
  labels:
    cmd: python pipeline/1_labels.py
    deps:
    - path: entrada/labels-eventos.parquet
      hash: md5
      md5: 4c1113345bcbc6605a6ad798b825746b
      size: 86774
    - path: pipeline/1_labels.py
      hash: md5
      md5: 7fbfb3ba98e94ce2e5e290eca34c0fa8
      size: 1754
    - path: pipeline/_comun.py
      hash: md5
      md5: 67ccbd71e969c5c0a66cb3199c09b514
      size: 2410
    params:
      params.yaml:
        labels.dias_maduracion: 30
        snapshot.corte: '2026-10-01T00:00:00Z'
    outs:
Terminal
git add dvc.lock && git commit -m "ds-2026-09-01"
python verificar.py dag
Salida
✓ dag            5 stages, con sus params declarados · dvc status: al día

1/1 en verde
Listo cuando: 5 stages con sus parámetros declarados y dvc status al día.
Ojo: Si un script lee split.umbral pero el stage no lo declara, cambiarlo no hace correr nada y DVC te da la salida vieja sin avisar. Es la trampa de latest en otra forma: la llave de la caché no ve lo que cambió.
Conceptos de este paso
DAG y caché de pasospipeline DAG y step cacheEl pipeline como pasos con flechas (qué lee y qué deja cada uno). La herramienta guarda la salida de cada paso con una llave hecha de su código, sus parámetros y sus entradas, y la reusa si la llave no cambió.Analogía, por qué importa y la trampa

AnalogíaUna receta con pasos: si ya picaste la cebolla y nadie cambió la cebolla, no la vuelves a picar.

Por qué importaAhorra horas y hace que repetir el pipeline sea seguro. dvc.lock guarda las huellas de cada entrada y salida: también es linaje.

TrampaLo que no está en la llave no existe para la caché: un parámetro que el script lee pero el stage no declara no hace correr el paso, y sale la salida vieja.

Paso idempotenteidempotent stepCorrerlo dos veces deja lo mismo que correrlo una.Analogía, por qué importa y la trampa

AnalogíaEl botón del elevador: picarle cinco veces no llama cinco elevadores.

Por qué importaEl orquestador reintenta pasos que fallan a la mitad. Publicar otra vez el mismo contenido sigue sin error; otro contenido con el mismo id se detiene.

TrampaIdempotente no es «sobrescribe sin preguntar»: eso borra la historia. Es «si ya está igual, no hago nada».

7Entrenar con linajeUna corrida que entrena con ds-2026-09-01, comprueba cada huella al leer y deja sus punteros.

La estación 3 entrena de verdad; aquí importa la entrada y lo que queda anotado. El snapshot llega por id. Se lee la tarjeta primero (sin tarjeta no hay snapshot), se comprueba rows_sha256 y la huella de cada foto. Las fotos del registro de borrados se saltan. La corrida guarda los punteros: snapshot y su huella, commit (con el árbol limpio), huella del entorno y semilla.

Pythonpipeline/6_entrenar.py
"""Paso 6 · Entrenar con un snapshot, comprobando todo al leer, y dejar los punteros del linaje.

Entra:  params.yaml                       entrenar.snapshot (un id, nunca «latest») y entrenar.semilla
        s3://ml-datos/datasets/<id>/      la tarjeta y las filas
        s3://fotos/…                      cada foto, por su llave
        entrada/borrados.csv              las fotos que se borraron: se saltan, con cualquier fecha
Sale:   corridas/run-AAAAMMDD-HHMMSS.json  run_id, modelo, fecha, snapshot, rows_sha256, commit, arbol_limpio,
        entorno_sha256, semilla, metricas y filas {train, val, omitidas_borradas}
Reglas: sin tarjeta no hay snapshot; si la huella de las filas o de una foto no coincide, se detiene.
        Solo entrena desde un commit con el árbol limpio (pipeline/, dvc.yaml, dvc.lock, params.yaml).
"""
import io
import json
import re
import subprocess
import sys
from concurrent.futures import ThreadPoolExecutor
from datetime import datetime, timezone

import pandas as pd
from botocore.exceptions import ClientError
from _comun import CORRIDAS, DATOS, ENTRADA, FOTOS, RAIZ, entrenar, huella_entorno, params, s3, sha256

p = params()["entrenar"]
sid = str(p["snapshot"])
if not re.fullmatch(r"ds-\d{4}-\d{2}-\d{2}(-r\d+)?", sid):
    sys.exit(f"✗ entrenar.snapshot = «{sid}»: tiene que ser un id de snapshot. Una carpeta como «latest» cambia de "
             "contenido y la corrida no podría decir con qué datos entrenó")
git = lambda *a: subprocess.run(["git", *a], cwd=RAIZ, capture_output=True, text=True).stdout.strip()  # noqa: E731
commit = git("rev-parse", "HEAD")
sucio = git("status", "--porcelain", "--", "pipeline", "dvc.yaml", "dvc.lock", "params.yaml")
if not commit or sucio:
    sys.exit(f"✗ hay cambios sin commit ({sucio.splitlines()[0] if sucio else 'no hay commits'}): el commit no diría qué código corrió")

cliente = s3()
try:
    tarjeta = json.loads(cliente.get_object(Bucket=DATOS, Key=f"datasets/{sid}/snapshot.json")["Body"].read())
except ClientError:
    sys.exit(f"✗ {sid} no tiene tarjeta (snapshot.json): un snapshot sin tarjeta no existe")
crudo = cliente.get_object(Bucket=DATOS, Key=f"datasets/{sid}/rows.parquet")["Body"].read()
if sha256(crudo) != tarjeta["rows_sha256"]:
    sys.exit(f"✗ las filas de {sid} no coinciden con su tarjeta: alguien las reescribió")
filas = pd.read_parquet(io.BytesIO(crudo))
borrados = set(pd.read_csv(ENTRADA / "borrados.csv")["image_sha256"])
omitidas = filas["image_sha256"].isin(borrados)
leer = filas[~omitidas]


def foto(fila):
    try:
        b = cliente.get_object(Bucket=FOTOS, Key=fila.image_key)["Body"].read()
    except ClientError:
        return fila.image_key, None, "no existe"
    return fila.image_key, b, None if sha256(b) == fila.image_sha256 else "su huella no coincide"


with ThreadPoolExecutor(16) as ex:
    fotos = list(ex.map(foto, leer.itertuples()))
malas = [(k, err) for k, _, err in fotos if err]
if malas:
    sys.exit(f"✗ {len(malas)} fotos no se pueden usar, por ejemplo {malas[0][0]}: {malas[0][1]}. "
             "Si alguien pidió borrarlas, anótalas en entrada/borrados.csv")
bytes_de = {k: b for k, b, _ in fotos}
tr = [(bytes_de[f.image_key], int(f.label_id)) for f in leer.itertuples() if f.split == "train"]
va = [(bytes_de[f.image_key], int(f.label_id)) for f in leer.itertuples() if f.split == "val"]
metricas = entrenar(tr, va, p["semilla"])

ahora = datetime.now(timezone.utc)
corrida = {"run_id": f"run-{ahora:%Y%m%d-%H%M%S}", "modelo": f"modelo-{ahora:%Y-%m-%d}", "fecha": ahora.isoformat(timespec="seconds"),
           "snapshot": sid, "rows_sha256": tarjeta["rows_sha256"], "commit": commit, "repo": "c01-versionado", "arbol_limpio": True,
           "entorno_sha256": huella_entorno(), "semilla": p["semilla"], "metricas": metricas,
           "filas": {"train": len(tr), "val": len(va), "omitidas_borradas": int(omitidas.sum())}}
CORRIDAS.mkdir(exist_ok=True)
(CORRIDAS / f"{corrida['run_id']}.json").write_text(json.dumps(corrida, ensure_ascii=False, indent=2) + "\n")
print(f"{len(leer)} fotos leídas y comprobadas · {int(omitidas.sum())} omitidas por borrado")
print(f"corridas/{corrida['run_id']}.json: {corrida['modelo']} ← {sid} ({tarjeta['rows_sha256'][:12]}…) · commit {commit[:7]} · "
      f"entorno {corrida['entorno_sha256'][:12]}… · accuracy_val {metricas['accuracy_val']}")
Terminal
python pipeline/6_entrenar.py

Con el script recién escrito y sin commit: se niega.

Salida
✗ hay cambios sin commit (M pipeline/6_entrenar.py): el commit no diría qué código corrió
[código 1]
Terminal
git add -A && git commit -m "entrenar con linaje"
python pipeline/6_entrenar.py
Salida
2467 fotos leídas y comprobadas · 0 omitidas por borrado
corridas/run-20261116-013958.json: modelo-2026-11-16 ← ds-2026-09-01 (a023a080132a…) · commit 6ac383f · entorno b25ca3c501e2… · accuracy_val 0.7468
Terminal
cat $(ls -t corridas/*.json | head -1)
Salida
{
  "run_id": "run-20261116-013958",
  "modelo": "modelo-2026-11-16",
  "fecha": "2026-11-16T01:39:58+00:00",
  "snapshot": "ds-2026-09-01",
  "rows_sha256": "a023a080132a6c59104e91ff1f946043d1461b30f5a55b8b04cf330dd5c0e2ac",
  "commit": "6ac383feccc07abc4f287b1f33ff397073fc7156",
  "repo": "c01-versionado",
  "arbol_limpio": true,
  "entorno_sha256": "b25ca3c501e27bfeb8126cf460e96dc25a45345eec438bdade9168a76769c201",
  "semilla": 17,
  "metricas": {
    "accuracy_val": 0.7468,
    "n_train": 2309,
    "n_val": 158
  },
  "filas": {
    "train": 2309,
    "val": 158,
    "omitidas_borradas": 0
  }
}
Terminal
python verificar.py corrida lectura
Salida
✓ corrida        run-20261116-013958 · modelo-2026-11-16 ← ds-2026-09-01 (a023a080132a…) · commit 6ac383f · entorno b25ca3c501e2… · accuracy_val 0.7468
✓ lectura        ds-2026-09-01: 2467 fotos existen y su huella coincide · 0 filas en el registro de borrados (se saltan)

2/2 en verde
Listo cuando: Tu corrida apunta a ds-2026-09-01 con su rows_sha256, un commit limpio y la huella del entorno; las 2,467 fotos se leen y coinciden.
Ojo: 0 omitidas: las fotos borradas en septiembre ya no están en este snapshot. Si entrenaras otra vez con ds-2026-08-01, se saltarían 13.
Conceptos de este paso
Id como parámetro, nunca «latest»pass the snapshot id, not a moving pathToda entrada que cambia el resultado llega como un id fijo (ds-2026-09-01), nunca como una carpeta que cambia de contenido sin cambiar de nombre.Analogía, por qué importa y la trampa

AnalogíaPedir «el libro con ISBN tal» en vez de «el libro de la repisa de arriba»: alguien puede cambiar el de la repisa.

Por qué importaLa corrida guarda un puntero que siempre dice lo mismo. Con latest, el registro no dice con qué entrenó y la caché ve la misma llave dos meses seguidos.

Trampa«Para no editar params.yaml cada mes» es la excusa típica. Cambiar el id cada mes es trabajo del orquestador, no de una carpeta mágica.

Commit con el árbol limpioclean working treeEntrenar (y publicar) solo desde un commit sin cambios pendientes en el código, para que el commit diga exactamente qué corrió.Analogía, por qué importa y la trampa

AnalogíaFirmar un contrato solo cuando ya no tiene tachones a mano.

Por qué importaEl commit es uno de los cinco ingredientes de la reproducibilidad (código, datos, configuración, entorno y semilla). Si el script tenía cambios sin commit, el puntero apunta a otro código.

Trampadvc repro cambia dvc.lock: hay que hacer commit después de cada repro, antes de entrenar.

LinajelineageLa cadena de qué salió de qué: modelo ← corrida ← snapshot (id + rows_sha256) ← cada foto (llave + huella), más el commit y el entorno. Se guarda como punteros, no como copias.Analogía, por qué importa y la trampa

AnalogíaEl árbol genealógico con acta de nacimiento en cada rama.

Por qué importaResponde en un minuto las tres preguntas: con qué datos se entrenó, si cambió el código o los datos, y en qué modelos está la foto que pidieron borrar.

TrampaUn puntero que se escribe a mano o «después» se desfasa. Lo escribe el mismo programa que entrena, en el momento.

Precálculo
3

¿Cuánto tarda comprobar la huella de cada foto al leerla?

tiempo = bytes de fotos ÷ velocidad de sha256 en un núcleo
Ver la cuenta
En C01387 GB ÷ ≈ 2.9 GB/s (lo que mide tu Mac) = ≈ 133 s de CPU en un núcleo≈ 2 minutos, contra las 3–4 horas de GPU del fine-tune
En el dojo6.1 MB ÷ 2.9 GB/s≈ 2 ms: lo que tarda es leer del S3, no hashear

Qué decides con esto. Comprobar cada foto al leer es casi gratis frente al entrenamiento. No hay excusa para no hacerlo: si una foto cambió bajo la misma llave, el entrenamiento se detiene en vez de aprender otra cosa.

Terminalterminal · compruébalo en el kit
python -c "import hashlib, time; b = bytes(512 * 2**20); t = time.perf_counter(); hashlib.sha256(b).hexdigest(); s = time.perf_counter() - t; print(f'sha256 de 512 MiB en {s:.2f} s: {512 / 1024 / s:.1f} GiB/s en un núcleo')"

En una M4. 2.7 GiB/s son ≈ 2.9 GB/s. Tu número puede variar.

Salida
sha256 de 512 MiB en 0.19 s: 2.7 GiB/s en un núcleo
8El linaje al revésDe una huella a los snapshots, las corridas y el borrado.

La pregunta de privacidad: alguien pide borrar sus fotos, ¿en qué snapshots y en qué modelos están? Con los punteros es mecánico: buscas la huella en los manifests (comprobados con su tarjeta) y sigues las corridas que usaron esos snapshots.

Pythonpipeline/7_linaje.py
"""Paso 7 · El linaje al revés: ¿en qué snapshots y en qué modelos está esta foto?

    python pipeline/7_linaje.py <sha256>            # la huella completa o sus primeros 12+ caracteres
    python pipeline/7_linaje.py <sha256> --json     # lo mismo, en JSON (lo usa verificar.py)

Entra:  s3://ml-datos/datasets/*/        cada snapshot con tarjeta (sus filas, comprobadas con su huella)
        corridas/*.json                  cada corrida y el snapshot con que entrenó
        entrada/borrados.csv             si alguien pidió borrarla
Sale:   {"sha256", "snapshots": [{"id", "split", "image_keys"}], "corridas": [{"run_id", "modelo", "snapshot"}],
         "borrado": {"fecha", "motivo"} o null}
"""
import io
import json
import sys

import pandas as pd
from _comun import CORRIDAS, DATOS, ENTRADA, s3, sha256

args = [a for a in sys.argv[1:] if not a.startswith("--")]
if not args or len(args[0]) < 12:
    sys.exit("uso: python pipeline/7_linaje.py <sha256 (12+ caracteres)> [--json]")
buscada = args[0].lower()
cliente = s3()
r = cliente.list_objects_v2(Bucket=DATOS, Prefix="datasets/", Delimiter="/")
snaps = []
for sid in sorted(x["Prefix"].split("/")[1] for x in r.get("CommonPrefixes", [])):
    try:
        tarjeta = json.loads(cliente.get_object(Bucket=DATOS, Key=f"datasets/{sid}/snapshot.json")["Body"].read())
    except cliente.exceptions.NoSuchKey:
        continue                                                   # sin tarjeta no es un snapshot
    crudo = cliente.get_object(Bucket=DATOS, Key=f"datasets/{sid}/rows.parquet")["Body"].read()
    if sha256(crudo) != tarjeta["rows_sha256"]:
        sys.exit(f"✗ las filas de {sid} no coinciden con su tarjeta: el linaje no es confiable")
    f = pd.read_parquet(io.BytesIO(crudo), columns=["image_key", "image_sha256", "split"])
    hay = f[f["image_sha256"].str.startswith(buscada)]
    if len(hay):
        snaps.append({"id": sid, "split": hay["split"].iloc[0], "image_keys": sorted(hay["image_key"])})
ids = {s["id"] for s in snaps}
corridas = sorted((json.loads(c.read_text()) for c in CORRIDAS.glob("*.json")), key=lambda c: c["fecha"])
usan = [{"run_id": c["run_id"], "modelo": c["modelo"], "snapshot": c["snapshot"]} for c in corridas if c["snapshot"] in ids]
b = pd.read_csv(ENTRADA / "borrados.csv")
b = b[b["image_sha256"].str.startswith(buscada)]
borrado = {"fecha": b["fecha"].iloc[0], "motivo": b["motivo"].iloc[0]} if len(b) else None
out = {"sha256": buscada, "snapshots": snaps, "corridas": usan, "borrado": borrado}
if "--json" in sys.argv:
    print(json.dumps(out, ensure_ascii=False, indent=2))
else:
    print(f"foto {buscada[:12]}…")
    for s in snaps:
        print(f"  snapshot {s['id']} · {s['split']} · {', '.join(s['image_keys'])}")
    for c in usan:
        print(f"  corrida {c['run_id']} · {c['modelo']} ← {c['snapshot']}")
    print(f"  borrada el {borrado['fecha']}: {borrado['motivo']}" if borrado else "  no está en el registro de borrados")
    if not snaps:
        print("  no aparece en ningún snapshot")
Terminal
python pipeline/7_linaje.py $(sed -n 2p entrada/borrados.csv | cut -d, -f1)

Una foto de la vendedora que pidió borrar: está en el snapshot de agosto y en el modelo de septiembre; el de septiembre ya no la trae.

Salida
foto 299c10e75b6a…
  snapshot ds-2026-08-01 · train · 2026/04/14/p-000237.jpg
  corrida run-20260901-061500 · modelo-2026-09-01 ← ds-2026-08-01
  borrada el 2026-09-15T10:00:00Z: derecho al borrado (solicitud del 2026-09-14)
Terminal
python pipeline/7_linaje.py 000706ca7a412e4b

Una foto que está en los dos snapshots, y por lo tanto en los dos modelos.

Salida
foto 000706ca7a41…
  snapshot ds-2026-08-01 · train · 2026/05/03/p-000555.jpg
  snapshot ds-2026-09-01 · train · 2026/05/03/p-000555.jpg
  corrida run-20260901-061500 · modelo-2026-09-01 ← ds-2026-08-01
  corrida run-20261116-013958 · modelo-2026-11-16 ← ds-2026-09-01
  no está en el registro de borrados
Terminal
python verificar.py

Todo junto.

Salida
✓ mundo          S3 local con fotos (1000+) y ml-datos (ds-2026-08-01 publicado) · entrada/ completa · git y DVC 3.67.1
✓ labels         2613 labels vigentes al 2026-10-01T00:00:00Z · {'vendedor': 1966, 'humano': 465, 'moderador': 182}
✓ manifest       2613 filas, cada una con su llave y su huella · manifest 246 kB · cita 6.1 MB de fotos
✓ split          2467 filas: sin duplicados, sin golden, sin borrados · {'train': 2309, 'val': 158} por vendedor
✓ split-estable  298 vendedores en los dos snapshots, 0 cambiaron de lado · ninguna foto de val del padre en train
✓ validacion     passed: esquema, categorias, duplicados, golden, split_vendedor, split_estable, volumen, vendedor
✓ snapshot       ds-2026-09-01: 2467 filas (2309 train · 158 val) · rows_sha256 a023a080132a… · parent ds-2026-08-01 · commit 1782106
✓ inmutable      versionado Enabled · 2 snapshots (ds-2026-08-01, ds-2026-09-01): cada llave escrita una sola vez y cada uno igual a su tarjeta
✓ dag            5 stages, con sus params declarados · dvc status: al día
✓ corrida        run-20261116-013958 · modelo-2026-11-16 ← ds-2026-09-01 (a023a080132a…) · commit 6ac383f · entorno b25ca3c501e2… · accuracy_val 0.7468
✓ lectura        ds-2026-09-01: 2467 fotos existen y su huella coincide · 0 filas en el registro de borrados (se saltan)
✓ linaje         299c10e7… → 1 snapshots, 1 corridas, borrada · 000706ca… → 2 snapshots, 2 corridas

12/12 en verde
Listo cuando: verificar.py completo: 12/12 en verde.
Ojo: El modelo de septiembre aprendió con fotos que ya se borraron. Qué hacer con él (reentrenar antes, esperar al siguiente) se decide aparte; el linaje es lo que te deja contestar en un minuto.

Solo

12 objetivos

Antes de empezar, python mundo/reiniciar.py --pipeline: respalda tus archivos en .respaldo/, pone el esqueleto (pipeline/, dvc.yaml vacío, params.yaml de fábrica) y borra data/, tus corridas y los snapshots que publicaste. El de agosto se queda. Haz commit del esqueleto.

Solo tienes OBJETIVOS.md, los contratos al inicio de cada archivo y python verificar.py. Nada de GUION.md ni de mundo/comun.py.

Claude no te da código: te dice qué check falla y te contesta con preguntas.

Mide tu tiempo por objetivo y anota en la bitácora dónde te atoraste.

01El S3 local arriba, el mundo creado, la carpeta en git y DVC iniciado.python verificar.py mundo
02Los labels vigentes al corte, uno por foto, con la regla de 30 días.python verificar.py labelsPista: Primero filtra por hora, después ordena y quédate con el último.
03El manifest: una fila por label, con su llave y su huella.python verificar.py manifest
04Las filas del snapshot sin borrados (al corte), sin duplicados, sin golden y con el split por vendedor.python verificar.py splitPista: De las huellas repetidas, ¿cuál publicación no cambia de un mes a otro?
05Ningún vendedor cambia de lado contra el snapshot de agosto.python verificar.py split-estable
06El reporte del contrato de datos, con las 8 reglas en verde.python verificar.py validacion
07El snapshot publicado en S3 con su tarjeta, desde un commit, igual a tu data/rows.parquet.python verificar.py snapshot
08Cada llave de datasets/ escrita una sola vez, con versionado y escritura condicional.python verificar.py inmutablePista: ¿Qué header hace que S3 conteste 412?
09Los 5 pasos en dvc.yaml, con sus parámetros declarados, y dvc status al día.python verificar.py dag
10Una corrida con un id de snapshot, su huella, un commit limpio, la huella del entorno y la semilla.python verificar.py corrida
11Todas las fotos del snapshot de entrenamiento existen y coinciden, salvo las del registro de borrados.python verificar.py lectura
12De una huella a sus snapshots, sus corridas y su borrado, en JSON con --json.python verificar.py linaje

Romper

7 fallas

Con todo en verde, romper.py mete una falla en el mundo, la configuración o la infraestructura (nunca en lo que escribiste) y, si hace falta, deja corriendo lo que «pasó anoche». Tú empiezas por verificar.py.

Terminalromper.py
python romper.py --mostrar   # con ayuda: Claude sabe cuál es
python romper.py             # solo: escondida, ni Claude la sabe
python romper.py --verificar # ¿ya quedó?
python romper.py --revelar   # me rindo
python romper.py --restaurar # deshacer

Repaso

para el celular
Snapshot = manifest, no copia.Un id inmutable que cita cada foto por llave y huella, una tarjeta que se escribe al final, y tres punteros desde cada modelo (snapshot y su huella, commit y entorno). Con eso, «¿con qué se entrenó?» se contesta en un minuto, y un contenido nuevo siempre lleva un id nuevo. Trampa: Inmutable «por convención». Sin escritura condicional y sin versiones, alguien reescribe el prefijo y el modelo de marzo deja de ser reproducible sin que nada truene. Y el versionado protege versiones, no llaves: un PUT nuevo a la misma llave pasa y es lo que se lee. Por eso la tarjeta guarda la huella y el modelo la comprueba. Listo cuando
  • Los labels del snapshot son los vigentes al corte, en UTC, con la regla de 30 días.
  • Cada foto cuenta una vez, ninguna del golden set entra, y ningún vendedor cambió de lado contra el padre.
  • El contrato de datos pasó antes de publicar, y si no hubiera pasado, nada se publicaba.
  • ds-2026-09-01 está en S3 con manifest, reporte y tarjeta, cada llave escrita una sola vez y con versionado.
  • dvc repro corre solo lo que cambió, y dvc.lock está en un commit.
  • Tu corrida guarda el id del snapshot, su huella, un commit limpio, la huella del entorno y la semilla.
  • Desde una huella llegas a sus snapshots, a sus modelos y a su borrado.

Así te lo pueden preguntar en una entrevista

¿Cómo sabes con qué datos se entrenó el modelo que está en producción?

La corrida guarda el id del snapshot y su rows_sha256. Leo la tarjeta del snapshot, recalculo la huella del manifest y la comparo: si coincide, el manifest me dice cada foto (llave + huella) y su label. Si el parámetro de la corrida fuera una ruta como latest, no lo sabría: por eso el id va como parámetro.

¿Por qué un manifest en vez de copiar las fotos en cada versión?

Porque cita y no copia: en C01 un snapshot pesa ≈ 0.1 % de las fotos (≈ 97 MB contra ≈ 387 GB), así que guardar uno por mes cuesta centavos. El costo escondido es que depende de que las fotos sigan ahí: por eso cada fila lleva la huella, el entrenamiento la comprueba al leer y los borrados se anotan.

¿Cómo evitas que alguien reescriba un snapshot publicado?

Tres capas: escritura condicional (If-None-Match: *, obligatoria por la política del bucket), versionado del bucket para recuperar lo que se pisó o se borró, y la huella en la tarjeta y en cada modelo, que delata cualquier cambio. Object Lock protege versiones, no llaves, así que no basta solo.

Llegaron correcciones de labels de un mes que ya publicaste. ¿Qué haces?

No toco el snapshot publicado: la corrida que lo usó tiene que seguir siendo reproducible. Armo uno nuevo con otro id (aquí, ds-2026-09-01-r2), que pasa por el mismo contrato, y el siguiente entrenamiento apunta a él. Las correcciones son eventos nuevos, así que el corte decide qué entra.

¿Por qué el split va por hash del vendedor y no al azar?

Por dos razones. Por vendedor, para que el modelo no reconozca la mesa o el fondo de alguien que vio en train. Por hash, para que sea estable: el mismo vendedor cae del mismo lado cada mes, y comparar el modelo nuevo contra el viejo es justo. Sortear cada mes movería ≈ 87,796 fotos de validación a train en C01.

Alguien pide borrar sus fotos. ¿Cómo sabes en qué modelos están?

Busco sus huellas en los manifests de todos los snapshots y sigo las corridas que usaron esos snapshots. Las fotos se borran del bucket (todas sus versiones), sus huellas entran a un registro de borrados de solo agregar, el snapshot siguiente ya no las incluye y el entrenamiento las salta al leer. Qué pasa con el modelo actual se decide aparte.

Versión del contenido: 15 de noviembre de 2026.

Contexto opcional

para consultar
Dónde estás en el pipeline

La estación 1 deja los labels del mes. Esta los convierte en un snapshot inmutable: una lista con id (ds-2026-09-01) que cita cada foto por su llave y su huella sha256, con una tarjeta que dice de dónde salió. No copia fotos: las referencia, así que un snapshot nuevo pesa ≈ 0.1 % de las imágenes en C01. Cada modelo guarda tres punteros (el snapshot, el commit y el entorno) y con eso respondes «¿con qué datos?», «¿lo puedo reproducir?» y «¿en qué modelos está esta foto que pidieron borrar?». La estación 3 entrena con ese id.

Entra
  • los labels del mes como eventos (quien vende, moderación y etiquetado humano), con su hora en UTC
  • las publicaciones: cada foto con su llave y su sha256, quién la vende y cuándo
  • el golden set congelado y el registro de borrados
  • el snapshot anterior, ds-2026-08-01 (el padre)
Sale
  • el snapshot ds-2026-09-01 en S3: rows.parquet (el manifest), validation.json y la tarjeta snapshot.json, escritos una sola vez
  • el reporte de validación del contrato de datos
  • el pipeline como DAG (dvc.yaml + dvc.lock), en un commit
  • una corrida con sus tres punteros y la búsqueda de una foto hacia sus snapshots y modelos
El escenario del proyecto
Con kit · 4 rondas

El kit trae el marketplace de C01 seis meses después de la estación 1, a principios de octubre de 2026: 3,120 publicaciones de abril a septiembre con sus fotos en un S3 local, los labels como eventos, el golden set, un registro de borrados y el snapshot de agosto que publicó el equipo. Tú escribes el pipeline que arma el de septiembre y el entrenamiento que deja el linaje. Todo corre con un entorno virtual de Python y un contenedor.

El mundo vive en dos lugares: las fotos y los snapshots en el S3 local, y la entrada en entrada/. mundo/crear.py lo crea igual cada vez (semilla fija), incluido el snapshot de agosto que publicó el equipo: es el padre del tuyo. La carpeta tiene que ser un repositorio de git desde el inicio: el commit es uno de los punteros del linaje, y DVC guarda sus huellas junto al código.

Glosario: los 18 conceptos

Una línea para entenderlo; abre la tarjeta para la analogía, por qué importa y la trampa.

Snapshot inmutableimmutable dataset snapshotUna versión del dataset con id propio (ds-2026-09-01) que, una vez escrita, nadie cambia: ni se borra, ni se reemplaza, ni se le agregan filas.Analogía, por qué importa y la trampa

AnalogíaLa foto de grupo de fin de año: si alguien llega tarde, sale en la del año siguiente; no se retoca la de este año.

Por qué importaEs lo que hace que «el modelo de octubre se entrenó con ds-2026-09-01» sea verdad para siempre. Si el contenido cambia, es otro snapshot con otro id.

TrampaInmutable «por acuerdo» no sirve: un script que corre dos veces o alguien que «arregla» una fila lo rompe sin dar error. Tiene que ser por diseño.

ManifestmanifestUn archivo (aquí, Parquet) con una fila por foto: su llave, su huella, quién la vende, su label, de dónde salió el label y su split.Analogía, por qué importa y la trampa

AnalogíaLa lista de invitados con foto de cada uno, en vez de meter a los invitados en la caja.

Por qué importaCita las fotos en vez de copiarlas: un snapshot pesa ≈ 0.1 % de las imágenes en C01 y se puede guardar uno por mes para siempre.

TrampaSi una foto se borra o cambia bajo la misma llave, la fila apunta a otra cosa. Por eso lleva la huella, y por eso se comprueba al leer.

Huella sha256content hash (SHA-256)64 caracteres hexadecimales que salen de los bytes de un archivo: el mismo contenido da siempre la misma huella; un byte distinto, otra.Analogía, por qué importa y la trampa

AnalogíaUna huella digital: no dice cómo es la persona, pero dice si es la misma.

Por qué importaHay dos: image_sha256 (cada foto) y rows_sha256 (el manifest entero, en la tarjeta). La segunda la guarda cada modelo: si alguien cambia una sola etiqueta, se nota.

TrampaLa huella no impide nada: delata. Y depende de los bytes: el mismo contenido escrito en otro orden da otra huella, por eso las filas se ordenan antes de escribir.

Tarjeta del snapshotdataset cardUn JSON chico junto al manifest (snapshot.json): id, padre, corte, conteos, mezcla de fuentes, regla del split, commit del código, rows_sha256 y resultado de la validación.Analogía, por qué importa y la trampa

AnalogíaLa etiqueta de un frasco de laboratorio: qué hay, de qué lote salió, quién lo preparó y cuándo.

Por qué importaEl manifest dice qué hay; la tarjeta, de dónde salió y cómo comprobarlo. Se escribe al final: un snapshot sin tarjeta no existe.

TrampaEl commit de la tarjeta es el del código que armó el snapshot, no el que entrena. Cada artefacto apunta a su propio código.

Labels como eventosappend-only label eventsCada label es una fila nueva que nunca se edita, con su fuente, su guía y su hora. Corregir es agregar otro evento más nuevo.Analogía, por qué importa y la trampa

AnalogíaEl historial de un expediente médico: el diagnóstico nuevo no borra el viejo, se escribe abajo con fecha.

Por qué importaCon eso, un snapshot es una consulta: «para cada foto, el label más reciente que ya existía a tal hora». Nada se pierde y se puede explicar por qué el modelo de agosto aprendió lo que aprendió.

TrampaSi la tabla guarda una fila por foto y la corrección la reescribe, ya no sabes qué label había el día del corte.

Corte (point-in-time)point-in-time cutoffLa hora, en UTC, hasta la que cuenta lo que existe: un snapshot solo ve eventos de antes del corte.Analogía, por qué importa y la trampa

AnalogíaEl cierre de una votación: los votos que llegan después cuentan para la siguiente.

Por qué importaHace que el snapshot sea reproducible: correrlo hoy o en un año da lo mismo, aunque sigan llegando eventos. También el registro de borrados se lee al corte.

TrampaUn corte sin zona horaria (2026-10-01 00:00) se interpreta en la hora de la máquina: en México son 6 horas de diferencia y se cuelan eventos.

Split establestable split (hash-based)Cada vendedor cae en train o en val por el hash de su seller_id (cubeta = sha256 mod 100) y se queda ahí en todas las versiones.Analogía, por qué importa y la trampa

AnalogíaEl número de lista en la escuela: el mismo alumno tiene el mismo número todo el año, aunque entren alumnos nuevos.

Por qué importaComparar el modelo nuevo contra el viejo solo es justo si ninguno vio el examen del otro. Los vendedores nuevos caen donde les toque, sin mover a nadie.

TrampaSortear otra vez, o mover el umbral «para tener más validación», manda a val vendedores con los que el modelo anterior ya entrenó.

Duplicados por huellahash-based deduplicationLa misma foto subida en varias publicaciones cuenta una sola vez: de cada huella queda la fila de la publicación más vieja.Analogía, por qué importa y la trampa

AnalogíaTres copias del mismo examen con distinto nombre en la portada: se califica una.

Por qué importaSi la misma foto cayera en train y en val, la validación premiaría memorizar. Pasa con vendedores que republican y con fotos de catálogo que usan dos tiendas.

TrampaDeduplicar por llave no sirve: cada publicación tiene su llave. Lo que se repite son los bytes, o sea la huella.

Contrato de datosdata contractLas reglas que los datos cumplen antes de entrenar: esquema exacto, categorías válidas, cero duplicados, cero golden, split por vendedor y estable, volumen en rango y tope de labels débiles.Analogía, por qué importa y la trampa

AnalogíaLa revisión de un avión antes de despegar: una lista fija, la misma cada vez, y si un punto falla no se despega.

Por qué importaDetiene el pipeline antes de gastar GPU. Cada regla viene de un error real: un join que duplica, el golden en train, un split que se movió.

TrampaUn contrato que solo avisa y deja seguir no es contrato: el paso de validar tiene que fallar (código de salida 1) para que nada se publique.

Escribir, auditar, publicarwrite-audit-publishEl snapshot se arma aparte, se audita con el contrato y solo si pasa se publica, con la tarjeta al final.Analogía, por qué importa y la trampa

AnalogíaImprimir el periódico de prueba, revisarlo y solo entonces mandarlo a todos los puestos.

Por qué importaUn job que se cae a medias no deja un snapshot «a medias» que alguien pueda usar: sin tarjeta no existe. En el dojo, «aparte» es data/ en tu Mac; en C01, un prefijo staging/.

TrampaPublicar la tarjeta primero (o en medio) abre la puerta a entrenar con algo que nadie revisó.

Escritura condicionalconditional write (If-None-Match: *)Un PUT que solo se cumple si la llave no existe. Si ya existe, S3 responde 412 Precondition Failed y no toca nada.Analogía, por qué importa y la trampa

AnalogíaUn buzón con candado: puedes dejar una carta nueva, pero no cambiar la que ya está adentro.

Por qué importaSin ella, un PUT a una llave que existe reemplaza el objeto en silencio: gana el último. Con ella, reescribir un snapshot es un error ruidoso.

TrampaEl header lo pone quien escribe: un script que no lo pone escribe igual. En AWS se vuelve obligatorio con la política del bucket; RustFS no tiene esa condición, así que aquí depende de tu código. Y con versiones solo mira la versión vigente: si es una marca de borrado, el PUT pasa.

Versionado del bucketS3 Versioning y delete markersCon el versionado prendido, un PUT a una llave existente guarda una versión nueva sin destruir la vieja, y un DELETE solo pone una marca de borrado encima.Analogía, por qué importa y la trampa

AnalogíaUn documento con historial de cambios: puedes volver a cualquier versión, y borrar es tachar, no quemar.

Por qué importaEs la red de seguridad: lo que se pisó o se borró por error se recupera borrando la versión mala o la marca. Y deja rastro de cada reescritura.

TrampaProtege versiones, no llaves: el PUT nuevo pasa y es lo que se lee. Y para un borrado por ley hay que borrar cada versión, no solo poner la marca.

DAG y caché de pasospipeline DAG y step cacheEl pipeline como pasos con flechas (qué lee y qué deja cada uno). La herramienta guarda la salida de cada paso con una llave hecha de su código, sus parámetros y sus entradas, y la reusa si la llave no cambió.Analogía, por qué importa y la trampa

AnalogíaUna receta con pasos: si ya picaste la cebolla y nadie cambió la cebolla, no la vuelves a picar.

Por qué importaAhorra horas y hace que repetir el pipeline sea seguro. dvc.lock guarda las huellas de cada entrada y salida: también es linaje.

TrampaLo que no está en la llave no existe para la caché: un parámetro que el script lee pero el stage no declara no hace correr el paso, y sale la salida vieja.

Id como parámetro, nunca «latest»pass the snapshot id, not a moving pathToda entrada que cambia el resultado llega como un id fijo (ds-2026-09-01), nunca como una carpeta que cambia de contenido sin cambiar de nombre.Analogía, por qué importa y la trampa

AnalogíaPedir «el libro con ISBN tal» en vez de «el libro de la repisa de arriba»: alguien puede cambiar el de la repisa.

Por qué importaLa corrida guarda un puntero que siempre dice lo mismo. Con latest, el registro no dice con qué entrenó y la caché ve la misma llave dos meses seguidos.

Trampa«Para no editar params.yaml cada mes» es la excusa típica. Cambiar el id cada mes es trabajo del orquestador, no de una carpeta mágica.

LinajelineageLa cadena de qué salió de qué: modelo ← corrida ← snapshot (id + rows_sha256) ← cada foto (llave + huella), más el commit y el entorno. Se guarda como punteros, no como copias.Analogía, por qué importa y la trampa

AnalogíaEl árbol genealógico con acta de nacimiento en cada rama.

Por qué importaResponde en un minuto las tres preguntas: con qué datos se entrenó, si cambió el código o los datos, y en qué modelos está la foto que pidieron borrar.

TrampaUn puntero que se escribe a mano o «después» se desfasa. Lo escribe el mismo programa que entrena, en el momento.

Commit con el árbol limpioclean working treeEntrenar (y publicar) solo desde un commit sin cambios pendientes en el código, para que el commit diga exactamente qué corrió.Analogía, por qué importa y la trampa

AnalogíaFirmar un contrato solo cuando ya no tiene tachones a mano.

Por qué importaEl commit es uno de los cinco ingredientes de la reproducibilidad (código, datos, configuración, entorno y semilla). Si el script tenía cambios sin commit, el puntero apunta a otro código.

Trampadvc repro cambia dvc.lock: hay que hacer commit después de cada repro, antes de entrenar.

Registro de borradosdeletion log (tombstones)Una lista de solo agregar con la huella de cada foto que se borró, la fecha y el motivo.Analogía, por qué importa y la trampa

AnalogíaLa lista de bajas de un club: no se arranca la hoja del acta vieja, se anota la baja con fecha.

Por qué importaRespeta el derecho al borrado sin romper la historia: los snapshots viejos no se reescriben, el siguiente ya no la incluye y el entrenamiento la salta al leer.

TrampaBorrar la foto del bucket sin anotarlo deja filas que apuntan a nada y un entrenamiento que truena; anotarlo sin borrar no cumple la solicitud.

Paso idempotenteidempotent stepCorrerlo dos veces deja lo mismo que correrlo una.Analogía, por qué importa y la trampa

AnalogíaEl botón del elevador: picarle cinco veces no llama cinco elevadores.

Por qué importaEl orquestador reintenta pasos que fallan a la mitad. Publicar otra vez el mismo contenido sigue sin error; otro contenido con el mismo id se detiene.

TrampaIdempotente no es «sobrescribe sin preguntar»: eso borra la historia. Es «si ya está igual, no hago nada».

Nube real vs. local
En C01En el dojo
Filas del snapshot1,932,628 fotos (1,840,211 train · 92,417 val)2,467 fotos (2,309 train · 158 val)
Lo que cita≈ 387 GB de fotos de ≈ 200 KB; el manifest ≈ 97 MB en Parquet6.1 MB de fotos de juguete de ≈ 2.3 kB; el manifest 242 kB en Parquet
Splitsha256(seller_id) mod 100 < 95 → trainsha256(seller_id) mod 100 < 90 → train (con 300 vendedores, el 5 % dejaría muy pocos en val)
Dónde viveAmazon S3, con versionado y una política del bucket que exige If-None-Match: *RustFS en tu Mac, con versionado; la escritura condicional la pone tu código
Quién lo arma cada mesel pipeline mensual en el orquestador (por ejemplo Kubeflow Pipelines), con caché por pasodvc repro sobre dvc.yaml, con la caché de DVC
Dónde quedan los punterosMLflow: parámetros y tags de la corrida, y el digest de la imagen de entrenamientocorridas/*.json y la huella de los paquetes instalados
En la nubeEn el dojoQué cambia
Amazon S3 con política del bucketRustFS en localhost:9300La misma API: versionado, marcas de borrado y PUT con If-None-Match (412) funcionan igual. RustFS no acepta la condición s3:if-none-match en una política, así que la escritura condicional depende de tu código; en AWS la política la vuelve obligatoria para todos.
El orquestador del pipeline mensual (por ejemplo Kubeflow Pipelines)DVC: dvc.yaml + dvc reproLos dos arman un DAG y reusan la salida de un paso si su llave no cambió. El orquestador corre en un clúster, con horario y reintentos; DVC corre en tu Mac cuando tú lo llamas.
MLflow (parámetros y tags de la corrida)corridas/*.jsonLos mismos punteros en un JSON por corrida. MLflow los guarda en un servidor, con interfaz y búsqueda; lo verás en la estación 3.
El digest de la imagen de entrenamientohuella_entorno(): sha256 de los paquetes instaladosEl digest fija todo el contenedor (sistema, CUDA, drivers); la huella de paquetes solo fija las versiones de Python.
Qué trae el kit y qué escribes tú

Lo que trae no lo escribes

El S3 local (compose.yaml). RustFS en el puerto 9300, con dos buckets: fotos (el del producto) y ml-datos (el de ML, con versionado).

mundo/crear.py. Crea todo con semilla fija en ≈ 10 s: las 3,120 fotos de juguete (64×64, el color y la forma dependen de la categoría), la entrada y el snapshot ds-2026-08-01.

entrada/. Lo que dejó la estación 1 y el producto: publicaciones.parquet, labels-eventos.parquet (3,908 eventos, 112 después del corte), golden.parquet (280 huellas), borrados.csv (las 14 fotos de una vendedora que pidió borrar) y categorias.json.

corridas/run-20260901-061500.json. La corrida del modelo de septiembre, que entrenó con ds-2026-08-01: el registro de corridas (en C01, MLflow).

mundo/s3.py. Mirar y reparar el S3 con permisos de administrador: ls, versiones (con la huella de cada versión), borrar-version y versionado. En C01, el AWS CLI.

verificar.py y romper.py. 12 checks con los criterios de «listo» y 7 fallas en el mundo, la configuración o la infraestructura, nunca en lo que escribes.

Lo que escribes lo escribes tú

  1. pipeline/1_labels.pyLos labels vigentes al corte, con la regla de 30 días para quien vende.
  2. pipeline/2_manifest.pyUna fila por foto con su llave y su huella.
  3. pipeline/3_split.pySin borrados, sin duplicados, sin golden, y el split estable por vendedor.
  4. pipeline/4_validar.pyEl contrato de datos: 8 reglas, y si una falla no se publica nada.
  5. pipeline/5_publicar.pyEl snapshot en S3 con escritura condicional y la tarjeta al final.
  6. dvc.yamlLos pasos 1 a 5 como DAG, con sus entradas, parámetros y salidas.
  7. pipeline/6_entrenar.pyEntrenar con un id, comprobando cada huella, y dejar los tres punteros.
  8. pipeline/7_linaje.pyDe una foto a sus snapshots, sus modelos y su borrado.
Reglas CLAUDE.md del kit
El CLAUDE.md del kitLas reglas de fondo para Claude Code en la carpeta del kit. Ya viene en el .zip.
Ver el CLAUDE.md
prompt
# Dojo de entrenamiento ML engineer's · C01 · Estación 2: Versionado y linaje

Este es un mini-proyecto de práctica. Reproduce en pequeño, en una Mac sin GPU ni nube, la estación «Versionado y linaje» del caso C01: convertir los labels del mes en un snapshot inmutable (manifest + tarjeta) y dejar en cada modelo los punteros que dicen con qué datos, con qué código y en qué entorno se entrenó. La persona con la que trabajas está aprendiendo; tu trabajo es que **entienda**, no que termine rápido.

## Qué es cada cosa

| Carpeta o archivo | Qué es | ¿Se toca? |
|---|---|---|
| `mundo/` | La empresa ficticia: `crear.py` (fotos, eventos de labels, el snapshot de agosto y la corrida de septiembre), `modelo.py` (el entrenamiento de juguete), `s3.py` (mirar y reparar el S3 con permisos de administrador), `reiniciar.py` y el esqueleto. | **No.** Es el mundo. `s3.py` sí se usa para diagnosticar y reparar. |
| `entrada/` | Lo que dejó la estación 1 y el producto: publicaciones, eventos de labels, golden set, categorías y el registro de borrados. | Solo `entrada/borrados.csv`, y solo cuando un arreglo lo pide (se **agregan** filas, nunca se editan). |
| `pipeline/1_labels.py` … `7_linaje.py` | Los 7 pasos de la persona. Cada uno trae su contrato arriba. | **Sí.** Es lo que la persona escribe. |
| `pipeline/_comun.py` | Lo que comparten los pasos: `params()`, `s3()`, `sha256()`, `utc()`, `huella_entorno()`, `entrenar()`. | No. |
| `dvc.yaml` | El pipeline como DAG (paso 6). | **Sí.** |
| `params.yaml` | Los parámetros: el id del snapshot, el corte, el padre, el umbral del split, el snapshot de entrenamiento. | Solo cuando un paso o un arreglo lo pide. |
| `dvc.lock`, `.dvc/` | Las huellas que deja DVC al correr. | No a mano: los escribe `dvc repro`. Sí van en los commits. |
| `data/` | Las salidas del pipeline (DVC las controla; git las ignora). | No a mano. |
| `corridas/` | El registro de corridas (en C01, MLflow). `run-20260901-061500.json` es del equipo. | No a mano: lo escribe `pipeline/6_entrenar.py`. |
| `verificar.py` | Revisa los criterios de «listo», uno por check. | No. |
| `romper.py` | Mete fallas en el mundo, la configuración o la infraestructura. Nunca en lo que escribe la persona. | No. Y no leas su código para adivinar una falla escondida. Tampoco leas `mundo/comun.py` para resolver un paso: trae la versión del equipo. |
| `GUION.md` / `OBJETIVOS.md` | El paso a paso (ronda Guiado) y solo los objetivos (ronda Solo). | No. |
| `taller/progreso.json`, `BITACORA.md` | El registro de las rondas. | Sí, tú los mantienes (ver abajo). |
| `taller/registro.py` | Lo usan `verificar.py` y `romper.py` para anotar en `progreso.json` sus corridas y las fallas cerradas. | No. |

## Cómo se trabaja

- Responde en español neutro, de tú, directo y sin relleno. Términos técnicos en inglés la primera vez, con su explicación.
- Explica siempre el **por qué**. Cuando algo en el dojo es distinto de C01 real (escala, RustFS en vez de Amazon S3, DVC en vez del orquestador, `corridas/` en vez de MLflow), dilo en una línea.
- Nunca inventes salidas: si no corriste algo, di que no lo corriste.
- El entorno virtual va activo en cada comando: `source .venv/bin/activate`.
- Antes de correr algo que cambia el mundo o la máquina (`dvc repro`, `pipeline/5_publicar.py`, `pipeline/6_entrenar.py`, `mundo/s3.py borrar-version`, `mundo/s3.py versionado … on|off`, `romper.py`, `mundo/*.py`, `git commit`), dilo. Lo que solo lee (`verificar.py`, `dvc status`, `dvc dag`, `mundo/s3.py ls` y `versiones`, `git status`, `git log`) se puede correr directo.
- Un snapshot publicado nunca se reescribe ni se borra para «arreglarlo». Si el contenido cambió, lleva un id nuevo.
- Sigue el prompt de la ronda que te pegaron: en Solo y en Romper solo **no das código ni pistas** salvo que la persona se rinda.

## Bitácora

Al terminar cada paso, objetivo o falla, agrega una entrada en los dos archivos:

`BITACORA.md`, legible en el celular:

```markdown
## 2026-11-16 10:42 · Guiado · paso 1 (labels al corte)
- **Hice:** …
- **Medí:** … (números reales que salieron)
- **Sigue:** …
```

`taller/progreso.json`, el que se importa en «Tu tablero» del Dojo (la página /tablero/ de la app). Agrega a `bitacora` y actualiza `rondas`:

```json
{
  "estacion": "c01-versionado",
  "rondas": {
    "guiado":       { "estado": "en_curso", "inicio": "2026-11-16T10:05:12-06:00", "fin": null },
    "solo":         { "estado": "pendiente", "inicio": null, "fin": null, "pistas": 0 },
    "romper_ayuda": { "estado": "pendiente", "fallas": [] },
    "romper_solo":  { "estado": "pendiente", "fallas": [] }
  },
  "bitacora": [
    { "fecha": "2026-11-16T10:42:30-06:00", "ronda": "guiado", "paso": "labels", "hice": "…", "medi": "…", "sigue": "…" }
  ],
  "verificaciones": [
    { "fecha": "2026-11-16T10:41:02-06:00", "pasan": ["mundo", "labels"], "fallan": [] }
  ]
}
```

- `estado` es `pendiente`, `en_curso` o `hecha`. En el tablero, `guiado` se llama «Construir con ayuda», `solo` «Construir solo», `romper_ayuda` «Romper con ayuda» y `romper_solo` «Romper solo».
- **Fecha y hora en cada avance**, en ISO 8601 con la zona de la Mac: sácala con `date -Iseconds` (da algo como `2026-11-16T10:42:30-06:00`). Nunca solo la fecha.
- `verificaciones` la escribe `verificar.py` solo, en cada corrida. No la edites.
- Cada falla la anota `romper.py` al cerrarla (`--verificar` o `--revelar`): `{ "id", "inicio", "fin", "minutos", "pistas": 0, "rendido", "aprendi": "" }`, con el tiempo real. Tú solo completas `pistas` y `aprendi` en esa misma entrada (la última de su ronda); no agregues otra.
- Mantén el JSON válido: después de editarlo, corre `python -m json.tool taller/progreso.json > /dev/null`.

La estación completa, con su lugar en el mapa: cheat sheet «Del dato a producción».

La teoría, en Sensei

Sensei es el curso de teoría desde cero de TrueML. Su lección de esta estación explica el porqué de lo que aquí construyes; léela antes o vuelve a ella cuando algo no cierre.

Lección de la estación 2Versionado y linajeLeer en Sensei ↗ Si te falta base, lee antes