fedora-fl 2.1.0b2__py3-none-any.whl

fedora/__init__.py

@@ -0,0 +1,535 @@
+"""Fedora: federated knowledge learning for agents and FL systems.
+
+Fedora helps distributed agents and organizations share useful learned knowledge
+without sharing raw private data, full local memory, or unrestricted internal
+state. Classic federated learning remains the ``parameters`` artifact type; the
+same planning surface can also represent adapters, memories, skills, traces,
+evaluation results, facts, policies, and distilled examples.
+
+It provides:
+
+- **Clean API**: Decorator and class-based client abstractions
+- **Simulation**: Run FL experiments locally without distributed infrastructure
+- **Knowledge Artifacts**: Typed exchange units for federated knowledge workflows
+- **Privacy and Trust Controls**: Threat models, robust aggregation, differential privacy
+- **Async Capable**: FedBuff-style buffered aggregation, deadline-based execution
+- **Transport Agnostic**: Local, gRPC, and WebSocket communication
+- **Aggregator Registry**: FedAvg, Krum, MultiKrum, Bulyan, FedAdam, and more
+- **Plan-First API**: Compile UFCG programs into inspectable plans with plan IDs
+
+Quick Start:
+
+    import fedora
+    import numpy as np
+
+    @fedora.client
+    def train(parameters, config):
+        updated = [p + np.random.randn(*p.shape) * 0.01 for p in parameters]
+        return updated, 100, {"loss": 0.5}
+
+    history = fedora.simulate(
+        client_fn=lambda cid: train,
+        num_clients=10,
+        num_rounds=5,
+    )
+    print(history.summary())
+
+Documentation: https://github.com/uib-slate/fedora
+"""
+
+from __future__ import annotations
+
+__version__ = "2.1.0b2"
+
+# Core engine abstractions
+# Aggregation strategies
+from .adapters.capabilities import (
+    BACKEND_CAPABILITY_MATRIX,
+    get_backend_capabilities,
+    validate_adapter_diagnostics,
+)
+from .aggregation import (
+    SCAFFOLD,
+    Aggregator,
+    Bulyan,
+    ClipNorm,
+    CoordinateMedian,
+    DPAggregator,
+    DPConfig,
+    FedAdagrad,
+    FedAdam,
+    FedAvg,
+    FedNova,
+    FedProx,
+    FedYogi,
+    FoolsGold,
+    GaussianMechanism,
+    Krum,
+    LoRAAggregator,
+    LoRAFFA,
+    LoRAFlexLoRA,
+    LoRAMergedDelta,
+    MixedPrecisionAggregator,
+    MultiKrum,
+    PrivacyAccountant,
+    RDPAccountant,
+    SecAgg,
+    SecAggPlus,
+    SecureAggregator,
+    SimpleAccountant,
+    TrimmedMean,
+    ZCDPAccountant,
+    get_aggregator,
+    list_aggregators,
+    register_aggregator,
+)
+from .artifacts import (
+    ARTIFACT_PROFILES,
+    ARTIFACT_THREAT_NOTES,
+    ARTIFACT_TYPES,
+    DEFAULT_ARTIFACT_TYPE,
+    ArtifactProfile,
+    ArtifactSpec,
+    describe_artifact,
+    get_artifact_profile,
+    validate_artifact_type,
+)
+from .backends.grpc_validation import (
+    raise_for_invalid_grpc_deployment,
+    validate_grpc_deployment_config,
+)
+
+# Framework client wrappers (optional dependencies)
+from .clients import (
+    FastaiClient,
+    HuggingFaceClient,
+    JaxClient,
+    LayerSelector,
+    PartialTrainingClient,
+    PyTorchClient,
+    SklearnClient,
+    TensorFlowClient,
+    XGBoostClient,
+    detect_framework,
+    get_framework_params,
+    set_framework_params,
+)
+
+# Compatibility layer (optional, for Flower migration)
+from .compat import (
+    FedoraFlowerAdapter,
+    FlowerClientAdapter,
+    FlowerStrategyAdapter,
+    MigrationHelper,
+    MigrationReport,
+)
+from .engine import (
+    Client,
+    ClientConfig,
+    ClientProxy,
+    ClientStatus,
+    Config,
+    EvalResult,
+    FederationServer,
+    FitResult,
+    Metrics,
+    NDArrays,
+    NumPyClient,
+    Parameters,
+    RoundConfig,
+    RoundManager,
+    RoundMode,
+    RoundResult,
+    Scalar,
+    ServerConfig,
+    ServerState,
+    client,
+)
+from .evidence import (
+    build_evidence_bundle,
+    run_proof_workflow,
+    verify_evidence_bundle,
+    verify_receipt_chain,
+)
+
+# Exception hierarchy
+from .exceptions import (
+    AggregationError,
+    ClientError,
+    ConfigurationError,
+    FedoraError,
+    InsecureTransportWarning,
+    PrivacyBudgetExhausted,
+    RoundError,
+    SecurityError,
+    SerializationError,
+    TransportError,
+)
+from .knowledge import (
+    AdoptionGate,
+    ArtifactValidationIssue,
+    ArtifactValidationResult,
+    CanaryAudit,
+    CanaryFinding,
+    CanaryReport,
+    FederationResult,
+    KnowledgeArtifact,
+    KnowledgeThreatControls,
+    KnowledgeThreatModel,
+    MergeReport,
+    RejectedArtifact,
+    federate,
+    filter_valid_artifacts,
+    merge_knowledge_artifacts,
+    validate_knowledge_artifact,
+)
+
+# Plan-first API
+from .planning import KnowledgeObjective, Plan, ThreatScenario, list_scenarios, plan, scenario
+from .schema_validation import SCHEMA_NAMES, load_schema, validate_json_schema
+
+# Security module
+from .security import (
+    Attack,
+    AuditEvent,
+    AuditTrail,
+    BackdoorAttack,
+    ContributionScoring,
+    Defense,
+    DefenseRecommendation,
+    FreeRider,
+    GradientInversion,
+    LabelFlip,
+    ModelReplace,
+    NormClipping,
+    ScalingAttack,
+    ShamirSecretSharing,
+    SignFlip,
+    SimilarityFilter,
+    SpectralDetector,
+    ThreatModel,
+    TrustManager,
+)
+
+# Simulation engine
+from .simulation import (
+    DataDistributor,
+    DeviceProfile,
+    DeviceSimulator,
+    DeviceType,
+    RoundHistory,
+    SimulationHistory,
+    SimulationRunner,
+    Subset,
+    VirtualClient,
+    VirtualClientManager,
+)
+
+# Transport layer
+from .transport import (
+    ClientTransport,
+    GrpcClientTransport,
+    GrpcServerTransport,
+    LocalClientTransport,
+    LocalServerTransport,
+    ServerTransport,
+    TLSConfig,
+    WebSocketClientTransport,
+    WebSocketServerTransport,
+    deserialize_client_config,
+    deserialize_eval_result,
+    deserialize_fit_result,
+    deserialize_parameters,
+    get_transport,
+    list_transports,
+    parse_transport_url,
+    register_transport,
+    serialize_client_config,
+    serialize_eval_result,
+    serialize_fit_result,
+    serialize_parameters,
+)
+
+
+# Convenience function: simulate is the main entry point for FL experiments
+def simulate(
+    client_fn,
+    num_clients: int,
+    num_rounds: int,
+    aggregator: str | Aggregator | None = None,
+    artifact: str = DEFAULT_ARTIFACT_TYPE,
+    threat_model: ThreatModel | None = None,
+    attack_fn=None,
+    defenses: list | None = None,
+    **kwargs,
+) -> SimulationHistory:
+    """Run a federated learning simulation.
+
+    This is the main entry point for running FL experiments locally. It handles
+    creating virtual clients, managing communication, and aggregating updates.
+
+    All security features compose automatically:
+    - Pass a ThreatModel to auto-select aggregator, DP, and defenses
+    - Pass an explicit aggregator to override the auto-selection
+    - Pass defenses to filter malicious updates before aggregation
+    - Pass attack_fn to simulate Byzantine clients
+
+    Args:
+        client_fn: Callable that takes client_id and returns a Client instance.
+        num_clients: Total number of virtual clients.
+        num_rounds: Number of training rounds.
+        aggregator: Aggregator instance or name string (e.g., "krum", "fedavg").
+                    If None and threat_model is set, auto-selected from threat model.
+        artifact: Knowledge artifact type exchanged by this run
+                  (e.g., "parameters", "adapter", "tool_trace").
+        threat_model: ThreatModel for automatic defense configuration.
+        attack_fn: Function(client_id) -> Attack or None for simulation.
+        defenses: List of Defense instances to filter results before aggregation.
+        **kwargs: Additional arguments passed to SimulationRunner
+                  (data, data_distribution, seed, dropout_rate, etc.)
+
+    Returns:
+        SimulationHistory with results, metrics, and analytics.
+
+    Examples:
+        Basic simulation::
+
+            history = fedora.simulate(
+                client_fn=lambda cid: MyClient(),
+                num_clients=10,
+                num_rounds=5,
+            )
+
+        With threat model (auto-configures everything)::
+
+            history = fedora.simulate(
+                client_fn=lambda cid: MyClient(),
+                num_clients=50,
+                num_rounds=10,
+                threat_model=fedora.ThreatModel(
+                    byzantine_fraction=0.2,
+                    privacy_level="strong",
+                ),
+            )
+
+        With explicit aggregator + attacks::
+
+            history = fedora.simulate(
+                client_fn=lambda cid: MyClient(),
+                num_clients=50,
+                num_rounds=10,
+                aggregator=fedora.Krum(num_byzantine=5),
+                attack_fn=lambda cid: fedora.ScalingAttack(10) if int(cid) < 10 else None,
+                defenses=[fedora.NormClipping(1.0)],
+            )
+    """
+    # Resolve aggregator: instance or string name
+    agg_instance = None
+    agg_name = None
+    if isinstance(aggregator, str):
+        agg_name = aggregator
+    elif aggregator is not None:
+        agg_instance = aggregator
+
+    runner = SimulationRunner(
+        client_fn=client_fn,
+        num_clients=num_clients,
+        num_rounds=num_rounds,
+        aggregator=agg_instance,
+        aggregator_name=agg_name,
+        artifact=artifact,
+        threat_model=threat_model,
+        attack_fn=attack_fn,
+        defenses=defenses,
+        **kwargs,
+    )
+    return runner.run()
+
+
+__all__ = [
+    "__version__",
+    # Knowledge artifacts
+    "ARTIFACT_PROFILES",
+    "ARTIFACT_TYPES",
+    "ARTIFACT_THREAT_NOTES",
+    "ArtifactProfile",
+    "ArtifactSpec",
+    "DEFAULT_ARTIFACT_TYPE",
+    "KnowledgeArtifact",
+    "KnowledgeObjective",
+    "KnowledgeThreatControls",
+    "KnowledgeThreatModel",
+    "FederationResult",
+    "AdoptionGate",
+    "CanaryAudit",
+    "CanaryFinding",
+    "CanaryReport",
+    "ArtifactValidationIssue",
+    "ArtifactValidationResult",
+    "MergeReport",
+    "RejectedArtifact",
+    "describe_artifact",
+    "filter_valid_artifacts",
+    "federate",
+    "get_artifact_profile",
+    "merge_knowledge_artifacts",
+    "validate_knowledge_artifact",
+    "validate_artifact_type",
+    # Core engine
+    "Client",
+    "NumPyClient",
+    "client",
+    "ClientConfig",
+    "ClientProxy",
+    "ClientStatus",
+    "Config",
+    "EvalResult",
+    "FitResult",
+    "Metrics",
+    "NDArrays",
+    "Parameters",
+    "Scalar",
+    "ServerState",
+    "RoundConfig",
+    "RoundMode",
+    "RoundManager",
+    "RoundResult",
+    "FederationServer",
+    "ServerConfig",
+    # Aggregation
+    "Aggregator",
+    "FedAvg",
+    "FedProx",
+    "FedNova",
+    "SCAFFOLD",
+    "TrimmedMean",
+    "CoordinateMedian",
+    "Krum",
+    "MultiKrum",
+    "Bulyan",
+    "FoolsGold",
+    "LoRAAggregator",
+    "LoRAFFA",
+    "LoRAFlexLoRA",
+    "LoRAMergedDelta",
+    "FedAdam",
+    "FedAdagrad",
+    "FedYogi",
+    "DPConfig",
+    "GaussianMechanism",
+    "ClipNorm",
+    "DPAggregator",
+    "PrivacyAccountant",
+    "SimpleAccountant",
+    "RDPAccountant",
+    "ZCDPAccountant",
+    "SecureAggregator",
+    "SecAgg",
+    "SecAggPlus",
+    "MixedPrecisionAggregator",
+    "get_aggregator",
+    "list_aggregators",
+    "register_aggregator",
+    # Security
+    "ThreatModel",
+    "DefenseRecommendation",
+    "Attack",
+    "LabelFlip",
+    "BackdoorAttack",
+    "SignFlip",
+    "ScalingAttack",
+    "ModelReplace",
+    "FreeRider",
+    "GradientInversion",
+    "Defense",
+    "NormClipping",
+    "ContributionScoring",
+    "SimilarityFilter",
+    "SpectralDetector",
+    "TrustManager",
+    "AuditEvent",
+    "AuditTrail",
+    "ShamirSecretSharing",
+    # Simulation
+    "SimulationRunner",
+    "VirtualClientManager",
+    "VirtualClient",
+    "DataDistributor",
+    "Subset",
+    "SimulationHistory",
+    "RoundHistory",
+    "DeviceSimulator",
+    "DeviceProfile",
+    "DeviceType",
+    "simulate",
+    # Transport
+    "ServerTransport",
+    "ClientTransport",
+    "LocalServerTransport",
+    "LocalClientTransport",
+    "GrpcServerTransport",
+    "GrpcClientTransport",
+    "WebSocketServerTransport",
+    "WebSocketClientTransport",
+    "register_transport",
+    "get_transport",
+    "list_transports",
+    "parse_transport_url",
+    "serialize_parameters",
+    "deserialize_parameters",
+    "serialize_fit_result",
+    "deserialize_fit_result",
+    "serialize_eval_result",
+    "deserialize_eval_result",
+    "serialize_client_config",
+    "deserialize_client_config",
+    "TLSConfig",
+    # Exceptions
+    "FedoraError",
+    "ConfigurationError",
+    "AggregationError",
+    "ClientError",
+    "RoundError",
+    "SecurityError",
+    "TransportError",
+    "SerializationError",
+    "PrivacyBudgetExhausted",
+    "InsecureTransportWarning",
+    # Framework clients
+    "PyTorchClient",
+    "TensorFlowClient",
+    "JaxClient",
+    "SklearnClient",
+    "HuggingFaceClient",
+    "XGBoostClient",
+    "FastaiClient",
+    "PartialTrainingClient",
+    "LayerSelector",
+    "detect_framework",
+    "get_framework_params",
+    "set_framework_params",
+    # Compatibility
+    "FlowerClientAdapter",
+    "FedoraFlowerAdapter",
+    "FlowerStrategyAdapter",
+    "MigrationHelper",
+    "MigrationReport",
+    # Plan-first API
+    "Plan",
+    "ThreatScenario",
+    "list_scenarios",
+    "plan",
+    "scenario",
+    "build_evidence_bundle",
+    "run_proof_workflow",
+    "verify_evidence_bundle",
+    "verify_receipt_chain",
+    "BACKEND_CAPABILITY_MATRIX",
+    "get_backend_capabilities",
+    "validate_adapter_diagnostics",
+    "raise_for_invalid_grpc_deployment",
+    "validate_grpc_deployment_config",
+    "SCHEMA_NAMES",
+    "load_schema",
+    "validate_json_schema",
+]

fedora/__version__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "2.1.0b2"

fedora/_circuits_cuda.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+"""
+CUDA-accelerated fused circuit (optional).
+
+This module uses CuPy if available to implement a fused
+clip+mean+momentum step on the GPU. It is enabled when the environment
+variable FEDORA_USE_CUDA_CIRCUITS is set to 1/true and CuPy is
+importable. Results are converted back to NumPy arrays.
+
+This path is intended for large tensors where device transfer overhead
+is amortised. For small models, the CPU (NumPy/native) path may be
+faster.
+"""
+
+from collections.abc import Iterable, Mapping
+
+import numpy as np
+
+try:  # pragma: no cover - optional dependency
+    import cupy as cp  # type: ignore
+    __cuda_available__ = True
+except Exception:  # pragma: no cover - optional
+    __cuda_available__ = False
+
+Params = dict[str, np.ndarray]
+Update = tuple[Params, int]
+
+
+def clip_mean_momentum(
+    updates: Iterable[Update],
+    *,
+    clip_norm: float,
+    lr: float,
+    momentum: float,
+    prev: Mapping[str, np.ndarray] | None = None,
+):  # -> Params
+    if not __cuda_available__:
+        raise RuntimeError("CuPy is not available; cannot use CUDA circuits")
+
+    ups = list(updates)
+    if not ups:
+        return {}
+
+    # Move to device and pre-clip
+    weights = cp.asarray([float(n) for (_p, n) in ups], dtype=cp.float32)
+    total = float(cp.sum(weights)) if float(cp.sum(weights)) > 0 else 1.0
+    keys = list(ups[0][0].keys())
+    clipped: list[dict[str, cp.ndarray]] = []
+    for p, _n in ups:
+        d: dict[str, cp.ndarray] = {}
+        if clip_norm and float(clip_norm) > 0.0:
+            sq = 0.0
+            for v in p.values():
+                a = cp.asarray(v, dtype=cp.float32)
+                sq += float(cp.sum(a * a))
+            norm = float(sq) ** 0.5 if sq > 1e-12 else 1e-6
+            factor = min(1.0, float(clip_norm) / norm)
+        else:
+            factor = 1.0
+        f = float(factor)
+        for k, v in p.items():
+            d[k] = cp.asarray(v, dtype=cp.float32) * f
+        clipped.append(d)
+
+    # Mean aggregate on device
+    mean_params: dict[str, cp.ndarray] = {}
+    wnorm = weights / float(total)
+    for k in keys:
+        acc = None
+        for i, d in enumerate(clipped):
+            contrib = d[k] * wnorm[i]
+            acc = contrib if acc is None else (acc + contrib)
+        mean_params[k] = acc if acc is not None else cp.zeros_like(clipped[0][k])
+
+    if prev is None:
+        return {k: cp.asnumpy(v) for k, v in mean_params.items()}
+
+    # Momentum step on device (stateless v for now)
+    mu = float(momentum)
+    lr_f = float(lr)
+    out: Params = {}
+    for k, a in mean_params.items():
+        w_prev = cp.asarray(prev.get(k, cp.asnumpy(a)), dtype=cp.float32)
+        g = a - w_prev
+        v = mu * g + g
+        out[k] = cp.asnumpy(w_prev + lr_f * v)
+    return out
+
+
+__all__ = ["clip_mean_momentum", "__cuda_available__"]
+

fedora/_circuits_native.py

@@ -0,0 +1,51 @@
+"""Native circuits shim.
+
+This module attempts to import a compiled extension (e.g., built via pybind11)
+exposing `clip_mean_momentum`. If not present, the symbol exists but raises at
+call time unless you enable the NumPy fallback in fedora.circuits instead.
+
+Build guidance:
+- Provide a compiled module named `fedora._circuits_native_ext` exposing
+  `clip_mean_momentum(updates, *, clip_norm, lr, momentum, prev=None)`.
+- Set `FEDORA_USE_NATIVE_CIRCUITS=1` to instruct fedora.circuits to prefer this
+  native path at runtime.
+"""
+
+from __future__ import annotations
+
+try:  # pragma: no cover - optional build
+    from fedora._circuits_native_ext import clip_mean_momentum as clip_mean_momentum  # type: ignore
+    from fedora._circuits_native_ext import (
+        coord_median_matrix as coord_median_matrix,  # type: ignore
+    )
+    from fedora._circuits_native_ext import (
+        krum_index as krum_index,  # type: ignore
+    )
+    from fedora._circuits_native_ext import (
+        krum_matrix as krum_matrix,  # type: ignore
+    )
+    from fedora._circuits_native_ext import (
+        multikrum_indices as multikrum_indices,  # type: ignore
+    )
+    from fedora._circuits_native_ext import (
+        trimmed_mean_matrix as trimmed_mean_matrix,  # type: ignore
+    )
+    __native__ = True
+except Exception:  # pragma: no cover - optional
+    __native__ = False
+
+    def clip_mean_momentum(*_args, **_kwargs):  # type: ignore[no-redef]
+        raise RuntimeError(
+            "Native circuits extension not available. Install/build the pybind11 module "
+            "(fedora._circuits_native_ext) or use the NumPy fallback in fedora.circuits."
+        )
+
+__all__ = ["clip_mean_momentum", "__native__"]
+if __native__:
+    __all__ += [
+        "trimmed_mean_matrix",
+        "coord_median_matrix",
+        "krum_matrix",
+        "krum_index",
+        "multikrum_indices",
+    ]