anteloc / ldraw-nova

# ldraw-nova
Build LEGO models with an AI agent, ordinary JSON plans and LDraw parts. The tools find parts and reference constructions, generate editable MPDs, check geometry, render previews and compare parts lists. Python generators support larger procedural designs.
Watch the demonstration · Project background
## Start locally
You need Python 3.12+, an installed LDraw parts library, Poppler (`pdftotext`) and LeoCAD on `PATH`. The repository includes the reference data and connector metadata used by the tools.
 [code] 
Open the PNGs in `output/bridge-review/previews/`. The same folder contains the model, validation report, Python BOM, LeoCAD BOM comparison and a manifest tying artifacts to the model revision. `review --no-render` runs intermediate Python checks when previews are not needed. `./ldraw-agent doctor` reports local dependencies.
## Build your own model
Give an agent your model idea and instructions.md. The working loop is:
1. Choose a design and inspect the parts or example constructions it needs.
2. Write a JSON plan; use Python when calculations or loops help.
3. Run `review`, open the previews, repair the source and repeat.
4. Deliver the editable MPD, source, checks and reviewed images.
 [code] 
`build` infers `output/my-model.mpd` and writes only after source/geometry checks pass. You can also run `review output/my-model.plan.json` to build and review in one command. Use `--force` for a deliberate rebuild or replacement of a generated review. Keep editable source and visual-review notes outside the generated review directory.
Existing JSON plans, `build --output`, individual check/render commands and shell wrappers remain supported. Successful checks provide evidence, not proof of physical buildability; warnings, skipped checks and required visual inspection stay explicit.
| Need | Read |
|---|---|
| Agent workflow and subject-specific guides | Instructions |
| Plan format, placements and Python API | Plan guide |
| Commands, review options and artifacts | Tool reference |
| Geometry checks and limitations | Validation |
| Reusable constructions and model examples | Reference atlas, `./ldraw-agent examples --help` |
Semantic reference search uses jev-rerank and a TypeSafe API key. It is optional: offline catalogs, examples and `discover search ... --engine fts` remain available. Follow the availability check before using the service.
## Run the web app
The web app and Docker configuration live in the sibling ldraw-nova-docker repository. Install Git and Docker, then clone matching release tags side by side:
 [code] 
The first build needs about 5 GB of disk space. Open **http://localhost:8765**, or **https://localhost:8443** for VR on Meta Quest 3 (accept the self-signed certificate). Devices on your network can use the host computer's IP address. The app has no login; run it on a trusted network. Set `TYPESAFE_API_KEY` in the app's Settings for semantic search. Stop it with `docker compose down`.
The web app provides interactiv