How to Debug text-to-CAD: A Complete Troubleshooting Guide

Use the --verbose flag to activate CliLogger timing contexts, trace execution through the generation pipeline in packages/cadpy/src/cadpy/generation.py, and inspect intermediate CadModel objects via interactive Python sessions to isolate failures in the CAD generation workflow.

The earthtojake/text-to-cad repository transforms plain-language prompts and Python scripts into manufacturable STEP, GLB, and STL files. When the pipeline fails silently or produces malformed geometry, systematic debugging requires tracing data flow through the CLI entry points, logging infrastructure, and core generation engine.

Understand the text-to-CAD Architecture

Effective debugging starts with knowing which layer handles your specific failure. The repository organizes functionality into distinct modules that pass data from user input to final artifact.

CLI Entry Points

The skills/cad/scripts/step/cli.py file parses arguments like --verbose and --output, then dispatches to the generation pipeline. This is the first place to verify that your command-line flags reach the underlying functions. When you append --verbose, the CLI instantiates CliLogger(name="scripts/step", verbose=True) and propagates it downstream.

Generation Engine

The heart of the system lives in packages/cadpy/src/cadpy/generation.py. This module walks target Python files, constructs a CadModel instance, and coordinates mesh creation and export. Failures here manifest as missing output files or geometry exceptions. Place breakpoints inside the generate_from_files function to inspect the model before it reaches the exporter.

Logging Infrastructure

Uniform diagnostic output comes from packages/cadpy/src/cadpy/cli_logging.py. The CliLogger class provides info(), debug(), and timing() methods that wrap code blocks in measured contexts. When --verbose is active, these calls print timestamped stage durations to stderr, revealing bottlenecks in parsing, meshing, or file I/O.

Step-by-Step Debugging Workflow

Trace failures systematically by moving from surface-level CLI diagnostics to deep code inspection.

1. Enable verbose output at the command line.
   Run your generation command with the --verbose flag to surface timing data for each major stage.

   text-to-cad cad parts/sample.py --output models/sample.step --verbose

   This activates CliLogger.timing contexts around parsing, mesh creation, and export operations, printing durations like [scripts/step] mesh creation completed in 1.2s.

2. Inspect intermediate objects in a REPL.
   Import the generation module directly to examine the CadModel before it hits the disk.

   from cadpy import generate_from_files
   model = generate_from_files(["parts/sample.py"], verbose=True)
   model.inspect()  # Prints vertices, faces, and bounding box
   

3. Validate STEP metadata independently.
   If the output file is corrupt, run the validation routine directly against the artifact helper.

   python -m cadpy.step_artifact --validate models/sample.step

   This uses step_metadata.py to report missing entities or schema violations without running the full generation pipeline.

4. Use the local CAD viewer for visual feedback.
   Launch the viewer to catch rendering errors that indicate underlying geometry issues.

   npx skills install earthtojake/text-to-cad
   skills run cad-viewer --dir $(pwd)/models

   The viewer logs CliLogger messages to its console, correlating UI failures with CLI pipeline stages.

5. Run targeted unit tests.
   The test suite in tests/python/skills/cad/step/test_cli.py exercises CLI flags and generation paths with mocked arguments.

   ./scripts/test/test.sh -k test_cli

   Failures here pinpoint exact functions that misbehave under specific input conditions.

6. Inject temporary logging for custom code.
   When --verbose is insufficient, instantiate a logger directly in your script.

   from cadpy.cli_logging import CliLogger
   logger = CliLogger("my-debug", verbose=True)
   with logger.timed("custom-step"):
       # Your debugging code here
   
       pass

7. Verify artifacts in the models/ directory.
   Confirm that expected files (STEP, STL, GLB) exist with non-zero size. Missing files usually indicate an early exit in generation.py before the export stage completes.

Code Examples for Common Debugging Scenarios

Debugging Step Generation with Timing Output

Generate a part while capturing per-stage performance metrics to identify slow operations.

text-to-cad cad parts/sample.py \
    --output models/sample.step \
    --verbose

The output reveals precise timing for each pipeline phase:

[scripts/step] parsing started
[scripts/step] parsing completed in 45ms
[scripts/step] mesh creation started
[scripts/step] mesh creation completed in 1.2s

Interactive Model Inspection

When geometry looks wrong, examine the mesh attributes before exporting.

from cadpy import generate_from_files

model = generate_from_files(["parts/sample.py"], verbose=True)
model.inspect()

# Output: Vertices: 1243, Faces: 2360, Bounds: (0,0,0)-(100,50,20) mm

# Export manually after verification

model.mesh.to_stl("models/sample.stl")

Validating GLB Exports in the Viewer

Debug WebGL-specific export issues by loading the generated file in the local viewer.

# Generate the GLB first

text-to-cad cad parts/sample.py --output models/sample.glb --verbose

# Launch viewer pointing at the models folder

npx skills run cad-viewer --dir $(pwd)/models

Open the URL printed by the viewer (typically http://127.0.0.1:4178). If the model fails to load, check the viewer console for CliLogger error messages that mirror the CLI output.

Summary

• Start with --verbose to activate CliLogger timing contexts in packages/cadpy/src/cadpy/cli_logging.py and surface stage-level diagnostics.
• Trace the data flow from skills/cad/scripts/step/cli.py through packages/cadpy/src/cadpy/generation.py to isolate where the pipeline exits early.
• Inspect interactively using generate_from_files() and model.inspect() to verify geometry before it reaches the exporter.
• Validate artifacts with python -m cadpy.step_artifact --validate for STEP-specific schema compliance.
• Leverage the viewer at skills/cad-viewer/scripts/viewer/ to catch rendering errors and correlate them with generation logs.

Frequently Asked Questions

How do I enable verbose logging in text-to-CAD?

Append the --verbose flag to any text-to-cad cad command. This instantiates CliLogger with verbose mode enabled in skills/cad/scripts/step/cli.py, causing the generation pipeline in packages/cadpy/src/cadpy/generation.py to print timestamped stage durations and debug messages to stderr.

Where should I place breakpoints when debugging generation failures?

Set breakpoints inside generate_from_files() in packages/cadpy/src/cadpy/generation.py. This function orchestrates the entire pipeline, making it ideal for inspecting the CadModel object after mesh creation but before export. You can also break inside cli.py to verify that command-line arguments parse correctly before reaching the engine.

How can I inspect intermediate CAD models during execution?

Import generate_from_files from the cadpy package in an interactive Python session. Call the function with your input files and verbose=True, then invoke .inspect() on the returned model object to print vertex counts, face statistics, and bounding box dimensions without writing to disk.

What is the best way to validate exported STEP files?

Use the standalone validation module: python -m cadpy.step_artifact --validate path/to/file.step. This runs the validation logic from packages/cadpy/src/cadpy/step_artifact.py against STEP metadata requirements and reports missing entities or schema violations directly, bypassing the full generation pipeline.

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