agentcad-cli 0.1.1__tar.gz

agentcad_cli-0.1.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: agentcad-cli
+Version: 0.1.1
+Summary: Agent-first CAD workflow runtime
+Author: AgentCAD contributors
+License-Expression: MIT
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: build123d
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# AgentCAD
+
+AgentCAD is a CLI-first CAD workflow runtime for coding agents.
+
+It gives a coding agent a repeatable workspace, a contract-driven modeling
+protocol, deterministic build/export, geometric measurement, multi-view
+previews, design-time and post-build validation, and a delivery manifest —
+so the agent can iterate on CAD models with measurable feedback instead of
+visual intuition.
+
+```text
+design contract -> precheck -> params/source -> build
+                  -> measure -> render -> validate -> review -> deliver
+```
+
+## What's in the box
+
+| Stage | Command | Purpose |
+|---|---|---|
+| Scaffold | `agentcad new <model>` | Create model folder; auto-init workspace |
+| Sync | `agentcad sync` | Refresh workspace scaffold from latest templates |
+| Precheck | `agentcad precheck <model>` | Solve `design.json` statically (schema, feature coverage, `min_clearance`) **before** part.py is written |
+| Build | `agentcad build <model>` | Run `part.py` through build123d, export STEP + STL, hash-cache stale runs |
+| Measure | `agentcad measure <model>` | Mesh stats + structural facts (bbox, watertight, triangles, voids) |
+| Render | `agentcad render <model>` | Iso/front/top/side/back SVG previews + Z/X/Y cross-section SVGs |
+| Probe | `agentcad probe <model>` | Cross-section diameter / bbox / void at specified Z, X, Y; `--scan` to discover step changes |
+| Inspect | `agentcad inspect <model>` | Three-axis scan + automatic section SVGs + suggested probes |
+| Validate | `agentcad validate <model>` | Build + measure + render + design checks + feature coverage; auto-emits debug SVGs on failure |
+| Review | `agentcad review <model>` | Pre-delivery checklist with pairwise relations matrix and must-view SVG list |
+| Deliver | `agentcad deliver <model>` | Delivery manifest |
+| Report | `agentcad report <model>` | Markdown summary of validation result |
+
+Every command supports `--json` for stable machine-readable output; failures
+return JSON containing `stage`, `error.type`, `error.message`.
+
+## Validation check types
+
+| Type | Layer | Notes |
+|---|---|---|
+| `bbox_size` | post-build | Outer envelope dimensions |
+| `watertight` | post-build | STL is a closed manifold |
+| `min_triangles` | post-build | Mesh density floor |
+| `artifact_exists` | post-build | STEP / STL / SVG present |
+| `metadata_equals` | post-build | Asserts a value emitted from `part.py` |
+| `outer_diameter_at_z` | post-build | Cross-section radial size at Z |
+| `inner_diameter_at_z` | post-build | Inner cavity diameter at Z |
+| `section_bbox_at_z` | post-build | Cross-section AABB / void detection at Z |
+| `diameter_decreases_along_z` | post-build | Monotonicity for tapers / lead-ins |
+| `volume_range` | post-build | Volume sanity bounds |
+| `min_clearance` | **design-time + post-build** | Pure-shape edge-to-edge clearance between two declared shapes (no STL required) |
+| `hole_accessibility` | post-build | Annular clearance around a hole at the working plane |
+| `min_wall_thickness` | post-build | Minimum point-pair distance inside a defined region |
+| `feature_position` | post-build | Assert a 3D point is `solid` or `void` |
+| `feature_coverage` | automatic | Every declared feature must reference at least one check |
+
+The four "geometric relation" checks (last block) close the historical gap
+where `inner_diameter_at_z` would happily report a 4.5 mm hole that was
+half-covered by an adjacent wall.
+
+## Quick start
+
+```bash
+uv tool install agentcad-cli
+agentcad --help
+```
+
+For local development:
+
+```bash
+uv sync
+uv run agentcad --help
+```
+
+## Quick example
+
+```bash
+uv run agentcad new bracket --project /tmp/my-cad-project
+cd /tmp/my-cad-project
+
+# 1. Design-time: solve the contract before writing geometry
+uv run agentcad precheck bracket --json
+
+# 2. Implement part.py, then run the post-build pipeline
+uv run agentcad validate bracket --json
+
+# 3. Pre-delivery review (relations matrix + must-view SVGs)
+uv run agentcad review bracket --json
+
+# 4. Deliver
+uv run agentcad deliver bracket --json
+```
+
+The default generated model is a simple build123d cuboid. Agent rules and
+common-error catalog live in `AGENTS.md`, `CLAUDE.md`, and `references/`
+(always-on reference docs for build123d patterns and validation strategy).
+
+## Examples
+
+| Path | What it shows |
+|---|---|
+| `examples/fan-adapter-8025/` | Two validated models: a fan-to-duct adapter and a magnetic outlet plate |
+| `examples/iphone15pro-case/` | Real-world phone case with multi-cutouts + section validation |
+| `examples/e2e-test/` | Sub-agent end-to-end test: design → precheck → build → validate → review on a mounting bracket |
+
+Re-run any example:
+
+```bash
+cd examples/fan-adapter-8025
+uv run agentcad validate fan_duct_adapter_8025 --json
+uv run agentcad review fan_duct_adapter_8025 --json
+```
+
+## Tests
+
+```bash
+uv run pytest -v
+```
+
+125 tests at last count, covering CLI dispatch, workspace scaffolding, STL
+reading and measurement, section extraction and SVG rendering, JSON IO,
+post-build validation checks, weak-check warnings, stale build detection,
+geometric primitives, and `precheck` / `review` integration.
+
+## Documentation
+
+- [`docs/DESIGN.md`](docs/DESIGN.md) — architecture, first principles, and
+  V0–V5 iteration roadmap (with delivered milestones marked).
+- [`docs/STATUS.md`](docs/STATUS.md) — current implementation state, recent
+  lessons (build123d traps, hole-wall interference), and the planned next
+  research and engineering work.
+- `AGENTS.md` / `CLAUDE.md` (workspace) — operating rules for the coding
+  agent, including the mandatory TDD red/green workflow and the common
+  design-error catalog.

agentcad_cli-0.1.1/README.md

@@ -0,0 +1,133 @@
+# AgentCAD
+
+AgentCAD is a CLI-first CAD workflow runtime for coding agents.
+
+It gives a coding agent a repeatable workspace, a contract-driven modeling
+protocol, deterministic build/export, geometric measurement, multi-view
+previews, design-time and post-build validation, and a delivery manifest —
+so the agent can iterate on CAD models with measurable feedback instead of
+visual intuition.
+
+```text
+design contract -> precheck -> params/source -> build
+                  -> measure -> render -> validate -> review -> deliver
+```
+
+## What's in the box
+
+| Stage | Command | Purpose |
+|---|---|---|
+| Scaffold | `agentcad new <model>` | Create model folder; auto-init workspace |
+| Sync | `agentcad sync` | Refresh workspace scaffold from latest templates |
+| Precheck | `agentcad precheck <model>` | Solve `design.json` statically (schema, feature coverage, `min_clearance`) **before** part.py is written |
+| Build | `agentcad build <model>` | Run `part.py` through build123d, export STEP + STL, hash-cache stale runs |
+| Measure | `agentcad measure <model>` | Mesh stats + structural facts (bbox, watertight, triangles, voids) |
+| Render | `agentcad render <model>` | Iso/front/top/side/back SVG previews + Z/X/Y cross-section SVGs |
+| Probe | `agentcad probe <model>` | Cross-section diameter / bbox / void at specified Z, X, Y; `--scan` to discover step changes |
+| Inspect | `agentcad inspect <model>` | Three-axis scan + automatic section SVGs + suggested probes |
+| Validate | `agentcad validate <model>` | Build + measure + render + design checks + feature coverage; auto-emits debug SVGs on failure |
+| Review | `agentcad review <model>` | Pre-delivery checklist with pairwise relations matrix and must-view SVG list |
+| Deliver | `agentcad deliver <model>` | Delivery manifest |
+| Report | `agentcad report <model>` | Markdown summary of validation result |
+
+Every command supports `--json` for stable machine-readable output; failures
+return JSON containing `stage`, `error.type`, `error.message`.
+
+## Validation check types
+
+| Type | Layer | Notes |
+|---|---|---|
+| `bbox_size` | post-build | Outer envelope dimensions |
+| `watertight` | post-build | STL is a closed manifold |
+| `min_triangles` | post-build | Mesh density floor |
+| `artifact_exists` | post-build | STEP / STL / SVG present |
+| `metadata_equals` | post-build | Asserts a value emitted from `part.py` |
+| `outer_diameter_at_z` | post-build | Cross-section radial size at Z |
+| `inner_diameter_at_z` | post-build | Inner cavity diameter at Z |
+| `section_bbox_at_z` | post-build | Cross-section AABB / void detection at Z |
+| `diameter_decreases_along_z` | post-build | Monotonicity for tapers / lead-ins |
+| `volume_range` | post-build | Volume sanity bounds |
+| `min_clearance` | **design-time + post-build** | Pure-shape edge-to-edge clearance between two declared shapes (no STL required) |
+| `hole_accessibility` | post-build | Annular clearance around a hole at the working plane |
+| `min_wall_thickness` | post-build | Minimum point-pair distance inside a defined region |
+| `feature_position` | post-build | Assert a 3D point is `solid` or `void` |
+| `feature_coverage` | automatic | Every declared feature must reference at least one check |
+
+The four "geometric relation" checks (last block) close the historical gap
+where `inner_diameter_at_z` would happily report a 4.5 mm hole that was
+half-covered by an adjacent wall.
+
+## Quick start
+
+```bash
+uv tool install agentcad-cli
+agentcad --help
+```
+
+For local development:
+
+```bash
+uv sync
+uv run agentcad --help
+```
+
+## Quick example
+
+```bash
+uv run agentcad new bracket --project /tmp/my-cad-project
+cd /tmp/my-cad-project
+
+# 1. Design-time: solve the contract before writing geometry
+uv run agentcad precheck bracket --json
+
+# 2. Implement part.py, then run the post-build pipeline
+uv run agentcad validate bracket --json
+
+# 3. Pre-delivery review (relations matrix + must-view SVGs)
+uv run agentcad review bracket --json
+
+# 4. Deliver
+uv run agentcad deliver bracket --json
+```
+
+The default generated model is a simple build123d cuboid. Agent rules and
+common-error catalog live in `AGENTS.md`, `CLAUDE.md`, and `references/`
+(always-on reference docs for build123d patterns and validation strategy).
+
+## Examples
+
+| Path | What it shows |
+|---|---|
+| `examples/fan-adapter-8025/` | Two validated models: a fan-to-duct adapter and a magnetic outlet plate |
+| `examples/iphone15pro-case/` | Real-world phone case with multi-cutouts + section validation |
+| `examples/e2e-test/` | Sub-agent end-to-end test: design → precheck → build → validate → review on a mounting bracket |
+
+Re-run any example:
+
+```bash
+cd examples/fan-adapter-8025
+uv run agentcad validate fan_duct_adapter_8025 --json
+uv run agentcad review fan_duct_adapter_8025 --json
+```
+
+## Tests
+
+```bash
+uv run pytest -v
+```
+
+125 tests at last count, covering CLI dispatch, workspace scaffolding, STL
+reading and measurement, section extraction and SVG rendering, JSON IO,
+post-build validation checks, weak-check warnings, stale build detection,
+geometric primitives, and `precheck` / `review` integration.
+
+## Documentation
+
+- [`docs/DESIGN.md`](docs/DESIGN.md) — architecture, first principles, and
+  V0–V5 iteration roadmap (with delivered milestones marked).
+- [`docs/STATUS.md`](docs/STATUS.md) — current implementation state, recent
+  lessons (build123d traps, hole-wall interference), and the planned next
+  research and engineering work.
+- `AGENTS.md` / `CLAUDE.md` (workspace) — operating rules for the coding
+  agent, including the mandatory TDD red/green workflow and the common
+  design-error catalog.

agentcad_cli-0.1.1/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentcad-cli"
+version = "0.1.1"
+description = "Agent-first CAD workflow runtime"
+readme = "README.md"
+requires-python = ">=3.11,<3.13"
+license = "MIT"
+authors = [
+  { name = "AgentCAD contributors" }
+]
+dependencies = [
+  "build123d"
+]
+
+[project.scripts]
+agentcad = "agentcad.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"agentcad._templates" = ["**/*.md", "**/*.json", "**/*.py", "**/.gitkeep"]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

agentcad_cli-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentcad_cli-0.1.1/src/agentcad/__init__.py

@@ -0,0 +1,3 @@
+"""Agent-first CAD workflow runtime."""
+
+__version__ = "0.1.0"

agentcad_cli-0.1.1/src/agentcad/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentcad_cli-0.1.1/src/agentcad/_templates/model/README.md

@@ -0,0 +1,46 @@
+# {name}
+
+AgentCAD model folder.
+
+## Files you edit
+
+- `design.json` — design intent + validation checks (the design contract)
+- `params.json` — tunable dimensions
+- `part.py` — build123d geometry (must assign final shape to `result`)
+
+## Recommended workflow
+
+```bash
+agentcad precheck {name} --json     # 1. solve design.json statically
+# write part.py once precheck is green
+agentcad build {name} --json        # 2. generate STEP/STL
+agentcad measure {name} --json      # 3. measure geometry stats
+agentcad validate {name} --json     # 4. run all checks (auto-renders SVGs)
+agentcad review {name} --json       # 5. pre-delivery checklist + relations matrix
+agentcad deliver {name} --json      # 6. write delivery manifest
+```
+
+## Common errors to design *against*
+
+For every hole declared in `params.json`, also declare a `min_clearance` check
+in `design.json` between the hole cylinder and each adjacent solid (walls,
+plates, flanges, edges). This catches the classic "hole edge buried under a
+wall" bug at design time, before any code is written.
+
+```json
+{
+  "id": "hole_X_clearance",
+  "type": "min_clearance",
+  "feature_a": {"type": "cylinder", "axis": "z",
+                "center": [hole_x, hole_y], "radius": hole_r,
+                "z_range": [z0, z1]},
+  "feature_b": {"type": "box",
+                "x_range": [...], "y_range": [...], "z_range": [...]},
+  "min_mm": 0.0
+}
+```
+
+See `../references/validation-strategy.md` for a complete catalog of design
+errors and the check types that catch them.
+
+Generated artifacts go to `outputs/`.

agentcad_cli-0.1.1/src/agentcad/_templates/model/design.json

@@ -0,0 +1,43 @@
+{
+  "schema": "design-spec.v1",
+  "model": "{name}",
+  "units": "mm",
+  "intent": "Default rectangular sample block.",
+  "features": [
+    {
+      "id": "base_block",
+      "intent": "Rectangular solid block with parameter-driven envelope.",
+      "checks": [
+        "bbox_size",
+        "watertight"
+      ]
+    }
+  ],
+  "checks": [
+    {
+      "id": "bbox_size",
+      "type": "bbox_size",
+      "expected": [
+        40.0,
+        30.0,
+        20.0
+      ],
+      "tolerance": 0.2
+    },
+    {
+      "id": "watertight",
+      "type": "watertight",
+      "expected": true
+    },
+    {
+      "id": "step_artifact",
+      "type": "artifact_exists",
+      "path": "outputs/{name}.step"
+    },
+    {
+      "id": "stl_artifact",
+      "type": "artifact_exists",
+      "path": "outputs/{name}.stl"
+    }
+  ]
+}

agentcad_cli-0.1.1/src/agentcad/_templates/model/params.json

@@ -0,0 +1,5 @@
+{
+  "length": 40.0,
+  "width": 30.0,
+  "height": 20.0
+}

agentcad_cli-0.1.1/src/agentcad/_templates/model/part.py

@@ -0,0 +1,33 @@
+"""Default AgentCAD build123d model.
+
+Tunable values live in params.json. The final geometry must be assigned to
+global variable `result`.
+"""
+import json
+from pathlib import Path
+
+from build123d import *
+
+PARAMS = json.loads((Path(__file__).with_name("params.json")).read_text(encoding="utf-8"))
+
+length = float(PARAMS["length"])
+width = float(PARAMS["width"])
+height = float(PARAMS["height"])
+
+
+def build():
+    with BuildPart() as bp:
+        add(Box(length, width, height))
+    return bp.part
+
+
+result = build()
+metadata = {
+    "schema": "agentcad.part.metadata.v1",
+    "units": "mm",
+    "anchors": {
+        "origin": [0, 0, 0],
+        "x_min": [-length / 2, 0, 0],
+        "x_max": [length / 2, 0, 0],
+    },
+}