diff --git a/CHANGELOG.md b/CHANGELOG.md index 63c97138..3c6682c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- **`create_sketch` takes `face_point`** (#206): a point in mm on a flat + face of the body, in place of `plane`. The sketch opens on that face and + moves with it when the model changes, so a pocket cut from it follows a + height edited later. Give exactly one of `plane` and `face_point`; a point + in the air or on a curved face fails with `invalid_input`. + +### Fixed + +Found building the monitor stand demo (#206): + +- **`list_features` returns rows in tree order.** When SolidWorks stopped + the forward walk at the system folders, the rest came newest first. +- **`verify_model` counts a plane the agent made.** It skipped the first + three reference planes in row order, so with rows newest first it counted + `Front Plane` and skipped `Plane1`. +- **`list_model_dimensions` lists each dimension once, under its own + feature.** It walks the tree the way `list_features` does, and takes each + dimension's feature from its full name: `D1@Plane1` is listed under + `Plane1`, never also under a cut sketched on that plane. +- **`export_stl` keeps its STL options.** `SaveAs2` was called with six + arguments of the wrong types, so it always failed with a type mismatch + and `SaveAs3` wrote the file without merging the bodies. It now gets its + eight arguments; if it still writes nothing, `SaveAs3` writes the file and + the reply's `warning` says the options weren't applied. + +### Changed + +- **The monitor stand demo** sketches its pocket on the stand's top face, + with no reference plane, and its camera turns to an isometric view after + each feature (`--look` in the script). + ## [2.0.0] - 2026-11-12 ### Added diff --git a/docs/assets/demos/monitor-stand/test_monitor_stand_from_prompt_to_part-motion.gif b/docs/assets/demos/monitor-stand/test_monitor_stand_from_prompt_to_part-motion.gif index 2e26b6f7..3b3c9b8e 100644 Binary files a/docs/assets/demos/monitor-stand/test_monitor_stand_from_prompt_to_part-motion.gif and b/docs/assets/demos/monitor-stand/test_monitor_stand_from_prompt_to_part-motion.gif differ diff --git a/docs/assets/progress/progress.json b/docs/assets/progress/progress.json index 2bacb41f..9b125dbd 100644 --- a/docs/assets/progress/progress.json +++ b/docs/assets/progress/progress.json @@ -440,7 +440,7 @@ "family": "sketching", "level": "stable", "reason": "", - "summary": "Open a new sketch on a plane of the active part, ready for lines, circles and other sketch entities." + "summary": "Open a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities." }, { "name": "create_sweep", diff --git a/docs/assets/progress/tables.html b/docs/assets/progress/tables.html index c1edd96d..1f4cc1a5 100644 --- a/docs/assets/progress/tables.html +++ b/docs/assets/progress/tables.html @@ -63,7 +63,7 @@ create_reference_pointmodelingstableAdd a reference point on an edge (at a distance or percentage along it) or at the centre of a face. create_revolvemodelingstableRevolve a closed sketch around an axis, adding a solid to the active part. create_section_viewdrawingplanned
no adapter implements it yet.Cut a section view along a line across a drawing view. -create_sketchsketchingstableOpen a new sketch on a plane of the active part, ready for lines, circles and other sketch entities. +create_sketchsketchingstableOpen a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities. create_sweepmodelingstableSweep a closed profile sketch along a path sketch to make a solid (Insert > Boss/Base > Sweep). create_technical_drawingdrawingstablePlace a model's three standard views (front, top and side) on the active drawing sheet in one call. create_templateautomationplanned
no adapter implements it yet.Create a part, assembly or drawing template file (.prtdot, .asmdot, .drwdot) with standard settings. diff --git a/docs/demos.md b/docs/demos.md index 7352b474..3702a498 100644 --- a/docs/demos.md +++ b/docs/demos.md @@ -146,8 +146,9 @@ powershell -ExecutionPolicy Bypass -File tests\scripts\live_demo.ps1 ` The recording opens on the prompts, then replays the build as the script below runs it, at the sizes the stand was finished at by hand (see -"Finished by hand"): 24 tool calls, each captioned with its result, and the -finished part in an isometric view. It is sped up five times. +"Finished by hand"): 23 tool calls, each captioned with its result. The +camera turns to an isometric view after the block, each cut, the arches and +the pocket, so each feature shows as it is made. It is sped up five times. **Printed.** The finished stand on the printer, in PETG, printed on its side with tree supports (sped up): @@ -281,16 +282,16 @@ the same legs, arches and pocket outline, cut 11.46 mm deep, comes to 901 762 mm³ by hand. SolidWorks measures 901 769 mm³. The script below was then updated to reproduce this part: 66 mm, a 26 mm -top and an 11.46 mm pocket are its defaults. One thing can't be matched: -the tools can only offset a plane from a named plane, so the script puts -the pocket's plane at Top Plane offset by the height. The solid is the -same, but the plane doesn't follow a height edited by hand. To change the -height, rerun the script. +top and an 11.46 mm pocket are its defaults. It sketches the pocket on the +stand's top face (`create_sketch` with `face_point`), as the user did by +hand, so the pocket follows the height when `D1@Boss-Extrude1` is edited +later, and no reference plane is needed. **Rebuild it, or at another size.** The script replays the calls with every dimension an option, and checks the result the same way. -At its defaults it makes the 24 calls in the recording; the session's own -28 calls are listed above. +At its defaults it makes 22 calls, and 23 with `--stl` as in the recording; +the session's own 28 calls are listed above. `--look` turns the camera to +an isometric view after each feature, as the recording does. ```powershell # The finished stand @@ -312,7 +313,7 @@ To record the demo again: ```powershell powershell -ExecutionPolicy Bypass -File tests\scripts\live_demo.ps1 ` - -Test tests/live/test_live_sw_monitor_stand_demo.py ` + -Test tests/live/test_live_sw_monitor_stand_demo.py::test_monitor_stand_from_prompt_to_part ` -CaptureDir docs/assets/demos/monitor-stand -Record -PromptSeconds 12 ``` diff --git a/docs/user-guide/tool-catalog/sketching.md b/docs/user-guide/tool-catalog/sketching.md index 4307afe2..4d8d8f0a 100644 --- a/docs/user-guide/tool-catalog/sketching.md +++ b/docs/user-guide/tool-catalog/sketching.md @@ -10,18 +10,22 @@ Build 2-D sketch geometry (lines, circles, arcs, splines, polygons) and apply ge ### `create_sketch` -Open a new sketch on a plane of the active part, ready for lines, circles and other sketch entities. +Open a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities. **Prerequisite:** Active part document, no active sketch -**Parameters:** +**Parameters:** give exactly one of `plane` and `face_point`. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| -| `plane` | `str` | ✅ | `` | Sketch plane name (e.g., 'Top', 'Front', 'Right', 'XY', 'XZ', 'YZ') | -| `sketch_name` | `str?` | — | `None` | Sketch name alias | +| `plane` | `str?` | one of | `None` | Sketch plane name (e.g., 'Top', 'Front', 'Right', 'XY', 'XZ', 'YZ', or a plane made by `create_reference_plane`) | +| `face_point` | `list[float]?` | one of | `None` | `[x, y, z]` in mm on a flat face of the body; the sketch opens on that face and moves with it when the model changes | +| `sketch_name` | `str?` | — | `None` | Name `exit_sketch` gives the sketch when it closes it | -**Sample call:** +A `face_point` that is not on a flat face of the body (in the air, or on a +fillet) fails with `error_type: "invalid_input"` and opens no sketch. + +**Sample calls:** ```json { @@ -29,6 +33,12 @@ Open a new sketch on a plane of the active part, ready for lines, circles and ot } ``` +```json +{ + "face_point": [0, 20, 0] +} +``` + --- ### `add_line` diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/.openspec.yaml b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/.openspec.yaml new file mode 100644 index 00000000..55ab199b --- /dev/null +++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-12 diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/design.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/design.md new file mode 100644 index 00000000..c1df4293 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/design.md @@ -0,0 +1,144 @@ +## Context + +See proposal.md for the six faults. Where each one comes from: + +- **`list_features`' traversal:** the real adapter walks with + `FirstFeature` and `GetNextFeature`, then always adds a + `FeatureByPositionReverse(0..GetFeatureCount(True)-1)` pass. The forward + walk can stop at the system folders. The second pass then finds the + remaining features newest first, and they are appended in that order. + The rows are de-duplicated but never sorted. +- **`verify_model`:** `_count_modelling_features` skips the first three + `RefPlane` rows it meets, in row order. On the monitor stand the rows came + newest first, so it skipped `Plane1`, `Right Plane` and `Top Plane` and + counted `Front Plane` (seen in the session's `verify_model` reply). +- **`list_model_dimensions`:** it has its own forward-only walk, with no + reverse pass, and reads `GetFirstDisplayDimension` on every feature, + folders included. It found 0 with no name on the monitor stand, and all + four when given each feature's name. The same walk serves both calls, so + the cause is not proven. A block's full listing does work live + (`test_dimensions_list_and_measure`). +- **`SaveAs2`:** the installed type library gives `IModelDocExtension.SaveAs2(Name, + Version, Options, ExportData, ReferencePrefixOrSuffixText As String, + AddTextAsPrefix As Boolean, Errors As Long by reference, Warnings As Long by + reference)` (eight arguments; a first live run with seven, leaving out + `Warnings`, failed with "Parameter not optional"). The adapter + calls it with `(path, 0, 2, stl_data, None, "")`. +- **`create_sketch`:** it selects a plane by name (with locale aliases), + then calls `InsertSketch`. Faces are already selected by coordinates + elsewhere, for example `create_reference_plane`'s `face_point` and + `select_face_edges`. + +## Goals / Non-Goals + +**Goals:** +- Feature and dimension listings that agree with the tree whatever the walk. +- A sketch on a face in one call, through the same adapter path as a plane. +- A demo whose recording shows each feature as it is made. + +**Non-Goals:** +- Sketching on a curved face, or on a face of an assembly component. +- Changing `export_stl`'s inputs; only the call underneath changes. +- Finding why `GetNextFeature` stops at the folders. Both passes stay. + +## Decisions + +### 1. Sort `list_features` rows by tree position, in the adapter + +Both passes number features by their place in the top-level tree. The +forward pass counts from 0, and the reverse pass uses +`count - reverse_pos - 1`, so a feature found by both gets the same number. +The adapter sorts each document's rows by `position` before returning +them, keeping each component's rows together as they are now. Every caller +then gets tree order: `verify_model`, the classifier, the bitmap, and +feature-tree diffs. + +*Alternative:* sort only in `verify_model`. Rejected: every caller assumes +tree order, and only one has been caught by it. + +### 2. `verify_model` skips default planes by position + +Once rows are in tree order, the first three `RefPlane` rows are the +defaults. To guard against an adapter that doesn't sort, `verify_model` +also sorts its rows by `position` before counting. This keeps the rule +language-independent, as now: no plane names are matched. + +### 3. `list_model_dimensions` walks with `list_features` + +The adapter reads the features with the same two-pass traversal as +`list_features` (a shared walk, not a copy), then reads each one's display +dimensions. Folder rows are skipped, as nothing there has dimensions. Each +dimension is kept once, keyed by `full_name`, with `feature` set from the +part after `@`. With `feature_name`, the result keeps the dimensions whose +`feature` matches. A sketch's own dimensions (`D1@Sketch3`) keep the sketch +as their feature, so asking for the cut no longer returns the plane's offset. + +*Live diagnostic:* a test builds the monitor stand at its defaults and +records, for the old and new walks, how many features each finds and how +many dimensions each lists. This proves the fix and explains the 0. + +### 4. `SaveAs2` with its eight arguments + +`ext.SaveAs2(path, 0, swSaveAsOptions_Silent, stl_data, "", False, errors, warnings)` +with `errors` and `warnings` by-reference Longs (`_byref_long`, as `RunMacro2` uses). When +`GetExportFileData` gives nothing, `ExportData` is a `VT_DISPATCH` null. +Success is the file existing. If `SaveAs2` writes nothing, `SaveAs3` runs +as now, and the tool's reply carries a `warning` that the STL options +weren't applied. The first `except` that retried `SaveAs2` without the data +goes: it was a second copy of the same wrong call. + +### 5. `create_sketch(face_point=...)` + +The input model takes exactly one of `plane` and `face_point`. Today `plane` +is required, so it becomes optional with the one-of check, and the error +names both. The adapter method gains `face_point: tuple[float, float, float] +| None`, through every adapter layer. The real adapter: + +1. finds and selects the face with `_select_face_at_point`, the helper + `create_reference_plane`'s `face_point` already uses live: it reads the + body's faces, takes the one whose closest point is within 0.01 mm, + refuses a face with no normal (curved), and selects it with + `IFace2.Select4`. It works from the body's geometry, so it needs neither + `SelectByID2` nor a rebuild first (decided at implementation, replacing + the `SelectByID2` + `IsPlane()` route first planned here); +2. on no face, a curved face or a refused selection, clears the selection + and raises `LookupError("face_point [x, y, z] mm is not on a flat face + of the active part ()")`. One rule in `error_classifier.py` + matches exactly that message and classifies it `invalid_input`; the + shared "No face found at point" message stays `not_found` for + `select_face_edges`; +3. calls `InsertSketch(True)`, and reads the new sketch's name as the + plane path does. + +The mock records the point and answers a point inside its block's top face +(mirroring its existing coordinate model), and refuses others. + +*Alternative:* `face_name` (`Face<3>`). Rejected: agents don't know face +names, and every other face input in the tools is a point. + +### 6. The demo + +`scripts/demo_monitor_stand.py` sketches the pocket with +`create_sketch({"face_point": ...})` on the top face, at the stand's +centre, at its height. `create_reference_plane` drops out of the script. +For the recording, the script turns the camera to isometric and zooms to +fit after each cut and the fillet. It reuses the README demo's `_look` +pattern (`ShowNamedView2("", 7)`, `ViewZoomtofit2`), behind a flag the live +test sets, since it is demo-side COM and not a tool. The GIF is re-recorded +with `SW_DEMO_RECORD`, and the docs page's call list and count are updated. + +## Risks / Trade-offs + +- [Sorting changes `list_features`' order for callers that relied on the + old order] → Only the broken case changes order: when the forward walk + finishes, the rows are already in tree order. Feature-tree diffs key by + name. +- [`SaveAs2` with the right arguments still fails on some versions] → The + `SaveAs3` fallback stays, now with a `warning`, so no export is lost. The + live test records which path wrote the file. +- [The diagnostic shows the 0 had another cause] → It runs in the bundle. + If the new walk still misses dimensions, that is fixed after the bundle, + one at a time, as agreed. +- [The pocket on the face changes the stand's volume] → No: the face is at + the same height the offset plane was. The live test checks the volume + against the recorded 901 769 mm³. diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/proposal.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/proposal.md new file mode 100644 index 00000000..307c11da --- /dev/null +++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/proposal.md @@ -0,0 +1,81 @@ +## Why + +Building the monitor stand demo (issue #206, queue item 9) turned up five tool +faults and one missing ability. On a real part, `verify_model` counted +`Front Plane` and skipped `Plane1`, and `list_model_dimensions` with no +feature name found nothing. The same dimension was listed under two +features. Every STL export logged a type mismatch and fell back to a path +that can't merge bodies. No tool could start a sketch on a face of the body. +Each one misleads an agent reading a finished part, and the demo recording +misses the cuts and fillet because the camera never turns. + +## What Changes + +- **`list_features` returns rows in tree order.** The real adapter walks + forward with `GetNextFeature`, then always adds a `FeatureByPositionReverse` + pass, because the forward walk can stop at the system folders. When it + stops, the remaining rows arrive newest first. The rows are now sorted by + `position`, and both passes give the same position to the same feature. +- **`verify_model` skips the three default planes by tree order**, so a + reference plane the agent made (`Plane1`) is counted and `Front Plane` is + not, whatever order the rows arrive in. +- **`list_model_dimensions` finds every dimension with no feature name.** + It walks the tree the way `list_features` does (both passes), and lists + each dimension once, under the feature its full name's `@` suffix names + (`D1@Plane1` under `Plane1`, never also under the cut on that plane). Why + the old walk found none is not proven, so a live diagnostic records + where it went wrong. +- **STL export calls `IModelDocExtension.SaveAs2` with its eight arguments** + (`Name, Version, Options, ExportData, ReferencePrefixOrSuffixText, + AddTextAsPrefix, Errors, Warnings`). The adapter passed six, with the wrong types, + so the call always failed with a type mismatch and `SaveAs3` wrote a file + without the merged-bodies option. The warning goes, and `SaveAs3` stays + only as the fallback for a `SaveAs2` that writes nothing. +- **`create_sketch` takes `face_point`** (`[x, y, z]` in mm on a flat face + of the body) in place of `plane`, and opens the sketch on that face. It + must name exactly one of `plane` and `face_point`. A point that is not on + a flat face fails with `invalid_input`. +- **The monitor stand demo** cuts its pocket on a sketch on the stand's top + face (via `face_point`), so the pocket follows a hand-edited height as the + user's finished part does. Its camera turns to isometric after each cut + and the fillet, and the GIF is re-recorded. + +No breaking changes: `plane` stays as it is; `face_point` is optional. + +## Capabilities + +### New Capabilities + +- `tools/dimension-listing`: `list_model_dimensions` lists every dimension + in the model once, under the feature that owns it. +- `tools/stl-export`: `export_stl` writes the file through `SaveAs2` with its + export options, without a type-mismatch warning. +- `tools/sketch-on-face`: `create_sketch` opens a sketch on a flat face of + the body given a point on it. + +### Modified Capabilities + +- `tools/list-features`: the rows come in tree order, whichever traversal + found them. +- `tools/model-verification`: the feature count skips the three default + planes by tree order, so a plane the agent made is counted. + +## Impact + +- **COM and adapter code:** this change touches `pywin32_adapter.py` + (`list_features`' traversal, `_save_stl_with_extension`), + `adapters/solidworks/documentation.py` (`list_model_dimensions`) and + `adapters/solidworks/sketch.py` (`create_sketch` on a face). `create_sketch`'s + new argument runs through `base.py`, `circuit_breaker.py`, + `connection_pool.py` and `mock_adapter.py`. All COM work stays on the + connect thread inside `_handle_com_operation`. The `SaveAs2` call needs a + by-reference `Errors` VARIANT, and face selection needs the `VT_DISPATCH` + null callout (runbook #11) and `ForceRebuild3` first (runbook #13). +- **Tools:** `sketching.py` (`CreateSketchInput`), `analysis.py` + (`_count_modelling_features`), `engineering_data.py` (description only). +- **Demo:** `scripts/demo_monitor_stand.py`, its live test and + `docs/demos.md#monitor-stand`, with the GIF re-recorded. +- **Docs:** the sketching tool catalog page, the skill's workflow notes on + sketching on a face, and the CHANGELOG. +- **Live tests:** one bundled set run at the end; failures are fixed one by + one afterwards. diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/dimension-listing/spec.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/dimension-listing/spec.md new file mode 100644 index 00000000..79939ddd --- /dev/null +++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/dimension-listing/spec.md @@ -0,0 +1,34 @@ +## Purpose + +`list_model_dimensions` lists every dimension in the active part or assembly +once, under the feature that owns it, so an agent can find a dimension by +name before reading or changing it. + +## ADDED Requirements + +### Requirement: Every dimension is listed with no feature name +`list_model_dimensions` with no `feature_name` SHALL return every dimension +of every feature in the active part or assembly: sketch dimensions, feature +dimensions such as an extrude's depth, and reference-plane offsets. It SHALL +return the same dimensions the per-feature calls return, together. + +#### Scenario: The monitor stand +- **WHEN** a part holds an extrude, two cuts, a fillet, `Plane1` and a cut + sketched on `Plane1`, and `list_model_dimensions` is called with no + `feature_name` +- **THEN** the result holds each dimension that a call naming each feature + in turn returns, and no fewer + +### Requirement: Each dimension is listed once, under its own feature +Each dimension SHALL appear once in the result, and its `feature` SHALL be +the feature its `full_name` names after the `@`. + +#### Scenario: A plane's offset seen from the cut on it +- **WHEN** a cut is sketched on `Plane1`, and SolidWorks also reports + `D1@Plane1` among the cut's dimensions +- **THEN** `D1@Plane1` appears once, with `feature` `Plane1` + +#### Scenario: Asking for one feature +- **WHEN** `list_model_dimensions` is called with `feature_name` `Cut-Extrude3` +- **THEN** only dimensions whose `full_name` ends in `@Cut-Extrude3` (or its + sketch's own name, for a sketch) are returned, not `D1@Plane1` diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/list-features/spec.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/list-features/spec.md new file mode 100644 index 00000000..96fab221 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/list-features/spec.md @@ -0,0 +1,26 @@ +## MODIFIED Requirements + +### Requirement: Response is always a flat list of feature descriptors +`list_features` SHALL always return a single flat list of feature +descriptors, regardless of document type. Each descriptor SHALL contain +`name`, `type`, `suppressed`, and `position`, exactly as it does today for +Part documents. The response SHALL NOT be restructured into a nested +object (for example, separate `components`/`assembly_features` +collections) for any document type, because existing callers (feature-tree +diffing, feature-family classification, and the MCP tool's `count` field) +depend on the result being a flat list. Within each document, the +descriptors SHALL be in feature-tree order (oldest first), each feature +SHALL appear once, and its `position` SHALL be its place in that order, +however SolidWorks was walked to find it. + +#### Scenario: Listing features on a Part +- **WHEN** `list_features` is called with the active document being a + `.SLDPRT` Part +- **THEN** the result is a flat list of that Part's own feature + descriptors, in the same shape as before this change + +#### Scenario: The forward walk stops early +- **WHEN** SolidWorks stops the feature walk at the system folders, so the + remaining features are found newest first +- **THEN** the result is still in tree order: the default planes come + before `Plane1`, and `Plane1` before the cut sketched on it diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/model-verification/spec.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/model-verification/spec.md new file mode 100644 index 00000000..3389f754 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/model-verification/spec.md @@ -0,0 +1,25 @@ +## MODIFIED Requirements + +### Requirement: Feature count counts modelling features only +`feature_count` SHALL count the document's own unsuppressed features, and +excludes: +- sketches; +- the origin; +- folder entries; +- the three default reference planes, which are the first three reference + planes in tree order, whatever their names; +- the mate group. + +A reference plane the agent made SHALL be counted. The agent can then +predict the number from the features it created. + +#### Scenario: Part with two extrudes and a fillet +- **WHEN** a part's tree holds the default entries, two sketches, two + extrudes and one fillet +- **THEN** the measured feature count is 3 + +#### Scenario: A part with a plane the agent made +- **WHEN** a part holds an extrude, `Plane1` offset from Top Plane, and a + cut sketched on `Plane1` +- **THEN** the measured feature count is 3, and the counted features are + the extrude, `Plane1` and the cut, never `Front Plane` diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/sketch-on-face/spec.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/sketch-on-face/spec.md new file mode 100644 index 00000000..427e6127 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/sketch-on-face/spec.md @@ -0,0 +1,46 @@ +## Purpose + +`create_sketch` opens a sketch on a flat face of the body, given a point on +that face, so a feature can follow the face when the model's dimensions +change. + +## ADDED Requirements + +### Requirement: A sketch opens on the flat face at a point +`create_sketch` SHALL accept `face_point`, `[x, y, z]` in millimetres in +model coordinates, in place of `plane`. It SHALL open the sketch on the flat +face of the active part at that point, and reply with the sketch's name +as it does for a plane. + +#### Scenario: Sketching on the top face +- **WHEN** a part has a 20 mm tall block whose top face is at y = 20 mm, and + `create_sketch` is called with `face_point` `[0, 20, 0]` +- **THEN** a sketch opens on that face, and a cut drawn there and extruded + 3 mm leaves the block 3 mm lower at the cut + +#### Scenario: The sketch follows the face +- **WHEN** the block's height is changed afterwards and the model rebuilt +- **THEN** the sketch, and the cut made from it, move with the top face + +### Requirement: Exactly one of plane and face_point +`create_sketch` SHALL fail with `invalid_input` when both `plane` and +`face_point` are given, or neither, or `face_point` does not have three +numbers. + +#### Scenario: Both given +- **WHEN** `create_sketch` is called with `plane` `Top` and a `face_point` +- **THEN** the call fails with `invalid_input`, and nothing is opened + +### Requirement: A point that is not on a flat face fails +When `face_point` is not on a face of the active part, or is on a curved +face, `create_sketch` SHALL fail with `invalid_input`, name the point, and +open no sketch. + +#### Scenario: A point in the air +- **WHEN** `face_point` is 50 mm above the part +- **THEN** the call fails with `invalid_input` naming the point, and no + sketch is open afterwards + +#### Scenario: A point on a fillet +- **WHEN** `face_point` lies on a filleted (curved) face +- **THEN** the call fails with `invalid_input` saying the face is not flat diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/stl-export/spec.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/stl-export/spec.md new file mode 100644 index 00000000..cdeade50 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/stl-export/spec.md @@ -0,0 +1,23 @@ +## Purpose + +`export_stl` writes the active part or assembly as an STL file through +SolidWorks' export call with its STL options, so a multibody part or an +assembly comes out as one merged file. + +## ADDED Requirements + +### Requirement: STL export uses its export options without a type mismatch +`export_stl` SHALL write the file with SolidWorks' STL export options (bodies +merged into one file), and SHALL NOT log a type-mismatch warning on the way. +A fallback without the options SHALL be used only when the first call +writes nothing, and the reply SHALL say when it was used. + +#### Scenario: A single-body part +- **WHEN** `export_stl` writes a part with one body +- **THEN** the file exists, is non-empty, and no type-mismatch warning is + logged + +#### Scenario: The export call writes nothing +- **WHEN** the export with options returns without writing the file +- **THEN** the fallback writes it, and the reply's `warning` says the STL + options were not applied diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/tasks.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/tasks.md new file mode 100644 index 00000000..c8cad0cb --- /dev/null +++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/tasks.md @@ -0,0 +1,42 @@ +## 1. Feature order + +- [x] 1.1 Real adapter: `list_features` sorts each document's rows by `position` (both passes numbered by tree place); tests where the forward walk stops early and the reverse pass finds the rest +- [x] 1.2 Mock adapter: its rows stay in tree order, with a test that `position` rises +- [x] 1.3 `verify_model`: sort rows by `position` before skipping the three default planes; tests with rows newest first and with `Plane1` + +## 2. Dimension listing + +- [x] 2.1 Real adapter: `list_model_dimensions` uses `list_features`' walk (shared), skips folders, keeps each `full_name` once with `feature` from the `@` suffix; tests for no name, a name, a plane offset seen from a cut, and a missing feature +- [x] 2.2 Mock adapter: same de-duplication and `feature` rule; tests +- [x] 2.3 Tool description: say each dimension is listed once, under its own feature + +## 3. STL export + +- [x] 3.1 Real adapter: `SaveAs2` with its eight arguments (by-reference `Errors` and `Warnings`, `VT_DISPATCH` null when there is no export data); remove the second wrong call; `SaveAs3` fallback reports that the options weren't applied; tests for each path +- [x] 3.2 Mock adapter and tool: the fallback's note reaches the reply's `warning`; tests + +## 4. Sketch on a face + +- [x] 4.1 `CreateSketchInput`: `plane` optional, `face_point` added, exactly one of them; tests for both, neither and a short point +- [x] 4.2 Adapter interface: `create_sketch(plane, face_point=None)` in `base.py`, `circuit_breaker.py` and `connection_pool.py`; tests +- [x] 4.3 Real adapter: select the face at the point with `_select_face_at_point` (flat check included), insert the sketch; a `face_point ... is not on a flat face` error, classified `invalid_input`, for no face or a curved face; tests +- [x] 4.4 Mock adapter: a point on its block's top face opens a sketch; other points are refused; tests +- [x] 4.5 Docs: the sketching catalog page and the skill's note on sketching on a face + +## 5. The monitor stand demo + +- [x] 5.1 `scripts/demo_monitor_stand.py`: pocket sketched on the top face with `face_point`; `create_reference_plane` drops out; camera to isometric after each cut and the fillet, behind a flag +- [x] 5.2 Its live test: the volume matches 901 769 mm³ at the defaults, and the pocket follows a changed height after a rebuild +- [x] 5.3 `docs/demos.md#monitor-stand`: the call list and count, and drop "one thing can't be matched" + +## 6. Live bundle (one set, run together, then fixes one by one) + +- [x] 6.1 Live tests (written in `test_live_sw_monitor_stand_follow_ups.py` and `test_live_sw_monitor_stand_demo.py`; run live 2026-11-14, all five pass): feature order and `verify_model` on a part with `Plane1`; the dimension diagnostic (old walk vs new, counts) and the full listing on the stand; STL export path and file size; `create_sketch` on a face, the follow-the-height rebuild, a point in the air and a point on a fillet +- [x] 6.2 Hand the user the bundle; fix each failure afterwards, one at a time (two failed: `SaveAs2` takes eight arguments, `Warnings` too; the face test read a name `exit_sketch` doesn't return. Both fixed and passed on the re-run) +- [x] 6.3 Re-record the monitor stand GIF with `SW_DEMO_RECORD` + +## 7. Finish + +- [x] 7.1 CHANGELOG (Unreleased): Fixed (feature order, `verify_model`, dimension listing, STL), Added (`create_sketch` `face_point`) +- [x] 7.2 Full mock suite at 100% coverage, ruff, `mkdocs build --strict`, progress files regenerated +- [x] 7.3 Sign-off, PR (no attribution), archive, and the queue updated diff --git a/openspec/changes/configuration-tools/.openspec.yaml b/openspec/changes/configuration-tools/.openspec.yaml new file mode 100644 index 00000000..55ab199b --- /dev/null +++ b/openspec/changes/configuration-tools/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-12 diff --git a/openspec/changes/configuration-tools/design.md b/openspec/changes/configuration-tools/design.md new file mode 100644 index 00000000..0f7cc708 --- /dev/null +++ b/openspec/changes/configuration-tools/design.md @@ -0,0 +1,75 @@ +## Context + +`list_configurations` reads the names (fixed in 2.0.0 to read +`IConfiguration.Name` as a property). `set_dimension`'s real adapter calls +`GetDimension2(0).SetSystemValue3(value_m, 1, None)`: 1 is +`swSetValue_InThisConfiguration`, so it already changes only the active +configuration. `suppress_feature` calls `EditSuppress2`/`EditUnsuppress2` +on the selected feature, which also act on the active configuration. + +COM members, from the type library index: + +| Need | Member | +| --- | --- | +| Create | `IConfigurationManager.AddConfiguration2(Name, Comment, AlternateName, Options, ParentConfigName, Description, Rebuild)` | +| Activate | `IModelDoc2.ShowConfiguration2(Name)` | +| Delete | `IModelDoc2.DeleteConfiguration2(Name)` | +| Active name | `IConfigurationManager.ActiveConfiguration` → `IConfiguration.Name` | +| Scoped value | `IDimension.SetSystemValue3(NewValue, WhichConfigurations, Config_names)` | +| Scoped suppression | `IFeature.SetSuppression2(SuppressionState, Config_opt, Config_names)` | + +## Goals / Non-Goals + +**Goals:** +- Variants of one model in a few calls, with every change's scope stated. +- Today's calls keep doing what they do: `this` is the default. + +**Non-Goals:** +- Design tables (Excel), configuration-specific materials or custom + properties, assembly component configurations (`set_component_state` + covers component suppression). +- Renaming a configuration. + +## Decisions + +### 1. One `configurations` input, three forms + +`configurations: Literal["this", "all"] | list[str] = "this"`. The adapter +maps it to the enum both COM calls share in meaning: +`this` → 1, `all` → 2, a list → 3 with the names as a string array +(`VARIANT(VT_ARRAY | VT_BSTR, names)`), and `None`/`Missing` for the names +otherwise. A list is checked against `list_configurations` in the tool +before any COM call, so an unknown name is `invalid_input`. + +### 2. Suppression keeps today's path for `this` + +For `this`, `suppress_feature` keeps `EditSuppress2`/`EditUnsuppress2`, +which are proven live. For `all` or a list, it uses +`IFeature.SetSuppression2` with `swSuppressFeature` (0) or +`swUnSuppressFeature` (1), then rebuilds. The reply's `configurations` +names where it applied. + +### 3. Creating doesn't switch unless asked + +`AddConfiguration2` makes the new configuration active. When `activate` is +off, the adapter shows the previous configuration again, so creating a +configuration doesn't change what the next call acts on. Options: 0 (no +special behaviour); a `parent` uses `ParentConfigName` for a derived +configuration. + +### 4. Delete guards in the tool + +The tool reads the active configuration and the list first and refuses +the active or the only configuration with `invalid_input`; SolidWorks +returns False in those cases without a reason. + +## Risks / Trade-offs + +- [`SetSystemValue3`'s names array marshals wrongly under late binding] → + the live bundle sets a value in a named configuration and reads it back + in each; if it fails, the adapter activates each named configuration and + sets `this`, then restores the active one. +- [Switching configurations rebuilds a large assembly slowly] → each + activation goes through the settle pause; no extra waits are added. +- [Agents forget the scope] → the default is the same as before, and every + reply names the configurations changed. diff --git a/openspec/changes/configuration-tools/proposal.md b/openspec/changes/configuration-tools/proposal.md new file mode 100644 index 00000000..60cfaad7 --- /dev/null +++ b/openspec/changes/configuration-tools/proposal.md @@ -0,0 +1,66 @@ +## Why + +Configurations are how SolidWorks users make size variants of one part (a +bolt in five lengths, a bracket with and without a slot). An agent can +only list them today (`list_configurations`). It can't make one, switch to +one, or change a dimension or suppress a feature in one configuration +only. Worse, `set_dimension` already changes the active configuration only +(it passes `swSetValue_InThisConfiguration` to `SetSystemValue3`), and +`suppress_feature` acts on the active one, and neither says so, so an +agent editing a part with configurations gets results it can't predict. +The planned `manage_design_table` is removed by the honest-tool-list change +(it needs Excel on the machine); these tools give agents the same variants +without it. + +## What Changes + +- **`create_configuration`**: adds a configuration to the active part or + assembly, by name, optionally as a derived (child) configuration of + another, with a description; it can be made active at once. +- **`activate_configuration`**: makes a configuration active and rebuilds. +- **`delete_configuration`**: deletes a configuration that isn't active. +- **`set_dimension` gains `configurations`**: `this` (the default, today's + behaviour, now stated), `all`, or a list of names. +- **`suppress_feature` gains `configurations`**: the same choices, through + `IFeature.SetSuppression2`. +- **`list_configurations`** also reports which configuration is active. +- The descriptions of `set_dimension`, `suppress_feature` and + `get_dimension` say which configuration they act on. + +## Capabilities + +### New Capabilities + +- `tools/configurations`: creating, activating and deleting + configurations, and scoping dimension and suppression changes to them. + +### Modified Capabilities + +- `tools/document-inspection`: `list_configurations` reports the active + configuration. + +## Impact + +- **COM and adapter code, all on the connect thread inside + `_handle_com_operation`:** + - `IConfigurationManager.AddConfiguration2`, + `IModelDoc2.ShowConfiguration2`, `DeleteConfiguration2`; + - `IConfigurationManager.ActiveConfiguration` (its `Name` is a property, + runbook "properties are still properties"); + - `IDimension.SetSystemValue3` with `WhichConfigurations` 1, 2 or 3 and + the names array; + - `IFeature.SetSuppression2` replaces `EditSuppress2`/`EditUnsuppress2` + when a scope other than `this` is given. + - Three new adapter methods, and `configurations` on two existing ones, + through `base.py`, `circuit_breaker.py`, `connection_pool.py` and + `mock_adapter.py`. +- **Tools:** `modeling.py` (`set_dimension`, `suppress_feature`, three new + tools), `file_management.py` (`list_configurations`), `tool_hints.py`, + `support_levels.py`. +- **Docs:** catalog pages, the agent skill's note on configurations, + CHANGELOG, progress bars. +- No issue is filed; this is queue item 13. +- **Depends on the honest-tool-list change (queue item 10)**, merged + first: it sets the verb list and runs the design-table probe. If that + probe shows design tables work without trouble, `manage_design_table` + stays planned and is added to this change's tasks before it starts. diff --git a/openspec/changes/configuration-tools/specs/tools/configurations/spec.md b/openspec/changes/configuration-tools/specs/tools/configurations/spec.md new file mode 100644 index 00000000..7ee1c44d --- /dev/null +++ b/openspec/changes/configuration-tools/specs/tools/configurations/spec.md @@ -0,0 +1,70 @@ +## Purpose + +An agent makes, switches and deletes configurations, and changes a +dimension or a feature's suppression in the configurations it names, so +one model can hold several variants. + +## ADDED Requirements + +### Requirement: Create a configuration +`create_configuration` SHALL take `name`, and optionally `parent` (an +existing configuration, making the new one derived from it), +`description`, and `activate` (default off). It SHALL add the +configuration to the active part or assembly and reply with its name and +whether it is active. + +#### Scenario: A long variant +- **WHEN** a part has only `Default` and `create_configuration` is called + with `name` `Long` +- **THEN** `list_configurations` lists `Default` and `Long`, and `Default` + is still active + +#### Scenario: A name already used +- **WHEN** `name` is `Default` +- **THEN** the call fails with `invalid_input` naming the existing + configuration, and nothing is added + +### Requirement: Activate a configuration +`activate_configuration` SHALL take `name`, make it the active +configuration, rebuild, and reply with the active name. + +#### Scenario: Switching and back +- **WHEN** `Long` is activated, then `Default` +- **THEN** each reply names the configuration asked for, and + `get_model_info` reports it as active + +#### Scenario: An unknown name +- **WHEN** `name` is not a configuration of the model +- **THEN** the call fails with `invalid_input` listing the configurations + +### Requirement: Delete a configuration +`delete_configuration` SHALL take `name` and delete that configuration. It +SHALL fail with `invalid_input` when `name` is the active configuration or +the only one. + +#### Scenario: Deleting the active one +- **WHEN** `Long` is active and `delete_configuration` is called with `Long` +- **THEN** the call fails, says to activate another configuration first, + and `Long` still exists + +### Requirement: Dimension and suppression changes name their configurations +`set_dimension` and `suppress_feature` SHALL take `configurations`: `this` +(the default: the active configuration only), `all`, or a list of +configuration names. The change SHALL apply to exactly those +configurations, and the reply SHALL name them. + +#### Scenario: A length in one variant +- **WHEN** `Long` is active and `set_dimension` sets `D1@Boss-Extrude1` to + 80 with `configurations` `this` +- **THEN** in `Long` the dimension is 80, and after activating `Default` + it is still its old value + +#### Scenario: A feature suppressed everywhere +- **WHEN** `suppress_feature` suppresses `Fillet1` with `configurations` + `all` +- **THEN** `Fillet1` is suppressed in `Default` and in `Long` + +#### Scenario: A named configuration that doesn't exist +- **WHEN** `configurations` is `["Short"]` and there is no `Short` +- **THEN** the call fails with `invalid_input` listing the configurations, + and nothing changes diff --git a/openspec/changes/configuration-tools/specs/tools/document-inspection/spec.md b/openspec/changes/configuration-tools/specs/tools/document-inspection/spec.md new file mode 100644 index 00000000..17a1ad16 --- /dev/null +++ b/openspec/changes/configuration-tools/specs/tools/document-inspection/spec.md @@ -0,0 +1,14 @@ +## MODIFIED Requirements + +### Requirement: Every configuration is listed + +`list_configurations` SHALL list the name of every configuration of the +active part or assembly, and SHALL report which one is active as `active`. + +#### Scenario: A part with two configurations +- **WHEN** a part has the configurations "Default" and "Long" +- **THEN** the reply's `configurations` holds both names and `count` is 2 + +#### Scenario: The active configuration +- **WHEN** "Long" is active +- **THEN** the reply's `active` is "Long" diff --git a/openspec/changes/configuration-tools/tasks.md b/openspec/changes/configuration-tools/tasks.md new file mode 100644 index 00000000..9f5da303 --- /dev/null +++ b/openspec/changes/configuration-tools/tasks.md @@ -0,0 +1,35 @@ +## 0. Before starting + +- [ ] 0.1 Confirm the honest-tool-list change is merged; read its design-table finding (its design decision 8). If `manage_design_table` was kept, add its tasks here (insert, read, update rows) before section 1 + +## 1. Create, activate, delete + +- [ ] 1.1 Inputs and tools `create_configuration`, `activate_configuration`, `delete_configuration`, with the name checks (existing, unknown, active, only); tests +- [ ] 1.2 Adapter interface for the three through `base.py`, `circuit_breaker.py`, `connection_pool.py`; tests +- [ ] 1.3 Real adapter: `AddConfiguration2` (restore the previous configuration unless `activate`), `ShowConfiguration2`, `DeleteConfiguration2`; tests +- [ ] 1.4 Mock adapter: a configuration list with an active one; tests + +## 2. The active configuration + +- [ ] 2.1 `list_configurations` reports `active` (real: `ActiveConfiguration.Name`); tests +- [ ] 2.2 Mock adapter: `active` from its state; tests + +## 3. Scoped changes + +- [ ] 3.1 `configurations` input on `set_dimension` and `suppress_feature`; a list checked against the model's configurations; replies name the configurations; tests +- [ ] 3.2 Adapter interface: `configurations` on `set_dimension` and `suppress_feature` through every layer; tests +- [ ] 3.3 Real adapter: `SetSystemValue3` with 1, 2 or 3 and the names array; `SetSuppression2` for `all` or a list, `EditSuppress2` kept for `this`; tests +- [ ] 3.4 Mock adapter: per-configuration dimension values and suppression; tests +- [ ] 3.5 Descriptions of `set_dimension`, `suppress_feature` and `get_dimension` say which configuration they act on + +## 4. Live bundle (one set, run together, then fixes one by one) + +- [ ] 4.1 Live tests: create `Long`, activate it and back; delete refused while active; a length in `Long` only, read in both; `Fillet1` suppressed in `all`; an unknown name refused +- [ ] 4.2 Hand the user the bundle; fix each failure afterwards, one at a time + +## 5. Docs and finish + +- [ ] 5.1 Catalog pages; the agent skill's note on configurations (scope defaults to the active one) +- [ ] 5.2 CHANGELOG (Added; Changed: `list_configurations` reports `active`), progress bars regenerated +- [ ] 5.3 Full mock suite at 100% coverage, ruff, `mkdocs build --strict` +- [ ] 5.4 Sign-off, PR (no attribution), archive, the queue updated diff --git a/openspec/changes/drawing-pack/.openspec.yaml b/openspec/changes/drawing-pack/.openspec.yaml new file mode 100644 index 00000000..55ab199b --- /dev/null +++ b/openspec/changes/drawing-pack/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-12 diff --git a/openspec/changes/drawing-pack/design.md b/openspec/changes/drawing-pack/design.md new file mode 100644 index 00000000..153f2d87 --- /dev/null +++ b/openspec/changes/drawing-pack/design.md @@ -0,0 +1,114 @@ +## Context + +The drawing tools are in `tools/drawing.py` and `tools/drawing_automation.py`; +the real adapter's drawing work is in `adapters/solidworks/documentation.py` +and `drawing_standard.py`. Already there and reusable: + +- `_sheet_bounds(drawing)`: the sheet's size, used to keep views on it; +- `title_block_properties(...)` and the DWG NO./TITLE fit in + `generate_drawing_package`; +- `find_sheet_format(adapter, name)`: finds a `.slddrt` by name; +- `list_drawing_views`, `insert_model_dimensions`, `insert_bom_table`. + +The seven tools are registered as `planned`; each raises +`UnsupportedOperationError` or fails `require_capability`. Their current +inputs were never used, so they can change. + +COM members, from the type library index: + +| Need | Member | +| --- | --- | +| Section view | `IDrawingDoc.CreateSectionViewAt5(X, Y, Z, SectionLabel, Options, ExcludedComponents, SectionDepth)` | +| Detail view | `IDrawingDoc.CreateDetailViewAt4(X, Y, Z, Style, Scale1, Scale2, LabelIn, Showtype, FullOutline, JaggedOutline, NoOutline, ShapeIntensity)` | +| Pick a view | `IDrawingDoc.ActivateView(ViewName)` | +| One dimension | `IModelDocExtension.AddDimension(X, Y, Z, Direction)` | +| Auto dimension | `IDrawingDoc.AutoDimension(EntitiesToDimension, HorizontalScheme, HorizontalPlacement, VerticalScheme, VerticalPlacement)` | +| Sheet format | `ISheet.SetTemplateName(NameIn)`, `ISheet.ReloadTemplate(KeepNoteChanges)`, `ISheet.SetProperties2(...)` | +| Checks | `IView.GetOutline()`, `IView.GetDimensionCount4()`, `IAnnotation.IsDangling()` | + +## Goals / Non-Goals + +**Goals:** +- The seven planned drawing tools work on SolidWorks, and no tool is left + `planned`. +- Every position is in sheet millimetres, the unit the other drawing tools + use. + +**Non-Goals:** +- Aligned, half or offset sections; section depth; excluding components. +- Ordinate dimensions, chamfer dimensions, tolerances on `add_dimension`. +- The title-block fit for fields other than DWG NO. and TITLE (#158). +- A drafting-standard score (ASME/ISO rule sets). `check_drawing` checks + completeness, not a standard. + +## Decisions + +### 1. Section line and detail circle are sketched in the parent view + +`CreateSectionViewAt5` and `CreateDetailViewAt4` use the selected sketch +line or circle. The adapter activates the parent view, sketches the line +(or circle) with the sketch manager in sheet coordinates converted to the +view's sketch space, selects it, and calls the creator at `position`. If +the call returns nothing, the sketch entity is deleted so no stray line is +left. The section line is checked against `IView.GetOutline()` first, and +`position` plus the parent view's size against `_sheet_bounds`, so the +common failures are `invalid_input` before any COM change. + +### 2. Picks for `add_dimension` are sheet points + +`SelectByID2("", "EDGE" | "VERTEX", x, y, 0, append, 0, null_callout, 0)` +in sheet metres selects view entities on a drawing. The adapter selects +entity 1, then entity 2 with `append`, then calls +`IModelDocExtension.AddDimension(x, y, 0, direction)` with the +direction from `dimension_type` (`swSmartDimensionDirection_e`: horizontal, +vertical, aligned; radial, diameter and angular use the smart direction). +The reply reads the new display dimension's `GetDimension2(0).Value`. + +*Alternative:* entity names from a view registry, as sketches have. Rejected +for now: drawing entities have no stable names, and agents can compute +sheet points from `list_drawing_views`' outlines. + +### 3. `auto_dimension_view` counts before and after + +The adapter activates and selects the view, calls `AutoDimension` with all +edges, the scheme for both directions, and placement above/right, then +reports `GetDimensionCount4()` after minus before. Zero added is a failure, +so a call that silently does nothing is visible. + +### 4. `update_title_block` reuses the package's mapping + +It calls `title_block_properties` with the given fields merged over the +current property values (read first), writes model and drawing properties +through the adapter's custom-property methods, then reruns the fit for +DWG NO. and TITLE and rebuilds. It is the same code path +`generate_drawing_package` uses, moved into one helper both call. + +### 5. `update_sheet_format` changes the template in place + +`find_sheet_format` resolves the name; the adapter calls +`SetTemplateName` then `ReloadTemplate(True)`, and `SetProperties2` for a +new paper size, then checks the views are still listed and on the sheet. +The live bundle confirms the title block's linked fields survive the +reload. + +### 6. `check_drawing` is read-only and composed from reads + +A new adapter method returns, per view: name, type, outline, dimension +count; plus the sheet size, the title-block properties, whether a BOM +table exists, and the dangling annotation count. The rules run in the tool +module as plain functions on that data (unit-tested without COM). The tool +is the renamed `check_drawing_standards`; the old name was planned and +never worked, so no deprecation is needed. + +## Risks / Trade-offs + +- [Sheet-to-view coordinate conversion for the section line] → the + conversion uses the view's position and scale (`IView.Position`, + `ScaleDecimal`); the live bundle checks a section through a hole's centre. +- [`AutoDimension` places dimensions over each other] → `arrange_dimensions` + already exists; the description points to it. +- [`ReloadTemplate` drops edited notes] → `KeepNoteChanges` is true; the + live test checks the title-block values after the reload. +- [`SelectByID2` on a drawing picks the wrong view's edge where views + overlap] → views are checked to be on the sheet; overlapping views are + rare in generated drawings; the error says which entity was picked. diff --git a/openspec/changes/drawing-pack/proposal.md b/openspec/changes/drawing-pack/proposal.md new file mode 100644 index 00000000..81616ef7 --- /dev/null +++ b/openspec/changes/drawing-pack/proposal.md @@ -0,0 +1,83 @@ +## Why + +Drawings are where this server goes further than the comparable servers +(the closest one declares drawings out of scope). An agent can already make +a drawing with standard views, a BOM, model dimensions, centre marks, GD&T +and a filled title block. Seven drawing tools are still `planned`, and +they are the ones a real drawing package needs next: a section and a detail +view, editing the title block or sheet format after the drawing exists, +adding one dimension by hand (#102), automatic dimensions on a view, and a +check that the drawing is complete. With them, an agent can take a part or +assembly to a finished, checked drawing. + +## What Changes + +- **`create_section_view`**: cuts a section through a view along a line + given by two points in sheet millimetres, and places the section view at + a point on the sheet, with a label (`A`, `B`, ...). +- **`create_detail_view`**: a detail of a circle (centre and radius in + sheet millimetres) in a view, placed on the sheet at a scale, with a + label. +- **`update_title_block`**: sets the title block's fields (title, drawing + number, drawn by, date, revision, company) on an existing drawing, with + the same field mapping and fit as `generate_drawing_package`. +- **`update_sheet_format`**: changes the active sheet's format (a format + name such as `a3 - iso`, or a `.slddrt` path) and paper size, keeping the + views. +- **`add_dimension`** (#102): one dimension in a view: linear (horizontal, + vertical or aligned), radial, diameter or angular, between entities + picked by points in sheet millimetres, placed at a point; it replies with + the measured value. +- **`auto_dimension_view`** (#102): SolidWorks' auto-dimension on one view + (baseline or chain, horizontal and vertical), replying with how many + dimensions it added. Its description says how it differs from + `insert_model_dimensions` (reference dimensions vs the model's own). +- **`check_drawing`** (the planned `check_drawing_standards`, renamed): a + read-only check of the active drawing: every view on the sheet, every + view dimensioned, the title block's fields filled, no dangling + annotations, and a BOM when the model is an assembly. It replies with a + list of findings and `passed`. +- All seven move from `planned` to `stable` after the live bundle, leaving + no planned tools. + +## Capabilities + +### New Capabilities + +- `tools/drawing-section-detail`: section and detail views. +- `tools/drawing-title-block`: `update_title_block` and + `update_sheet_format` on an existing drawing. +- `tools/drawing-dimensions`: `add_dimension` and `auto_dimension_view`. +- `tools/drawing-check`: `check_drawing`. + +### Modified Capabilities + +- `tools/support-levels`: no tool is `planned` after this change. + +## Impact + +- **COM and adapter code, all on the connect thread inside + `_handle_com_operation`:** + - `adapters/solidworks/documentation.py` gains the view-creation and + dimension methods: + - `IDrawingDoc.CreateSectionViewAt5`, `CreateDetailViewAt4`, + `AutoDimension`, `ActivateView`; + - `IModelDocExtension.AddDimension`; + - `ISheet.SetTemplateName` and `ReloadTemplate`; + - `IView.GetOutline`, `GetDisplayDimensions`; + - `IAnnotation.IsDangling`. + - The section line and detail circle are sketched in the view before the + call; entity picks use `SelectByID2` with the null callout (runbook #11). + - New adapter methods through `base.py`, `circuit_breaker.py`, + `connection_pool.py` and `mock_adapter.py`. +- **Tools:** `drawing.py` (the seven tools; `check_drawing_standards` + renamed), `tool_hints.py`, `support_levels.py`. +- **Reuse:** `drawing_standard.title_block_properties` and its fit code, + `find_sheet_format`, `_sheet_bounds`. +- **Docs:** drawing catalog pages, the drawing tutorial's "What is and + isn't live today" table, the agent skill's drawing workflow, CHANGELOG, + progress bars. +- Closes #102. From #158 it settles the BOM-on-a-formatted-sheet check (in + the live bundle); the title-block fit improvements stay in #158. +- Depends on the honest-tool-list change (queue item 10), which leaves + these seven as the only planned tools. diff --git a/openspec/changes/drawing-pack/specs/tools/drawing-check/spec.md b/openspec/changes/drawing-pack/specs/tools/drawing-check/spec.md new file mode 100644 index 00000000..37ba635c --- /dev/null +++ b/openspec/changes/drawing-pack/specs/tools/drawing-check/spec.md @@ -0,0 +1,44 @@ +## Purpose + +`check_drawing` tells an agent whether the active drawing is complete +before it is exported, as findings it can act on with the other drawing +tools. + +## ADDED Requirements + +### Requirement: Findings for an incomplete drawing +`check_drawing` SHALL read the active drawing without changing it and +reply with `passed` and `findings`, each finding having `rule`, `severity` +(`error` or `warning`), `message` and, where it applies, `view`. The rules: + +- `view_off_sheet` (error): a view's outline extends past the sheet; +- `view_not_dimensioned` (warning): a view, other than an isometric or + detail view, has no dimensions; +- `title_block_field_empty` (warning): a title-block field the standard + fills (title, drawn by, revision) is empty; +- `dangling_annotation` (error): an annotation has lost its reference; +- `bom_missing` (warning): the drawing's model is an assembly and the + sheet has no BOM table. + +`passed` SHALL be true when there are no `error` findings. + +#### Scenario: A finished package +- **WHEN** a drawing from `generate_drawing_package` with model dimensions + is checked +- **THEN** `passed` is true and `findings` is empty + +#### Scenario: A view dragged off the sheet +- **WHEN** a view's outline crosses the sheet's edge +- **THEN** `passed` is false, and a `view_off_sheet` finding names the view + +#### Scenario: An assembly drawing with no BOM +- **WHEN** an assembly's drawing has views but no BOM +- **THEN** a `bom_missing` warning is listed, and `passed` stays true + +### Requirement: Only on a drawing +`check_drawing` SHALL fail with `invalid_input` when the active document is +not a drawing. + +#### Scenario: A part is active +- **WHEN** a part is the active document +- **THEN** the call fails with `invalid_input` saying to activate a drawing diff --git a/openspec/changes/drawing-pack/specs/tools/drawing-dimensions/spec.md b/openspec/changes/drawing-pack/specs/tools/drawing-dimensions/spec.md new file mode 100644 index 00000000..c178f4b5 --- /dev/null +++ b/openspec/changes/drawing-pack/specs/tools/drawing-dimensions/spec.md @@ -0,0 +1,45 @@ +## Purpose + +`add_dimension` and `auto_dimension_view` put dimensions on drawing views, +by hand or automatically, so a drawing with views is a deliverable. + +## ADDED Requirements + +### Requirement: One dimension between picked entities +`add_dimension` SHALL take `dimension_type` (`horizontal`, `vertical`, +`aligned`, `radial`, `diameter` or `angular`), `entity1_point` and, for +the types that need two entities, `entity2_point` (`[x, y]` in sheet +millimetres on a view's edges or vertices), and `position` (`[x, y]` in +sheet millimetres for the text). It SHALL add one dimension and reply with +its name and measured value in millimetres (degrees for angular). + +#### Scenario: A plate's width +- **WHEN** a front view of a 60 mm wide plate is on the sheet and + `add_dimension` is called with `horizontal` and points on its left and + right edges +- **THEN** one dimension is added and its value is 60 within 0.01 mm + +#### Scenario: A hole's diameter +- **WHEN** `add_dimension` is called with `diameter` and a point on a + Ø6 mm hole's edge +- **THEN** the value is 6 within 0.01 mm + +#### Scenario: A point on no entity +- **WHEN** `entity1_point` is on empty sheet +- **THEN** the call fails with `invalid_input` naming the point, and no + dimension is added + +### Requirement: Auto-dimension one view +`auto_dimension_view` SHALL take `view`, `scheme` (`baseline` or `chain`, +default `baseline`) and apply SolidWorks' auto-dimension to that view's +edges, horizontally and vertically, replying with the number of +dimensions added. + +#### Scenario: A plate's front view +- **WHEN** `auto_dimension_view` is called on a plate's front view +- **THEN** the reply's `added` is at least 2, and the view's dimension + count rises by that number + +#### Scenario: A view that doesn't exist +- **WHEN** `view` names no view on the sheet +- **THEN** the call fails with `invalid_input` listing the views diff --git a/openspec/changes/drawing-pack/specs/tools/drawing-section-detail/spec.md b/openspec/changes/drawing-pack/specs/tools/drawing-section-detail/spec.md new file mode 100644 index 00000000..bb795aa9 --- /dev/null +++ b/openspec/changes/drawing-pack/specs/tools/drawing-section-detail/spec.md @@ -0,0 +1,44 @@ +## Purpose + +`create_section_view` and `create_detail_view` add the two derived views a +drawing package needs to show inside and small features. + +## ADDED Requirements + +### Requirement: A section view along a line +`create_section_view` SHALL take `view` (the parent view's name), +`line_start` and `line_end` (`[x, y]` in sheet millimetres, crossing the +view), `position` (`[x, y]` in sheet millimetres for the new view) and +`label` (default the next free letter). It SHALL add a section view cut +along that line, and reply with the new view's name, label and outline. + +#### Scenario: A section through a plate with a hole +- **WHEN** a drawing has a front view of a plate with a hole, and + `create_section_view` is called with a line across the hole's centre +- **THEN** `list_drawing_views` lists one more view, labelled `A`, and + its outline is inside the sheet + +#### Scenario: A line that misses the view +- **WHEN** the line lies wholly outside the parent view's outline +- **THEN** the call fails with `invalid_input` naming the view, and no view + or sketch line is left behind + +### Requirement: A detail view of a circle +`create_detail_view` SHALL take `view`, `center` (`[x, y]` in sheet +millimetres inside the view), `radius` in millimetres, `position`, `scale` +(for example `2:1`, default `2:1`) and `label`. It SHALL add a detail view +and reply with its name, label and scale. + +#### Scenario: A detail of a corner +- **WHEN** `create_detail_view` is called with a circle on a corner of the + front view and scale `3:1` +- **THEN** one more view exists, labelled, at scale 3:1 + +### Requirement: New views stay on the sheet +Both tools SHALL refuse a `position` that would put the new view's outline +off the sheet, before creating it, with `invalid_input` naming the sheet's +size. + +#### Scenario: A position off the sheet +- **WHEN** `position` is beyond the sheet's right edge +- **THEN** the call fails with `invalid_input`, and no view is added diff --git a/openspec/changes/drawing-pack/specs/tools/drawing-title-block/spec.md b/openspec/changes/drawing-pack/specs/tools/drawing-title-block/spec.md new file mode 100644 index 00000000..d6c1e136 --- /dev/null +++ b/openspec/changes/drawing-pack/specs/tools/drawing-title-block/spec.md @@ -0,0 +1,41 @@ +## Purpose + +`update_title_block` and `update_sheet_format` change an existing drawing's +title block and sheet, so an agent can revise a drawing without +regenerating it. + +## ADDED Requirements + +### Requirement: Title-block fields on an existing drawing +`update_title_block` SHALL take any of `title`, `drawing_number`, +`drawn_by`, `drawn_date`, `revision` and `company` (at least one), write +each to the property the sheet format reads (the same mapping +`generate_drawing_package` uses), rebuild, and reply with the fields it +set. Fields not given SHALL keep their values. + +#### Scenario: A new revision +- **WHEN** a drawing made by `generate_drawing_package` is active and + `update_title_block` is called with `revision` `B` +- **THEN** the title block shows `B`, and the title and drawn-by fields are + unchanged + +#### Scenario: No fields +- **WHEN** `update_title_block` is called with no fields +- **THEN** the call fails with `invalid_input` listing the fields + +### Requirement: A different sheet format, keeping the views +`update_sheet_format` SHALL take `format` (a format name found by +`find_sheet_format`, or a path to a `.slddrt` file) and optionally +`paper_size`. It SHALL change the active sheet's format, keep every view, +and reply with the format's path and the sheet's size. + +#### Scenario: From A3 to A2 +- **WHEN** the active sheet uses `a3 - iso` and `update_sheet_format` is + called with `a2 - iso` +- **THEN** the sheet is A2, `list_drawing_views` lists the same views, and + the title block's fields still show their values + +#### Scenario: A format that doesn't exist +- **WHEN** `format` names no format SolidWorks can find +- **THEN** the call fails with `invalid_input` naming the folders searched, + and the sheet is unchanged diff --git a/openspec/changes/drawing-pack/specs/tools/support-levels/spec.md b/openspec/changes/drawing-pack/specs/tools/support-levels/spec.md new file mode 100644 index 00000000..9286d12f --- /dev/null +++ b/openspec/changes/drawing-pack/specs/tools/support-levels/spec.md @@ -0,0 +1,17 @@ +## MODIFIED Requirements + +### Requirement: Levels are consistent with the code + +The check SHALL fail when a level contradicts what the code shows. A `planned` tool's reason SHALL name the queue item that builds it. + +#### Scenario: Planned means not implemented +- **WHEN** a tool is `planned` +- **THEN** its description says "Not available yet", no tool outside `planned` says so, and its reason names a queue item + +#### Scenario: Stable means checked live +- **WHEN** a tool is `stable` +- **THEN** at least one test under `tests/live/` calls it by name + +#### Scenario: After the drawing pack +- **WHEN** the levels are counted after this change +- **THEN** no tool is `planned` diff --git a/openspec/changes/drawing-pack/tasks.md b/openspec/changes/drawing-pack/tasks.md new file mode 100644 index 00000000..a45a25df --- /dev/null +++ b/openspec/changes/drawing-pack/tasks.md @@ -0,0 +1,47 @@ +## 1. Section and detail views + +- [ ] 1.1 New inputs for `create_section_view` (`view`, `line_start`, `line_end`, `position`, `label`) and `create_detail_view` (`view`, `center`, `radius`, `position`, `scale`, `label`); the off-sheet and missed-view checks; tests +- [ ] 1.2 Adapter interface for both through `base.py`, `circuit_breaker.py`, `connection_pool.py`; tests +- [ ] 1.3 Real adapter: activate the view, sketch the line or circle in view space, `CreateSectionViewAt5` / `CreateDetailViewAt4`, delete the sketch entity on failure; tests +- [ ] 1.4 Mock adapter: a new view appended to its view list with a label and outline; tests + +## 2. Title block and sheet format + +- [ ] 2.1 One title-block helper shared by `generate_drawing_package` and `update_title_block` (mapping, merge over current values, fit); tests +- [ ] 2.2 `update_title_block` input (at least one field) and tool; tests +- [ ] 2.3 `update_sheet_format` input and tool; `find_sheet_format` errors name the folders searched; tests +- [ ] 2.4 Adapter interface for the sheet format through every layer; tests +- [ ] 2.5 Real adapter: `SetTemplateName`, `ReloadTemplate(True)`, `SetProperties2`; tests +- [ ] 2.6 Mock adapter: the sheet's format and size change, views kept; tests + +## 3. Drawing dimensions (#102) + +- [ ] 3.1 `add_dimension` input (type, points, position) and the two-entity rule; tests +- [ ] 3.2 `auto_dimension_view` input (`view`, `scheme`); tests +- [ ] 3.3 Adapter interface for both through every layer; tests +- [ ] 3.4 Real adapter: point picks with the null callout, `AddDimension` with the direction, value read back; `ActivateView`, `AutoDimension`, the count before and after; tests +- [ ] 3.5 Mock adapter: a dimension's value from its mock geometry; auto-dimension adds two per view; tests + +## 4. Drawing check + +- [ ] 4.1 Adapter method returning views (name, type, outline, dimension count), sheet size, title-block properties, BOM present, dangling count; through every layer; tests +- [ ] 4.2 Real adapter: `GetOutline`, `GetDimensionCount4`, `IsDangling`, BOM table lookup; tests +- [ ] 4.3 Mock adapter: the same report from its drawing state; tests +- [ ] 4.4 The five rules as plain functions; `check_drawing` replaces `check_drawing_standards`; tests for each rule and for a part being active + +## 5. Levels and descriptions + +- [ ] 5.1 The seven tools' descriptions rewritten to the standard (no "Not available yet"); `auto_dimension_view` vs `insert_model_dimensions` stated; levels `beta` until the bundle passes +- [ ] 5.2 The support-level test: no tool `planned` + +## 6. Live bundle (one set, run together, then fixes one by one) + +- [ ] 6.1 Live tests: a section through a plate's hole and one off the view; a 3:1 corner detail; revision B on a package drawing; A3 to A2 keeping views and title values; width 60 and Ø6 dimensions; auto-dimension on the front view; `check_drawing` on a finished package, a view off the sheet and an assembly with no BOM; `insert_bom_table` on the A3 ISO format, checked on the sheet (#158) +- [ ] 6.2 Hand the user the bundle; fix each failure afterwards, one at a time; move each tool to stable when its tests pass + +## 7. Docs and finish + +- [ ] 7.1 Drawing catalog pages, the drawing tutorial's "What is and isn't live today" table, the agent skill's drawing workflow (views, then dimensions, then `check_drawing`, then export) +- [ ] 7.2 CHANGELOG (Added; Changed: `check_drawing_standards` is now `check_drawing`), progress bars regenerated +- [ ] 7.3 Full mock suite at 100% coverage, ruff, `mkdocs build --strict` +- [ ] 7.4 Sign-off, PR (no attribution) closing #102, a comment on #158 for the BOM check, archive, the queue updated diff --git a/openspec/changes/honest-tool-list/.openspec.yaml b/openspec/changes/honest-tool-list/.openspec.yaml new file mode 100644 index 00000000..55ab199b --- /dev/null +++ b/openspec/changes/honest-tool-list/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-12 diff --git a/openspec/changes/honest-tool-list/design.md b/openspec/changes/honest-tool-list/design.md new file mode 100644 index 00000000..1d65e7d2 --- /dev/null +++ b/openspec/changes/honest-tool-list/design.md @@ -0,0 +1,127 @@ +## Context + +After 2.0.0 the server has 156 tools: 116 `stable`, 40 `planned` +(`tools/support_levels.py`). Planned tools are registered so their names +are reserved, and every call returns `not_supported`. Issue #174 lists the +overlapping clusters; Glama's review (2.3/5) says an agent can't pick the +intended tool. `ToolRegistrar` (`tools/tool_boundary.py`) already adds a +level tag, a description opening and a success `warning` from the levels +table, so a new level costs one table entry per tool. + +Each overlapping cluster, compared in the code: + +| Cluster | Finding | Decision | +| --- | --- | --- | +| `open_model`, `load_part`, `load_assembly` | Same adapter call; the two loaders only check the extension | keep `open_model` | +| `save_file`, `save_part`, `save_assembly`, `save_as` | `save_part`/`save_assembly` = `save_file` plus `_prepare_save_target`; `save_as` writes other formats | keep `save_file` (with the checks) and `save_as` | +| `get_mass_properties`, `calculate_mass_properties` | Same adapter call; one takes optional input | keep `get_mass_properties` | +| `get_model_info`, `get_file_properties` | Different fields: tree and rebuild vs size and dates | keep `get_model_info`, add size and dates | +| `create_drawing_view`, `add_drawing_view` | Same code; `add_drawing_view`'s description already says so | keep `create_drawing_view` | +| `create_technical_drawing` | Three views in one call: a different job | keep | +| `sketch_tutorial_simple_hole`, `tutorial_simple_hole` | Fixed examples; the second never worked | remove the planned one, deprecate the other | +| `generate_vba_code` and ten `generate_vba_*` | Offline text generators with different inputs | leave to item 14 (an optional toolset) | +| Seven drawing checks | All planned | remove six; `check_drawing_standards` becomes item 12's `check_drawing` | +| Macro recording (four) | All planned; the type-library index has no recorder start/stop member | remove | +| Templates (five, plus `create_template`) | All planned; `set_custom_property`/`set_material` cover applying settings | remove; keep `compare_templates` | + +## Goals / Non-Goals + +**Goals:** +- Every registered tool either works or is one of seven named drawing + tools that item 12 builds. +- One tool per job, with a release in which old names still work. +- A verb list new tools follow. + +**Non-Goals:** +- Renaming stable tools that break the verb list (`pattern_circular`, + `mirror_feature`, `select_face_edges`, ...): renames break clients for no + gain in function. They are listed as exceptions. +- Merging the VBA generators, or turning families off: item 14. +- Building any planned tool. + +## Decisions + +### 1. `deprecated` is a support level + +`SupportLevel.DEPRECATED`, with `Support(level, reason)` where the reason +is "use ``" or "no replacement", and a new `since` field holding the +version it was deprecated in. `Support.warning()` returns +"Deprecated: use ``." for it, so `ToolRegistrar` adds the description +opening and the success `warning` exactly as it does for beta. The level +tag is `level:deprecated`. The progress page counts deprecated tools +separately and leaves them out of the coverage bars. + +*Alternative:* a separate aliases table that re-registers the replacement +under the old name. Rejected: inputs differ (`load_part` checks the +extension), so each old tool must keep its own body for one release. + +### 2. The removal check uses the package version + +The support-level test reads `solidworks_mcp.version.__version__`. When its +major number is above a deprecated tool's `since` major, the test fails. +This forces the removal at 3.0.0 without a calendar. + +### 3. Planned tools name their queue item + +The planned reason becomes "planned in queue item 12 (the drawing pack)." +for the seven left. The test checks that every planned reason names a +queue item, so a planned tool can't be left without an owner again. + +### 4. Removing a tool removes everything that names it + +For each removed tool: its function and input model, its `tool_hints.py` +and `support_levels.py` entries, its tests, its catalog row, and any +"use ``" sentence in another description. A repo-wide grep for each +name, run in the tests (the existing description check already fails on a +backticked name that isn't registered), keeps this honest. + +### 5. `save_file` and `get_model_info` gain what their duplicates had + +`save_file` calls `_prepare_save_target` when `file_path` is given, with +the extension taken from the active document's type (the adapter's model +info already reports it), and gains `overwrite` (default off). This makes +`save_file` refuse an existing file where it overwrote before; the +CHANGELOG says so. `get_model_info` adds `size_bytes`, `created` and +`modified` with the same `os.stat` code `get_file_properties` uses, moved +into one helper. + +### 6. The verb list lives with the description standard + +The table goes into `docs/agents/tool-description-standard.md`, with the +exceptions listed under it, and CONTRIBUTING.md links to it. The existing +description-standard test gains a naming check. + +### 7. Version 2.1.0 + +Removing tools that never worked is not a break for a working client, so +the release is 2.1.0. The CHANGELOG lists the removed names under +"Removed" and the deprecated ones under "Deprecated". + +### 8. `manage_design_table` is checked before it goes + +It is in the removal list because a design table needs Excel on the +machine, and item 13's configuration tools give agents the same variants +without it. That reason is not yet proven on the user's SolidWorks, so a +live probe (task 2.0) inserts a design table on a scratch part and reads it +back. If it works, the tool stays `planned` for item 13 and the planned +count is eight; if not, it is removed and the finding is recorded here. + +### 9. Items 11 to 14 depend on this change + +`part-feature-depth`, `drawing-pack`, `configuration-tools` and +`tool-discovery-mode` use the verb list, the `deprecated` level, the +planned-reason rule and the final family list from this change. None of +them starts until this change is merged. + +## Risks / Trade-offs + +- [A client scripted a planned tool's name] → it only ever got + `not_supported`; the CHANGELOG lists every removed name. +- [`save_file` now refuses an existing file without `overwrite`] → this is + what `save_as` and `save_part` already do; the error names `overwrite`. +- [Deprecation warnings add noise to replies] → one sentence, and only on + the eight old names. +- [Removing a family empties a module] → `drawing_analysis.py` keeps + `compare_drawing_versions`; `template_management.py` keeps + `compare_templates`; `macro_recording.py` keeps `execute_macro`. No module + is emptied. diff --git a/openspec/changes/honest-tool-list/proposal.md b/openspec/changes/honest-tool-list/proposal.md new file mode 100644 index 00000000..c4e7864d --- /dev/null +++ b/openspec/changes/honest-tool-list/proposal.md @@ -0,0 +1,102 @@ +## Why + +The server registers 156 tools, but 40 of them are `planned`: every call +returns `not_supported`. A client still pays for their schemas on every +turn, and an agent can pick one and fail. Among the 116 that work, several +do the same job under different names (`load_part` and `open_model`, +`get_mass_properties` and `calculate_mass_properties`), so an agent can't +reliably pick the intended one. Glama's tool-quality review scored the +server 2.3/5 for exactly this (issue #174). The fix is a list where every +tool works, does one job, and is named by one verb list. + +## What Changes + +- **33 planned tools are removed.** Each either duplicates a working tool, + is a loop an agent can run itself, or has no SolidWorks API behind it: + - analysis: `analyze_geometry`, `get_material_properties`; + - automation: `automation_start_macro_recording`, + `automation_stop_macro_recording`, `batch_process_files`, + `create_template`, `execute_workflow`, `manage_design_table`, + `optimize_performance`; + - drawing: `add_annotation`; + - drawing analysis: `analyze_drawing_annotations`, + `analyze_drawing_comprehensive`, `analyze_drawing_dimensions`, + `analyze_drawing_views`, `check_drawing_compliance`, + `generate_drawing_report`, `validate_drawing_completeness`; + - export: `batch_export`; + - file management: `batch_file_operations`, `convert_file_format`, + `manage_file_properties`; + - macros: `analyze_macro`, `batch_execute_macros`, + `create_macro_library`, `optimize_macro`, `start_macro_recording`, + `stop_macro_recording`; + - sketching: `tutorial_simple_hole`; + - templates: `apply_template`, `batch_apply_template`, + `extract_template`, `list_template_library`, + `save_to_template_library`. +- **The seven planned drawing tools stay planned** for the drawing pack + (queue item 12): `add_dimension`, `auto_dimension_view`, + `create_section_view`, `create_detail_view`, `update_title_block`, + `update_sheet_format`, `check_drawing_standards`. Their reason names that + item. +- **A new support level, `deprecated`**, for a working tool replaced by + another. It keeps working for one minor release. Its description opens + "Deprecated: use ``.", and a successful result carries the same + sentence as `warning`. It is removed in 3.0.0. +- **Eight stable tools are deprecated**, after their replacement gains what + they did: + - `load_part`, `load_assembly` → `open_model`; + - `save_part`, `save_assembly` → `save_file`, which gains the new-path + checks (folder exists, extension matches the document, no overwrite + unless asked). `save_assembly`'s `include_references` copy is + `pack_and_go_assembly`'s job; + - `calculate_mass_properties` → `get_mass_properties`; + - `get_file_properties` → `get_model_info`, which gains the file's size + and dates; + - `add_drawing_view` → `create_drawing_view`; + - `sketch_tutorial_simple_hole` → none; it is a fixed example, and its + description already points to the real tools. +- **One verb list**, in CONTRIBUTING.md and the description standard, that + new tools follow. Stable tools that break it are listed as exceptions, + not renamed. +- **BREAKING (for clients that call them):** the 33 removed tool names + disappear. They never did anything but return `not_supported`, so this + ships in 2.1.0. The eight deprecated names keep working until 3.0.0. + +## Capabilities + +### New Capabilities + +- `tools/tool-deprecation`: a deprecated tool keeps working, names its + replacement in its description and its results, and is removed at the + next major release. +- `tools/tool-naming`: one verb per meaning, checked for new tools. + +### Modified Capabilities + +- `tools/support-levels`: a fifth level, `deprecated`; the levels check + allows only the seven drawing tools to be `planned`, each naming the + queue item that builds it. +- `tools/file-saving`: `save_file` checks a new path the way `save_part` + did. +- `tools/document-inspection`: `get_model_info` reports the file's size and + dates. + +## Impact + +- **No COM or adapter code changes.** Removed tools have no adapter + method; deprecated tools already call the adapter method their + replacement calls. `get_model_info`'s size and dates come from the file + on disk (`os.stat`), as `get_file_properties` reads them today. +- **Tools:** `analysis.py`, `automation.py`, `drawing.py`, + `drawing_analysis.py`, `export.py`, `file_management.py`, + `macro_recording.py`, `sketching.py`, `template_management.py` lose the + removed tools and their input models. `support_levels.py`, + `tool_hints.py` and `tool_boundary.py` gain `deprecated`. +- **Docs:** the tool catalog pages, the README's counts and progress bars + (regenerated), the agent skill's tool list, CHANGELOG, CONTRIBUTING.md. +- **Tests:** each removed tool's tests go; the support-level and description + checks gain the new rules. No live run is needed for removals; the two + replacements that gain behaviour (`save_file`, `get_model_info`) get a + live check in one bundle. +- Issue #174 closes with this change. The VBA generators are left to + item 14's optional toolsets, not merged here. diff --git a/openspec/changes/honest-tool-list/specs/tools/document-inspection/spec.md b/openspec/changes/honest-tool-list/specs/tools/document-inspection/spec.md new file mode 100644 index 00000000..a8dc0c9c --- /dev/null +++ b/openspec/changes/honest-tool-list/specs/tools/document-inspection/spec.md @@ -0,0 +1,17 @@ +## ADDED Requirements + +### Requirement: Model info includes the file's details +`get_model_info` SHALL report, besides what it reports today, the active +document's file size in bytes and its created and modified times, read +from the file on disk. For a document never saved, they SHALL be `null`. + +#### Scenario: A saved part +- **WHEN** a part saved to disk is active and an agent calls + `get_model_info` +- **THEN** the reply has `size_bytes` above 0 and `created` and `modified` + times, as `get_file_properties` reports them + +#### Scenario: A new, unsaved part +- **WHEN** a part never saved is active +- **THEN** `size_bytes`, `created` and `modified` are `null`, and the call + succeeds diff --git a/openspec/changes/honest-tool-list/specs/tools/file-saving/spec.md b/openspec/changes/honest-tool-list/specs/tools/file-saving/spec.md new file mode 100644 index 00000000..ede70f1e --- /dev/null +++ b/openspec/changes/honest-tool-list/specs/tools/file-saving/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: save_file checks a new path before writing +When `save_file` is given `file_path`, it SHALL check, before calling +SolidWorks, that the folder exists and is writable, that the extension +matches the active document's type (`.sldprt`, `.sldasm`, `.slddrw`), and +that no file is there unless `overwrite` is on. A failed check SHALL be an +`invalid_input` error that leaves the disk unchanged. + +#### Scenario: A part saved to a missing folder +- **WHEN** the active document is a part and `save_file` is called with + `C:/no/such/folder/bracket.sldprt` +- **THEN** the call fails with `invalid_input` naming the folder, and + SolidWorks is not asked to save + +#### Scenario: The wrong extension +- **WHEN** the active document is an assembly and `file_path` ends `.sldprt` +- **THEN** the call fails with `invalid_input` naming `.sldasm` + +#### Scenario: Saving in place +- **WHEN** `save_file` is called with no `file_path` +- **THEN** the document is saved to its own path, as before diff --git a/openspec/changes/honest-tool-list/specs/tools/support-levels/spec.md b/openspec/changes/honest-tool-list/specs/tools/support-levels/spec.md new file mode 100644 index 00000000..a485944f --- /dev/null +++ b/openspec/changes/honest-tool-list/specs/tools/support-levels/spec.md @@ -0,0 +1,33 @@ +## MODIFIED Requirements + +### Requirement: One support level per tool + +Every registered tool SHALL have exactly one support level, `stable`, `beta`, `experimental`, `planned` or `deprecated`, recorded in one table, with a one-line reason for every level other than `stable`. A `deprecated` tool's reason SHALL name its replacement (or say there is none) and the version it was deprecated in. + +#### Scenario: A new tool without a level +- **WHEN** a tool is registered that the table does not list +- **THEN** the support-level check fails and names the tool + +#### Scenario: A listed tool that no longer exists +- **WHEN** the table lists a name that no registered tool has +- **THEN** the check fails and names it + +#### Scenario: A deprecated tool without a replacement named +- **WHEN** a tool is `deprecated` and its entry names neither a registered replacement nor "no replacement" +- **THEN** the check fails and names the tool + +### Requirement: Levels are consistent with the code + +The check SHALL fail when a level contradicts what the code shows. A `planned` tool's reason SHALL name the queue item that builds it. + +#### Scenario: Planned means not implemented +- **WHEN** a tool is `planned` +- **THEN** its description says "Not available yet", no tool outside `planned` says so, and its reason names a queue item + +#### Scenario: Stable means checked live +- **WHEN** a tool is `stable` +- **THEN** at least one test under `tests/live/` calls it by name + +#### Scenario: After the clean-up +- **WHEN** the levels are counted after this change +- **THEN** exactly seven tools are `planned`, all drawing tools, each naming queue item 12 diff --git a/openspec/changes/honest-tool-list/specs/tools/tool-deprecation/spec.md b/openspec/changes/honest-tool-list/specs/tools/tool-deprecation/spec.md new file mode 100644 index 00000000..f1a7307f --- /dev/null +++ b/openspec/changes/honest-tool-list/specs/tools/tool-deprecation/spec.md @@ -0,0 +1,42 @@ +## Purpose + +A tool replaced by another keeps working for one minor release, and says +what replaced it, so a client can move without breaking. + +## ADDED Requirements + +### Requirement: A deprecated tool keeps working and names its replacement +A tool at the `deprecated` level SHALL behave as before. Its description +SHALL open with "Deprecated: use ``." (or "Deprecated: no +replacement." when there is none), and a successful result SHALL carry that +sentence as `warning`. + +#### Scenario: Calling a deprecated tool +- **WHEN** an agent calls `load_part` with a valid part path +- **THEN** the part opens as before, and the result's `warning` is + "Deprecated: use `open_model`." + +#### Scenario: Reading its description +- **WHEN** a client lists the tools +- **THEN** `load_part`'s description starts "Deprecated: use `open_model`." + and its tags include `level:deprecated` + +### Requirement: A replacement covers what it replaces +A tool SHALL be deprecated only when its replacement accepts every input +the deprecated tool accepted, or the description names the other tool +that does the rest. + +#### Scenario: save_assembly's reference copy +- **WHEN** `save_assembly` is deprecated in favour of `save_file` +- **THEN** its description says to use `pack_and_go_assembly` for a copy + with the referenced parts + +### Requirement: Deprecated tools are removed at the next major release +The support-level check SHALL fail when the package's major version is +higher than the one a tool was deprecated in and the tool is still +registered. + +#### Scenario: Releasing 3.0.0 +- **WHEN** the version is 3.0.0 and `load_part` (deprecated in 2.1.0) is + still registered +- **THEN** the check fails and names `load_part` diff --git a/openspec/changes/honest-tool-list/specs/tools/tool-naming/spec.md b/openspec/changes/honest-tool-list/specs/tools/tool-naming/spec.md new file mode 100644 index 00000000..bf490f23 --- /dev/null +++ b/openspec/changes/honest-tool-list/specs/tools/tool-naming/spec.md @@ -0,0 +1,34 @@ +## Purpose + +Tool names use one verb per meaning, so an agent can guess a tool's name +and tell two tools apart from their names alone. + +## ADDED Requirements + +### Requirement: One verb per meaning +A tool's name SHALL start with a verb from the list in +`docs/agents/tool-description-standard.md`: + +| Verb | Meaning | +| --- | --- | +| `create_` | makes a new document, or a new feature built from a sketch or acting on the whole body (extrusion, rib, hole, shell) | +| `add_` | adds an entity to an open sketch or a drawing, or treats edges or faces of an existing body (fillet, chamfer, draft, thread) | +| `pattern_`, `mirror_` | repeats existing features | +| `sketch_` | an operation on the open sketch's entities (offset, mirror, pattern, convert) | +| `get_` | reads one thing | +| `list_` | reads a collection | +| `set_` | changes one value | +| `open_`, `save_`, `close_`, `export_` | file operations | +| `check_`, `verify_`, `measure_`, `compare_` | read-only checks | + +Names already registered that break the list SHALL be listed as +exceptions in the same file, and the check SHALL fail on any other name +that breaks it. + +#### Scenario: A new tool with an unlisted verb +- **WHEN** a tool named `make_hole` is registered +- **THEN** the naming check fails and names the tool and the verb list + +#### Scenario: An existing exception +- **WHEN** `insert_component` is registered +- **THEN** the check passes because it is a listed exception diff --git a/openspec/changes/honest-tool-list/tasks.md b/openspec/changes/honest-tool-list/tasks.md new file mode 100644 index 00000000..24836a84 --- /dev/null +++ b/openspec/changes/honest-tool-list/tasks.md @@ -0,0 +1,48 @@ +## 1. The deprecated level + +- [ ] 1.1 `SupportLevel.DEPRECATED` and `Support.since`; `warning()` gives "Deprecated: use ``." or "Deprecated: no replacement."; tests +- [ ] 1.2 `ToolRegistrar`: the description opening and success `warning` for deprecated tools (same path as beta); tests +- [ ] 1.3 Support-level test: a deprecated entry names a registered replacement or "no replacement"; fails when the major version is above `since`'s; every planned reason names a queue item; tests for each rule +- [ ] 1.4 Progress generator: deprecated tools counted on their own, left out of the coverage bars; tests + +## 2. Remove the 33 planned tools + +- [ ] 2.0 Check `manage_design_table` before removing it: does `IModelDoc2.InsertFamilyTableNew` work on the user's machine (it needs Excel), and is there a read path (`IDesignTable`) without Excel? Record the finding in design.md. If design tables work, keep the tool `planned` for queue item 13 (`configuration-tools`) and add it there; otherwise remove it with the rest. Its live probe joins this change's live bundle (7.1), not a separate run +- [ ] 2.1 Analysis, automation, drawing (`add_annotation`) and export: remove the tools, input models, hints, levels and tests +- [ ] 2.2 Drawing analysis (six), file management (three), macros (six), sketching (`tutorial_simple_hole`), templates (five): the same +- [ ] 2.3 Remove every "use ``" sentence from other descriptions; a test that no description names an unregistered tool +- [ ] 2.4 The seven planned drawing tools' reason: "planned in queue item 12 (the drawing pack)." + +## 3. Replacements gain what they replace + +- [ ] 3.1 `save_file`: `overwrite` input, `_prepare_save_target` on a new path with the extension from the active document's type; tests for a missing folder, the wrong extension, an existing file, and in place +- [ ] 3.2 `get_model_info`: `size_bytes`, `created`, `modified` from one `os.stat` helper shared with `get_file_properties`; tests for saved and unsaved +- [ ] 3.3 Mock adapter: the model info it returns carries a path that the tests can stat, and an unsaved document has none; tests + +## 4. Deprecate the eight stable duplicates + +- [ ] 4.1 Levels: `load_part`, `load_assembly` → `open_model`; `save_part`, `save_assembly` → `save_file`; `calculate_mass_properties` → `get_mass_properties`; `get_file_properties` → `get_model_info`; `add_drawing_view` → `create_drawing_view`; `sketch_tutorial_simple_hole` → no replacement; all `since` 2.1.0 +- [ ] 4.2 `save_assembly`'s description names `pack_and_go_assembly` for `include_references` +- [ ] 4.3 Replacements' descriptions drop "for X, use ``" pointers; tests + +## 5. Verb list + +- [ ] 5.1 The verb table and its exceptions in `docs/agents/tool-description-standard.md`; CONTRIBUTING.md links it +- [ ] 5.2 The naming check in the description-standard test; a test that an unlisted verb fails + +## 6. Docs + +- [ ] 6.1 Tool catalog pages: removed rows gone, deprecated rows marked +- [ ] 6.2 The agent skill's tool lists and `errors-and-limits.md` +- [ ] 6.3 README counts and progress bars regenerated (`python -m solidworks_mcp.progress.generate`) +- [ ] 6.4 CHANGELOG (2.1.0): Removed (the 33 names), Deprecated (the eight), Changed (`save_file` refuses an existing file without `overwrite`; `get_model_info` adds file details) + +## 7. Live bundle (one set, run together, then fixes one by one) + +- [ ] 7.1 Live tests: `save_file` to a new path, a missing folder and an existing file; `get_model_info` on a saved and a new part; one deprecated tool's `warning`; the design-table probe (task 2.0): insert one on a scratch part and read it back +- [ ] 7.2 Hand the user the bundle; fix each failure afterwards, one at a time + +## 8. Finish + +- [ ] 8.1 Full mock suite at 100% coverage, ruff, `mkdocs build --strict` +- [ ] 8.2 Sign-off, PR (no attribution) closing #174, archive, the queue updated diff --git a/openspec/changes/part-feature-depth/.openspec.yaml b/openspec/changes/part-feature-depth/.openspec.yaml new file mode 100644 index 00000000..55ab199b --- /dev/null +++ b/openspec/changes/part-feature-depth/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-12 diff --git a/openspec/changes/part-feature-depth/design.md b/openspec/changes/part-feature-depth/design.md new file mode 100644 index 00000000..4084b8ab --- /dev/null +++ b/openspec/changes/part-feature-depth/design.md @@ -0,0 +1,108 @@ +## Context + +The feature tools live in `tools/modeling.py` and call adapter methods +implemented in `adapters/solidworks/features.py` (real) and +`mock_adapter.py`. Faces and edges are already picked by points: +`create_reference_plane`'s `face_point`, `select_face_edges`, and +`face_selection.py`'s helpers, which rebuild first and pass a `VT_DISPATCH` +null callout (runbook #11, #13). `pattern_circular` and `mirror_feature` +already check the volume change, and the extrude tools report +`measured_change`. + +The COM calls, from the type library index (`lookup_api_method`): + +| Tool | COM call | +| --- | --- | +| `create_hole` | `IFeatureManager.HoleWizard5` (27 arguments) | +| `add_cosmetic_thread` | `IFeatureManager.InsertCosmeticThread3(Standard, StandardType, Size, Diameter, EndType, Depth, Note)` | +| `pattern_linear` | `IFeatureManager.FeatureLinearPattern5` (22 arguments) | +| `create_shell` | `IModelDoc2.InsertFeatureShell(Thickness, Outward)` | +| `add_draft` | `IFeatureManager.InsertMultiFaceDraft(Angle, FlipDir, EdgeDraft, PropType, IsStepDraft, IsBodyDraft)` | +| `create_rib` | `IFeatureManager.InsertRib(Is2Sided, ReverseThicknessDir, Thickness, ReferenceEdgeIndex, ReverseMaterialDir, IsDrafted, DraftOutward, DraftAngle, IsNormToSketch, IsDraftedFromWall)` | +| `sketch_convert_entities` | `ISketchManager.SketchUseEdge3(Chain, InnerLoops)` | + +## Goals / Non-Goals + +**Goals:** +- The six features and convert-entities, each in one call, with points + for every pick. +- Each solid tool proves itself by the volume change, as the existing ones + do. + +**Non-Goals:** +- Several holes in one call: one hole per call, then `pattern_linear` or + `pattern_circular`. Editing a Hole Wizard position sketch is a second + feature's worth of work. +- Every Hole Wizard standard and fastener type: ISO and ANSI inch, four + hole types, a fixed size list each. +- Variable-pitch patterns, step draft, drafted ribs, multi-thickness + shells. +- Sheet metal (queue item 15). + +## Decisions + +### 1. Points for every pick, through `face_selection.py` + +Every face or edge input is a point in millimetres, as the existing tools +take, resolved by the shared helpers (rebuild once, `SelectByID2` with +`FACE` or `EDGE` and the null callout, read the selected object's type). +Marks: the shell's faces to remove and the draft's faces are mark 1 (the +draft's neutral face is mark 2), set through the helpers' `append`/`mark` +arguments. No tool takes face or edge names; agents don't know them. + +### 2. `HoleWizard5` is mapped by a live diagnostic first + +`HoleWizard5` takes integer standard, fastener-type and end-condition +codes, a size string, and twelve type-dependent values. The first task is +a live diagnostic (run in the bundle, not before) that makes one hole of +each of the four types for ISO and ANSI at one size, with the codes from +the `swWzdHoleStandards_e` and `swWzdHoleStandardFastenerTypes_e` enums, +and records which arguments SolidWorks honours. The tool's table of +`(hole_type, standard) → (StandardIndex, FastenerTypeIndex)` and its size +lists come from that run. Until it passes, `create_hole` is `beta`. + +The hole sits where the face was picked: `HoleWizard5` places the hole at +the selection point of the selected face. + +### 3. `pattern_linear` mirrors `pattern_circular` + +Same input style (`features`, plus per-direction direction, count and +spacing), same adapter flow: select the features (mark 4), the direction +edge or axis (mark 1, and mark 2 for direction 2), call +`FeatureLinearPattern5` with `GeometryPattern` off and the +`CtrlByNum`/offset arguments at their defaults, then check the volume. + +### 4. One success rule + +A solid tool succeeds when its feature exists and the volume moved. When +SolidWorks returns a feature but the volume didn't change, the tool deletes +the feature it made (the same path `delete_feature` uses) and fails, so a +failure never leaves a no-op feature in the tree. `add_cosmetic_thread` is +the exception: its check is the thread feature in the tree and an +unchanged volume. + +### 5. `sketch_convert_entities` returns registry ids + +The sketch adapter keeps a registry of entities it created so other tools +can name them. `SketchUseEdge3` returns only a Boolean, so the adapter +reads the sketch's segments before and after, registers the new ones, and +sets them to construction when asked (`ISketchSegment.ConstructionGeometry`). + +### 6. Names follow the verb list + +`create_` for features built from a sketch or acting on the body (hole, +shell, rib), `add_` for treating existing faces and edges (draft, thread), +`pattern_` and `sketch_` as listed in the honest-tool-list change's verb +table. This change depends on that change being merged first. + +## Risks / Trade-offs + +- [`HoleWizard5`'s codes differ by SolidWorks version] → the diagnostic + runs on the user's SolidWorks 2026; the tool stays `beta` with that as + its reason until checked on another version. +- [A point on an edge also lies on two faces] → face picks use `FACE`, edge + picks `EDGE`; the helpers already handle this for chamfers. +- [Seven new tools grow the tool list] → item 10 removes 33 first, and + item 14's toolsets can turn families off. +- [Shell or draft fails on a body with fillets] → SolidWorks' own error is + passed on through the error classifier; no retry. diff --git a/openspec/changes/part-feature-depth/proposal.md b/openspec/changes/part-feature-depth/proposal.md new file mode 100644 index 00000000..a57fc38e --- /dev/null +++ b/openspec/changes/part-feature-depth/proposal.md @@ -0,0 +1,78 @@ +## Why + +An agent can extrude, cut, revolve, sweep, loft, fillet, chamfer and +pattern around an axis, but it can't make the features most real parts +need next: a standard tapped or counterbored hole, a thread, a row of +features, a hollowed body, drafted walls for moulding, or a rib. The +closest comparable server leads with holes and threads, so this is where an +agent comparing the two finds us short. An agent working without these +draws a circle at a guessed size and cuts it, which gives no thread data, +no standard callout in a drawing, and a part that doesn't match the +fastener. Issue #105 (convert entities) was hit live: an agent couldn't +sketch on an existing edge and cut in the wrong place. + +## What Changes + +- **`create_hole`**: a Hole Wizard hole (simple, counterbored, + countersunk or tapped) of a standard size (`M6`, `#10`, ...) on a flat + face, at a point on that face, blind to a depth or through all. +- **`add_cosmetic_thread`**: a cosmetic thread on a cylindrical edge picked + by a point, to a standard size and depth (or through), so a drawing shows + the thread callout. +- **`pattern_linear`**: repeats features along one or two directions given + by edges or axes, with count and spacing, like `pattern_circular`. +- **`create_shell`**: hollows the active body to a wall thickness, with the + faces to remove picked by points, inward or outward. +- **`add_draft`**: drafts faces picked by points by an angle against a + neutral plane or face. +- **`create_rib`**: a rib from an open sketch, of a thickness, on one or + both sides of the sketch. +- **`sketch_convert_entities`**: projects edges (picked by points) or a + face's outline into the open sketch, as normal or construction + geometry, and returns the new entities' ids (#105). +- Each solid-changing tool replies with `measured_change`, as the extrude + tools do, and fails when the volume does not change. + +## Capabilities + +### New Capabilities + +- `tools/hole-wizard`: `create_hole` makes a standard hole at a point on a + flat face. +- `tools/cosmetic-thread`: `add_cosmetic_thread` adds a thread to a + cylindrical edge. +- `tools/shell-draft-rib`: `create_shell`, `add_draft` and `create_rib` + shape an existing body. +- `tools/sketch-convert-entities`: `sketch_convert_entities` copies model + edges into the open sketch. + +### Modified Capabilities + +- `tools/feature-patterns`: `pattern_linear` joins `pattern_circular` and + `mirror_feature` under the volume-change rule. +- `tools/measured-feature-change`: the new solid tools report + `measured_change`. + +## Impact + +- **COM and adapter code, all on the connect thread inside + `_handle_com_operation`:** + - `adapters/solidworks/features.py`: `IFeatureManager.HoleWizard5`, + `InsertCosmeticThread3`, `FeatureLinearPattern5`, + `InsertMultiFaceDraft`, `InsertRib`, and `IModelDoc2.InsertFeatureShell`; + - `adapters/solidworks/sketch.py`: `ISketchManager.SketchUseEdge3`; + - face and edge picks through `face_selection.py` (`ForceRebuild3` + first, `SelectByID2` with a `VT_DISPATCH` null callout: runbook #11, + #13). + - Seven new adapter methods through `base.py`, `circuit_breaker.py`, + `connection_pool.py` and `mock_adapter.py`. +- **Tools:** `modeling.py` (six tools), `sketching.py` + (`sketch_convert_entities`), `tool_hints.py`, `support_levels.py`. +- **Docs:** tool catalog pages, the agent skill's workflow notes (hole + before thread, convert then cut), `docs/planning/solidworks-api-coverage.md` + section 3.7, CHANGELOG, regenerated progress bars. +- **Live tests:** one bundle at the end; `HoleWizard5`'s 27 arguments are + checked live before the tool's inputs are fixed (design decision 2). +- Closes #105. Sheet metal (#57) is queue item 15, not this change. +- **Depends on the honest-tool-list change (queue item 10)**, merged + first: the tool names follow its verb list. diff --git a/openspec/changes/part-feature-depth/specs/tools/cosmetic-thread/spec.md b/openspec/changes/part-feature-depth/specs/tools/cosmetic-thread/spec.md new file mode 100644 index 00000000..c990c4e3 --- /dev/null +++ b/openspec/changes/part-feature-depth/specs/tools/cosmetic-thread/spec.md @@ -0,0 +1,28 @@ +## Purpose + +`add_cosmetic_thread` marks a cylindrical edge as threaded, so the thread +shows in drawings without modelling its helix. + +## ADDED Requirements + +### Requirement: A thread on a circular edge +`add_cosmetic_thread` SHALL take `edge_point`, `[x, y, z]` in millimetres +on a circular edge of the active part, `standard` (`iso` or `ansi_inch`), +`size`, and either `depth` in millimetres or `through: true`. It SHALL add +one cosmetic thread feature on that edge and reply with its name. The +part's volume SHALL be unchanged. + +#### Scenario: A thread on a shaft end +- **WHEN** a Ø10 mm shaft is active and `add_cosmetic_thread` is called + with a point on its end edge, `iso`, `M10` and `depth` 15 +- **THEN** a cosmetic thread feature appears under the shaft's feature, + and the volume is unchanged + +### Requirement: The edge must be circular +When `edge_point` is not on a circular edge, `add_cosmetic_thread` SHALL +fail with `invalid_input`, name the point, and add nothing. + +#### Scenario: A straight edge +- **WHEN** `edge_point` is on a straight edge of a block +- **THEN** the call fails with `invalid_input` saying the edge is not + circular diff --git a/openspec/changes/part-feature-depth/specs/tools/feature-patterns/spec.md b/openspec/changes/part-feature-depth/specs/tools/feature-patterns/spec.md new file mode 100644 index 00000000..a7853899 --- /dev/null +++ b/openspec/changes/part-feature-depth/specs/tools/feature-patterns/spec.md @@ -0,0 +1,35 @@ +## MODIFIED Requirements + +### Requirement: A pattern or mirror succeeds when the volume changes + +`pattern_circular`, `pattern_linear` and `mirror_feature` SHALL succeed when the part's volume +changes, up or down, and SHALL fail when it doesn't change. The reply SHALL +include the volume before and after. + +#### Scenario: A ring of holes +- **WHEN** an agent patterns a Ø6 mm through-hole in a 10 mm plate 6 times around an axis, with every instance on the plate +- **THEN** the call succeeds and the volume falls by 5 × π·3²·10 = 1,413.7 mm³ within 0.1 % + +#### Scenario: A row of holes +- **WHEN** an agent patterns a Ø6 mm through-hole in a 10 mm plate 4 times at 15 mm along a straight edge of the plate +- **THEN** the call succeeds and the volume falls by 3 × π·3²·10 = 848.2 mm³ within 0.1 % + +#### Scenario: A mirrored cut +- **WHEN** an agent mirrors a cut about a plane, and the mirrored cut lands on the body +- **THEN** the call succeeds and the volume falls by the cut's volume + +#### Scenario: Nothing patterned +- **WHEN** a pattern's instances all land off the body, so the volume is unchanged +- **THEN** the call fails and says the pattern produced no geometry + +## ADDED Requirements + +### Requirement: A linear pattern along one or two directions +`pattern_linear` SHALL take `features` (at least one name), `direction_1` +(an edge picked by a point, or an axis name), `count_1` (at least 2) and +`spacing_1` in millimetres, and optionally `direction_2`, `count_2` and +`spacing_2` for a grid, plus `reverse_1` and `reverse_2`. + +#### Scenario: A 3 × 2 grid +- **WHEN** a hole is patterned 3 times at 15 mm along one edge and 2 times at 20 mm along the other +- **THEN** six holes exist in all and the volume falls by five holes' volume diff --git a/openspec/changes/part-feature-depth/specs/tools/hole-wizard/spec.md b/openspec/changes/part-feature-depth/specs/tools/hole-wizard/spec.md new file mode 100644 index 00000000..a34f793f --- /dev/null +++ b/openspec/changes/part-feature-depth/specs/tools/hole-wizard/spec.md @@ -0,0 +1,45 @@ +## Purpose + +`create_hole` makes a standard Hole Wizard hole at a point on a flat face, +so the hole matches its fastener and a drawing can call it out. + +## ADDED Requirements + +### Requirement: A standard hole at a point on a face +`create_hole` SHALL take `hole_type` (`simple`, `counterbore`, +`countersink` or `tapped`), `standard` (`iso` or `ansi_inch`), `size` (for +example `M6`, `#10`), `end_condition` (`blind` or `through_all`), `depth` +in millimetres for `blind`, and `position`, `[x, y, z]` in millimetres on a +flat face of the active part. It SHALL make one Hole Wizard feature at that +point, normal to the face, and reply with the feature's name and +`measured_change`. + +#### Scenario: A through M6 counterbore +- **WHEN** a 10 mm plate is active and `create_hole` is called with + `counterbore`, `iso`, `M6`, `through_all` and a point on the top face +- **THEN** one Hole Wizard feature appears in the tree, the volume falls, + and the reply names the feature + +#### Scenario: A blind tapped hole +- **WHEN** `create_hole` is called with `tapped`, `iso`, `M5`, `blind` and + `depth` 8 +- **THEN** the hole is 8 mm deep (measured from the volume change within + 1 %), and its feature carries the M5 thread data + +### Requirement: Bad hole inputs fail before SolidWorks +`create_hole` SHALL fail with `invalid_input` when `size` is not a size of +the given `standard` and `hole_type`, when `blind` has no `depth`, or when +`position` is not three numbers; nothing SHALL be added. + +#### Scenario: A size from the wrong standard +- **WHEN** `standard` is `iso` and `size` is `#10` +- **THEN** the call fails with `invalid_input` listing the ISO sizes + +### Requirement: The point must be on a flat face +When `position` is not on a flat face of the active part, `create_hole` +SHALL fail with `invalid_input`, name the point, and add nothing. + +#### Scenario: A point in the air +- **WHEN** `position` is 50 mm above the plate +- **THEN** the call fails with `invalid_input` and the feature tree is + unchanged diff --git a/openspec/changes/part-feature-depth/specs/tools/measured-feature-change/spec.md b/openspec/changes/part-feature-depth/specs/tools/measured-feature-change/spec.md new file mode 100644 index 00000000..47d63dd1 --- /dev/null +++ b/openspec/changes/part-feature-depth/specs/tools/measured-feature-change/spec.md @@ -0,0 +1,13 @@ +## ADDED Requirements + +### Requirement: The new solid feature tools report the measured change +On success, `create_hole`, `create_shell`, `add_draft`, `create_rib` and +`pattern_linear` SHALL include the same `measured_change` block as +`create_extrusion`, under the same best-effort rule. `create_hole`, +`create_shell` and `create_rib` SHALL fail, removing nothing, when the +volume is unchanged. + +#### Scenario: A hole off the body +- **WHEN** SolidWorks accepts a hole that removes no material +- **THEN** the call fails, says the hole changed no volume, and the hole + feature is deleted so the tree is as before diff --git a/openspec/changes/part-feature-depth/specs/tools/shell-draft-rib/spec.md b/openspec/changes/part-feature-depth/specs/tools/shell-draft-rib/spec.md new file mode 100644 index 00000000..c5bc04b0 --- /dev/null +++ b/openspec/changes/part-feature-depth/specs/tools/shell-draft-rib/spec.md @@ -0,0 +1,54 @@ +## Purpose + +`create_shell`, `add_draft` and `create_rib` shape an existing body: hollow +it, taper its walls, or stiffen it, each picked by points the agent already +knows. + +## ADDED Requirements + +### Requirement: Shell to a wall thickness +`create_shell` SHALL take `thickness` in millimetres, `remove_face_points` +(a list of `[x, y, z]` points, each on a face to remove; may be empty for a +closed hollow body) and `outward` (default off). It SHALL make one shell +feature and reply with its name and `measured_change`. + +#### Scenario: An open box +- **WHEN** a 40 × 40 × 20 mm block is active and `create_shell` is called + with `thickness` 2 and a point on the top face +- **THEN** the volume falls to 40·40·20 − 36·36·18 = 8,672 mm³ within 0.5 % + +#### Scenario: Too thick +- **WHEN** `thickness` is more than half the block's smallest size +- **THEN** the call fails, says SolidWorks could not build the shell, and + the tree is unchanged + +### Requirement: Draft faces against a neutral plane +`add_draft` SHALL take `angle` in degrees (above 0 and below 90), +`neutral_point` (a point on the neutral face) or `neutral_plane` (a plane +name), exactly one of them, and `face_points` (points on the faces to +draft, at least one). It SHALL make one draft feature and reply with its +name and `measured_change`. + +#### Scenario: Drafting a block's sides +- **WHEN** a block's four side faces are drafted 5° from its bottom face +- **THEN** one draft feature appears and the volume changes + +#### Scenario: Both neutral inputs +- **WHEN** `neutral_point` and `neutral_plane` are both given +- **THEN** the call fails with `invalid_input` + +### Requirement: A rib from an open sketch +`create_rib` SHALL take `sketch` (the name of an open-profile sketch), +`thickness` in millimetres, `both_sides` (default on) and `flip_material` +(default off). It SHALL make one rib feature and reply with its name and +`measured_change`. + +#### Scenario: A rib between two walls +- **WHEN** a sketch line runs between two walls of a shelled box and + `create_rib` is called with `thickness` 3 +- **THEN** one rib feature appears and the volume rises + +#### Scenario: A rib that reaches nothing +- **WHEN** the rib's sketch does not reach the body in its material + direction +- **THEN** the call fails and says the rib added no material diff --git a/openspec/changes/part-feature-depth/specs/tools/sketch-convert-entities/spec.md b/openspec/changes/part-feature-depth/specs/tools/sketch-convert-entities/spec.md new file mode 100644 index 00000000..7cf8f705 --- /dev/null +++ b/openspec/changes/part-feature-depth/specs/tools/sketch-convert-entities/spec.md @@ -0,0 +1,35 @@ +## Purpose + +`sketch_convert_entities` copies model edges into the open sketch, so a new +feature can be drawn on the real geometry instead of a guessed copy of it. + +## ADDED Requirements + +### Requirement: Edges or a face outline into the open sketch +`sketch_convert_entities` SHALL take exactly one of `edge_points` (points +on edges of the active part) and `face_point` (a point on a face, whose +outer loop is converted), plus `construction` (default off). With a sketch +open, it SHALL add one sketch entity per converted edge and reply with the +new entities' ids, usable by `add_sketch_constraint` and +`add_sketch_dimension`. + +#### Scenario: A face outline +- **WHEN** a sketch is open on a plate's top face and + `sketch_convert_entities` is called with a point on that face +- **THEN** four lines are added, one per edge of the face, and their ids + are returned + +#### Scenario: Construction geometry +- **WHEN** `construction` is on +- **THEN** the converted entities are construction geometry, and a cut + from the sketch uses only the other entities + +### Requirement: No sketch or no edge fails +`sketch_convert_entities` SHALL fail with `invalid_input` when no sketch is +open, or when a point is not on an edge (or face) of the active part, +naming the point; nothing SHALL be added. + +#### Scenario: No sketch open +- **WHEN** no sketch is open +- **THEN** the call fails with `invalid_input` saying to open a sketch with + `create_sketch` first diff --git a/openspec/changes/part-feature-depth/tasks.md b/openspec/changes/part-feature-depth/tasks.md new file mode 100644 index 00000000..1bdaab60 --- /dev/null +++ b/openspec/changes/part-feature-depth/tasks.md @@ -0,0 +1,46 @@ +## 1. Shared pieces + +- [ ] 1.1 `face_selection.py`: pick a face or edge by point with a mark and append, and report whether it is flat, circular or neither; tests +- [ ] 1.2 Feature tools' shared success rule: the feature exists and the volume moved, else delete the feature and fail; tests + +## 2. Linear pattern + +- [ ] 2.1 `PatternLinearInput`, `pattern_linear` tool, hints, level; tests +- [ ] 2.2 Adapter interface `pattern_linear` in `base.py`, `circuit_breaker.py`, `connection_pool.py`; tests +- [ ] 2.3 Real adapter: select features and directions, `FeatureLinearPattern5`, volume check; tests +- [ ] 2.4 Mock adapter: a pattern's volume change from count and the seed's volume; tests + +## 3. Shell, draft, rib + +- [ ] 3.1 Inputs and tools `create_shell`, `add_draft`, `create_rib`; the one-of rule for the neutral face; tests +- [ ] 3.2 Adapter interface for the three, through every layer; tests +- [ ] 3.3 Real adapter: `InsertFeatureShell`, `InsertMultiFaceDraft`, `InsertRib`, with the picks and marks; tests +- [ ] 3.4 Mock adapter: the open-box shell volume, a draft's volume change, a rib's volume; tests + +## 4. Holes and threads + +- [ ] 4.1 `CreateHoleInput` with the hole type, standard, size table and end condition; `invalid_input` for a size outside the table and a blind hole with no depth; tests +- [ ] 4.2 `AddCosmeticThreadInput` and tool; tests +- [ ] 4.3 Adapter interface for both, through every layer; tests +- [ ] 4.4 Real adapter: `HoleWizard5` from the code table (to be confirmed by 6.1), `InsertCosmeticThread3` on a circular edge; tests +- [ ] 4.5 Mock adapter: a hole's volume from its size and depth; a thread leaves the volume; tests + +## 5. Convert entities + +- [ ] 5.1 `SketchConvertEntitiesInput` (one of `edge_points`, `face_point`; `construction`) and tool; tests +- [ ] 5.2 Adapter interface through every layer; tests +- [ ] 5.3 Real adapter: picks, `SketchUseEdge3`, new segments registered, construction set; tests +- [ ] 5.4 Mock adapter: a face's four edges become four registered lines; tests + +## 6. Live bundle (one set, run together, then fixes one by one) + +- [ ] 6.1 Hole Wizard diagnostic: one hole of each type for ISO and ANSI, recording which codes SolidWorks honoured +- [ ] 6.2 Live tests for each tool's spec scenarios: the 3 × 2 grid, the open box, drafted sides, a rib in the box, an M6 counterbore and M5 tapped hole, an M10 thread, a converted face outline cut through; each failure case +- [ ] 6.3 Hand the user the bundle; fix each failure afterwards, one at a time; move `create_hole` to stable when the diagnostic and its tests pass + +## 7. Docs and finish + +- [ ] 7.1 Tool catalog pages, the agent skill's notes (one hole per call then pattern; thread after hole; convert then cut), `docs/planning/solidworks-api-coverage.md` section 3.7 +- [ ] 7.2 CHANGELOG (Added), progress bars regenerated +- [ ] 7.3 Full mock suite at 100% coverage, ruff, `mkdocs build --strict` +- [ ] 7.4 Sign-off, PR (no attribution) closing #105, archive, the queue updated diff --git a/openspec/changes/tool-discovery-mode/.openspec.yaml b/openspec/changes/tool-discovery-mode/.openspec.yaml new file mode 100644 index 00000000..55ab199b --- /dev/null +++ b/openspec/changes/tool-discovery-mode/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-12 diff --git a/openspec/changes/tool-discovery-mode/design.md b/openspec/changes/tool-discovery-mode/design.md new file mode 100644 index 00000000..370f31c6 --- /dev/null +++ b/openspec/changes/tool-discovery-mode/design.md @@ -0,0 +1,101 @@ +## Context + +`ToolRegistrar` tags every tool with its family (the defining module's +name, `tool_family()` in `tools/tool_boundary.py`) and its level. The +families are: `analysis`, `automation`, `docs_discovery`, `drawing`, +`drawing_analysis`, `drawing_automation`, `engineering_data`, `export`, +`file_management`, `macro_recording`, `modeling`, `server_admin`, +`sketching`, `template_management`, `vba_generation`. + +FastMCP 3.4.9, the pinned version, provides both pieces: + +- `enable(tags=..., only=True)` on the server: an allowlist by tag, applied + as a visibility transform; +- `fastmcp.server.transforms.search.BM25SearchTransform(max_results, + always_visible, search_tool_name, call_tool_name)`: replaces the listed + tools with `search_tools` and `call_tool`. + +Settings are read from `SOLIDWORKS_MCP_*` variables in `config.py`. + +## Goals / Non-Goals + +**Goals:** +- A smaller tool list for users who want one, with no change for users + who don't. +- Numbers that show what each choice saves. + +**Non-Goals:** +- Changing the default list. A default of `core` would hide tools from + current users without warning; the measured numbers can make the case + for that later. +- Tools that turn toolsets on and off during a session (FastMCP's + per-session visibility): clients cache the list, and few handle + `list_changed`. +- Our own search ranking. + +## Decisions + +### 1. Toolsets map families, in one table + +A `TOOLSETS: dict[str, frozenset[str]]` table beside the hints table: + +| Toolset | Families | +| --- | --- | +| `core` | modeling, sketching, file_management, analysis, engineering_data, export, server_admin | +| `drawing` | drawing, drawing_automation, drawing_analysis | +| `automation` | macro_recording, automation, template_management | +| `vba` | vba_generation | +| `docs` | docs_discovery | + +A test checks every family is in exactly one toolset. After registration, +`server.py` calls `mcp.enable(tags={}, only=True)` +unless the choice is `all`. Tools stay registered, so the support-level +and description checks still see all of them. + +### 2. Search mode is FastMCP's BM25 transform + +With `search`, `server.py` adds `BM25SearchTransform(max_results=5, +always_visible=["get_model_info", "reset_circuit_breaker"])` after the +toolset filter, so the search covers only visible tools. BM25 needs no +model or network, and ranks on names and descriptions, which item 1's +description standard already made consistent. `call_tool` runs a tool +through the same registered function, so the error boundary, levels and +warnings apply unchanged. + +*Alternative:* the regex transform. Rejected: agents search in plain +words, not patterns. + +### 3. Settings fail fast + +Both settings are validated in `config.py` at start. An unknown toolset or +mode raises a configuration error listing the valid values, and the server +doesn't start; a silently empty tool list would be worse. + +### 4. Instructions are built from the mode + +The server instructions are a constant today (`SERVER_INSTRUCTIONS`, +passed to FastMCP in `server.py`). They become a function of the two +settings, called at start. They gain one line naming the toolsets, the drawing paragraph only when `drawing` is on, +and, in search mode, a paragraph on `search_tools` and `call_tool`. The +skill gets a short "If you see `search_tools`" note. + +### 5. Measuring with the real list + +`python -m solidworks_mcp.progress.tool_list_size` starts the server +in-process with the mock adapter, reads `tools/list` per mode and toolset, +and writes bytes and an estimate of tokens (bytes ÷ 4, stated as an +estimate) to a docs table. It runs with the progress generator, so the +numbers can't go stale. + +## Risks / Trade-offs + +- [An agent in search mode can't find a tool] → BM25 on consistent + descriptions; the live check runs the U-joint-style prompts' first + steps in search mode; list mode stays the default. +- [`enable(only=True)` hides a tool another tool's description names] → + descriptions name tools across families (for example "use + `create_drawing_view`"); in a reduced set those pointers can name hidden + tools. A test lists them for `core`; the description says "(drawing + toolset)" where it points across toolsets. +- [FastMCP's transform API changes] → it is pinned at 3.4.9; the tests + exercise both transforms through the real server object. diff --git a/openspec/changes/tool-discovery-mode/proposal.md b/openspec/changes/tool-discovery-mode/proposal.md new file mode 100644 index 00000000..3cd18d88 --- /dev/null +++ b/openspec/changes/tool-discovery-mode/proposal.md @@ -0,0 +1,70 @@ +## Why + +Every tool's schema is sent to the model on every turn. After the +honest-tool-list change the list is still about 125 tools, and the next +three items add about 20 more. Glama's review called the list "bloated +rather than scoped" (issue #176), and the internal assessment found that +the size of the list, not missing tools, is now the main cost of using +the server. Users who only model parts pay for VBA generators, API-help +lookup and drawing tools on every turn, and a client with a tool limit +can't load the server at all. + +## What Changes + +- **The tool list is measured.** A script reports the size of + `tools/list`, in bytes and estimated tokens, overall and per family. The + numbers go in the docs and are regenerated with the progress files. +- **Toolsets.** `SOLIDWORKS_MCP_TOOLSETS` picks which groups of families + are registered as visible: + - `core`: modelling, sketching, file management, analysis, engineering + data, export, server admin; + - `drawing`: drawing, drawing automation, drawing analysis; + - `automation`: macros, automation, templates; + - `vba`: the VBA generators; + - `docs`: the API-help lookup tools; + - `all` (the default): everything, as today. + Several can be given, comma-separated (`core,drawing`). +- **Search mode.** `SOLIDWORKS_MCP_TOOL_MODE=search` replaces the list + with FastMCP's search transform: `search_tools` (finds tools by a + plain-language query and returns their schemas) and `call_tool`, plus a + few always-visible tools (`get_model_info`, `reset_circuit_breaker`). + `list` (the default) keeps today's full list. The two settings combine: + search covers only the chosen toolsets. +- **The server's instructions and the agent skill** say which mode is on, + and in search mode tell the agent to search before calling. +- **`--selftest`** reports the mode, the toolsets and the visible tool + count. +- No breaking change: with neither setting, the server behaves as now. + +## Capabilities + +### New Capabilities + +- `setup/toolsets`: choosing which tool families a client sees. +- `setup/tool-search-mode`: an opt-in search-and-call surface in place of + the full list. + +### Modified Capabilities + +- `agents/server-instructions`: the instructions name the active mode and, + in search mode, how to find tools. +- `setup/selftest`: the self-test reports the mode and the visible tool + count. + +## Impact + +- **No COM or adapter code changes.** Visibility is applied after + registration, with FastMCP 3.4.9's `enable(tags=..., only=True)` on the + family tags `ToolRegistrar` already adds, and its `BM25SearchTransform`. + Every tool is still registered, so the support-level and description + checks see all of them. +- **Code:** `config.py` (two settings), `server.py` (apply them after + registration), a toolset table beside `tool_hints.py`, the server + instructions, `selftest`, a measuring script under + `solidworks_mcp/progress/`. +- **Docs:** a "Choosing tools" section in the client setup page, the + numbers, the skill's note, CHANGELOG. +- **Tests:** each mode and toolset reaches the same tool bodies; `all` + equals today's list. +- Depends on the honest-tool-list change (queue item 10), which settles the + families. Closes #176. diff --git a/openspec/changes/tool-discovery-mode/specs/agents/server-instructions/spec.md b/openspec/changes/tool-discovery-mode/specs/agents/server-instructions/spec.md new file mode 100644 index 00000000..bc164bf5 --- /dev/null +++ b/openspec/changes/tool-discovery-mode/specs/agents/server-instructions/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: The instructions follow the tool mode +The server's instructions SHALL name the active toolsets. In search mode +they SHALL tell the agent to find tools with `search_tools` and run them +with `call_tool`, and SHALL name no tool the agent can't see. + +#### Scenario: Search mode +- **WHEN** a client connects to a server in search mode +- **THEN** the instructions say to search before calling, and every tool + they name directly is `search_tools`, `call_tool` or an always-visible + tool + +#### Scenario: Core only +- **WHEN** the toolsets are `core` +- **THEN** the instructions don't mention the drawing workflow diff --git a/openspec/changes/tool-discovery-mode/specs/setup/selftest/spec.md b/openspec/changes/tool-discovery-mode/specs/setup/selftest/spec.md new file mode 100644 index 00000000..650e41e1 --- /dev/null +++ b/openspec/changes/tool-discovery-mode/specs/setup/selftest/spec.md @@ -0,0 +1,10 @@ +## ADDED Requirements + +### Requirement: The tool mode is reported +The self-test's environment section SHALL report the tool mode, the +active toolsets and the number of visible tools. + +#### Scenario: A core-only setup +- **WHEN** `--selftest` runs with `SOLIDWORKS_MCP_TOOLSETS=core` +- **THEN** the report shows mode `list`, toolsets `core`, and the visible + tool count diff --git a/openspec/changes/tool-discovery-mode/specs/setup/tool-search-mode/spec.md b/openspec/changes/tool-discovery-mode/specs/setup/tool-search-mode/spec.md new file mode 100644 index 00000000..20f13657 --- /dev/null +++ b/openspec/changes/tool-discovery-mode/specs/setup/tool-search-mode/spec.md @@ -0,0 +1,44 @@ +## Purpose + +An opt-in mode in which the client sees a small search-and-call surface +instead of every tool's schema. + +## ADDED Requirements + +### Requirement: Search mode replaces the list +With `SOLIDWORKS_MCP_TOOL_MODE=search`, `tools/list` SHALL hold +`search_tools`, `call_tool` and the always-visible tools +(`get_model_info`, `reset_circuit_breaker`) only. `search_tools` SHALL +take a plain-language query and return up to five matching tools with +their full input schemas. `call_tool` SHALL run any tool the active +toolsets allow, by name, with the same result as calling it directly. + +#### Scenario: Finding and calling a tool +- **WHEN** the agent searches "fillet edges" and calls the returned + `add_fillet` through `call_tool` +- **THEN** the search's results include `add_fillet` with its schema, and + the fillet result is the same as a direct call's + +#### Scenario: A tool outside the toolsets +- **WHEN** toolsets are `core` and the agent calls `generate_vba_extrusion` + through `call_tool` +- **THEN** the call fails and says the tool is not in the active toolsets + +### Requirement: List mode is the default +With `SOLIDWORKS_MCP_TOOL_MODE` unset or `list`, the server SHALL list the +toolsets' tools directly, with no `search_tools` or `call_tool`. Any other +value SHALL stop the server at start with an error naming `list` and +`search`. + +#### Scenario: Unset +- **WHEN** the mode is unset +- **THEN** `tools/list` holds no `search_tools` + +### Requirement: The list's size is measured +A script SHALL report `tools/list`'s size in bytes and estimated tokens, +overall and per family, for list mode and for search mode, and the docs +SHALL show the latest numbers. + +#### Scenario: Regenerating +- **WHEN** the progress files are regenerated +- **THEN** the docs' size table matches the registered tools diff --git a/openspec/changes/tool-discovery-mode/specs/setup/toolsets/spec.md b/openspec/changes/tool-discovery-mode/specs/setup/toolsets/spec.md new file mode 100644 index 00000000..28566116 --- /dev/null +++ b/openspec/changes/tool-discovery-mode/specs/setup/toolsets/spec.md @@ -0,0 +1,43 @@ +## Purpose + +A user chooses which tool families their client sees, so a client pays +only for the tools its work needs. + +## ADDED Requirements + +### Requirement: Toolsets choose the visible families +The server SHALL read `SOLIDWORKS_MCP_TOOLSETS`, a comma-separated list of +`core`, `drawing`, `automation`, `vba`, `docs` and `all`. Only tools whose +family belongs to a listed toolset SHALL appear in `tools/list` and be +callable. Unset or `all` SHALL show every tool. + +#### Scenario: Core only +- **WHEN** the server starts with `SOLIDWORKS_MCP_TOOLSETS=core` +- **THEN** `tools/list` holds `create_extrusion` and `open_model`, and no + `generate_vba_*`, drawing or API-help tool + +#### Scenario: Core and drawing +- **WHEN** the setting is `core,drawing` +- **THEN** `create_drawing_view` is listed too, and the VBA generators are + not + +#### Scenario: Default +- **WHEN** the setting is unset +- **THEN** `tools/list` is the same as before this change + +### Requirement: A bad toolset name stops the server with a clear error +The server SHALL refuse to start when `SOLIDWORKS_MCP_TOOLSETS` names an +unknown toolset, and the error SHALL list the valid names. + +#### Scenario: A typo +- **WHEN** the setting is `core,drawings` +- **THEN** the server exits at start with an error naming `drawings` and + the valid toolsets + +### Requirement: Every family is in exactly one toolset +Each tool family SHALL belong to exactly one toolset, and a check SHALL +fail on a family that belongs to none or more than one. + +#### Scenario: A new family +- **WHEN** a new tool module adds a family no toolset lists +- **THEN** the check fails and names the family diff --git a/openspec/changes/tool-discovery-mode/tasks.md b/openspec/changes/tool-discovery-mode/tasks.md new file mode 100644 index 00000000..e01868d1 --- /dev/null +++ b/openspec/changes/tool-discovery-mode/tasks.md @@ -0,0 +1,38 @@ +## 1. Measure first + +- [ ] 1.1 `progress/tool_list_size.py`: `tools/list` bytes and estimated tokens, overall and per family, through the in-process server with the mock adapter; tests +- [ ] 1.2 Record today's numbers in the change's notes before anything else changes + +## 2. Toolsets + +- [ ] 2.1 The `TOOLSETS` table; a test that every family is in exactly one toolset +- [ ] 2.2 `config.py`: `tool_toolsets` from `SOLIDWORKS_MCP_TOOLSETS`, validated, default `all`; tests for a list, `all`, unset and a typo +- [ ] 2.3 `server.py`: `enable(tags=..., only=True)` after registration unless `all`; tests that `core` and `core,drawing` list the right tools and that unset equals today's list +- [ ] 2.4 Cross-toolset pointers in descriptions: list those that name a tool outside `core`, and add "(drawing toolset)" or similar; test + +## 3. Search mode + +- [ ] 3.1 `config.py`: `tool_mode` from `SOLIDWORKS_MCP_TOOL_MODE`, `list` or `search`, validated; tests +- [ ] 3.2 `server.py`: `BM25SearchTransform` with the always-visible tools, after the toolset filter; tests that search finds `add_fillet` for "fillet edges", `call_tool` gives a direct call's result, and a tool outside the toolsets is refused + +## 4. Instructions, skill and self-test + +- [ ] 4.1 Server instructions name the toolsets, leave out the drawing paragraph without `drawing`, and explain search mode; tests +- [ ] 4.2 The agent skill's note for search mode +- [ ] 4.3 `--selftest` reports mode, toolsets and visible count; tests + +## 5. Docs + +- [ ] 5.1 "Choosing tools" in the client setup page: the two settings, examples per client, and the size table +- [ ] 5.2 The size table generated with the progress files +- [ ] 5.3 CHANGELOG (Added) + +## 6. Live bundle (one set, run together, then fixes one by one) + +- [ ] 6.1 Live tests: in search mode with `core`, an agent-style sequence (search, open a part, extrude, fillet) through `call_tool`; `--selftest` with `core` +- [ ] 6.2 Hand the user the bundle; fix each failure afterwards, one at a time + +## 7. Finish + +- [ ] 7.1 Full mock suite at 100% coverage, ruff, `mkdocs build --strict` +- [ ] 7.2 Sign-off, PR (no attribution) closing #176, archive, the queue updated diff --git a/openspec/queue.md b/openspec/queue.md index 3b08306c..ca9c2281 100644 --- a/openspec/queue.md +++ b/openspec/queue.md @@ -6,7 +6,7 @@ reviewed, then implemented, signed off live where it touches SolidWorks, and archived after its PR merges. Update this file when an item is done or the order changes. -Last updated 2026-11-12. +Last updated 2026-11-14. | # | Item | Issue | OpenSpec change | State | | --- | --- | --- | --- | --- | @@ -19,20 +19,26 @@ Last updated 2026-11-12. | 6 | `--selftest` command and a compatibility-report issue template | #179 | `selftest-and-compatibility-report` (archived) | Done 2026-11-09 (#217), signed off live | | 7 | Beta tools to stable: fix each beta tool's known fault (the small faults listed below), prove it live, and move it up a level | not filed yet | `beta-tool-faults` (archived) | Done 2026-11-09 (#219, 2.0.0): 23 tools promoted, signed off live | | 8 | Experimental tools to stable: a live test for each of the 10, then promote it or record its fault | not filed yet | `experimental-tools-to-stable` (archived) | Done 2026-11-12 (2.0.0, tagged `v2.0.0`): all 10 promoted, signed off live. Pack and Go now copies the files `GetDependencies2` lists (SolidWorks 2026's own Pack and Go copied only the assembly); `comtypes` dropped | -| 9 | Monitor stand demo follow-ups | #206 | not yet written | | -| 10 | The 40 planned tools: implement each one or take it out of the tool list (listed below). A registered tool that can't run is a promise the server doesn't keep | not filed yet | not yet written | Check against #174 first, which may retire some as duplicates | -| 11 | Clear out duplicate and overlapping tools: compare each cluster, keep one, settle a verb list, deprecate old names for one release | #174 | not yet written | | -| 12 | Optional toolsets or a discovery mode, to cut the tool list's size | #176 | not yet written | After #174, which decides which families are core | -| 13 | README: licence-tier tags | #79 (other half) | not yet written | | -| 14 | Remove the stale `validate_coverage.py`; decide whether mypy gates CI | #157 | not yet written | | -| 15 | Skills that improve the agent's results, measured on the U-joint prompt | #207 | not yet written | Tabled 2026-11-09: needs research first (what "better" means, a harness to run and score sessions). See `openspec/research/agent-skill-evaluation.md` | - -## Tools that can't run yet (item 10) +| 9 | Monitor stand demo follow-ups: feature order, `verify_model`'s planes, dimension listing, STL export, `create_sketch` on a face, the demo's camera | #206 | `monitor-stand-follow-ups` (archived) | Done 2026-11-14: all five live tests pass, GIF re-recorded; PR open | +| 10 | An honest tool list: remove the 33 planned tools no item will build, deprecate the stable duplicates for one release, settle a verb list. Replaces the old items "the 40 planned tools" and "duplicate tools" | #174 | `honest-tool-list` | Planned 2026-11-12. Items 11-14 depend on it. It probes `manage_design_table` live before removing it (kept for item 13 if design tables work) | +| 11 | Part features the peers lead with: Hole Wizard holes, cosmetic threads, a linear feature pattern, shell, draft, rib, and sketch convert-entities | #105 | `part-feature-depth` | Planned 2026-11-12 | +| 12 | The drawing pack, where no peer goes: section and detail views, the title block and sheet format, drawing dimensions, and one drawing check | #102, #158 | `drawing-pack` | Planned 2026-11-12. Builds the 7 planned drawing tools item 10 leaves | +| 13 | Configurations: create, activate and delete one, and suppress a feature or set a dimension in one configuration only | none | `configuration-tools` | Planned 2026-11-12 | +| 14 | Optional toolsets and a discovery mode, to cut the tool list's size | #176 | `tool-discovery-mode` | Planned 2026-11-12. After item 10, which decides the families | +| 15 | Sheet metal: base flange, edge flange, sketched bend, flat pattern | #57 | not yet written | After item 11 | +| 16 | README: licence-tier tags | #79 (other half) | not yet written | | +| 17 | Remove the stale `validate_coverage.py`; decide whether mypy gates CI | #157 | not yet written | | +| 18 | Skills that improve the agent's results, measured on the U-joint prompt | #207 | not yet written | Tabled 2026-11-09: needs research first (what "better" means, a harness to run and score sessions). See `openspec/research/agent-skill-evaluation.md` | +## Tools that can't run yet (items 10 and 12) Each one's description says "Not available yet ... planned for a future release" (the wording is in `docs/agents/tool-description-standard.md`). Found while rewriting the descriptions (39), plus `tutorial_simple_hole` -(40 in all). Their support level is `planned`. +(40 in all). Their support level is `planned`. Item 10 removes 33 of them; +item 12 builds the seven drawing tools that are left (`add_dimension`, +`auto_dimension_view`, `create_section_view`, `create_detail_view`, +`update_title_block`, `update_sheet_format`, and `check_drawing_standards` +renamed `check_drawing`). - **Drawing analysis (7):** `analyze_drawing_comprehensive`, `analyze_drawing_dimensions`, `analyze_drawing_annotations`, @@ -70,17 +76,15 @@ their reason), then run `python -m solidworks_mcp.progress.generate`. `position` says, even off the sheet, and report success (seen in the beta live tests, 2026-11-09). They could read the sheet size (`_sheet_bounds` in `adapters/solidworks/documentation.py`) and refuse or warn. -- `export_stl` logs `Extension.SaveAs2 failed: Type mismatch` on its first - attempt, then writes the file through its fallback (seen on SolidWorks - 2026, 2026-11-09). The export works; the first attempt's arguments need - checking. ## Notes +- Items 11 and 12 come from the internal assessment: match the closest + peer on part depth, and lead on drawings, which it leaves out. - Until #174 lands, item 1's descriptions say which of two overlapping tools to use ("For ..., use `other_tool`."), so agents can pick correctly before any tool is removed. -- Item 1's family tags are what item 12's toolsets filter on. +- Item 1's family tags are what item 14's toolsets filter on. - Parked: the intermittent SolidWorks error sound during `create_cut_extrude` in the chamfer live tests (#199, #201). Revisit if it causes failures; run `live_demo.ps1 -Trace` and read the "The hole cut" diff --git a/openspec/specs/tools/dimension-listing/spec.md b/openspec/specs/tools/dimension-listing/spec.md new file mode 100644 index 00000000..91d696df --- /dev/null +++ b/openspec/specs/tools/dimension-listing/spec.md @@ -0,0 +1,34 @@ +# tools/dimension-listing Specification + +## Purpose +`list_model_dimensions` lists every dimension in the active part or assembly +once, under the feature that owns it, so an agent can find a dimension by +name before reading or changing it. +## Requirements +### Requirement: Every dimension is listed with no feature name +`list_model_dimensions` with no `feature_name` SHALL return every dimension +of every feature in the active part or assembly: sketch dimensions, feature +dimensions such as an extrude's depth, and reference-plane offsets. It SHALL +return the same dimensions the per-feature calls return, together. + +#### Scenario: The monitor stand +- **WHEN** a part holds an extrude, two cuts, a fillet, `Plane1` and a cut + sketched on `Plane1`, and `list_model_dimensions` is called with no + `feature_name` +- **THEN** the result holds each dimension that a call naming each feature + in turn returns, and no fewer + +### Requirement: Each dimension is listed once, under its own feature +Each dimension SHALL appear once in the result, and its `feature` SHALL be +the feature its `full_name` names after the `@`. + +#### Scenario: A plane's offset seen from the cut on it +- **WHEN** a cut is sketched on `Plane1`, and SolidWorks also reports + `D1@Plane1` among the cut's dimensions +- **THEN** `D1@Plane1` appears once, with `feature` `Plane1` + +#### Scenario: Asking for one feature +- **WHEN** `list_model_dimensions` is called with `feature_name` `Cut-Extrude3` +- **THEN** only dimensions whose `full_name` ends in `@Cut-Extrude3` (or its + sketch's own name, for a sketch) are returned, not `D1@Plane1` + diff --git a/openspec/specs/tools/list-features/spec.md b/openspec/specs/tools/list-features/spec.md index 829034f0..01fe3bdc 100644 --- a/openspec/specs/tools/list-features/spec.md +++ b/openspec/specs/tools/list-features/spec.md @@ -14,7 +14,10 @@ Part documents. The response SHALL NOT be restructured into a nested object (for example, separate `components`/`assembly_features` collections) for any document type, because existing callers (feature-tree diffing, feature-family classification, and the MCP tool's `count` field) -depend on the result being a flat list. +depend on the result being a flat list. Within each document, the +descriptors SHALL be in feature-tree order (oldest first), each feature +SHALL appear once, and its `position` SHALL be its place in that order, +however SolidWorks was walked to find it. #### Scenario: Listing features on a Part - **WHEN** `list_features` is called with the active document being a @@ -22,6 +25,12 @@ depend on the result being a flat list. - **THEN** the result is a flat list of that Part's own feature descriptors, in the same shape as before this change +#### Scenario: The forward walk stops early +- **WHEN** SolidWorks stops the feature walk at the system folders, so the + remaining features are found newest first +- **THEN** the result is still in tree order: the default planes come + before `Plane1`, and `Plane1` before the cut sketched on it + ### Requirement: Feature descriptors identify their originating component Each feature descriptor SHALL carry a `component` field and a `component_path` field. For a feature that belongs to the document's own diff --git a/openspec/specs/tools/model-verification/spec.md b/openspec/specs/tools/model-verification/spec.md index fccb93b0..aed144a9 100644 --- a/openspec/specs/tools/model-verification/spec.md +++ b/openspec/specs/tools/model-verification/spec.md @@ -82,16 +82,24 @@ excludes: - sketches; - the origin; - folder entries; -- the three default reference planes; +- the three default reference planes, which are the first three reference + planes in tree order, whatever their names; - the mate group. -The agent can then predict the number from the features it created. +A reference plane the agent made SHALL be counted. The agent can then +predict the number from the features it created. #### Scenario: Part with two extrudes and a fillet - **WHEN** a part's tree holds the default entries, two sketches, two extrudes and one fillet - **THEN** the measured feature count is 3 +#### Scenario: A part with a plane the agent made +- **WHEN** a part holds an extrude, `Plane1` offset from Top Plane, and a + cut sketched on `Plane1` +- **THEN** the measured feature count is 3, and the counted features are + the extrude, `Plane1` and the cut, never `Front Plane` + ### Requirement: Invalid requests fail clearly The tool SHALL return the standard error payload (`status: "error"`, `error_type`, `hint`): diff --git a/openspec/specs/tools/sketch-on-face/spec.md b/openspec/specs/tools/sketch-on-face/spec.md new file mode 100644 index 00000000..6000716a --- /dev/null +++ b/openspec/specs/tools/sketch-on-face/spec.md @@ -0,0 +1,46 @@ +# tools/sketch-on-face Specification + +## Purpose +`create_sketch` opens a sketch on a flat face of the body, given a point on +that face, so a feature can follow the face when the model's dimensions +change. +## Requirements +### Requirement: A sketch opens on the flat face at a point +`create_sketch` SHALL accept `face_point`, `[x, y, z]` in millimetres in +model coordinates, in place of `plane`. It SHALL open the sketch on the flat +face of the active part at that point, and reply with the sketch's name +as it does for a plane. + +#### Scenario: Sketching on the top face +- **WHEN** a part has a 20 mm tall block whose top face is at y = 20 mm, and + `create_sketch` is called with `face_point` `[0, 20, 0]` +- **THEN** a sketch opens on that face, and a cut drawn there and extruded + 3 mm leaves the block 3 mm lower at the cut + +#### Scenario: The sketch follows the face +- **WHEN** the block's height is changed afterwards and the model rebuilt +- **THEN** the sketch, and the cut made from it, move with the top face + +### Requirement: Exactly one of plane and face_point +`create_sketch` SHALL fail with `invalid_input` when both `plane` and +`face_point` are given, or neither, or `face_point` does not have three +numbers. + +#### Scenario: Both given +- **WHEN** `create_sketch` is called with `plane` `Top` and a `face_point` +- **THEN** the call fails with `invalid_input`, and nothing is opened + +### Requirement: A point that is not on a flat face fails +When `face_point` is not on a face of the active part, or is on a curved +face, `create_sketch` SHALL fail with `invalid_input`, name the point, and +open no sketch. + +#### Scenario: A point in the air +- **WHEN** `face_point` is 50 mm above the part +- **THEN** the call fails with `invalid_input` naming the point, and no + sketch is open afterwards + +#### Scenario: A point on a fillet +- **WHEN** `face_point` lies on a filleted (curved) face +- **THEN** the call fails with `invalid_input` saying the face is not flat + diff --git a/openspec/specs/tools/stl-export/spec.md b/openspec/specs/tools/stl-export/spec.md new file mode 100644 index 00000000..8bca9111 --- /dev/null +++ b/openspec/specs/tools/stl-export/spec.md @@ -0,0 +1,23 @@ +# tools/stl-export Specification + +## Purpose +`export_stl` writes the active part or assembly as an STL file through +SolidWorks' export call with its STL options, so a multibody part or an +assembly comes out as one merged file. +## Requirements +### Requirement: STL export uses its export options without a type mismatch +`export_stl` SHALL write the file with SolidWorks' STL export options (bodies +merged into one file), and SHALL NOT log a type-mismatch warning on the way. +A fallback without the options SHALL be used only when the first call +writes nothing, and the reply SHALL say when it was used. + +#### Scenario: A single-body part +- **WHEN** `export_stl` writes a part with one body +- **THEN** the file exists, is non-empty, and no type-mismatch warning is + logged + +#### Scenario: The export call writes nothing +- **WHEN** the export with options returns without writing the file +- **THEN** the fallback writes it, and the reply's `warning` says the STL + options were not applied + diff --git a/scripts/demo_monitor_stand.py b/scripts/demo_monitor_stand.py index 804d9b3d..54e6dccc 100644 --- a/scripts/demo_monitor_stand.py +++ b/scripts/demo_monitor_stand.py @@ -9,11 +9,9 @@ leaves a 14.54 mm floor under the monitor. The session built it 55 mm tall with a 3 mm pocket (``--height 55 --top 15 --pocket-depth 3``). -The one difference from the hand-finished part: there, the pocket's plane -sits on the top face, so it follows the height if the height is edited in -SolidWorks. The tools can only offset a plane from a named plane, so here -it is Top Plane offset by the height. The solid is the same; to change the -height, rerun the script rather than editing the extrusion by hand. +The pocket is sketched on the top face itself (``create_sketch`` with +``face_point``), as in the hand-finished part, so it follows the height when +the extrusion's depth is edited later in SolidWorks. The stand is a top plate on four square legs. The openings at the front, left and right are arched (large fillets where the legs meet the top); the @@ -31,9 +29,9 @@ underside, picked by each edge's midpoint (metres): two for the front arch, four for the side arches. The back legs' edges facing the back opening are left sharp. -6. The pocket: ``create_reference_plane`` on the top face (Top Plane - offset by the height), a rectangle the base's size plus the clearance - on each side, and a blind cut down into the top. +6. The pocket: ``create_sketch`` on the top face (``face_point`` at its + centre), a rectangle the base's size plus the clearance on each side, + and a blind cut down into the top. 7. ``rebuild_model``, then ``verify_model`` against a hand calculation. 8. ``save_part`` and, with ``--stl``, ``export_stl``. @@ -49,8 +47,10 @@ .\.venv\Scripts\python.exe scripts\demo_monitor_stand.py --out "C:\path\to\MonitorStand.SLDPRT" --height 70 --fillet 30 --pocket-depth 8 --replace --stl ``--replace`` closes the part if it is open in SolidWorks (unsaved changes -to it are lost) and overwrites the file. ``--mock`` runs every call against -the mock adapter instead, without SolidWorks. +to it are lost) and overwrites the file. ``--look`` turns the camera to the +isometric view after the extrusion, each cut and the fillet, for a +recording. ``--mock`` runs every call against the mock adapter instead, +without SolidWorks. """ from __future__ import annotations @@ -60,6 +60,7 @@ import json import math import sys +from collections.abc import Callable from dataclasses import dataclass from pathlib import Path from typing import Any @@ -67,6 +68,9 @@ REPO_ROOT = Path(__file__).resolve().parents[1] sys.path.insert(0, str(REPO_ROOT / "src")) +#: swStandardViews_e (swconst.tlb, SW 2026): the isometric view. +ISO_VIEW = 7 + @dataclass(frozen=True) class Stand: @@ -219,14 +223,31 @@ async def _close_if_open(call: Session, out: Path) -> None: await call("close_model", {"save": False}) +def look_isometric(adapter: Any) -> None: + """Turn the camera to the isometric view, zoomed to fit. + + Staging for a recording, not a tool call: an agent does not need it, so + it reaches the adapter directly. + """ + model = adapter.currentModel + adapter._attempt(lambda: model.ShowNamedView2("", ISO_VIEW), default=None) + adapter._zoom_to_fit(model) + + def _mm(value: float) -> float: """Round a length to 0.0001 mm so the calls read cleanly.""" return round(value, 4) -async def _centred_rectangle(call: Session, plane: str, width: float, length: float) -> None: - """Sketch a rectangle centred on the origin of ``plane`` and exit the sketch.""" - await call("create_sketch", {"plane": plane}) +async def _centred_rectangle( + call: Session, where: dict[str, Any], width: float, length: float +) -> None: + """Sketch a rectangle centred on the origin and exit the sketch. + + ``where`` is ``create_sketch``'s place: ``{"plane": ...}`` or + ``{"face_point": [...]}``. + """ + await call("create_sketch", where) await call( "add_rectangle", {"x1": -_mm(width / 2), "y1": -_mm(length / 2), "x2": _mm(width / 2), "y2": _mm(length / 2)}, @@ -234,8 +255,24 @@ async def _centred_rectangle(call: Session, plane: str, width: float, length: fl await call("exit_sketch") -async def build(stand: Stand, out: Path, replace: bool, stl: bool, call: Session) -> None: - """Run the build's tool calls in order.""" +async def build( + stand: Stand, + out: Path, + replace: bool, + stl: bool, + call: Session, + look: Callable[[], None] | None = None, +) -> None: + """Run the build's tool calls in order. + + ``look``, when given, runs after the extrusion, each cut and the fillet, + so a recording shows each feature as it is made. + """ + + def _show() -> None: + if look is not None: + look() + if replace: await _close_if_open(call, out) @@ -243,8 +280,9 @@ async def build(stand: Stand, out: Path, replace: bool, stl: bool, call: Session await call("set_units", {"unit_system": "mm"}) # Block: the full footprint, extruded to the full height. - await _centred_rectangle(call, "Top", stand.width, stand.depth) + await _centred_rectangle(call, {"plane": "Top"}, stand.width, stand.depth) await call("create_extrusion", {"sketch_name": "Sketch1", "depth": stand.height}) + _show() # Front/back opening, between the legs along X. inner_x = _mm(stand.width / 2 - stand.leg) @@ -259,6 +297,7 @@ async def build(stand: Stand, out: Path, replace: bool, stl: bool, call: Session "create_cut_extrude", {"sketch_name": "Sketch2", "depth": cut_depth, "end_condition": "ThroughAllBoth"}, ) + _show() # Left/right opening, between the legs along Z. inner_z = _mm(stand.depth / 2 - stand.leg) @@ -272,18 +311,25 @@ async def build(stand: Stand, out: Path, replace: bool, stl: bool, call: Session "create_cut_extrude", {"sketch_name": "Sketch3", "depth": cut_depth, "end_condition": "ThroughAllBoth"}, ) + _show() # Arches: front, left and right. The back stays square. await call("add_fillet", {"radius": stand.fillet, "edge_names": stand.arch_edges_m()}) - - # Pocket: a plane on the top face, the base's outline plus clearance, - # cut down into the top. The cut finds the material itself. - plane = await call("create_reference_plane", {"reference": "Top Plane", "offset": stand.height}) - await _centred_rectangle(call, plane["plane"]["name"], stand.pocket_width, stand.pocket_length) + _show() + + # Pocket: sketched on the top face itself, so it follows the height, the + # base's outline plus clearance, cut down into the top. + await _centred_rectangle( + call, + {"face_point": [0, _mm(stand.height), 0]}, + stand.pocket_width, + stand.pocket_length, + ) await call( "create_cut_extrude", {"sketch_name": "Sketch4", "depth": stand.pocket_depth, "end_condition": "Blind"}, ) + _show() await call("rebuild_model") verdict = await call( @@ -292,7 +338,7 @@ async def build(stand: Stand, out: Path, replace: bool, stl: bool, call: Session "bounding_box_mm": [_mm(stand.width), _mm(stand.height), _mm(stand.depth)], "volume_mm3": round(stand.expected_volume_mm3(), 1), "solid_body_count": 1, - "feature_count": 6, # extrude, two cuts, fillet, plane, pocket + "feature_count": 5, # extrude, two cuts, fillet, pocket "relative_tolerance": 0.01, }, ) @@ -327,6 +373,10 @@ def _parse(argv: list[str] | None) -> argparse.Namespace: p.add_argument("--replace", action="store_true", help="close the open part and overwrite the file") p.add_argument("--stl", action="store_true", help="also export an STL beside the part") p.add_argument("--calls-json", type=Path, help="write the tool calls made to this file") + p.add_argument( + "--look", action="store_true", + help="turn the camera to isometric after each feature, for a recording", + ) p.add_argument("--mock", action="store_true", help="use the mock adapter, not SolidWorks") return p.parse_args(argv) @@ -343,7 +393,8 @@ async def _run(args: argparse.Namespace, stand: Stand) -> list[dict[str, Any]]: await adapter.connect() try: call = Session(await _tools(adapter)) - await build(stand, args.out, args.replace, args.stl, call) + look = (lambda: look_isometric(adapter)) if args.look else None + await build(stand, args.out, args.replace, args.stl, call, look) return call.calls finally: await adapter.disconnect() diff --git a/src/solidworks_mcp/adapters/base.py b/src/solidworks_mcp/adapters/base.py index 594d5b1f..b8249c7e 100644 --- a/src/solidworks_mcp/adapters/base.py +++ b/src/solidworks_mcp/adapters/base.py @@ -594,11 +594,17 @@ async def create_loft( # Sketch Operations @abstractmethod - async def create_sketch(self, plane: str) -> AdapterResult[str]: - """Create a new sketch on the specified plane. + async def create_sketch( + self, + plane: str | None, + face_point: tuple[float, float, float] | None = None, + ) -> AdapterResult[str]: + """Create a new sketch on a plane, or on the flat face at a point. Args: - plane (str): The plane value. + plane (str | None): The plane's name; None when ``face_point`` is given. + face_point (tuple[float, float, float] | None): ``(x, y, z)`` in mm on + a flat face of the active part, in place of ``plane``. Returns: AdapterResult[str]: The result produced by the operation. diff --git a/src/solidworks_mcp/adapters/circuit_breaker.py b/src/solidworks_mcp/adapters/circuit_breaker.py index 0a6d3de8..aec2ecf6 100644 --- a/src/solidworks_mcp/adapters/circuit_breaker.py +++ b/src/solidworks_mcp/adapters/circuit_breaker.py @@ -914,19 +914,25 @@ async def create_loft( # Sketch operations - async def create_sketch(self, plane: str) -> AdapterResult[str]: + async def create_sketch( + self, + plane: str | None, + face_point: tuple[float, float, float] | None = None, + ) -> AdapterResult[str]: """Create sketch through circuit breaker. Args: - plane (str): The plane value. + plane (str | None): The plane's name; None with ``face_point``. + face_point (tuple[float, float, float] | None): A point in mm on a + flat face, in place of ``plane``. Returns: AdapterResult[str]: The result produced by the operation. """ return await self._execute_with_circuit_breaker( "create_sketch", - lambda: self.adapter.create_sketch(plane), - input_dict={"plane": plane}, + lambda: self.adapter.create_sketch(plane, face_point), + input_dict={"plane": plane, "face_point": face_point}, ) async def add_line( diff --git a/src/solidworks_mcp/adapters/connection_pool.py b/src/solidworks_mcp/adapters/connection_pool.py index 4d8b9793..db59df61 100644 --- a/src/solidworks_mcp/adapters/connection_pool.py +++ b/src/solidworks_mcp/adapters/connection_pool.py @@ -826,17 +826,23 @@ async def create_loft( # Sketch operations - async def create_sketch(self, plane: str) -> AdapterResult[str]: + async def create_sketch( + self, + plane: str | None, + face_point: tuple[float, float, float] | None = None, + ) -> AdapterResult[str]: """Create sketch using pool. Args: - plane (str): The plane value. + plane (str | None): The plane's name; None with ``face_point``. + face_point (tuple[float, float, float] | None): A point in mm on a + flat face, in place of ``plane``. Returns: AdapterResult[str]: The result produced by the operation. """ return await self._execute_with_pool( - "create_sketch", lambda adapter: adapter.create_sketch(plane) + "create_sketch", lambda adapter: adapter.create_sketch(plane, face_point) ) async def add_line( diff --git a/src/solidworks_mcp/adapters/mock_adapter.py b/src/solidworks_mcp/adapters/mock_adapter.py index bea80829..6867003d 100644 --- a/src/solidworks_mcp/adapters/mock_adapter.py +++ b/src/solidworks_mcp/adapters/mock_adapter.py @@ -551,6 +551,9 @@ async def list_features( "component_parent": None, }, ] + # Every row carries its tree place, as the real adapter's do. + for position, row in enumerate(seeded): + row["position"] = position if is_assembly: components = self._assembly_components or _DEFAULT_ASSEMBLY_COMPONENTS seeded.extend( @@ -1420,11 +1423,21 @@ async def create_loft( execution_time=self._delays["feature_operation"], ) - async def create_sketch(self, plane: str) -> AdapterResult[dict[str, Any]]: # type: ignore[override] - """Mock creating a sketch. + async def create_sketch( # type: ignore[override] + self, + plane: str | None, + face_point: tuple[float, float, float] | None = None, + ) -> AdapterResult[dict[str, Any]]: + """Mock creating a sketch on a plane, or on a face of the canned block. + + With ``face_point``, the point must lie on a face of the 10 mm block + ``select_face_edges`` models (every face of it is flat); any other + point is refused with the real adapter's message. Args: - plane (str): The plane value. + plane (str | None): The plane value; None with ``face_point``. + face_point (tuple[float, float, float] | None): A point in mm on a + face of the block. Returns: AdapterResult[dict[str, Any]]: The result produced by the operation. @@ -1433,11 +1446,23 @@ async def create_sketch(self, plane: str) -> AdapterResult[dict[str, Any]]: # t # Legacy tests start sketching immediately after connect. await self.create_part() + if face_point is not None and self._mock_face_at(list(face_point)) is None: + return AdapterResult( + status=AdapterResultStatus.ERROR, + error=( + f"face_point {[float(c) for c in face_point]} mm is not on a " + "flat face of the active part (No face found at point " + f"{list(face_point)} mm.)" + ), + ) + await asyncio.sleep(self._delays["sketch_operation"]) self._operation_count += 1 sketch_id = f"Sketch{len(self._sketches) + 1}" - self._sketches[sketch_id] = plane + self._sketches[sketch_id] = ( + plane if face_point is None else f"face at {list(face_point)} mm" + ) self._current_sketch = sketch_id return AdapterResult( diff --git a/src/solidworks_mcp/adapters/pywin32_adapter.py b/src/solidworks_mcp/adapters/pywin32_adapter.py index 058efd7d..a2aa0ddd 100644 --- a/src/solidworks_mcp/adapters/pywin32_adapter.py +++ b/src/solidworks_mcp/adapters/pywin32_adapter.py @@ -32,6 +32,7 @@ SolidWorksSketchMixin, bitmap, ) +from .solidworks.feature_walk import walk_feature_tree from .solidworks.features import _null_callout, _select_feature_by_name from .solidworks.io import _byref_int @@ -91,6 +92,12 @@ def _byref_long(initial: int = 0) -> Any: ) +#: The note an STL export carries when SaveAs3 had to write it. +STL_OPTIONS_NOT_APPLIED = ( + "The STL was written by SaveAs3 because SaveAs2 wrote nothing, so its STL " + "options (bodies merged into one file) were not applied." +) + # OLE2 / Compound File Binary Format magic. A real (SW-authored) ``.swp`` is a # compound file; a hand-written text macro is not. _OLE2_MAGIC = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1" @@ -1059,15 +1066,6 @@ def resolve_export_target_doc(self) -> Any: return self._adapter.currentModel -#: Members the ``list_features`` tree walk actually reads on each feature -#: dispatch. Flagging just these instead of the whole ``IFeature`` interface -#: (~100 names, ~27 ms per object) is what keeps the walk cheap: the flag -#: cache in ``sw_type_info`` is keyed by ``id(obj)``, and every feature here -#: is a freshly returned dispatch, so a full-interface flag never hits that -#: cache and pays its full cost on every single feature. -_WALK_MEMBERS = ("GetNextFeature", "GetTypeName2", "IsSuppressed", "IsSuppressed2") - - class _FeatureSelectionService: """Encapsulate feature-selection strategies and name-candidate expansion. @@ -1539,74 +1537,23 @@ def _list_document_features( list[dict[str, Any]]: Ordered feature descriptors. """ features: list[dict[str, Any]] = [] - seen: set[tuple[str, str]] = set() - - feature = self._adapter._attempt(lambda: document.FirstFeature()) - # Flag only the members this walk reads (see ``_WALK_MEMBERS``) so - # methods like GetNextFeature work, without paying the cost of - # flagging the entire IFeature interface on every fresh dispatch. - if feature is not None: - self._adapter._attempt( - lambda f=feature: sw_type_info.flag_members(f, *_WALK_MEMBERS), # type: ignore[misc] - default=0, - ) - pos = 0 - guard = 0 - while feature and guard < 10000: - self._append_feature_to( - features, - seen, - feature, - pos, - include_suppressed, - component=component, - component_path=component_path, - component_parent=component_parent, - ) - pos += 1 - guard += 1 - next_feature = self._adapter._attempt( - lambda current_feature=feature: current_feature.GetNextFeature() # type: ignore[misc] - ) - if next_feature is None: - break - feature = next_feature - # Flag each new feature dispatch - if feature is not None: - self._adapter._attempt( - lambda f=feature: sw_type_info.flag_members(f, *_WALK_MEMBERS), # type: ignore[misc] - default=0, - ) - - # Always augment the forward traversal with FeatureByPositionReverse. - # Some SolidWorks COM/type-library combinations stop GetNextFeature at - # the system folders even though later sketches and body features - # exist. The dedupe set keeps this fallback safe when both traversals - # return the same entries. - feature_manager = getattr(document, "FeatureManager", None) - count = self._adapter._attempt( - lambda: int(feature_manager.GetFeatureCount(True) or 0), # type: ignore[union-attr] - default=0, - ) - # FeatureByPositionReverse is zero-based. Starting at one silently - # skipped the newest feature (typically the just-created extrusion). - for reverse_pos in range(0, count or 0): - feature = self._adapter._attempt( - lambda pos=reverse_pos: document.FeatureByPositionReverse(pos) - ) - if feature is None: + # One walk, shared with list_model_dimensions: both passes, each + # feature once, in tree order (see ``feature_walk``). + for item in walk_feature_tree(self._adapter, document): + suppressed = self._is_feature_suppressed(item.feature) + if suppressed and not include_suppressed: continue - self._append_feature_to( - features, - seen, - feature, - (count or 0) - reverse_pos - 1, - include_suppressed, - component=component, - component_path=component_path, - component_parent=component_parent, + features.append( + { + "name": item.name, + "type": item.type_name, + "suppressed": suppressed, + "position": item.position, + "component": component, + "component_path": component_path, + "component_parent": component_parent, + } ) - return features def _list_assembly_component_features( @@ -1737,61 +1684,6 @@ def _list_assembly_component_features( return results - def _append_feature_to( - self, - features: list[dict[str, Any]], - seen: set[tuple[str, str]], - feature: Any, - position: int, - include_suppressed: bool, - component: str | None = None, - component_path: str | None = None, - component_parent: str | None = None, - ) -> None: - """Append one feature descriptor when dedupe and suppression rules allow. - - Args: - features: Output list being populated. - seen: Dedupe set of ``(name, type)`` keys. - feature: Feature COM object. - position: Display position index. - include_suppressed: Include suppressed entries when ``True``. - component: Owning component name, or ``None`` for a document's - own (non-component) feature. - component_path: Owning component's resolved document path, or - ``None`` to match ``component``. - component_parent: Immediate parent component's name, or - ``None`` for a top-level component or a document's own - feature. - """ - name = str(getattr(feature, "Name", "")) - feature_type = str( - self._adapter._attempt( - lambda: self._adapter._get_attr_or_call(feature, "GetTypeName2"), - default="Unknown", - ) - ) - dedupe_key = (name, feature_type) - if dedupe_key in seen: - return - seen.add(dedupe_key) - - suppressed = self._is_feature_suppressed(feature) - if not include_suppressed and suppressed: - return - - features.append( - { - "name": name, - "type": feature_type, - "suppressed": suppressed, - "position": position, - "component": component, - "component_path": component_path, - "component_parent": component_parent, - } - ) - def _is_feature_suppressed(self, feature: Any) -> bool: """Determine feature suppression state across COM API variants. @@ -2560,37 +2452,37 @@ def _prepare_stl_export_data(self) -> Any | None: def _save_stl_with_extension( self, ext: Any, stl_data: Any | None, resolved_path: str ) -> bool: - """Attempt STL export using Extension.SaveAs2 with optional ISTLExportData. + """Export STL with ``IModelDocExtension.SaveAs2`` and the STL options. - Tries SaveAs2 with stl_data first (enables body merging); falls back to - SaveAs2(None) if type mismatch occurs (late-bound IDispatch can't marshal - ISTLExportData* through IDispatch::Invoke). + ``SaveAs2`` takes eight arguments: ``Name``, ``Version``, ``Options``, + ``ExportData``, ``ReferencePrefixOrSuffixText`` (String), + ``AddTextAsPrefix`` (Boolean), ``Errors`` and ``Warnings`` (both + by-reference Longs). Leaving ``Warnings`` out fails with + "Parameter not optional". + ``ExportData`` is the ``ISTLExportData`` that merges the bodies, or a + ``VT_DISPATCH`` null when SolidWorks gave none (runbook #11: a bare + ``None`` marshals as ``VT_NULL`` and is rejected). Args: - ext: Extension object from target document - stl_data: Optional ISTLExportData configuration - resolved_path: Full path where to save STL file + ext: The document's ``IModelDocExtension``. + stl_data: The ``ISTLExportData``, or None. + resolved_path: Full path of the STL file to write. Returns: - True if file was created, False otherwise. + bool: True when the file exists afterwards. """ + export_data = stl_data if stl_data is not None else _null_callout() + errors = _byref_long(0) + warnings = _byref_long(0) try: - # Try with stl_data first - try: - # swSaveAsVersion_e.swSaveAsCurrentVersion = 0 - # swSaveAsOptions_e.swSaveAsOptions_Silent = 2 - ext.SaveAs2(resolved_path, 0, 2, stl_data, None, "") - except Exception: - # Fallback: try without stl_data (type mismatch on IDispatch) - ext.SaveAs2(resolved_path, 0, 2, None, None, "") - - return os.path.exists(resolved_path) + # swSaveAsCurrentVersion = 0, swSaveAsOptions_Silent = 2 + ext.SaveAs2(resolved_path, 0, 2, export_data, "", False, errors, warnings) except Exception as exc: logger.warning( - "[pywin32.export_file] Extension.SaveAs2 failed: {}", - str(exc), + "[pywin32.export_file] Extension.SaveAs2 failed: {}", str(exc) ) return False + return os.path.exists(resolved_path) def _save_stl_with_fallback(self, target_doc: Any, resolved_path: str) -> None: """Fallback STL export using SaveAs3 if SaveAs2 didn't create file. @@ -2624,9 +2516,7 @@ def _save_stl_with_fallback(self, target_doc: Any, resolved_path: str) -> None: "(tried Extension.SaveAs2 and SaveAs3)" ) - async def export_file( - self, file_path: str, format_type: str - ) -> AdapterResult[None]: + async def export_file(self, file_path: str, format_type: str) -> AdapterResult[Any]: """Export the current model to a file. Args: @@ -2634,7 +2524,8 @@ async def export_file( format_type (str): The format type value. Returns: - AdapterResult[None]: The result produced by the operation. + AdapterResult[Any]: No data, except an STL written by the SaveAs3 + fallback, whose data is ``{"warning": ...}``. Raises: Exception: If the operation cannot be completed. @@ -2645,11 +2536,11 @@ async def export_file( status=AdapterResultStatus.ERROR, error="No active model" ) - def _export_operation() -> None: + def _export_operation() -> dict[str, str] | None: """Build internal export operation. Returns: - None: None. + dict[str, str] | None: The fallback warning for an STL, else None. Raises: Exception: If the operation cannot be completed. @@ -2698,11 +2589,12 @@ def _export_operation() -> None: raise RuntimeError("No Extension object available for STL export") stl_data = self._prepare_stl_export_data() - if not self._save_stl_with_extension(ext, stl_data, resolved_path): - # SaveAs2 didn't produce file — try SaveAs3 fallback - self._save_stl_with_fallback(target_doc, resolved_path) - - return None + if self._save_stl_with_extension(ext, stl_data, resolved_path): + return None + # SaveAs2 wrote nothing: SaveAs3 writes the file without the + # STL options, so the reply says they weren't applied. + self._save_stl_with_fallback(target_doc, resolved_path) + return {"warning": STL_OPTIONS_NOT_APPLIED} # ---------------------------------------------------------------- # All other formats — classic SaveAs3 path. diff --git a/src/solidworks_mcp/adapters/solidworks/com_utils.py b/src/solidworks_mcp/adapters/solidworks/com_utils.py index 319317fc..2f76ef81 100644 --- a/src/solidworks_mcp/adapters/solidworks/com_utils.py +++ b/src/solidworks_mcp/adapters/solidworks/com_utils.py @@ -20,7 +20,7 @@ def flag(adapter: Any, obj: Any, *names: str) -> None: """Flag just ``names`` as methods on ``obj`` (no-op for ``None``/fakes). Flagging a whole interface costs ~27 ms per fresh dispatch (see - ``_WALK_MEMBERS`` in pywin32_adapter); SolidWorks hands back a fresh + ``WALK_MEMBERS`` in feature_walk); SolidWorks hands back a fresh dispatch on most calls, so flag only what is about to be read. """ attempt(adapter, lambda: _sw_type_info.flag_members(obj, *names), 0) diff --git a/src/solidworks_mcp/adapters/solidworks/documentation.py b/src/solidworks_mcp/adapters/solidworks/documentation.py index dbbe42d6..3cb5a08d 100644 --- a/src/solidworks_mcp/adapters/solidworks/documentation.py +++ b/src/solidworks_mcp/adapters/solidworks/documentation.py @@ -19,6 +19,7 @@ from ..base import AdapterResult, AdapterResultStatus from . import dimension_layout as _layout +from .feature_walk import walk_feature_tree from .features import _null_callout, _parse_edge_spec, _select_edge_by_coord from .io import ( _as_com, @@ -311,6 +312,34 @@ def _strip_document_suffix(full_name: Any) -> str | None: return full_name +def _owning_feature(full_name: str | None) -> str | None: + """The feature a dimension's full name says owns it. + + Args: + full_name: A short full name such as ``"D1@Plane1"``. + + Returns: + str | None: The part after the first ``@`` (``"Plane1"``); ``None`` + when there is no name or no ``@``. + """ + if not full_name or "@" not in full_name: + return None + return full_name.split("@", 1)[1] + + +def _is_folder(type_name: str) -> bool: + """Whether a feature-tree row is a folder, which owns no dimensions. + + Args: + type_name: The row's ``GetTypeName2`` type. + + Returns: + bool: True for folder types (``CommentsFolder``, ``MaterialFolder``, + ...) and the annotations folder (``DetailCabinet``). + """ + return type_name.endswith("Folder") or type_name == "DetailCabinet" + + def _sequence(raw: Any) -> list[Any]: """Normalise a COM array return (``None``, scalar or tuple) into a list. @@ -383,20 +412,24 @@ def _require_doc_type( async def list_model_dimensions( self, feature_name: str | None = None ) -> AdapterResult[list[dict[str, Any]]]: - """List every dimension in the active part or assembly. + """List every dimension in the active part or assembly, once each. - Walks ``IModelDoc2::FirstFeature`` / ``IFeature::GetNextFeature`` and - each feature's ``GetFirstDisplayDimension`` chain. ``full_name`` (e.g. - ``"D1@Sketch1"``) is the name ``set_dimension`` accepts, so the pair - gives edit-by-name access to every driving parameter in the model. + Reads the features with the same two-pass walk as ``list_features`` + (:func:`~.feature_walk.walk_feature_tree`), skips folder rows, and + reads each feature's ``GetFirstDisplayDimension`` chain. SolidWorks + can show one dimension under several features (a plane's offset under + the cut sketched on it), so each ``full_name`` (e.g. ``"D1@Sketch1"``, + the name ``set_dimension`` accepts) is kept once, with ``feature`` set + from the part after the ``@``. Args: - feature_name: Only list dimensions of this feature (case-insensitive). + feature_name: Only list dimensions owned by this feature + (case-insensitive), by the ``@`` suffix of their full name. Returns: AdapterResult[list[dict[str, Any]]]: ``full_name``, ``feature``, ``value`` (document units), ``system_value`` (metres / radians) - and ``read_only`` per dimension. + and ``read_only`` per dimension, in tree order. """ guard = self._require_doc_type({1, 2}, "list_model_dimensions") if guard is not None: @@ -404,56 +437,25 @@ async def list_model_dimensions( target = (feature_name or "").strip().lower() def _list() -> list[dict[str, Any]]: - model = self.currentModel dims: list[dict[str, Any]] = [] - feature = self._attempt(lambda: model.FirstFeature(), default=None) - guard_count = 0 - while feature is not None and guard_count < 20000: - guard_count += 1 - feat = _sw_type_info.flagged(feature, "IFeature") - name = str(self._attempt(lambda f=feat: f.Name, default="") or "") - if not target or name.lower() == target: - display = self._attempt( - lambda f=feat: f.GetFirstDisplayDimension(), default=None + seen: set[str] = set() + for item in walk_feature_tree(self, self.currentModel): + if _is_folder(item.type_name): + continue + for row in self._read_display_dimensions(item.feature, item.name): + full_name = row["full_name"] + if full_name is not None: + if full_name in seen: + continue + seen.add(full_name) + dims.append(row) + if target: + dims = [d for d in dims if d["feature"].lower() == target] + if not dims: + raise LookupError( + f"No dimensions found on feature {feature_name!r}; list " + "the feature tree with list_features for exact names" ) - while display is not None: - disp = _sw_type_info.flagged(display, "IDisplayDimension") - dim = self._attempt( - lambda d=disp: d.GetDimension2(0), default=None - ) - if dim is not None: - dim = _sw_type_info.flagged(dim, "IDimension") - dims.append( - { - "full_name": _strip_document_suffix( - self._attempt( - lambda d=dim: d.FullName, default=None - ) - ), - "feature": name, - "value": self._attempt( - lambda d=dim: d.Value, default=None - ), - "system_value": self._attempt( - lambda d=dim: d.SystemValue, default=None - ), - "read_only": bool( - self._attempt( - lambda d=dim: d.ReadOnly, default=False - ) - ), - } - ) - display = self._attempt( - lambda f=feat, d=display: f.GetNextDisplayDimension(d), - default=None, - ) - feature = self._attempt(lambda f=feat: f.GetNextFeature(), default=None) - if target and not dims: - raise LookupError( - f"No dimensions found on feature {feature_name!r}; list " - "the feature tree with list_features for exact names" - ) return dims return cast( @@ -461,6 +463,50 @@ def _list() -> list[dict[str, Any]]: self._handle_com_operation("list_model_dimensions", _list), ) + def _read_display_dimensions( + self, feature: Any, feature_name: str + ) -> list[dict[str, Any]]: + """Read one feature's display dimensions. + + Args: + feature: The ``IFeature`` dispatch. + feature_name: Its name, used as ``feature`` when a dimension's + full name can't be read. + + Returns: + list[dict[str, Any]]: One row per dimension SolidWorks lists under + the feature, with ``feature`` taken from the full name's ``@`` + suffix. + """ + feat = _sw_type_info.flagged(feature, "IFeature") + rows: list[dict[str, Any]] = [] + display = self._attempt(lambda: feat.GetFirstDisplayDimension(), default=None) + while display is not None: + disp = _sw_type_info.flagged(display, "IDisplayDimension") + dim = self._attempt(lambda d=disp: d.GetDimension2(0), default=None) + if dim is not None: + dim = _sw_type_info.flagged(dim, "IDimension") + full_name = _strip_document_suffix( + self._attempt(lambda d=dim: d.FullName, default=None) + ) + rows.append( + { + "full_name": full_name, + "feature": _owning_feature(full_name) or feature_name, + "value": self._attempt(lambda d=dim: d.Value, default=None), + "system_value": self._attempt( + lambda d=dim: d.SystemValue, default=None + ), + "read_only": bool( + self._attempt(lambda d=dim: d.ReadOnly, default=False) + ), + } + ) + display = self._attempt( + lambda d=display: feat.GetNextDisplayDimension(d), default=None + ) + return rows + async def measure_entities( self, entities: list[str] ) -> AdapterResult[dict[str, Any]]: diff --git a/src/solidworks_mcp/adapters/solidworks/face_selection.py b/src/solidworks_mcp/adapters/solidworks/face_selection.py index 3085f31f..138164b8 100644 --- a/src/solidworks_mcp/adapters/solidworks/face_selection.py +++ b/src/solidworks_mcp/adapters/solidworks/face_selection.py @@ -208,7 +208,7 @@ def edge_matches(kind: str, edge_type: str) -> bool: #: Exactly the members read below. Flagging a whole interface costs ~27 ms -#: per fresh dispatch (see ``_WALK_MEMBERS`` in pywin32_adapter); a face can +#: per fresh dispatch (see ``WALK_MEMBERS`` in feature_walk); a face can #: hand back dozens of edges/curves/vertices, so flag just what is used. _EDGE_MEMBERS = ("GetCurve", "GetStartVertex", "GetEndVertex", "Select4") _FACE_MEMBERS = ("GetBox", "GetArea", "GetEdges", "GetClosestPointOn") diff --git a/src/solidworks_mcp/adapters/solidworks/feature_walk.py b/src/solidworks_mcp/adapters/solidworks/feature_walk.py new file mode 100644 index 00000000..2688c0fd --- /dev/null +++ b/src/solidworks_mcp/adapters/solidworks/feature_walk.py @@ -0,0 +1,115 @@ +"""The one walk of a document's top-level feature tree. + +``list_features`` and ``list_model_dimensions`` both read the tree through +:func:`walk_feature_tree`, so they always see the same features in the same +order. + +SolidWorks can stop ``IFeature.GetNextFeature`` at the system folders even +though later sketches and features exist, so the walk always makes a second +pass with ``IModelDoc2.FeatureByPositionReverse``. Both passes number a +feature by its place in the tree (the forward pass counts from 0, the +reverse pass uses ``count - reverse_position - 1``), so a feature found by +both gets one number, and sorting by it gives tree order, oldest first. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + +from .com_utils import attempt, flag + +#: The ``IFeature`` members the walk and its callers read. Flagging only these +#: keeps each fresh dispatch cheap (a whole interface costs ~27 ms). +WALK_MEMBERS = ("GetNextFeature", "GetTypeName2", "IsSuppressed", "IsSuppressed2") + +#: Upper bound on the forward walk, against a feature chain that loops. +_MAX_FORWARD_STEPS = 10000 + + +@dataclass(frozen=True) +class TreeFeature: + """One top-level feature found by the walk. + + Attributes: + position: Its place in the tree, 0 for the first. + name: The feature's name. + type_name: Its ``GetTypeName2`` type, ``"Unknown"`` when unreadable. + feature: The ``IFeature`` dispatch, for reading more from it. + """ + + position: int + name: str + type_name: str + feature: Any + + +def _describe(adapter: Any, feature: Any, position: int) -> TreeFeature: + """Read one feature's name and type into a :class:`TreeFeature`. + + Args: + adapter: The adapter, for ``_attempt`` and ``_get_attr_or_call``. + feature: The ``IFeature`` dispatch. + position: Its place in the tree. + + Returns: + TreeFeature: The feature with its name and type. + """ + type_name = attempt( + adapter, + lambda: adapter._get_attr_or_call(feature, "GetTypeName2"), + "Unknown", + ) + return TreeFeature( + position=position, + name=str(getattr(feature, "Name", "")), + type_name=str(type_name), + feature=feature, + ) + + +def walk_feature_tree(adapter: Any, document: Any) -> list[TreeFeature]: + """Every top-level feature of ``document``, once each, in tree order. + + Args: + adapter: The adapter, for ``_attempt`` and ``_get_attr_or_call``. + document: The ``IModelDoc2`` dispatch to walk. + + Returns: + list[TreeFeature]: The features, sorted by tree position. A feature + found by both passes (same name and type) is kept once. + """ + found: list[TreeFeature] = [] + seen: set[tuple[str, str]] = set() + + def _keep(feature: Any, position: int) -> None: + item = _describe(adapter, feature, position) + key = (item.name, item.type_name) + if key not in seen: + seen.add(key) + found.append(item) + + feature = attempt(adapter, lambda: document.FirstFeature()) + position = 0 + while feature is not None and position < _MAX_FORWARD_STEPS: + flag(adapter, feature, *WALK_MEMBERS) + _keep(feature, position) + position += 1 + feature = attempt(adapter, lambda f=feature: f.GetNextFeature()) + + feature_manager = getattr(document, "FeatureManager", None) + count = attempt( + adapter, + lambda: int(feature_manager.GetFeatureCount(True) or 0), # type: ignore[union-attr] + 0, + ) + # FeatureByPositionReverse is zero-based: 0 is the newest feature. + for reverse_position in range(count): + feature = attempt( + adapter, lambda p=reverse_position: document.FeatureByPositionReverse(p) + ) + if feature is not None: + _keep(feature, count - reverse_position - 1) + + found.sort(key=lambda item: item.position) + return found diff --git a/src/solidworks_mcp/adapters/solidworks/features.py b/src/solidworks_mcp/adapters/solidworks/features.py index 278b43ab..5ff82db0 100644 --- a/src/solidworks_mcp/adapters/solidworks/features.py +++ b/src/solidworks_mcp/adapters/solidworks/features.py @@ -2977,7 +2977,7 @@ def _select_face_at_point(adapter: Any, point_mm: list[float], mark: int) -> boo face = selector.face_at_point(selector.faces(), point_mm) if not face.is_planar: raise LookupError( - f"The face at {list(point_mm)} mm is not flat; a plane needs a flat face." + f"The face at {list(point_mm)} mm is not flat; a plane or a sketch needs a flat face." ) sel_mgr = adapter.currentModel.SelectionManager _flag(adapter, sel_mgr, "CreateSelectData") diff --git a/src/solidworks_mcp/adapters/solidworks/sketch.py b/src/solidworks_mcp/adapters/solidworks/sketch.py index 6b76c9d2..f139ba51 100644 --- a/src/solidworks_mcp/adapters/solidworks/sketch.py +++ b/src/solidworks_mcp/adapters/solidworks/sketch.py @@ -100,8 +100,12 @@ def _angular_dimension_placement( adapter._sketch_geometry.angular_dimension_placement(entity1, entity2), ) - async def create_sketch(self, plane: str) -> AdapterResult[str]: - return _create_sketch_impl(self, plane) + async def create_sketch( + self, + plane: str | None, + face_point: tuple[float, float, float] | None = None, + ) -> AdapterResult[str]: + return _create_sketch_impl(self, plane, face_point) async def add_line( self, x1: float, y1: float, x2: float, y2: float @@ -202,8 +206,146 @@ async def check_sketch_fully_defined( return _check_sketch_fully_defined_impl(self, sketch_name) -def _create_sketch_impl(adapter: Any, plane: str) -> AdapterResult[str]: - """Open a new sketch on a named reference plane. +def _select_sketch_plane(adapter: Any, plane: str) -> None: + """Select the reference plane a new sketch opens on. + + Tries the plane's locale aliases by name (``FeatureByName`` then + ``Select2``), then ``Extension.SelectByID2`` with type ``"PLANE"``. + + Args: + adapter: A connected adapter with a part open. + plane: The plane's short or full name. + + Raises: + Exception: If no plane candidate could be selected. + """ + plane_name_map = { + "Top": "Top Plane", + "Front": "Front Plane", + "Right": "Right Plane", + "XY": "Top Plane", + "XZ": "Front Plane", + "YZ": "Right Plane", + } + + semantic_plane_aliases = { + "Top": ["Top Plane", "Planta", "上视基准面", "上視基準面"], + "Front": ["Front Plane", "Alzado", "前视基准面", "前視基準面"], + "Right": ["Right Plane", "Vista lateral", "右视基准面", "右視基準面"], + "XY": ["Top Plane", "Planta", "上视基准面"], + "XZ": ["Front Plane", "Alzado", "前视基准面"], + "YZ": ["Right Plane", "Vista lateral", "右视基准面"], + } + + actual_plane = plane_name_map.get(plane, plane) + selected = False + selection_error = None + + plane_candidates = [ + *semantic_plane_aliases.get(plane, []), + actual_plane, + plane, + "Top Plane", + "Front Plane", + "Right Plane", + "Planta", + "Alzado", + "Vista lateral", + "上视基准面", + "前视基准面", + "右视基准面", + "上視基準面", + "前視基準面", + "右視基準面", + ] + for candidate in plane_candidates: + if not candidate: + continue + plane_feature, selection_error_candidate = adapter._attempt_with_error( + lambda c=candidate: adapter.currentModel.FeatureByName(c) + ) + if selection_error_candidate: + selection_error = selection_error_candidate + continue + selected = bool( + plane_feature + and adapter._attempt( + lambda pf=plane_feature: pf.Select2(False, 0), default=False + ) + ) + if selected: + break + + if not selected: + # SW 2022: callout must be None (empty string causes type mismatch) + selected, selection_error_candidate = adapter._attempt_with_error( + lambda: adapter.currentModel.Extension.SelectByID2( + actual_plane, + "PLANE", + 0, + 0, + 0, + False, + 0, + None, + 0, + ) + ) + if selection_error_candidate: + selection_error = selection_error_candidate + elif selected: + pass + + if not selected: + if selection_error: + raise Exception( + f"Failed to select plane: {actual_plane} ({selection_error})" + ) + raise Exception(f"Failed to select plane: {actual_plane}") + + +def _select_sketch_face(adapter: Any, face_point: tuple[float, float, float]) -> None: + """Select the flat face of the active part at ``face_point`` for a sketch. + + Uses the same face lookup as ``create_reference_plane``'s ``face_point`` + (the body face whose closest point is within 0.01 mm, which must be + flat). On any failure the selection is cleared, so no sketch opens on a + stale selection. + + Args: + adapter: A connected adapter with a part open. + face_point: ``(x, y, z)`` in mm on the face. + + Raises: + LookupError: When no flat face lies at the point. + """ + from .features import _select_face_at_point + + point = [float(c) for c in face_point] + adapter._attempt(lambda: adapter.currentModel.ClearSelection2(True), default=None) + try: + selected = _select_face_at_point(adapter, point, 0) + reason = "SolidWorks would not select it" + except LookupError as exc: + selected, reason = False, str(exc) + if not selected: + adapter._attempt( + lambda: adapter.currentModel.ClearSelection2(True), default=None + ) + raise LookupError( + f"face_point {point} mm is not on a flat face of the active part ({reason})" + ) + + +def _create_sketch_impl( + adapter: Any, + plane: str | None, + face_point: tuple[float, float, float] | None = None, +) -> AdapterResult[str]: + """Open a new sketch on a named reference plane, or on a flat face. + + With ``face_point``, the flat face of the active part at that point is + selected (see :func:`_select_sketch_face`) in place of a plane. The function resolves English short-hand names (``"Top"``, ``"Front"``, ``"Right"``, ``"XY"``, ``"XZ"``, ``"YZ"``) to their full SolidWorks plane @@ -224,7 +366,8 @@ def _create_sketch_impl(adapter: Any, plane: str) -> AdapterResult[str]: plane: Reference-plane identifier. Accepts short English names (``"Top"``, ``"Front"``, ``"Right"``, ``"XY"``, ``"XZ"``, ``"YZ"``) or the exact SolidWorks plane name as it appears in - the FeatureManager tree. + the FeatureManager tree. Ignored when ``face_point`` is given. + face_point: ``(x, y, z)`` in mm on a flat face of the active part. Returns: AdapterResult[str]: On success, ``data`` is the sketch name string @@ -232,7 +375,8 @@ def _create_sketch_impl(adapter: Any, plane: str) -> AdapterResult[str]: Raises: Exception: Propagated through ``_handle_com_operation`` when no plane - candidate can be selected. + candidate can be selected, or (as ``LookupError``) when + ``face_point`` is not on a flat face. Example:: @@ -245,100 +389,19 @@ def _create_sketch_impl(adapter: Any, plane: str) -> AdapterResult[str]: return AdapterResult(status=AdapterResultStatus.ERROR, error="No active model") def _sketch_operation() -> str: - """Inner COM closure that selects the plane and opens the sketch. - - Iterates through all locale aliases and ``SelectByID2`` fallbacks. - Updates adapter sketch state on success. + """Inner COM closure that selects the plane or face and opens the sketch. Returns: str: The resolved SolidWorks sketch name. Raises: Exception: If no plane candidate could be selected. + LookupError: If ``face_point`` is not on a flat face. """ - plane_name_map = { - "Top": "Top Plane", - "Front": "Front Plane", - "Right": "Right Plane", - "XY": "Top Plane", - "XZ": "Front Plane", - "YZ": "Right Plane", - } - - semantic_plane_aliases = { - "Top": ["Top Plane", "Planta", "上视基准面", "上視基準面"], - "Front": ["Front Plane", "Alzado", "前视基准面", "前視基準面"], - "Right": ["Right Plane", "Vista lateral", "右视基准面", "右視基準面"], - "XY": ["Top Plane", "Planta", "上视基准面"], - "XZ": ["Front Plane", "Alzado", "前视基准面"], - "YZ": ["Right Plane", "Vista lateral", "右视基准面"], - } - - actual_plane = plane_name_map.get(plane, plane) - selected = False - selection_error = None - - plane_candidates = [ - *semantic_plane_aliases.get(plane, []), - actual_plane, - plane, - "Top Plane", - "Front Plane", - "Right Plane", - "Planta", - "Alzado", - "Vista lateral", - "上视基准面", - "前视基准面", - "右视基准面", - "上視基準面", - "前視基準面", - "右視基準面", - ] - for candidate in plane_candidates: - if not candidate: - continue - plane_feature, selection_error_candidate = adapter._attempt_with_error( - lambda c=candidate: adapter.currentModel.FeatureByName(c) - ) - if selection_error_candidate: - selection_error = selection_error_candidate - continue - selected = bool( - plane_feature - and adapter._attempt( - lambda pf=plane_feature: pf.Select2(False, 0), default=False - ) - ) - if selected: - break - - if not selected: - # SW 2022: callout must be None (empty string causes type mismatch) - selected, selection_error_candidate = adapter._attempt_with_error( - lambda: adapter.currentModel.Extension.SelectByID2( - actual_plane, - "PLANE", - 0, - 0, - 0, - False, - 0, - None, - 0, - ) - ) - if selection_error_candidate: - selection_error = selection_error_candidate - elif selected: - pass - - if not selected: - if selection_error: - raise Exception( - f"Failed to select plane: {actual_plane} ({selection_error})" - ) - raise Exception(f"Failed to select plane: {actual_plane}") + if face_point is not None: + _select_sketch_face(adapter, face_point) + else: + _select_sketch_plane(adapter, str(plane or "")) adapter.currentSketchManager = adapter.currentModel.SketchManager adapter._attempt( diff --git a/src/solidworks_mcp/skills/solidworks-mcp/references/workflows.md b/src/solidworks_mcp/skills/solidworks-mcp/references/workflows.md index 85e9e069..b40385f8 100644 --- a/src/solidworks_mcp/skills/solidworks-mcp/references/workflows.md +++ b/src/solidworks_mcp/skills/solidworks-mcp/references/workflows.md @@ -28,8 +28,14 @@ step. Values are examples; sizes are millimetres. ## Sketching somewhere other than the three planes -`create_reference_plane` with `reference: "Top Plane"` and `offset: 10` makes -a plane 10 mm up; its name (e.g. "Plane1") goes into `create_sketch`. +On a flat face of the body: `create_sketch` with `face_point`, a point on the +face in mm (e.g. `[0, 20, 0]` on the top of a 20 mm tall block). The sketch +sits on the face, so a cut made from it follows the face when a dimension +changes later. Prefer this to a plane at the same height. + +Away from the body: `create_reference_plane` with `reference: "Top Plane"` +and `offset: 10` makes a plane 10 mm up; its name (e.g. "Plane1") goes into +`create_sketch`. - At an angle: `create_axis` first (its reply names the axis, e.g. "Axis1"), then `reference`, `angle` (degrees) and `axis`. diff --git a/src/solidworks_mcp/tools/analysis.py b/src/solidworks_mcp/tools/analysis.py index 8fa739a0..f91db70c 100644 --- a/src/solidworks_mcp/tools/analysis.py +++ b/src/solidworks_mcp/tools/analysis.py @@ -155,7 +155,10 @@ def _count_modelling_features(descriptors: list[dict[str, Any]]) -> list[str]: Skips component features, sketches, the origin, folders, the mate group and the first three reference planes (the default ones, matched by - position so it works in any SolidWorks language). + position so it works in any SolidWorks language). The rows are put in + tree order by their ``position`` first, so the default planes are found + whatever order an adapter returned them in; a row without a position + keeps its place. Args: descriptors: ``list_features`` rows. @@ -163,9 +166,13 @@ def _count_modelling_features(descriptors: list[dict[str, Any]]) -> list[str]: Returns: list[str]: Counted feature names, in tree order. """ + ordered = sorted( + enumerate(descriptors), + key=lambda item: (item[1].get("position", item[0]), item[0]), + ) names: list[str] = [] planes_seen = 0 - for row in descriptors: + for _, row in ordered: if row.get("component") is not None: continue kind = str(row.get("type") or "") diff --git a/src/solidworks_mcp/tools/engineering_data.py b/src/solidworks_mcp/tools/engineering_data.py index 0e1819fd..7cd1e1e0 100644 --- a/src/solidworks_mcp/tools/engineering_data.py +++ b/src/solidworks_mcp/tools/engineering_data.py @@ -216,13 +216,15 @@ async def list_model_dimensions( Use it to find a dimension in an existing model before changing it: each `full_name` (e.g. "D1@Sketch1") is the name `get_dimension` and `set_dimension` - take. Needs: an open part or assembly. Read-only. Returns: `data`, one entry per - dimension with `full_name`, `feature`, `value` (document units), `system_value` - (metres or radians) and `read_only`. + take. Each dimension is listed once, under the feature its full name names + after the `@` (`D1@Plane1` under `Plane1`, never also under a cut sketched on + that plane). Needs: an open part or assembly. Read-only. Returns: `data`, one + entry per dimension with `full_name`, `feature`, `value` (document units), + `system_value` (metres or radians) and `read_only`. Args: - input_data: Nothing is required: give `feature_name` to list one - feature's dimensions, or omit it for every dimension. + input_data: Nothing is required: give `feature_name` to list the + dimensions that feature owns, or omit it for every dimension. Returns: dict[str, Any]: The dimensions. diff --git a/src/solidworks_mcp/tools/error_classifier.py b/src/solidworks_mcp/tools/error_classifier.py index bf2ce1ad..d18457bd 100644 --- a/src/solidworks_mcp/tools/error_classifier.py +++ b/src/solidworks_mcp/tools/error_classifier.py @@ -163,6 +163,15 @@ def matches(self, message: str, hresult: int | None) -> bool: ), patterns=(r"built no feature",), ), + ErrorRule( + error_type=INVALID_INPUT, + hint=( + "face_point must lie on a flat face of the active part's body, in " + "mm. Read the faces' centres with select_face_edges, or sketch on " + "a plane instead." + ), + patterns=(r"face_point \[[^\]]*\] mm is not on a flat face",), + ), ErrorRule( error_type="not_found", hint=( diff --git a/src/solidworks_mcp/tools/export.py b/src/solidworks_mcp/tools/export.py index 9da6a74b..40e1cd6f 100644 --- a/src/solidworks_mcp/tools/export.py +++ b/src/solidworks_mcp/tools/export.py @@ -285,7 +285,8 @@ async def export_stl(input_data: ExportFileInput) -> dict[str, Any]: extension, so end `file_path` in .stl. Needs: an open, active part or assembly. Changes: writes the file, creating its folder and replacing a file already there; the open document is unchanged. Returns: `export` with `file_path` and - `format`. + `format`, plus `warning` when SolidWorks wrote the file without its STL options + (bodies not merged into one file). Args: input_data: The export. `file_path` (ending in .stl) is required; @@ -309,7 +310,7 @@ async def export_stl(input_data: ExportFileInput) -> dict[str, Any]: "data": result.data, "execution_time": result.execution_time, } - return { + reply: dict[str, Any] = { "status": "success", "message": f"Exported to STL format: {input_data.file_path}", "export": { @@ -320,6 +321,11 @@ async def export_stl(input_data: ExportFileInput) -> dict[str, Any]: }, "execution_time": result.execution_time, } + # The adapter's data is a dict only when its fallback wrote the file + # without the STL options. + if isinstance(result.data, dict) and result.data.get("warning"): + reply["warning"] = result.data["warning"] + return reply @mcp.tool() async def export_pdf(input_data: ExportFileInput) -> dict[str, Any]: diff --git a/src/solidworks_mcp/tools/sketching.py b/src/solidworks_mcp/tools/sketching.py index 7b8a8e0e..2d2f3b6b 100644 --- a/src/solidworks_mcp/tools/sketching.py +++ b/src/solidworks_mcp/tools/sketching.py @@ -27,12 +27,25 @@ class CreateSketchInput(CompatInput): """Input schema for creating a sketch. Attributes: - plane (str): The plane value. + plane (str | None): The plane to sketch on. + face_point (list[float] | None): A point on a flat face to sketch on + instead. sketch_name (str | None): The sketch name value. """ - plane: str = Field( - description="Sketch plane name (e.g., 'Top', 'Front', 'Right', 'XY', 'XZ', 'YZ')" + plane: str | None = Field( + default=None, + description=( + "Sketch plane name (e.g., 'Top', 'Front', 'Right', 'XY', 'XZ', 'YZ', " + "or a plane made by create_reference_plane). Give this or face_point" + ), + ) + face_point: list[float] | None = Field( + default=None, + description=( + "[x, y, z] in mm on a flat face of the part's body; the sketch opens " + "on that face and follows it when the model changes. Give this or plane" + ), ) sketch_name: str | None = Field( default=None, @@ -44,19 +57,20 @@ class CreateSketchInput(CompatInput): ) def model_post_init(self, __context: Any) -> None: - """Provide model post init support for the create sketch input. + """Require exactly one of ``plane`` and ``face_point``. Args: __context (Any): The context value. - Returns: - None: None. - Raises: - ValueError: Plane is required. + ValueError: When both or neither are given, or ``face_point`` is not + three numbers. """ - if not self.plane.strip(): - raise ValueError("plane is required") + has_plane = bool((self.plane or "").strip()) + if has_plane == (self.face_point is not None): + raise ValueError("give exactly one of plane and face_point") + if self.face_point is not None and len(self.face_point) != 3: + raise ValueError("face_point must be [x, y, z] in millimetres") class AddLineInput(CompatInput): @@ -351,25 +365,43 @@ async def register_sketching_tools( @mcp.tool() async def create_sketch(input_data: CreateSketchInput) -> dict[str, Any]: - """Open a new sketch on a plane of the active part, ready for lines, circles and other sketch entities. + """Open a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities. Use it first in every feature: sketch, draw, `exit_sketch`, then `create_extrusion` or `create_cut_extrude`. Planes: Front, Top, Right (or XY, - XZ, YZ), or a plane made by `create_reference_plane`. Coordinates in the sketch - are mm from the origin. Needs: an open part. Changes: adds a sketch and opens it - for editing; give `sketch_name` and `exit_sketch` names it that when it closes - it (SolidWorks won't rename an open sketch). Returns: `sketch` with `name` (the - name in the feature tree now) and `plane`, plus `name_on_exit` when you gave - `sketch_name`. + XZ, YZ), or a plane made by `create_reference_plane`. Or give `face_point`, a + point in mm on a flat face of the body: the sketch opens on that face and moves + with it when the model changes. Coordinates in the sketch are mm from the + origin. Needs: an open part. Changes: adds a sketch and opens it for editing; + give `sketch_name` and `exit_sketch` names it that when it closes it (SolidWorks + won't rename an open sketch). Returns: `sketch` with `name` (the name in the + feature tree now) and `plane` (or `face_point`), plus `name_on_exit` when you + gave `sketch_name`. A `face_point` not on a flat face fails with + `invalid_input`. Args: - input_data: The sketch. `plane` is required; `sketch_name` names it. + input_data: The sketch. Exactly one of `plane` and `face_point`; + `sketch_name` names it. Returns: dict[str, Any]: The new sketch. """ input_data = normalize_input(input_data, CreateSketchInput) - result = await adapter.create_sketch(input_data.plane) + face_point = ( + ( + float(input_data.face_point[0]), + float(input_data.face_point[1]), + float(input_data.face_point[2]), + ) + if input_data.face_point is not None + else None + ) + if face_point is None: + result = await adapter.create_sketch(input_data.plane) + where = f"{input_data.plane} plane" + else: + result = await adapter.create_sketch(None, face_point) + where = f"the face at {list(face_point)} mm" require_success(result, context="Failed to create sketch") sketch_name = ( @@ -377,13 +409,13 @@ async def create_sketch(input_data: CreateSketchInput) -> dict[str, Any]: if isinstance(result.data, dict) else result.data ) + sketch: dict[str, Any] = {"name": sketch_name, "plane": input_data.plane} + if face_point is not None: + sketch["face_point"] = list(face_point) reply: dict[str, Any] = { "status": "success", - "message": f"Created sketch '{sketch_name}' on {input_data.plane} plane", - "sketch": { - "name": sketch_name, - "plane": input_data.plane, - }, + "message": f"Created sketch '{sketch_name}' on {where}", + "sketch": sketch, "execution_time": result.execution_time, } names_on_exit.clear() # a sketch left open is abandoned with its name diff --git a/tests/live/test_live_sw_monitor_stand_demo.py b/tests/live/test_live_sw_monitor_stand_demo.py index 1cc0763f..a587b0a6 100644 --- a/tests/live/test_live_sw_monitor_stand_demo.py +++ b/tests/live/test_live_sw_monitor_stand_demo.py @@ -7,13 +7,17 @@ each call a captioned frame. The stand is built at the script's defaults, the part as the user finished it: 66 mm tall, a 26 mm top, R25 arches and an 11.46 mm pocket. ``build()`` checks it with ``verify_model`` against a hand -calculation before saving and exporting an STL. The last frame is the part -in an isometric view. +calculation before saving and exporting an STL. The camera turns to the +isometric view after the extrusion, each cut and the fillet, and the last +frame is the finished part. + +A second test (not recorded) builds the stand again, raises its height in +the extrusion's dimension, and checks the pocket followed the top face. Record it with:: powershell -ExecutionPolicy Bypass -File tests\\scripts\\live_demo.ps1 ` - -Test tests/live/test_live_sw_monitor_stand_demo.py ` + -Test tests/live/test_live_sw_monitor_stand_demo.py::test_monitor_stand_from_prompt_to_part ` -CaptureDir docs/assets/demos/monitor-stand -Record -PromptSeconds 12 Collected only with ``SOLIDWORKS_MCP_RUN_REAL_INTEGRATION=1`` on Windows (see @@ -65,11 +69,12 @@ _PROMPT_MAX_LINES = 26 _PROMPT_WRAP_CHARS = 70 -#: swStandardViews_e (swconst.tlb, SW 2026): the isometric view. -_ISO_VIEW = 7 -#: Calls after which the camera turns to the isometric view: from the first -#: solid on, the cuts, arches and pocket are seen in 3D. -_LOOK_AFTER = {"create_extrusion"} +#: The stand's volume at the script's defaults, measured on SolidWorks 2026 +#: in the session that built it (issue #206). The script's hand calculation +#: leaves out a small blend and reads about 0.3 % low. +_MEASURED_VOLUME_MM3 = 901_769.0 +#: How much the height is raised in the follow-the-height test, in mm. +_RAISE_MM = 4.0 def _load_script() -> Any: @@ -90,16 +95,6 @@ def _prompt_lines() -> list[str]: return lines -def _look(adapter: Any, view: int) -> None: - """Point the camera for the demo: a standard view, zoomed to fit. - - Staging for the recording, not a tool call: an agent does not need it. - """ - model = adapter.currentModel - adapter._attempt(lambda: model.ShowNamedView2("", view), default=None) - adapter._zoom_to_fit(model) - - def _brief(result: dict[str, Any]) -> dict[str, Any]: """The part of a reply worth a caption: its message and what it measured.""" shown: dict[str, Any] = {"message": result.get("message")} @@ -145,8 +140,6 @@ async def __call__( self.calls.append({"tool": name, "args": args or {}}) self.results[name] = result assert result.get("status") == "success", f"{name}: {result.get('message')}" - if name in _LOOK_AFTER: - _look(self.adapter, _ISO_VIEW) brief = _brief(result) brief["message"] = str(brief["message"]).replace(self.prefix, "") evidence(label, brief, call=shown) @@ -166,14 +159,25 @@ async def test_monitor_stand_from_prompt_to_part(scratch: Any, tmp_path: Path) - evidence("the prompt", _prompt_lines(), max_lines=_PROMPT_MAX_LINES) - await script.build(stand, out, replace=False, stl=True, call=call) + await script.build( + stand, + out, + replace=False, + stl=True, + call=call, + look=lambda: script.look_isometric(adapter), + ) assert out.is_file(), out assert out.with_suffix(".stl").is_file() check = call.results["verify_model"] assert check["verdict"] == "pass", check + assert check["measured"]["volume_mm3"] == pytest.approx( + _MEASURED_VOLUME_MM3, rel=1e-3 + ) + assert "create_reference_plane" not in [c["tool"] for c in call.calls] - _look(adapter, _ISO_VIEW) + script.look_isometric(adapter) evidence( f"the finished stand, isometric: {len(call.calls)} tool calls, all successful", { @@ -182,3 +186,54 @@ async def test_monitor_stand_from_prompt_to_part(scratch: Any, tmp_path: Path) - "saved": [out.name, out.with_suffix(".stl").name], }, ) + + +@pytest.mark.asyncio +@pytest.mark.timeout(900) +async def test_the_pocket_follows_a_raised_height(scratch: Any, tmp_path: Path) -> None: + """Raise the stand by editing its extrusion; the pocket moves with the top. + + The pocket is sketched on the top face, so after the block's depth goes + from 66 to 70 mm the part grows by exactly the plate's footprint times + 4 mm, and the pocket is still 11.46 mm deep from the new top. A pocket on + a plane fixed at 66 mm would leave the volume short by the pocket's + footprint times 4 mm. + """ + script = _load_script() + stand = script.Stand() + adapter = scratch.adapter + call = script.Session(await script._tools(adapter)) + out = tmp_path / "MonitorStandRaised.SLDPRT" + scratch.written_files.append(str(out)) + + # build() ends with verify_model, so the stand is right before the edit. + await script.build(stand, out, replace=False, stl=False, call=call) + + raised = stand.height + _RAISE_MM + await call("set_dimension", {"name": "D1@Boss-Extrude1", "value": raised}) + await call("rebuild_model") + check = await call( + "verify_model", + { + "bounding_box_mm": [ + round(stand.width, 4), + round(raised, 4), + round(stand.depth, 4), + ], + "volume_mm3": round( + _MEASURED_VOLUME_MM3 + stand.width * stand.depth * _RAISE_MM, 1 + ), + "solid_body_count": 1, + "relative_tolerance": 0.002, + }, + ) + + evidence( + "the pocket followed the top face", + { + "height_mm": raised, + "volume_after_mm3": round(check["measured"]["volume_mm3"], 1), + "verdict": check["verdict"], + }, + ) + assert check["verdict"] == "pass", check diff --git a/tests/live/test_live_sw_monitor_stand_follow_ups.py b/tests/live/test_live_sw_monitor_stand_follow_ups.py new file mode 100644 index 00000000..31f55c91 --- /dev/null +++ b/tests/live/test_live_sw_monitor_stand_follow_ups.py @@ -0,0 +1,251 @@ +"""The monitor-stand follow-ups (issue #206), checked on real SolidWorks. + +One bundle, run together after the work is done, then failures are fixed one +at a time: + +1. ``list_features`` comes back in tree order, and ``verify_model`` counts + ``Plane1`` and not ``Front Plane``; +2. a diagnostic of the dimension listing on the monitor stand: how many + features the old forward-only walk and the shared walk find, and whether + the full listing holds every dimension the per-feature calls find; +3. ``export_stl`` writes through ``SaveAs2`` with its options (no warning); +4. ``create_sketch`` on a face: the top face works, a point in the air and + a point on a fillet are refused with ``invalid_input``. + +The follow-the-height rebuild is in ``test_live_sw_monitor_stand_demo.py`` +(``test_the_pocket_follows_a_raised_height``). + +Run one with:: + + powershell -ExecutionPolicy Bypass -File tests\\scripts\\live_demo.ps1 ` + -Test tests/live/test_live_sw_monitor_stand_follow_ups.py::test_feature_order_and_verify_model_with_a_plane + +Collected only with ``SOLIDWORKS_MCP_RUN_REAL_INTEGRATION=1`` on Windows (see +``tests/live/conftest.py``). +""" + +from __future__ import annotations + +from pathlib import Path +from typing import Any + +import pytest + +from tests.live.evidence import evidence +from tests.live.test_live_sw_beta_tools import _sketch +from tests.live.test_live_sw_monitor_stand_demo import _load_script + +pytestmark = pytest.mark.asyncio + +#: The test block: 40 x 40 mm on the Top Plane, 20 mm tall (top face at y = 20). +_HALF = 20.0 +_HEIGHT = 20.0 + + +async def _tools(adapter: Any) -> dict[str, Any]: + """The tool families these tests use, registered on ``adapter``; name -> fn.""" + from fastmcp import FastMCP + + from solidworks_mcp.tools.analysis import register_analysis_tools + from solidworks_mcp.tools.engineering_data import register_engineering_data_tools + from solidworks_mcp.tools.export import register_export_tools + from solidworks_mcp.tools.file_management import register_file_management_tools + from solidworks_mcp.tools.modeling import register_modeling_tools + from solidworks_mcp.tools.sketching import register_sketching_tools + + mcp = FastMCP("monitor-stand-follow-ups-live") + for register in ( + register_modeling_tools, + register_sketching_tools, + register_analysis_tools, + register_engineering_data_tools, + register_file_management_tools, + register_export_tools, + ): + await register(mcp, adapter, {}) + return {t.name: t.fn for t in await mcp.list_tools()} + + +async def _block(tools: dict[str, Any]) -> None: + """A new part holding the 40 x 40 x 20 mm test block.""" + assert (await tools["create_part"]({"name": "follow_ups"}))["status"] == "success" + await _sketch(tools, "Top", {"x1": -_HALF, "y1": -_HALF, "x2": _HALF, "y2": _HALF}) + made = await tools["create_extrusion"]({"depth": _HEIGHT}) + assert made["status"] == "success", made + + +async def _block_with_a_plane_and_a_cut(tools: dict[str, Any]) -> str: + """The block, ``Plane1`` on its top, and a 10 x 10 x 3 mm cut on Plane1.""" + await _block(tools) + plane = await tools["create_reference_plane"]( + {"reference": "Top Plane", "offset": _HEIGHT} + ) + assert plane["status"] == "success", plane + plane_name = str(plane["plane"]["name"]) + sketch = await _sketch(tools, plane_name, {"x1": -5, "y1": -5, "x2": 5, "y2": 5}) + cut = await tools["create_cut_extrude"]( + {"sketch_name": sketch, "depth": 3, "end_condition": "Blind"} + ) + assert cut["status"] == "success", cut + return plane_name + + +async def test_feature_order_and_verify_model_with_a_plane(scratch: Any) -> None: + """Rows in tree order; the agent's plane is counted, Front Plane is not.""" + tools = await _tools(scratch.adapter) + plane_name = await _block_with_a_plane_and_a_cut(tools) + + listed = await tools["list_features"]({}) + rows = [r for r in listed["features"] if r.get("component") is None] + names = [r["name"] for r in rows] + positions = [r["position"] for r in rows] + verified = await tools["verify_model"]({"feature_count": 3}) + + evidence( + "list_features order, and verify_model's counted features", + { + "names": names, + "positions": positions, + "counted": verified["measured"].get("features"), + "verdict": verified["verdict"], + }, + ) + assert positions == sorted(positions) + assert names.index("Front Plane") < names.index(plane_name) + assert names.index(plane_name) < names.index("Cut-Extrude1") + assert verified["verdict"] == "pass", verified + assert plane_name in verified["measured"]["features"] + assert "Front Plane" not in verified["measured"]["features"] + + +def _forward_walk_count(adapter: Any) -> int: + """How many features the old forward-only walk reaches (test-side COM).""" + from solidworks_mcp.adapters import sw_type_info + + count = 0 + feature = adapter._attempt(lambda: adapter.currentModel.FirstFeature()) + while feature is not None and count < 10000: + count += 1 + flagged = sw_type_info.flagged(feature, "IFeature") + feature = adapter._attempt(lambda f=flagged: f.GetNextFeature()) + return count + + +async def test_dimension_listing_on_the_monitor_stand( + scratch: Any, tmp_path: Path +) -> None: + """The full listing holds every dimension the per-feature calls find.""" + from solidworks_mcp.adapters.solidworks.feature_walk import walk_feature_tree + + script = _load_script() + adapter = scratch.adapter + out = tmp_path / "StandDims.SLDPRT" + scratch.written_files.append(str(out)) + await script.build( + script.Stand(), + out, + replace=False, + stl=False, + call=script.Session(await script._tools(adapter)), + ) + tools = await _tools(adapter) + + walked = walk_feature_tree(adapter, adapter.currentModel) + full = await tools["list_model_dimensions"]({}) + per_feature: dict[str, list[str]] = {} + for item in walked: + one = await tools["list_model_dimensions"]({"feature_name": item.name}) + if one["status"] == "success": + per_feature[item.name] = [d["full_name"] for d in one["data"]] + + full_names = [d["full_name"] for d in full["data"]] + found_by_features = {n for names in per_feature.values() for n in names} + evidence( + "dimension listing: old walk vs shared walk, full vs per feature", + { + "old_forward_walk_features": _forward_walk_count(adapter), + "shared_walk_features": len(walked), + "full_listing": full_names, + "per_feature": per_feature, + }, + ) + assert full["status"] == "success", full + assert len(full_names) == len(set(full_names)), "a dimension is listed twice" + assert found_by_features <= set(full_names) + for row in full["data"]: + if row["full_name"] and "@" in row["full_name"]: + assert row["feature"] == row["full_name"].split("@", 1)[1], row + + +async def test_export_stl_uses_its_options(scratch: Any, tmp_path: Path) -> None: + """The STL is written by SaveAs2 with its options: no fallback warning.""" + tools = await _tools(scratch.adapter) + await _block(tools) + out = tmp_path / "block.stl" + scratch.written_files.append(str(out)) + + exported = await tools["export_stl"]({"file_path": str(out)}) + + evidence( + "export_stl", + { + "status": exported["status"], + "size_bytes": out.stat().st_size if out.exists() else None, + "warning": exported.get("warning"), + }, + call=f'export_stl({{"file_path": "{out.name}"}})', + ) + assert exported["status"] == "success", exported + assert out.stat().st_size > 0 + assert "warning" not in exported, exported["warning"] + + +async def test_create_sketch_on_a_face(scratch: Any) -> None: + """The top face takes a sketch; the air and a fillet are refused.""" + tools = await _tools(scratch.adapter) + await _block(tools) + + on_top = await tools["create_sketch"]({"face_point": [0, _HEIGHT, 0]}) + assert on_top["status"] == "success", on_top + assert (await tools["add_rectangle"]({"x1": -5, "y1": -5, "x2": 5, "y2": 5}))[ + "status" + ] == "success" + closed = await tools["exit_sketch"]() + assert closed["status"] == "success", closed + cut = await tools["create_cut_extrude"]( + {"sketch_name": on_top["sketch"]["name"], "depth": 3, "end_condition": "Blind"} + ) + in_air = await tools["create_sketch"]({"face_point": [0, _HEIGHT + 50, 0]}) + + # Round one vertical corner (x = z = 20), then point at the fillet's middle. + fillet = await tools["add_fillet"]( + {"radius": 5, "edge_names": [f"{_HALF / 1000},{_HEIGHT / 2000},{_HALF / 1000}"]} + ) + assert fillet["status"] == "success", fillet + on_fillet_mm = _HALF - 5 + 5 * 0.7071068 + on_fillet = await tools["create_sketch"]( + {"face_point": [on_fillet_mm, _HEIGHT / 2, on_fillet_mm]} + ) + + evidence( + "create_sketch on a face: the top, the air, a fillet", + { + "top": on_top["message"], + "cut_volume_delta_mm3": (cut.get("measured_change") or {}).get( + "volume_delta_mm3" + ), + "air": [in_air["status"], in_air.get("error_type"), in_air["message"]], + "fillet": [ + on_fillet["status"], + on_fillet.get("error_type"), + on_fillet["message"], + ], + }, + ) + assert cut["status"] == "success", cut + assert cut["measured_change"]["volume_delta_mm3"] == pytest.approx(-300, rel=1e-3) + assert in_air["status"] == "error" + assert in_air["error_type"] == "invalid_input" + assert on_fillet["status"] == "error" + assert on_fillet["error_type"] == "invalid_input" + assert "not flat" in on_fillet["message"] diff --git a/tests/solidworks_mcp/adapters/solidworks/test_documentation.py b/tests/solidworks_mcp/adapters/solidworks/test_documentation.py index 6d81c684..99d513a1 100644 --- a/tests/solidworks_mcp/adapters/solidworks/test_documentation.py +++ b/tests/solidworks_mcp/adapters/solidworks/test_documentation.py @@ -283,6 +283,99 @@ async def test_list_model_dimensions_unknown_feature_is_not_found() -> None: assert "No dimensions found on feature 'Fillet9'" in result.error +class _TreeFeature(_Feature): + """A feature with a type, for walks that skip folders.""" + + def __init__(self, name: str, kind: str, dims: list[Any]) -> None: + super().__init__(name, dims) + self._kind = kind + + def GetTypeName2(self): # noqa: N802 - COM name + return self._kind + + +def _monitor_stand() -> SimpleNamespace: + """A part whose forward walk stops at the folders, as on the monitor stand. + + The cut sketched on ``Plane1`` also reports the plane's offset. + """ + tree = [ + _TreeFeature("Comments", "CommentsFolder", [_dim("D9@Bogus@P.Part", 1.0)]), + _TreeFeature("Front Plane", "RefPlane", []), + _TreeFeature("Boss-Extrude1", "Extrusion", [_dim("D1@Boss-Extrude1", 20.0)]), + _TreeFeature("Plane1", "RefPlane", [_dim("D1@Plane1@Stand.Part", 20.0)]), + _TreeFeature( + "Cut-Extrude3", + "Cut", + [_dim("D1@Cut-Extrude3", 3.0), _dim("D1@Plane1@Stand.Part", 20.0)], + ), + ] + count = len(tree) + return SimpleNamespace( + GetType=lambda: 1, + FirstFeature=lambda: tree[0], # its GetNextFeature is None: the walk stops + FeatureByPositionReverse=lambda pos: tree[count - pos - 1], + FeatureManager=SimpleNamespace(GetFeatureCount=lambda _all: count), + ) + + +@pytest.mark.asyncio +async def test_list_model_dimensions_finds_what_the_reverse_pass_finds() -> None: + result = await _Harness(_monitor_stand()).list_model_dimensions() + + assert result.is_success + assert [(d["full_name"], d["feature"]) for d in result.data] == [ + ("D1@Boss-Extrude1", "Boss-Extrude1"), + ("D1@Plane1", "Plane1"), + ("D1@Cut-Extrude3", "Cut-Extrude3"), + ] + + +@pytest.mark.asyncio +async def test_list_model_dimensions_for_a_cut_leaves_out_its_plane() -> None: + result = await _Harness(_monitor_stand()).list_model_dimensions("Cut-Extrude3") + + assert [d["full_name"] for d in result.data] == ["D1@Cut-Extrude3"] + + +@pytest.mark.asyncio +async def test_list_model_dimensions_keeps_a_dimension_with_no_full_name() -> None: + nameless = SimpleNamespace( + FullName=None, Value=5.0, SystemValue=0.005, ReadOnly=True + ) + feature = _Feature("Fillet1", [nameless, nameless]) + model = SimpleNamespace(GetType=lambda: 1, FirstFeature=lambda: feature) + + result = await _Harness(model).list_model_dimensions() + + assert [(d["full_name"], d["feature"]) for d in result.data] == [ + (None, "Fillet1"), + (None, "Fillet1"), + ] + assert result.data[0]["read_only"] is True + + +@pytest.mark.parametrize( + ("full_name", "owner"), + [("D1@Plane1", "Plane1"), ("D1@Sketch@2", "Sketch@2"), ("D1", None), (None, None)], +) +def test_owning_feature(full_name, owner) -> None: + assert doc._owning_feature(full_name) == owner + + +@pytest.mark.parametrize( + ("type_name", "folder"), + [ + ("MaterialFolder", True), + ("DetailCabinet", True), + ("RefPlane", False), + ("Unknown", False), + ], +) +def test_is_folder(type_name, folder) -> None: + assert doc._is_folder(type_name) is folder + + # ---- measure_entities --------------------------------------------------------- diff --git a/tests/solidworks_mcp/adapters/solidworks/test_feature_walk.py b/tests/solidworks_mcp/adapters/solidworks/test_feature_walk.py new file mode 100644 index 00000000..7cf11875 --- /dev/null +++ b/tests/solidworks_mcp/adapters/solidworks/test_feature_walk.py @@ -0,0 +1,116 @@ +"""Tests for the shared feature-tree walk.""" + +from __future__ import annotations + +from types import SimpleNamespace +from typing import Any + +from solidworks_mcp.adapters.solidworks.feature_walk import ( + WALK_MEMBERS, + TreeFeature, + walk_feature_tree, +) + + +class _Adapter: + """The two adapter members the walk uses.""" + + def _attempt(self, operation, default=None): + try: + return operation() + except Exception: + return default + + def _get_attr_or_call(self, obj, name): + value = getattr(obj, name) + return value() if callable(value) else value + + +class _Feature: + """A fake ``IFeature`` with a forward link.""" + + def __init__(self, name: str, kind: str = "Extrusion") -> None: + self.Name = name + self._kind = kind + self.next: Any = None + + def GetTypeName2(self): # noqa: N802 - COM name + return self._kind + + def GetNextFeature(self): # noqa: N802 - COM name + return self.next + + +def _chain(*features: _Feature) -> None: + for current, following in zip(features, features[1:], strict=False): + current.next = following + + +def _document(features: list[_Feature], first: Any) -> Any: + total = len(features) + return SimpleNamespace( + FirstFeature=lambda: first, + FeatureByPositionReverse=lambda pos: features[total - pos - 1], + FeatureManager=SimpleNamespace(GetFeatureCount=lambda _all: total), + ) + + +def test_a_full_forward_walk_gives_each_feature_once_in_order() -> None: + features = [ + _Feature("Front Plane", "RefPlane"), + _Feature("Sketch1"), + _Feature("Boss"), + ] + _chain(*features) + + walked = walk_feature_tree(_Adapter(), _document(features, features[0])) + + assert [(f.position, f.name) for f in walked] == [ + (0, "Front Plane"), + (1, "Sketch1"), + (2, "Boss"), + ] + assert walked[0].type_name == "RefPlane" + assert walked[2].feature is features[2] + + +def test_a_walk_that_stops_early_is_completed_and_sorted() -> None: + features = [_Feature(name) for name in ("A", "B", "C", "D")] + _chain(features[0], features[1]) # the forward walk stops after B + + walked = walk_feature_tree(_Adapter(), _document(features, features[0])) + + assert [f.name for f in walked] == ["A", "B", "C", "D"] + assert [f.position for f in walked] == [0, 1, 2, 3] + + +def test_no_forward_walk_and_gaps_in_the_reverse_pass() -> None: + # The count says three; the newest (reverse position 0) can't be read. + by_reverse = {1: _Feature("B"), 2: _Feature("A")} + document = SimpleNamespace( + FirstFeature=lambda: None, + FeatureByPositionReverse=lambda pos: by_reverse.get(pos), + FeatureManager=SimpleNamespace(GetFeatureCount=lambda _all: 3), + ) + + walked = walk_feature_tree(_Adapter(), document) + + assert [(f.position, f.name) for f in walked] == [(0, "A"), (1, "B")] + + +def test_an_unreadable_type_and_a_missing_feature_manager() -> None: + class _Bare: + Name = "Odd" + + def GetNextFeature(self): # noqa: N802 - COM name + return None + + document = SimpleNamespace(FirstFeature=lambda: _Bare()) + + walked = walk_feature_tree(_Adapter(), document) + + assert walked == [TreeFeature(0, "Odd", "Unknown", walked[0].feature)] + + +def test_walk_members_cover_what_callers_read() -> None: + assert {"GetNextFeature", "GetTypeName2", "IsSuppressed"} <= set(WALK_MEMBERS) diff --git a/tests/solidworks_mcp/adapters/solidworks/test_io.py b/tests/solidworks_mcp/adapters/solidworks/test_io.py index db9a04a7..57e0e585 100644 --- a/tests/solidworks_mcp/adapters/solidworks/test_io.py +++ b/tests/solidworks_mcp/adapters/solidworks/test_io.py @@ -39,7 +39,10 @@ def _handle_com_operation(self, _name, callback, *args): import solidworks_mcp.adapters.pywin32_adapter as pywin32_mod from solidworks_mcp.adapters.mock_adapter import MockSolidWorksAdapter -from solidworks_mcp.adapters.pywin32_adapter import PyWin32Adapter +from solidworks_mcp.adapters.pywin32_adapter import ( + STL_OPTIONS_NOT_APPLIED, + PyWin32Adapter, +) from solidworks_mcp.adapters.solidworks import bitmap as _io_bitmap from solidworks_mcp.adapters.solidworks.io import ( SolidWorksIOMixin, @@ -2642,26 +2645,44 @@ def test_prepare_stl_export_data_paths(self, monkeypatch) -> None: assert stl_data.Merge is True assert stl_data.ExportBodiesAs == 0 - def test_save_stl_with_extension_fallback_to_no_export_data( + def test_save_stl_with_extension_passes_eight_arguments( self, monkeypatch, tmp_path ) -> None: - """_save_stl_with_extension should retry SaveAs2 with None export data.""" + """SaveAs2 gets its eight arguments, the export data included, once. + + The last two are the by-reference ``Errors`` and ``Warnings``; leaving + ``Warnings`` out failed live with "Parameter not optional". + """ adapter = self._build_adapter(monkeypatch) out_file = tmp_path / "out.stl" - - call_counter = {"count": 0} + stl_data = object() def _saveas2(path, *_args): - call_counter["count"] += 1 - if call_counter["count"] == 1: - raise RuntimeError("type mismatch") out_file.write_text("solid", encoding="utf-8") + return True extension = SimpleNamespace(SaveAs2=Mock(side_effect=_saveas2)) - saved = adapter._save_stl_with_extension(extension, object(), str(out_file)) + saved = adapter._save_stl_with_extension(extension, stl_data, str(out_file)) assert saved is True - assert extension.SaveAs2.call_count == 2 + extension.SaveAs2.assert_called_once() + args = extension.SaveAs2.call_args.args + assert len(args) == 8 + assert args[:6] == (str(out_file), 0, 2, stl_data, "", False) + + def test_save_stl_with_extension_without_export_data_passes_a_null( + self, monkeypatch, tmp_path + ) -> None: + """No ISTLExportData: ExportData is the VT_DISPATCH null, never None.""" + adapter = self._build_adapter(monkeypatch) + extension = SimpleNamespace(SaveAs2=Mock(return_value=True)) + + saved = adapter._save_stl_with_extension( + extension, None, str(tmp_path / "never.stl") + ) + + assert saved is False # SaveAs2 said True but wrote nothing + assert extension.SaveAs2.call_args.args[3] is not None def test_save_stl_with_extension_returns_false_on_failure( self, monkeypatch @@ -2783,6 +2804,7 @@ async def test_export_file_stl_success_via_extension_path( result = await adapter.export_file(str(out_file), "stl") assert result.is_success + assert result.data is None target_doc.ResolveAllLightweightComponents.assert_called_once_with(True) adapter._save_stl_with_extension.assert_called_once() adapter._save_stl_with_fallback.assert_not_called() @@ -2817,6 +2839,7 @@ async def test_export_file_stl_falls_back_to_saveas3( result = await adapter.export_file(str(out_file), "stl") assert result.is_success + assert result.data == {"warning": STL_OPTIONS_NOT_APPLIED} adapter._save_stl_with_extension.assert_called_once() adapter._save_stl_with_fallback.assert_called_once_with( target_doc, str(out_file) diff --git a/tests/solidworks_mcp/adapters/solidworks/test_selection.py b/tests/solidworks_mcp/adapters/solidworks/test_selection.py index 2eeba192..1d3e8ab9 100644 --- a/tests/solidworks_mcp/adapters/solidworks/test_selection.py +++ b/tests/solidworks_mcp/adapters/solidworks/test_selection.py @@ -407,7 +407,65 @@ def IsSuppressed(self): result = await adapter.list_features(include_suppressed=False) assert result.is_success - assert [row["name"] for row in result.data] == ["Boss-Extrude1", "Sketch1"] + # The reverse pass finds them newest first; the rows come in tree order. + assert [row["name"] for row in result.data] == ["Sketch1", "Boss-Extrude1"] + assert [row["position"] for row in result.data] == [0, 1] + + @pytest.mark.asyncio + async def test_list_features_sorts_when_the_forward_walk_stops_early( + self, monkeypatch + ): + """A forward walk that stops at the folders still yields tree order.""" + adapter = self._build_adapter(monkeypatch) + + class _Feature: + """A feature whose forward link can be cut short.""" + + def __init__(self, name, feature_type, next_feature=None): + """Store the name, type and next feature.""" + self.Name = name + self._feature_type = feature_type + self._next = next_feature + + def GetTypeName2(self): + """Return the feature's type.""" + return self._feature_type + + def IsSuppressed(self): + """Never suppressed.""" + return False + + def GetNextFeature(self): + """Return the next feature, or None where the walk stops.""" + return self._next + + tree = [ + ("Front Plane", "RefPlane"), + ("Top Plane", "RefPlane"), + ("Right Plane", "RefPlane"), + ("Sketch1", "ProfileFeature"), + ("Boss-Extrude1", "Extrusion"), + ("Plane1", "RefPlane"), + ("Sketch2", "ProfileFeature"), + ("Cut-Extrude1", "Cut"), + ] + objects = [_Feature(name, kind) for name, kind in tree] + # The forward walk reaches the default planes, then stops. + objects[0]._next = objects[1] + objects[1]._next = objects[2] + count = len(objects) + + adapter.currentModel = SimpleNamespace( + FirstFeature=lambda: objects[0], + FeatureByPositionReverse=lambda pos: objects[count - pos - 1], + FeatureManager=SimpleNamespace(GetFeatureCount=lambda _all: count), + ) + + result = await adapter.list_features(include_suppressed=False) + + assert result.is_success + assert [row["name"] for row in result.data] == [name for name, _ in tree] + assert [row["position"] for row in result.data] == list(range(count)) @pytest.mark.asyncio async def test_list_features_suppressed_fallback_uses_is_suppressed2( diff --git a/tests/solidworks_mcp/adapters/solidworks/test_sketch.py b/tests/solidworks_mcp/adapters/solidworks/test_sketch.py index 034237b4..91d186d1 100644 --- a/tests/solidworks_mcp/adapters/solidworks/test_sketch.py +++ b/tests/solidworks_mcp/adapters/solidworks/test_sketch.py @@ -2433,3 +2433,83 @@ def test_text_beside_line(ends, point, expected) -> None: text = sketch._text_beside_line(adapter, object(), point) assert text == (None if expected is None else pytest.approx(expected)) + + +# ---- create_sketch on a face (face_point) -------------------------------------- + + +def _face_model(cleared: list[bool]) -> SimpleNamespace: + """A model whose sketch manager opens ``FaceSketch``; records clears.""" + return SimpleNamespace( + ClearSelection2=lambda _all: cleared.append(True), + SketchManager=SimpleNamespace( + InsertSketch=lambda *args: SimpleNamespace(Name="FaceSketch") + ), + ) + + +def test_create_sketch_on_a_flat_face(monkeypatch) -> None: + from solidworks_mcp.adapters.solidworks import features + + picked: list[list[float]] = [] + monkeypatch.setattr( + features, + "_select_face_at_point", + lambda _adapter, point, mark: picked.append(point) or True, + ) + adapter = _FakeSketchAdapter() + adapter.currentModel = _face_model([]) + + result = sketch._create_sketch_impl(adapter, None, (5.0, 20.0, 5.0)) + + assert result.is_success + assert result.data == "FaceSketch" + assert picked == [[5.0, 20.0, 5.0]] + + +def test_create_sketch_point_off_the_body_names_the_point(monkeypatch) -> None: + from solidworks_mcp.adapters.solidworks import features + + def _no_face(_adapter, point, _mark): + raise LookupError(f"No face found at point {point} mm.") + + monkeypatch.setattr(features, "_select_face_at_point", _no_face) + cleared: list[bool] = [] + adapter = _FakeSketchAdapter() + adapter.currentModel = _face_model(cleared) + + result = sketch._create_sketch_impl(adapter, None, (0.0, 70.0, 0.0)) + + assert not result.is_success + assert "face_point [0.0, 70.0, 0.0] mm is not on a flat face" in result.error + assert "No face found" in result.error + assert len(cleared) == 2 # before the pick, and again after the failure + assert adapter.currentSketch is None + + +def test_create_sketch_face_that_will_not_select(monkeypatch) -> None: + from solidworks_mcp.adapters.solidworks import features + + monkeypatch.setattr(features, "_select_face_at_point", lambda *_: False) + adapter = _FakeSketchAdapter() + adapter.currentModel = _face_model([]) + + result = sketch._create_sketch_impl(adapter, None, (1.0, 2.0, 3.0)) + + assert "SolidWorks would not select it" in result.error + + +@pytest.mark.asyncio +async def test_mixin_create_sketch_forwards_face_point(monkeypatch) -> None: + calls: list[tuple] = [] + monkeypatch.setattr( + sketch, + "_create_sketch_impl", + lambda adapter, plane, face_point: calls.append((plane, face_point)) or "ok", + ) + + class _Mixin(SolidWorksSketchMixin): + pass + + assert await _Mixin().create_sketch(None, (1.0, 2.0, 3.0)) == "ok" + assert calls == [(None, (1.0, 2.0, 3.0))] diff --git a/tests/solidworks_mcp/adapters/test_circuit_breaker.py b/tests/solidworks_mcp/adapters/test_circuit_breaker.py index c01fcce9..c9cc0de4 100644 --- a/tests/solidworks_mcp/adapters/test_circuit_breaker.py +++ b/tests/solidworks_mcp/adapters/test_circuit_breaker.py @@ -600,8 +600,9 @@ async def create_loft(self, params): """Test helper for create loft.""" return AdapterResult(status=AdapterResultStatus.SUCCESS, data=None) - async def create_sketch(self, plane: str): - """Test helper for create sketch.""" + async def create_sketch(self, plane: str | None, face_point=None): + """Test helper for create sketch; echoes where it was asked to sketch.""" + self.last_sketch_args = (plane, face_point) return AdapterResult(status=AdapterResultStatus.SUCCESS, data="Sketch1") async def add_line(self, x1: float, y1: float, x2: float, y2: float): @@ -1116,3 +1117,23 @@ async def test_reset_circuit_breakers_reports_through_a_result(self) -> None: result = await breaker.reset_circuit_breakers() assert result.is_success and result.data == {"reset": ["a"]} + + +@pytest.mark.asyncio +async def test_circuit_breaker_create_sketch_forwards_face_point(monkeypatch): + """face_point reaches the wrapped adapter and the breaker's input record.""" + inner = _DummyAdapter({}) + cb = CircuitBreakerAdapter(adapter=inner, config={}) + recorded: dict = {} + + async def _run(name, operation, **kwargs): + recorded.update(kwargs.get("input_dict") or {}) + return await operation() + + monkeypatch.setattr(cb, "_execute_with_circuit_breaker", _run) + + result = await cb.create_sketch(None, (1.0, 2.0, 3.0)) + + assert result.is_success + assert inner.last_sketch_args == (None, (1.0, 2.0, 3.0)) + assert recorded == {"plane": None, "face_point": (1.0, 2.0, 3.0)} diff --git a/tests/solidworks_mcp/adapters/test_connection_pool.py b/tests/solidworks_mcp/adapters/test_connection_pool.py index 396b0103..490fe07b 100644 --- a/tests/solidworks_mcp/adapters/test_connection_pool.py +++ b/tests/solidworks_mcp/adapters/test_connection_pool.py @@ -1830,3 +1830,27 @@ async def test_reset_circuit_breakers_resets_a_shared_breaker_once() -> None: assert result.data == {"reset": ["create_extrusion"]} assert breaker._get_bucket("create_extrusion").state == CircuitState.CLOSED + + +@pytest.mark.asyncio +async def test_connection_pool_create_sketch_forwards_face_point(monkeypatch): + """The pool passes face_point through to the adapter it borrows.""" + pool = ConnectionPoolAdapter( + adapter_factory=lambda: _PoolAdapterStub(), pool_size=1 + ) + seen: list[tuple] = [] + + class _Borrowed: + async def create_sketch(self, plane, face_point=None): + seen.append((plane, face_point)) + return AdapterResult(status=AdapterResultStatus.SUCCESS, data="Sketch1") + + async def _fake_execute(name, operation): + return await operation(_Borrowed()) + + monkeypatch.setattr(pool, "_execute_with_pool", _fake_execute) + + result = await pool.create_sketch(None, (1.0, 2.0, 3.0)) + + assert result.is_success + assert seen == [(None, (1.0, 2.0, 3.0))] diff --git a/tests/solidworks_mcp/adapters/test_mock_adapter.py b/tests/solidworks_mcp/adapters/test_mock_adapter.py index 4717ad59..46d301a9 100644 --- a/tests/solidworks_mcp/adapters/test_mock_adapter.py +++ b/tests/solidworks_mcp/adapters/test_mock_adapter.py @@ -423,6 +423,9 @@ async def test_list_features_with_actual_features(self): result = await adapter.list_features(include_suppressed=False) assert result.status == AdapterResultStatus.SUCCESS assert isinstance(result.data, list) + positions = [row["position"] for row in result.data] + assert positions == sorted(positions) + assert result.data[-1]["name"].startswith("Boss-Extrude") @pytest.mark.asyncio async def test_list_features_seeded_when_empty(self): @@ -435,6 +438,7 @@ async def test_list_features_seeded_when_empty(self): assert result.status == AdapterResultStatus.SUCCESS assert len(result.data) > 0 assert any(f["name"] == "Origin" for f in result.data) + assert [f["position"] for f in result.data] == list(range(len(result.data))) @pytest.mark.asyncio async def test_list_configurations_non_default_config(self): diff --git a/tests/solidworks_mcp/adapters/test_mock_adapter_engineering_data.py b/tests/solidworks_mcp/adapters/test_mock_adapter_engineering_data.py index 196af870..ea8bbbcc 100644 --- a/tests/solidworks_mcp/adapters/test_mock_adapter_engineering_data.py +++ b/tests/solidworks_mcp/adapters/test_mock_adapter_engineering_data.py @@ -24,6 +24,20 @@ async def test_list_model_dimensions_filters_by_feature(part) -> None: assert [d["full_name"] for d in result.data] == ["D1@Boss-Extrude1"] +@pytest.mark.asyncio +async def test_list_model_dimensions_lists_each_once_under_its_owner(part) -> None: + part._dimensions = {"D1@Plane1": 20.0, "D1@Cut-Extrude3": 3.0} + + everything = await part.list_model_dimensions() + cut = await part.list_model_dimensions("Cut-Extrude3") + + assert [(d["full_name"], d["feature"]) for d in everything.data] == [ + ("D1@Plane1", "Plane1"), + ("D1@Cut-Extrude3", "Cut-Extrude3"), + ] + assert [d["full_name"] for d in cut.data] == ["D1@Cut-Extrude3"] + + @pytest.mark.asyncio async def test_list_model_dimensions_unknown_feature(part) -> None: result = await part.list_model_dimensions("Fillet9") diff --git a/tests/solidworks_mcp/tools/test_analysis_verify_model.py b/tests/solidworks_mcp/tools/test_analysis_verify_model.py index c253ba37..eed79dea 100644 --- a/tests/solidworks_mcp/tools/test_analysis_verify_model.py +++ b/tests/solidworks_mcp/tools/test_analysis_verify_model.py @@ -405,6 +405,30 @@ def test_feature_filter_skips_furniture_and_default_planes() -> None: ] +def test_feature_filter_uses_tree_order_when_rows_arrive_newest_first() -> None: + # The monitor stand: rows found newest first by the reverse pass. + in_tree_order = [ + ("Front Plane", "RefPlane"), + ("Top Plane", "RefPlane"), + ("Right Plane", "RefPlane"), + ("Origin", "OriginProfileFeature"), + ("Sketch1", "ProfileFeature"), + ("Boss-Extrude1", "Extrusion"), + ("Plane1", "RefPlane"), + ("Sketch2", "ProfileFeature"), + ("Cut-Extrude1", "Cut"), + ] + rows = [ + {**_feature(name, kind), "position": position} + for position, (name, kind) in enumerate(in_tree_order) + ] + + counted = _count_modelling_features(list(reversed(rows))) + + assert counted == ["Boss-Extrude1", "Plane1", "Cut-Extrude1"] + assert "Front Plane" not in counted + + def test_verdict_order() -> None: assert _verdict([]) == "report_only" assert _verdict([{"passed": True}, {"passed": None}]) == "inconclusive" diff --git a/tests/solidworks_mcp/tools/test_error_classifier.py b/tests/solidworks_mcp/tools/test_error_classifier.py index 6d4b3f99..1fbdeb2b 100644 --- a/tests/solidworks_mcp/tools/test_error_classifier.py +++ b/tests/solidworks_mcp/tools/test_error_classifier.py @@ -74,6 +74,11 @@ def classifier() -> ErrorClassifier: ), ("The selected face has no edges", "not_found"), ("No face found at point [1000, 1000, 1000] mm.", "not_found"), + ( + "Error in create_sketch: face_point [5.0, 60.0, 5.0] mm is not on a " + "flat face of the active part (No face found at point [5, 60, 5] mm.)", + "invalid_input", + ), ("The active part has no solid body faces.", "not_found"), ("No view named 'Side'. Views: Front, Top", "not_found"), ("No drawing views found to dimension (pictorial ...)", "not_found"), diff --git a/tests/solidworks_mcp/tools/test_export.py b/tests/solidworks_mcp/tools/test_export.py index 055469a2..68e0d1ca 100644 --- a/tests/solidworks_mcp/tools/test_export.py +++ b/tests/solidworks_mcp/tools/test_export.py @@ -750,3 +750,41 @@ async def test_a_file_export_without_format_type_uses_the_tools_own( assert result["status"] == "success" assert mock_adapter.export_step.call_args.args[0]["format_type"] == "step" assert ExportFileInput(file_path="C:/out/part.step").format_type is None + + +class _StlFallbackAdapter: + """An adapter whose STL export went through the SaveAs3 fallback.""" + + async def export_file(self, file_path: str, format_type: str): + """Report the fallback's note, as the real adapter does.""" + return SimpleNamespace( + is_success=True, + error=None, + data={"warning": "the STL options were not applied"}, + execution_time=0.01, + ) + + +@pytest.mark.asyncio +async def test_export_stl_passes_the_fallback_warning_on(mcp_server, mock_config): + """A file written without the STL options says so in the reply.""" + await register_export_tools(mcp_server, _StlFallbackAdapter(), mock_config) + + reply = await (await _tool(mcp_server, "export_stl"))( + input_data=ExportFileInput(file_path="a.stl") + ) + + assert reply["status"] == "success" + assert reply["warning"] == "the STL options were not applied" + + +@pytest.mark.asyncio +async def test_export_stl_without_a_fallback_has_no_warning(mcp_server, mock_config): + """The usual export carries no warning.""" + await register_export_tools(mcp_server, _ExportFallbackAdapter(), mock_config) + + reply = await (await _tool(mcp_server, "export_stl"))( + input_data=ExportFileInput(file_path="a.stl") + ) + + assert "warning" not in reply diff --git a/tests/solidworks_mcp/tools/test_sketching.py b/tests/solidworks_mcp/tools/test_sketching.py index e707cd17..8c3ff16a 100644 --- a/tests/solidworks_mcp/tools/test_sketching.py +++ b/tests/solidworks_mcp/tools/test_sketching.py @@ -1429,3 +1429,71 @@ async def test_the_hole_tutorial_points_at_the_cut_tool( assert cut["sketch_name"] == "Sketch1" assert cut["end_condition"] == "ThroughAll" assert cut["depth"] > 0 + + +# ---- create_sketch on a face --------------------------------------------------- + + +@pytest.mark.parametrize( + "kwargs", + [ + {"plane": "Top", "face_point": [0, 0, 0]}, + {}, + {"plane": " "}, + {"face_point": [1, 2]}, + ], +) +def test_create_sketch_input_needs_exactly_one_place(kwargs) -> None: + """Both, neither, a blank plane or a short point are refused.""" + with pytest.raises(ValueError): + CreateSketchInput(**kwargs) + + +def test_create_sketch_input_takes_a_face_point() -> None: + data = CreateSketchInput(face_point=[5, 10, 5]) + assert data.plane is None + assert data.face_point == [5, 10, 5] + + +async def _create_sketch_tool(mcp_server, adapter, config): + await register_sketching_tools(mcp_server, adapter, config) + for tool in await mcp_server.list_tools(): + if tool.name == "create_sketch": + return tool.fn + raise AssertionError("create_sketch is not registered") + + +@pytest.mark.asyncio +async def test_create_sketch_on_a_face_of_the_mock_block(mcp_server, mock_config): + """A point on the block's top face opens a sketch there.""" + from solidworks_mcp.adapters.mock_adapter import MockSolidWorksAdapter + + adapter = MockSolidWorksAdapter({}) + await adapter.connect() + await adapter.create_part() + tool = await _create_sketch_tool(mcp_server, adapter, mock_config) + + reply = await tool({"face_point": [5, 5, 10]}) + + assert reply["status"] == "success" + assert reply["sketch"]["face_point"] == [5.0, 5.0, 10.0] + assert reply["sketch"]["plane"] is None + assert "the face at [5.0, 5.0, 10.0] mm" in reply["message"] + + +@pytest.mark.asyncio +async def test_create_sketch_point_in_the_air_is_invalid_input(mcp_server, mock_config): + """A point off the body fails with invalid_input naming the point.""" + from solidworks_mcp.adapters.mock_adapter import MockSolidWorksAdapter + + adapter = MockSolidWorksAdapter({}) + await adapter.connect() + await adapter.create_part() + tool = await _create_sketch_tool(mcp_server, adapter, mock_config) + + reply = await tool({"face_point": [5, 60, 5]}) + + assert reply["status"] == "error" + assert reply["error_type"] == "invalid_input" + assert "[5.0, 60.0, 5.0]" in reply["message"] + assert adapter._current_sketch is None