ProteinClaw

ProteinClaw is a protein design pipeline built on Artisan. It ties together RFD3, MPNN, RF3, and downstream scoring so you can run phosphopeptide design jobs locally and inspect the results in one place.

The repo has two supported modes:

• Direct pipeline runs, where you launch the Artisan workflow yourself.
• Autoresearch, where an agent iterates on the experiment surface and runs parameter sweeps as a closed loop.

Setup

Start from a fresh clone and initialize the bundled dependencies:

git submodule update --init --recursive
pixi install
pixi run -e protein-dev protein-bootstrap
pixi run -e protein-dev prefect-start
pixi run -e protein-dev python prepare.py

protein-bootstrap writes .proteinclaw.env, and the protein-dev pixi environment loads it automatically for later runs. The protein-dev environment now installs CUDA-enabled PyTorch by default, so local RF3 and other Torch-backed steps can see the NVIDIA GPU when one is available.

If prepare.py reports missing paths, fix the generated environment until it ends with prepare_status: ok. For local runs, it should also report local_gpu_present: True.

Direct Pipeline Runs

Use this when you want to run the design pipeline yourself and keep the loop manual.

• Primary tutorial: examples/protein-design/01-phosphopeptide-binder-design.py
• Compatibility wrapper: examples/pipeline/run_local_10x5.py
• Tutorial guide: examples/protein-design/README.md
• Analysis notebook: examples/protein-design/02-phosphopeptide-binder-design-analysis.ipynb

The default direct example is a local 10x5 run:

• 10 RFD3 backbones
• 5 MPNN sequences per backbone
• 1 MPNN batch per backbone

Run the tutorial with:

pixi run -e protein-dev python examples/protein-design/01-phosphopeptide-binder-design.py

By default, the tutorial writes its run directories under examples/protein-design/runs/, so the matching analysis notebook can open the latest example run without extra path configuration.

The tutorial is written in explicit PipelineManager style. Edit build_plan() when you want to change parameters, or edit the pipeline.run(...) block inside main() when you want to change the workflow graph itself.

Autoresearch

Use this when you want an agent to evolve the experiment settings over repeated runs.

• Root loop brief: program.md
• Root experiment surface: train.py
• Example seed: examples/autoresearch/train.py
• Example brief: examples/autoresearch/program.md

Run the live loop from the repo root with:

pixi run -e protein-dev python train.py > run.log 2>&1

If you want Claude Code to drive the example seed unattended, use:

pixi run -e protein-dev autoresearch-example-claude --tag overnight --start-prefect --run-prepare

That launcher uses examples/autoresearch/train.py, keeps run outputs under examples/autoresearch/runs/, writes scores to examples/autoresearch/results.tsv, and saves Claude transcripts plus activity logs under examples/autoresearch/logs/<tag>/.

The root train.py now exposes the same explicit PipelineManager surface as the direct tutorial. Autoresearch can change build_plan() for parameter searches or edit the inlined pipeline.run(...) graph inside run() to change the actual workflow.

Repository Map

• src/proteinclaw/ - pipeline code, operations, and runtime helpers
• prepare.py - environment validation
• train.py - autoresearch experiment surface
• examples/protein-design/ - direct pipeline tutorial and analysis notebook
• examples/autoresearch/ - autoresearch example seed and brief
• third_party/artisan/ - pinned Artisan dependency
• third_party/autoresearch/ - pinned Autoresearch dependency
• third_party/foundry/ - pinned Foundry dependency