65 lines
2.7 KiB
Markdown
65 lines
2.7 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
SciMesh is a Python package for local 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 live in `tests/`; task specifications in `docs/`; the
|
|
roadmap is `PLAN.md`.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
Create a virtual environment, install the package with development tools, and
|
|
run the suite:
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -e '.[dev]'
|
|
pytest
|
|
```
|
|
|
|
Use `pytest tests/test_similarity_graph.py` to focus on one module. Exercise
|
|
the public CLI with `scimesh help` or `scimesh similarity-search --help`.
|
|
Run `python -m build` only when packaging is needed; install `build` first if
|
|
it is not available.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Target Python 3.10+ and use type hints for public functions, protocols, and
|
|
data exchanged between modules. 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 small standard-library 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.
|