Skip to content

README.md

Latest commit

 

History

History
257 lines (188 loc) · 7.99 KB

README.md

File metadata and controls

257 lines (188 loc) · 7.99 KB
Raw

ProtForge

中文版本 | English

A unified, extensible agent framework for protein design tools.

ProtForge is an Agent Skills package and Python framework that lets AI agents discover, configure, run, and chain external protein-design tools through one standardized interface. It is designed for agent harnesses such as pi, Claude Code, OpenAI Codex, and similar systems.

Important: This repository ships the framework, workflow templates, and a tool-integration template only. It does not include built-in AlphaFold, ProteinMPNN, RFdiffusion, ColabFold, or other third-party tool integrations. Add tool modules under tools/ before running real protein-design workflows.

What ProtForge Provides

  • Agent-native operations — list tools, inspect schemas, configure paths, run tools, and execute pipelines through structured dictionaries suitable for LLM agents.
  • Unified data model — ToolInput / ToolOutput for sequences, structures, MSAs, files, metadata, parameters, and timeouts; optional Artifact wrappers for richer provenance.
  • Safe pipeline orchestration — each step receives only its own parameters, skipped steps do not leak state, and FASTA/PDB/MSA-style outputs are carried forward.
  • Schema-validated configuration — tool configuration values are validated/coerced before being persisted to ~/.protforge/config.json.
  • Private tool discovery — project tools are loaded under a private namespace so unrelated Python packages named tools cannot shadow integrations.
  • CLI and Python API — use protforge ... from a shell or import the framework directly.
  • Starter workflow templates — JSON examples for structure prediction, sequence redesign, and binder design.

Quick Start

1. Install for local Python / CLI use

cd /path/to/ProtForge
python -m pip install -e .

Optional extras:

python -m pip install -e '.[test]'   # pytest support
python -m pip install -e '.[yaml]'   # YAML pipeline support

2. Initialize and verify

python scripts/setup.py
protforge list-tools
protforge validate

A fresh checkout should report no registered tools:

0/0 tools ready to use

That is expected until you add real integrations under tools/.

3. Use as an Agent Skill

Copy or symlink this repository into your agent's skills directory:

# Claude Code
cp -r ProtForge ~/.claude/skills/

# OpenAI Codex
cp -r ProtForge ~/.codex/skills/

Then ask the agent to list tools, configure a tool path, or run a workflow. The agent should collect missing installation paths from you and call ProtForge through AgentInterface.

Command Line Usage

protforge list-tools
protforge validate
protforge tool-info alphafold
protforge configure alphafold --set executable_path=/opt/alphafold/run_alphafold.py
protforge run alphafold --sequences '{"A":"MTEYKLVVV"}' --parameters '{"num_recycles":3}'
protforge pipeline workflows/structure_prediction.json --sequences '{"A":"MTEYKLVVV"}'
protforge pipeline workflows/binder_design.json --structures '{"target":"1abc.pdb"}'

Pipeline files are JSON by default. YAML files are supported when PyYAML is installed via the yaml extra.

Python API Example

from protforge import AgentInterface, ConfigManager, Pipeline, PipelineStep, ToolInput, ToolRegistry

cfg = ConfigManager()
registry = ToolRegistry(cfg)

tool = registry.get_tool("alphafold")
if tool is None:
    raise RuntimeError("Add tools/alphafold.py before using this example")

cfg.set_tool_config(
    "alphafold",
    {"executable_path": "/opt/alphafold/run_alphafold.py"},
    schema=tool._config_schema,
    validate_required=True,
    coerce=True,
)

# Run one tool directly after refreshing its config.
tool = registry.get_tool("alphafold")
output = tool.run(ToolInput(
    sequences={"A": "MTEYKLVVV..."},
    parameters={"num_recycles": 3},
))

# Or run a multi-step pipeline.
pipeline = Pipeline([
    PipelineStep("rfdiffusion", {"num_designs": 10}),
    PipelineStep("proteinmpnn", {"sampling_temp": 0.1}),
    PipelineStep("alphafold", {"num_recycles": 3}),
])
result = pipeline.run(ToolInput(structures={"target": "1abc.pdb"}))

# Agent-facing API returns structured dictionaries.
agent = AgentInterface(cfg)
agent_result = agent.run_pipeline(
    [{"tool_name": "alphafold", "parameters": {"num_recycles": 3}}],
    initial_sequences={"A": "MTEYKLVVV..."},
)

Workflow Templates

The workflows/ directory contains loadable JSON templates:

File Purpose Expected integrations
workflows/structure_prediction.json Predict structure from sequence AlphaFold/ColabFold-style tool
workflows/sequence_redesign.json Design sequences for a backbone ProteinMPNN-style tool
workflows/binder_design.json RFdiffusion → ProteinMPNN → AlphaFold-style binder workflow RFdiffusion, ProteinMPNN, AlphaFold/ColabFold

These templates can be loaded before tools exist; execution will return a structured “tool not found/configured” error until integrations are added.

Adding a New Tool

  1. Copy the template:

    cp tools/_template.py tools/<your_tool>.py

  2. Fill in metadata:

    • _tool_name
    • _tool_version
    • _tool_category
    • _input_types
    • _output_types
    • _config_schema

  3. Implement:

    • validate_config()
    • run(tool_input)
    • any input preparation/output parsing helpers

  4. Uncomment or add @register_tool on the customized class.

  5. Verify discovery:

    protforge list-tools

See references/DEV-GUIDE.md for a full walkthrough.

Project Structure

ProtForge/
├── SKILL.md                  # Agent Skills entry point
├── pyproject.toml            # Package metadata, extras, CLI entry point
├── protforge/                # Core framework
│   ├── agent.py              # AgentInterface
│   ├── artifacts.py          # Artifact / ArtifactType
│   ├── backends.py           # Execution backend abstraction
│   ├── base.py               # ToolBase, ToolInput, ToolOutput, ToolStatus
│   ├── cli.py                # Command-line interface
│   ├── config.py             # ConfigManager + schema validation
│   ├── executor.py           # Synchronous/lightweight async pipeline executor
│   ├── jobs.py               # JobRecord / JobStore provenance records
│   ├── pipeline.py           # Pipeline + DataTransformer
│   ├── registry.py           # @register_tool + private tool discovery
│   ├── reporting.py          # Markdown report helpers
│   ├── runner.py             # Shared subprocess runner
│   └── specs.py              # PipelineSpec helper
├── tools/                    # User-added tool integrations
│   └── _template.py          # Copy/customize to add a tool
├── workflows/                # Starter JSON workflow templates
├── scripts/                  # Setup/verification helpers
├── tests/                    # Core framework tests
└── references/               # Architecture, API, and developer docs

Configuration

Configuration is stored at ~/.protforge/config.json:

{
  "tools": {
    "alphafold": {
      "executable_path": "/opt/alphafold/run_alphafold.py",
      "conda_env": "alphafold",
      "num_threads": 8
    }
  },
  "global": {
    "default_timeout": 3600,
    "temp_dir": "/tmp/protforge"
  }
}

Testing

Default validation uses the standard library unittest and does not require external protein-design tools:

python -m unittest discover -v
python -m py_compile protforge/*.py tools/_template.py scripts/*.py tests/test_framework.py

If you install the test extra, you can also run:

python -m pytest

Requirements

  • Python 3.9+
  • External protein-design tools installed separately by the user

License

MIT