Development

Contributor workflow: dev environment, test suite, lint and type-check.

Prepare the developer environment

Prerequisites: EVA Client source checkout, uv, and Python 3.10+. See Installation. Run the following from the project root. The [dev] extra pulls in pytest, ruff, and pyright.

bash

# create and activate the venv
uv venv --python 3.10 --system-site-packages .venv
source .venv/bin/activate

# install EVA Client with contributor tools
uv pip install -e ".[dev]"

Re-run source .venv/bin/activate in every new shell. If installs hang behind a proxy, clear it with unset http_proxy https_proxy.

Run the test suite

Run from the project root, after code changes and before commit:

bash

# all tests
pytest

# skip slow IK tests
pytest -m "not slow"

# one area
pytest tests/integration/web

Slow-tagged tests depend on optional IK libraries; they auto-skip when those libraries are absent, so a clean machine still passes.

Folder	What it checks
`tests/config/`	Config loading and merging; strategy and robot selection.
`tests/comms/`	Policy server transport and on-wire data flow.
`tests/ik/`	IK solvers. Contains slow tests.
`tests/strategy/`	Inference strategies and the action buffer.
`tests/transport/` · `tests/recorder/`	ROS transport and the episode recorder.
`tests/integration/web/`	End-to-end Web console driven over HTTP.

No ROS install or hardware is required — the robot side is faked.

How the Web console tests run offline

tests/integration/web/ boots the real console server and drives it over HTTP with no ROS, no hardware, no policy server — the robot transport and policy are stubbed. When writing or fixing a test, use the helpers in that folder.

Run a manual verification script

tests/manual/ holds standalone end-to-end scripts run outside pytest:

bash

PYTHONPATH=src python tests/manual/<script>.py

Script	Flow
`verify_eval_flow_e2e.py`	Full EVAL run: start, record, score, resume, scoring rules.
`verify_eval_rollout.py`	Scoring edge cases and re-test of the same trial.
`verify_eval_lerobot_meta.py`	Trial score and notes are written into the recorded dataset.
`viser_track_chunk.py`	Interactive 3D tool: record a hand path, inspect how closely the solved joint motion tracks it.

Format and check the code

Run before commit:

bash

# lint, then auto-fix
ruff check .
ruff check --fix .

# format
ruff format .

# type-check
pyright

ruff enforces a 100-column line limit. Vendored ARX / alicia_d SDKs under examples/ are excluded — do not reformat them.
pyright runs in relaxed mode and ignores missing imports (ROS and hardware libs are often absent on dev machines). Test files run under even looser rules.

Enable the pre-commit hook once with pre-commit install to run ruff automatically on commit.

Follow the contributor conventions

CLAUDE.md (also exposed as AGENTS.md — same file) is the contributor guide. Key rules:

Minimal diff. Touch only what the task requires; no drive-by reformatting.
Imports at file top; record every new dependency in pyproject.toml.
Comments in English, sparingly. Explain non-obvious reasons; do not narrate the change.
Document public functions with a one-line summary plus inputs and outputs.
No automatic commits; no AI-signature or co-author tags in any output.