Skip to content

Contributor Guide

When to use this page

Use this page when you are working on the mechestim repository itself rather than only consuming the published API.

Repository layout

This repository contains three Python packages plus docs and Docker assets:

Path Purpose
src/mechestim/ Core library backed by NumPy
mechestim-client/src/mechestim/ Client proxy used in sandboxed participant environments
mechestim-server/src/mechestim_server/ ZMQ server that executes the real library
tests/ Core library test suite
mechestim-client/tests/ Client unit, integration, and adversarial tests
mechestim-server/tests/ Server unit tests
docs/ MkDocs source
scripts/generate_api_docs.py Generates the API/reference inventory pages
docker/ Local client-server and hardened evaluation images

Initial setup

For normal work on the core package, docs, and root test suite:

git clone https://github.com/AIcrowd/mechestim.git
cd mechestim
make install

make install runs uv sync --all-extras and configures the local git hooks.

Which environment to use

The root environment covers the core package, linting, docs, and the main test suite. The client and server each also have their own pyproject.toml.

One important caveat: mechestim-server depends on the local mechestim package, which is not resolved from a package index in a fresh source checkout. For server development, run commands from the repository root with PYTHONPATH=src:mechestim-server/src instead of relying on cd mechestim-server && uv run ....

Common commands

Core library

make lint
make test
make test-numpy-compat
make docs-build
make docs-serve
make ci

If you prefer direct uv commands:

uv run pytest
uv run mkdocs serve

Client package

The client package is independently installable, so its test suite can run via its own project file:

uv run --project mechestim-client pytest mechestim-client/tests

Client integration and adversarial tests start a real server subprocess using the repository root .venv/bin/python, so run make install first.

Server package

Run server tests from the repository root so the local core package is on PYTHONPATH:

PYTHONPATH=src:mechestim-server/src \
  uv run --with pyzmq --with msgpack pytest mechestim-server/tests

To launch the server manually from a source checkout:

PYTHONPATH=src:mechestim-server/src \
  uv run --with pyzmq --with msgpack \
  python -m mechestim_server --url ipc:///tmp/mechestim.sock

Running client and server together without Docker

From a source checkout, use repo-root commands so both packages resolve correctly:

# Terminal 1
PYTHONPATH=src:mechestim-server/src \
  uv run --with pyzmq --with msgpack \
  python -m mechestim_server --url ipc:///tmp/mechestim.sock

# Terminal 2
export MECHESTIM_SERVER_URL=ipc:///tmp/mechestim.sock
PYTHONPATH=mechestim-client/src \
  uv run --with pyzmq --with msgpack python your_script.py

See Running with Docker if you want the same split using containers.

Generated documentation

Do not hand-edit pages that start with:

<!-- Auto-generated by scripts/generate_api_docs.py. Do not edit manually. -->

Today that includes:

  • docs/api/fft.md
  • docs/api/linalg.md
  • docs/api/polynomial.md
  • docs/api/random.md
  • docs/api/window.md
  • docs/reference/cheat-sheet.md
  • docs/reference/operation-audit.md

Instead, update scripts/generate_api_docs.py, the relevant source docstrings, or the operation registry, then regenerate:

uv run python scripts/generate_api_docs.py
uv run python scripts/generate_api_docs.py --verify