secure-fl 26.8.85__py3-none-any.whl

secure_fl/__init__.py

@@ -0,0 +1,452 @@
+"""
+Secure FL: Dual-Verifiable Federated Learning with Zero-Knowledge Proofs
+
+A dual-verifiable framework for federated learning using zero-knowledge proofs to ensure
+training integrity and aggregation correctness.
+
+Main components:
+- Core: Types, exceptions, configuration, and version information
+- Federation: FL clients, servers, and aggregation algorithms
+- ZKP: Zero-knowledge proof managers and quantization
+- Models: Pre-built neural network architectures
+- Utils: Logging, parameter handling, and helper utilities
+- CLI: Command-line interface for interaction
+
+Example usage:
+    # Server setup
+    from secure_fl import create_server_strategy, SecureFlowerServer
+
+    strategy = create_server_strategy(
+        model_fn=lambda: MyModel(),
+        enable_zkp=True,
+        proof_rigor="high"
+    )
+    server = SecureFlowerServer(strategy=strategy)
+    server.start(num_rounds=10)
+
+    # Client setup
+    from secure_fl import create_client, start_client
+
+    client = create_client(
+        client_id="client_1",
+        model_fn=lambda: MyModel(),
+        train_data=train_dataset,
+        enable_zkp=True
+    )
+    start_client(client, "localhost:8080")
+"""
+
+from typing import Any
+
+# Version information
+from .core import DEFAULT_CLIENT_CONFIG
+from .core import DEFAULT_SERVER_CONFIG
+from .core import DEFAULT_ZKP_CONFIG
+from .core import AggregationError
+from .core import AggregationResult
+from .core import BaseAggregator
+from .core import BaseProofManager
+from .core import CircuitCompilationError
+from .core import ClientConfig
+from .core import ClientError
+from .core import ClientID  # Types
+from .core import ComponentStatus
+from .core import ConfigManager
+from .core import ConfigurationError
+from .core import DataError
+from .core import Metrics
+from .core import ModelError
+from .core import ModelFunction
+from .core import ModelParameters
+from .core import NetworkError
+from .core import ProofData
+from .core import ProofError
+from .core import ProofGenerationError
+from .core import ProofID
+from .core import ProofMetrics
+from .core import ProofResult
+from .core import ProofRigor
+from .core import ProofVerificationError
+from .core import QuantizationBits
+from .core import QuantizationError
+from .core import RoundID
+
+# Core components
+from .core import SecureFlConfig  # Configuration
+from .core import SecureFlError  # Exceptions
+from .core import ServerConfig
+from .core import ServerError
+from .core import SystemMetrics
+from .core import TrainingMetrics
+from .core import TrainingPhase
+from .core import TrainingResult
+from .core import ValidationError
+from .core import ValidationResult
+from .core import ZKPConfig
+from .core import __version__
+from .core import create_example_config
+from .core import ensure_model_parameters
+from .core import get_client_config
+from .core import get_default_config
+from .core import get_server_config
+from .core import get_zkp_config
+from .core import handle_error
+from .core import is_valid_client_id  # Utilities
+from .core import is_valid_proof_rigor
+from .core import is_valid_round_id
+from .core import load_config
+from .core import safe_execute
+from .core import save_config
+from .core import validate_client_id
+from .core import validate_positive_int
+from .core import validate_proof_rigor
+from .core import validate_range
+from .core import wrap_error
+from .federation import FedJSCMAggregator
+from .federation import SecureFlowerClient
+
+# Federation components
+from .federation import SecureFlowerServer
+from .federation import SecureFlowerStrategy
+from .federation import StabilityMetrics
+from .federation import StabilityMonitor
+from .federation import create_client
+from .federation import create_server_strategy
+from .federation import start_client
+from .models import MNISTCNN
+from .models import ResNet18Model
+
+# Models
+from .models import SimpleModel
+from .models import model_fn
+from .utils import AuditLogger
+from .utils import PerformanceLogger
+from .utils import SecureFlLogger
+from .utils import aggregate_weighted_average
+from .utils import compute_hash
+from .utils import compute_parameter_diff
+from .utils import compute_parameter_norm
+from .utils import deserialize_parameters
+from .utils import get_client_logger
+from .utils import get_logger
+from .utils import get_parameter_stats
+from .utils import get_proof_logger
+from .utils import get_server_logger
+from .utils import ndarrays_to_parameters
+from .utils import ndarrays_to_torch
+
+# Utility functions
+from .utils import parameters_to_ndarrays  # Parameter utilities
+from .utils import serialize_parameters
+from .utils import setup_development_logging
+from .utils import setup_logging  # Logging utilities
+from .utils import setup_production_logging
+from .utils import setup_testing_logging
+from .utils import torch_to_ndarrays
+from .utils import validate_parameters
+
+# ZKP components
+from .zkp import ClientProofManager
+from .zkp import FixedPointQuantizer
+from .zkp import GradientAwareQuantizer
+from .zkp import QuantizationConfig
+from .zkp import QuantizationScheme
+from .zkp import ScaleMethod
+from .zkp import ServerProofManager
+from .zkp import compute_quantization_error
+from .zkp import dequantize_parameters
+from .zkp import get_circuit_friendly_config
+from .zkp import get_high_precision_config
+from .zkp import get_int8_config
+from .zkp import quantize_parameters
+
+# Package metadata
+__author__ = "Krishant Timilsina, Bindu Paudel"
+__email__ = "krishtimil@gmail.com, binduupaudel565@gmail.com"
+__title__ = "secure-fl"
+__description__ = (
+    "Dual-Verifiable Framework for Federated Learning using Zero-Knowledge Proofs"
+)
+__url__ = "https://github.com/krishantt/secure-fl"
+__license__ = "MIT"
+__copyright__ = "Copyright (c) 2024 Krishant Timilsina, Bindu Paudel"
+
+# Export main classes and functions
+__all__ = [
+    # Version information
+    "__version__",
+    # Package metadata
+    "__author__",
+    "__email__",
+    "__title__",
+    "__description__",
+    "__url__",
+    "__license__",
+    "__copyright__",
+    # Configuration
+    "SecureFlConfig",
+    "ConfigManager",
+    "get_default_config",
+    "load_config",
+    "save_config",
+    "get_server_config",
+    "get_client_config",
+    "get_zkp_config",
+    "create_example_config",
+    # Types
+    "ClientID",
+    "RoundID",
+    "ProofID",
+    "ModelFunction",
+    "ModelParameters",
+    "ProofData",
+    "Metrics",
+    "ProofRigor",
+    "QuantizationBits",
+    "TrainingPhase",
+    "ComponentStatus",
+    "ClientConfig",
+    "ServerConfig",
+    "ZKPConfig",
+    "TrainingMetrics",
+    "ProofMetrics",
+    "SystemMetrics",
+    "TrainingResult",
+    "ProofResult",
+    "AggregationResult",
+    "ValidationResult",
+    "BaseProofManager",
+    "BaseAggregator",
+    "DEFAULT_CLIENT_CONFIG",
+    "DEFAULT_SERVER_CONFIG",
+    "DEFAULT_ZKP_CONFIG",
+    "is_valid_client_id",
+    "is_valid_round_id",
+    "is_valid_proof_rigor",
+    "ensure_model_parameters",
+    # Main FL components
+    "SecureFlowerServer",
+    "SecureFlowerStrategy",
+    "SecureFlowerClient",
+    "create_server_strategy",
+    "create_client",
+    "start_client",
+    # Aggregation
+    "FedJSCMAggregator",
+    # ZKP components
+    "ClientProofManager",
+    "ServerProofManager",
+    # Stability monitoring
+    "StabilityMonitor",
+    "StabilityMetrics",
+    # Quantization
+    "FixedPointQuantizer",
+    "GradientAwareQuantizer",
+    "QuantizationConfig",
+    "ScaleMethod",
+    "QuantizationScheme",
+    "quantize_parameters",
+    "dequantize_parameters",
+    "compute_quantization_error",
+    "get_int8_config",
+    "get_circuit_friendly_config",
+    "get_high_precision_config",
+    # Utilities
+    "parameters_to_ndarrays",
+    "ndarrays_to_parameters",
+    "torch_to_ndarrays",
+    "ndarrays_to_torch",
+    "compute_parameter_norm",
+    "compute_parameter_diff",
+    "compute_hash",
+    "serialize_parameters",
+    "deserialize_parameters",
+    "aggregate_weighted_average",
+    "validate_parameters",
+    "get_parameter_stats",
+    # Logging
+    "setup_logging",
+    "setup_development_logging",
+    "setup_production_logging",
+    "setup_testing_logging",
+    "get_logger",
+    "SecureFlLogger",
+    "PerformanceLogger",
+    "AuditLogger",
+    "get_client_logger",
+    "get_server_logger",
+    "get_proof_logger",
+    # Exceptions
+    "SecureFlError",
+    "ConfigurationError",
+    "ClientError",
+    "ServerError",
+    "ProofError",
+    "CircuitCompilationError",
+    "ProofGenerationError",
+    "ProofVerificationError",
+    "AggregationError",
+    "QuantizationError",
+    "DataError",
+    "NetworkError",
+    "ValidationError",
+    "ModelError",
+    "handle_error",
+    "wrap_error",
+    "safe_execute",
+    "validate_positive_int",
+    "validate_range",
+    "validate_client_id",
+    "validate_proof_rigor",
+    # Models
+    "SimpleModel",
+    "MNISTCNN",
+    "ResNet18Model",
+    "model_fn",
+]
+
+
+def get_default_config_dict() -> dict[str, Any]:
+    """Get default configuration as dictionary (for backward compatibility)."""
+    return get_default_config().to_dict()
+
+
+def _command_available(command: list[str], timeout: int = 5) -> bool:
+    import subprocess
+
+    try:
+        result = subprocess.run(command, capture_output=True, timeout=timeout)
+        return result.returncode == 0
+    except (subprocess.SubprocessError, OSError, FileNotFoundError):
+        return False
+
+
+def _get_component_status() -> dict[str, bool]:
+    components = {
+        "Flower": False,
+        "PyTorch": False,
+        "Circom": _command_available(["circom", "--version"]),
+        "SnarkJS": _command_available(["snarkjs", "help"]),
+    }
+
+    try:
+        import torch  # noqa: F401
+
+        components["PyTorch"] = True
+    except ImportError:
+        pass
+
+    try:
+        import flwr  # noqa: F401
+
+        components["Flower"] = True
+    except ImportError:
+        pass
+
+    return components
+
+
+def print_system_info() -> None:
+    """Print system information and component status."""
+    print(f"Secure FL v{__version__}")
+    print(f"Description: {__description__}")
+    print(f"Authors: {__author__}")
+    print()
+
+    components = _get_component_status()
+
+    print("Component Status:")
+    for component, available in components.items():
+        status = "✓ Available" if available else "✗ Not Found"
+        print(f"  {component}: {status}")
+
+    print()
+    print("Note: Cairo, Circom, and SnarkJS are required for full ZKP functionality")
+    print("Install them separately for complete proof generation capabilities")
+
+
+def create_secure_fl_setup(
+    model_fn: Any,
+    train_datasets: Any,
+    val_datasets: Any = None,
+    config: Any = None,
+) -> Any:
+    """
+    Create a complete secure FL setup with server and multiple clients.
+
+    Args:
+        model_fn: Function that returns a PyTorch model
+        train_datasets: List of training datasets for each client
+        val_datasets: Optional list of validation datasets
+        config: Optional configuration dictionary or SecureFlConfig instance
+
+    Returns:
+        Tuple of (server, clients) ready for training
+    """
+    if config is None:
+        config = get_default_config()
+
+    # Create server strategy
+    if isinstance(config, SecureFlConfig):
+        server_config = config.server
+    else:
+        # Legacy dict format
+        server_config = ServerConfig(**config.get("server", {}))
+
+    strategy = create_server_strategy(
+        model_fn=model_fn,
+        momentum=server_config.momentum,
+        learning_rate=server_config.learning_rate,
+        enable_zkp=server_config.enable_zkp,
+        proof_rigor=(
+            server_config.proof_rigor.value
+            if isinstance(server_config.proof_rigor, ProofRigor)
+            else server_config.proof_rigor
+        ),
+    )
+
+    # Create server
+    if isinstance(config, SecureFlConfig):
+        server = SecureFlowerServer(
+            strategy=strategy, num_rounds=config.server.num_rounds
+        )
+    else:
+        # Legacy dict format
+        server = SecureFlowerServer(strategy=strategy, **config.get("server", {}))
+
+    # Create clients
+    clients = []
+    for i, train_data in enumerate(train_datasets):
+        val_data = val_datasets[i] if val_datasets else None
+
+        if isinstance(config, SecureFlConfig):
+            client_config = config.client
+            client = create_client(
+                client_id=f"client_{i}",
+                model_fn=model_fn,
+                train_data=train_data,
+                val_data=val_data,
+                enable_zkp=client_config.enable_zkp,
+                proof_rigor=(
+                    client_config.proof_rigor.value
+                    if isinstance(client_config.proof_rigor, ProofRigor)
+                    else client_config.proof_rigor
+                ),
+                quantization_bits=(
+                    client_config.quantization_bits.value
+                    if isinstance(client_config.quantization_bits, QuantizationBits)
+                    else client_config.quantization_bits
+                ),
+            )
+        else:
+            # Legacy dict format
+            client = create_client(
+                client_id=f"client_{i}",
+                model_fn=model_fn,
+                train_data=train_data,
+                val_data=val_data,
+                **config.get("zkp", {}),
+            )
+        clients.append(client)
+
+    return server, clients

secure_fl/__main__.py

@@ -0,0 +1,11 @@
+"""
+Main entry point for Secure FL CLI
+
+This allows the package to be executed as a module:
+python -m secure_fl <command>
+"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

secure_fl/benchmarks/__init__.py

@@ -0,0 +1,42 @@
+"""Benchmark orchestration helpers for experiment entrypoints."""
+
+from secure_fl.data.benchmark_data import SUPPORTED_DATASETS
+from secure_fl.data.benchmark_data import kfold_split_indices
+from secure_fl.data.benchmark_data import load_dataset
+from secure_fl.data.benchmark_data import normalize_datasets
+from secure_fl.data.benchmark_data import partition_dataset
+from secure_fl.data.benchmark_data import subsample_dataset
+from secure_fl.models.factory import model_fn
+
+from .attacks import ATTACK_SCALE
+from .attacks import MAX_NORM
+from .attacks import GradientPoisonClient
+from .attacks import run_attack_fold
+from .defaults import PAPER_DEFAULT_ROUNDS
+from .defaults import resolve_num_rounds
+from .execution import run_training_rounds
+from .pipeline import run_single
+from .reporting import build_tradeoff_report
+from .reporting import summarize_folds
+from .reporting import summarize_repeats
+
+__all__ = [
+    "PAPER_DEFAULT_ROUNDS",
+    "resolve_num_rounds",
+    "SUPPORTED_DATASETS",
+    "normalize_datasets",
+    "load_dataset",
+    "partition_dataset",
+    "subsample_dataset",
+    "kfold_split_indices",
+    "model_fn",
+    "run_single",
+    "run_attack_fold",
+    "run_training_rounds",
+    "summarize_folds",
+    "summarize_repeats",
+    "build_tradeoff_report",
+    "GradientPoisonClient",
+    "MAX_NORM",
+    "ATTACK_SCALE",
+]