Magician — Designer Plugin System¶
This page documents the Magician gimmick orchestration system, the plugin registry that discovers designer/scorer subclasses, and the two concrete built-in designers.
Overview¶
The Magician system manages third-party design and scoring tools ("gimmicks") through a singleton-driven lifecycle. Plugins are auto-discovered at import time via a PluginRegistry that scans the REvoDesign.magician.designers package for non-abstract subclasses of ExternalDesignerAbstract.
Plugin Discovery Mechanism¶
The registry is created in REvoDesign.magician:
DESIGNER_REGISTRY = build_plugin_registry(
base_class=ExternalDesignerAbstract,
package="REvoDesign.magician.designers",
)
At module load time, PluginRegistry.__post_init__ calls _discover_classes(), which:
- Imports all modules under
REvoDesign.magician.designers(including subpackages likeopenkinetics/). - Scans every module for non-abstract subclasses of
ExternalDesignerAbstract. - Indexes them by their
.nameattribute, rejecting duplicates. - Exposes the results through
all_classes,implemented_map, andinstalled_names.
The designers/__init__.py explicitly imports each known designer module to trigger class creation and also re-exports its top-level symbols. The OpenKinetics subpackage additionally uses a _SCORER_SPECS loop with type() to generate dynamic scorer subclasses at import time.
Registry and Discovery¶
REvoDesign.magician.DESIGNER_REGISTRY = build_plugin_registry(base_class=ExternalDesignerAbstract, package='REvoDesign.magician.designers')
module-attribute
¶
REvoDesign.magician.ALL_DESIGNER_CLASSES = list(DESIGNER_REGISTRY.all_classes)
module-attribute
¶
REvoDesign.magician.IMPLEMENTED_DESIGNERS = DESIGNER_REGISTRY.implemented_map
module-attribute
¶
Magician¶
REvoDesign.magician.Magician
¶
Bases: SingletonAbstract
The Magician class inherits from SingletonAbstract, ensuring that there is only one instance of Magician. This class is responsible for setting up and managing the magician's gimmicks, including initializing and cooling down gimmicks based on different configurations.
singleton_init()
¶
Initializes the Magician instance, including setting up the configuration bus, initializing the gimmick, and creating an instance of the assistant.
setup(name_badget_id='', name_cfg_term='', gimmick_name='', **kwargs)
¶
Sets up the magician's gimmick based on different methods.
Parameters: - name_badget_id: Optional[str] - The ID badge for obtaining the name. - name_cfg_term: Optional[str] - The configuration term for obtaining the name. - gimmick_name: Optional[str] - The directly provided name of the gimmick. - **kwargs: Additional parameters for setting up the gimmick.
Returns: - Magician: Returns the instance of the Magician for method chaining.
MagicianAssistant¶
REvoDesign.magician.MagicianAssistant
dataclass
¶
A class to manage the installation and usage of external design tools.
PluginRegistry¶
REvoDesign.basic.plugin_registry.PluginRegistry
dataclass
¶
Bases: Generic[PluginT]
Package-scoped plugin registry.
Discovery is performed during initialization by importing all modules
under package and collecting subclasses of base_class.
Built-in Designers¶
ColabDesigner_MPNN¶
The ColabDesigner_MPNN class wraps ProteinMPNN (via the ColabDesign package) for sequence design and scoring.
REvoDesign.magician.designers.colabdesign.ColabDesigner_MPNN
¶
Bases: ExternalDesignerAbstract
initialize(*args, **kwargs)
¶
Initialize the ColabDesigner_MPNN class.
Args: - molecule: Molecule for design.
Notes: - Initializes attributes required for the ColabDesigner_MPNN class.
preffer_substitutions(aa='')
¶
Set preferred substitutions for the model.
Args: - aa: Amino acids for preferred substitutions.
Notes: - Modifies model inputs to set preferred substitutions.
scorer(mutant, **kwargs)
¶
Compute the score for a given sequence.
Args: - mutant: Mutant object.
Returns: - float: Score value for the given mutant sequence.
Notes: - Computes the score using the MPNN model.
designer(*args, **kwargs)
¶
Run the designer to obtain design results.
Args: - args: Variable length argument list. - *kwargs: Arbitrary keyword arguments.
Returns: - dict: Dictionary containing sequences and scores.
Notes: - Executes the designer to obtain sequence and score iterables.
Cartesian-ddG (ddg)¶
The ddg class wraps RosettaPy's Cartesian-ddG module for mutation stability scoring.
REvoDesign.magician.designers.cart_ddg.ddg
¶
Bases: ExternalDesignerAbstract