proto-tools: Instructions file for Claude Code

Project Overview

proto_tools is the Proto Bio library of typed bioinformatics tool wrappers. It provides uniform Python APIs, schemas, docs, examples, citations, licenses, and isolated execution environments for sequence, structure, ligand, genomic, and publication/database tools.

Read Before Editing

• README.md: user-facing setup, usage examples, gated model access, and tool catalog.
• Toolkit docs under proto_tools/tools/{category}/{toolkit}/: scientific context, metadata, examples, and standalone setup for the touched toolkit.
• Relevant notes/ files before changing runtime behavior, standalone environments, logging, storage, seeding, error handling, testing, or platform support.
• Source and tests: the final authority for signatures, schemas, exports, and behavior.

Development Setup

Use the active Python environment. For first-time development setup, install the package in editable mode with dev dependencies:

pip install -e ".[dev]"      # first-time setup only

Do not manually create or activate tool-specific environments; proto-tools builds and manages standalone tool environments automatically.

Integration tests are skipped by default. See notes/testing.md for markers, selection flags, logs, and test layout.

Do not write frivolous tests. A test that asserts Pydantic stored the default you just wrote (test_sample_config_defaults, test_*_config_defaults) proves nothing: it restates the source in a second place, so changing a default means editing both and the test never catches a mistake. Test computed properties, validators, normalization, error cases, and defaults that are derived from other fields. Pinning a value is only worth it when it must agree with something external, such as an upstream snapshot.

Before pushing any PR, run the full tests/style_consistency_tests/ suite (fast, CPU-only, no env). These run in CI and enforce consistency checks (docstring style, config/schema field metadata including the <100-char description limit, README/license/version consistency, tool I/O round-trip, and more) that ruff and mypy do not catch (ruff ignores E501). Failures propagate through configs embedded by other tools, e.g. an over-long Mmseqs2HomologySearchConfig field description fails every predictor that nests it.