Metadata-Version: 2.4
Name: dcad
Version: 0.1.0
Summary: Text to CAD from your terminal — generate real STEP/STL/3MF/GLB files from plain-language descriptions.
Project-URL: Homepage, https://github.com/HumfDev/derive-cad
Project-URL: Repository, https://github.com/HumfDev/derive-cad
Project-URL: Issues, https://github.com/HumfDev/derive-cad/issues
Author: HumfDev
License-Expression: MIT
License-File: LICENSE
Keywords: 3d,build123d,cad,llm,text-to-cad
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: <3.15,>=3.11
Requires-Dist: build123d<0.12,>=0.11.1
Requires-Dist: keyring<26,>=25.6
Requires-Dist: litellm<2,>=1.83
Requires-Dist: playwright<2,>=1.49
Requires-Dist: pydantic<3,>=2.9
Requires-Dist: questionary<3,>=2.1
Requires-Dist: rich<16,>=15.0
Requires-Dist: tomli-w<2,>=1.0
Requires-Dist: typer<0.27,>=0.26
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest<10,>=9.1; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
Description-Content-Type: text/markdown

# dcad

Text to CAD from your terminal. Connect an LLM API key, pick a working folder, and describe
what you want to build — `dcad` generates real CAD files (STEP, STL, 3MF, GLB) on disk.

> **Status: Milestone 2.** `dcad run "your prompt"` sends your description to the
> configured LLM, which writes a build123d script, runs it through vendored cadpy
> (`skills/cad/scripts/step`), and retries on failure.

## How it works

Before writing any code, the configured LLM produces a CAD brief (persisted as
`brief.md`) — dimensions, units, features, and a small set of machine-checkable
validation targets derived from your prompt. It then writes
[build123d](https://github.com/gumyr/build123d) — a Python parametric CAD library built
on the OpenCASCADE kernel — which is executed via cadpy to produce a STEP file and
optional sidecar exports (STL, 3MF, GLB).

The result is checked against the brief's validation targets (bounding box, face/solid
count). When enabled, a rendered snapshot (`snapshots/*.png`) is also reviewed by the
same LLM; that visual review is **advisory** — deterministic checks decide pass/fail,
and vision findings are logged without blocking acceptance when validation passes.
Deterministic failures are classified and repaired per the vendored
`skills/cad/references/repair-loop.md` — the LLM reads the failure output, classifies it,
and applies the smallest source fix before rerunning.

## CAD tools (upstream-shaped CLI)

`dcad` mirrors the [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) skill tool layout:

```bash
dcad run "your prompt"     # full SKILL.md workflow (primary UX)
dcad step model.py -o model.step --stl model.stl
dcad inspect refs model.step --facts --planes --positioning
dcad snapshot model.step   # Playwright snapshots (requires `.model.step.glb` sidecar)
dcad open step|stl|recent  # open artifacts with your OS default app
```

The vendored skill lives at `skills/cad/` (see `skills/cad/UPSTREAM_SHA` for the pinned commit).

## Install

```bash
pipx install dcad
```

Requires Python 3.11–3.14. [pipx](https://pipx.pypa.io/) keeps `dcad` and its dependencies
(including the OpenCASCADE binding) isolated from your other Python projects.

If `pipx` is not installed yet:

```bash
brew install pipx
pipx ensurepath
```

> **First release:** `dcad` is published to PyPI when a GitHub release is cut. Until then,
> install from a built wheel with `pipx install /path/to/dcad-*.whl` or follow the source
> setup below.

**From source** (contributors):

```bash
git clone https://github.com/HumfDev/derive-cad.git
cd derive-cad
bash scripts/setup-dev.sh
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

Do **not** also run `pip install -e packages/cadpy` — `dcad` already pulls in the vendored
`cadpy` via `pyproject.toml`. Installing both in one command makes pip treat them as
conflicting requirements.

> **Note:** `dcad` vendors [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)'s
> `skills/cad/` workflow and `packages/cadpy`. STEP generation and inspection use
> `skills/cad/scripts/step` and `skills/cad/scripts/inspect`. OpenCASCADE comes via
> `cadquery-ocp` (~60MB per platform). **Alpine/musl Docker images are not supported**; use
> `python:3.12-slim` or similar glibc base images.

## Quickstart

```bash
dcad run "design a phone stand with 45 degree angle"
```

On first use, `dcad run` launches an interactive setup wizard (LLM provider, model
dropdown, API key, working folder) and immediately generates your model. Reconfigure any
time with `dcad init`.

`dcad run` creates a named design folder directly in your working directory — for
example `~/derivecad-projects/phone-stand/model.stl`. The folder name is generated by your
configured LLM from your prompt (falls back to a slug if naming fails). Each design folder
contains `model.step`, your configured export formats (default: `model.stl`), the generated
Python source, `brief.md` (the CAD brief the model wrote before coding),
`snapshots/*.png` (the rendered views used for visual review), and stdout/stderr logs.
Open the latest outputs with:

```bash
dcad open stl      # open the most recent STL in your default viewer
dcad open step     # open the most recent STEP file
dcad open recent   # open the most recent run folder in Finder/Files
```

Supported `open` targets: `step`, `stl`, `3mf`, `glb`, `py`, `recent`.

Browse and run any command interactively:

```bash
dcad commands
```

## Supported LLM providers

| Provider  | Env var            | Notes                          |
|-----------|---------------------|---------------------------------|
| OpenAI    | `OPENAI_API_KEY`    |                                  |
| Anthropic | `ANTHROPIC_API_KEY` |                                  |
| Gemini    | `GEMINI_API_KEY`    |                                  |
| Groq      | `GROQ_API_KEY`      |                                  |
| Ollama    | *(none)*            | Local, no API key required.     |
| Other     | *(you choose)*      | Any [litellm](https://github.com/BerriAI/litellm)-supported model string + env var. |

API keys are stored in your OS keychain via [`keyring`](https://github.com/jaraco/keyring).
If no OS keychain backend is available (common in CI/containers/headless Linux), `dcad
init` falls back to `~/.derivecad/credentials.toml` (mode 600) and warns you that this is
less secure. An already-set environment variable always takes precedence over stored config.

## Supported output formats

STEP, STL, 3MF, GLB.

## Configuration

- Global config: `~/.derivecad/config.toml`
- Per-project override: `.derivecad.toml` in your working folder
- Precedence: CLI flags > per-project config > env vars (API keys only) > global config > defaults
- `enable_snapshot_review` (default `true`): set to `false` to skip rendering and reviewing
  a snapshot of each result — the release valve if the extra LLM call's cost/latency isn't
  worth it for your use case. When enabled, vision findings are logged but do not block
  acceptance if deterministic validation already passed. Vision review is also automatically
  skipped (and reported as such) for models with no known vision support.
- `bbox_tolerance_pct` (default `15.0`): tolerance applied to a brief's bounding-box
  validation targets before a mismatch is treated as a failure.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT
