Burr

Burr is design-rule checking for CAD-as-code.

It gives agents and humans a hard feedback loop before a part becomes a print:

design file -> generated part -> burr-design-data.json -> Burr checks -> receipt

Burr does not design the part. It verifies declared mechanical intent against metadata, dimensions, source/artifact freshness, and STEP geometry evidence.

Why

CAD agents can make parts that look plausible while hiding bad edge distances, missing holes, stale STEP exports, or decorative holes that should not be judged as fastener interfaces. Image review helps, but it cannot reliably prove those facts.

Burr turns CAD work into measurable receipts:

M3 loaded mounting hole
measured center-to-edge = 8.0 mm
required center-to-edge = 10.2 mm
result = fail by 2.2 mm

Then burr explain turns the receipt into fix guidance:

Feature: m3_lower_left
Problem: the loaded M3 hole is too close to a free edge.
Why it matters: thin edge material can crack, delaminate, or fail.
Fix: move the hole inward or make the surrounding part larger.

Quickstart

Install from crates.io:

cargo install burr --version 0.13.1

Create and check a build123d starter part:

burr init my-part
cd my-part
uv run python design.py
burr check .
burr explain .

The generated starter installs burr-build123d==0.8.0 from PyPI.

To prove the published install path from this repo:

npm run check:fresh-install

The fresh-install check also proves the starter failure-to-fix loop: move the M3 hole too close to the side edge, fail edge distance, explain the measured problem, restore the hole, and pass again.

Product Loop

Use Burr like tests for generated mechanical parts:

write or generate CAD
  -> emit burr-design-data.json with intended features
  -> export STEP
  -> burr check .
  -> burr explain .
  -> fix CAD or metadata

Burr is not a constraint solver, FEA engine, slicer, or universal CAD brain. It checks specific declared mechanical claims. Workload/stress survival belongs to later FEA/FEM or physical testing.

Local Development

npm install
uv sync --all-packages
npm run check

Run the build123d adapter examples:

uv sync --all-packages
npm run check:build123d

Run the optional OpenCascade STEP backend proof:

uv sync --all-packages
npm run check:ocp

Run the mixed-intent CAD proof:

uv sync --all-packages
npm run check:mixed-intent

Run the counterbore CAD proof:

uv sync --all-packages
npm run check:counterbore

Run the straight-slot CAD proof:

uv sync --all-packages
npm run check:slots

Run the printable example gallery:

uv sync --all-packages
npm run check:gallery
npm run gallery:render
npm run gallery:artifact

The build123d examples and gallery commit only source and docs. STEP files, burr-design-data.json, receipts, and preview PNGs are generated by the example scripts and ignored by git. Preview PNGs are visual review artifacts; Burr receipts remain the verifier.

For website or release use, npm run gallery:artifact writes a versioned bundle:

artifacts/releases/burr-gallery-v<version>/
artifacts/releases/burr-gallery-v<version>.zip

The bundle contains PNG previews, passing Burr receipts, stamped design data, and a manifest. Burr owns these generated proof artifacts; websites should consume the zip or GitHub release asset read-only instead of regenerating CAD. See docs/fray-website-contract.md for the website ingestion contract.

Start a build123d part:

burr init my-part
cd my-part
uv run python design.py
burr check .

Commands

burr --version
burr init <folder>
burr check <folder|burr-design-data.json>...
burr explain <folder|burr-receipt.json>...
burr stamp <folder|burr-design-data.json>...

init creates a minimal build123d project with design.py, pyproject.toml, and .gitignore. The generated project depends on burr-build123d==0.8.0 from PyPI.

check finds burr-design-data.json, runs freshness checks and rulepack checks, then writes burr-receipt.json beside each design data file.

explain reads burr-receipt.json and expands failed checks into plain feature/rule/problem/evidence/why/fix output.

stamp computes sha256 and size_bytes for declared source and generated artifact files.

Build123d Helper

Burr does not replace build123d. The optional helper records design data while your normal build123d file creates geometry.

from build123d import Box, BuildPart, Locations, export_step
from burr_build123d import BurrDesignData, DESIGN_DATA_FILE, m3_clearance_hole

design = BurrDesignData(
    artifact_id="my-actuator",
    artifact_type="actuator_mount",
    process={"kind": "FDM", "material": "PETG", "nozzle_mm": 0.4},
)
design.source("design.py")
design.artifact("actuator.step")
design.part("housing", bbox_min=(-42, -16, 0), bbox_max=(42, 16, 26))

with BuildPart() as housing:
    with Locations((0, 0, 13)):
        Box(84, 32, 26)

    m3_clearance_hole(
        design,
        feature_id="m3_lower_left",
        part="housing",
        center=(39.5, -8, 8),
        axis=(1, 0, 0),
        role="loaded_mount",
    )

export_step(housing.part, "actuator.step")
design.write(DESIGN_DATA_FILE)

That one helper call cuts the hole in build123d and records the feature Burr checks. Burr core still reads only burr-design-data.json, so other CAD tools can use the same contract.

For custom rulepacks and non-standard features, the helper can emit plain Burr metadata without a specialized geometry helper:

design.rulepack("../../../rules/captured_slider.rulepack.json")
design.measurements_update({
    "head_side_clearance_mm": 0.25,
    "carriage_lip_each_side_mm": 3.5,
})
design.feature(
    feature_id="left_capture_lip",
    kind="capture_lip",
    part="carriage",
    role="lift_off_blocker",
    engagement_mm=3.5,
)

Design Data

A lintable CAD artifact folder contains burr-design-data.json.

This file is the language-agnostic contract. It can be emitted by build123d, CadQuery, OpenSCAD, JavaScript CAD, Rust CAD, Fusion scripts, or any tool that can write JSON.

{
  "schema_version": "burr.design-data.v1",
  "artifact_id": "linear-actuator-bad",
  "artifact_version": "0.1.0",
  "artifact_type": "actuator_mount",
  "units": "mm",
  "source": {
    "path": "source.py",
    "sha256": "..."
  },
  "artifacts": [
    {
      "kind": "step",
      "path": "actuator.step",
      "sha256": "..."
    }
  ],
  "parts": [
    {
      "id": "housing",
      "bbox_mm": {
        "min": [-42, -16, 0],
        "max": [42, 16, 26]
      }
    }
  ],
  "features": [
    {
      "id": "m3_lower_left",
      "part": "housing",
      "kind": "clearance_hole",
      "intent": "mechanical_interface",
      "fastener": "M3",
      "diameter_mm": 3.4,
      "center_mm": [39.5, -8, 8],
      "axis": [1, 0, 0],
      "role": "loaded_mount"
    }
  ]
}

Declared Feature Intent

Burr does not infer that every cylinder or hole in a STEP file is mechanically important. A STEP file may contain vents, lightening holes, fluid passages, cosmetic cuts, construction reliefs, bosses, fillets, and unrelated round faces.

Burr judges only features that are declared in burr-design-data.json and selected by the active rulepack. Use intent to separate mechanical interfaces from incidental geometry:

mechanical_interface  -> judged by mechanical rulepacks
weight_reduction      -> declared if useful, but not judged by actuator rules
fluid_or_air_path     -> separate rules, not screw-mount rules
manufacturing_feature -> process-specific rules only
cosmetic              -> normally unjudged

For legacy design data, missing intent is treated as mechanical_interface. Set intent explicitly when a declared feature should not be judged by mechanical rulepacks.

Rulepacks

The included actuator mount rulepack checks loaded M3 clearance-hole edge distance, minimum wall thickness around M3 clearance holes, whether declared M3 clearance holes exist as matching cylindrical geometry in the exported STEP, and whether declared straight slots, counterbores, heat-set insert pockets, and bearing seats exist as matching STEP cylinder/plane evidence:

{
  "schema_version": "burr.rulepack.v1",
  "id": "actuator_mount",
  "version": "0.8.0",
  "rules": [
    {
      "id": "m3_loaded_hole_edge_distance",
      "kind": "hole_edge_distance",
      "applies_to": {
        "kind": "clearance_hole",
        "fastener": "M3",
        "intent_any": ["mechanical_interface"],
        "role_any": ["loaded_mount", "mount", "housing_mount"]
      },
      "min_center_to_edge_diameter_multiple": 3.0
    },
    {
      "id": "m3_clearance_hole_wall_thickness",
      "kind": "minimum_wall_thickness",
      "applies_to": {
        "kind": "clearance_hole",
        "fastener": "M3",
        "intent_any": ["mechanical_interface"]
      },
      "min_wall_thickness_mm": 2.0
    },
    {
      "id": "m3_clearance_hole_step_presence",
      "kind": "feature_presence",
      "applies_to": {
        "kind": "clearance_hole",
        "fastener": "M3",
        "intent_any": ["mechanical_interface"]
      },
      "artifact_kind": "step",
      "diameter_tolerance_mm": 0.05,
      "centerline_tolerance_mm": 0.25,
      "axis_dot_min": 0.99
    },
    {
      "id": "straight_slot_step_presence",
      "kind": "feature_presence",
      "applies_to": {
        "kind": "straight_slot",
        "intent_any": ["mechanical_interface"]
      },
      "artifact_kind": "step",
      "width_tolerance_mm": 0.05,
      "endpoint_tolerance_mm": 0.25,
      "side_plane_tolerance_mm": 0.25,
      "axis_dot_min": 0.99
    },
    {
      "id": "counterbore_step_presence",
      "kind": "feature_presence",
      "applies_to": {
        "kind": "counterbore",
        "intent_any": ["mechanical_interface"]
      },
      "artifact_kind": "step",
      "bore_diameter_tolerance_mm": 0.05,
      "counterbore_diameter_tolerance_mm": 0.05,
      "centerline_tolerance_mm": 0.25,
      "counterbore_center_tolerance_mm": 0.5,
      "shoulder_plane_tolerance_mm": 0.25,
      "axis_dot_min": 0.99
    },
    {
      "id": "heat_set_insert_pocket_step_presence",
      "kind": "feature_presence",
      "applies_to": {
        "kind": "heat_set_insert_pocket",
        "intent_any": ["mechanical_interface"]
      },
      "artifact_kind": "step",
      "pocket_diameter_tolerance_mm": 0.05,
      "centerline_tolerance_mm": 0.25,
      "pocket_center_tolerance_mm": 0.5,
      "bottom_plane_tolerance_mm": 0.25,
      "axis_dot_min": 0.99
    },
    {
      "id": "bearing_seat_step_presence",
      "kind": "feature_presence",
      "applies_to": {
        "kind": "bearing_seat",
        "intent_any": ["mechanical_interface"]
      },
      "artifact_kind": "step",
      "seat_diameter_tolerance_mm": 0.05,
      "centerline_tolerance_mm": 0.25,
      "seat_center_tolerance_mm": 0.5,
      "shoulder_plane_tolerance_mm": 0.25,
      "axis_dot_min": 0.99
    }
  ]
}

Design data can also choose a rulepack beside the artifact:

{
  "schema_version": "burr.design-data.v1",
  "artifact_type": "captured_slider",
  "rulepack": { "path": "../../../rules/captured_slider.rulepack.json" }
}

The CLI --rulepack <file> flag still overrides this when you want to run a different rulepack against the same artifact.

Supported rule kinds include:

hole_edge_distance       -> feature center is far enough from a free edge
minimum_wall_thickness   -> enough material remains around a declared hole
feature_presence         -> declared feature has matching STEP evidence
feature_count            -> enough matching declared features exist
numeric_range            -> declared measurement is inside an allowed range

feature_count and numeric_range are useful for parts that are not mostly mechanical interfaces: dense plates, captured sliders, clearance windows, and other cases where the source emits measurements Burr can check directly.

Versioning

Burr has three versioned surfaces:

Burr package version       -> CLI/library behavior
Design data schema version -> JSON shape Burr can read
Rulepack schema version    -> rule syntax Burr can execute

Receipts include all three:

{
  "schema_version": "burr.receipt.v1",
  "burr_version": "0.13.1",
  "artifact_version": "0.1.0",
  "rulepack_version": "0.8.0",
  "compatibility": {
    "design_data_schema_version": "burr.design-data.v1",
    "rulepack_schema_version": "burr.rulepack.v1"
  }
}

Unsupported design data or rulepack schemas fail lint instead of silently producing untrustworthy receipts.

Legacy fray-cad.json files with schema fray.cad.artifact.v1 are still read for transition, but new integrations should emit burr-design-data.json.

Example Result

Bad actuator:

FAIL examples/build123d-actuator/bad/burr-design-data.json -> <not written>

1 problem:
1. M3 loaded hole m3_lower_left is too close to the edge.
   Measured center-to-edge: 8 mm
   Required center-to-edge: 10.2 mm
   Short by: 2.2 mm
   Try moving the hole inward or increasing the surrounding part size.

Fixed actuator:

{
  "status": "pass",
  "measured": {
    "center_to_edge_mm": 12,
    "wall_to_edge_mm": 10.3
  },
  "required": {
    "center_to_edge_mm": 10.2,
    "wall_to_edge_mm": 8.5
  },
  "margin_mm": 1.8
}

Thin wall fixture:

FAIL examples/build123d-wall-thickness/bad/burr-design-data.json -> <not written>

1 problem:
1. M3 clearance hole m3_alignment leaves too little wall.
   Measured wall thickness: 1.2 mm
   Required wall thickness: 2 mm
   Short by: 0.8 mm
   Try moving the hole inward or increasing part width.

Missing STEP feature fixture:

FAIL examples/build123d-step-presence/bad/burr-design-data.json -> <not written>

1 problem:
1. Declared clearance hole m3_claimed is missing from the STEP artifact.
   Checked artifact: presence.step
   Candidate cylinders found: 0
   Regenerate the STEP from the same helper that emitted the design data.

Candidate cylinders found and Candidate planes found are not counts of failed features. They are the STEP faces Burr considered while trying to prove one declared feature. Extra faces are ignored unless a rulepack selects matching declared intent and the geometry fits the declared tolerances.

Status

Early prototype. Current checks combine design-data rules with narrow STEP feature-presence verification for declared M3 clearance holes, declared straight slots, declared counterbores, declared heat-set insert pockets, and declared bearing seats. Burr does not classify all holes, slots, counterbores, pockets, or seats in a model or decide which features matter.

By default, the Rust CLI reads simple analytic STEP cylinder entities directly. For stronger local verification, install the optional Python/OCP workspace and run with:

BURR_STEP_CYLINDER_BACKEND=ocp \
BURR_OCP_STEP_CYLINDERS="uv run --package burr-ocp burr-ocp-step-cylinders" \
burr check .

The OCP helper extracts measured cylinder and plane candidates. Burr still owns rule matching, diagnostics, and receipts.