Loan-Predictor: How a Notebook Model Becomes a Real Loan Decision Product
From CatBoost training to FastAPI validation and a Streamlit front end, this repo shows the full path from ML experiment to a user-facing decision workflow.
- Loan-Predictor is really about shipping a decision workflow, not just training a classifier.
- The repo’s strongest idea is the strict path from raw form inputs to a validated 16-feature inference contract.
- FastAPI and Pydantic act as guardrails, while Streamlit makes uncertainty visible instead of hiding it.
- This is more complete than a typical notebook demo, but it still reads like a polished prototype rather than an audited lending system.
Not Just a Prediction, a Decision Screen
Most loan demo apps stop at a binary answer. This one does more work. It surfaces approval probability, rejection probability, confidence, risk score, and risk level, which makes the output feel like something a product team could actually put in front of a user.
That matters because loan decisions are rarely just yes or no. A useful system has to show uncertainty, make the output interpretable, and leave a paper trail for how the result was formed. Loan-Predictor understands that the user experience is part of the model experience.
Why This Repo Feels More Finished Than Most ML Demos
The repo separates the work into layers. The notebook handles exploration and training. FastAPI handles inference. Streamlit handles the interface. CSS handles the visual polish. That split is the difference between a notebook project and a deployable product template.
| Typical ML demo | Loan-Predictor |
|---|---|
| Trains in a notebook and prints a class label | Trains in a notebook, then serves predictions through an API and UI |
| Returns yes or no | Returns probability, confidence, risk score, and risk level |
| Accepts loosely shaped input | Validates input with a strict schema before inference |
| Uses default widgets and plain output | Uses a custom dashboard with gauges and probability bars |
The Inference Contract: 16 Inputs, One Strict Path
The backend’s core job is not glamorous, but it is decisive. Raw form values are validated, encoded, scaled, and aligned into the exact 16-feature vector the model expects. Without that contract, the model would be brittle, and the app would be easy to misuse.
# Conceptual flow from the backend
input_data = LoanInput(**form_payload)
encoded = _encode_input(input_data)
scaled = scaler.transform([encoded])
prediction = model.predict(scaled)
probability = model.predict_proba(scaled)[0]
result = {
"risk_level": "High",
"risk_score": 0.81,
"confidence": 0.87,
"summary": "Likely rejection"
}That shape is the story. The application is not handing a model random JSON and hoping for the best. It is enforcing structure, keeping the feature order stable, and making sure the model sees a predictable numeric representation every time.
FastAPI as the Guardrail
The backend uses FastAPI with Pydantic validation and startup-time model loading. That is a practical choice, because it reduces request overhead and blocks bad input before it reaches the classifier. The service is built to be hard to misuse.
| Backend concern | What Loan-Predictor does |
|---|---|
| Model loading | Loads the CatBoost model and scaler once at startup |
| Input safety | Uses Pydantic field validation to reject invalid values |
| Latency | Keeps inference lean by avoiding repeated setup work |
| Reliability | Treats preprocessing as part of the service, not a loose script |
This is the part many demos skip. They focus on model accuracy, then paste the model behind a route. Here, the API is part of the product design. It controls the shape of the data, not just the shape of the response.
The UI Makes Uncertainty Visible
The Streamlit front end does not hide the model behind a sterile form. It turns the output into a dashboard, with a custom gauge and a probability bar that separate approval from rejection. That is a good instinct for a lending workflow, where confidence matters as much as the label.
The styling work also matters. The interface is tuned like a financial product, not a classroom demo. It gives the repo a sense of finish that makes the backend feel more credible.
What This Repo Teaches About Shipping ML
The strongest lesson here is simple: production-adjacent ML needs more than a trained model. It needs validation, a deterministic inference path, a user interface that explains uncertainty, and enough presentation polish that the system feels trustworthy.
| Shipping principle | Why it matters |
|---|---|
| Validate before inference | Bad inputs fail early instead of becoming bad predictions |
| Keep preprocessing explicit | Feature drift is easier to spot and debug |
| Expose probabilities | Users can see uncertainty instead of guessing |
| Separate notebook from service | Research stays flexible while deployment stays stable |
Loan-Predictor is a solid template for that mindset. It does not overclaim, and it does not pretend the notebook is the product. It shows the work required to make the model usable.
What It Is, and What It Isn’t
This is a polished prototype or portfolio-grade starter, not an audited lending system. The repo appears light on tests, CI, and production data infrastructure. That is fine, as long as we name the category correctly.
What it gets right is the essential shape of a real ML product. It draws a line between training and inference, treats input validation as a first-class concern, and gives the user a meaningful explanation of the output.