El repositorio cineclick-churn ya tiene estructura, semillas fijas y configuración externa, pero cerramos la lección anterior señalando la grieta: nada declara con qué versiones de pandas, scikit-learn o Python debe ejecutarse ese código. Es el problema nº 8 del diagnóstico ("dependencias implícitas"), y en ML es más traicionero que en el software clásico, porque una versión distinta de una librería no siempre rompe con un error visible: a veces simplemente produce un modelo distinto o métricas distintas, en silencio. En esta lección montaremos el entorno reproducible del proyecto: entorno virtual, dependencias declaradas en pyproject.toml, versiones fijadas con un fichero de lock, y los detalles extra que la reproducibilidad en ML exige más allá de la lista de paquetes.

1. "En mi máquina funciona", edición ML
2. Entornos virtuales: uno por proyecto
3. Declarar dependencias en pyproject.toml
4. Fijar versiones: rangos, pins y ficheros de lock
5. Reproducibilidad más allá de los paquetes
6. Buenas prácticas para el repo de CineClick

Imagina que un nuevo compañero, Marc, clona cineclick-churn, hace pip install pandas scikit-learn pyyaml en su Python global y ejecuta el entrenamiento. Posibles finales de la historia, todos reales:

• Rotura ruidosa: su versión de scikit-learn eliminó o renombró un parámetro que usamos, y el script muere con un TypeError. Molesto, pero al menos es visible.
• Rotura silenciosa de resultados: entre versiones de scikit-learn cambian detalles de implementación (algoritmos internos, manejo de empates, valores por defecto de hiperparámetros). El mismo código con la misma semilla puede producir un modelo con métricas ligeramente distintas. Marc obtiene recall 0.41 en vez de 0.43 y pierde una tarde buscando un bug que no existe: la diferencia era la versión de la librería. La semilla fija el azar dentro de una versión, no entre versiones.
• El pickle traidor: Marc intenta cargar el modelo_churn.pkl entrenado con otra versión de scikit-learn. Un pickle no es un formato de intercambio: es un volcado de objetos Python que asume que las clases al cargarlo son las mismas que al guardarlo. Con versiones distintas puede fallar al cargar, o —peor— cargar con un aviso (InconsistentVersionWarning) y predecir mal. Regla de hierro: un modelo picklado se sirve con exactamente las mismas versiones con las que se entrenó.
• Contaminación entre proyectos: Marc instala después otro proyecto que exige una versión incompatible de pandas en el mismo Python global, y cineclick-churn deja de funcionar sin que nadie lo haya tocado.

La conclusión es la misma del DevOps clásico, agravada: el entorno es parte del artefacto. Reproducir el modelo exige reproducir código + datos + entorno.

La primera defensa es aislar: cada proyecto con su propio conjunto de paquetes, sin compartir nada con el Python global ni con otros proyectos. En Python la herramienta de serie es venv:

Qué acaba de pasar: python -m venv .venv crea un directorio .venv/ con una copia ligera del intérprete y un site-packages vacío y propio. Al activarlo, la shell antepone ese entorno al PATH: python y pip pasan a ser los del proyecto. Todo pip install posterior instala dentro de .venv/, sin tocar nada más de la máquina.

Convenciones que adoptamos en CineClick:

• El entorno se llama .venv y vive en la raíz del proyecto (es la convención que las herramientas y editores detectan automáticamente).
• .venv/ va al .gitignore: el entorno no se versiona (es enorme, específico de cada SO, y regenerable). Lo que se versiona es la receta para recrearlo — de eso van los dos apartados siguientes.
• Un proyecto = un entorno. Nunca instales dependencias de dos proyectos en el mismo entorno "porque total, son parecidos".

Alternativa que verás en muchos equipos de datos: conda, que además de paquetes Python gestiona binarios no-Python (CUDA, compiladores). Es una opción legítima, especialmente en deep learning; en este curso nos quedamos con venv + pip por ser el estándar mínimo y porque nuestro stack no lo necesita.

Con el entorno aislado, falta la receta. En la lección anterior dejamos un pyproject.toml mínimo; ahora le añadimos la sección de dependencias, distinguiendo dos categorías:

• Dependencias de runtime (dependencies): las que el código necesita para funcionar — pandas, scikit-learn, PyYAML. Cualquiera que instale el paquete las necesita, incluida la imagen de producción.
• Dependencias de desarrollo (extras opcionales): las que solo necesita quien trabaja en el proyecto — pytest, herramientas de lint o de lock. Producción no debe cargar con ellas.

Y la instalación para desarrollo pasa a ser:

El sufijo [dev] activa el extra: instala el paquete en modo editable más las herramientas de desarrollo. En producción (o en la imagen Docker del módulo 4) bastará pip install . a secas, sin pytest ni utilidades de desarrollo a bordo.

Fíjate en los rangos: scikit-learn>=1.5,<1.6 es deliberadamente más estricto que el de pandas, por lo que vimos del pickle — no queremos que un salto de versión menor de scikit-learn se cuele entre el entrenamiento y el servicio. Lo cual nos lleva a la pregunta clave: ¿cómo de fijas deben ser las versiones?

Hay tres estrategias posibles, cada una con su lugar:

La práctica moderna combina las dos últimas: rangos en pyproject.toml, pins exactos en un fichero de lock generado automáticamente. El pyproject.toml dice "funciono con cualquier scikit-learn 1.5.x"; el lock dice "el entorno bendecido, el que produce exactamente nuestras métricas, es scikit-learn 1.5.2 con estas 30 dependencias transitivas exactas". Lo importante del lock es que incluye las dependencias transitivas: tú declaras pandas, pero pandas arrastra numpy, python-dateutil, tzdata... y una versión distinta de numpy también puede cambiar resultados numéricos.

Para generar el lock usaremos pip-tools (la alternativa moderna y mucho más rápida es uv, cuyo flujo es casi idéntico — uv pip compile / uv pip sync; elige la que prefieras, el concepto es el mismo):

El requirements.lock resultante es un fichero de texto plano, versionado en Git, con este aspecto (fragmento):

El flujo de trabajo del equipo queda así:

• Añadir o actualizar una dependencia: se edita pyproject.toml, se re-ejecuta pip-compile, y se commitean los dos ficheros juntos. El diff del lock muestra exactamente qué versiones cambiaron — revisable en un pull request.
• Incorporarse al proyecto o desplegar: nunca pip install pandas a mano; siempre pip-sync requirements.lock. Marc obtiene un entorno idéntico al de Laura, byte a byte de versiones.
• Actualizar deliberadamente (p. ej. una versión nueva de scikit-learn): pip-compile --upgrade-package scikit-learn, re-entrenar, comparar métricas, y solo entonces commitear. La actualización de dependencias en ML es un experimento, no un trámite.

Con entorno + lock cubrimos las librerías, pero quedan tres flecos que en ML importan:

Python 3.11 y 3.12 no son intercambiables: cambian rendimiento, avisos y, ocasionalmente, comportamiento de librerías compiladas contra cada versión. Ya declaramos requires-python = ">=3.11" en pyproject.toml (el rango admisible); además, fijamos la versión concreta de desarrollo en un fichero .python-version en la raíz:

Es una convención que entienden los gestores de versiones de Python (pyenv, uv, varios IDE): al entrar en el directorio, seleccionan ese intérprete automáticamente. Un fichero de una línea que elimina toda una categoría de "en mi máquina funciona".

Python aleatoriza por defecto el hash de las cadenas en cada proceso (una medida de seguridad). Consecuencia: cualquier código cuyo resultado dependa del orden de iteración de un set o del hash de strings puede variar entre ejecuciones aunque todas las semillas de ML estén fijadas. Nuestro pipeline actual no depende de ello (pandas y scikit-learn usan sus propios generadores, que ya controlamos con random_state), pero es una fuente clásica de irreproducibilidad difícil de cazar. La vacuna es fijar la variable de entorno antes de ejecutar:

En CineClick la documentamos en el README y, más adelante, quedará fijada de serie en la imagen Docker (04-03) y en los pipelines automatizados.

Las semillas de train_test_split y del RandomForestClassifier quedaron fijadas en 02-01 — son la tercera pata, y la más conocida, de la reproducibilidad. Queda un último nivel que debes conocer aunque no nos afecte: con GPU y deep learning, ciertas operaciones son no-deterministas por diseño (paralelismo con sumas en coma flotante en orden variable), y la reproducibilidad exacta exige opciones específicas del framework, a veces pagando rendimiento. Para nuestro RandomForest en CPU, no aplica; si algún día CineClick entrena redes, recuerda que la frontera existe.

La jerarquía completa, de dentro afuera:

Cada capa asume la anterior. Y observa la última fila: aunque entorno virtual + lock cubren el 95% de los casos, siguen ejecutándose sobre tu sistema operativo. Empaquetar también el SO es exactamente lo que hace Docker, y lo dejamos para el módulo 4.

Recapitulando, el estado del repositorio tras esta lección:

Y el ritual de incorporación de cualquier compañero, documentado en el README:

Reglas de equipo que quedan establecidas: nadie instala paquetes a mano fuera del flujo pyproject.toml → pip-compile → commit; el lock se regenera solo de forma deliberada y su diff se revisa; y toda máquina que entrene o sirva el modelo —humana o automatizada— parte del mismo lock.

• Error: versionar .venv/ en Git. Es pesado, específico de cada sistema operativo y regenerable. Se versiona la receta (pyproject.toml + requirements.lock), jamás el entorno. Si ves .venv/ en un git status, corre al .gitignore.
• Error: pip freeze > requirements.txt como "lock". Funciona a medias, pero vuelca todo lo instalado en el entorno (incluido lo que probaste una tarde y no usas), no distingue directas de transitivas, y no se regenera desde una fuente de intención. pip-compile parte de pyproject.toml y anota de dónde viene cada paquete: es la diferencia entre una foto ordenada y el cajón de los cables.
• Error: entrenar con unas versiones y servir con otras. El caso del pickle traidor. El entorno de entrenamiento y el de inferencia deben salir del mismo lock; cuando lleguemos a Docker (04-03) y al servicio (04-02), esta regla se convertirá en construcción de imagen, pero la disciplina empieza hoy.
• Error: actualizar dependencias "porque había una versión nueva" sin re-evaluar. En ML una actualización de scikit-learn puede mover tus métricas. Trátala como un cambio más: rama, pip-compile --upgrade-package, re-entrenar, comparar métricas, revisar, mergear.
• Consejo: si el equipo ya domina uv, úsalo: es un reemplazo casi directo (uv venv, uv pip compile, uv pip sync) y órdenes de magnitud más rápido. Lo importante de esta lección es el patrón intención/lock, no la herramienta concreta.

Marc clona el repo, crea su .venv, pero en lugar de usar el lock ejecuta pip install pandas scikit-learn pyyaml pytest y luego pip install -e . --no-deps. Los tests pasan, el entrenamiento corre sin errores... pero obtiene recall = 0.41 en lugar del 0.43 esperado. (1) ¿Cuál es la causa más probable? (2) ¿Por qué no lo detectó ningún error ni test? (3) ¿Qué dos comandos debería haber ejecutado en su lugar?

Clasifica estas dependencias del proyecto CineClick como runtime (dependencies) o desarrollo (optional-dependencies.dev), justificando cada una: (a) scikit-learn — entrena y ejecuta el modelo; (b) pytest — ejecuta los tests; (c) pyyaml — carga configs/config.yaml; (d) pip-tools — regenera el lock; (e) fastapi — servirá el modelo en el módulo 4: cuando llegue, ¿dónde irá?

El requirements.lock actual fija scikit-learn==1.5.2. Sale la 1.6.0 con una mejora de rendimiento que os interesa. Describe, paso a paso y con los comandos concretos, el procedimiento correcto para adoptarla en CineClick, incluyendo qué harías con el modelo modelo_churn.pkl ya entrenado y por qué.

Solución 1: (1) pip install sin versiones instaló lo último de cada paquete, seguramente una versión de scikit-learn (o de numpy, transitiva) distinta de la del lock; los detalles internos del algoritmo cambian entre versiones y, aunque la semilla es la misma, el modelo resultante difiere ligeramente. (2) No hay error porque la API que usamos no cambió, y el test de features no evalúa métricas del modelo — comprueba el encoding, que es determinista en cualquier versión razonable (los tests que vigilan métricas llegarán en 05-01). (3) pip-sync requirements.lock seguido de pip install -e . --no-deps: eso reproduce el entorno bendecido exacto.

Solución 2: (a) runtime — sin scikit-learn ni se entrena ni se puede deserializar/usar el modelo; (b) dev — producción no ejecuta tests; (c) runtime — el código de entrenamiento lee la configuración en cualquier entorno donde corra; (d) dev — es una herramienta del flujo de trabajo, el código nunca la importa; (e) runtime — el servicio de predicción la importará para funcionar en producción (de hecho, equipos grandes a veces separan extras train/serve para no llevar scikit-learn completo al servicio y viceversa; para CineClick, de momento, un solo grupo runtime es suficiente).

Solución 3: (1) crear una rama (git checkout -b actualiza-sklearn-16); (2) ampliar el rango en pyproject.toml (scikit-learn>=1.5,<1.7 o directamente >=1.6,<1.7); (3) regenerar el lock solo para ese paquete: pip-compile pyproject.toml --extra dev -o requirements.lock --upgrade-package scikit-learn; (4) pip-sync requirements.lock y pip install -e . --no-deps; (5) re-entrenar el modelo desde cero y comparar las métricas con la línea base (accuracy 0.86 / precision 0.61 / recall 0.43 / F1 0.50); (6) descartar el modelo_churn.pkl antiguo: un pickle de la 1.5.2 no debe servirse desde un entorno 1.6.0 — el modelo "bueno" pasa a ser el re-entrenado; (7) commit de pyproject.toml + requirements.lock juntos, pull request con las métricas comparadas, merge. Si las métricas empeoraran sin explicación, se descarta la rama y no ha pasado nada: esa reversibilidad barata es justo lo que compran el lock y Git.

El problema nº 8 tiene los días contados: el entorno de CineClick ya es una receta versionada —.venv por proyecto, dependencias con rangos en pyproject.toml separando runtime de desarrollo, pins exactos de todo el árbol en requirements.lock generado con pip-compile, .python-version y PYTHONHASHSEED cerrando los flecos— y cualquier compañero puede recrear byte a byte de versiones el entorno que produce nuestras métricas. Código reproducible (02-01) + entorno reproducible (esta lección) nos dejan a las puertas del tercer ingrediente, y el más voluminoso: los datos. El clientes_churn.csv sigue siendo un fichero suelto que cada extracto mensual sobrescribe, sin historia ni forma de volver atrás — el problema nº 3 del diagnóstico. Git no puede con él (y en la próxima lección veremos exactamente por qué), así que toca presentar a la herramienta nacida para esto: DVC, el control de versiones para datos.