The decision is made: alongside the weekly batch for marketing, CineClick needs an online service that, the moment a customer clicks "cancel subscription", returns their churn probability in under 300 ms so product can decide whether to show an offer. In this lesson we build that service with FastAPI: we'll define input and output contracts with Pydantic, load the champion from the registry at startup, expose the /predict, /health, and /version endpoints, and — honoring the mandate from lesson 03-03 — import build_features from the installable package instead of rewriting it. By the end you'll have the service running on your machine with uvicorn, tested from the interactive documentation and from curl, and leaving in the logs the seed of the monitoring that arrives in module 6.

1. Why FastAPI for serving models
2. The service's structure in the repo
3. Pydantic schemas: the input and output contract
4. Loading the model at startup: lifespan
5. The POST /predict endpoint
6. Healthcheck and version: GET /health and GET /version
7. Trying the service: uvicorn, /docs, and curl
8. Structured logging of every prediction

There are many ways to expose a model over HTTP (Flask, Django, a hand-rolled server). FastAPI has become the de facto standard for serving ML in Python for four concrete reasons:

• Typing with Pydantic: you define the input and output as typed Python classes, and FastAPI automatically validates every request against that schema. In an ML service this is gold: the number one cause of absurd predictions in production is a malformed input the model swallows without complaint (a nonexistent plan, a negative tenure). With Pydantic, the invalid request dies at the door with an explanatory 422 error, before ever touching the model.
• Automatic OpenAPI documentation: the service publishes at /docs an interactive interface generated from the schemas. CineClick's product team can see and try the contract without reading a line of Python.
• Native async support: FastAPI runs on an ASGI server (uvicorn) and can handle many concurrent connections. An important nuance for ML: scikit-learn's predict is synchronous CPU-bound code, so we'll declare it in a plain def endpoint (not async def) and FastAPI will run it in a threadpool without blocking the event loop.
• Performance and ergonomics: it's among the fastest in the Python ecosystem and the resulting code is short and readable — you'll see the whole service fits in two files.

We add the dependencies to the project (and freeze them in the lock, as module 2 mandates):

The service lives inside the cineclick_churn package, not in a separate repo. This decision follows directly from 03-03: the service must import build_features from the same package training uses, and keeping them together guarantees both get installed and versioned at once.

Two files: schemas.py defines what goes in and out; main.py defines what gets done with it. Separating them keeps the contract readable on its own.

The input schema mirrors the raw columns of churn_customers.csv (minus customer_id, which travels separately for traceability, and churned, which is what we predict). Notice that the validations encode domain rules, not just types:

Breaking down the decisions:

• ge=0 on tenure_months and support_tickets cuts off negative inputs cold — which, remember, would silently break the ratio_tickets feature (the clip(lower=1) guards against odd divisions, but a tenure of -3 is corrupt data that should never get that far).
• le=168 on weekly_hours: a week has 168 hours; more than that is a bug in the sender, not a very devoted customer.
• Literal[...] on plan and payment_method restricts them to the values the model was trained on. If the business launches the "family" plan tomorrow, the API will return a 422 instead of letting the model hallucinate over a category it never saw — and that 422 is the early alarm that it's time to retrain and update the contract.
• PredictionOutput returns not just the probability but the applied threshold and the model version: every response is self-explanatory and auditable. When we investigate drift in module 6, knowing which version answered each request will be indispensable.

The golden rule of serving: the model is loaded once, when the process starts — never inside the endpoint. Loading from the registry takes seconds; doing it per request would destroy any latency budget. FastAPI offers the lifespan pattern for running code at startup and shutdown:

The resilience note deserves a pause: if the registry doesn't respond at startup, there are two philosophies. The wrong one is to catch the exception, start up "anyway", and return errors on every /predict — a service that looks healthy but can't do its job (a zombie). The right one, and the one we implement, is to fail fast and loud: the raise kills the process with an unambiguous message in the log, and the orchestrator (Docker in 04-03, Kubernetes in 04-04) will detect it and retry or alert. A process that dies noisily gets diagnosed in minutes; a silent zombie, in days.

Step by step:

1. customer.model_dump() turns the (already validated) Pydantic object into a dictionary, and pd.DataFrame([...]) wraps it in a one-row DataFrame — the format build_features expects, identical to training's.
2. build_features imported from the package. This is the moment the 03-03 decision pays off: ratio_tickets = support_tickets / tenure_months.clip(lower=1) is computed with the canonical implementation. If someone improves it tomorrow in features.py, training and serving change together — training/serving skew becomes structurally impossible.
3. predict_proba(X)[0, 1]: row 0 (there's only one), column 1 (probability of the positive class). We return the probability, not just the boolean, because the consumer may want to grade the offer.
4. The threshold is configurable (the CHURN_THRESHOLD environment variable, overridable per request with the threshold query param). The default 0.5 is just the mathematical starting point: the real threshold is a business decision. With the current champion (precision 0.55, recall 0.68), lowering the threshold captures more future churners at the cost of offering discounts to customers who weren't going to leave; raising it does the opposite. Product and finance must pick that point with a cost calculation — the API only needs to allow changing it without redeploying.

• /health doesn't just answer "I'm alive": it checks that the model is in memory. This nuance matters because it's the endpoint Docker (04-03) and Kubernetes probes (04-04) will call to decide whether the container receives traffic or gets restarted. A healthcheck that lies is worse than no healthcheck.
• /version answers the quintessential operational question: "which model is this serving RIGHT NOW?". When we moved the @champion alias in 03-02, we said rollback was "moving an alias"; /version is how you verify, after restarting the service, that the change took effect.

With the MLflow server running (the sqlite one from module 3), we start up:

In the log you'll see Loading model from models:/churn-cineclick@champion ... followed by Model churn-cineclick v2 loaded. — the lifespan in action. Now open http://localhost:8000/docs: FastAPI has generated the interactive documentation with the three endpoints, the schemas with their constraints (tenure_months >= 0, the allowed plan values), and a Try it out button to fire requests from the browser. This /docs is the contract you hand to the product team.

Let's try curl with a fictional customer of risky profile (short tenure, low usage, tickets):

Response:

And the validation in action — a plan that doesn't exist:

The model never even noticed. That's Pydantic working the door.

A note on security, without straying: this service will run on CineClick's internal network, but even so the bare minimum is a simple API key (an X-API-Key header verified by a FastAPI dependency against a secret held in an environment variable). Serious enterprise authentication — OAuth2, mTLS, gateway — is the company platform's territory, not this lesson's; what matters is that the endpoint isn't left open to anyone, not even "temporarily".

You've already seen it in the endpoint: every prediction emits a log line with structured fields, not a free-form sentence. We configure the output as JSON so machines can process it:

Each prediction log line contains: the input's hash (via input_hash over the payload — traceable without dumping customer data in plain text), probability, prediction, model version, and latency in ms. It looks like little, but it's exactly the seed of module 6's monitoring: with these logs accumulated we'll be able to plot the probability distribution over time (drift, 06-02), the p95 latency (06-01), and the request volume. The rule: if you don't log it from day one, it won't exist when you need it.

• Mistake: loading the model inside the endpoint. Every request would pay seconds of registry loading. The model is loaded once in the lifespan and lives in memory.
• Mistake: reimplementing the features in the API. "It's just a division" — until someone changes the clip in features.py and serving keeps the old version: silent training/serving skew, the most expensive bug to detect. At CineClick it's forbidden by the 03-03 decision: always from cineclick_churn.features import build_features.
• Mistake: starting without a model and returning errors per request. The zombie service. Fail fast at startup (the raise in the lifespan) and let the orchestrator do its job.
• Mistake: using async def on the prediction endpoint. predict_proba is synchronous CPU work: inside async def it would block the event loop and sink concurrency. With def, FastAPI moves it to the threadpool automatically.
• Mistake: accepting any string in the categorical fields. Without Literal, a plan="Basic" (with a capital letter) would reach the model as an unknown category. The schema must reflect the exact vocabulary of training.
• Tip: always return the model version in the response. It costs one field and turns every response into auditable evidence.
• Tip: treat the threshold as business configuration, not a code constant. Going from 0.5 to 0.4 shouldn't require a deployment.

Product asks for a POST /predict-batch endpoint that receives a list of customers (100 at most) and returns a list of predictions, to score all the attendees of a retention webinar in one go. Implement it reusing the existing schemas. Hint: predict_proba accepts an N-row DataFrame.

Write a test with FastAPI's TestClient (in tests/test_api.py) verifying that a request with tenure_months: -5 receives a 422 without ever invoking the model. Hint: you can monkeypatch state so the tests don't depend on the registry.

Right now, if MLflow is down when the service starts, the process dies (correct). But what happens if MLflow goes down afterwards, with the service already up? Reason through it: (a) does /predict keep working?, (b) what does /health return?, (c) is this behavior acceptable?

Solution 1

The essential part: one single call to build_features and to predict_proba for the N rows, not a loop of N predictions — we'll quantify the performance difference in 04-05. The max_length=100 protects the service from someone sending it the entire customer base over HTTP (that's what the batch from 04-01 is for).

Solution 2

If Pydantic let the input through, ForbiddenModel.predict_proba would raise the AssertionError and the test would fail with a clear message. This test will join the CI in lesson 05-01.

Solution 3

(a) Yes. The model is already in memory; /predict never touches MLflow on the request path. The registry being down doesn't affect in-flight traffic — a virtue of the "load at startup" pattern. (b) /health returns 200 ok, because it only checks that the model is in memory, not connectivity to MLflow — and that's correct: the healthcheck must measure the ability to do the job (predict), not the health of dependencies it no longer needs. (c) Acceptable, with one caveat: new startups (a restart, a fresh replica when scaling out) will fail while MLflow is down. It's a known risk we note down for 04-03: there we'll discuss the alternative of baking the model into the image precisely to remove this startup dependency, and why CineClick still chooses the registry.

Laura's model now takes requests. The service has an explicit contract (Pydantic validates domain, not just types), loads the champion exactly once from models:/churn-cineclick@champion with a fail-fast policy, predicts by importing build_features from the single source — zero duplicated logic —, exposes /health and /version so machines and humans know what's running, and logs every prediction as JSON that module 6 will turn into monitoring. All of this works... on your machine, with your Python 3.11.9, your installed requirements.lock, and your environment variable pointing at your MLflow. The production server has none of that, and "install it by hand and cross your fingers" is exactly the kind of process this course came to eliminate. The next lesson freezes the whole service — operating system, Python, dependencies, and code — into a Docker image that runs identically anywhere: "works on my machine" is about to stop being an excuse.