arena-score 1.0.0__py3-none-any.whl

arena_score/__init__.py

@@ -0,0 +1,46 @@
+"""
+ARENA Score - Adaptive Review and Evaluation using Novel Aggregation Score
+
+A novel client evaluation and weighted aggregation algorithm for Federated Learning.
+
+Key Features:
+- Adaptive client evaluation using ΔAcc, CS, and SN metrics
+- Robust aggregation with anomaly detection
+- Gradient recycling for missing clients
+- Model agnostic design
+"""
+
+from arena_score.score import compute_arena_score, compute_adaptive_weights
+from arena_score.client import ARENAScoreClient
+from arena_score.server import ARENAScoreServer
+from arena_score.aggregator import run_arena_score
+from arena_score.utils import (
+    compute_cosine_similarity,
+    compute_spectral_norm,
+    compute_kl_divergence,
+    flatten_weights,
+    unflatten_weights
+)
+
+__version__ = "1.0.0"
+__author__ = "Ronit Mehta"
+__email__ = "ronit26mehta@gmail.com"
+
+__all__ = [
+    # Core classes
+    "ARENAScoreClient",
+    "ARENAScoreServer",
+    # Main function
+    "run_arena_score",
+    # Score computation
+    "compute_arena_score",
+    "compute_adaptive_weights",
+    # Utilities
+    "compute_cosine_similarity",
+    "compute_spectral_norm",
+    "compute_kl_divergence",
+    "flatten_weights",
+    "unflatten_weights",
+    # Version
+    "__version__",
+]

arena_score/aggregator.py

@@ -0,0 +1,163 @@
+"""
+ARENA Score Aggregator
+
+Main federated learning loop using ARENA Score aggregation.
+"""
+
+import numpy as np
+from typing import Dict, List, Tuple, Optional, Any, Protocol
+
+from arena_score.client import ARENAScoreClient
+from arena_score.server import ARENAScoreServer
+
+
+class ModelProtocol(Protocol):
+    """Protocol defining the required model interface."""
+    
+    def get_weights(self) -> Dict[str, np.ndarray]: ...
+    def set_weights(self, weights: Dict[str, np.ndarray]) -> None: ...
+    def predict(self, X: np.ndarray) -> np.ndarray: ...
+    def predict_proba(self, X: np.ndarray) -> np.ndarray: ...
+    def copy(self) -> 'ModelProtocol': ...
+
+
+def run_arena_score(
+    global_model: ModelProtocol,
+    clients: List[ARENAScoreClient],
+    n_rounds: int = 10,
+    eval_data: Optional[Tuple[np.ndarray, np.ndarray]] = None,
+    server_config: Optional[Dict[str, Any]] = None,
+    verbose: bool = True
+) -> Dict[str, Any]:
+    """
+    Run ARENA Score federated learning algorithm.
+    
+    This is the main entry point for running federated learning with
+    ARENA Score aggregation.
+    
+    Args:
+        global_model: Global model to train (must implement ModelProtocol)
+        clients: List of ARENAScoreClient instances
+        n_rounds: Number of communication rounds (default: 10)
+        eval_data: Optional (X_test, y_test) tuple for evaluation
+        server_config: Optional server configuration dictionary with keys:
+            - alpha_0, alpha_min: Accuracy weight parameters
+            - gamma_0, gamma_min: Cosine similarity weight parameters
+            - eta: Spectral norm coefficient
+            - lambda_decay: Decay rate
+            - s_min: Minimum score threshold
+            - anomaly_threshold: CS anomaly threshold
+            - kl_threshold: KL divergence threshold
+            - enable_gradient_recycling: Enable gradient recycling
+        verbose: Print progress (default: True)
+    
+    Returns:
+        Training history dictionary with keys:
+        - round: List of round numbers
+        - train_loss: Average training loss per round
+        - train_accuracy: Average training accuracy per round
+        - test_accuracy: Test accuracy per round (if eval_data provided)
+        - test_loss: Test loss per round (if eval_data provided)
+        - arena_scores: ARENA scores per round
+        - alpha_t, gamma_t: Adaptive weights per round
+        - mean_delta_acc, mean_cosine_sim, mean_spectral_norm: Mean metrics
+        - valid_clients_ratio: Ratio of non-anomalous clients
+    
+    Example:
+        >>> from arena_score import ARENAScoreClient, run_arena_score
+        >>> 
+        >>> # Create clients
+        >>> clients = [
+        ...     ARENAScoreClient(i, model.copy(), X[i], y[i])
+        ...     for i in range(n_clients)
+        ... ]
+        >>> 
+        >>> # Run ARENA Score FL
+        >>> history = run_arena_score(
+        ...     global_model=model,
+        ...     clients=clients,
+        ...     n_rounds=10,
+        ...     eval_data=(X_test, y_test)
+        ... )
+        >>> 
+        >>> print(f"Final accuracy: {history['test_accuracy'][-1]:.4f}")
+    """
+    # Initialize server
+    config = server_config or {}
+    server = ARENAScoreServer(global_model, **config)
+    
+    # Initialize history
+    history: Dict[str, List[Any]] = {
+        'round': [],
+        'train_loss': [],
+        'train_accuracy': [],
+        'test_accuracy': [],
+        'test_loss': [],
+        'arena_scores': [],
+        'alpha_t': [],
+        'gamma_t': [],
+        'mean_delta_acc': [],
+        'mean_cosine_sim': [],
+        'mean_spectral_norm': [],
+        'valid_clients_ratio': []
+    }
+    
+    for round_num in range(n_rounds):
+        global_weights = server.get_global_weights()
+        
+        # Collect client updates
+        client_weights: List[Dict[str, np.ndarray]] = []
+        client_metrics: List[Dict[str, Any]] = []
+        client_samples: List[int] = []
+        client_ids: List[int] = []
+        
+        for client in clients:
+            weights, metrics, n_samples = client.local_train(global_weights)
+            client_weights.append(weights)
+            client_metrics.append(metrics)
+            client_samples.append(n_samples)
+            client_ids.append(client.client_id)
+        
+        # ARENA Score aggregation
+        _, agg_info = server.aggregate(
+            client_weights, client_metrics, client_samples, client_ids
+        )
+        
+        # Record metrics
+        avg_loss = float(np.mean([m['avg_loss'] for m in client_metrics]))
+        avg_acc = float(np.mean([m['accuracy'] for m in client_metrics]))
+        
+        history['round'].append(round_num + 1)
+        history['train_loss'].append(avg_loss)
+        history['train_accuracy'].append(avg_acc)
+        history['arena_scores'].append(agg_info['scores'])
+        history['alpha_t'].append(agg_info['alpha_t'])
+        history['gamma_t'].append(agg_info['gamma_t'])
+        history['mean_delta_acc'].append(float(np.mean([m['delta_acc'] for m in client_metrics])))
+        history['mean_cosine_sim'].append(float(np.mean([m['cosine_sim'] for m in client_metrics])))
+        history['mean_spectral_norm'].append(float(np.mean([m['spectral_norm'] for m in client_metrics])))
+        history['valid_clients_ratio'].append(agg_info['valid_clients'] / agg_info['total_clients'])
+        
+        # Evaluate on test data
+        if eval_data is not None:
+            X_test, y_test = eval_data
+            test_pred = global_model.predict(X_test)
+            test_proba = global_model.predict_proba(X_test)
+            test_acc = float(np.mean(test_pred == y_test))
+            test_loss = float(-np.mean(
+                y_test * np.log(np.clip(test_proba, 1e-7, 1-1e-7)) +
+                (1 - y_test) * np.log(np.clip(1 - test_proba, 1e-7, 1-1e-7))
+            ))
+            history['test_accuracy'].append(test_acc)
+            history['test_loss'].append(test_loss)
+            
+            if verbose:
+                print(f"Round {round_num + 1}/{n_rounds}: "
+                      f"Train Acc={avg_acc:.4f}, Test Acc={test_acc:.4f}, "
+                      f"Valid Clients={agg_info['valid_clients']}/{agg_info['total_clients']}")
+        elif verbose:
+            print(f"Round {round_num + 1}/{n_rounds}: "
+                  f"Train Acc={avg_acc:.4f}, "
+                  f"Valid Clients={agg_info['valid_clients']}/{agg_info['total_clients']}")
+    
+    return history

arena_score/client.py

@@ -0,0 +1,221 @@
+"""
+ARENA Score Client
+
+Client implementation for ARENA Score federated learning.
+Performs local training and computes ARENA metrics for server evaluation.
+"""
+
+import numpy as np
+from typing import Dict, Tuple, Any, Optional, Protocol
+
+
+class ModelProtocol(Protocol):
+    """Protocol defining the required model interface."""
+    
+    def get_weights(self) -> Dict[str, np.ndarray]: ...
+    def set_weights(self, weights: Dict[str, np.ndarray]) -> None: ...
+    def forward(self, X: np.ndarray) -> np.ndarray: ...
+    def backward(self, X: np.ndarray, y: np.ndarray, y_pred: np.ndarray) -> Dict[str, np.ndarray]: ...
+    def update_weights(self, gradients: Dict[str, np.ndarray]) -> None: ...
+    def predict(self, X: np.ndarray) -> np.ndarray: ...
+    def predict_proba(self, X: np.ndarray) -> np.ndarray: ...
+    def copy(self) -> 'ModelProtocol': ...
+
+
+class ARENAScoreClient:
+    """
+    ARENA Score Client with adaptive evaluation metrics.
+    
+    This client performs local training and computes the metrics needed
+    for ARENA Score evaluation:
+    - ΔAcc (delta accuracy): Accuracy improvement after local training
+    - CS (cosine similarity): Alignment with global update direction
+    - SN (spectral norm): Weight matrix regularization
+    - KL divergence: Distribution shift detection
+    
+    Args:
+        client_id: Unique identifier for this client
+        model: Model implementing the ModelProtocol interface
+        X: Training data features
+        y: Training data labels
+        local_epochs: Number of local training epochs (default: 1)
+        batch_size: Batch size for training (default: 32)
+        eta: Spectral norm coefficient (default: 0.5)
+    
+    Example:
+        >>> client = ARENAScoreClient(
+        ...     client_id=0,
+        ...     model=my_model,
+        ...     X=X_train,
+        ...     y=y_train,
+        ...     local_epochs=5
+        ... )
+        >>> weights, metrics, n_samples = client.local_train(global_weights)
+    """
+    
+    def __init__(
+        self,
+        client_id: int,
+        model: ModelProtocol,
+        X: np.ndarray,
+        y: np.ndarray,
+        local_epochs: int = 1,
+        batch_size: int = 32,
+        eta: float = 0.5
+    ):
+        self.client_id = client_id
+        self.model = model
+        self.X = X
+        self.y = y
+        self.local_epochs = local_epochs
+        self.batch_size = batch_size
+        self.eta = eta
+        self.n_samples = len(X)
+        
+        # Track previous state for ΔAcc and CS computation
+        self.prev_accuracy: Optional[float] = None
+        self.prev_weights: Optional[Dict[str, np.ndarray]] = None
+    
+    def local_train(
+        self,
+        global_weights: Dict[str, np.ndarray]
+    ) -> Tuple[Dict[str, np.ndarray], Dict[str, Any], int]:
+        """
+        Perform local training and compute ARENA metrics.
+        
+        Args:
+            global_weights: Current global model weights
+        
+        Returns:
+            Tuple of:
+            - updated_weights: New model weights after local training
+            - metrics: Dict containing accuracy, delta_acc, cosine_sim, 
+                      spectral_norm, kl_divergence, f1, etc.
+            - n_samples: Number of local training samples
+        
+        Example:
+            >>> weights, metrics, n = client.local_train(server.get_global_weights())
+            >>> print(f"Delta Acc: {metrics['delta_acc']:.4f}")
+            >>> print(f"Cosine Sim: {metrics['cosine_sim']:.4f}")
+        """
+        from arena_score.utils import (
+            compute_spectral_norm, 
+            flatten_weights,
+            compute_kl_divergence
+        )
+        
+        # Store previous weights for CS computation
+        if self.prev_weights is None:
+            self.prev_weights = {k: v.copy() for k, v in global_weights.items()}
+        
+        # Set model to global weights and compute initial metrics
+        self.model.set_weights(global_weights)
+        initial_preds = self.model.predict_proba(self.X)
+        initial_accuracy = self._compute_accuracy(self.model.predict(self.X), self.y)
+        
+        # Local training
+        total_loss = 0.0
+        n_batches = 0
+        accumulated_grads: Optional[Dict[str, np.ndarray]] = None
+        
+        for epoch in range(self.local_epochs):
+            indices = np.random.permutation(len(self.X))
+            
+            for start_idx in range(0, len(self.X), self.batch_size):
+                end_idx = min(start_idx + self.batch_size, len(self.X))
+                batch_indices = indices[start_idx:end_idx]
+                
+                X_batch = self.X[batch_indices]
+                y_batch = self.y[batch_indices]
+                
+                # Forward pass
+                y_pred = self.model.forward(X_batch)
+                loss = self._compute_loss(y_batch, y_pred)
+                total_loss += loss
+                n_batches += 1
+                
+                # Backward pass
+                gradients = self.model.backward(X_batch, y_batch, y_pred)
+                
+                # Accumulate gradients for analysis
+                if accumulated_grads is None:
+                    accumulated_grads = {k: v.copy() for k, v in gradients.items()}
+                else:
+                    for k in gradients:
+                        accumulated_grads[k] += gradients[k]
+                
+                # Update weights
+                self.model.update_weights(gradients)
+        
+        # Get final weights and predictions
+        final_weights = self.model.get_weights()
+        final_preds = self.model.predict_proba(self.X)
+        final_predictions = self.model.predict(self.X)
+        final_accuracy = self._compute_accuracy(final_predictions, self.y)
+        
+        # ===== Compute ARENA Metrics =====
+        
+        # 1. Delta Accuracy (ΔAcc)
+        delta_acc = final_accuracy - initial_accuracy
+        
+        # 2. Cosine Similarity (CS) - between update and global gradient direction
+        update_flat = flatten_weights(final_weights) - flatten_weights(global_weights)
+        global_flat = flatten_weights(global_weights) - flatten_weights(self.prev_weights)
+        
+        if np.linalg.norm(global_flat) > 1e-8:
+            cosine_sim = float(np.dot(update_flat, global_flat) / 
+                              (np.linalg.norm(update_flat) * np.linalg.norm(global_flat) + 1e-8))
+        else:
+            cosine_sim = 1.0  # First round or no previous update
+        
+        # 3. Spectral Norm (SN)
+        spectral_norm = compute_spectral_norm(final_weights)
+        
+        # 4. KL Divergence - detect distribution drift
+        kl_divergence = compute_kl_divergence(final_preds, initial_preds)
+        
+        # 5. Flag potentially corrupted clients
+        is_potentially_corrupted = final_accuracy < 0.5 or delta_acc < -0.1
+        
+        # Compute F1 score
+        f1 = self._compute_f1(final_predictions, self.y)
+        
+        # Store current state for next round
+        self.prev_accuracy = final_accuracy
+        self.prev_weights = {k: v.copy() for k, v in final_weights.items()}
+        
+        metrics = {
+            'accuracy': final_accuracy,
+            'loss': self._compute_loss(self.y, final_preds),
+            'avg_loss': total_loss / n_batches if n_batches > 0 else 0,
+            'delta_acc': delta_acc,
+            'cosine_sim': cosine_sim,
+            'spectral_norm': spectral_norm,
+            'kl_divergence': kl_divergence,
+            'is_potentially_corrupted': is_potentially_corrupted,
+            'f1': f1,
+            'accumulated_grads': accumulated_grads
+        }
+        
+        return final_weights, metrics, self.n_samples
+    
+    def _compute_accuracy(self, y_pred: np.ndarray, y_true: np.ndarray) -> float:
+        """Compute accuracy."""
+        return float(np.mean(y_pred == y_true))
+    
+    def _compute_loss(self, y_true: np.ndarray, y_pred: np.ndarray, eps: float = 1e-7) -> float:
+        """Compute binary cross-entropy loss."""
+        y_pred = np.clip(y_pred, eps, 1 - eps)
+        return float(-np.mean(y_true * np.log(y_pred) + (1 - y_true) * np.log(1 - y_pred)))
+    
+    def _compute_f1(self, y_pred: np.ndarray, y_true: np.ndarray) -> float:
+        """Compute F1 score."""
+        tp = np.sum((y_pred == 1) & (y_true == 1))
+        fp = np.sum((y_pred == 1) & (y_true == 0))
+        fn = np.sum((y_pred == 0) & (y_true == 1))
+        
+        precision = tp / (tp + fp + 1e-8)
+        recall = tp / (tp + fn + 1e-8)
+        f1 = 2 * precision * recall / (precision + recall + 1e-8)
+        
+        return float(f1)

arena_score/score.py

@@ -0,0 +1,153 @@
+"""
+ARENA Score Computation Module
+
+Implements the core ARENA Score formula from the research paper:
+S_j = α(t) × max(0, ΔAcc_j) + γ(t) × CS_j + η × SN_j/(1 + SN_j)
+
+Where:
+- ΔAcc: Local accuracy improvement
+- CS: Cosine similarity between client update and global direction
+- SN: Spectral norm regularization = log(1 + σ_max(W_j))
+- α(t), γ(t): Adaptive time-varying weights
+"""
+
+import numpy as np
+from typing import Tuple
+
+
+def compute_adaptive_weights(
+    t: int,
+    alpha_0: float = 0.7,
+    alpha_min: float = 0.3,
+    gamma_0: float = 0.3,
+    gamma_min: float = 0.5,
+    lambda_decay: float = 0.1
+) -> Tuple[float, float]:
+    """
+    Compute time-varying adaptive weights α(t) and γ(t).
+    
+    From the paper:
+    - α(t) = α_min + (α_0 - α_min) × exp(-λt)
+    - γ(t) = γ_min + (γ_0 - γ_min) × (1 - exp(-λt))
+    
+    Args:
+        t: Current communication round (0-indexed)
+        alpha_0: Initial accuracy weight (default: 0.7)
+        alpha_min: Minimum accuracy weight (default: 0.3)
+        gamma_0: Initial cosine similarity weight (default: 0.3)
+        gamma_min: Minimum cosine similarity weight (default: 0.5)
+        lambda_decay: Decay rate (default: 0.1)
+    
+    Returns:
+        Tuple of (alpha_t, gamma_t)
+    
+    Example:
+        >>> alpha_t, gamma_t = compute_adaptive_weights(t=5)
+        >>> print(f"Round 5: α={alpha_t:.3f}, γ={gamma_t:.3f}")
+    """
+    decay_factor = np.exp(-lambda_decay * t)
+    
+    alpha_t = alpha_min + (alpha_0 - alpha_min) * decay_factor
+    gamma_t = gamma_min + (gamma_0 - gamma_min) * (1 - decay_factor)
+    
+    return float(alpha_t), float(gamma_t)
+
+
+def compute_arena_score(
+    delta_acc: float,
+    cosine_sim: float,
+    spectral_norm: float,
+    alpha_t: float,
+    gamma_t: float,
+    eta: float = 0.5,
+    is_potentially_corrupted: bool = False
+) -> float:
+    """
+    Compute ARENA Score for a client update.
+    
+    Formula:
+    S_j = α(t) × max(0, ΔAcc_j) + γ(t) × CS_j + η × SN_j/(1 + SN_j)
+    
+    Key improvements:
+    - Heavily penalizes negative delta_acc (indicates corrupted training)
+    - Normalizes CS to [0, 1] range
+    - Applies 90% penalty for potentially corrupted clients
+    
+    Args:
+        delta_acc: Accuracy improvement (final - initial accuracy)
+        cosine_sim: Cosine similarity between update and global direction [-1, 1]
+        spectral_norm: Spectral norm value log(1 + σ_max)
+        alpha_t: Current adaptive weight for accuracy
+        gamma_t: Current adaptive weight for cosine similarity
+        eta: Spectral norm coefficient (default: 0.5)
+        is_potentially_corrupted: Flag for suspected corrupted client
+    
+    Returns:
+        ARENA score (non-negative float)
+    
+    Example:
+        >>> score = compute_arena_score(
+        ...     delta_acc=0.05,
+        ...     cosine_sim=0.8,
+        ...     spectral_norm=2.5,
+        ...     alpha_t=0.5,
+        ...     gamma_t=0.4
+        ... )
+        >>> print(f"ARENA Score: {score:.2f}")
+    """
+    # Accuracy contribution - PENALIZE negative delta_acc heavily
+    if delta_acc >= 0:
+        acc_term = alpha_t * delta_acc
+    else:
+        # Negative improvement = likely corrupted, apply strong penalty
+        acc_term = alpha_t * delta_acc * 2.0  # Double the penalty
+    
+    # Cosine similarity contribution (normalized to [0, 1] from [-1, 1])
+    cs_normalized = (cosine_sim + 1) / 2  # Map [-1, 1] to [0, 1]
+    cs_term = gamma_t * cs_normalized
+    
+    # Spectral norm contribution (normalized)
+    sn_term = eta * (spectral_norm / (1 + spectral_norm))
+    
+    # Total score (scaled to reasonable range)
+    score = 100 * (acc_term + cs_term + sn_term)
+    
+    # Apply additional penalty for potentially corrupted clients
+    if is_potentially_corrupted:
+        score *= 0.1  # Reduce score by 90%
+    
+    return max(0.0, float(score))  # Ensure non-negative score
+
+
+def detect_anomaly(
+    cosine_sim: float,
+    kl_divergence: float = 0.0,
+    is_potentially_corrupted: bool = False,
+    anomaly_threshold: float = -0.5,
+    kl_threshold: float = 0.5
+) -> bool:
+    """
+    Detect anomalous client update using multiple criteria.
+    
+    From the paper (lines 17-18):
+    - KL divergence thresholds
+    - CS < -0.5 threshold
+    
+    Args:
+        cosine_sim: Cosine similarity value
+        kl_divergence: KL divergence between predictions (default: 0.0)
+        is_potentially_corrupted: Pre-computed corruption flag
+        anomaly_threshold: CS threshold (default: -0.5)
+        kl_threshold: KL divergence threshold (default: 0.5)
+    
+    Returns:
+        True if anomaly detected, False otherwise
+    
+    Example:
+        >>> is_anomaly = detect_anomaly(cosine_sim=-0.7, kl_divergence=0.3)
+        >>> print(f"Anomaly: {is_anomaly}")  # True (CS < -0.5)
+    """
+    cs_anomaly = cosine_sim < anomaly_threshold
+    kl_anomaly = kl_divergence > kl_threshold
+    
+    return cs_anomaly or kl_anomaly or is_potentially_corrupted

arena_score/server.py

@@ -0,0 +1,268 @@
+"""
+ARENA Score Server
+
+Server implementation for ARENA Score federated learning.
+Performs adaptive weighted aggregation with anomaly detection.
+"""
+
+import numpy as np
+from typing import Dict, List, Tuple, Any, Optional, Protocol
+
+
+class ModelProtocol(Protocol):
+    """Protocol defining the required model interface."""
+    
+    def get_weights(self) -> Dict[str, np.ndarray]: ...
+    def set_weights(self, weights: Dict[str, np.ndarray]) -> None: ...
+    def copy(self) -> 'ModelProtocol': ...
+
+
+class ARENAScoreServer:
+    """
+    ARENA Score Server with adaptive weighted aggregation.
+    
+    Implements the ARENA Score aggregation formula:
+    S_j = α(t) × max(0, ΔAcc_j) + γ(t) × CS_j + η × SN_j/(1 + SN_j)
+    
+    With time-varying weights:
+    - α(t) = α_min + (α_0 - α_min) × exp(-λt)
+    - γ(t) = γ_min + (γ_0 - γ_min) × (1 - exp(-λt))
+    
+    Args:
+        global_model: The global model to aggregate updates into
+        alpha_0: Initial accuracy weight (default: 0.7)
+        alpha_min: Minimum accuracy weight (default: 0.3)
+        gamma_0: Initial cosine similarity weight (default: 0.3)
+        gamma_min: Minimum cosine similarity weight (default: 0.5)
+        eta: Spectral norm coefficient (default: 0.5)
+        lambda_decay: Decay rate for adaptive weights (default: 0.1)
+        s_min: Minimum score threshold (default: 0)
+        anomaly_threshold: CS threshold for anomaly detection (default: -0.5)
+        kl_threshold: KL divergence threshold (default: 0.5)
+        enable_gradient_recycling: Enable gradient recycling (default: True)
+    
+    Example:
+        >>> server = ARENAScoreServer(
+        ...     global_model=my_model,
+        ...     alpha_0=0.7,
+        ...     eta=0.5
+        ... )
+        >>> aggregated, info = server.aggregate(client_weights, client_metrics, ...)
+    """
+    
+    def __init__(
+        self,
+        global_model: ModelProtocol,
+        alpha_0: float = 0.7,
+        alpha_min: float = 0.3,
+        gamma_0: float = 0.3,
+        gamma_min: float = 0.5,
+        eta: float = 0.5,
+        lambda_decay: float = 0.1,
+        s_min: float = 0,
+        anomaly_threshold: float = -0.5,
+        kl_threshold: float = 0.5,
+        enable_gradient_recycling: bool = True
+    ):
+        self.global_model = global_model
+        self.alpha_0 = alpha_0
+        self.alpha_min = alpha_min
+        self.gamma_0 = gamma_0
+        self.gamma_min = gamma_min
+        self.eta = eta
+        self.lambda_decay = lambda_decay
+        self.s_min = s_min
+        self.anomaly_threshold = anomaly_threshold
+        self.kl_threshold = kl_threshold
+        self.enable_gradient_recycling = enable_gradient_recycling
+        
+        # Gradient recycling storage
+        self.gradient_cache: Dict[int, Dict[str, np.ndarray]] = {}
+        self.current_round = 0
+    
+    def _compute_adaptive_weights(self, t: int) -> Tuple[float, float]:
+        """
+        Compute time-varying α(t) and γ(t).
+        
+        Returns:
+            Tuple of (alpha_t, gamma_t)
+        """
+        from arena_score.score import compute_adaptive_weights
+        return compute_adaptive_weights(
+            t,
+            self.alpha_0, self.alpha_min,
+            self.gamma_0, self.gamma_min,
+            self.lambda_decay
+        )
+    
+    def _compute_arena_score(
+        self,
+        delta_acc: float,
+        cosine_sim: float,
+        spectral_norm: float,
+        alpha_t: float,
+        gamma_t: float,
+        is_potentially_corrupted: bool = False
+    ) -> float:
+        """Compute ARENA score for a client update."""
+        from arena_score.score import compute_arena_score
+        return compute_arena_score(
+            delta_acc, cosine_sim, spectral_norm,
+            alpha_t, gamma_t, self.eta,
+            is_potentially_corrupted
+        )
+    
+    def _detect_anomaly(
+        self,
+        cosine_sim: float,
+        kl_divergence: float = 0.0,
+        is_potentially_corrupted: bool = False
+    ) -> bool:
+        """
+        Detect anomalous update using multiple criteria.
+        
+        From the paper:
+        - CS < -0.5 threshold
+        - KL divergence thresholds
+        """
+        from arena_score.score import detect_anomaly
+        return detect_anomaly(
+            cosine_sim, kl_divergence,
+            is_potentially_corrupted,
+            self.anomaly_threshold, self.kl_threshold
+        )
+    
+    def aggregate(
+        self,
+        client_weights: List[Dict[str, np.ndarray]],
+        client_metrics: List[Dict[str, Any]],
+        client_samples: List[int],
+        client_ids: List[int],
+        participating_clients: Optional[List[int]] = None
+    ) -> Tuple[Dict[str, np.ndarray], Dict[str, Any]]:
+        """
+        Aggregate client updates using ARENA scoring.
+        
+        Args:
+            client_weights: List of weight dictionaries from clients
+            client_metrics: List of metric dictionaries from clients
+            client_samples: Number of samples per client
+            client_ids: Client identifiers
+            participating_clients: Optional list of participating client IDs
+        
+        Returns:
+            Tuple of:
+            - aggregated_weights: New global model weights
+            - aggregation_info: Dict with scores, selected clients, etc.
+        
+        Example:
+            >>> aggregated, info = server.aggregate(
+            ...     client_weights, client_metrics, client_samples, client_ids
+            ... )
+            >>> print(f"Mean score: {info['mean_score']:.2f}")
+            >>> print(f"Valid clients: {info['valid_clients']}/{info['total_clients']}")
+        """
+        self.current_round += 1
+        alpha_t, gamma_t = self._compute_adaptive_weights(self.current_round)
+        
+        # Compute ARENA scores for each client
+        scores = []
+        is_anomaly = []
+        
+        for metrics in client_metrics:
+            kl_div = metrics.get('kl_divergence', 0.0)
+            is_corrupted = metrics.get('is_potentially_corrupted', False)
+            
+            score = self._compute_arena_score(
+                metrics['delta_acc'],
+                metrics['cosine_sim'],
+                metrics['spectral_norm'],
+                alpha_t, gamma_t,
+                is_potentially_corrupted=is_corrupted
+            )
+            
+            # Check for anomaly
+            anomaly = self._detect_anomaly(
+                metrics['cosine_sim'],
+                kl_divergence=kl_div,
+                is_potentially_corrupted=is_corrupted
+            )
+            
+            if anomaly:
+                score = 0.0  # Set score to 0 for anomalous updates
+            
+            scores.append(score)
+            is_anomaly.append(anomaly)
+        
+        scores = np.array(scores)
+        
+        # Filter clients by minimum score threshold
+        valid_mask = (scores >= self.s_min) & (~np.array(is_anomaly))
+        
+        # Fallback: if no clients pass, use all non-anomalous
+        if not np.any(valid_mask):
+            valid_mask = ~np.array(is_anomaly)
+        
+        # Final fallback: use all clients
+        if not np.any(valid_mask):
+            valid_mask = np.ones(len(scores), dtype=bool)
+        
+        # Normalize scores for weighting
+        valid_scores = np.where(valid_mask, scores, 0)
+        total_score = np.sum(valid_scores)
+        
+        if total_score > 0:
+            weights_normalized = valid_scores / total_score
+        else:
+            # Fall back to sample-based weighting
+            total_samples = sum(n for n, v in zip(client_samples, valid_mask) if v)
+            weights_normalized = np.array([
+                n / total_samples if v else 0
+                for n, v in zip(client_samples, valid_mask)
+            ])
+        
+        # Aggregate weights
+        aggregated: Dict[str, np.ndarray] = {}
+        for key in client_weights[0]:
+            aggregated[key] = np.zeros_like(client_weights[0][key])
+        
+        for w_client, weight in zip(client_weights, weights_normalized):
+            for key in w_client:
+                aggregated[key] += w_client[key] * weight
+        
+        # Gradient recycling: cache gradients for clients
+        if self.enable_gradient_recycling:
+            for client_id, metrics in zip(client_ids, client_metrics):
+                if 'accumulated_grads' in metrics and metrics['accumulated_grads'] is not None:
+                    self.gradient_cache[client_id] = metrics['accumulated_grads']
+        
+        # Update global model
+        self.global_model.set_weights(aggregated)
+        
+        aggregation_info = {
+            'round': self.current_round,
+            'alpha_t': alpha_t,
+            'gamma_t': gamma_t,
+            'scores': scores.tolist(),
+            'weights_normalized': weights_normalized.tolist(),
+            'is_anomaly': is_anomaly,
+            'valid_clients': int(np.sum(valid_mask)),
+            'total_clients': len(scores),
+            'mean_score': float(np.mean(scores)),
+            'std_score': float(np.std(scores))
+        }
+        
+        return aggregated, aggregation_info
+    
+    def get_global_weights(self) -> Dict[str, np.ndarray]:
+        """Get current global model weights."""
+        return self.global_model.get_weights()
+    
+    def get_recycled_gradient(self, client_id: int) -> Optional[Dict[str, np.ndarray]]:
+        """Get cached gradient for a missing client."""
+        return self.gradient_cache.get(client_id)
+    
+    def reset(self) -> None:
+        """Reset server state for a new training run."""
+        self.current_round = 0
+        self.gradient_cache.clear()

arena_score/utils.py

@@ -0,0 +1,207 @@
+"""
+ARENA Score Utility Functions
+
+Helper functions for weight manipulation, similarity computation,
+and anomaly detection metrics.
+"""
+
+import numpy as np
+from typing import Dict
+
+# Try Numba for acceleration
+try:
+    from numba import jit
+    HAS_NUMBA = True
+except ImportError:
+    HAS_NUMBA = False
+    def jit(*args, **kwargs):
+        """Fallback decorator when Numba is not available."""
+        def decorator(func):
+            return func
+        return decorator
+
+
+@jit(nopython=True, cache=True)
+def _compute_cosine_similarity_numba(a: np.ndarray, b: np.ndarray) -> float:
+    """Numba-optimized cosine similarity computation."""
+    dot = np.dot(a, b)
+    norm_a = np.sqrt(np.dot(a, a))
+    norm_b = np.sqrt(np.dot(b, b))
+    if norm_a < 1e-8 or norm_b < 1e-8:
+        return 0.0
+    return dot / (norm_a * norm_b)
+
+
+def compute_cosine_similarity(
+    weights_a: Dict[str, np.ndarray],
+    weights_b: Dict[str, np.ndarray]
+) -> float:
+    """
+    Compute cosine similarity between two weight dictionaries.
+    
+    Args:
+        weights_a: First weight dictionary
+        weights_b: Second weight dictionary
+    
+    Returns:
+        Cosine similarity in range [-1, 1]
+    
+    Example:
+        >>> cs = compute_cosine_similarity(model_a.get_weights(), model_b.get_weights())
+        >>> print(f"Similarity: {cs:.4f}")
+    """
+    flat_a = flatten_weights(weights_a)
+    flat_b = flatten_weights(weights_b)
+    
+    if HAS_NUMBA:
+        return float(_compute_cosine_similarity_numba(flat_a, flat_b))
+    
+    # Fallback pure numpy implementation
+    dot = np.dot(flat_a, flat_b)
+    norm_a = np.linalg.norm(flat_a)
+    norm_b = np.linalg.norm(flat_b)
+    
+    if norm_a < 1e-8 or norm_b < 1e-8:
+        return 0.0
+    
+    return float(dot / (norm_a * norm_b))
+
+
+def compute_spectral_norm(weights: Dict[str, np.ndarray]) -> float:
+    """
+    Compute spectral norm regularization term.
+    
+    Formula: SN_j = log(1 + σ_max(W_j))
+    
+    Where σ_max is the maximum singular value of the weight matrix.
+    
+    Args:
+        weights: Dictionary of weight arrays
+    
+    Returns:
+        Spectral norm value
+    
+    Example:
+        >>> sn = compute_spectral_norm(model.get_weights())
+        >>> print(f"Spectral Norm: {sn:.4f}")
+    """
+    max_singular = 0.0
+    
+    for key, w in weights.items():
+        if len(w.shape) == 2:
+            # Compute largest singular value for 2D matrices
+            try:
+                s = np.linalg.svd(w, compute_uv=False)
+                max_singular = max(max_singular, s[0])
+            except np.linalg.LinAlgError:
+                max_singular = max(max_singular, np.max(np.abs(w)))
+        else:
+            max_singular = max(max_singular, np.max(np.abs(w)))
+    
+    return float(np.log(1 + max_singular))
+
+
+def compute_kl_divergence(
+    p: np.ndarray,
+    q: np.ndarray,
+    eps: float = 1e-8
+) -> float:
+    """
+    Compute KL divergence between two probability distributions.
+    
+    Used for anomaly detection as per the paper (lines 17-18).
+    
+    Args:
+        p: Prediction distribution after local training
+        q: Prediction distribution before training (from global model)
+        eps: Small epsilon for numerical stability
+    
+    Returns:
+        KL divergence value (higher = more divergent = potentially corrupted)
+    
+    Example:
+        >>> kl = compute_kl_divergence(new_preds, old_preds)
+        >>> if kl > 0.5:
+        ...     print("Potential anomaly detected")
+    """
+    p = np.clip(p, eps, 1 - eps)
+    q = np.clip(q, eps, 1 - eps)
+    
+    # For binary classification, compute symmetric KL divergence
+    kl_pq = np.mean(p * np.log(p / q) + (1 - p) * np.log((1 - p) / (1 - q)))
+    
+    return float(kl_pq)
+
+
+def flatten_weights(weights: Dict[str, np.ndarray]) -> np.ndarray:
+    """
+    Flatten all weights into a single vector.
+    
+    Args:
+        weights: Dictionary of weight arrays
+    
+    Returns:
+        1D numpy array containing all flattened weights
+    
+    Example:
+        >>> flat = flatten_weights(model.get_weights())
+        >>> print(f"Total parameters: {len(flat)}")
+    """
+    return np.concatenate([w.flatten() for w in weights.values()])
+
+
+def unflatten_weights(
+    flat: np.ndarray,
+    template: Dict[str, np.ndarray]
+) -> Dict[str, np.ndarray]:
+    """
+    Unflatten vector back to weight dictionary.
+    
+    Args:
+        flat: 1D array of flattened weights
+        template: Template dictionary with correct shapes
+    
+    Returns:
+        Weight dictionary with original shapes
+    
+    Example:
+        >>> flat = flatten_weights(weights)
+        >>> restored = unflatten_weights(flat, weights)
+    """
+    result = {}
+    idx = 0
+    
+    for key, w in template.items():
+        size = w.size
+        result[key] = flat[idx:idx + size].reshape(w.shape)
+        idx += size
+    
+    return result
+
+
+def compute_weight_distance(
+    weights_a: Dict[str, np.ndarray],
+    weights_b: Dict[str, np.ndarray]
+) -> float:
+    """
+    Compute L2 distance between two weight dictionaries.
+    
+    Args:
+        weights_a: First weight dictionary
+        weights_b: Second weight dictionary
+    
+    Returns:
+        L2 distance (Euclidean norm of difference)
+    
+    Example:
+        >>> dist = compute_weight_distance(w1, w2)
+        >>> print(f"Weight distance: {dist:.4f}")
+    """
+    total_dist = 0.0
+    
+    for key in weights_a:
+        if key in weights_b:
+            diff = weights_a[key].flatten() - weights_b[key].flatten()
+            total_dist += np.sum(diff ** 2)
+    
+    return float(np.sqrt(total_dist))

arena_score-1.0.0.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: arena-score
+Version: 1.0.0
+Summary: ARENA Score - Adaptive Review and Evaluation using Novel Aggregation Score for Federated Learning
+Project-URL: Homepage, https://github.com/Ronit26Mehta/Arena_exp
+Project-URL: Documentation, https://github.com/Ronit26Mehta/Arena_exp#readme
+Project-URL: Repository, https://github.com/Ronit26Mehta/Arena_exp
+Project-URL: Issues, https://github.com/Ronit26Mehta/Arena_exp/issues
+Author-email: Ronit Mehta <mehtaronit702@gmail.com>
+Maintainer-email: Ronit Mehta <mehtaronit702@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: adaptive-aggregation,aggregation,anomaly-detection,arena-score,client-evaluation,deep-learning,distributed-systems,federated-learning,machine-learning,robust-aggregation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: numpy>=1.21.0
+Provides-Extra: accelerate
+Requires-Dist: numba>=0.56.0; extra == 'accelerate'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ARENA Score
+
+[![PyPI version](https://badge.fury.io/py/arena-score.svg)](https://badge.fury.io/py/arena-score)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**ARENA Score** (Adaptive Review and Evaluation using Novel Aggregation Score) is a novel client evaluation and weighted aggregation algorithm for Federated Learning.
+
+## 🎯 Key Features
+
+- **Adaptive Client Evaluation**: Dynamically assesses client update quality using multiple metrics
+- **Robust Aggregation**: Filters out unreliable/malicious client contributions
+- **Anomaly Detection**: Detects Byzantine clients using KL divergence and cosine similarity
+- **Gradient Recycling**: Maintains momentum by reusing successful updates from missing clients
+- **Model Agnostic**: Works with any model that implements the simple weight interface
+
+## 📊 ARENA Score Formula
+
+```
+S_j = α(t) × max(0, ΔAcc_j) + γ(t) × CS_j + η × SN_j/(1 + SN_j)
+```
+
+Where:
+- **ΔAcc** - Local accuracy improvement
+- **CS** - Cosine similarity between client update and global direction
+- **SN** - Spectral norm: `log(1 + σ_max(W_j))`
+- **α(t), γ(t)** - Adaptive time-varying weights
+
+## 🚀 Installation
+
+```bash
+pip install arena-score
+```
+
+For Numba acceleration (optional):
+```bash
+pip install arena-score[accelerate]
+```
+
+## 📝 Quick Start
+
+```python
+from arena_score import ARENAScoreClient, ARENAScoreServer, run_arena_score
+
+# Create clients with your model
+clients = [
+    ARENAScoreClient(
+        client_id=i,
+        model=your_model.copy(),  # Model with get_weights/set_weights
+        X=X_train[i],
+        y=y_train[i],
+        local_epochs=5,
+        batch_size=32
+    )
+    for i in range(n_clients)
+]
+
+# Run ARENA Score federated learning
+history = run_arena_score(
+    global_model=your_model,
+    clients=clients,
+    n_rounds=10,
+    eval_data=(X_test, y_test)
+)
+
+print(f"Final accuracy: {history['test_accuracy'][-1]:.4f}")
+```
+
+## 🔧 Advanced Usage
+
+### Custom Server Configuration
+
+```python
+from arena_score import ARENAScoreServer
+
+server = ARENAScoreServer(
+    global_model=model,
+    alpha_0=0.7,           # Initial accuracy weight
+    alpha_min=0.3,         # Minimum accuracy weight
+    gamma_0=0.3,           # Initial cosine similarity weight
+    gamma_min=0.5,         # Minimum cosine similarity weight
+    eta=0.5,               # Spectral norm coefficient
+    lambda_decay=0.1,      # Decay rate for adaptive weights
+    anomaly_threshold=-0.5, # CS threshold for anomaly detection
+    kl_threshold=0.5,      # KL divergence threshold
+    enable_gradient_recycling=True
+)
+```
+
+### Computing ARENA Score Directly
+
+```python
+from arena_score import compute_arena_score
+
+score = compute_arena_score(
+    delta_acc=0.05,      # Accuracy improvement
+    cosine_sim=0.8,      # Cosine similarity
+    spectral_norm=2.5,   # Spectral norm
+    alpha_t=0.5,         # Current alpha weight
+    gamma_t=0.4          # Current gamma weight
+)
+```
+
+### Utility Functions
+
+```python
+from arena_score import (
+    compute_cosine_similarity,
+    compute_spectral_norm,
+    compute_kl_divergence,
+    flatten_weights,
+    unflatten_weights
+)
+
+# Compute cosine similarity between weight vectors
+cs = compute_cosine_similarity(weights_a, weights_b)
+
+# Compute spectral norm of weights
+sn = compute_spectral_norm(weights_dict)
+```
+
+## 📈 Model Interface
+
+Your model must implement these methods:
+
+```python
+class YourModel:
+    def get_weights(self) -> Dict[str, np.ndarray]:
+        """Return model weights as a dictionary."""
+        pass
+    
+    def set_weights(self, weights: Dict[str, np.ndarray]):
+        """Set model weights from a dictionary."""
+        pass
+    
+    def forward(self, X: np.ndarray) -> np.ndarray:
+        """Forward pass, returns predictions."""
+        pass
+    
+    def backward(self, X, y, y_pred) -> Dict[str, np.ndarray]:
+        """Backward pass, returns gradients."""
+        pass
+    
+    def update_weights(self, gradients: Dict[str, np.ndarray]):
+        """Update weights using gradients."""
+        pass
+    
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """Make predictions (0/1 for classification)."""
+        pass
+    
+    def predict_proba(self, X: np.ndarray) -> np.ndarray:
+        """Return probability predictions."""
+        pass
+    
+    def copy(self) -> 'YourModel':
+        """Return a deep copy of the model."""
+        pass
+```
+
+<!-- ## 📄 Citation
+
+If you use ARENA Score in your research, please cite:
+
+```bibtex
+@article{arena_score2026,
+  title={ARENA Score: Adaptive Review and Evaluation using Novel Aggregation Score for Federated Learning},
+  author={Mehta, Ronit},
+  year={2026}
+}
+``` -->
+
+## 📜 License
+
+MIT License - see [LICENSE](LICENSE) for details.

arena_score-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+arena_score/__init__.py,sha256=Cyk7ffH8TPvT0qDSPd7VJfAcNEWy7iQrxe72DsRlokA,1269
+arena_score/aggregator.py,sha256=Umrfx72Fi0QnmuiEQc5KGoB2qA3A9pbEnupBrQ8qNX4,6601
+arena_score/client.py,sha256=fbBkOvpTrr-rYsO4nbpgawpTKS8ba7p_QfO0E94upJ4,8801
+arena_score/score.py,sha256=PbHNhSjFfyrpACTGqvQu3JYLnVyUt4aC834YnQGLAAI,5115
+arena_score/server.py,sha256=wg_lehQasXxAcO-6basXTANwnEcIRlGCnP60sid73iA,9876
+arena_score/utils.py,sha256=44My0OioHsyGDI_JzDQWFTamrnav5uEBVPR2b8xh1BE,5766
+arena_score-1.0.0.dist-info/METADATA,sha256=Eq1gkaq6nlQ7A8EM3Q8ZpJJgEEMY-fUY9qF1LDE0WrA,6609
+arena_score-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+arena_score-1.0.0.dist-info/licenses/LICENSE,sha256=vxLqz6mA4Swb4VY17lg4XEpWmiwkUqeXTmlcIqdF92Q,1089
+arena_score-1.0.0.dist-info/RECORD,,

arena_score-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

arena_score-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronit Mehta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.