feat(solver): Phase 2 — pybind11 bindings and Python solver support #288

New Issue

forbes · 2026-02-19T21:01:43Z

forbes commented

2026-02-19 21:01:43 +00:00

Summary

Expose the KCSolve C++ API to Python via pybind11, add pure-Python solver base class, and build the debug/introspection API.

Scope

Per INTER_SOLVER.md Phase 2:

pybind11 module (`kcsolve`)

Bind all core types: JointTypeId, JointDef, Constraint, SolveContext, SolveResult, etc.
kcsolve.available() — list loaded solvers
kcsolve.load(solver_id) — get solver instance
kcsolve.register(py_solver) — register a Python solver at runtime
Pythonic SolveContext builder: ctx.add_part(), ctx.add_constraint()

PySolver base class

Python solvers subclass kcsolve.PySolver
Must implement: id, name, version, supported_joints(), solve(ctx)
Discovered from mods/*/solvers/*.py and <user_macros>/solvers/*.py

Debug / introspection API

kcsolve.Debugger(solver, ctx) — step-through iteration with per-step residuals
kcsolve.dependency_graph(ctx) — constraint dependency visualization
kcsolve.dof_analysis(ctx) — DOF count per part and total

File locations

src/Lib/KCSolve/bindings/
├── kcsolve_py.cpp
└── CMakeLists.txt

Dependencies

#287 (Phase 1: C++ API must exist first)

References

docs/INTER_SOLVER.md §6

## Summary Expose the KCSolve C++ API to Python via pybind11, add pure-Python solver base class, and build the debug/introspection API. ## Scope Per INTER_SOLVER.md Phase 2: ### pybind11 module (`kcsolve`) - Bind all core types: JointTypeId, JointDef, Constraint, SolveContext, SolveResult, etc. - `kcsolve.available()` — list loaded solvers - `kcsolve.load(solver_id)` — get solver instance - `kcsolve.register(py_solver)` — register a Python solver at runtime - Pythonic SolveContext builder: `ctx.add_part()`, `ctx.add_constraint()` ### PySolver base class - Python solvers subclass `kcsolve.PySolver` - Must implement: `id`, `name`, `version`, `supported_joints()`, `solve(ctx)` - Discovered from `mods/*/solvers/*.py` and `<user_macros>/solvers/*.py` ### Debug / introspection API - `kcsolve.Debugger(solver, ctx)` — step-through iteration with per-step residuals - `kcsolve.dependency_graph(ctx)` — constraint dependency visualization - `kcsolve.dof_analysis(ctx)` — DOF count per part and total ### File locations ``` src/Lib/KCSolve/bindings/ ├── kcsolve_py.cpp └── CMakeLists.txt ``` ## Dependencies - #287 (Phase 1: C++ API must exist first) ## References - docs/INTER_SOLVER.md §6

forbes added the enhancement label 2026-02-19 21:01:43 +00:00

forbes referenced this issue

2026-02-19 21:01:57 +00:00

feat(solver): Phase 3 — server integration and headless solve jobs #289

forbes referenced this issue

2026-02-19 21:02:07 +00:00

feat(solver): Phase 4 — second solver plugin (API validation) #290

forbes referenced this issue

2026-02-19 21:04:12 +00:00

Phase 5: GNN solver plugin (future) #291

forbes referenced this issue from a commit

2026-02-20 00:04:30 +00:00