El mòdul 4 va acabar amb una confessió incòmoda: tot el sistema de CineClick funciona, però el que ho lliga tot són mans. Els tests s'executen "si algú se'n recorda", i això vol dir que un git push un divendres a la tarda pot trencar features.py sense que ningú se n'adoni fins que el batch de dilluns produeixi prediccions absurdes. La integració contínua (CI) resol exactament això: cada canvi dispara automàticament una bateria de comprovacions, i el canvi no s'integra si alguna cosa falla. Però en un projecte de ML la CI clàssica es queda curta, perquè el comportament del sistema no depèn només del codi: depèn del codi, de les dades i del model. En aquesta lliçó construirem la CI real de cineclick-churn: ampliarem els tests de codi existents, afegirem validació de dades amb pandera, escriurem tests de model (de fum, de comportament i de llindar de mètriques) i ho lligarem tot amb un workflow de GitHub Actions.

1. Què canvia a la CI quan hi ha ML: tres coses a testejar
2. La piràmide de tests per a ML
3. Tests de codi: features i API
4. Tests de dades: esquema i expectatives amb pandera
5. Tests de model: fum, comportament i llindar de mètriques
6. El workflow: .github/workflows/ci.yml explicat per blocs
7. Què corre a cada esdeveniment

En una aplicació web tradicional, CI significa: a cada push, executa el linter i els tests; si passen, el codi es pot integrar a main. La premissa implícita és que el codi és l'única font de comportament: si el codi no canvia, el sistema es comporta igual.

En ML aquesta premissa és falsa. El comportament del servei de churn de CineClick és el producte de tres ingredients, i qualsevol dels tres es pot degradar de manera independent:

• Codi: features.py, train.py, l'API de FastAPI. Canvia quan la Laura o en Marc fan commits. Es testeja com sempre: tests unitaris i d'integració.
• Dades: clients_churn.csv i les seves futures actualitzacions. Canvien quan l'equip de dades exporta una versió nova, encara que ningú no toqui ni una línia de codi. Un canvi d'esquema silenciós (una columna reanomenada, un pla nou, nuls on no n'hi havia) pot enverinar l'entrenament sense produir cap error de Python.
• Model: l'artefacte registrat a MLflow. Un model reentrenat amb els mateixos hiperparàmetres pot ser pitjor que l'anterior si les dades han canviat, i pytest no té ni idea de què és un recall.

La conseqüència pràctica: la nostra CI necessita tres famílies de tests, no una. I cada família falla per motius diferents i protegeix contra riscos diferents:

La piràmide clàssica de testing (molts tests unitaris barats a baix, pocs tests end-to-end cars a dalt) continua aplicant-se, però en ML s'hi afegeixen capes. Ordenades de més barates i freqüents a més cares i esporàdiques:

La regla d'or: el que és barat corre sempre; el que és car corre quan aporta. No té sentit avaluar el recall del challenger a cada push a una branca de treball, però sí que és obligatori abans que aquest challenger aspiri a @champion.

Al mòdul 3 vam decidir que features.py és l'única font de veritat de les features: la fan servir l'entrenament, l'API online i el scoring batch. Això la converteix en el fitxer més crític del repo — un bug aquí es propaga als tres consumidors alhora. Mereix els tests més exhaustius.

Recordem el detall fixat al seu dia: ratio_tickets es calcula com a tiquets de suport per mes d'antiguitat, amb clip(lower=1) al denominador per evitar la divisió per zero amb clients acabats d'arribar. Això és exactament el tipus de decisió que un company "simplifica" sense voler en un refactor. La blindem amb tests:

Punts que convé entendre bé:

• _client_base com a fàbrica de fixtures: en lloc de repetir un diccionari de 7 camps a cada test, se'n defineix un de vàlid i cada test canvia només el que és rellevant. Els tests es llegeixen com frases: "un client amb antiguitat 0 i 3 tiquets té ràtio 3".
• El test del one-hot codifica una decisió de disseny, no només un càlcul: construir_features ha de fer servir una llista fixa de categories conegudes (per exemple pd.Categorical amb categories explícites), perquè pd.get_dummies sense més genera columnes segons el que veu, i un pla nou en producció produiria un DataFrame amb columnes diferents de les de l'entrenament — el model fallaria o, pitjor, prediria sobre columnes desordenades.
• Els docstrings expliquen el perquè. Quan aquest test falli d'aquí a un any, qui el llegeixi sabrà què protegeix.

L'API ja té el seu test de validació del mòdul 4: comprovar que una petició mal formada retorna 422 sense invocar el model. Aquest test és or a la CI perquè no necessita MLflow ni artefactes — corre en segons a qualsevol runner:

A la CI aquest test valida el contracte d'entrada del servei: els esquemes de schemas.py són la frontera entre el món exterior i el model, i qualsevol relaxació accidental (algú treu una restricció de Pydantic) es detecta aquí.

Es pot validar un DataFrame amb asserts solts (assert df["pla"].isin(...)), i per a casos trivials és suficient. Però un esquema declaratiu amb pandera aporta tres coses que els asserts no donen: tots els errors de cop (no només el primer), un informe llegible de què ha fallat i a quines files, i un objecte esquema que es pot importar des de qualsevol punt (CI, entrenament, scoring batch) — de nou, una única font de veritat, aquesta vegada del contracte de dades.

El definim al paquet, no als tests, precisament per poder-lo reutilitzar:

Desglossament de les decisions:

• Tipus i rangs: antiguitat_mesos entre 0 i 240 (20 anys; CineClick no existia abans), hores_setmana entre 0 i 168 (no hi ha més hores en una setmana). Els rangs impossibles són la trampa més habitual d'una exportació trencada.
• Categories tancades: pla i metode_pagament només admeten els valors coneguts. Si apareix un pla nou legítim, aquest check ha de fallar: és el senyal per actualitzar features.py, reentrenar i actualitzar l'esquema, en aquest ordre i a consciència — no en silenci.
• Proporció de nuls: hores_setmana admet nuls (hi ha clients sense telemetria), però si superen el 5% alguna cosa va malament a la instrumentació. És una expectativa estadística, no una regla per fila.
• Taxa de churn ≤ 30%: el dataset històric volta el 15%. Si de sobte arriba un 45%, el més probable no és una estampida de clients sinó un filtre trencat a l'extracció. Validar la forma de la variable objectiu evita entrenar amb escombraries.
• strict=True converteix "algú ha afegit una columna" en un error visible en lloc d'una sorpresa.

Validar és una línia: esquema_clients.validate(df, lazy=True) (amb lazy=True pandera acumula tots els errors en un sol informe en lloc d'aturar-se al primer).

Aquí hi ha una subtilesa important: les dades completes no són al repo (són al remote magatzem de DVC), i la CI no hauria de descarregar gigabytes a cada PR. La solució té dues potes:

1. A la CI: es valida una mostra versionada (data/mostres/clients_churn_mostra.csv, unes 2.000 files, trackejada amb DVC igual que el dataset complet). Detecta canvis d'esquema i de contracte amb cost mínim. El workflow fa dvc pull només d'aquesta mostra.
2. Abans de cada entrenament: la primera acció de l'stage preparar_dades del dvc.yaml (i, com veurem a 05-03, la segona task del flow de scoring) és validar el dataset complet amb el mateix esquema_clients. Mateix esquema, dues ubicacions: la CI vigila el contracte; el pipeline vigila les dades reals del dia.

El test més rendible de tota aquesta lliçó: comprovar que el pipeline d'entrenament funciona de principi a fi amb dades sintètiques diminutes. No valida qualitat — valida que ningú no ha trencat la cadena dades → features → fit → predict:

Fixa't en els hiperparàmetres nans (n_estimators=10): no volem el model de producció, volem velocitat. Aquest test triga segons i hauria caçat la meitat dels "funciona a la meva màquina" del mòdul 1.

Aquesta idea ve del paper CheckList (Ribeiro et al., 2020), pensat originalment per a models de NLP, i la seva intuïció es trasllada perfectament al tabular: a més de preguntar "quina mètrica treu el model?", cal preguntar "es comporta el model segons el que sabem del problema?". Un model pot tenir bon recall global i tot i així haver après una relació absurda que petarà amb dades futures. Dos tipus de check:

• Invariància: hi ha entrades que no haurien d'afectar la predicció. id_client és un identificador arbitrari; si canviar-lo canvia la probabilitat de churn, el model (o més probablement features.py) està filtrant l'identificador com a feature — un bug greu i silenciós.
• Direccionalitat: hi ha canvis el sentit dels quals coneixem encara que no en sapiguem la magnitud. Un client idèntic amb més tiquets_suport està, com a mínim, igual d'insatisfet: la seva probabilitat de churn no hauria de baixar. Si baixa, o les features estan mal construïdes o el model va aprendre soroll en aquella zona.

El fixture model_challenger carrega models:/churn-cineclick@challenger des del registry (necessita MLFLOW_TRACKING_URI, per això aquests tests porten la marca @pytest.mark.model i no corren a qualsevol push). Fixa't en la tolerància -0.02 a la direccionalitat: un RandomForest no és monòton per construcció i exigir monotonicitat estricta en un punt donaria falsos positius; el que cacem és una inversió clara de la relació.

Al mòdul 3 el criteri de promoció va quedar escrit en prosa: "precision ≥ 0.50 si recall > 0.60". La prosa no bloqueja merges; els tests sí. El convertim en el gate final, avaluant el challenger contra el test set versionat (data/processed/test.csv, l'split amb test_size=0.2 i random_state=42 de params.yaml, trackejat per DVC — si el test set canviés a cada execució, les mètriques no serien comparables entre candidats):

Com a referència: el champion actual (v2) dona recall 0.68 i precision 0.55, així que passa amb marge. Un challenger que no passi aquest test no arriba ni a la conversa de promoció — la revisió humana del mòdul 3 continua existint (la reprenem a 05-02), però ara revisa només candidats que ja han superat el llistó automàtic.

Tot l'anterior necessita un motor que ho executi sol. Aquest és el workflow real del repo:

Bloc a bloc:

• on: — dos disparadors amb intencions diferents. push a branques de treball dona feedback ràpid mentre desenvolupes; pull_request cap a main és la porta amb tots els controls.
• actions/checkout@v4 — clona el repo al runner. Sense això no hi ha res a testejar.
• setup-python amb cache: pip — instal·la Python 3.11 (la versió fixada al mòdul 2) i caceja els paquets descarregats; la segona execució instal·la en segons.
• pip install -r requirements.lock — instal·lem des del lock de pip-tools, no des de dependències soltes: el runner reprodueix exactament l'entorn de producció (scikit-learn 1.5.2, pandas 2.2.3, FastAPI 0.115.5). Una CI amb versions flotants és una CI que menteix.
• ruff + pytest -m "not model" — linter i tots els tests que no requereixen ni registry ni dades. El marcador model (declarat a pyproject.toml) separa el que és barat del que és car.
• dvc pull amb credencials a secrets — les credencials del remote magatzem viuen als secrets del repositori de GitHub (Settings → Secrets and variables → Actions), mai al YAML ni al codi. El workflow les injecta com a variables d'entorn només al pas que les necessita.
• dorny/paths-filter + etiqueta — els tests de model només corren si la PR toca src/** o si algú posa l'etiqueta tests-model (útil per forçar-los en una PR de dades o de configuració). És el mecanisme que implementa "el que és car corre quan aporta".
• needs: — encadena els jobs: si el linter falla, no gastem temps (ni minuts de runner) a descarregar dades.

I una fila que falta expressament: construir i publicar la imatge Docker. Això ja no és integració sinó lliurament, i és exactament el tema de la propera lliçó.

• Instal·lar a la CI amb pip install pandas scikit-learn a pèl. El runner resoldrà les versions del dia i els teus tests validaran un entorn que no és el de producció. Sempre des de requirements.lock.
• Tests de comportament massa estrictes. Exigir monotonicitat exacta a un RandomForest produeix tests intermitents (flaky), i un test flaky acaba ignorat — cosa que és pitjor que no tenir-lo. Fes servir toleràncies petites i clients "tipus" representatius.
• Validar les dades només a la CI. La mostra de la CI vigila el contracte, però les dades fresques de producció es validen al pipeline (stage preparar_dades i, des de 05-03, al flow de scoring). Si només valides la mostra, dilluns entrenaràs amb el que sigui que hagi arribat.
• Posar les credencials de DVC al YAML "només per provar". Queden a l'historial de Git per sempre. Secrets de GitHub des del primer minut, i rota la clau si mai s'ha escapat.
• Llindar de mètriques contra un test set que canvia. Si cada execució fa el seu propi split, dos candidats mai no es comparen sobre el mateix terreny. El test set és un artefacte versionat amb DVC, i punt.
• Convertir la CI en un mur de 40 minuts. Si cada push triga mitja hora, la gent agrupa canvis enormes o busca com saltar-se-la. Protegeix el cicle ràpid (nivells 1-2 de la piràmide en menys de 5 minuts) i empeny el que és car cap a les PRs.
• Consell: quan un bug arribi a producció malgrat la CI, la retrospectiva correcta no és "qui ha estat?" sinó "quin test faltava?". Afegeix aquell test al mateix fix. Així creix una suite que reflecteix les fallades reals del teu sistema.

En Marc proposa afegir la feature dies_des_ultim_tiquet. Escriu dos tests unitaris per a ella a l'estil de test_features.py: (a) un client que mai no ha obert cap tiquet (el camp font data_ultim_tiquet és nul) ha de produir un valor sentinella de 9999, no un nul ni un error; (b) el valor mai no pot ser negatiu encara que arribi una data futura per error de dades.

Amplia esquema_clients amb dues comprovacions noves: (a) una columna pais amb categories permeses ["ES", "PT", "AD"] i sense nuls; (b) una expectativa a nivell de dataset: cap client amb descompte_actiu = 1 no pot tenir pla = "basic" (el descompte només s'aplica als plans de pagament superiors). Escriu només el fragment d'esquema.

El job tests-model triga 8 minuts i l'equip es queixa que les PRs de documentació (canvis només a docs/) també l'esperen. L'esperen de debò, amb el workflow tal com està escrit? Raona la resposta mirant el YAML i explica quin paper hi juga dorny/paths-filter.

Exercici 1

La clau de l'apartat (a) és el doble assert: no n'hi ha prou amb no fallar, cal comprovar el sentinella concret i l'absència de nuls (un nul aquí trencaria scikit-learn més tard, lluny de l'origen del problema). A (b), el test fixa la decisió de disseny (clip(lower=0)) igual que vam fer amb ratio_tickets.

Exercici 2

i a la llista checks de l'esquema:

La segona és una regla de negoci entre columnes: no es pot expressar com a check d'una sola columna, per això va als checks a nivell de DataFrame. Aquest tipus de regla és la que detecta corrupcions lògiques que els tipus i els rangs no veuen.

Exercici 3

No l'esperen (gairebé): el job arrenca, però dorny/paths-filter avalua els fitxers tocats per la PR i, com que docs/** no encaixa amb el filtre src/**, la sortida steps.canvis.outputs.src és 'false'. Tots els passos pesats porten if: sobre aquesta sortida (i sobre l'etiqueta tests-model), així que se salten: el job acaba en segons havent fet només el checkout i el filtre. El cost real d'una PR de docs és el job ràpid de lint i tests, que sí que corre sempre — i això és correcte: fins i tot una PR de docs pot trencar un import si toca un fitxer de més.

La CI de cineclick-churn ja no depèn de la memòria de ningú: cada push passa linter i tests de codi en minuts; cada PR cap a main valida a més el contracte de dades amb pandera sobre una mostra versionada; i quan el canvi toca src/, el candidat demostra que entrena (fum), que raona (invariància respecte a id_client, direccionalitat de tiquets_suport) i que rendeix (recall ≥ 0.60 i precision ≥ 0.50 contra el test set versionat — el criteri de negoci del mòdul 3 convertit en codi que bloqueja merges). La piràmide completa, amb el que és barat corrent sempre i el que és car corrent quan aporta. Però fixa't on acaba: en un tic verd. El codi validat continua sense arribar a producció tot sol — la imatge encara es construeix en un portàtil i el kubectl apply encara es tecleja. La lliçó següent tanca aquest forat amb el lliurament continu, i amb una particularitat que és ML pur: a CineClick no hi ha un pipeline de desplegament, n'hi ha dos — un per al servei i un altre per al model — i confondre'ls surt car.