solidworks-mcp-python 1.5.0__py3-none-any.whl

solidworks_mcp/adapters/vba_macro_executor.py

@@ -0,0 +1,215 @@
+"""VBA macro execution lifecycle management for SolidWorks automation."""
+
+from __future__ import annotations
+
+import tempfile
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from .base import AdapterResult, AdapterResultStatus
+
+
+@dataclass(frozen=True)
+class MacroExecutionRequest:
+    """Request to execute a VBA macro.
+
+    Attributes:
+        macro_code (str): The macro code value.
+        macro_name (str): The macro name value.
+        subroutine (str): The subroutine value.
+    """
+
+    macro_code: str
+    macro_name: str
+    subroutine: str = "Main"
+
+
+@dataclass(frozen=True)
+class MacroExecutionResult:
+    """Result of VBA macro execution.
+
+    Attributes:
+        duration_seconds (float): The duration seconds value.
+        error (str | None): The error value.
+        macro_name (str): The macro name value.
+        output (str | dict[str, Any] | None): The output value.
+        success (bool): The success value.
+    """
+
+    success: bool
+    macro_name: str
+    output: str | dict[str, Any] | None = None
+    error: str | None = None
+    duration_seconds: float = 0.0
+
+
+class VbaMacroExecutor:
+    """Manage VBA macro execution with save and tracking.
+
+    This executor handles the full lifecycle: code generation, on-disk persistence,
+    execution via the backing adapter, and result tracking.
+
+    Args:
+        temp_macro_dir (Path | None): The temp macro dir value. Defaults to None.
+
+    Attributes:
+        _temp_macro_dir (Any): The temp macro dir value.
+    """
+
+    def __init__(self, temp_macro_dir: Path | None = None) -> None:
+        """Initialize macro executor.
+
+        Args:
+            temp_macro_dir (Path | None): The temp macro dir value. Defaults to None.
+
+        Returns:
+            None: None.
+        """
+        self._temp_macro_dir = temp_macro_dir or Path(tempfile.gettempdir())
+        self._execution_history: dict[str, MacroExecutionResult] = {}
+
+    async def execute_macro(
+        self,
+        request: MacroExecutionRequest,
+        backing_adapter: Any,
+    ) -> AdapterResult[MacroExecutionResult]:
+        """Provide execute macro support for the vba macro executor.
+
+        Args:
+            request (MacroExecutionRequest): The request value.
+            backing_adapter (Any): The backing adapter value.
+
+        Returns:
+            AdapterResult[MacroExecutionResult]: The result produced by the operation.
+        """
+        start_time = datetime.utcnow()
+        macro_path = self._save_macro_to_disk(request.macro_code, request.macro_name)
+
+        try:
+            result = await self._execute_via_adapter(
+                macro_path=macro_path,
+                subroutine=request.subroutine,
+                backing_adapter=backing_adapter,
+            )
+
+            duration = (datetime.utcnow() - start_time).total_seconds()
+            execution_result = MacroExecutionResult(
+                success=result.get("success", False),
+                macro_name=request.macro_name,
+                output=result.get("output"),
+                error=result.get("error"),
+                duration_seconds=duration,
+            )
+
+            self._execution_history[request.macro_name] = execution_result
+
+            return AdapterResult(
+                status=AdapterResultStatus.SUCCESS,
+                data=execution_result,
+                metadata={
+                    "macro_path": str(macro_path),
+                    "macro_name": request.macro_name,
+                    "duration_seconds": duration,
+                    "subroutine": request.subroutine,
+                },
+            )
+
+        except Exception as exc:
+            duration = (datetime.utcnow() - start_time).total_seconds()
+            execution_result = MacroExecutionResult(
+                success=False,
+                macro_name=request.macro_name,
+                error=str(exc),
+                duration_seconds=duration,
+            )
+
+            self._execution_history[request.macro_name] = execution_result
+
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR,
+                error=f"macro execution failed: {exc}",
+            )
+
+    def get_execution_history(
+        self, macro_name: str | None = None
+    ) -> dict[
+        str,
+        MacroExecutionResult,
+    ]:
+        """Retrieve macro execution history.
+
+        Args:
+            macro_name (str | None): The macro name value. Defaults to None.
+
+        Returns:
+            dict[
+                str,
+                MacroExecutionResult,
+            ]: A dictionary containing the
+                                                                    resulting values.
+        """
+        if macro_name is not None:
+            return (
+                {
+                    macro_name: self._execution_history[macro_name],
+                }
+                if macro_name in self._execution_history
+                else {}
+            )
+        return dict(self._execution_history)
+
+    def _save_macro_to_disk(self, macro_code: str, macro_name: str) -> Path:
+        """Save VBA macro code to a file.
+
+        Args:
+            macro_code (str): The macro code value.
+            macro_name (str): The macro name value.
+
+        Returns:
+            Path: The result produced by the operation.
+        """
+        safe_name = "".join(
+            c if c.isalnum() or c in ("_", "-") else "_" for c in macro_name
+        )
+        timestamp = datetime.utcnow().timestamp()
+        macro_file = self._temp_macro_dir / f"{safe_name}_{timestamp}.swp"
+        macro_file.write_text(macro_code, encoding="utf-8")
+        return macro_file
+
+    async def _execute_via_adapter(
+        self,
+        macro_path: Path,
+        subroutine: str,
+        backing_adapter: Any,
+    ) -> dict[str, Any]:
+        """Delegate macro execution to backing adapter.
+
+        Args:
+            macro_path (Path): The macro path value.
+            subroutine (str): The subroutine value.
+            backing_adapter (Any): The backing adapter value.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+        """
+        if not hasattr(backing_adapter, "execute_macro"):
+            return {
+                "success": False,
+                "error": "backing adapter does not support macro execution",
+            }
+
+        try:
+            result = await backing_adapter.execute_macro(
+                macro_path=str(macro_path),
+                subroutine=subroutine,
+            )
+            if hasattr(result, "data"):
+                return result.data or {}
+            return result if isinstance(result, dict) else {"output": str(result)}
+        except AttributeError:
+            return {
+                "success": False,
+                "error": "adapter execute_macro failed",
+            }

solidworks_mcp/agents/__init__.py

@@ -0,0 +1,68 @@
+"""Agent-testing utilities for SolidWorks MCP custom agents."""
+
+from .harness import pretty_json, run_validated_prompt
+from .history_db import (
+    DEFAULT_DB_PATH,
+    ErrorRecord,
+    create_soc_checkpoint,
+    find_conversation_events,
+    find_recent_errors,
+    find_run_timeline,
+    get_design_session,
+    get_soc_checkpoint,
+    init_db,
+    insert_conversation_event,
+    insert_evidence_link,
+    insert_model_state_snapshot,
+    insert_plan_checkpoint,
+    insert_sketch_graph_snapshot,
+    insert_tool_call_record,
+    list_evidence_links,
+    list_model_state_snapshots,
+    list_plan_checkpoints,
+    list_sketch_graph_snapshots,
+    list_soc_checkpoints,
+    list_tool_call_records,
+    update_plan_checkpoint,
+    upsert_design_session,
+)
+from .retrieval_index import build_local_retrieval_index
+from .schemas import (
+    DocsPlan,
+    ManufacturabilityReview,
+    RecoverableFailure,
+    ToolRoutingDecision,
+)
+
+__all__ = [
+    "DEFAULT_DB_PATH",
+    "DocsPlan",
+    "ErrorRecord",
+    "ManufacturabilityReview",
+    "RecoverableFailure",
+    "ToolRoutingDecision",
+    "build_local_retrieval_index",
+    "create_soc_checkpoint",
+    "find_conversation_events",
+    "get_design_session",
+    "get_soc_checkpoint",
+    "find_recent_errors",
+    "find_run_timeline",
+    "init_db",
+    "insert_evidence_link",
+    "insert_model_state_snapshot",
+    "insert_plan_checkpoint",
+    "insert_sketch_graph_snapshot",
+    "insert_tool_call_record",
+    "insert_conversation_event",
+    "list_evidence_links",
+    "list_model_state_snapshots",
+    "list_plan_checkpoints",
+    "list_sketch_graph_snapshots",
+    "list_soc_checkpoints",
+    "list_tool_call_records",
+    "pretty_json",
+    "run_validated_prompt",
+    "update_plan_checkpoint",
+    "upsert_design_session",
+]

solidworks_mcp/agents/design_knowledge/assembly_patterns.md

@@ -0,0 +1,127 @@
+# FDM Print-in-Place and Assembly Design Patterns
+
+## Overview
+
+This guide covers design patterns for functional 3D-printed assemblies with a focus on
+reducing or eliminating post-print hardware.
+
+## Interlocking Joints
+
+### Dovetail Joint
+- Classic woodworking joint adapted for FDM
+- Angle: 14–18° is typical (wider = stronger pull resistance, harder to assemble)
+- Clearance: 0.25–0.35 mm per side for PETG
+- Print the male (tail) piece upright; female (pin) piece can be flat
+- Add 0.5 mm chamfer at entry to guide assembly
+
+### Mortise and Tenon
+- Simple rectangular tab and slot
+- Clearance: 0.20–0.30 mm per side
+- Tenon width should be 1/3 of joint width for best strength ratio
+- Add 1:5 taper on tenon faces for self-aligning entry
+
+### T-Slot / Extrusion Runner
+- Allows sliding and locking at any position
+- T-slot clearance: 0.30–0.45 mm (accounting for layer stepping on angled face)
+- Lock mechanism: quarter-turn cam, set screw boss, or wedge
+
+## Multi-Material Print-in-Place
+
+### Rigid + Flexible Combination
+- Print rigid structural frame in PLA/PETG
+- Print flexible gasket or grip in TPU (dual-extrusion or manual switch)
+- TPU-to-PLA interface: 0.0 mm clearance (TPU compresses to seal)
+- TPU-to-PETG: same, or -0.05 mm undersizing on TPU for preload seal
+
+### Dissolvable Support for Embedded Components
+- Use PVA (water soluble) or BVOH as support for internal channels and print-in-place joints
+- Soak in warm water 2–6 hours post-print
+
+## Living Assemblies (Mechanisms in One Print)
+
+### Universal Joint (Printed in One Piece)
+- Two yokes + crosspiece, assembled in-print
+- Crosspiece clearance: 0.4–0.5 mm (PETG)
+- Yoke knuckle clearance: 0.3–0.4 mm
+- Print axis: crosspiece horizontal for best print quality
+
+### Gear Train (In-Place)
+- Module 1.5–2.0 recommended (coarser = more robust)
+- Clearance on gear flanks (backlash): 0.15–0.25 mm total
+- Print gears with 5–6 top/bottom layers and 4+ perimeters for tooth strength
+- Infill 40–60% for gears under moderate load
+
+### Flexible Linkage / Compliant Mechanism
+- Use topology-optimization-inspired curved beams
+- Minimum wall for reliable flex: 0.8 mm (PETG/Nylon), 0.6 mm (TPU)
+- Print in a single orientation — never reorient mid-print
+
+## Structural Patterns for FDM
+
+### Ribs and Gussets
+- Rib thickness: 60–70% of wall thickness to reduce sink marks
+- Rib height-to-thickness: max 3:1 without risk of print instability
+- Gusset angle: 45° for equal XY and Z load distribution
+
+### Honeycomb Infill for Panels
+- For large flat panels, print 20–30% gyroid or honeycomb infill
+- Use 3–4 perimeters for lateral stiffness
+- Add filet radius at panel border (improves layer adhesion under peel loads)
+
+### Column / Pillar Features
+- Hollow columns with 2–3 perimeter walls and spiral vase-mode walls are light and stiff
+- Minimum column OD: 6 mm for 0.4 mm nozzle with 2 walls
+- Internal strengthening ribs at 3–6 mm pitch for taller columns
+
+## Fastener Boss Design
+
+### Heat-Set Insert Boss
+```
+Boss OD = insert OD × 2.0 (minimum 1.5× for space-constrained parts)
+Boss depth = insert length + 0.5 mm clearance at bottom
+Boss ID = (see tolerancing guide table)
+```
+
+### Self-Tapping Screw Boss
+```
+Boss OD = screw OD × 2.5
+Pilot hole = screw OD × 0.75 (e.g., M3: drill at 2.25 mm)
+Boss depth = screw length - 1.5 mm
+```
+
+### Through-Hole with Counter-bore
+```
+Through hole = bolt OD + 0.4 mm (M3: 3.4 mm)
+Counter-bore = washer OD + 0.5 mm (M3 washer: 7.0 mm → 7.5 mm bore)
+Counter-bore depth = washer thickness + 0.5 mm
+```
+
+## Print Orientation Rules for Mechanical Parts
+
+| Feature               | Best Orientation                          |
+|-----------------------|--------------------------------------------|
+| Snap fit arm          | Arm bends parallel to layers (horizontal)  |
+| Living hinge          | Web horizontal (flat to bed)               |
+| Gear teeth            | Teeth grow vertically (parallel to Z)      |
+| Threaded hole (tapped)| Thread axis vertical                       |
+| Tensile member        | Load axis parallel to X or Y (not Z)       |
+| Bearing surface       | Bore axis horizontal for rounder hole      |
+
+## Support-Free Design Tips
+
+1. Keep overhangs ≤ 45° from horizontal (or use chamfers instead of undercuts)
+2. Use internal chamfers (45°) instead of horizontal shelves
+3. Replace bridge > 50 mm with an arch or intermediate support pillar
+4. Tilt parts 5–15° to eliminate a single flat overhang without adding supports
+5. Use "teardrop" holes (circle + triangle point at top) for horizontal holes that self-support
+
+## Design Checklist Before Printing
+
+- [ ] All clearances set for target material (see tolerancing guide)
+- [ ] No unsupported overhangs > 45° (or supports planned)
+- [ ] Snap fit arms oriented parallel to bed
+- [ ] Living hinges web horizontal
+- [ ] Boss walls ≥ 1.5× insert OD
+- [ ] Thread/hole diameters compensated for hole undersizing
+- [ ] Part fits printer build volume (check with SolidWorks mass properties envelope)
+- [ ] Infill and wall count appropriate for load case

solidworks_mcp/agents/design_knowledge/hinges.md

@@ -0,0 +1,118 @@
+# Hinge Design Guide for FDM 3D Printing
+
+## Overview
+
+Hinges are rotational joints that allow controlled angular motion between two components.
+For FDM printing, hinges divide into two major categories:
+
+1. **Print-in-place hinges** — printed as a single assembly with a clearance gap; no assembly required
+2. **Hardware-assisted hinges** — use an M-series pin, dowel, or standard hinge hardware
+
+## Print-in-Place Hinges
+
+### Living Hinge (Flexure Hinge)
+
+A thin flexible web that bends instead of rotating.
+
+**Best materials:** PETG, TPU, Nylon (flexible layer bonding required)
+**Avoid:** PLA (brittle after repeated flex cycles)
+
+**Geometry guidelines:**
+
+- Minimum web thickness: 0.8–1.2 mm (PETG), 1.0–1.5 mm (Nylon), 0.4–0.8 mm (TPU)
+- Web width: 2–5× web thickness for stability
+- Transition fillets: R ≥ 1.5× web thickness to minimize stress concentration
+- Max reliable flex angle: ±30° for PETG, ±45° for Nylon, ±90° for TPU
+- Cycle life: PETG ~1000 cycles before fatigue crack; Nylon ~10,000+; TPU ~100,000+
+
+**Print orientation:** The web MUST be printed flat (parallel to bed) for maximum inter-layer
+adhesion in flex. Never print a living hinge on edge.
+
+**Layer height:** Use 0.15 mm or finer for living hinges to maximize layer count through
+the thin web. More layers = better fatigue life.
+
+### Barrel / Knuckle Print-in-Place Hinge
+
+Printed assembled with a clearance between pin and barrel.
+
+**Clearance recommendation:**
+
+| Material combo (pin/barrel) | Clearance |
+|-----------------------------|-----------|
+| PLA / PLA                   | 0.30–0.40 mm |
+| PETG / PETG                 | 0.35–0.50 mm |
+| ABS / ABS                   | 0.30–0.40 mm |
+| TPU pin / PLA barrel        | 0.15–0.25 mm |
+
+**Design rules:**
+
+- Minimum barrel length: 8–10 mm to prevent pin from camming out under load
+- Barrel wall thickness: ≥ 1.5 mm (3 perimeters at 0.4 mm nozzle)
+- Pin diameter: 3–6 mm typical; larger for structural load
+- Print orientation: hinge axis horizontal (pin parallel to bed) for round barrel geometry
+- Add a small (1 mm) chamfer at barrel entrance to help pin pop in
+
+**Assembly tip:** Print support removal easier if you use a 1.0 mm support gap and
+0.3–0.5 mm Z-gap on support interface.
+
+### Living Flexure with Stops
+
+Add hard-stop features to limit rotation and protect the living section from over-rotation.
+
+- Stop faces can be angled 0–90° to set max rotation
+- Position stops ≥ 5 mm from hinge center to allow clean rotation before contact
+
+## Hardware-Assisted Hinges
+
+### M3 / M4 Shoulder Bolt Hinge
+
+Use a stainless shoulder bolt as the hinge pin.
+
+**Pin hole tolerance:**
+
+- For M3 shoulder bolt (3.0 mm shank): print hole at Ø3.1–3.2 mm (clearance fit)
+- For M4 shoulder bolt (4.0 mm shank): print hole at Ø4.1–4.2 mm
+
+**Wear recommendation:** Insert a brass or steel M3/M4 heat-set insert as a sleeve if
+the hinge will be used frequently. Heat set inserts greatly extend wear life.
+
+**Wall thickness around pin:** minimum 2.5 mm on each side of pin hole.
+
+### Dowel Pin Hinge
+
+A 3 mm steel dowel pin is cheap and strong. Print hole at Ø3.1 mm and press the pin in.
+
+### Piano Hinge (Continuous Hinge)
+
+Mount a commercial piano hinge with M3 self-tapping or heat-set inserts.
+
+- Boss diameter for M3 insert: 5.5 mm OD, 4.0 mm deep
+- Boss OD should be ≥ 2× insert OD for sufficient wall
+
+## Hinge Variants for SolidWorks Parametric Design
+
+| Variant            | Recommended For                        | Key Parameter  |
+|--------------------|----------------------------------------|----------------|
+| Living hinge       | Light loads, frequent flex, TPU/Nylon  | web thickness  |
+| Barrel hinge       | Panel doors, enclosure lids            | barrel clearance|
+| Wrapped hinge      | Continuous flex (cable management)     | wrap radius    |
+| Ratchet hinge      | One-way or indexed rotation            | tooth count    |
+| Fold-flat hinge    | Portable structures, flat pack         | fold angle     |
+
+## SolidWorks Workflow
+
+1. Use **Revolve** for barrel/pin geometry
+2. Use **Shell** to thin the web for living hinges
+3. Use **Mates** to simulate rotation range and check interference
+4. Use **Flex** to visualize living hinge deflection
+5. Export as separate bodies for split-file printing if needed
+
+## Common Hinge Failure Modes
+
+| Failure                  | Cause                          | Fix                                     |
+|--------------------------|--------------------------------|-----------------------------------------|
+| Stiff / won't rotate     | Clearance too small            | Increase clearance 0.1 mm               |
+| Pin falls out            | Clearance too large            | Decrease clearance or add detent        |
+| Living web cracks        | Thickness too small / PLA      | Switch to PETG/Nylon, increase thickness |
+| Barrel cracks at entry   | Wall too thin                  | Increase wall thickness to ≥ 2 mm       |
+| Wobble / slop            | Barrel too short               | Extend barrel length                    |

solidworks_mcp/agents/design_knowledge/snap_fits.md

@@ -0,0 +1,93 @@
+# Snap-Fit Design Guide for FDM 3D Printing
+
+## Overview
+
+Snap fits are one of the most useful joint types for 3D-printed assemblies. They allow
+tool-free assembly and disassembly. FDM-specific design rules differ from injection
+molding guidelines due to layer anisotropy and material properties.
+
+## Types of Snap Fits
+
+### 1. Cantilever Snap Fit (Most Common for FDM)
+
+A cantilever snap fit is an arm that deflects laterally and then snaps into a recession
+or over a ledge.
+
+**Key geometry parameters:**
+
+- Arm length (L): longer arm = easier deflection, less stress
+- Arm width (b): wider = stiffer
+- Arm thickness (h): thinner at base for controlled flex
+- Deflection (δ): the snap travel before engagement
+- Lead angle: 15–30° for easy entry, 90° for permanent lock, 45° for reusable
+
+**FDM design rules:**
+
+- Orient the cantilever so it bends parallel to the print layers (not through layers)
+- Minimum arm length: 5× arm thickness at root to avoid crack at root
+- Clearance on non-deflecting sides: 0.3–0.5 mm (PETG), 0.2–0.4 mm (PLA)
+- Add a 0.5–1.0 mm fillet at the arm root to reduce stress concentration
+- Recommended retention angle for reusable snap: 30–45°
+- Recommended retention angle for permanent: 70–90°
+
+**Material-specific max strain:**
+
+- PLA: 2–3% safe strain limit
+- PETG: 3–5% safe strain limit
+- ABS: 3–5% safe strain limit
+- TPU/TPE: 10–20% (very flexible, use thick snaps)
+- Nylon PA12: 4–6%
+
+**Deflection formula (cantilever):**
+  δ = (strain × L²) / (1.5 × h)
+
+where L = arm length, h = arm thickness at root, strain = material limit.
+
+### 2. Annular (Ring) Snap Fit
+
+Used for caps, lids, and cylindrical closures.
+
+**FDM adaptation:**
+
+- Print vertically when possible so the ring is printed in-plane
+- Undercut depth: 0.5–1.0 mm for PLA/PETG
+- Lead chamfer: 30° for easy assembly
+- Oversize the male feature by 0.1–0.2 mm to preload the joint
+
+### 3. Torsional Snap Fit
+
+Less common but useful for panel inserts. The arm twists rather than bends.
+
+**FDM consideration:** Torsion through layers is weak; keep torsional snap fits
+in-plane with prints.
+
+### 4. Ball-and-Socket Snap (Print-in-Place)
+
+Popular for print-in-place joints:
+
+- Minimum clearance between ball and socket: 0.4–0.6 mm (PETG), 0.3–0.5 mm (PLA)
+- Print vertically for best-of-round socket
+- Socket opening angle: 90–120° for good retention while allowing disassembly
+
+## General FDM Snap Fit Clearances
+
+| Interface        | PLA         | PETG        | ABS         | Nylon       |
+|-----------------|-------------|-------------|-------------|-------------|
+| Sliding fit     | 0.25–0.35 mm| 0.30–0.40 mm| 0.25–0.35 mm| 0.20–0.35 mm|
+| Snap engagement | 0.20–0.30 mm| 0.25–0.35 mm| 0.20–0.30 mm| 0.15–0.25 mm|
+| Press fit       | 0.00–0.10 mm| 0.05–0.15 mm| 0.00–0.10 mm| -0.05–0.10 mm|
+
+## Common Snap Fit Failure Modes
+
+1. **Root fracture**: Arm too short or fillet missing → add fillet, increase arm length
+2. **No click/engagement**: Clearance too large → reduce by 0.1 mm increments
+3. **Permanent deformation**: Strain too high → increase arm length or switch material
+4. **Layer delamination**: Arm bending through layers → reorient print
+5. **Wobble after assembly**: Mating side clearance too large → add a locating boss
+
+## SolidWorks Implementation Tips
+
+- Model snap fits as separate bodies to control print orientation per body
+- Use the "Flex" feature to simulate deflection and check interference
+- Add "Draft" to snap faces to ease assembly direction
+- Use Equations to drive snap geometry from a single "clearance" variable

solidworks_mcp/agents/design_knowledge/solidworks_basics.md

@@ -0,0 +1,3 @@
+# SolidWorks Basics
+
+SolidWorks is a parametric 3D CAD system.