Skip to content

Commit 312168b

Browse files
abhiprd2000abhiprd2000
committed
feat: add ROADMAP.md
1 parent 64d34af commit 312168b

2 files changed

Lines changed: 138 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -335,8 +335,10 @@ CNSD is **v1.0.0** and one step from public release. The framework, physics/caus
335335
- [x] Three-dataset cross-domain validation (PU, XJTU-SY, CWRU)
336336
- [x] Pluggable provider registry; dependency-light core
337337
- [ ] Gear-mesh provider (mechanism-agnostic verification)
338-
......and continued
339-
See [`CHANGELOG.md`](CHANGELOG.md) for version history.
338+
339+
......and continued.
340+
341+
See [`ROADMAP.md`](ROADMAP.md) for where CNSD is headed and how to help, and [`CHANGELOG.md`](CHANGELOG.md) for version history.
340342

341343
---
342344

‎ROADMAP.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# 🗺️ CNSD Roadmap
2+
3+
> Where **Causal Neuro-Symbolic Diagnosis** is headed, and where you can jump in.
4+
5+
This roadmap is a living document, not a contract. Priorities shift as the community grows and as evidence comes in — and in the spirit of the project, we'd rather revise a plan honestly than quietly let it rot. If something here is stale, that's a bug: [open an issue](https://github.com/abhiprd2000/CNSD/issues).
6+
7+
---
8+
9+
## How to read this
10+
11+
Work is grouped by **horizon**, following a convention that keeps roadmaps useful to contributors:
12+
13+
- **🔜 Now** — actively in progress, mostly maintainer-led. Getting us to the public release.
14+
- **🙌 Next** — *not currently being worked on, and ready for you to pick up.* This is the section for new contributors.
15+
- **🔭 Later** — direction and vision. Bigger ideas that need design before code.
16+
17+
Tasks in **Next** carry a difficulty signal:
18+
19+
| Label | Meaning |
20+
|-------|---------|
21+
| 🟢 **good first issue** | Self-contained, well-scoped, no deep context needed. A great first PR. |
22+
| 🟡 **help wanted** | Substantial and valuable; some familiarity with the relevant layer helps. |
23+
| 🔴 **needs design** | Worth doing, but let's agree on the approach in an issue before coding. |
24+
25+
> 💡 Many **Next** items are things we'd happily accept *now* if someone wrote them. If an item excites you, comment on (or open) the matching issue and claim it — see [How to get involved](#-how-to-get-involved).
26+
27+
---
28+
29+
## ✅ Where we are now
30+
31+
The core is built, tested, and validated. In place today:
32+
33+
- The full **five-layer pipeline** — perception → symbolic → causal → counterfactual → consensus — with a physics veto.
34+
- **Physics verification** with a three-valued verdict, harmonic prominence, and adaptive tolerance.
35+
- **Causal layer**: Pearl Rung-2 `do(Z)` intervention, CATE, cross-load invariance, and a DoWhy refutation suite.
36+
- **Counterfactual layer**: Pearl Rung-3 on an invertible SCM, with a sensitivity-analysis fallback.
37+
- **Cross-domain validation** on three bearing datasets (PU, XJTU-SY, CWRU) — see [`EXPERIMENTS.md`](EXPERIMENTS.md).
38+
- A **pluggable provider registry**, a **dependency-light core**, CI (ruff + pytest), and a full set of community files.
39+
40+
See the [README status board](README.md#-project-status--roadmap) for the checklist view.
41+
42+
---
43+
44+
## 🔜 Now
45+
46+
47+
## 🙌 Next — where you can help
48+
49+
**This is the heart of the roadmap.** Each item below is real, scoped, and *not* currently being worked on. Pick one, claim it in an issue, and go. "Where to start" points you at the code.
50+
51+
### 🔬 Physics & new machinery
52+
53+
| Task | Why it matters | Label | Where to start |
54+
|------|----------------|-------|----------------|
55+
| **Gear-mesh physics provider** | The provider registry is built and `gear` is a stub; a real gear provider (mesh frequency, sidebands, hunting tooth) is the single biggest step toward a mechanism-agnostic verifier. The SEU gearbox failure in [`EXPERIMENTS.md`](EXPERIMENTS.md) documents exactly why it's needed. | 🔴 needs design | `cnsd/physics/gear.py`, `cnsd/physics/providers/gear.py` |
56+
| **New dataset loaders** (MFPT, IMS, JNU, …) | The universal dataset contract means a new dataset is a small, self-contained loader — perfect first contribution, and each one strengthens the evidence base. | 🟢 good first issue | `cnsd/datasets/contract.py`, `cnsd/datasets/xjtusy.py` (reference) |
57+
| **Improve the spectral fallback** | The zero-knowledge `spectral` provider diagnoses when geometry is unknown. Better peak-picking / cepstral cues would raise its recall. | 🟡 help wanted | `cnsd/physics/providers/spectral.py` |
58+
| **Shaft/imbalance/misalignment families** | Order-domain signatures (1×, 2×, 3× shaft) would extend verification beyond bearing faults on the same signal. | 🔴 needs design | `cnsd/physics/`, provider registry |
59+
60+
### 🎯 Causal & counterfactual
61+
62+
| Task | Why it matters | Label | Where to start |
63+
|------|----------------|-------|----------------|
64+
| **Additional refuters** | More DoWhy refuters (bootstrap, unobserved-common-cause sensitivity) make the Rung-2 warrant harder to fool. | 🟡 help wanted | `cnsd/causal/refutation.py` |
65+
| **Counterfactual outcome choices** | The Rung-3 outcome is vibration RMS; adding other model-independent severity measures (kurtosis, crest factor) as configurable outcomes would broaden the stability check. | 🟢 good first issue | `cnsd/counterfactual/rung3.py` |
66+
67+
### 🛠️ Developer experience & software
68+
69+
| Task | Why it matters | Label | Where to start |
70+
|------|----------------|-------|----------------|
71+
| **`cnsd` CLI** | A `cnsd diagnose <data>` command would let non-Python users run the pipeline from a terminal. | 🟡 help wanted | new `cnsd/cli.py`, wraps `cnsd/api.py` |
72+
| **Visualization helpers** | A `cnsd.viz` module to plot the envelope spectrum with the characteristic-frequency comb and verdict overlay — great for reports and notebooks. | 🟢 good first issue | new module; `cnsd/physics/bearing.py` for the spectrum |
73+
| **Config schema validation** | Validate `cnsd_config.yaml` against a schema with friendly error messages. | 🟢 good first issue | `cnsd/config.py` |
74+
| **Expand the test suite** | More coverage on the physics and causal logic (which run without heavy deps) — always welcome. | 🟢 good first issue | `test/test_layers.py` |
75+
76+
### 📚 Documentation
77+
78+
| Task | Why it matters | Label | Where to start |
79+
|------|----------------|-------|----------------|
80+
| **Worked example notebooks** | End-to-end notebooks on a public dataset are often a contributor's first experience of the project. | 🟢 good first issue | `examples/` |
81+
| **API reference site** | A small docs site (mkdocs / Sphinx) generated from docstrings. | 🟡 help wanted | `docs/` |
82+
| **Tutorials for each layer** | Short guides: "reading a verdict", "interpreting a counterfactual". | 🟢 good first issue | `docs/` |
83+
84+
---
85+
86+
## 🔭 Later — vision & research
87+
88+
Bigger directions that shape where CNSD goes. These need discussion and design before implementation; issues tagged `discussion` are the place for that.
89+
90+
- **A mechanism-agnostic verifier.** Bearings, gears, and shafts under one verification interface, so CNSD checks any rotating-machinery diagnosis against the right physics automatically.
91+
- **Physics-informed self-supervised perception.** A JEPA-style backbone that bakes characteristic-frequency structure into the learned representation, tightening the loop between perception and verification.
92+
- **Online / streaming diagnosis.** Windowed, real-time verification for condition-monitoring deployments rather than batch evaluation.
93+
- **Calibration-aware consensus.** Fuse the physics verdict with *calibrated* uncertainty, not raw softmax, and study how the veto threshold should adapt.
94+
- **Multi-component machines.** Diagnose and verify combined bearing + gear signatures in a single drivetrain signal.
95+
96+
If you're doing research adjacent to any of these, we'd love to collaborate — open a `discussion` issue.
97+
98+
---
99+
100+
## 🧭 Non-goals (for now)
101+
102+
Being clear about scope keeps the project honest and focused:
103+
104+
- **CNSD is not a new classifier.** The perception layer is deliberately a standard CNN; the contribution is verification, not peak accuracy. PRs that swap in a fancier backbone for its own sake are out of scope.
105+
- **CNSD does not claim domain adaptation.** It does not adapt the network or repair the raw signal under shift — it flags which predictions to trust. Framing that blurs this line will be sent back.
106+
- **No fabricated or cherry-picked results, ever.** See the integrity norms below.
107+
- **Non-rotating machinery** (e.g. reciprocating, structural) is out of current scope.
108+
109+
---
110+
111+
## 🤝 How to get involved
112+
113+
New here? Welcome — we're glad you found the project.
114+
115+
1. **Find something.** Browse **🙌 Next** above, or the [issue tracker](https://github.com/abhiprd2000/CNSD/issues) filtered by `good first issue` / `help wanted`.
116+
2. **Claim it.** Comment on the issue (or open one if it doesn't exist yet) describing what you plan to do. This avoids two people building the same thing.
117+
3. **Build it.** Read [`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow. In short: fork → branch → `ruff check . && ruff format .` and `pytest test/` → PR with a clear description → green CI.
118+
4. **Ask.** Stuck or unsure if an idea fits? Open a `discussion` issue. Half-formed questions are welcome; that's how scope gets refined in the open.
119+
120+
### The one rule that never bends: integrity
121+
122+
CNSD is a scientific tool, and its credibility is the whole point. Contributions are expected to uphold the project's core discipline:
123+
124+
- **Honest results.** Null, weak, and unflattering results are reported alongside the good ones — the CWRU null in [`EXPERIMENTS.md`](EXPERIMENTS.md) is a feature, not something to hide.
125+
- **Real artifacts.** Benchmark numbers come from the run scripts, not hand-transcribed tables.
126+
- **No overclaiming.** Say what the evidence supports, and no more.
127+
128+
If a change trades honesty for a better-looking number, it will not be merged — no matter how good the number looks.
129+
130+
---
131+
132+
<div align="center">
133+
<sub>Have an idea that isn't here? <a href="https://github.com/abhiprd2000/CNSD/issues">Open an issue</a> — the roadmap grows with its community.</sub>
134+
</div>

0 commit comments

Comments
 (0)