dromeus 0.4.0.dev1__tar.gz

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-0.4.0.dev1/.gitignore +93 -0
  2. dromeus-0.4.0.dev1/LICENSE +21 -0
  3. dromeus-0.4.0.dev1/PKG-INFO +150 -0
  4. dromeus-0.4.0.dev1/README.md +128 -0
  5. dromeus-0.4.0.dev1/pyproject.toml +73 -0
  6. dromeus-0.4.0.dev1/src/dromeus/__init__.py +109 -0
  7. dromeus-0.4.0.dev1/src/dromeus/__main__.py +6 -0
  8. dromeus-0.4.0.dev1/src/dromeus/algorithms/__init__.py +31 -0
  9. dromeus-0.4.0.dev1/src/dromeus/algorithms/base.py +188 -0
  10. dromeus-0.4.0.dev1/src/dromeus/algorithms/codec.py +623 -0
  11. dromeus-0.4.0.dev1/src/dromeus/algorithms/noloco.py +486 -0
  12. dromeus-0.4.0.dev1/src/dromeus/application.py +523 -0
  13. dromeus-0.4.0.dev1/src/dromeus/cli.py +341 -0
  14. dromeus-0.4.0.dev1/src/dromeus/diagnostics.py +303 -0
  15. dromeus-0.4.0.dev1/src/dromeus/errors.py +57 -0
  16. dromeus-0.4.0.dev1/src/dromeus/gossip/__init__.py +29 -0
  17. dromeus-0.4.0.dev1/src/dromeus/gossip/_async.py +15 -0
  18. dromeus-0.4.0.dev1/src/dromeus/gossip/axl.py +497 -0
  19. dromeus-0.4.0.dev1/src/dromeus/gossip/engine.py +378 -0
  20. dromeus-0.4.0.dev1/src/dromeus/gossip/interfaces.py +158 -0
  21. dromeus-0.4.0.dev1/src/dromeus/gossip/peer_scheduler.py +117 -0
  22. dromeus-0.4.0.dev1/src/dromeus/manifests/__init__.py +1 -0
  23. dromeus-0.4.0.dev1/src/dromeus/manifests/canonical.py +157 -0
  24. dromeus-0.4.0.dev1/src/dromeus/manifests/models.py +694 -0
  25. dromeus-0.4.0.dev1/src/dromeus/membership/__init__.py +1 -0
  26. dromeus-0.4.0.dev1/src/dromeus/membership/formation.py +576 -0
  27. dromeus-0.4.0.dev1/src/dromeus/node.py +338 -0
  28. dromeus-0.4.0.dev1/src/dromeus/persistence/__init__.py +20 -0
  29. dromeus-0.4.0.dev1/src/dromeus/persistence/archive.py +576 -0
  30. dromeus-0.4.0.dev1/src/dromeus/persistence/files.py +39 -0
  31. dromeus-0.4.0.dev1/src/dromeus/persistence/privacy_ledger.py +104 -0
  32. dromeus-0.4.0.dev1/src/dromeus/persistence/run_store.py +352 -0
  33. dromeus-0.4.0.dev1/src/dromeus/protocol/__init__.py +25 -0
  34. dromeus-0.4.0.dev1/src/dromeus/protocol/codec.py +127 -0
  35. dromeus-0.4.0.dev1/src/dromeus/protocol/models.py +199 -0
  36. dromeus-0.4.0.dev1/src/dromeus/protocol/version.py +5 -0
  37. dromeus-0.4.0.dev1/src/dromeus/py.typed +1 -0
  38. dromeus-0.4.0.dev1/src/dromeus/runtime.py +1081 -0
  39. dromeus-0.4.0.dev1/src/dromeus/telemetry/__init__.py +61 -0
  40. dromeus-0.4.0.dev1/src/dromeus/telemetry/consensus.py +909 -0
  41. dromeus-0.4.0.dev1/src/dromeus/telemetry/divergence.py +321 -0
  42. dromeus-0.4.0.dev1/src/dromeus/telemetry/divergence_monitor.py +97 -0
  43. dromeus-0.4.0.dev1/src/dromeus/telemetry/events.py +214 -0
  44. dromeus-0.4.0.dev1/src/dromeus/telemetry/evidence.py +429 -0
  45. dromeus-0.4.0.dev1/src/dromeus/telemetry/metrics.py +200 -0
  46. dromeus-0.4.0.dev1/src/dromeus/telemetry/progress.py +255 -0
  47. dromeus-0.4.0.dev1/src/dromeus/training/__init__.py +1 -0
  48. dromeus-0.4.0.dev1/src/dromeus/training/base.py +60 -0
  49. dromeus-0.4.0.dev1/src/dromeus/training/model_state.py +111 -0
  50. dromeus-0.4.0.dev1/src/dromeus/training/native_gradients.py +289 -0
  51. dromeus-0.4.0.dev1/src/dromeus/training/optimizer_factory.py +426 -0
  52. dromeus-0.4.0.dev1/src/dromeus/training/ordinary_task.py +408 -0
  53. dromeus-0.4.0.dev1/src/dromeus/training/privacy.py +96 -0
  54. dromeus-0.4.0.dev1/src/dromeus/training/private_data.py +96 -0
  55. dromeus-0.4.0.dev1/src/dromeus/training/private_model.py +414 -0
  56. dromeus-0.4.0.dev1/src/dromeus/training/private_state.py +97 -0
  57. dromeus-0.4.0.dev1/src/dromeus/training/private_trainer.py +534 -0
  58. dromeus-0.4.0.dev1/src/dromeus/training/private_workload.py +217 -0
  59. dromeus-0.4.0.dev1/src/dromeus/training/state.py +57 -0
  60. dromeus-0.4.0.dev1/src/dromeus/training/task.py +464 -0
  61. dromeus-0.4.0.dev1/src/dromeus/training/trainer.py +294 -0
  62. dromeus-0.4.0.dev1/src/dromeus/training/versions.py +15 -0
  63. dromeus-0.4.0.dev1/src/dromeus/transport/__init__.py +1 -0
  64. dromeus-0.4.0.dev1/src/dromeus/transport/axl.py +168 -0
  65. dromeus-0.4.0.dev1/src/dromeus/transport/envelope_sender.py +73 -0
  66. dromeus-0.4.0.dev1/src/dromeus/transport/interface.py +31 -0
  67. dromeus-0.4.0.dev1/src/dromeus/transport/outbound_scheduler.py +326 -0
  68. dromeus-0.4.0.dev1/src/dromeus/transport/receiver.py +345 -0
  69. dromeus-0.4.0.dev1/src/dromeus/transport/transfer.py +854 -0
@@ -0,0 +1,93 @@
1
+ # Python
2
+ *.py[cod]
3
+ .pytest_cache/
4
+ .ruff_cache
5
+ .venv/
6
+ __pycache__/
7
+ /dist/
8
+
9
+ # Local documentation
10
+ docs/
11
+ graphify-out
12
+ learning-records
13
+ lessons
14
+ reference
15
+
16
+ # Logs
17
+ logs/*.log
18
+
19
+ # Local formation dashboard runtime
20
+ .demo-cache/
21
+
22
+ # Misc
23
+ .DS_Store
24
+ misc/
25
+ tmp
26
+
27
+ # Local AWS instance credentials and connection state
28
+ aws
29
+
30
+ # Local credentials and machine configuration
31
+ .env
32
+ .env.*
33
+ !.env.example
34
+ !.env.sample
35
+ *.pem
36
+ *.key
37
+
38
+ # New benchmark Python scripts stay local; tracked modules remain tracked.
39
+ /benchmarks/**/*.py
40
+
41
+ # M3 experiment tooling remains local.
42
+ /benchmarks/m3/
43
+
44
+ # Benchmark tests stay local; source-module tests remain tracked.
45
+ /tests/benchmarks/
46
+
47
+ # Keep logs and compact benchmark evidence in Git; keep model binaries external.
48
+ benchmarks/results/m2/**/*.safetensors
49
+ benchmarks/results/m2/**/*.pt
50
+ benchmarks/results/m2/**/*.pth
51
+ benchmarks/results/m2/**/*.npz
52
+ benchmarks/results/m2/**/*.tar.gz
53
+ benchmarks/results/m2/**/*.zip
54
+ benchmarks/results/m2/**/archives/
55
+ benchmarks/results/m2/**/provisioning/
56
+ benchmarks/results/m2/**/cifar-cache/
57
+ benchmarks/results/m2/nccl-reference/**/preflight/
58
+ benchmarks/results/m2/nccl-reference/**/aws/
59
+ benchmarks/results/m2/nccl-reference/**/cleanup/*
60
+ !benchmarks/results/m2/nccl-reference/**/cleanup/final-state.json
61
+ benchmarks/results/m2/nccl-reference/remediation-preflight-*/
62
+ benchmarks/results/m2/nccl-reference/campaign-*/
63
+
64
+ # Generated application-development runs are separate from the M2 submission.
65
+ benchmarks/results/local-data-validation/
66
+
67
+ # Keep M3 working experiments local; expose only the curated judge handoff.
68
+ /benchmarks/results/m3/*
69
+ !/benchmarks/results/m3/README.md
70
+ !/benchmarks/results/m3/milestone-requirements.md
71
+ !/benchmarks/results/m3/proposal-basis.json
72
+ !/benchmarks/results/m3/run-index.json
73
+ !/benchmarks/results/m3/artifact-availability.json
74
+ !/benchmarks/results/m3/file-manifest.json
75
+ !/benchmarks/results/m3/checksums.sha256
76
+ !/benchmarks/results/m3/results/
77
+ !/benchmarks/results/m3/configurations/
78
+ !/benchmarks/results/m3/audit/
79
+ !/benchmarks/results/m3/provenance/
80
+ !/benchmarks/results/m3/verification/
81
+ !/benchmarks/results/m3/verification/verify-retained-logs.py
82
+
83
+ # Local application samples; maintained fixtures and workloads live elsewhere.
84
+ /examples/*
85
+ !/examples/README.md
86
+ !/examples/__init__.py
87
+ !/examples/custom_training.py
88
+ !/examples/custom-regression-draft.yaml
89
+ !/examples/node.yaml
90
+
91
+ releases
92
+
93
+ benchmarks/results/history-reports-2026-10-29
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Devesh
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,150 @@
1
+ Metadata-Version: 2.5
2
+ Name: dromeus
3
+ Version: 0.4.0.dev1
4
+ Summary: Decentralized federated learning over AXL
5
+ Author: Dromeus contributors
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Classifier: Development Status :: 2 - Pre-Alpha
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Programming Language :: Python :: 3.12
11
+ Classifier: Typing :: Typed
12
+ Requires-Python: <3.13,>=3.12
13
+ Requires-Dist: msgpack<2,>=1.1
14
+ Requires-Dist: numpy<3,>=2
15
+ Requires-Dist: pydantic<3,>=2.11
16
+ Requires-Dist: pyyaml<7,>=6.0
17
+ Requires-Dist: safetensors<1,>=0.5
18
+ Requires-Dist: torch<3,>=2.7
19
+ Provides-Extra: privacy
20
+ Requires-Dist: opacus==1.6.0; extra == 'privacy'
21
+ Description-Content-Type: text/markdown
22
+
23
+ # Dromeus
24
+
25
+ Dromeus is a Python library for **decentralized federated learning**. Each
26
+ participant trains on its own local dataset and exchanges model updates with
27
+ peers over [Gensyn's AXL network](https://github.com/gensyn-ai/axl), without a
28
+ central server aggregating those updates.
29
+
30
+ You bring the model, per-record loss and optimizer as a `TrainingTask`. Dromeus
31
+ coordinates the group, runs local training and applies
32
+ [NoLoCo](https://github.com/gensyn-ai/noloco) updates between peers. It is built for developers experimenting with decentralized training on
33
+ independently operated machines.
34
+
35
+ ## How training works
36
+
37
+ Participants agree on a model, training policy, and fixed membership before the
38
+ run starts. They then repeat the same loop:
39
+
40
+ 1. Train on local data for the configured number of steps.
41
+ 2. Exchange outer gradients and slow weights with the scheduled peer.
42
+ 3. Apply NoLoCo's outer momentum update and save the committed round.
43
+
44
+ The peer schedule changes each round. Pairs make progress independently, subject
45
+ to readiness and timeout limits. One node coordinates group setup; training
46
+ updates happen between peers without a global all-reduce.
47
+
48
+ AXL runs beside each application and handles encrypted network routing. Dromeus
49
+ adds chunk acknowledgments, bounded retries, and checks on the sender, round,
50
+ and tensor contents. Top-k sparsification and 8-bit quantization reduce update
51
+ traffic, while error feedback carries outer-gradient compression error into
52
+ later rounds. An identity codec is also available.
53
+
54
+ Each worker keeps its own model, and final weights can differ. Per-node logs
55
+ record evaluation metrics, timing, and transfer behavior.
56
+
57
+ ## Get started
58
+
59
+ Use Python 3.12 and `uv`. Install from the source checkout:
60
+
61
+ ```bash
62
+ git clone https://github.com/devesh1011/dromeus.git
63
+ cd dromeus
64
+ ./scripts/bootstrap
65
+ ```
66
+
67
+ The [training guide](guides/application-training.md) covers the three steps
68
+ with a complete regression example:
69
+
70
+ ```python
71
+ import dromeus
72
+
73
+ task = dromeus.TrainingTask(...) # model, batches, loss, optimizer; same on every node
74
+ dromeus.make_draft(task, "draft.yaml", run_id="my-run", participants=4,
75
+ rounds=20, local_steps=10, axl_version="your-axl-version")
76
+ # on each node, with its own records:
77
+ await dromeus.Node.from_file("node.yaml").run(task, local=dromeus.LocalData(...))
78
+ ```
79
+
80
+ Before launching, configure an AXL node on each machine and connect the group's
81
+ peers. The [configuration guide](guides/configuration.md) covers each node's
82
+ `node.yaml`. One participant initiates group formation; share its invitation file
83
+ with the other participants. From the command line, each node runs:
84
+
85
+ ```bash
86
+ dromeus doctor --config /path/to/node.yaml # optional: is this machine ready?
87
+ dromeus run --config /path/to/node.yaml --task my_training:setup
88
+ ```
89
+
90
+ where `my_training.setup()` returns this node's `(task, LocalData)`. The
91
+ [command-line guide](guides/command-line.md) covers every command and exit code.
92
+
93
+ ## Working assumptions
94
+
95
+ Dromeus supports fixed, even-sized groups of 4 to 16 participants. Nodes must
96
+ agree on model structure and parameter meaning; the PyTorch integration exchanges
97
+ compatible FP32 model state. Participants may hold different amounts of data,
98
+ but each node has equal weight in the outer update.
99
+
100
+ Membership stays fixed for the run. A peer failure or missed deadline can end
101
+ training; automatic distributed restart is not implemented. Checkpoint restore
102
+ requires compatible application state.
103
+
104
+ Keeping datasets local does not make ordinary model updates private. Optional
105
+ private training uses Opacus per-example clipping, Gaussian noise and per-node
106
+ accounting through an owned trainer. Groups supply compatible optimizer factories;
107
+ private execution also requires an admitted model/loss and the documented state
108
+ contract. See [private training](guides/private-training.md) for supported
109
+ profiles, secure randomness, privacy scope and fresh-start restrictions.
110
+
111
+ Divergence monitoring records model disagreement and emits configurable warnings.
112
+ Thresholds are workload-specific and require calibration; agreement alone does not
113
+ prove model utility. See [monitoring](guides/divergence-monitoring.md).
114
+ Secure aggregation and Byzantine fault tolerance are not implemented.
115
+
116
+ ## Benchmarks
117
+
118
+ The [technical report](https://github.com/devesh1011/dromeus/releases/download/v0.2.0/M2_Gensyn_Submission_Report.pdf)
119
+ compares NoLoCo over AXL with an independent NCCL reference at 4, 8, and 16 GPU
120
+ workers using GroupNorm ResNet-18 on IID CIFAR-10 partitions. It includes codec
121
+ comparisons, learning curves, communication measurements, and deployment limits.
122
+ These results describe that workload; they do not establish convergence for
123
+ arbitrary models or data distributions.
124
+
125
+ See the [accuracy table](https://github.com/devesh1011/dromeus/blob/v0.2.0/benchmarks/results/m2/report/metrics.csv)
126
+ and [published M2 evidence index](https://github.com/devesh1011/dromeus/blob/v0.2.0/benchmarks/results/m2/README.md)
127
+ for retained metrics, charts and frozen settings. The owner permanently retired
128
+ the old local raw-result trees; unique deleted logs and models are no longer
129
+ available for re-audit from this checkout.
130
+
131
+ The [M3 team review](https://github.com/devesh1011/dromeus/blob/v0.3.0/benchmarks/results/m3/README.md)
132
+ maps the proposal requirements to numeric results, runtime and privacy checks, and
133
+ the validated digit-warning policy. It also includes the completed language-model
134
+ study as additional evidence. The folder omits report charts and large training
135
+ artifacts. Read the [criteria check](https://github.com/devesh1011/dromeus/blob/v0.3.0/benchmarks/results/m3/milestone-requirements.md)
136
+ for verified scope, publication status, and evidence-retention limits.
137
+
138
+ Each milestone's benchmark code and evidence are verified at its release tag
139
+ (`v0.1.0`, `v0.2.0`, `v0.3.0`). `main` carries only the current library and its
140
+ tests; the benchmark runners used for those milestones are not maintained here.
141
+
142
+ ## Development
143
+
144
+ Run `./scripts/verify` before contributing. It checks architecture boundaries,
145
+ lint, types, and tests. The [test guide](tests/README.md) lists focused commands
146
+ and the prerequisites for real-AXL integration tests.
147
+
148
+ ## License
149
+
150
+ [MIT](LICENSE).
@@ -0,0 +1,128 @@
1
+ # Dromeus
2
+
3
+ Dromeus is a Python library for **decentralized federated learning**. Each
4
+ participant trains on its own local dataset and exchanges model updates with
5
+ peers over [Gensyn's AXL network](https://github.com/gensyn-ai/axl), without a
6
+ central server aggregating those updates.
7
+
8
+ You bring the model, per-record loss and optimizer as a `TrainingTask`. Dromeus
9
+ coordinates the group, runs local training and applies
10
+ [NoLoCo](https://github.com/gensyn-ai/noloco) updates between peers. It is built for developers experimenting with decentralized training on
11
+ independently operated machines.
12
+
13
+ ## How training works
14
+
15
+ Participants agree on a model, training policy, and fixed membership before the
16
+ run starts. They then repeat the same loop:
17
+
18
+ 1. Train on local data for the configured number of steps.
19
+ 2. Exchange outer gradients and slow weights with the scheduled peer.
20
+ 3. Apply NoLoCo's outer momentum update and save the committed round.
21
+
22
+ The peer schedule changes each round. Pairs make progress independently, subject
23
+ to readiness and timeout limits. One node coordinates group setup; training
24
+ updates happen between peers without a global all-reduce.
25
+
26
+ AXL runs beside each application and handles encrypted network routing. Dromeus
27
+ adds chunk acknowledgments, bounded retries, and checks on the sender, round,
28
+ and tensor contents. Top-k sparsification and 8-bit quantization reduce update
29
+ traffic, while error feedback carries outer-gradient compression error into
30
+ later rounds. An identity codec is also available.
31
+
32
+ Each worker keeps its own model, and final weights can differ. Per-node logs
33
+ record evaluation metrics, timing, and transfer behavior.
34
+
35
+ ## Get started
36
+
37
+ Use Python 3.12 and `uv`. Install from the source checkout:
38
+
39
+ ```bash
40
+ git clone https://github.com/devesh1011/dromeus.git
41
+ cd dromeus
42
+ ./scripts/bootstrap
43
+ ```
44
+
45
+ The [training guide](guides/application-training.md) covers the three steps
46
+ with a complete regression example:
47
+
48
+ ```python
49
+ import dromeus
50
+
51
+ task = dromeus.TrainingTask(...) # model, batches, loss, optimizer; same on every node
52
+ dromeus.make_draft(task, "draft.yaml", run_id="my-run", participants=4,
53
+ rounds=20, local_steps=10, axl_version="your-axl-version")
54
+ # on each node, with its own records:
55
+ await dromeus.Node.from_file("node.yaml").run(task, local=dromeus.LocalData(...))
56
+ ```
57
+
58
+ Before launching, configure an AXL node on each machine and connect the group's
59
+ peers. The [configuration guide](guides/configuration.md) covers each node's
60
+ `node.yaml`. One participant initiates group formation; share its invitation file
61
+ with the other participants. From the command line, each node runs:
62
+
63
+ ```bash
64
+ dromeus doctor --config /path/to/node.yaml # optional: is this machine ready?
65
+ dromeus run --config /path/to/node.yaml --task my_training:setup
66
+ ```
67
+
68
+ where `my_training.setup()` returns this node's `(task, LocalData)`. The
69
+ [command-line guide](guides/command-line.md) covers every command and exit code.
70
+
71
+ ## Working assumptions
72
+
73
+ Dromeus supports fixed, even-sized groups of 4 to 16 participants. Nodes must
74
+ agree on model structure and parameter meaning; the PyTorch integration exchanges
75
+ compatible FP32 model state. Participants may hold different amounts of data,
76
+ but each node has equal weight in the outer update.
77
+
78
+ Membership stays fixed for the run. A peer failure or missed deadline can end
79
+ training; automatic distributed restart is not implemented. Checkpoint restore
80
+ requires compatible application state.
81
+
82
+ Keeping datasets local does not make ordinary model updates private. Optional
83
+ private training uses Opacus per-example clipping, Gaussian noise and per-node
84
+ accounting through an owned trainer. Groups supply compatible optimizer factories;
85
+ private execution also requires an admitted model/loss and the documented state
86
+ contract. See [private training](guides/private-training.md) for supported
87
+ profiles, secure randomness, privacy scope and fresh-start restrictions.
88
+
89
+ Divergence monitoring records model disagreement and emits configurable warnings.
90
+ Thresholds are workload-specific and require calibration; agreement alone does not
91
+ prove model utility. See [monitoring](guides/divergence-monitoring.md).
92
+ Secure aggregation and Byzantine fault tolerance are not implemented.
93
+
94
+ ## Benchmarks
95
+
96
+ The [technical report](https://github.com/devesh1011/dromeus/releases/download/v0.2.0/M2_Gensyn_Submission_Report.pdf)
97
+ compares NoLoCo over AXL with an independent NCCL reference at 4, 8, and 16 GPU
98
+ workers using GroupNorm ResNet-18 on IID CIFAR-10 partitions. It includes codec
99
+ comparisons, learning curves, communication measurements, and deployment limits.
100
+ These results describe that workload; they do not establish convergence for
101
+ arbitrary models or data distributions.
102
+
103
+ See the [accuracy table](https://github.com/devesh1011/dromeus/blob/v0.2.0/benchmarks/results/m2/report/metrics.csv)
104
+ and [published M2 evidence index](https://github.com/devesh1011/dromeus/blob/v0.2.0/benchmarks/results/m2/README.md)
105
+ for retained metrics, charts and frozen settings. The owner permanently retired
106
+ the old local raw-result trees; unique deleted logs and models are no longer
107
+ available for re-audit from this checkout.
108
+
109
+ The [M3 team review](https://github.com/devesh1011/dromeus/blob/v0.3.0/benchmarks/results/m3/README.md)
110
+ maps the proposal requirements to numeric results, runtime and privacy checks, and
111
+ the validated digit-warning policy. It also includes the completed language-model
112
+ study as additional evidence. The folder omits report charts and large training
113
+ artifacts. Read the [criteria check](https://github.com/devesh1011/dromeus/blob/v0.3.0/benchmarks/results/m3/milestone-requirements.md)
114
+ for verified scope, publication status, and evidence-retention limits.
115
+
116
+ Each milestone's benchmark code and evidence are verified at its release tag
117
+ (`v0.1.0`, `v0.2.0`, `v0.3.0`). `main` carries only the current library and its
118
+ tests; the benchmark runners used for those milestones are not maintained here.
119
+
120
+ ## Development
121
+
122
+ Run `./scripts/verify` before contributing. It checks architecture boundaries,
123
+ lint, types, and tests. The [test guide](tests/README.md) lists focused commands
124
+ and the prerequisites for real-AXL integration tests.
125
+
126
+ ## License
127
+
128
+ [MIT](LICENSE).
@@ -0,0 +1,73 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "dromeus"
7
+ version = "0.4.0.dev1"
8
+ description = "Decentralized federated learning over AXL"
9
+ readme = "README.md"
10
+ requires-python = ">=3.12,<3.13"
11
+ license = "MIT"
12
+ authors = [{ name = "Dromeus contributors" }]
13
+ classifiers = [
14
+ "Development Status :: 2 - Pre-Alpha",
15
+ "License :: OSI Approved :: MIT License",
16
+ "Programming Language :: Python :: 3.12",
17
+ "Typing :: Typed",
18
+ ]
19
+ dependencies = [
20
+ "msgpack>=1.1,<2",
21
+ "numpy>=2,<3",
22
+ "pydantic>=2.11,<3",
23
+ "pyyaml>=6.0,<7",
24
+ "safetensors>=0.5,<1",
25
+ "torch>=2.7,<3",
26
+ ]
27
+
28
+ [project.scripts]
29
+ dromeus = "dromeus.cli:main"
30
+
31
+ [project.optional-dependencies]
32
+ privacy = ["opacus==1.6.0"]
33
+
34
+ [tool.uv.sources]
35
+ torch = [{ index = "pytorch-cpu", marker = "sys_platform == 'linux'" }]
36
+
37
+ [[tool.uv.index]]
38
+ name = "pytorch-cpu"
39
+ url = "https://download.pytorch.org/whl/cpu"
40
+ explicit = true
41
+
42
+ [dependency-groups]
43
+ dev = [
44
+ "pyright>=1.1.400",
45
+ "pytest>=8.4",
46
+ "ruff>=0.12",
47
+ ]
48
+
49
+ [tool.hatch.build.targets.wheel]
50
+ packages = ["src/dromeus"]
51
+
52
+ [tool.hatch.build.targets.sdist]
53
+ # Runtime source only. Benchmark evidence is distributed separately.
54
+ only-include = ["src", "pyproject.toml", "README.md", "LICENSE"]
55
+
56
+ [tool.pyright]
57
+ extraPaths = [".", "src", "tests"]
58
+ include = ["src", "tests", "benchmarks"]
59
+ # Retained results are frozen evidence for their tagged release, not code
60
+ # maintained against the current library.
61
+ exclude = ["benchmarks/results"]
62
+ typeCheckingMode = "strict"
63
+
64
+ [tool.pytest.ini_options]
65
+ testpaths = ["tests"]
66
+
67
+ [tool.ruff]
68
+ target-version = "py312"
69
+ # Lint only the installed library; benchmarks, tests and frozen results are excluded.
70
+ include = ["src/dromeus/**/*.py"]
71
+
72
+ [tool.ruff.lint]
73
+ select = ["E", "F", "I", "UP"]
@@ -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
+ ]
@@ -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
+ ]