cadpilot 0.4.0__py3-none-any.whl

cadpilot/assembly_state.py

@@ -0,0 +1,192 @@
+"""Assembly sessions: component registry + joint sequence + precomputed-undo rollback.
+
+独立于建模会话（session_state.py）的装配状态机。每个装配步骤在记录时就
+预计算好 undo 负载（删哪些关节/裁剪、恢复哪些 Link 位姿、Link 重指向谁），
+rollback 时聚合为单个 rollback_step RPC spec 发给 addon 原子执行。
+
+Storage layout: ``<data_dir>/assembly/<session_id>.json``，data_dir 与建模会话
+共用 ``$CADPILOT_HOME``（默认 ``~/.cadpilot``）。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from .session_state import _now, data_dir
+
+logger = logging.getLogger("CADPilot")
+
+_lock = threading.Lock()
+_current: AssemblySession | None = None
+
+
+def assembly_dir():
+    path = data_dir() / "assembly"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+@dataclass
+class AssemblyStep:
+    """一个装配步骤；undo 是预计算的 rollback_step spec 字段。"""
+
+    step_number: int
+    operation: str  # start / add_component / mate / unmate
+    description: str
+    spec_echo: dict[str, Any] = field(default_factory=dict)
+    undo: dict[str, Any] = field(default_factory=dict)
+    timestamp: str = field(default_factory=_now)
+
+
+@dataclass
+class AssemblySession:
+    session_id: str
+    name: str
+    doc_name: str
+    assembly_name: str
+    ground_part: str
+    status: str = "active"  # active | completed
+    components: dict[str, Any] = field(default_factory=dict)  # part -> {"link", "added_step"}
+    joints: list[dict[str, Any]] = field(default_factory=list)
+    steps: list[AssemblyStep] = field(default_factory=list)
+    created_at: str = field(default_factory=_now)
+    updated_at: str = field(default_factory=_now)
+
+
+def save(session: AssemblySession) -> None:
+    """原子写入（tmp + replace）：写盘失败不会损坏已保存的会话文件。"""
+    session.updated_at = _now()
+    path = assembly_dir() / f"{session.session_id}.json"
+    payload = asdict(session)
+    tmp = path.with_suffix(".tmp")
+    try:
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(payload, f, ensure_ascii=False, indent=1)
+        tmp.replace(path)
+    finally:
+        tmp.unlink(missing_ok=True)
+
+
+def load(session_id: str) -> AssemblySession | None:
+    """加载会话；文件缺失/损坏/结构不符时返回 None（与 session_state 一致）。"""
+    path = assembly_dir() / f"{session_id}.json"
+    if not path.exists():
+        return None
+    try:
+        with open(path, encoding="utf-8") as f:
+            d = json.load(f)
+        d["steps"] = [s if isinstance(s, AssemblyStep) else AssemblyStep(**s) for s in d["steps"]]
+        return AssemblySession(**d)
+    except (OSError, json.JSONDecodeError, KeyError, TypeError) as exc:
+        logger.warning("cannot load assembly session %s: %s", session_id, exc)
+        return None
+
+
+def list_sessions() -> list[dict[str, Any]]:
+    out = []
+    for fn in assembly_dir().glob("*.json"):
+        s = load(fn.stem)
+        if s is None:
+            logger.warning("skipping corrupt assembly session %s", fn)
+            continue
+        out.append(
+            {
+                "session_id": s.session_id,
+                "name": s.name,
+                "doc_name": s.doc_name,
+                "status": s.status,
+                "steps": len(s.steps),
+                "updated_at": s.updated_at,
+            }
+        )
+    out.sort(key=lambda s: s["updated_at"], reverse=True)
+    return out
+
+
+def start_session(doc_name: str, ground: str, name: str = "") -> AssemblySession:
+    sid = uuid.uuid4().hex[:12]
+    session = AssemblySession(
+        session_id=sid,
+        name=name or f"assembly-{sid}",
+        doc_name=doc_name,
+        assembly_name="MCP_Assembly",
+        ground_part=ground,
+    )
+    save(session)
+    set_current(session)
+    return session
+
+
+def current_session() -> AssemblySession | None:
+    with _lock:
+        return _current
+
+
+def set_current(session: AssemblySession | None) -> None:
+    global _current
+    with _lock:
+        _current = session
+
+
+def resume_session(session_id: str) -> AssemblySession | None:
+    session = load(session_id)
+    if session is None:
+        return None
+    set_current(session)
+    return session
+
+
+def record_step(
+    session: AssemblySession, operation: str, description: str, spec_echo: dict, undo: dict
+) -> AssemblyStep:
+    step = AssemblyStep(
+        step_number=len(session.steps) + 1,
+        operation=operation,
+        description=description,
+        spec_echo=spec_echo,
+        undo=undo,
+    )
+    session.steps.append(step)
+    save(session)
+    return step
+
+
+def plan_rollback(session: AssemblySession, to_step: int) -> dict[str, Any]:
+    """聚合 to_step 之后所有步骤的 undo（逆序）为单个 rollback_step spec。
+
+    links_restore 记录的是每步**之前**的 Link 位姿快照；逆序遍历时
+    setdefault 保留最靠后步骤的快照，即最接近 to_step 时刻的状态。
+    """
+    joints: list[str] = []
+    cuts: list[str] = []
+    restore: dict[str, Any] = {}
+    repoint: dict[str, Any] = {}
+    remove_links: list[str] = []
+    for step in reversed([s for s in session.steps if s.step_number > to_step]):
+        undo = step.undo
+        joints += list(undo.get("joints_to_delete", []))
+        cuts += list(undo.get("cuts_to_delete", []))
+        for link, plc in undo.get("links_restore", {}).items():
+            restore.setdefault(link, plc)
+        repoint.update(undo.get("links_repoint", {}))
+        remove_links += list(undo.get("remove_links", []))
+    return {
+        "operation": "rollback_step",
+        "joints_to_delete": joints,
+        "cuts_to_delete": cuts,
+        "links_restore": restore,
+        "links_repoint": repoint,
+        "remove_links": remove_links,
+    }
+
+
+def truncate_after_rollback(session: AssemblySession, to_step: int) -> None:
+    session.steps = [s for s in session.steps if s.step_number <= to_step]
+    session.joints = [j for j in session.joints if j["step"] <= to_step]
+    session.components = {p: c for p, c in session.components.items() if c["added_step"] <= to_step}
+    save(session)

cadpilot/freecad_client.py

@@ -0,0 +1,319 @@
+import http.client
+import logging
+import xmlrpc.client
+from typing import Any
+
+logger = logging.getLogger("CADPilot")
+
+# Errors that mean the TCP connection is dead (FreeCAD restarted, addon
+# restarted, socket reset). Retrying once on a fresh proxy is safe.
+# socket.timeout is deliberately excluded: a timeout may mean FreeCAD is
+# still executing the request, and retrying would double-execute it.
+_RECOVERABLE_ERRORS = (ConnectionError, http.client.HTTPException)
+
+
+class _TimeoutTransport(xmlrpc.client.Transport):
+    """XML-RPC transport with a configurable socket timeout.
+
+    The default Transport has no timeout, so a frozen FreeCAD GUI thread
+    causes the MCP client to hang indefinitely (observed: 4+ minute waits).
+    """
+
+    def __init__(self, timeout: float = 30, **kwargs):
+        super().__init__(**kwargs)
+        self._timeout = timeout
+
+    def make_connection(self, host):
+        conn = super().make_connection(host)
+        conn.timeout = self._timeout
+        return conn
+
+
+class FreeCADConnection:
+    def __init__(self, host: str = "localhost", port: int = 9875, timeout: float = 150):
+        self._uri = f"http://{host}:{port}"
+        self._timeout = timeout
+        self.server = self._make_proxy(timeout)
+
+    def _make_proxy(self, timeout: float) -> xmlrpc.client.ServerProxy:
+        return xmlrpc.client.ServerProxy(
+            self._uri,
+            allow_none=True,
+            transport=_TimeoutTransport(timeout=timeout),
+        )
+
+    def _invoke(self, method: str, *args):
+        """Call an RPC method, rebuilding the proxy and retrying once if the
+        connection died (e.g. FreeCAD or the addon was restarted)."""
+        try:
+            return getattr(self.server, method)(*args)
+        except _RECOVERABLE_ERRORS as e:
+            logger.warning(
+                f"RPC connection lost during '{method}' ({e}); reconnecting and retrying once"
+            )
+            self.server = self._make_proxy(self._timeout)
+            return getattr(self.server, method)(*args)
+
+    def _invoke_with_screenshot(self, method: str, *args, screenshot: dict[str, Any] | None):
+        """Call a mutation RPC with an inline screenshot request.
+
+        Falls back to the legacy two-call path (op + get_active_screenshot)
+        when the addon predates the screenshot parameter, so a new MCP server
+        keeps working against an old addon install.
+        """
+        if screenshot is None:
+            return self._invoke(method, *args)
+        try:
+            return self._invoke(method, *args, screenshot)
+        except xmlrpc.client.Fault as e:
+            if "TypeError" not in str(e):
+                raise
+            logger.info(
+                f"Addon does not support inline screenshots for '{method}'; using legacy path"
+            )
+            res = self._invoke(method, *args)
+            if isinstance(res, dict) and res.get("success"):
+                shot = self.get_active_screenshot(
+                    screenshot.get("view_name", "Isometric"),
+                    screenshot.get("width"),
+                    screenshot.get("height"),
+                    screenshot.get("focus_object"),
+                )
+                if shot:
+                    res["screenshot"] = shot
+            return res
+
+    def disconnect(self) -> None:
+        # Transport.close() clears cached HTTP connections if one was opened.
+        transport = getattr(self.server, "_ServerProxy__transport", None)
+        close = getattr(transport, "close", None)
+        if callable(close):
+            close()
+
+    def ping(self) -> bool:
+        return self._invoke("ping")
+
+    def create_document(
+        self, name: str, screenshot: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        return self._invoke_with_screenshot("create_document", name, screenshot=screenshot)
+
+    def create_object(
+        self,
+        doc_name: str,
+        obj_data: dict[str, Any],
+        screenshot: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._invoke_with_screenshot(
+            "create_object", doc_name, obj_data, screenshot=screenshot
+        )
+
+    def create_feature(
+        self,
+        doc_name: str,
+        spec: dict[str, Any],
+        screenshot: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._invoke_with_screenshot("create_feature", doc_name, spec, screenshot=screenshot)
+
+    def assembly_op(self, doc_name: str, spec: dict[str, Any]) -> dict[str, Any]:
+        """Assembly-session RPC (addon joint_ops.assembly_op). No screenshots."""
+        return self._invoke("assembly_op", doc_name, spec)
+
+    def edit_object(
+        self,
+        doc_name: str,
+        obj_name: str,
+        obj_data: dict[str, Any],
+        screenshot: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._invoke_with_screenshot(
+            "edit_object", doc_name, obj_name, obj_data, screenshot=screenshot
+        )
+
+    def delete_object(
+        self,
+        doc_name: str,
+        obj_name: str,
+        screenshot: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._invoke_with_screenshot(
+            "delete_object", doc_name, obj_name, screenshot=screenshot
+        )
+
+    def execute_code(self, code: str, screenshot: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._invoke_with_screenshot("execute_code", code, screenshot=screenshot)
+
+    def execute_code_async(self, code: str) -> dict[str, Any]:
+        return self._invoke("execute_code_async", code)
+
+    def get_task_result(self, task_id: str) -> dict[str, Any]:
+        return self._invoke("get_task_result", task_id)
+
+    def execute_operations(
+        self,
+        doc_name: str,
+        ops: list[dict[str, Any]],
+        stop_on_error: bool = False,
+        screenshot: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._invoke_with_screenshot(
+            "execute_operations", doc_name, ops, stop_on_error, screenshot=screenshot
+        )
+
+    def undo_transactions(self, doc_name: str, n: int = 1) -> dict[str, Any]:
+        return self._invoke("undo_transactions", doc_name, n)
+
+    def redo_transactions(self, doc_name: str, n: int = 1) -> dict[str, Any]:
+        return self._invoke("redo_transactions", doc_name, n)
+
+    def save_document(self, doc_name: str, path: str | None = None) -> dict[str, Any]:
+        return self._invoke("save_document", doc_name, path)
+
+    def inspect_freecad(
+        self,
+        doc_name: str | None = None,
+        obj_name: str | None = None,
+        dotted_name: str | None = None,
+    ) -> dict[str, Any]:
+        return self._invoke("inspect_freecad", doc_name, obj_name, dotted_name)
+
+    def measure_geometry(self, doc_name: str, obj_name: str) -> dict[str, Any]:
+        return self._invoke("measure_geometry", doc_name, obj_name)
+
+    def get_topology(
+        self,
+        doc_name: str,
+        obj_name: str,
+        element: str = "faces",
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        return self._invoke("get_topology", doc_name, obj_name, element, limit, offset)
+
+    def check_interference(self, doc_name: str, obj_a: str, obj_b: str) -> dict[str, Any]:
+        return self._invoke("check_interference", doc_name, obj_a, obj_b)
+
+    def get_positioning_info(
+        self,
+        doc_name: str,
+        obj_name: str,
+        element: str,
+        element_index: int,
+    ) -> dict[str, Any]:
+        return self._invoke("get_positioning_info", doc_name, obj_name, element, element_index)
+
+    def align_shapes(
+        self,
+        doc_name: str,
+        obj_name: str,
+        element: str,
+        element_index: int,
+        target_obj_name: str,
+        target_element: str,
+        target_element_index: int,
+        mode: str = "touch",
+        offset: float = 0.0,
+    ) -> dict[str, Any]:
+        return self._invoke(
+            "align_shapes",
+            doc_name,
+            obj_name,
+            element,
+            element_index,
+            target_obj_name,
+            target_element,
+            target_element_index,
+            mode,
+            offset,
+        )
+
+    def get_anchors(self, doc_name: str, obj_name: str) -> dict[str, Any]:
+        return self._invoke("get_anchors", doc_name, obj_name)
+
+    def set_anchors(
+        self,
+        doc_name: str,
+        obj_name: str,
+        anchors: dict[str, Any],
+        replace: bool = False,
+        coord_frame: str = "local",
+        screenshot: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._invoke_with_screenshot(
+            "set_anchors",
+            doc_name,
+            obj_name,
+            anchors,
+            replace,
+            coord_frame,
+            screenshot=screenshot,
+        )
+
+    def assemble(
+        self,
+        doc_name: str,
+        mates: list[dict[str, Any]],
+        tolerance: float = 0.1,
+        stop_on_error: bool = True,
+        screenshot: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._invoke_with_screenshot(
+            "assemble", doc_name, mates, tolerance, stop_on_error, screenshot=screenshot
+        )
+
+    def verify_assembly(
+        self,
+        doc_name: str,
+        checks: list[dict[str, Any]] | None = None,
+        float_threshold: float = 1.0,
+        interference_min_volume: float = 1.0,
+    ) -> dict[str, Any]:
+        return self._invoke(
+            "verify_assembly", doc_name, checks, float_threshold, interference_min_volume
+        )
+
+    def get_active_screenshot(
+        self,
+        view_name: str = "Isometric",
+        width: int | None = None,
+        height: int | None = None,
+        focus_object: str | None = None,
+    ) -> str | None:
+        try:
+            return self._invoke("get_active_screenshot", view_name, width, height, focus_object)
+        except Exception as e:
+            logger.error(f"Error getting screenshot: {e}")
+            return None
+
+    def get_objects(self, doc_name: str) -> list[dict[str, Any]]:
+        res = self._invoke("get_objects", doc_name)
+        # New addon returns {"success": ..., "objects": [...]};
+        # old addon returns the list directly. A failure (e.g. document not
+        # found) must surface as an error, not as a misleading empty list.
+        if isinstance(res, dict):
+            if res.get("success") is False:
+                raise RuntimeError(res.get("error", "get_objects failed"))
+            if "objects" in res:
+                return res["objects"]
+            return []
+        return res if isinstance(res, list) else []
+
+    def get_object(self, doc_name: str, obj_name: str) -> dict[str, Any]:
+        res = self._invoke("get_object", doc_name, obj_name)
+        # New addon returns {"success": ..., "object": {...}};
+        # old addon returns the dict directly.
+        if isinstance(res, dict):
+            if res.get("success") is False:
+                raise RuntimeError(res.get("error", "get_object failed"))
+            if "object" in res:
+                return res["object"] or {}
+        return res if isinstance(res, dict) else {}
+
+    def list_documents(self) -> list[str]:
+        res = self._invoke("list_documents")
+        # New addon returns {"success": True, "documents": [...]};
+        # old addon returns the list directly.
+        if isinstance(res, dict) and "documents" in res:
+            return res["documents"]
+        return res if isinstance(res, list) else []

cadpilot/guidance.py

@@ -0,0 +1,192 @@
+"""Lightweight guidance for modeling sessions (CAD-trimmed from nsforge).
+
+Only heuristics that are genuinely useful while modeling: what to do next
+based on the document state, and risks that make rollback unreliable.
+Deliberately omitted from the nsforge original: goal/progress tracking,
+derivation patterns, and step replay verification.
+"""
+
+from __future__ import annotations
+
+from .session_state import ModelingSession
+
+# Ops that count as "sketch mode" activity for the primitive_without_sketch
+# heuristic (designing parts from constrained sketches, not raw primitives).
+_SKETCH_OPS = {
+    "sketch",
+    "pad",
+    "pocket",
+    "revolution",
+    "groove",
+    "hull",
+    "datum_plane",
+    "variables",
+}
+
+
+def suggest_next_steps(
+    session: ModelingSession,
+    object_names: list[str],
+) -> list[dict[str, str]]:
+    suggestions: list[dict[str, str]] = []
+
+    if not object_names:
+        suggestions.append(
+            {
+                "tool": "cad",
+                "operation": "create_object",
+                "reason": "The document is empty — create the first solid "
+                "(e.g. Part::Box / Part::Cylinder)",
+            }
+        )
+        return suggestions
+
+    non_atomic = [s.step_number for s in session.steps if not s.atomic]
+    if non_atomic:
+        suggestions.append(
+            {
+                "tool": "cad",
+                "operation": "batch",
+                "reason": f"Step(s) {non_atomic} used execute_code and cannot be rolled back "
+                "reliably; prefer cad() mutations for undoable steps",
+            }
+        )
+
+    # Multiple parts and no assembly activity yet → assembly mode.
+    if len(object_names) >= 2:
+        from . import assembly_state as _astate  # lazy: read-only registry probe
+
+        has_assembly = (
+            any(s.operation == "assemble" for s in session.steps)
+            or _astate.current_session() is not None
+        )
+        if not has_assembly:
+            suggestions.append(
+                {
+                    "tool": "assembly_session",
+                    "operation": "start",
+                    "reason": "Multiple parts in the document — assembly mode mates them "
+                    "with persistent joints (start → add_component → mate → solve)",
+                }
+            )
+
+    if session.step_count >= 10 and session.status == "active":
+        suggestions.append(
+            {
+                "tool": "session_complete",
+                "operation": "",
+                "reason": f"{session.step_count} steps recorded — consider completing the "
+                "session to save the workflow into the pattern store",
+            }
+        )
+
+    suggestions.append(
+        {
+            "tool": "get_view",
+            "operation": "",
+            "reason": "Visually check the current model state if unsure",
+        }
+    )
+    return suggestions[:3]
+
+
+def detect_risks(
+    session: ModelingSession,
+    doc_open: bool,
+    object_names: list[str] | None,
+) -> list[dict[str, str]]:
+    risks: list[dict[str, str]] = []
+
+    if not doc_open:
+        risks.append(
+            {
+                "level": "warning",
+                "type": "document_closed",
+                "message": f"Session document '{session.doc_name}' is not open in FreeCAD "
+                "(closed externally?). Rollback and mutations will fail.",
+            }
+        )
+        return risks
+
+    non_atomic = [s.step_number for s in session.steps if not s.atomic]
+    if non_atomic:
+        risks.append(
+            {
+                "level": "warning",
+                "type": "non_atomic_steps",
+                "message": f"Step(s) {non_atomic} were recorded via execute_code without a "
+                "transaction; session_rollback past them may undo the wrong change.",
+            }
+        )
+
+    # Fingerprint drift: the document's objects no longer match what the last
+    # recorded step saw — someone/something edited the document outside cad().
+    if object_names is not None and session.steps:
+        expected = session.steps[-1].objects_after
+        if expected and sorted(object_names) != expected:
+            risks.append(
+                {
+                    "level": "warning",
+                    "type": "state_drift",
+                    "message": "Document objects differ from the last recorded step — "
+                    "the model was edited outside cad() (GUI?). Rollback may "
+                    "undo those external edits too.",
+                }
+            )
+
+    # Connectivity: the last committed mutation's auto-audit found parts not
+    # touching the main assembly (recorded in the step's result_summary).
+    if session.steps and "Connectivity:" in session.steps[-1].result_summary:
+        detail = (
+            session.steps[-1].result_summary.split("Connectivity:", 1)[1].split("\n", 1)[0].strip()
+        )
+        risks.append(
+            {
+                "level": "warning",
+                "type": "disconnected_islands",
+                "message": f"Last mutation left disconnected islands: {detail} — "
+                "fix gaps so parts touch (≤0.5mm) or intersect.",
+            }
+        )
+
+    # Sketch-mode steer: several raw Part:: primitives and no sketch activity.
+    primitive = [
+        s
+        for s in session.steps
+        if s.operation == "create_object" and s.params_summary.startswith("Part::")
+    ]
+    if len(primitive) >= 2 and not any(s.operation in _SKETCH_OPS for s in session.steps):
+        risks.append(
+            {
+                "level": "info",
+                "type": "primitive_without_sketch",
+                "message": f"{len(primitive)} raw Part:: primitives created and no sketch "
+                "used — sketch mode (constrained sketch → pad/revolution/hull) "
+                "gives parametric, editable parts.",
+            }
+        )
+
+    # Blind placement: steps that set an absolute Placement (marker added by
+    # cad_operation in the step's params_summary).
+    placed = [s.step_number for s in session.steps if "+Placement" in s.params_summary]
+    if placed:
+        risks.append(
+            {
+                "level": "info",
+                "type": "absolute_placement",
+                "message": f"Step(s) {placed} set an absolute Placement — blind coordinates "
+                "cause floating parts. Prefer move/align_shapes/anchors "
+                "(free mode) or assembly_session mates.",
+            }
+        )
+
+    if session.redo_buffer:
+        risks.append(
+            {
+                "level": "info",
+                "type": "redo_available",
+                "message": f"{len(session.redo_buffer)} undone step(s) can be restored with "
+                "session_redo — any new cad() step discards them.",
+            }
+        )
+    return risks