suresafe-ai 1.0.0
SureSafe AI - Fraud detection SDK for Bank Transfer, Credit Card, Online Payment, and UPI transactions
Requires Python: >=3.8
Keywords: fraud-detection, bank-transfer, credit-card, upi, online-payment, machine-learning, fintech, security

# SureSafe AI

A unified Python SDK for fraud detection across multiple transaction types using machine learning models.

## Installation

```bash
pip install suresafe-ai
```

## Quick Start

```python
from suresafe_ai import create_client

client = create_client(
    base_url="https://api.yoursite.com",
    api_key="your-api-key"
)

# Check service health
health = client.health_check()
print(health)
# {'bank_transfer': True, 'credit_card': True, 'online_payment': True, 'upi': True}
```

## Available Methods

### Bank Transfer Fraud Detection

4-model ensemble (Isolation Forest, LOF, One-Class SVM, MCD + XGBoost)

```python
result = client.bank_transfer(
    TransactionAmount=1500,
    TransactionType="Debit",
    Location="Houston",
    DeviceID="D000051",
    MerchantID="M052",
    Channel="Online",
    CustomerAge=35,
    CustomerOccupation="Engineer",
    TransactionDuration=120,
    LoginAttempts=1,
    AccountBalance=5000,
    Hour=14,
    DayOfWeek=2,
    Month=6
)

print(result.is_fraud)          # True
print(result.fraud_probability) # 0.32
print(result.risk_level)        # 'HIGH'
print(result.model_votes)       # 3
```

### Credit Card Fraud Detection

3-model ensemble (XGBoost, LightGBM, CatBoost)

```python
result = client.credit_card(
    amt=500,
    merchant="amazon_store",
    category="shopping_net",
    gender="M",
    job="Engineer",
    lat=33.96,
    long=-80.93,
    city_pop=333497,
    merch_lat=33.98,
    merch_long=-81.20,
    hour=14,
    day_of_week=2,
    month=6,
    age=35
)

print(result.prediction)  # 'SAFE'
print(result.risk_level)  # 'LOW'
```

### Online Payment Fraud Detection

Random Forest classifier with balance flow analysis

```python
result = client.online_payment(
    amount=5000,
    oldbalanceOrg=10000,
    newbalanceOrig=5000,
    oldbalanceDest=20000,
    newbalanceDest=25000,
    isFlaggedFraud=0
)

print(result.fraud_probability)  # 0.02
```

### UPI Fraud Detection

Random Forest with Indian banking features

```python
result = client.upi(
    amount=5000,
    transaction_type="P2P",
    merchant_category="Shopping",
    sender_age_group="26-35",
    receiver_age_group="26-35",
    sender_state="Delhi",
    sender_bank="SBI",
    receiver_bank="ICICI",
    device_type="Android",
    network_type="4G",
    hour_of_day=14,
    is_weekend=0
)

print(result.risk_level)  # 'MEDIUM'
```

## Response Format

All methods return a `FraudResult` object:

```python
@dataclass
class FraudResult:
    is_fraud: bool           # True if fraud detected
    fraud_probability: float # 0-1 probability score
    prediction: str          # 'FRAUD' or 'SAFE'
    risk_level: str          # 'HIGH', 'MEDIUM', or 'LOW'
```

Bank transfer results include additional fields:
- `model_votes`: Number of models that flagged as fraud (0-4)
- `details`: Individual model predictions

## Error Handling

```python
from suresafe_ai import create_client

client = create_client(base_url="http://localhost")

try:
    result = client.bank_transfer(...)
except ConnectionError as e:
    print("Server not reachable:", e)
except TimeoutError as e:
    print("Request timed out:", e)
except Exception as e:
    print("API error:", e)
```

## License

MIT