dyno-phi 0.1.1__tar.gz

dyno_phi-0.1.1/.claude/skills/phi/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: phi
+description: "Run phi CLI commands for the dyno protein design platform: fetch structures, design binders (RFDiffusion3, BoltzGen), run folding/inverse-folding pipelines (ESMFold, AlphaFold2, ProteinMPNN), filter and score candidates, download results, and run research queries. Use when the user asks about phi commands, binder design, uploading PDB/CIF files, or scoring designs."
+argument-hint: "[command] [options]"
+allowed-tools: Bash(phi *)
+---
+
+# phi CLI skill
+
+`phi` is the command-line interface for **dyno-phi**, a protein design platform.
+Install it from PyPI:
+
+```bash
+pip install dyno-phi
+```
+
+Configure with a single environment variable (or a `.env` file at the repo root):
+
+```bash
+export DYNO_API_KEY=sk-...
+# Optional — defaults to the hosted API
+export DYNO_API_BASE_URL=https://api.dynotx.com
+```
+
+Verify connectivity:
+
+```bash
+phi login
+```
+
+---
+
+## End-to-end workflow
+
+```
+research → fetch → design → filter → download
+```
+
+Each step is optional depending on your starting point.
+
+---
+
+## 1. Research a target
+
+```bash
+# Biological research query with literature citations
+phi research \
+  --question "What are the key binding hotspots on PD-L1?" \
+  --target PD-L1 \
+  --structures \
+  --dataset-id <ID>
+
+# Stream results live
+phi research --question "..." --stream
+
+# Append notes to a local file and cloud storage
+phi research --question "..." --notes-file ./research.md --dataset-id <ID>
+
+# View accumulated notes for a dataset
+phi notes <DATASET_ID>
+```
+
+---
+
+## 2. Fetch and prepare structures
+
+`phi fetch` downloads a structure from RCSB PDB or the AlphaFold DB, optionally crops
+it by chain or residue range, and uploads it to a new dataset ready for design.
+
+```bash
+# Fetch a PDB entry (all chains)
+phi fetch --pdb 6M0J
+
+# Fetch a specific chain and residue range
+phi fetch --pdb 6M0J --chain A --start 1 --end 200
+
+# Fetch an AlphaFold DB prediction and trim low-confidence regions (pLDDT < 70)
+phi fetch --uniprot P12345 --plddt-cutoff 70
+
+# Upload the prepared structure to a new dataset for use with phi design
+phi fetch --pdb 6M0J --chain A --upload
+```
+
+After `--upload`, a new `dataset_id` is cached. The output prints the full `phi design`
+command ready to run.
+
+---
+
+## 3. Design binders
+
+### RFDiffusion3 (backbone diffusion — recommended default)
+
+```bash
+# Alias: phi design
+phi design --fasta target.fasta --hotspots A25,A30,A35 --num-designs 50 --wait
+
+# Specify binder length range
+phi design --fasta target.fasta --binder-min-length 60 --binder-max-length 100 --num-designs 50 --wait
+
+# Use a structure file from a cached dataset
+phi design --dataset-id <ID> --hotspots A25,A30 --num-designs 50 --wait
+
+# Specify partial diffusion steps (for motif scaffolding)
+phi rfdiffusion3 --fasta target.fasta --hotspots A25,A30 --partial-diffusion-steps 10 --num-designs 50 --wait
+```
+
+### BoltzGen (all-atom diffusion — for high-quality production runs)
+
+```bash
+# Full pipeline from a design YAML
+phi boltzgen --yaml design.yaml --protocol protein-anything --num-designs 50 --wait
+
+# Specify a budget (final diversity-filtered set size)
+phi boltzgen --yaml design.yaml --num-designs 1000 --budget 50 --wait
+
+# Run only specific pipeline steps
+phi boltzgen --yaml design.yaml --boltzgen-steps "design inverse_folding" --num-designs 50 --wait
+
+# Inverse folding only (resequence an existing backbone from a YAML spec)
+phi boltzgen --yaml backbone.yaml --only-inverse-fold --inverse-fold-num-sequences 10 --wait
+
+# Use a structure already uploaded to cloud storage
+phi boltzgen --yaml design.yaml --yaml-gcs gs://bucket/design.yaml --structure-gcs gs://bucket/target.cif --wait
+```
+
+**BoltzGen protocols:**
+
+| Protocol | Use |
+|---|---|
+| `protein-anything` | Design proteins to bind proteins or peptides (default) |
+| `peptide-anything` | Design (cyclic) peptides to bind proteins |
+| `protein-small_molecule` | Design proteins to bind small molecules |
+| `antibody-anything` | Design antibody CDRs |
+| `nanobody-anything` | Design nanobody CDRs |
+| `protein-redesign` | Redesign or optimize existing proteins |
+
+**BoltzGen pipeline steps** (pass to `--boltzgen-steps`):
+`design`, `inverse_folding`, `folding`, `design_folding`, `affinity`, `analysis`, `filtering`
+
+---
+
+## 4. Upload an existing design set
+
+```bash
+# Upload a directory of PDB / CIF files (auto-expands directories)
+phi upload ./designs/
+
+# Upload specific files
+phi upload binder_001.cif binder_002.pdb
+
+# Cache the dataset ID for subsequent commands
+phi use <DATASET_ID>
+```
+
+---
+
+## 5. Run the filter pipeline
+
+`phi filter` scores binder candidates end-to-end:
+inverse folding (ProteinMPNN) → folding (ESMFold) → complex folding (AlphaFold2) → score.
+
+```bash
+# Run with the default filter preset and wait for completion
+phi filter --dataset-id <DATASET_ID> --preset default --wait
+
+# Or, if a dataset is cached:
+phi filter --preset default --wait
+
+# Download results immediately after completion:
+phi filter --preset default --wait --out ./results
+```
+
+**Filter presets:**
+
+| Preset | pLDDT | pTM | ipTM | iPAE | RMSD |
+|--------|-------|-----|------|------|------|
+| `default` | ≥0.80 | ≥0.55 | ≥0.50 | ≤0.35 | ≤3.5 Å |
+| `relaxed` | ≥0.80 | ≥0.45 | ≥0.50 | ≤0.40 | ≤4.5 Å |
+
+Override any threshold individually:
+
+```bash
+phi filter --preset default --plddt-threshold 0.75 --rmsd-threshold 4.0 --wait
+```
+
+**MSA tool for complex folding:**
+
+```bash
+# Default: mmseqs2 (uses sequence homologs — best for natural-like designs)
+phi filter --preset default --msa-tool mmseqs2 --wait
+
+# single_sequence: skip MSA — best for truly novel de novo binders
+phi filter --preset relaxed --msa-tool single_sequence --wait
+```
+
+---
+
+## 6. Run individual tools
+
+All tool commands accept `--dataset-id ID` or use the cached dataset. Add `--wait` to
+poll until completion.
+
+#### Inverse folding (ProteinMPNN)
+```bash
+phi inverse_folding --dataset-id <ID> --wait
+phi proteinmpnn --dataset-id <ID> --num-sequences 10 --temperature 0.1 --wait
+```
+
+#### Folding (ESMFold)
+```bash
+phi folding --dataset-id <ID> --wait
+phi esmfold --dataset-id <ID> --recycles 3 --wait
+```
+
+#### Complex folding (AlphaFold2 multimer)
+```bash
+phi complex_folding --dataset-id <ID> --wait
+phi alphafold --dataset-id <ID> \
+  --models 1,2 \
+  --model-type multimer_v3 \
+  --msa-tool mmseqs2 \
+  --wait
+```
+
+#### ESM2 language model scoring
+```bash
+phi esm2 --dataset-id <ID> --wait
+```
+
+#### Boltz complex prediction
+```bash
+phi boltz --dataset-id <ID> --recycles 3 --wait
+```
+
+---
+
+## 7. Download results
+
+```bash
+# Download to ./results (default) — key files: structures/, scores/
+phi download
+
+# Download a specific job
+phi download <JOB_ID> --out ./my-results
+
+# Download everything including MSA files and archives
+phi download --all
+```
+
+`phi download` organizes output into:
+- `structures/` — PDB files
+- `scores/` — scores.csv and raw JSON sidecars
+- `scores.csv` — merged scores table
+
+---
+
+## 8. View scores
+
+```bash
+# Display scores table for the last job
+phi scores
+
+# Display top-20 candidates for a specific job
+phi scores <JOB_ID> --top 20
+
+# Save scores CSV locally
+phi scores --out ./scores.csv
+```
+
+---
+
+## Job management
+
+```bash
+phi jobs                        # List recent jobs
+phi jobs --status completed
+phi status <JOB_ID>             # Check a specific job
+phi cancel <JOB_ID>
+phi logs <JOB_ID>               # Print the log stream URL
+```
+
+---
+
+## Dataset management
+
+```bash
+phi datasets                    # List all datasets
+phi dataset <DATASET_ID>        # Show details
+phi use <DATASET_ID>            # Cache as the current working dataset
+```
+
+---
+
+## Tips
+
+### State caching
+`phi use <DATASET_ID>` writes to `.phi-state.json` in the current directory.
+`phi filter` also caches `last_job_id`, so `phi download` and `phi scores` work
+without arguments after a filter run.
+
+### Polling interval
+```bash
+phi filter --preset default --wait --poll-interval 10
+```
+
+### Key scoring metrics
+
+| Metric | Source | Good threshold |
+|--------|--------|----------------|
+| `plddt` | ESMFold | ≥ 0.80 |
+| `ptm` | AlphaFold2 | ≥ 0.55 |
+| `af2_iptm` | AlphaFold2 multimer | ≥ 0.50 |
+| `af2_ipae` | AlphaFold2 multimer | ≤ 0.35 |
+| `rmsd` | Binder vs design backbone | ≤ 3.5 Å |
+
+### Tool name aliases
+
+| Generic name | Tool | Notes |
+|---|---|---|
+| `folding` | ESMFold | Fast single-sequence folding |
+| `complex_folding` | AlphaFold2 multimer | Binder–target complex |
+| `inverse_folding` | ProteinMPNN | Sequence design from backbone |
+| `design` | RFDiffusion3 | Backbone diffusion (default) |
+
+---
+
+## Common workflows
+
+### Research-guided design
+```bash
+phi research \
+  --question "Which residues on EGFR domain III are critical for antibody binding?" \
+  --target EGFR --structures --notes-file ./research.md
+
+phi fetch --pdb 1IVO --chain A --start 300 --end 500 --upload
+
+phi design --hotspots A310,A315,A320 --num-designs 100 --wait
+
+phi filter --preset relaxed --msa-tool single_sequence --wait --out ./results
+phi scores
+```
+
+### Upload existing designs and score
+```bash
+phi upload ./designs/
+phi filter --preset default --wait --out ./results
+phi scores
+```
+
+### Relax thresholds for novel de novo binders
+```bash
+phi filter --preset relaxed --msa-tool single_sequence --wait
+```
+
+### BoltzGen inverse folding only (resequence a backbone)
+```bash
+phi boltzgen \
+  --yaml backbone_spec.yaml \
+  --only-inverse-fold \
+  --inverse-fold-num-sequences 10 \
+  --wait
+```
+
+### Full BoltzGen production run
+```bash
+phi boltzgen \
+  --yaml design_spec.yaml \
+  --protocol protein-anything \
+  --num-designs 10000 \
+  --budget 100 \
+  --wait
+```

dyno_phi-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    name: Lint, type-check & test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: ruff format (check)
+        run: ruff format --check src/ tests/
+
+      - name: ruff lint
+        run: ruff check src/ tests/
+
+      - name: mypy
+        run: mypy src/phi/
+
+      - name: pytest
+        run: pytest --tb=short

dyno_phi-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write  # required for OIDC trusted publishing
+
+jobs:
+  # ── 1. Build ──────────────────────────────────────────────────────────────────
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Hatch
+        run: pip install hatch
+
+      - name: Build wheel and sdist
+        run: hatch build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # ── 2. Publish to TestPyPI (automatic) ────────────────────────────────────────
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/dyno-phi
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  # ── 3. Publish to PyPI (requires manual approval) ─────────────────────────────
+  publish-pypi:
+    name: Publish to PyPI
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dyno-phi
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

dyno_phi-0.1.1/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+
+# Type checking
+.mypy_cache/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Phi runtime state
+.phi/
+.phi-state.json
+results/
+research.md
+
+# Credentials
+service-account.json
+*.json.key
+.env
+.env.*
+!.env.example
+
+# Modal
+.modal/
+
+# Cursor docs (local only)
+docs/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store

dyno_phi-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+        types_or: [python, pyi]
+      - id: ruff-format
+        types_or: [python, pyi]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        args: [src/phi/]
+        pass_filenames: false
+        additional_dependencies: []
+        stages: [pre-push]
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: pytest --tb=short -q
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

dyno_phi-0.1.1/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-03-01
+
+### Added
+- Initial public release of the `phi` CLI
+- `phi upload` — upload PDB/CIF files or a directory as a dataset
+- `phi fetch` — fetch a structure from RCSB PDB or AlphaFold DB
+- `phi datasets` / `phi dataset` — list and inspect datasets
+- `phi use` — set the active dataset (cached to `.phi-state.json`)
+- `phi design` (`rfdiffusion3`) — backbone diffusion via RFDiffusion3
+- `phi boltzgen` — all-atom binder design via BoltzGen
+- `phi folding` (`esmfold`) — single-sequence structure prediction
+- `phi complex_folding` (`alphafold`) — multi-chain complex prediction
+- `phi inverse_folding` (`proteinmpnn`) — sequence design via inverse folding
+- `phi esm2` — ESM2 sequence embeddings and scoring
+- `phi boltz` — Boltz-1 structure prediction
+- `phi filter` — full quality-control pipeline with configurable thresholds
+- `phi status` / `phi jobs` / `phi logs` / `phi cancel` — job management
+- `phi scores` — display scored results table
+- `phi download` — download job artifacts (structures, scores, raw JSONs)
+- `phi research` — research query against the platform
+- `phi notes` — manage dataset research notes
+- `biomodals/` — Modal GPU apps for AlphaFold2, ESMFold, ProteinMPNN, Boltz,
+  BoltzGen, BindCraft, Chai-1, RFdiffusion3, RF3, LigandMPNN, AF2Rank, RSO,
+  TM-score, structure alignment
+- Claude Code skill (`skills/phi/SKILL.md`)