README.md

---
base_model: Qwen/Qwen2.5-0.5B
library_name: transformers
tags:
- robotics
- cnc
- gcode
- spatial-reasoning
- qwen
datasets:
- vanishingradient/Instruct2GCode-Synthetic-Dataset
license: mit
---

# 🤖 Instruct2GCode: Spatial Chain-of-Thought for CNC Machining

## 📝 Model Overview
**Instruct2GCode** is an experimental Small Language Model (SLM) fine-tuned to translate natural language instructions directly into deterministic, mathematically precise CNC milling G-Code. 

Traditional LLMs hallucinate continuous physical dimensions. This model utilizes **Spatial Chain-of-Thought (S-CoT)** anchoring—forcing the attention mechanism to first predict a geometric bounding box and Cartesian waypoints before emitting the actual G-Code sequence.

- **Base Model:** `Qwen/Qwen2.5-0.5B`
- **Training Paradigm:** 4-bit QLoRA using synthetic S-CoT pairs
- **Language:** English / G-Code (RS-274)
- **License:** MIT

## 💻 How to Use

To utilize the Spatial-CoT mechanism, you must allow the model to generate the intermediate `<SPATIAL_REASONING>` block prior to printing the code.

```python
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_id = "vanishingradient/Instruct2GCode-Qwen2.5"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float16, device_map="auto")

prompt = "Write CNC G-code to mill a rectangle with width 150mm and height 80mm starting at X=25, Y=25. Use a feed rate of 350 mm/min."

# Instruct2GCode is trained on ChatML conversation formats
text = f"<|im_start|>user\n{prompt}<|im_end|>\n<|im_start|>assistant\n"
inputs = tokenizer(text, return_tensors="pt").to(model.device)

outputs = model.generate(**inputs, max_new_tokens=300, temperature=0.1, do_sample=False)
print(tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True))
```
```
<SPATIAL_REASONING>
Bounds: X[25 to 175], Y[25 to 105]
Key Waypoints: [[25, 25], [175, 25], [175, 105], [25, 105], [25, 25]]
</SPATIAL_REASONING>
```gcode
G21 ; Set units to metric
G90 ; Absolute positioning
G0 Z5 ; Safe Z height
G0 X25 Y25 ; Move to start
...
M30 ; End program
```

## ⚠️ Limitations & Safety
- **Experimental Only:** This model generates physical toolpaths. If executed on a real CNC machine without simulation routing, it **may crash your spindle** or cause hardware damage. 
- **Domain Constraint:** Currently restricted to continuous 2D planar milling (Rectangles, Circles). Does not support complex 3D adaptive clearing or G-code specific to 3D printing (Slicing logic).
- Always verify outputs using a visual G-Code parser prior to execution.