convez.ai
AgenteAutomaçãoAvançado
jvogan

Proteus — Biologia Estrutural para Agentes de IA

jvogan/proteus

Análise de proteínas para agentes de IA com PyMOL, ChimeraX e AlphaFold

Ver no GitHub
BomPluginScore · de 0 a 100

Agent skill que capacita agentes de código em IA (Claude, Codex) para análise de estruturas proteicas via terminal, integrando PyMOL, ChimeraX, AlphaFold DB, RCSB PDB, UniProt e workflows Rosetta. Resolve proteínas, busca estruturas, renderiza figuras e automatiza análises sem instalar plugins customizados.

Instalação

$npx convez-ai jvogan/proteus

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
31
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 4 meses
Versão
v0.1.0
Issues abertas
1
Contribuidores
1

Casos de uso

  • Automação de renderização PyMOL e análise ChimeraX para biólogos computacionais
  • Pipelines de design de proteínas com validação Rosetta e inspecção de confiança AlphaFold
  • Geração de figuras de bolsas de ligação e análises de interface proteína-proteína
  • Workflows cryo-EM com ajuste de densidade e renderização headless

Veredito

Ferramenta niche e profunda para biólogos estruturais e engenheiros de proteínas que usam agentes de IA. Documentação excelente de gotchas reais (PyMOL, ChimeraX, AlphaFold), zero dependências para operações básicas e saída JSON para encadeamento. Requer domínio técnico em biologia estrutural e CLI.

README

A tradução para o português deste README ainda está na fila.

Proteus

License: MIT Python 3.10+ CI

Structural biology superpowers for AI coding agents.

Proteus is a structural biology agent skill and stdlib-only helper toolkit for Codex, Claude Code, and other AI coding agents. It teaches agents how to do AI protein structure analysis from the terminal: resolve proteins, fetch structures, inspect AlphaFold confidence, render PyMOL figures, automate ChimeraX analysis, compare models, validate experimental structures, and reason about protein design tooling.

Proteus is for computational biologists, protein engineers, educators, and agent builders who want reliable PyMOL automation, ChimeraX automation, AlphaFold DB / pLDDT / PAE workflows, RCSB PDB and UniProt helpers, and Rosetta-oriented protein design guidance without building a custom plugin.

What is a skill? A skill is a directory that an AI coding agent reads to gain domain-specific knowledge. Clone it into the agent's skills folder and it becomes part of the agent's working context — no code changes or plugin installs required.

Why Proteus?

  • Turns vague protein prompts into reproducible workflows. TP53, P04637, 4HHB, and local .pdb / .cif files become local structures with provenance.
  • Keeps agents out of known tool traps. Proteus documents hard-won PyMOL, ChimeraX, and AlphaFold DB gotchas that otherwise waste hours.
  • Works even before heavy tools are installed. Zero-dependency scripts inspect PDB/mmCIF files, query public APIs, and emit structured JSON.
  • Scales up when PyMOL or ChimeraX are available. Agents can render publication-quality PyMOL images or run ChimeraX SASA, H-bond, alignment, and cryo-EM workflows.
  • Produces outputs agents can chain. Reports use machine-readable JSON for parallel runs, CI checks, notebooks, and downstream analysis.

What It Provides

  • 23 documented gotchas for PyMOL, ChimeraX, AlphaFold DB, rendering, and cryo-EM maps — hard-won from real debugging
  • Tool detection for PyMOL, ChimeraX, and ffmpeg across macOS and Linux installs
  • Headless PyMOL rendering for publication-quality structure figures, with publication/illustration/soft presets and pLDDT coloring
  • One-command annotated binding-pocket figures (ligand + pocket sticks + polar contacts + transparent context)
  • Headless turntable movies (PyMOL ray-traced frames + ffmpeg), degrading gracefully when ffmpeg is absent
  • Managed ChimeraX REST rendering — launches a GUI session, renders via GPU, defeats the 0-byte-PNG save race, and tears down cleanly
  • ChimeraX analysis helpers for alignment, SASA, and hydrogen-bond workflows
  • Zero-dependency protein-protein interface residue analysis between chains
  • HELIX-record injection for CA-only backbones (RFdiffusion / Genie designs) so cartoons render correctly
  • MRC/CCP4 map inspection with sigma-based contour-level suggestions
  • Cryo-EM density-fit figures (model in carved density mesh; works with a real map or simulated density)
  • AlphaFold DB fetch with confidence interpretation and pLDDT coloring
  • RCSB PDB fetch for experimental coordinates, metadata, and biological assembly mmCIF
  • UniProt lookup for resolving gene/protein names before AlphaFold fetches
  • PDB/mmCIF inspection via structure_info.py
  • One-command readiness checks via proteus_doctor.py
  • Query resolution via resolve_structure.py for local files, PDB IDs, UniProt accessions, and gene/protein names
  • PAE, validation, ligand-pocket, and structure-comparison reports
  • Rosetta/PyRosetta patterns plus ML alternatives (ProteinMPNN, ESM2)
  • Zero-dependency PDB file inspector (pdb_info.py — stdlib only)
  • Structured JSON output from all helper scripts, safe for parallel agent runs

Agent Prompts That Work

Use prompts like these with $proteus or after installing this directory as an agent skill:

Use Proteus to resolve TP53, fetch the AlphaFold prediction, and summarize low-confidence regions.
Render the 1HSG binding pocket around indinavir in PyMOL and save a clean PNG.
Compare AF-P04637-F1 against an experimental p53 structure and report RMSD plus high-deviation residues.
Run a ChimeraX hydrogen-bond and SASA analysis for this protein-protein interface.
Check whether 4HHB has validation red flags before using it as a reference structure.

Capabilities Matrix

CapabilityNo local toolsPyMOLChimeraXPublic APIsRosetta/PyRosetta
PDB/mmCIF inspectionyesoptionaloptionalnono
Protein/name resolutionyesnonoUniProtno
Experimental structure fetchyesnonoRCSB PDBno
AlphaFold confidence, pLDDT, PAEyesrender optionaloptionalAlphaFold DBno
Headless structure renderingnoyeslimitednono
SASA, H-bonds, contacts, alignmentpartialpartialyesnooptional
Protein design/scoring guidancedocsoptionaloptionaloptionalyes

Generated Outputs

Small, checked-in snapshots show the JSON shape without requiring downloads:

The repository also includes a curated social preview image at assets/social-preview.jpg. The larger generated banner gallery stays ignored to keep the public repository lean.

Try It In 60 Seconds

git clone https://github.com/jvogan/proteus.git
cd proteus
make test
python3 scripts/proteus_doctor.py --json
python3 scripts/resolve_structure.py TP53 --no-download --json
python3 scripts/pocket_report.py tests/fixtures/tiny.pdb --json

These commands require only Python 3.10+. Install PyMOL or ChimeraX later when you want rendering, SASA, hydrogen bonds, structure alignment, or live molecular visualization.

Install

Clone into your agent's skills directory:

# Claude Code
git clone https://github.com/jvogan/proteus.git ~/.claude/skills/proteus

# Codex
git clone https://github.com/jvogan/proteus.git ~/.codex/skills/proteus

Or copy the directory manually into your agent's skills folder. The skill path may vary by agent version — check your agent's documentation if the above doesn't work.

Runtime requirements

Proteus degrades gracefully — pdb_info.py and AlphaFold metadata fetches work with zero local tools. For full capability, install at least one:

ToolRoleInstall
PyMOLHeadless rendering, structure inspectionpymol.org or conda install -c conda-forge pymol-open-source
ChimeraXAnalysis, GUI demos, cryo-EM visualizationcgl.ucsf.edu/chimerax
AlphaFold DBPublic prediction databaseNo install — uses the EBI REST API
PyRosettaScoring, energy minimization, protein designpip install pyrosetta-installer (academic license required)

Python 3.10+ is required. All helper scripts use only the standard library.

Quick examples

With the skill installed, natural-language prompts trigger it automatically:

Fetch the AlphaFold prediction for p53 and show which regions look disordered.
Render the 1HSG binding pocket in PyMOL and save a clean PNG.
Compare an AlphaFold model to an experimental structure and report RMSD.
Analyze the hydrogen bonds at a protein-protein interface in ChimeraX.

The helper scripts also work standalone:

python3 scripts/pdb_info.py structure.pdb                          # zero-dep PDB inspection
python3 scripts/structure_info.py structure.cif --json             # PDB/mmCIF inspection
python3 scripts/fetch_pdb.py 4HHB --json                           # RCSB PDB fetch
python3 scripts/uniprot_lookup.py TP53 --gene-exact --json         # UniProt lookup
python3 scripts/fetch_alphafold.py P04637 --pae --json             # AlphaFold fetch
python3 scripts/pae_report.py AF-P04637-F1_pae.json --json         # PAE/domain hints
python3 scripts/validation_report.py 4HHB --json                   # wwPDB validation metrics
python3 scripts/pocket_report.py 1HSG --json                       # ligand-pocket contacts
python3 scripts/interface_report.py 1BRS --chains A,D --json        # protein-protein interface residues
python3 scripts/resolve_structure.py TP53 --json                   # one-command resolver
python3 scripts/pymol_agent.py render structure.pdb output.png     # headless render
python3 scripts/pymol_agent.py pocket 1HSG.pdb pocket.png --label  # annotated binding-pocket figure
python3 scripts/pymol_agent.py spin structure.pdb spin.mp4         # turntable movie (needs ffmpeg)
python3 scripts/chimerax_agent.py align reference.pdb mobile.pdb   # structure alignment
python3 scripts/chimerax_rest.py render structure.pdb out.png      # GPU render via managed REST
python3 scripts/add_helix_records.py model.pdb --json              # fix CA-only backbone cartoons
python3 scripts/map_info.py map.mrc --json                         # cryo-EM contour levels
python3 scripts/pymol_agent.py density model.pdb fit.png --simulate # model in (simulated) density

See SHOWCASE.md for end-to-end, copy-pasteable examples on canonical public structures (HIV protease, ACE2–RBD, hemoglobin, AlphaFold p53, and more).

Layout

proteus/
├── SKILL.md              # Main skill — agent reads this first
├── agents/openai.yaml    # Codex discovery metadata
├── references/           # On-demand deep docs (loaded as needed)
│   ├── alphafold.md
│   ├── chimerax.md
│   ├── data-sources.md
│   ├── file-formats.md
│   ├── prediction-models.md
│   ├── pymol.md
│   └── rosetta.md
└── scripts/              # Agent helper scripts (all stdlib-only)
    ├── add_helix_records.py
    ├── chimerax_agent.py
    ├── chimerax_rest.py
    ├── compare_structures.py
    ├── fetch_pdb.py
    ├── fetch_alphafold.py
    ├── interface_report.py
    ├── map_info.py
    ├── pae_report.py
    ├── pdb_info.py
    ├── pocket_report.py
    ├── proteus_doctor.py
    ├── resolve_structure.py
    ├── structure_info.py
    ├── uniprot_lookup.py
    ├── validation_report.py
    └── pymol_agent.py

Design intent

The tool split is deliberate:

  • PyMOL is the default for headless image generation (software ray tracer — no display needed).
  • ChimeraX is the default for analysis-heavy workflows and GPU-rendered GUI sessions.
  • RCSB/UniProt/AlphaFold DB provide lightweight upstream data discovery before local visualization.
  • Rosetta/PyRosetta are optional extensions. ML alternatives (ProteinMPNN, ESM2) are documented for when Rosetta isn't available.

Helper scripts emit machine-readable JSON, with human-readable text as a fallback. Temporary handoff files are per-process, so parallel agent runs never collide.

Test

make test            # run the unit tests
make release-check   # pre-publish hygiene sweep (no tracked structures/maps/media/secrets, no large files)

Safety And Privacy

Proteus does not include telemetry or credential collection. Some workflows call public APIs with user-provided protein names, UniProt accessions, or PDB IDs. Read PRIVACY.md, SECURITY.md, and DISCLAIMER.md before using Proteus with private structures, unpublished sequences, or regulated data.

Contributing

Found a gotcha that isn't documented? Have a workflow that should be covered? Open an issue or submit a PR. The most valuable contributions are real debugging discoveries — the kind of thing that takes hours to figure out and one sentence to explain. See CONTRIBUTING.md.

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados