What Is the Role of the cadpy Package in text-to-cad?

The cadpy package functions as the core Python CAD toolkit within the text-to-cad ecosystem, providing STEP file parsing, GLB generation, multi-part assembly composition, and metadata tracking to transform textual specifications into production-ready geometric artifacts.

Within the earthtojake/text-to-cad repository, the cadpy package serves as the foundational layer for all computer-aided design operations. This self-contained library isolates CAD processing logic from higher-level skill implementations, ensuring consistent geometry handling across the pipeline. Understanding the role of the cadpy package in text-to-cad is essential for developers extending the system's modeling capabilities or integrating new export formats.

Core CAD Processing Capabilities

The cadpy package delivers a dependency-light, pure-Python interface for CAD manipulation. Beyond STEP and GLB handling, it provides thin wrappers for 3MF, STL, and other mesh formats while maintaining a lightweight footprint free of heavy external CAD kernels. It handles the entire lifecycle of geometric data from ingestion to final export.

STEP File Parsing and Geometry Extraction

At the heart of cadpy lies the ability to read and interpret STEP files (ISO 10303), the industry standard for CAD data exchange. The load_step() function in packages/cadpy/src/cadpy/api.py ingests STEP archives and extracts topology, geometry, and metadata into native Python objects. This capability enables downstream agents to analyze model structure without relying on heavy external CAD kernels.

GLB Generation and Web Viewer Export

To support web-based visualization, cadpy converts STEP geometry into GLB (glTF Binary) format. The export_glb() method and the low-level glb_from_step() function in packages/cadpy/src/cadpy/glb.py handle mesh optimization and binary serialization. This ensures that models produced by the text-to-cad pipeline render efficiently in the viewer component, bridging the gap between engineering data and web graphics.

Multi-Part Assembly Management

Complex mechanical designs require compositional logic. The Assembly class in packages/cadpy/src/cadpy/assembly.py provides utilities for combining multiple STEP parts into coherent scenes. It supports URDF and SRDF joint definitions, allowing agents to specify parent-child relationships and kinematic chains. The assemble() workflow logically groups components while maintaining individual part identities for downstream manufacturing steps.

Metadata Provenance and Change Tracking

Reproducibility demands rigorous data lineage. The generate_metadata() function in packages/cadpy/src/cadpy/metadata.py computes cryptographic hashes, timestamps, and source provenance for every model. This metadata layer enables change-tracking across iterations and ensures that generated artifacts carry embedded documentation about their origin and transformation history.

Key Source Files in the cadpy Architecture

The package structure under packages/cadpy/src/cadpy/ organizes functionality into discrete, single-responsibility modules. The package is deliberately independent of other skill code and is vendored into runtime bundles for the viewer and plugin components, ensuring a single source of truth for CAD processing across the repository.

• api.py (packages/cadpy/src/cadpy/api.py): Exposes the high-level façade including load_step(), export_glb(), and assemble() for skill script consumption.

• step_export.py (packages/cadpy/src/cadpy/step_export.py): Contains logic for transforming STEP geometry into intermediate mesh formats and preparing data for GLB serialization.

• glb.py (packages/cadpy/src/cadpy/glb.py): Implements low-level GLB construction, binary buffer management, and topology optimization for web delivery.

• assembly.py (packages/cadpy/src/cadpy/assembly.py): Defines the Assembly class and joint definition utilities for multi-part model composition.

• metadata.py (packages/cadpy/src/cadpy/metadata.py): Provides hashing algorithms, UUID generation, and provenance reporting structures.

• README.md (packages/cadpy/README.md): Documents installation procedures, design goals, and package boundaries for contributors.

Working with cadpy: Practical Examples

The following patterns demonstrate how skills and agents interact with cadpy to process CAD data.

Loading and Inspecting STEP Metadata

from cadpy.api import load_step

step_model = load_step("models/example_robot/robot.step")
print(step_model.metadata)          # → dictionary with author, UUID, timestamps

print(step_model.topology)          # → topology object for further queries

This snippet utilizes load_step() to ingest a robot model and access its metadata dictionary, providing immediate visibility into file provenance.

Composing Multi-Part Assemblies

from cadpy.assembly import Assembly
from cadpy.api import load_step

assembly = Assembly()
assembly.add_part(load_step("models/arm/shoulder.step"))
assembly.add_part(load_step("models/arm/elbow.step"))
assembly.define_joint("shoulder_elbow", parent="shoulder", child="elbow")
assembly.export_glb("output/robot.glb")   # produces a GLB ready for the viewer

Here, the Assembly class aggregates individual STEP components and defines kinematic relationships before exporting a unified GLB file.

Generating GLB with Embedded Metadata

from cadpy.glb import glb_from_step
from cadpy.metadata import generate_metadata

metadata = generate_metadata(source_path="models/wheel.step")
glb_bytes = glb_from_step("models/wheel.step", metadata=metadata)

with open("wheel.glb", "wb") as f:
    f.write(glb_bytes)

This example demonstrates the generate_metadata() and glb_from_step() pipeline, ensuring the output binary carries complete provenance information.

Summary

• The cadpy package provides the foundational CAD processing layer for the earthtojake/text-to-cad repository, isolating geometry operations from skill logic.
• It handles STEP file parsing, GLB export, multi-part assembly, and metadata tracking through a pure-Python API.
• Key entry points include load_step() for ingestion, the Assembly class for composition, and export_glb() for web-ready output.
• Source files are organized under packages/cadpy/src/cadpy/, with api.py, assembly.py, glb.py, and metadata.py serving as the primary modules.
• The package is designed to be vendored into runtime bundles, ensuring consistent CAD capabilities across the viewer and plugin components.

Frequently Asked Questions

What is the primary function of cadpy in the text-to-cad pipeline?

The cadpy package functions as the geometric processing engine, converting raw STEP data and textual specifications into structured, exportable 3D assets. It abstracts file I/O, mesh conversion, and assembly logic into a unified toolkit that higher-level agents invoke to generate physical designs.

How does cadpy convert STEP files to GLB format?

Conversion occurs through a two-stage process: step_export.py first translates STEP topology into intermediate mesh representations, then glb.py serializes these meshes into binary GLB buffers using the glb_from_step() function. This pipeline preserves geometric fidelity while optimizing for web-viewer performance.

Can cadpy operate independently from the larger text-to-cad system?

Yes. cadpy is intentionally designed as a self-contained, dependency-light package. While it serves as the CAD backbone for the earthtojake/text-to-cad repository, its modular structure and pure-Python implementation allow it to function as a standalone library for STEP processing and GLB generation in other projects.

What types of metadata does cadpy generate for CAD models?

The metadata.py module generates cryptographic hashes, UUIDs, timestamps, and source file provenance. This metadata attaches to both intermediate Python objects and final exported files (such as GLB), enabling complete traceability from natural language prompt through to generated geometry.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}