# How to Search for Off-the-Shelf STEP Components with the step-parts Skill

> Learn how to search for off-the-shelf STEP components using the step-parts skill. Download verified STEP files and launch them directly in your CAD viewer.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-08-01

---

**The step-parts skill provides a deterministic command-line interface to query the step.parts catalog, download verified STEP files, and automatically launch them in the CAD viewer for immediate inspection.**

The text-to-cad repository implements a modular, skill-driven architecture for generating CAD models from natural language. By leveraging the step-parts skill, engineers can programmatically discover and import manufacturer-verified STEP files—such as fasteners, bearings, and motors—directly into their `models/` directory for seamless assembly integration.

## What Is the step-parts Skill?

The **step-parts** skill is a self-contained module under `skills/step-parts/` that abstracts the step.parts REST API into reproducible, testable commands. It serves as the gateway to the public [step.parts](https://www.step.parts) catalog, enabling automatic discovery of real-world mechanical components.

Unlike ad-hoc scripts, this skill bundles its runtime logic, documentation, and API references together. It connects to `https://api.step.parts` to execute queries and handles result disambiguation, SHA-256 checksum verification, and automatic hand-off to the CAD viewer through the `$cad-viewer` environment variable.

## Repository Architecture

The text-to-cad repository organizes functionality into isolated layers that keep skills interoperable yet independent:

- **Skill Registry**: Each skill includes a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) manifest describing its purpose and interface.
- **Skill Implementations**: Self-contained logic under `skills/*/` that never imports code from sibling skills.
- **Shared Packages**: Common utilities like CAD rendering live in `packages/cadjs/`, `packages/implicitjs/`, and `packages/cadpy/`.
- **CAD Viewer**: The web-based viewer in `viewer/` receives files via the `$cad-viewer` command.
- **Models Store**: Downloaded artifacts are stored in `models/` and tracked via Git LFS.

## How the step-parts Skill Works

The skill executes a five-phase pipeline defined in [`skills/step-parts/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/step-parts/SKILL.md) to ensure reliable component retrieval:

1. **Interpret the request** – Parses natural language queries into API parameters (`q`, `category`, `family`).
2. **Query the API** – Calls `GET /v1/parts` on the step.parts service (documented in [`references/step-parts-api.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/step-parts-api.md)).
3. **Disambiguate results** – When multiple candidates match, presents top results showing `id`, `name`, `standard`, and key attributes.
4. **Download and verify** – Fetches the `stepUrl`, verifies SHA-256 checksums, and writes files to `models/`.
5. **Viewer hand-off** – Automatically invokes `$cad-viewer` to render the downloaded component.

## Searching and Downloading STEP Files

### Command-Line Search

The [`scripts/download_step_part.py`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/download_step_part.py) script provides a deterministic CLI for searching and downloading. To search and download in one operation:

```bash
python scripts/download_step_part.py "M3 socket head 12" --download

```

This command searches the catalog, selects the best match, downloads the STEP file, verifies the checksum, and outputs a JSON payload containing the local file path and source URLs.

### Programmatic Usage in Python

You can invoke the downloader from Python using subprocess calls to first search, then download by specific ID:

```python
from pathlib import Path
import json, subprocess

def find_step_part(query: str) -> Path:
    # Run the bundled downloader in "search-only" mode

    result = subprocess.check_output([
        "python", "scripts/download_step_part.py",
        query, "--json"
    ], text=True)
    data = json.loads(result)
    # Assume the first hit is acceptable

    part_id = data["items"][0]["id"]
    # Download the STEP file

    download = subprocess.check_output([
        "python", "scripts/download_step_part.py",
        f"--id={part_id}", "--download", "--json"
    ], text=True)
    download_info = json.loads(download)
    return Path(download_info["filePath"])

step_file = find_step_part("bearing 608zz")
print(f"Saved STEP file: {step_file}")

```

### Visualizing Components in the CAD Viewer

After downloading, launch the viewer to inspect the geometry immediately:

```bash
cad-viewer open --file models/M3_socket_head_12.step

```

The `$cad-viewer` command starts a new viewer instance or connects to an existing one, rendering the STEP file using the rendering utilities defined in [`packages/cadjs/src/lib/stepRenderAssetClient.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/lib/stepRenderAssetClient.js).

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`skills/step-parts/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/step-parts/SKILL.md) | Human-readable skill manifest with workflow and API reference |
| [`scripts/download_step_part.py`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/download_step_part.py) | Deterministic CLI implementing search, download, and checksum verification |
| [`references/step-parts-api.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/step-parts-api.md) | OpenAPI specification for the step.parts service |
| [`packages/cadjs/src/lib/stepRenderAssetClient.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/lib/stepRenderAssetClient.js) | JavaScript helper used by the viewer to render STEP assets |
| `models/` | LFS-tracked directory storing downloaded STEP and STL files |
| [`viewer/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/README.md) | Configuration and launch instructions for the CAD viewer |

## Summary

- The **step-parts** skill provides deterministic access to the step.parts catalog through [`scripts/download_step_part.py`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/download_step_part.py).
- It verifies downloaded files using SHA-256 checksums before writing to `models/`.
- The skill integrates seamlessly with the CAD viewer via the `$cad-viewer` environment variable.
- All API logic is documented in [`references/step-parts-api.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/step-parts-api.md) and encapsulated to avoid cross-skill dependencies.
- Components are searchable via CLI or Python subprocess calls, returning structured JSON for programmatic use.

## Frequently Asked Questions

### What types of components can I search for with the step-parts skill?

The skill supports any component indexed by the step.parts catalog, including standardized mechanical parts like screws, bolts, bearings, motors, gears, and connectors. The API accepts queries across multiple attribute fields including `category`, `family`, and `standard` identifiers.

### How does the step-parts skill ensure file integrity?

When downloading via [`scripts/download_step_part.py`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/download_step_part.py), the skill calculates the SHA-256 hash of the retrieved file and compares it against the checksum provided by the step.parts API. If verification fails, the file is rejected and the operation exits with an error code, ensuring only validated geometry enters your `models/` directory.

### Can I use the step-parts skill independently of other text-to-cad features?

Yes. While designed for the text-to-cad ecosystem, the step-parts skill is self-contained under `skills/step-parts/` and relies only on shared packages in `packages/`. You can execute [`scripts/download_step_part.py`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/download_step_part.py) as a standalone utility provided Python dependencies are met, though the automatic viewer integration requires the `$cad-viewer` environment variable to be set.

### Where can I find the API specification for step.parts?

The complete OpenAPI specification is documented in [`references/step-parts-api.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/step-parts-api.md) within the step-parts skill directory. This file details the `GET /v1/parts` endpoint, query parameters, response schemas, and authentication requirements for direct API access beyond the skill abstraction.