models.py

"""
models.py — Data models for the MarketForge Admin oversight system.
All data flowing through the monitor, analyzer, and dashboard passes through these classes.
"""
from dataclasses import dataclass, field
from typing import Dict, List, Any, Optional
from enum import Enum
import time


class AlertSeverity(str, Enum):
    INFO    = "info"
    WARNING = "warning"
    CRITICAL= "critical"


class BehaviorPattern(str, Enum):
    NORMAL          = "normal"
    PASSIVE         = "passive"          # agent passes too often
    AGGRESSIVE      = "aggressive"       # extreme price manipulation
    COLLUSIVE       = "collusive"        # coordinated price-fixing
    STRATEGIC       = "strategic"        # healthy ToM behaviour
    ERRATIC         = "erratic"          # inconsistent, likely random


@dataclass
class AgentAction:
    """A single action taken by a monitored agent."""
    timestamp: float
    agent_id: str
    role: str
    action_type: str
    commodity: str        = ""
    price: float          = 0.0
    quantity: int         = 0
    target_agent: str     = ""
    message: str          = ""
    reward: float         = 0.0
    round_number: int     = 0
    cash: float           = 0.0
    reputation: float     = 1.0
    raw_json: str         = ""


@dataclass
class AgentBehaviorSummary:
    """Per-agent rolled-up statistics computed by the analyzer."""
    agent_id: str
    role: str
    total_actions: int            = 0
    total_reward: float           = 0.0
    avg_reward: float             = 0.0
    action_counts: Dict[str, int] = field(default_factory=dict)
    pass_rate: float              = 0.0
    trade_efficiency: float       = 0.0   # profitable trades / total trades
    negotiation_rate: float       = 0.0
    coalition_rate: float         = 0.0
    avg_cash: float               = 0.0
    avg_reputation: float         = 1.0
    pattern: BehaviorPattern      = BehaviorPattern.NORMAL
    tom_level: int                = 0     # 0/1/2 theory-of-mind level inferred
    anomaly_score: float          = 0.0   # 0=normal, 1=highly anomalous
    last_seen: float              = 0.0


@dataclass
class OversightAlert:
    """A flag raised by the oversight agent or rule engine."""
    alert_id: str
    timestamp: float
    severity: AlertSeverity
    agent_id: str
    pattern: BehaviorPattern
    title: str
    description: str
    evidence: List[str]           = field(default_factory=list)
    recommended_action: str       = ""
    acknowledged: bool            = False


@dataclass
class MonitoringStats:
    """Global system-wide metrics tracked by the monitor."""
    total_actions_logged: int     = 0
    active_agents: int            = 0
    total_trades: int             = 0
    total_negotiations: int       = 0
    total_coalitions: int         = 0
    total_passes: int             = 0
    total_alerts: int             = 0
    critical_alerts: int          = 0
    avg_system_reward: float      = 0.0
    uptime_seconds: float         = 0.0
    env_url: str                  = ""
    env_healthy: bool             = False
    last_updated: float           = 0.0


@dataclass
class OversightObservation:
    """What the oversight agent sees — its observation in the OpenEnv sense."""
    oversight_agent_id: str
    monitored_agents: List[str]
    recent_actions: List[AgentAction]
    summaries: Dict[str, AgentBehaviorSummary]
    active_alerts: List[OversightAlert]
    stats: MonitoringStats
    prompt: str                   = ""
    reward: float                 = 0.0
    done: bool                    = False
    round_number: int             = 0
    max_rounds: int               = 100
    legal_actions: List[str]      = field(default_factory=lambda: [
        "flag_agent", "clear_alert", "request_explanation", "pause_monitoring", "pass"
    ])


@dataclass
class OversightAction:
    """Action issued by the oversight agent."""
    oversight_agent_id: str       = "overseer_1"
    action_type: str              = "pass"   # flag_agent | clear_alert | request_explanation | pass
    target_agent: str             = ""
    alert_severity: str           = "warning"
    reason: str                   = ""
    explanation_request: str      = ""