dromeus 0.4.0.dev1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. dromeus/__init__.py +109 -0
  2. dromeus/__main__.py +6 -0
  3. dromeus/algorithms/__init__.py +31 -0
  4. dromeus/algorithms/base.py +188 -0
  5. dromeus/algorithms/codec.py +623 -0
  6. dromeus/algorithms/noloco.py +486 -0
  7. dromeus/application.py +523 -0
  8. dromeus/cli.py +341 -0
  9. dromeus/diagnostics.py +303 -0
  10. dromeus/errors.py +57 -0
  11. dromeus/gossip/__init__.py +29 -0
  12. dromeus/gossip/_async.py +15 -0
  13. dromeus/gossip/axl.py +497 -0
  14. dromeus/gossip/engine.py +378 -0
  15. dromeus/gossip/interfaces.py +158 -0
  16. dromeus/gossip/peer_scheduler.py +117 -0
  17. dromeus/manifests/__init__.py +1 -0
  18. dromeus/manifests/canonical.py +157 -0
  19. dromeus/manifests/models.py +694 -0
  20. dromeus/membership/__init__.py +1 -0
  21. dromeus/membership/formation.py +576 -0
  22. dromeus/node.py +338 -0
  23. dromeus/persistence/__init__.py +20 -0
  24. dromeus/persistence/archive.py +576 -0
  25. dromeus/persistence/files.py +39 -0
  26. dromeus/persistence/privacy_ledger.py +104 -0
  27. dromeus/persistence/run_store.py +352 -0
  28. dromeus/protocol/__init__.py +25 -0
  29. dromeus/protocol/codec.py +127 -0
  30. dromeus/protocol/models.py +199 -0
  31. dromeus/protocol/version.py +5 -0
  32. dromeus/py.typed +1 -0
  33. dromeus/runtime.py +1081 -0
  34. dromeus/telemetry/__init__.py +61 -0
  35. dromeus/telemetry/consensus.py +909 -0
  36. dromeus/telemetry/divergence.py +321 -0
  37. dromeus/telemetry/divergence_monitor.py +97 -0
  38. dromeus/telemetry/events.py +214 -0
  39. dromeus/telemetry/evidence.py +429 -0
  40. dromeus/telemetry/metrics.py +200 -0
  41. dromeus/telemetry/progress.py +255 -0
  42. dromeus/training/__init__.py +1 -0
  43. dromeus/training/base.py +60 -0
  44. dromeus/training/model_state.py +111 -0
  45. dromeus/training/native_gradients.py +289 -0
  46. dromeus/training/optimizer_factory.py +426 -0
  47. dromeus/training/ordinary_task.py +408 -0
  48. dromeus/training/privacy.py +96 -0
  49. dromeus/training/private_data.py +96 -0
  50. dromeus/training/private_model.py +414 -0
  51. dromeus/training/private_state.py +97 -0
  52. dromeus/training/private_trainer.py +534 -0
  53. dromeus/training/private_workload.py +217 -0
  54. dromeus/training/state.py +57 -0
  55. dromeus/training/task.py +464 -0
  56. dromeus/training/trainer.py +294 -0
  57. dromeus/training/versions.py +15 -0
  58. dromeus/transport/__init__.py +1 -0
  59. dromeus/transport/axl.py +168 -0
  60. dromeus/transport/envelope_sender.py +73 -0
  61. dromeus/transport/interface.py +31 -0
  62. dromeus/transport/outbound_scheduler.py +326 -0
  63. dromeus/transport/receiver.py +345 -0
  64. dromeus/transport/transfer.py +854 -0
  65. dromeus-0.4.0.dev1.dist-info/METADATA +150 -0
  66. dromeus-0.4.0.dev1.dist-info/RECORD +69 -0
  67. dromeus-0.4.0.dev1.dist-info/WHEEL +4 -0
  68. dromeus-0.4.0.dev1.dist-info/entry_points.txt +2 -0
  69. dromeus-0.4.0.dev1.dist-info/licenses/LICENSE +21 -0
dromeus/__init__.py ADDED
@@ -0,0 +1,109 @@
1
+ """Decentralized federated learning over Gensyn AXL.
2
+
3
+ Every node trains the same `TrainingTask` on its own records and exchanges NoLoCo
4
+ updates with one peer per round. Typical use:
5
+
6
+ 1. Define a `TrainingTask` that every node builds identically.
7
+ 2. One person writes the shared draft with `make_draft(task, "draft.yaml", ...)`.
8
+ 3. Each node runs `await Node.from_file("node.yaml").run(task, local=LocalData(...))`.
9
+
10
+ Only the names exported here are the public, stable API.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from importlib import import_module
16
+ from importlib.metadata import version as _version
17
+ from typing import TYPE_CHECKING, Any
18
+
19
+ if TYPE_CHECKING:
20
+ from dromeus.application import (
21
+ LocalData,
22
+ NoLoCo,
23
+ Privacy,
24
+ check_draft,
25
+ code_hash,
26
+ make_draft,
27
+ )
28
+ from dromeus.errors import (
29
+ ConfigError,
30
+ DraftError,
31
+ DromeusError,
32
+ FormationError,
33
+ PrivacyError,
34
+ RunError,
35
+ TaskError,
36
+ )
37
+ from dromeus.manifests.models import DivergencePolicy, TransportLimits
38
+ from dromeus.node import Node, RunResult
39
+ from dromeus.persistence.privacy_ledger import PrivacyLedger
40
+ from dromeus.training.optimizer_factory import OptimizerRegistration
41
+ from dromeus.training.task import Optimizer, TensorBatchAdapter, TrainingTask
42
+
43
+ __version__ = _version("dromeus")
44
+
45
+ # Imported on first use, so `import dromeus` stays light (no PyTorch until needed).
46
+ _EXPORTS = {
47
+ "LocalData": "dromeus.application",
48
+ "NoLoCo": "dromeus.application",
49
+ "Privacy": "dromeus.application",
50
+ "check_draft": "dromeus.application",
51
+ "code_hash": "dromeus.application",
52
+ "make_draft": "dromeus.application",
53
+ "ConfigError": "dromeus.errors",
54
+ "DraftError": "dromeus.errors",
55
+ "DromeusError": "dromeus.errors",
56
+ "FormationError": "dromeus.errors",
57
+ "PrivacyError": "dromeus.errors",
58
+ "RunError": "dromeus.errors",
59
+ "TaskError": "dromeus.errors",
60
+ "DivergencePolicy": "dromeus.manifests.models",
61
+ "TransportLimits": "dromeus.manifests.models",
62
+ "Node": "dromeus.node",
63
+ "RunResult": "dromeus.node",
64
+ "PrivacyLedger": "dromeus.persistence.privacy_ledger",
65
+ "OptimizerRegistration": "dromeus.training.optimizer_factory",
66
+ "Optimizer": "dromeus.training.task",
67
+ "TensorBatchAdapter": "dromeus.training.task",
68
+ "TrainingTask": "dromeus.training.task",
69
+ }
70
+
71
+
72
+ def __getattr__(name: str) -> Any:
73
+ module = _EXPORTS.get(name)
74
+ if module is None:
75
+ raise AttributeError(f"module 'dromeus' has no attribute {name!r}")
76
+ value = getattr(import_module(module), name)
77
+ globals()[name] = value
78
+ return value
79
+
80
+
81
+ def __dir__() -> list[str]:
82
+ return sorted(__all__)
83
+
84
+
85
+ __all__ = [
86
+ "ConfigError",
87
+ "DivergencePolicy",
88
+ "DraftError",
89
+ "DromeusError",
90
+ "FormationError",
91
+ "LocalData",
92
+ "NoLoCo",
93
+ "Node",
94
+ "Optimizer",
95
+ "OptimizerRegistration",
96
+ "Privacy",
97
+ "PrivacyError",
98
+ "PrivacyLedger",
99
+ "RunError",
100
+ "RunResult",
101
+ "TaskError",
102
+ "TensorBatchAdapter",
103
+ "TrainingTask",
104
+ "TransportLimits",
105
+ "__version__",
106
+ "check_draft",
107
+ "code_hash",
108
+ "make_draft",
109
+ ]
dromeus/__main__.py ADDED
@@ -0,0 +1,6 @@
1
+ """`python -m dromeus` runs the `dromeus` command."""
2
+
3
+ from dromeus.cli import main
4
+
5
+ if __name__ == "__main__":
6
+ raise SystemExit(main())
@@ -0,0 +1,31 @@
1
+ """Training algorithm adapters."""
2
+
3
+ from dromeus.algorithms.base import (
4
+ AlgorithmObservations,
5
+ AlgorithmSnapshot,
6
+ MaterializedArtifact,
7
+ SerializableState,
8
+ UpdateBundle,
9
+ ValidatedUpdate,
10
+ )
11
+ from dromeus.algorithms.codec import (
12
+ IdentityCodec,
13
+ NamedSafetensorsUpdateBundleCodec,
14
+ NamedUpdateBundleCodec,
15
+ UpdateCodec,
16
+ )
17
+ from dromeus.manifests.models import UpdateCodecBinding
18
+
19
+ __all__ = [
20
+ "AlgorithmObservations",
21
+ "AlgorithmSnapshot",
22
+ "IdentityCodec",
23
+ "MaterializedArtifact",
24
+ "NamedSafetensorsUpdateBundleCodec",
25
+ "NamedUpdateBundleCodec",
26
+ "SerializableState",
27
+ "UpdateBundle",
28
+ "UpdateCodec",
29
+ "UpdateCodecBinding",
30
+ "ValidatedUpdate",
31
+ ]
@@ -0,0 +1,188 @@
1
+ """Training algorithm interface."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import math
7
+ from collections.abc import Mapping
8
+ from dataclasses import dataclass
9
+ from pathlib import Path
10
+ from types import MappingProxyType
11
+ from typing import Protocol
12
+
13
+ import numpy as np
14
+
15
+ from dromeus.manifests.canonical import file_sha256, update_bundle_digest
16
+ from dromeus.manifests.models import (
17
+ Identifier,
18
+ OpaqueUpdateBundleMetadata,
19
+ RoundId,
20
+ TensorSchema,
21
+ )
22
+
23
+
24
+ class SerializableState(Protocol):
25
+ """State seam shared by algorithm and codec implementations."""
26
+
27
+ def state_dict(self) -> dict[str, object]: ...
28
+
29
+ def load_state_dict(self, state: Mapping[str, object]) -> None: ...
30
+
31
+
32
+ @dataclass(frozen=True, slots=True)
33
+ class AlgorithmObservations:
34
+ """Immutable algorithm observations captured for one round."""
35
+
36
+ local_loss: float | None = None
37
+ error_feedback_residual_l2_norm: float | None = None
38
+ error_feedback_signal_l2_norm: float | None = None
39
+ error_feedback_residual_to_signal_ratio: float | None = None
40
+
41
+ def __post_init__(self) -> None:
42
+ if self.local_loss is not None and not math.isfinite(self.local_loss):
43
+ raise ValueError("local loss must be finite")
44
+ values = (
45
+ ("error-feedback residual norm", self.error_feedback_residual_l2_norm),
46
+ ("error-feedback signal norm", self.error_feedback_signal_l2_norm),
47
+ (
48
+ "error-feedback residual-to-signal ratio",
49
+ self.error_feedback_residual_to_signal_ratio,
50
+ ),
51
+ )
52
+ for label, value in values:
53
+ if value is not None and (not math.isfinite(value) or value < 0):
54
+ raise ValueError(f"{label} must be finite and non-negative")
55
+
56
+
57
+ def checksum_tensors(tensors: Mapping[str, np.ndarray]) -> str:
58
+ """Hash named tensor values independently of the algorithm implementation."""
59
+ digest = hashlib.sha256()
60
+ for name in sorted(tensors):
61
+ tensor = np.ascontiguousarray(tensors[name])
62
+ digest.update(name.encode())
63
+ digest.update(str(tensor.dtype).encode())
64
+ digest.update(str(tensor.shape).encode())
65
+ digest.update(tensor.tobytes())
66
+ return digest.hexdigest()
67
+
68
+
69
+ def _immutable_tensors(
70
+ tensors: Mapping[str, np.ndarray],
71
+ ) -> Mapping[str, np.ndarray]:
72
+ copied: dict[str, np.ndarray] = {}
73
+ for name, value in tensors.items():
74
+ tensor = np.ascontiguousarray(value).copy()
75
+ tensor.flags.writeable = False
76
+ copied[name] = tensor
77
+ return MappingProxyType(copied)
78
+
79
+
80
+ @dataclass(frozen=True, slots=True)
81
+ class AlgorithmSnapshot:
82
+ round_id: RoundId
83
+ phase: str
84
+ weights: Mapping[str, np.ndarray]
85
+
86
+ def __post_init__(self) -> None:
87
+ object.__setattr__(self, "weights", _immutable_tensors(self.weights))
88
+
89
+
90
+ @dataclass(frozen=True, slots=True)
91
+ class ValidatedUpdate:
92
+ """Algorithm-owned peer update ready to apply."""
93
+
94
+ round_id: RoundId
95
+ tensors: Mapping[str, np.ndarray]
96
+ checksum: str
97
+
98
+ def __post_init__(self) -> None:
99
+ object.__setattr__(self, "tensors", _immutable_tensors(self.tensors))
100
+
101
+
102
+ @dataclass(frozen=True, slots=True)
103
+ class NamedValidatedUpdate:
104
+ """Algorithm-owned named peer artifacts ready to apply."""
105
+
106
+ round_id: RoundId
107
+ artifacts: Mapping[str, Mapping[str, np.ndarray]]
108
+ checksum: str
109
+
110
+ def __post_init__(self) -> None:
111
+ object.__setattr__(
112
+ self,
113
+ "artifacts",
114
+ MappingProxyType(
115
+ {
116
+ name: _immutable_tensors(tensors)
117
+ for name, tensors in self.artifacts.items()
118
+ }
119
+ ),
120
+ )
121
+
122
+
123
+ AlgorithmUpdate = ValidatedUpdate | NamedValidatedUpdate
124
+
125
+
126
+ def checksum_artifacts(
127
+ artifacts: Mapping[str, Mapping[str, np.ndarray]],
128
+ ) -> str:
129
+ """Hash named tensor artifacts without flattening their public shape."""
130
+ return checksum_tensors(
131
+ {
132
+ f"{artifact_name}.{tensor_name}": tensor
133
+ for artifact_name, tensors in artifacts.items()
134
+ for tensor_name, tensor in tensors.items()
135
+ }
136
+ )
137
+
138
+
139
+ @dataclass(frozen=True, slots=True)
140
+ class MaterializedArtifact:
141
+ """Algorithm-produced bytes plus their transfer metadata."""
142
+
143
+ path: Path
144
+ transfer_codec_id: Identifier
145
+ transfer_schema: TensorSchema
146
+
147
+
148
+ @dataclass(frozen=True, slots=True)
149
+ class UpdateBundle:
150
+ """Materialized algorithm update whose contents are opaque to gossip."""
151
+
152
+ metadata: OpaqueUpdateBundleMetadata
153
+ artifacts: tuple[MaterializedArtifact, ...]
154
+
155
+ def __post_init__(self) -> None:
156
+ if len(self.artifacts) != len(self.metadata.artifacts):
157
+ raise ValueError("materialized artifacts must match bundle metadata")
158
+
159
+ @property
160
+ def digest(self) -> str:
161
+ return update_bundle_digest(self.metadata)
162
+
163
+ def validate_materialized(self, max_bytes: int) -> None:
164
+ """Validate materialized hashes plus aggregate encoded size."""
165
+ declared = sum(artifact.size_bytes for artifact in self.metadata.artifacts)
166
+ actual = sum(artifact.path.stat().st_size for artifact in self.artifacts)
167
+ if actual != declared:
168
+ raise ValueError("materialized update bundle size mismatch")
169
+ if actual > max_bytes:
170
+ raise ValueError("materialized update bundle exceeds payload limit")
171
+ for metadata, materialized in zip(
172
+ self.metadata.artifacts, self.artifacts, strict=True
173
+ ):
174
+ if file_sha256(materialized.path) != metadata.sha256:
175
+ raise ValueError("materialized update bundle checksum mismatch")
176
+
177
+
178
+ __all__ = [
179
+ "AlgorithmSnapshot",
180
+ "AlgorithmUpdate",
181
+ "MaterializedArtifact",
182
+ "NamedValidatedUpdate",
183
+ "SerializableState",
184
+ "UpdateBundle",
185
+ "ValidatedUpdate",
186
+ "checksum_artifacts",
187
+ "checksum_tensors",
188
+ ]