CadQuery Agent
Du texte ou d’une image à un modèle 3D éditable, en local
Décrivez une pièce en mots ou en image et obtenez un modèle 3D éditable.
Construit avec
Python
FastAPICadQuery
Ollama
Docker
Three.js
PodmanQwen2.5-Coder / Qwen2.5-VL
pytest
Présentation
Les outils de texte-vers-CAO vous livrent généralement un maillage impossible à modifier, et ils envoient souvent vos prompts et vos images à un modèle hébergé. Je voulais autre chose : un outil qui écrit du vrai code Python CadQuery, pour que chaque dimension reste éditable, et qui tourne entièrement sur ma propre machine avec un modèle à poids ouverts.
J’ai construit CadQuery Studio, un harnais local qui transforme une description textuelle, une image de référence ou les deux en code source CadQuery, en aperçu 3D interactif et en fichiers STL/STEP. Il ne dialogue qu’avec un serveur de modèle sur l’interface loopback (Ollama ou un serveur vLLM local) ; les URL de points d’accès distants ou hébergés sont rejetées.
La difficulté, c’est que le modèle écrit du code qui est ensuite exécuté. Chaque script passe d’abord par des vérifications statiques, puis s’exécute dans un conteneur sans réseau, en lecture seule et aux ressources limitées. La géométrie générée doit encore être relue par un humain avant fabrication, mais comme la sortie est du simple Python et du STEP, une dimension erronée se corrige en une ligne au lieu d’exiger une régénération complète.
La question
Un petit modèle local peut-il générer des programmes CAO utiles et éditables, tout en gardant le code généré isolé, vérifiable et sûr à exécuter ?
Fonctionnalités clés
- Accepte un prompt textuel, une image de référence PNG/JPEG/WebP accompagnée de texte, ou les deux, via un point d’accès de chat local compatible avec l’API OpenAI.
- Vérifie statiquement chaque script généré avant exécution, en bloquant les imports autres que CadQuery, l’accès aux fichiers et au réseau, ainsi que l’exécution dynamique de code.
- Exécute le code dans un worker Docker ou Podman rootless sans réseau, avec un système de fichiers en lecture seule, des capabilities Linux retirées et des limites de CPU, de mémoire, de processus et de temps.
- Affiche un aperçu Three.js interactif à côté du code source Python complet et éditable, avec téléchargement STL et STEP.
- Conserve chaque projet sous forme de révisions immuables, de sorte qu’un objet peut être construit prompt après prompt et que toute révision antérieure peut servir de base à une nouvelle branche.
- Demande automatiquement au modèle de réparer certaines erreurs d’exécution CadQuery, et une étape en échec n’écrase jamais la dernière révision fonctionnelle.
Comment ça marche
Interroger le modèle local
Le texte et l’image optionnelle sont envoyés à un modèle à poids ouverts (par exemple qwen2.5-coder ou qwen2.5vl) servi sur localhost, avec pour consigne de ne renvoyer que du Python CadQuery qui affecte son objet final à result.
Vérifications statiques
Le code renvoyé est analysé avec le module ast de Python et rejeté s’il importe autre chose que cadquery ou numpy, s’il appelle eval/exec/open ou s’il ne construit jamais de cq.Workplane. Les erreurs sont renvoyées au modèle, jusqu’à trois tentatives.
Rendu isolé
Un conteneur worker CadQuery/OpenCascade exécute le script validé sans réseau et avec des limites de ressources strictes, puis exporte la géométrie.
Aperçu et révision
Le navigateur affiche le modèle 3D et son code source ; les modifications en langage naturel (Add part, Change, Remove part, Enhance) ou les éditions directes du code deviennent de nouvelles révisions vérifiées.
Exemples
Entrée
Model output: import os result = os.getcwd()
Sortie
Rejected before execution: "import is not allowed: os" and "code must construct geometry with cq.Workplane(...)". The errors are appended to the prompt and the model is asked for a corrected script.
Entrée
1. Create a 100 x 60 x 8 mm mounting plate. 2. Add four 6 mm holes, each 10 mm from the nearest corner. 3. Add a centered 24 mm diameter boss, 12 mm tall. 4. Cut an 8 mm through-hole through the boss and plate. 5. Add 3 mm fillets to the outside vertical edges.
Sortie
Five saved revisions, one per prompt, each with its own editable CadQuery source, 3D preview, and STL/STEP export. Selecting an earlier revision before the next prompt starts a new branch.
Stack technique
Agent, validation et logique de projet
API HTTP locale et backend du studio web
Code CAO paramétrique éditable et exports
Sert les modèles à poids ouverts sur loopback
Worker de rendu CAO isolé et sans réseau
Aperçu 3D interactif dans le navigateur
Alternative rootless pour le worker
Modèles locaux texte et vision recommandés
Tests contre un point d’accès local simulé
Ce que j’ai appris
- Le code généré exige des vérifications statiques explicites et une isolation à l’exécution avant d’être lancé
- Un code source éditable et des exports CAO standard rendent les erreurs du modèle corrigeables plutôt qu’opaques
Limites
- Les intentions mécaniques complexes et les dimensions déduites d’images nécessitent encore une relecture humaine