2.8 KiB
Repository Guidelines
Project Structure & Module Organization
SciMesh is a Python package for molecular-similarity workloads. Source lives in
scimesh/: chemistry/ reads data and makes fingerprints, workloads/
contains commands, and core/ provides the workload protocol and registry.
The worker daemon in scimesh/worker/ is a coordinator client, not a database
client. Tests are in tests/; specifications in docs/; roadmap: PLAN.md.
For distributed work, read .agents/, docs/api-contract.md,
and STATUS.md. Use one CTX task per pull request; local workloads are the
scientific reference.
Build, Test, and Development Commands
Create a virtual environment, install the package with development tools, and run the suite:
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest
Use pytest tests/test_similarity_graph.py for one module. Exercise the CLI
with scimesh help or scimesh similarity-search --help. Run python -m build
only when packaging is needed; install build first if necessary.
Coding Style & Naming Conventions
Target Python 3.10+; type public APIs and exchanged data. Use four spaces,
snake_case for modules,
functions, and variables, PascalCase for classes, and descriptive test names
such as test_graph_is_deterministic_across_block_sizes. Keep CLI parsing in
workload modules and register new workloads through scimesh/core/registry.py;
do not add workload-specific logic to the main CLI.
Prefer few dependencies. RDKit is the chemistry dependency. For worker/coordinator work, keep network payloads explicit and multi-line; never make the worker access PostgreSQL directly.
Testing Guidelines
Use pytest and add a regression test for every defect. Similarity code must be
checked against a small brute-force or fully sorted reference. Graph results
must be deterministic, have no self-loops or duplicate pairs, and remain
stable for different block sizes. Worker changes need success and failure
tests: checksum mismatch, lease failure, upload failure, and safe reporting.
Run the full pytest suite before committing.
Commit & Pull Request Guidelines
Use short imperative commit subjects, for example Add graph threshold mode or
Fix worker result and lease contracts. Keep one logical change per commit.
In a pull request, state the problem, behaviour changed, tests run, and any API
or documentation changes. Link the relevant CTX-* item in PLAN.md for
distributed work. Do not commit datasets, generated CSV/PNG files, .venv/,
tokens, or local worker artifacts.
Security & Protocol Rules
Upload worker results through the coordinator before posting completion; never
submit file:// or worker:// result URIs. Send failures to /failure, not
/result. Do not log bearer tokens, raw tracebacks, or private local paths.