volume_agent.py

class VolumeSurgeAgent:
    """
    Detects volume surges compared to recent average volume.
    Returns a structured object with surge status and ratio.
    """

    def run(self, df, threshold=1.8):
        if len(df) < 21:
            return {
                "volume_surge": False,
                "ratio": 0,
                "status": "⚠️ Insufficient data"
            }

        recent_avg = df['Volume'].iloc[-20:-1].mean()
        latest_volume = df['Volume'].iloc[-1]
        ratio = latest_volume / recent_avg

        surge = ratio > threshold

        return {
            "volume_surge": surge,
            "ratio": round(ratio, 2),
            "status": "✅ Spike" if surge else "Normal"
        }