docs: update AGENTS.md and README for the current codebase

[mmmarinho]

Refreshes the agent-facing (AGENTS.md) and user-facing (README.md) docs against the latest main, and includes a one-line type-narrowing fix that keeps the pyright check at 0 errors.

Changes

AGENTS.md

• Build section — replaced the stale “venv bin not on PATH” note with the real prerequisites: cmake/ninja/g++, Eigen3 (find_package(Eigen3 REQUIRED)), and initialised git submodules (pybind11 + dqrobotics/cpp). Also notes git-tag-based versioning and the aarch64 -ffp-contract=off flag.
• New: constraint debug output — documents the _debug module and the single verbose kwarg (bool | dict) with per-category control (radius/plane/orientation/insertion/rcm).
• New: saul/ — clarifies these are live, simulator-driven scripts (need a running PedriatricSimulator over TCP), not a test suite.
• Tests — adds a caveat to run the smoke test outside the repo root (the source tree shadows the installed package and lacks the compiled _core).
• pyright — corrects the claim to “the invariant is 0 errors”; dqrobotics ships no type info so the repo keeps its own stubs/ (via stubPath). The 12 reportMissingModuleSource warnings only appear when the deps aren’t installed — an environment artifact, not a regression.

README.md

• Expands the one-line example into a short overview of what the package provides, the three installed example commands, and a pointer to saul/. Kept brief.

needle_controller.py

• Adds assert W is not None and w is not None before the .dtype checks. _get_optimization_parameters always returns non-None W/w (at least the joint-limit rows) but types them as Optional; the assert narrows the type so pyright resolves the reportOptionalMemberAccess error at the .dtype access. No runtime behaviour change.

Verification

• pyright → 0 errors (was 1 error before the fix).
• Built the C++ _core extension and ran the documented smoke test from a neutral dir — it constructs a NeedleController and returns W.shape == (19, 9).

Pre-existing issues spotted (not changed here)

Two things surfaced while verifying the docs; flagging for a follow-up PR rather than mixing into this docs change:

1. example_load_from_file.py passes 2-tuple rcm_constraints, but ICRA19TaskSpaceController._get_optimization_parameters unpacks each as a 3-tuple (p, r, idx) → ValueError: not enough values to unpack (expected 3, got 2) on first run. The sibling example uses index 6.
2. License metadata is inconsistent: LICENSE is LGPL-2.1, Python file headers say “LGPLv3”, the C++ header says MIT, and pyproject.toml says MIT. The README links to LICENSE without asserting a specific license.

---

This PR was created by an AI agent (OpenHands) on behalf of the user.

[mmmarinho]

License fix: standardise everything to MIT

New commit d50f288 on this branch resolves the license inconsistency I flagged in the PR description.

What was inconsistent

Location	Before
LICENSE file	Full LGPL 2.1 text (~500 lines)
7 Python file docstrings (_debug, _impl, example, example_create_needle_controller, example_load_from_file, icra2019_controller, needle_controller)	LGPLv3 License
pyproject.toml	license = {text = "MIT"} (already correct)
setup.py	license="MIT" (already correct)
include/M3_SerialManipulatorSimulatorFriendly.h	MIT License (already correct)

What changed

• LICENSE: replaced the LGPL 2.1 text with the standard MIT license (Copyright (c) 2025 Murilo M. Marinho — the author/maintainer declared in pyproject.toml).
• The 7 Python files: LGPLv3 License → MIT License (one-line change each, inside the existing docstring header).

Net diff: 8 files, +28 / −511 (the deletions are the LGPL license text).

With this, the entire repository is consistently MIT: the LICENSE file, every source-file header, pyproject.toml, setup.py and the C++ header all agree. git grep -iE 'LGPL' over the tracked source now returns nothing.

A comment posted by an AI agent (OpenHands) on behalf of the user.

[mmmarinho]

Remove CoppeliaSim/VREP from the repo

New commit c064356 on this branch. Per the clarification that saul/ is Saul's own bespoke simulator (unrelated to CoppeliaSim), I audited the repo for actual CoppeliaSim/V-REP artifacts and removed the one that exists.

What I found

The only tracked CoppeliaSim/V-REP item was:

• marinholab/working/needlemanipulation/scenes/UR3_410rev0.ttt — a CoppeliaSim scene file. It starts with the VREP magic bytes (VREP031...), and its git history is literally 1b7dcf9 "Added the coppeliasim evaluation". No Python code, example, or build configuration (pyproject.toml/setup.py/CMakeLists.txt/MANIFEST.in/CI) references it, so it was dead weight sitting inside the shipped package.

What changed

• Deleted marinholab/working/needlemanipulation/scenes/UR3_410rev0.ttt (and the now-empty scenes/ directory).

What I did not touch

• The saul/ folder is left completely intact — it's the bespoke simulator's scripts and .simstate state files, not CoppeliaSim. (saul/PedriatricSimulator.py talks to the simulator over a raw TCP socket on port 23815, which happens to coincide with CoppeliaSim's default Remote API port, but that is a port number, not a CoppeliaSim dependency.)
• The historical example_kinematics_from_coppeliasim.py (using dqrobotics.interfaces.coppeliasim) was already deleted earlier in history (e5655aa), so there was nothing else to remove from the current tree.

Verification

• git grep -iE "coppelia|vrep|v_rep" over the tracked tree now returns nothing — CoppeliaSim/V-REP is no longer present in the repo.

A comment posted by an AI agent (OpenHands) on behalf of the user.

[mmmarinho]

Replace quadprog with marinholab-solvers-qpoases

New commit 7fdf57a on this branch. The velocity QP now uses the qpOASES-backed marinholab-solvers-qpoases solver from PyPI instead of dqrobotics.solvers.DQ_QuadprogSolver (the thin quadprog wrapper).

What changed

• icra2019_controller.py — from dqrobotics.solvers import DQ_QuadprogSolver → from marinholab.solvers.qpoases import Solver, and self.qp_solver = Solver(). The solve_quadratic_program(H, f, A, b, Aeq, beq) signature is identical and accepts A=None/Aeq=None (exactly the pattern the controllers use: solve_quadratic_program(H, f, W, np.squeeze(w), None, None)), so the ICRA19TaskSpaceController and NeedleController call sites are untouched.
• pyproject.toml — dependencies: removed "quadprog", added "marinholab-solvers-qpoases".
• stubs/dqrobotics/solvers/__init__.pyi — removed the now-unused DQ_QuadprogSolver stub; the abstract DQ_QuadraticProgrammingSolver remains (it's still part of the dqrobotics API). The qpoases Solver is typed from its own package.
• AGENTS.md — the old "dqrobotics solver classes (important)" section (which was entirely about quadprog missing and the "pure virtual function" symptom) is replaced with a "QP solver (marinholab-solvers-qpoases)" section documenting the current solver; the stub-tree listing no longer mentions DQ_QuadprogSolver.

Verification

• git grep -iE "quadprog" over the tracked tree: no matches — it's fully gone.
• Rebuilt the package (pip install . --no-build-isolation) and, from a neutral directory, confirmed the NeedleController now holds a marinholab.solvers.qpoases.Solver and solves the controller-shaped QP (H 9×9, W 19×9, u 9-DoF, all finite).
• pyright: 0 errors, 0 warnings.

Note (pre-existing, not caused by this change): solving the actual q0 QP from example_load_from_file's RCM sphere still reports ValueError: constraints are inconsistent — the RCM margins for the candidate indices are violated at q0 (the scenario/calibration issue flagged earlier in this PR, e.g. the 2-tuple vs 3-tuple arity). I verified the solver wiring with a feasible QP of identical shape to keep this change's scope clean; the example's numerical infeasibility remains open for its own fix.

A comment posted by an AI agent (OpenHands) on behalf of the user.

[mmmarinho]

👍