Credit Scoring and Pipeline Domain - Runtime Scoring Contract, Global-Score Conversion, and Fail-Closed Behavior
backend/src/usecase/credit_score_runtime.py
backend/src/usecase/credit_scoring.py
backend/src/ml/credit_model.py
backend/src/ml/lita_global_score_converter.py
backend/src/interface/http_endpoints.py
backend/src/interface/schemas.py
backend/tests/usecase/test_credit_score_runtime.py
backend/tests/ml/test_lita_global_score_converter.py
Overview
This domain turns a stored housing application into a runtime credit decision payload with calibrated metadata, coverage reporting, reason codes, and a Lita global score. The API layer exposes two read endpoints for application scoring and one conversion endpoint for transforming an arbitrary source score into the Lita global score scale.
The runtime scorer does not accept partial or malformed model output. It calls Vertex AI, validates the returned contract, applies coverage honesty adjustments, computes legacy and global score translations, derives risk flags, and appends a scoring artifact for traceability. If the Vertex response does not match the expected Lita contract, the scorer raises an error instead of fabricating a score.
Architecture Overview
flowchart TD
subgraph HTTPInterface[HTTP Interface Layer]
CreditScoreHandler[get_application_credit_score]
GlobalScoreHandler[get_application_global_score]
ScoreConvertHandler[score_convert_endpoint]
end
subgraph RuntimeScoring[Runtime Scoring Domain]
ScoreApplication[score_housing_application]
BuildFeatures[_build_features]
ScoreWithVertex[_score_with_vertex]
ValidateContract[_validate_risk_engine_contract]
ApplyHonesty[apply_coverage_honesty_policy]
CalibratePD[calibrate_pd]
ConvertLegacy[pd_to_legacy_score]
ConvertGlobal[pd_to_global_score]
DeriveFlags[_derive_risk_flags]
StoreArtifact[_store_score_artifact]
end
subgraph GlobalConversion[Global Score Conversion]
SourceScoreConvert[_convert_source_score_to_global]
ConfidenceScore[confidence_score]
TargetMapping[target_mapping]
GlobalBand[_global_band]
end
subgraph ExternalSystems[External Systems]
VertexAI[Vertex AI Endpoint]
ArtifactFile[LITA score artifact file]
ApplicationRepo[Housing application repository]
end
CreditScoreHandler --> ApplicationRepo
GlobalScoreHandler --> ApplicationRepo
CreditScoreHandler --> ScoreApplication
GlobalScoreHandler --> ScoreApplication
ScoreConvertHandler --> SourceScoreConvert
ScoreApplication --> BuildFeatures
ScoreApplication --> ScoreWithVertex
ScoreWithVertex --> VertexAI
ScoreWithVertex --> ValidateContract
ScoreApplication --> CalibratePD
ScoreApplication --> ApplyHonesty
ScoreApplication --> ConvertLegacy
ScoreApplication --> ConvertGlobal
ScoreApplication --> DeriveFlags
ScoreApplication --> StoreArtifact
StoreArtifact --> ArtifactFile
ScoreConvertHandler --> ConfidenceScore
ScoreConvertHandler --> TargetMapping
ScoreConvertHandler --> GlobalBand
Runtime Scoring Contract
HTTP interface
Get Application Credit Score
[!IMPORTANT] The runtime scorer is fail-closed. A missing prediction list, unsupported
reason_codes, mismatchedbreakdownkeys, or missingmeta.model_versioncausesscore_housing_applicationto raiseValueErrorrather than returning a degraded estimate.
backend/src/interface/http_endpoints.py
This handler loads a housing application by application_id, scores it with score_housing_application, and returns the full runtime response contract. It requires the application detail dependency before the handler runs, so authenticated access is enforced at the dependency layer.
{
"title": "Get Application Credit Score",
"description": "Returns the runtime Lita credit score, calibrated metadata, coverage flags, reason codes, and global-score projection for a stored housing application.",
"method": "GET",
"baseUrl": "<BackendApiBaseUrl>",
"endpoint": "/v1/applications/{application_id}/credit-score",
"headers": [
{
"key": "Authorization",
"value": "Bearer <token>",
"required": true
},
{
"key": "Accept",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "application_id",
"type": "int",
"required": true,
"description": "Housing application identifier"
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"application_id\": 1,\n \"score\": 742,\n \"score_band\": \"B\",\n \"provider\": \"lita\",\n \"model_version\": \"lita-risk-v1.0.0\",\n \"featureset_version\": \"ApplicantFeatureSetV3\",\n \"calibration_version\": \"corridor-v2-us-gb\",\n \"confidence\": 0.88,\n \"data_coverage\": {\n \"institutions_linked\": 1,\n \"accounts_linked\": 2,\n \"days_covered\": 90,\n \"salary_detected\": true,\n \"coverage_score\": 0.78,\n \"coverage_flags\": [\n \"SHORT_HISTORY\"\n ]\n },\n \"reason_codes\": [\n \"LOW_LIQUIDITY_BUFFER\"\n ],\n \"breakdown\": {\n \"affordability\": 0.44,\n \"stability\": 0.51,\n \"bureau_strength\": 0.49,\n \"liquidity\": 0.3,\n \"risk_signals\": 0.67\n },\n \"lita_global_score\": 818,\n \"global_band\": \"B\",\n \"risk_flags\": [\n {\n \"code\": \"OVERDRAFT_STRESS\",\n \"severity\": \"medium\",\n \"display_text\": \"Overdraft events indicate liquidity stress.\"\n }\n ],\n \"target_scale\": null,\n \"target_score\": null,\n \"target_confidence\": null\n}"
}
}
}
Get Application Global Score
backend/src/interface/http_endpoints.py
This handler uses the same runtime scorer but returns only the global-score view. It keeps the calibrated metadata, coverage data, reason codes, breakdown, and risk flags, but omits the legacy score and target conversion fields.
{
"title": "Get Application Global Score",
"description": "Returns the Lita global score and calibrated runtime metadata for a stored housing application.",
"method": "GET",
"baseUrl": "<BackendApiBaseUrl>",
"endpoint": "/v1/applications/{application_id}/global-score",
"headers": [
{
"key": "Authorization",
"value": "Bearer <token>",
"required": true
},
{
"key": "Accept",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "application_id",
"type": "int",
"required": true,
"description": "Housing application identifier"
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"application_id\": 1,\n \"lita_global_score\": 818,\n \"global_band\": \"B\",\n \"confidence\": 0.88,\n \"data_coverage\": {\n \"institutions_linked\": 1,\n \"accounts_linked\": 2,\n \"days_covered\": 90,\n \"salary_detected\": true,\n \"coverage_score\": 0.78,\n \"coverage_flags\": [\n \"SHORT_HISTORY\"\n ]\n },\n \"reason_codes\": [\n \"LOW_LIQUIDITY_BUFFER\"\n ],\n \"breakdown\": {\n \"affordability\": 0.44,\n \"stability\": 0.51,\n \"bureau_strength\": 0.49,\n \"liquidity\": 0.3,\n \"risk_signals\": 0.67\n },\n \"provider\": \"lita\",\n \"model_version\": \"lita-risk-v1.0.0\",\n \"featureset_version\": \"ApplicantFeatureSetV3\",\n \"calibration_version\": \"corridor-v2-us-gb\",\n \"risk_flags\": [\n {\n \"code\": \"OVERDRAFT_STRESS\",\n \"severity\": \"medium\",\n \"display_text\": \"Overdraft events indicate liquidity stress.\"\n }\n ]\n}"
}
}
}
Convert Score to Global Score
backend/src/interface/http_endpoints.py
This endpoint converts an incoming source score into the Lita global scale. It also blends bureau primitives when present, computes confidence from coverage and bureau parse confidence, and returns an optional target-scale projection.
{
"title": "Convert Score to Global Score",
"description": "Converts a source score to the Lita global score scale, blends bureau primitives when available, and returns target-scale mapping metadata.",
"method": "POST",
"baseUrl": "<BackendApiBaseUrl>",
"endpoint": "/v1/score-convert",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
},
{
"key": "Accept",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"source_score\": 742,\n \"source_scale_min\": 300,\n \"source_scale_max\": 850,\n \"bureau_primitives\": {\n \"score_value\": 730,\n \"score_scale_min\": 300,\n \"score_scale_max\": 850,\n \"parse_confidence\": 0.92\n },\n \"banking_summary_features\": {\n \"coverage_score\": 0.76,\n \"days_covered\": 90\n },\n \"target_scale\": \"FICO_300_850\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"lita_global_score\": 814,\n \"global_band\": \"B\",\n \"confidence\": 0.84,\n \"target_scale\": \"FICO_300_850\",\n \"target_score\": 746,\n \"target_confidence\": 0.84\n}"
}
}
}
backend/src/interface/http_endpoints.py
| Method | Description |
|---|---|
get_application_credit_score |
Loads a housing application, scores it with score_housing_application, and returns CreditScoreResponse. |
get_application_global_score |
Loads a housing application, scores it with score_housing_application, and returns GlobalScoreResponse. |
score_convert_endpoint |
Converts a source score into the Lita global score scale and returns ScoreConvertResponse. |
get_application_score |
Thin wrapper that forwards to get_application_credit_score. |
Runtime scoring flow
sequenceDiagram
participant Client
participant Http as HTTP Endpoint
participant Repo as Housing Application Repository
participant Runtime as score_housing_application
participant Vertex as Vertex AI Endpoint
participant Converter as lita_global_score_converter
participant Store as Artifact File
Client->>Http: GET application credit score
Http->>Repo: get_housing_application
Repo-->>Http: HousingApplication
Http->>Runtime: score_housing_application
Runtime->>Runtime: _build_features
Runtime->>Vertex: endpoint.predict
Vertex-->>Runtime: predictions
Runtime->>Runtime: _validate_risk_engine_contract
Runtime->>Converter: calibrate_pd
Runtime->>Converter: apply_coverage_honesty_policy
Runtime->>Converter: pd_to_legacy_score
Runtime->>Converter: pd_to_global_score
Runtime->>Runtime: _derive_risk_flags
Runtime->>Store: _store_score_artifact
Runtime-->>Http: CreditScoreEstimate
Http-->>Client: CreditScoreResponse
Runtime scoring behavior
| Step | Code path | Behavior |
|---|---|---|
| Application lookup | get_housing_application |
Rejects non-positive ids with ValueError; the credit-score handler maps that to HTTP 400. |
| Vertex call | _score_with_vertex |
Calls aiplatform.init, resolves the endpoint name from environment, and sends one flattened feature object. |
| Contract validation | _validate_risk_engine_contract |
Accepts only a dict prediction with bounded PD values, allowlisted reason codes, exact breakdown keys, and meta.model_version. |
| PD calibration | calibrate_pd |
Uses _CORRIDOR_CALIBRATION_REGISTRY keyed by {product_type}:{corridor_cluster} and returns a calibrated PD plus calibration_version. |
| Coverage honesty | apply_coverage_honesty_policy |
Uplifts PD when coverage is low and adds SCORE_CAP_UNLINKED_ACCOUNTS when unlinked accounts are suspected for lending products. |
| Legacy score | pd_to_legacy_score |
Converts calibrated PD into the 300–850 legacy score range. |
| Global score | pd_to_global_score |
Converts calibrated PD into the 0–1000 Lita global score scale. |
| Risk flags | _derive_risk_flags |
Builds structured flags from coverage, liquidity, transfer, debt load, and delinquency signals. |
| Artifact write | _store_score_artifact |
Appends a JSON Lines record to the configured score artifact file. |
Score banding
| Function | Thresholds |
|---|---|
_score_band |
A >= 750, B >= 700, C >= 650, D >= 600, E < 600 |
_global_band |
A >= 850, B >= 750, C >= 650, D >= 550, E < 550 |
backend/src/usecase/credit_score_runtime.py
CreditScoreEstimate
This dataclass is the runtime output consumed by the HTTP layer. It carries the calibrated score, the Lita global score, the model and calibration metadata, coverage information, reason codes, breakdown weights, and optional target-scale projections.
| Property | Type | Description |
|---|---|---|
score |
int |
Legacy credit score in the 300–850 range. |
score_band |
str |
Legacy band from _score_band. |
provider |
str |
Fixed to lita in the runtime scorer. |
model_version |
str |
Vertex model version returned in meta.model_version. |
featureset_version |
str |
Fixed to ApplicantFeatureSetV3. |
calibration_version |
str |
Version returned by calibrate_pd. |
confidence |
float |
Calibrated confidence returned by confidence_score. |
data_coverage |
Dict[str, Any] |
Coverage summary with institutions, accounts, days, salary detection, coverage score, and coverage flags. |
reason_codes |
list[str] |
Allowlisted model and policy reason codes. |
breakdown |
Dict[str, float] |
Model breakdown with the exact five keys enforced by _validate_risk_engine_contract. |
lita_global_score |
int |
Global score in the 0–1000 range. |
global_band |
str |
Global band from _global_band. |
risk_flags |
list[dict[str, str]] |
Structured risk flags derived from runtime features. |
target_scale |
`str \ | None` |
target_score |
`int \ | None` |
target_confidence |
`float \ | None` |
_RiskEngineOutput
This internal dataclass mirrors the raw Vertex contract after validation.
| Property | Type | Description |
|---|---|---|
pd_p50_12m |
float |
Median annualized probability of default returned by Vertex. |
pd_p90_12m |
float |
Upper-tail probability of default returned by Vertex. |
reason_codes |
list[str] |
Reason codes returned by Vertex. |
breakdown |
Dict[str, float] |
Five-part breakdown with exact required keys. |
model_version |
str |
Version string from Vertex metadata. |
Module functions
| Function | Description |
|---|---|
score_housing_application |
End-to-end runtime scoring pipeline from HousingApplication to CreditScoreEstimate. |
_score_with_vertex |
Flattens features, resolves the Vertex endpoint, predicts once, and validates the contract. |
_validate_risk_engine_contract |
Enforces the strict Vertex response schema and raises ValueError on mismatch. |
_build_features |
Builds the runtime feature dictionary from application data and connected accounts. |
_canonicalize_banking |
Normalizes heterogeneous connected-account payloads into canonical account and transaction objects. |
_derive_risk_flags |
Converts feature conditions and reason codes into structured risk flags. |
_apply_coverage_adjustments |
Applies coverage-based PD and score adjustments and augments reason codes. |
_confidence |
Wraps confidence_score for the runtime feature set. |
_store_score_artifact |
Writes the runtime artifact JSON line to LITA_SCORE_ARTIFACT_PATH or the default temp file. |
_target_score_from_global |
Delegates to target_mapping for optional target-scale projections. |
_score_band |
Maps the legacy score to a band label. |
_global_band |
Maps the global score to a band label. |
_resolve_endpoint_name |
Resolves the Vertex endpoint from VERTEX_CREDIT_ENDPOINT_NAME or VERTEX_CREDIT_ENDPOINT_ID. |
_require_project_id |
Requires PROJECT_ID or GCP_PROJECT_ID. |
_load_fx_rates |
Loads FX overrides from LITA_FX_RATES_JSON and falls back to built-in rates. |
_to_iso_date |
Parses ISO-like dates used in transaction records. |
_to_usd |
Converts amounts into USD using the active FX map. |
_employment_status_code |
Converts employment status text into the numeric feature used by the model. |
Vertex contract enforcement
| Vertex field | Required rule | Failure mode |
|---|---|---|
pd_p50_12m |
Numeric and within [0, 1] |
ValueError("pd_p50_12m must be numeric in [0,1]") |
pd_p90_12m |
Numeric, within [pd_p50_12m, 1] |
ValueError(...) |
reason_codes |
List of strings, max 6, all allowlisted | ValueError(...) |
breakdown |
Dict with exactly affordability, stability, bureau_strength, liquidity, risk_signals |
ValueError(...) |
meta.model_version |
Required string | ValueError("meta.model_version is required") |
meta.corridor_cluster |
Optional string when present | ValueError(...) |
Coverage flags and reason codes
Coverage flags from _build_features
| Flag | Trigger |
|---|---|
POSSIBLE_UNLINKED_ACCOUNTS |
Coverage score falls below 0.55. |
SHORT_HISTORY |
days_covered < 60. |
INCOME_UNVERIFIED |
Income is above 5000 and salary is not detected. |
HIGH_EXTERNAL_TRANSFER_OUT |
External transfer out share exceeds 0.4. |
Allowlisted reason codes from _REASON_CODE_ALLOWLIST
| Code |
|---|
INSUFFICIENT_LIABILITY_VISIBILITY |
LOW_LIQUIDITY_BUFFER |
INSUFFICIENT_DATA_COVERAGE |
HIGH_SPEND_TO_INCOME |
INCOME_INSTABILITY |
RECENT_DELINQUENCY |
HIGH_BUREAU_UTILIZATION |
MULTIPLE_RECENT_INQUIRIES |
RECENT_NEW_CREDIT |
NEGATIVE_BALANCE_PATTERN |
OVERDRAFT_ACTIVITY |
RETURNED_PAYMENTS |
UNVERIFIED_INCOME |
POSSIBLE_UNLINKED_ACCOUNTS |
LIMITED_CREDIT_HISTORY |
HIGH_RISK_TX_PATTERN |
Structured risk flags from _derive_risk_flags
| Code | Severity | Trigger |
|---|---|---|
NO_BANK_DATA |
high |
accounts_linked_count == 0 |
INSUFFICIENT_HISTORY |
high |
days_covered < 60 |
OVERDRAFT_STRESS |
medium |
overdraft_events_90d > 0 |
HIGH_EXTERNAL_TRANSFERS |
medium |
external_transfer_out_share > 0.40 |
HIGH_DEBT_PAYMENT_LOAD |
high |
Debt payment load exceeds 35% of income |
RECENT_DELINQUENCY |
high |
RECENT_DELINQUENCY is present in reason_codes |
MISSING_KEY_VARIABLES |
high |
Income parse confidence is zero or days_covered == 0 |
Scoring artifact telemetry
backend/src/usecase/credit_score_runtime.py
_store_score_artifact appends one JSON object per scored application to a local JSONL file. The destination path comes from LITA_SCORE_ARTIFACT_PATH, with /tmp/lita_score_artifacts.jsonl as the fallback.
| Artifact field | Description |
|---|---|
application_id |
Application identifier passed to the runtime scorer. |
feature_hash |
SHA-256 hash of the feature payload. |
model_version |
Vertex model version. |
calibration_version |
Calibration version returned by calibrate_pd. |
pd_p50_12m |
Median PD from the Vertex contract. |
pd_p90_12m |
Upper-tail PD from the Vertex contract. |
final_score |
Final legacy score after policy and coverage adjustments. |
score_band |
Band from _score_band. |
coverage_summary |
The data_coverage payload. |
confidence |
Final confidence value. |
reason_codes |
Final reason code list. |
adjustments_applied |
Policy and cap markers applied during scoring. |
latency_ms |
End-to-end runtime latency in milliseconds. |
request_id |
Generated score request id. |
status |
Final status string, currently success on the success path. |
timestamp |
UTC timestamp when the artifact record was written. |
Global Score Conversion
backend/src/ml/lita_global_score_converter.py
This module holds the calibration and cross-scale mapping helpers used by both runtime scoring and the dedicated conversion endpoint. It converts calibrated PD into legacy and global scores, and it maps the global score into external scales such as FICO and UK Experian.
| Function | Description |
|---|---|
calibrate_pd |
Applies corridor-specific PD calibration using the registry keyed by {product_type}:{corridor_cluster}. |
confidence_score |
Produces the final confidence score from coverage, bureau parse confidence, and PD spread. |
pd_to_legacy_score |
Converts PD into the legacy 300–850 credit score scale. |
pd_to_global_score |
Converts PD into the Lita 0–1000 global score scale. |
pd_band |
Returns a PD band label. |
apply_coverage_honesty_policy |
Uplifts PD for low coverage and caps scores for suspected unlinked accounts on lending products. |
target_mapping |
Maps the global score to a named target scale. |
apply_coverage_honesty_policy
When coverage is low, the policy multiplies PD by 1.20 and appends PD_UPLIFT_LOW_COVERAGE. If possible_unlinked_accounts_flag is true and the product is loan or credit_card, it also appends SCORE_CAP_UNLINKED_ACCOUNTS.
target_mapping
| Target scale | Behavior |
|---|---|
FICO_300_850 |
Maps the global score to the 300–850 scale and returns confidence 0.9. |
UK_EXPERIAN_0_999 |
Maps the global score to the 0–999 scale and returns confidence 0.85. |
| Any other value | Returns the normalized scale string with no mapped score and confidence 0.0. |
Tested conversion behavior
backend/tests/ml/test_lita_global_score_converter.py verifies these outcomes:
pd_to_global_score(0.08) == 920pd_to_legacy_score(0.08) == 806pd_band(0.03) == "B"- low coverage with unlinked accounts appends
PD_UPLIFT_LOW_COVERAGEandSCORE_CAP_UNLINKED_ACCOUNTS
Global-score conversion flow
sequenceDiagram
participant Client
participant Http as score_convert_endpoint
participant Converter as lita_global_score_converter
participant Response as ScoreConvertResponse
Client->>Http: POST score convert request
Http->>Http: _convert_source_score_to_global
Http->>Converter: confidence_score
Http->>Converter: target_mapping
Http->>Http: _global_band
Http-->>Response: ScoreConvertResponse
Response-->>Client: global score payload
backend/src/interface/schemas.py
CreditScoreResponse
| Property | Type | Description |
|---|---|---|
application_id |
int |
Application identifier. |
score |
int |
Legacy score in the 300–850 range. |
score_band |
Literal["A", "B", "C", "D", "E"] |
Legacy band label. |
provider |
str |
Runtime provider label, set to lita. |
model_version |
str |
Vertex model version. |
featureset_version |
str |
Fixed featureset version label. |
calibration_version |
str |
Calibration version returned by the runtime scorer. |
confidence |
float |
Calibrated confidence. |
data_coverage |
Dict[str, Any] |
Coverage summary object. |
reason_codes |
List[str] |
Final reason codes. |
breakdown |
Dict[str, float] |
Five-part model breakdown. |
lita_global_score |
int |
Global score in the 0–1000 range. |
global_band |
Literal["A", "B", "C", "D", "E"] |
Global band label. |
risk_flags |
List[Dict[str, str]] |
Structured risk flags. |
target_scale |
Optional[str] |
Optional target scale name. |
target_score |
Optional[int] |
Optional mapped target score. |
target_confidence |
Optional[float] |
Optional mapped target confidence. |
GlobalScoreResponse
| Property | Type | Description |
|---|---|---|
application_id |
int |
Application identifier. |
lita_global_score |
int |
Global score in the 0–1000 range. |
global_band |
Literal["A", "B", "C", "D", "E"] |
Global band label. |
confidence |
float |
Calibrated confidence. |
data_coverage |
Dict[str, Any] |
Coverage summary object. |
reason_codes |
List[str] |
Final reason codes. |
breakdown |
Dict[str, float] |
Five-part model breakdown. |
provider |
str |
Defaults to lita. |
model_version |
str |
Vertex model version. |
featureset_version |
str |
Fixed featureset version label. |
calibration_version |
str |
Calibration version returned by the runtime scorer. |
risk_flags |
List[Dict[str, str]] |
Structured risk flags. |
ScoreConvertResponse
| Property | Type | Description |
|---|---|---|
lita_global_score |
int |
Global score on the 0–1000 scale. |
global_band |
Literal["A", "B", "C", "D", "E"] |
Global band label. |
confidence |
float |
Confidence produced by confidence_score. |
target_scale |
Optional[str] |
Normalized target scale name. |
target_score |
Optional[int] |
Score mapped into the target scale, when supported. |
target_confidence |
Optional[float] |
Confidence for the target-scale projection. |
backend/src/usecase/credit_scoring.py
This module provides the legacy heuristic scorer used in tests and older application flows. It includes its own CreditScoreEstimate dataclass with only the fields needed by that scorer.
CreditScoreEstimate
| Property | Type | Description |
|---|---|---|
score |
int |
Legacy score produced by the heuristic scorer. |
model_version |
str |
Heuristic model version string. |
breakdown |
Dict[str, float] |
Score component breakdown. |
Observed legacy scoring behavior
backend/tests/usecase/test_credit_scoring.py verifies these outputs:
- Standard scoring clamps between
300and850 model_version == "housing-application-heuristic-v1"for the non-student path- Student applications use
model_version == "student-open-banking-v1" - The breakdown includes the expected component keys, including
income_strength,savings_buffer,connected_accounts_bonus,employment_stability, andaffordability_penalty - Extreme positive inputs clamp to
850
backend/src/ml/credit_model.py
This module defines the unified bureau and open-banking model feature contract used by the runtime scorer. The visible surface is the model input schema, the feature lists, and the score conversion helpers used by the model wrapper.
| Constant or Function | Description |
|---|---|
ALL_FEATURE_COLUMNS |
Full model input column list, combining bureau and open-banking features. |
OPEN_BANKING_LEAKAGE_TOKENS |
Tokens used to detect target leakage in open-banking inputs. |
UNIFIED_MODEL_PATH |
Path to the serialized credit score model artifact. |
OPEN_BANKING_LGBM_PARAMS |
LightGBM hyperparameters for the open-banking model. |
score_to_category |
Converts a numeric score into a qualitative category. |
vantage_to_dwilar |
Maps a VantageScore-style score into the Dwilar 0–100 scale. |
score |
Returns a full scoring result dict for runtime consumption. |
Visible score wrapper behavior
The wrapper returns a dictionary with these keys:
vantage_scoredwilar_scoremodel_versionbureau_usedob_used
The open-banking model path uses ALL_FEATURE_COLUMNS so that missing inputs are imputed to zero before scoring.
Fail-closed contract details
backend/src/usecase/credit_score_runtime.py
The runtime scorer rejects invalid Vertex responses at the contract boundary.
| Failure condition | Runtime result |
|---|---|
| No predictions returned | ValueError("Vertex endpoint returned no predictions for credit score request") |
| Prediction is not an object | ValueError("Risk engine payload must be an object") |
pd_p50_12m out of range or non-numeric |
ValueError("pd_p50_12m must be numeric in [0,1]") |
pd_p90_12m invalid or lower than pd_p50_12m |
ValueError(...) |
reason_codes not a string list or contains unsupported values |
ValueError(...) |
breakdown keys do not exactly match the required five |
ValueError(...) |
meta.model_version missing or not a string |
ValueError("meta.model_version is required") |
meta.corridor_cluster present but not a string |
ValueError(...) |
The tests in backend/tests/usecase/test_credit_score_runtime.py assert both the happy path and the failure path:
- A valid Vertex response returns a bounded score,
provider == "lita",model_version == "lita-risk-v1.0.0", and the exact breakdown and coverage keys. - An invalid response containing only
{"score": 777}raisesValueErrorwithpd_p50_12min the message.
Dependencies
External libraries and services
| Dependency | Role |
|---|---|
google.cloud.aiplatform |
Vertex AI endpoint initialization and prediction. |
fastapi |
HTTP routing and dependency injection in http_endpoints.py. |
sqlalchemy.orm.Session |
Database session used to load applications. |
| Local artifact file | JSONL output written by _store_score_artifact. |
Internal modules
| Module | Role |
|---|---|
src.ml.lita_global_score_converter |
PD calibration, honesty policy, score conversion, and target mapping. |
src.usecase.housing_application |
Application lookup by id. |
src.infra.mysql.housing_application_repository |
Application persistence and retrieval. |
src.infra.mysql.database |
Database session dependency. |
src.interface.schemas |
HTTP response models for score endpoints. |
Environment variables
| Variable | Role |
|---|---|
PROJECT_ID / GCP_PROJECT_ID |
Required for Vertex AI initialization. |
REGION |
Vertex AI location, defaults to us-central1. |
VERTEX_CREDIT_ENDPOINT_NAME / VERTEX_CREDIT_ENDPOINT_ID |
Resolves the Vertex endpoint. |
LITA_SCORE_ARTIFACT_PATH |
Destination for JSONL score artifacts. |
LITA_FX_RATES_JSON |
Optional FX overrides for currency normalization. |
LITA_HOST_COUNTRY |
Host country used in feature building. |
LITA_CORRIDOR_CLUSTER_ID |
Overrides the corridor cluster id used for calibration. |
LITA_HOST_UNEMPLOYMENT_RATE |
Macro feature used in scoring. |
LITA_HOST_INFLATION_RATE |
Macro feature used in scoring. |
LITA_HOST_INTEREST_RATE_PROXY |
Macro feature used in scoring. |
Testing Considerations
Runtime scoring tests
backend/tests/usecase/test_credit_score_runtime.py exercises:
- Vertex contract acceptance with a valid
predictions[0]payload - Coverage keys in the returned
data_coverageobject - Breakdown keys exactly matching the required runtime contract
- Fail-closed behavior when the Vertex payload omits the required contract fields
Conversion tests
backend/tests/ml/test_lita_global_score_converter.py exercises:
pd_to_global_scorepd_to_legacy_scorepd_bandapply_coverage_honesty_policytarget_mappingthrough runtime usage
Legacy score tests
backend/tests/usecase/test_credit_scoring.py exercises:
- Legacy score clamping to
300–850 - Student-specific model version routing
- Breakdown content for standard and student flows
- Connected-account inference in the heuristic scorer
Key Classes Reference
| Class | Location | Responsibility |
|---|---|---|
CreditScoreEstimate |
credit_score_runtime.py |
Runtime scoring result with legacy score, global score, calibration metadata, coverage, reasons, and target mapping fields. |
_RiskEngineOutput |
credit_score_runtime.py |
Validated Vertex prediction contract used internally before calibration and conversion. |
CreditScoreResponse |
schemas.py |
HTTP response model for the application credit-score endpoint. |
GlobalScoreResponse |
schemas.py |
HTTP response model for the application global-score endpoint. |
ScoreConvertResponse |
schemas.py |
HTTP response model for the score-convert endpoint. |
CreditScoreEstimate |
credit_scoring.py |
Legacy heuristic scoring result used by the older credit-scoring path. |