python-cad-tools 0.1.9__tar.gz → 0.1.10__tar.gz

{python_cad_tools-0.1.9 → python_cad_tools-0.1.10}/.github/workflows/ci.yml

@@ -250,6 +250,124 @@ jobs:
           name: ${{ matrix.lock }}
           path: ${{ matrix.lock }}
 
+  toolchain-matrix:
+    name: Toolchain matrix (${{ matrix.os }}, py${{ matrix.python }}, ${{ matrix.group }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.12", "3.13"]
+        group: [core, cad, bim, mesh, drawings, engineering, visualization, all]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      # Full matrix on main/tags/release-candidates; a fast core+all subset on pull requests.
+      - name: Determine whether this matrix cell runs
+        id: gate
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ] && \
+             ! { [ "${{ matrix.os }}" = "ubuntu-latest" ] && [ "${{ matrix.python }}" = "3.13" ] && \
+                 { [ "${{ matrix.group }}" = "core" ] || [ "${{ matrix.group }}" = "all" ]; }; }; then
+            echo "run=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        if: steps.gate.outputs.run == 'true'
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+        if: steps.gate.outputs.run == 'true'
+      - name: Install capability group
+        if: steps.gate.outputs.run == 'true'
+        run: |
+          if [ "${{ matrix.group }}" = "core" ]; then
+            pip install -e .
+          else
+            pip install -e ".[${{ matrix.group }}]"
+          fi
+      - run: pip check
+        if: steps.gate.outputs.run == 'true'
+      - name: Import declared libraries for this group
+        if: steps.gate.outputs.run == 'true'
+        run: |
+          python - <<'PY'
+          import importlib
+          import json
+          import sys
+
+          GROUPS = {
+              "core": ["build123d", "OCP", "ifcopenshell", "trimesh", "numpy", "ezdxf", "reportlab", "pypdf"],
+              "cad": ["build123d", "OCP"],
+              "bim": ["ifcopenshell"],
+              "mesh": ["trimesh", "numpy"],
+              "drawings": ["ezdxf", "reportlab", "pypdf"],
+              "engineering": ["shapely", "manifold3d", "meshio"],
+              "visualization": [],
+              "all": [
+                  "build123d", "OCP", "ifcopenshell", "trimesh", "numpy", "ezdxf", "reportlab", "pypdf",
+                  "shapely", "manifold3d", "meshio",
+              ],
+          }
+          group = "${{ matrix.group }}"
+          modules = GROUPS[group]
+          results = {}
+          for name in modules:
+              try:
+                  module = importlib.import_module(name)
+                  results[name] = getattr(module, "__version__", "unknown")
+              except ImportError as error:
+                  print(f"::error::failed to import {name!r} for group {group!r}: {error}", file=sys.stderr)
+                  sys.exit(1)
+          report = {
+              "schema_id": "urn:python-cad-tools:schema:toolchain-compatibility:1",
+              "schema_version": 1,
+              "os": "${{ matrix.os }}",
+              "python": "${{ matrix.python }}",
+              "group": group,
+              "resolved_versions": results,
+              "ok": True,
+          }
+          with open("toolchain-compatibility.json", "w", encoding="utf-8") as stream:
+              json.dump(report, stream, indent=2, sort_keys=True)
+          print(json.dumps(report, indent=2, sort_keys=True))
+          PY
+      - name: Tier-2 interop smoke and no-GUI assertion
+        if: steps.gate.outputs.run == 'true' && matrix.group == 'all'
+        run: |
+          python - <<'PY'
+          import sys
+
+          from build123d import Box
+          from python_cad_tools.geometry import tessellate
+
+          solid = Box(10, 10, 10)
+          vertices, triangles = tessellate(solid, 0.5, 0.25)
+          assert vertices and triangles, "tessellation produced no geometry"
+
+          import trimesh
+          mesh = trimesh.Trimesh(vertices=vertices, faces=triangles, process=False)
+          assert mesh.is_watertight or len(mesh.faces) > 0, "trimesh failed to load the tessellated shape"
+
+          import ifcopenshell
+          file = ifcopenshell.file(schema="IFC4")
+          file.createIfcCartesianPoint((0.0, 0.0, 0.0))
+
+          import ezdxf
+          document = ezdxf.new("R2018")
+          document.modelspace().add_line((0, 0), (1, 1))
+
+          forbidden = [name for name in sys.modules if name.startswith(("vtk", "pyvista", "PyQt", "PySide", "tkinter"))]
+          assert not forbidden, f"GUI/visualization modules present after Tier-2 interop smoke: {forbidden}"
+          print("Tier-2 interop smoke and no-GUI assertion passed.")
+          PY
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        if: steps.gate.outputs.run == 'true'
+        with:
+          name: toolchain-compatibility-${{ matrix.os }}-py${{ matrix.python }}-${{ matrix.group }}
+          path: toolchain-compatibility.json
+
   build-publish:
     name: Build and publish to PyPI
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')

{python_cad_tools-0.1.9 → python_cad_tools-0.1.10}/CHANGELOG.md

@@ -7,6 +7,33 @@ stable release is published.
 
 ## [Unreleased]
 
+## [0.1.10] - 2026-08-11
+
+### Added
+
+- Capability-based dependency extras (`cad`, `bim`, `mesh`, `drawings`,
+  `engineering`, `visualization`, `all`); the Tier 1 verified stack stays
+  required in `[project.dependencies]`. See `docs/toolchain.md`.
+- A documented two-tier authoring contract (`docs/two-tier-contract.md`) and a
+  neutral-model field reference (`docs/neutral-model.md`).
+- `DesignElement.properties` now exports as `Pset_PythonCadUser` on IFC-exported
+  elements; property values must be `str`, `bool`, `int`, or `float`.
+- Computed quantities now export as an `IfcElementQuantity` named
+  `Qto_PythonCadDesign` on IFC-exported elements with a quantity record.
+- `DesignElement.storey` now drives on-demand `IfcBuildingStorey` creation; a
+  model with no declared storey is unaffected.
+- New `DesignElement.openings: list[Opening]` field; each opening exports an
+  `IfcOpeningElement` + `IfcRelVoidsElement` on its host. Openings add IFC
+  semantics only — geometry in every other format is unaffected.
+- New public `python_cad_tools.drawings.Dimension` annotation primitive,
+  rendered through the verified annotation pipeline in SVG, DXF, and PDF.
+
+### Changed
+
+- The IFC unit assignment gains a `MASSUNIT` (`KILO`/`GRAM`) entry. This
+  changes the emitted IFC file, and therefore its artifact hash, for every
+  project — a one-time change from this release.
+
 ## [0.1.9] - 2026-08-03
 
 ### Fixed

{python_cad_tools-0.1.9/src/python_cad_tools.egg-info → python_cad_tools-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cad-tools
-Version: 0.1.9
+Version: 0.1.10
 Summary: Typed, headless Python tooling for CAD/BIM models and artifacts
 Author: Brandon Benge
 License: AGPL-3.0-only
@@ -26,6 +26,25 @@ Requires-Dist: numpy<3,>=2.3
 Requires-Dist: ezdxf<2,>=1.4
 Requires-Dist: reportlab<5,>=4.4
 Requires-Dist: pypdf<7,>=6
+Provides-Extra: cad
+Requires-Dist: build123d<0.12,>=0.11.1; extra == "cad"
+Requires-Dist: cadquery-ocp-novtk<7.10,>=7.9.3.1.1; extra == "cad"
+Provides-Extra: bim
+Requires-Dist: ifcopenshell<0.9,>=0.8.5; extra == "bim"
+Provides-Extra: mesh
+Requires-Dist: trimesh<5,>=4.12; extra == "mesh"
+Requires-Dist: numpy<3,>=2.3; extra == "mesh"
+Provides-Extra: drawings
+Requires-Dist: ezdxf<2,>=1.4; extra == "drawings"
+Requires-Dist: reportlab<5,>=4.4; extra == "drawings"
+Requires-Dist: pypdf<7,>=6; extra == "drawings"
+Provides-Extra: engineering
+Requires-Dist: shapely<3,>=2.1; extra == "engineering"
+Requires-Dist: manifold3d<4,>=3; extra == "engineering"
+Requires-Dist: meshio<6,>=5.3; extra == "engineering"
+Provides-Extra: visualization
+Provides-Extra: all
+Requires-Dist: python-cad-tools[bim,cad,drawings,engineering,mesh,visualization]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: build<2,>=1.2; extra == "dev"
 Requires-Dist: twine<7,>=6; extra == "dev"
@@ -50,6 +69,17 @@ The canonical project identities are:
 
 Licensed under [AGPL-3.0-only](LICENSE). Published on [PyPI](https://pypi.org/project/python-cad-tools/).
 
+## Install
+
+```bash
+pip install "python-cad-tools[all]"
+```
+
+Capability-based extras (`cad`, `bim`, `mesh`, `drawings`, `engineering`,
+`visualization`) install a subset of the curated, version-tested toolchain.
+See [`docs/toolchain.md`](docs/toolchain.md) for the supported-library table,
+the dependency license policy, and the compatibility verification matrix.
+
 ## Install for development
 
 Python 3.12 or 3.13 is required.
@@ -162,6 +192,14 @@ documented in [`docs/drawing-extensions.md`](docs/drawing-extensions.md). One
 annotation set is validated and rendered consistently to SVG, DXF, and PDF
 before artifact hashes are recorded.
 
+Python CAD Tools is a curated engineering platform with a two-tier authoring
+contract: verified authoring through the neutral model (Tier 1), and
+supported-but-unverified direct use of a pinned library such as
+`ifcopenshell` or `trimesh` (Tier 2). See
+[`docs/two-tier-contract.md`](docs/two-tier-contract.md),
+[`docs/neutral-model.md`](docs/neutral-model.md), and
+[`docs/toolchain.md`](docs/toolchain.md).
+
 ## Verification
 
 ```bash
@@ -175,6 +213,7 @@ before artifact hashes are recorded.
 .venv/bin/python -m twine check dist/*
 ```
 
+
 The default pytest command runs the fast unit suite. Integration, packaging,
 and external typing suites are explicit release gates. Packaging tests inspect wheel and sdist inventories, install the wheel
 non-editably into an isolated environment outside the checkout, prove the

{python_cad_tools-0.1.9 → python_cad_tools-0.1.10}/README.md

@@ -13,6 +13,17 @@ The canonical project identities are:
 
 Licensed under [AGPL-3.0-only](LICENSE). Published on [PyPI](https://pypi.org/project/python-cad-tools/).
 
+## Install
+
+```bash
+pip install "python-cad-tools[all]"
+```
+
+Capability-based extras (`cad`, `bim`, `mesh`, `drawings`, `engineering`,
+`visualization`) install a subset of the curated, version-tested toolchain.
+See [`docs/toolchain.md`](docs/toolchain.md) for the supported-library table,
+the dependency license policy, and the compatibility verification matrix.
+
 ## Install for development
 
 Python 3.12 or 3.13 is required.
@@ -125,6 +136,14 @@ documented in [`docs/drawing-extensions.md`](docs/drawing-extensions.md). One
 annotation set is validated and rendered consistently to SVG, DXF, and PDF
 before artifact hashes are recorded.
 
+Python CAD Tools is a curated engineering platform with a two-tier authoring
+contract: verified authoring through the neutral model (Tier 1), and
+supported-but-unverified direct use of a pinned library such as
+`ifcopenshell` or `trimesh` (Tier 2). See
+[`docs/two-tier-contract.md`](docs/two-tier-contract.md),
+[`docs/neutral-model.md`](docs/neutral-model.md), and
+[`docs/toolchain.md`](docs/toolchain.md).
+
 ## Verification
 
 ```bash
@@ -138,6 +157,7 @@ before artifact hashes are recorded.
 .venv/bin/python -m twine check dist/*
 ```
 
+
 The default pytest command runs the fast unit suite. Integration, packaging,
 and external typing suites are explicit release gates. Packaging tests inspect wheel and sdist inventories, install the wheel
 non-editably into an isolated environment outside the checkout, prove the

{python_cad_tools-0.1.9 → python_cad_tools-0.1.10}/docs/drawing-extensions.md

@@ -42,9 +42,20 @@ so the prior generated tree and its recorded hashes remain unchanged.
 
 The stable home module `python_cad_tools.drawings` exports `Point2`,
 `Direction`, `DrawingStyleToken`, `DrawingSheet`, `Line`, `Polyline`, `Text`,
-`SectionCallout`, `ElevationMarker`, `TableRow`, `Table`, `SheetAnnotations`,
-and `DrawingAnnotationSet`. The dataclass fields and literal tokens are the v1
-contract; there is no dictionary or renderer-specific alternate form.
+`Dimension`, `SectionCallout`, `ElevationMarker`, `TableRow`, `Table`,
+`SheetAnnotations`, and `DrawingAnnotationSet`. The dataclass fields and
+literal tokens are the v1 contract; there is no dictionary or
+renderer-specific alternate form.
+
+`Dimension(id, sheet_id, start, end, offset_mm, label, style)` draws a
+measurement: a dimension line offset from the measured segment (in Y for a
+predominantly horizontal segment, in X otherwise), extension/witness lines
+back to `start`/`end`, arrowheads at both ends, and a centred label. It uses
+the `"annotation-dimension"` style token. The rendered DXF output is tagged
+geometry (lines, arrowheads, and text with `PYTHON_CAD_TOOLS` XDATA), not a
+native associative `DIMENSION` entity — a project needing an editable CAD
+dimension should treat the drawing as conceptual, consistent with every other
+Python CAD Tools drawing output.
 
 `DrawingContext.sheets` contains these standard sheets:
 
@@ -125,6 +136,8 @@ direction.
 
 Compound IDs are deterministic:
 
+- dimension: `.line`, `.extension.start`, `.extension.end`, `.arrow.start`,
+  `.arrow.end`, and `.label`;
 - section callout: `.line`, `.arrow.start`, `.arrow.end`, `.label.start`, and
   `.label.end`;
 - elevation marker: `.outline`, `.pointer`, and `.label`;

python_cad_tools-0.1.10/docs/neutral-model.md

@@ -0,0 +1,138 @@
+# Neutral model reference
+
+This is the Tier 1 authoring reference: the `DesignElement`/`DesignModel`
+field semantics, the `IfcMapping` contract, the new Phase 1 capabilities
+(user properties, computed quantities, multiple storeys, openings, drawing
+dimensions), and the validator invocation model. See
+`docs/two-tier-contract.md` for what "Tier 1" means and
+`docs/public-api.md` for the full module allowlist.
+
+## `DesignElement` fields
+
+| Field | Type | Semantics |
+| --- | --- | --- |
+| `id` | `str` | Stable, unique identifier. Used to derive every downstream IFC `GlobalId` and to key manifests. |
+| `name` | `str` | Human-readable display name. |
+| `category` | `str` | Free-text classification, exported as `ObjectType` in IFC. |
+| `geometry` | `Any` | A build123d-compatible solid, shell, wire, or edge. Required and opaque — the framework does not restrict how it was built. |
+| `geometry_kind` | `"solid" \| "shell" \| "wire" \| "edge" \| "reference"` | Declares the geometry's topological kind. Physical elements must be `"solid"`. |
+| `placement` | `Placement` | Translation (mm) and rotation (degrees, XYZ) applied on top of `geometry`'s own coordinates. |
+| `dimensions` | `Dimensions` | Declared, author-stated extents. Independent of the geometry's actual bounds; exported into `Pset_PythonCadDesign`. |
+| `material` | `MaterialSpec \| None` | Required for physical elements. Drives IFC material association and quantity mass calculation (`density_kg_m3`). |
+| `color_rgb` | `Color \| None` | Overrides the material color for this element's rendering/styling. |
+| `ifc_mapping` | `IfcMapping` | See below. |
+| `storey` | `str \| None` | The `IfcBuildingStorey` this element belongs to. `None` means the framework's implicit "Default Storey". |
+| `tags` | `set[str]` | Free-text classification tags; not exported to any format. |
+| `properties` | `dict[str, Any]` | User properties. Exported to IFC as `Pset_PythonCadUser` for IFC-exported elements (see below). Values must be `str`, `bool`, `int`, or `float`. |
+| `children` | `list[DesignElement]` | Nested elements, walked depth-first by `DesignModel.walk()`. |
+| `visible` | `bool` | Excludes the element from every exporter when `False`. |
+| `export_formats` | `set[str]` | Which exporters (`step`, `ifc`, `glb`, `drawings`, `quantities`) include this element. |
+| `source_module` | `str` | Free-text provenance, exported into `Pset_PythonCadDesign`. |
+| `physical` | `bool` | Physical elements must be `"solid"` and require a material; non-physical (reference) elements are excluded from IFC, quantities, and mass. |
+| `parent_id` | `str \| None` | Parent element ID, exported as an `IfcRelAggregates` relationship when both ends are IFC-exported. |
+| `openings` | `list[Opening]` | Semantic voids in this host element. See "Openings" below. |
+
+## `IfcMapping`
+
+```python
+IfcMapping(ifc_class: str | None, predefined_type: str | None = None, exclude_reason: str | None = None)
+```
+
+Exactly one of `ifc_class` or `exclude_reason` must be set (enforced at
+`validate` time). `ifc_class` is validated live against the installed
+`ifcopenshell` IFC4 schema at export time: it must name a concrete (non-
+abstract) subtype of `IfcElement`, and `predefined_type` (default
+`"NOTDEFINED"`) must be a member of that class's declared `PredefinedType`
+enumeration. Any concrete `IfcElement` subtype is accepted — the framework
+does not restrict the mapping to a fixed list.
+
+## Openings
+
+```python
+Opening(id: str, geometry: Any, name: str | None = None, predefined_type: str | None = None)
+```
+
+An `Opening` on `DesignElement.openings` produces one `IfcOpeningElement` and
+one `IfcRelVoidsElement` per opening when the host is IFC-exported.
+`predefined_type` maps to `IfcOpeningElementTypeEnum` (`"OPENING"` or
+`"RECESS"`; defaults to `"OPENING"`).
+
+**Openings add IFC semantics only.** The host element's `geometry` stays
+authoritative for STEP, GLB, drawings, quantities, and bounds — the framework
+does not boolean-subtract an opening from the host tessellation. The
+supported authoring pattern is to cut the void from the host solid directly
+(`host_solid.cut(opening_solid)`, as `benge-property-cad/model.py` already
+does) and declare the same void as an `Opening` so IFC also carries the
+`IfcOpeningElement`/`IfcRelVoidsElement` pair. Declaring an opening without
+cutting the host geometry produces an IFC void that other formats do not
+reflect — do not do this for artifacts that need Tier 1 multi-format
+consistency.
+
+## IFC property sets and quantities
+
+Every IFC-exported element carries `Pset_PythonCadDesign`
+(`StableId`, `Category`, `SourceModule`, `GeometryKind`, and any declared
+dimensions) — unchanged from before this document existed, and the sole
+anchor the framework uses to identify its own authored elements.
+
+- **`Pset_PythonCadUser`** — present when `element.properties` is non-empty.
+  One `IfcPropertySingleValue` per entry, typed by Python type:
+  `bool → IfcBoolean`, `int → IfcInteger`, `float → IfcReal`,
+  `str → IfcLabel`. Any other value type is a `validate`-time error.
+- **`Qto_PythonCadDesign`** — an `IfcElementQuantity` present when the
+  element has a computed quantity record (the same records
+  `python-cad build`'s `quantities` exporter produces). Contains `Count`
+  (`IfcQuantityCount`), `NetSurfaceArea` (`IfcQuantityArea`, m²), `NetVolume`
+  (`IfcQuantityVolume`, m³), and — only when the element's material has a
+  density — `NetWeight` (`IfcQuantityWeight`, kg). Units convert from the
+  neutral model's mm/mm²/mm³ into the file's declared unit assignment, which
+  includes an explicit `MASSUNIT` (`KILO`/`GRAM`).
+
+`IfcOpeningElement` entities carry `Pset_PythonCadOpening`
+(`StableId`, `HostId`) instead of `Pset_PythonCadDesign`, so they are never
+mistaken for an authored design element by `_design_products` or by any
+sidecar reconciliation.
+
+## Storeys
+
+An element with `storey=None` is placed in the implicit "Default Storey"
+(stable ID `<model.id>.ifc.storey` — unchanged from before multi-storey
+support existed). An element with `storey="Some Name"` is placed in an
+`IfcBuildingStorey` named `"Some Name"`, created on demand, one per distinct
+declared name among IFC-exported elements. A model that declares no storey on
+any element produces byte-identical spatial structure to a single-storey
+model. Storey names must be non-empty text (validated).
+
+## Drawing dimensions
+
+`python_cad_tools.drawings.Dimension` is a public annotation primitive:
+
+```python
+Dimension(id: str, sheet_id: str, start: Point2, end: Point2, offset_mm: float, label: str, style: DrawingStyleToken)
+```
+
+It renders through the same verified annotation-entity pipeline as every
+other annotation primitive (`Line`, `Text`, `Table`, ...): it flattens into
+six identified child entities (dimension line, two extension/witness lines,
+two arrowheads, and a label), each carrying an `SVG data-annotation-id`, a DXF
+`PYTHON_CAD_TOOLS` XDATA tag, and an annotation-manifest record, so it
+round-trip verifies in SVG, DXF, and PDF like any other Tier 1 drawing
+annotation. The dimension line offsets perpendicular to the measured segment:
+in Y for a predominantly horizontal measurement, in X otherwise. The rendered
+DXF output is tagged geometry, not a native associative `DIMENSION` entity.
+
+## Validator invocation
+
+`validate_model(model)` runs the built-in element/model rules (stable IDs,
+geometry validity, material requirements, IFC mapping intent, storey names,
+user property types, opening identity/geometry) and then every callable in
+`DesignModel.validators` in list order, each receiving the model and
+returning a `list[ValidationIssue]`. `fatal_issues(...)` filters to
+`severity == "error"`; `python-cad build`/`validate` fail on any fatal issue
+before export begins.
+
+## Construction recipes (Phase 2)
+
+Parametric BREP/SweptSolid IFC representation via a construction-recipe model
+(`python_cad_tools.recipes`) is scoped as a separate SpecRepo proposal and is
+not yet implemented. This section will be extended when that proposal ships.

{python_cad_tools-0.1.9 → python_cad_tools-0.1.10}/docs/public-api.md

@@ -9,7 +9,8 @@ of optional runtime imports.
 
 - `python_cad_tools.context`: `BuildContext` and `DrawingContext`.
 - `python_cad_tools.elements`: `Color`, `GeometryKind`, `DesignElement`,
-  `DesignModel`, `Dimensions`, `IfcMapping`, `MaterialSpec`, and `Placement`.
+  `DesignModel`, `Dimensions`, `IfcMapping`, `MaterialSpec`, `Opening`, and
+  `Placement`.
 - `python_cad_tools.units`: `Length`, `Area`, `Volume`, `MM`, `INCH`, `FOOT`,
   `mm`, `inches`, `feet`, `feet_inches`, `to_mm`, `square_feet`, `cubic_feet`,
   `cubic_yards`, `metres`, and `square_metres`.
@@ -17,7 +18,7 @@ of optional runtime imports.
   `prism_between`, `sloped_pool`, `bounds`, `combined_bounds`, `tessellate`,
   `is_valid_solid`, and `diagonal`.
 - `python_cad_tools.drawings`: `Point2`, `Direction`, `DrawingStyleToken`,
-  `DrawingSheet`, `Line`, `Polyline`, `Text`, `SectionCallout`,
+  `DrawingSheet`, `Line`, `Polyline`, `Text`, `Dimension`, `SectionCallout`,
   `ElevationMarker`, `TableRow`, `Table`, `SheetAnnotations`, and
   `DrawingAnnotationSet`.
 - `python_cad_tools.validation`: `ValidationIssue`.
@@ -35,6 +36,12 @@ of optional runtime imports.
 flattened compound entities, file writers, and drawing validators remain
 private. See [Format-neutral drawing extensions](drawing-extensions.md).
 
+Python CAD Tools distinguishes Tier 1 (verified authoring through this public
+API) from Tier 2 (supported, unverified direct use of a library named in
+`docs/toolchain.md`). See [The two-tier authoring
+contract](two-tier-contract.md) and the full field reference in
+[Neutral model reference](neutral-model.md).
+
 Every public type is inline-typed and the wheel includes `py.typed`. Public
 module `__all__` values are tested as allowlists. Exporter implementations,
 `_project_loader`, `_project_state`, renderer code, staging helpers, and other

python_cad_tools-0.1.10/docs/toolchain.md

@@ -0,0 +1,102 @@
+# Curated toolchain
+
+Python CAD Tools curates a validated engineering ecosystem rather than
+recreating the APIs of mature open-source CAD, BIM, geometry, and mesh
+libraries. This document is the supported-library reference and the
+dependency license policy. `tests/packaging/test_toolchain.py` asserts this
+table against `pyproject.toml` metadata, so a pin change without a matching
+doc change fails the test suite.
+
+## Install
+
+```
+pip install "python-cad-tools[all]"
+```
+
+Capability-based extras install only the libraries a project needs:
+
+```
+python-cad-tools[cad]            # build123d, cadquery-ocp-novtk
+python-cad-tools[bim]            # ifcopenshell
+python-cad-tools[mesh]           # trimesh, numpy
+python-cad-tools[drawings]       # ezdxf, reportlab, pypdf
+python-cad-tools[engineering]    # shapely, manifold3d, meshio
+python-cad-tools[visualization]  # reserved; see below
+python-cad-tools[all]            # every capability group
+```
+
+**The Tier 1 verified stack (`cad`, `bim`, `mesh`, `drawings`) stays in
+`[project.dependencies]`.** A plain `pip install python-cad-tools` already
+installs those eight packages; the four extras restate the same pins so the
+capability-to-library map is explicit and testable. This keeps the
+`build_project` multi-format-consistency guarantee (STEP, IFC, GLB, drawings,
+quantities from one model, cross-verified) unconditional on install shape.
+`engineering` and `visualization` add libraries beyond what `build_project`
+itself uses today; they exist for Tier 2 (direct library) use. A future major
+version may move the core Tier 1 packages behind extras as a metadata-only
+change — the extras names would not change.
+
+See `docs/two-tier-contract.md` for what "Tier 1" and "Tier 2" mean.
+
+## Supported libraries
+
+| Library | Version range | Capability group | License | Notes |
+| --- | --- | --- | --- | --- |
+| `build123d` | `>=0.11.1,<0.12` | `cad` | Apache-2.0 | Tier 1 solid modeling kernel API. |
+| `cadquery-ocp-novtk` | `>=7.9.3.1.1,<7.10` | `cad` | Apache-2.0 | OCCT/OCP bindings built without VTK, to keep the default build GUI-free. |
+| `ifcopenshell` | `>=0.8.5,<0.9` | `bim` | LGPL-3.0-or-later | IFC4 authoring, schema validation, and round-trip reload. |
+| `trimesh` | `>=4.12,<5` | `mesh` | MIT | GLB export and mesh inspection. |
+| `numpy` | `>=2.3,<3` | `mesh` | BSD-3-Clause | Numeric array support for geometry and mesh code. |
+| `ezdxf` | `>=1.4,<2` | `drawings` | MIT | DXF authoring and round-trip reload. |
+| `reportlab` | `>=4.4,<5` | `drawings` | BSD (ReportLab license) | PDF authoring. |
+| `pypdf` | `>=6,<7` | `drawings` | BSD-3-Clause | PDF page-count and text-extraction verification. |
+| `shapely` | `>=2.1,<3` | `engineering` | BSD-3-Clause | 2D geometry and topology for Tier 2 post-processing. |
+| `manifold3d` | `>=3,<4` | `engineering` | Apache-2.0 | Robust mesh boolean operations for Tier 2 post-processing. |
+| `meshio` | `>=5.3,<6` | `engineering` | MIT | Mesh format interchange for Tier 2 post-processing. |
+
+`visualization` currently ships with no packages (see below).
+
+## License policy
+
+- **Allowed** in any shipped capability group, including `all`: Apache-2.0,
+  MIT, BSD-2/3-Clause, ISC, PSF, and LGPL where the dependency is consumed as
+  a separately-distributed library (as `ifcopenshell` is here).
+- **Not allowed** as a required dependency of any shipped group: GPL-only and
+  AGPL-only distributions. Such a library may still be documented as usable at
+  Tier 2 by a downstream project that chooses to depend on it directly, but
+  the framework never installs it.
+- The framework's own license is **AGPL-3.0-only** and is unaffected by this
+  policy — the policy governs dependencies only.
+- Adding a supported library requires, in the same change: a row in the table
+  above, coverage in the CI compatibility matrix (`toolchain-matrix` in
+  `.github/workflows/ci.yml`), and an import/interop assertion.
+
+## Evaluated and deferred
+
+- **CadQuery.** CadQuery depends on `cadquery-ocp`, which conflicts with the
+  deliberately VTK-free `cadquery-ocp-novtk` build this framework pins for
+  `cad`. Admitting CadQuery would duplicate or displace the pinned OCCT
+  distribution. Not added.
+- **PyVista (the `visualization` group).** PyVista (MIT) and VTK (BSD-3) are
+  license-compatible, but two constraints apply: the framework pins
+  `cadquery-ocp-novtk` specifically to avoid VTK, and the default build must
+  never import or invoke a GUI. `visualization` ships only once the CI
+  compatibility matrix proves `pip install '.[all]'` resolves, `pip check`
+  passes, and a full `build_project` completes with no `vtk*`/`pyvista`
+  module present in `sys.modules`. Until then, `visualization` is a
+  documented empty placeholder group — the name is reserved so no downstream
+  install command has to change if it is admitted later.
+
+## Compatibility verification
+
+The `toolchain-matrix` CI job (`.github/workflows/ci.yml`) installs every
+capability group across `{ubuntu-latest, macos-latest} × {3.12, 3.13}`, runs
+`pip check`, imports every library the group declares, and — for `all` — runs
+a Tier-2 interop smoke (a shape crosses build123d → `geometry.tessellate` →
+trimesh → ifcopenshell read-back → ezdxf) plus the no-GUI assertion. It
+publishes `toolchain-compatibility.json` as a CI artifact recording resolved
+versions and pass/fail per library and cell.
+
+This job answers the "does it install and interoperate" question for Tier 2.
+It does not verify artifact determinism — that is a Tier 1 guarantee proven by
+`build_project` and `verify_build_output`, not by the toolchain matrix.

python_cad_tools-0.1.10/docs/two-tier-contract.md

@@ -0,0 +1,51 @@
+# The two-tier authoring contract
+
+Python CAD Tools is a curated engineering platform, not a wrapper around every
+API of every supported library. It defines a clear boundary between two ways a
+downstream project can use it.
+
+## Tier 1 — verified authoring
+
+A project authors a `DesignModel` of `DesignElement` values using documented
+fields (see `docs/neutral-model.md`) and builds through `build_project`. The
+framework guarantees, for the selected formats:
+
+- **Deterministic output.** The same model produces byte-identical artifacts.
+- **Manifest hashing.** Every build emits a schema-versioned design manifest
+  with a `semantic_hash` and a build manifest with an `artifact_set_hash`.
+- **Round-trip verification.** Every exported format is reloaded and checked
+  against the model it was built from (stable IDs, storeys, user properties,
+  quantities, openings, drawing annotation identity — see the exporter-specific
+  sections of `docs/neutral-model.md`).
+- **Multi-format consistency.** STEP, IFC, GLB, drawings, and quantities all
+  derive from one model and are cross-reconciled by `verify_build_output`.
+
+## Tier 2 — supported, unverified direct library access
+
+A project directly imports a supported library (`ifcopenshell`, `trimesh`,
+`ezdxf`, `build123d`, `shapely`, etc. — see `docs/toolchain.md`) to read,
+query, validate, or post-process. The framework guarantees the library
+installs, imports, and interoperates with the rest of the pinned stack on
+every supported platform/Python combination (verified by the
+`toolchain-matrix` CI job). It guarantees **nothing** about artifacts a project
+authors outside `build_project`: no determinism, no manifest coverage, no
+round-trip, no multi-format consistency.
+
+This is already the lived pattern for consumption — downstream projects
+already `import ifcopenshell` to read and assert on generated IFC. This
+document makes it explicit and names its boundary.
+
+## The extension rule
+
+When Tier 1 lacks a capability a project needs, the path is a SpecRepo request
+against the neutral model — not a silent bypass to Tier 2 for an artifact that
+needs verification. Tier 2 is for reading, querying, validating, and
+post-processing; it is not a substitute authoring path for artifacts that need
+Tier 1 guarantees.
+
+## Downstream agent governance
+
+Downstream project agent governance (`AGENTS.md`, `opencode.jsonc`) states
+which tier each agent's responsibilities fall into, so an agent understands
+its boundary without re-deriving it from source. See each sister repository's
+`AGENTS.md` "Authoring tiers" section.