federated-graph 0.1.0__tar.gz

federated_graph-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.so
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.venv/
+venv/
+*.cover
+htmlcov/
+.coverage
+.tox/

federated_graph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Temitope Adeyeha
+
+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.

federated_graph-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: federated-graph
+Version: 0.1.0
+Summary: Federated Graph Intelligence SDK for financial fraud detection
+Project-URL: Repository, https://github.com/Adeyeha/federated_graph
+Project-URL: Issues, https://github.com/Adeyeha/federated_graph/issues
+Author-email: Temitope Adeyeha <temitope.adeyeha@yahoo.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: federated-learning,fraud-detection,gnn,graph-neural-network,privacy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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 :: Security
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: structlog>=23.0
+Requires-Dist: torch-geometric>=2.4
+Requires-Dist: torch>=2.1
+Provides-Extra: all
+Requires-Dist: grpcio-tools>=1.60; extra == 'all'
+Requires-Dist: grpcio>=1.60; extra == 'all'
+Requires-Dist: mypy; extra == 'all'
+Requires-Dist: protobuf>=4.25; extra == 'all'
+Requires-Dist: pytest-asyncio; extra == 'all'
+Requires-Dist: pytest-cov; extra == 'all'
+Requires-Dist: pytest>=7.4; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Requires-Dist: ruff; extra == 'all'
+Requires-Dist: scikit-learn>=1.3; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: grpc
+Requires-Dist: grpcio-tools>=1.60; extra == 'grpc'
+Requires-Dist: grpcio>=1.60; extra == 'grpc'
+Requires-Dist: protobuf>=4.25; extra == 'grpc'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: scoring
+Requires-Dist: scikit-learn>=1.3; extra == 'scoring'
+Description-Content-Type: text/markdown
+
+# Federated Graph
+
+A privacy-preserving Graph Neural Network framework for financial fraud detection using federated learning. Federated Graph enables organizations to collaboratively train fraud detection models on their transaction graphs without sharing raw data.
+
+## Features
+
+- **Federated Learning** — Train models collaboratively across multiple clients with privacy-preserving aggregation
+- **Temporal Graph Neural Networks** — Capture temporal dynamics in transaction networks with decay-aware convolutions
+- **Dual-Head Risk Scoring** — Entity-level and transaction-level fraud risk assessment
+- **Privacy & Security** — Differential privacy, secure aggregation, and cryptographic verification
+- **Feature Engineering** — Node and edge feature extraction with temporal windowing and missing data handling
+- **Robust Aggregation** — Multiple strategies including FedAvg, robust aggregation, and trust-weighted
+- **Model Validation** — Canary generators, conformance checking, and model contract validation
+- **Score Calibration** — Isotonic regression-based calibration with cold-start fallback
+- **Multiple Backends** — In-process, HTTP, and gRPC communication options
+- **Compliance Ready** — Built-in audit trails, SAR support, and serialization for regulatory requirements
+
+## Installation
+
+```bash
+pip install federated-graph
+```
+
+Optional extras:
+
+```bash
+pip install federated-graph[grpc]      # gRPC communication backend
+pip install federated-graph[redis]     # Redis-based embedding store
+pip install federated-graph[scoring]   # Score calibration with scikit-learn
+pip install federated-graph[dev]       # Development tools
+pip install federated-graph[all]       # Everything
+```
+
+## Quick Start
+
+```python
+import torch
+from torch_geometric.data import Data
+from federated_graph import FGIConfig
+from federated_graph.models import FGIModel
+
+# Create configuration
+config = FGIConfig()
+
+# Initialize model
+model = FGIModel(in_channels=10, config=config.model)
+
+# Prepare graph data
+x = torch.randn(100, 10)
+edge_index = torch.randint(0, 100, (2, 500))
+
+# Forward pass returns embeddings and risk scores
+embeddings, entity_scores, txn_scores = model(x, edge_index)
+```
+
+### Federated Training
+
+```python
+from federated_graph.federation import FederationServer, FederationClient
+
+server = FederationServer(
+    num_rounds=config.federation.num_rounds,
+    min_clients=config.federation.min_clients,
+)
+
+client = FederationClient(client_id="client_1", model=model, config=config)
+```
+
+### Configuration
+
+Pydantic-based configuration with sensible defaults:
+
+```python
+from federated_graph import FGIConfig
+
+config = FGIConfig.from_yaml("config.yaml")
+config.to_yaml("config_output.yaml")
+```
+
+## License
+
+MIT

federated_graph-0.1.0/README.md

@@ -0,0 +1,82 @@
+# Federated Graph
+
+A privacy-preserving Graph Neural Network framework for financial fraud detection using federated learning. Federated Graph enables organizations to collaboratively train fraud detection models on their transaction graphs without sharing raw data.
+
+## Features
+
+- **Federated Learning** — Train models collaboratively across multiple clients with privacy-preserving aggregation
+- **Temporal Graph Neural Networks** — Capture temporal dynamics in transaction networks with decay-aware convolutions
+- **Dual-Head Risk Scoring** — Entity-level and transaction-level fraud risk assessment
+- **Privacy & Security** — Differential privacy, secure aggregation, and cryptographic verification
+- **Feature Engineering** — Node and edge feature extraction with temporal windowing and missing data handling
+- **Robust Aggregation** — Multiple strategies including FedAvg, robust aggregation, and trust-weighted
+- **Model Validation** — Canary generators, conformance checking, and model contract validation
+- **Score Calibration** — Isotonic regression-based calibration with cold-start fallback
+- **Multiple Backends** — In-process, HTTP, and gRPC communication options
+- **Compliance Ready** — Built-in audit trails, SAR support, and serialization for regulatory requirements
+
+## Installation
+
+```bash
+pip install federated-graph
+```
+
+Optional extras:
+
+```bash
+pip install federated-graph[grpc]      # gRPC communication backend
+pip install federated-graph[redis]     # Redis-based embedding store
+pip install federated-graph[scoring]   # Score calibration with scikit-learn
+pip install federated-graph[dev]       # Development tools
+pip install federated-graph[all]       # Everything
+```
+
+## Quick Start
+
+```python
+import torch
+from torch_geometric.data import Data
+from federated_graph import FGIConfig
+from federated_graph.models import FGIModel
+
+# Create configuration
+config = FGIConfig()
+
+# Initialize model
+model = FGIModel(in_channels=10, config=config.model)
+
+# Prepare graph data
+x = torch.randn(100, 10)
+edge_index = torch.randint(0, 100, (2, 500))
+
+# Forward pass returns embeddings and risk scores
+embeddings, entity_scores, txn_scores = model(x, edge_index)
+```
+
+### Federated Training
+
+```python
+from federated_graph.federation import FederationServer, FederationClient
+
+server = FederationServer(
+    num_rounds=config.federation.num_rounds,
+    min_clients=config.federation.min_clients,
+)
+
+client = FederationClient(client_id="client_1", model=model, config=config)
+```
+
+### Configuration
+
+Pydantic-based configuration with sensible defaults:
+
+```python
+from federated_graph import FGIConfig
+
+config = FGIConfig.from_yaml("config.yaml")
+config.to_yaml("config_output.yaml")
+```
+
+## License
+
+MIT

federated_graph-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "federated-graph"
+version = "0.1.0"
+description = "Federated Graph Intelligence SDK for financial fraud detection"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "Temitope Adeyeha", email = "temitope.adeyeha@yahoo.com" }]
+keywords = ["federated-learning", "graph-neural-network", "fraud-detection", "gnn", "privacy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Security",
+]
+
+dependencies = [
+    "torch>=2.1",
+    "torch-geometric>=2.4",
+    "pydantic>=2.0",
+    "numpy>=1.24",
+    "cryptography>=41.0",
+    "structlog>=23.0",
+]
+
+[project.urls]
+Repository = "https://github.com/Adeyeha/federated_graph"
+Issues = "https://github.com/Adeyeha/federated_graph/issues"
+
+[project.optional-dependencies]
+grpc = ["grpcio>=1.60", "grpcio-tools>=1.60", "protobuf>=4.25"]
+redis = ["redis>=5.0"]
+scoring = ["scikit-learn>=1.3"]
+dev = ["pytest>=7.4", "pytest-cov", "pytest-asyncio", "ruff", "mypy"]
+all = ["federated-graph[grpc,redis,scoring,dev]"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/federated_graph"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true

federated_graph-0.1.0/src/federated_graph/__init__.py

@@ -0,0 +1,6 @@
+"""FGI SDK - Federated Graph Intelligence."""
+
+from federated_graph._version import __version__
+from federated_graph.config import FGIConfig
+
+__all__ = ["__version__", "FGIConfig"]

federated_graph-0.1.0/src/federated_graph/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

federated_graph-0.1.0/src/federated_graph/aggregation/__init__.py

@@ -0,0 +1,4 @@
+from federated_graph.aggregation.base import Aggregator
+from federated_graph.aggregation.fedavg import FedAvg
+from federated_graph.aggregation.robust import CoordinateMedian, TrimmedMean, Krum, GeometricMedian
+from federated_graph.aggregation.trust import TrustWeighting

federated_graph-0.1.0/src/federated_graph/aggregation/base.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+import torch
+from federated_graph.federation.update import ModelUpdate
+
+
+class Aggregator(ABC):
+    """Abstract base class for model update aggregators."""
+
+    @abstractmethod
+    def aggregate(self, updates: list[ModelUpdate],
+                  global_state: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        """Aggregate client updates into new global state."""
+        ...

federated_graph-0.1.0/src/federated_graph/aggregation/fedavg.py

@@ -0,0 +1,23 @@
+import torch
+from federated_graph.aggregation.base import Aggregator
+from federated_graph.federation.update import ModelUpdate
+
+
+class FedAvg(Aggregator):
+    """Federated Averaging: weighted average by number of samples."""
+
+    def aggregate(self, updates: list[ModelUpdate],
+                  global_state: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        total_samples = sum(u.num_samples for u in updates)
+        if total_samples == 0:
+            return global_state
+
+        new_state = {}
+        for key in global_state:
+            weighted_delta = torch.zeros_like(global_state[key].float())
+            for update in updates:
+                if key in update.state_delta:
+                    weight = update.num_samples / total_samples
+                    weighted_delta += update.state_delta[key].float() * weight
+            new_state[key] = global_state[key].float() + weighted_delta
+        return new_state

federated_graph-0.1.0/src/federated_graph/aggregation/robust.py

@@ -0,0 +1,162 @@
+import torch
+from federated_graph.aggregation.base import Aggregator
+from federated_graph.federation.update import ModelUpdate
+
+
+class CoordinateMedian(Aggregator):
+    """Coordinate-wise median aggregation (Byzantine-robust)."""
+
+    def aggregate(self, updates: list[ModelUpdate],
+                  global_state: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        new_state = {}
+        for key in global_state:
+            deltas = []
+            for update in updates:
+                if key in update.state_delta:
+                    deltas.append(update.state_delta[key].float())
+            if deltas:
+                stacked = torch.stack(deltas, dim=0)
+                median_delta = stacked.median(dim=0).values
+                new_state[key] = global_state[key].float() + median_delta
+            else:
+                new_state[key] = global_state[key].clone()
+        return new_state
+
+
+class TrimmedMean(Aggregator):
+    """Trimmed mean aggregation: remove top/bottom fraction before averaging."""
+
+    def __init__(self, trim_fraction: float = 0.1):
+        self.trim_fraction = trim_fraction
+
+    def aggregate(self, updates: list[ModelUpdate],
+                  global_state: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        n = len(updates)
+        k = max(1, int(n * self.trim_fraction))
+
+        new_state = {}
+        for key in global_state:
+            deltas = []
+            for update in updates:
+                if key in update.state_delta:
+                    deltas.append(update.state_delta[key].float())
+            if len(deltas) > 2 * k:
+                stacked = torch.stack(deltas, dim=0)
+                sorted_deltas, _ = stacked.sort(dim=0)
+                trimmed = sorted_deltas[k:n-k]
+                mean_delta = trimmed.mean(dim=0)
+                new_state[key] = global_state[key].float() + mean_delta
+            elif deltas:
+                stacked = torch.stack(deltas, dim=0)
+                new_state[key] = global_state[key].float() + stacked.mean(dim=0)
+            else:
+                new_state[key] = global_state[key].clone()
+        return new_state
+
+
+class Krum(Aggregator):
+    """
+    Krum aggregation: select the update closest to all others.
+    Byzantine-robust when f < n/2 - 1.
+    """
+
+    def __init__(self, num_byzantine: int = 1):
+        self.num_byzantine = num_byzantine
+
+    def _flatten(self, state_delta: dict[str, torch.Tensor]) -> torch.Tensor:
+        """Flatten a state dict into a single vector."""
+        return torch.cat([v.float().flatten() for v in sorted(state_delta.items(), key=lambda x: x[0]) for v in [v[1]]])
+
+    def aggregate(self, updates: list[ModelUpdate],
+                  global_state: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        n = len(updates)
+        if n == 0:
+            return global_state
+        if n == 1:
+            new_state = {}
+            for key in global_state:
+                delta = updates[0].state_delta.get(key, torch.zeros_like(global_state[key]))
+                new_state[key] = global_state[key].float() + delta.float()
+            return new_state
+
+        # Flatten all updates
+        flat_updates = []
+        for u in updates:
+            parts = []
+            for key in sorted(global_state.keys()):
+                if key in u.state_delta:
+                    parts.append(u.state_delta[key].float().flatten())
+                else:
+                    parts.append(torch.zeros(global_state[key].numel()))
+            flat_updates.append(torch.cat(parts))
+
+        # Compute pairwise distances
+        n_select = n - self.num_byzantine - 2
+        n_select = max(1, n_select)
+
+        scores = []
+        for i in range(n):
+            dists = []
+            for j in range(n):
+                if i != j:
+                    dists.append((flat_updates[i] - flat_updates[j]).pow(2).sum().item())
+            dists.sort()
+            scores.append(sum(dists[:n_select]))
+
+        # Select update with minimum score
+        best_idx = scores.index(min(scores))
+        best_update = updates[best_idx]
+
+        new_state = {}
+        for key in global_state:
+            delta = best_update.state_delta.get(key, torch.zeros_like(global_state[key]))
+            new_state[key] = global_state[key].float() + delta.float()
+        return new_state
+
+
+class GeometricMedian(Aggregator):
+    """Geometric median aggregation via Weiszfeld's algorithm."""
+
+    def __init__(self, max_iter: int = 100, tol: float = 1e-6):
+        self.max_iter = max_iter
+        self.tol = tol
+
+    def aggregate(self, updates: list[ModelUpdate],
+                  global_state: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        n = len(updates)
+        if n == 0:
+            return global_state
+
+        # Flatten updates
+        flat_updates = []
+        for u in updates:
+            parts = []
+            for key in sorted(global_state.keys()):
+                if key in u.state_delta:
+                    parts.append(u.state_delta[key].float().flatten())
+                else:
+                    parts.append(torch.zeros(global_state[key].numel()))
+            flat_updates.append(torch.cat(parts))
+
+        stacked = torch.stack(flat_updates, dim=0)
+
+        # Weiszfeld's algorithm
+        median = stacked.mean(dim=0)
+        for _ in range(self.max_iter):
+            dists = (stacked - median.unsqueeze(0)).pow(2).sum(dim=1).sqrt().clamp(min=1e-8)
+            weights = 1.0 / dists
+            weights = weights / weights.sum()
+            new_median = (stacked * weights.unsqueeze(1)).sum(dim=0)
+            if (new_median - median).pow(2).sum().sqrt() < self.tol:
+                break
+            median = new_median
+
+        # Unflatten back to state dict
+        new_state = {}
+        offset = 0
+        for key in sorted(global_state.keys()):
+            numel = global_state[key].numel()
+            delta = median[offset:offset+numel].reshape(global_state[key].shape)
+            new_state[key] = global_state[key].float() + delta
+            offset += numel
+        return new_state

federated_graph-0.1.0/src/federated_graph/aggregation/trust.py

@@ -0,0 +1,49 @@
+import torch
+from federated_graph.aggregation.base import Aggregator
+from federated_graph.federation.update import ModelUpdate
+
+
+class TrustWeighting(Aggregator):
+    """
+    Trust-weighted aggregation: w_i = p_i * tau_i
+    where p_i = n_i / sum(n) and tau_i is a trust score in [0, 1].
+    """
+
+    def __init__(self):
+        self._trust_scores: dict[str, float] = {}
+
+    def set_trust(self, client_id: str, trust: float) -> None:
+        """Set trust score for a client (0 to 1)."""
+        self._trust_scores[client_id] = max(0.0, min(1.0, trust))
+
+    def get_trust(self, client_id: str) -> float:
+        return self._trust_scores.get(client_id, 1.0)
+
+    def aggregate(self, updates: list[ModelUpdate],
+                  global_state: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        # Compute weights: w_i = p_i * tau_i
+        total_samples = sum(u.num_samples for u in updates)
+        if total_samples == 0:
+            return global_state
+
+        weights = []
+        for u in updates:
+            p_i = u.num_samples / total_samples
+            tau_i = self.get_trust(u.client_id)
+            weights.append(p_i * tau_i)
+
+        # Normalize weights
+        w_sum = sum(weights)
+        if w_sum > 0:
+            weights = [w / w_sum for w in weights]
+        else:
+            weights = [1.0 / len(updates)] * len(updates)
+
+        new_state = {}
+        for key in global_state:
+            weighted_delta = torch.zeros_like(global_state[key].float())
+            for update, weight in zip(updates, weights):
+                if key in update.state_delta:
+                    weighted_delta += update.state_delta[key].float() * weight
+            new_state[key] = global_state[key].float() + weighted_delta
+        return new_state

federated_graph-0.1.0/src/federated_graph/compliance/__init__.py

@@ -0,0 +1,4 @@
+from federated_graph.compliance.audit import AuditLogger
+from federated_graph.compliance.serialization import ComplianceRecord, deterministic_json, hash_json
+from federated_graph.compliance.sar import SARNarrativeGenerator, SARPattern
+from federated_graph.compliance.metrics import ComplianceMetrics, compute_compliance_metrics

federated_graph-0.1.0/src/federated_graph/compliance/audit.py

@@ -0,0 +1,64 @@
+"""Structured JSON audit logging for all federation events."""
+
+import json
+import time
+import structlog
+from pathlib import Path
+from typing import Any
+
+logger = structlog.get_logger()
+
+
+class AuditLogger:
+    """Structured JSON audit logger for federation events."""
+
+    def __init__(self, log_dir: str | Path | None = None):
+        self.log_dir = Path(log_dir) if log_dir else None
+        self._events: list[dict[str, Any]] = []
+        if self.log_dir:
+            self.log_dir.mkdir(parents=True, exist_ok=True)
+
+    def log_event(self, event_type: str, **kwargs: Any) -> dict[str, Any]:
+        """Log a structured audit event."""
+        event = {
+            "timestamp": time.time(),
+            "event_type": event_type,
+            **kwargs,
+        }
+        self._events.append(event)
+        logger.info(event_type, **kwargs)
+
+        if self.log_dir:
+            log_file = self.log_dir / f"audit_{int(time.time())}.jsonl"
+            with open(log_file, "a") as f:
+                f.write(json.dumps(event) + "\n")
+
+        return event
+
+    def log_round_start(self, round_num: int, num_clients: int) -> dict:
+        return self.log_event("round_start", round_num=round_num, num_clients=num_clients)
+
+    def log_round_end(self, round_num: int, verdict: str, state_hash: str = "") -> dict:
+        return self.log_event("round_end", round_num=round_num, verdict=verdict, state_hash=state_hash)
+
+    def log_client_update(self, round_num: int, client_id: str,
+                          num_samples: int, update_hash: str = "") -> dict:
+        return self.log_event("client_update", round_num=round_num,
+                             client_id=client_id, num_samples=num_samples, update_hash=update_hash)
+
+    def log_rejection(self, round_num: int, client_id: str, reason: str) -> dict:
+        return self.log_event("rejection", round_num=round_num, client_id=client_id, reason=reason)
+
+    def log_model_publish(self, round_num: int, state_hash: str, model_version: str = "") -> dict:
+        return self.log_event("model_publish", round_num=round_num,
+                             state_hash=state_hash, model_version=model_version)
+
+    def get_events(self, event_type: str | None = None) -> list[dict]:
+        if event_type:
+            return [e for e in self._events if e["event_type"] == event_type]
+        return list(self._events)
+
+    def export_json(self, path: str | Path) -> None:
+        """Export all events to a JSON file."""
+        with open(path, "w") as f:
+            json.dump(self._events, f, indent=2)