FreeCAD-Agent-27B

FreeCAD-Agent-27B is a LoRA adapter for Qwen/Qwen3.8-27B. It turns the base model into an autonomous agent that builds parametric 3D models in FreeCAD.

Given a written description of a part and its key dimensions, the agent works step by step in a shell. It writes a FreeCAD Python script, runs it with freecadcmd, checks the result, fixes errors, and saves a valid .FCStd document. The model is built as an editable PartDesign feature tree (sketches, pads, pockets, fillets and patterns, driven by named parameters), not as a fixed, non-editable shape.

Base model	Qwen/Qwen3.8-27B
Method	QLoRA supervised fine-tuning on agent trajectories
Adapter	LoRA rank 32, alpha 32, on all attention and MLP projections
Formats	PEFT safetensors, plus a llama.cpp LoRA GGUF
Training context	24,576 tokens
Companion dataset	Yas1n/freecad-part-dataset
License	Apache 2.0

Highlights

• Builds models you can edit. Output is a single PartDesign Body with one solid and named, editable features.
• Fixes its own errors. The agent runs its code, reads FreeCAD's output and corrects mistakes before submitting.
• Two ways to work. It can write scripts through a bash agent loop, or call FreeCAD tools directly (sketch, edit and execute).
• Runs on a single GPU. It can be served with llama.cpp on a single 48 GB GPU, using a quantised base model plus the LoRA.

Intended use

• An autonomous text-to-CAD agent inside a sandboxed shell with FreeCAD 1.x installed, such as mini-swe-agent or a similar bash-tool loop.
• A FreeCAD scripting assistant that calls tools to create and edit sketches and features.
• A starting point for research on CAD agents and for further fine-tuning or reinforcement learning.

Out of scope

• Engineering sign-off. Treat generated geometry as a draft and check dimensions, tolerances and manufacturability before use.
• General chat. The adapter is specialised for CAD and may perform worse than the base model on unrelated tasks.
• Running without a sandbox. The agent runs shell commands it writes itself, so always run it in an isolated container.

How to use

llama.cpp (recommended)

Apply the GGUF LoRA on top of a GGUF build of Qwen3.8-27B. Q6_K or higher is recommended.

llama-server \
  --model Qwen3.8-27B-Q6_K.gguf \
  --lora FreeCAD-Agent-27B-lora.gguf \
  --n-gpu-layers 99 --ctx-size 131072 --flash-attn on \
  --jinja --reasoning on

The server exposes an OpenAI-compatible endpoint that any agent harness can use.

Transformers + PEFT

from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

tok = AutoTokenizer.from_pretrained("Yas1n/FreeCAD-Agent-27B")
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3.8-27B", torch_dtype="auto", device_map="auto")
model = PeftModel.from_pretrained(model, "Yas1n/FreeCAD-Agent-27B")

messages = [{"role": "user", "content": (
    "Write a FreeCAD Python script to /app/answer.py that builds a 60 x 40 x 8 mm plate "
    "with four 5 mm corner holes inset 6 mm, as a single PartDesign Body, and saves "
    "/app/answer.FCStd."
)}]
inputs = tok.apply_chat_template(messages, add_generation_prompt=True, return_tensors="pt").to(model.device)
out = model.generate(inputs, max_new_tokens=4096)
print(tok.decode(out[0][inputs.shape[-1]:], skip_special_tokens=True))

To load it in 4-bit, pass BitsAndBytesConfig(load_in_4bit=True), or use Unsloth's FastLanguageModel.from_pretrained(..., load_in_4bit=True).

Tip: The model does best in an agent loop where it runs its own scripts and reads the output. A single generation with no execution feedback is noticeably less reliable.

Training

Data

5,234 multi-turn agent trajectories:

Source	Rows	Description
Scripted CAD trajectories	4,607	Bash-agent trajectories solving procedurally generated mechanical parts: general parts, gears and composite parts. Each trajectory comes from a verified reference solution and covers writing the script, running FreeCAD, checking the result and submitting.
Tool-calling trajectories	627	FreeCAD tool-use sessions (create_sketch, edit_sketch, execute_code, ...) that write a feature plan before building.

Loss is applied only to assistant turns: reasoning, text and tool calls. System prompts, user turns and tool outputs are masked.

Hyperparameters

Framework	Unsloth + TRL SFTTrainer, PEFT
Quantisation	4-bit base (QLoRA), gradient checkpointing
LoRA	r = 32, alpha = 32, dropout = 0, targets q, k, v, o, gate, up, down
Epochs	1
Learning rate	1e-4
Effective batch size	16
Max sequence length	24,576
Hardware	1 × NVIDIA L40S (48 GB), about 11 hours

Evaluation

We compared FreeCAD-Agent-27B with the un-fine-tuned Qwen3.8-27B on a text-to-CAD benchmark. Each task gives a written description of a part and its named key parameters, and the model must build it as a parametric FreeCAD model. Both models ran as agents in the same Docker sandbox with FreeCAD 1.1, with one attempt per task. Each result is scored from 0 to 1 against a reference model, combining geometry similarity with spec compliance (for example: a single PartDesign Body that produces exactly one solid).

Model	Mean score	Tasks failed (score 0)
Qwen3.8-27B (base)	0.416	7 / 13
FreeCAD-Agent-27B	0.534	4 / 13
Change	+28% relative (+0.118)	3 fewer

Most of the gain comes from finishing more tasks. The base model often stopped without producing a saved model, while the fine-tuned agent usually completes the full write, run, check and save loop.

The comparison uses the 13 benchmark tasks where both models have a scored run.

Limitations

• Repair loops. On hard geometry, such as filleted hinge knuckles, the agent can keep patching one feature for many steps. Run it with a step or time limit.
• Incomplete submissions. Most failures are an empty Body after a broken feature, a script that was written but never run, or a Body that produces more than one solid.
• Version sensitivity. Trained and evaluated against FreeCAD 1.1. Older versions (0.21 or earlier) may cause API errors.
• Training distribution. Most training parts are procedurally generated mechanical parts, so organic or freeform shapes are less well covered.
• Code execution. The agent runs shell commands it writes itself. Use it only in an isolated environment.

Related resources

• FreeCAD Part Dataset: 147k FreeCAD parts, each with a FreeCAD script, STEP and STL exports, seven rendered views and metadata. It is a companion dataset for text-to-CAD and CAD-understanding research, and suits further fine-tuning or evaluation of this model.

Citation

@misc{freecad_agent_27b_2026,
  title        = {FreeCAD-Agent-27B: A Fine-Tuned Agent for Parametric FreeCAD Modelling},
  author       = {Syed, Yasin},
  year         = {2026},
  howpublished = {\url{https://huggingface.co/Yas1n/FreeCAD-Agent-27B}}
}

Acknowledgements

Built on Qwen3.8-27B by the Qwen team, and trained with Unsloth and TRL.