Spaces:
Sleeping
Sleeping
File size: 5,578 Bytes
39c0d5b f953d1e 39c0d5b f953d1e 39c0d5b f953d1e 39c0d5b f953d1e 39c0d5b | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 | # Copyright (c) Meta Platforms, Inc. and affiliates.
# All rights reserved.
#
# This source code is licensed under the BSD-style license found in the
# LICENSE file in the root directory of this source tree.
"""
Data models for the Smartpayenv Environment.
Rich, production-inspired payment transaction observation and action types.
"""
from pydantic import BaseModel, Field
from openenv.core.env_server.types import Action, Observation
class SmartpayenvAction(Action):
"""
Agent action for one payment transaction step.
gateway: Which payment gateway to attempt (0=GatewayA cheap, 1=GatewayB balanced, 2=GatewayC premium)
retry_strategy: 0=no retry on failure, 1=failover to next gateway
fraud_decision: 0=allow transaction, 1=block transaction (ends episode)
"""
gateway: int = Field(default=0, description="0=GatewayA (cheap), 1=GatewayB (balanced), 2=GatewayC (premium)")
retry_strategy: int = Field(default=0, description="0=No Retry, 1=Failover to next gateway on failure")
fraud_decision: int = Field(default=0, description="0=Allow, 1=Block, 2=Challenge (3DS), 3=Manual Review (Delayed)")
class SmartpayenvObservation(Observation):
"""
Rich observation for one incoming payment transaction.
Includes multi-factor signals that a real payment intelligence
system would use: merchant context, device fingerprinting,
transaction velocity, international flag, and gateway health.
"""
# ── Transaction context ────────────────────────────────────────────
amount: float = Field(default=0.0, description="Transaction amount in USD")
merchant_category: int = Field(
default=0,
description="Merchant category: 0=grocery, 1=travel, 2=electronics, 3=dining, 4=gaming, 5=other"
)
is_international: bool = Field(default=False, description="Cross-border transaction flag")
card_present: bool = Field(default=True, description="Card physically present (lowers fraud risk)")
# ── User / device signals ──────────────────────────────────────────
user_type: int = Field(default=0, description="Derived risk tier: 0=Normal, 1=Risky, 2=Fraud")
user_segment: int = Field(default=1, description="Cohort: 0=New/Guest, 1=Existing, 2=Premium/VIP")
user_history_score: float = Field(default=1.0, description="Normalized user reliability score [0,1]")
device_type: int = Field(default=0, description="0=mobile, 1=desktop, 2=tablet")
bin_category: int = Field(default=0, description="Bank Identification Number category (0-9)")
transaction_velocity: float = Field(
default=0.0,
description="Normalized count of transactions in the last 5 steps [0,1]"
)
# ── Temporal ──────────────────────────────────────────────────────
time_of_day: int = Field(default=0, description="Hour of day 0–23")
# ── Gateway health ────────────────────────────────────────────────
gateway_success_rates: list[float] = Field(
default_factory=list,
description="Current success-rate estimates for [GatewayA, GatewayB, GatewayC]"
)
gateway_states: list[str] = Field(
default_factory=list,
description="Health state for each gateway: 'normal' | 'degraded' | 'recovering'"
)
# ── Risk scores ───────────────────────────────────────────────────
observed_fraud_risk: float = Field(
default=0.0,
description="Noisy multi-factor fraud risk estimate [0,1] (true risk is hidden)"
)
# ── Episode tracking ──────────────────────────────────────────────
previous_failures: int = Field(default=0, description="Consecutive failed transactions in this episode")
difficulty: int = Field(default=0, description="Episode difficulty tier: 0=easy, 1=medium, 2=hard")
# ── Step outputs ──────────────────────────────────────────────────
reward: float = Field(default=0.0, description="Combined step reward [0,1]")
done: bool = Field(default=False, description="Episode done flag")
chargeback_penalty_applied: float = Field(default=0.0, description="Penalty deducted this step from a past transaction chargeback")
review_resolutions: list[dict] = Field(default_factory=list, description="List of resolved manual reviews this step: [{ 'amount': float, 'is_fraud': bool, 'outcome': 'accepted'|'rejected' }]")
# Per-task scores — declared as first-class fields so openenv framework serializes them
task_routing_score: float = Field(default=0.0, description="Routing efficacy score [0,1]")
task_fraud_mcc_score: float = Field(default=0.0, description="Fraud detection MCC score [0,1]")
task_retention_score: float = Field(default=1.0, description="User retention score [0,1]")
# Metadata dict for backward compatibility / agent introspection
metadata: dict = Field(default_factory=dict, description="Per-task score breakdown")
|