feat(ml): build ML-powered churn prediction with intervention automation

[retkatmun]

Summary

Implements issue #936 – ML-powered churn prediction with intervention automation.

What changed

Python ML Service ()

• main.py rebuilt as a production FastAPI app:
  • GET /health – liveness/readiness probe
  • POST /v1/churn/predict – single prediction with feature store + drift detection
  • POST /v1/churn/predict/batch – up to 500 subscribers per call
  • POST /v1/churn/forecast – revenue forecast (Holt smoothing + confidence intervals)
  • POST /v1/interventions/evaluate – stateless intervention recommendation engine
  • POST /v1/models/retrain – hot-reloads weights without restart
  • GET /v1/models/status – active model metadata
• models.py upgraded: GradientBoostingClassifier (calibrated, sklearn) with deterministic heuristic fallback; Holt double-exponential smoothing forecast
• model_registry.py: versioned JSON registry, runtime counters, safe retraining pipeline
• requirements.txt: added numpy==1.26.4 and scikit-learn==1.4.2

TypeScript Backend (backend/services/analytics/)

• prediction.ts (new): production client with retry (3×, jittered back-off), 10 s timeout, in-process circuit breaker (5 failures → 30 s open), full camelCase ↔ snake_case mapping
• interventionService.ts rewritten: pluggable InterventionDispatcher interface, LogDispatcher, CompositeDispatcher, dryRun mode, schedule() helper, full InterventionRecord audit log

Tests

• ml-service/tests/test_churn_prediction.py: 60+ Python tests (models, registry, all 8 endpoints, feature client with mocked Redis)
• backend/services/analytics/__tests__/prediction.test.ts: 35/35 TypeScript tests passing (retry logic, circuit breaker, dryRun, dispatchers, scheduler, end-to-end round-trip)

Documentation

• docs/churn-prediction-ml.md: full API reference, TypeScript usage examples, intervention automation guide, feature engineering table, performance benchmarks

Acceptance criteria

• Feature implemented with full functionality
• Unit tests added with >80% coverage
• Integration tests for critical paths
• No regression introduced (55 existing tests still pass)
• Documentation updated
• Performance benchmarks documented

Testing

# TypeScript (35/35 pass)
npx jest --config jest.backend.config.js \
  backend/services/analytics/__tests__/prediction.test.ts \
  --no-coverage --forceExit

# Python
cd ml-service && pip install -r requirements.txt pytest httpx
pytest tests/test_churn_prediction.py -v

Closes #936

[drips-wave]

@retkatmun Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits