feat: add protpardelle

[marcuscollins]

This is a working version of Protpardelle-1c in SampleWorks. It may still require parameter tuning and other updates--in particular it isn't clear how to use self-conditioning. However we can generate structures with this version and so I'm making this PR as a milestone.

Only a couple significant changes have been made outside the Protpardelle wrapper code itself. One is to make a features class that is unfrozen, so that we can pass self-conditioning input forward to the next Euler step during sampling. Another is that we define different sampling parameters for Protpardelle when instantiating the sampler. There is no CLI control for either change in this PR.

Summary by CodeRabbit

• New Features
  • Added Protpardelle structure guidance support, including a new model option, Protpardelle-specific CLI parameters, and packaged sampling configuration.
• Bug Fixes
  • Guidance now logs the parsed configuration at startup.
• Chores
  • Updated development ignore rules for sample data and refined dependency/feature pins for Protpardelle-related installs.
• Tests
  • Added Protpardelle wrapper and CLI argument parsing tests; adjusted runner tests for more deterministic behavior.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds Protpardelle support across configuration, wrapper logic, guidance wiring, availability checks, fixtures, and tests. Also updates Pixi metadata, bundled data handling, and runner-test inputs.

Changes

Protpardelle wrapper and guidance integration

Layer / File(s)	Summary
Packaged config and environment setup .actlignore, pyproject.toml, src/sampleworks/data/cc89_epoch415.yaml, src/sampleworks/models/protpardelle/__init__.py	Adds the bundled Protpardelle YAML config, Pixi environment and dependency updates, and .actlignore rules that re-include src/sampleworks/data/.
Availability checks and wrapper import guards src/sampleworks/utils/imports.py	Adds Protpardelle availability detection, guarded import handling, dedicated decorators and checks, and extends generic model-availability helpers.
Protpardelle wrapper contracts and sampling flow src/sampleworks/models/protpardelle/wrapper.py	Defines wrapper constants and dataclasses, sequence extraction, structure annotation, featurization, coordinate conversion, sampling kwargs, noise expansion, step(), and prior initialization.
Guidance CLI and sampler integration src/sampleworks/utils/guidance_constants.py, src/sampleworks/utils/guidance_script_arguments.py, src/sampleworks/utils/guidance_script_utils.py, src/sampleworks/cli/guidance.py, src/sampleworks/core/samplers/edm.py	Adds the Protpardelle enum and CLI args, wires model construction and config propagation, applies Protpardelle-specific EDM sampler settings, and logs the parsed guidance config.
Protpardelle fixtures and tests tests/models/protpardelle/conftest.py, tests/models/protpardelle/test_protpardelle_wrapper.py, tests/cli/test_guidance_cli.py	Adds a small in-memory Protpardelle model fixture and tests for sequence extraction, annotation, featurization, coordinate conversion, prior initialization, step execution, and CLI argument parsing.
Runner test input hardening tests/runs/test_runner.py	Updates runner tests to use smaller GPU-count overrides and relaxes one argv assertion to check the script path by substring.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• diff-use/sampleworks#207: Directly related guidance-CLI plumbing and GuidanceConfig parsing changes.
• diff-use/sampleworks#255: Overlaps on Pixi feature and environment configuration in pyproject.toml.
• diff-use/sampleworks#261: Also adjusts .actlignore rules around data/ and src/sampleworks/data/.

Suggested reviewers: k-chrispens

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 48.68% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding Protpardelle support.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch mdc/add-protpardelle

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 8

🧹 Nitpick comments (1)

tests/models/protpardelle/test_protpardelle_wrapper.py (1)

147-160: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Keep these assertions at the public wrapper boundary.

These tests reach into _build_sampling_kwargs() and _convert_to_atom37() directly, which makes the suite brittle to internal refactors that preserve featurize(), initialize_from_prior(), and step() behavior. Either move the coverage to public API outcomes or promote the helpers if they are intended contract. As per coding guidelines, tests/**/*.py: "Write black-box tests that verify behavior, not implementation."

Also applies to: 287-320

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/models/protpardelle/test_protpardelle_wrapper.py` around lines 147 -
160, The tests are asserting private helper behavior via
ProtpardelleWrapper._build_sampling_kwargs() and _convert_to_atom37(), which
makes them brittle to internal refactors. Move this coverage to black-box
assertions around the public wrapper methods featurize(),
initialize_from_prior(), and step(), or explicitly promote those helpers if they
are meant to be part of the contract. Keep the checks focused on observable
outputs and behavior at the wrapper boundary rather than internal implementation
details.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@pyproject.toml`:
- Around line 139-141: The pyproject.toml currently defines the
dependency-overrides table twice under tool.pixi.pypi-options, which breaks TOML
parsing. Consolidate the duplicate [tool.pixi.pypi-options.dependency-overrides]
blocks into a single table, and keep the pandas and gemmi pins together there
only if they are intended to apply globally.

In `@src/sampleworks/models/protpardelle/wrapper.py`:
- Around line 707-709: The self-conditioning cached in
features.conditioning.x_self_conditioning is being stored with its autograd
history intact, which can carry the prior graph into later sampling steps.
Update the assignment in step() to cache a detached version of x_self_cond
before writing it to features.conditioning.x_self_conditioning, so repeated
iterations do not retain gradients across steps.

In `@src/sampleworks/utils/guidance_script_utils.py`:
- Around line 223-230: In the Protpardelle branch of guidance_script_utils, the
config_path is still built from a hardcoded src/sampleworks/data path, which
breaks when the package is installed and run from outside the repo. Update the
ProtpardelleWrapper config_path handling to load cc89_epoch415.yaml as a bundled
package resource using the package’s resource-loading APIs instead of resolving
a filesystem path relative to the current working directory. Keep the change
localized to the model-loading logic around StructurePredictor.PROTPARDELLE and
ProtpardelleWrapper.
- Around line 63-67: The Protpardelle fallback in the import block for
ProtpardelleWrapper is too narrow and can still crash non-Protpardelle runs.
Update the try/except around the ProtpardelleWrapper import to catch the
additional failure modes noted in imports.py, not just ImportError, and keep the
existing fallback assignment/logging. Also make the bundled YAML path in the
guidance script resolution independent of the current checkout by resolving it
from the package/module location instead of using a repo-relative path.

In `@src/sampleworks/utils/imports.py`:
- Around line 265-270: The install hint in require_any_model() is stale because
the availability check now includes PROTPARDELLE_AVAILABLE, but the
default_message still only mentions Boltz, Protenix, and RF3. Update the
default_message text in src/sampleworks/utils/imports.py to include Protpardelle
alongside the other supported model options so the decorator’s remediation
guidance matches the current logic.
- Around line 187-230: The bare decorator usage of require_protpardelle is
broken because the function object is being passed into the message parameter,
so the wrapper is not applied. Update require_protpardelle in imports.py to
support both `@require_protpardelle` and `@require_protpardelle`("...") by detecting
when the first argument is a callable vs a custom message, or remove the bare
form from the examples/docstring so only the parenthesized usage is advertised.

In `@tests/models/protpardelle/conftest.py`:
- Around line 17-21: The `os.environ.setdefault(...)` usage is eagerly creating
a temp directory via `tempfile.mkdtemp(...)` even when
`PROTPARDELLE_MODEL_PARAMS` is already set, so update the setup in `conftest.py`
to only call `mkdtemp` when the env var is missing. Apply the same lazy pattern
in `test_protpardelle_wrapper.py` where the same `setdefault`/`mkdtemp` usage
appears, using the existing `PROTPARDELLE_MODEL_PARAMS` guard to avoid
allocating untracked temp dirs on import.

In `@tests/runs/test_runner.py`:
- Around line 29-30: The argv assertion in the test is not hermetic because
runner._build_argv() can switch to a direct Python executable when a baked pixi
env is detected. Update the test setup for the affected assertion in
test_runner.py to force the pixi code path before checking the ["pixi", "run",
"-e", "rf3", "python"] prefix, using the existing test fixture/monkeypatch
around runner._build_argv() so the environment detection cannot change the
expected argv.

---

Nitpick comments:
In `@tests/models/protpardelle/test_protpardelle_wrapper.py`:
- Around line 147-160: The tests are asserting private helper behavior via
ProtpardelleWrapper._build_sampling_kwargs() and _convert_to_atom37(), which
makes them brittle to internal refactors. Move this coverage to black-box
assertions around the public wrapper methods featurize(),
initialize_from_prior(), and step(), or explicitly promote those helpers if they
are meant to be part of the contract. Keep the checks focused on observable
outputs and behavior at the wrapper boundary rather than internal implementation
details.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8a25473f-58ce-43f8-b062-7b353055864f

📥 Commits

Reviewing files that changed from the base of the PR and between 4826154 and 6713208.

⛔ Files ignored due to path filters (1)

• pixi.lock is excluded by !**/*.lock

📒 Files selected for processing (15)

• .actlignore
• pyproject.toml
• src/sampleworks/cli/guidance.py
• src/sampleworks/core/samplers/edm.py
• src/sampleworks/data/cc89_epoch415.yaml
• src/sampleworks/models/protpardelle/__init__.py
• src/sampleworks/models/protpardelle/wrapper.py
• src/sampleworks/utils/guidance_constants.py
• src/sampleworks/utils/guidance_script_arguments.py
• src/sampleworks/utils/guidance_script_utils.py
• src/sampleworks/utils/imports.py
• tests/models/protpardelle/__init__.py
• tests/models/protpardelle/conftest.py
• tests/models/protpardelle/test_protpardelle_wrapper.py
• tests/runs/test_runner.py

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/sampleworks/core/samplers/edm.py (1)

416-428: 🗄️ Data Integrity & Integration | 🔴 Critical | 🏗️ Heavy lift

model_wrapper.step() now breaks non-Protpardelle wrappers

src/sampleworks/core/samplers/edm.py:425-428 passes eps as a third positional argument, but Boltz, Protenix, and RF3 still define step(x_t, t, *, features=...). That will raise TypeError on those sampling paths. Update the protocol and wrapper signatures together, or gate this call to the Protpardelle-only implementation.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/sampleworks/core/samplers/edm.py` around lines 416 - 428, The
`model_wrapper.step()` call in the EDM sampler is now passing `eps`
positionally, which breaks wrappers like `Boltz`, `Protenix`, and `RF3` that
still only accept `step(x_t, t, *, features=...)`. Fix this by updating the
shared protocol and the wrapper implementations together so their `step`
signatures match the new call, or by restricting the extra `eps` argument to the
Protpardelle-specific path. Check the `model_wrapper.step()` invocation in the
EDM sampler and the corresponding `step` methods on the wrapper classes to keep
the interface consistent.

🧹 Nitpick comments (1)

src/sampleworks/cli/guidance.py (1)

13-16: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Redundant local logger import duplicates the new top-level import.

A top-level from loguru import logger is already added at the module level (lines 6-7), making this local re-import inside main() dead code. Lazy-loading get_model_and_device/run_guidance to keep --help light makes sense, but loguru is not a heavy dependency, so duplicating the import adds noise without benefit.

♻️ Proposed fix

 def main(argv: list[str] | None = None) -> int:
     config = GuidanceConfig.from_cli(argv)
 
-    from loguru import logger
-
     from sampleworks.utils.guidance_script_utils import get_model_and_device, run_guidance
 
     logger.info(f"Running guidance with config: {config}")

As per coding guidelines, "No dead code and no compatibility shims for hypothetical users."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/sampleworks/cli/guidance.py` around lines 13 - 16, The local re-import of
logger inside main() is redundant because logger is already imported at module
scope. Remove the inner from loguru import logger from main() and keep the lazy
import only for get_model_and_device and run_guidance so guidance.py uses the
existing top-level logger symbol consistently.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/sampleworks/core/samplers/edm.py`:
- Around line 416-428: The `model_wrapper.step()` call in the EDM sampler is now
passing `eps` positionally, which breaks wrappers like `Boltz`, `Protenix`, and
`RF3` that still only accept `step(x_t, t, *, features=...)`. Fix this by
updating the shared protocol and the wrapper implementations together so their
`step` signatures match the new call, or by restricting the extra `eps` argument
to the Protpardelle-specific path. Check the `model_wrapper.step()` invocation
in the EDM sampler and the corresponding `step` methods on the wrapper classes
to keep the interface consistent.

---

Nitpick comments:
In `@src/sampleworks/cli/guidance.py`:
- Around line 13-16: The local re-import of logger inside main() is redundant
because logger is already imported at module scope. Remove the inner from loguru
import logger from main() and keep the lazy import only for get_model_and_device
and run_guidance so guidance.py uses the existing top-level logger symbol
consistently.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f581f2ae-9bd1-4cb2-9dbc-72bd9be16919

📥 Commits

Reviewing files that changed from the base of the PR and between 6713208 and 4ac3e5b.

📒 Files selected for processing (7)

• src/sampleworks/cli/guidance.py
• src/sampleworks/core/samplers/edm.py
• src/sampleworks/models/protpardelle/wrapper.py
• src/sampleworks/utils/guidance_script_arguments.py
• src/sampleworks/utils/guidance_script_utils.py
• tests/cli/test_guidance_cli.py
• tests/models/protpardelle/test_protpardelle_wrapper.py

🚧 Files skipped from review as they are similar to previous changes (4)

• src/sampleworks/utils/guidance_script_arguments.py
• src/sampleworks/utils/guidance_script_utils.py
• tests/models/protpardelle/test_protpardelle_wrapper.py
• src/sampleworks/models/protpardelle/wrapper.py

[marcuscollins]

commit history got messed up. Closing this and re-opening on mdc/protpardelle