feat(kcsolve): pybind11 bindings and Python solver support

Add the kcsolve pybind11 module exposing the KCSolve C++ API to Python:

- PyIKCSolver trampoline enabling Python IKCSolver subclasses
- Bindings for all 5 enums, 10 structs, IKCSolver, and OndselAdapter
- Module functions wrapping SolverRegistry (available, load, joints_for,
  set_default, get_default, register_solver)
- PySolverHolder class forwarding virtual calls with GIL acquisition
- register_solver() for runtime Python solver registration

IKCSolver constructor moved from protected to public for pybind11
trampoline access (class remains abstract via 3 pure virtuals).

Includes 16 Python tests covering module import, type bindings, enum
values, registry functions, Python solver subclassing, and full
register/load/solve round-trip.

Closes #288

src/Mod/Assembly/AssemblyTests/TestKCSolvePy.py

@@ -0,0 +1,237 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# ***************************************************************************
+# *                                                                         *
+# *   Copyright (c) 2025 Kindred Systems <development@kindred-systems.com>  *
+# *                                                                         *
+# *   This file is part of FreeCAD.                                         *
+# *                                                                         *
+# *   FreeCAD is free software: you can redistribute it and/or modify it    *
+# *   under the terms of the GNU Lesser General Public License as           *
+# *   published by the Free Software Foundation, either version 2.1 of the  *
+# *   License, or (at your option) any later version.                       *
+# *                                                                         *
+# *   FreeCAD is distributed in the hope that it will be useful, but        *
+# *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
+# *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU      *
+# *   Lesser General Public License for more details.                       *
+# *                                                                         *
+# *   You should have received a copy of the GNU Lesser General Public      *
+# *   License along with FreeCAD. If not, see                               *
+# *   <https://www.gnu.org/licenses/>.                                      *
+# *                                                                         *
+# ***************************************************************************
+
+"""Unit tests for the kcsolve pybind11 module."""
+
+import unittest
+
+
+class TestKCSolveImport(unittest.TestCase):
+    """Verify that the kcsolve module loads and exposes expected symbols."""
+
+    def test_import(self):
+        import kcsolve
+
+        for sym in (
+            "IKCSolver",
+            "OndselAdapter",
+            "Transform",
+            "Part",
+            "Constraint",
+            "SolveContext",
+            "SolveResult",
+            "BaseJointKind",
+            "SolveStatus",
+            "available",
+            "load",
+            "register_solver",
+        ):
+            self.assertTrue(hasattr(kcsolve, sym), f"missing symbol: {sym}")
+
+    def test_api_version(self):
+        import kcsolve
+
+        self.assertEqual(kcsolve.API_VERSION_MAJOR, 1)
+
+
+class TestKCSolveTypes(unittest.TestCase):
+    """Verify struct/enum bindings behave correctly."""
+
+    def test_transform_identity(self):
+        import kcsolve
+
+        t = kcsolve.Transform.identity()
+        self.assertEqual(list(t.position), [0.0, 0.0, 0.0])
+        self.assertEqual(list(t.quaternion), [1.0, 0.0, 0.0, 0.0])  # w,x,y,z
+
+    def test_part_defaults(self):
+        import kcsolve
+
+        p = kcsolve.Part()
+        self.assertEqual(p.id, "")
+        self.assertAlmostEqual(p.mass, 1.0)
+        self.assertFalse(p.grounded)
+
+    def test_solve_context_construction(self):
+        import kcsolve
+
+        ctx = kcsolve.SolveContext()
+        self.assertEqual(len(ctx.parts), 0)
+        self.assertEqual(len(ctx.constraints), 0)
+
+        p = kcsolve.Part()
+        p.id = "part1"
+        # pybind11 def_readwrite on std::vector returns a copy,
+        # so we must assign the whole list back.
+        ctx.parts = [p]
+        self.assertEqual(len(ctx.parts), 1)
+        self.assertEqual(ctx.parts[0].id, "part1")
+
+    def test_enum_values(self):
+        import kcsolve
+
+        self.assertEqual(int(kcsolve.SolveStatus.Success), 0)
+        # BaseJointKind.Fixed should exist
+        self.assertIsNotNone(kcsolve.BaseJointKind.Fixed)
+        # DiagnosticKind should exist
+        self.assertIsNotNone(kcsolve.DiagnosticKind.Redundant)
+
+    def test_constraint_fields(self):
+        import kcsolve
+
+        c = kcsolve.Constraint()
+        c.id = "Joint001"
+        c.part_i = "part1"
+        c.part_j = "part2"
+        c.type = kcsolve.BaseJointKind.Fixed
+        self.assertEqual(c.id, "Joint001")
+        self.assertEqual(c.type, kcsolve.BaseJointKind.Fixed)
+
+    def test_solve_result_fields(self):
+        import kcsolve
+
+        r = kcsolve.SolveResult()
+        self.assertEqual(r.status, kcsolve.SolveStatus.Success)
+        self.assertEqual(r.dof, -1)
+        self.assertEqual(len(r.placements), 0)
+
+
+class TestKCSolveRegistry(unittest.TestCase):
+    """Verify SolverRegistry wrapper functions."""
+
+    def test_available_returns_list(self):
+        import kcsolve
+
+        result = kcsolve.available()
+        self.assertIsInstance(result, list)
+
+    def test_load_ondsel(self):
+        import kcsolve
+
+        solver = kcsolve.load("ondsel")
+        # Ondsel should be registered by FreeCAD init
+        if solver is not None:
+            self.assertIn("Ondsel", solver.name())
+
+    def test_load_unknown_returns_none(self):
+        import kcsolve
+
+        solver = kcsolve.load("nonexistent_solver_xyz")
+        self.assertIsNone(solver)
+
+    def test_get_set_default(self):
+        import kcsolve
+
+        original = kcsolve.get_default()
+        # Setting unknown solver should return False
+        self.assertFalse(kcsolve.set_default("nonexistent_solver_xyz"))
+        # Default should be unchanged
+        self.assertEqual(kcsolve.get_default(), original)
+
+
+class TestPySolver(unittest.TestCase):
+    """Verify Python IKCSolver subclassing and registration."""
+
+    def _make_solver_class(self):
+        import kcsolve
+
+        class _DummySolver(kcsolve.IKCSolver):
+            def name(self):
+                return "DummyPySolver"
+
+            def supported_joints(self):
+                return [
+                    kcsolve.BaseJointKind.Fixed,
+                    kcsolve.BaseJointKind.Revolute,
+                ]
+
+            def solve(self, ctx):
+                r = kcsolve.SolveResult()
+                r.status = kcsolve.SolveStatus.Success
+                parts = ctx.parts  # copy from C++ vector
+                r.dof = len(parts) * 6
+                placements = []
+                for p in parts:
+                    pr = kcsolve.SolveResult.PartResult()
+                    pr.id = p.id
+                    pr.placement = p.placement
+                    placements.append(pr)
+                r.placements = placements
+                return r
+
+        return _DummySolver
+
+    def test_instantiate_python_solver(self):
+        cls = self._make_solver_class()
+        solver = cls()
+        self.assertEqual(solver.name(), "DummyPySolver")
+        self.assertEqual(len(solver.supported_joints()), 2)
+
+    def test_python_solver_solve(self):
+        import kcsolve
+
+        cls = self._make_solver_class()
+        solver = cls()
+
+        ctx = kcsolve.SolveContext()
+        p = kcsolve.Part()
+        p.id = "box1"
+        p.grounded = True
+        ctx.parts = [p]
+
+        result = solver.solve(ctx)
+        self.assertEqual(result.status, kcsolve.SolveStatus.Success)
+        self.assertEqual(result.dof, 6)
+        self.assertEqual(len(result.placements), 1)
+        self.assertEqual(result.placements[0].id, "box1")
+
+    def test_register_and_roundtrip(self):
+        import kcsolve
+
+        cls = self._make_solver_class()
+        # Use a unique name to avoid collision across test runs
+        name = "test_dummy_roundtrip"
+        kcsolve.register_solver(name, cls)
+
+        self.assertIn(name, kcsolve.available())
+
+        loaded = kcsolve.load(name)
+        self.assertIsNotNone(loaded)
+        self.assertEqual(loaded.name(), "DummyPySolver")
+
+        ctx = kcsolve.SolveContext()
+        result = loaded.solve(ctx)
+        self.assertEqual(result.status, kcsolve.SolveStatus.Success)
+
+    def test_default_virtuals(self):
+        """Default implementations of optional virtuals should not crash."""
+        import kcsolve
+
+        cls = self._make_solver_class()
+        solver = cls()
+        self.assertTrue(solver.is_deterministic())
+        self.assertFalse(solver.supports_bundle_fixed())
+
+        ctx = kcsolve.SolveContext()
+        diags = solver.diagnose(ctx)
+        self.assertEqual(len(diags), 0)