Metadata-Version: 2.4
Name: fedora-fl
Version: 2.1.0b2
Summary: FedoRA: federated learning and federated knowledge — typed knowledge artifacts with a security-first merge layer
Author-email: FedoRA Contributors <sam.urmian@gmail.com>
Maintainer-email: FedoRA Contributors <sam.urmian@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/mlgorithm/FedoRA
Project-URL: Documentation, https://github.com/mlgorithm/FedoRA#documentation
Project-URL: Repository, https://github.com/mlgorithm/FedoRA
Project-URL: Bug Tracker, https://github.com/mlgorithm/FedoRA/issues
Project-URL: Changelog, https://github.com/mlgorithm/FedoRA/releases
Keywords: fedora,FedoRA,federated-learning,federated-knowledge,knowledge-federation,llm-agents,agent-memory,model-merging,agents,lora,knowledge-artifacts,machine-learning,privacy,security,Byzantine-robust,differential-privacy,distributed-learning,asynchronous
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0.0,>=1.24.0
Requires-Dist: typer<1.0.0,>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest<10.0.0,>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov<6.0.0,>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio<2.0.0,>=1.4.0; extra == "dev"
Requires-Dist: PyYAML<7.0.0,>=6.0.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.8.0; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.3.0; extra == "dev"
Requires-Dist: build<2.0.0,>=1.0.0; extra == "dev"
Requires-Dist: twine<7.0.0,>=6.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest<10.0.0,>=9.0.3; extra == "test"
Requires-Dist: pytest-cov<6.0.0,>=4.0.0; extra == "test"
Requires-Dist: pytest-asyncio<2.0.0,>=1.4.0; extra == "test"
Requires-Dist: PyYAML<7.0.0,>=6.0.0; extra == "test"
Provides-Extra: flower
Requires-Dist: flwr<2.0.0,>=1.19.0; extra == "flower"
Provides-Extra: ray
Requires-Dist: ray<3.0.0,>=2.9.0; extra == "ray"
Provides-Extra: grpc
Requires-Dist: grpcio<2.0.0,>=1.57.0; extra == "grpc"
Requires-Dist: grpcio-health-checking<2.0.0,>=1.57.0; extra == "grpc"
Requires-Dist: grpcio-tools<2.0.0,>=1.57.0; extra == "grpc"
Requires-Dist: cryptography<51.0.0,>=50.0.2; extra == "grpc"
Provides-Extra: websocket
Requires-Dist: websockets<15.0,>=11.0; extra == "websocket"
Provides-Extra: knowledge
Requires-Dist: sentence-transformers<6.0.0,>=2.2.0; extra == "knowledge"
Provides-Extra: security
Requires-Dist: cryptography<51.0.0,>=50.0.2; extra == "security"
Requires-Dist: jsonschema<5.0.0,>=4.0.0; extra == "security"
Provides-Extra: mpc
Requires-Dist: phe<2.0.0,>=1.4.0; extra == "mpc"
Provides-Extra: mpc-paillier
Requires-Dist: phe<2.0.0,>=1.4.0; extra == "mpc-paillier"
Provides-Extra: privacy
Requires-Dist: scipy<2.0.0,>=1.11.0; extra == "privacy"
Requires-Dist: pandas<3.0.0,>=2.0.0; extra == "privacy"
Provides-Extra: robust
Requires-Dist: scikit-learn<2.0.0,>=1.3.0; extra == "robust"
Requires-Dist: scipy<2.0.0,>=1.11.0; extra == "robust"
Provides-Extra: benchmarks
Requires-Dist: pandas<3.0.0,>=2.0.0; extra == "benchmarks"
Requires-Dist: scikit-learn<2.0.0,>=1.3.0; extra == "benchmarks"
Requires-Dist: scipy<2.0.0,>=1.11.0; extra == "benchmarks"
Provides-Extra: observability
Requires-Dist: prometheus-client<1.0.0,>=0.16.0; extra == "observability"
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.22.0; extra == "observability"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0.0,>=1.22.0; extra == "observability"
Provides-Extra: gpu
Requires-Dist: pynvml<12.0.0,>=11.5.0; extra == "gpu"
Provides-Extra: enterprise
Requires-Dist: cryptography<51.0.0,>=50.0.2; extra == "enterprise"
Requires-Dist: grpcio<2.0.0,>=1.57.0; extra == "enterprise"
Requires-Dist: grpcio-health-checking<2.0.0,>=1.57.0; extra == "enterprise"
Requires-Dist: jsonschema<5.0.0,>=4.0.0; extra == "enterprise"
Requires-Dist: pandas<3.0.0,>=2.0.0; extra == "enterprise"
Requires-Dist: prometheus-client<1.0.0,>=0.16.0; extra == "enterprise"
Requires-Dist: PyYAML<7.0.0,>=6.0.0; extra == "enterprise"
Requires-Dist: scikit-learn<2.0.0,>=1.3.0; extra == "enterprise"
Requires-Dist: scipy<2.0.0,>=1.11.0; extra == "enterprise"
Provides-Extra: docs
Requires-Dist: mkdocs<2.0.0,>=1.6.0; extra == "docs"
Requires-Dist: mkdocs-material<10.0.0,>=9.5.0; extra == "docs"
Provides-Extra: all
Requires-Dist: cryptography<51.0.0,>=50.0.2; extra == "all"
Requires-Dist: flwr<2.0.0,>=1.19.0; extra == "all"
Requires-Dist: grpcio<2.0.0,>=1.57.0; extra == "all"
Requires-Dist: grpcio-health-checking<2.0.0,>=1.57.0; extra == "all"
Requires-Dist: grpcio-tools<2.0.0,>=1.57.0; extra == "all"
Requires-Dist: jsonschema<5.0.0,>=4.0.0; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0.0,>=1.22.0; extra == "all"
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.22.0; extra == "all"
Requires-Dist: pandas<3.0.0,>=2.0.0; extra == "all"
Requires-Dist: phe<2.0.0,>=1.4.0; extra == "all"
Requires-Dist: prometheus-client<1.0.0,>=0.16.0; extra == "all"
Requires-Dist: pynvml<12.0.0,>=11.5.0; extra == "all"
Requires-Dist: PyYAML<7.0.0,>=6.0.0; extra == "all"
Requires-Dist: ray<3.0.0,>=2.9.0; extra == "all"
Requires-Dist: scikit-learn<2.0.0,>=1.3.0; extra == "all"
Requires-Dist: scipy<2.0.0,>=1.11.0; extra == "all"
Requires-Dist: sentence-transformers<6.0.0,>=2.2.0; extra == "all"
Requires-Dist: websockets<15.0,>=11.0; extra == "all"
Dynamic: license-file

<div align="center">

# FedoRA

**Security-first federated learning — and federated knowledge learning for LLM agents**

[Quick Start](#quick-start) · [Federated Knowledge](#federated-knowledge-new-in-20) · [API Stability](docs/API_STABILITY.md) · [Industry Launch](docs/INDUSTRY_LAUNCH.md) · [Proof Workflow](docs/PROOF_WORKFLOW.md) · [Production Readiness](docs/PRODUCTION_READINESS.md) · [Documentation](#documentation) · [Comparison](docs/COMPARISON.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)

![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen)
![Maturity](https://img.shields.io/badge/FL%20core-production--gated-green)
![Knowledge](https://img.shields.io/badge/knowledge%20layer-beta-orange)
[![CI](https://github.com/mlgorithm/FedoRA/actions/workflows/ci.yml/badge.svg)](https://github.com/mlgorithm/FedoRA/actions/workflows/ci.yml)
![Coverage gate](https://img.shields.io/badge/security--critical%20coverage%20gate-%E2%89%A580%25-blue)
![Version](https://img.shields.io/badge/version-2.1.0b2-blue)

</div>

---

## Why FedoRA?

The bigger idea behind FedoRA is **federated knowledge learning**: agents,
devices, and organizations should be able to share useful learned knowledge
without sharing raw private data, full local memory, or unrestricted internal
state.

Classic federated learning is one case of this idea: participants exchange
model parameters. Agentic systems need a more general exchange unit:
LoRA/task adapters, summarized memories, tool-use traces, evaluation results,
fact bundles, policies, skills, and distilled examples.

Enterprise teams deploying federated learning hit a practical problem: **security configuration is manual, error-prone, and disconnected from the threats the deployment actually faces.** You pick an aggregator, bolt on differential privacy separately, tune filters, track trust, and assemble audit logs without one object that explains why those choices belong together.

FedoRA turns a knowledge-sharing objective into an executable, auditable plan.
Declare what kind of knowledge can cross the boundary; FedoRA records the
artifact type, composes the supporting privacy/trust controls, and produces the
receipts needed to review, reproduce, and port the run.

- **Knowledge artifacts** for parameters, adapters, memories, skills, examples, traces, eval results, fact bundles, and policies
- **Defense selection** for Byzantine robustness, privacy, poisoning, backdoors, and anomalous clients
- **Composable execution plans** through the UFCG/FedoRA Plan representation
- **Privacy and trust artifacts** that explain the selected DP, clipping, trust, and audit settings
- **Portable execution paths** for local proof workflows, gRPC/WebSocket experiments, and Flower/FLARE adapters
- **Evidence packs** from plan hashes, receipts, audit logs, and compliance-oriented summaries

> **Packaging:** install the single `fedora-fl` package — that's the whole
> library. `fedora-fl-security` and `fedora-fl-runtime` are thin persona
> *facades* that re-export from `fedora-fl` and depend on it; they give each
> audience a clean import namespace (`import fedora_security` / `fedora_runtime`),
> but the implementation is **not** split into independently installable layers.
> The `[security]` and `[knowledge]` extras pull the optional dependencies for
> each path. Split rationale: [docs/REPO_SPLIT.md](docs/REPO_SPLIT.md).

This checkout targets the corrected beta **2.1.0b2**. Before publication, evaluate
the supplied candidate wheels using the [external review packet](docs/SUPPORT_AGENT_REVIEW.md).
Once that version is published, pin it explicitly with
`pip install "fedora-fl==2.1.0b2"`; extras go before the version pin, for example
`pip install "fedora-fl[security,grpc]==2.1.0b2"`. Both persona facades use the
same version. The approved-data pilot, three independent external users, and
deployment/security review remain separate promotion gates.

As of 2.0, FedoRA federates more than parameters. The same security-first engine now merges **typed knowledge artifacts** — LoRA adapters, distillation logits, prototypes, and natural-language memories and skills for LLM agents — through one pluggable merge interface. Classic FedAvg is the special case (the merge operator for the `tensor` artifact kind). See [Federated Knowledge](#federated-knowledge-new-in-20).

**Current maturity:** the FL security/evidence layer is production-gated. The native gRPC path is available for review-ready deployments only when `fedora verify-grpc-config --review-ready` passes for the concrete run config. WebSocket, Flower, and FLARE paths must still be evaluated against the [Backend Capability Matrix](docs/BACKEND_CAPABILITY_MATRIX.md) before deployment. **The federated-knowledge layer (`fedora.knowledge`) is beta**: usable and tested, with pluggable production seams (real embeddings, isolated skill execution), but not yet production-gated — see its rows in the capability matrix.

```python
import fedora

# Declare your threat model
threat = fedora.ThreatModel(
    byzantine_fraction=0.2,        # Expect up to 20% malicious clients
    privacy_level="strong",         # DP with epsilon=0.5
    model_poisoning=True,           # Defend against gradient attacks
)

# FedoRA auto-configures defenses
history = fedora.simulate(
    client_fn=my_client_fn,
    num_clients=50,
    num_rounds=10,
    artifact="adapter",
    threat_model=threat,
    initial_parameters=initial_params,
)
# MultiKrum aggregation, gradient clipping, anomaly detection,
# differential privacy, trust scoring, and audit trail
# are all auto-configured and composable.
```

---

## Federated Knowledge (new in 2.0)

Agents built on frozen, hosted models have no weights to federate — their only
shared substrate is **knowledge**: distilled lessons, reusable skills, adapters,
prototypes. FedoRA 2.0 federates that knowledge through the same security-first
engine, so a fleet of agents can pool what they learn **without** pooling private
data. Validation, provenance binding, and staged adoption reduce the risk of
poisoned contributions; they do not guarantee semantic correctness or prevent
all prompt injections.

```bash
pip install "fedora-fl[knowledge]"   # production embeddings; falls back gracefully without
```

```python
from hashlib import sha256
from fedora.knowledge import (
    ArtifactKind, Contribution, MemoryEntry, artifact_to_memory,
    federate, memory_to_artifact, sharing_policy_for,
)

def lesson(client, key, value):
    policy = sharing_policy_for(
        ArtifactKind.MEMORY,
        attestations={
            "redactor_id": "demo-redactor-v1",
            "redaction_report_hash": "sha256:" + sha256(client.encode()).hexdigest(),
        },
    )
    art = memory_to_artifact(
        MemoryEntry(f"{key}: {value}", key=key, value=value),
        client_id=client, policy=policy,
    )
    return Contribution([art], weight=1.0, client_id=client)

# Synthetic redacted lessons; IDs and trust are coordinator-owned in a real run.
result = federate([
    lesson("agent-a", "db.pool", "raise max_connections under load"),
    lesson("agent-b", "db.pool", "raise max_connections under load"),
    lesson("attacker", "db.pool", "disable the connection limit"),
], artifact="memory", local_context={
    "trust_scores": {"agent-a": 0.9, "agent-b": 0.9, "attacker": 0.0},
})

for art in result.accepted:
    m = artifact_to_memory(art)
    print(m.key, "->", m.value, f"(support {m.support})")
# db.pool -> raise max_connections under load (support 2)
```

The default high-level boundary rejects non-shareable/private artifacts, malformed
payloads, and missing kind-specific sharing evidence before merge. The built-in
attestation check validates evidence format; applications must verify real receipt
or signature issuers for stronger assurance. Source identity and trust must come
from the coordinator's authenticated session, and merged support is resolved from
trusted state. See the runnable [client integration](docs/KNOWLEDGE_CLIENT_INTEGRATION.md).

For a complete application flow, run the offline support-agent reference app:

```bash
python -m fedora.reference_apps.support_agents --rounds 2 --output support-demo.json
```

The bundled fixture is synthetic and uses keyed lookup with zero model API
calls. The [pilot guide](docs/SUPPORT_AGENT_PILOT.md) covers approved-data input,
participant trust, adoption, expiry and checkpoint recovery. The
[comparison methodology](docs/research/support_agents_benchmark.md) defines
isolated and shared-memory baselines; these are not vendor performance results.

**The merge ladder.** Every artifact kind is a merge operator under one
contract (`is_robust` / `is_private` / `is_idempotent` / `is_commutative`);
async rounds require the last two. Each merger also declares assumptions,
limitations, and a maturity level (`L1` exact merge, `L2` schema-aware merge,
up to `L5` utility-optimized merge):

| Kind | Merge operator | What it federates |
|------|----------------|-------------------|
| `tensor` | FedAvg · Krum · trimmed mean · DP | model parameters (classic FL) |
| `adapter` | delta-space TIES / DARE (rank-heterogeneous) | LoRA fine-tunes |
| `logits` | FedMD/FedDF consensus + robust trimmed mean | predictions across heterogeneous models |
| `prototype` | FedProto count-weighted average | per-class embedding anchors |
| `memory` | validate → trust-weighted vote → quarantine | natural-language lessons |
| `skill` | test-gated acceptance (pooled evals) | executable skills |

Extended agent-native artifact kinds:

| Kind | Merge operator | What it federates |
|------|----------------|-------------------|
| `tool_trace` | schema-aware workflow merge (`L2` when workflow metadata is present) | successful tool-use traces |
| `eval_result` | run-deduped weighted/median/trimmed/trust-weighted metrics | benchmark evidence and failure summaries |
| `fact_bundle` | highest-confidence claim selection | structured facts with provenance |
| `policy` | deterministic union + conflict reporting (`L2`) | guardrails and operating rules |
| `example` | exact distilled-example dedupe | synthetic or distilled demonstrations |

The robust mergers turn a $0.667$ undefended memory-poisoning attack into $0.000$
attack success in the reference experiment. See the [wire-format spec](docs/SPEC_KNOWLEDGE_ARTIFACT_V1.md),
the [position paper](paper/federated_knowledge_position.pdf), and the reproducible
benchmark (`python benchmarks/knowledge_federation_benchmark.py`).

---

## What FedoRA Offers

| Capability | What users get |
|------------|----------------|
| **Knowledge Objective Planner** | Start with a `KnowledgeObjective` or `artifact=...`; receive a plan for what knowledge can cross the boundary and how it is validated. |
| **Secure Experiment Builder** | Start with clients, data, and a `ThreatModel`; receive a runnable configuration with aggregator, DP, defenses, trust, and audit defaults selected together. |
| **Threat Model Compiler** | Convert business/security concerns into a recommended defense stack with rationale, parameters, and validation hooks. |
| **FedoRA Plan** | Represent FL rounds as a typed UFCG plan with policy constraints, plan hashing, backend decisions, and receipts. |
| **Composable Security Stack** | Combine robust aggregation, DP, explicit SecAgg modes, anomaly detection, trust scoring, and attack simulation without hand-wiring each path. |
| **Portability Layer** | Run proof workflows locally, experiment with gRPC/WebSocket, or lower compatible plans into Flower/FLARE paths when existing infrastructure matters. |
| **Evidence Pack** | Export audit and receipt artifacts that show what ran, why defenses were selected, and how privacy/trust state evolved. |

```python
import fedora

threat = fedora.ThreatModel(
    byzantine_fraction=0.2,
    privacy_level="strong",
    model_poisoning=True,
)

plan = fedora.plan(
    fedora.KnowledgeObjective(
        name="agent-adapter-sharing",
        artifact="adapter",
        num_clients=50,
        num_rounds=10,
        threat_model=threat,
    ),
    receipts_path="receipts/run.jsonl",
)
print(plan.plan_id)
print(plan.explain())
plan.export("exec_plan.json")
```

Want an even shorter starting point? Use a built-in scenario:

```python
import fedora

plan = fedora.scenario("healthcare", num_clients=12, num_rounds=20).plan()
print(plan.run_config["strategy"])
```

```bash
fedora plan --scenario healthcare --clients 12 --rounds 20 --output healthcare_plan.json
```

Run the local proof workflow and export an evidence bundle:

```bash
fedora proof --scenario byzantine-privacy --clients 20 --rounds 3 --output-dir fedora_proof
```

## Competitive Position

| Framework | Best at | FedoRA's role beside it |
|-----------|---------|--------------------------|
| **Flower** | Mature FL app/runtime architecture and broad ecosystem | Add threat-driven defense composition and auditable plans around Flower-compatible work. |
| **NVIDIA FLARE** | Production cross-silo deployment, provisioning, filters, and operational controls | Generate or validate security plans and evidence before lowering into FLARE-style deployments. |
| **FedML** | Broad MLOps and run-anywhere FL workflows | Stay focused on the security/compiler layer instead of duplicating full MLOps. |
| **OpenFL** | Institution-oriented plans, TLS/PKI workflows, and healthcare-style collaborations | Make the plan contract more threat-aware and receipt-driven. |
| **FATE** | Vertical FL, MPC/HE workflows, and large enterprise deployments | Avoid competing on vertical FL; focus on horizontal FL security composition and evidence. |
| **TensorFlow Federated** | Typed federated computation research in TensorFlow | Keep FedoRA Plan backend-agnostic and security-oriented. |
| **PySyft** | Data-owner governance and privacy-preserving remote data science | Keep FedoRA FL-specific while borrowing the idea that governance artifacts matter. |

### Backend Maturity

FedoRA's backend support is intentionally explicit:

| Path | Current claim |
|------|---------------|
| **Local simulation** | Beta-supported proof workflow for planning, attacks, defenses, and evidence. |
| **local-mp / Ray** | Optional simulation backends when dependencies are installed. |
| **gRPC / WebSocket** | Experimental deployment paths for controlled evaluation. |
| **Flower / FLARE adapters** | Compatibility layers with feature-specific caveats, not full runtime parity. |

See [Backend Capability Matrix](docs/BACKEND_CAPABILITY_MATRIX.md) before making deployment or security claims.

---

## Quick Start

### Installation

```bash
pip install fedora-fl
```

### Your First Secure FL Experiment

```python
import numpy as np
import fedora

# 1. Define your client
class MyClient(fedora.NumPyClient):
    def fit(self, parameters, config):
        # Your local training logic here
        updated = [p + np.random.randn(*p.shape) * 0.01 for p in parameters]
        return fedora.FitResult(
            parameters=fedora.Parameters.from_ndarrays(updated),
            num_examples=1000,
            metrics={"loss": 0.5},
        )

    def evaluate(self, parameters, config):
        return fedora.EvalResult(loss=0.3, num_examples=500)

# 2. Run a simulation
history = fedora.simulate(
    client_fn=lambda cid: MyClient(),
    num_clients=20,
    num_rounds=5,
    initial_parameters=fedora.Parameters.from_ndarrays([np.ones(100)]),
)

print(history.summary())
```

### Add Security in One Line

```python
# Declare threats — defenses are auto-configured
history = fedora.simulate(
    client_fn=lambda cid: MyClient(),
    num_clients=20,
    num_rounds=5,
    threat_model=fedora.ThreatModel(
        byzantine_fraction=0.3,       # 30% malicious clients
        privacy_level="strong",       # DP with epsilon=0.5
        model_poisoning=True,         # Expect gradient attacks
        backdoor_attack=True,         # Expect backdoor triggers
    ),
    initial_parameters=fedora.Parameters.from_ndarrays([np.ones(100)]),
)
```

What this auto-configures:
- **MultiKrum aggregation** (tolerates up to 30% Byzantine clients)
- **Differential privacy** (epsilon=0.5, delta=1e-6, Gaussian mechanism)
- **Gradient clipping** (norm bound = 1.0)
- **Anomaly detection** (spectral + similarity filtering)
- **Trust scoring** (per-client reputation tracking)
- **Audit trail** (hash-linked events for tamper detection and review)

---

## Key Features

### 1. Declarative Threat Model

Declare your security requirements, and FedoRA auto-selects and configures the right combination of defenses instead of forcing each component to be wired independently.

```python
threat = fedora.ThreatModel(
    byzantine_fraction=0.2,
    privacy_level="strong",
    model_poisoning=True,
)
rec = threat.recommend_defenses()
print(rec.aggregator)        # "multikrum"
print(rec.dp_enabled)        # True
print(rec.dp_epsilon)        # 0.5
print(rec.trust_scoring)     # True
print(rec.anomaly_detection) # True
print(rec.rationale)         # Human-readable explanation
```

### 2. 14 Aggregation Strategies

From standard averaging to Byzantine-robust to adaptive optimizers:

| Category | Aggregators |
|----------|------------|
| **Standard** | FedAvg, FedProx, FedNova |
| **Byzantine-Robust** | TrimmedMean, CoordinateMedian, Krum, MultiKrum, Bulyan, FoolsGold |
| **Adaptive** | FedAdam, FedAdagrad, FedYogi |
| **Privacy** | DPAggregator (wraps any base), SecAgg, SecAggPlus |

All aggregators are composable. Wrap any base aggregator with differential privacy:

```python
base = fedora.Krum(num_byzantine=2)
dp_agg = fedora.DPAggregator(base, config=fedora.DPConfig(epsilon=1.0))
```

This is central DP for replacement of one client's clipped update under a trusted
coordinator and fixed roster. `DPConfig.public_weights` supplies externally fixed
public client weights for a tighter weighted-average bound; client-reported
example counts are not evidence of public weights. Without that mapping, the
bound is conservatively `2 * clip_norm`. Nonlinear aggregators clip the output delta and use a conservative sensitivity
bound, trading utility for a defensible release budget. The guarantee applies
to the privatized aggregate, not raw updates seen by the server or additional
diagnostic outputs. See [DP scope and accounting](docs/guide/security.md#differential-privacy-scope).

Secure aggregation has multiple modes. `SecAgg()` selects the Shamir-backed
in-process evaluation mode; additive masking requires explicit `mode="demo"`.
Neither provides an independently audited distributed cryptographic protocol.
Name and validate a target runtime protocol before making a deployment claim.

### 3. Built-in Attack Simulation

Test your defenses before deployment. 7 attack types ship with the framework:

```python
from fedora.security.attacks import SignFlip, ScalingAttack, BackdoorAttack

def attack_fn(client_id):
    if int(client_id) < 5:  # First 5 clients are adversaries
        return SignFlip()
    return None

history = fedora.simulate(
    client_fn=my_client_fn,
    num_clients=20,
    num_rounds=5,
    attack_fn=attack_fn,
    threat_model=fedora.ThreatModel(byzantine_fraction=0.25),
    initial_parameters=params,
)
```

**Attack types:** LabelFlip, SignFlip, ScalingAttack, ModelReplace, BackdoorAttack, FreeRider, GradientInversion

### 4. Async-Capable Design

Three round execution modes for real-world deployments:

```python
from fedora.engine.round import RoundConfig, RoundMode

# Synchronous: wait for all clients
sync = RoundConfig(mode=RoundMode.SYNC)

# Async (FedBuff): aggregate when buffer fills
async_buf = RoundConfig(mode=RoundMode.ASYNC, buffer_size=10)

# Deadline: aggregate whoever responds in time
deadline = RoundConfig(mode=RoundMode.DEADLINE, deadline_seconds=30.0)
```

**Client selection strategies:** Random, Stratified, Power-of-Choice, OORT

### 5. Pluggable Transport Layer

```python
# Local (simulation)
from fedora.transport.local import LocalServerTransport

# gRPC (controlled deployment experiment)
from fedora.transport.grpc_transport import GrpcServerTransport

# WebSocket (browser/edge clients)
from fedora.transport.websocket_transport import WebSocketServerTransport
```

### 6. Evidence and Compliance Artifacts

Audit trails and receipts help reviewers understand what happened during an FL run. They can support regulated workflows, but they are not a substitute for a legal or security compliance review.

```python
from fedora.security.audit import AuditTrail

trail = AuditTrail()
# Auto-logs: client joins, update rejections, attack detections,
# trust score changes, privacy budget consumption
trail.export_json("audit_report.json")
```

---

## Benchmarks

### Security Configuration Example

FedoRA's declarative approach is designed to reduce security setup effort:

| Approach | Lines of Code | Components Auto-Configured |
|----------|:---:|---|
| **FedoRA ThreatModel** | **8** | Aggregator, DP, clipping, defenses, trust, audit |
| Manual configuration | 78 | Same components, hand-wired |

### Attack Resilience

The benchmark harness is intended to compare no-defense, manual-defense, and FedoRA-recommended configurations under the same declared threat:

| Attack (30% Byzantine) | No Defense | Manual Krum | FedoRA Auto |
|---|:---:|:---:|:---:|
| SignFlip | Diverges | Converges | Converges |
| ScalingAttack | Diverges | Converges | Converges |
| ModelReplace | Diverges | Converges | Converges |

Run benchmarks yourself: `python benchmarks/run_all.py`. Treat published benchmark claims as release artifacts only when the environment, command, and raw output are committed with the result.

### Test Suite

The suite has **1,464 passing tests** across the FL core and the knowledge layer. Representative coverage:

| Area | Status |
|------|:------:|
| Engine (types, server, client, scheduler) | All passing |
| Aggregation (16 strategies + mixed-precision) | All passing |
| Clients (PyTorch, TF, JAX, sklearn, partial training) | All passing |
| Transport (local, gRPC, WebSocket) | All passing |
| Security (threats, attacks, defenses, trust, audit) | All passing |
| Knowledge spine (artifacts, mergers, state, wire format) | All passing |
| Knowledge mergers and adoption ladder | All passing |
| Knowledge seams (embedder fallback, subprocess sandbox) | All passing |
| Agent-memory gate experiment + capability benchmark | All passing |

---

## Coming from Flower?

FedoRA ships bidirectional adapters and a migration assistant.

### Use Your Flower Clients with FedoRA

```python
from fedora.compat.flower import FlowerClientAdapter

# Wrap any existing Flower NumPyClient
fedora_client = FlowerClientAdapter(your_flower_client)
```

### Use FedoRA Clients with Flower

```python
from fedora.compat.flower import FedoraFlowerAdapter

# Wrap a FedoRA client for use in Flower
flower_client = FedoraFlowerAdapter(your_fedora_client)
```

### Scan Your Flower Project

```python
from fedora.compat.migration import MigrationHelper

helper = MigrationHelper()
report = helper.scan_flower_project("./my_flower_project")
report.print_migration_plan()
# Outputs: file-by-file migration steps, effort estimates, code examples
```

---

## Architecture

```
fedora/
  engine/          # Core types, server, client, round management, history
  aggregation/     # 14 strategies: averaging, robust, adaptive, DP, secure
  security/        # Threat model, attacks, defenses, trust scoring, audit trail
  transport/       # Local, gRPC, WebSocket (pluggable via registry)
  simulation/      # Runner, data distribution, virtual clients
  compat/          # Flower adapters and migration tools
  enterprise/      # Governance, compliance helpers, deployment utilities
```

---

## Installation Options

```bash
# Core (numpy + typer)
pip install fedora-fl

# Test/development baseline
pip install -e ".[test]"

# With gRPC transport
pip install "fedora-fl[grpc]"

# With Flower compatibility
pip install "fedora-fl[flower]"

# With privacy extras (scipy, pandas)
pip install "fedora-fl[privacy]"

# Security/evidence layer at full capability (signed attestation, TLS, schema validation)
pip install "fedora-fl[security]"

# Federated knowledge: production embeddings for the memory merger
pip install "fedora-fl[knowledge]"

# Everything
pip install "fedora-fl[all]"
```

---

## Documentation

- **[Getting Started](docs/getting_started.md)** — Installation and basic usage
- **[Worked Scenarios](docs/scenarios/README.md)** — Eight runnable end-to-end walkthroughs across both personas (Byzantine+privacy, healthcare, edge devices; agent knowledge, prototypes, distillation logits, LoRA adapters, executable skills)
- **[Scenario Reference](docs/getting-started/scenarios.md)** — Quick reference for every built-in scenario
- **[Security & Defenses](docs/guide/security.md)** — Threat models, defenses, trust scoring, and audit trails
- **[Aggregation Strategies](docs/guide/aggregation.md)** — Deep dive into available aggregation strategies
- **[Migration from Flower](docs/MIGRATION.md)** — Adapter API and code examples
- **[Backend Guide](docs/BACKENDS.md)** — Local, gRPC, Ray, Flower, and FLARE execution paths
- **[Backend Capability Matrix](docs/BACKEND_CAPABILITY_MATRIX.md)** — Supported, experimental, adapter, and demo-only claims
- **[Proof Workflow](docs/PROOF_WORKFLOW.md)** — Reproducible local proof run and evidence bundle
- **[Knowledge Federation RFC](docs/KNOWLEDGE_FEDERATION_RFC.md)** — Design of the `fedora.knowledge` layer and its phases
- **[Knowledge Artifact Spec v1](docs/SPEC_KNOWLEDGE_ARTIFACT_V1.md)** — Wire format, content addressing, and the merge contract
- **[Knowledge Benchmark](docs/research/knowledge_federation_benchmark.md)** — Gate experiment and the current knowledge capability matrix
- **[Repo Split](docs/REPO_SPLIT.md)** — Two-package monorepo structure for `fedora-fl-security` and `fedora-fl`
- **[FedoRA Plan / UFCG](docs/UFCG.md)** — Portable, auditable plan representation
- **[Competitive Comparison](docs/COMPARISON.md)** — What FedoRA should own and where other frameworks lead
- **[API Reference](https://fedora-fl.github.io/fedora/api)** — Full API documentation

---

## Citation

If you use FedoRA in research, please cite:

```bibtex
@software{fedora2026,
  title     = {FedoRA: Security-First Federated Learning and Federated Knowledge},
  author    = {FedoRA Contributors},
  year      = {2026},
  version   = {2.0.0},
  url       = {https://github.com/mlgorithm/FedoRA}
}
```

---

## License

FedoRA is licensed under the [Apache 2.0 License](LICENSE).

---

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
- Setting up your development environment
- Running tests and quality checks
- Submitting pull requests
- Adding new aggregation strategies or attack simulations

---

## Support

- **Issues & Bugs:** [GitHub Issues](https://github.com/mlgorithm/FedoRA/issues)
- **Security:** See [SECURITY.md](SECURITY.md)
