docs(site): update to the trained-models + native-MLX reality (follow-up to #15)#16
Merged
Merged
Conversation
The site described several models as "untrained" and omitted the native-MLX work and the now-working valid-CAD generation. Corrected across 14 pages (Astro build passes, all internal links valid): - ll_gen: was badged "Untrained" / "ship untrained" -> now documents the trained program-based generators (autoregressive command model 0.914 valid; latent diffusion 0.934 valid, sampled-z vs z=0 baseline) and the honest solid+volume validity gate; notes the parallel-decoder VAE (~12%) and raw-geometry diffusion (0) are superseded. - ll_stepnet: "Untrained" -> trained classifier (val acc 0.976) + native-MLX parity port. - ll_brepnet: added the parity-verified native-MLX port alongside the 0.828 result. - ll_ocadr: "ships no trained weights" -> documents the trained, geometry-grounded MLX model (0.919 vs 0.313 shuffled); keeps the accurate vLLM-experimental caveat. - index.mdx: removed the false "ll_brepnet is an empty scaffold / Planned" claim (it is trained, mIoU 0.828); added it as a package card; refreshed status + ll_gen card. - get-started (installation + quickstart): added the native-MLX (Apple Silicon) path and corrected the "no trained checkpoints" note. - concepts (index / the-reality / inside-models): distinguish field-literature numbers from the toolkit's own measured results; add the program-vs-geometry validity lesson. - tutorials (generate-cad / ocadr-hf-inference): point to the trained MLX generators. Untouched: cadling / geotoken / ll_clouds and auto-generated API references — accurate as-is; no fabricated changes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…nav) Reviewed the docs not touched in the previous pass. Updated the four with genuine staleness; left the utility-package docs (cadling/geotoken/ll_clouds), guides, contributing, and auto-generated API references unchanged (accurate as-is — verified by grep for untrained/scaffold/proof-of-life/package-count claims): - roadmap/ll_brepnet.md: note the parity-verified native-MLX port runs the trained GNN on Apple Silicon. - concepts/how-neural-cad-generation-works.md: add a labeled "measured in this toolkit" note — independent-face B-Rep diffusion scores 0 valid, while the program-latent + autoregressive decode route reaches 0.934 / 0.914 through the real kernel. - contributing/docs-site.md: roadmap/ comment no longer calls ll_brepnet "not-yet-built". - tutorials/index.md: Generate-CAD row now says "train generators that produce valid CAD" instead of "a proof-of-life model". Astro build passes (46 pages, all internal links valid). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Reviewer's GuideUpdates the docs site to accurately reflect the newly trained, native-MLX models and honest validity metrics added in #15, especially around ll_gen’s program-based generators, ll_stepnet, ll_brepnet, and ll_ocadr, and clarifies which paths are trained vs experimental across concepts, tutorials, and getting-started pages. Flow diagram for ll_gen program-based valid CAD generationflowchart LR
Prompt["Prompt"] --> ARGen["ar_generator_mlx.py --mode train"]
Prompt --> LatentDiff["latent_diffusion_mlx.py --mode train"]
ARGen --> Prog["Construction_program"]
LatentDiff --> Prog
Prog --> Kernel["OCC / CadQuery sandbox"]
Kernel --> Solid["Non_degenerate_solid"]
Solid --> Metrics["GenerationMetrics.is_valid_solid"]
Metrics --> Validity["Validity 0.914 / 0.934 + num_distinct"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- There’s a lot of repeated MLX command snippets and metric descriptions (e.g. AR 0.914 / latent 0.934, brepnet parity commands) across overview, usage, tutorials, and concepts; consider centralizing these into a shared partial or a single canonical section and linking to it to reduce future drift when numbers or CLIs change.
- Some status/badge text and prose use slightly different terminology for the same concepts (e.g. “validity 0.914”, “0.914 valid”, “measured-valid CAD”, “non-degenerate solids”); standardizing phrasing and metric labels across pages would make it easier for users to compare models and avoid confusion.
- Several pages now make strong, time-sensitive claims like “ships trained generators” and “recently shipped”; consider adding brief scope qualifiers or version anchors (e.g. ‘as of vX.Y’ or ‘DeepCAD-trained’) so that as models evolve those statements remain accurate or clearly historical.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- There’s a lot of repeated MLX command snippets and metric descriptions (e.g. AR 0.914 / latent 0.934, brepnet parity commands) across overview, usage, tutorials, and concepts; consider centralizing these into a shared partial or a single canonical section and linking to it to reduce future drift when numbers or CLIs change.
- Some status/badge text and prose use slightly different terminology for the same concepts (e.g. “validity 0.914”, “0.914 valid”, “measured-valid CAD”, “non-degenerate solids”); standardizing phrasing and metric labels across pages would make it easier for users to compare models and avoid confusion.
- Several pages now make strong, time-sensitive claims like “ships trained generators” and “recently shipped”; consider adding brief scope qualifiers or version anchors (e.g. ‘as of vX.Y’ or ‘DeepCAD-trained’) so that as models evolve those statements remain accurate or clearly historical.
## Individual Comments
### Comment 1
<location path="site/src/content/docs/ll_gen/usage.md" line_range="80" />
<code_context>
+python ll_gen/mlx/latent_diffusion_mlx.py --mode train
+```
+
+For the latent diffusion the headline metric is **sampled-z** validity
+(noise → denoise → decode → execute), reported against a `z=0` predict-the-mean
+baseline so a diverse generator is distinguishable from one that repeats the mean shape.
</code_context>
<issue_to_address>
**suggestion (typo):** Consider adding a comma after "latent diffusion" for correctness and readability.
Rephrasing to “For the latent diffusion, the headline metric is…” would better follow standard grammar for introductory clauses.
```suggestion
For the latent diffusion, the headline metric is **sampled-z** validity
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| python ll_gen/mlx/latent_diffusion_mlx.py --mode train | ||
| ``` | ||
|
|
||
| For the latent diffusion the headline metric is **sampled-z** validity |
Contributor
There was a problem hiding this comment.
suggestion (typo): Consider adding a comma after "latent diffusion" for correctness and readability.
Rephrasing to “For the latent diffusion, the headline metric is…” would better follow standard grammar for introductory clauses.
Suggested change
| For the latent diffusion the headline metric is **sampled-z** validity | |
| For the latent diffusion, the headline metric is **sampled-z** validity |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #15 (merged). The model work from #15 (native-MLX faithful ports, the
autoregressive + latent-diffusion CAD generators, the honest validity metric) landed in
main, but the docs site was not updated in that PR. This brings the site in linewith what the code now does — 18 pages, build-verified.
What changed (the site told a stale story)
program-based generators (AR 0.914 valid, latent diffusion 0.934 valid,
sampled-z vs z=0 baseline), the honest solid+volume validity gate, and that the
parallel-decoder VAE (~12%) and raw-geometry diffusion (0 valid) are superseded.
parity port.
(0.919 vs 0.313 shuffled); kept the accurate vLLM-experimental caveat.
claim (it's trained, mIoU 0.828); added it as a package card; refreshed status.
path; corrected the "no trained checkpoints" note.
field-literature numbers from the toolkit's own measured results; added the
program-vs-geometry validity lesson (independent-face diffusion → 0; program latent →
0.934).
contributing — point to the trained MLX generators; drop "not-yet-built"/
"proof-of-life" language.
Untouched (verified accurate as-is): cadling / geotoken / ll_clouds, guides, and the
auto-generated API references — no fabricated changes.
Astro build passes: 46 pages, all internal links valid.
🤖 Generated with Claude Code
Summary by Sourcery
Update the docs site to reflect newly trained, MLX-native CAD models and honest validity metrics across packages.
New Features:
Enhancements: