How adwaitsatav/credit-risk-engine works
1. Repository purpose
- This repo is a two-part machine learning system: an offline training pipeline that builds a credit-risk classifier, and an online Streamlit app that serves predictions from the saved artifacts.
2. Primary architectural boundary
- The key split is between training-time code (train_model.py) and runtime inference code (app.py).
- Training produces serialized assets; the app consumes them without retraining.
3. Offline ML pipeline
- train_model.py is responsible for generating or preparing the Lending Club-style synthetic dataset, fitting the model, evaluating it, and persisting outputs.
- The model is a Random Forest classifier from scikit-learn, chosen for tabular credit-risk prediction.
4. Persisted model artifacts
- model.pkl stores the trained classifier.
- model_columns.pkl preserves the exact feature order expected by the model.
- label_encoder.pkl stores categorical encoding state so the app can transform inputs consistently.
- metrics.pkl stores evaluation results for display in the UI.
5. Online inference layer
- app.py is the Streamlit application that acts as the presentation and inference layer.
- It loads the saved artifacts at startup, collects user inputs, transforms them into the trained feature representation, and runs the model to generate a default-risk prediction.
6. Data flow at runtime
- User enters applicant attributes in the Streamlit UI.
- The app encodes/aligns those values to the saved feature schema.
- The model returns a probability and class/risk-band output.
- The app then renders the prediction, risk band, feature importance, and stored metrics.
7. Feature schema and preprocessing contract
- The presence of model_columns.pkl and label_encoder.pkl indicates the app must strictly match the training-time schema.
- This is an important architecture constraint: inference depends on the same categorical encoding and column ordering used during training.
8. User-facing functionality
- The app exposes an interactive credit-risk calculator with adjustable inputs.
- It also surfaces explanatory outputs such as feature importance and model performance metrics to make the decision more interpretable.
9. Technology stack
- Python is the runtime.
- Streamlit provides the web UI and deployment target.
- scikit-learn provides the Random Forest model and evaluation metrics.
- Serialization is handled through Python pickle artifacts.
10. Deployment model
- The README indicates deployment on Streamlit Cloud, so the production boundary is a hosted Streamlit process that loads the prebuilt .pkl files from the repo.
- There is no separate API service, database, or job queue visible in this repository.
11. Operational lifecycle
- To refresh the system, an engineer would rerun train_model.py to regenerate the model and associated artifacts, then redeploy the Streamlit app.
- This means the repository favors a simple, reproducible, file-based ML deployment pattern rather than a microservice architecture.
12. What to draw in an architecture diagram
- A good diagram would show: input form in Streamlit UI → preprocessing/encoding using saved schema → Random Forest inference → risk band + metrics/feature importance displayed back to the user.
- Separately, show the training pipeline feeding the serialized artifacts used by the live app.
Main entry points: metrics.pkl Metrics pickle · model.pkl Model pickle · model_columns.pkl Column schema · label_encoder.pkl Encoder pickle
Components 16
Offline training
Builds the credit-risk model and serializes the reusable artifacts.
- Train model · Orchestrates data preparation, model fitting, evaluation, and persistence.
train_model.py - Prep data · Generates or prepares the Lending Club-style training dataset.
- Fit RF · Trains the Random Forest classifier for credit-risk prediction.
- Evaluate · Computes model performance metrics for later display.
- Save artifacts · Writes the trained model, schema, encoder state, and metrics to disk.
Online inference
Streamlit app that loads saved artifacts and serves predictions.
- Streamlit app · Interactive UI and inference layer for credit-risk prediction.
app.py - Load assets · Reads the saved model, column order, encoder, and metrics at app startup.
- Input form · Collects applicant attributes from the user.
- Encode input · Transforms user values into the trained feature representation.
- Align columns · Matches inference features to the saved training-time column order.
- Predict risk · Runs the saved classifier to produce class and probability outputs.
- Show results · Renders prediction, risk band, feature importance, and metrics.
Saved artifacts
Files persisted by training and consumed at runtime.
- Model pickle · Serialized Random Forest classifier.
model.pkl - Column schema · Persisted feature order expected by the model.
model_columns.pkl - Encoder pickle · Stored categorical encoding state used during inference.
label_encoder.pkl - Metrics pickle · Saved evaluation results displayed in the UI.
metrics.pkl
Connections 18
- Train model → Prep data: orchestrates · Training begins by preparing the dataset.
- Prep data → Fit RF: feeds · Prepared features and target are used to train the classifier.
- Fit RF → Evaluate: produces · The trained model is scored on evaluation metrics.
- Evaluate → Save artifacts: records · Metrics and trained state are written out together.
- Save artifacts → Model pickle: writes · Stores the trained classifier.
- Save artifacts → Column schema: writes · Stores the exact feature order.
- Save artifacts → Encoder pickle: writes · Stores categorical encoding state.
- Save artifacts → Metrics pickle: writes · Stores performance metrics.
- Streamlit app → Load assets: starts with · The app loads serialized assets when it launches.
- Load assets → Model pickle: reads · Loads the classifier for inference.
- Load assets → Column schema: reads · Loads the expected feature schema.
- Load assets → Encoder pickle: reads · Loads the encoding state.
- Load assets → Metrics pickle: reads · Loads metrics for display.
- Input form → Encode input: feeds · User-entered values are transformed for the model.
- Encode input → Align columns: normalizes · Encoded values are aligned to the saved column order.
- Align columns → Predict risk: inputs · Schema-aligned features are passed to the model.
- Predict risk → Show results: outputs · Prediction results are rendered to the user.
- Show results → Metrics pickle: displays · Stored metrics are surfaced in the UI.