SARIAH345/fintech-risk-api

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Fintech Risk Scoring API

Uncertainty-Aware, Containerized Machine Learning Service Live Deployment

• —Space Page: https://huggingface.co/spaces/SARIAH345/fintech-risk-api
• —Live API: https://sariah345-fintech-risk-api.hf.space/
• —Swagger UI (Docs): https://sariah345-fintech-risk-api.hf.space/docs
• —Health Check: https://sariah345-fintech-risk-api.hf.space/health

Overview

This project implements a production-style fintech risk-scoring API designed to reflect how real-world decision systems handle uncertainty, input validation, and deployment constraints.

The service exposes a REST API that accepts transaction and account features and returns:

• —calibrated risk probabilities,
• —uncertainty-aware prediction sets,
• —and an explicit decision (APPROVE, REVIEW, or DECLINE).

Rather than forcing a single prediction, the system abstains when uncertainty is high, routing ambiguous cases for review—mirroring best practices in high-stakes domains such as finance.

Key Features

🔹 Calibrated Probabilistic Outputs

The model produces well-calibrated risk probabilities, not opaque scores, enabling meaningful interpretation of model confidence.

🔹 Uncertainty-Aware Decision Logic

Using conformal prediction principles, the system outputs prediction sets and abstains when confidence thresholds are not met. This prevents overconfident automation in ambiguous cases.

🔹 Strict Input Validation

All requests are schema-validated:

• —required fields enforced,
• —out-of-spec values detected,
• —malformed inputs rejected with clear error messages.

🔹 Production-Style API Design

• —Health check endpoint (/health)
• —OpenAPI / Swagger documentation (/docs)
• —Explicit decision thresholds
• —Structured JSON responses suitable for logging and audit

Architecture

• —Model: Lightweight logistic-style model trained on synthetic, schema-aligned data
• —Calibration: Platt scaling
• —Uncertainty: Conformal prediction sets (binary)
• —API: FastAPI
• —Deployment: Dockerized service (CPU-only)

The model is trained at container build time, ensuring reproducibility and eliminating runtime training dependencies.

API Endpoints

GET /health

Health check endpoint used for deployment verification.

Response

{
  "status": "ok",
  "model_version": "fintech-purepy-v1.1"
}
POST /predict

Returns a risk assessment and decision for a given transaction.

Request
{
  "x": {
    "amount": 1200,
    "account_age_days": 40,
    "txn_hour": 23,
    "country_risk_score": 0.7,
    "device_trust_score": 0.2
  },
  "request_id": "demo-1"
}
Response
{
  "p_risk": 0.39,
  "p_safe": 0.61,
  "decision": {
    "action": "REVIEW",
    "reasons": ["CONFORMAL_AMBIGUOUS"]
  }
}
Deployment Notes

This service is fully containerized and designed for cloud deployment.

A public demonstration is hosted on Hugging Face Spaces (Docker).

The system is structured to be deployable on enterprise container platforms (e.g., Azure Container Apps).

Cloud resources are intentionally minimized to reflect cost-aware engineering decisions.

Design Philosophy

This project prioritizes:

honest uncertainty handling over forced predictions,

interpretability over model complexity,

deployment realism over benchmark chasing.

The goal is not maximum accuracy at any cost, but responsible ML system design suitable for high-stakes environments.

License

MIT License