English · Español

Lab 03 — Versiona el corpus con `dvc`¶

Objetivo: añade dvc al proyecto (según §A8), úsalo para trackear data/processed/, commitea los archivos puntero .dvc y confirma la reproducibilidad desde el manifest.

Tiempo estimado: 45–60 minutos.

Prerrequisito: lab 02 commiteado; data/processed/{train,val,test}.jsonl + data/MANIFEST.json existen.

Lo que produces¶

dvc inicializado en el repo (directorio .dvc/).
Archivos puntero data/processed/*.jsonl.dvc commiteados.
data/processed/*.jsonl añadido a .gitignore.
experiments/12-corpus-stats/ con tres plots y un README.md.
El PHASE_12_REPORT.md de fin de fase (según §7).

TODOs¶

Bloque A — instala e inicializa `dvc`¶

Añade dvc a pyproject.toml bajo un opt-in group data (según el patrón "fija ahora, instala cuando se necesite" de §A8). Ejecuta uv sync --extra data.
dvc init en la raíz del repo. Verifica que .dvc/ se cree y .dvc/config esté vacío (sin remoto).
git add .dvc/, commit con mensaje chore: initialize dvc for data layer.

Bloque B — trackea los archivos del corpus¶

dvc add data/processed/train.jsonl. Confirma:
data/processed/train.jsonl.dvc se crea.
data/processed/train.jsonl se añade automáticamente a data/.gitignore.
Repite para val.jsonl y test.jsonl.
git add data/processed/*.dvc data/.gitignore.
git commit -m "chore: track corpus jsonl with dvc".
git status — confirma que data/processed/*.jsonl no esté trackeado, pero los archivos .dvc sí.

Bloque C — confirma reproducibilidad¶

Borra data/processed/{train,val,test}.jsonl (mueve a /tmp/ por seguridad, no borres permanentemente).
Ejecuta el pipeline completo: python scripts/gen_corpus.py --seed 42 && python scripts/validate_corpus.py && python scripts/split_corpus.py --seed 42 && python scripts/build_manifest.py.
Confirma que los archivos regenerados tienen SHA256s idénticos a los valores en data/MANIFEST.json.
Si no coinciden: párate aquí, depura, no procedas. La teoría 03 lista las causas raíz probables.
Restaura los archivos (ahora regenerados) vía dvc checkout si es necesario (o simplemente deja las copias regeneradas; son idénticas a nivel de bytes).

Bloque D — plots en `experiments/12-corpus-stats/`¶

Heatmap de cobertura. 20 verbos × 6 superficies de tiempo, coloreado por conteo total de filas (correct + mis-conjugated) por celda. Conteos por persona colapsados para claridad visual. Guarda como coverage_heatmap.png.
Histograma de longitud de token por tiempo. Usa el BPE de la Fase 11 para tokenizar cada fila en inglés; agrupa por tiempo. Seis histogramas superpuestos (o una pequeña rejilla de seis). Guarda como token_length_per_tense.png.
Pareto de mis-conjugaciones. Bar chart del conteo de mis-conjugaciones por tipo. Guarda como mis_conjugation_pareto.png.
Scatter de longitud inglés vs español. Un punto por fila; x = longitud en bytes en inglés, y = longitud en bytes en español; color por tiempo. Guarda como english_spanish_length_scatter.png.
Escribe experiments/12-corpus-stats/README.md interpretando cada plot en 2–4 frases. Anota cualquier sorpresa.
Escribe experiments/12-corpus-stats/manifest.json según CLAUDE.md §0.5 (semilla, versiones, entradas).

Bloque E — `PHASE_12_REPORT.md`¶

Sigue la plantilla de ritual §7. Incluye:

Números destacados: filas totales, desglose por etiqueta, estado de la verificación de cobertura de celdas.
Revisión de la tabla de verbos: cualquier traducción al español que revisarías post-implementación.
Revisión de la taxonomía de mis-conjugaciones: cualquier tipo que resultó difícil de generar limpiamente; cualquier tipo que se solapa (p. ej., subject_verb_disagreement vs bare_participle_missing_aux ambos aplican a celdas de participio).
Balance de splits: ¿qué tan sesgado terminó el split estratificado por (verbo, tiempo)? (Algunos splits pueden tener todos los verbos irregulares por casualidad.)
Checklist DoD: cada ítem de PHASE_12_PLAN.md §6 marcado o explícitamente renunciado.
Preguntas abiertas planteadas: cualquier cosa no anticipada en PHASE_12_PLAN.md §7 que surgió.
Traspaso a la Fase 13: ¿qué necesita saber el lab de embeddings? P. ej., "el BPE de la Fase 11 se re-entrenó sobre el corpus completo al cierre de la Fase 12 — ver experiments/12-bpe-rerun/ para el nuevo vocab."

Bloque F — Re-ejecución del BPE de la Fase 11¶

Según la nota "Re-ejecuta este lab al cierre de la Fase 12" del lab-02 de la Fase 11: re-entrena el BPE sobre el corpus completo de la Fase 12.
Salida: experiments/12-bpe-rerun/vocabs/512/ con el nuevo tokenizer.
Compara los top-30 merges con el resultado del corpus de bootstrap; documenta cualquier nueva morfología que apareció (p. ej., sufijo imperfecto en español -aba si es relevante — aunque no está en nuestro alcance de tiempos v1; más probable: stem trab, stem gust, going to como un único token).
Actualiza experiments/12-bpe-rerun/README.md con la comparación.

Bloque G — `learners/borja/phase-12/reflections.md`¶

Según CLAUDE.md §3 y el ritual por-fase: escribe la reflexión.

¿Qué cuajó? ¿Qué no?
¿Fue el split estratificado por (verbo, tiempo) la granularidad correcta? ¿Lo cambiarías?
¿Cuál es el mayor punto ciego del corpus para el tutor de la Fase 32?
Tiempo estimado gastado por lab vs las estimaciones de los enunciados de lab.

Restricciones¶

dvc es un grupo de dependencias opcional. uv sync (sin extras) no debería traerlo.
Sin dvc push. Sin remoto configurado en v1 (según teoría 03).
Sin pipeline dvc.yaml. v1 mantiene dvc solo a tracking de archivos.
Los reportes son markdown. Los plots son PNG. Los manifests son JSON.

Condiciones de parada¶

Hecho cuando:

dvc está inicializado; archivos data/processed/*.jsonl.dvc commiteados.
data/processed/*.jsonl está en .gitignore y es regenerable.
Heatmap de cobertura, distribución de longitud, plots Pareto de mis-conjugaciones commiteados en experiments/12-corpus-stats/.
PHASE_12_REPORT.md escrito y commiteado.
learners/borja/phase-12/reflections.md rellenado y commiteado.
La re-ejecución del BPE de la Fase 11 sobre el corpus completo está commiteada en experiments/12-bpe-rerun/.

Escollos¶

Olvidar .gitignore. dvc add auto-edita .gitignore, pero si accidentalmente haces git add data/processed/*.jsonl antes de dvc add, el archivo se trackea en git y dvc. Confuso. Resetea y rehaz.
Plotear con el tokenizer incorrecto. El histograma de longitud de token (punto 2 del Bloque D) usa el BPE de la Fase 11. Si usas el BPE de bootstrap (vocab pequeño), los conteos de tokens están inflados. Usa el BPE re-ejecutado de la Fase 12 (Bloque F) para el plot oficial.
Longitud en español siempre > inglés. Espera esto — el español es morfológicamente más rico (4 sílabas por verbo vs 2 en inglés típicamente) y los caracteres con acento son 2 bytes cada uno en UTF-8. El scatter debería mostrar español ≈ 1.3× inglés. Si están iguales, al campo en español le faltan los acentos.
Drift de ítems del DoD. Cuando rellenes el checklist en el reporte, re-lee PHASE_12_PLAN.md §6 línea por línea. No resumas de memoria.

Pista de último recurso¶

Si dvc add falla con un error "file is tracked by git": git rm --cached data/processed/<file> primero, luego dvc add de nuevo. El archivo está entonces no-trackeado-por-git pero trackeado-por-dvc.

Cuándo consultar `solutions/`¶

Tras que todo esté commiteado. Solución: solutions/03-version-with-dvc-ref.md (apertura de fase) contiene la secuencia canónica de comandos y un PHASE_12_REPORT.md de muestra.

Fase 12 completa. Siguiente fase: docs/phase-13-embeddings/.

Lab 03 — Versiona el corpus con dvc¶