Modelling with an LLM

The modelling guide

llms-full.txt is everything a model needs to write Python for the kernel, in one self-contained Markdown file of about 130 KB — some 33,000 tokens, well inside what current models read at once:

Nothing in it is written by hand twice. It is generated with these pages, from the same descriptions and from the Python wrapper's own source, so a name the wrapper does not have cannot appear in it; every example in it is a program the site's checks run. llms.txt beside it is the short index, in the llms.txt convention, for tools that look for one.

Each release also attaches the guide for that version to the SDK release, as cadaclysm-llm-guide.md, and the SDK repository carries it as LLM-GUIDE.md. Use that copy when you work against a pinned version; the site's copy follows the latest.

Give it to the model

Download the file and attach it to the chat, or add it to wherever your assistant keeps standing material, so that every conversation starts with it: a project's files in ChatGPT or Claude, a custom GPT's knowledge, a Gem's knowledge in Gemini. A model that can browse can also be pointed at the URL, but an attached file is read whole, which is what the reference needs. Then start with a prompt such as:

You are an expert with cadaclysm's blacksmith, an exact B-rep CAD kernel. The
attached file, llms-full.txt, is its guide and Python API reference: treat it as the source
of truth, and use only the classes, methods and arguments it lists.

I will ask you all kinds of things about my designs and how to make them. Answer as an
experienced CAD engineer would. When you write code, make it complete and runnable, and
tell me what you assumed.

It sets a role and a reference, not a task: from there, ask what you would ask a colleague who knows the kernel well. For instance:

• A phone stand bent from 3 mm sheet: the back leaning at 70 degrees, a lip for the phone, a slot for the cable.
• Take the bracket from before: make it 5 mm thick and add a gusset in the bend.
• Machine it from a 100 x 60 x 20 aluminium block. I have a 6 mm and a 3 mm end mill.
• Why does my fillet fail with "the rim's rounding runs off its face"?
• What is the best way to model a spring with flat ground ends: coil, sweep or loft?
• Review this script and make it easier to change.

For a part, name the dimensions that matter and let the model choose the rest. If you always work a certain way, say so once in the prompt:

• I run your scripts in the browser notebook: end each on the finished solid, and don't use Job.machine. — when you work in the Python notebook, which draws the solid on the last line and does not have Job.machine yet.
• Work in inches and write the STEP file with unit="in"; for machining, convert to mm, which the CAM calls use. — when your drawings are in inches.
• My machine is a <describe it: work area, spindle, the tools you own>. Use only those tools and stay inside its limits. — when you will run the G-code, so the model picks tools you have and speeds your machine can reach.
• Before the script, list the features in the order you will build them. — when the part is complex, since a wrong step is easier to spot in a plan.

The guide's own first example is this request:

A wall bracket: an L of 4 mm plate, 60 mm wide, a 40 mm leg on the floor and a 30 mm leg up the wall, the inside of the bend rounded 3 mm, and two 5 mm holes through each leg.

and the script it answers with:

import math
from cadaclysm_blacksmith import Frame, Profile, Solid

# Dimensions, in mm.
width = 60        # along X
base = 40         # the horizontal leg, along +Y
height = 30       # the upright leg, up +Z
t = 4             # plate thickness
bend = 3          # inside corner radius
hole_r = 2.5      # 5 mm holes

# The L as a side view on the YZ plane (sketch x = world Y, sketch y = world Z), its
# inside corner rounded in the sketch: corner k is where segment k ends, and the
# inside corner is where segment 2, (base, t) -> (t, t), ends.
section = Profile.polygon([(0, 0), (base, 0), (base, t), (t, t), (t, height), (0, height)])
section = section.round(bend, corners=[2])
bracket = Solid.extrude(section, Frame.yz(), width)       # from x = 0 to x = width

# Two holes down through the base, two through the upright (drilled along +Y).
for x in (width / 4, 3 * width / 4):
    down = Solid.cylinder(hole_r, t + 2).translate(x, (base + t) / 2, -1)
    across = Solid.extrude(Profile.circle(hole_r), Frame.at((x, -1, (height + t) / 2), (0, 1, 0)), t + 2)
    bracket = bracket.cut(down).cut(across)

bracket.step("bracket.stp")

Run it, look, ask again

Paste the script into the Python notebook: it runs in the browser over WebAssembly, nothing installed, and draws the solid on the last line. On a machine, pip install cadaclysm and run it with Python; open the STEP it writes in any CAD program.

The model gets simple parts right the first time. For anything more, work the way you would with a colleague at the CAD station:

• Send the error back. A refused step raises BuildError with the kernel's reason (a fillet too large for its faces, a profile that crosses itself). Paste the message; the model fixes that step.
• Describe what looks wrong. "The holes are on the wrong leg", "the boss sinks into the plate": the guide's conventions give the model what it needs to find the cause.
• Build it in steps. For a complex part, ask for the base first, then each feature in turn, checking the picture between them.
• Ask for changes by name. With the dimensions at the top of the script, "make the flange 12 mm thick" is a one-line edit.

Where to go from here

Concepts explains the object model; the Python reference lists every call, reader included; the blacksmith page shows what the kernel does.