Skip to content
Back to search

ipro-agent

SkillWorks with Claude CodeGitHub

Agent-drivable protein redesign: point the IPRO procedure at any protein and a stated goal (specificity, pore size, affinity, catalysis, stability, terminal indels). Independent reimplementation; rotamer selection as a MILP so your constraints are enforced exactly.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/chowdhurylab-studio--ipro-agent/badge.svg)](/listings/chowdhurylab-studio--ipro-agent)

HTML

<a href="/listings/chowdhurylab-studio--ipro-agent"><img src="/api/listings/chowdhurylab-studio--ipro-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Two lines, if you want to drive it from an agent.** Install it, then point your MCP client at it:

pip install ipro-agent
{"mcpServers": {"ipro-agent": {"command": "ipro-agent-mcp"}}}

Then ask your agent to run `ipro_doctor`, which reports what resolved. On a bare pip install it reports PyMOL missing: `ipro_validate`, `ipro_inspect_structure` and `ipro_goals` still work, so the agent can read a structure and check a spec, while `ipro_score` and `ipro_milp` refuse in those words rather than guessing. PyMOL is the one dependency pip cannot supply, so for a design install it from conda-forge and point `command` at that environment's `ipro-agent-mcp`:

conda create -n ipro-agent -c conda-forge pymol-open-source python=3.12
conda activate ipro-agent
pip install ipro-agent

Set `IPRO_REPO` to a checkout as well if you want the server to serve its own documents rather than tell the agent where to fetch them.

**One command, if you want the example, the documents and the worked prompts too.** This one needs the repository, so clone it first:

git clone https://github.com/chowdhurylab-studio/ipro-agent
cd ipro-agent
bash scripts/bootstrap.sh

That creates the environment, reports what resolved, runs the test suite and the shipped example, and prints the exact commands and MCP config with your own paths filled in. Safe to re-run; the only thing it deletes is its own `runs/bootstrap` directory, which it recreates (without that, a second run would append onto the first one's trajectory).

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/chowdhurylab-studio/ipro-agent/main/docs/demo-chat-dark.gif"> </picture>

*What using it looks like: resolve the positions, prove the constraint reached the solver, run, and read the refusal. Reconstructed rather than recorded, from real output of the shipped example. [More worked prompts](https://github.com/chowdhurylab-studio/ipro-agent/blob/main/docs/EXAMPLE_PROMPTS.md), with what each one produces. `docs/index.html` is the same five as a page you can open or send.*

By hand instead. The install step is not optional: rotamers come only from PyMOL's mutagenesis wizard, and `pymol-open-source` is conda-only, so `pip install` alone cannot give you a working design pipeline:

conda env create -f environment.yml && conda activate ipro-agent

Then check what resolved. Everything below runs from the repo root; nothing needs installing the package itself:

python3 scripts/doctor.py --require pymol
python3 -m ipro_agent validate examples/ompf_pore/spec_smoke.yaml
python3 -m ipro_agent run examples/ompf_pore/spec_smoke.yaml --run-dir runs/smoke
python3 -m ipro_agent status runs/smoke

What that run produces, so you can tell a working install from a real result: with the shipped seed it accepts 3 iterations and reports zero mutations. The native residues win at those four positions because no reference-energy term offsets the packing bias against large side chains, and the run says so in its `notes`. That is a successful smoke test rather than a design. For a run that does mutate, see `examples/ompf_pore/spec_full.yaml` (25 positions, ~85 s/iteration) or set `goal_options.reference_energies`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 12 lines
  1. # This file has moved
  2. The skill lives at **[.claude/skills/ipro-agent/SKILL.md](.claude/skills/ipro-agent/SKILL.md)**,
  3. which is where an agent discovers it automatically: clone this repo, open it with
  4. an agent, and ask for a redesign in plain language — the skill loads itself from
  5. its `description`, with no setup step.
  6. This stub stays because the convention this repo was modelled on
  7. (`lucidfrontier45/autodock-vina-agent`) keeps a `SKILL.md` at the root, so
  8. anything following that convention still finds its way.
  9. Start here if you are a person rather than an agent: [README.md](README.md).
README.md · README · 374 lines
  1. # ipro-agent
  2. <!-- mcp-name: io.github.chowdhurylab-studio/ipro-agent -->
  3. An independent, agent-drivable reimplementation of the published **IPRO**
  4. procedure (Iterative Protein Redesign and Optimization).
  5. > Unsupported research code, maintained by the
  6. > [Chowdhury Lab](https://github.com/chowdhurylab-studio); please use GitHub
  7. > issues. It implements a method published by the Maranas group (Penn State),
  8. > cited under [Citing](#citing). It is not their software and is not endorsed
  9. > by them. None of their code is in it.
  10. IPRO as published is a suite of programs wired to specific case studies: the
  11. molecules, the design positions and the objective live in a per-case Python
  12. input deck. This repo keeps the machinery and replaces the wiring with a
  13. declarative problem statement, so the same optimizer can be pointed at an
  14. arbitrary protein and an arbitrary stated goal, by a person or by an LLM agent.
  15. You give it:
  16. - a goal in plain language, mapped to one of five objectives;
  17. - structures of the interacting partners (protein, peptide, small molecule,
  18. transition-state analogue);
  19. - the positions where mutation is allowed, and the amino acids allowed at
  20. each.
  21. It writes the rotamer-selection MILP that encodes those constraints, then
  22. iterates: perturb → choose optimal rotamers → dock → relax → accept or reject
  23. on energy. Out comes a design sequence, the per-iteration energies, and an
  24. ensemble of the best designs.
  25. ## Quick start
  26. **Two lines, if you want to drive it from an agent.** Install it, then point
  27. your MCP client at it:
  28. ```bash
  29. pip install ipro-agent
  30. ```
  31. ```json
  32. {"mcpServers": {"ipro-agent": {"command": "ipro-agent-mcp"}}}
  33. ```
  34. Then ask your agent to run `ipro_doctor`, which reports what resolved. On a
  35. bare pip install it reports PyMOL missing: `ipro_validate`,
  36. `ipro_inspect_structure` and `ipro_goals` still work, so the agent can read a
  37. structure and check a spec, while `ipro_score` and `ipro_milp` refuse in those
  38. words rather than guessing. PyMOL is the one dependency pip cannot supply, so
  39. for a design install it from conda-forge and point `command` at that
  40. environment's `ipro-agent-mcp`:
  41. ```bash
  42. conda create -n ipro-agent -c conda-forge pymol-open-source python=3.12
  43. conda activate ipro-agent
  44. pip install ipro-agent
  45. ```
  46. Set `IPRO_REPO` to a checkout as well if you want the server to serve its own
  47. documents rather than tell the agent where to fetch them.
  48. **One command, if you want the example, the documents and the worked prompts
  49. too.** This one needs the repository, so clone it first:
  50. ```bash
  51. git clone https://github.com/chowdhurylab-studio/ipro-agent
  52. cd ipro-agent
  53. bash scripts/bootstrap.sh
  54. ```
  55. That creates the environment, reports what resolved, runs the test suite and the
  56. shipped example, and prints the exact commands and MCP config with your own
  57. paths filled in. Safe to re-run; the only thing it deletes is its own
  58. `runs/bootstrap` directory, which it recreates (without that, a second run
  59. would append onto the first one's trajectory).
  60. <picture>
  61. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/chowdhurylab-studio/ipro-agent/main/docs/demo-chat-dark.gif">
  62. <img alt="A conversation: the agent resolves the positions against the right chain, shows the long-residue constraint inside the integer program, runs, and then refuses to stand behind the pore number" src="https://raw.githubusercontent.com/chowdhurylab-studio/ipro-agent/main/docs/demo-chat.gif">
  63. </picture>
  64. *What using it looks like: resolve the positions, prove the constraint reached
  65. the solver, run, and read the refusal. Reconstructed rather than recorded, from
  66. real output of the shipped example. [More worked
  67. prompts](https://github.com/chowdhurylab-studio/ipro-agent/blob/main/docs/EXAMPLE_PROMPTS.md), with what each one produces. `docs/index.html`
  68. is the same five as a page you can open or send.*
  69. By hand instead. The install step is not optional: rotamers come only from
  70. PyMOL's mutagenesis wizard, and `pymol-open-source` is conda-only, so
  71. `pip install` alone cannot give you a working design pipeline:
  72. ```bash
  73. conda env create -f environment.yml && conda activate ipro-agent
  74. ```
  75. Then check what resolved. Everything below runs from the repo root; nothing
  76. needs installing the package itself:
  77. ```bash
  78. python3 scripts/doctor.py --require pymol
  79. ```
  80. ```bash
  81. python3 -m ipro_agent validate examples/ompf_pore/spec_smoke.yaml
  82. ```
  83. ```bash
  84. python3 -m ipro_agent run examples/ompf_pore/spec_smoke.yaml --run-dir runs/smoke
  85. ```
  86. ```bash
  87. python3 -m ipro_agent status runs/smoke
  88. ```
  89. What that run produces, so you can tell a working install from a real result:
  90. with the shipped seed it accepts 3 iterations and reports zero mutations. The
  91. native residues win at those four positions because no reference-energy term
  92. offsets the packing bias against large side chains, and the run says so in its
  93. `notes`. That is a successful smoke test rather than a design. For a run that
  94. does mutate, see `examples/ompf_pore/spec_full.yaml` (25 positions,
  95. ~85 s/iteration) or set `goal_options.reference_energies`.
  96. ## For agents
  97. Clone the repo, create the conda environment above, open it with an agent and
  98. ask in plain language: "redesign this thioesterase to prefer C12 over C14, you
  99. may change residues 110, 113 and 117". The skill at
  100. [.claude/skills/ipro-agent/SKILL.md](.claude/skills/ipro-agent/SKILL.md) loads
  101. itself from its description. Beyond that one environment step there is nothing
  102. for the agent to configure; it should run `scripts/doctor.py` first and report
  103. the mode it finds.
  104. To read it yourself, it is the operating manual: goal selection, spec format,
  105. encoding user constraints into the integer program, the degraded modes, and a
  106. validation checklist to work through before reporting a design.
  107. ## Use it from another agent (MCP)
  108. The section above assumes an agent that has cloned this repo and can read
  109. `SKILL.md`. For an agent working somewhere else, or one that cannot read a repo
  110. at all, there is an MCP server. It presents the tool as fifteen typed tools
  111. rather than a manual to read:
  112. ```bash
  113. pip install ipro-agent
  114. ```
  115. ```json
  116. {"mcpServers": {"ipro-agent": {"command": "ipro-agent-mcp",
  117. "cwd": "/path/to/a/clone"}}}
  118. ```
  119. That block goes in your client's MCP config (Claude Desktop's config file,
  120. `.mcp.json` for Claude Code, Cursor's settings; the shape is shared).
  121. `bash scripts/bootstrap.sh` prints it with your own paths already filled in,
  122. which is the easier route.
  123. The MCP Registry lists the server as
  124. `io.github.chowdhurylab-studio/ipro-agent`, which is the name to give a
  125. client that installs from the registry instead of from a config block.
  126. Set `cwd` to a checkout even when you installed with pip. The documents served
  127. as resources (`ipro://skill` and the rest) ship with the repository rather than
  128. inside the package, so a server that cannot see a checkout will list them and
  129. then tell the agent where to fetch them instead of serving them. Use the conda
  130. environment's python rather than a bare `python3`: a local server sees only what
  131. its own interpreter can import, so the wrong one means PyMOL does not resolve
  132. and no design can run.
  133. | Tool | What it does |
  134. |---|---|
  135. | `ipro_doctor` | what resolved, and whether a design is possible at all |
  136. | `ipro_setup` | create the environment, when the agent has a shell and the user says so |
  137. | `ipro_fetch_structure` | download a PDB entry by id, optionally one chain; the only networked tool |
  138. | `ipro_inspect_structure` | chains, residue span, sequence, and **what residue a position number actually is** |
  139. | `ipro_goals` | the five objectives and the paper each comes from |
  140. | `ipro_validate` | check a spec before spending CPU |
  141. | `ipro_positions` | propose design positions from the structure |
  142. | `ipro_score` | measure a structure without designing |
  143. | `ipro_milp` | emit the integer program, to prove the constraints are in it |
  144. | `ipro_run` | launch a run **detached**, returns a run id |
  145. | `ipro_status` | poll it; carries the mode and the notes |
  146. | `ipro_result` | the design itself: mutations, sequence, ensemble, and the PDB on request |
  147. | `ipro_iterations` | the trajectory's tail, with the reason each iteration was rejected |
  148. | `ipro_runs` | every run this server can see, for a lost id |
  149. | `ipro_cancel` | stop a running design, keeping what it has written |
  150. `ipro_fetch_structure` and `ipro_inspect_structure` are there because a remote
  151. agent has no shell: without them "redesign OmpF, you may change residues 18,
  152. 20, 38 and 40" cannot even be started, and a position number that is never
  153. resolved against the structure silently designs a different residue than the
  154. user named. Resolve the positions and say what they are before writing a spec;
  155. `docs/EXAMPLE_PROMPTS.md` prompt 1 is that path end to end.
  156. A spec can be a file path **or** inline YAML, since an agent usually has it in
  157. context rather than on disk. `ipro_run` refuses to launch when PyMOL has not
  158. resolved, rather than starting a job that dies at the first rotamer harvest.
  159. It also serves the documents, so a remote agent is not worse informed than one
  160. that cloned the repo. Fifteen tool descriptions cannot carry the operating
  161. manual, so the manual is a resource instead:
  162. | Resource | |
  163. |---|---|
  164. | `ipro://skill` | the full operating manual: goal selection, spec format, degraded modes, validation checklist |
  165. | `ipro://house-rules` | the non-negotiables, short |
  166. | `ipro://example-spec` | an annotated spec to copy from |
  167. | `ipro://design-notes`, `ipro://milp`, `ipro://install`, `ipro://responsible-use`, `ipro://example-expectations` | provenance, the integer program, dependencies, scope of use, what the example can reproduce |
  168. There are also three prompts, which clients show as slash commands:
  169. `ipro-redesign` (walks the whole documented order for a new protein),
  170. `ipro-check-setup`, and `ipro-report` (turns a finished run into an honest
  171. report).
  172. The server can install its own dependencies. It is pure standard library, so it
  173. starts on a machine with nothing installed, which is the only way it can report
  174. that nothing is installed. `ipro_doctor` names what is missing and `ipro_setup`
  175. reports the exact command; with `confirm=true` it runs the conda install itself.
  176. Measured in an empty virtualenv: the server starts, reports
  177. `missing_required: ['numpy', 'Bio', 'yaml']`, finds mamba, and hands back the
  178. command without installing anything.
  179. One limit remains. It is a local server, so the environment it installs has to
  180. be the one the server itself runs in: after `ipro_setup` finishes, point your
  181. MCP config at that environment's python
  182. (`.../envs/ipro-agent/bin/python -m ipro_agent.mcp_server`), or PyMOL still
  183. will not resolve. `ipro_setup` says so in its result.
  184. ## Documentation
  185. | File | Contents |
  186. |---|---|
  187. | [.claude/skills/ipro-agent/SKILL.md](.claude/skills/ipro-agent/SKILL.md) | how an agent drives this tool (auto-loaded) |
  188. | [docs/DESIGN.md](https://github.com/chowdhurylab-studio/ipro-agent/blob/main/docs/DESIGN.md) | every capability traced to its paper and equation, and every deviation |
  189. | [docs/MILP.md](https://github.com/chowdhurylab-studio/ipro-agent/blob/main/docs/MILP.md) | the integer program in full |
  190. | [docs/INSTALL.md](https://github.com/chowdhurylab-studio/ipro-agent/blob/main/docs/INSTALL.md) | dependencies and what each one unlocks |
  191. | [examples/ompf_pore/](examples/ompf_pore/) | worked case, with an `EXPECTED.md` of what can and cannot be compared |
  192. | [docs/EXAMPLE_PROMPTS.md](https://github.com/chowdhurylab-studio/ipro-agent/blob/main/docs/EXAMPLE_PROMPTS.md) | five prompts to paste at an agent, and what each actually produces |
  193. | [docs/HANDOFF.md](https://github.com/chowdhurylab-studio/ipro-agent/blob/main/docs/HANDOFF.md) | passing this to a labmate, a student or your future self |
  194. ## Dependencies
  195. Required: Python ≥ 3.10, numpy, Biopython, PyYAML, and PyMOL, which has
  196. no fallback. Rotamers come only from its mutagenesis wizard; there is no
  197. built-in rotamer builder, and `backends.mutate: builtin` is refused by the config.
  198. Without it `validate`, `positions` and `goals` work; `milp`, `score` and `run`
  199. do not, because all three build rotamer tables and rotamers come only from
  200. PyMOL. Measured on a machine with no PyMOL discoverable: `validate` and `goals`
  201. exit 0, `milp` and `score` refuse with "backend missing: no PyMOL available". `conda env create -f environment.yml` installs all
  202. five.
  203. Genuinely optional, each resolved at run time with a documented fallback:
  204. | Tool | Used for | Without it |
  205. |---|---|---|
  206. | PyRosetta | backbone relaxation, scoring | loop runs `fixed-backbone`; energies come from a screening function |
  207. | AutoDock Vina | re-docking partners after mutation | input poses are kept |
  208. | MILP solver (CPLEX, Gurobi, CBC, HiGHS, GLPK) | proving the optimal packing | a heuristic that does not prove optimality |
  209. `scripts/doctor.py` reports what resolved and what a run will actually use. It
  210. also refuses an interpreter below the floor: on Python 3.9 with every
  211. dependency installed it reports `can_run: false` and exits 1, because
  212. `import ipro_agent` fails there whatever else is present.
  213. Platforms: developed and tested on macOS (Apple silicon), and used on Linux.
  214. Windows is untested. The detached-run path has a Windows branch and the
  215. interpreter search looks in `Scripts/python.exe` and `%USERPROFILE%`, but
  216. nothing here has ever run on Windows, PyMOL's conda package is the only
  217. supported route to it, and a few paths assume a POSIX shell. On Windows use WSL
  218. 2, where the Linux instructions apply unchanged.
  219. ## Status and honesty
  220. This is research code and an independent reimplementation. It was written from
  221. the published formulations; the released upstream source was read for behaviour
  222. the papers leave ambiguous, and every value taken from it is cited as such in
  223. `docs/DESIGN.md` §2 and `docs/MILP.md`. No upstream IPRO code is copied. It
  224. substitutes an open stack for the original's CHARMM, GAMS/CPLEX and in-house
  225. Monte-Carlo docking, so energies are not comparable to the numbers in the IPRO
  226. papers, and identical designs should not be expected.
  227. What it has actually been run on: every end-to-end run in this repo has been on
  228. one chain of PDB 2OMF, with 1CRN as a test fixture. No other protein has been
  229. tried here, and no design from this code has been synthesised or tested
  230. experimentally. The checks listed below are self-consistency checks of the
  231. optimizer rather than validation against experiment.
  232. What has been verified here: the MILP reproduces exhaustive enumeration exactly
  233. on a test case (including with a class-cardinality constraint), the integer cuts
  234. provably prevent revisiting a sequence, and the Metropolis temperature
  235. reproduces IPRO's published calibration. The PyRosetta and AutoDock Vina paths
  236. have now been executed. Both were installed deliberately to do so, and between
  237. them that found seven defects, because neither path had ever run
  238. (`docs/DESIGN.md` §7e). What remains unexercised is listed in
  239. `ipro_agent/energy/pyrosetta_backend.UNEXERCISED`, which a test keeps honest.
  240. One known defect is open, and it can produce a wrong answer that looks right.
  241. The channel axis is fitted through the centroid of the design positions, so it
  242. only follows the channel when those positions *ring* the lumen. When they do
  243. not, as with four positions along one wall in the shipped smoke example, the
  244. axis runs inside the protein and the reported "bottleneck" is a gap beside a
  245. wall, which then passes PoreDesigner's published sub-4 Å filter. The run says
  246. so in its notes and reports the axis clearance, but any pore radius from a spec
  247. whose positions do not surround the channel must be treated as meaningless;
  248. give `goal_options.pore_axis` explicitly instead. `docs/DESIGN.md` §7h has the
  249. measurements, and why the clearance has to be measured on the input structure
  250. rather than on a candidate.
  251. Objectives of this kind reproduce the rank and sign of a change far better than
  252. its magnitude; published hit rates for this family of methods are roughly
  253. 24–43%. Every design is a hypothesis for the bench.
  254. ## Responsible use
  255. This is a research tool that proposes mutations. It does not know what it is
  256. being pointed at, and a coding agent driving it knows even less.
  257. - Research use, on targets you are authorised to work on. Every design is a
  258. hypothesis for the bench rather than a validated construct; published hit
  259. rates for this family of methods are roughly 24–43%.
  260. - Some targets need a human in the loop before anything is run, not after the
  261. result arrives: toxins, virulence factors and select agents; anything
  262. intended to change host range, transmissibility, immune escape or drug
  263. resistance; and any sequence heading for synthesis. If the goal is to make a
  264. protein *better at harming*, that is not a use this repo supports.
  265. - An agent must not relax the user's stated constraints to make a failing run
  266. succeed. The troubleshooting tables offer knobs (widen `allowed`, loosen a
  267. catalytic-distance restraint, raise `max_self_energy`) and every one of them
  268. changes the scientific question. Report the change; do not absorb it.
  269. - Report the mode and the notes with every design, a house rule in `AGENTS.md`.
  270. A run in a degraded mode, or one where nothing was accepted, is not a design
  271. and must not be presented as one.
  272. - Screening energies from the built-in backend are not kcal/mol comparable to
  273. the papers, and no design from this code has been tested experimentally.
  274. ## Citing
  275. For the implementation, cite this repository. `CITATION.cff` carries the
  276. metadata, and GitHub's "Cite this repository" button renders it.
  277. For the method, cite the original work. `docs/DESIGN.md` has the full list
  278. with DOIs; the main entries are:
  279. - IPRO: Saraf, Moore, Goodey, Cao, Benkovic, Maranas. *Biophys J* **90**:4167 (2006).
  280. - The IPRO suite: Pantazes, Grisewood, Li, Gifford, Maranas. *J Comput Chem* **36**:251 (2015).
  281. - PoreDesigner: Chowdhury et al. *Nat Commun* **9**:3661 (2018).
  282. - IPRO+/−, insertions and deletions: Chowdhury et al. *Structure* **28**:1344 (2020).
  283. - Specificity redesign: Grisewood et al. *ACS Catal* **7**:3837 (2017).
  284. - OptZyme: Grisewood et al. *PLoS ONE* **8**:e75358 (2013).
  285. ## Licence
  286. **MIT**: see [`LICENSE`](LICENSE), with the scope spelled out in [`NOTICE.md`](NOTICE.md).
  287. That covers *this implementation only*: the code, tests and documentation
  288. written here. Three things in this tree are deliberately **not** covered, and
  289. the licence file says so in its own words:
  290. | | |
  291. |---|---|
  292. | **The method** | Not ours and not licensed by us. Cite the papers above for the method and this repo only for the implementation. |
  293. | **`refs/`** | Publisher PDFs and clones of upstream repositories, kept locally for provenance and git-ignored: they are not in this repository and are not redistributed. |
  294. | **Optional dependencies** | PyMOL, AutoDock Vina, Open Babel, PyRosetta and any MILP solver are separately licensed and separately installed. **PyRosetta requires its own licence**; see [`docs/INSTALL.md`](https://github.com/chowdhurylab-studio/ipro-agent/blob/main/docs/INSTALL.md). |
  295. No upstream IPRO code is copied here. That is what makes publishing this
  296. defensible: the upstream releases carry no `LICENSE` file at all, and the
  297. Maranas group's pages describe the suite as freely available to academic users.
  298. This is an independent reimplementation rather than a fork, written from the
  299. papers, with the released source read only for behaviour the papers leave
  300. ambiguous (chiefly a handful of numeric defaults); every such value is cited as
  301. coming from the source in `docs/DESIGN.md` §2 and `docs/MILP.md`.
  302. `docs/DESIGN.md` §6 maps every capability back to the paper and equation it came
  303. from, so the provenance of each piece is checkable.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.