feat: add dataset query and clustering wrappers

[cristianvogel]

Why this PR

This PR adds the dataset-oriented search, query, clustering, and projection tools that fit together as one reviewable group.

What changed

• add safe Rust wrappers for:
  • KDTree
  • DataSetQuery
  • Grid
  • KMeans
  • SKMeans
  • Mds
• expose the relevant types through the public crate API
• add the minimal flucoma-sys bindings required for these algorithms
• include unit tests for the added wrapper surface

Merge

I did go through, rebase and merge with upstream

Intentionally not included

• no docs
• no STATUS changes
• no examples

Validation

• cargo clippy --lib
• cargo test --lib

[cristianvogel]

I refreshed after the merge of #10 and rebased onto current master.

Now keeps the upstream stats layer from #10 (BufStats, MultiStats, RunningStats) and only adds the dataset/query/clustering pieces from this PR:

• DataSetQuery
• Grid
• KDTree
• KMeans
• SKMeans
• Mds

The only shared touch-points are src/lib.rs and flucoma-sys/src/lib.rs, where the branch now merges the upstream stats exports/bindings with the new query/clustering bindings.

checks

• cargo clippy --lib
• cargo test --lib

[emuell]

Docs are missing here, else this looks good to me.

This is in detail hard to test and verify though, so I'm wondering if adding a somewhat practical CLI too here makes sense here too, to show how all this dataset stuff can be used - in practice.

Any idea how such a CLI tool could look like?

[cristianvogel]

Docs are missing here, else this looks good to me.

This is in detail hard to test and verify though, so I'm wondering if adding a somewhat practical CLI too here makes sense here too, to show how all this dataset stuff can be used - in practice.

Any idea how such a CLI tool could look like?

agreed. I had written something, and even made an interactive demo to show the clustering.

https://script.google.com/macros/s/AKfycbzOR8otksbdEl0Lg5uqDEIiuX_k8NHQlr0LqQWQtOI/dev

I was using Grid and Scalars in my Incline app, to great effect.

[cristianvogel]

added doc comments for
dataset_query.rs
grid.rs
kdtree.rs
kmeans.rs
mds.rs

[emuell]

Please tell codex to use one of the existing wrapped structs as template for the documentation style. For example this one: https://github.com/emuell/flucoma-rs/blob/master/src/pca.rs

[cristianvogel]

Ok I'll ask but I can't guarantee it'll do what I ask :/

Otherwise I can do it manually , but it will be a bit of a chore

[cristianvogel]

I see what upstream means. The gap isn’t just “missing docs,” it’s that these wrappers still read like short notes instead of the fuller pca.rs template: summary, behavior paragraph, optional workflow notes, usage example, and reference link. I’m reshaping the main struct docs in that style now.

…

On 15 Mar 2026, at 17.12, emuell ***@***.***> wrote: emuell left a comment (emuell/flucoma-rs#11) <#11 (comment)> Please tell codex to use one of the existing wrapped structs as template for the documentation style. For example this one: https://github.com/emuell/flucoma-rs/blob/master/src/pca.rs — Reply to this email directly, view it on GitHub <#11 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADB4C6WP2OBINRL7X6DH7QL4Q3I6NAVCNFSM6AAAAACWQ2W3PSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DANRTGMYDIMJUGE>. You are receiving this because you authored the thread.

[Cristian-Vogel]

main struct doc comments done, ready to merge

[emuell]

I'll fix them in a second pass. It would be great to work on some more practical tests (CLI example, as discussed before) to verify all the existing new stuff before adding more wrappers. Most of the new wrappers are pretty thin, but I haven't tested them in detail yet.

[Cristian-Vogel]

are they still not right?

…

On 16 Mar 2026, at 08.57, emuell ***@***.***> wrote: emuell left a comment (emuell/flucoma-rs#11) <#11 (comment)> I'll fix them in a second pass. It would be great to work on some more practical tests (CLI example, as discussed before) to verify all the existing new stuff before adding more wrappers. Most of the new wrappers are pretty thin, but I haven't tested them in detail yet. — Reply to this email directly, view it on GitHub <#11 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BYFIJ6KOVTNKMJLZAXX6LF34Q6XVZAVCNFSM6AAAAACWQ2W3PSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DANRVG43DKNBSGM>. You are receiving this because you commented.