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, mismatched breakdown keys, or missing meta.model_version causes score_housing_application to raise ValueError rather 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) == 920
  • pd_to_legacy_score(0.08) == 806
  • pd_band(0.03) == "B"
  • low coverage with unlinked accounts appends PD_UPLIFT_LOW_COVERAGE and SCORE_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 300 and 850
  • 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, and affordability_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_score
  • dwilar_score
  • model_version
  • bureau_used
  • ob_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} raises ValueError with pd_p50_12m in 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_coverage object
  • 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_score
  • pd_to_legacy_score
  • pd_band
  • apply_coverage_honesty_policy
  • target_mapping through 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.