Skip to content

Commit cbab16d

Browse files
2-meancursoragent
2-mean
and
cursoragent
committed
docs: add descriptions to repository layout trees
Annotate README, docs index, and structure layout sections with per-path purpose notes while keeping docs-style tree formatting. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 6f46e43 commit cbab16d

3 files changed

Lines changed: 118 additions & 110 deletions

File tree

‎README.md‎

Lines changed: 31 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -140,35 +140,40 @@ Guide: [docs/framework/extension-guide.md](docs/framework/extension-guide.md)
140140

141141
```text
142142
.
143-
├── configs/
144-
│ ├── vision/
145-
│ └── cora/
146-
├── graphfl_lab/
147-
│ ├── cli/
148-
│ ├── data/
149-
│ ├── designs/
150-
│ ├── diagnostics/
151-
│ ├── graph/
152-
│ ├── lifecycle/
143+
├── configs/ JSON configs (track, smoke, suite, stress)
144+
│ ├── vision/ Fashion-MNIST vision track
145+
│ └── cora/ Cora / FGL graph-ablation track
146+
├── graphfl_lab/ installable package (Graph-FL runtime)
147+
│ ├── app/ Flower App config and server glue
148+
│ ├── cli/ argparse-only CLI modules
149+
│ ├── clients/ Flower client implementations
150+
│ ├── data/ dataset load and partition helpers
151+
│ ├── designs/ GraphFLDesign registry and presets
152+
│ ├── diagnostics/ result schemas, metrics, evidence writers
153+
│ ├── graph/ client relation graph (source, builder, registry)
154+
│ ├── lifecycle/ contracts, traces, counterfactual runner
155+
│ ├── models/ vision / Cora model definitions
153156
│ ├── strategies/
154-
│ │ ├── graphfl/
155-
│ │ └── baselines/
157+
│ │ ├── graphfl/ graph-FL server strategy (filter, aggregate, trace)
158+
│ │ └── baselines/ FedAvgM, FedSim, dominance-aware, graph_smooth, …
156159
│ └── experiments/
157-
│ ├── vision/
158-
│ └── suites/vision/
160+
│ ├── vision/ single-run and suite orchestration
161+
│ ├── cora/ Cora single-run and ablation helpers
162+
│ └── suites/vision/ variant grammar, artifacts, reporting
159163
├── scripts/
160-
│ ├── checks/
161-
│ ├── smoke/
162-
│ ├── reports/
163-
│ └── analysis/
164-
├── docs/
165-
│ ├── framework/
166-
│ ├── research/
167-
│ └── archive/
168-
├── tests/
169-
├── run_vision_experiment.py
170-
├── run_vision_suite.py
171-
└── run_graph_ablation.py
164+
│ ├── checks/ validation without full training
165+
│ ├── smoke/ short executable smoke workflows
166+
│ ├── reports/ convergence plots and dashboard helpers
167+
│ ├── analysis/ suite deep-dive and merge helpers
168+
│ └── dev/ gate-check, migration utilities
169+
├── docs/ active and archived documentation
170+
├── tests/ unit, graph, strategy, suite, structure tests
171+
├── data/ dataset cache (gitignored)
172+
├── run_vision_experiment.py thin launcher → vision single run
173+
├── run_vision_suite.py thin launcher → vision suite
174+
├── run_vision_client_count_sweep.py thin launcher → client-count sweep
175+
├── run_vision_stress_grid.py thin launcher → stress grid
176+
└── run_graph_ablation.py thin launcher → Cora graph ablation
172177
```
173178

174179
Edit routing: [docs/structure.md](docs/structure.md)

‎docs/README.md‎

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,29 @@ Use `framework/` for current work. Use `research/` for background notes. Use `ar
66

77
```text
88
docs/
9-
├── README.md
10-
├── structure.md
11-
├── framework/
12-
│ ├── claim.md
13-
│ ├── graph_fl_experimental_design.md
14-
│ ├── graph_fl_experimental_design_appendix.md
15-
│ ├── diagnostics.md
16-
│ ├── interfaces.md
17-
│ ├── lifecycle.md
18-
│ ├── prior-work-mapping.md
19-
│ ├── extension-guide.md
20-
│ ├── cleanup-plan.md
21-
│ ├── naming-and-compatibility.md
22-
│ ├── project-prompt.md
23-
│ └── experiment-results.md
24-
├── research/
25-
└── archive/
9+
├── README.md this index
10+
├── structure.md where to edit code; source and config maps
11+
├── removed-materials.md Gate 6 removals and remaining read-only aliases
12+
├── framework/ active framework documentation
13+
│ ├── claim.md project claim and non-goals
14+
│ ├── graph_fl_experimental_design.md main experiment design
15+
│ ├── graph_fl_experimental_design_appendix.md metric definitions
16+
│ ├── diagnostics.md how to read diagnostic traces
17+
│ ├── interfaces.md GraphFLDesign, graph_source, aggregation_target
18+
│ ├── lifecycle.md lifecycle modules and contracts
19+
│ ├── prior-work-mapping.md exact vs proxy vs out-of-scope prior work
20+
│ ├── extension-guide.md add graph_source / builder workflow
21+
│ ├── cleanup-plan.md rename execution summary (closed)
22+
│ ├── naming-and-compatibility.md canonical names vs read-only aliases
23+
│ ├── project-prompt.md handoff prompt for agents/maintainers
24+
│ └── experiment-results.md how to store and cite experiment outputs
25+
├── maintenance/ gate checks and rename inventory (cleanup closed)
26+
│ ├── cleanup-status.md Gate 6 execution log (closed)
27+
│ ├── gate-6-prep.md Gate 6 checklist
28+
│ ├── rename-inventory.md legacy name inventory
29+
│ └── last_gate_check.json latest gate-check record
30+
├── research/ literature and design notes (non-normative)
31+
└── archive/ superseded direction and migration phases
2632
```
2733

2834
## First Read

‎docs/structure.md‎

Lines changed: 64 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -32,60 +32,57 @@ Source code is organized by responsibility, not experiment name. Use the narrowe
3232

3333
```text
3434
graphfl_lab/
35-
app/ Flower app config/runtime glue
36-
cli/ argparse only
37-
clients/ Flower client implementations
38-
data/ dataset loading and partitioning
39-
designs/ GraphFLDesign composer/registry/presets
40-
diagnostics/ schemas, metrics, CSV/JSONL writers
41-
graph/ client relation graph construction
42-
builders.py
43-
diagnostics.py
44-
method_specs.py
45-
registry.py
46-
signals/
47-
similarity/
48-
sources/
49-
sparsification.py
50-
lifecycle/ contracts, traces, counterfactual runner
51-
strategies/
52-
baselines/
53-
graphfl/
54-
aggregation.py
55-
config.py
56-
diagnostics.py
57-
filtering.py
58-
momentum.py
59-
strategy.py
60-
targets.py
61-
tracing.py
62-
experiments/
63-
vision/
64-
cora/
65-
suites/
66-
vision/
67-
artifacts.py result/suite artifact discovery
68-
reporting.py suite summaries, dashboard, interpretation
69-
variant_helpers.py per-run result path resolution
35+
├── app/ Flower App config and runtime glue
36+
├── cli/ argparse only (vision, cora, suite, sweep)
37+
├── clients/ Flower client train/eval implementations
38+
├── data/ dataset loading and Dirichlet partition
39+
├── designs/ GraphFLDesign composer, registry, presets
40+
├── diagnostics/ result schemas, metrics, evidence bundle
41+
├── graph/ client relation graph construction
42+
│ ├── builders.py register builders; compose relation + topology
43+
│ ├── registry.py graph_mode lookup and plugin dispatch
44+
│ ├── method_specs.py runnable graph_method profiles
45+
│ ├── presets.py named graph presets
46+
│ ├── signals/ raw client signals (update, head, …)
47+
│ ├── similarity/ cosine, magnitude, RBF helpers
48+
│ ├── sources/ graph_source adapters (graphfl, fedsim, …)
49+
│ └── sparsification.py kNN and sparsification utilities
50+
├── lifecycle/ contracts, traces, counterfactual runner
51+
├── models/ CNN/MLP and Cora model wrappers
52+
├── strategies/
53+
│ ├── graphfl/ Graph-FL server strategy
54+
│ │ ├── strategy.py round loop and orchestration
55+
│ │ ├── filtering.py Laplacian / graph filter on client matrices
56+
│ │ ├── aggregation.py weighted combine and dominance hooks
57+
│ │ ├── targets.py aggregation_target dispatch
58+
│ │ └── diagnostics.py per-round graph/control metrics
59+
│ └── baselines/ non-graph and proxy baselines
60+
└── experiments/
61+
├── vision/ single_run, suite, stress_grid, sweeps
62+
├── cora/ single_run, graph_ablation helpers
63+
└── suites/vision/
64+
├── variants.py suite token grammar
65+
├── artifacts.py result/suite path discovery
66+
├── reporting.py summaries, dashboard, interpretation
67+
└── variant_helpers.py per-variant result path resolution
7068
```
7169

7270
## Compatibility Facades
7371

74-
Keep these thin. Add new logic in scoped modules, then re-export only if compatibility requires it.
72+
Keep these thin. Add new logic in scoped modules, then re-export only if a stable import path requires it.
7573

7674
```text
77-
graphfl_lab/aggregation.py
78-
graphfl_lab/client.py
79-
graphfl_lab/model.py
80-
graphfl_lab/spectral_diagnostics.py
81-
graphfl_lab/strategy.py
82-
graphfl_lab/suite_stats.py
83-
graphfl_lab/update_graph.py
84-
graphfl_lab/experiments/suite.py
85-
graphfl_lab/experiments/stress_grid.py
86-
graphfl_lab/experiments/client_count_sweep.py
87-
graphfl_lab/experiments/graph_ablation.py
88-
run_vision_*.py (canonical entrypoints; `run_general_*` removed Gate 6 batch 3)
75+
graphfl_lab/aggregation.py re-export lifecycle aggregation helpers
76+
graphfl_lab/client.py re-export Flower client entry
77+
graphfl_lab/model.py re-export model factory
78+
graphfl_lab/strategy.py re-export strategy factory
79+
graphfl_lab/suite_stats.py re-export suite statistics helpers
80+
graphfl_lab/update_graph.py re-export graph update utilities
81+
graphfl_lab/experiments/suite.py re-export vision suite runner
82+
graphfl_lab/experiments/stress_grid.py re-export stress grid runner
83+
graphfl_lab/experiments/client_count_sweep.py re-export client-count sweep
84+
graphfl_lab/experiments/graph_ablation.py re-export Cora ablation runner
85+
run_vision_*.py root thin launchers (canonical public CLI)
8986
```
9087

9188
## Boundary Rules
@@ -106,29 +103,29 @@ run_vision_*.py (canonical entrypoints; `run_general_*` removed Gate 6 batch 3)
106103

107104
```text
108105
configs/
109-
cora/
110-
ablations/
111-
graph/
112-
vision/
113-
baselines/
114-
diagnostic/
115-
smoke/
116-
probes/
117-
frequency/
118-
graph_source/
119-
structure/
120-
tau/
121-
stress/
122-
client_count/
123-
fedavg_collapse/
124-
sweeps/
125-
client_count/
106+
├── vision/ Fashion-MNIST / vision track
107+
│ ├── baselines/ FedAvg, FedOpt, dominance baselines
108+
│ ├── diagnostic/ mechanism and diagnostic suites
109+
│ ├── smoke/ shortest runnable configs
110+
│ ├── probes/ single-knob attribution probes
111+
│ │ ├── frequency/ warmup / frequency ablations
112+
│ │ ├── graph_source/ client-state source comparisons
113+
│ │ ├── structure/ topology / relation structure
114+
│ │ └── tau/ tau and filter-strength sweeps
115+
│ ├── stress/ Non-IID stress and collapse checks
116+
│ │ ├── client_count/ scaling num_clients
117+
│ │ └── fedavg_collapse/ FedAvg failure modes
118+
│ └── sweeps/ multi-config sweep grids
119+
│ └── client_count/
120+
└── cora/ Cora / FGL track
121+
└── ablations/
122+
└── graph/ graph construction ablation smoke/full
126123
```
127124

128-
Generated results:
125+
Generated results (gitignored output root, name from `--out-dir` / config):
129126

130127
```text
131-
experiments_current/
128+
<output-dir>/ per-run JSON, suite summaries, plots
132129
```
133130

134131
## Suite Output Artifacts

0 commit comments

Comments
 (0)