Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,91 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM --platform=linux/amd64 ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=cadforge
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# # Explicitly install scipy if it's missing (workaround for dependency resolution issues)
+# RUN /app/env/.venv/bin/pip install scipy>=1.10.0
+
+# Final runtime stage
+FROM --platform=linux/amd64 ${BASE_IMAGE}
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        libgl1 libglib2.0-0 libxrender1 libxext6 libx11-6 \
+        libsm6 libice6 libxmu6 libxi6 libgomp1 && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+ENV ENABLE_WEB_INTERFACE=true
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -1,10 +1,212 @@
 ---
-title: Cadforge
-emoji: 🌍
-colorFrom: indigo
-colorTo: pink
+title: CAD Forge Environment Server
+emoji: 🔩
+colorFrom: blue
+colorTo: indigo
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# CadForge
+
+A multi-step RL environment built on the [OpenEnv](https://github.com/facebookresearch/openenv) framework where an LLM agent writes CadQuery (Python CAD) code to produce 3D geometry matching a ground truth target.
+
+## Overview
+
+CadForge presents the agent with a natural-language description of a 3D mechanical part (e.g. "Create a hollow tube with outer diameter 40mm, inner diameter 30mm, height 60mm"). The agent iteratively writes CadQuery code, receives geometric feedback, and refines its design. The reward measures how closely the agent's shape matches the reference geometry using volumetric (IoU), surface (Chamfer Distance), and property-based metrics.
+
+## Architecture
+
+```
+cadforge/
+├── client.py                  # CadforgeEnv client wrapper
+├── models.py                  # CadforgeAction / CadforgeObservation (Pydantic)
+├── openenv.yaml               # OpenEnv manifest
+├── pyproject.toml             # Dependencies and build config
+├── requirements.txt           # Pip-installable dependencies
+├── verify_all_tasks.py        # End-to-end verification script
+├── scripts/
+│   ├── generate_ground_truth.py   # Generate GT data for all tasks
+│   ├── verify_reference_codes.py  # Phase 1: verify all reference codes execute
+│   └── verify_rewards.py         # Phase 2: verify reward pipeline (ref code = high score)
+└── server/
+    ├── app.py                 # FastAPI application (HTTP + WebSocket)
+    ├── cadforge_environment.py# Core environment: reset(), step(), GEOMETRY_RUNNER
+    ├── docs_search.py         # CadQuery documentation search for agent
+    ├── executor.py            # Sandboxed CadQuery code execution (subprocess)
+    ├── geometry.py            # Property extraction (faces, volume, euler, holes)
+    ├── preprocessor.py        # Ground truth generation, voxelization, surface sampling
+    ├── reward.py              # Reward rubrics: Rexec, Rgeom (IoU+CD), Reval
+    ├── docs/                  # CadQuery documentation for agent read_docs action
+    └── tasks/
+        ├── task_001_flat_plate/   # Each task has: task.json, reference_code.py, GT data
+        ├── task_002_box_with_hole/
+        ├── ...
+        └── task_020_dovetail_block/
+```
+
+## Tasks (20 total)
+
+| # | Task | Key Features |
+|---|------|-------------|
+| 001 | Flat Plate | Simple box, 6 planar faces |
+| 002 | Box with Hole | Through-hole, boolean cut |
+| 003 | Cylinder Shaft | Revolve, cylindrical faces |
+| 004 | L-Bracket | Extrude + union, 8 faces |
+| 005 | Stepped Shaft | Multi-diameter revolve |
+| 006 | Hollow Tube | Shell / boolean subtract |
+| 007 | Plate with Four Holes | Array of cuts |
+| 008 | Flange Disc | Concentric features |
+| 009 | Hexagonal Prism | Polygon extrude |
+| 010 | Counterbore Box | Multi-depth cuts |
+| 011 | T-Bracket | Multi-body union |
+| 012 | Chamfered Block | Edge chamfers |
+| 013 | Filleted Box | Edge fillets, through-hole |
+| 014 | Bushing | Thick-wall tube |
+| 015 | U-Channel | Extrude profile |
+| 016 | Cone | Loft / revolve |
+| 017 | Plate with Slot | Slot cut |
+| 018 | Sphere | Full revolve |
+| 019 | Bolt Flange | Circular bolt pattern |
+| 020 | Dovetail Block | Angled extrude |
+
+## Reward Structure
+
+```
+R = Rexec_gate x (0.70 x Rgeom + 0.30 x Reval)
+```
+
+### Rexec (Gate)
+Binary gate: code must execute, produce a valid shape with positive volume.
+
+### Rgeom (Geometric Similarity) — weight 0.70
+- **IoU (best-of-6 rotations)**: 60% — voxel grid overlap at 64^3
+- **Mean Chamfer Distance**: 20% — average nearest-point distance (2048 surface points)
+- **Median Chamfer Distance**: 20% — robust to outliers
+
+Chamfer Distance can be toggled via `ENABLE_CHAMFER_DISTANCE` flag.
+
+### Reval (Property Evaluation) — weight 0.30
+- **Volume similarity**: 35% — min/max ratio
+- **Bounding box aspect ratio**: 30% — sorted dimension comparison
+- **Dominant face type match**: 15% — PLANE vs CYLINDER vs CONE etc.
+- **Euler characteristic match**: 20% — topological invariant
+
+## Voxelization Pipeline
+
+Shapes are voxelized at 64^3 resolution using:
+1. OCC tessellation (`BRepMesh_IncrementalMesh`) to extract triangle mesh
+2. `trimesh.Trimesh` construction with `process=True` + `fix_normals()`
+3. `trimesh.contains()` for vectorized ray-cast point-in-solid test
+4. Backed by **Embree** (Intel's ray tracing kernel) for ~130ms per shape
+
+### Normalization
+Both ground truth and agent shapes are normalized before comparison:
+1. Center at origin
+2. Align longest axis to X, second to Y, shortest to Z
+
+Original (unnormalized) STEP files are preserved as `ground_truth.step`.
+
+## Ground Truth Data (per task)
+
+Each task directory contains:
+- `task.json` — prompt, metadata, difficulty
+- `reference_code.py` — canonical CadQuery solution
+- `ground_truth.json` — properties (volume, bbox, face counts, euler, etc.)
+- `ground_truth.step` — original STEP geometry
+- `ground_truth_normalized.step` — normalized STEP geometry
+- `surface_points.npy` — 2048 surface sample points (normalized frame)
+- `voxels_64.npy` — 64^3 boolean voxel grid (normalized frame)
+
+## Verification Pipeline
+
+Three-phase verification ensures correctness:
+
+```bash
+# Phase 1: All reference codes execute and produce valid shapes
+python scripts/verify_reference_codes.py
+
+# Ground truth generation
+python scripts/generate_ground_truth.py
+
+# Phase 2: Reference code achieves high reward against its own GT
+python scripts/verify_rewards.py
+```
+
+**Latest results**: 20/20 PASS on all phases (rewards 0.954–0.976).
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+Key dependencies:
+- **cadquery** >= 2.4.0 — parametric 3D CAD (wraps OpenCASCADE)
+- **trimesh** >= 4.0.0 — mesh operations
+- **embreex** >= 4.0.0 — Embree ray tracing (makes trimesh.contains() fast)
+- **scipy** >= 1.10.0 — cKDTree for Chamfer Distance
+- **numpy** >= 1.24.0
+- **networkx** >= 3.0.0 — required by trimesh for mesh repair
+- **pydantic** >= 2.0.0 — action/observation models
+- **openenv-core** >= 0.2.2 — OpenEnv framework
+
+## Development Notes: What We Tried
+
+### Voxelization Approaches (chronological)
+
+1. **OCC `BRepClass3d_SolidClassifier` at 64^3** (first implementation)
+   - Pure Python triple loop, 262K OCC calls per shape
+   - Accurate but catastrophically slow: 2–191s per shape (cone worst case)
+   - **Abandoned** due to speed
+
+2. **trimesh `.voxelized(pitch).fill()`** (second attempt)
+   - Fast for simple solids (0.05–0.3s) but slow for hollow/complex shapes (5–25s)
+   - `.fill()` uses flood-fill which breaks on non-watertight OCC tessellations
+   - **Abandoned** due to inconsistent performance on hollow shapes
+
+3. **STL export -> trimesh load -> `.voxelized().fill()`**
+   - CQ's STL export produces watertight meshes, solving the fill problem
+   - Still slow for some shapes due to trimesh's Python flood-fill internals
+   - **Abandoned** — marginal improvement
+
+4. **OCC SolidClassifier at 32^3 + scipy zoom to 64^3** (attempted optimization)
+   - 8x fewer points, ~0.5s uniform across shapes
+   - Explored but superseded by embree solution
+   - **Not used** — embree was faster
+
+5. **trimesh `.contains()` without embree**
+   - Vectorized ray-cast, should have been fast
+   - Without embree: falls back to pure-Python ray-triangle test
+   - 4–70s per shape — **worse than OCC loop**
+
+6. **trimesh `.contains()` + embreex** (current, final)
+   - Embree provides C++ SIMD ray tracing kernel
+   - ~15–20ms at 32^3, ~100–140ms at 64^3, uniform across all shapes
+   - Handles non-watertight meshes via winding-number ray parity
+   - **Winner** — 1000x faster than original OCC loop
+
+### Hole Detection
+
+- Attempted automated through-hole detection via cylindrical face analysis
+- Used `BRepAdaptor_Surface` to get cylinder radius, compared height to bounding box
+- 10/20 tasks had incorrect counts (outer cylindrical surfaces falsely detected as holes)
+- **Removed from reward** — not reliable enough. Kept in `geometry.py` for informational purposes but not scored.
+
+### Reward Metrics Removed
+
+- **frame_score**: Compared orientation alignment — redundant after normalization (both sides aligned)
+- **hole_count**: Removed due to unreliable detection (see above)
+- **param_score**: Dimension-matching metric — redundant with bbox aspect ratio comparison
+- **face_count_ratio**: Risky — different valid CAD approaches can produce different face counts
+- **IoU canonical** in Reval: Redundant with Rgeom's best-of-6 IoU
+
+### OCP API Gotchas
+
+- `TopExp_Explorer.Current()` returns `TopoDS_Shape`, not `TopoDS_Face` — must downcast with `TopoDS.Face_s()`
+- CadQuery v2.7.0 `Face` objects don't have `.Surface()` — use `BRepAdaptor_Surface(TopoDS.Face_s(f.wrapped))` instead
+- `BRep_Tool.Triangulation_s()` requires `TopoDS_Face`, not generic `TopoDS_Shape`

__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Cadforge Environment."""
+
+from .client import CadforgeEnv
+from .models import CadforgeAction, CadforgeObservation
+
+__all__ = [
+    "CadforgeAction",
+    "CadforgeObservation",
+    "CadforgeEnv",
+]

client.py

@@ -0,0 +1,50 @@
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+
+try:
+    from .models import CadforgeAction, CadforgeObservation
+except ImportError:
+    from models import CadforgeAction, CadforgeObservation
+
+
+class CadforgeEnv(
+    EnvClient[CadforgeAction, CadforgeObservation, State]
+):
+    def _step_payload(self, action: CadforgeAction) -> Dict:
+        return {
+            "action_type": action.action_type,
+            "params": action.params,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[CadforgeObservation]:
+        obs_data = payload.get("observation", {})
+        observation = CadforgeObservation(
+            task=obs_data.get("task"),
+            step_count=obs_data.get("step_count", 0),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            docs_results=obs_data.get("docs_results"),
+            code_executed=obs_data.get("code_executed"),
+            code_error=obs_data.get("code_error"),
+            object_id=obs_data.get("object_id"),
+            object_properties=obs_data.get("object_properties"),
+            artifacts=obs_data.get("artifacts"),
+            last_executed=obs_data.get("last_executed"),
+            image_path=obs_data.get("image_path"),
+            metadata=obs_data.get("metadata", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> State:
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

inference.py

@@ -0,0 +1,734 @@
+import asyncio
+import json
+import os
+import re
+import textwrap
+import time
+from typing import Dict, List, Optional
+
+from openai import OpenAI
+
+from client import CadforgeEnv
+from models import CadforgeAction
+
+API_BASE_URL = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "Qwen/Qwen2.5-7B-Instruct")  # Qwen/Qwen2.5-72B-Instruct
+HF_TOKEN = os.getenv("HF_TOKEN")
+LOCAL_IMAGE_NAME = os.getenv("LOCAL_IMAGE_NAME")
+
+BENCHMARK = "cadforge"
+TASKS = [
+    "task_001_flat_plate",
+    "task_002_box_with_hole",
+    "task_003_cylinder_shaft",
+    "task_004_l_bracket",
+    "task_005_stepped_shaft",
+    "task_006_hollow_tube",
+    "task_007_plate_four_holes",
+    "task_008_flange_disc",
+    "task_009_hexagonal_prism",
+    "task_010_counterbore_box",
+    "task_011_t_bracket",
+    "task_012_chamfered_block",
+    "task_013_filleted_box",
+    "task_014_bushing",
+    "task_015_u_channel",
+    "task_016_cone",
+    "task_017_plate_with_slot",
+    "task_018_sphere",
+    "task_019_bolt_flange",
+    "task_020_dovetail_block",
+    "task_021_hf_317",
+    "task_022_hf_711",
+    "task_023_hf_2915",
+    "task_024_hf_20869",
+    "task_025_hf_24513",
+    "task_026_hf_42634",
+    "task_027_hf_45747",
+    "task_028_hf_53812",
+    "task_029_hf_54584",
+    "task_030_hf_54975",
+    "task_031_hf_80392",
+    "task_032_hf_82865",
+    "task_033_hf_107429",
+    "task_034_hf_107462",
+    "task_035_hf_134249",
+    "task_036_hf_138605",
+    "task_037_hf_147235",
+    "task_038_hf_989",
+    "task_039_hf_17430",
+    "task_040_hf_22992",
+    "task_041_hf_30431",
+    "task_042_hf_31743",
+    "task_043_hf_40909",
+    "task_044_hf_51152",
+    "task_045_hf_71839",
+    "task_046_hf_76438",
+    "task_047_hf_90788",
+    "task_048_hf_103736",
+    "task_049_hf_113406",
+    "task_050_hf_113626",
+    "task_051_hf_128576",
+    "task_052_hf_131511",
+    "task_053_hf_133973",
+    "task_054_hf_141332",
+    "task_055_hf_7795",
+    "task_056_hf_9711",
+    "task_057_hf_12096",
+    "task_058_hf_12781",
+    "task_059_hf_17967",
+    "task_060_hf_38041",
+    "task_061_hf_40479",
+    "task_062_hf_50296",
+    "task_063_hf_57703",
+    "task_064_hf_59913",
+    "task_065_hf_75184",
+    "task_066_hf_89325",
+    "task_067_hf_106267",
+    "task_068_hf_106604",
+    "task_069_hf_119258",
+    "task_070_hf_121236",
+]
+MAX_STEPS_DEFAULT = 10
+TEMPERATURE = 0.3
+MAX_TOKENS = 8192
+
+# ---------------------------------------------------------------------------
+# TOOLS — Hermes-style <tools> block for Qwen2.5-Instruct
+# These definitions match the server handlers in cadforge_environment.py:
+#   _handle_read_docs(params)      -> params: {topic?, query?}
+#   _handle_execute_cadquery(params) -> params: {code}
+#   _handle_submit(params)          -> params: {object_id?}  (defaults to best object if omitted)
+# ---------------------------------------------------------------------------
+
+TOOLS_BLOCK = textwrap.dedent("""\
+# Tools
+
+You may call one or more functions to assist with the user query.
+
+You are provided with function signatures within <tools></tools> XML tags:
+<tools>
+{
+  "type": "function",
+  "function": {
+    "name": "read_docs",
+    "description": "Search CadQuery documentation. Pass just a query to grep across ALL docs, or narrow with a topic. Available docs cover: basics (overview, quickstart, primer), selectors (face/edge selector syntax like >Z |X %Circle), booleans (BRep mindset, cut/union/intersect), transforms (workplane placement, .transformed(), offset), features (holes, fillets, chamfers, shell, polar/rect arrays, anti-patterns), sketch (Sketch API: rect, circle, slot, arc, constraints), advanced (free-function API, loft, sweep, surfaces), examples (full worked examples: plates, brackets, enclosures, gears), anti-patterns (common mistakes & fixes), workplanes (creation, offset, centerOption).",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "topic": {
+          "type": "string",
+          "enum": ["basics", "selectors", "booleans", "transforms", "features", "sketch", "advanced", "examples", "anti-patterns", "workplanes"],
+          "description": "Optional. Narrow search to a topic. Omit to search all docs."
+        },
+        "query": {
+          "type": "string",
+          "description": "Keyword to grep for, e.g. 'polarArray', 'cboreHole', 'shell', 'loft'. Omit to browse the full topic."
+        }
+      },
+      "required": []
+    }
+  }
+}
+{
+  "type": "function",
+  "function": {
+    "name": "execute_cadquery",
+    "description": "Execute a CadQuery Python script. The script MUST define a variable called 'result' containing the final CadQuery Workplane or Shape object. On success, returns the object_id and geometric properties of the shape (volume, bounding box, face counts, euler characteristic, etc.). On failure, returns the error message.",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "string",
+          "description": "Complete Python script using CadQuery. Must 'import cadquery as cq' and assign the final shape to a variable named 'result'."
+        }
+      },
+      "required": ["code"]
+    }
+  }
+}
+{
+  "type": "function",
+  "function": {
+    "name": "submit",
+    "description": "Submit and end the episode. Specify which object_id to submit (from a previous execute_cadquery executions). Without submit, even if you do your best work, it will not be considered.",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "object_id": {
+          "type": "string",
+          "description": "The object_id from a previous execute_cadquery result to submit. If omitted, the best object is submitted."
+        }
+      },
+      "required": ["object_id"]
+    }
+  }
+}
+</tools>
+
+IMPORTANT: Every response MUST contain exactly one <tool_call></tool_call> block. You may include analysis or reasoning text before it, but you MUST end with a tool call. Responses without a <tool_call> block are invalid and waste a step.
+
+Format:
+<tool_call>
+{"name": <function-name>, "arguments": <args-json-object>}
+</tool_call>
+
+IMPORTANT: You MUST call `submit` before your steps run out. If you never submit, your score is 0 regardless of how good your shape is.""")
+
+# ---------------------------------------------------------------------------
+# SYSTEM_PROMPT — CadQuery domain knowledge (no workflow/strategy section)
+# Separated from tools block for clarity; combined at runtime.
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT_KNOWLEDGE = textwrap.dedent("""\
+You are a CadQuery CAD agent. You write CadQuery Python scripts that create 3D solid geometry matching a task description. You produce correct, idiomatic CadQuery code on the first try whenever possible, and iterate using execution feedback and library docs when needed to reach to the correct query that generates the expected 3D object.
+
+Your shape is compared against a ground truth 3D object. You will receive the geometric properties of your shape after each execution — use these to verify your shape matches the task description (correct volume, bounding box dimensions, face types, euler characteristic, etc.).
+
+You MUST call `submit` before your steps run out. Without submit, your score is 0.
+
+## CadQuery Knowledge
+
+### Fluent (Workplane) API — Primary API
+```python
+import cadquery as cq
+result = cq.Workplane("XY").box(10, 10, 10).faces(">Z").hole(3)
+```
+- Chain operations on a `Workplane` with hidden state (current plane, stack)
+- Best for: parts built from sketches and feature operations (extrude, hole, fillet, shell)
+- `result` must be the final Workplane object
+
+### Core Mindset: BRep, NOT CSG
+CadQuery uses Boundary Representation. Avoid the CSG reflex of union/cut for everything.
+
+| Instead of...              | Use...                                      |
+|---------------------------|---------------------------------------------|
+| `.cut(cylinder)` for hole | `.faces(...).hole(d)`                       |
+| `.cut(shell_solid)`       | `.shell(thickness)`                         |
+| `.union(chamfered_edge)`  | `.edges(...).chamfer(d)`                    |
+| `.cut(box)` for pocket    | `.faces(...).workplane().rect(w,h).cutBlind(depth)` |
+
+Only use `.cut()`, `.union()`, `.intersect()` when genuinely combining separate solids.
+
+### Workplanes
+```python
+wp = cq.Workplane("XY")                    # named plane at origin
+wp = solid.faces(">Z").workplane()          # on a face
+wp = solid.faces(">Z").workplane(offset=5)  # offset from face
+```
+- `"XY"` = horizontal, `"XZ"` = front, `"YZ"` = side
+- `.workplane()` resets 2D origin to center of selected face by default
+- After `.workplane()`, coordinates are LOCAL to that plane
+
+### Selectors — Cheat Sheet
+| Selector     | Meaning                                    |
+|-------------|-------------------------------------------|
+| `">Z"`      | Highest Z centroid (top face)             |
+| `"<Z"`      | Lowest Z centroid (bottom face)           |
+| `"|X"`      | Normal parallel to X axis (vertical faces)|
+| `"#Z"`      | Orthogonal to Z                           |
+| `">Z and |X"` | Combine with AND                       |
+| `"%Plane"`  | Faces of type Plane                       |
+| `"%Circle"` | Circular edges                            |
+
+### 2D Sketch Operations (on Workplane)
+`center`, `lineTo`, `line`, `vLine`, `hLine`, `moveTo`, `spline`, `threePointArc`, `sagittaArc`, `radiusArc`, `tangentArcPoint`, `mirrorY`, `mirrorX`, `rect`, `circle`, `ellipse`, `polyline`, `close`, `polygon`, `slot2D`, `offset2D`
+
+### 3D Operations
+**Require 2D wire on workplane:** `extrude`, `cutBlind`, `cutThruAll`, `hole`, `cboreHole`, `cskHole`, `loft`, `sweep`, `revolve`, `twistExtrude`
+**No workplane needed:** `shell`, `fillet`, `chamfer`, `split`, `translate`, `rotate`, `mirror`
+
+### Common Patterns
+
+**Box:** `cq.Workplane("XY").box(L, W, H)`
+- `.box()` centers the box at the workplane origin by default
+
+**Cylinder:** `cq.Workplane("XY").cylinder(height, radius)`
+
+**Sphere:** `cq.Workplane("XY").sphere(radius)`
+
+**Cone:** `cq.Workplane("XY").union(cq.Solid.makeCone(r1, r2, h))`
+
+**Through-hole:** `.faces(">Z").hole(diameter)`
+
+**Blind hole:** `.faces(">Z").hole(diameter, depth)`
+
+**Fillet edges:** `.edges("|Z").fillet(radius)` or `.edges(">Z").fillet(radius)`
+
+**Chamfer:** `.edges(">Z").chamfer(distance)`
+
+**Shell (hollow):** `.faces(">Z").shell(-wallThickness)` (negative = inward)
+
+**Polar array of holes:**
+```python
+result = (
+    cq.Workplane("XY")
+    .cylinder(height, outer_r)
+    .faces(">Z").workplane()
+    .polarArray(bolt_circle_r, startAngle, 360, count)
+    .hole(hole_d)
+)
+```
+
+**Rectangular array of holes:**
+```python
+result = (
+    cq.Workplane("XY")
+    .box(L, W, H)
+    .faces(">Z").workplane()
+    .rarray(xSpacing, ySpacing, xCount, yCount)
+    .hole(hole_d)
+)
+```
+
+**Revolve profile:**
+```python
+result = (
+    cq.Workplane("XZ")
+    .moveTo(r_inner, 0)
+    .lineTo(r_outer, 0).lineTo(r_outer, h).lineTo(r_inner, h)
+    .close()
+    .revolve(360, (0, 0, 0), (0, 1, 0))
+)
+```
+
+**Sweep:**
+```python
+path = cq.Workplane("XZ").spline([(0,0), (10,5), (20,0)])
+result = cq.Workplane("XY").circle(r).sweep(path)
+```
+
+**Loft:**
+```python
+result = (
+    cq.Workplane("XY")
+    .rect(w1, h1)
+    .workplane(offset=height)
+    .circle(r2)
+    .loft()
+)
+```
+
+**Sketch API:**
+```python
+s = cq.Sketch().rect(10, 10).vertices().fillet(1)
+result = cq.Workplane("XY").placeSketch(s).extrude(5)
+```
+
+**Hexagonal prism:**
+```python
+result = cq.Workplane("XY").polygon(6, diameter).extrude(height)
+```
+Note: `.polygon(nSides, diameter)` where diameter is the circumscribed circle diameter (distance across corners).
+
+**L-bracket (subtractive approach):**
+```python
+result = (
+    cq.Workplane("XY")
+    .box(L, W, H)
+    .faces(">Z").workplane()
+    .center(offset_x, offset_y)
+    .rect(cut_w, cut_h)
+    .cutBlind(-cut_depth)
+)
+```
+
+**Dovetail / trapezoidal groove (profile-based cut):**
+```python
+result = (
+    cq.Workplane("XY")
+    .box(L, W, H)
+    .faces(">Y").workplane()
+    .moveTo(-top_w/2, H)
+    .lineTo(-bot_w/2, H - depth)
+    .lineTo(bot_w/2, H - depth)
+    .lineTo(top_w/2, H)
+    .close()
+    .cutThruAll()
+)
+```
+
+### Critical Anti-Patterns — AVOID
+1. **Boolean when a feature suffices** — use `.hole()`, `.shell()`, `.fillet()`, `.chamfer()`, `.cutBlind()`
+2. **Unclosed wires** — always call `.close()` before `.extrude()` or `.revolve()` with profiles
+3. **`.cutBlind()` direction** — negative value cuts INTO the solid from the current face
+4. **Fillet/chamfer too large** — radius must be less than shortest adjacent edge length
+5. **Boolean in a loop** — combine into compound first, then subtract once
+6. **Forgetting `import cadquery as cq`**
+7. **Forgetting to assign to `result`**
+
+All dimensions are in millimeters. Always use `import cadquery as cq`.""")
+
+SYSTEM_PROMPT = SYSTEM_PROMPT_KNOWLEDGE + "\n\n" + TOOLS_BLOCK
+
+# ---------------------------------------------------------------------------
+# USER_PROMPT_TEMPLATE — First turn: task description
+# ---------------------------------------------------------------------------
+
+USER_PROMPT_TEMPLATE = textwrap.dedent("""\
+## Task
+{task_description}
+
+You have {max_steps} steps to complete this task.
+Write CadQuery code that creates this exact geometry. Assign the final shape to `result`.
+Pay careful attention to every dimension (in mm), orientation, and feature described above.""")
+
+# ---------------------------------------------------------------------------
+# Per-tool observation templates
+# ---------------------------------------------------------------------------
+
+OBS_EXECUTE_SUCCESS = textwrap.dedent("""\
+## execute_cadquery — Success
+- Code Executed Successfully: True
+- object_id: {object_id}
+- Object properties:
+```json
+{properties_json}
+```
+- Objects so far: {artifacts}
+Step {step_count}/{max_steps} used.""")
+
+OBS_EXECUTE_ERROR = textwrap.dedent("""\
+## execute_cadquery — Error
+- Code Executed Successfully: False
+- error: {code_error}
+Step {step_count}/{max_steps} used.""")
+
+OBS_READ_DOCS = textwrap.dedent("""\
+## read_docs — Results
+{docs_text}
+Step {step_count}/{max_steps} used.""")
+
+OBS_SUBMIT = textwrap.dedent("""\
+## submit — Episode Complete
+- done: True""")
+
+OBS_UNKNOWN_ACTION = textwrap.dedent("""\
+## Error — Unknown Action
+{error_message}
+Step {step_count}/{max_steps} used.
+Valid actions: read_docs, execute_cadquery, submit.""")
+
+
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+
+def log_step(step: int, action: str, reward: float, done: bool, error: Optional[str]) -> None:
+    error_val = error if error else "null"
+    done_val = str(done).lower()
+    print(f"[STEP] step={step} action={action} reward={reward:.4f} done={done_val} error={error_val}", flush=True)
+
+
+def log_end(success: bool, steps: int, score: float, rewards: List[float]) -> None:
+    rewards_str = ",".join(f"{r:.4f}" for r in rewards)
+    print(f"[END] success={str(success).lower()} steps={steps} score={score:.4f} rewards={rewards_str}", flush=True)
+
+
+def format_user_prompt(obs, max_steps: int) -> str:
+    return USER_PROMPT_TEMPLATE.format(
+        task_description=obs.task or "N/A",
+        max_steps=max_steps,
+    )
+
+
+def format_observation(obs, max_steps: int) -> str:
+    if obs.done and obs.metadata and obs.metadata.get("message") == "Episode submitted":
+        return OBS_SUBMIT.format()
+
+    if obs.docs_results:
+        docs_text = "\n".join(doc[:800] for doc in obs.docs_results[:5])
+        return OBS_READ_DOCS.format(
+            docs_text=docs_text,
+            step_count=obs.step_count,
+            max_steps=max_steps,
+        )
+
+    if obs.code_error:
+        return OBS_EXECUTE_ERROR.format(
+            code_error=obs.code_error,
+            step_count=obs.step_count,
+            max_steps=max_steps,
+        )
+
+    if obs.code_executed is True:
+        safe_props = {}
+        if obs.object_properties:
+            safe_props = dict(obs.object_properties)
+        artifacts_list = []
+        if obs.artifacts:
+            artifacts_list = [a.get("object_id", "?") for a in obs.artifacts]
+        return OBS_EXECUTE_SUCCESS.format(
+            object_id=obs.object_id or "N/A",
+            properties_json=json.dumps(safe_props, indent=2),
+            artifacts=json.dumps(artifacts_list),
+            step_count=obs.step_count,
+            max_steps=max_steps,
+        )
+
+    if obs.code_error or (obs.metadata and "Unknown action_type" in str(obs.metadata)):
+        return OBS_UNKNOWN_ACTION.format(
+            error_message=obs.code_error or json.dumps(obs.metadata),
+            step_count=obs.step_count,
+            max_steps=max_steps,
+        )
+
+    parts = []
+    if obs.task:
+        parts.append(f"Task: {obs.task}")
+    parts.append(f"Step: {obs.step_count}/{max_steps}")
+    if obs.metadata:
+        parts.append(f"Info: {json.dumps(obs.metadata)}")
+    return "\n".join(parts)
+
+
+def fallback_action(obs) -> Optional[Dict]:
+    if obs.done:
+        return None
+    return {"action_type": "read_docs", "params": {"topic": "basics"}}
+
+
+def _extract_tool_call(text: str) -> Optional[Dict]:
+    tc_match = re.search(r'<tool_call>\s*(\{.*?\})\s*</tool_call>', text, re.DOTALL)
+    if tc_match:
+        try:
+            call = json.loads(tc_match.group(1))
+            name = call.get("name", "")
+            arguments = call.get("arguments", {})
+            return {"action_type": name, "params": arguments}
+        except json.JSONDecodeError:
+            pass
+
+    tc_open = re.search(r'<tool_call>\s*(\{.*)', text, re.DOTALL)
+    if tc_open:
+        raw = tc_open.group(1).strip()
+        raw = re.sub(r'</tool_call>.*', '', raw, flags=re.DOTALL).strip()
+        try:
+            call = json.loads(raw)
+            name = call.get("name", "")
+            arguments = call.get("arguments", {})
+            if name:
+                return {"action_type": name, "params": arguments}
+        except json.JSONDecodeError:
+            brace_depth = 0
+            end_idx = -1
+            for i, ch in enumerate(raw):
+                if ch == '{':
+                    brace_depth += 1
+                elif ch == '}':
+                    brace_depth -= 1
+                    if brace_depth == 0:
+                        end_idx = i
+                        break
+            if end_idx > 0:
+                try:
+                    call = json.loads(raw[:end_idx + 1])
+                    name = call.get("name", "")
+                    arguments = call.get("arguments", {})
+                    if name:
+                        return {"action_type": name, "params": arguments}
+                except json.JSONDecodeError:
+                    pass
+
+    text_clean = text.strip().strip("`")
+    if text_clean.startswith("json"):
+        text_clean = text_clean[4:].strip()
+    try:
+        parsed = json.loads(text_clean)
+        if "action_type" in parsed:
+            return parsed
+        if "name" in parsed:
+            return {"action_type": parsed["name"], "params": parsed.get("arguments", {})}
+    except json.JSONDecodeError:
+        pass
+
+    match = re.search(r'\{[^{}]*"action_type"[^{}]*\}', text, re.DOTALL)
+    if match:
+        try:
+            return json.loads(match.group())
+        except json.JSONDecodeError:
+            pass
+
+    match = re.search(r'\{[^{}]*"name"\s*:\s*"(read_docs|execute_cadquery|submit)".*?\}', text, re.DOTALL)
+    if match:
+        try:
+            call = json.loads(match.group())
+            return {"action_type": call["name"], "params": call.get("arguments", {})}
+        except json.JSONDecodeError:
+            pass
+
+    code_match = re.search(r'```python\s*(.*?)```', text, re.DOTALL)
+    if code_match:
+        code = code_match.group(1).strip()
+        if "import cadquery" in code or "cq." in code:
+            return {"action_type": "execute_cadquery", "params": {"code": code}}
+
+    return None
+
+
+RETRY_NUDGE = "Your previous response did not contain a valid <tool_call> block and was discarded. You MUST respond with exactly one <tool_call></tool_call> block. Respond now with a tool call."
+
+
+def _build_messages(history: List[Dict], obs, is_first_turn: bool, max_steps: int, nudge: Optional[str] = None) -> List[Dict]:
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+
+    for h in history[-6:]:
+        action = h["action"]
+        if action.get("action_type") == "execute_cadquery":
+            tc_json = json.dumps({"name": "execute_cadquery", "arguments": {"code": action["params"].get("code", "")}})
+        elif action.get("action_type") == "submit":
+            tc_json = json.dumps({"name": "submit", "arguments": action.get("params", {})})
+        else:
+            tc_json = json.dumps({"name": action.get("action_type", "read_docs"), "arguments": action.get("params", {})})
+        messages.append({"role": "assistant", "content": f"<tool_call>\n{tc_json}\n</tool_call>"})
+        messages.append({"role": "user", "content": h["observation"]})
+
+    if is_first_turn:
+        messages.append({"role": "user", "content": format_user_prompt(obs, max_steps)})
+    else:
+        messages.append({"role": "user", "content": format_observation(obs, max_steps)})
+
+    if nudge:
+        messages.append({"role": "user", "content": nudge})
+
+    return messages
+
+
+def get_model_action(client: OpenAI, obs, history: List[Dict], is_first_turn: bool = False, max_steps: int = MAX_STEPS_DEFAULT, current_step: int = 0) -> Optional[Dict]:
+    for attempt in range(2):
+        nudge = RETRY_NUDGE if attempt > 0 else None
+        messages = _build_messages(history, obs, is_first_turn, max_steps, nudge=nudge)
+
+        try:
+            t0 = time.time()
+            completion = client.chat.completions.create(
+                model=MODEL_NAME,
+                messages=messages,
+                temperature=TEMPERATURE,
+                max_tokens=MAX_TOKENS,
+                stream=False,
+            )
+            elapsed = time.time() - t0
+            text = (completion.choices[0].message.content or "").strip()
+            print(f"[LLM] attempt={attempt} response in {elapsed:.1f}s: {text[:300]}", flush=True)
+
+            parsed = _extract_tool_call(text)
+            if parsed is not None:
+                return parsed
+            print(f"[DEBUG] Could not parse tool call (attempt {attempt}): {text[:500]}", flush=True)
+        except Exception as exc:
+            print(f"[DEBUG] Model request failed (attempt {attempt}): {exc}", flush=True)
+
+    print(f"[DEBUG] All parse attempts failed, using fallback (step {current_step}/{max_steps})", flush=True)
+    if current_step >= max_steps - 1 and obs.object_id:
+        return {"action_type": "submit", "params": {"object_id": obs.object_id}}
+    return fallback_action(obs)
+
+
+async def run_task(task_id: str, llm: OpenAI) -> float:
+    if LOCAL_IMAGE_NAME:
+        env = await CadforgeEnv.from_docker_image(LOCAL_IMAGE_NAME)
+    else:
+        base_url = os.getenv("ENV_BASE_URL", "http://localhost:8000")
+        env = CadforgeEnv(base_url=base_url)
+
+    rewards: List[float] = []
+    steps_taken = 0
+    score = 0.0
+    success = False
+    max_steps = MAX_STEPS_DEFAULT
+
+    log_start(task=task_id, env=BENCHMARK, model=MODEL_NAME)
+
+    try:
+        await env.connect()
+        result = await env.reset(task_id=task_id)
+        obs = result.observation
+
+        if obs.metadata and "max_steps" in obs.metadata:
+            max_steps = obs.metadata["max_steps"]
+            print(f"[INFO] max_steps loaded from task: {max_steps}", flush=True)
+
+        history: List[Dict] = []
+        consecutive_failures = 0
+
+        for step in range(1, max_steps + 1):
+            if result.done:
+                break
+
+            is_first_turn = step == 1
+            action_dict = get_model_action(llm, obs, history, is_first_turn=is_first_turn, max_steps=max_steps, current_step=step)
+
+            if action_dict is None:
+                consecutive_failures += 1
+                if consecutive_failures >= 3:
+                    print("[DEBUG] LLM unavailable and no valid fallback. Ending task.", flush=True)
+                    break
+                continue
+            else:
+                consecutive_failures = 0
+
+            action_type = action_dict.get("action_type", "read_docs")
+            params = action_dict.get("params", {})
+
+            try:
+                action = CadforgeAction(action_type=action_type, params=params)
+            except Exception:
+                action = CadforgeAction(action_type="read_docs", params={"topic": "basics"})
+                action_dict = {"action_type": "read_docs", "params": {"topic": "basics"}}
+
+            result = await env.step(action)
+            obs = result.observation
+
+            reward = result.reward or 0.0
+            done = result.done
+            error = obs.code_error if obs.code_error else None
+
+            rewards.append(reward)
+            steps_taken = step
+
+            action_str = f"{action_type}({json.dumps(params)[:100]})"
+            log_step(step=step, action=action_str, reward=reward, done=done, error=error)
+
+            history.append({
+                "action": action_dict,
+                "observation": format_observation(obs, max_steps),
+            })
+
+            if done:
+                break
+
+        score = rewards[-1] if rewards else 0.0
+        score = min(max(score, 0.0), 1.0)
+        success = score > 0.5
+
+    finally:
+        try:
+            await env.close()
+        except Exception as e:
+            print(f"[DEBUG] env.close() error: {e}", flush=True)
+        log_end(success=success, steps=steps_taken, score=score, rewards=rewards)
+
+    return score
+
+
+async def main() -> None:
+    llm = OpenAI(base_url=API_BASE_URL, api_key=HF_TOKEN)
+
+    task_filter = os.getenv("TASKS")
+    if task_filter:
+        tasks = [t.strip() for t in task_filter.split(",")]
+    else:
+        tasks = TASKS
+
+    scores = []
+    for task_id in tasks:
+        score = await run_task(task_id, llm)
+        scores.append(score)
+
+    avg = sum(scores) / len(scores) if scores else 0.0
+    print(f"\n[SUMMARY] tasks={len(tasks)} avg_score={avg:.4f} scores={','.join(f'{s:.4f}' for s in scores)}", flush=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

models.py

@@ -0,0 +1,59 @@
+from typing import Any, Dict, List, Optional
+
+from openenv.core.env_server.types import Action, Observation
+from pydantic import Field, PrivateAttr
+
+
+class CadforgeAction(Action):
+    action_type: str = Field(
+        ...,
+        description="One of: read_docs | execute_cadquery | submit | render_object",
+    )
+    params: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Parameters for the action",
+    )
+
+
+class CadforgeObservation(Observation):
+    task: Optional[str] = Field(
+        default=None,
+        description="Task prompt provided on reset",
+    )
+    step_count: int = Field(
+        default=0,
+        description="Number of steps taken so far",
+    )
+    docs_results: Optional[List[str]] = Field(
+        default=None,
+        description="Documentation paragraphs returned by read_docs",
+    )
+    code_executed: Optional[bool] = Field(
+        default=None,
+        description="True if code ran successfully, False if errored, None if no code run",
+    )
+    code_error: Optional[str] = Field(
+        default=None,
+        description="Exception message if code_executed is False",
+    )
+    object_id: Optional[str] = Field(
+        default=None,
+        description="Unique identifier for the shape produced by execute_cadquery",
+    )
+    object_properties: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Geometric properties of the shape produced by execute_cadquery",
+    )
+    artifacts: Optional[List[Dict[str, Any]]] = Field(
+        default=None,
+        description="Registry of all shapes created so far: [{object_id, step_path}]",
+    )
+    last_executed: Optional[str] = Field(
+        default=None,
+        description="Object ID of the most recently executed shape",
+    )
+    image_path: Optional[str] = Field(
+        default=None,
+        description="Path to rendered PNG (Phase 2 only)",
+    )
+    _raw_data: Optional[Dict[str, Any]] = PrivateAttr(default=None)

openenv.yaml

@@ -0,0 +1,7 @@
+spec_version: 1
+name: cadforge
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+

pyproject.toml

@@ -0,0 +1,42 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-cadforge"
+version = "0.1.0"
+description = "Cadforge environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core[core]>=0.2.2",
+    "cadquery>=2.4.0",
+    "numpy>=1.24.0",
+    "scipy>=1.10.0",
+    "trimesh>=4.0.0",
+    "embreex>=4.0.0",
+    "networkx>=3.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m cadforge.server.app
+server = "cadforge.server.app:main"
+
+
+[tool.setuptools]
+include-package-data = true
+packages = ["cadforge", "cadforge.server"]
+package-dir = { "cadforge" = ".", "cadforge.server" = "server" }

scripts/generate_ground_truth.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Generate ground truth files (ground_truth.json, .npy) for all tasks.
+
+Usage:
+    python scripts/generate_ground_truth.py
+    python scripts/generate_ground_truth.py --task task_001_flat_plate
+"""
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+TASKS_ROOT = Path(__file__).parent.parent / "server" / "tasks"
+
+
+def generate_one(task_dir: Path) -> dict:
+    task_id = task_dir.name
+    t0 = time.time()
+
+    result = {
+        "task_id": task_id,
+        "success": False,
+        "error": None,
+    }
+
+    try:
+        from server.preprocessor import preprocess_from_code
+
+        ref_code = (task_dir / "reference_code.py").read_text()
+        gt = preprocess_from_code(ref_code, str(task_dir), task_id=task_id)
+
+        result["success"] = True
+        result["volume"] = gt.get("volume_mm3")
+        result["bbox"] = gt.get("bbox_mm")
+        result["euler"] = gt.get("euler_characteristic")
+        result["dominant_face_type"] = gt.get("dominant_face_type")
+        result["face_count"] = gt.get("face_count")
+
+    except Exception as e:
+        import traceback
+        result["error"] = f"{type(e).__name__}: {e}"
+        result["traceback"] = traceback.format_exc()
+
+    result["elapsed_s"] = round(time.time() - t0, 2)
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate ground truth for CadForge tasks")
+    parser.add_argument("--task", type=str, default=None, help="Specific task id")
+    args = parser.parse_args()
+
+    if args.task:
+        task_dirs = [TASKS_ROOT / args.task]
+    else:
+        task_dirs = sorted(TASKS_ROOT.glob("task_*"))
+
+    print(f"Generating ground truth for {len(task_dirs)} tasks...")
+    print("-" * 80)
+
+    results = []
+    for task_dir in task_dirs:
+        r = generate_one(task_dir)
+        status = "OK" if r["success"] else "FAIL"
+        print(
+            f"  {r['task_id']:35s} {status:5s} "
+            f"vol={r.get('volume', 'N/A')} "
+            f"euler={r.get('euler', 'N/A')} "
+            f"faces={r.get('face_count', 'N/A')} "
+            f"({r['elapsed_s']:.1f}s)"
+        )
+        if r["error"]:
+            print(f"    ERROR: {r['error']}")
+        results.append(r)
+
+    passed = sum(1 for r in results if r["success"])
+    print("-" * 80)
+    print(f"Result: {passed}/{len(results)} generated successfully")
+
+    out_path = TASKS_ROOT.parent / "verification_ground_truth.json"
+    with open(out_path, "w") as f:
+        json.dump(results, f, indent=2)
+    print(f"Saved to {out_path}")
+
+    return 0 if passed == len(results) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/generate_tasks_thomasmaker.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""Generate task files from the ThomasTheMaker/cadquery HuggingFace dataset.
+
+Pipeline per example:
+  1. Execute CadQuery code -> get shape
+  2. Run preprocess_from_code -> ground_truth.step, ground_truth.json, .npy
+  3. Send HF image + code + ground_truth.json to Claude Sonnet -> get NL prompt
+  4. Write task.json, reference_code.py
+
+Usage:
+    python scripts/generate_tasks_thomasmaker.py --limit 3        # test on 3
+    python scripts/generate_tasks_thomasmaker.py                  # all 50
+    python scripts/generate_tasks_thomasmaker.py --dry-run        # just show prompts
+"""
+import argparse
+import base64
+import io
+import json
+import logging
+import math
+import os
+import re
+import sys
+import time
+import traceback
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+logger = logging.getLogger(__name__)
+
+TASKS_ROOT = Path(__file__).parent.parent / "server" / "tasks"
+SELECTED_PATH = Path(__file__).parent.parent / "selected_50.json"
+START_TASK_NUM = 21
+
+def _load_api_key():
+    key = os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("ANTHROPIC_KEY")
+    if key:
+        return key
+    env_path = Path(__file__).parent.parent.parent / ".env"
+    if env_path.exists():
+        for line in env_path.read_text().splitlines():
+            line = line.strip()
+            if line.startswith("ANTHROPIC_KEY="):
+                return line.split("=", 1)[1].strip().strip("'\"")
+            if line.startswith("ANTHROPIC_API_KEY="):
+                return line.split("=", 1)[1].strip().strip("'\"")
+    return ""
+
+ANTHROPIC_API_KEY = _load_api_key()
+
+PROMPT_SYSTEM = """You are a CAD engineering assistant. You will be shown an image of a 3D CAD part along with its geometric properties. Your job is to write a clear, detailed natural language description that a CAD engineer could use to recreate this exact part in CadQuery.
+
+Rules:
+- Write in natural language, NOT code. Do not use any code syntax.
+- Be specific about dimensions in millimeters (use the bbox and geometry data provided).
+- Describe the construction steps: what base shape, what features are added/removed, what boolean operations.
+- Mention the number and types of faces if it helps clarify the geometry.
+- Describe holes, bosses, pockets, curved surfaces, arcs, fillets if visible.
+- Mention symmetry if present.
+- End with "Orient the longest axis along X."
+- Keep it to one clear paragraph, 3-8 sentences.
+- Do NOT start with "Create a" - vary your openings."""
+
+
+def image_to_base64(pil_image):
+    buf = io.BytesIO()
+    pil_image.save(buf, format="PNG")
+    return base64.standard_b64encode(buf.getvalue()).decode("utf-8")
+
+
+def call_claude_for_prompt(pil_image, gt_json, code, code_info):
+    import anthropic
+    client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY)
+
+    img_b64 = image_to_base64(pil_image)
+
+    user_text = f"""Here is the ground truth geometry data for this 3D part:
+
+{json.dumps(gt_json, indent=2)}
+
+Here is the CadQuery code that generates this part:
+
+```python
+{code}
+```
+
+Additional construction info:
+- Number of extrusions: {code_info.get('extrudes', 0)}
+- Number of union operations: {code_info.get('unions', 0)}
+- Number of cut operations: {code_info.get('cuts', 0)}
+- Number of arc segments: {code_info.get('arcs', 0)}
+- Number of circular features: {code_info.get('circles', 0)}
+
+Look at the image carefully along with the ground truth data and the code above. Write a detailed natural language prompt describing this part so someone could recreate it in CadQuery."""
+
+    t0 = time.time()
+    response = client.messages.create(
+        model="claude-sonnet-4-20250514",
+        max_tokens=700,
+        system=PROMPT_SYSTEM,
+        messages=[
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/png",
+                            "data": img_b64,
+                        },
+                    },
+                    {
+                        "type": "text",
+                        "text": user_text,
+                    },
+                ],
+            }
+        ],
+    )
+    elapsed = time.time() - t0
+    prompt_text = response.content[0].text.strip()
+    logger.info(f"  Claude API call took {elapsed:.1f}s, prompt length={len(prompt_text)}")
+    return prompt_text
+
+
+def execute_code(code):
+    import cadquery as cq
+    adapted = code.rstrip()
+    if "\nresult" not in adapted and "\nresult " not in adapted:
+        last_solid = None
+        for m in re.finditer(r"^(solid\w*)\s*=", adapted, re.MULTILINE):
+            last_solid = m.group(1)
+        if last_solid:
+            adapted += f"\nresult = {last_solid}"
+        else:
+            adapted += "\nresult = solid"
+
+    local_ns = {"cq": cq, "cadquery": cq, "math": math}
+    exec(adapted, local_ns)
+
+    result = local_ns.get("result")
+    if result is None:
+        raise ValueError("No 'result' variable after execution")
+
+    if hasattr(result, "val"):
+        shape = result.val()
+    else:
+        shape = result
+
+    bb = shape.BoundingBox()
+    if bb.xlen < 1e-6 and bb.ylen < 1e-6 and bb.zlen < 1e-6:
+        raise ValueError("Degenerate shape (zero bbox)")
+
+    return shape, adapted
+
+
+def analyze_geometry(shape, code_info):
+    from server.geometry import extract_properties
+    props = extract_properties(shape)
+
+    bb = shape.BoundingBox()
+    bbox = [round(bb.xlen, 4), round(bb.ylen, 4), round(bb.zlen, 4)]
+
+    return {
+        "bbox": bbox,
+        "volume": props.get("volume_mm3", 0),
+        "surface_area": props.get("surface_area_mm2", 0),
+        "face_count": props.get("face_count", 0),
+        "face_type_counts": props.get("face_type_counts", {}),
+        "dominant_face_type": props.get("dominant_face_type", ""),
+        "euler": props.get("euler_characteristic", 2),
+        "shape_class": props.get("shape_class", "COMPLEX_SOLID"),
+        "edge_count": props.get("edge_count", 0),
+        "vertex_count": props.get("vertex_count", 0),
+        "has_xy_symmetry": props.get("has_xy_symmetry", False),
+        "has_xz_symmetry": props.get("has_xz_symmetry", False),
+        "has_yz_symmetry": props.get("has_yz_symmetry", False),
+        "extrudes": code_info.get("extrudes", 0),
+        "unions": code_info.get("unions", 0),
+        "cuts": code_info.get("cuts", 0),
+        "arcs": code_info.get("arcs", 0),
+        "circles": code_info.get("circles", 0),
+    }
+
+
+def difficulty_bin(label, score):
+    if label == "medium":
+        return min(5, max(3, 3 + (score - 10) // 3))
+    elif label == "hard":
+        return min(7, max(5, 5 + (score - 19) // 6))
+    else:
+        return min(9, max(7, 7 + (score - 35) // 15))
+
+
+def generate_one_task(ds, info, task_num, dry_run=False):
+    t0 = time.time()
+    idx = info["idx"]
+    row = ds[idx]
+    code = row["texts"][0]["assistant"]
+    pil_image = row["images"][0]
+    label = info["difficulty_label"]
+
+    task_id = f"task_{task_num:03d}_hf_{idx}"
+    task_dir = TASKS_ROOT / task_id
+
+    logger.info(f"[{task_num}] Processing {task_id} (hf_idx={idx}, score={info['score']}, {label})")
+
+    try:
+        shape, adapted_code = execute_code(code)
+        logger.info(f"  Code executed OK")
+    except Exception as e:
+        logger.error(f"  EXEC FAIL: {e}")
+        return {"task_id": task_id, "success": False, "error": f"exec: {e}",
+                "elapsed_s": round(time.time() - t0, 2)}
+
+    task_dir.mkdir(parents=True, exist_ok=True)
+
+    with open(task_dir / "reference_code.py", "w") as f:
+        f.write(adapted_code)
+
+    try:
+        from server.preprocessor import preprocess_from_code
+        gt = preprocess_from_code(adapted_code, str(task_dir), task_id=task_id)
+        logger.info(f"  GT OK: vol={gt.get('volume_mm3')}, bbox={gt.get('bbox_mm')}")
+    except Exception as e:
+        logger.error(f"  GT FAIL: {e}")
+        logger.error(traceback.format_exc())
+        return {"task_id": task_id, "success": False, "error": f"gt: {e}",
+                "elapsed_s": round(time.time() - t0, 2)}
+
+    gt_json_path = task_dir / "ground_truth.json"
+    with open(gt_json_path) as f:
+        gt_json = json.load(f)
+
+    try:
+        nl_prompt = call_claude_for_prompt(pil_image, gt_json, code, info)
+    except Exception as e:
+        logger.error(f"  PROMPT FAIL: {e}")
+        return {"task_id": task_id, "success": False, "error": f"prompt: {e}",
+                "elapsed_s": round(time.time() - t0, 2)}
+
+    d_bin = difficulty_bin(label, info["score"])
+    max_steps = 20 if label == "medium" else (25 if label == "hard" else 30)
+
+    task_json = {
+        "id": task_id,
+        "part_class": gt_json.get("dominant_face_type", "complex").lower(),
+        "difficulty_bin": d_bin,
+        "max_steps": max_steps,
+        "prompt": nl_prompt,
+        "ground_truth_step": f"tasks/{task_id}/ground_truth.step",
+        "ground_truth_json": f"tasks/{task_id}/ground_truth.json",
+        "reference_code": f"tasks/{task_id}/reference_code.py",
+        "source": "ThomasTheMaker/cadquery",
+        "hf_index": idx,
+        "complexity_score": info["score"],
+        "difficulty_label": label,
+    }
+
+    with open(task_dir / "task.json", "w") as f:
+        json.dump(task_json, f, indent=2)
+
+    elapsed = round(time.time() - t0, 2)
+    logger.info(f"  DONE {task_id} ({elapsed}s)")
+    return {"task_id": task_id, "success": True, "elapsed_s": elapsed,
+            "prompt_preview": nl_prompt[:150],
+            "volume": gt.get("volume_mm3"), "face_count": gt.get("face_count")}
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--limit", type=int, default=None)
+    parser.add_argument("--start-num", type=int, default=START_TASK_NUM)
+    args = parser.parse_args()
+
+    t0_total = time.time()
+
+    if not ANTHROPIC_API_KEY:
+        logger.error("ANTHROPIC_API_KEY not set")
+        return 1
+
+    with open(SELECTED_PATH) as f:
+        selected = json.load(f)
+    logger.info(f"Loaded {len(selected)} selected examples")
+
+    if args.limit:
+        selected = selected[:args.limit]
+
+    from datasets import load_dataset
+    logger.info("Loading HF dataset...")
+    ds = load_dataset("ThomasTheMaker/cadquery", split="train")
+    logger.info(f"Loaded {len(ds)} rows")
+
+    results = []
+    task_num = args.start_num
+    success_count = 0
+    fail_count = 0
+
+    for i, info in enumerate(selected):
+        r = generate_one_task(ds, info, task_num, dry_run=args.dry_run)
+        results.append(r)
+        if r.get("success"):
+            success_count += 1
+        else:
+            fail_count += 1
+        task_num += 1
+
+        if (i + 1) % 5 == 0:
+            logger.info(f"=== Progress: {i+1}/{len(selected)} (ok={success_count}, fail={fail_count}) ===")
+
+    elapsed_total = time.time() - t0_total
+    print("\n" + "=" * 80)
+    print(f"DONE: {success_count}/{len(selected)} succeeded, {fail_count} failed")
+    print(f"Total time: {elapsed_total:.1f}s ({elapsed_total/60:.1f}m)")
+
+    report_path = TASKS_ROOT.parent / "thomasmaker_generation_report.json"
+    with open(report_path, "w") as f:
+        json.dump(results, f, indent=2)
+    print(f"Report: {report_path}")
+
+    return 0 if fail_count == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/verify_all_tasks.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+import json
+import sys
+import time
+import traceback
+from pathlib import Path
+
+TASKS_ROOT = Path(__file__).parent.parent / "server" / "tasks"
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+def verify_reference_code(task_dir: Path) -> dict:
+    task_json_path = task_dir / "task.json"
+    ref_code_path = task_dir / "reference_code.py"
+
+    with open(task_json_path) as f:
+        task_data = json.load(f)
+
+    code = ref_code_path.read_text()
+
+    result_dict = {
+        "task_id": task_data["id"],
+        "code_executes": False,
+        "shape_valid": False,
+        "volume_gt_zero": False,
+        "ground_truth_generated": False,
+        "error": None,
+    }
+
+    try:
+        import cadquery as cq
+        import math
+        local_ns = {"cq": cq, "cadquery": cq, "math": math}
+        exec(code, local_ns)
+
+        if "result" not in local_ns:
+            result_dict["error"] = "No 'result' variable defined"
+            return result_dict
+
+        result_dict["code_executes"] = True
+        result_obj = local_ns["result"]
+
+        if hasattr(result_obj, "val"):
+            shape = result_obj.val()
+        else:
+            shape = result_obj
+
+        result_dict["shape_valid"] = shape.isValid()
+        vol = shape.Volume()
+        result_dict["volume"] = round(vol, 2)
+        result_dict["volume_gt_zero"] = vol > 0
+
+        bb = shape.BoundingBox()
+        result_dict["bbox"] = [round(bb.xlen, 2), round(bb.ylen, 2), round(bb.zlen, 2)]
+
+        faces = shape.Faces()
+        result_dict["face_count"] = len(faces)
+
+    except Exception as e:
+        result_dict["error"] = f"{type(e).__name__}: {e}"
+        return result_dict
+
+    try:
+        from server.preprocessor import preprocess_from_code
+        gt = preprocess_from_code(code, str(task_dir), task_id=task_data["id"])
+        result_dict["ground_truth_generated"] = True
+        result_dict["gt_volume"] = gt.get("volume_mm3")
+        result_dict["gt_euler"] = gt.get("euler_characteristic")
+        result_dict["gt_dominant_face"] = gt.get("dominant_face_type")
+    except Exception as e:
+        result_dict["error"] = f"Preprocessing failed: {type(e).__name__}: {e}"
+
+    return result_dict
+
+
+def run_reward_verification(task_dir: Path) -> dict:
+    result_dict = {
+        "reward_computed": False,
+        "reward_value": 0.0,
+        "error": None,
+    }
+
+    gt_json = task_dir / "ground_truth.json"
+    if not gt_json.exists():
+        result_dict["error"] = "No ground_truth.json"
+        return result_dict
+
+    ref_code = (task_dir / "reference_code.py").read_text()
+
+    try:
+        from server.executor import execute_cadquery_code
+        exec_result = execute_cadquery_code(ref_code, timeout=15.0)
+
+        if not exec_result["success"]:
+            result_dict["error"] = f"Execution failed: {exec_result['error']}"
+            return result_dict
+
+        props = exec_result["properties"]
+
+        import numpy as np
+        from server.preprocessor import sample_surface_points, voxelize, normalize_shape
+        import cadquery as cq
+        import math
+
+        local_ns = {"cq": cq, "cadquery": cq, "math": math}
+        exec(ref_code, local_ns)
+        result_obj = local_ns["result"]
+        shape = result_obj.val() if hasattr(result_obj, "val") else result_obj
+
+        normalized_shape, _ = normalize_shape(shape)
+        agent_points = sample_surface_points(normalized_shape, 2048)
+        agent_voxels = voxelize(normalized_shape, 64)
+
+        gt_points = np.load(str(task_dir / "surface_points.npy"))
+        gt_voxels = np.load(str(task_dir / "voxels_64.npy"))
+
+        from server.reward import compute_iou, best_of_6_iou, compute_mean_chamfer, compute_median_chamfer
+
+        iou = compute_iou(agent_voxels, gt_voxels)
+        iou_best = best_of_6_iou(agent_voxels, gt_voxels)
+        mean_cd = compute_mean_chamfer(agent_points, gt_points)
+        median_cd = compute_median_chamfer(agent_points, gt_points)
+
+        with open(gt_json) as f:
+            gt_data = json.load(f)
+
+        bbox_mm = gt_data.get("bbox_mm", [1, 1, 1])
+        bbox_diag = (sum(d**2 for d in bbox_mm)) ** 0.5
+        threshold = bbox_diag * 0.1
+
+        mean_cd_r = max(0, 1 - mean_cd / threshold) if threshold > 0 else 0
+        median_cd_r = max(0, 1 - median_cd / threshold) if threshold > 0 else 0
+
+        rgeom = 0.60 * iou_best + 0.20 * mean_cd_r + 0.20 * median_cd_r
+
+        frame_gap = iou_best - iou
+        frame_score = 0.1 if frame_gap > 0.15 else 1.0
+
+        norm_bb = normalized_shape.BoundingBox()
+        agent_bbox = [round(norm_bb.xlen, 4), round(norm_bb.ylen, 4), round(norm_bb.zlen, 4)]
+        gt_bbox = gt_data["bbox_mm"]
+        sorted_a = sorted(agent_bbox, reverse=True)
+        sorted_t = sorted(gt_bbox, reverse=True)
+
+        def match(a, b, tol=0.05):
+            for ai, bi in zip(a, b):
+                if bi == 0:
+                    continue
+                if abs(ai - bi) / max(abs(bi), 1e-6) > tol:
+                    return False
+            return True
+
+        s_match = match(sorted_a, sorted_t)
+        u_match = match(agent_bbox, gt_bbox)
+        param_score = 0.1 if (s_match and not u_match) else 1.0
+
+        face_score = 1.0 if props["dominant_face_type"] == gt_data["dominant_face_type"] else 0.0
+
+        reval = 0.40 * frame_score + 0.40 * param_score + 0.20 * face_score
+        total = 1.0 * (0.70 * rgeom + 0.30 * reval)
+
+        result_dict["reward_computed"] = True
+        result_dict["reward_value"] = round(total, 4)
+        result_dict["detail"] = {
+            "iou": round(iou, 4),
+            "iou_best": round(iou_best, 4),
+            "mean_cd": round(mean_cd, 4),
+            "mean_cd_reward": round(mean_cd_r, 4),
+            "median_cd": round(median_cd, 4),
+            "median_cd_reward": round(median_cd_r, 4),
+            "rgeom": round(rgeom, 4),
+            "frame_score": frame_score,
+            "param_score": param_score,
+            "face_score": face_score,
+            "reval": round(reval, 4),
+        }
+
+    except Exception as e:
+        result_dict["error"] = f"{type(e).__name__}: {e}\n{traceback.format_exc()}"
+
+    return result_dict
+
+
+def main():
+    print("=" * 80)
+    print("CadForge Task Verification Pipeline")
+    print("=" * 80)
+
+    task_dirs = sorted(TASKS_ROOT.glob("task_*"))
+    print(f"\nFound {len(task_dirs)} tasks\n")
+
+    phase1_results = []
+    print("PHASE 1: Verify reference codes execute and generate ground truth")
+    print("-" * 60)
+
+    for task_dir in task_dirs:
+        t0 = time.time()
+        result = verify_reference_code(task_dir)
+        elapsed = time.time() - t0
+
+        status = "PASS" if all([
+            result["code_executes"],
+            result["shape_valid"],
+            result["volume_gt_zero"],
+            result["ground_truth_generated"],
+        ]) else "FAIL"
+
+        print(f"  {result['task_id']:35s} {status:5s} ({elapsed:.1f}s) "
+              f"vol={result.get('volume', 'N/A')} bbox={result.get('bbox', 'N/A')}")
+        if result.get("error"):
+            print(f"    ERROR: {result['error']}")
+        phase1_results.append(result)
+
+    phase1_pass = sum(1 for r in phase1_results if r["ground_truth_generated"])
+    print(f"\nPhase 1: {phase1_pass}/{len(phase1_results)} tasks passed\n")
+
+    print("PHASE 2: Verify reward scores for reference code (should be ~1.0)")
+    print("-" * 60)
+
+    phase2_results = []
+    for task_dir in task_dirs:
+        t0 = time.time()
+        result = run_reward_verification(task_dir)
+        elapsed = time.time() - t0
+
+        task_id = task_dir.name
+        reward = result.get("reward_value", 0)
+        status = "PASS" if reward > 0.85 else "WARN" if reward > 0.5 else "FAIL"
+
+        print(f"  {task_id:35s} {status:5s} reward={reward:.4f} ({elapsed:.1f}s)")
+        if result.get("error"):
+            print(f"    ERROR: {result['error'][:200]}")
+        if result.get("detail"):
+            d = result["detail"]
+            print(f"    IoU={d['iou_best']:.3f} MeanCD_r={d['mean_cd_reward']:.3f} "
+                  f"MedianCD_r={d['median_cd_reward']:.3f} Rgeom={d['rgeom']:.3f} Reval={d['reval']:.3f}")
+        phase2_results.append(result)
+
+    phase2_pass = sum(1 for r in phase2_results if r.get("reward_value", 0) > 0.85)
+    print(f"\nPhase 2: {phase2_pass}/{len(phase2_results)} tasks score > 0.85")
+
+    print("\n" + "=" * 80)
+    print("SUMMARY")
+    print(f"  Phase 1 (code + ground truth): {phase1_pass}/{len(phase1_results)}")
+    print(f"  Phase 2 (reward > 0.85):       {phase2_pass}/{len(phase2_results)}")
+    print("=" * 80)
+
+    with open(TASKS_ROOT.parent / "verification_results.json", "w") as f:
+        json.dump({
+            "phase1": phase1_results,
+            "phase2": phase2_results,
+        }, f, indent=2, default=str)
+
+    print(f"\nDetailed results saved to verification_results.json")
+
+    if phase1_pass < len(phase1_results) or phase2_pass < len(phase2_results):
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/verify_reference_codes.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Verify all 20 reference codes execute and produce valid geometry.
+
+Usage:
+    python scripts/verify_reference_codes.py
+    python scripts/verify_reference_codes.py --task task_001_flat_plate
+"""
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+TASKS_ROOT = Path(__file__).parent.parent / "server" / "tasks"
+
+
+def verify_one(task_dir: Path) -> dict:
+    task_id = task_dir.name
+    ref_code = (task_dir / "reference_code.py").read_text()
+    t0 = time.time()
+
+    result = {
+        "task_id": task_id,
+        "code_executes": False,
+        "shape_valid": False,
+        "volume_gt_zero": False,
+        "volume": None,
+        "bbox": None,
+        "face_count": None,
+        "error": None,
+    }
+
+    try:
+        import cadquery as cq
+        import math
+
+        local_ns = {"cq": cq, "cadquery": cq, "math": math}
+        exec(ref_code, local_ns)
+
+        if "result" not in local_ns:
+            result["error"] = "No 'result' variable defined"
+            return result
+
+        result["code_executes"] = True
+        obj = local_ns["result"]
+        shape = obj.val() if hasattr(obj, "val") else obj
+
+        result["shape_valid"] = shape.isValid()
+        vol = shape.Volume()
+        result["volume"] = round(vol, 2)
+        result["volume_gt_zero"] = vol > 0
+
+        bb = shape.BoundingBox()
+        result["bbox"] = [round(bb.xlen, 2), round(bb.ylen, 2), round(bb.zlen, 2)]
+        result["face_count"] = len(shape.Faces())
+
+    except Exception as e:
+        result["error"] = f"{type(e).__name__}: {e}"
+
+    result["elapsed_s"] = round(time.time() - t0, 2)
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Verify CadForge reference codes")
+    parser.add_argument("--task", type=str, default=None, help="Specific task id to verify")
+    args = parser.parse_args()
+
+    if args.task:
+        task_dirs = [TASKS_ROOT / args.task]
+    else:
+        task_dirs = sorted(TASKS_ROOT.glob("task_*"))
+
+    print(f"Verifying {len(task_dirs)} reference codes...")
+    print("-" * 80)
+
+    results = []
+    for task_dir in task_dirs:
+        r = verify_one(task_dir)
+        passed = r["code_executes"] and r["shape_valid"] and r["volume_gt_zero"]
+        status = "PASS" if passed else "FAIL"
+        print(
+            f"  {r['task_id']:35s} {status:5s} "
+            f"vol={r['volume'] or 'N/A':>10} "
+            f"bbox={r['bbox'] or 'N/A'} "
+            f"faces={r['face_count'] or 'N/A'} "
+            f"({r['elapsed_s']:.1f}s)"
+        )
+        if r["error"]:
+            print(f"    ERROR: {r['error']}")
+        results.append(r)
+
+    passed = sum(1 for r in results if r["code_executes"] and r["shape_valid"] and r["volume_gt_zero"])
+    print("-" * 80)
+    print(f"Result: {passed}/{len(results)} passed")
+
+    out_path = TASKS_ROOT.parent / "verification_phase1.json"
+    with open(out_path, "w") as f:
+        json.dump(results, f, indent=2)
+    print(f"Saved to {out_path}")
+
+    return 0 if passed == len(results) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/verify_reward_scenarios.py

@@ -0,0 +1,370 @@
+#!/usr/bin/env python3
+"""Verify reward component breakdown for adversarial / wrong-shape scenarios.
+
+Computes all reward components locally (no server needed) for various
+agent code vs ground truth combinations. Useful for tuning weights.
+
+Prerequisites: run generate_ground_truth.py first.
+
+Usage:
+    python scripts/verify_reward_scenarios.py
+    python scripts/verify_reward_scenarios.py --task task_001_flat_plate
+    python scripts/verify_reward_scenarios.py --json
+"""
+import argparse
+import json
+import sys
+import time
+import traceback
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+TASKS_ROOT = Path(__file__).parent.parent / "server" / "tasks"
+
+W_RGEOM = 0.80
+W_REVAL = 0.20
+W_IOU = 0.60
+W_MEAN_CD = 0.20
+W_MEDIAN_CD = 0.20
+W_VOLUME = 0.35
+W_BBOX = 0.30
+W_FACE_TYPE = 0.15
+W_EULER = 0.20
+
+SCENARIOS = [
+    {
+        "task_id": "task_001_flat_plate",
+        "label": "perfect_match",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').box(80, 40, 5)",
+        "expect_reward_gt": 0.85,
+    },
+    {
+        "task_id": "task_001_flat_plate",
+        "label": "tiny_cube",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').box(1, 1, 1)",
+        "expect_reward_lt": 0.15,
+    },
+    {
+        "task_id": "task_001_flat_plate",
+        "label": "cylinder_instead",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').cylinder(50, 20)",
+        "expect_reward_lt": 0.5,
+    },
+    {
+        "task_id": "task_001_flat_plate",
+        "label": "sphere_instead",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').sphere(25)",
+        "expect_reward_lt": 0.5,
+    },
+    {
+        "task_id": "task_001_flat_plate",
+        "label": "cylinder_similar_dims",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').cylinder(40, 40)",
+        "expect_reward_lt": 0.7,
+    },
+    {
+        "task_id": "task_001_flat_plate",
+        "label": "10x_smaller_plate",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').box(8, 4, 0.5)",
+        "expect_reward_lt": 0.15,
+    },
+    {
+        "task_id": "task_001_flat_plate",
+        "label": "10x_bigger_plate",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').box(800, 400, 50)",
+        "expect_reward_lt": 0.7,
+    },
+    {
+        "task_id": "task_001_flat_plate",
+        "label": "wrong_proportions",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').box(80, 80, 80)",
+        "expect_reward_lt": 0.6,
+    },
+    {
+        "task_id": "task_002_box_with_hole",
+        "label": "perfect_match",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').box(50, 30, 20).faces('>Z').hole(10)",
+        "expect_reward_gt": 0.85,
+    },
+    {
+        "task_id": "task_002_box_with_hole",
+        "label": "box_no_hole",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').box(50, 30, 20)",
+        "expect_reward_gt": 0.0,
+    },
+    {
+        "task_id": "task_002_box_with_hole",
+        "label": "wrong_hole_diameter",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').box(50, 30, 20).faces('>Z').hole(25)",
+        "expect_reward_gt": 0.0,
+    },
+    {
+        "task_id": "task_002_box_with_hole",
+        "label": "cylinder_instead",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').cylinder(20, 15)",
+        "expect_reward_lt": 0.7,
+    },
+    {
+        "task_id": "task_003_cylinder_shaft",
+        "label": "box_instead",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').box(30, 30, 60)",
+        "expect_reward_lt": 0.8,
+    },
+    {
+        "task_id": "task_003_cylinder_shaft",
+        "label": "wrong_radius",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').cylinder(60, 5)",
+        "expect_reward_lt": 0.7,
+    },
+    {
+        "task_id": "task_006_hollow_tube",
+        "label": "solid_cylinder_no_hole",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').cylinder(40, 15)",
+        "expect_reward_lt": 0.85,
+    },
+    {
+        "task_id": "task_009_hexagonal_prism",
+        "label": "regular_box",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').box(30, 26, 25)",
+        "expect_reward_lt": 0.8,
+    },
+    {
+        "task_id": "task_016_cone",
+        "label": "cylinder_instead",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').cylinder(30, 20)",
+        "expect_reward_lt": 0.8,
+    },
+    {
+        "task_id": "task_018_sphere",
+        "label": "cube_instead",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').box(40, 40, 40)",
+        "expect_reward_lt": 0.8,
+    },
+    {
+        "task_id": "task_018_sphere",
+        "label": "tiny_sphere",
+        "code": "import cadquery as cq\nresult = cq.Workplane('XY').sphere(1)",
+        "expect_reward_lt": 0.15,
+    },
+    {
+        "task_id": "task_001_flat_plate",
+        "label": "syntax_error",
+        "code": "this is not valid python!!!",
+        "expect_reward_lt": 0.01,
+    },
+    {
+        "task_id": "task_001_flat_plate",
+        "label": "no_result_var",
+        "code": "import cadquery as cq\nx = cq.Workplane('XY').box(80, 40, 5)",
+        "expect_reward_lt": 0.01,
+    },
+]
+
+
+def compute_scenario_reward(task_dir: Path, code: str) -> dict:
+    t0 = time.time()
+
+    result = {
+        "reward_computed": False,
+        "total": 0.0,
+        "rexec": 0.0,
+        "rgeom": 0.0,
+        "reval": 0.0,
+        "iou_best6": 0.0,
+        "mean_cd_r": 0.0,
+        "median_cd_r": 0.0,
+        "vol_score": 0.0,
+        "bbox_score": 0.0,
+        "face_score": 0.0,
+        "euler_score": 0.0,
+        "error": None,
+    }
+
+    try:
+        from server.executor import execute_cadquery_code
+        exec_result = execute_cadquery_code(code, timeout=15.0)
+
+        if not exec_result["success"]:
+            result["error"] = f"exec_fail: {exec_result.get('error', '')[:100]}"
+            return result
+
+        props = exec_result["properties"]
+        if not props.get("is_valid", False) or props.get("volume_mm3", 0) <= 0:
+            result["error"] = "invalid_shape_or_zero_volume"
+            return result
+
+        result["rexec"] = 1.0
+
+        import cadquery as cq
+        import math
+        import numpy as np
+
+        local_ns = {"cq": cq, "cadquery": cq, "math": math}
+        exec(code, local_ns)
+        obj = local_ns["result"]
+        shape = obj.val() if hasattr(obj, "val") else obj
+
+        from server.preprocessor import normalize_shape, sample_surface_points, voxelize_in_bbox
+        normalized_shape, _ = normalize_shape(shape)
+        agent_points = sample_surface_points(normalized_shape, 2048)
+
+        gt_step_path = task_dir / "ground_truth_normalized.step"
+        if not gt_step_path.exists():
+            gt_step_path = task_dir / "ground_truth.step"
+        gt_wp = cq.importers.importStep(str(gt_step_path))
+        gt_shape = gt_wp.val()
+        gt_bb = gt_shape.BoundingBox()
+        bbox_min = [gt_bb.xmin, gt_bb.ymin, gt_bb.zmin]
+        bbox_max = [gt_bb.xmax, gt_bb.ymax, gt_bb.zmax]
+
+        agent_voxels = voxelize_in_bbox(normalized_shape, bbox_min, bbox_max, 64)
+        gt_voxels = voxelize_in_bbox(gt_shape, bbox_min, bbox_max, 64)
+        gt_points = np.load(str(task_dir / "surface_points.npy"))
+
+        import json as _json
+        with open(task_dir / "ground_truth.json") as f:
+            gt_data = _json.load(f)
+
+        from server.reward import best_of_6_iou, compute_mean_chamfer, compute_median_chamfer
+
+        iou_best = best_of_6_iou(agent_voxels, gt_voxels)
+        result["iou_best6"] = round(iou_best, 4)
+
+        bbox_mm = gt_data.get("bbox_mm", [1, 1, 1])
+        bbox_diag = sum(d**2 for d in bbox_mm) ** 0.5
+        threshold = bbox_diag * 0.1
+
+        mean_cd = compute_mean_chamfer(agent_points, gt_points)
+        median_cd = compute_median_chamfer(agent_points, gt_points)
+        mean_cd_r = max(0.0, 1.0 - mean_cd / threshold) if threshold > 0 else 0.0
+        median_cd_r = max(0.0, 1.0 - median_cd / threshold) if threshold > 0 else 0.0
+        result["mean_cd_r"] = round(mean_cd_r, 4)
+        result["median_cd_r"] = round(median_cd_r, 4)
+
+        rgeom = W_IOU * iou_best + W_MEAN_CD * mean_cd_r + W_MEDIAN_CD * median_cd_r
+        result["rgeom"] = round(rgeom, 4)
+
+        gt_vol = gt_data.get("volume_mm3", 0)
+        agent_vol = props.get("volume_mm3", 0)
+        if gt_vol > 0:
+            vol_score = max(0.0, min(agent_vol, gt_vol) / max(agent_vol, gt_vol))
+        else:
+            vol_score = 1.0 if agent_vol == 0 else 0.0
+        result["vol_score"] = round(vol_score, 4)
+
+        gt_bbox_sorted = sorted(gt_data.get("bbox_mm", [0, 0, 0]), reverse=True)
+        agent_bbox_sorted = sorted([
+            props.get("bbox_x_mm", 0),
+            props.get("bbox_y_mm", 0),
+            props.get("bbox_z_mm", 0),
+        ], reverse=True)
+        bbox_scores = []
+        for a, g in zip(agent_bbox_sorted, gt_bbox_sorted):
+            if g > 0:
+                bbox_scores.append(max(0.0, 1.0 - abs(a - g) / g))
+            else:
+                bbox_scores.append(1.0 if a == 0 else 0.0)
+        bbox_score = sum(bbox_scores) / 3.0 if bbox_scores else 0.0
+        result["bbox_score"] = round(bbox_score, 4)
+
+        face_score = 1.0 if props.get("dominant_face_type", "") == gt_data.get("dominant_face_type", "") else 0.0
+        result["face_score"] = face_score
+
+        euler_score = 1.0 if props.get("euler_characteristic", 2) == gt_data.get("euler_characteristic", 2) else 0.0
+        result["euler_score"] = euler_score
+
+        reval = W_VOLUME * vol_score + W_BBOX * bbox_score + W_FACE_TYPE * face_score + W_EULER * euler_score
+        result["reval"] = round(reval, 4)
+
+        total = result["rexec"] * (W_RGEOM * rgeom + W_REVAL * reval)
+        result["total"] = round(total, 4)
+        result["reward_computed"] = True
+
+    except Exception as e:
+        result["error"] = f"{type(e).__name__}: {str(e)[:100]}"
+        result["traceback"] = traceback.format_exc()
+
+    result["elapsed_s"] = round(time.time() - t0, 2)
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Verify reward scenarios with component breakdown")
+    parser.add_argument("--task", type=str, default=None, help="Filter to specific task_id")
+    parser.add_argument("--json", action="store_true", help="Output JSON instead of table")
+    args = parser.parse_args()
+
+    scenarios = SCENARIOS
+    if args.task:
+        scenarios = [s for s in scenarios if s["task_id"] == args.task]
+
+    if not scenarios:
+        print(f"No scenarios found for task={args.task}")
+        return 1
+
+    header = (
+        f"  {'TASK':30s} {'SCENARIO':25s} {'TOTAL':>6s}  "
+        f"{'Rexec':>5s}  {'IoU':>5s}  {'MnCD':>5s}  {'MdCD':>5s}  {'Rgeom':>5s}  "
+        f"{'Vol':>5s}  {'Bbox':>5s}  {'Face':>4s}  {'Eulr':>4s}  {'Reval':>5s}  "
+        f"{'TIME':>5s}  {'STATUS'}"
+    )
+
+    print(f"Reward scenario analysis ({len(scenarios)} scenarios)")
+    print(f"Weights: Rgeom={W_RGEOM} (IoU={W_IOU}, MnCD={W_MEAN_CD}, MdCD={W_MEDIAN_CD}) | Reval={W_REVAL} (Vol={W_VOLUME}, Bbox={W_BBOX}, Face={W_FACE_TYPE}, Euler={W_EULER})")
+    print("-" * 160)
+    print(header)
+    print("-" * 160)
+
+    all_results = []
+    pass_count, fail_count = 0, 0
+
+    for s in scenarios:
+        task_dir = TASKS_ROOT / s["task_id"]
+        r = compute_scenario_reward(task_dir, s["code"])
+        r["task_id"] = s["task_id"]
+        r["label"] = s["label"]
+
+        expectation_met = True
+        if "expect_reward_gt" in s and r["total"] <= s["expect_reward_gt"]:
+            expectation_met = False
+        if "expect_reward_lt" in s and r["total"] >= s["expect_reward_lt"]:
+            expectation_met = False
+
+        status = "PASS" if expectation_met else "FAIL"
+        if expectation_met:
+            pass_count += 1
+        else:
+            fail_count += 1
+
+        expect_str = ""
+        if "expect_reward_gt" in s:
+            expect_str = f" (exp >{s['expect_reward_gt']})"
+        if "expect_reward_lt" in s:
+            expect_str = f" (exp <{s['expect_reward_lt']})"
+
+        print(
+            f"  {s['task_id']:30s} {s['label']:25s} {r['total']:6.4f}  "
+            f"{r['rexec']:5.1f}  {r['iou_best6']:5.3f}  {r['mean_cd_r']:5.3f}  {r['median_cd_r']:5.3f}  {r['rgeom']:5.3f}  "
+            f"{r['vol_score']:5.3f}  {r['bbox_score']:5.3f}  {r['face_score']:4.1f}  {r['euler_score']:4.1f}  {r['reval']:5.3f}  "
+            f"{r.get('elapsed_s', 0):5.1f}s  {status}{expect_str}"
+        )
+        if r.get("error"):
+            print(f"    -> {r['error']}")
+
+        all_results.append(r)
+
+    print("-" * 160)
+    print(f"PASS: {pass_count}  |  FAIL: {fail_count}  |  Total: {len(scenarios)}")
+
+    if args.json:
+        out_path = TASKS_ROOT.parent / "reward_scenarios.json"
+        with open(out_path, "w") as f:
+            json.dump(all_results, f, indent=2, default=str)
+        print(f"\nSaved JSON to {out_path}")
+
+    return 0 if fail_count == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/verify_rewards.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""Verify that reference codes score ~1.0 when evaluated against their own ground truth.
+
+Prerequisites: run generate_ground_truth.py first.
+
+Usage:
+    python scripts/verify_rewards.py
+    python scripts/verify_rewards.py --task task_001_flat_plate
+"""
+import argparse
+import json
+import sys
+import time
+import traceback
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+TASKS_ROOT = Path(__file__).parent.parent / "server" / "tasks"
+
+
+def verify_reward_one(task_dir: Path) -> dict:
+    task_id = task_dir.name
+    t0 = time.time()
+
+    result = {
+        "task_id": task_id,
+        "reward_computed": False,
+        "reward_value": 0.0,
+        "detail": None,
+        "error": None,
+    }
+
+    gt_json = task_dir / "ground_truth.json"
+    if not gt_json.exists():
+        result["error"] = "No ground_truth.json — run generate_ground_truth.py first"
+        return result
+
+    ref_code = (task_dir / "reference_code.py").read_text()
+
+    try:
+        import cadquery as cq
+        import math
+        import numpy as np
+
+        local_ns = {"cq": cq, "cadquery": cq, "math": math}
+        exec(ref_code, local_ns)
+        obj = local_ns["result"]
+        shape = obj.val() if hasattr(obj, "val") else obj
+
+        from server.executor import execute_cadquery_code
+        exec_result = execute_cadquery_code(ref_code, timeout=15.0)
+        if not exec_result["success"]:
+            result["error"] = f"Execution failed: {exec_result['error']}"
+            return result
+        props = exec_result["properties"]
+
+        from server.preprocessor import sample_surface_points, voxelize_in_bbox, normalize_shape
+        normalized_shape, _ = normalize_shape(shape)
+        agent_points = sample_surface_points(normalized_shape, 2048)
+
+        gt_step_path = task_dir / "ground_truth_normalized.step"
+        if not gt_step_path.exists():
+            gt_step_path = task_dir / "ground_truth.step"
+        gt_wp = cq.importers.importStep(str(gt_step_path))
+        gt_shape = gt_wp.val()
+        gt_bb = gt_shape.BoundingBox()
+        bbox_min = [gt_bb.xmin, gt_bb.ymin, gt_bb.zmin]
+        bbox_max = [gt_bb.xmax, gt_bb.ymax, gt_bb.zmax]
+
+        agent_voxels = voxelize_in_bbox(normalized_shape, bbox_min, bbox_max, 64)
+        gt_voxels = voxelize_in_bbox(gt_shape, bbox_min, bbox_max, 64)
+
+        gt_points = np.load(str(task_dir / "surface_points.npy"))
+
+        from server.reward import (
+            compute_iou, best_of_6_iou,
+            compute_mean_chamfer, compute_median_chamfer,
+        )
+
+        iou_best = best_of_6_iou(agent_voxels, gt_voxels)
+
+        with open(gt_json) as f:
+            gt_data = json.load(f)
+
+        bbox_mm = gt_data.get("bbox_mm", [1, 1, 1])
+        bbox_diag = sum(d**2 for d in bbox_mm) ** 0.5
+        threshold = bbox_diag * 0.1
+
+        mean_cd = compute_mean_chamfer(agent_points, gt_points)
+        median_cd = compute_median_chamfer(agent_points, gt_points)
+        mean_cd_r = max(0, 1 - mean_cd / threshold) if threshold > 0 else 0
+        median_cd_r = max(0, 1 - median_cd / threshold) if threshold > 0 else 0
+
+        rgeom = 0.60 * iou_best + 0.20 * mean_cd_r + 0.20 * median_cd_r
+
+        gt_vol = gt_data.get("volume_mm3", 0)
+        agent_vol = props.get("volume_mm3", 0)
+        if gt_vol > 0:
+            volume_score = max(0.0, min(agent_vol, gt_vol) / max(agent_vol, gt_vol))
+        else:
+            volume_score = 1.0 if agent_vol == 0 else 0.0
+
+        norm_bb = normalized_shape.BoundingBox()
+        agent_bbox = sorted([round(norm_bb.xlen, 4), round(norm_bb.ylen, 4), round(norm_bb.zlen, 4)], reverse=True)
+        gt_bbox = sorted(gt_data["bbox_mm"], reverse=True)
+        bbox_scores = []
+        for a, g in zip(agent_bbox, gt_bbox):
+            if g > 0:
+                bbox_scores.append(max(0.0, 1.0 - abs(a - g) / g))
+            else:
+                bbox_scores.append(1.0 if a == 0 else 0.0)
+        bbox_score = sum(bbox_scores) / 3.0
+
+        target_dom = gt_data.get("dominant_face_type", "")
+        agent_dom = props.get("dominant_face_type", "")
+        face_type_score = 1.0 if agent_dom == target_dom else 0.0
+
+        gt_euler = gt_data.get("euler_characteristic", 2)
+        agent_euler = props.get("euler_characteristic", 2)
+        euler_score = 1.0 if agent_euler == gt_euler else 0.0
+
+        reval = 0.35 * volume_score + 0.30 * bbox_score + 0.15 * face_type_score + 0.20 * euler_score
+
+        rexec = 1.0
+        total = rexec * (0.80 * rgeom + 0.20 * reval)
+
+        result["reward_computed"] = True
+        result["reward_value"] = round(total, 4)
+        result["detail"] = {
+            "rexec": rexec,
+            "iou_best_of_6": round(iou_best, 4),
+            "mean_cd_reward": round(mean_cd_r, 4),
+            "median_cd_reward": round(median_cd_r, 4),
+            "rgeom": round(rgeom, 4),
+            "volume_score": round(volume_score, 4),
+            "bbox_score": round(bbox_score, 4),
+            "face_type_score": face_type_score,
+            "euler_score": euler_score,
+            "reval": round(reval, 4),
+        }
+
+    except Exception as e:
+        result["error"] = f"{type(e).__name__}: {e}"
+        result["traceback"] = traceback.format_exc()
+
+    result["elapsed_s"] = round(time.time() - t0, 2)
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Verify reward scores for reference codes")
+    parser.add_argument("--task", type=str, default=None, help="Specific task id")
+    args = parser.parse_args()
+
+    if args.task:
+        task_dirs = [TASKS_ROOT / args.task]
+    else:
+        task_dirs = sorted(TASKS_ROOT.glob("task_*"))
+
+    print(f"Verifying rewards for {len(task_dirs)} tasks...")
+    print("-" * 100)
+    print(f"  {'TASK':35s} {'STATUS':6s} {'REWARD':>7s}  {'IoU':>5s}  {'MnCD':>5s}  {'MdCD':>5s}  {'Rgeom':>5s}  {'Vol':>5s}  {'Bbox':>5s}  {'Face':>4s}  {'Eulr':>4s}  {'Reval':>5s}  {'TIME':>5s}")
+    print("-" * 100)
+
+    results = []
+    for task_dir in task_dirs:
+        r = verify_reward_one(task_dir)
+        reward = r.get("reward_value", 0)
+        status = "PASS" if reward > 0.85 else "WARN" if reward > 0.5 else "FAIL"
+        d = r.get("detail", {})
+
+        print(
+            f"  {r['task_id']:35s} {status:6s} {reward:7.4f}  "
+            f"{d.get('iou_best_of_6', 0):5.3f}  "
+            f"{d.get('mean_cd_reward', 0):5.3f}  "
+            f"{d.get('median_cd_reward', 0):5.3f}  "
+            f"{d.get('rgeom', 0):5.3f}  "
+            f"{d.get('volume_score', 0):5.3f}  "
+            f"{d.get('bbox_score', 0):5.3f}  "
+            f"{d.get('face_type_score', 0):4.1f}  "
+            f"{d.get('euler_score', 0):4.1f}  "
+            f"{d.get('reval', 0):5.3f}  "
+            f"{r.get('elapsed_s', 0):5.1f}s"
+        )
+        if r["error"]:
+            print(f"    ERROR: {r['error'][:200]}")
+        results.append(r)
+
+    print("-" * 100)
+    passed = sum(1 for r in results if r.get("reward_value", 0) > 0.85)
+    warned = sum(1 for r in results if 0.5 < r.get("reward_value", 0) <= 0.85)
+    failed = sum(1 for r in results if r.get("reward_value", 0) <= 0.5)
+    print(f"PASS (>0.85): {passed}  |  WARN (0.5-0.85): {warned}  |  FAIL (<0.5): {failed}")
+
+    out_path = TASKS_ROOT.parent / "verification_rewards.json"
+    with open(out_path, "w") as f:
+        json.dump(results, f, indent=2, default=str)
+    print(f"\nSaved to {out_path}")
+
+    return 0 if passed == len(results) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Cadforge environment server components."""
+
+from .cadforge_environment import CadforgeEnvironment
+
+__all__ = ["CadforgeEnvironment"]

server/app.py

@@ -0,0 +1,36 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:
+    raise ImportError(
+        "openenv is required for the web interface. Install dependencies with '\n    uv sync\n'"
+    ) from e
+
+try:
+    from ..models import CadforgeAction, CadforgeObservation
+    from .cadforge_environment import CadforgeEnvironment
+except (ImportError, ValueError):
+    from models import CadforgeAction, CadforgeObservation
+    from server.cadforge_environment import CadforgeEnvironment
+
+app = create_app(
+    CadforgeEnvironment,
+    CadforgeAction,
+    CadforgeObservation,
+    env_name="cadforge",
+    max_concurrent_envs=4,
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    import uvicorn
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/cadforge_environment.py

@@ -0,0 +1,363 @@
+import json
+import logging
+import pickle
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+import numpy as np
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+from .docs_search import search_docs
+from .executor import execute_cadquery_code
+from .reward import build_cadforge_rubric
+
+try:
+    from ..models import CadforgeAction, CadforgeObservation
+except ImportError:
+    from models import CadforgeAction, CadforgeObservation
+
+logger = logging.getLogger(__name__)
+
+TASKS_ROOT = Path(__file__).parent / "tasks"
+STEP_OUTPUT_DIR = Path("/tmp/cadforge_steps")
+
+STEP_EXPORT_RUNNER = r'''
+import sys
+import pickle
+import os
+
+try:
+    import cadquery as cq
+    import math
+
+    code = sys.stdin.buffer.read().decode("utf-8")
+    parts = code.split("\n---STEP_PATH---\n", 1)
+    user_code = parts[0]
+    step_path = parts[1].strip() if len(parts) > 1 else "/tmp/agent_shape.step"
+
+    local_ns = {"cq": cq, "cadquery": cq, "math": math}
+    exec(user_code, local_ns)
+
+    result = local_ns.get("result")
+    if result is None:
+        pickle.dump({"success": False, "error": "No variable named 'result' was defined"}, sys.stdout.buffer)
+        sys.exit(0)
+
+    if hasattr(result, "val"):
+        shape = result.val()
+    else:
+        shape = result
+
+    os.makedirs(os.path.dirname(step_path), exist_ok=True)
+    cq.exporters.export(cq.Workplane().add(shape), step_path, exportType="STEP")
+
+    pickle.dump({"success": True, "step_path": step_path}, sys.stdout.buffer)
+
+except Exception as e:
+    import traceback
+    pickle.dump({"success": False, "error": str(e), "traceback": traceback.format_exc()}, sys.stdout.buffer)
+'''
+
+
+class CadforgeEnvironment(Environment):
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        super().__init__()
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._task_data = None
+        self._task_dir = None
+        self._ground_truth = None
+        self._max_steps = 10
+        self._best_reward = 0.0
+        self._done = False
+        self._task_prompt = None
+        self._artifact_registry: List[Dict[str, Any]] = []
+        self._last_executed: Optional[str] = None
+        self._best_object_id: Optional[str] = None
+        self._reward_cache: Dict[str, float] = {}
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> CadforgeObservation:
+        t0 = time.time()
+
+        self._state = State(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+        )
+        self._best_reward = 0.0
+        self._done = False
+        self._artifact_registry = []
+        self._last_executed = None
+        self._best_object_id = None
+        self._reward_cache = {}
+
+        task_id = kwargs.get("task_id", None)
+        if task_id is None:
+            task_dirs = sorted(TASKS_ROOT.glob("task_*"))
+            if not task_dirs:
+                raise RuntimeError(f"No tasks found in {TASKS_ROOT}")
+            if seed is not None:
+                rng = np.random.RandomState(seed)
+                idx = rng.randint(0, len(task_dirs))
+            else:
+                idx = np.random.randint(0, len(task_dirs))
+            self._task_dir = task_dirs[idx]
+            task_id = self._task_dir.name
+        else:
+            self._task_dir = TASKS_ROOT / task_id
+
+        task_json_path = self._task_dir / "task.json"
+        if not task_json_path.exists():
+            raise RuntimeError(f"task.json not found at {task_json_path}")
+
+        with open(task_json_path) as f:
+            self._task_data = json.load(f)
+
+        self._task_prompt = self._task_data.get("prompt", "")
+        self._max_steps = self._task_data.get("max_steps", 10)
+
+        gt_json_path = self._task_dir / "ground_truth.json"
+        if gt_json_path.exists():
+            with open(gt_json_path) as f:
+                self._ground_truth = json.load(f)
+            self.rubric = build_cadforge_rubric(str(self._task_dir))
+        else:
+            self._ground_truth = None
+            self.rubric = None
+            logger.warning(f"No ground_truth.json for task {task_id}")
+
+        self._reset_rubric()
+
+        elapsed = time.time() - t0
+        logger.info(f"reset(task={task_id}) took {elapsed:.3f}s")
+
+        return CadforgeObservation(
+            task=self._task_prompt,
+            step_count=0,
+            done=False,
+            reward=0.0,
+            metadata={"task_id": task_id, "max_steps": self._max_steps},
+        )
+
+    def step(
+        self,
+        action: CadforgeAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> CadforgeObservation:
+        t0 = time.time()
+
+        if self._done:
+            return CadforgeObservation(
+                task=self._task_prompt,
+                step_count=self._state.step_count,
+                done=True,
+                reward=self._best_reward,
+                metadata={"message": "Episode already done"},
+            )
+
+        self._state.step_count += 1
+        action_type = action.action_type
+        params = action.params or {}
+
+        logger.info(f"step {self._state.step_count}: action_type={action_type}")
+
+        if action_type == "read_docs":
+            obs = self._handle_read_docs(params)
+        elif action_type == "execute_cadquery":
+            obs = self._handle_execute_cadquery(action, params)
+        elif action_type == "submit":
+            obs = self._handle_submit(params)
+        elif action_type == "render_object":
+            obs = self._handle_render_object(params)
+        else:
+            obs = CadforgeObservation(
+                task=self._task_prompt,
+                step_count=self._state.step_count,
+                done=False,
+                reward=0.0,
+                code_error=f"Unknown action_type: {action_type}",
+            )
+
+        if self._state.step_count >= self._max_steps and not self._done:
+            self._done = True
+            obs.done = True
+            obs.reward = 0.0
+            logger.info(f"Max steps reached without submit. Episode done. reward=0.")
+
+        elapsed = time.time() - t0
+        logger.info(f"step took {elapsed:.3f}s total")
+        return obs
+
+    def _handle_read_docs(self, params: dict) -> CadforgeObservation:
+        topic = params.get("topic")
+        query = params.get("query")
+        results = search_docs(topic=topic, query=query)
+
+        return CadforgeObservation(
+            task=self._task_prompt,
+            step_count=self._state.step_count,
+            done=False,
+            reward=0.0,
+            docs_results=results,
+        )
+
+    def _handle_execute_cadquery(self, action: CadforgeAction, params: dict) -> CadforgeObservation:
+        code = params.get("code", "")
+        if not code:
+            return CadforgeObservation(
+                task=self._task_prompt,
+                step_count=self._state.step_count,
+                done=False,
+                reward=0.0,
+                code_executed=False,
+                code_error="No code provided in params.code",
+                artifacts=self._artifact_registry[:] or None,
+                last_executed=self._last_executed,
+            )
+
+        exec_result = execute_cadquery_code(code, timeout=10.0)
+
+        if not exec_result["success"]:
+            return CadforgeObservation(
+                task=self._task_prompt,
+                step_count=self._state.step_count,
+                done=False,
+                reward=0.0,
+                code_executed=False,
+                code_error=exec_result.get("error", "Unknown execution error"),
+                artifacts=self._artifact_registry[:] or None,
+                last_executed=self._last_executed,
+            )
+
+        props = exec_result["properties"]
+        agent_visible_props = dict(props)
+
+        object_id = f"{self._state.episode_id}_step{self._state.step_count}"
+        step_path = str(STEP_OUTPUT_DIR / f"{object_id}.step")
+
+        export_result = self._export_agent_step(code, step_path)
+
+        raw_data = None
+        if export_result and export_result.get("success"):
+            raw_data = {"step_path": export_result["step_path"]}
+            artifact = {"object_id": object_id, "step_path": export_result["step_path"]}
+            self._artifact_registry.append(artifact)
+            self._last_executed = object_id
+        else:
+            error_msg = export_result.get("error", "unknown") if export_result else "export failed"
+            logger.warning(f"STEP export failed for {object_id}: {error_msg}")
+            self._last_executed = object_id
+
+        obs = CadforgeObservation(
+            task=self._task_prompt,
+            step_count=self._state.step_count,
+            done=False,
+            reward=0.0,
+            code_executed=True,
+            object_id=object_id,
+            object_properties=agent_visible_props,
+            artifacts=self._artifact_registry[:] or None,
+            last_executed=self._last_executed,
+        )
+        obs._raw_data = raw_data
+
+        reward = self._apply_rubric(action, obs)
+        self._reward_cache[object_id] = reward
+        logger.info(f"Reward for {object_id}: {reward:.4f} (cached)")
+
+        if reward > self._best_reward:
+            self._best_reward = reward
+            self._best_object_id = object_id
+            logger.info(f"New best reward: {self._best_reward:.4f} (object_id={object_id})")
+
+        obs.reward = reward
+        return obs
+
+    def _export_agent_step(self, code: str, step_path: str) -> Optional[Dict[str, Any]]:
+        t0 = time.time()
+        try:
+            payload = code + "\n---STEP_PATH---\n" + step_path
+            proc = subprocess.run(
+                [sys.executable, "-c", STEP_EXPORT_RUNNER],
+                input=payload.encode(),
+                capture_output=True,
+                timeout=30,
+            )
+
+            if proc.returncode != 0:
+                logger.warning(f"STEP export subprocess failed (rc={proc.returncode}): {proc.stderr[:500]}")
+                return {"success": False, "error": proc.stderr[:500].decode() if isinstance(proc.stderr, bytes) else proc.stderr[:500]}
+
+            data = pickle.loads(proc.stdout)
+            elapsed = time.time() - t0
+            logger.info(f"_export_agent_step took {elapsed:.3f}s, success={data.get('success')}")
+            return data
+
+        except Exception as e:
+            elapsed = time.time() - t0
+            logger.error(f"_export_agent_step failed after {elapsed:.3f}s: {e}")
+            return {"success": False, "error": str(e)}
+
+    def _handle_submit(self, params: dict) -> CadforgeObservation:
+        self._done = True
+
+        submit_object_id = params.get("object_id", None)
+        if submit_object_id is None:
+            submit_object_id = self._best_object_id
+            logger.info(f"Submit: no object_id provided, using best: {submit_object_id}")
+
+        if submit_object_id and submit_object_id in self._reward_cache:
+            submit_reward = self._reward_cache[submit_object_id]
+        else:
+            submit_reward = self._best_reward
+            logger.warning(
+                f"Submit: object_id={submit_object_id} not in reward cache, "
+                f"falling back to best_reward={self._best_reward:.4f}"
+            )
+
+        logger.info(
+            f"Submit: object_id={submit_object_id}, reward={submit_reward:.4f}, "
+            f"best_reward={self._best_reward:.4f}, best_object={self._best_object_id}"
+        )
+
+        return CadforgeObservation(
+            task=self._task_prompt,
+            step_count=self._state.step_count,
+            done=True,
+            reward=submit_reward,
+            artifacts=self._artifact_registry[:] or None,
+            last_executed=self._last_executed,
+            metadata={
+                "message": "Episode submitted",
+                "submitted_object_id": submit_object_id,
+                "submitted_reward": submit_reward,
+                "best_reward": self._best_reward,
+                "best_object_id": self._best_object_id,
+                "reward_cache": {k: round(v, 4) for k, v in self._reward_cache.items()},
+            },
+        )
+
+    def _handle_render_object(self, params: dict) -> CadforgeObservation:
+        return CadforgeObservation(
+            task=self._task_prompt,
+            step_count=self._state.step_count,
+            done=False,
+            reward=0.0,
+            metadata={"message": "render_object is not available in Phase 1"},
+        )
+
+    @property
+    def state(self) -> State:
+        return self._state

server/docs/concepts/brep-mindset.md

@@ -0,0 +1,121 @@
+# BRep vs CSG — The Core Mindset
+
+## What BRep Is
+
+**Boundary Representation (BRep)** defines a solid by its boundary: the faces, edges, and vertices
+that enclose it. The interior is implied - it is whatever is inside those boundaries.
+
+A BRep model has explicit **topology** (how faces connect to edges, edges connect to vertices)
+and **geometry** (the actual surfaces and curves those topological entities lie on).
+
+```
+Solid
+├── Shell (closed set of faces)
+│   ├── Face (bounded region of a surface)
+│   │   ├── Wire (closed loop of edges bounding the face)
+│   │   │   └── Edge (bounded curve)
+│   │   │       └── Vertex (point)
+```
+
+This hierarchy is what CadQuery exposes through selectors. When you write `.faces(">Z")`,
+you are querying the topology of a BRep solid.
+
+## What CSG Is
+
+**Constructive Solid Geometry (CSG)** defines a solid as a tree of Boolean operations on primitives:
+
+```
+union
+├── box(10, 10, 10)
+└── cut
+    ├── cylinder(r=3, h=15)
+    └── box(5, 5, 5)
+```
+
+CSG is intuitive and maps well to how humans think about "adding" and "removing" material.
+OpenSCAD is pure CSG. Many LLMs default to this mental model because most training examples use it.
+
+## Why CadQuery Is Different
+
+CadQuery's kernel (OpenCASCADE) is BRep-native. The model is always stored as BRep.
+Boolean operations exist but are expensive — they recompute the entire boundary from scratch.
+
+CadQuery's fluent API is designed around **working with existing topology**:
+- Select a face → define a new workplane on it → sketch → extrude
+- Select edges → apply fillet or chamfer directly
+- Select a face → shell inward
+
+These operations modify or extend the BRep directly, without rebuilding it from scratch.
+
+## The Practical Difference
+
+**CSG thinking** asks: *what shapes do I combine?*
+
+**BRep thinking** asks: *what topology already exists, and what can I build from it?*
+
+### Example: adding a boss to a plate
+
+CSG approach:
+```python
+plate = cq.Workplane("XY").box(50, 50, 5)
+boss = cq.Workplane("XY").cylinder(10, 8).translate((10, 10, 7.5))
+result = plate.union(boss)
+```
+
+BRep approach:
+```python
+result = (
+    cq.Workplane("XY")
+    .box(50, 50, 5)
+    .faces(">Z").workplane()
+    .center(10, 10)
+    .circle(8).extrude(10)
+)
+```
+
+The BRep approach:
+- Produces cleaner topology (no Boolean seam)
+- Is faster to compute
+- Keeps the chain readable
+- Leaves faces available for further selection
+
+### Example: hollowing a box
+
+CSG approach:
+```python
+outer = cq.Workplane("XY").box(20, 20, 20)
+inner = cq.Workplane("XY").box(16, 16, 20).translate((0, 0, 2))
+result = outer.cut(inner)
+```
+
+BRep approach:
+```python
+result = cq.Workplane("XY").box(20, 20, 20).faces(">Z").shell(-2)
+```
+
+## When Booleans Are Appropriate
+
+Not all Booleans are wrong. Use them when:
+
+- Combining **separately constructed solids** that have no shared topology
+- The geometry cannot be described as a profile operation (extrude/revolve/sweep/loft)
+- Working with imported STEP/IGES geometry that you need to subtract from
+- Using the Free Function API where operator syntax (`+`, `-`, `*`) is natural
+
+Even then, in the Free Function API, prefer `addHole()` and `replace()` over cut() when
+modifying individual faces — it avoids recomputing the full solid boundary.
+
+## BRep Vocabulary in CadQuery
+
+| Term | Meaning | CadQuery access |
+|------|---------|-----------------|
+| `Solid` | A closed volume | `.solids()` |
+| `Shell` | A set of connected faces (may be open) | `.shells()` |
+| `Face` | A bounded surface region | `.faces()` |
+| `Wire` | A closed or open loop of edges | `.wires()` |
+| `Edge` | A bounded curve | `.edges()` |
+| `Vertex` | A point | `.vertices()` |
+| `Compound` | A collection of any shapes | `.compounds()` |
+
+Understanding this hierarchy is essential for writing correct selectors and knowing
+which `.val()` / `.vals()` calls will return what type.

server/docs/concepts/free-function-api.md

@@ -0,0 +1,306 @@
+# Free Function API
+
+## Overview
+
+The Free Function API provides an alternative to the fluent Workplane API.
+It has no hidden state - every operation takes explicit inputs and returns explicit outputs.
+Selectors still work as methods on Shape objects, but all other operations are free functions.
+
+```python
+from cadquery.func import *
+```
+
+Use this API when:
+- Building shapes face-by-face or edge-by-edge
+- Lofting between non-planar edges or constructing organic surfaces
+- Avoiding booleans via `addHole()` / `replace()` for performance
+- Working in parametric surface space (`trim()`, `edgeOn()`, `wireOn()`)
+- The explicit, stateless style is clearer for the task at hand
+
+---
+
+## Primitives
+
+All primitives return Shape objects that can be immediately operated on.
+
+```python
+from cadquery.func import *
+
+e = segment((0, 0), (0, 1))     # line edge
+c = circle(1)                    # circular edge
+r = rect(2, 1)                   # rectangular wire
+f = plane(1, 1.5)                # flat face
+b = box(1, 1, 1)                 # solid box
+cy = cylinder(1, 2)              # solid cylinder (radius, height)
+sp = sphere(1)                   # solid sphere
+co = cone(1, 1.5)                # solid cone (r1, r2)
+```
+
+Combine unrelated shapes into a compound for display or export:
+
+```python
+result = compound(e, c.moved(x=2), f.moved(x=4), b.moved(x=6))
+```
+
+---
+
+## Shape Construction
+
+Build higher-level shapes from lower-level ones.
+
+```python
+e1 = segment((0, 0), (1, 0))
+e2 = segment((1, 0), (1, 1))
+
+w = wire(e1, e2)           # edges → wire
+f = face(circle(1))        # closed wire → face
+s = solid(f1, f2, f3)      # faces → solid
+sh = shell(f1, f2)         # faces → shell (open solid — use before solid() when sewing)
+cp = compound(s1, s2)      # shapes → compound
+```
+
+**`solid()` vs `shell()`:** Use `solid()` when all faces are already properly connected.
+Use `shell()` first to sew faces together when the topology needs explicit stitching
+(e.g., when adding protrusions or working with trimmed surfaces).
+
+---
+
+## Operations
+
+### Extrude
+
+Accepts a wire or a face. Direction is a 3-tuple vector.
+
+```python
+r = rect(1, 0.5)
+f = face(r)
+
+s1 = extrude(r, (0, 0, 2))      # wire → solid with open ends
+s2 = extrude(f, (0, 0, 1))      # face → closed solid
+```
+
+### Loft
+
+Lofts through a sequence of edges or wires. `cap=True` closes the ends automatically.
+
+```python
+s = loft(circle(1), circle(1.5).moved(z=5), circle(1).moved(z=10))
+s_capped = loft(rect(2, 1), circle(1).moved(z=5), cap=True)
+```
+
+For curvature-continuous end caps, use `cap()` instead of `fill()` after lofting:
+
+```python
+side = loft(circle(1), circle(1.3).moved(z=5), circle(1).moved(z=10))
+base = fill(side.edges("<Z"))                  # flat cap — no curvature continuity
+top  = cap(side.edges(">Z"), side)             # smooth cap — continuous with side
+result = solid(side, base, top)
+```
+
+### Sweep
+
+```python
+profile = rect(0.5, 0.3)
+path = segment((0, 0, 0), (0, 0, 10))   # straight path
+
+result = sweep(profile, path)
+```
+
+Spline paths are supported - see the CadQuery docs and tests for the correct
+`spline()` argument form, as dispatch is sensitive to argument types.
+
+### Revolve
+
+```python
+# revolve(face, axis_point, axis_direction, angle_degrees)
+f = face(rect(1, 0.5)).moved(x=2)
+result = revolve(f, (0, 0, 0), (0, 1, 0), 90)
+```
+
+---
+
+## Placement
+
+The Free Function API has no workplane. Position shapes with `.moved()` and `.move()`.
+
+```python
+b = box(1, 1, 1)
+
+b.moved(x=2)                    # translate
+b.moved(rx=90)                  # rotate 90° around X (degrees)
+b.moved(x=2, rz=45)             # translate and rotate
+b.move(z=5)                     # in-place variant (modifies and returns self)
+```
+
+### Patterns - multiple locations in one call
+
+Passing multiple position tuples to `.moved()` creates a **compound** of copies:
+
+```python
+peg = cylinder(1, 5)
+
+result = peg.moved(
+    (-5, -5, 0),
+    ( 5, -5, 0),
+    (-5,  5, 0),
+    ( 5,  5, 0),
+)   # compound of 4 pegs
+```
+
+### Face-relative placement
+
+Select the face and use its geometry to derive position:
+
+```python
+b = box(20, 20, 10)
+top = b.faces(">Z")
+z = top.Center().z
+
+boss = cylinder(3, 8).moved(z=z)
+result = b + boss
+```
+
+---
+
+## Boolean Operations
+
+Boolean ops are available as both operators and free functions.
+**Avoid booleans in loops** - they recompute the full boundary each time.
+
+```python
+c1 = cylinder(1, 2)
+c2 = cylinder(0.5, 3)
+
+r1 = c1 + c2          # union  (also: fuse(c1, c2))
+r2 = c1 - c2          # cut    (also: cut(c1, c2))
+r3 = c1 * c2          # intersect (also: intersect(c1, c2))
+r4 = c1 / plane()     # split  (also: split(c1, plane()))
+```
+
+Boolean ops work on 2D shapes (faces, wires) as well as solids:
+
+```python
+outer = plane(20, 20)
+inner = plane(10, 10)
+frame = outer - inner          # face with a hole
+result = extrude(frame, (0, 0, 5))
+```
+
+When unioning many shapes, combine into a compound first to reduce operation count:
+
+```python
+pins = [cylinder(0.5, 5).moved(x=i*1.5) for i in range(8)]
+result = box(20, 5, 5) - compound(pins)   # one boolean, not 8
+```
+
+---
+
+## Adding Features Without Booleans
+
+For complex shapes where boolean performance matters, use `addHole()` and `replace()`
+to modify individual faces directly rather than recomputing the full solid boundary.
+
+```python
+from cadquery.func import *
+
+w = 1
+r = 0.9 * w / 2
+
+b = box(w, w, w)
+b_bot = b.faces("<Z")
+b_top = b.faces(">Z")
+
+inner = extrude(circle(r), (0, 0, w))
+
+b_bot_hole = b_bot.addHole(inner.edges("<Z"))
+b_top_hole = b_top.addHole(inner.edges(">Z"))
+
+result = solid(
+    b.remove(b_top, b_bot).faces(),
+    b_bot_hole,
+    inner,
+    b_top_hole,
+)
+```
+
+For protrusions (adding material rather than removing it), sew with `shell()` first
+to give the kernel enough context to stitch the new faces correctly:
+
+```python
+b = box(1, 1, 1)
+b_top = b.faces(">Z")
+
+feat_side = extrude(circle(0.4).moved(b_top.Center()), (0, 0, 0.2))
+feat_top  = face(feat_side.edges(">Z"))
+feat      = shell(feat_side, feat_top)   # sew into a shell first
+
+b_top_hole = b_top.addHole(feat.edges("<Z"))
+b = b.replace(b_top, b_top_hole)
+
+sh = shell(b_top_hole, feat.faces("<Z"), ctx=(b, feat))
+result = solid(sh)
+```
+
+---
+
+## Text
+
+`text()` uses multimethod dispatch — **all arguments must be positional**.
+Keyword arguments will raise a `DispatchError`.
+
+```python
+from cadquery.func import *
+
+# Planar text along a line
+spine = segment((0, 0, 0), (30, 0, 0))
+result = text("CadQuery", 3, spine, planar=True)
+
+# Normal (projected) text along a spine on a surface
+# See the CadQuery docs for the full surface projection example
+```
+
+---
+
+## Parametric Surface Mapping
+
+Advanced: trim faces and edges in parametric (u, v) space.
+
+```python
+from cadquery.func import cylinder, edgeOn, wire
+
+base = cylinder(1.5, 3).faces("%CYLINDER")
+
+# Rectangular trim
+r = base.trim(-1.5, 0, 0, 1)
+
+# Construct an edge in parametric space and trim with it
+from math import pi
+pcurve = edgeOn(base, [(0, 0.5), (pi, 0.5), (pi, 1.5), (0, 1.5)], periodic=True)
+trimmed = base.trim(wire(pcurve))
+```
+
+Use `wireOn()` to map a 3D wire onto a surface, and `faceOn()` to map a face:
+
+```python
+from cadquery.func import sphere, text, faceOn
+
+base = sphere(5).faces()
+result = faceOn(base, text("CadQuery", 1))
+```
+
+---
+
+## Selectors in the Free Function API
+
+Selectors work identically to the fluent API — as string methods on any Shape object.
+
+```python
+b = box(20, 20, 10)
+
+top       = b.faces(">Z")
+side_faces = b.faces("#Z")
+circ_edges = b.faces(">Z").edges("%Circle")
+```
+
+No Workplane is needed. The same selector strings, combinators, and tag syntax all apply.
+See `concepts/selectors.md` for the full reference.

server/docs/concepts/selectors.md

@@ -0,0 +1,200 @@
+# Selectors
+
+Selectors filter the topology of a shape - faces, edges, wires, or vertices - down to the
+subset you want to operate on. They work the same way in both the fluent API and the
+Free Function API (as methods on Shape objects).
+
+## Selector Syntax
+
+Selectors are strings passed to `.faces()`, `.edges()`, `.wires()`, or `.vertices()`.
+
+### Axis-based selectors
+
+| Selector | Applies to | Meaning |
+|----------|-----------|---------|
+| `">X"` | faces, edges | Highest centroid along X |
+| `"<X"` | faces, edges | Lowest centroid along X |
+| `"\|X"` | faces | Normal is parallel to X axis (faces the ±X direction) |
+| `"#X"` | faces, edges | Face normal or edge direction is orthogonal to X axis |
+| `"+X"` | faces | Normal points in the +X direction |
+| `"-X"` | faces | Normal points in the -X direction |
+
+Replace `X` with `Y` or `Z` as needed.
+
+### Sorted index selectors
+
+`">>X[n]"` and `"<<X[n]"` sort entities by their centroid along an axis and pick by index (0-based).
+
+```python
+# Face with the second-highest Z centroid
+solid.faces(">>Z[1]")
+
+# Edge with the lowest X centroid
+solid.edges("<<X[0]")
+```
+
+**Warning:** index selectors are fragile. Adding fillets, chamfers, or other features
+changes the entity count and shifts indices. Prefer geometric selectors or tags.
+
+### Type selectors
+
+Filters by the geometric type of the surface or curve.
+
+| Selector | Meaning |
+|----------|---------|
+| `"%Plane"` | Planar faces |
+| `"%Cylinder"` | Cylindrical faces |
+| `"%Cone"` | Conical faces |
+| `"%Sphere"` | Spherical faces |
+| `"%Torus"` | Toroidal faces |
+| `"%Line"` | Linear edges |
+| `"%Circle"` | Circular edges |
+
+```python
+# All cylindrical faces
+solid.faces("%Cylinder")
+
+# All circular edges
+solid.edges("%Circle")
+```
+
+### Boolean combinators
+
+| Syntax | Meaning |
+|--------|---------|
+| `"not >Z"` | All faces except the highest Z face |
+| `">Z and \|X"` | Faces that are both highest Z AND normal parallel to X |
+| `">Z or <Z"` | Top and bottom faces |
+
+```python
+# All faces except the top
+solid.faces("not >Z")
+
+# Edges that are both circular and on the top face - use chaining instead
+solid.faces(">Z").edges("%Circle")
+```
+
+For complex filtering, chaining selectors (`.faces(...).edges(...)`) is clearer than
+combining them in a single string.
+
+## Tag-Based Selection
+
+Tags are the most stable selection mechanism. They survive feature additions that would
+shift index-based selectors.
+
+```python
+result = (
+    cq.Workplane("XY")
+    .box(20, 20, 10)
+    .faces(">Z").tag("top")
+    .end()
+    .faces("<Z").tag("bottom")
+    .end()
+    .faces(tag="top").workplane().hole(4)
+    .faces(tag="bottom").workplane().hole(2)
+)
+```
+
+Tag early - as soon as a face or edge is created that you will need later.
+Tags are stored on the Workplane object, not on the shape itself.
+
+## Selectors in the Free Function API
+
+Selectors work as methods on any Shape object - no Workplane needed.
+
+```python
+from cadquery.func import *
+
+b = box(20, 20, 10)
+
+top = b.faces(">Z")
+top_edges = b.faces(">Z").edges("%Circle")
+side_faces = b.faces("|Z")   # faces whose normal is parallel to Z i i.e. sides
+```
+
+The same selector strings work identically in both APIs.
+
+## How Selectors Match
+
+Understanding what a selector actually tests prevents subtle bugs.
+
+### `">Z"` — highest centroid
+
+Finds the entity whose **centroid** has the highest Z coordinate. On a simple box this
+is the top face. On a complex solid it may not be the face you expect - the centroid
+is the geometric center of the face area, not the highest point.
+
+### `"|X"` — normal parallel to axis
+
+Selects faces whose **outward normal** is parallel (in either direction) to the given axis.
+On a box, `"|X"` gives both the left and right faces.
+
+```python
+# Both faces whose normal is parallel to X
+solid.faces("|X")   # returns 2 faces on a box
+
+# Just the face pointing in +X
+solid.faces("+X")   # returns 1 face
+```
+
+### `"#X"` — orthogonal to axis
+
+Selects faces whose **normal** is orthogonal to the given axis, or edges whose
+**direction** is orthogonal to the given axis.
+
+On a box, `#Z` gives the four side faces (normals point in X or Y, which are orthogonal to Z),
+and the horizontal edges (direction lies in the XY plane, orthogonal to Z).
+
+```python
+# Side faces of a box (normals orthogonal to Z)
+solid.faces("#Z")   # 4 side faces
+
+# Horizontal edges (direction orthogonal to Z)
+solid.edges("#Z")   # 8 horizontal edges on a box
+```
+
+Contrast with `|Z`, which selects entities whose normal or direction is **parallel** to Z
+(top and bottom faces, vertical edges).
+
+## Common Mistakes
+
+### Expecting `">Z"` to return the topmost point
+
+`">Z"` returns the face with the highest **centroid Z**, not the face containing
+the highest Z vertex. On a slanted or irregular solid these can differ.
+
+### Using `"|Z"` when you mean `">Z"`
+
+`"|Z"` selects faces whose normal is parallel to Z - both top AND bottom faces on a box.
+`">Z"` selects only the top face (highest centroid).
+
+```python
+solid.faces("|Z")   # top and bottom - probably not what you want
+solid.faces(">Z")   # top face only
+```
+
+### Chaining selectors vs combining them
+
+Two chained calls filter progressively; a combined string filters in one pass.
+These are not always equivalent:
+
+```python
+# First selects all circular edges, then filters to those on >Z faces - may not work as expected
+solid.edges("%Circle and >Z")
+
+# Correct: select the top face first, then get its circular edges
+solid.faces(">Z").edges("%Circle")
+```
+
+### Index selectors shifting after feature changes
+
+```python
+# Fragile: index 1 may shift after a fillet is added
+solid.faces(">>Z[1]").workplane().hole(3)
+
+# Stable: tag the face when you create it
+solid.faces(">>Z[1]").tag("target").end()
+# ... add fillets or other features ...
+solid.faces(tag="target").workplane().hole(3)
+```
+

server/docs/concepts/workplanes.md

@@ -0,0 +1,274 @@
+# Workplanes
+
+## What a Workplane Is
+
+A workplane is a local 2D coordinate system attached to a point in 3D space.
+All sketch operations (circles, rectangles, polygons, splines) are defined in this
+local space, then extruded, revolved, swept, etc into 3D geometry.
+
+The workplane has:
+- An **origin** — the 2D (0, 0) point in 3D space
+- An **x-direction** — defines the local X axis
+- A **normal** — the Z axis of the local system (points "out" of the plane)
+
+## Creating a Workplane
+
+```python
+import cadquery as cq
+
+# Named planes — origin at (0,0,0)
+wp1 = cq.Workplane("XY")   # normal = +Z
+wp2 = cq.Workplane("YZ")   # normal = +X
+wp3 = cq.Workplane("XZ")   # normal = +Y
+
+# From a cq.Plane object - explicit origin and normal
+wp4 = cq.Workplane(cq.Plane(origin=(0, 0, 10), normal=(0, 0, 1)))
+
+# From an existing solid's face
+wp5 = solid.faces(">Z").workplane()
+
+# Offset along the face normal
+wp6 = solid.faces(">Z").workplane(offset=5)
+```
+
+## Moving the Workplane
+
+### `.workplane()` — attaches to selected geometry
+
+After selecting a face or edge, `.workplane()` creates a new plane on that entity.
+The origin defaults to the center of the selected entity (controlled by `centerOption`).
+
+```python
+result = (
+    cq.Workplane("XY")
+    .box(20, 20, 10)
+    .faces(">Z").workplane()   # plane is now on the top face
+    .circle(5).extrude(10)
+)
+```
+
+### `.transformed()` — offsets and rotates the current plane
+
+`.transformed()` moves the workplane relative to its current position.
+Rotation is in degrees around the local X, Y, Z axes (applied in that order).
+
+```python
+result = (
+    cq.Workplane("XY")
+    .box(20, 20, 10)
+    .faces(">Z").workplane()
+    .transformed(offset=(5, 5, 0), rotate=(0, 0, 45))
+    .rect(4, 4).extrude(3)
+)
+```
+
+`.transformed()` is cumulative — each call moves relative to the current plane, not the global origin.
+
+### `.center()` — shifts the 2D origin within the current plane
+
+```python
+solid.faces(">Z").workplane().center(10, 5).circle(3).extrude(5)
+```
+
+This shifts where (0, 0) is in the current plane. Useful for placing features
+without recalculating coordinates manually.
+
+## Placing a Sketch on a Workplane
+
+Instead of building a profile directly in the fluent chain, you can define a `cq.Sketch`
+independently and place it onto a workplane with `.placeSketch()`. This separates
+profile definition from placement and allows the same sketch to be reused in multiple locations.
+
+```python
+import cadquery as cq
+
+# Define the profile separately
+profile = (
+    cq.Sketch()
+    .rect(10, 10)
+    .circle(3, mode="s")   # subtract a circular hole from the rect
+)
+
+# Place it on a workplane and extrude
+result = (
+    cq.Workplane("XY")
+    .box(30, 30, 5)
+    .faces(">Z").workplane()
+    .placeSketch(profile)
+    .extrude(5)
+)
+```
+
+Sketches can also be placed at multiple locations in a single call by passing
+pre-moved sketch instances:
+
+```python
+s = cq.Sketch().circle(3)
+
+result = (
+    cq.Workplane("XY")
+    .box(30, 30, 5)
+    .faces(">Z").workplane()
+    .placeSketch(
+        s.moved(cq.Location((8, 8, 0))),
+        s.moved(cq.Location((-8, -8, 0))),
+    )
+    .extrude(5)
+)
+```
+
+The Sketch API also supports constraints, arcs, splines, and hull construction -
+operations that are cumbersome or impossible to express in the fluent chain alone.
+When a profile is complex, build it as a `cq.Sketch` and place it, rather than
+trying to encode it inline.
+
+## `centerOption` — Where the Origin Lands
+
+When calling `.workplane()` on a selected face, `centerOption` controls the origin placement.
+
+| Value | Origin location |
+|-------|----------------|
+| `"CenterOfMass"` | Center of mass of the face |
+| `"CenterOfBoundBox"` | Center of the bounding box |
+| `"ProjectedOrigin"` | Projects the parent workplane's origin onto the new plane (default) |
+
+```python
+# Explicit is always safer
+solid.faces(">Z").workplane(centerOption="CenterOfBoundBox")
+```
+
+**Never assume the default matches your intent.** For symmetric faces it usually
+doesn't matter, but for irregular faces it can place the origin far from where you expect.
+
+## The Workplane Stack
+
+The Workplane object maintains a stack of shapes. Operations push results onto the stack;
+selectors filter the stack. This is how the fluent chain works.
+
+```python
+result = (
+    cq.Workplane("XY")
+    .box(20, 20, 10)        # stack: [box solid]
+    .faces(">Z")            # stack: [top face]
+    .workplane()            # stack: [top face], plane updated
+    .circle(5)              # stack: [circle wire]
+    .extrude(10)            # stack: [new solid]
+)
+```
+
+Key rules:
+- `.val()` returns the first item on the stack as a `Shape`
+- `.vals()` returns all items on the stack as a list of `Shape`
+- `.end(n)` pops `n` levels back up the chain (default 1)
+- `.newObject(list)` replaces the stack with a new list
+
+## Common Mistakes
+
+### Forgetting that coordinates are local
+
+After `.workplane()`, all coordinates are in the **local** frame, not global.
+
+```python
+# Wrong mental model: thinking (10, 10) is a global position
+solid.faces(">Z").workplane().circle(3).extrude(5)   # circle at local (0,0) = face center
+
+# Correct: use .center() or .transformed() to shift within the local frame
+solid.faces(">Z").workplane().center(10, 10).circle(3).extrude(5)
+```
+
+### Losing context after `.tag()`
+
+`.tag()` records the current stack state but does not change it.
+After tagging, chain `.end()` to return to the solid before continuing.
+
+```python
+result = (
+    cq.Workplane("XY")
+    .box(20, 20, 10)
+    .faces(">Z").tag("top")
+    .end()                          # back to the solid
+    .faces("<Z").workplane().hole(4)
+)
+```
+
+### Cut going the wrong direction — forgetting `invert=True`
+
+The workplane normal points **outward** from the selected face by default.
+Cut operations (`.cutBlind()`, `.extrude(..., combine="cut")`) remove material
+in the direction of the normal - so cutting from the top face will cut upward,
+away from the solid, removing nothing.
+
+Use `invert=True` to flip the normal inward when you need to cut into the solid
+from an outward-facing face:
+
+```python
+# Wrong: cuts upward away from the solid — no material removed
+solid.faces(">Z").workplane().circle(3).cutBlind(5)
+
+# Correct: invert flips the normal to point into the solid
+solid.faces(">Z").workplane(invert=True).circle(3).cutBlind(5)
+```
+
+This also applies to extrusions where you want to build downward (into the solid)
+rather than upward. When in doubt, check which direction the face normal points
+relative to the solid's interior.
+
+### Operating on a face without creating a workplane
+
+After selecting a face, some operations (`.hole()`, `.shell()`, `.fillet()`) work
+directly on the selected geometry without needing a workplane. Others require one.
+Skipping `.workplane()` when it is needed will silently use whatever plane was
+active before the face selection, producing geometry in the wrong position or orientation.
+
+```python
+# Fine - .hole() works directly on the selected face
+solid.faces(">Z").hole(3)
+
+# Fine - .shell() operates on the selected face
+solid.faces(">Z").shell(-2)
+
+# Wrong - .circle().extrude() needs a workplane; this uses the previous plane context
+solid.faces(">Z").circle(3).extrude(5)
+
+# Correct
+solid.faces(">Z").workplane().circle(3).extrude(5)
+```
+
+When in doubt, always call `.workplane()` after a face selection before sketching.
+
+### Using `.workplane()` without a prior face selection
+
+Calling `.workplane()` without first selecting a face creates a plane at the
+center of whatever is on the stack - often not what you want.
+Always select a face first.
+
+```python
+# Ambiguous
+solid.workplane().circle(3).extrude(5)
+
+# Explicit
+solid.faces(">Z").workplane().circle(3).extrude(5)
+```
+
+## Workplanes in the Free Function API
+
+The Free Function API has no workplane concept. Placement is done with `.moved()` and `.move()`.
+
+```python
+from cadquery.func import *
+
+b = box(20, 20, 10)
+
+# Place a feature by moving it to the right position, then fuse or addHole
+boss = cylinder(5, 10).moved(z=10)   # sits on top of the box
+result = b + boss
+```
+
+For face-relative placement, select the face and use its properties:
+
+```python
+top = b.faces(">Z")
+origin = top.Center()   # returns a Vector
+boss = cylinder(5, 10).moved(z=origin.z)
+result = b + boss
+```

server/docs/patterns/anti-patterns.md

@@ -0,0 +1,353 @@
+# Anti-Patterns
+
+Common mistakes LLMs make when generating CadQuery code, and how to fix them.
+
+---
+
+## 1. The CSG Reflex — Booleans Instead of Feature Operations
+
+The most pervasive anti-pattern: reaching for `.union()` / `.cut()` when a direct
+feature operation would be cleaner, faster, and produce better topology.
+
+| Instead of... | Use... |
+|--------------|--------|
+| `.union(cylinder(...))` for a boss | `.faces(...).workplane().circle(r).extrude(h)` |
+| `.cut(cylinder(...))` for a hole | `.faces(...).hole(diameter)` |
+| `.cut(box(...))` for a pocket | `.faces(...).workplane().rect(w, h).cutBlind(depth)` |
+| `.union(...)` for a chamfered edge | `.edges(...).chamfer(d)` |
+| `.union(...)` for a filleted edge | `.edges(...).fillet(r)` |
+| `.cut(shell_solid)` to hollow | `.faces(...).shell(thickness)` |
+
+Booleans rebuild the full boundary from scratch. Feature operations extend or modify
+the existing BRep directly - they are faster and leave cleaner topology for subsequent
+selections.
+
+**Use booleans only when combining genuinely separate solids** or when the geometry
+cannot be expressed as a profile operation.
+
+---
+
+## 2. Using `.translate()` on a Workplane Chain
+
+`.translate()` is a method on `Shape` objects, not on `Workplane` objects. Calling it
+in a fluent chain after building geometry moves the shape, but does so in global
+coordinates — bypassing the workplane system entirely.
+
+```python
+# Wrong: translate is called on the Workplane, not the Shape
+result = cq.Workplane("XY").box(10, 10, 10).translate((5, 0, 0))
+
+# If you need to position geometry, use workplane placement instead
+result = cq.Workplane("XY").center(5, 0).box(10, 10, 10)
+
+# Or move the workplane origin explicitly
+result = cq.Workplane(cq.Plane(origin=(5, 0, 0))).box(10, 10, 10)
+
+# .translate() is valid when called on a Shape extracted from the chain
+shape = cq.Workplane("XY").box(10, 10, 10).val()
+moved = shape.translate(cq.Vector(5, 0, 0))
+```
+
+---
+
+## 3. Building in Global Coordinates Instead of Using Workplanes
+
+Hardcoding global coordinates creates scripts that are brittle and hard to modify.
+Use workplanes and relative positioning instead.
+
+```python
+# Wrong: all positions hardcoded in global space
+result = (
+    cq.Workplane("XY")
+    .box(30, 30, 10)
+    .union(cq.Workplane("XY").cylinder(5, 8).translate((0, 0, 9)))
+    .union(cq.Workplane("XY").cylinder(5, 8).translate((10, 10, 9)))
+)
+
+# Right: build relative to existing faces
+result = (
+    cq.Workplane("XY")
+    .box(30, 30, 10)
+    .faces(">Z").workplane()
+    .circle(5).extrude(8)            # center boss
+    .faces(">Z").workplane()
+    .center(10, 10).circle(5).extrude(8)   # offset boss
+)
+```
+
+---
+
+## 4. Forgetting `combine=False` on `.extrude()`
+
+By default, `.extrude()` unions the new solid with whatever is on the context stack.
+If you want a separate solid (e.g., to combine later or export independently),
+pass `combine=False`.
+
+```python
+# Default: extrusion is unioned into the existing solid
+result = solid.faces(">Z").workplane().circle(3).extrude(5)
+
+# Separate solid
+new_part = cq.Workplane("XY").circle(3).extrude(5, combine=False)
+```
+
+The inverse mistake also occurs: forgetting that `combine=True` is the default,
+and then trying to union the result again — producing a double union.
+
+---
+
+## 5. Misreading `.cutBlind()` Direction
+
+`.cutBlind(depth)` cuts in the direction of the workplane normal. The normal points
+**outward** from the selected face by default, so cutting from the top face without
+inverting will cut away from the solid.
+
+```python
+# Wrong: cuts upward, away from the solid
+solid.faces(">Z").workplane().rect(5, 5).cutBlind(3)
+
+# Correct: invert=True flips the normal into the solid
+solid.faces(">Z").workplane(invert=True).rect(5, 5).cutBlind(3)
+```
+
+Also applies to `.extrude(..., combine="cut")`.
+
+---
+
+## 6. `.val()` on a Multi-Item Stack
+
+`.val()` returns the **first** item on the stack. It does not error if there are
+multiple items - it silently discards the rest. Use `.vals()` when you need all items.
+
+```python
+solid = cq.Workplane("XY").box(10, 10, 10)
+
+# Returns one Face - the first face in iteration order, not necessarily ">Z"
+face = solid.faces().val()
+
+# Returns all 6 faces as a list
+faces = solid.faces().vals()
+
+# To get a specific face as a Shape, select first
+top_face = solid.faces(">Z").val()
+```
+
+---
+
+## 7. Misusing `.each()`
+
+`.each(callback)` calls `callback` on every item in the stack and **replaces the stack**
+with the results. The callback must return a `Shape`. It is not for iteration with
+side effects.
+
+```python
+# Wrong: callback doesn't return a Shape; result is undefined
+solid.edges().each(lambda e: print(e.Length()))
+
+# Wrong: trying to accumulate results
+results = []
+solid.faces().each(lambda f: results.append(f))  # each() ignores the return value None
+
+# Right: use .each() to transform stack items
+# e.g., get the center point of each face as a Vertex
+centers = solid.faces().each(lambda f: f.Center())
+
+# For iteration/inspection, use .vals() instead
+for face in solid.faces().vals():
+    print(face.Area())
+```
+
+---
+
+## 8. Losing the Solid Context After a Selector
+
+After `.faces(...)` or `.edges(...)`, the stack contains only the selected entities —
+not the full solid. Calling `.workplane()` on a face selection is correct;
+calling feature operations directly on the selection without a workplane can
+silently use the wrong context.
+
+```python
+# Wrong: after .faces(), the solid is not the active context
+solid.faces(">Z").box(5, 5, 3)   # adds a new box to the face selection context, not the solid
+
+# Correct: use .workplane() to re-establish context for sketching
+solid.faces(">Z").workplane().rect(5, 5).extrude(3)
+
+# Correct: use .end() to return to the solid context
+solid.faces(">Z").tag("top").end().faces("<Z").workplane().hole(3)
+```
+
+---
+
+## 9. Assuming `centerOption` Default
+
+The default `centerOption="ProjectedOrigin"` projects the parent workplane's origin
+onto the new face - which is often not the face center and can place the origin
+well outside the face bounds on irregular geometry.
+
+```python
+# Fragile: origin placement depends on face shape
+solid.faces(">Z").workplane().circle(3).extrude(5)
+
+# Explicit and predictable
+solid.faces(">Z").workplane(centerOption="CenterOfBoundBox").circle(3).extrude(5)
+```
+
+---
+
+## 10. Index Selector Fragility
+
+Selectors like `">>Z[1]"` depend on a sorted count of all matching entities.
+Adding fillets, chamfers, holes, or shells changes the entity count and can
+silently shift which entity is selected.
+
+```python
+# Fragile: index may shift after any feature is added
+solid.faces(">>Z[1]").workplane().hole(3)
+
+# Robust: tag the face before adding features
+solid = (
+    cq.Workplane("XY")
+    .box(20, 20, 20)
+    .faces(">>Z[1]").tag("target")
+    .end()
+    .edges(">Z").fillet(1)          # this would shift the index above
+    .faces(tag="target").workplane().hole(3)
+)
+```
+
+---
+
+## 11. Mixing Fluent and Free Function APIs Unintentionally
+
+The two APIs are not interchangeable mid-script. A `Workplane` object is not
+a `Shape`, and Free Function operations do not accept `Workplane` objects.
+
+```python
+from cadquery.func import *
+import cadquery as cq
+
+# Wrong: passing a Workplane to a free function
+b = box(10, 10, 10)
+wp = cq.Workplane("XY").box(5, 5, 5)
+result = b + wp   # TypeError — wp is not a Shape
+
+# Correct: extract the Shape from the Workplane first
+wp_shape = cq.Workplane("XY").box(5, 5, 5).val()
+result = b + wp_shape
+```
+
+When mixing is intentional, always extract with `.val()` or `.vals()` before
+passing to Free Function API operations.
+
+---
+
+## 12. Unclosed Wires
+
+When building a profile with `.lineTo()`, `.spline()`, `.threePointArc()`, etc.,
+the wire must be closed before `.extrude()` or `.revolve()`. An unclosed wire
+produces an error or unexpected open shell.
+
+```python
+# Wrong: missing .close()
+result = (
+    cq.Workplane("XY")
+    .moveTo(0, 0)
+    .lineTo(10, 0)
+    .lineTo(10, 5)
+    .lineTo(0, 5)
+    .extrude(3)   # error - wire is not closed
+)
+
+# Correct
+result = (
+    cq.Workplane("XY")
+    .moveTo(0, 0)
+    .lineTo(10, 0)
+    .lineTo(10, 5)
+    .lineTo(0, 5)
+    .close()
+    .extrude(3)
+)
+```
+
+---
+
+## 13. Free Function API: Boolean in a Loop
+
+Boolean operations in the Free Function API (and the fluent API) are expensive
+because they recompute the full boundary. Never perform them in a loop.
+
+```python
+from cadquery.func import *
+
+holes = [cylinder(0.5, 5).moved(x=i*2) for i in range(10)]
+
+# Wrong: 10 sequential boolean operations
+result = box(20, 5, 5)
+for h in holes:
+    result = result - h
+
+# Correct: combine into a compound first, then subtract once
+result = box(20, 5, 5) - compound(holes)
+```
+
+---
+
+## 14. `BREP_API command not done` Errors
+
+This error comes from the OpenCASCADE kernel and means a BRep operation could not be
+completed geometrically. It is not a CadQuery bug — it means the requested geometry
+is invalid or degenerate. The error message does not identify which operation failed.
+
+**Common causes:**
+
+### Fillet or chamfer radius too large
+
+A fillet fails when its radius is larger than the shortest adjacent edge, or when
+adjacent fillets overlap each other.
+
+```python
+# Fails if the box edge is shorter than radius=5, or if adjacent fillets intersect
+solid.edges("|Z").fillet(5)   # BREP_API command not done
+```
+
+Fixes:
+- Reduce the radius
+- Fillet edges in separate calls, smallest features first
+- Fillet different edge groups separately rather than all at once
+
+```python
+# Apply smaller fillets to shorter edges first
+result = (
+    cq.Workplane("XY")
+    .box(20, 20, 5)
+    .edges("|Z").fillet(1)      # vertical edges first
+    .edges(">Z").fillet(0.5)    # then top perimeter with smaller radius
+)
+```
+
+### Self-intersecting profiles
+
+A profile (wire or sketch) that crosses itself cannot be extruded, revolved, or swept.
+This includes profiles where an arc or spline curves back through the outline.
+
+Check that:
+- All `lineTo()` / `spline()` sequences form a simple (non-self-intersecting) closed loop
+- Revolve profiles do not cross the axis of revolution
+- Sweep profiles are small enough to navigate tight path curvature without self-intersection
+
+### Self-intersecting sweep
+
+A sweep fails when the profile is too large relative to the path curvature — the
+extruded solid folds back on itself at tight bends.
+
+Reduce the profile size or increase the path radius.
+
+### Shell thickness too large
+
+`.shell()` fails when the thickness is larger than the smallest local radius of
+curvature — the offset surface self-intersects.
+
+Reduce the shell thickness or simplify the geometry before shelling.
+

server/docs/patterns/common-patterns.md

@@ -0,0 +1,278 @@
+# Common Patterns
+
+Idiomatic CadQuery recipes for tasks that come up frequently.
+Each pattern shows the preferred approach and explains why.
+
+---
+
+## Fluent API Patterns
+
+### Base solid with features on multiple faces
+
+Build the base first, then add features face by face. Tag faces before adding
+features that might change topology.
+
+```python
+import cadquery as cq
+
+result = (
+    cq.Workplane("XY")
+    .box(40, 30, 15)
+    .faces(">Z").tag("top")
+    .faces("<Z").tag("bottom")
+    .end()
+    .faces(tag="top").workplane()
+    .rect(20, 15).cutBlind(-5)          # pocket on top
+    .faces(tag="bottom").workplane()
+    .hole(6)                             # through hole from bottom
+    .edges("|Z").fillet(2)               # fillet vertical edges last
+)
+```
+
+### Polar pattern of features
+
+Use `.polarArray()` to place features at equal angular intervals.
+
+```python
+result = (
+    cq.Workplane("XY")
+    .cylinder(5, 20)
+    .faces(">Z").workplane()
+    .polarArray(radius=8, startAngle=0, angle=360, count=6)
+    .hole(2, depth=8)
+)
+```
+
+### Rectangular pattern of features
+
+Use `.rarray()` to place features in a grid.
+
+```python
+result = (
+    cq.Workplane("XY")
+    .box(40, 40, 10)
+    .faces(">Z").workplane()
+    .rarray(xSpacing=10, ySpacing=10, xCount=3, yCount=3, center=True)
+    .hole(3, depth=8)
+)
+```
+
+### Revolve a profile
+
+Define the profile on a plane that includes the rotation axis, then revolve.
+The axis is always on the X axis of the workplane by default.
+
+```python
+result = (
+    cq.Workplane("XZ")
+    .moveTo(5, 0)
+    .lineTo(5, 10)
+    .lineTo(8, 10)
+    .lineTo(8, 6)
+    .lineTo(5, 6)
+    .close()
+    .revolve(angleDegrees=360, axisStart=(0, 0, 0), axisEnd=(0, 1, 0))
+)
+```
+
+### Sweep a profile along a path
+
+Define the path, then the profile, then sweep. The profile is placed perpendicular
+to the path at its start point.
+
+```python
+path = (
+    cq.Workplane("XZ")
+    .moveTo(0, 0)
+    .spline([(10, 5), (20, 0)], includeCurrent=True)
+)
+
+result = (
+    cq.Workplane("YZ")
+    .circle(2)
+    .sweep(path)
+)
+```
+
+### Loft between profiles
+
+Chain profiles on the same Workplane — each sketch pushed onto the stack before
+`.loft()` becomes a section. Use `.workplane(offset=...)` to move between levels.
+
+```python
+result = (
+    cq.Workplane("XY")
+    .rect(20, 10)
+    .workplane(offset=15)
+    .circle(6)
+    .loft()
+)
+```
+
+### Shell a solid
+
+Select the face(s) to open before calling `.shell()`. Negative thickness = inward.
+
+```python
+# Open-top box
+result = cq.Workplane("XY").box(30, 20, 15).faces(">Z").shell(-2)
+
+# Open on two opposite faces
+result = cq.Workplane("XY").box(30, 20, 15).faces(">Z").shell(-2)
+```
+
+### Reusable sketch profile with `.placeSketch()`
+
+Define the profile once and place it at multiple locations.
+
+```python
+slot = (
+    cq.Sketch()
+    .slot(8, 3)   # length, width
+)
+
+result = (
+    cq.Workplane("XY")
+    .box(40, 20, 8)
+    .faces(">Z").workplane()
+    .placeSketch(
+        slot.moved(cq.Location((-10, 0, 0))),
+        slot.moved(cq.Location((10, 0, 0))),
+    )
+    .cutBlind(-4)
+)
+```
+
+### Selecting edges for fillet/chamfer
+
+Fillet or chamfer specific edges by combining type and position selectors.
+
+```python
+result = (
+    cq.Workplane("XY")
+    .box(20, 20, 20)
+    .edges(">Z").chamfer(1)          # top face perimeter edges
+    .edges("<Z").fillet(2)           # bottom face perimeter edges
+    .edges("|Z").fillet(1)           # vertical edges
+)
+```
+
+---
+
+## Free Function API Patterns
+
+### Loft with curvature-continuous cap
+
+Use `loft()` for the side and `cap()` (not `fill()`) for the top when you need
+the top to maintain curvature continuity with the side surface.
+
+```python
+from cadquery.func import *
+
+r = 5
+h = 10
+
+bottom = circle(r)
+mid = circle(r * 1.3).moved(z=h * 0.5)
+top_edge_guide = circle(r).moved(z=h)
+
+side = loft(bottom, mid, top_edge_guide)
+base = fill(side.edges("<Z"))
+top = cap(side.edges(">Z"), side)   # curvature-continuous with side
+
+result = solid(side, base, top)
+```
+
+### Adding a hole without a boolean
+
+For performance on complex shapes, use `addHole()` instead of subtracting a cylinder.
+
+```python
+from cadquery.func import *
+
+w = 1
+r = 0.9*w/2
+
+# box
+b = box(w, w, w)
+# bottom face
+b_bot = b.faces('<Z')
+# top faces
+b_top = b.faces('>Z')
+
+# inner face
+inner = extrude(circle(r), (0,0,w))
+
+# add holes to the bottom and top face
+b_bot_hole = b_bot.addHole(inner.edges('<Z'))
+b_top_hole = b_top.addHole(inner.edges('>Z'))
+
+# construct the final solid
+result = solid(
+    b.remove(b_top, b_bot).faces(), #side faces
+    b_bot_hole, # bottom with a hole
+    inner, # inner cylinder face
+    b_top_hole, # top with a hole
+)
+```
+
+### Pattern with `.moved()`
+
+Pass multiple location tuples to `.moved()` to create a compound of copies.
+
+```python
+from cadquery.func import *
+
+peg = cylinder(2, 8)
+
+# 4 pegs in a 2x2 grid
+result = peg.moved(
+    (-5, -5, 0),
+    ( 5, -5, 0),
+    (-5,  5, 0),
+    ( 5,  5, 0),
+)
+```
+
+### Boolean on 2D shapes
+
+Boolean operators work on faces and wires, not just solids.
+Useful for constructing profiles before extruding.
+
+```python
+from cadquery.func import *
+
+outer = plane(20, 20)
+cutout = plane(10, 10)
+
+profile = outer - cutout   # frame-shaped face with hole
+result = extrude(profile, (0, 0, 5))   # hollow frame solid
+```
+
+### Text along a spine
+
+`text()` takes positional arguments — keyword args will fail multimethod dispatch.
+For planar text, pass a line segment as the spine with `planar=True`.
+For text projected onto a curved surface, see the full example in the CadQuery docs.
+
+```python
+from cadquery.func import *
+
+from math import pi
+
+# parameters
+D = 5
+H = 2*D
+S = H/10
+TH = S/10
+TXT = "CadQuery"
+
+c = cylinder(D, H).moved(rz=-135)
+spine = (c*plane().moved(z=D)).edges().trim(pi/2, pi)
+
+# planar
+r1 = text(TXT, 1, spine, planar=True).moved(z=-S)
+```
+
+```
+

server/docs/reference/Untitled

@@ -0,0 +1 @@
+I'm just going to do this one thing. I think in Cadforge, the original documentation that they have on the website has a list of examples. I think they are even present in our folder, in docs, in @examples.rst, where you have examples. I was just thinking if we can use those examples to get harder tasks and work with them. Let's add them; let's do that.

server/docs/reference/examples.rst

@@ -0,0 +1,1705 @@
+.. _examples:
+
+.. currentmodule:: cadquery
+
+*********************************
+Examples
+*********************************
+
+
+
+The examples on this page can help you learn how to build objects with CadQuery.
+
+They are organized from simple to complex, so working through them in order is the best way to absorb them.
+
+Each example lists the API elements used in the example for easy reference.
+Items introduced in the example are marked with a **!**
+
+
+
+.. note::
+
+    We strongly recommend installing `CQ-editor <https://github.com/CadQuery/CQ-editor>`_,
+    so that you can work along with these examples interactively. See :ref:`installation` for more info.
+
+    If you do, make sure to take these steps so that they work:
+
+       1. import cadquery as cq
+       2. add the line ``show_object(result)``  at the end. The samples below are autogenerated, but they use a different
+          syntax than the models on the website need to be.
+
+.. contents:: List of Examples
+    :backlinks: entry
+
+
+Simple Rectangular Plate
+------------------------
+
+Just about the simplest possible example, a rectangular box
+
+.. cadquery::
+
+    result = cadquery.Workplane("front").box(2.0, 2.0, 0.5)
+
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane` **!**
+        * :py:meth:`Workplane.box` **!**
+
+Plate with Hole
+------------------------
+
+A rectangular box, but with a hole added.
+
+"\>Z" selects the top most face of the resulting box. The hole is located in the center because the default origin
+of a working plane is the projected origin of the last Workplane, the last Workplane having origin at (0,0,0) the
+projection is at the center of the face. The default hole depth is through the entire part.
+
+
+.. cadquery::
+
+        # The dimensions of the box. These can be modified rather than changing the
+        # object's code directly.
+        length = 80.0
+        height = 60.0
+        thickness = 10.0
+        center_hole_dia = 22.0
+
+        # Create a box based on the dimensions above and add a 22mm center hole
+        result = (
+            cq.Workplane("XY")
+            .box(length, height, thickness)
+            .faces(">Z")
+            .workplane()
+            .hole(center_hole_dia)
+        )
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.hole` **!**
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane.box`
+
+An extruded prismatic solid
+-------------------------------
+
+Build a prismatic solid using extrusion. After a drawing operation, the center of the previous object
+is placed on the stack, and is the reference for the next operation. So in this case, the rect() is drawn
+centered on the previously draw circle.
+
+By default, rectangles and circles are centered around the previous working point.
+
+.. cadquery::
+
+    result = cq.Workplane("front").circle(2.0).rect(0.5, 0.75).extrude(0.5)
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.circle` **!**
+        * :py:meth:`Workplane.rect` **!**
+        * :py:meth:`Workplane.extrude` **!**
+        * :py:meth:`Workplane`
+
+Building Profiles using lines and arcs
+--------------------------------------
+
+Sometimes you need to build complex profiles using lines and arcs. This example builds a prismatic
+solid from 2D operations.
+
+2D operations maintain a current point, which is initially at the origin. Use close() to finish a
+closed curve.
+
+
+.. cadquery::
+
+    result = (
+        cq.Workplane("front")
+        .lineTo(2.0, 0)
+        .lineTo(2.0, 1.0)
+        .threePointArc((1.0, 1.5), (0.0, 1.0))
+        .close()
+        .extrude(0.25)
+    )
+
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.threePointArc` **!**
+        * :py:meth:`Workplane.lineTo` **!**
+        * :py:meth:`Workplane.extrude`
+        * :py:meth:`Workplane`
+
+Moving The Current working point
+---------------------------------
+
+In this example, a closed profile is required, with some interior features as well.
+
+This example also demonstrates using multiple lines of code instead of longer chained commands,
+though of course in this case it was possible to do it in one long line as well.
+
+A new work plane center can be established at any point.
+
+.. cadquery::
+
+    result = cq.Workplane("front").circle(
+        3.0
+    )  # current point is the center of the circle, at (0, 0)
+    result = result.center(1.5, 0.0).rect(0.5, 0.5)  # new work center is (1.5, 0.0)
+
+    result = result.center(-1.5, 1.5).circle(0.25)  # new work center is (0.0, 1.5).
+    # The new center is specified relative to the previous center, not global coordinates!
+
+    result = result.extrude(0.25)
+
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.center` **!**
+        * :py:meth:`Workplane`
+        * :py:meth:`Workplane.circle`
+        * :py:meth:`Workplane.rect`
+        * :py:meth:`Workplane.extrude`
+
+Using Point Lists
+---------------------------
+
+Sometimes you need to create a number of features at various locations, and using :py:meth:`Workplane.center`
+is too cumbersome.
+
+You can use a list of points to construct multiple objects at once. Most construction methods,
+like :py:meth:`Workplane.circle` and :py:meth:`Workplane.rect`, will operate on multiple points if they are on the stack
+
+.. cadquery::
+
+   r = cq.Workplane("front").circle(2.0)  # make base
+   r = r.pushPoints(
+       [(1.5, 0), (0, 1.5), (-1.5, 0), (0, -1.5)]
+   )  # now four points are on the stack
+   r = r.circle(0.25)  # circle will operate on all four points
+   result = r.extrude(0.125)  # make prism
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.pushPoints` **!**
+        * :py:meth:`Workplane`
+        * :py:meth:`Workplane.circle`
+        * :py:meth:`Workplane.extrude`
+
+Polygons
+-------------------------
+
+You can create polygons for each stack point if you would like. Useful in 3d printers whose firmware does not
+correct for small hole sizes.
+
+.. cadquery::
+
+    result = (
+        cq.Workplane("front")
+        .box(3.0, 4.0, 0.25)
+        .pushPoints([(0, 0.75), (0, -0.75)])
+        .polygon(6, 1.0)
+        .cutThruAll()
+    )
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.polygon` **!**
+        * :py:meth:`Workplane.pushPoints`
+        * :py:meth:`Workplane.box`
+
+Polylines
+-------------------------
+
+:py:meth:`Workplane.polyline` allows creating a shape from a large number of chained points connected by lines.
+
+This example uses a polyline to create one half of an i-beam shape, which is mirrored to create the final profile.
+
+.. cadquery::
+
+    (L, H, W, t) = (100.0, 20.0, 20.0, 1.0)
+    pts = [
+        (0, H / 2.0),
+        (W / 2.0, H / 2.0),
+        (W / 2.0, (H / 2.0 - t)),
+        (t / 2.0, (H / 2.0 - t)),
+        (t / 2.0, (t - H / 2.0)),
+        (W / 2.0, (t - H / 2.0)),
+        (W / 2.0, H / -2.0),
+        (0, H / -2.0),
+    ]
+    result = cq.Workplane("front").polyline(pts).mirrorY().extrude(L)
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.polyline` **!**
+        * :py:meth:`Workplane`
+        * :py:meth:`Workplane.mirrorY`
+        * :py:meth:`Workplane.extrude`
+
+
+
+Defining an Edge with a Spline
+------------------------------
+
+This example defines a side using a spline curve through a collection of points. Useful when you have an edge that
+needs a complex profile
+
+.. cadquery::
+
+    s = cq.Workplane("XY")
+    sPnts = [
+        (2.75, 1.5),
+        (2.5, 1.75),
+        (2.0, 1.5),
+        (1.5, 1.0),
+        (1.0, 1.25),
+        (0.5, 1.0),
+        (0, 1.0),
+    ]
+    r = s.lineTo(3.0, 0).lineTo(3.0, 1.0).spline(sPnts, includeCurrent=True).close()
+    result = r.extrude(0.5)
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.spline` **!**
+        * :py:meth:`Workplane`
+        * :py:meth:`Workplane.close`
+        * :py:meth:`Workplane.lineTo`
+        * :py:meth:`Workplane.extrude`
+
+Mirroring Symmetric Geometry
+-----------------------------
+
+You can mirror 2D geometry when your shape is symmetric. In this example we also
+introduce horizontal and vertical lines, which make for slightly easier coding.
+
+
+.. cadquery::
+
+   r = cq.Workplane("front").hLine(1.0)  # 1.0 is the distance, not coordinate
+   r = (
+       r.vLine(0.5).hLine(-0.25).vLine(-0.25).hLineTo(0.0)
+   )  # hLineTo allows using xCoordinate not distance
+   result = r.mirrorY().extrude(0.25)  # mirror the geometry and extrude
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.hLine` **!**
+        * :py:meth:`Workplane.vLine` **!**
+        * :py:meth:`Workplane.hLineTo` **!**
+        * :py:meth:`Workplane.mirrorY` **!**
+        * :py:meth:`Workplane.mirrorX` **!**
+        * :py:meth:`Workplane`
+        * :py:meth:`Workplane.extrude`
+
+Mirroring 3D Objects
+-----------------------------
+
+.. cadquery::
+
+    result0 = (
+        cadquery.Workplane("XY")
+        .moveTo(10, 0)
+        .lineTo(5, 0)
+        .threePointArc((3.9393, 0.4393), (3.5, 1.5))
+        .threePointArc((3.0607, 2.5607), (2, 3))
+        .lineTo(1.5, 3)
+        .threePointArc((0.4393, 3.4393), (0, 4.5))
+        .lineTo(0, 13.5)
+        .threePointArc((0.4393, 14.5607), (1.5, 15))
+        .lineTo(28, 15)
+        .lineTo(28, 13.5)
+        .lineTo(24, 13.5)
+        .lineTo(24, 11.5)
+        .lineTo(27, 11.5)
+        .lineTo(27, 10)
+        .lineTo(22, 10)
+        .lineTo(22, 13.2)
+        .lineTo(14.5, 13.2)
+        .lineTo(14.5, 10)
+        .lineTo(12.5, 10)
+        .lineTo(12.5, 13.2)
+        .lineTo(5.5, 13.2)
+        .lineTo(5.5, 2)
+        .threePointArc((5.793, 1.293), (6.5, 1))
+        .lineTo(10, 1)
+        .close()
+    )
+    result = result0.extrude(100)
+
+    result = result.rotate((0, 0, 0), (1, 0, 0), 90)
+
+    result = result.translate(result.val().BoundingBox().center.multiply(-1))
+
+    mirXY_neg = result.mirror(mirrorPlane="XY", basePointVector=(0, 0, -30))
+    mirXY_pos = result.mirror(mirrorPlane="XY", basePointVector=(0, 0, 30))
+    mirZY_neg = result.mirror(mirrorPlane="ZY", basePointVector=(-30, 0, 0))
+    mirZY_pos = result.mirror(mirrorPlane="ZY", basePointVector=(30, 0, 0))
+
+    result = result.union(mirXY_neg).union(mirXY_pos).union(mirZY_neg).union(mirZY_pos)
+
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.moveTo`
+        * :py:meth:`Workplane.lineTo`
+        * :py:meth:`Workplane.threePointArc`
+        * :py:meth:`Workplane.extrude`
+        * :py:meth:`Workplane.mirror`
+        * :py:meth:`Workplane.union`
+        * :py:meth:`Workplane.rotate`
+
+
+Mirroring From Faces
+-----------------------------
+
+This example shows how you can mirror about a selected face. It also shows how the resulting mirrored object can be unioned immediately with the referenced mirror geometry.
+
+.. cadquery::
+
+    result = cq.Workplane("XY").line(0, 1).line(1, 0).line(0, -0.5).close().extrude(1)
+
+    result = result.mirror(result.faces(">X"), union=True)
+
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.line`
+        * :py:meth:`Workplane.close`
+        * :py:meth:`Workplane.extrude`
+        * :py:meth:`Workplane.faces`
+        * :py:meth:`Workplane.mirror`
+        * :py:meth:`Workplane.union`
+
+Creating Workplanes on Faces
+-----------------------------
+
+This example shows how to locate a new workplane on the face of a previously created feature.
+
+.. note::
+    Using workplanes in this way are a key feature of CadQuery. Unlike a typical 3d scripting
+    language, using work planes frees you from tracking the position of various features in
+    variables, and allows the model to adjust itself with removing redundant dimensions
+
+The :py:meth:`Workplane.faces()` method allows you to select the faces of a resulting solid. It
+accepts a selector string or object, that allows you to target a single face, and make a workplane
+oriented on that face.
+
+Keep in mind that by default the origin of a new workplane is calculated by forming a plane from the
+selected face and projecting the previous origin onto that plane. This behaviour can be changed
+through the centerOption argument of :py:meth:`Workplane.workplane`.
+
+.. cadquery::
+
+    result = cq.Workplane("front").box(2, 3, 0.5)  # make a basic prism
+    result = (
+        result.faces(">Z").workplane().hole(0.5)
+    )  # find the top-most face and make a hole
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.faces` **!**
+        * :py:meth:`StringSyntaxSelector` **!**
+        * :ref:`selector_reference` **!**
+        * :py:meth:`Workplane.workplane`
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane`
+
+Locating a Workplane on a vertex
+---------------------------------
+
+Normally, the :py:meth:`Workplane.workplane` method requires a face to be selected. But if a vertex
+is selected **immediately after a face**, :py:meth:`Workplane.workplane` with the centerOption
+argument set to CenterOfMass will locate the workplane on the face, with the origin at the vertex
+instead of at the center of the face
+
+The example also introduces :py:meth:`Workplane.cutThruAll`, which makes a cut through the entire
+part, no matter how deep the part is.
+
+.. cadquery::
+
+    result = cq.Workplane("front").box(3, 2, 0.5)  # make a basic prism
+    result = (
+        result.faces(">Z").vertices("<XY").workplane(centerOption="CenterOfMass")
+    )  # select the lower left vertex and make a workplane
+    result = result.circle(1.0).cutThruAll()  # cut the corner out
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.cutThruAll` **!**
+
+        * :ref:`selector_reference` **!**
+        * :py:meth:`Workplane.vertices` **!**
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane`
+        * :py:meth:`StringSyntaxSelector` **!**
+
+Offset Workplanes
+--------------------------
+
+Workplanes do not have to lie exactly on a face. When you make a workplane, you can define it at an offset
+from an existing face.
+
+This example uses an offset workplane to make a compound object, which is perfectly valid!
+
+.. cadquery::
+
+    result = cq.Workplane("front").box(3, 2, 0.5)  # make a basic prism
+    result = result.faces("<X").workplane(
+        offset=0.75
+    )  # workplane is offset from the object surface
+    result = result.circle(1.0).extrude(0.5)  # disc
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.extrude`
+        * :ref:`selector_reference` **!**
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane`
+
+Copying Workplanes
+--------------------------
+
+An existing CQ object can copy a workplane from another CQ object.
+
+.. cadquery::
+
+    result = (
+        cq.Workplane("front")
+        .circle(1)
+        .extrude(10)  # make a cylinder
+        # We want to make a second cylinder perpendicular to the first,
+        # but we have no face to base the workplane off
+        .copyWorkplane(
+            # create a temporary object with the required workplane
+            cq.Workplane("right", origin=(-5, 0, 0))
+        )
+        .circle(1)
+        .extrude(10)
+    )
+
+.. topic:: API References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.copyWorkplane` **!**
+        * :py:meth:`Workplane.circle`
+        * :py:meth:`Workplane.extrude`
+        * :py:meth:`Workplane`
+
+Rotated Workplanes
+--------------------------
+
+You can create a rotated work plane by specifying angles of rotation relative to another workplane
+
+.. cadquery::
+
+    result = (
+        cq.Workplane("front")
+        .box(4.0, 4.0, 0.25)
+        .faces(">Z")
+        .workplane()
+        .transformed(offset=cq.Vector(0, -1.5, 1.0), rotate=cq.Vector(60, 0, 0))
+        .rect(1.5, 1.5, forConstruction=True)
+        .vertices()
+        .hole(0.25)
+    )
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.transformed` **!**
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane.rect`
+        * :py:meth:`Workplane.faces`
+
+Using construction Geometry
+---------------------------
+
+You can draw shapes to use the vertices as points to locate other features. Features that are used to
+locate other features, rather than to create them, are called ``Construction Geometry``
+
+In the example below, a rectangle is drawn, and its vertices are used to locate a set of holes.
+
+.. cadquery::
+
+    result = (
+        cq.Workplane("front")
+        .box(2, 2, 0.5)
+        .faces(">Z")
+        .workplane()
+        .rect(1.5, 1.5, forConstruction=True)
+        .vertices()
+        .hole(0.125)
+    )
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.rect` (forConstruction=True)
+        * :ref:`selector_reference`
+        * :py:meth:`Workplane.workplane`
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane.hole`
+        * :py:meth:`Workplane`
+
+Shelling To Create Thin features
+--------------------------------
+
+Shelling converts a solid object into a shell of uniform thickness.
+
+To shell an object and 'hollow out' the inside pass a negative thickness parameter
+to the :py:meth:`Workplane.shell()` method of a shape.
+
+.. cadquery::
+
+    result = cq.Workplane("front").box(2, 2, 2).shell(-0.1)
+
+A positive thickness parameter wraps an object with filleted outside edges
+and the original object will be the 'hollowed out' portion.
+
+.. cadquery::
+
+    result = cq.Workplane("front").box(2, 2, 2).shell(0.1)
+
+Use face selectors to select a face to be removed from the resulting hollow shape.
+
+.. cadquery::
+
+    result = cq.Workplane("front").box(2, 2, 2).faces("+Z").shell(0.1)
+
+Multiple faces can be removed using more complex selectors.
+
+.. cadquery::
+
+   result = cq.Workplane("front").box(2, 2, 2).faces("+Z or -X or +X").shell(0.1)
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.shell` **!**
+        * :ref:`selector_reference`
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane.faces`
+        * :py:meth:`Workplane`
+
+Making Lofts
+--------------------------------------------
+
+A loft is a solid swept through a set of wires. This example creates lofted section between a rectangle
+and a circular section.
+
+.. cadquery::
+
+    result = (
+        cq.Workplane("front")
+        .box(4.0, 4.0, 0.25)
+        .faces(">Z")
+        .circle(1.5)
+        .workplane(offset=3.0)
+        .rect(0.75, 0.5)
+        .loft(combine=True)
+    )
+
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.loft` **!**
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane.faces`
+        * :py:meth:`Workplane.circle`
+        * :py:meth:`Workplane.rect`
+
+Extruding until a given face
+--------------------------------------------
+
+Sometimes you will want to extrude a wire until a given face that can be not planar or where you
+might not know easily the distance you have to extrude to. In such cases you can use `next`, `last`
+or even give a :class:`~cadquery.Face` object for the `until` argument of
+:meth:`~cadquery.Workplane.extrude`.
+
+
+.. cadquery::
+
+    result = (
+        cq.Workplane(origin=(20, 0, 0))
+        .circle(2)
+        .revolve(180, (-20, 0, 0), (-20, -1, 0))
+        .center(-20, 0)
+        .workplane()
+        .rect(20, 4)
+        .extrude("next")
+    )
+
+The same behaviour is available with :meth:`~cadquery.Workplane.cutBlind` and as you can see it is
+also possible to work on several :class:`~cadquery.Wire` objects at a time (the
+same is true for :meth:`~cadquery.Workplane.extrude`).
+
+.. cadquery::
+
+    skyscrapers_locations = [(-16, 1), (-8, 0), (7, 0.2), (17, -1.2)]
+    angles = iter([15, 0, -8, 10])
+    skyscrapers = (
+        cq.Workplane()
+        .pushPoints(skyscrapers_locations)
+        .eachpoint(
+            lambda loc: (
+                cq.Workplane()
+                .rect(5, 16)
+                .workplane(offset=10)
+                .ellipse(3, 8)
+                .workplane(offset=10)
+                .slot2D(20, 5, 90)
+                .loft()
+                .rotateAboutCenter((0, 0, 1), next(angles))
+                .val()
+                .located(loc)
+            )
+        )
+    )
+
+    result = (
+        skyscrapers.transformed((0, -90, 0))
+        .moveTo(15, 0)
+        .rect(3, 3, forConstruction=True)
+        .vertices()
+        .circle(1)
+        .cutBlind("last")
+    )
+
+Here is a typical situation where extruding and cuting until a given surface is very handy. It allows us to extrude or cut until a curved surface without overlapping issues.
+
+.. cadquery::
+
+    import cadquery as cq
+
+    sphere = cq.Workplane().sphere(5)
+    base = cq.Workplane(origin=(0, 0, -2)).box(12, 12, 10).cut(sphere).edges("|Z").fillet(2)
+    sphere_face = base.faces(">>X[2] and (not |Z) and (not |Y)").val()
+    base = base.faces("<Z").workplane().circle(2).extrude(10)
+
+    shaft = cq.Workplane().sphere(4.5).circle(1.5).extrude(20)
+
+    spherical_joint = (
+        base.union(shaft)
+        .faces(">X")
+        .workplane(centerOption="CenterOfMass")
+        .move(0, 4)
+        .slot2D(10, 2, 90)
+        .cutBlind(sphere_face)
+        .workplane(offset=10)
+        .move(0, 2)
+        .circle(0.9)
+        .extrude("next")
+    )
+
+    result = spherical_joint
+
+.. warning::
+
+    If the wire you want to extrude cannot be fully projected on the target surface, the result will
+    be unpredictable. Furthermore, the algorithm in charge of finding the candidate faces does its search by counting all the faces intersected
+    by a line created from your wire center along your
+    extrusion direction. So make sure your wire can be projected on your target face to avoid
+    unexpected behaviour.
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 3
+
+        * :py:meth:`Workplane.cutBlind` **!**
+        * :py:meth:`Workplane.rect`
+        * :py:meth:`Workplane.ellipse`
+        * :py:meth:`Workplane.workplane`
+        * :py:meth:`Workplane.slot2D`
+        * :py:meth:`Workplane.loft`
+        * :py:meth:`Workplane.rotateAboutCenter`
+        * :py:meth:`Workplane.transformed`
+        * :py:meth:`Workplane.moveTo`
+        * :py:meth:`Workplane.circle`
+
+
+Making Counter-bored and Counter-sunk Holes
+----------------------------------------------
+
+Counterbored and countersunk holes are so common that CadQuery creates macros to create them in a single step.
+
+Similar to :py:meth:`Workplane.hole`, these functions operate on a list of points as well as a single point.
+
+.. cadquery::
+
+    result = (
+        cq.Workplane(cq.Plane.XY())
+        .box(4, 2, 0.5)
+        .faces(">Z")
+        .workplane()
+        .rect(3.5, 1.5, forConstruction=True)
+        .vertices()
+        .cboreHole(0.125, 0.25, 0.125, depth=None)
+    )
+
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.cboreHole` **!**
+        * :py:meth:`Workplane.cskHole` **!**
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane.rect`
+        * :py:meth:`Workplane.workplane`
+        * :py:meth:`Workplane.vertices`
+        * :py:meth:`Workplane.faces`
+        * :py:meth:`Workplane`
+
+Offsetting wires in 2D
+----------------------
+
+Two dimensional wires can be transformed with :py:meth:`Workplane.offset2D`. They can be offset
+inwards or outwards, and with different techniques for extending the corners.
+
+.. cadquery::
+
+    original = cq.Workplane().polygon(5, 10).extrude(0.1).translate((0, 0, 2))
+    arc = cq.Workplane().polygon(5, 10).offset2D(1, "arc").extrude(0.1).translate((0, 0, 1))
+    intersection = cq.Workplane().polygon(5, 10).offset2D(1, "intersection").extrude(0.1)
+    result = original.add(arc).add(intersection)
+
+
+Using the forConstruction argument you can do the common task of offsetting a series of bolt holes
+from the outline of an object. Here is the counterbore example from above but with the bolt holes
+offset from the edges.
+
+.. cadquery::
+
+    result = (
+        cq.Workplane()
+        .box(4, 2, 0.5)
+        .faces(">Z")
+        .edges()
+        .toPending()
+        .offset2D(-0.25, forConstruction=True)
+        .vertices()
+        .cboreHole(0.125, 0.25, 0.125, depth=None)
+    )
+
+
+Note that :py:meth:`Workplane.edges` is for selecting objects. It does not add the selected edges to
+pending edges in the modelling context, because this would result in your next extrusion including
+everything you had only selected in addition to the lines you had drawn. To specify you want these
+edges to be used in :py:meth:`Workplane.offset2D`, you call :py:meth:`Workplane.toPending` to
+explicitly put them in the list of pending edges.
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.offset2D` **!**
+        * :py:meth:`Workplane.cboreHole`
+        * :py:meth:`Workplane.cskHole`
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane.polygon`
+        * :py:meth:`Workplane.workplane`
+        * :py:meth:`Workplane.vertices`
+        * :py:meth:`Workplane.edges`
+        * :py:meth:`Workplane.faces`
+        * :py:meth:`Workplane`
+
+
+Rounding Corners with Fillet
+-----------------------------
+
+Filleting is done by selecting the edges of a solid, and using the fillet function.
+
+Here we fillet all of the edges of a simple plate.
+
+.. cadquery::
+
+    result = cq.Workplane("XY").box(3, 3, 0.5).edges("|Z").fillet(0.125)
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.fillet` **!**
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane.edges`
+        * :py:meth:`Workplane`
+
+Tagging objects
+----------------
+
+The :py:meth:`Workplane.tag` method can be used to tag a particular object in the chain with a string, so that it can be referred to later in the chain.
+
+The :py:meth:`Workplane.workplaneFromTagged` method applies :py:meth:`Workplane.copyWorkplane` to a tagged object. For example, when extruding two different solids from a surface, after the first solid is extruded it can become difficult to reselect the original surface with CadQuery's other selectors.
+
+.. cadquery::
+
+    result = (
+        cq.Workplane("XY")
+        # create and tag the base workplane
+        .box(10, 10, 10)
+        .faces(">Z")
+        .workplane()
+        .tag("baseplane")
+        # extrude a cylinder
+        .center(-3, 0)
+        .circle(1)
+        .extrude(3)
+        # to reselect the base workplane, simply
+        .workplaneFromTagged("baseplane")
+        # extrude a second cylinder
+        .center(3, 0)
+        .circle(1)
+        .extrude(2)
+    )
+
+
+Tags can also be used with most selectors, including :py:meth:`Workplane.vertices`, :py:meth:`Workplane.faces`, :py:meth:`Workplane.edges`, :py:meth:`Workplane.wires`, :py:meth:`Workplane.shells`, :py:meth:`Workplane.solids` and :py:meth:`Workplane.compounds`.
+
+.. cadquery::
+
+    result = (
+        cq.Workplane("XY")
+        # create a triangular prism and tag it
+        .polygon(3, 5)
+        .extrude(4)
+        .tag("prism")
+        # create a sphere that obscures the prism
+        .sphere(10)
+        # create features based on the prism's faces
+        .faces("<X", tag="prism")
+        .workplane()
+        .circle(1)
+        .cutThruAll()
+        .faces(">X", tag="prism")
+        .faces(">Y")
+        .workplane()
+        .circle(1)
+        .cutThruAll()
+    )
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.tag` **!**
+        * :py:meth:`Workplane.getTagged` **!**
+        * :py:meth:`Workplane.workplaneFromTagged` **!**
+        * :py:meth:`Workplane.extrude`
+        * :py:meth:`Workplane.cutThruAll`
+        * :py:meth:`Workplane.circle`
+        * :py:meth:`Workplane.faces`
+        * :py:meth:`Workplane`
+
+A Parametric Bearing Pillow Block
+------------------------------------
+
+Combining a few basic functions, its possible to make a very good parametric bearing pillow block,
+with just a few lines of code.
+
+.. cadquery::
+
+        (length, height, bearing_diam, thickness, padding) = (30.0, 40.0, 22.0, 10.0, 8.0)
+
+        result = (
+            cq.Workplane("XY")
+            .box(length, height, thickness)
+            .faces(">Z")
+            .workplane()
+            .hole(bearing_diam)
+            .faces(">Z")
+            .workplane()
+            .rect(length - padding, height - padding, forConstruction=True)
+            .vertices()
+            .cboreHole(2.4, 4.4, 2.1)
+        )
+
+
+Splitting an Object
+---------------------
+
+You can split an object using a workplane, and retain either or both halves
+
+.. cadquery::
+
+        c = cq.Workplane("XY").box(1, 1, 1).faces(">Z").workplane().circle(0.25).cutThruAll()
+
+        # now cut it in half sideways
+        result = c.faces(">Y").workplane(-0.5).split(keepTop=True)
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.split` **!**
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane.circle`
+        * :py:meth:`Workplane.cutThruAll`
+        * :py:meth:`Workplane.workplane`
+        * :py:meth:`Workplane`
+
+The Classic OCC Bottle
+----------------------
+
+CadQuery is based on the OpenCascade.org (OCC) modeling Kernel. Those who are familiar with OCC know about the
+famous 'bottle' example. `The bottle example in the OCCT online documentation <https://old.opencascade.com/doc/occt-7.5.0/overview/html/occt__tutorial.html>`_.
+
+A pythonOCC version is listed `here <https://github.com/tpaviot/pythonocc-demos/blob/f3ea9b4f65a9dff482be04b153d4ce5ec2430e13/examples/core_classic_occ_bottle.py>`_.
+
+Of course one difference between this sample and the OCC version is the length. This sample is one of the longer
+ones at 13 lines, but that's very short compared to the pythonOCC version, which is 10x longer!
+
+
+.. cadquery::
+
+    (L, w, t) = (20.0, 6.0, 3.0)
+    s = cq.Workplane("XY")
+
+    # Draw half the profile of the bottle and extrude it
+    p = (
+        s.center(-L / 2.0, 0)
+        .vLine(w / 2.0)
+        .threePointArc((L / 2.0, w / 2.0 + t), (L, w / 2.0))
+        .vLine(-w / 2.0)
+        .mirrorX()
+        .extrude(30.0, True)
+    )
+
+    # Make the neck
+    p = p.faces(">Z").workplane(centerOption="CenterOfMass").circle(3.0).extrude(2.0, True)
+
+    # Make a shell
+    result = p.faces(">Z").shell(0.3)
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 2
+
+        * :py:meth:`Workplane.extrude`
+        * :py:meth:`Workplane.mirrorX`
+        * :py:meth:`Workplane.threePointArc`
+        * :py:meth:`Workplane.workplane`
+        * :py:meth:`Workplane.vertices`
+        * :py:meth:`Workplane.vLine`
+        * :py:meth:`Workplane.faces`
+        * :py:meth:`Workplane`
+
+A Parametric Enclosure
+-----------------------
+
+.. cadquery::
+    :height: 400px
+
+    # parameter definitions
+    p_outerWidth = 100.0  # Outer width of box enclosure
+    p_outerLength = 150.0  # Outer length of box enclosure
+    p_outerHeight = 50.0  # Outer height of box enclosure
+
+    p_thickness = 3.0  # Thickness of the box walls
+    p_sideRadius = 10.0  # Radius for the curves around the sides of the box
+    p_topAndBottomRadius = (
+        2.0  # Radius for the curves on the top and bottom edges of the box
+    )
+
+    p_screwpostInset = 12.0  # How far in from the edges the screw posts should be place.
+    p_screwpostID = 4.0  # Inner Diameter of the screw post holes, should be roughly screw diameter not including threads
+    p_screwpostOD = 10.0  # Outer Diameter of the screw posts.\nDetermines overall thickness of the posts
+
+    p_boreDiameter = 8.0  # Diameter of the counterbore hole, if any
+    p_boreDepth = 1.0  # Depth of the counterbore hole, if
+    p_countersinkDiameter = 0.0  # Outer diameter of countersink. Should roughly match the outer diameter of the screw head
+    p_countersinkAngle = 90.0  # Countersink angle (complete angle between opposite sides, not from center to one side)
+    p_flipLid = True  # Whether to place the lid with the top facing down or not.
+    p_lipHeight = 1.0  # Height of lip on the underside of the lid.\nSits inside the box body for a snug fit.
+
+    # outer shell
+    oshell = (
+        cq.Workplane("XY")
+        .rect(p_outerWidth, p_outerLength)
+        .extrude(p_outerHeight + p_lipHeight)
+    )
+
+    # weird geometry happens if we make the fillets in the wrong order
+    if p_sideRadius > p_topAndBottomRadius:
+        oshell = oshell.edges("|Z").fillet(p_sideRadius)
+        oshell = oshell.edges("#Z").fillet(p_topAndBottomRadius)
+    else:
+        oshell = oshell.edges("#Z").fillet(p_topAndBottomRadius)
+        oshell = oshell.edges("|Z").fillet(p_sideRadius)
+
+    # inner shell
+    ishell = (
+        oshell.faces("<Z")
+        .workplane(p_thickness, True)
+        .rect((p_outerWidth - 2.0 * p_thickness), (p_outerLength - 2.0 * p_thickness))
+        .extrude(
+            (p_outerHeight - 2.0 * p_thickness), False
+        )  # set combine false to produce just the new boss
+    )
+    ishell = ishell.edges("|Z").fillet(p_sideRadius - p_thickness)
+
+    # make the box outer box
+    box = oshell.cut(ishell)
+
+    # make the screw posts
+    POSTWIDTH = p_outerWidth - 2.0 * p_screwpostInset
+    POSTLENGTH = p_outerLength - 2.0 * p_screwpostInset
+
+    box = (
+        box.faces(">Z")
+        .workplane(-p_thickness)
+        .rect(POSTWIDTH, POSTLENGTH, forConstruction=True)
+        .vertices()
+        .circle(p_screwpostOD / 2.0)
+        .circle(p_screwpostID / 2.0)
+        .extrude(-1.0 * (p_outerHeight + p_lipHeight - p_thickness), True)
+    )
+
+    # split lid into top and bottom parts
+    (lid, bottom) = (
+        box.faces(">Z")
+        .workplane(-p_thickness - p_lipHeight)
+        .split(keepTop=True, keepBottom=True)
+        .all()
+    )  # splits into two solids
+
+    # translate the lid, and subtract the bottom from it to produce the lid inset
+    lowerLid = lid.translate((0, 0, -p_lipHeight))
+    cutlip = lowerLid.cut(bottom).translate(
+        (p_outerWidth + p_thickness, 0, p_thickness - p_outerHeight + p_lipHeight)
+    )
+
+    # compute centers for screw holes
+    topOfLidCenters = (
+        cutlip.faces(">Z")
+        .workplane(centerOption="CenterOfMass")
+        .rect(POSTWIDTH, POSTLENGTH, forConstruction=True)
+        .vertices()
+    )
+
+    # add holes of the desired type
+    if p_boreDiameter > 0 and p_boreDepth > 0:
+        topOfLid = topOfLidCenters.cboreHole(
+            p_screwpostID, p_boreDiameter, p_boreDepth, 2.0 * p_thickness
+        )
+    elif p_countersinkDiameter > 0 and p_countersinkAngle > 0:
+        topOfLid = topOfLidCenters.cskHole(
+            p_screwpostID, p_countersinkDiameter, p_countersinkAngle, 2.0 * p_thickness
+        )
+    else:
+        topOfLid = topOfLidCenters.hole(p_screwpostID, 2.0 * p_thickness)
+
+    # flip lid upside down if desired
+    if p_flipLid:
+        topOfLid = topOfLid.rotateAboutCenter((1, 0, 0), 180)
+
+    # return the combined result
+    result = topOfLid.union(bottom)
+
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 3
+
+        * :py:meth:`Workplane.circle`
+        * :py:meth:`Workplane.rect`
+        * :py:meth:`Workplane.extrude`
+        * :py:meth:`Workplane.box`
+        * :py:meth:`Workplane.all`
+        * :py:meth:`Workplane.faces`
+        * :py:meth:`Workplane.vertices`
+        * :py:meth:`Workplane.edges`
+        * :py:meth:`Workplane.workplane`
+        * :py:meth:`Workplane.fillet`
+        * :py:meth:`Workplane.cut`
+        * :py:meth:`Workplane.union`
+        * :py:meth:`Workplane.rotateAboutCenter`
+        * :py:meth:`Workplane.cboreHole`
+        * :py:meth:`Workplane.cskHole`
+        * :py:meth:`Workplane.hole`
+
+Lego Brick
+-------------------
+
+This script will produce any size regular rectangular Lego(TM) brick. Its only tricky because of the logic
+regarding the underside of the brick.
+
+.. cadquery::
+    :select: tmp
+    :height: 400px
+
+    #####
+    # Inputs
+    ######
+    lbumps = 6  # number of bumps long
+    wbumps = 2  # number of bumps wide
+    thin = True  # True for thin, False for thick
+
+    #
+    # Lego Brick Constants-- these make a Lego brick a Lego :)
+    #
+    pitch = 8.0
+    clearance = 0.1
+    bumpDiam = 4.8
+    bumpHeight = 1.8
+    if thin:
+        height = 3.2
+    else:
+        height = 9.6
+
+    t = (pitch - (2 * clearance) - bumpDiam) / 2.0
+    postDiam = pitch - t  # works out to 6.5
+    total_length = lbumps * pitch - 2.0 * clearance
+    total_width = wbumps * pitch - 2.0 * clearance
+
+    # make the base
+    s = cq.Workplane("XY").box(total_length, total_width, height)
+
+    # shell inwards not outwards
+    s = s.faces("<Z").shell(-1.0 * t)
+
+    # make the bumps on the top
+    s = (
+        s.faces(">Z")
+        .workplane()
+        .rarray(pitch, pitch, lbumps, wbumps, True)
+        .circle(bumpDiam / 2.0)
+        .extrude(bumpHeight)
+    )
+
+    # add posts on the bottom. posts are different diameter depending on geometry
+    # solid studs for 1 bump, tubes for multiple, none for 1x1
+    tmp = s.faces("<Z").workplane(invert=True)
+
+    if lbumps > 1 and wbumps > 1:
+        tmp = (
+            tmp.rarray(pitch, pitch, lbumps - 1, wbumps - 1, center=True)
+            .circle(postDiam / 2.0)
+            .circle(bumpDiam / 2.0)
+            .extrude(height - t)
+        )
+    elif lbumps > 1:
+        tmp = (
+            tmp.rarray(pitch, pitch, lbumps - 1, 1, center=True)
+            .circle(t)
+            .extrude(height - t)
+        )
+    elif wbumps > 1:
+        tmp = (
+            tmp.rarray(pitch, pitch, 1, wbumps - 1, center=True)
+            .circle(t)
+            .extrude(height - t)
+        )
+    else:
+        tmp = s
+
+
+Braille Example
+---------------------
+
+.. cadquery::
+    :height: 400px
+
+    from collections import namedtuple
+
+
+    # text_lines is a list of text lines.
+    # Braille (converted with braille-converter:
+    # https://github.com/jpaugh/braille-converter.git).
+    text_lines = ["⠠ ⠋ ⠗ ⠑ ⠑ ⠠ ⠉ ⠠ ⠁ ⠠ ⠙"]
+    # See http://www.tiresias.org/research/reports/braille_cell.htm for examples
+    # of braille cell geometry.
+    horizontal_interdot = 2.5
+    vertical_interdot = 2.5
+    horizontal_intercell = 6
+    vertical_interline = 10
+    dot_height = 0.5
+    dot_diameter = 1.3
+
+    base_thickness = 1.5
+
+    # End of configuration.
+    BrailleCellGeometry = namedtuple(
+        "BrailleCellGeometry",
+        (
+            "horizontal_interdot",
+            "vertical_interdot",
+            "intercell",
+            "interline",
+            "dot_height",
+            "dot_diameter",
+        ),
+    )
+
+
+    class Point(object):
+        def __init__(self, x, y):
+            self.x = x
+            self.y = y
+
+        def __add__(self, other):
+            return Point(self.x + other.x, self.y + other.y)
+
+        def __len__(self):
+            return 2
+
+        def __getitem__(self, index):
+            return (self.x, self.y)[index]
+
+        def __str__(self):
+            return "({}, {})".format(self.x, self.y)
+
+
+    def brailleToPoints(text, cell_geometry):
+        # Unicode bit pattern (cf. https://en.wikipedia.org/wiki/Braille_Patterns).
+        mask1 = 0b00000001
+        mask2 = 0b00000010
+        mask3 = 0b00000100
+        mask4 = 0b00001000
+        mask5 = 0b00010000
+        mask6 = 0b00100000
+        mask7 = 0b01000000
+        mask8 = 0b10000000
+        masks = (mask1, mask2, mask3, mask4, mask5, mask6, mask7, mask8)
+
+        # Corresponding dot position
+        w = cell_geometry.horizontal_interdot
+        h = cell_geometry.vertical_interdot
+        pos1 = Point(0, 2 * h)
+        pos2 = Point(0, h)
+        pos3 = Point(0, 0)
+        pos4 = Point(w, 2 * h)
+        pos5 = Point(w, h)
+        pos6 = Point(w, 0)
+        pos7 = Point(0, -h)
+        pos8 = Point(w, -h)
+        pos = (pos1, pos2, pos3, pos4, pos5, pos6, pos7, pos8)
+
+        # Braille blank pattern (u'\u2800').
+        blank = "⠀"
+        points = []
+        # Position of dot1 along the x-axis (horizontal).
+        character_origin = 0
+        for c in text:
+            for m, p in zip(masks, pos):
+                delta_to_blank = ord(c) - ord(blank)
+                if m & delta_to_blank:
+                    points.append(p + Point(character_origin, 0))
+            character_origin += cell_geometry.intercell
+        return points
+
+
+    def get_plate_height(text_lines, cell_geometry):
+        # cell_geometry.vertical_interdot is also used as space between base
+        # borders and characters.
+        return (
+            2 * cell_geometry.vertical_interdot
+            + 2 * cell_geometry.vertical_interdot
+            + (len(text_lines) - 1) * cell_geometry.interline
+        )
+
+
+    def get_plate_width(text_lines, cell_geometry):
+        # cell_geometry.horizontal_interdot is also used as space between base
+        # borders and characters.
+        max_len = max([len(t) for t in text_lines])
+        return (
+            2 * cell_geometry.horizontal_interdot
+            + cell_geometry.horizontal_interdot
+            + (max_len - 1) * cell_geometry.intercell
+        )
+
+
+    def get_cylinder_radius(cell_geometry):
+        """Return the radius the cylinder should have
+        The cylinder have the same radius as the half-sphere make the dots (the
+        hidden and the shown part of the dots).
+        The radius is such that the spherical cap with diameter
+        cell_geometry.dot_diameter has a height of cell_geometry.dot_height.
+        """
+        h = cell_geometry.dot_height
+        r = cell_geometry.dot_diameter / 2
+        return (r**2 + h**2) / 2 / h
+
+
+    def get_base_plate_thickness(plate_thickness, cell_geometry):
+        """Return the height on which the half spheres will sit"""
+        return (
+            plate_thickness + get_cylinder_radius(cell_geometry) - cell_geometry.dot_height
+        )
+
+
+    def make_base(text_lines, cell_geometry, plate_thickness):
+        base_width = get_plate_width(text_lines, cell_geometry)
+        base_height = get_plate_height(text_lines, cell_geometry)
+        base_thickness = get_base_plate_thickness(plate_thickness, cell_geometry)
+        base = cq.Workplane("XY").box(
+            base_width, base_height, base_thickness, centered=False
+        )
+        return base
+
+
+    def make_embossed_plate(text_lines, cell_geometry):
+        """Make an embossed plate with dots as spherical caps
+        Method:
+            - make a thin plate on which sit cylinders
+            - fillet the upper edge of the cylinders so to get pseudo half-spheres
+            - make the union with a thicker plate so that only the sphere caps stay
+              "visible".
+        """
+        base = make_base(text_lines, cell_geometry, base_thickness)
+
+        dot_pos = []
+        base_width = get_plate_width(text_lines, cell_geometry)
+        base_height = get_plate_height(text_lines, cell_geometry)
+        y = base_height - 3 * cell_geometry.vertical_interdot
+        line_start_pos = Point(cell_geometry.horizontal_interdot, y)
+        for text in text_lines:
+            dots = brailleToPoints(text, cell_geometry)
+            dots = [p + line_start_pos for p in dots]
+            dot_pos += dots
+            line_start_pos += Point(0, -cell_geometry.interline)
+
+        r = get_cylinder_radius(cell_geometry)
+        base = (
+            base.faces(">Z")
+            .vertices("<XY")
+            .workplane()
+            .pushPoints(dot_pos)
+            .circle(r)
+            .extrude(r)
+        )
+        # Make a fillet almost the same radius to get a pseudo spherical cap.
+        base = base.faces(">Z").edges().fillet(r - 0.001)
+        hidding_box = cq.Workplane("XY").box(
+            base_width, base_height, base_thickness, centered=False
+        )
+        result = hidding_box.union(base)
+        return result
+
+
+    _cell_geometry = BrailleCellGeometry(
+        horizontal_interdot,
+        vertical_interdot,
+        horizontal_intercell,
+        vertical_interline,
+        dot_height,
+        dot_diameter,
+    )
+
+    if base_thickness < get_cylinder_radius(_cell_geometry):
+        raise ValueError("Base thickness should be at least {}".format(dot_height))
+
+    result = make_embossed_plate(text_lines, _cell_geometry)
+
+Panel With Various Connector Holes
+-----------------------------------
+
+.. cadquery::
+    :height: 400px
+
+    # The dimensions of the model. These can be modified rather than changing the
+    # object's code directly.
+    width = 400
+    height = 500
+    thickness = 2
+
+    # Create a plate with two polygons cut through it
+    result = cq.Workplane("front").box(width, height, thickness)
+
+    h_sep = 60
+    for idx in range(4):
+        result = (
+            result.workplane(offset=1, centerOption="CenterOfBoundBox")
+            .center(157, 210 - idx * h_sep)
+            .moveTo(-23.5, 0)
+            .circle(1.6)
+            .moveTo(23.5, 0)
+            .circle(1.6)
+            .moveTo(-17.038896, -5.7)
+            .threePointArc((-19.44306, -4.70416), (-20.438896, -2.3))
+            .lineTo(-21.25, 2.3)
+            .threePointArc((-20.25416, 4.70416), (-17.85, 5.7))
+            .lineTo(17.85, 5.7)
+            .threePointArc((20.25416, 4.70416), (21.25, 2.3))
+            .lineTo(20.438896, -2.3)
+            .threePointArc((19.44306, -4.70416), (17.038896, -5.7))
+            .close()
+            .cutThruAll()
+        )
+
+    for idx in range(4):
+        result = (
+            result.workplane(offset=1, centerOption="CenterOfBoundBox")
+            .center(157, -30 - idx * h_sep)
+            .moveTo(-16.65, 0)
+            .circle(1.6)
+            .moveTo(16.65, 0)
+            .circle(1.6)
+            .moveTo(-10.1889, -5.7)
+            .threePointArc((-12.59306, -4.70416), (-13.5889, -2.3))
+            .lineTo(-14.4, 2.3)
+            .threePointArc((-13.40416, 4.70416), (-11, 5.7))
+            .lineTo(11, 5.7)
+            .threePointArc((13.40416, 4.70416), (14.4, 2.3))
+            .lineTo(13.5889, -2.3)
+            .threePointArc((12.59306, -4.70416), (10.1889, -5.7))
+            .close()
+            .cutThruAll()
+        )
+
+    h_sep4DB9 = 30
+    for idx in range(8):
+        result = (
+            result.workplane(offset=1, centerOption="CenterOfBoundBox")
+            .center(91, 225 - idx * h_sep4DB9)
+            .moveTo(-12.5, 0)
+            .circle(1.6)
+            .moveTo(12.5, 0)
+            .circle(1.6)
+            .moveTo(-6.038896, -5.7)
+            .threePointArc((-8.44306, -4.70416), (-9.438896, -2.3))
+            .lineTo(-10.25, 2.3)
+            .threePointArc((-9.25416, 4.70416), (-6.85, 5.7))
+            .lineTo(6.85, 5.7)
+            .threePointArc((9.25416, 4.70416), (10.25, 2.3))
+            .lineTo(9.438896, -2.3)
+            .threePointArc((8.44306, -4.70416), (6.038896, -5.7))
+            .close()
+            .cutThruAll()
+        )
+
+    for idx in range(4):
+        result = (
+            result.workplane(offset=1, centerOption="CenterOfBoundBox")
+            .center(25, 210 - idx * h_sep)
+            .moveTo(-23.5, 0)
+            .circle(1.6)
+            .moveTo(23.5, 0)
+            .circle(1.6)
+            .moveTo(-17.038896, -5.7)
+            .threePointArc((-19.44306, -4.70416), (-20.438896, -2.3))
+            .lineTo(-21.25, 2.3)
+            .threePointArc((-20.25416, 4.70416), (-17.85, 5.7))
+            .lineTo(17.85, 5.7)
+            .threePointArc((20.25416, 4.70416), (21.25, 2.3))
+            .lineTo(20.438896, -2.3)
+            .threePointArc((19.44306, -4.70416), (17.038896, -5.7))
+            .close()
+            .cutThruAll()
+        )
+
+    for idx in range(4):
+        result = (
+            result.workplane(offset=1, centerOption="CenterOfBoundBox")
+            .center(25, -30 - idx * h_sep)
+            .moveTo(-16.65, 0)
+            .circle(1.6)
+            .moveTo(16.65, 0)
+            .circle(1.6)
+            .moveTo(-10.1889, -5.7)
+            .threePointArc((-12.59306, -4.70416), (-13.5889, -2.3))
+            .lineTo(-14.4, 2.3)
+            .threePointArc((-13.40416, 4.70416), (-11, 5.7))
+            .lineTo(11, 5.7)
+            .threePointArc((13.40416, 4.70416), (14.4, 2.3))
+            .lineTo(13.5889, -2.3)
+            .threePointArc((12.59306, -4.70416), (10.1889, -5.7))
+            .close()
+            .cutThruAll()
+        )
+
+    for idx in range(8):
+        result = (
+            result.workplane(offset=1, centerOption="CenterOfBoundBox")
+            .center(-41, 225 - idx * h_sep4DB9)
+            .moveTo(-12.5, 0)
+            .circle(1.6)
+            .moveTo(12.5, 0)
+            .circle(1.6)
+            .moveTo(-6.038896, -5.7)
+            .threePointArc((-8.44306, -4.70416), (-9.438896, -2.3))
+            .lineTo(-10.25, 2.3)
+            .threePointArc((-9.25416, 4.70416), (-6.85, 5.7))
+            .lineTo(6.85, 5.7)
+            .threePointArc((9.25416, 4.70416), (10.25, 2.3))
+            .lineTo(9.438896, -2.3)
+            .threePointArc((8.44306, -4.70416), (6.038896, -5.7))
+            .close()
+            .cutThruAll()
+        )
+
+    for idx in range(4):
+        result = (
+            result.workplane(offset=1, centerOption="CenterOfBoundBox")
+            .center(-107, 210 - idx * h_sep)
+            .moveTo(-23.5, 0)
+            .circle(1.6)
+            .moveTo(23.5, 0)
+            .circle(1.6)
+            .moveTo(-17.038896, -5.7)
+            .threePointArc((-19.44306, -4.70416), (-20.438896, -2.3))
+            .lineTo(-21.25, 2.3)
+            .threePointArc((-20.25416, 4.70416), (-17.85, 5.7))
+            .lineTo(17.85, 5.7)
+            .threePointArc((20.25416, 4.70416), (21.25, 2.3))
+            .lineTo(20.438896, -2.3)
+            .threePointArc((19.44306, -4.70416), (17.038896, -5.7))
+            .close()
+            .cutThruAll()
+        )
+
+    for idx in range(4):
+        result = (
+            result.workplane(offset=1, centerOption="CenterOfBoundBox")
+            .center(-107, -30 - idx * h_sep)
+            .circle(14)
+            .rect(24.7487, 24.7487, forConstruction=True)
+            .vertices()
+            .hole(3.2)
+            .cutThruAll()
+        )
+
+    for idx in range(8):
+        result = (
+            result.workplane(offset=1, centerOption="CenterOfBoundBox")
+            .center(-173, 225 - idx * h_sep4DB9)
+            .moveTo(-12.5, 0)
+            .circle(1.6)
+            .moveTo(12.5, 0)
+            .circle(1.6)
+            .moveTo(-6.038896, -5.7)
+            .threePointArc((-8.44306, -4.70416), (-9.438896, -2.3))
+            .lineTo(-10.25, 2.3)
+            .threePointArc((-9.25416, 4.70416), (-6.85, 5.7))
+            .lineTo(6.85, 5.7)
+            .threePointArc((9.25416, 4.70416), (10.25, 2.3))
+            .lineTo(9.438896, -2.3)
+            .threePointArc((8.44306, -4.70416), (6.038896, -5.7))
+            .close()
+            .cutThruAll()
+        )
+
+    for idx in range(4):
+        result = (
+            result.workplane(offset=1, centerOption="CenterOfBoundBox")
+            .center(-173, -30 - idx * h_sep)
+            .moveTo(-2.9176, -5.3)
+            .threePointArc((-6.05, 0), (-2.9176, 5.3))
+            .lineTo(2.9176, 5.3)
+            .threePointArc((6.05, 0), (2.9176, -5.3))
+            .close()
+            .cutThruAll()
+        )
+
+
+Cycloidal gear
+--------------
+
+You can define complex geometries using the parametricCurve functionality.
+This specific examples generates a helical cycloidal gear.
+
+.. cadquery::
+    :height: 400px
+
+    import cadquery as cq
+    from math import sin, cos, pi, floor
+
+
+    # define the generating function
+    def hypocycloid(t, r1, r2):
+        return (
+            (r1 - r2) * cos(t) + r2 * cos(r1 / r2 * t - t),
+            (r1 - r2) * sin(t) + r2 * sin(-(r1 / r2 * t - t)),
+        )
+
+
+    def epicycloid(t, r1, r2):
+        return (
+            (r1 + r2) * cos(t) - r2 * cos(r1 / r2 * t + t),
+            (r1 + r2) * sin(t) - r2 * sin(r1 / r2 * t + t),
+        )
+
+
+    def gear(t, r1=4, r2=1):
+        if (-1) ** (1 + floor(t / 2 / pi * (r1 / r2))) < 0:
+            return epicycloid(t, r1, r2)
+        else:
+            return hypocycloid(t, r1, r2)
+
+
+    # create the gear profile and extrude it
+    result = (
+        cq.Workplane("XY")
+        .parametricCurve(lambda t: gear(t * 2 * pi, 6, 1))
+        .twistExtrude(15, 90)
+        .faces(">Z")
+        .workplane()
+        .circle(2)
+        .cutThruAll()
+    )

server/docs/reference/extending.rst

@@ -0,0 +1,242 @@
+.. _extending:
+
+Extending CadQuery
+======================
+
+
+If you find that CadQuery does not suit your needs, you can easily extend it.  CadQuery provides several extension
+methods:
+
+   * You can load plugins others have developed. This is by far the easiest way to access other code
+   * You can define your own plugins.
+   * You can use OCP scripting directly
+
+
+Using OpenCascade methods
+-------------------------
+
+The easiest way to extend CadQuery is to simply use OpenCascade/OCP scripting inside of your build method.  Just about
+any valid OCP script will execute just fine. For example, this simple CadQuery script::
+
+    return cq.Workplane("XY").box(1.0, 2.0, 3.0).val()
+
+is actually equivalent to::
+
+    from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox
+    from OCP.gp import gp_Ax2, gp_Dir, gp_Pnt
+
+    return cq.Shape.cast(
+        BRepPrimAPI_MakeBox(
+            gp_Ax2(gp_Pnt(-0.5, -1.0, -1.5), gp_Dir(0, 0, 1)), 1.0, 2.0, 3.0
+        ).Shape()
+    )
+
+As long as you return a valid OCP Shape, you can use any OCP methods you like. You can even mix and match the
+two. For example, consider this script, which creates a OCP box, but then uses CadQuery to select its faces::
+
+    box1 = cq.Shape.cast(
+        BRepPrimAPI_MakeBox(
+            gp_Ax2(gp_Pnt(-0.5, -1.0, -1.5), gp_Dir(0, 0, 1)), 1.0, 2.0, 3.0
+        ).Shape()
+    )
+    return box1.faces(">X").Area()      # return 6.0
+
+
+Extending CadQuery: Plugins
+----------------------------
+
+Though you can get a lot done with OpenCascade, the code gets pretty nasty in a hurry. CadQuery shields you from
+a lot of the complexity of the OpenCascade API.
+
+You can get the best of both worlds by wrapping your OCP script into a CadQuery plugin.
+
+A CadQuery plugin is simply a function that is attached to the CadQuery :py:meth:`cadquery.CQ` or :py:meth:`cadquery.Workplane` class.
+When connected, your plugin can be used in the chain just like the built-in functions.
+
+There are a few key concepts important to understand when building a plugin
+
+
+The Stack
+-------------------
+
+Every CadQuery object has a local stack, which contains a list of items.  The items on the stack will be
+one of these types:
+
+   * **A CadQuery SolidReference object**, which holds a reference to a OCP solid
+   * **A OCP object**, a Vertex, Edge, Wire, Face, Shell, Solid, or Compound
+
+The stack is available by using self.objects, and will always contain at least one object.
+
+.. note::
+
+    Objects and points on the stack are **always** in global coordinates.  Similarly, any objects you
+    create must be created in terms of global coordinates as well!
+
+
+Preserving the Chain
+-----------------------
+
+CadQuery's fluent API relies on the ability to chain calls together one after another. For this to work,
+you must return a valid CadQuery object as a return value.  If you choose not to return a CadQuery object,
+then your plugin will end the chain. Sometimes this is desired for example :py:meth:`cadquery.Workplane.size`
+
+There are two ways you can safely continue the chain:
+
+   1.  **return self**  If you simply wish to modify the stack contents, you can simply return a reference to
+       self.  This approach is destructive, because the contents of the stack are modified, but it is also the
+       simplest.
+   2.  :py:meth:`cadquery.Workplane.newObject`  Most of the time, you will want to return a new object.  Using newObject will
+       return a new CQ or Workplane object having the stack you specify, and will link this object to the
+       previous one.  This preserves the original object and its stack.
+
+
+Helper Methods
+-----------------------
+
+When you implement a CadQuery plugin, you are extending CadQuery's base objects.  As a result, you can call any
+CadQuery or Workplane methods from inside of your extension.  You can also call a number of internal methods that
+are designed to aid in plugin creation:
+
+
+   * :py:meth:`cadquery.Workplane._makeWireAtPoints` will invoke a factory function you supply for all points on the stack,
+     and return a properly constructed cadquery object. This function takes care of registering wires for you
+     and everything like that
+
+   * :py:meth:`cadquery.Workplane.newObject` returns a new Workplane object with the provided stack, and with its parent set
+     to the current object. The preferred way to continue the chain
+
+   * :py:meth:`cadquery.Workplane.findSolid` returns the first Solid found in the chain, working from the current object upwards
+     in the chain. commonly used when your plugin will modify an existing solid, or needs to create objects and
+     then combine them onto the 'main' part that is in progress
+
+   * :py:meth:`cadquery.Workplane._addPendingWire` must be called if you add a wire.  This allows the base class to track all the wires
+     that are created, so that they can be managed when extrusion occurs.
+
+   * :py:meth:`cadquery.Workplane.wire` gathers up all of the edges that have been drawn ( eg, by line, vline, etc ), and
+     attempts to combine them into a single wire, which is returned. This should be used when your plugin creates
+     2D edges, and you know it is time to collect them into a single wire.
+
+   * :py:meth:`cadquery.Workplane.plane` provides a reference to the workplane, which allows you to convert between workplane
+     coordinates and global coordinates:
+     * :py:meth:`cadquery.occ_impl.geom.Plane.toWorldCoords` will convert local coordinates to global ones
+     * :py:meth:`cadquery.occ_impl.geom.Plane.toLocalCoords` will convert from global coordinates to local coordinates
+
+Coordinate Systems
+-----------------------
+
+Keep in mind that the user may be using a work plane that has created a local coordinate system. Consequently,
+the orientation of shapes that you create are often implicitly defined by the user's workplane.
+
+Any objects that you create must be fully defined in *global coordinates*, even though some or all of the users'
+inputs may be defined in terms of local coordinates.
+
+
+Linking in your plugin
+-----------------------
+
+Your plugin is a single method, which is attached to the main Workplane or CadQuery object.
+
+Your plugin method's first parameter should be 'self', which will provide a reference to base class functionality.
+You can also accept other arguments.
+
+To install it, simply attach it to the CadQuery or Workplane object, like this::
+
+    def _yourFunction(self, arg1, arg):
+        # do stuff
+        return whatever_you_want
+
+
+    cq.Workplane.yourPlugin = _yourFunction
+
+That's it!
+
+CadQueryExample Plugins
+-----------------------
+Some core cadquery code is intentionally written exactly like a plugin.
+If you are writing your own plugins, have a look at these methods for inspiration:
+
+   * :py:meth:`cadquery.Workplane.polygon`
+   * :py:meth:`cadquery.Workplane.cboreHole`
+
+
+Plugin Example
+-----------------------
+
+This ultra simple plugin makes cubes of the specified size for each stack point.
+
+.. cadquery::
+
+        import cadquery as cq
+        from cadquery.func import box
+
+        def makeCubes(self, length):
+            # self refers to the Workplane object
+
+            # inner method that creates a cube
+            def _singleCube(loc):
+                # loc is a location in local coordinates
+                # since we're using eachpoint with useLocalCoordinates=True
+                return box(length, length, length).locate(loc)
+
+            # use CQ utility method to iterate over the stack, call our
+            # method, and convert to/from local coordinates.
+            return self.eachpoint(_singleCube, True)
+
+
+        # link the plugin into CadQuery
+        cq.Workplane.makeCubes = makeCubes
+
+        # use the plugin
+        result = (
+            cq.Workplane("XY")
+            .box(6.0, 8.0, 0.5)
+            .faces(">Z")
+            .rect(4.0, 4.0, forConstruction=True)
+            .vertices()
+            .makeCubes(1.0)
+            .combine()
+        )
+
+
+Extending CadQuery: Special Methods
+-----------------------------------
+
+The above-mentioned approach has one drawback, it requires monkey-patching or subclassing. To avoid this
+one can also use the following special methods of :py:class:`cadquery.Workplane` and :py:class:`cadquery.Sketch`
+and write plugins in a more functional style.
+
+    * :py:meth:`cadquery.Workplane.map`
+    * :py:meth:`cadquery.Workplane.apply`
+    * :py:meth:`cadquery.Workplane.invoke`
+    * :py:meth:`cadquery.Sketch.map`
+    * :py:meth:`cadquery.Sketch.apply`
+    * :py:meth:`cadquery.Sketch.invoke`
+
+Here is the same plugin rewritten using one of those methods.
+
+.. cadquery::
+
+        import cadquery as cq
+        from cadquery.func import box
+
+        def makeCubes(length):
+
+            # inner method that creates the cubes
+            def callback(wp):
+
+                return wp.eachpoint(box(length, length, length), True)
+
+            return callback
+
+        # use the plugin
+        result = (
+            cq.Workplane("XY")
+            .box(6.0, 8.0, 0.5)
+            .faces(">Z")
+            .rect(4.0, 4.0, forConstruction=True)
+            .vertices()
+            .invoke(makeCubes(1.0))
+            .combine()
+        )
+
+Such an approach is more friendly for auto-completion and static analysis tools.

server/docs/reference/free-func.rst

@@ -0,0 +1,461 @@
+
+.. _freefuncapi:
+
+*****************
+Free function API
+*****************
+
+.. warning:: The free function API is experimental and may change.
+
+For situations when more freedom in crafting individual objects is required, a free function API is provided.
+This API has no hidden state, but may result in more verbose code. One can still use selectors as methods, but all other operations are implemented as free functions.
+Placement of objects and creation of patterns can be achieved using the various overloads of the moved method.
+
+Currently this documentation is incomplete, more examples can be found in the tests.
+
+Tutorial
+--------
+
+The purpose of this section is to demonstrate how to construct Shape objects using the free function API.
+
+
+.. cadquery::
+    :height: 600px
+
+    from cadquery.func import *
+
+    dh = 2
+    r = 1
+
+    # construct edges
+    edge1 = circle(r)
+    edge2 = circle(1.5*r).moved(z=dh)
+    edge3 = circle(r).moved(z=1.5*dh)
+
+    # loft the side face
+    side = loft(edge1, edge2, edge3)
+
+    # bottom face
+    bottom = fill(side.edges('<Z'))
+
+    # top face with continuous curvature
+    top = cap(side.edges('>Z'), side, [(0,0,1.6*dh)])
+
+    # assemble into a solid
+    s = solid(side, bottom, top)
+
+    # construct the final result
+    result = s.moved((-3*r, 0, 0), (3*r, 0, 0))
+
+
+The code above builds a non-trivial object by sequentially constructing individual faces, assembling them into a solid and finally generating a pattern.
+
+It begins with defining few edges.
+
+.. code-block:: python
+
+   edge1 = circle(r)
+   edge2 = circle(2*r).moved(z=dh)
+   edge3 = circle(r).moved(z=1.5*dh)
+
+
+Those edges are used to create the side faces of the final solid using :meth:`~cadquery.occ_impl.shapes.loft`.
+
+.. code-block:: python
+
+   side = loft(edge1, edge2, edge3)
+
+Once the side is there, :meth:`~cadquery.occ_impl.shapes.cap` and :meth:`~cadquery.occ_impl.shapes.fill` are used to define the top and bottom faces.
+Note that :meth:`~cadquery.occ_impl.shapes.cap` tries to maintain curvature continuity with respect to the context shape. This is not the case for :meth:`~cadquery.occ_impl.shapes.fill`.
+
+.. code-block:: python
+
+   # bottom face
+   bottom = fill(side.edges('<Z'))
+
+   # top face with continuous curvature
+   top = cap(side.edges('>Z'), side, [(0,0,1.75*dh)])
+
+Next, all the faces are assembled into a solid.
+
+.. code-block:: python
+
+   s = solid(side, bottom, top)
+
+Finally, the solid is duplicated and placed in the desired locations creating the final compound object. Note various usages of :meth:`~cadquery.Shape.moved`.
+
+.. code-block:: python
+
+   result = s.moved((-3*r, 0, 0), (3*r, 0, 0))
+
+In general all the operations are implemented as free functions, with the exception of placement and selection which are strictly related to a specific shape.
+
+
+Primitives
+----------
+
+Various 1D, 2D and 3D primitives are supported.
+
+.. cadquery::
+
+    from cadquery.func import *
+
+    e = segment((0,0), (0,1))
+
+    c = circle(1)
+
+    f = plane(1, 1.5)
+
+    b = box(1, 1, 1)
+
+    result = compound(e, c.move(2), f.move(4), b.move(6))
+
+
+Boolean operations
+------------------
+
+Boolean operations are supported and implemented as operators and free functions.
+In general boolean operations are slow and it is advised to avoid them and not to perform the in a loop.
+One can for example union multiple solids at once by first combining them into a compound.
+
+.. cadquery::
+
+    from cadquery.func import *
+
+    c1 = cylinder(1, 2)
+    c2 = cylinder(0.5, 3)
+
+    f1 = plane(2, 2).move(z=1)
+    f2 = plane(1, 1).move(z=1)
+
+    e1 = segment((0,-2.5, 1), (0,2.5,1))
+
+    # union
+    r1 = c2 + c1
+    r2 = fuse(f1, f2)
+
+    # difference
+    r3 = c1 - c2
+    r4 = cut(f1, f2)
+
+    # intersection
+    r5 = c1*c2
+    r6 = intersect(f1, f2)
+
+    # splitting
+    r7 = (c1 / f1).solids('<Z')
+    r8 = split(f2, e1).faces('<X')
+
+    results = (r1, r2, r3, r4, r5, r6, r7, r8)
+    result = compound([el.moved(2*i) for i,el in enumerate(results)])
+
+Note that bool operations work on 2D shapes as well.
+
+
+Shape construction
+------------------
+
+Constructing complex shapes from simple shapes is possible in various contexts.
+
+.. cadquery::
+
+    from cadquery.func import *
+
+    e1 = segment((0,0), (1,0))
+    e2 = segment((1,0), (1,1))
+
+    # wire from edges
+    r1 = wire(e1, e2)
+
+    c1 = circle(1)
+
+    # face from a planar wire
+    r2 = face(c1)
+
+    # solid from faces
+    f1 = plane(1,1)
+    f2 = f1.moved(z=1)
+    f3 = extrude(f1.wires(), (0,0,1))
+
+    r3 = solid(f1,f2,*f3)
+
+    # compound from shapes
+    s1 = circle(1).moved(ry=90)
+    s2 = plane(1,1).move(rx=90).move(y=2)
+    s3 = cone(1,1.5).move(y=4)
+
+    r4 = compound(s1, s2, s3)
+
+    results = (r1, r2, r3, r4,)
+    result = compound([el.moved(2*i) for i,el in enumerate(results)])
+
+
+Operations
+----------
+
+Free function API currently supports :meth:`~cadquery.occ_impl.shapes.extrude`, :meth:`~cadquery.occ_impl.shapes.loft`, :meth:`~cadquery.occ_impl.shapes.revolve` and :meth:`~cadquery.occ_impl.shapes.sweep` operations.
+
+.. cadquery::
+
+    from cadquery.func import *
+
+    r = rect(1,0.5)
+    f = face(r, circle(0.2).moved(0.2), rect(0.2, 0.4).moved(-0.2))
+    c = circle(0.2)
+    p = spline([(0,0,0), (0,-1,2)], [(0,0,1), (0,-1,1)])
+
+    # extrude
+    s1 = extrude(r, (0,0,2))
+    s2 = extrude(fill(r), (0,0,1))
+
+    # sweep
+    s3 = sweep(r, p)
+    s4 = sweep(f, p)
+
+    # loft
+    s5 = loft(r, c.moved(z=2))
+    s6 = loft(r, c.moved(z=1), cap=True)\
+
+    # revolve
+    s7 = revolve(fill(r), (0.5, 0, 0), (0, 1, 0), 90)
+
+    results = (s1, s2, s3, s4, s5, s6, s7)
+    result = compound([el.moved(2*i) for i,el in enumerate(results)])
+
+
+Placement
+---------
+
+Placement and creation of arrays is possible using :meth:`~cadquery.Shape.move` and :meth:`~cadquery.Shape.moved`.
+
+.. cadquery::
+
+    from cadquery.func import *
+
+    locs = [(0,-1,0), (0,1,0)]
+
+    s = sphere(1).moved(locs)
+    c = cylinder(1,2).move(rx=15).moved(*locs)
+
+    result = compound(s, c.moved(2))
+
+Text
+----
+
+The free function API has extensive text creation capabilities including text on
+planar curves and text on surfaces.
+
+
+.. cadquery::
+
+    from cadquery.func import *
+
+    from math import pi
+
+    # parameters
+    D = 5
+    H = 2*D
+    S = H/10
+    TH = S/10
+    TXT = "CadQuery"
+
+    # base and spine
+    c = cylinder(D, H).moved(rz=-135)
+    cf = c.faces("%CYLINDER")
+    spine = (c*plane().moved(z=D)).edges().trim(pi/2, pi)
+
+    # planar
+    r1 = text(TXT, 1, spine, planar=True).moved(z=-S)
+
+    # normal
+    r2 = text(TXT, 1, spine)
+
+    # projected
+    r3 = text(TXT, 1, spine, cf).moved(z=S)
+
+    # projected and thickened
+    r4 = offset(r3, TH).moved(z=S)
+
+    result = compound(r1, r2, r3, r4)
+
+
+Adding features manually
+------------------------
+
+In certain cases it is desirable to add features such as holes or protrusions manually.
+E.g., for complicated shapes it might be beneficial performance-wise because it
+avoids boolean operations. One can add or remove faces, add holes to existing faces
+and last but not least reconstruct existing solids. 
+
+.. cadquery::
+    
+    from cadquery.func import *
+    
+    w = 1
+    r = 0.9*w/2
+    
+    # box
+    b = box(w, w, w)
+    # bottom face
+    b_bot = b.faces('<Z')
+    # top faces
+    b_top = b.faces('>Z')
+    
+    # inner face 
+    inner = extrude(circle(r), (0,0,w))
+    
+    # add holes to the bottom and top face
+    b_bot_hole = b_bot.addHole(inner.edges('<Z'))
+    b_top_hole = b_top.addHole(inner.edges('>Z'))
+    
+    # construct the final solid
+    result = solid(
+        b.remove(b_top, b_bot).faces(), #side faces
+        b_bot_hole, # bottom with a hole
+        inner, # inner cylinder face
+        b_top_hole, # top with a hole
+    )
+
+If the base shape is more complicated, it is possible to use local sewing that
+takes into account on indicated elements of the context shape. This, however,
+necessitates a two step approach - first a shell needs to be explicitly sewn
+and only then the final solid can be constructed.
+
+.. cadquery::
+
+    from cadquery.func import *
+    
+    w = 1
+    h = 0.1
+    r = 0.9*w/2
+    
+    # box
+    b = box(w, w, w)
+    # top face
+    b_top = b.faces('>Z')
+    
+    # protrusion
+    feat_side = extrude(circle(r).moved(b_top.Center()), (0,0,h))
+    feat_top = face(feat_side.edges('>Z'))
+    feat = shell(feat_side, feat_top) # sew into a shell
+    
+    # add hole to the box
+    b_top_hole = b_top.addHole(feat.edges('<Z'))
+    b = b.replace(b_top, b_top_hole)
+    
+    # local sewing - only two faces are taken into account
+    sh = shell(b_top_hole, feat.faces('<Z'), ctx=(b, feat))
+    # construct the final solid
+    result = solid(sh)
+
+
+Mapping onto parametric space
+-----------------------------
+
+To complement functionalities described, it is possible to trim edges and faces explicitly using simple rectangular
+trims, polygons, splines or arbitrary wires.
+
+.. cadquery::
+
+    from math import pi
+    from cadquery.func import cylinder, edgeOn, compound, wire
+
+    # parameters
+    d = 1.5
+    h = 3
+    du = pi
+    Nturns = 2
+
+    # construct the base surface
+    base = cylinder(d, h).faces("%CYLINDER")
+
+    # rectangular trim
+    r1 = base.trim(-pi/2, 0, 0, h/3)
+
+    # polyline trim
+    r2 = base.trim((0,0), (pi,0), (pi/2, h/2))
+
+    # construct a pcurve
+    pcurve = edgeOn(base, [(pi/2, h/4), (pi, h/4), (pi, h/2), (pi/2, h/2)], periodic=True)
+
+    # pcurve trim
+    r3 = base.trim(wire(pcurve))
+
+    result = compound(r1, r2.moved(x=2), r3.moved(x=4))
+
+
+This in principle allows to model arbitrary shapes in the parametric domain, but often it is more desirable
+to work with higher level objects like wires.
+
+
+.. cadquery::
+
+    from cadquery.func import cylinder, loft, wireOn, segment
+    from math import pi
+
+    # parameters
+    d = 1.5
+    h = 3
+    du = pi
+    Nturns = 2
+
+    # construct the base surface
+    base = cylinder(d, h).faces("%CYLINDER")
+
+    # construct a planar 2D patch for u,v trimming
+    uv_patch = loft(
+        segment((0, 0), (du, 0)), segment((Nturns * 2 * pi, h), (Nturns * 2 * pi + du, h))
+    )
+
+    # map it onto the cylinder
+    w = wireOn(base, uv_patch)
+
+    # check that the pcurves were created
+    for e in w:
+        assert e.hasPCurve(base), "No p-curve on base present"
+
+    # trim the base surface
+    result = base.trim(w)
+
+
+Note that trimming of periodic faces requires manual seam construction and an additional sewing
+step to ensure correctness.
+
+
+.. cadquery::
+
+    from cadquery.func import circle, extrude, spline, edgeOn, segment, wire, shell
+    from math import pi
+
+    # base
+    r = 5
+    h = 5
+
+    f = extrude(circle(r), (0, 0, -h))
+
+    # trimming edges
+    spl = spline([(0, h), (pi, h / 2.5), (2 * pi, h)], tgts=[(0.1, 0), (0.1, 0)])
+    top = edgeOn(f, spl)
+    bot = edgeOn(f, segment((2 * pi, 0), (0, 0)))
+    side1 = edgeOn(f, segment((0, 0), (0, h)))
+    side2 = edgeOn(f, segment((2 * pi, h), (2 * pi, 0)))
+
+    # trimming wire
+    trim_wire = wire(top, side1, bot, side2)
+
+    # trim and sew
+    result = shell(f.trim(trim_wire))
+
+
+Finally, it is also possible to map complete faces.
+
+
+.. cadquery::
+
+    from cadquery.func import sphere, text, faceOn
+
+    base = sphere(5).faces()
+
+    result = faceOn(base, text("CadQuery", 1))
+
+

server/docs/reference/primer.rst

@@ -0,0 +1,370 @@
+.. _3d_cad_primer:
+
+.. _cadquery_concepts:
+
+Concepts
+===================================
+
+
+3D BREP Topology Concepts
+---------------------------
+Before talking about CadQuery, it makes sense to talk a little about 3D CAD topology. CadQuery is based upon the
+OpenCascade kernel, which uses Boundary Representations (BREP) for objects.  This just means that objects
+are defined by their enclosing surfaces.
+
+When working in a BREP system, these fundamental constructs exist to define a shape (working up the food chain):
+
+   :vertex: a single point in space
+   :edge: a connection between two or more vertices along a particular path (called a curve)
+   :wire: a collection of edges that are connected together.
+   :face: a set of edges or wires that enclose a surface
+   :shell: a collection of faces that are connected together along some of their edges
+   :solid: a shell that has a closed interior
+   :compound: a collection of solids
+
+When using CadQuery, all of these objects are created, hopefully with the least possible work. In the actual CAD
+kernel, there is another set of Geometrical constructs involved as well. For example, an arc-shaped edge will
+hold a reference to an underlying curve that is a full circle, and each linear edge holds underneath it the equation
+for a line.  CadQuery shields you from these constructs.
+
+CadQuery API layers
+---------------------------
+
+Once you start to dive a bit more into CadQuery, you may find yourself a bit confused juggling between different types of objects the CadQuery APIs can return.
+This chapter aims to give an explanation on this topic and to provide background on the underlying implementation and kernel layers so you can leverage more of CadQuery functionality.
+
+CadQuery is composed of 4 different API, which are implemented on top of each other.
+
+1. The Fluent API
+    #. :class:`~cadquery.Workplane` 
+    #. :class:`~cadquery.Sketch` 
+    #. :class:`~cadquery.Assembly`
+2. The Direct API
+    #. :class:`~cadquery.Shape` 
+3. The Geometry API
+    #. :class:`~cadquery.Vector`
+    #. :class:`~cadquery.Plane`
+    #. :class:`~cadquery.Location`
+4. The OCCT API
+
+The Fluent API
+~~~~~~~~~~~~~~~~~~~~~~
+
+What we call the fluent API is what you work with when you first start using CadQuery, the :class:`~cadquery.Workplane` class and all its methods defines the Fluent API.
+This is the API you will use and see most of the time, it's fairly easy to use and it simplifies a lot of things for you. A classic example could be : ::
+
+    part = Workplane("XY").box(1, 2, 3).faces(">Z").vertices().circle(0.5).cutThruAll()
+
+Here we create a :class:`~cadquery.Workplane` object on which we subsequently call several methods to create our part. A general way of thinking about the Fluent API is to
+consider the :class:`~cadquery.Workplane` as your part object and all it's methods as operations that will affect your part.
+Often you will start with an empty :class:`~cadquery.Workplane`, then add more features by calling :class:`~cadquery.Workplane` methods.
+
+This hierarchical structure of operations modifying a part is well seen with the traditional code style used in CadQuery code.
+Code written with the CadQuery fluent API will often look like this : ::
+
+    part = Workplane("XY").box(1, 2, 3).faces(">Z").vertices().circle(0.5).cutThruAll()
+
+Or like this : ::
+
+    part = Workplane("XY")
+    part = part.box(1, 2, 3)
+    part = part.faces(">Z")
+    part = part.vertices()
+    part = part.circle(0.5)
+    part = part.cutThruAll()
+
+.. note::
+  While the first code style is what people default to, it's important to note that when you write your code like this it's equivalent as writting it on a single line.
+  It's then more difficult to debug as you cannot visualize each operation step by step, which is a functionality that is provided by the CQ-Editor debugger for example.
+
+The Direct API
+~~~~~~~~~~~~~~
+
+While the fluent API exposes much functionality, you may find scenarios that require extra flexibility or require working with lower level objects.
+
+The direct API is the API that is called by the fluent API under the hood. The 9 topological classes and their methods compose the direct API.
+These classes actually wrap the equivalent Open CASCADE Technology (OCCT) classes.
+The 9 topological classes are :
+
+1. :class:`~cadquery.Shape`
+2. :class:`~cadquery.Compound`
+3. :class:`~cadquery.CompSolid`
+4. :class:`~cadquery.Solid`
+5. :class:`~cadquery.Shell`
+6. :class:`~cadquery.Face`
+7. :class:`~cadquery.Wire`
+8. :class:`~cadquery.Edge`
+9. :class:`~cadquery.Vertex`
+
+Each class has its own methods to create and/or edit shapes of their respective type. One can also use the :ref:`freefuncapi` to create and modify shapes. As already explained in :ref:`cadquery_concepts` there is also some kind of hierarchy in the
+topological classes. A Wire is made of several edges which are themselves made of several vertices. This means you can create geometry from the bottom up and have a lot of control over it.
+
+For example we can create a circular face like so ::
+
+  circle_wire = Wire.makeCircle(10, Vector(0, 0, 0), Vector(0, 0, 1))
+  circular_face = Face.makeFromWires(circle_wire, [])
+
+.. note::
+  In CadQuery (and OCCT) all the topological classes are shapes, the :class:`~cadquery.Shape` class is the most abstract topological class.
+  The topological class inherits :class:`~cadquery.Mixin3D` or :class:`~cadquery.Mixin1D` which provide aditional methods that are shared between the classes that inherits them.
+
+The direct API as its name suggests doesn't provide a parent/children data structure, instead each method call directly returns an object of the specified topological type.
+It is more verbose than the fluent API and more tedious to work with, but as it offers more flexibility (you can work with faces, which is something you can't do in the fluent API)
+it is sometimes more convenient than the fluent API.
+
+The OCCT API
+~~~~~~~~~~~~~
+
+Finally we are discussing about the OCCT API. The OCCT API is the lowest level of CadQuery. The direct API is built upon the OCCT API, where the OCCT API in CadQuery is available through OCP.
+OCP are the Python bindings of the OCCT C++ libraries CadQuery uses. This means you have access to (almost) all the OCCT C++ libraries in Python and in CadQuery.
+Working with the OCCT API will give you the maximum flexibility and control over you designs, it is however very verbose and difficult to use. You will need to have a strong
+knowledge of the different C++ libraries to be able to achieve what you want. To obtain this knowledge the most obvious ways are :
+
+1. Read the direct API source code, since it is build upon the OCCT API it is full of example usage.
+2. Go through the `C++ documentation <https://dev.opencascade.org/doc/overview/html/>`_
+
+.. note::
+  The general way of importing a specific class of the OCCT API is ::
+
+    from OCP.thePackageName import theClassName
+
+  For example if you want to use the class `BRepPrimAPI_MakeBox <https://dev.opencascade.org/doc/refman/html/class_b_rep_prim_a_p_i___make_box.html>`_.
+  You will go by the following ::
+
+    from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox
+
+  The package name of any class is written at the top of the documentation page. Often it's written in the class name itself as a prefix.
+
+Going back and forth between the APIs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While the 3 APIs provide 3 different layer of complexity and functionality you can mix the 3 layers as you wish.
+Below is presented the different ways you can interact with the different API layers.
+
+-------------------------
+Fluent API <=> Direct API
+-------------------------
+
+.. currentmodule:: cadquery
+
+Here are all the possibilities you have to get an object from the Direct API (i.e a topological object).
+
+You can end the Fluent API call chain and get the last object on the stack with :py:meth:`Workplane.val` alternatively you can get all
+the objects with :py:meth:`Workplane.vals`
+
+.. code-block:: pycon
+
+    >>> box = Workplane().box(10, 5, 5)
+    >>> print(type(box))
+    <class cadquery.cq.Workplane>
+
+    >>> box = Workplane().box(10, 5, 5).val()
+    >>> print(type(box))
+    <class cadquery.occ_impl.shapes.Solid>
+
+If you are only interested in getting the context solid of your Workplane, you can use :py:meth:`Workplane.findSolid`:
+
+.. code-block::
+
+    >>> part = Workplane().box(10,5,5).circle(3).val()
+    >>> print(type(part))
+    <class cadquery.cq.Wire>
+
+    >>> part = Workplane().box(10,5,5).circle(3).findSolid()
+    >>> print(type(part))
+    <class cadquery.occ_impl.shapes.Compound>
+    # The return type of findSolid is either a Solid or a Compound object
+
+If you want to go the other way around i.e using objects from the topological API in the Fluent API here are your options :
+
+You can pass a topological object as a base object to the :class:`~cadquery.Workplane` object. ::
+
+  solid_box = Solid.makeBox(10, 10, 10)
+  part = Workplane(obj=solid_box)
+  # And you can continue your modelling in the fluent API
+  part = part.faces(">Z").circle(1).extrude(10)
+
+
+You can add a topological object as a new operation/step in the Fluent API call chain with :py:meth:`Workplane.newObject` ::
+
+  circle_wire = Wire.makeCircle(1, Vector(0, 0, 0), Vector(0, 0, 1))
+  box = Workplane().box(10, 10, 10).newObject([circle_wire])
+  # And you can continue modelling
+  box = (
+      box.toPending().cutThruAll()
+  )  # notice the call to `toPending` that is needed if you want to use it in a subsequent operation
+
+-------------------------
+Direct API <=> OCCT API
+-------------------------
+
+Every object of the Direct API stores its OCCT equivalent object in its :attr:`wrapped` attribute.:
+
+.. code-block::
+
+    >>> box = Solid.makeBox(10,5,5)
+    >>> print(type(box))
+    <class cadquery.occ_impl.shapes.Solid>
+
+    >>> box = Solid.makeBox(10,5,5).wrapped
+    >>> print(type(box))
+    <class OCP.TopoDS.TopoDS_Solid>
+
+
+If you want to cast an OCCT object into a Direct API one you can just pass it as a parameter of the intended class:
+
+.. code-block::
+
+    >>> occt_box = BRepPrimAPI_MakeBox(5,5,5).Solid()
+    >>> print(type(occt_box))
+    <class OCP.TopoDS.TopoDS_Solid>
+
+    >>> direct_api_box = Solid(occt_box)
+    >>> print(type(direct_api_box))
+    <class cadquery.occ_impl.shapes.Solid>
+
+.. note::
+  You can cast into the direct API the types found `here <https://dev.opencascade.org/doc/refman/html/class_topo_d_s___shape.html>`_
+
+Multimethods
+------------
+
+CadQuery uses `Multimethod <https://coady.github.io/multimethod/>`_ to allow a call to a method to
+be dispatched depending on the types of the arguments. An example is :meth:`~cadquery.Sketch.arc`,
+where ``a_sketch.arc((1, 2), (2, 3))`` would be dispatched to one method but ``a_sketch.arc((1, 2),
+(2, 3), (3, 4))`` would be dispatched to a different method. For multimethods to work, you should
+not use keyword arguments to specify positional parameters. For example, you **should not** write
+``a_sketch.arc(p1=(1, 2), p2=(2, 3), p3=(3, 4))``, instead you should use the previous example.
+Note CadQuery makes an attempt to fall back on the first registered multimethod in the event of a
+dispatch error, but it is still best practice to not use keyword arguments to specify positional
+arguments in CadQuery.
+
+Selectors
+---------------------------
+
+Selectors allow you to select one or more features, in order to define new features.  As an example, you might
+extrude a box, and then select the top face as the location for a new feature.  Or, you might extrude a box, and
+then select all of the vertical edges so that you can apply a fillet to them.
+
+You can select Vertices, Edges, Faces, Solids, and Wires using selectors.
+
+Think of selectors as the equivalent of your hand and mouse, if you were to build an object using a conventional CAD system.
+
+See :ref:`selectors` to learn more.
+
+
+Workplane class
+---------------------------
+
+The Workplane class contains the currently selected objects (a list of Shapes, Vectors or Locations
+in the :attr:`~cadquery.Workplane.objects` attribute), the modelling context (in the
+:attr:`~cadquery.Workplane.ctx` attribute), and CadQuery's fluent api methods. It is the main class
+that users will instantiate.
+
+See :ref:`apireference` to learn more.
+
+
+Assemblies
+----------
+
+Simple models can be combined into complex, possibly nested, assemblies.
+
+.. image:: _static/assy.png
+
+A simple example could look as follows::
+
+    from cadquery import *
+
+    w = 10
+    d = 10
+    h = 10
+
+    part1 = Workplane().box(2 * w, 2 * d, h)
+    part2 = Workplane().box(w, d, 2 * h)
+    part3 = Workplane().box(w, d, 3 * h)
+
+    assy = (
+        Assembly(part1, loc=Location(Vector(-w, 0, h / 2)))
+        .add(
+            part2, loc=Location(Vector(1.5 * w, -0.5 * d, h / 2)), color=Color(0, 0, 1, 0.5)
+        )
+        .add(part3, loc=Location(Vector(-0.5 * w, -0.5 * d, 2 * h)), color=Color("red"))
+    )
+
+Resulting in:
+
+.. image:: _static/simple_assy.png
+
+Note that the locations of the children parts are defined with respect to their parents - in the above example ``part3`` will be located at (-5,-5,20) in the global coordinate system. Assemblies with different colors can be created this way and exported to STEP or the native OCCT xml format.
+
+You can browse assembly related methods here: :ref:`assembly`.
+
+Assemblies with constraints
+---------------------------
+
+Sometimes it is not desirable to define the component positions explicitly but rather use
+constraints to obtain a fully parametric assembly. This can be achieved in the following way::
+
+    from cadquery import *
+
+    w = 10
+    d = 10
+    h = 10
+
+    part1 = Workplane().box(2 * w, 2 * d, h)
+    part2 = Workplane().box(w, d, 2 * h)
+    part3 = Workplane().box(w, d, 3 * h)
+
+    assy = (
+        Assembly(part1, name="part1", loc=Location(Vector(-w, 0, h / 2)))
+        .add(part2, name="part2", color=Color(0, 0, 1, 0.5))
+        .add(part3, name="part3", color=Color("red"))
+        .constrain("part1@faces@>Z", "part3@faces@<Z", "Axis")
+        .constrain("part1@faces@>Z", "part2@faces@<Z", "Axis")
+        .constrain("part1@faces@>Y", "part3@faces@<Y", "Axis")
+        .constrain("part1@faces@>Y", "part2@faces@<Y", "Axis")
+        .constrain("part1@vertices@>(-1,-1,1)", "part3@vertices@>(-1,-1,-1)", "Point")
+        .constrain("part1@vertices@>(1,-1,-1)", "part2@vertices@>(-1,-1,-1)", "Point")
+        .solve()
+    )
+
+This code results in identical object as one from the previous section. The added
+benefit is that with changing parameters ``w``, ``d``, ``h`` the final locations
+will be calculated automatically. It is admittedly dense and can be made clearer
+using tags. Tags can be directly referenced when constructing the constraints::
+
+    from cadquery import *
+
+    w = 10
+    d = 10
+    h = 10
+
+    part1 = Workplane().box(2 * w, 2 * d, h)
+    part2 = Workplane().box(w, d, 2 * h)
+    part3 = Workplane().box(w, d, 3 * h)
+
+    part1.faces(">Z").edges("<X").vertices("<Y").tag("pt1")
+    part1.faces(">X").edges("<Z").vertices("<Y").tag("pt2")
+    part3.faces("<Z").edges("<X").vertices("<Y").tag("pt1")
+    part2.faces("<X").edges("<Z").vertices("<Y").tag("pt2")
+
+    assy1 = (
+        Assembly(part1, name="part1", loc=Location(Vector(-w, 0, h / 2)))
+        .add(part2, name="part2", color=Color(0, 0, 1, 0.5))
+        .add(part3, name="part3", color=Color("red"))
+        .constrain("part1@faces@>Z", "part3@faces@<Z", "Axis")
+        .constrain("part1@faces@>Z", "part2@faces@<Z", "Axis")
+        .constrain("part1@faces@>Y", "part3@faces@<Y", "Axis")
+        .constrain("part1@faces@>Y", "part2@faces@<Y", "Axis")
+        .constrain("part1?pt1", "part3?pt1", "Point")
+        .constrain("part1?pt2", "part2?pt2", "Point")
+        .solve()
+    )
+
+The following constraints are currently implemented:
+
+   :Axis: two normal vectors are anti-coincident or the angle (in radians) between them is equal to the specified value. Can be defined for all entities with consistent normal vector - planar faces, wires and edges.
+   :Point: two points are coincident or separated by a specified distance. Can be defined for all entities, center of mass is used for lines, faces, solids and the vertex position for vertices.
+   :Plane: combination of :Axis: and :Point: constraints.
+
+For a more elaborate assembly example see :ref:`assytutorial`.

server/docs/reference/quickstart.rst

@@ -0,0 +1,294 @@
+.. _quickstart:
+
+***********************
+QuickStart
+***********************
+
+.. currentmodule:: cadquery
+
+Want a quick glimpse of what CadQuery can do?  This quickstart will demonstrate the basics of CadQuery using a simple example
+
+Prerequisites: CadQuery and CQ-editor installation
+==================================================
+
+If you have not already done so, follow the :ref:`installation`, to install CadQuery and CQ-editor.
+
+After installation, run CQ-editor:
+
+.. image:: _static/quickstart/001.png
+
+Find the CadQuery code editor, on the left side.  You'll see that we start out with the script for a simple block.
+
+What we'll accomplish
+========================
+
+We will build a fully parametric bearing pillow block in this quickstart.  Our finished object will look like this:
+
+.. image:: _static/quickstart/000.png
+
+**We would like our block to have these features:**
+
+    1. It should be sized to hold a single 608 ( 'skate' ) bearing, in the center of the block.
+    2. It should have counter-bored holes for M2 socket head cap screws at the corners.
+    3. The length and width of the block should be configurable by the user to any reasonable size.
+
+A human would describe this as:
+
+     "A rectangular block 80mm x 60mm x 10mm , with counter-bored holes for M2 socket head cap screws
+     at the corners, and a circular pocket 22mm in diameter in the middle for a bearing."
+
+Human descriptions are very elegant, right?
+Hopefully our finished script will not be too much more complex than this human-oriented description.
+
+Let's see how we do.
+
+Start With A single, simple Plate
+======================================
+
+Let's start with a simple model that makes nothing but a rectangular block, but
+with place-holders for the dimensions. Paste this into the code editor:
+
+.. code-block:: python
+   :linenos:
+
+   height = 60.0
+   width = 80.0
+   thickness = 10.0
+
+   # make the base
+   result = cq.Workplane("XY").box(height, width, thickness)
+
+   # Render the solid
+   show_object(result)
+
+Press the green Render button in the toolbar to run the script. You should see our base object.
+
+.. image:: _static/quickstart/002.png
+
+Nothing special, but its a start!
+
+Add the Holes
+================
+
+Our pillow block needs to have a 22mm diameter hole in the center to hold the bearing.
+
+This modification will do the trick:
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 4,10-12
+
+   height = 60.0
+   width = 80.0
+   thickness = 10.0
+   diameter = 22.0
+
+   # make the base
+   result = (
+       cq.Workplane("XY")
+       .box(height, width, thickness)
+       .faces(">Z")
+       .workplane()
+       .hole(diameter)
+   )
+
+   # Render the solid
+   show_object(result)
+
+Rebuild your model by clicking the Render button. Your block should look like this:
+
+.. image:: _static/quickstart/003.png
+
+
+The code is pretty compact, let's step through it.
+
+**Line 4** adds a new parameter, diameter, for the diameter of the hole
+
+**Lines 10-12**, we're adding the hole.
+:py:meth:`cadquery.Workplane.faces` selects the top-most face in the Z direction, and then
+:py:meth:`cadquery.Workplane.workplane` begins a new workplane located on this face. The center of this workplane
+is located at the center of mass of the shape, which in this case is the center of the plate.
+Finally, :py:meth:`cadquery.Workplane.hole` drills a hole through the part, 22mm in diameter.
+
+.. note::
+
+    Don't worry about the CadQuery syntax now.. you can learn all about it in the :ref:`apireference` later.
+
+More Holes
+============
+
+Ok, that hole was not too hard, but what about the counter-bored holes in the corners?
+
+An M2 Socket head cap screw has these dimensions:
+
+  * **Head Diameter** : 3.8 mm
+  * **Head height**  : 2.0 mm
+  * **Clearance Hole** : 2.4 mm
+  * **CounterBore diameter** : 4.4 mm
+
+The centers of these holes should be 6mm from the edges of the block. And,
+we want the block to work correctly even when the block is re-sized by the user.
+
+**Don't tell me** we'll have to repeat the steps above 8 times to get counter-bored holes?
+Good news!-- we can get the job done with just a few lines of code. Here's the code we need:
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 5,14-18
+
+   height = 60.0
+   width = 80.0
+   thickness = 10.0
+   diameter = 22.0
+   padding = 12.0
+
+   # make the base
+   result = (
+       cq.Workplane("XY")
+       .box(height, width, thickness)
+       .faces(">Z")
+       .workplane()
+       .hole(diameter)
+       .faces(">Z")
+       .workplane()
+       .rect(height - padding, width - padding, forConstruction=True)
+       .vertices()
+       .cboreHole(2.4, 4.4, 2.1)
+   )
+   # Render the solid
+   show_object(result)
+
+
+After clicking the Render button to re-execute the model, you should see something like this:
+
+        .. image:: _static/quickstart/004.png
+
+
+There is quite a bit going on here, so let's break it down a bit.
+
+**Line 5** creates a new padding parameter that decides how far the holes are from the edges of the plate.
+
+**Lines 14-15** selects the top-most face of the block, and creates a workplane on the top of that face, which we'll use to
+define the centers of the holes in the corners.
+
+**Line 16** draws a rectangle 12mm smaller than the overall length and width of the block, which we will use to
+locate the corner holes. We'll use the vertices ( corners ) of this rectangle to locate the holes. The rectangle's
+center is at the center of the workplane, which in this case coincides with the center of the bearing hole.
+
+There are a couple of things to note about this line:
+
+    1. The :py:meth:`cadquery.Workplane.rect` function draws a rectangle.  **forConstruction=True**
+       tells CadQuery that this rectangle will not form a part of the solid,
+       but we are just using it to help define some other geometry.
+    2. Unless you specify otherwise, a rectangle is drawn with its center on the current workplane center-- in
+       this case, the center of the top face of the block. So this rectangle will be centered on the face.
+
+**Line 17** selects the vertices of the rectangle, which we will use for the centers of the holes.
+The :py:meth:`cadquery.Workplane.vertices` function selects the corners of the rectangle.
+
+**Line 18** uses the cboreHole function to draw the holes.
+The :py:meth:`cadquery.Workplane.cboreHole` function is a handy CadQuery function that makes a counterbored hole.
+Like most other CadQuery functions, it operates on the values on the stack.  In this case, since we
+selected the four vertices before calling the function, the function operates on each of the four points--
+which results in a counterbore hole at each of the rectangle corners.
+
+
+Filleting
+===========
+
+Almost done. Let's just round the corners of the block a bit. That's easy, we just need to select the edges
+and then fillet them:
+
+We can do that using the preset dictionaries in the parameter definition:
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 19-20
+
+   height = 60.0
+   width = 80.0
+   thickness = 10.0
+   diameter = 22.0
+   padding = 12.0
+
+   # make the base
+   result = (
+       cq.Workplane("XY")
+       .box(height, width, thickness)
+       .faces(">Z")
+       .workplane()
+       .hole(diameter)
+       .faces(">Z")
+       .workplane()
+       .rect(height - padding, width - padding, forConstruction=True)
+       .vertices()
+       .cboreHole(2.4, 4.4, 2.1)
+       .edges("|Z")
+       .fillet(2.0)
+   )
+
+   # Render the solid
+   show_object(result)
+
+**Line 19** To grab the right edges, the :py:meth:`cadquery.Workplane.edges` selects all of the
+edges that are parallel to the Z axis ("\|Z").
+
+**Line 20** fillets the edges using the :py:meth:`cadquery.Workplane.fillet` method.
+
+The finished product looks like this:
+
+        .. image:: _static/quickstart/005.png
+
+Exporting
+=========
+
+If you want to fabricate a physical object you need to export the result to STL or DXF. Additionally, exporting as STEP for post-processing in another CAD tool is also possible.
+
+This can be easily accomplished using the :py:meth:`cadquery.exporters.export` function:
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 27-29
+
+   height = 60.0
+   width = 80.0
+   thickness = 10.0
+   diameter = 22.0
+   padding = 12.0
+
+   # make the base
+   result = (
+       cq.Workplane("XY")
+       .box(height, width, thickness)
+       .faces(">Z")
+       .workplane()
+       .hole(diameter)
+       .faces(">Z")
+       .workplane()
+       .rect(height - padding, width - padding, forConstruction=True)
+       .vertices()
+       .cboreHole(2.4, 4.4, 2.1)
+       .edges("|Z")
+       .fillet(2.0)
+   )
+
+   # Render the solid
+   show_object(result)
+
+   # Export
+   cq.exporters.export(result, "result.stl")
+   cq.exporters.export(result.section(), "result.dxf")
+   cq.exporters.export(result, "result.step")
+
+Done!
+============
+
+You just made a parametric, model that can generate pretty much any bearing pillow block
+with <30 lines of code.
+
+Want to learn more?
+====================
+
+   * The :ref:`examples` contains lots of examples demonstrating cadquery features
+   * The :ref:`apireference` is a good overview of language features grouped by function
+   * The :ref:`classreference` is the hard-core listing of all functions available.

server/docs/reference/selectors.rst

@@ -0,0 +1,232 @@
+.. _selector_reference:
+
+Selectors Reference
+===================
+
+
+CadQuery selector strings allow filtering various types of object lists. Most commonly, Edges, Faces, and Vertices are
+used, but all objects types can be filtered.
+
+Object lists are created by using the following methods, which each collect a type of shape:
+
+    * :py:meth:`cadquery.Workplane.vertices`
+    * :py:meth:`cadquery.Workplane.edges`
+    * :py:meth:`cadquery.Workplane.faces`
+    * :py:meth:`cadquery.Workplane.shells`
+    * :py:meth:`cadquery.Workplane.solids`
+
+Each of these methods accepts either a Selector object or a string. String selectors are simply
+shortcuts for using the full object equivalents. If you pass one of the string patterns in,
+CadQuery will automatically use the associated selector object.
+
+
+.. note::
+
+    String selectors are simply shortcuts to concrete selector classes, which you can use or
+    extend. For a full description of how each selector class works, see :ref:`classreference`.
+
+    If you find that the built-in selectors are not sufficient, you can easily plug in your own.
+    See :ref:`extending` to see how.
+
+
+Combining Selectors
+--------------------------
+
+Selectors can be combined logically, currently defined operators include **and**, **or**, **not** and **exc[ept]** (set difference).  For example:
+
+.. cadquery::
+
+    result = cq.Workplane("XY").box(2, 2, 2).edges("|Z and >Y").chamfer(0.2)
+
+Much more complex expressions are possible as well:
+
+.. cadquery::
+
+    result = (
+        cq.Workplane("XY")
+        .box(2, 2, 2)
+        .faces(">Z")
+        .shell(-0.2)
+        .faces(">Z")
+        .edges("not(<X or >X or <Y or >Y)")
+        .chamfer(0.1)
+    )
+
+.. _filteringfaces:
+
+Filtering Faces
+----------------
+
+All types of string selectors work on faces.  In most cases, the selector refers to the direction
+of the **normal vector** of the face.
+
+.. warning::
+
+    If a face is not planar, selectors are evaluated at the center of mass of the face. This can lead
+    to results that are quite unexpected.
+
+The axis used in the listing below are for illustration: any axis would work similarly in each case.
+
+=========   =========================================  =======================================================
+Selector    Selects                                    Selector Class
+=========   =========================================  =======================================================
++Z          Faces with normal in +z direction          :py:class:`cadquery.DirectionSelector`
+\|Z         Faces with normal parallel to z dir        :py:class:`cadquery.ParallelDirSelector`
+-X          Faces with normal in neg x direction       :py:class:`cadquery.DirectionSelector`
+#Z          Faces with normal orthogonal to z dir      :py:class:`cadquery.PerpendicularDirSelector`
+%Plane      Faces of type plane                        :py:class:`cadquery.TypeSelector`
+>Y          Face farthest in the positive y dir        :py:class:`cadquery.DirectionMinMaxSelector`
+<Y          Face farthest in the negative y dir        :py:class:`cadquery.DirectionMinMaxSelector`
+>Y[-2]      2nd farthest Face **normal** to the y dir  :py:class:`cadquery.DirectionNthSelector`
+<Y[0]       1st closest Face **normal** to the y dir   :py:class:`cadquery.DirectionNthSelector`
+>>Y[-2]     2nd farthest Face in the y dir             :py:class:`cadquery.CenterNthSelector`
+<<Y[0]      1st closest Face in the y dir              :py:class:`cadquery.CenterNthSelector`
+=========   =========================================  =======================================================
+
+
+.. _filteringedges:
+
+Filtering Edges
+----------------
+
+The selector usually refers to the **direction** of the edge.
+
+.. warning::
+
+    Non-linear edges are not selected for any string selectors except type (%) and center (>>).
+    Non-linear edges are never returned when these filters are applied.
+
+The axis used in the listing below are for illustration: any axis would work similarly in each case.
+
+
+========  ====================================================  =============================================
+Selector  Selects                                               Selector Class
+========  ====================================================  =============================================
++Z        Edges aligned in the Z direction                      :py:class:`cadquery.DirectionSelector`
+\|Z       Edges parallel to z direction                         :py:class:`cadquery.ParallelDirSelector`
+-X        Edges aligned in neg x direction                      :py:class:`cadquery.DirectionSelector`
+#Z        Edges perpendicular to z direction                    :py:class:`cadquery.PerpendicularDirSelector`
+%Line     Edges of type line                                    :py:class:`cadquery.TypeSelector`
+>Y        Edges farthest in the positive y dir                  :py:class:`cadquery.DirectionMinMaxSelector`
+<Y        Edges farthest in the negative y dir                  :py:class:`cadquery.DirectionMinMaxSelector`
+>Y[1]     2nd closest **parallel** edge in the positive y dir   :py:class:`cadquery.DirectionNthSelector`
+<Y[-2]    2nd farthest **parallel** edge in the negative y dir  :py:class:`cadquery.DirectionNthSelector`
+>>Y[-2]   2nd farthest edge in the y dir                        :py:class:`cadquery.CenterNthSelector`
+<<Y[0]    1st closest edge in the y dir                         :py:class:`cadquery.CenterNthSelector`
+========  ====================================================  =============================================
+
+
+.. _filteringvertices:
+
+Filtering Vertices
+-------------------
+
+Only a few of the filter types apply to vertices. The location of the vertex is the subject of the filter.
+
+=========   =======================================    =======================================================
+Selector    Selects                                    Selector Class
+=========   =======================================    =======================================================
+>Y          Vertices farthest in the positive y dir    :py:class:`cadquery.DirectionMinMaxSelector`
+<Y          Vertices farthest in the negative y dir    :py:class:`cadquery.DirectionMinMaxSelector`
+>>Y[-2]     2nd farthest vertex in the y dir           :py:class:`cadquery.CenterNthSelector`
+<<Y[0]      1st closest vertex in the y dir            :py:class:`cadquery.CenterNthSelector`
+=========   =======================================    =======================================================
+
+User-defined Directions
+-----------------------
+
+It is possible to use user defined vectors as a basis for the selectors. For example:
+
+.. cadquery::
+
+    result = cq.Workplane("XY").box(10, 10, 10)
+
+    # chamfer only one edge
+    result = result.edges(">(-1, 1, 0)").chamfer(1)
+
+
+Topological Selectors
+---------------------
+
+Is is also possible to use topological relations to select objects. Currently
+the following methods are supported:
+
+    * :py:meth:`cadquery.Workplane.ancestors`
+    * :py:meth:`cadquery.Workplane.siblings`
+
+Ancestors allows to select all objects containing currently selected object.
+
+.. cadquery::
+
+    result = cq.Workplane("XY").box(10, 10, 10).faces(">Z").edges("<Y")
+
+    result = result.ancestors("Face")
+
+Siblings allows to select all objects of the same type as selection that are connected
+via the specfied kind of elements.
+
+.. cadquery::
+
+    result = cq.Workplane("XY").box(10, 10, 10).faces(">Z")
+
+    result = result.siblings("Edge")
+
+
+Using selectors with Shape and Sketch objects
+---------------------------------------------
+
+It is possible to use selectors with :py:class:`cadquery.Shape` and :py:class:`cadquery.Sketch`
+objects. This includes chaining and combining.
+
+.. cadquery::
+
+    box = cq.Solid.makeBox(1,2,3)
+
+    # select top and bottom wires
+    result = box.faces(">Z or <Z").wires()
+
+
+
+
+Additional special methods
+--------------------------
+
+:py:class:`cadquery.Workplane` and :py:class:`cadquery.Sketch` provide the following special methods that can be used
+for quick prototyping of selectors when implementing a complete selector via subclassing of
+:py:class:`cadquery.Selector` is not desirable.
+
+    * :py:meth:`cadquery.Workplane.filter`
+    * :py:meth:`cadquery.Workplane.sort`
+    * :py:meth:`cadquery.Workplane.__getitem__`
+    * :py:meth:`cadquery.Sketch.filter`
+    * :py:meth:`cadquery.Sketch.sort`
+    * :py:meth:`cadquery.Sketch.__getitem__`
+
+For example, one could use those methods for selecting objects within a certain range of volumes.
+
+.. cadquery::
+
+    from cadquery.occ_impl.shapes import box
+
+    result = (
+        cq.Workplane()
+        .add([box(1,1,i+1).moved(x=2*i) for i in range(5)])
+    )
+
+    # select boxes with volume <= 3
+    result = result.filter(lambda s: s.Volume() <= 3)
+
+
+The same can be achieved using sorting.
+
+.. cadquery::
+
+    from cadquery.occ_impl.shapes import box
+
+    result = (
+        cq.Workplane()
+        .add([box(1,1,i+1).moved(x=2*i) for i in range(5)])
+    )
+
+    # select boxes with volume <= 3
+    result = result.sort(lambda s: s.Volume())[:3]

server/docs/reference/sketch.rst

@@ -0,0 +1,378 @@
+.. _sketchtutorial:
+
+******
+Sketch
+******
+
+Sketch tutorial
+---------------
+
+The purpose of this section is to demonstrate how to construct sketches using different
+approaches.
+
+Face-based API
+==============
+
+The main approach for constructing sketches is based on constructing faces and
+combining them using boolean operations.
+
+.. cadquery::
+    :height: 600px
+
+    import cadquery as cq
+
+    result = (
+        cq.Sketch()
+        .trapezoid(4, 3, 90)
+        .vertices()
+        .circle(0.5, mode="s")
+        .reset()
+        .vertices()
+        .fillet(0.25)
+        .reset()
+        .rarray(0.6, 1, 5, 1)
+        .slot(1.5, 0.4, mode="s", angle=90)
+    )
+
+Note that selectors are implemented, but selection has to be explicitly reset. Sketch
+class does not implement history and all modifications happen in-place.
+
+Modes
+^^^^^
+
+Every operation from the face API accepts a mode parameter to define
+how to combine the created object with existing ones. It can be fused (``mode='a'``),
+cut (``mode='s'``), intersected (``mode='i'``), replaced (``mode='r'``)
+or just stored for construction (``mode='c'``).
+In the last case, it is mandatory to specify a ``tag`` in order to be able to
+refer to the object later on. By default faces are fused together.
+Note the usage of the subtractive and additive modes in the example above.
+The additional two are demonstrated below.
+
+.. cadquery::
+    :height: 600px
+
+    result = (
+        cq.Sketch()
+        .rect(1, 2, mode="c", tag="base")
+        .vertices(tag="base")
+        .circle(0.7)
+        .reset()
+        .edges("|Y", tag="base")
+        .ellipse(1.2, 1, mode="i")
+        .reset()
+        .rect(2, 2, mode="i")
+        .clean()
+    )
+
+
+Edge-based API
+==============
+
+If needed, one can construct sketches by placing individual edges.
+
+.. cadquery::
+    :height: 600px
+
+    import cadquery as cq
+
+    result = (
+        cq.Sketch()
+        .segment((0.0, 0), (0.0, 2.0))
+        .segment((2.0, 0))
+        .close()
+        .arc((0.6, 0.6), 0.4, 0.0, 360.0)
+        .assemble(tag="face")
+        .edges("%LINE", tag="face")
+        .vertices()
+        .chamfer(0.2)
+    )
+
+Once the construction is finished it has to be converted to the face-based representation
+using :meth:`~cadquery.Sketch.assemble`. Afterwards, face based operations can be applied.
+
+
+Convex hull
+===========
+
+.. warning:: The Convex Hull feature is currently experimental.
+
+For certain special use-cases convex hull can be constructed from straight segments
+and circles.
+
+.. cadquery::
+    :height: 600px
+
+    result = (
+        cq.Sketch()
+        .arc((0, 0), 1.0, 0.0, 360.0)
+        .arc((1, 1.5), 0.5, 0.0, 360.0)
+        .segment((0.0, 2), (-1, 3.0))
+        .hull()
+    )
+
+Constraint-based sketches
+=========================
+
+.. warning:: The 2D Sketch constraints and solver is currently experimental.
+
+Finally, if desired, geometric constraints can be used to construct sketches. So
+far only line segments and arcs can be used in such a use case.
+
+.. cadquery::
+    :height: 600px
+
+    import cadquery as cq
+
+    result = (
+        cq.Sketch()
+        .segment((0, 0), (0, 3.0), "s1")
+        .arc((0.0, 3.0), (1.5, 1.5), (0.0, 0.0), "a1")
+        .constrain("s1", "Fixed", None)
+        .constrain("s1", "a1", "Coincident", None)
+        .constrain("a1", "s1", "Coincident", None)
+        .constrain("s1", "a1", "Angle", 45)
+        .solve()
+        .assemble()
+    )
+
+Following constraints are implemented. Arguments are passed in as one tuple in :meth:`~cadquery.Sketch.constrain`. In this table, `0..1` refers to a float between 0 and 1 where 0 would create a constraint relative to the start of the element, and 1 the end.
+
+.. list-table::
+    :widths: 15 10 15 30 30
+    :header-rows: 1
+
+    * - Name
+      - Arity
+      - Entities
+      - Arguments
+      - Description
+    * - FixedPoint
+      - 1
+      - All
+      - `None` for arc center or `0..1` for point on segment/arc
+      - Specified point is fixed
+    * - Coincident
+      - 2
+      - All
+      - None
+      - Specified points coincide
+    * - Angle
+      - 2
+      - All
+      - `angle`
+      - Angle between the tangents of the two entities is fixed
+    * - Length
+      - 1
+      - All
+      - `length`
+      - Specified entity has fixed length
+    * - Distance
+      - 2
+      - All
+      - `None or 0..1, None or 0..1, distance`
+      - Distance between two points is fixed
+    * - Radius
+      - 1
+      - Arc
+      - `radius`
+      - Specified entity has a fixed radius
+    * - Orientation
+      - 1
+      - Segment
+      - `x,y`
+      - Specified entity is parallel to `(x,y)`
+    * - ArcAngle
+      - 1
+      - Arc
+      - `angle`
+      - Specified entity is fixed angular span
+
+
+Workplane integration
+---------------------
+
+Once created, a sketch can be used to construct various features on a workplane.
+Supported operations include :meth:`~cadquery.Workplane.extrude`,
+:meth:`~cadquery.Workplane.twistExtrude`, :meth:`~cadquery.Workplane.revolve`,
+:meth:`~cadquery.Workplane.sweep`, :meth:`~cadquery.Workplane.cutBlind`, :meth:`~cadquery.Workplane.cutThruAll` and :meth:`~cadquery.Workplane.loft`.
+
+Sketches can be created as separate entities and reused, but also created ad-hoc
+in one fluent chain of calls as shown below.
+
+Sketches in-place
+=================
+
+Constructing sketches in-place can be accomplished as follows.
+
+.. cadquery::
+    :height: 600px
+
+    import cadquery as cq
+
+    result = (
+        cq.Workplane()
+        .box(5, 5, 1)
+        .faces(">Z")
+        .sketch()
+        .regularPolygon(2, 3, tag="outer")
+        .regularPolygon(1.5, 3, mode="s")
+        .vertices(tag="outer")
+        .fillet(0.2)
+        .finalize()
+        .extrude(0.5)
+    )
+
+Sketch API is available after the :meth:`~cadquery.Workplane.sketch` call and original `workplane`.
+
+Placing an existing sketch on a workplane
+=========================================
+
+Sometimes it is desired to place an existing sketches as-is on a workplane. This can be done with :meth:`~cadquery.Workplane.placeSketch`
+
+.. cadquery::
+    :height: 600px
+
+    import cadquery as cq
+
+    s = cq.Sketch().trapezoid(3, 1, 110).vertices().fillet(0.2)
+
+    result = (
+        cq.Workplane()
+        .box(5, 5, 5)
+        .faces(">X")
+        .workplane()
+        .transformed((0, 0, -90))
+        .placeSketch(s)
+        .cutThruAll()
+    )
+
+Sketches spanning multiple elements
+===================================
+
+When multiple elements are selected before constructing the sketch, multiple sketches will be created.
+
+Note that the sketch is placed on all locations that are on the top of the stack.
+
+.. cadquery::
+    :height: 600px
+
+    import cadquery as cq
+
+    result = (
+        cq.Workplane()
+        .box(5, 5, 1)
+        .faces(">Z")
+        .workplane()
+        .rarray(2, 2, 2, 2)
+        .rect(1.5, 1.5)
+        .extrude(0.5)
+        .faces(">Z")
+        .sketch()
+        .circle(0.4)
+        .wires()
+        .distribute(6)
+        .circle(0.1, mode="a")
+        .clean()
+        .finalize()
+        .cutBlind(-0.5, taper=10)
+    )
+
+Lofting between two sketches
+============================
+
+Two sketches on different workplanes are needed when using :meth:`~cadquery.Workplane.loft`.
+
+.. cadquery::
+    :height: 600px
+
+    from cadquery import Workplane, Sketch, Vector, Location
+
+    s1 = Sketch().trapezoid(3, 1, 110).vertices().fillet(0.2)
+
+    s2 = Sketch().rect(2, 1).vertices().fillet(0.2)
+
+    result = Workplane().placeSketch(s1, s2.moved(z=3)).loft()
+
+When lofting only outer wires are taken into account and inner wires are silently ignored. Note that only sketches on the top of stack are considered for the current operation (i.e. there are no pending sketches), so when lofting or sweeping all relevant sketches have to be added in one `placeSketch` call.
+
+
+Combining sketches
+==================
+
+Sketches can be combined using :meth:`~cadquery.Sketch.face`.
+
+.. cadquery::
+   :height: 600px
+
+   import cadquery as cq
+
+   s1 = cq.Sketch().rect(2, 2)
+   s2 = cq.Sketch().circle(0.5)
+
+   result = s1.face(s2, mode='s')
+
+
+It is also possible to use boolean operations to achieve the same effect.
+
+.. cadquery::
+   :height: 600px
+
+   import cadquery as cq
+
+   s1 = cq.Sketch().rect(2, 2).vertices().fillet(0.25).reset()
+   s2 = cq.Sketch().rect(1, 1, angle=45).vertices().chamfer(0.1).reset()
+
+   result = s1 - s2
+
+Boolean operations are selection sensitive, so in this example
+:meth:`~cadquery.Sketch.reset` call is needed.
+
+Offsets made easy
+=================
+
+Conveniently, it is possible to reuse a sketch to create an :meth:`~cadquery.Sketch.offset` shape.
+
+.. cadquery::
+   :height: 600px
+
+   import cadquery as cq
+
+   sketch  = (cq.Sketch()
+   .rect(1.0, 4.0)
+   .circle(1.0)
+   .clean()
+   )
+
+   sketch_offset = sketch.copy().wires().offset(0.25)
+
+   result = cq.Workplane("front").placeSketch(sketch_offset).extrude(1.0)
+   result = result.faces(">Z").workplane().placeSketch(sketch).cutBlind(-0.50)
+
+
+It is obviously possible to use negative offsets, but it requires being more careful with the mode
+of the offset operation. Usually one wants to replace the original face, hence ``mode='r'``.
+
+.. cadquery::
+   :height: 600px
+
+   import cadquery as cq
+
+   sketch  = (cq.Sketch()
+   .rect(1.0, 4.0)
+   .circle(1.0)
+   .clean()
+   )
+
+   sketch_offset = sketch.copy().wires().offset(-0.25, mode='r')
+
+   result = cq.Workplane("front").placeSketch(sketch).extrude(1.0)
+   result = result.faces(">Z").workplane().placeSketch(sketch_offset).cutBlind(-0.50)
+
+
+Exporting and importing
+=======================
+
+It is possible to export sketches using :meth:`~cadquery.Sketch.export`.
+See :ref:`importexport` for more details.
+Importing of DXF files is supported as well using :meth:`~cadquery.Sketch.importDXF`.

server/docs/reference/workplane.rst

@@ -0,0 +1,557 @@
+
+Workplane
+=========
+
+Most CAD programs use the concept of Workplanes. If you have experience with other CAD programs you will probably
+feel comfortable with CadQuery's Workplanes, but if you don't have experience then they are an essential concept to
+understand.
+
+Workplanes represent a plane in space, from which other features can be located. They have a center point and a local
+coordinate system. Most methods that create an object do so relative to the current workplane.
+
+Usually the first workplane created is the "XY" plane, also known as the "front" plane. Once a solid is defined the most
+common way to create a workplane is to select a face on the solid that you intend to modify and create a new workplane
+relative to it. You can also create new workplanes anywhere in the world coordinate system, or relative to other planes
+using offsets or rotations.
+
+The most powerful feature of workplanes is that they allow you to work in 2D space in the coordinate system of the
+workplane, and then CadQuery will transform these points from the workplane coordinate system to the world coordinate
+system so your 3D features are located where you intended. This makes scripts much easier to create and maintain.
+
+See :py:class:`cadquery.Workplane` to learn more.
+
+
+2D Construction
+---------------------------
+
+Once you create a workplane, you can work in 2D, and then later use the features you create to make 3D objects.
+You'll find all of the 2D constructs you expect -- circles, lines, arcs, mirroring, points, etc.
+
+See :ref:`2dOperations` to learn more.
+
+
+3D Construction
+---------------------------
+
+You can construct 3D primitives such as boxes, wedges, cylinders and spheres directly. You can also sweep, extrude,
+and loft 2D geometry to form 3D features.  Of course the basic primitive operations are also available.
+
+See :ref:`3doperations` to learn more.
+
+
+
+Selectors
+---------------------------
+
+Selectors allow you to select one or more features, in order to define new features.  As an example, you might
+extrude a box, and then select the top face as the location for a new feature.  Or, you might extrude a box, and
+then select all of the vertical edges so that you can apply a fillet to them.
+
+You can select Vertices, Edges, Faces, Solids, and Wires using selectors.
+
+Think of selectors as the equivalent of your hand and mouse, if you were to build an object using a conventional CAD system.
+
+See :ref:`selectors` to learn more.
+
+
+Construction Geometry
+---------------------------
+Construction geometry are features that are not part of the object, but are only defined to aid in building the object.
+A common example might be to define a rectangle, and then use the corners to define the location of a set of holes.
+
+Most CadQuery construction methods provide a ``forConstruction`` keyword, which creates a feature that will only be used
+to locate other features.
+
+
+The Stack
+---------------------------
+
+As you work in CadQuery, each operation returns a new Workplane object with the result of that
+operation. Each Workplane object has a list of objects, and a reference to its parent.
+
+You can always go backwards to older operations by removing the current object from the stack.  For example::
+
+    Workplane(someObject).faces(">Z").first().vertices()
+
+returns a CadQuery object that contains all of the vertices on the highest face of someObject. But you can always move
+backwards in the stack to get the face as well::
+
+    Workplane(someObject).faces(">Z").first().vertices().end()
+
+You can browse stack access methods here: :ref:`stackMethods`.
+
+
+.. _chaining:
+
+Chaining
+---------------------------
+
+All Workplane methods return another Workplane object, so that you can chain the methods together
+fluently. Use the core Workplane methods to get at the objects that were created.
+
+Each time a new Workplane object is produced during these chained calls, it has a
+:attr:`~cadquery.Workplane.parent` attribute that points to the Workplane object that created it.
+Several CadQuery methods search this parent chain, for example when searching for the context solid.
+You can also give a Workplane object a tag, and further down your chain of calls you can refer back
+to this particular object using its tag.
+
+
+The Context Solid
+---------------------------
+
+Most of the time, you are building a single object, and adding features to that single object.  CadQuery watches
+your operations, and defines the first solid object created as the 'context solid'.  After that, any features
+you create are automatically combined (unless you specify otherwise) with that solid.  This happens even if the
+solid was created a long way up in the stack.  For example::
+
+    Workplane("XY").box(1, 2, 3).faces(">Z").circle(0.25).extrude(1)
+
+Will create a 1x2x3 box, with a cylindrical boss extending from the top face.  It was not necessary to manually
+combine the cylinder created by extruding the circle with the box, because the default behavior for extrude is
+to combine the result with the context solid. The :meth:`~cadquery.Workplane.hole` method works similarly -- CadQuery presumes that you want
+to subtract the hole from the context solid.
+
+If you want to avoid this, you can specify ``combine=False``, and CadQuery will create the solid separately.
+
+
+Iteration
+---------------------------
+
+CAD models often have repeated geometry, and it's really annoying to resort to for loops to construct features.
+Many CadQuery methods operate automatically on each element on the stack, so that you don't have to write loops.
+For example, this::
+
+    Workplane("XY").box(1, 2, 3).faces(">Z").vertices().circle(0.5)
+
+Will actually create 4 circles, because ``vertices()`` selects 4 vertices of a rectangular face, and the ``circle()`` method
+iterates on each member of the stack.
+
+This is really useful to remember when you author your own plugins. :py:meth:`cadquery.Workplane.each` is useful for this purpose.
+
+
+An Introspective Example
+------------------------
+
+.. note::
+    If you are just beginning with CadQuery then you can leave this example for later.  If you have
+    some experience with creating CadQuery models and now you want to read the CadQuery source to
+    better understand what your code does, then it is recommended you read this example first.
+
+To demonstrate the above concepts, we can define a more detailed string representations for the
+:class:`~cadquery.Workplane`, :class:`~cadquery.Plane` and :class:`~cadquery.CQContext` classes and
+patch them in::
+
+    import cadquery as cq
+
+
+    def tidy_repr(obj):
+        """Shortens a default repr string"""
+        return repr(obj).split(".")[-1].rstrip(">")
+
+
+    def _ctx_str(self):
+        return (
+            tidy_repr(self)
+            + ":\n"
+            + f"    pendingWires: {self.pendingWires}\n"
+            + f"    pendingEdges: {self.pendingEdges}\n"
+            + f"    tags: {self.tags}"
+        )
+
+
+    cq.cq.CQContext.__str__ = _ctx_str
+
+
+    def _plane_str(self):
+        return (
+            tidy_repr(self)
+            + ":\n"
+            + f"    origin: {self.origin.toTuple()}\n"
+            + f"    z direction: {self.zDir.toTuple()}"
+        )
+
+
+    cq.occ_impl.geom.Plane.__str__ = _plane_str
+
+
+    def _wp_str(self):
+        out = tidy_repr(self) + ":\n"
+        out += f"  parent: {tidy_repr(self.parent)}\n" if self.parent else "  no parent\n"
+        out += f"  plane: {self.plane}\n"
+        out += f"  objects: {self.objects}\n"
+        out += f"  modelling context: {self.ctx}"
+        return out
+
+
+    cq.Workplane.__str__ = _wp_str
+
+Now we can make a simple part and examine the :class:`~cadquery.Workplane` and
+:class:`~cadquery.cq.CQContext` objects at each step. The final part looks like:
+
+.. cadquery::
+    :select: part
+
+    part = (
+        cq.Workplane()
+        .box(1, 1, 1)
+        .tag("base")
+        .wires(">Z")
+        .toPending()
+        .translate((0.1, 0.1, 1.0))
+        .toPending()
+        .loft()
+        .faces(">>X", tag="base")
+        .workplane(centerOption="CenterOfMass")
+        .circle(0.2)
+        .extrude(1)
+    )
+
+.. note::
+    Some of the modelling process for this part is a bit contrived and not a great example of fluent
+    CadQuery techniques.
+
+The start of our chain of calls is::
+
+    part = cq.Workplane()
+    print(part)
+
+Which produces the output:
+
+.. code-block:: none
+
+    Workplane object at 0x2760:
+      no parent
+      plane: Plane object at 0x2850:
+        origin: (0.0, 0.0, 0.0)
+        z direction: (0.0, 0.0, 1.0)
+      objects: []
+      modelling context: CQContext object at 0x2730:
+        pendingWires: []
+        pendingEdges: []
+        tags: {}
+
+This is simply an empty :class:`~cadquery.Workplane`. Being the first :class:`~cadquery.Workplane`
+in the chain, it does not have a parent. The :attr:`~cadquery.Workplane.plane` attribute contains a
+:class:`~cadquery.Plane` object that describes the XY plane.
+
+Now we create a simple box. To keep things short, the ``print(part)`` line will not be shown for the
+rest of these code blocks::
+
+    part = part.box(1, 1, 1)
+
+Which produces the output:
+
+.. code-block:: none
+
+    Workplane object at 0xaa90:
+      parent: Workplane object at 0x2760
+      plane: Plane object at 0x3850:
+        origin: (0.0, 0.0, 0.0)
+        z direction: (0.0, 0.0, 1.0)
+      objects: [<cadquery.occ_impl.shapes.Solid object at 0xbbe0>]
+      modelling context: CQContext object at 0x2730:
+        pendingWires: []
+        pendingEdges: []
+        tags: {}
+
+The first thing to note is that this is a different :class:`~cadquery.Workplane` object to the
+previous one, and in the :attr:`~cadquery.Workplane.parent` attribute of this
+:class:`~cadquery.Workplane` is our previous :class:`~cadquery.Workplane`. Returning a new instance
+of :class:`~cadquery.Workplane` is the normal behaviour of most :class:`~cadquery.Workplane` methods
+(with some exceptions, as will be shown below) and this is how the `chaining`_ concept is
+implemented.
+
+Secondly, the modelling context object is the same as the one in the previous
+:class:`~cadquery.Workplane`, and this one modelling context at ``0x2730`` will be shared between
+every :class:`Workplane` object in this chain. If we instantiate a new :class:`~cadquery.Workplane`
+with ``part2 = cq.Workplane()``, then this ``part2`` would have a different instance of the
+:class:`~cadquery.cq.CQContext` attached to it.
+
+Thirdly, in our objects list is a single :class:`~cadquery.Solid` object, which is the box we just
+created.
+
+Often when creating models you will find yourself wanting to refer back to a specific
+:class:`~cadquery.Workplane` object, perhaps because it is easier to select the feature you want in this
+earlier state, or because you want to reuse a plane. Tags offer a way to refer back to a previous
+:class:`~cadquery.Workplane`. We can tag the :class:`~cadquery.Workplane` that contains this basic box now::
+
+    part = part.tag("base")
+
+The string representation of ``part`` is now:
+
+.. code-block:: none
+
+    Workplane object at 0xaa90:
+      parent: Workplane object at 0x2760
+      plane: Plane object at 0x3850:
+        origin: (0.0, 0.0, 0.0)
+        z direction: (0.0, 0.0, 1.0)
+      objects: [<cadquery.occ_impl.shapes.Solid object at 0xbbe0>]
+      modelling context: CQContext object at 0x2730:
+        pendingWires: []
+        pendingEdges: []
+        tags: {'base': <cadquery.cq.Workplane object at 0xaa90>}
+
+The :attr:`~cadquery.cq.CQContext.tags` attribute of the modelling context is simply a dict
+associating the string name given by the :meth:`~cadquery.Workplane.tag` method to the
+:class:`~cadquery.Workplane`. Methods such as :meth:`~cadquery.Workplane.workplaneFromTagged` and
+selection methods like :meth:`~cadquery.Workplane.edges` can operate on a tagged
+:class:`~cadquery.Workplane`. Note that unlike the ``part = part.box(1, 1, 1)`` step where we went
+from ``Workplane object at 0x2760`` to ``Workplane object at 0xaa90``, the
+:meth:`~cadquery.Workplane.tag` method has returned the same object at ``0xaa90``. This is unusual
+for a :class:`~cadquery.Workplane` method.
+
+The next step is::
+
+    part = part.faces(">>Z")
+
+The output is:
+
+.. code-block:: none
+
+    Workplane object at 0x8c40:
+      parent: Workplane object at 0xaa90
+      plane: Plane object at 0xac40:
+        origin: (0.0, 0.0, 0.0)
+        z direction: (0.0, 0.0, 1.0)
+      objects: [<cadquery.occ_impl.shapes.Face object at 0x3c10>]
+      modelling context: CQContext object at 0x2730:
+        pendingWires: []
+        pendingEdges: []
+        tags: {'base': <cadquery.cq.Workplane object at 0xaa90>}
+
+Our selection method has taken the :class:`~cadquery.Solid` from the
+:attr:`~cadquery.Workplane.objects` list of the previous :class:`~cadquery.Workplane`, found the
+face with its center furthest in the Z direction, and placed that face into the
+:attr:`~cadquery.Workplane.objects` attribute. The :class:`~cadquery.Solid` representing the box we
+are modelling is gone, and when a :class:`~cadquery.Workplane` method needs to access that solid it
+searches through the parent chain for the nearest solid. This action can also be done by a user
+through the :meth:`~cadquery.Workplane.findSolid` method.
+
+Now we want to select the boundary of this :class:`~cadquery.Face` (a :class:`~cadquery.Wire`), so
+we use::
+
+    part = part.wires()
+
+The output is now:
+
+.. code-block:: none
+
+    Workplane object at 0x6880:
+      parent: Workplane object at 0x8c40
+      plane: Plane object at 0x38b0:
+        origin: (0.0, 0.0, 0.0)
+        z direction: (0.0, 0.0, 1.0)
+      objects: [<cadquery.occ_impl.shapes.Wire object at 0xaca0>]
+      modelling context: CQContext object at 0x2730:
+        pendingWires: []
+        pendingEdges: []
+        tags: {'base': <cadquery.cq.Workplane object at 0xaa90>}
+
+Modelling operations take their wires and edges from the modelling context's pending lists. In order
+to use the :meth:`~cadquery.Workplane.loft` command further down the chain, we need to push this wire
+to the modelling context with::
+
+    part = part.toPending()
+
+Now we have:
+
+.. code-block:: none
+
+    Workplane object at 0x6880:
+      parent: Workplane object at 0x8c40
+      plane: Plane object at 0x38b0:
+        origin: (0.0, 0.0, 0.0)
+        z direction: (0.0, 0.0, 1.0)
+      objects: [<cadquery.occ_impl.shapes.Wire object at 0xaca0>]
+      modelling context: CQContext object at 0x2730:
+        pendingWires: [<cadquery.occ_impl.shapes.Wire object at 0xaca0>]
+        pendingEdges: []
+        tags: {'base': <cadquery.cq.Workplane object at 0xaa90>}
+
+The :class:`~cadquery.Wire` object that was only in the :attr:`~cadquery.Workplane.objects`
+attribute before is now also in the modelling context's :attr:`~cadquery.cq.CQContext.pendingWires`.
+The :meth:`~cadquery.Workplane.toPending` method is also another of the unusual methods that return
+the same :class:`~cadquery.Workplane` object instead of a new one.
+
+To set up the other side of the :meth:`~cadquery.Workplane.loft` command further down the chain, we
+translate the wire in :attr:`~cadquery.Workplane.objects` by calling::
+
+    part = part.translate((0.1, 0.1, 1.0))
+
+Now the string representation of ``part`` looks like:
+
+.. code-block:: none
+
+    Workplane object at 0x3a00:
+      parent: Workplane object at 0x6880
+      plane: Plane object at 0xac70:
+        origin: (0.0, 0.0, 0.0)
+        z direction: (0.0, 0.0, 1.0)
+      objects: [<cadquery.occ_impl.shapes.Wire object at 0x35e0>]
+      modelling context: CQContext object at 0x2730:
+        pendingWires: [<cadquery.occ_impl.shapes.Wire object at 0xaca0>]
+        pendingEdges: []
+        tags: {'base': <cadquery.cq.Workplane object at 0xaa90>}
+
+It may look similar to the previous step, but the :class:`~cadquery.Wire` object in
+:attr:`~cadquery.Workplane.objects` is different. To get this wire into the pending wires list,
+again we use::
+
+    part = part.toPending()
+
+The result:
+
+.. code-block:: none
+
+    Workplane object at 0x3a00:
+      parent: Workplane object at 0x6880
+      plane: Plane object at 0xac70:
+        origin: (0.0, 0.0, 0.0)
+        z direction: (0.0, 0.0, 1.0)
+      objects: [<cadquery.occ_impl.shapes.Wire object at 0x35e0>]
+      modelling context: CQContext object at 0x2730:
+        pendingWires: [<cadquery.occ_impl.shapes.Wire object at 0xaca0>, <cadquery.occ_impl.shapes.Wire object at 0x7f5c7f5c35e0>]
+        pendingEdges: []
+        tags: {'base': <cadquery.cq.Workplane object at 0xaa90>}
+
+The modelling context's :attr:`~cadquery.cq.CQContext.pendingWires` attribute now contains the two
+wires we want to loft between, and we simply call::
+
+    part = part.loft()
+
+After the loft operation, our Workplane looks quite different:
+
+.. code-block:: none
+
+    Workplane object at 0x32b0:
+      parent: Workplane object at 0x3a00
+      plane: Plane object at 0x3d60:
+        origin: (0.0, 0.0, 0.0)
+        z direction: (0.0, 0.0, 1.0)
+      objects: [<cadquery.occ_impl.shapes.Compound object at 0xad30>]
+      modelling context: CQContext object at 0x2730:
+        pendingWires: []
+        pendingEdges: []
+        tags: {'base': <cadquery.cq.Workplane object at 0xaa90>}
+
+In the :attr:`cq.Workplane.objects` attribute we now have one :class:`~cadquery.Compound` object and the modelling
+context's :attr:`~cadquery.cq.CQContext.pendingWires` has been cleared by
+:meth:`~cadquery.Workplane.loft`.
+
+.. note::
+    To inspect the :class:`~cadquery.Compound` object further you can use
+    :meth:`~cadquery.Workplane.val` or :meth:`~cadquery.Workplane.findSolid` to get at the
+    :class:`~cadquery.Compound` object, then use :meth:`cadquery.Shape.Solids` to return a list
+    of the :class:`~cadquery.Solid` objects contained in the :class:`~cadquery.Compound`, which in
+    this example will be a single :class:`~cadquery.Solid` object. For example:
+
+.. code-block:: pycon
+
+    >>> a_compound = part.findSolid()
+    >>> a_list_of_solids = a_compound.Solids()
+    >>> len(a_list_of_solids)
+    1
+
+Now we will create a small cylinder protruding from a face on the original box. We need to set up a
+workplane to draw a circle on, so firstly we will select the correct face::
+
+    part = part.faces(">>X", tag="base")
+
+Which results in:
+
+.. code-block:: none
+
+    Workplane object at 0x3f10:
+      parent: Workplane object at 0x32b0
+      plane: Plane object at 0xefa0:
+        origin: (0.0, 0.0, 0.0)
+        z direction: (0.0, 0.0, 1.0)
+      objects: [<cadquery.occ_impl.shapes.Face object at 0x3af0>]
+      modelling context: CQContext object at 0x2730:
+        pendingWires: []
+        pendingEdges: []
+        tags: {'base': <cadquery.cq.Workplane object at 0xaa90>}
+
+We have the desired :class:`~cadquery.Face` in the :attr:`~cadquery.Workplane.objects` attribute,
+but the :attr:`~cadquery.Workplane.plane` has not changed yet. To create the new plane we use the
+:meth:`Workplane.workplane` method::
+
+    part = part.workplane()
+
+Now:
+
+.. code-block:: none
+
+    Workplane object at 0xe700:
+      parent: Workplane object at 0x3f10
+      plane: Plane object at 0xe730:
+        origin: (0.5, 0.0, 0.0)
+        z direction: (1.0, 0.0, 0.0)
+      objects: []
+      modelling context: CQContext object at 0x2730:
+        pendingWires: []
+        pendingEdges: []
+        tags: {'base': <cadquery.cq.Workplane object at 0xaa90>}
+
+The :attr:`~cadquery.Workplane.objects` list has been cleared and the :class:`~cadquery.Plane`
+object has a local Z direction in the global X direction. Since the base of the plane is the side of
+the box, the origin is offset in the X direction.
+
+Onto this plane we can draw a circle::
+
+    part = part.circle(0.2)
+
+Now:
+
+.. code-block:: none
+
+    Workplane object at 0xe790:
+      parent: Workplane object at 0xe700
+      plane: Plane object at 0xaf40:
+        origin: (0.5, 0.0, 0.0)
+        z direction: (1.0, 0.0, 0.0)
+      objects: [<cadquery.occ_impl.shapes.Wire object at 0xe610>]
+      modelling context: CQContext object at 0x2730:
+        pendingWires: [<cadquery.occ_impl.shapes.Wire object at 0xe610>]
+        pendingEdges: []
+        tags: {'base': <cadquery.cq.Workplane object at 0xaa90>}
+
+The :meth:`~cadquery.Workplane.circle` method - like all 2D drawing methods - has placed the circle
+into both the :attr:`~cadquery.Workplane.objects` attribute (where it will be cleared during the
+next modelling step), and the modelling context's pending wires (where it will persist until used by
+another :class:`~cadquery.Workplane` method).
+
+The next step is to extrude this circle and create a cylindrical protrusion::
+
+    part = part.extrude(1, clean=False)
+
+Now:
+
+.. code-block:: none
+
+    Workplane object at 0xafd0:
+      parent: Workplane object at 0xe790
+      plane: Plane object at 0x3e80:
+        origin: (0.5, 0.0, 0.0)
+        z direction: (1.0, 0.0, 0.0)
+      objects: [<cadquery.occ_impl.shapes.Compound object at 0xaaf0>]
+      modelling context: CQContext object at 0x2730:
+        pendingWires: []
+        pendingEdges: []
+        tags: {'base': <cadquery.cq.Workplane object at 0xaa90>}
+
+The :meth:`~cadquery.Workplane.extrude` method has cleared all the pending wires and edges. The
+:attr:`~cadquery.Workplane.objects` attribute contains the final :class:`~cadquery.Compound` object
+that is shown in the 3D view above.
+
+
+.. note::
+  The :meth:`~cadquery.Workplane.extrude` has an argument for ``clean`` which defaults to ``True``.
+  This extrudes the pending wires (creating a new :class:`~cadquery.Workplane` object), then runs
+  the :meth:`~cadquery.Workplane.clean` method to refine the result, creating another
+  :class:`~cadquery.Workplane`. If you were to run the example with the default
+  ``clean=True`` then you would see an intermediate
+  :class:`~cadquery.Workplane` object in :attr:`~cadquery.Workplane.parent`
+  rather than the object from the previous step.
+

server/docs/skill.md

@@ -0,0 +1,264 @@
+# CadQuery LLM Skill
+
+This skill helps LLMs write correct, idiomatic CadQuery code.
+Load this file before any CadQuery task. For deeper reference, read the files listed at the bottom.
+
+---
+
+## Two APIs — Know Which One You're Using
+
+CadQuery provides two distinct APIs. Always identify which is appropriate before writing code.
+
+### Fluent (Workplane) API
+```python
+import cadquery as cq
+result = cq.Workplane("XY").box(10, 10, 10).faces(">Z").hole(3)
+```
+- Chains operations on a `Workplane` object with hidden state (current plane, stack)
+- Best for: parts built up from sketches and feature operations (extrude, hole, fillet, shell)
+- Most tutorials and examples use this style
+
+### Free Function API
+```python
+from cadquery.func import *
+b = box(10, 10, 10)
+result = b - cylinder(1.5, 10)
+```
+- No hidden state — all operations are explicit free functions
+- Selectors still work as methods on Shape objects
+- Boolean ops available as operators: `+` (union), `-` (cut), `*` (intersect), `/` (split)
+- Best for: complex face-by-face construction, lofted/swept surfaces, avoiding booleans via `addHole()`/`replace()`, parametric surface mapping
+- More verbose but more explicit and composable
+
+**Do not mix the two styles in the same script** unless you explicitly convert between them.
+When the task involves building shapes face-by-face, lofting between non-planar edges, or
+trimming surfaces in parametric space — prefer the Free Function API.
+
+---
+
+## The Core Mindset: BRep, Not CSG
+
+CadQuery uses **Boundary Representation (BRep)**: a model is defined by its surfaces, edges, and vertices — not by Boolean operations on primitives.
+
+The CSG reflex (union/cut everything) produces brittle, unidiomatic code. The BRep reflex asks:
+- What faces, edges, or vertices already exist on this shape?
+- Can I select them and build from there?
+- Does a workplane operation (extrude, shell, fillet, chamfer) get me there without a Boolean?
+
+**Wrong reflex (CSG):**
+```python
+result = base.union(cq.Workplane().box(10, 10, 5).translate((0, 0, 10)))
+```
+
+**Right reflex (BRep):**
+```python
+result = base.faces(">Z").workplane().rect(10, 10).extrude(5)
+```
+
+Only reach for `.union()`, `.cut()`, or `.intersect()` when you genuinely need to combine separate solids.
+
+---
+
+## Workplanes
+
+A workplane is a local 2D coordinate system. Most geometry is created relative to it.
+
+```python
+import cadquery as cq
+
+# Start on XY plane at origin
+wp = cq.Workplane("XY")
+
+# Build a solid to work from
+cube = cq.Workplane("XY").box(10, 10, 10)
+
+# Move to a face
+wp2 = cube.faces(">Z").workplane()
+
+# Offset from a face
+wp3 = cube.faces(">Z").workplane(offset=5)
+
+# Arbitrary origin and normal — must use cq.Plane, not keyword args on Workplane
+wp4 = cq.Workplane(cq.Plane(origin=(0, 0, 10), normal=(0, 1, 0)))
+
+# Move with transformation (rotate is degrees around local X, Y, Z)
+wp5 = cube.faces(">Z").workplane().transformed(offset=(1, 2, 3), rotate=(0, 0, 45))
+```
+
+**Rules:**
+- `.workplane()` resets the 2D origin to the center of the selected face/edge by default.
+- `centerOption` controls what "center" means — the default `"ProjectedOrigin"` projects the parent workplane origin onto the new face, which is often not the face center. Always set it explicitly when position matters.
+- After `.workplane()`, coordinates are **local** to that plane, not global.
+- `.transformed()` is cumulative within the current workplane context.
+
+---
+
+## Selectors — Cheat Sheet
+
+Selectors filter faces, edges, wires, or vertices from the current stack.
+
+| Selector | Meaning |
+|----------|---------|
+| `">Z"` | Face/edge with highest Z centroid |
+| `"<Z"` | Face/edge with lowest Z centroid |
+| `"\|X"` | Faces whose normal is parallel to X axis |
+| `"#Z"` | Faces/edges whose normal or direction is orthogonal to Z |
+| `"+Z"` | Faces whose normal points in +Z direction |
+| `">>Z[1]"` | Second item when sorted ascending by Z (0-indexed) |
+| `"<<Z[0]"` | First item when sorted descending by Z |
+| `"%Plane"` | Faces of type Plane (vs Cylinder, Cone, etc.) |
+| `"not >Z"` | Inverts the selector |
+| `">Z and \|X"` | Combines selectors (AND) |
+| `">Z or <Z"` | Combines selectors (OR) |
+
+**Tag-based selection (preferred for stability):**
+```python
+result = (
+    cq.Workplane("XY")
+    .box(10, 10, 10)
+    .faces(">Z").tag("top")
+    .end()
+    .faces(tag="top").workplane().hole(3)
+)
+```
+
+The code above demonstrates how to use tags, and is not a suggestion of the proper way to use them.
+In practices you would not call `end` and then query the tagged face immediately again.
+Use tags when the geometry might need to be referred to later, and may become hard to access.
+Tagging can be very useful, but do not force it in to the script unless it seems needed.
+
+---
+
+## Critical Anti-Patterns
+
+
+### 1. Boolean when a feature operation suffices
+| Instead of... | Use... |
+|--------------|--------|
+| `.cut(cylinder)` | `.faces(...).hole(d)` |
+| `.cut(shell_solid)` | `.shell(thickness)` |
+| `.union(chamfered_edge)` | `.edges(...).chamfer(d)` |
+
+### 2. workplane `centerOption` behaviors 
+By default, a `workplane()` call uses `ProjectedOrigin` as the default, which uses the current origin and projects it onto the plan defined by the selected faces.
+This usually works, but can cause unintended results sometimes.
+If the geometric center of the object is the indended center for the operation, it can sometimes be better to use `CenterOfBoundBox`, which uses the X, Y and Z centers of the object's bounding box.
+If the user mentions that the features added on the workplane are not in the expected position, one cause could be this `centerOption` parameter.
+```python
+# Explicit is always better
+cq.Workplane("XY").box(10, 10, 5).faces(">Z").workplane(centerOption="CenterOfBoundBox")
+```
+
+### 3. Selector ordering assumptions
+Selectors like `">>Z[1]"` depend on sort order across all matching entities. Adding fillets or other features changes the entity count and can shift indices. Prefer tags or geometric selectors (`">Z"`) over index-based ones.
+
+### 4. Unclosed wires
+When building profiles with `.lineTo()`, `.spline()`, etc., always call `.close()` before `.extrude()` or `.revolve()` unless the wire is intentionally open.
+
+### 5. Forgetting `.end()` after tagging or selector context
+After `.tag()` or navigating into a sub-context, use `.end()` to return to the solid before chaining further operations.
+
+### 6. `BREP_API command not done`
+This OpenCASCADE kernel error means the requested geometry is invalid. Common causes:
+- Fillet/chamfer radius larger than the shortest adjacent edge, or adjacent fillets overlapping — reduce the radius or fillet edge groups separately
+- Self-intersecting profile (wire crosses itself, revolve profile crosses the axis)
+- Sweep profile too large for the path curvature — the solid folds back on itself
+- Shell thickness larger than the local radius of curvature
+
+See `patterns/anti-patterns.md` #14 for detailed fixes.
+
+---
+
+## Free Function API — Quick Reference
+
+Import: `from cadquery.func import *`
+
+**Primitives:**
+```python
+box(w, h, d)
+cylinder(r, h)
+sphere(r)
+cone(r1, r2)
+plane(w, h)          # flat face
+circle(r)            # edge
+rect(w, h)           # edge
+segment((x1,y1,z1), (x2,y2,z2))
+```
+
+**Shape assembly:**
+```python
+wire(e1, e2, ...)         # edges → wire
+face(wire)                # closed wire → face
+solid(f1, f2, ...)        # faces → solid
+shell(f1, f2, ...)        # faces → shell (open solid)
+compound(s1, s2, ...)     # shapes → compound
+```
+
+**Operations:**
+```python
+extrude(profile, direction_vector)
+loft(e1, e2, e3, cap=False)
+sweep(profile, path)
+revolve(face, axis_point, axis_dir, angle)
+```
+
+**Placement (no workplane needed):**
+```python
+shape.moved(x=1, y=2, z=3)           # translate
+shape.moved(rx=90, ry=0, rz=45)      # rotate (degrees)
+shape.moved((1,0,0), (0,1,0))        # place at multiple locations → compound
+shape.move(z=5)                       # in-place variant
+```
+
+**Boolean operators:**
+```python
+a + b      # fuse / union
+a - b      # cut / difference
+a * b      # intersect
+a / plane  # split
+```
+
+**Adding features without booleans (preferred for performance):**
+```python
+top = solid.faces(">Z")
+inner = extrude(circle(r), (0, 0, h))
+top_with_hole = top.addHole(inner.edges("<Z"))
+result = solid(solid.remove(top).faces(), inner, top_with_hole)
+```
+
+**Selectors work the same way** — they are methods on Shape objects, not tied to either API.
+
+---
+
+## `.shell()` and Hollow Bodies
+
+Shell operates on the existing solid — select the face(s) to open, then shell:
+
+```python
+box = cq.Workplane("XY").box(20, 20, 20)
+hollow = box.faces(">Z").shell(-2)  # negative = inward
+```
+
+Common mistake: calling `.shell()` without first selecting which face to remove, resulting in a fully closed thin shell (usually not what you want).
+Shell can be a little buggy with certain profiles, as can offsetting.
+
+---
+
+## For Deeper Reference
+
+| Topic | File |
+|-------|------|
+| BRep vs CSG concepts | `concepts/brep-mindset.md` |
+| Workplane (fluent) API | `concepts/workplanes.md` |
+| Free Function API | `concepts/free-function-api.md` |
+| Full selector reference | `concepts/selectors.md` |
+| Idiomatic patterns | `patterns/common-patterns.md` |
+| Anti-patterns (extended) | `patterns/anti-patterns.md` |
+| Annotated examples | `examples/` |
+| CadQuery API reference | `docs/` |
+
+When working on a CadQuery task:
+1. Read this file first.
+2. If the task involves selectors, read `concepts/selectors.md`.
+3. Grep `examples/` for methods you're unsure about: `grep -rn "\.shell\(" examples/`
+4. Grep `docs/` for API signatures: `grep -n "def shell" docs/`

server/docs_search.py

@@ -0,0 +1,200 @@
+import logging
+import re
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+DOCS_ROOT = Path(__file__).parent / "docs"
+
+TOPIC_MAP: Dict[str, List[Path]] = {
+    "basics": [
+        DOCS_ROOT / "skill.md",
+        DOCS_ROOT / "reference" / "quickstart.rst",
+        DOCS_ROOT / "reference" / "primer.rst",
+    ],
+    "selectors": [
+        DOCS_ROOT / "concepts" / "selectors.md",
+        DOCS_ROOT / "reference" / "selectors.rst",
+    ],
+    "booleans": [
+        DOCS_ROOT / "concepts" / "brep-mindset.md",
+        DOCS_ROOT / "patterns" / "common-patterns.md",
+    ],
+    "transforms": [
+        DOCS_ROOT / "concepts" / "workplanes.md",
+        DOCS_ROOT / "reference" / "workplane.rst",
+    ],
+    "features": [
+        DOCS_ROOT / "patterns" / "common-patterns.md",
+        DOCS_ROOT / "patterns" / "anti-patterns.md",
+    ],
+    "sketch": [
+        DOCS_ROOT / "reference" / "sketch.rst",
+    ],
+    "advanced": [
+        DOCS_ROOT / "concepts" / "free-function-api.md",
+        DOCS_ROOT / "reference" / "free-func.rst",
+        DOCS_ROOT / "reference" / "extending.rst",
+    ],
+    "examples": [
+        DOCS_ROOT / "reference" / "examples.rst",
+    ],
+    "anti-patterns": [
+        DOCS_ROOT / "patterns" / "anti-patterns.md",
+    ],
+    "workplanes": [
+        DOCS_ROOT / "concepts" / "workplanes.md",
+    ],
+}
+
+
+def search_docs(
+    topic: Optional[str] = None,
+    query: Optional[str] = None,
+    context_lines: int = 5,
+    max_results: int = 10,
+    max_chars: int = 4000,
+) -> List[str]:
+    t0 = time.time()
+
+    if topic and topic in TOPIC_MAP:
+        files = TOPIC_MAP[topic]
+    elif topic:
+        files = _find_files_by_name(topic)
+    else:
+        files = []
+        for file_list in TOPIC_MAP.values():
+            files.extend(file_list)
+        files = list(set(files))
+
+    if not files:
+        return [f"No documentation found for topic: {topic}"]
+
+    if not query:
+        results = []
+        total_chars = 0
+        for fp in files:
+            if not fp.exists():
+                continue
+            content = fp.read_text(encoding="utf-8", errors="replace")
+            if total_chars + len(content) > max_chars:
+                remaining = max_chars - total_chars
+                if remaining > 200:
+                    results.append(f"=== {fp.name} (truncated) ===\n{content[:remaining]}...")
+                break
+            results.append(f"=== {fp.name} ===\n{content}")
+            total_chars += len(content)
+        elapsed = time.time() - t0
+        logger.info(f"search_docs(topic={topic}) returned {len(results)} files in {elapsed:.3f}s")
+        return results
+
+    results = _grep_search(files, query, context_lines, max_results)
+
+    if not results:
+        results = _fuzzy_search(files, query, context_lines, max_results)
+
+    total_chars = 0
+    trimmed = []
+    for r in results:
+        if total_chars + len(r) > max_chars:
+            remaining = max_chars - total_chars
+            if remaining > 100:
+                trimmed.append(r[:remaining] + "...")
+            break
+        trimmed.append(r)
+        total_chars += len(r)
+
+    elapsed = time.time() - t0
+    logger.info(f"search_docs(topic={topic}, query={query}) returned {len(trimmed)} results in {elapsed:.3f}s")
+
+    if not trimmed:
+        return [f"No results found for query: {query}"]
+    return trimmed
+
+
+def _find_files_by_name(name: str) -> List[Path]:
+    results = []
+    for fp in DOCS_ROOT.rglob("*"):
+        if fp.is_file() and name.lower() in fp.stem.lower():
+            results.append(fp)
+    return results
+
+
+def _grep_search(
+    files: List[Path],
+    query: str,
+    context_lines: int = 5,
+    max_results: int = 10,
+) -> List[str]:
+    results = []
+    keywords = query.lower().split()
+
+    for fp in files:
+        if not fp.exists():
+            continue
+        try:
+            lines = fp.read_text(encoding="utf-8", errors="replace").splitlines()
+        except Exception:
+            continue
+
+        for i, line in enumerate(lines):
+            line_lower = line.lower()
+            if any(kw in line_lower for kw in keywords):
+                start = max(0, i - context_lines)
+                end = min(len(lines), i + context_lines + 1)
+                snippet = "\n".join(lines[start:end])
+                results.append(f"--- {fp.name}:{i+1} ---\n{snippet}")
+
+                if len(results) >= max_results:
+                    return results
+
+    return results
+
+
+def _fuzzy_search(
+    files: List[Path],
+    query: str,
+    context_lines: int = 5,
+    max_results: int = 5,
+) -> List[str]:
+    results = []
+    keywords = query.lower().split()
+
+    for fp in files:
+        if not fp.exists():
+            continue
+        try:
+            content = fp.read_text(encoding="utf-8", errors="replace")
+        except Exception:
+            continue
+
+        paragraphs = re.split(r"\n\s*\n", content)
+
+        scored = []
+        for para in paragraphs:
+            para_lower = para.lower()
+            score = sum(1 for kw in keywords if kw in para_lower)
+            if score > 0:
+                scored.append((score, para, fp.name))
+
+        scored.sort(key=lambda x: x[0], reverse=True)
+
+        for score, para, fname in scored[:max_results]:
+            results.append(f"--- {fname} (relevance: {score}/{len(keywords)}) ---\n{para.strip()}")
+            if len(results) >= max_results:
+                return results
+
+    return results
+
+
+def get_system_prompt() -> str:
+    skill_path = DOCS_ROOT / "skill.md"
+    if skill_path.exists():
+        return skill_path.read_text(encoding="utf-8", errors="replace")
+    return ""
+
+
+def list_topics() -> List[str]:
+    return list(TOPIC_MAP.keys())

server/executor.py

@@ -0,0 +1,183 @@
+import json
+import logging
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+RUNNER_SCRIPT = '''
+import sys
+import json
+import traceback
+
+try:
+    import cadquery as cq
+    code = sys.stdin.read()
+    local_ns = {"cq": cq, "cadquery": cq}
+
+    try:
+        import math
+        local_ns["math"] = math
+    except Exception:
+        pass
+
+    exec(code, local_ns)
+
+    if "result" not in local_ns:
+        print(json.dumps({"success": False, "error": "No variable named 'result' was defined"}))
+        sys.exit(0)
+
+    result = local_ns["result"]
+
+    if hasattr(result, "val"):
+        shape = result.val()
+    else:
+        shape = result
+
+    bb = shape.BoundingBox()
+    volume = shape.Volume()
+    is_valid = shape.isValid()
+
+    faces = shape.Faces()
+    face_types = [f.geomType() for f in faces]
+
+    from collections import Counter
+    type_counts = dict(Counter(face_types))
+    total_faces = len(face_types)
+    dominant = max(type_counts, key=type_counts.get) if type_counts else "UNKNOWN"
+
+    edges = shape.Edges()
+    vertices = shape.Vertices()
+
+    dims = [bb.xlen, bb.ylen, bb.zlen]
+    sorted_axes = sorted(zip(["X", "Y", "Z"], dims), key=lambda x: x[1], reverse=True)
+    longest_axis = sorted_axes[0][0]
+    max_dim = max(dims) if max(dims) > 0 else 1.0
+
+    shells = shape.Shells()
+    is_watertight = True
+    if not shells:
+        is_watertight = False
+    else:
+        for s in shells:
+            if not s.Closed():
+                is_watertight = False
+                break
+
+    V = len(vertices)
+    E = len(edges)
+    F = total_faces
+
+    output = {
+        "success": True,
+        "properties": {
+            "is_valid": is_valid,
+            "is_watertight": is_watertight,
+            "volume_mm3": round(volume, 4),
+            "surface_area_mm2": round(shape.Area(), 4),
+            "bbox_x_mm": round(bb.xlen, 4),
+            "bbox_y_mm": round(bb.ylen, 4),
+            "bbox_z_mm": round(bb.zlen, 4),
+            "bbox_longest_axis": longest_axis,
+            "bbox_ratio_yx": round(sorted_axes[1][1] / max_dim, 4),
+            "bbox_ratio_zx": round(sorted_axes[2][1] / max_dim, 4),
+            "face_count": total_faces,
+            "face_type_counts": type_counts,
+            "dominant_face_type": dominant,
+            "face_type_distribution": {k: round(v / total_faces, 4) for k, v in type_counts.items()} if total_faces > 0 else {},
+            "edge_count": E,
+            "vertex_count": V,
+            "euler_characteristic": V - E + F,
+        }
+    }
+    print(json.dumps(output))
+
+except Exception as e:
+    tb = traceback.format_exc()
+    print(json.dumps({"success": False, "error": str(e), "traceback": tb}))
+'''
+
+
+def execute_cadquery_code(
+    code: str,
+    timeout: float = 10.0,
+    python_path: Optional[str] = None,
+) -> Dict[str, Any]:
+    t0 = time.time()
+    if python_path is None:
+        python_path = sys.executable
+
+    logger.info(f"Executing CadQuery code ({len(code)} chars, timeout={timeout}s)")
+
+    try:
+        proc = subprocess.run(
+            [python_path, "-c", RUNNER_SCRIPT],
+            input=code,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+
+        elapsed = time.time() - t0
+        logger.info(f"Subprocess completed in {elapsed:.3f}s, returncode={proc.returncode}")
+
+        stdout = proc.stdout.strip()
+        stderr = proc.stderr.strip()
+
+        if proc.returncode != 0 and not stdout:
+            return {
+                "success": False,
+                "error": stderr or f"Process exited with code {proc.returncode}",
+                "properties": None,
+            }
+
+        if not stdout:
+            return {
+                "success": False,
+                "error": "No output from subprocess",
+                "properties": None,
+            }
+
+        result = json.loads(stdout)
+
+        if not result.get("success", False):
+            return {
+                "success": False,
+                "error": result.get("error", "Unknown error"),
+                "properties": None,
+            }
+
+        return {
+            "success": True,
+            "error": None,
+            "properties": result["properties"],
+        }
+
+    except subprocess.TimeoutExpired:
+        elapsed = time.time() - t0
+        logger.warning(f"CadQuery execution timed out after {elapsed:.3f}s")
+        return {
+            "success": False,
+            "error": f"Code execution timed out after {timeout} seconds",
+            "properties": None,
+        }
+    except json.JSONDecodeError as e:
+        elapsed = time.time() - t0
+        logger.error(f"Failed to parse subprocess output after {elapsed:.3f}s: {e}")
+        return {
+            "success": False,
+            "error": f"Failed to parse execution output: {e}",
+            "properties": None,
+        }
+    except Exception as e:
+        elapsed = time.time() - t0
+        logger.error(f"execute_cadquery_code failed after {elapsed:.3f}s: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "properties": None,
+        }

server/geometry.py

@@ -0,0 +1,206 @@
+import logging
+import time
+from collections import Counter
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def extract_properties(shape) -> Dict[str, Any]:
+    t0 = time.time()
+    try:
+        props = {}
+
+        bb = shape.BoundingBox()
+        dims = [bb.xlen, bb.ylen, bb.zlen]
+        sorted_axes = sorted(
+            zip(["X", "Y", "Z"], dims), key=lambda x: x[1], reverse=True
+        )
+        longest_axis = sorted_axes[0][0]
+
+        props["is_valid"] = shape.isValid()
+
+        volume = shape.Volume()
+        surface_area = shape.Area()
+        props["volume_mm3"] = round(volume, 4)
+        props["surface_area_mm2"] = round(surface_area, 4)
+
+        props["bbox_x_mm"] = round(bb.xlen, 4)
+        props["bbox_y_mm"] = round(bb.ylen, 4)
+        props["bbox_z_mm"] = round(bb.zlen, 4)
+        props["bbox_longest_axis"] = longest_axis
+
+        max_dim = max(dims)
+        props["bbox_ratio_yx"] = round(sorted_axes[1][1] / max_dim, 4) if max_dim > 0 else 0.0
+        props["bbox_ratio_zx"] = round(sorted_axes[2][1] / max_dim, 4) if max_dim > 0 else 0.0
+
+        faces = shape.Faces()
+        face_types = [f.geomType() for f in faces]
+        type_counts = dict(Counter(face_types))
+        total_faces = len(face_types)
+
+        props["face_count"] = total_faces
+        props["face_type_counts"] = type_counts
+        props["dominant_face_type"] = max(type_counts, key=type_counts.get) if type_counts else "UNKNOWN"
+        props["face_type_distribution"] = {
+            k: round(v / total_faces, 4) for k, v in type_counts.items()
+        } if total_faces > 0 else {}
+
+        props["edge_count"] = len(shape.Edges())
+        props["vertex_count"] = len(shape.Vertices())
+
+        V = props["vertex_count"]
+        E = props["edge_count"]
+        F = props["face_count"]
+        props["euler_characteristic"] = V - E + F
+
+        props["is_watertight"] = _check_watertight(shape)
+
+        xy_sym, xz_sym, yz_sym = _check_symmetry(shape, bb)
+        props["has_xy_symmetry"] = xy_sym
+        props["has_xz_symmetry"] = xz_sym
+        props["has_yz_symmetry"] = yz_sym
+
+        props["shape_class"] = _classify_shape(props)
+
+        elapsed = time.time() - t0
+        logger.info(f"extract_properties took {elapsed:.3f}s")
+        return props
+
+    except Exception as e:
+        elapsed = time.time() - t0
+        logger.error(f"extract_properties failed after {elapsed:.3f}s: {e}")
+        raise
+
+
+def _check_watertight(shape) -> bool:
+    try:
+        shells = shape.Shells()
+        if not shells:
+            return False
+        for shell in shells:
+            if not shell.Closed():
+                return False
+        return True
+    except Exception:
+        return False
+
+
+def _check_symmetry(shape, bb, n_sample: int = 200, tol_ratio: float = 0.05) -> Tuple[bool, bool, bool]:
+    try:
+        from OCP.BRepMesh import BRepMesh_IncrementalMesh
+        from OCP.BRep import BRep_Tool
+        from OCP.TopExp import TopExp_Explorer
+        from OCP.TopAbs import TopAbs_FACE
+        from OCP.TopLoc import TopLoc_Location
+        from OCP.TopoDS import TopoDS
+
+        mesh = BRepMesh_IncrementalMesh(shape.wrapped, 0.5, False, 0.5, True)
+        mesh.Perform()
+
+        points = []
+        explorer = TopExp_Explorer(shape.wrapped, TopAbs_FACE)
+        while explorer.More():
+            face = TopoDS.Face_s(explorer.Current())
+            loc = TopLoc_Location()
+            tri = BRep_Tool.Triangulation_s(face, loc)
+            if tri is not None:
+                for i in range(1, tri.NbNodes() + 1):
+                    p = tri.Node(i)
+                    trsf = loc.Transformation()
+                    p.Transform(trsf)
+                    points.append([p.X(), p.Y(), p.Z()])
+            explorer.Next()
+
+        if len(points) < 10:
+            return False, False, False
+
+        pts = np.array(points)
+        if len(pts) > n_sample:
+            idx = np.random.choice(len(pts), n_sample, replace=False)
+            pts = pts[idx]
+
+        diag = np.sqrt(bb.xlen**2 + bb.ylen**2 + bb.zlen**2)
+        tol = diag * tol_ratio
+
+        from scipy.spatial import cKDTree
+
+        tree = cKDTree(pts)
+
+        def check_plane_symmetry(pts_arr, axis_idx):
+            reflected = pts_arr.copy()
+            reflected[:, axis_idx] = -reflected[:, axis_idx]
+            dists, _ = tree.query(reflected)
+            return float(np.mean(dists)) < tol
+
+        cx = (bb.xmin + bb.xmax) / 2
+        cy = (bb.ymin + bb.ymax) / 2
+        cz = (bb.zmin + bb.zmax) / 2
+        centered = pts - np.array([cx, cy, cz])
+        tree_c = cKDTree(centered)
+
+        def check_sym(axis_idx):
+            reflected = centered.copy()
+            reflected[:, axis_idx] = -reflected[:, axis_idx]
+            dists, _ = tree_c.query(reflected)
+            return float(np.mean(dists)) < tol
+
+        has_yz = check_sym(0)
+        has_xz = check_sym(1)
+        has_xy = check_sym(2)
+
+        return has_xy, has_xz, has_yz
+
+    except Exception as e:
+        logger.warning(f"Symmetry check failed: {e}")
+        return False, False, False
+
+
+def _classify_shape(props: Dict[str, Any]) -> str:
+    ratio_yx = props.get("bbox_ratio_yx", 0)
+    ratio_zx = props.get("bbox_ratio_zx", 0)
+    dominant = props.get("dominant_face_type", "")
+    euler = props.get("euler_characteristic", 2)
+    is_valid = props.get("is_valid", False)
+
+    if not is_valid or props.get("volume_mm3", 0) <= 0:
+        return "DEGENERATE"
+
+    is_flat = ratio_zx < 0.25
+    is_cubic = ratio_yx > 0.7 and ratio_zx > 0.7
+    is_round = dominant in ("CYLINDER", "CONE", "SPHERE", "TORUS")
+    is_tall = ratio_zx > 0.5 and not is_cubic
+
+    if is_round:
+        if is_flat:
+            return "FLAT_ROUND_SOLID"
+        if euler != 2:
+            return "HOLLOW_ROUND_SOLID"
+        if is_tall:
+            return "TALL_ROUND_SOLID"
+        return "FLAT_ROUND_SOLID"
+
+    if is_flat:
+        if euler != 2:
+            return "FLAT_SOLID_WITH_HOLES"
+        return "FLAT_SOLID"
+
+    if is_cubic:
+        if euler != 2:
+            return "CUBIC_SOLID_WITH_HOLES"
+        return "CUBIC_SOLID"
+
+    face_count = props.get("face_count", 0)
+
+    if face_count > 8 and ratio_yx < 0.5:
+        return "L_SHAPED_SOLID"
+
+    if face_count > 8 and ratio_yx > 0.5:
+        return "T_SHAPED_SOLID"
+
+    if face_count > 10:
+        return "STEPPED_SOLID"
+
+    return "COMPLEX_SOLID"

server/preprocessor.py

@@ -0,0 +1,339 @@
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def normalize_shape(shape) -> Tuple[Any, Dict[str, Any]]:
+    t0 = time.time()
+    import cadquery as cq
+
+    bb = shape.BoundingBox()
+    cx = (bb.xmin + bb.xmax) / 2
+    cy = (bb.ymin + bb.ymax) / 2
+    cz = (bb.zmin + bb.zmax) / 2
+    shape = shape.translate((-cx, -cy, -cz))
+
+    bb = shape.BoundingBox()
+    dims = {"X": bb.xlen, "Y": bb.ylen, "Z": bb.zlen}
+    sorted_dims = sorted(dims.items(), key=lambda x: x[1], reverse=True)
+
+    longest, second, shortest = sorted_dims[0][0], sorted_dims[1][0], sorted_dims[2][0]
+
+    target_order = ["X", "Y", "Z"]
+    current_order = [longest, second, shortest]
+
+    rotation = _compute_alignment_rotation(current_order, target_order)
+    if rotation is not None:
+        rx, ry, rz = rotation
+        if rx != 0 or ry != 0 or rz != 0:
+            from OCP.gp import gp_Ax1, gp_Pnt, gp_Dir, gp_Trsf
+            from OCP.BRepBuilderAPI import BRepBuilderAPI_Transform
+
+            trsf = gp_Trsf()
+            if rz != 0:
+                trsf_z = gp_Trsf()
+                trsf_z.SetRotation(gp_Ax1(gp_Pnt(0, 0, 0), gp_Dir(0, 0, 1)), np.radians(rz))
+                trsf.Multiply(trsf_z)
+            if ry != 0:
+                trsf_y = gp_Trsf()
+                trsf_y.SetRotation(gp_Ax1(gp_Pnt(0, 0, 0), gp_Dir(0, 1, 0)), np.radians(ry))
+                trsf.Multiply(trsf_y)
+            if rx != 0:
+                trsf_x = gp_Trsf()
+                trsf_x.SetRotation(gp_Ax1(gp_Pnt(0, 0, 0), gp_Dir(1, 0, 0)), np.radians(rx))
+                trsf.Multiply(trsf_x)
+
+            builder = BRepBuilderAPI_Transform(shape.wrapped, trsf, True)
+            builder.Build()
+            shape = cq.Shape(builder.Shape())
+
+    bb = shape.BoundingBox()
+    cx2 = (bb.xmin + bb.xmax) / 2
+    cy2 = (bb.ymin + bb.ymax) / 2
+    cz2 = (bb.zmin + bb.zmax) / 2
+    if abs(cx2) > 0.01 or abs(cy2) > 0.01 or abs(cz2) > 0.01:
+        shape = shape.translate((-cx2, -cy2, -cz2))
+
+    transform_info = {
+        "units": "mm",
+        "translation_to_origin": [round(cx, 4), round(cy, 4), round(cz, 4)],
+        "axis_alignment": current_order,
+        "longest_axis": "X",
+    }
+
+    elapsed = time.time() - t0
+    logger.info(f"normalize_shape took {elapsed:.3f}s")
+    return shape, transform_info
+
+
+def _compute_alignment_rotation(current, target):
+    if current == target:
+        return None
+
+    c = current
+    if c == ["Y", "X", "Z"]:
+        return (0, 0, 90)
+    elif c == ["Z", "Y", "X"]:
+        return (0, 90, 0)
+    elif c == ["Z", "X", "Y"]:
+        return (90, 0, 0)
+    elif c == ["X", "Z", "Y"]:
+        return (90, 0, 0)
+    elif c == ["Y", "Z", "X"]:
+        return (0, 0, 90)
+    else:
+        return (0, 0, 0)
+
+
+def sample_surface_points(shape, n_points: int = 2048) -> np.ndarray:
+    t0 = time.time()
+    from OCP.BRepMesh import BRepMesh_IncrementalMesh
+    from OCP.BRep import BRep_Tool
+    from OCP.TopExp import TopExp_Explorer
+    from OCP.TopAbs import TopAbs_FACE
+    from OCP.TopLoc import TopLoc_Location
+    from OCP.TopoDS import TopoDS
+
+    mesh = BRepMesh_IncrementalMesh(shape.wrapped, 0.1, False, 0.1, True)
+    mesh.Perform()
+
+    all_points = []
+    all_areas = []
+
+    explorer = TopExp_Explorer(shape.wrapped, TopAbs_FACE)
+    while explorer.More():
+        face = TopoDS.Face_s(explorer.Current())
+        loc = TopLoc_Location()
+        tri = BRep_Tool.Triangulation_s(face, loc)
+        if tri is not None:
+            trsf = loc.Transformation()
+            nodes = []
+            for i in range(1, tri.NbNodes() + 1):
+                p = tri.Node(i)
+                p.Transform(trsf)
+                nodes.append([p.X(), p.Y(), p.Z()])
+            nodes = np.array(nodes)
+
+            for i in range(1, tri.NbTriangles() + 1):
+                t = tri.Triangle(i)
+                n1, n2, n3 = t.Get()
+                v0 = nodes[n1 - 1]
+                v1 = nodes[n2 - 1]
+                v2 = nodes[n3 - 1]
+                area = 0.5 * np.linalg.norm(np.cross(v1 - v0, v2 - v0))
+                if area > 1e-12:
+                    all_points.append((v0, v1, v2))
+                    all_areas.append(area)
+
+        explorer.Next()
+
+    if not all_points:
+        logger.warning("No triangles found for surface sampling")
+        return np.zeros((n_points, 3))
+
+    areas = np.array(all_areas)
+    probs = areas / areas.sum()
+
+    sampled = []
+    chosen = np.random.choice(len(all_points), size=n_points, p=probs)
+    for idx in chosen:
+        v0, v1, v2 = all_points[idx]
+        r1, r2 = np.random.random(), np.random.random()
+        if r1 + r2 > 1:
+            r1, r2 = 1 - r1, 1 - r2
+        pt = v0 * (1 - r1 - r2) + v1 * r1 + v2 * r2
+        sampled.append(pt)
+
+    result = np.array(sampled, dtype=np.float32)
+    elapsed = time.time() - t0
+    logger.info(f"sample_surface_points ({n_points} pts) took {elapsed:.3f}s")
+    return result
+
+
+def _occ_to_trimesh(shape):
+    import trimesh
+    from OCP.BRepMesh import BRepMesh_IncrementalMesh
+    from OCP.BRep import BRep_Tool
+    from OCP.TopExp import TopExp_Explorer
+    from OCP.TopAbs import TopAbs_FACE
+    from OCP.TopLoc import TopLoc_Location
+    from OCP.TopoDS import TopoDS
+
+    mesh_occ = BRepMesh_IncrementalMesh(shape.wrapped, 0.1, False, 0.1, True)
+    mesh_occ.Perform()
+
+    verts, faces = [], []
+    offset = 0
+    explorer = TopExp_Explorer(shape.wrapped, TopAbs_FACE)
+    while explorer.More():
+        face = TopoDS.Face_s(explorer.Current())
+        loc = TopLoc_Location()
+        tri = BRep_Tool.Triangulation_s(face, loc)
+        if tri is not None:
+            trsf = loc.Transformation()
+            nodes = []
+            for i in range(1, tri.NbNodes() + 1):
+                p = tri.Node(i)
+                p.Transform(trsf)
+                nodes.append([p.X(), p.Y(), p.Z()])
+            for i in range(1, tri.NbTriangles() + 1):
+                t = tri.Triangle(i)
+                n1, n2, n3 = t.Get()
+                faces.append([n1 - 1 + offset, n2 - 1 + offset, n3 - 1 + offset])
+            verts.extend(nodes)
+            offset += len(nodes)
+        explorer.Next()
+
+    if not verts:
+        raise ValueError("No mesh triangles extracted from shape")
+
+    m = trimesh.Trimesh(
+        vertices=np.array(verts, dtype=np.float64),
+        faces=np.array(faces, dtype=np.int64),
+        process=True,
+    )
+    m.fix_normals()
+    return m
+
+
+def voxelize(shape, resolution: int = 64) -> np.ndarray:
+    t0 = time.time()
+
+    tri_mesh = _occ_to_trimesh(shape)
+
+    bb = shape.BoundingBox()
+    padding = 0.01
+    xs = np.linspace(bb.xmin - padding, bb.xmax + padding, resolution)
+    ys = np.linspace(bb.ymin - padding, bb.ymax + padding, resolution)
+    zs = np.linspace(bb.zmin - padding, bb.zmax + padding, resolution)
+    grid_pts = np.stack(np.meshgrid(xs, ys, zs, indexing='ij'), axis=-1).reshape(-1, 3)
+
+    inside = tri_mesh.contains(grid_pts)
+    grid = inside.reshape(resolution, resolution, resolution)
+
+    elapsed = time.time() - t0
+    logger.info(f"voxelize ({resolution}^3, trimesh+embree) took {elapsed:.3f}s, fill={grid.sum()}")
+    return grid
+
+
+def voxelize_in_bbox(shape, bbox_min, bbox_max, resolution: int = 64) -> np.ndarray:
+    t0 = time.time()
+
+    tri_mesh = _occ_to_trimesh(shape)
+
+    padding = 0.01
+    xs = np.linspace(bbox_min[0] - padding, bbox_max[0] + padding, resolution)
+    ys = np.linspace(bbox_min[1] - padding, bbox_max[1] + padding, resolution)
+    zs = np.linspace(bbox_min[2] - padding, bbox_max[2] + padding, resolution)
+    grid_pts = np.stack(np.meshgrid(xs, ys, zs, indexing='ij'), axis=-1).reshape(-1, 3)
+
+    inside = tri_mesh.contains(grid_pts)
+    grid = inside.reshape(resolution, resolution, resolution)
+
+    elapsed = time.time() - t0
+    logger.info(f"voxelize_in_bbox ({resolution}^3) took {elapsed:.3f}s, fill={grid.sum()}/{resolution**3}")
+    return grid
+
+
+def generate_ground_truth(
+    shape,
+    output_dir: str,
+    source_step: Optional[str] = None,
+) -> Dict[str, Any]:
+    t0 = time.time()
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    from .geometry import extract_properties
+    props = extract_properties(shape)
+
+    points = sample_surface_points(shape, n_points=2048)
+    np.save(str(output_path / "surface_points.npy"), points)
+
+    voxels = voxelize(shape, resolution=64)
+    np.save(str(output_path / "voxels_64.npy"), voxels)
+
+    bb = shape.BoundingBox()
+
+    ground_truth = {
+        "source_step": source_step,
+        "volume_mm3": props["volume_mm3"],
+        "surface_area_mm2": props["surface_area_mm2"],
+        "bbox_mm": [round(bb.xlen, 4), round(bb.ylen, 4), round(bb.zlen, 4)],
+        "face_count": props["face_count"],
+        "face_types": list(props["face_type_counts"].keys()),
+        "dominant_face_type": props["dominant_face_type"],
+        "euler_characteristic": props["euler_characteristic"],
+        "surface_points_file": "surface_points.npy",
+        "voxels_file": "voxels_64.npy",
+    }
+
+    with open(output_path / "ground_truth.json", "w") as f:
+        json.dump(ground_truth, f, indent=2)
+
+    elapsed = time.time() - t0
+    logger.info(f"generate_ground_truth took {elapsed:.3f}s")
+    return ground_truth
+
+
+def preprocess_from_code(
+    code: str,
+    output_dir: str,
+    task_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    t0 = time.time()
+    import cadquery as cq
+
+    local_ns = {"cq": cq, "cadquery": cq}
+    try:
+        import math
+        local_ns["math"] = math
+    except Exception:
+        pass
+
+    exec(code, local_ns)
+
+    if "result" not in local_ns:
+        raise ValueError("Code must define a variable named 'result'")
+
+    result = local_ns["result"]
+    if hasattr(result, "val"):
+        shape = result.val()
+    else:
+        shape = result
+
+    orig_bb = shape.BoundingBox()
+    orig_bbox_mm = [round(orig_bb.xlen, 4), round(orig_bb.ylen, 4), round(orig_bb.zlen, 4)]
+
+    normalized_shape, transform_info = normalize_shape(shape)
+
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    import cadquery as cq
+    original_step_path = str(output_path / "ground_truth.step")
+    cq.exporters.export(cq.Workplane().add(shape), original_step_path, exportType="STEP")
+
+    normalized_step_path = str(output_path / "ground_truth_normalized.step")
+    cq.exporters.export(cq.Workplane().add(normalized_shape), normalized_step_path, exportType="STEP")
+
+    gt = generate_ground_truth(
+        normalized_shape,
+        output_dir,
+        source_step=f"server/tasks/{task_id}/ground_truth.step" if task_id else original_step_path,
+    )
+    gt["canonical_transform"] = transform_info
+    gt["original_bbox_mm"] = orig_bbox_mm
+
+    with open(output_path / "ground_truth.json", "w") as f:
+        json.dump(gt, f, indent=2)
+
+    elapsed = time.time() - t0
+    logger.info(f"preprocess_from_code took {elapsed:.3f}s total")
+    return gt

server/requirements.txt

@@ -0,0 +1,7 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+scipy>=1.11.0
+
+
+

server/reward.py

@@ -0,0 +1,325 @@
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict
+
+import numpy as np
+from scipy.spatial import cKDTree
+
+from openenv.core.rubrics.base import Rubric
+from openenv.core.rubrics.containers import Gate, Sequential, WeightedSum
+
+from .preprocessor import normalize_shape, sample_surface_points, voxelize_in_bbox
+
+logger = logging.getLogger(__name__)
+
+ENABLE_CHAMFER_DISTANCE = True
+
+
+class RexecRubric(Rubric):
+    def __init__(self):
+        super().__init__()
+
+    def forward(self, action: Any, observation: Any) -> float:
+        t0 = time.time()
+
+        if observation.code_executed is not True:
+            logger.info("Rexec=0: code did not execute successfully")
+            return 0.0
+
+        props = observation.object_properties
+        if props is None:
+            logger.info("Rexec=0: no object properties")
+            return 0.0
+
+        if not props.get("is_valid", False):
+            logger.info("Rexec=0: shape is not valid")
+            return 0.0
+
+        if props.get("volume_mm3", 0) <= 0:
+            logger.info("Rexec=0: volume is zero or negative")
+            return 0.0
+
+        elapsed = time.time() - t0
+        logger.info(f"Rexec=1.0 (took {elapsed:.3f}s)")
+        return 1.0
+
+
+class RgeomRubric(Rubric):
+    def __init__(self, ground_truth_dir: str, enable_cd: bool = True):
+        super().__init__()
+        self._gt_dir = Path(ground_truth_dir)
+        self._gt_shape = None
+        self._gt_points = None
+        self._gt_data = None
+        self._gt_bbox = None
+        self._enable_cd = enable_cd and ENABLE_CHAMFER_DISTANCE
+
+    def _load_ground_truth(self):
+        if self._gt_data is None:
+            import json
+            gt_path = self._gt_dir / "ground_truth.json"
+            with open(gt_path) as f:
+                self._gt_data = json.load(f)
+
+        if self._gt_shape is None:
+            import cadquery as cq
+            t0 = time.time()
+            gt_step_path = self._gt_dir / "ground_truth_normalized.step"
+            if not gt_step_path.exists():
+                gt_step_path = self._gt_dir / "ground_truth.step"
+            wp = cq.importers.importStep(str(gt_step_path))
+            self._gt_shape = wp.val()
+            bb = self._gt_shape.BoundingBox()
+            self._gt_bbox = {
+                "xmin": bb.xmin, "xmax": bb.xmax,
+                "ymin": bb.ymin, "ymax": bb.ymax,
+                "zmin": bb.zmin, "zmax": bb.zmax,
+            }
+            elapsed = time.time() - t0
+            logger.info(f"Loaded GT STEP in {elapsed:.3f}s, bbox=[{bb.xlen:.2f}, {bb.ylen:.2f}, {bb.zlen:.2f}]")
+
+        if self._gt_points is None:
+            pts_path = self._gt_dir / "surface_points.npy"
+            if pts_path.exists():
+                self._gt_points = np.load(str(pts_path))
+                logger.info(f"Loaded ground truth points: {self._gt_points.shape}")
+            else:
+                t0 = time.time()
+                self._gt_points = sample_surface_points(self._gt_shape, n_points=2048)
+                elapsed = time.time() - t0
+                logger.info(f"Sampled GT surface points in {elapsed:.3f}s")
+
+    def _load_agent_shape(self, step_path: str):
+        import cadquery as cq
+        t0 = time.time()
+        wp = cq.importers.importStep(step_path)
+        raw_shape = wp.val()
+        normalized_shape, _ = normalize_shape(raw_shape)
+        elapsed = time.time() - t0
+        logger.info(f"Loaded + normalized agent STEP in {elapsed:.3f}s")
+        return normalized_shape
+
+    def forward(self, action: Any, observation: Any) -> float:
+        t0 = time.time()
+
+        props = observation.object_properties
+        if props is None:
+            return 0.0
+
+        raw_data = getattr(observation, "_raw_data", None)
+        if raw_data is None or raw_data.get("step_path") is None:
+            logger.warning("Rgeom: no agent STEP path in _raw_data, returning 0")
+            return 0.0
+
+        agent_step_path = raw_data["step_path"]
+        if not Path(agent_step_path).exists():
+            logger.warning(f"Rgeom: agent STEP file not found: {agent_step_path}")
+            return 0.0
+
+        self._load_ground_truth()
+
+        try:
+            agent_shape = self._load_agent_shape(agent_step_path)
+        except Exception as e:
+            logger.error(f"Rgeom: failed to load agent STEP: {e}")
+            return 0.0
+
+        gt_bb = self._gt_bbox
+        bbox_min = [gt_bb["xmin"], gt_bb["ymin"], gt_bb["zmin"]]
+        bbox_max = [gt_bb["xmax"], gt_bb["ymax"], gt_bb["zmax"]]
+
+        try:
+            t_vox = time.time()
+            agent_voxels = voxelize_in_bbox(agent_shape, bbox_min, bbox_max, resolution=64)
+            gt_voxels = voxelize_in_bbox(self._gt_shape, bbox_min, bbox_max, resolution=64)
+            logger.info(f"Voxelization (both shapes) took {time.time() - t_vox:.3f}s")
+        except Exception as e:
+            logger.error(f"Rgeom: voxelization failed: {e}")
+            return 0.0
+
+        iou_score = best_of_6_iou(agent_voxels, gt_voxels)
+
+        mean_cd_reward = 0.0
+        median_cd_reward = 0.0
+
+        if self._enable_cd:
+            try:
+                t_cd = time.time()
+                agent_points = sample_surface_points(agent_shape, n_points=2048)
+
+                bbox_mm = self._gt_data.get("bbox_mm", [1, 1, 1])
+                bbox_diag = np.sqrt(sum(d**2 for d in bbox_mm))
+                threshold = bbox_diag * 0.1
+
+                mean_cd = compute_mean_chamfer(agent_points, self._gt_points)
+                mean_cd_reward = max(0.0, 1.0 - (mean_cd / threshold)) if threshold > 0 else 0.0
+
+                median_cd = compute_median_chamfer(agent_points, self._gt_points)
+                median_cd_reward = max(0.0, 1.0 - (median_cd / threshold)) if threshold > 0 else 0.0
+                logger.info(f"Chamfer distance took {time.time() - t_cd:.3f}s")
+            except Exception as e:
+                logger.error(f"Rgeom: chamfer distance failed: {e}")
+
+        if self._enable_cd:
+            rgeom = 0.60 * iou_score + 0.20 * mean_cd_reward + 0.20 * median_cd_reward
+        else:
+            rgeom = iou_score
+
+        elapsed = time.time() - t0
+        logger.info(
+            f"Rgeom={rgeom:.4f} (IoU={iou_score:.4f}, MeanCD={mean_cd_reward:.4f}, "
+            f"MedianCD={median_cd_reward:.4f}, cd_enabled={self._enable_cd}, took {elapsed:.3f}s)"
+        )
+
+        return rgeom
+
+
+class RevalRubric(Rubric):
+    W_VOLUME = 0.35
+    W_BBOX = 0.30
+    W_FACE_TYPE = 0.15
+    W_EULER = 0.20
+
+    def __init__(self, ground_truth_dir: str):
+        super().__init__()
+        self._gt_dir = Path(ground_truth_dir)
+        self._gt_data = None
+
+    def _load_ground_truth(self):
+        if self._gt_data is None:
+            import json
+            gt_path = self._gt_dir / "ground_truth.json"
+            with open(gt_path) as f:
+                self._gt_data = json.load(f)
+
+    def forward(self, action: Any, observation: Any) -> float:
+        t0 = time.time()
+
+        props = observation.object_properties
+        if props is None:
+            return 0.0
+
+        self._load_ground_truth()
+
+        gt_vol = self._gt_data.get("volume_mm3", 0)
+        agent_vol = props.get("volume_mm3", 0)
+        if gt_vol > 0:
+            vol_ratio = min(agent_vol, gt_vol) / max(agent_vol, gt_vol)
+            volume_score = max(0.0, vol_ratio)
+        else:
+            volume_score = 1.0 if agent_vol == 0 else 0.0
+
+        gt_bbox = sorted(self._gt_data.get("bbox_mm", [0, 0, 0]), reverse=True)
+        agent_bbox = sorted([
+            props.get("bbox_x_mm", 0),
+            props.get("bbox_y_mm", 0),
+            props.get("bbox_z_mm", 0),
+        ], reverse=True)
+
+        bbox_scores = []
+        for a, g in zip(agent_bbox, gt_bbox):
+            if g > 0:
+                bbox_scores.append(max(0.0, 1.0 - abs(a - g) / g))
+            else:
+                bbox_scores.append(1.0 if a == 0 else 0.0)
+        bbox_score = sum(bbox_scores) / 3.0 if bbox_scores else 0.0
+
+        target_dominant = self._gt_data.get("dominant_face_type", "")
+        agent_dominant = props.get("dominant_face_type", "")
+        face_type_score = 1.0 if agent_dominant == target_dominant else 0.0
+
+        gt_euler = self._gt_data.get("euler_characteristic", 2)
+        agent_euler = props.get("euler_characteristic", 2)
+        euler_score = 1.0 if agent_euler == gt_euler else 0.0
+
+        reval = (
+            self.W_VOLUME * volume_score
+            + self.W_BBOX * bbox_score
+            + self.W_FACE_TYPE * face_type_score
+            + self.W_EULER * euler_score
+        )
+
+        elapsed = time.time() - t0
+        logger.info(
+            f"Reval={reval:.4f} (vol={volume_score:.2f}, bbox={bbox_score:.2f}, "
+            f"face_type={face_type_score:.2f}, euler={euler_score:.2f}, took {elapsed:.3f}s)"
+        )
+
+        return reval
+
+
+def build_cadforge_rubric(ground_truth_dir: str, enable_cd: bool = True) -> Rubric:
+    rexec = RexecRubric()
+    rgeom = RgeomRubric(ground_truth_dir, enable_cd=enable_cd)
+    reval = RevalRubric(ground_truth_dir)
+
+    quality = WeightedSum([rgeom, reval], weights=[0.8, 0.2])
+    rubric = Sequential(Gate(rexec), quality)
+
+    return rubric
+
+
+def compute_iou(voxels_a: np.ndarray, voxels_b: np.ndarray) -> float:
+    a = voxels_a.astype(bool)
+    b = voxels_b.astype(bool)
+
+    if a.shape != b.shape:
+        from scipy.ndimage import zoom
+        target_shape = b.shape
+        zoom_factors = tuple(t / s for t, s in zip(target_shape, a.shape))
+        a = zoom(a.astype(float), zoom_factors, order=0) > 0.5
+
+    intersection = np.logical_and(a, b).sum()
+    union = np.logical_or(a, b).sum()
+
+    if union == 0:
+        return 0.0
+    return float(intersection / union)
+
+
+def best_of_6_iou(agent_voxels: np.ndarray, gt_voxels: np.ndarray) -> float:
+    orientations = [
+        lambda v: v,
+        lambda v: np.rot90(v, 1, (0, 1)),
+        lambda v: np.rot90(v, 1, (0, 2)),
+        lambda v: np.rot90(v, 1, (1, 2)),
+        lambda v: np.rot90(v, 2, (0, 1)),
+        lambda v: np.rot90(v, 1, (0, 1)).T,
+    ]
+
+    best = 0.0
+    for orient in orientations:
+        rotated = orient(agent_voxels.copy())
+        iou = compute_iou(rotated, gt_voxels)
+        if iou > best:
+            best = iou
+    return best
+
+
+def compute_mean_chamfer(points_a: np.ndarray, points_b: np.ndarray) -> float:
+    if len(points_a) == 0 or len(points_b) == 0:
+        return float("inf")
+
+    tree_a = cKDTree(points_a)
+    tree_b = cKDTree(points_b)
+
+    dists_a_to_b, _ = tree_b.query(points_a)
+    dists_b_to_a, _ = tree_a.query(points_b)
+
+    mean_cd = (np.mean(dists_a_to_b) + np.mean(dists_b_to_a)) / 2
+    return float(mean_cd)
+
+
+def compute_median_chamfer(points_a: np.ndarray, points_b: np.ndarray) -> float:
+    if len(points_a) == 0 or len(points_b) == 0:
+        return float("inf")
+
+    tree_a = cKDTree(points_a)
+    tree_b = cKDTree(points_b)
+
+    dists_a_to_b, _ = tree_b.query(points_a)
+    dists_b_to_a, _ = tree_a.query(points_b)
+
+    median_cd = (np.median(dists_a_to_b) + np.median(dists_b_to_a)) / 2
+    return float(median_cd)

server/tasks/task_001_flat_plate/ground_truth.json

@@ -0,0 +1,39 @@
+{
+  "source_step": "tasks/task_001_flat_plate/ground_truth.step",
+  "volume_mm3": 16000.0,
+  "surface_area_mm2": 7600.0,
+  "bbox_mm": [
+    80.0,
+    40.0,
+    5.0
+  ],
+  "face_count": 6,
+  "face_types": [
+    "PLANE"
+  ],
+  "dominant_face_type": "PLANE",
+  "hole_count": 0,
+  "hole_diameters_mm": [],
+  "euler_characteristic": 2,
+  "surface_points_file": "surface_points.npy",
+  "voxels_file": "voxels_64.npy",
+  "canonical_transform": {
+    "units": "mm",
+    "translation_to_origin": [
+      0.0,
+      0.0,
+      0.0
+    ],
+    "axis_alignment": [
+      "X",
+      "Y",
+      "Z"
+    ],
+    "longest_axis": "X"
+  },
+  "original_bbox_mm": [
+    80.0,
+    40.0,
+    5.0
+  ]
+}

server/tasks/task_001_flat_plate/ground_truth.step

@@ -0,0 +1,416 @@
+ISO-10303-21;
+HEADER;
+FILE_DESCRIPTION(('Open CASCADE Model'),'2;1');
+FILE_NAME('Open CASCADE Shape Model','2026-04-25T17:44:28',('Author'),(
+    'Open CASCADE'),'Open CASCADE STEP processor 7.8','Open CASCADE 7.8'
+  ,'Unknown');
+FILE_SCHEMA(('AUTOMOTIVE_DESIGN { 1 0 10303 214 1 1 1 1 }'));
+ENDSEC;
+DATA;
+#1 = APPLICATION_PROTOCOL_DEFINITION('international standard',
+  'automotive_design',2000,#2);
+#2 = APPLICATION_CONTEXT(
+  'core data for automotive mechanical design processes');
+#3 = SHAPE_DEFINITION_REPRESENTATION(#4,#10);
+#4 = PRODUCT_DEFINITION_SHAPE('','',#5);
+#5 = PRODUCT_DEFINITION('design','',#6,#9);
+#6 = PRODUCT_DEFINITION_FORMATION('','',#7);
+#7 = PRODUCT('Open CASCADE STEP translator 7.8 1',
+  'Open CASCADE STEP translator 7.8 1','',(#8));
+#8 = PRODUCT_CONTEXT('',#2,'mechanical');
+#9 = PRODUCT_DEFINITION_CONTEXT('part definition',#2,'design');
+#10 = ADVANCED_BREP_SHAPE_REPRESENTATION('',(#11,#15),#345);
+#11 = AXIS2_PLACEMENT_3D('',#12,#13,#14);
+#12 = CARTESIAN_POINT('',(0.,0.,0.));
+#13 = DIRECTION('',(0.,0.,1.));
+#14 = DIRECTION('',(1.,0.,-0.));
+#15 = MANIFOLD_SOLID_BREP('',#16);
+#16 = CLOSED_SHELL('',(#17,#137,#237,#284,#331,#338));
+#17 = ADVANCED_FACE('',(#18),#32,.F.);
+#18 = FACE_BOUND('',#19,.F.);
+#19 = EDGE_LOOP('',(#20,#55,#83,#111));
+#20 = ORIENTED_EDGE('',*,*,#21,.F.);
+#21 = EDGE_CURVE('',#22,#24,#26,.T.);
+#22 = VERTEX_POINT('',#23);
+#23 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#24 = VERTEX_POINT('',#25);
+#25 = CARTESIAN_POINT('',(-40.,-20.,2.5));
+#26 = SURFACE_CURVE('',#27,(#31,#43),.PCURVE_S1.);
+#27 = LINE('',#28,#29);
+#28 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#29 = VECTOR('',#30,1.);
+#30 = DIRECTION('',(0.,0.,1.));
+#31 = PCURVE('',#32,#37);
+#32 = PLANE('',#33);
+#33 = AXIS2_PLACEMENT_3D('',#34,#35,#36);
+#34 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#35 = DIRECTION('',(1.,0.,0.));
+#36 = DIRECTION('',(0.,0.,1.));
+#37 = DEFINITIONAL_REPRESENTATION('',(#38),#42);
+#38 = LINE('',#39,#40);
+#39 = CARTESIAN_POINT('',(0.,0.));
+#40 = VECTOR('',#41,1.);
+#41 = DIRECTION('',(1.,0.));
+#42 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#43 = PCURVE('',#44,#49);
+#44 = PLANE('',#45);
+#45 = AXIS2_PLACEMENT_3D('',#46,#47,#48);
+#46 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#47 = DIRECTION('',(0.,1.,0.));
+#48 = DIRECTION('',(0.,0.,1.));
+#49 = DEFINITIONAL_REPRESENTATION('',(#50),#54);
+#50 = LINE('',#51,#52);
+#51 = CARTESIAN_POINT('',(0.,0.));
+#52 = VECTOR('',#53,1.);
+#53 = DIRECTION('',(1.,0.));
+#54 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#55 = ORIENTED_EDGE('',*,*,#56,.T.);
+#56 = EDGE_CURVE('',#22,#57,#59,.T.);
+#57 = VERTEX_POINT('',#58);
+#58 = CARTESIAN_POINT('',(-40.,20.,-2.5));
+#59 = SURFACE_CURVE('',#60,(#64,#71),.PCURVE_S1.);
+#60 = LINE('',#61,#62);
+#61 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#62 = VECTOR('',#63,1.);
+#63 = DIRECTION('',(0.,1.,0.));
+#64 = PCURVE('',#32,#65);
+#65 = DEFINITIONAL_REPRESENTATION('',(#66),#70);
+#66 = LINE('',#67,#68);
+#67 = CARTESIAN_POINT('',(0.,0.));
+#68 = VECTOR('',#69,1.);
+#69 = DIRECTION('',(0.,-1.));
+#70 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#71 = PCURVE('',#72,#77);
+#72 = PLANE('',#73);
+#73 = AXIS2_PLACEMENT_3D('',#74,#75,#76);
+#74 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#75 = DIRECTION('',(0.,0.,1.));
+#76 = DIRECTION('',(1.,0.,0.));
+#77 = DEFINITIONAL_REPRESENTATION('',(#78),#82);
+#78 = LINE('',#79,#80);
+#79 = CARTESIAN_POINT('',(0.,0.));
+#80 = VECTOR('',#81,1.);
+#81 = DIRECTION('',(0.,1.));
+#82 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#83 = ORIENTED_EDGE('',*,*,#84,.T.);
+#84 = EDGE_CURVE('',#57,#85,#87,.T.);
+#85 = VERTEX_POINT('',#86);
+#86 = CARTESIAN_POINT('',(-40.,20.,2.5));
+#87 = SURFACE_CURVE('',#88,(#92,#99),.PCURVE_S1.);
+#88 = LINE('',#89,#90);
+#89 = CARTESIAN_POINT('',(-40.,20.,-2.5));
+#90 = VECTOR('',#91,1.);
+#91 = DIRECTION('',(0.,0.,1.));
+#92 = PCURVE('',#32,#93);
+#93 = DEFINITIONAL_REPRESENTATION('',(#94),#98);
+#94 = LINE('',#95,#96);
+#95 = CARTESIAN_POINT('',(0.,-40.));
+#96 = VECTOR('',#97,1.);
+#97 = DIRECTION('',(1.,0.));
+#98 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#99 = PCURVE('',#100,#105);
+#100 = PLANE('',#101);
+#101 = AXIS2_PLACEMENT_3D('',#102,#103,#104);
+#102 = CARTESIAN_POINT('',(-40.,20.,-2.5));
+#103 = DIRECTION('',(0.,1.,0.));
+#104 = DIRECTION('',(0.,0.,1.));
+#105 = DEFINITIONAL_REPRESENTATION('',(#106),#110);
+#106 = LINE('',#107,#108);
+#107 = CARTESIAN_POINT('',(0.,0.));
+#108 = VECTOR('',#109,1.);
+#109 = DIRECTION('',(1.,0.));
+#110 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#111 = ORIENTED_EDGE('',*,*,#112,.F.);
+#112 = EDGE_CURVE('',#24,#85,#113,.T.);
+#113 = SURFACE_CURVE('',#114,(#118,#125),.PCURVE_S1.);
+#114 = LINE('',#115,#116);
+#115 = CARTESIAN_POINT('',(-40.,-20.,2.5));
+#116 = VECTOR('',#117,1.);
+#117 = DIRECTION('',(0.,1.,0.));
+#118 = PCURVE('',#32,#119);
+#119 = DEFINITIONAL_REPRESENTATION('',(#120),#124);
+#120 = LINE('',#121,#122);
+#121 = CARTESIAN_POINT('',(5.,0.));
+#122 = VECTOR('',#123,1.);
+#123 = DIRECTION('',(0.,-1.));
+#124 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#125 = PCURVE('',#126,#131);
+#126 = PLANE('',#127);
+#127 = AXIS2_PLACEMENT_3D('',#128,#129,#130);
+#128 = CARTESIAN_POINT('',(-40.,-20.,2.5));
+#129 = DIRECTION('',(0.,0.,1.));
+#130 = DIRECTION('',(1.,0.,0.));
+#131 = DEFINITIONAL_REPRESENTATION('',(#132),#136);
+#132 = LINE('',#133,#134);
+#133 = CARTESIAN_POINT('',(0.,0.));
+#134 = VECTOR('',#135,1.);
+#135 = DIRECTION('',(0.,1.));
+#136 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#137 = ADVANCED_FACE('',(#138),#152,.T.);
+#138 = FACE_BOUND('',#139,.T.);
+#139 = EDGE_LOOP('',(#140,#170,#193,#216));
+#140 = ORIENTED_EDGE('',*,*,#141,.F.);
+#141 = EDGE_CURVE('',#142,#144,#146,.T.);
+#142 = VERTEX_POINT('',#143);
+#143 = CARTESIAN_POINT('',(40.,-20.,-2.5));
+#144 = VERTEX_POINT('',#145);
+#145 = CARTESIAN_POINT('',(40.,-20.,2.5));
+#146 = SURFACE_CURVE('',#147,(#151,#163),.PCURVE_S1.);
+#147 = LINE('',#148,#149);
+#148 = CARTESIAN_POINT('',(40.,-20.,-2.5));
+#149 = VECTOR('',#150,1.);
+#150 = DIRECTION('',(0.,0.,1.));
+#151 = PCURVE('',#152,#157);
+#152 = PLANE('',#153);
+#153 = AXIS2_PLACEMENT_3D('',#154,#155,#156);
+#154 = CARTESIAN_POINT('',(40.,-20.,-2.5));
+#155 = DIRECTION('',(1.,0.,0.));
+#156 = DIRECTION('',(0.,0.,1.));
+#157 = DEFINITIONAL_REPRESENTATION('',(#158),#162);
+#158 = LINE('',#159,#160);
+#159 = CARTESIAN_POINT('',(0.,0.));
+#160 = VECTOR('',#161,1.);
+#161 = DIRECTION('',(1.,0.));
+#162 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#163 = PCURVE('',#44,#164);
+#164 = DEFINITIONAL_REPRESENTATION('',(#165),#169);
+#165 = LINE('',#166,#167);
+#166 = CARTESIAN_POINT('',(0.,80.));
+#167 = VECTOR('',#168,1.);
+#168 = DIRECTION('',(1.,0.));
+#169 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#170 = ORIENTED_EDGE('',*,*,#171,.T.);
+#171 = EDGE_CURVE('',#142,#172,#174,.T.);
+#172 = VERTEX_POINT('',#173);
+#173 = CARTESIAN_POINT('',(40.,20.,-2.5));
+#174 = SURFACE_CURVE('',#175,(#179,#186),.PCURVE_S1.);
+#175 = LINE('',#176,#177);
+#176 = CARTESIAN_POINT('',(40.,-20.,-2.5));
+#177 = VECTOR('',#178,1.);
+#178 = DIRECTION('',(0.,1.,0.));
+#179 = PCURVE('',#152,#180);
+#180 = DEFINITIONAL_REPRESENTATION('',(#181),#185);
+#181 = LINE('',#182,#183);
+#182 = CARTESIAN_POINT('',(0.,0.));
+#183 = VECTOR('',#184,1.);
+#184 = DIRECTION('',(0.,-1.));
+#185 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#186 = PCURVE('',#72,#187);
+#187 = DEFINITIONAL_REPRESENTATION('',(#188),#192);
+#188 = LINE('',#189,#190);
+#189 = CARTESIAN_POINT('',(80.,0.));
+#190 = VECTOR('',#191,1.);
+#191 = DIRECTION('',(0.,1.));
+#192 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#193 = ORIENTED_EDGE('',*,*,#194,.T.);
+#194 = EDGE_CURVE('',#172,#195,#197,.T.);
+#195 = VERTEX_POINT('',#196);
+#196 = CARTESIAN_POINT('',(40.,20.,2.5));
+#197 = SURFACE_CURVE('',#198,(#202,#209),.PCURVE_S1.);
+#198 = LINE('',#199,#200);
+#199 = CARTESIAN_POINT('',(40.,20.,-2.5));
+#200 = VECTOR('',#201,1.);
+#201 = DIRECTION('',(0.,0.,1.));
+#202 = PCURVE('',#152,#203);
+#203 = DEFINITIONAL_REPRESENTATION('',(#204),#208);
+#204 = LINE('',#205,#206);
+#205 = CARTESIAN_POINT('',(0.,-40.));
+#206 = VECTOR('',#207,1.);
+#207 = DIRECTION('',(1.,0.));
+#208 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#209 = PCURVE('',#100,#210);
+#210 = DEFINITIONAL_REPRESENTATION('',(#211),#215);
+#211 = LINE('',#212,#213);
+#212 = CARTESIAN_POINT('',(0.,80.));
+#213 = VECTOR('',#214,1.);
+#214 = DIRECTION('',(1.,0.));
+#215 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#216 = ORIENTED_EDGE('',*,*,#217,.F.);
+#217 = EDGE_CURVE('',#144,#195,#218,.T.);
+#218 = SURFACE_CURVE('',#219,(#223,#230),.PCURVE_S1.);
+#219 = LINE('',#220,#221);
+#220 = CARTESIAN_POINT('',(40.,-20.,2.5));
+#221 = VECTOR('',#222,1.);
+#222 = DIRECTION('',(0.,1.,0.));
+#223 = PCURVE('',#152,#224);
+#224 = DEFINITIONAL_REPRESENTATION('',(#225),#229);
+#225 = LINE('',#226,#227);
+#226 = CARTESIAN_POINT('',(5.,0.));
+#227 = VECTOR('',#228,1.);
+#228 = DIRECTION('',(0.,-1.));
+#229 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#230 = PCURVE('',#126,#231);
+#231 = DEFINITIONAL_REPRESENTATION('',(#232),#236);
+#232 = LINE('',#233,#234);
+#233 = CARTESIAN_POINT('',(80.,0.));
+#234 = VECTOR('',#235,1.);
+#235 = DIRECTION('',(0.,1.));
+#236 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#237 = ADVANCED_FACE('',(#238),#44,.F.);
+#238 = FACE_BOUND('',#239,.F.);
+#239 = EDGE_LOOP('',(#240,#261,#262,#283));
+#240 = ORIENTED_EDGE('',*,*,#241,.F.);
+#241 = EDGE_CURVE('',#22,#142,#242,.T.);
+#242 = SURFACE_CURVE('',#243,(#247,#254),.PCURVE_S1.);
+#243 = LINE('',#244,#245);
+#244 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#245 = VECTOR('',#246,1.);
+#246 = DIRECTION('',(1.,0.,0.));
+#247 = PCURVE('',#44,#248);
+#248 = DEFINITIONAL_REPRESENTATION('',(#249),#253);
+#249 = LINE('',#250,#251);
+#250 = CARTESIAN_POINT('',(0.,0.));
+#251 = VECTOR('',#252,1.);
+#252 = DIRECTION('',(0.,1.));
+#253 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#254 = PCURVE('',#72,#255);
+#255 = DEFINITIONAL_REPRESENTATION('',(#256),#260);
+#256 = LINE('',#257,#258);
+#257 = CARTESIAN_POINT('',(0.,0.));
+#258 = VECTOR('',#259,1.);
+#259 = DIRECTION('',(1.,0.));
+#260 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#261 = ORIENTED_EDGE('',*,*,#21,.T.);
+#262 = ORIENTED_EDGE('',*,*,#263,.T.);
+#263 = EDGE_CURVE('',#24,#144,#264,.T.);
+#264 = SURFACE_CURVE('',#265,(#269,#276),.PCURVE_S1.);
+#265 = LINE('',#266,#267);
+#266 = CARTESIAN_POINT('',(-40.,-20.,2.5));
+#267 = VECTOR('',#268,1.);
+#268 = DIRECTION('',(1.,0.,0.));
+#269 = PCURVE('',#44,#270);
+#270 = DEFINITIONAL_REPRESENTATION('',(#271),#275);
+#271 = LINE('',#272,#273);
+#272 = CARTESIAN_POINT('',(5.,0.));
+#273 = VECTOR('',#274,1.);
+#274 = DIRECTION('',(0.,1.));
+#275 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#276 = PCURVE('',#126,#277);
+#277 = DEFINITIONAL_REPRESENTATION('',(#278),#282);
+#278 = LINE('',#279,#280);
+#279 = CARTESIAN_POINT('',(0.,0.));
+#280 = VECTOR('',#281,1.);
+#281 = DIRECTION('',(1.,0.));
+#282 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#283 = ORIENTED_EDGE('',*,*,#141,.F.);
+#284 = ADVANCED_FACE('',(#285),#100,.T.);
+#285 = FACE_BOUND('',#286,.T.);
+#286 = EDGE_LOOP('',(#287,#308,#309,#330));
+#287 = ORIENTED_EDGE('',*,*,#288,.F.);
+#288 = EDGE_CURVE('',#57,#172,#289,.T.);
+#289 = SURFACE_CURVE('',#290,(#294,#301),.PCURVE_S1.);
+#290 = LINE('',#291,#292);
+#291 = CARTESIAN_POINT('',(-40.,20.,-2.5));
+#292 = VECTOR('',#293,1.);
+#293 = DIRECTION('',(1.,0.,0.));
+#294 = PCURVE('',#100,#295);
+#295 = DEFINITIONAL_REPRESENTATION('',(#296),#300);
+#296 = LINE('',#297,#298);
+#297 = CARTESIAN_POINT('',(0.,0.));
+#298 = VECTOR('',#299,1.);
+#299 = DIRECTION('',(0.,1.));
+#300 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#301 = PCURVE('',#72,#302);
+#302 = DEFINITIONAL_REPRESENTATION('',(#303),#307);
+#303 = LINE('',#304,#305);
+#304 = CARTESIAN_POINT('',(0.,40.));
+#305 = VECTOR('',#306,1.);
+#306 = DIRECTION('',(1.,0.));
+#307 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#308 = ORIENTED_EDGE('',*,*,#84,.T.);
+#309 = ORIENTED_EDGE('',*,*,#310,.T.);
+#310 = EDGE_CURVE('',#85,#195,#311,.T.);
+#311 = SURFACE_CURVE('',#312,(#316,#323),.PCURVE_S1.);
+#312 = LINE('',#313,#314);
+#313 = CARTESIAN_POINT('',(-40.,20.,2.5));
+#314 = VECTOR('',#315,1.);
+#315 = DIRECTION('',(1.,0.,0.));
+#316 = PCURVE('',#100,#317);
+#317 = DEFINITIONAL_REPRESENTATION('',(#318),#322);
+#318 = LINE('',#319,#320);
+#319 = CARTESIAN_POINT('',(5.,0.));
+#320 = VECTOR('',#321,1.);
+#321 = DIRECTION('',(0.,1.));
+#322 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#323 = PCURVE('',#126,#324);
+#324 = DEFINITIONAL_REPRESENTATION('',(#325),#329);
+#325 = LINE('',#326,#327);
+#326 = CARTESIAN_POINT('',(0.,40.));
+#327 = VECTOR('',#328,1.);
+#328 = DIRECTION('',(1.,0.));
+#329 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#330 = ORIENTED_EDGE('',*,*,#194,.F.);
+#331 = ADVANCED_FACE('',(#332),#72,.F.);
+#332 = FACE_BOUND('',#333,.F.);
+#333 = EDGE_LOOP('',(#334,#335,#336,#337));
+#334 = ORIENTED_EDGE('',*,*,#56,.F.);
+#335 = ORIENTED_EDGE('',*,*,#241,.T.);
+#336 = ORIENTED_EDGE('',*,*,#171,.T.);
+#337 = ORIENTED_EDGE('',*,*,#288,.F.);
+#338 = ADVANCED_FACE('',(#339),#126,.T.);
+#339 = FACE_BOUND('',#340,.T.);
+#340 = EDGE_LOOP('',(#341,#342,#343,#344));
+#341 = ORIENTED_EDGE('',*,*,#112,.F.);
+#342 = ORIENTED_EDGE('',*,*,#263,.T.);
+#343 = ORIENTED_EDGE('',*,*,#217,.T.);
+#344 = ORIENTED_EDGE('',*,*,#310,.F.);
+#345 = ( GEOMETRIC_REPRESENTATION_CONTEXT(3) 
+GLOBAL_UNCERTAINTY_ASSIGNED_CONTEXT((#349)) GLOBAL_UNIT_ASSIGNED_CONTEXT
+((#346,#347,#348)) REPRESENTATION_CONTEXT('Context #1',
+  '3D Context with UNIT and UNCERTAINTY') );
+#346 = ( LENGTH_UNIT() NAMED_UNIT(*) SI_UNIT(.MILLI.,.METRE.) );
+#347 = ( NAMED_UNIT(*) PLANE_ANGLE_UNIT() SI_UNIT($,.RADIAN.) );
+#348 = ( NAMED_UNIT(*) SI_UNIT($,.STERADIAN.) SOLID_ANGLE_UNIT() );
+#349 = UNCERTAINTY_MEASURE_WITH_UNIT(LENGTH_MEASURE(1.E-07),#346,
+  'distance_accuracy_value','confusion accuracy');
+#350 = PRODUCT_RELATED_PRODUCT_CATEGORY('part',$,(#7));
+ENDSEC;
+END-ISO-10303-21;

server/tasks/task_001_flat_plate/ground_truth_normalized.step

@@ -0,0 +1,416 @@
+ISO-10303-21;
+HEADER;
+FILE_DESCRIPTION(('Open CASCADE Model'),'2;1');
+FILE_NAME('Open CASCADE Shape Model','2026-04-25T17:44:28',('Author'),(
+    'Open CASCADE'),'Open CASCADE STEP processor 7.8','Open CASCADE 7.8'
+  ,'Unknown');
+FILE_SCHEMA(('AUTOMOTIVE_DESIGN { 1 0 10303 214 1 1 1 1 }'));
+ENDSEC;
+DATA;
+#1 = APPLICATION_PROTOCOL_DEFINITION('international standard',
+  'automotive_design',2000,#2);
+#2 = APPLICATION_CONTEXT(
+  'core data for automotive mechanical design processes');
+#3 = SHAPE_DEFINITION_REPRESENTATION(#4,#10);
+#4 = PRODUCT_DEFINITION_SHAPE('','',#5);
+#5 = PRODUCT_DEFINITION('design','',#6,#9);
+#6 = PRODUCT_DEFINITION_FORMATION('','',#7);
+#7 = PRODUCT('Open CASCADE STEP translator 7.8 2',
+  'Open CASCADE STEP translator 7.8 2','',(#8));
+#8 = PRODUCT_CONTEXT('',#2,'mechanical');
+#9 = PRODUCT_DEFINITION_CONTEXT('part definition',#2,'design');
+#10 = ADVANCED_BREP_SHAPE_REPRESENTATION('',(#11,#15),#345);
+#11 = AXIS2_PLACEMENT_3D('',#12,#13,#14);
+#12 = CARTESIAN_POINT('',(0.,0.,0.));
+#13 = DIRECTION('',(0.,0.,1.));
+#14 = DIRECTION('',(1.,0.,-0.));
+#15 = MANIFOLD_SOLID_BREP('',#16);
+#16 = CLOSED_SHELL('',(#17,#137,#237,#284,#331,#338));
+#17 = ADVANCED_FACE('',(#18),#32,.F.);
+#18 = FACE_BOUND('',#19,.F.);
+#19 = EDGE_LOOP('',(#20,#55,#83,#111));
+#20 = ORIENTED_EDGE('',*,*,#21,.F.);
+#21 = EDGE_CURVE('',#22,#24,#26,.T.);
+#22 = VERTEX_POINT('',#23);
+#23 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#24 = VERTEX_POINT('',#25);
+#25 = CARTESIAN_POINT('',(-40.,-20.,2.5));
+#26 = SURFACE_CURVE('',#27,(#31,#43),.PCURVE_S1.);
+#27 = LINE('',#28,#29);
+#28 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#29 = VECTOR('',#30,1.);
+#30 = DIRECTION('',(0.,0.,1.));
+#31 = PCURVE('',#32,#37);
+#32 = PLANE('',#33);
+#33 = AXIS2_PLACEMENT_3D('',#34,#35,#36);
+#34 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#35 = DIRECTION('',(1.,0.,0.));
+#36 = DIRECTION('',(0.,0.,1.));
+#37 = DEFINITIONAL_REPRESENTATION('',(#38),#42);
+#38 = LINE('',#39,#40);
+#39 = CARTESIAN_POINT('',(0.,0.));
+#40 = VECTOR('',#41,1.);
+#41 = DIRECTION('',(1.,0.));
+#42 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#43 = PCURVE('',#44,#49);
+#44 = PLANE('',#45);
+#45 = AXIS2_PLACEMENT_3D('',#46,#47,#48);
+#46 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#47 = DIRECTION('',(0.,1.,0.));
+#48 = DIRECTION('',(0.,0.,1.));
+#49 = DEFINITIONAL_REPRESENTATION('',(#50),#54);
+#50 = LINE('',#51,#52);
+#51 = CARTESIAN_POINT('',(0.,0.));
+#52 = VECTOR('',#53,1.);
+#53 = DIRECTION('',(1.,0.));
+#54 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#55 = ORIENTED_EDGE('',*,*,#56,.T.);
+#56 = EDGE_CURVE('',#22,#57,#59,.T.);
+#57 = VERTEX_POINT('',#58);
+#58 = CARTESIAN_POINT('',(-40.,20.,-2.5));
+#59 = SURFACE_CURVE('',#60,(#64,#71),.PCURVE_S1.);
+#60 = LINE('',#61,#62);
+#61 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#62 = VECTOR('',#63,1.);
+#63 = DIRECTION('',(0.,1.,0.));
+#64 = PCURVE('',#32,#65);
+#65 = DEFINITIONAL_REPRESENTATION('',(#66),#70);
+#66 = LINE('',#67,#68);
+#67 = CARTESIAN_POINT('',(0.,0.));
+#68 = VECTOR('',#69,1.);
+#69 = DIRECTION('',(0.,-1.));
+#70 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#71 = PCURVE('',#72,#77);
+#72 = PLANE('',#73);
+#73 = AXIS2_PLACEMENT_3D('',#74,#75,#76);
+#74 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#75 = DIRECTION('',(0.,0.,1.));
+#76 = DIRECTION('',(1.,0.,0.));
+#77 = DEFINITIONAL_REPRESENTATION('',(#78),#82);
+#78 = LINE('',#79,#80);
+#79 = CARTESIAN_POINT('',(0.,0.));
+#80 = VECTOR('',#81,1.);
+#81 = DIRECTION('',(0.,1.));
+#82 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#83 = ORIENTED_EDGE('',*,*,#84,.T.);
+#84 = EDGE_CURVE('',#57,#85,#87,.T.);
+#85 = VERTEX_POINT('',#86);
+#86 = CARTESIAN_POINT('',(-40.,20.,2.5));
+#87 = SURFACE_CURVE('',#88,(#92,#99),.PCURVE_S1.);
+#88 = LINE('',#89,#90);
+#89 = CARTESIAN_POINT('',(-40.,20.,-2.5));
+#90 = VECTOR('',#91,1.);
+#91 = DIRECTION('',(0.,0.,1.));
+#92 = PCURVE('',#32,#93);
+#93 = DEFINITIONAL_REPRESENTATION('',(#94),#98);
+#94 = LINE('',#95,#96);
+#95 = CARTESIAN_POINT('',(0.,-40.));
+#96 = VECTOR('',#97,1.);
+#97 = DIRECTION('',(1.,0.));
+#98 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#99 = PCURVE('',#100,#105);
+#100 = PLANE('',#101);
+#101 = AXIS2_PLACEMENT_3D('',#102,#103,#104);
+#102 = CARTESIAN_POINT('',(-40.,20.,-2.5));
+#103 = DIRECTION('',(0.,1.,0.));
+#104 = DIRECTION('',(0.,0.,1.));
+#105 = DEFINITIONAL_REPRESENTATION('',(#106),#110);
+#106 = LINE('',#107,#108);
+#107 = CARTESIAN_POINT('',(0.,0.));
+#108 = VECTOR('',#109,1.);
+#109 = DIRECTION('',(1.,0.));
+#110 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#111 = ORIENTED_EDGE('',*,*,#112,.F.);
+#112 = EDGE_CURVE('',#24,#85,#113,.T.);
+#113 = SURFACE_CURVE('',#114,(#118,#125),.PCURVE_S1.);
+#114 = LINE('',#115,#116);
+#115 = CARTESIAN_POINT('',(-40.,-20.,2.5));
+#116 = VECTOR('',#117,1.);
+#117 = DIRECTION('',(0.,1.,0.));
+#118 = PCURVE('',#32,#119);
+#119 = DEFINITIONAL_REPRESENTATION('',(#120),#124);
+#120 = LINE('',#121,#122);
+#121 = CARTESIAN_POINT('',(5.,0.));
+#122 = VECTOR('',#123,1.);
+#123 = DIRECTION('',(0.,-1.));
+#124 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#125 = PCURVE('',#126,#131);
+#126 = PLANE('',#127);
+#127 = AXIS2_PLACEMENT_3D('',#128,#129,#130);
+#128 = CARTESIAN_POINT('',(-40.,-20.,2.5));
+#129 = DIRECTION('',(0.,0.,1.));
+#130 = DIRECTION('',(1.,0.,0.));
+#131 = DEFINITIONAL_REPRESENTATION('',(#132),#136);
+#132 = LINE('',#133,#134);
+#133 = CARTESIAN_POINT('',(0.,0.));
+#134 = VECTOR('',#135,1.);
+#135 = DIRECTION('',(0.,1.));
+#136 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#137 = ADVANCED_FACE('',(#138),#152,.T.);
+#138 = FACE_BOUND('',#139,.T.);
+#139 = EDGE_LOOP('',(#140,#170,#193,#216));
+#140 = ORIENTED_EDGE('',*,*,#141,.F.);
+#141 = EDGE_CURVE('',#142,#144,#146,.T.);
+#142 = VERTEX_POINT('',#143);
+#143 = CARTESIAN_POINT('',(40.,-20.,-2.5));
+#144 = VERTEX_POINT('',#145);
+#145 = CARTESIAN_POINT('',(40.,-20.,2.5));
+#146 = SURFACE_CURVE('',#147,(#151,#163),.PCURVE_S1.);
+#147 = LINE('',#148,#149);
+#148 = CARTESIAN_POINT('',(40.,-20.,-2.5));
+#149 = VECTOR('',#150,1.);
+#150 = DIRECTION('',(0.,0.,1.));
+#151 = PCURVE('',#152,#157);
+#152 = PLANE('',#153);
+#153 = AXIS2_PLACEMENT_3D('',#154,#155,#156);
+#154 = CARTESIAN_POINT('',(40.,-20.,-2.5));
+#155 = DIRECTION('',(1.,0.,0.));
+#156 = DIRECTION('',(0.,0.,1.));
+#157 = DEFINITIONAL_REPRESENTATION('',(#158),#162);
+#158 = LINE('',#159,#160);
+#159 = CARTESIAN_POINT('',(0.,0.));
+#160 = VECTOR('',#161,1.);
+#161 = DIRECTION('',(1.,0.));
+#162 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#163 = PCURVE('',#44,#164);
+#164 = DEFINITIONAL_REPRESENTATION('',(#165),#169);
+#165 = LINE('',#166,#167);
+#166 = CARTESIAN_POINT('',(0.,80.));
+#167 = VECTOR('',#168,1.);
+#168 = DIRECTION('',(1.,0.));
+#169 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#170 = ORIENTED_EDGE('',*,*,#171,.T.);
+#171 = EDGE_CURVE('',#142,#172,#174,.T.);
+#172 = VERTEX_POINT('',#173);
+#173 = CARTESIAN_POINT('',(40.,20.,-2.5));
+#174 = SURFACE_CURVE('',#175,(#179,#186),.PCURVE_S1.);
+#175 = LINE('',#176,#177);
+#176 = CARTESIAN_POINT('',(40.,-20.,-2.5));
+#177 = VECTOR('',#178,1.);
+#178 = DIRECTION('',(0.,1.,0.));
+#179 = PCURVE('',#152,#180);
+#180 = DEFINITIONAL_REPRESENTATION('',(#181),#185);
+#181 = LINE('',#182,#183);
+#182 = CARTESIAN_POINT('',(0.,0.));
+#183 = VECTOR('',#184,1.);
+#184 = DIRECTION('',(0.,-1.));
+#185 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#186 = PCURVE('',#72,#187);
+#187 = DEFINITIONAL_REPRESENTATION('',(#188),#192);
+#188 = LINE('',#189,#190);
+#189 = CARTESIAN_POINT('',(80.,0.));
+#190 = VECTOR('',#191,1.);
+#191 = DIRECTION('',(0.,1.));
+#192 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#193 = ORIENTED_EDGE('',*,*,#194,.T.);
+#194 = EDGE_CURVE('',#172,#195,#197,.T.);
+#195 = VERTEX_POINT('',#196);
+#196 = CARTESIAN_POINT('',(40.,20.,2.5));
+#197 = SURFACE_CURVE('',#198,(#202,#209),.PCURVE_S1.);
+#198 = LINE('',#199,#200);
+#199 = CARTESIAN_POINT('',(40.,20.,-2.5));
+#200 = VECTOR('',#201,1.);
+#201 = DIRECTION('',(0.,0.,1.));
+#202 = PCURVE('',#152,#203);
+#203 = DEFINITIONAL_REPRESENTATION('',(#204),#208);
+#204 = LINE('',#205,#206);
+#205 = CARTESIAN_POINT('',(0.,-40.));
+#206 = VECTOR('',#207,1.);
+#207 = DIRECTION('',(1.,0.));
+#208 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#209 = PCURVE('',#100,#210);
+#210 = DEFINITIONAL_REPRESENTATION('',(#211),#215);
+#211 = LINE('',#212,#213);
+#212 = CARTESIAN_POINT('',(0.,80.));
+#213 = VECTOR('',#214,1.);
+#214 = DIRECTION('',(1.,0.));
+#215 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#216 = ORIENTED_EDGE('',*,*,#217,.F.);
+#217 = EDGE_CURVE('',#144,#195,#218,.T.);
+#218 = SURFACE_CURVE('',#219,(#223,#230),.PCURVE_S1.);
+#219 = LINE('',#220,#221);
+#220 = CARTESIAN_POINT('',(40.,-20.,2.5));
+#221 = VECTOR('',#222,1.);
+#222 = DIRECTION('',(0.,1.,0.));
+#223 = PCURVE('',#152,#224);
+#224 = DEFINITIONAL_REPRESENTATION('',(#225),#229);
+#225 = LINE('',#226,#227);
+#226 = CARTESIAN_POINT('',(5.,0.));
+#227 = VECTOR('',#228,1.);
+#228 = DIRECTION('',(0.,-1.));
+#229 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#230 = PCURVE('',#126,#231);
+#231 = DEFINITIONAL_REPRESENTATION('',(#232),#236);
+#232 = LINE('',#233,#234);
+#233 = CARTESIAN_POINT('',(80.,0.));
+#234 = VECTOR('',#235,1.);
+#235 = DIRECTION('',(0.,1.));
+#236 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#237 = ADVANCED_FACE('',(#238),#44,.F.);
+#238 = FACE_BOUND('',#239,.F.);
+#239 = EDGE_LOOP('',(#240,#261,#262,#283));
+#240 = ORIENTED_EDGE('',*,*,#241,.F.);
+#241 = EDGE_CURVE('',#22,#142,#242,.T.);
+#242 = SURFACE_CURVE('',#243,(#247,#254),.PCURVE_S1.);
+#243 = LINE('',#244,#245);
+#244 = CARTESIAN_POINT('',(-40.,-20.,-2.5));
+#245 = VECTOR('',#246,1.);
+#246 = DIRECTION('',(1.,0.,0.));
+#247 = PCURVE('',#44,#248);
+#248 = DEFINITIONAL_REPRESENTATION('',(#249),#253);
+#249 = LINE('',#250,#251);
+#250 = CARTESIAN_POINT('',(0.,0.));
+#251 = VECTOR('',#252,1.);
+#252 = DIRECTION('',(0.,1.));
+#253 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#254 = PCURVE('',#72,#255);
+#255 = DEFINITIONAL_REPRESENTATION('',(#256),#260);
+#256 = LINE('',#257,#258);
+#257 = CARTESIAN_POINT('',(0.,0.));
+#258 = VECTOR('',#259,1.);
+#259 = DIRECTION('',(1.,0.));
+#260 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#261 = ORIENTED_EDGE('',*,*,#21,.T.);
+#262 = ORIENTED_EDGE('',*,*,#263,.T.);
+#263 = EDGE_CURVE('',#24,#144,#264,.T.);
+#264 = SURFACE_CURVE('',#265,(#269,#276),.PCURVE_S1.);
+#265 = LINE('',#266,#267);
+#266 = CARTESIAN_POINT('',(-40.,-20.,2.5));
+#267 = VECTOR('',#268,1.);
+#268 = DIRECTION('',(1.,0.,0.));
+#269 = PCURVE('',#44,#270);
+#270 = DEFINITIONAL_REPRESENTATION('',(#271),#275);
+#271 = LINE('',#272,#273);
+#272 = CARTESIAN_POINT('',(5.,0.));
+#273 = VECTOR('',#274,1.);
+#274 = DIRECTION('',(0.,1.));
+#275 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#276 = PCURVE('',#126,#277);
+#277 = DEFINITIONAL_REPRESENTATION('',(#278),#282);
+#278 = LINE('',#279,#280);
+#279 = CARTESIAN_POINT('',(0.,0.));
+#280 = VECTOR('',#281,1.);
+#281 = DIRECTION('',(1.,0.));
+#282 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#283 = ORIENTED_EDGE('',*,*,#141,.F.);
+#284 = ADVANCED_FACE('',(#285),#100,.T.);
+#285 = FACE_BOUND('',#286,.T.);
+#286 = EDGE_LOOP('',(#287,#308,#309,#330));
+#287 = ORIENTED_EDGE('',*,*,#288,.F.);
+#288 = EDGE_CURVE('',#57,#172,#289,.T.);
+#289 = SURFACE_CURVE('',#290,(#294,#301),.PCURVE_S1.);
+#290 = LINE('',#291,#292);
+#291 = CARTESIAN_POINT('',(-40.,20.,-2.5));
+#292 = VECTOR('',#293,1.);
+#293 = DIRECTION('',(1.,0.,0.));
+#294 = PCURVE('',#100,#295);
+#295 = DEFINITIONAL_REPRESENTATION('',(#296),#300);
+#296 = LINE('',#297,#298);
+#297 = CARTESIAN_POINT('',(0.,0.));
+#298 = VECTOR('',#299,1.);
+#299 = DIRECTION('',(0.,1.));
+#300 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#301 = PCURVE('',#72,#302);
+#302 = DEFINITIONAL_REPRESENTATION('',(#303),#307);
+#303 = LINE('',#304,#305);
+#304 = CARTESIAN_POINT('',(0.,40.));
+#305 = VECTOR('',#306,1.);
+#306 = DIRECTION('',(1.,0.));
+#307 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#308 = ORIENTED_EDGE('',*,*,#84,.T.);
+#309 = ORIENTED_EDGE('',*,*,#310,.T.);
+#310 = EDGE_CURVE('',#85,#195,#311,.T.);
+#311 = SURFACE_CURVE('',#312,(#316,#323),.PCURVE_S1.);
+#312 = LINE('',#313,#314);
+#313 = CARTESIAN_POINT('',(-40.,20.,2.5));
+#314 = VECTOR('',#315,1.);
+#315 = DIRECTION('',(1.,0.,0.));
+#316 = PCURVE('',#100,#317);
+#317 = DEFINITIONAL_REPRESENTATION('',(#318),#322);
+#318 = LINE('',#319,#320);
+#319 = CARTESIAN_POINT('',(5.,0.));
+#320 = VECTOR('',#321,1.);
+#321 = DIRECTION('',(0.,1.));
+#322 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#323 = PCURVE('',#126,#324);
+#324 = DEFINITIONAL_REPRESENTATION('',(#325),#329);
+#325 = LINE('',#326,#327);
+#326 = CARTESIAN_POINT('',(0.,40.));
+#327 = VECTOR('',#328,1.);
+#328 = DIRECTION('',(1.,0.));
+#329 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#330 = ORIENTED_EDGE('',*,*,#194,.F.);
+#331 = ADVANCED_FACE('',(#332),#72,.F.);
+#332 = FACE_BOUND('',#333,.F.);
+#333 = EDGE_LOOP('',(#334,#335,#336,#337));
+#334 = ORIENTED_EDGE('',*,*,#56,.F.);
+#335 = ORIENTED_EDGE('',*,*,#241,.T.);
+#336 = ORIENTED_EDGE('',*,*,#171,.T.);
+#337 = ORIENTED_EDGE('',*,*,#288,.F.);
+#338 = ADVANCED_FACE('',(#339),#126,.T.);
+#339 = FACE_BOUND('',#340,.T.);
+#340 = EDGE_LOOP('',(#341,#342,#343,#344));
+#341 = ORIENTED_EDGE('',*,*,#112,.F.);
+#342 = ORIENTED_EDGE('',*,*,#263,.T.);
+#343 = ORIENTED_EDGE('',*,*,#217,.T.);
+#344 = ORIENTED_EDGE('',*,*,#310,.F.);
+#345 = ( GEOMETRIC_REPRESENTATION_CONTEXT(3) 
+GLOBAL_UNCERTAINTY_ASSIGNED_CONTEXT((#349)) GLOBAL_UNIT_ASSIGNED_CONTEXT
+((#346,#347,#348)) REPRESENTATION_CONTEXT('Context #1',
+  '3D Context with UNIT and UNCERTAINTY') );
+#346 = ( LENGTH_UNIT() NAMED_UNIT(*) SI_UNIT(.MILLI.,.METRE.) );
+#347 = ( NAMED_UNIT(*) PLANE_ANGLE_UNIT() SI_UNIT($,.RADIAN.) );
+#348 = ( NAMED_UNIT(*) SI_UNIT($,.STERADIAN.) SOLID_ANGLE_UNIT() );
+#349 = UNCERTAINTY_MEASURE_WITH_UNIT(LENGTH_MEASURE(1.E-07),#346,
+  'distance_accuracy_value','confusion accuracy');
+#350 = PRODUCT_RELATED_PRODUCT_CATEGORY('part',$,(#7));
+ENDSEC;
+END-ISO-10303-21;

server/tasks/task_001_flat_plate/reference_code.py

@@ -0,0 +1,2 @@
+import cadquery as cq
+result = cq.Workplane("XY").box(80, 40, 5)

server/tasks/task_001_flat_plate/surface_points.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2d18b2112728d40eb99ff7ee970f562d4f3fbfa29c6f16bc85e6e01cfddc1a4f
+size 24704

server/tasks/task_001_flat_plate/task.json

@@ -0,0 +1,10 @@
+{
+  "id": "task_001_flat_plate",
+  "part_class": "flat plate",
+  "difficulty_bin": 1,
+  "max_steps": 10,
+  "prompt": "Create a solid flat rectangular plate made of a single block of material. The plate measures exactly 80 millimeters along the X axis, 40 millimeters along the Y axis, and 5 millimeters along the Z axis. The bottom face of the plate sits flush on the XY plane. The plate has no holes, no chamfers, no fillets, and no other features. It is a plain rectangular solid. Orient the longest axis along X.",
+  "ground_truth_step": "tasks/task_001_flat_plate/ground_truth.step",
+  "ground_truth_json": "tasks/task_001_flat_plate/ground_truth.json",
+  "reference_code": "tasks/task_001_flat_plate/reference_code.py"
+}

server/tasks/task_001_flat_plate/voxels_64.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5d029cfdec59acafbd813c82ddea228d541ec16cc6bee655108120bd95682c32
+size 262272

server/tasks/task_002_box_with_hole/ground_truth.json

@@ -0,0 +1,42 @@
+{
+  "source_step": "tasks/task_002_box_with_hole/ground_truth.step",
+  "volume_mm3": 28429.2037,
+  "surface_area_mm2": 6671.2389,
+  "bbox_mm": [
+    50.0,
+    30.0,
+    20.0031
+  ],
+  "face_count": 7,
+  "face_types": [
+    "PLANE",
+    "CYLINDER"
+  ],
+  "dominant_face_type": "PLANE",
+  "hole_count": 1,
+  "hole_diameters_mm": [
+    10.0
+  ],
+  "euler_characteristic": 2,
+  "surface_points_file": "surface_points.npy",
+  "voxels_file": "voxels_64.npy",
+  "canonical_transform": {
+    "units": "mm",
+    "translation_to_origin": [
+      0.0,
+      0.0,
+      0.0
+    ],
+    "axis_alignment": [
+      "X",
+      "Y",
+      "Z"
+    ],
+    "longest_axis": "X"
+  },
+  "original_bbox_mm": [
+    50.0,
+    30.0,
+    20.0
+  ]
+}

server/tasks/task_002_box_with_hole/ground_truth.step

@@ -0,0 +1,533 @@
+ISO-10303-21;
+HEADER;
+FILE_DESCRIPTION(('Open CASCADE Model'),'2;1');
+FILE_NAME('Open CASCADE Shape Model','2026-04-25T17:44:29',('Author'),(
+    'Open CASCADE'),'Open CASCADE STEP processor 7.8','Open CASCADE 7.8'
+  ,'Unknown');
+FILE_SCHEMA(('AUTOMOTIVE_DESIGN { 1 0 10303 214 1 1 1 1 }'));
+ENDSEC;
+DATA;
+#1 = APPLICATION_PROTOCOL_DEFINITION('international standard',
+  'automotive_design',2000,#2);
+#2 = APPLICATION_CONTEXT(
+  'core data for automotive mechanical design processes');
+#3 = SHAPE_DEFINITION_REPRESENTATION(#4,#10);
+#4 = PRODUCT_DEFINITION_SHAPE('','',#5);
+#5 = PRODUCT_DEFINITION('design','',#6,#9);
+#6 = PRODUCT_DEFINITION_FORMATION('','',#7);
+#7 = PRODUCT('Open CASCADE STEP translator 7.8 3',
+  'Open CASCADE STEP translator 7.8 3','',(#8));
+#8 = PRODUCT_CONTEXT('',#2,'mechanical');
+#9 = PRODUCT_DEFINITION_CONTEXT('part definition',#2,'design');
+#10 = ADVANCED_BREP_SHAPE_REPRESENTATION('',(#11,#15),#437);
+#11 = AXIS2_PLACEMENT_3D('',#12,#13,#14);
+#12 = CARTESIAN_POINT('',(0.,0.,0.));
+#13 = DIRECTION('',(0.,0.,1.));
+#14 = DIRECTION('',(1.,0.,-0.));
+#15 = MANIFOLD_SOLID_BREP('',#16);
+#16 = CLOSED_SHELL('',(#17,#137,#213,#297,#346,#403,#410));
+#17 = ADVANCED_FACE('',(#18),#32,.F.);
+#18 = FACE_BOUND('',#19,.F.);
+#19 = EDGE_LOOP('',(#20,#55,#83,#111));
+#20 = ORIENTED_EDGE('',*,*,#21,.F.);
+#21 = EDGE_CURVE('',#22,#24,#26,.T.);
+#22 = VERTEX_POINT('',#23);
+#23 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#24 = VERTEX_POINT('',#25);
+#25 = CARTESIAN_POINT('',(-25.,-15.,10.));
+#26 = SURFACE_CURVE('',#27,(#31,#43),.PCURVE_S1.);
+#27 = LINE('',#28,#29);
+#28 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#29 = VECTOR('',#30,1.);
+#30 = DIRECTION('',(0.,0.,1.));
+#31 = PCURVE('',#32,#37);
+#32 = PLANE('',#33);
+#33 = AXIS2_PLACEMENT_3D('',#34,#35,#36);
+#34 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#35 = DIRECTION('',(1.,0.,0.));
+#36 = DIRECTION('',(0.,0.,1.));
+#37 = DEFINITIONAL_REPRESENTATION('',(#38),#42);
+#38 = LINE('',#39,#40);
+#39 = CARTESIAN_POINT('',(0.,0.));
+#40 = VECTOR('',#41,1.);
+#41 = DIRECTION('',(1.,0.));
+#42 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#43 = PCURVE('',#44,#49);
+#44 = PLANE('',#45);
+#45 = AXIS2_PLACEMENT_3D('',#46,#47,#48);
+#46 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#47 = DIRECTION('',(0.,1.,0.));
+#48 = DIRECTION('',(0.,0.,1.));
+#49 = DEFINITIONAL_REPRESENTATION('',(#50),#54);
+#50 = LINE('',#51,#52);
+#51 = CARTESIAN_POINT('',(0.,0.));
+#52 = VECTOR('',#53,1.);
+#53 = DIRECTION('',(1.,0.));
+#54 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#55 = ORIENTED_EDGE('',*,*,#56,.T.);
+#56 = EDGE_CURVE('',#22,#57,#59,.T.);
+#57 = VERTEX_POINT('',#58);
+#58 = CARTESIAN_POINT('',(-25.,15.,-10.));
+#59 = SURFACE_CURVE('',#60,(#64,#71),.PCURVE_S1.);
+#60 = LINE('',#61,#62);
+#61 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#62 = VECTOR('',#63,1.);
+#63 = DIRECTION('',(0.,1.,0.));
+#64 = PCURVE('',#32,#65);
+#65 = DEFINITIONAL_REPRESENTATION('',(#66),#70);
+#66 = LINE('',#67,#68);
+#67 = CARTESIAN_POINT('',(0.,0.));
+#68 = VECTOR('',#69,1.);
+#69 = DIRECTION('',(0.,-1.));
+#70 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#71 = PCURVE('',#72,#77);
+#72 = PLANE('',#73);
+#73 = AXIS2_PLACEMENT_3D('',#74,#75,#76);
+#74 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#75 = DIRECTION('',(0.,0.,1.));
+#76 = DIRECTION('',(1.,0.,0.));
+#77 = DEFINITIONAL_REPRESENTATION('',(#78),#82);
+#78 = LINE('',#79,#80);
+#79 = CARTESIAN_POINT('',(0.,0.));
+#80 = VECTOR('',#81,1.);
+#81 = DIRECTION('',(0.,1.));
+#82 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#83 = ORIENTED_EDGE('',*,*,#84,.T.);
+#84 = EDGE_CURVE('',#57,#85,#87,.T.);
+#85 = VERTEX_POINT('',#86);
+#86 = CARTESIAN_POINT('',(-25.,15.,10.));
+#87 = SURFACE_CURVE('',#88,(#92,#99),.PCURVE_S1.);
+#88 = LINE('',#89,#90);
+#89 = CARTESIAN_POINT('',(-25.,15.,-10.));
+#90 = VECTOR('',#91,1.);
+#91 = DIRECTION('',(0.,0.,1.));
+#92 = PCURVE('',#32,#93);
+#93 = DEFINITIONAL_REPRESENTATION('',(#94),#98);
+#94 = LINE('',#95,#96);
+#95 = CARTESIAN_POINT('',(0.,-30.));
+#96 = VECTOR('',#97,1.);
+#97 = DIRECTION('',(1.,0.));
+#98 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#99 = PCURVE('',#100,#105);
+#100 = PLANE('',#101);
+#101 = AXIS2_PLACEMENT_3D('',#102,#103,#104);
+#102 = CARTESIAN_POINT('',(-25.,15.,-10.));
+#103 = DIRECTION('',(0.,1.,0.));
+#104 = DIRECTION('',(0.,0.,1.));
+#105 = DEFINITIONAL_REPRESENTATION('',(#106),#110);
+#106 = LINE('',#107,#108);
+#107 = CARTESIAN_POINT('',(0.,0.));
+#108 = VECTOR('',#109,1.);
+#109 = DIRECTION('',(1.,0.));
+#110 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#111 = ORIENTED_EDGE('',*,*,#112,.F.);
+#112 = EDGE_CURVE('',#24,#85,#113,.T.);
+#113 = SURFACE_CURVE('',#114,(#118,#125),.PCURVE_S1.);
+#114 = LINE('',#115,#116);
+#115 = CARTESIAN_POINT('',(-25.,-15.,10.));
+#116 = VECTOR('',#117,1.);
+#117 = DIRECTION('',(0.,1.,0.));
+#118 = PCURVE('',#32,#119);
+#119 = DEFINITIONAL_REPRESENTATION('',(#120),#124);
+#120 = LINE('',#121,#122);
+#121 = CARTESIAN_POINT('',(20.,0.));
+#122 = VECTOR('',#123,1.);
+#123 = DIRECTION('',(0.,-1.));
+#124 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#125 = PCURVE('',#126,#131);
+#126 = PLANE('',#127);
+#127 = AXIS2_PLACEMENT_3D('',#128,#129,#130);
+#128 = CARTESIAN_POINT('',(-25.,-15.,10.));
+#129 = DIRECTION('',(0.,0.,1.));
+#130 = DIRECTION('',(1.,0.,0.));
+#131 = DEFINITIONAL_REPRESENTATION('',(#132),#136);
+#132 = LINE('',#133,#134);
+#133 = CARTESIAN_POINT('',(0.,0.));
+#134 = VECTOR('',#135,1.);
+#135 = DIRECTION('',(0.,1.));
+#136 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#137 = ADVANCED_FACE('',(#138),#44,.F.);
+#138 = FACE_BOUND('',#139,.F.);
+#139 = EDGE_LOOP('',(#140,#163,#164,#187));
+#140 = ORIENTED_EDGE('',*,*,#141,.F.);
+#141 = EDGE_CURVE('',#22,#142,#144,.T.);
+#142 = VERTEX_POINT('',#143);
+#143 = CARTESIAN_POINT('',(25.,-15.,-10.));
+#144 = SURFACE_CURVE('',#145,(#149,#156),.PCURVE_S1.);
+#145 = LINE('',#146,#147);
+#146 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#147 = VECTOR('',#148,1.);
+#148 = DIRECTION('',(1.,0.,0.));
+#149 = PCURVE('',#44,#150);
+#150 = DEFINITIONAL_REPRESENTATION('',(#151),#155);
+#151 = LINE('',#152,#153);
+#152 = CARTESIAN_POINT('',(0.,0.));
+#153 = VECTOR('',#154,1.);
+#154 = DIRECTION('',(0.,1.));
+#155 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#156 = PCURVE('',#72,#157);
+#157 = DEFINITIONAL_REPRESENTATION('',(#158),#162);
+#158 = LINE('',#159,#160);
+#159 = CARTESIAN_POINT('',(0.,0.));
+#160 = VECTOR('',#161,1.);
+#161 = DIRECTION('',(1.,0.));
+#162 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#163 = ORIENTED_EDGE('',*,*,#21,.T.);
+#164 = ORIENTED_EDGE('',*,*,#165,.T.);
+#165 = EDGE_CURVE('',#24,#166,#168,.T.);
+#166 = VERTEX_POINT('',#167);
+#167 = CARTESIAN_POINT('',(25.,-15.,10.));
+#168 = SURFACE_CURVE('',#169,(#173,#180),.PCURVE_S1.);
+#169 = LINE('',#170,#171);
+#170 = CARTESIAN_POINT('',(-25.,-15.,10.));
+#171 = VECTOR('',#172,1.);
+#172 = DIRECTION('',(1.,0.,0.));
+#173 = PCURVE('',#44,#174);
+#174 = DEFINITIONAL_REPRESENTATION('',(#175),#179);
+#175 = LINE('',#176,#177);
+#176 = CARTESIAN_POINT('',(20.,0.));
+#177 = VECTOR('',#178,1.);
+#178 = DIRECTION('',(0.,1.));
+#179 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#180 = PCURVE('',#126,#181);
+#181 = DEFINITIONAL_REPRESENTATION('',(#182),#186);
+#182 = LINE('',#183,#184);
+#183 = CARTESIAN_POINT('',(0.,0.));
+#184 = VECTOR('',#185,1.);
+#185 = DIRECTION('',(1.,0.));
+#186 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#187 = ORIENTED_EDGE('',*,*,#188,.F.);
+#188 = EDGE_CURVE('',#142,#166,#189,.T.);
+#189 = SURFACE_CURVE('',#190,(#194,#201),.PCURVE_S1.);
+#190 = LINE('',#191,#192);
+#191 = CARTESIAN_POINT('',(25.,-15.,-10.));
+#192 = VECTOR('',#193,1.);
+#193 = DIRECTION('',(0.,0.,1.));
+#194 = PCURVE('',#44,#195);
+#195 = DEFINITIONAL_REPRESENTATION('',(#196),#200);
+#196 = LINE('',#197,#198);
+#197 = CARTESIAN_POINT('',(0.,50.));
+#198 = VECTOR('',#199,1.);
+#199 = DIRECTION('',(1.,0.));
+#200 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#201 = PCURVE('',#202,#207);
+#202 = PLANE('',#203);
+#203 = AXIS2_PLACEMENT_3D('',#204,#205,#206);
+#204 = CARTESIAN_POINT('',(25.,-15.,-10.));
+#205 = DIRECTION('',(1.,0.,0.));
+#206 = DIRECTION('',(0.,0.,1.));
+#207 = DEFINITIONAL_REPRESENTATION('',(#208),#212);
+#208 = LINE('',#209,#210);
+#209 = CARTESIAN_POINT('',(0.,0.));
+#210 = VECTOR('',#211,1.);
+#211 = DIRECTION('',(1.,0.));
+#212 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#213 = ADVANCED_FACE('',(#214,#262),#126,.T.);
+#214 = FACE_BOUND('',#215,.T.);
+#215 = EDGE_LOOP('',(#216,#217,#218,#241));
+#216 = ORIENTED_EDGE('',*,*,#112,.F.);
+#217 = ORIENTED_EDGE('',*,*,#165,.T.);
+#218 = ORIENTED_EDGE('',*,*,#219,.T.);
+#219 = EDGE_CURVE('',#166,#220,#222,.T.);
+#220 = VERTEX_POINT('',#221);
+#221 = CARTESIAN_POINT('',(25.,15.,10.));
+#222 = SURFACE_CURVE('',#223,(#227,#234),.PCURVE_S1.);
+#223 = LINE('',#224,#225);
+#224 = CARTESIAN_POINT('',(25.,-15.,10.));
+#225 = VECTOR('',#226,1.);
+#226 = DIRECTION('',(0.,1.,0.));
+#227 = PCURVE('',#126,#228);
+#228 = DEFINITIONAL_REPRESENTATION('',(#229),#233);
+#229 = LINE('',#230,#231);
+#230 = CARTESIAN_POINT('',(50.,0.));
+#231 = VECTOR('',#232,1.);
+#232 = DIRECTION('',(0.,1.));
+#233 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#234 = PCURVE('',#202,#235);
+#235 = DEFINITIONAL_REPRESENTATION('',(#236),#240);
+#236 = LINE('',#237,#238);
+#237 = CARTESIAN_POINT('',(20.,0.));
+#238 = VECTOR('',#239,1.);
+#239 = DIRECTION('',(0.,-1.));
+#240 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#241 = ORIENTED_EDGE('',*,*,#242,.F.);
+#242 = EDGE_CURVE('',#85,#220,#243,.T.);
+#243 = SURFACE_CURVE('',#244,(#248,#255),.PCURVE_S1.);
+#244 = LINE('',#245,#246);
+#245 = CARTESIAN_POINT('',(-25.,15.,10.));
+#246 = VECTOR('',#247,1.);
+#247 = DIRECTION('',(1.,0.,0.));
+#248 = PCURVE('',#126,#249);
+#249 = DEFINITIONAL_REPRESENTATION('',(#250),#254);
+#250 = LINE('',#251,#252);
+#251 = CARTESIAN_POINT('',(0.,30.));
+#252 = VECTOR('',#253,1.);
+#253 = DIRECTION('',(1.,0.));
+#254 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#255 = PCURVE('',#100,#256);
+#256 = DEFINITIONAL_REPRESENTATION('',(#257),#261);
+#257 = LINE('',#258,#259);
+#258 = CARTESIAN_POINT('',(20.,0.));
+#259 = VECTOR('',#260,1.);
+#260 = DIRECTION('',(0.,1.));
+#261 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#262 = FACE_BOUND('',#263,.T.);
+#263 = EDGE_LOOP('',(#264));
+#264 = ORIENTED_EDGE('',*,*,#265,.T.);
+#265 = EDGE_CURVE('',#266,#266,#268,.T.);
+#266 = VERTEX_POINT('',#267);
+#267 = CARTESIAN_POINT('',(-5.,-1.722026714179E-15,10.));
+#268 = SURFACE_CURVE('',#269,(#274,#285),.PCURVE_S1.);
+#269 = CIRCLE('',#270,5.);
+#270 = AXIS2_PLACEMENT_3D('',#271,#272,#273);
+#271 = CARTESIAN_POINT('',(-4.440892098501E-16,-4.973799150321E-16,10.)
+  );
+#272 = DIRECTION('',(0.,0.,-1.));
+#273 = DIRECTION('',(-1.,0.,0.));
+#274 = PCURVE('',#126,#275);
+#275 = DEFINITIONAL_REPRESENTATION('',(#276),#284);
+#276 = ( BOUNDED_CURVE() B_SPLINE_CURVE(2,(#277,#278,#279,#280,#281,#282
+,#283),.UNSPECIFIED.,.T.,.F.) B_SPLINE_CURVE_WITH_KNOTS((1,2,2,2,2,1),(
+    -2.094395102393,0.,2.094395102393,4.188790204786,6.28318530718,
+8.377580409573),.UNSPECIFIED.) CURVE() GEOMETRIC_REPRESENTATION_ITEM() 
+RATIONAL_B_SPLINE_CURVE((1.,0.5,1.,0.5,1.,0.5,1.)) REPRESENTATION_ITEM(
+  '') );
+#277 = CARTESIAN_POINT('',(20.,15.));
+#278 = CARTESIAN_POINT('',(20.,23.660254037844));
+#279 = CARTESIAN_POINT('',(27.5,19.330127018922));
+#280 = CARTESIAN_POINT('',(35.,15.));
+#281 = CARTESIAN_POINT('',(27.5,10.669872981078));
+#282 = CARTESIAN_POINT('',(20.,6.339745962156));
+#283 = CARTESIAN_POINT('',(20.,15.));
+#284 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#285 = PCURVE('',#286,#291);
+#286 = CYLINDRICAL_SURFACE('',#287,5.);
+#287 = AXIS2_PLACEMENT_3D('',#288,#289,#290);
+#288 = CARTESIAN_POINT('',(-4.440892098501E-16,-4.973799150321E-16,10.)
+  );
+#289 = DIRECTION('',(0.,0.,-1.));
+#290 = DIRECTION('',(-1.,0.,0.));
+#291 = DEFINITIONAL_REPRESENTATION('',(#292),#296);
+#292 = LINE('',#293,#294);
+#293 = CARTESIAN_POINT('',(0.,0.));
+#294 = VECTOR('',#295,1.);
+#295 = DIRECTION('',(1.,0.));
+#296 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#297 = ADVANCED_FACE('',(#298),#100,.T.);
+#298 = FACE_BOUND('',#299,.T.);
+#299 = EDGE_LOOP('',(#300,#323,#324,#325));
+#300 = ORIENTED_EDGE('',*,*,#301,.F.);
+#301 = EDGE_CURVE('',#57,#302,#304,.T.);
+#302 = VERTEX_POINT('',#303);
+#303 = CARTESIAN_POINT('',(25.,15.,-10.));
+#304 = SURFACE_CURVE('',#305,(#309,#316),.PCURVE_S1.);
+#305 = LINE('',#306,#307);
+#306 = CARTESIAN_POINT('',(-25.,15.,-10.));
+#307 = VECTOR('',#308,1.);
+#308 = DIRECTION('',(1.,0.,0.));
+#309 = PCURVE('',#100,#310);
+#310 = DEFINITIONAL_REPRESENTATION('',(#311),#315);
+#311 = LINE('',#312,#313);
+#312 = CARTESIAN_POINT('',(0.,0.));
+#313 = VECTOR('',#314,1.);
+#314 = DIRECTION('',(0.,1.));
+#315 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#316 = PCURVE('',#72,#317);
+#317 = DEFINITIONAL_REPRESENTATION('',(#318),#322);
+#318 = LINE('',#319,#320);
+#319 = CARTESIAN_POINT('',(0.,30.));
+#320 = VECTOR('',#321,1.);
+#321 = DIRECTION('',(1.,0.));
+#322 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#323 = ORIENTED_EDGE('',*,*,#84,.T.);
+#324 = ORIENTED_EDGE('',*,*,#242,.T.);
+#325 = ORIENTED_EDGE('',*,*,#326,.F.);
+#326 = EDGE_CURVE('',#302,#220,#327,.T.);
+#327 = SURFACE_CURVE('',#328,(#332,#339),.PCURVE_S1.);
+#328 = LINE('',#329,#330);
+#329 = CARTESIAN_POINT('',(25.,15.,-10.));
+#330 = VECTOR('',#331,1.);
+#331 = DIRECTION('',(0.,0.,1.));
+#332 = PCURVE('',#100,#333);
+#333 = DEFINITIONAL_REPRESENTATION('',(#334),#338);
+#334 = LINE('',#335,#336);
+#335 = CARTESIAN_POINT('',(0.,50.));
+#336 = VECTOR('',#337,1.);
+#337 = DIRECTION('',(1.,0.));
+#338 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#339 = PCURVE('',#202,#340);
+#340 = DEFINITIONAL_REPRESENTATION('',(#341),#345);
+#341 = LINE('',#342,#343);
+#342 = CARTESIAN_POINT('',(0.,-30.));
+#343 = VECTOR('',#344,1.);
+#344 = DIRECTION('',(1.,0.));
+#345 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#346 = ADVANCED_FACE('',(#347,#373),#72,.F.);
+#347 = FACE_BOUND('',#348,.F.);
+#348 = EDGE_LOOP('',(#349,#350,#351,#372));
+#349 = ORIENTED_EDGE('',*,*,#56,.F.);
+#350 = ORIENTED_EDGE('',*,*,#141,.T.);
+#351 = ORIENTED_EDGE('',*,*,#352,.T.);
+#352 = EDGE_CURVE('',#142,#302,#353,.T.);
+#353 = SURFACE_CURVE('',#354,(#358,#365),.PCURVE_S1.);
+#354 = LINE('',#355,#356);
+#355 = CARTESIAN_POINT('',(25.,-15.,-10.));
+#356 = VECTOR('',#357,1.);
+#357 = DIRECTION('',(0.,1.,0.));
+#358 = PCURVE('',#72,#359);
+#359 = DEFINITIONAL_REPRESENTATION('',(#360),#364);
+#360 = LINE('',#361,#362);
+#361 = CARTESIAN_POINT('',(50.,0.));
+#362 = VECTOR('',#363,1.);
+#363 = DIRECTION('',(0.,1.));
+#364 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#365 = PCURVE('',#202,#366);
+#366 = DEFINITIONAL_REPRESENTATION('',(#367),#371);
+#367 = LINE('',#368,#369);
+#368 = CARTESIAN_POINT('',(0.,0.));
+#369 = VECTOR('',#370,1.);
+#370 = DIRECTION('',(0.,-1.));
+#371 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#372 = ORIENTED_EDGE('',*,*,#301,.F.);
+#373 = FACE_BOUND('',#374,.F.);
+#374 = EDGE_LOOP('',(#375));
+#375 = ORIENTED_EDGE('',*,*,#376,.T.);
+#376 = EDGE_CURVE('',#377,#377,#379,.T.);
+#377 = VERTEX_POINT('',#378);
+#378 = CARTESIAN_POINT('',(-5.,-1.722026714179E-15,-10.));
+#379 = SURFACE_CURVE('',#380,(#385,#396),.PCURVE_S1.);
+#380 = CIRCLE('',#381,5.);
+#381 = AXIS2_PLACEMENT_3D('',#382,#383,#384);
+#382 = CARTESIAN_POINT('',(-4.440892098501E-16,-4.973799150321E-16,-10.)
+  );
+#383 = DIRECTION('',(0.,0.,-1.));
+#384 = DIRECTION('',(-1.,0.,0.));
+#385 = PCURVE('',#72,#386);
+#386 = DEFINITIONAL_REPRESENTATION('',(#387),#395);
+#387 = ( BOUNDED_CURVE() B_SPLINE_CURVE(2,(#388,#389,#390,#391,#392,#393
+,#394),.UNSPECIFIED.,.T.,.F.) B_SPLINE_CURVE_WITH_KNOTS((1,2,2,2,2,1),(
+    -2.094395102393,0.,2.094395102393,4.188790204786,6.28318530718,
+8.377580409573),.UNSPECIFIED.) CURVE() GEOMETRIC_REPRESENTATION_ITEM() 
+RATIONAL_B_SPLINE_CURVE((1.,0.5,1.,0.5,1.,0.5,1.)) REPRESENTATION_ITEM(
+  '') );
+#388 = CARTESIAN_POINT('',(20.,15.));
+#389 = CARTESIAN_POINT('',(20.,23.660254037844));
+#390 = CARTESIAN_POINT('',(27.5,19.330127018922));
+#391 = CARTESIAN_POINT('',(35.,15.));
+#392 = CARTESIAN_POINT('',(27.5,10.669872981078));
+#393 = CARTESIAN_POINT('',(20.,6.339745962156));
+#394 = CARTESIAN_POINT('',(20.,15.));
+#395 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#396 = PCURVE('',#286,#397);
+#397 = DEFINITIONAL_REPRESENTATION('',(#398),#402);
+#398 = LINE('',#399,#400);
+#399 = CARTESIAN_POINT('',(0.,20.));
+#400 = VECTOR('',#401,1.);
+#401 = DIRECTION('',(1.,0.));
+#402 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#403 = ADVANCED_FACE('',(#404),#202,.T.);
+#404 = FACE_BOUND('',#405,.T.);
+#405 = EDGE_LOOP('',(#406,#407,#408,#409));
+#406 = ORIENTED_EDGE('',*,*,#188,.F.);
+#407 = ORIENTED_EDGE('',*,*,#352,.T.);
+#408 = ORIENTED_EDGE('',*,*,#326,.T.);
+#409 = ORIENTED_EDGE('',*,*,#219,.F.);
+#410 = ADVANCED_FACE('',(#411),#286,.F.);
+#411 = FACE_BOUND('',#412,.F.);
+#412 = EDGE_LOOP('',(#413,#414,#435,#436));
+#413 = ORIENTED_EDGE('',*,*,#376,.F.);
+#414 = ORIENTED_EDGE('',*,*,#415,.F.);
+#415 = EDGE_CURVE('',#266,#377,#416,.T.);
+#416 = SEAM_CURVE('',#417,(#421,#428),.PCURVE_S1.);
+#417 = LINE('',#418,#419);
+#418 = CARTESIAN_POINT('',(-5.,-1.722026714179E-15,10.));
+#419 = VECTOR('',#420,1.);
+#420 = DIRECTION('',(0.,0.,-1.));
+#421 = PCURVE('',#286,#422);
+#422 = DEFINITIONAL_REPRESENTATION('',(#423),#427);
+#423 = LINE('',#424,#425);
+#424 = CARTESIAN_POINT('',(6.28318530718,-0.));
+#425 = VECTOR('',#426,1.);
+#426 = DIRECTION('',(0.,1.));
+#427 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#428 = PCURVE('',#286,#429);
+#429 = DEFINITIONAL_REPRESENTATION('',(#430),#434);
+#430 = LINE('',#431,#432);
+#431 = CARTESIAN_POINT('',(0.,-0.));
+#432 = VECTOR('',#433,1.);
+#433 = DIRECTION('',(0.,1.));
+#434 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#435 = ORIENTED_EDGE('',*,*,#265,.T.);
+#436 = ORIENTED_EDGE('',*,*,#415,.T.);
+#437 = ( GEOMETRIC_REPRESENTATION_CONTEXT(3) 
+GLOBAL_UNCERTAINTY_ASSIGNED_CONTEXT((#441)) GLOBAL_UNIT_ASSIGNED_CONTEXT
+((#438,#439,#440)) REPRESENTATION_CONTEXT('Context #1',
+  '3D Context with UNIT and UNCERTAINTY') );
+#438 = ( LENGTH_UNIT() NAMED_UNIT(*) SI_UNIT(.MILLI.,.METRE.) );
+#439 = ( NAMED_UNIT(*) PLANE_ANGLE_UNIT() SI_UNIT($,.RADIAN.) );
+#440 = ( NAMED_UNIT(*) SI_UNIT($,.STERADIAN.) SOLID_ANGLE_UNIT() );
+#441 = UNCERTAINTY_MEASURE_WITH_UNIT(LENGTH_MEASURE(1.E-07),#438,
+  'distance_accuracy_value','confusion accuracy');
+#442 = PRODUCT_RELATED_PRODUCT_CATEGORY('part',$,(#7));
+ENDSEC;
+END-ISO-10303-21;

server/tasks/task_002_box_with_hole/ground_truth_normalized.step

@@ -0,0 +1,533 @@
+ISO-10303-21;
+HEADER;
+FILE_DESCRIPTION(('Open CASCADE Model'),'2;1');
+FILE_NAME('Open CASCADE Shape Model','2026-04-25T17:44:29',('Author'),(
+    'Open CASCADE'),'Open CASCADE STEP processor 7.8','Open CASCADE 7.8'
+  ,'Unknown');
+FILE_SCHEMA(('AUTOMOTIVE_DESIGN { 1 0 10303 214 1 1 1 1 }'));
+ENDSEC;
+DATA;
+#1 = APPLICATION_PROTOCOL_DEFINITION('international standard',
+  'automotive_design',2000,#2);
+#2 = APPLICATION_CONTEXT(
+  'core data for automotive mechanical design processes');
+#3 = SHAPE_DEFINITION_REPRESENTATION(#4,#10);
+#4 = PRODUCT_DEFINITION_SHAPE('','',#5);
+#5 = PRODUCT_DEFINITION('design','',#6,#9);
+#6 = PRODUCT_DEFINITION_FORMATION('','',#7);
+#7 = PRODUCT('Open CASCADE STEP translator 7.8 4',
+  'Open CASCADE STEP translator 7.8 4','',(#8));
+#8 = PRODUCT_CONTEXT('',#2,'mechanical');
+#9 = PRODUCT_DEFINITION_CONTEXT('part definition',#2,'design');
+#10 = ADVANCED_BREP_SHAPE_REPRESENTATION('',(#11,#15),#437);
+#11 = AXIS2_PLACEMENT_3D('',#12,#13,#14);
+#12 = CARTESIAN_POINT('',(0.,0.,0.));
+#13 = DIRECTION('',(0.,0.,1.));
+#14 = DIRECTION('',(1.,0.,-0.));
+#15 = MANIFOLD_SOLID_BREP('',#16);
+#16 = CLOSED_SHELL('',(#17,#137,#213,#297,#346,#403,#410));
+#17 = ADVANCED_FACE('',(#18),#32,.F.);
+#18 = FACE_BOUND('',#19,.F.);
+#19 = EDGE_LOOP('',(#20,#55,#83,#111));
+#20 = ORIENTED_EDGE('',*,*,#21,.F.);
+#21 = EDGE_CURVE('',#22,#24,#26,.T.);
+#22 = VERTEX_POINT('',#23);
+#23 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#24 = VERTEX_POINT('',#25);
+#25 = CARTESIAN_POINT('',(-25.,-15.,10.));
+#26 = SURFACE_CURVE('',#27,(#31,#43),.PCURVE_S1.);
+#27 = LINE('',#28,#29);
+#28 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#29 = VECTOR('',#30,1.);
+#30 = DIRECTION('',(0.,0.,1.));
+#31 = PCURVE('',#32,#37);
+#32 = PLANE('',#33);
+#33 = AXIS2_PLACEMENT_3D('',#34,#35,#36);
+#34 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#35 = DIRECTION('',(1.,0.,0.));
+#36 = DIRECTION('',(0.,0.,1.));
+#37 = DEFINITIONAL_REPRESENTATION('',(#38),#42);
+#38 = LINE('',#39,#40);
+#39 = CARTESIAN_POINT('',(0.,0.));
+#40 = VECTOR('',#41,1.);
+#41 = DIRECTION('',(1.,0.));
+#42 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#43 = PCURVE('',#44,#49);
+#44 = PLANE('',#45);
+#45 = AXIS2_PLACEMENT_3D('',#46,#47,#48);
+#46 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#47 = DIRECTION('',(0.,1.,0.));
+#48 = DIRECTION('',(0.,0.,1.));
+#49 = DEFINITIONAL_REPRESENTATION('',(#50),#54);
+#50 = LINE('',#51,#52);
+#51 = CARTESIAN_POINT('',(0.,0.));
+#52 = VECTOR('',#53,1.);
+#53 = DIRECTION('',(1.,0.));
+#54 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#55 = ORIENTED_EDGE('',*,*,#56,.T.);
+#56 = EDGE_CURVE('',#22,#57,#59,.T.);
+#57 = VERTEX_POINT('',#58);
+#58 = CARTESIAN_POINT('',(-25.,15.,-10.));
+#59 = SURFACE_CURVE('',#60,(#64,#71),.PCURVE_S1.);
+#60 = LINE('',#61,#62);
+#61 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#62 = VECTOR('',#63,1.);
+#63 = DIRECTION('',(0.,1.,0.));
+#64 = PCURVE('',#32,#65);
+#65 = DEFINITIONAL_REPRESENTATION('',(#66),#70);
+#66 = LINE('',#67,#68);
+#67 = CARTESIAN_POINT('',(0.,0.));
+#68 = VECTOR('',#69,1.);
+#69 = DIRECTION('',(0.,-1.));
+#70 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#71 = PCURVE('',#72,#77);
+#72 = PLANE('',#73);
+#73 = AXIS2_PLACEMENT_3D('',#74,#75,#76);
+#74 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#75 = DIRECTION('',(0.,0.,1.));
+#76 = DIRECTION('',(1.,0.,0.));
+#77 = DEFINITIONAL_REPRESENTATION('',(#78),#82);
+#78 = LINE('',#79,#80);
+#79 = CARTESIAN_POINT('',(0.,0.));
+#80 = VECTOR('',#81,1.);
+#81 = DIRECTION('',(0.,1.));
+#82 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#83 = ORIENTED_EDGE('',*,*,#84,.T.);
+#84 = EDGE_CURVE('',#57,#85,#87,.T.);
+#85 = VERTEX_POINT('',#86);
+#86 = CARTESIAN_POINT('',(-25.,15.,10.));
+#87 = SURFACE_CURVE('',#88,(#92,#99),.PCURVE_S1.);
+#88 = LINE('',#89,#90);
+#89 = CARTESIAN_POINT('',(-25.,15.,-10.));
+#90 = VECTOR('',#91,1.);
+#91 = DIRECTION('',(0.,0.,1.));
+#92 = PCURVE('',#32,#93);
+#93 = DEFINITIONAL_REPRESENTATION('',(#94),#98);
+#94 = LINE('',#95,#96);
+#95 = CARTESIAN_POINT('',(0.,-30.));
+#96 = VECTOR('',#97,1.);
+#97 = DIRECTION('',(1.,0.));
+#98 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#99 = PCURVE('',#100,#105);
+#100 = PLANE('',#101);
+#101 = AXIS2_PLACEMENT_3D('',#102,#103,#104);
+#102 = CARTESIAN_POINT('',(-25.,15.,-10.));
+#103 = DIRECTION('',(0.,1.,0.));
+#104 = DIRECTION('',(0.,0.,1.));
+#105 = DEFINITIONAL_REPRESENTATION('',(#106),#110);
+#106 = LINE('',#107,#108);
+#107 = CARTESIAN_POINT('',(0.,0.));
+#108 = VECTOR('',#109,1.);
+#109 = DIRECTION('',(1.,0.));
+#110 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#111 = ORIENTED_EDGE('',*,*,#112,.F.);
+#112 = EDGE_CURVE('',#24,#85,#113,.T.);
+#113 = SURFACE_CURVE('',#114,(#118,#125),.PCURVE_S1.);
+#114 = LINE('',#115,#116);
+#115 = CARTESIAN_POINT('',(-25.,-15.,10.));
+#116 = VECTOR('',#117,1.);
+#117 = DIRECTION('',(0.,1.,0.));
+#118 = PCURVE('',#32,#119);
+#119 = DEFINITIONAL_REPRESENTATION('',(#120),#124);
+#120 = LINE('',#121,#122);
+#121 = CARTESIAN_POINT('',(20.,0.));
+#122 = VECTOR('',#123,1.);
+#123 = DIRECTION('',(0.,-1.));
+#124 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#125 = PCURVE('',#126,#131);
+#126 = PLANE('',#127);
+#127 = AXIS2_PLACEMENT_3D('',#128,#129,#130);
+#128 = CARTESIAN_POINT('',(-25.,-15.,10.));
+#129 = DIRECTION('',(0.,0.,1.));
+#130 = DIRECTION('',(1.,0.,0.));
+#131 = DEFINITIONAL_REPRESENTATION('',(#132),#136);
+#132 = LINE('',#133,#134);
+#133 = CARTESIAN_POINT('',(0.,0.));
+#134 = VECTOR('',#135,1.);
+#135 = DIRECTION('',(0.,1.));
+#136 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#137 = ADVANCED_FACE('',(#138),#44,.F.);
+#138 = FACE_BOUND('',#139,.F.);
+#139 = EDGE_LOOP('',(#140,#163,#164,#187));
+#140 = ORIENTED_EDGE('',*,*,#141,.F.);
+#141 = EDGE_CURVE('',#22,#142,#144,.T.);
+#142 = VERTEX_POINT('',#143);
+#143 = CARTESIAN_POINT('',(25.,-15.,-10.));
+#144 = SURFACE_CURVE('',#145,(#149,#156),.PCURVE_S1.);
+#145 = LINE('',#146,#147);
+#146 = CARTESIAN_POINT('',(-25.,-15.,-10.));
+#147 = VECTOR('',#148,1.);
+#148 = DIRECTION('',(1.,0.,0.));
+#149 = PCURVE('',#44,#150);
+#150 = DEFINITIONAL_REPRESENTATION('',(#151),#155);
+#151 = LINE('',#152,#153);
+#152 = CARTESIAN_POINT('',(0.,0.));
+#153 = VECTOR('',#154,1.);
+#154 = DIRECTION('',(0.,1.));
+#155 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#156 = PCURVE('',#72,#157);
+#157 = DEFINITIONAL_REPRESENTATION('',(#158),#162);
+#158 = LINE('',#159,#160);
+#159 = CARTESIAN_POINT('',(0.,0.));
+#160 = VECTOR('',#161,1.);
+#161 = DIRECTION('',(1.,0.));
+#162 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#163 = ORIENTED_EDGE('',*,*,#21,.T.);
+#164 = ORIENTED_EDGE('',*,*,#165,.T.);
+#165 = EDGE_CURVE('',#24,#166,#168,.T.);
+#166 = VERTEX_POINT('',#167);
+#167 = CARTESIAN_POINT('',(25.,-15.,10.));
+#168 = SURFACE_CURVE('',#169,(#173,#180),.PCURVE_S1.);
+#169 = LINE('',#170,#171);
+#170 = CARTESIAN_POINT('',(-25.,-15.,10.));
+#171 = VECTOR('',#172,1.);
+#172 = DIRECTION('',(1.,0.,0.));
+#173 = PCURVE('',#44,#174);
+#174 = DEFINITIONAL_REPRESENTATION('',(#175),#179);
+#175 = LINE('',#176,#177);
+#176 = CARTESIAN_POINT('',(20.,0.));
+#177 = VECTOR('',#178,1.);
+#178 = DIRECTION('',(0.,1.));
+#179 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#180 = PCURVE('',#126,#181);
+#181 = DEFINITIONAL_REPRESENTATION('',(#182),#186);
+#182 = LINE('',#183,#184);
+#183 = CARTESIAN_POINT('',(0.,0.));
+#184 = VECTOR('',#185,1.);
+#185 = DIRECTION('',(1.,0.));
+#186 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#187 = ORIENTED_EDGE('',*,*,#188,.F.);
+#188 = EDGE_CURVE('',#142,#166,#189,.T.);
+#189 = SURFACE_CURVE('',#190,(#194,#201),.PCURVE_S1.);
+#190 = LINE('',#191,#192);
+#191 = CARTESIAN_POINT('',(25.,-15.,-10.));
+#192 = VECTOR('',#193,1.);
+#193 = DIRECTION('',(0.,0.,1.));
+#194 = PCURVE('',#44,#195);
+#195 = DEFINITIONAL_REPRESENTATION('',(#196),#200);
+#196 = LINE('',#197,#198);
+#197 = CARTESIAN_POINT('',(0.,50.));
+#198 = VECTOR('',#199,1.);
+#199 = DIRECTION('',(1.,0.));
+#200 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#201 = PCURVE('',#202,#207);
+#202 = PLANE('',#203);
+#203 = AXIS2_PLACEMENT_3D('',#204,#205,#206);
+#204 = CARTESIAN_POINT('',(25.,-15.,-10.));
+#205 = DIRECTION('',(1.,0.,0.));
+#206 = DIRECTION('',(0.,0.,1.));
+#207 = DEFINITIONAL_REPRESENTATION('',(#208),#212);
+#208 = LINE('',#209,#210);
+#209 = CARTESIAN_POINT('',(0.,0.));
+#210 = VECTOR('',#211,1.);
+#211 = DIRECTION('',(1.,0.));
+#212 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#213 = ADVANCED_FACE('',(#214,#262),#126,.T.);
+#214 = FACE_BOUND('',#215,.T.);
+#215 = EDGE_LOOP('',(#216,#217,#218,#241));
+#216 = ORIENTED_EDGE('',*,*,#112,.F.);
+#217 = ORIENTED_EDGE('',*,*,#165,.T.);
+#218 = ORIENTED_EDGE('',*,*,#219,.T.);
+#219 = EDGE_CURVE('',#166,#220,#222,.T.);
+#220 = VERTEX_POINT('',#221);
+#221 = CARTESIAN_POINT('',(25.,15.,10.));
+#222 = SURFACE_CURVE('',#223,(#227,#234),.PCURVE_S1.);
+#223 = LINE('',#224,#225);
+#224 = CARTESIAN_POINT('',(25.,-15.,10.));
+#225 = VECTOR('',#226,1.);
+#226 = DIRECTION('',(0.,1.,0.));
+#227 = PCURVE('',#126,#228);
+#228 = DEFINITIONAL_REPRESENTATION('',(#229),#233);
+#229 = LINE('',#230,#231);
+#230 = CARTESIAN_POINT('',(50.,0.));
+#231 = VECTOR('',#232,1.);
+#232 = DIRECTION('',(0.,1.));
+#233 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#234 = PCURVE('',#202,#235);
+#235 = DEFINITIONAL_REPRESENTATION('',(#236),#240);
+#236 = LINE('',#237,#238);
+#237 = CARTESIAN_POINT('',(20.,0.));
+#238 = VECTOR('',#239,1.);
+#239 = DIRECTION('',(0.,-1.));
+#240 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#241 = ORIENTED_EDGE('',*,*,#242,.F.);
+#242 = EDGE_CURVE('',#85,#220,#243,.T.);
+#243 = SURFACE_CURVE('',#244,(#248,#255),.PCURVE_S1.);
+#244 = LINE('',#245,#246);
+#245 = CARTESIAN_POINT('',(-25.,15.,10.));
+#246 = VECTOR('',#247,1.);
+#247 = DIRECTION('',(1.,0.,0.));
+#248 = PCURVE('',#126,#249);
+#249 = DEFINITIONAL_REPRESENTATION('',(#250),#254);
+#250 = LINE('',#251,#252);
+#251 = CARTESIAN_POINT('',(0.,30.));
+#252 = VECTOR('',#253,1.);
+#253 = DIRECTION('',(1.,0.));
+#254 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#255 = PCURVE('',#100,#256);
+#256 = DEFINITIONAL_REPRESENTATION('',(#257),#261);
+#257 = LINE('',#258,#259);
+#258 = CARTESIAN_POINT('',(20.,0.));
+#259 = VECTOR('',#260,1.);
+#260 = DIRECTION('',(0.,1.));
+#261 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#262 = FACE_BOUND('',#263,.T.);
+#263 = EDGE_LOOP('',(#264));
+#264 = ORIENTED_EDGE('',*,*,#265,.T.);
+#265 = EDGE_CURVE('',#266,#266,#268,.T.);
+#266 = VERTEX_POINT('',#267);
+#267 = CARTESIAN_POINT('',(-5.,-1.722026714179E-15,10.));
+#268 = SURFACE_CURVE('',#269,(#274,#285),.PCURVE_S1.);
+#269 = CIRCLE('',#270,5.);
+#270 = AXIS2_PLACEMENT_3D('',#271,#272,#273);
+#271 = CARTESIAN_POINT('',(-4.440892098501E-16,-4.973799150321E-16,10.)
+  );
+#272 = DIRECTION('',(0.,0.,-1.));
+#273 = DIRECTION('',(-1.,0.,0.));
+#274 = PCURVE('',#126,#275);
+#275 = DEFINITIONAL_REPRESENTATION('',(#276),#284);
+#276 = ( BOUNDED_CURVE() B_SPLINE_CURVE(2,(#277,#278,#279,#280,#281,#282
+,#283),.UNSPECIFIED.,.T.,.F.) B_SPLINE_CURVE_WITH_KNOTS((1,2,2,2,2,1),(
+    -2.094395102393,0.,2.094395102393,4.188790204786,6.28318530718,
+8.377580409573),.UNSPECIFIED.) CURVE() GEOMETRIC_REPRESENTATION_ITEM() 
+RATIONAL_B_SPLINE_CURVE((1.,0.5,1.,0.5,1.,0.5,1.)) REPRESENTATION_ITEM(
+  '') );
+#277 = CARTESIAN_POINT('',(20.,15.));
+#278 = CARTESIAN_POINT('',(20.,23.660254037844));
+#279 = CARTESIAN_POINT('',(27.5,19.330127018922));
+#280 = CARTESIAN_POINT('',(35.,15.));
+#281 = CARTESIAN_POINT('',(27.5,10.669872981078));
+#282 = CARTESIAN_POINT('',(20.,6.339745962156));
+#283 = CARTESIAN_POINT('',(20.,15.));
+#284 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#285 = PCURVE('',#286,#291);
+#286 = CYLINDRICAL_SURFACE('',#287,5.);
+#287 = AXIS2_PLACEMENT_3D('',#288,#289,#290);
+#288 = CARTESIAN_POINT('',(-4.440892098501E-16,-4.973799150321E-16,10.)
+  );
+#289 = DIRECTION('',(0.,0.,-1.));
+#290 = DIRECTION('',(-1.,0.,0.));
+#291 = DEFINITIONAL_REPRESENTATION('',(#292),#296);
+#292 = LINE('',#293,#294);
+#293 = CARTESIAN_POINT('',(0.,0.));
+#294 = VECTOR('',#295,1.);
+#295 = DIRECTION('',(1.,0.));
+#296 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#297 = ADVANCED_FACE('',(#298),#100,.T.);
+#298 = FACE_BOUND('',#299,.T.);
+#299 = EDGE_LOOP('',(#300,#323,#324,#325));
+#300 = ORIENTED_EDGE('',*,*,#301,.F.);
+#301 = EDGE_CURVE('',#57,#302,#304,.T.);
+#302 = VERTEX_POINT('',#303);
+#303 = CARTESIAN_POINT('',(25.,15.,-10.));
+#304 = SURFACE_CURVE('',#305,(#309,#316),.PCURVE_S1.);
+#305 = LINE('',#306,#307);
+#306 = CARTESIAN_POINT('',(-25.,15.,-10.));
+#307 = VECTOR('',#308,1.);
+#308 = DIRECTION('',(1.,0.,0.));
+#309 = PCURVE('',#100,#310);
+#310 = DEFINITIONAL_REPRESENTATION('',(#311),#315);
+#311 = LINE('',#312,#313);
+#312 = CARTESIAN_POINT('',(0.,0.));
+#313 = VECTOR('',#314,1.);
+#314 = DIRECTION('',(0.,1.));
+#315 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#316 = PCURVE('',#72,#317);
+#317 = DEFINITIONAL_REPRESENTATION('',(#318),#322);
+#318 = LINE('',#319,#320);
+#319 = CARTESIAN_POINT('',(0.,30.));
+#320 = VECTOR('',#321,1.);
+#321 = DIRECTION('',(1.,0.));
+#322 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#323 = ORIENTED_EDGE('',*,*,#84,.T.);
+#324 = ORIENTED_EDGE('',*,*,#242,.T.);
+#325 = ORIENTED_EDGE('',*,*,#326,.F.);
+#326 = EDGE_CURVE('',#302,#220,#327,.T.);
+#327 = SURFACE_CURVE('',#328,(#332,#339),.PCURVE_S1.);
+#328 = LINE('',#329,#330);
+#329 = CARTESIAN_POINT('',(25.,15.,-10.));
+#330 = VECTOR('',#331,1.);
+#331 = DIRECTION('',(0.,0.,1.));
+#332 = PCURVE('',#100,#333);
+#333 = DEFINITIONAL_REPRESENTATION('',(#334),#338);
+#334 = LINE('',#335,#336);
+#335 = CARTESIAN_POINT('',(0.,50.));
+#336 = VECTOR('',#337,1.);
+#337 = DIRECTION('',(1.,0.));
+#338 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#339 = PCURVE('',#202,#340);
+#340 = DEFINITIONAL_REPRESENTATION('',(#341),#345);
+#341 = LINE('',#342,#343);
+#342 = CARTESIAN_POINT('',(0.,-30.));
+#343 = VECTOR('',#344,1.);
+#344 = DIRECTION('',(1.,0.));
+#345 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#346 = ADVANCED_FACE('',(#347,#373),#72,.F.);
+#347 = FACE_BOUND('',#348,.F.);
+#348 = EDGE_LOOP('',(#349,#350,#351,#372));
+#349 = ORIENTED_EDGE('',*,*,#56,.F.);
+#350 = ORIENTED_EDGE('',*,*,#141,.T.);
+#351 = ORIENTED_EDGE('',*,*,#352,.T.);
+#352 = EDGE_CURVE('',#142,#302,#353,.T.);
+#353 = SURFACE_CURVE('',#354,(#358,#365),.PCURVE_S1.);
+#354 = LINE('',#355,#356);
+#355 = CARTESIAN_POINT('',(25.,-15.,-10.));
+#356 = VECTOR('',#357,1.);
+#357 = DIRECTION('',(0.,1.,0.));
+#358 = PCURVE('',#72,#359);
+#359 = DEFINITIONAL_REPRESENTATION('',(#360),#364);
+#360 = LINE('',#361,#362);
+#361 = CARTESIAN_POINT('',(50.,0.));
+#362 = VECTOR('',#363,1.);
+#363 = DIRECTION('',(0.,1.));
+#364 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#365 = PCURVE('',#202,#366);
+#366 = DEFINITIONAL_REPRESENTATION('',(#367),#371);
+#367 = LINE('',#368,#369);
+#368 = CARTESIAN_POINT('',(0.,0.));
+#369 = VECTOR('',#370,1.);
+#370 = DIRECTION('',(0.,-1.));
+#371 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#372 = ORIENTED_EDGE('',*,*,#301,.F.);
+#373 = FACE_BOUND('',#374,.F.);
+#374 = EDGE_LOOP('',(#375));
+#375 = ORIENTED_EDGE('',*,*,#376,.T.);
+#376 = EDGE_CURVE('',#377,#377,#379,.T.);
+#377 = VERTEX_POINT('',#378);
+#378 = CARTESIAN_POINT('',(-5.,-1.722026714179E-15,-10.));
+#379 = SURFACE_CURVE('',#380,(#385,#396),.PCURVE_S1.);
+#380 = CIRCLE('',#381,5.);
+#381 = AXIS2_PLACEMENT_3D('',#382,#383,#384);
+#382 = CARTESIAN_POINT('',(-4.440892098501E-16,-4.973799150321E-16,-10.)
+  );
+#383 = DIRECTION('',(0.,0.,-1.));
+#384 = DIRECTION('',(-1.,0.,0.));
+#385 = PCURVE('',#72,#386);
+#386 = DEFINITIONAL_REPRESENTATION('',(#387),#395);
+#387 = ( BOUNDED_CURVE() B_SPLINE_CURVE(2,(#388,#389,#390,#391,#392,#393
+,#394),.UNSPECIFIED.,.T.,.F.) B_SPLINE_CURVE_WITH_KNOTS((1,2,2,2,2,1),(
+    -2.094395102393,0.,2.094395102393,4.188790204786,6.28318530718,
+8.377580409573),.UNSPECIFIED.) CURVE() GEOMETRIC_REPRESENTATION_ITEM() 
+RATIONAL_B_SPLINE_CURVE((1.,0.5,1.,0.5,1.,0.5,1.)) REPRESENTATION_ITEM(
+  '') );
+#388 = CARTESIAN_POINT('',(20.,15.));
+#389 = CARTESIAN_POINT('',(20.,23.660254037844));
+#390 = CARTESIAN_POINT('',(27.5,19.330127018922));
+#391 = CARTESIAN_POINT('',(35.,15.));
+#392 = CARTESIAN_POINT('',(27.5,10.669872981078));
+#393 = CARTESIAN_POINT('',(20.,6.339745962156));
+#394 = CARTESIAN_POINT('',(20.,15.));
+#395 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#396 = PCURVE('',#286,#397);
+#397 = DEFINITIONAL_REPRESENTATION('',(#398),#402);
+#398 = LINE('',#399,#400);
+#399 = CARTESIAN_POINT('',(0.,20.));
+#400 = VECTOR('',#401,1.);
+#401 = DIRECTION('',(1.,0.));
+#402 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#403 = ADVANCED_FACE('',(#404),#202,.T.);
+#404 = FACE_BOUND('',#405,.T.);
+#405 = EDGE_LOOP('',(#406,#407,#408,#409));
+#406 = ORIENTED_EDGE('',*,*,#188,.F.);
+#407 = ORIENTED_EDGE('',*,*,#352,.T.);
+#408 = ORIENTED_EDGE('',*,*,#326,.T.);
+#409 = ORIENTED_EDGE('',*,*,#219,.F.);
+#410 = ADVANCED_FACE('',(#411),#286,.F.);
+#411 = FACE_BOUND('',#412,.F.);
+#412 = EDGE_LOOP('',(#413,#414,#435,#436));
+#413 = ORIENTED_EDGE('',*,*,#376,.F.);
+#414 = ORIENTED_EDGE('',*,*,#415,.F.);
+#415 = EDGE_CURVE('',#266,#377,#416,.T.);
+#416 = SEAM_CURVE('',#417,(#421,#428),.PCURVE_S1.);
+#417 = LINE('',#418,#419);
+#418 = CARTESIAN_POINT('',(-5.,-1.722026714179E-15,10.));
+#419 = VECTOR('',#420,1.);
+#420 = DIRECTION('',(0.,0.,-1.));
+#421 = PCURVE('',#286,#422);
+#422 = DEFINITIONAL_REPRESENTATION('',(#423),#427);
+#423 = LINE('',#424,#425);
+#424 = CARTESIAN_POINT('',(6.28318530718,-0.));
+#425 = VECTOR('',#426,1.);
+#426 = DIRECTION('',(0.,1.));
+#427 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#428 = PCURVE('',#286,#429);
+#429 = DEFINITIONAL_REPRESENTATION('',(#430),#434);
+#430 = LINE('',#431,#432);
+#431 = CARTESIAN_POINT('',(0.,-0.));
+#432 = VECTOR('',#433,1.);
+#433 = DIRECTION('',(0.,1.));
+#434 = ( GEOMETRIC_REPRESENTATION_CONTEXT(2) 
+PARAMETRIC_REPRESENTATION_CONTEXT() REPRESENTATION_CONTEXT('2D SPACE',''
+  ) );
+#435 = ORIENTED_EDGE('',*,*,#265,.T.);
+#436 = ORIENTED_EDGE('',*,*,#415,.T.);
+#437 = ( GEOMETRIC_REPRESENTATION_CONTEXT(3) 
+GLOBAL_UNCERTAINTY_ASSIGNED_CONTEXT((#441)) GLOBAL_UNIT_ASSIGNED_CONTEXT
+((#438,#439,#440)) REPRESENTATION_CONTEXT('Context #1',
+  '3D Context with UNIT and UNCERTAINTY') );
+#438 = ( LENGTH_UNIT() NAMED_UNIT(*) SI_UNIT(.MILLI.,.METRE.) );
+#439 = ( NAMED_UNIT(*) PLANE_ANGLE_UNIT() SI_UNIT($,.RADIAN.) );
+#440 = ( NAMED_UNIT(*) SI_UNIT($,.STERADIAN.) SOLID_ANGLE_UNIT() );
+#441 = UNCERTAINTY_MEASURE_WITH_UNIT(LENGTH_MEASURE(1.E-07),#438,
+  'distance_accuracy_value','confusion accuracy');
+#442 = PRODUCT_RELATED_PRODUCT_CATEGORY('part',$,(#7));
+ENDSEC;
+END-ISO-10303-21;

server/tasks/task_002_box_with_hole/reference_code.py

@@ -0,0 +1,2 @@
+import cadquery as cq
+result = cq.Workplane("XY").box(50, 30, 20).faces(">Z").hole(10)