--- language: pt library_name: sklearn tags: - tabular-classification - churn - scikit-learn --- # Telco Churn — modelo de risco de saída (EDSB 2026, Grupo 1) ## Objetivo Estimar a probabilidade de um cliente de telecomunicações sair, P(churn), para que a equipa de retenção contacte primeiro os clientes com maior **perda esperada = P(churn) × CLTV**. O repositório tem dois modelos, ambos usados pela app Gradio do projeto: - `priority_model.joblib` — **modelo de priorização**, treinado só com clientes estabelecidos (tenure > 3). É o que pontua e ordena os clientes na app (cliente individual e lote). - `final_model.joblib` — **modelo core**, treinado com todos os tenures (população do enunciado). É o que se compara com o Churn Score IBM; nos clientes novos (tenure ≤ 3) dá apenas um valor indicativo, porque extrapola. ## Dados - **Fonte:** dataset sintético *Telco Customer Churn* da IBM (5 ficheiros: demographics, location, population, services, status), um único extrato do 3.º trimestre, Califórnia. - **7 043 clientes.** Validados na ingestão por contratos de dados (pandera): esquema, chaves, domínios, regras de negócio e estatísticas (`src/telco_churn/schemas.py`). - **População de modelação:** Churned + Stayed (6 589 clientes, 28,4% de churn). Os 454 *Joined* (1 a 3 meses de casa) não têm resposta e não são usados no treino. - **Divisão:** 80% treino / 20% holdout, estratificada, ao nível do cliente (`random_state=42`). ## Features 32 variáveis originais (perfil, contrato e faturação, serviços, localização) e 4 derivadas, calculadas linha a linha: nº de serviços adicionais, média histórica da fatura, diferença entre a fatura atual e a média, e se houve reembolso. **Excluídas:** colunas que codificam o resultado (Customer Status, Churn Label/Value/Category/ Reason), saídas de outros modelos (Churn Score, CLTV), Satisfaction Score (suspeita de ser registada no contexto da saída: com ela o AUC sobe para 0,996, o que indica *leakage*) e colunas redundantes ou de alta cardinalidade (City, Zip Code, etc.). ## Seleção do modelo Nove modelos (regressão logística, árvore, kNN, MLP, Random Forest, Extra Trees, Gradient Boosting, Soft Voting, Stacking) afinados com `RandomizedSearchCV` e comparados no mesmo 5-fold estratificado, ao lado de três referências: taxa de churn (Dummy), uma **regra de negócio sem ML** (Month-to-Month + tenure ≤ 12 meses + fibra ótica) e o **Churn Score da IBM**. **Regra de parcimónia:** entre o melhor em AUC e os empatados com ele (diferença menor do que um desvio-padrão entre folds), escolhe-se o mais simples. O holdout é usado uma única vez. As métricas desta versão (CV e holdout) estão na secção seguinte, gerada a partir do artefacto no momento da publicação. ## Como usar ```python import joblib from huggingface_hub import hf_hub_download repo = "tvf007/EDSBG1TP2-model" priority = joblib.load(hf_hub_download(repo_id=repo, filename="priority_model.joblib")) # tenure > 3 core = joblib.load(hf_hub_download(repo_id=repo, filename="final_model.joblib")) # bundle["model"]: Pipeline scikit-learn (pré-processador + classificador) # bundle["features"]: colunas de entrada (as derivadas calculam-se com telco_churn.features.add_features) # priority["risk_levels"]: níveis de risco absolutos (médio ≥ 0,30, alto ≥ 0,60) # priority["capacity_cuts"]: P(churn) a partir da qual um cliente estabelecido está no # top 10% / 20% dos clientes estabelecidos ``` Requer `scikit-learn==1.9.1` (a versão com que o artefacto foi gravado). ## Limitações - **Clientes novos.** Os clientes recentes que ficaram são registados como *Joined* e saem da população de treino; os que saíram ficam como *Churned*. Por isso, no treino, quase todos os clientes com tenure ≤ 3 meses saíram, o que é um efeito da forma como os estados foram registados e não um comportamento. Para clientes novos o modelo extrapola; a app mostra um aviso e o projeto usa uma regra de onboarding em vez de P(churn). - **Causalidade do desconto.** O modelo prevê risco, não o efeito de uma ação. A eficácia do desconto usada na app é um pressuposto e deve ser medida com um grupo de controlo. - **Dados sintéticos IBM.** Os padrões podem não se transferir para dados reais. É um único extrato (Q3), sem datas, por isso não há validação temporal. - **Nos clientes estabelecidos, a IBM ordena melhor.** Com tenure > 3, o modelo de priorização tem AUC 0,899 contra 0,939 do Churn Score IBM, e o intervalo de confiança a 95% da diferença (bootstrap emparelhado) não inclui zero. O modelo é publicado porque dá probabilidades calibradas (Brier 0,097 contra 0,234), necessárias para P(churn) × CLTV, e usa só variáveis conhecidas. **Não substitui o Churn Score como ordenação.** O gate do deploy exige bater a Dummy e a regra de negócio, sobreajuste < 0,05, Brier < IBM e níveis de risco calibrados. - **Comparação com a IBM (modelo core, base completa).** O Churn Score da IBM é calculado com informação que não conhecemos. Em ROC AUC o modelo está empatado com ele (diferença dentro do desvio-padrão entre folds); é melhor em PR AUC e muito mais bem calibrado (Brier). - **Importância das variáveis** mostra associação, não causa. ## Publicação Publicado pelo GitHub Actions (`deploy-hf.yml`) **só** depois de a pipeline correr e de todos os testes passarem (contratos de dados, pré-processamento, qualidade do modelo e app). ## Métricas desta versão Seleção: Gradient Boosting tem o maior AUC em CV e é o mais simples entre os empatados (Gradient Boosting, Stacking, Soft Voting). | | AUC CV (± dp) | AUC holdout | PR AUC holdout | Brier holdout | |---|---|---|---|---| | Modelo core: Gradient Boosting | 0.938 ± 0.004 | 0.936 | 0.883 | 0.086 | | Churn Score IBM (benchmark) | 0.942 ± 0.008 | 0.941 | 0.876 | 0.214 | | Modelo de priorização (tenure > 3): Gradient Boosting | 0.909 ± 0.007 | 0.899 | 0.726 | 0.097 | | Churn Score IBM nos mesmos clientes (tenure > 3) | 0.944 ± 0.012 | 0.939 | 0.831 | 0.234 | O modelo de priorização e a sua linha IBM são avaliados no holdout com tenure > 3. Nesses clientes a IBM ordena melhor: diferença de AUC -0.040, IC 95% [-0.063; -0.018] (bootstrap emparelhado). Não é gate do deploy. Nível de risco (absoluto): baixo < 30%, médio 30%–60%, alto ≥ 60%. Prioridade de contacto (capacidade, só clientes estabelecidos, modelo de priorização): top 10% se P ≥ 0.696, top 20% se P ≥ 0.443.