schrodinger.application.bunsen.maestro_tools module

Maestro tool provider for Bunsen.

Provides tools that let Bunsen interact with the Maestro application running on the user’s machine. Connect with:

pythonrun schrodinger.application.bunsen.maestro_tools connect <url> <session_id>

class schrodinger.application.bunsen.maestro_tools.SendStructuresTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'send_structures'

DESCRIPTION: str = 'Import structures into the Maestro project table.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='filename', type='file', description='Structure file to import'), ToolParam(name='group', type='string', description="Optional group path to place imported entries into. Use ' / ' to specify nested groups, e.g. 'Docking Results / Pose 1'."))

main(filename: str, group: str = '')

Import structures and optionally group them.

Parameters:

• filename – Path to the structure file.

• group – If provided, all imported entries are placed into this group hierarchy (created if it doesn’t exist). Use " / " to nest groups.

class schrodinger.application.bunsen.maestro_tools.MoveToGroupTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'move_to_group'

DESCRIPTION: str = 'Move entries in the Maestro project table to a group. The group is created if it does not already exist.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='entry_ids', type='list[string]', description='List of Maestro entry IDs to move.'), ToolParam(name='group_path', type='string', description="Title path of the target group, using ' / ' for nesting, e.g. 'Docking Results / Pose 1'. Groups are created as needed."))

main(entry_ids: list[str], group_path: str)

Move project-table entries into a group.

Parameters:

• entry_ids – Entry IDs to move.

• group_path – Title path of the target group, using " / " for nesting. Groups are created as needed.

class schrodinger.application.bunsen.maestro_tools.GetStructuresTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'get_structures'

DESCRIPTION: str = 'Export structures from the Maestro project table.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='entry_ids', type='list[string]', description='List of Maestro entry IDs to export'), ToolParam(name='format', type='string', description="Output format: 'mae', 'maegz', 'sdf', 'csv'. Defaults to 'mae'."))

RESPONSE_FILES: tuple[str, ...] = ('filename',)

main(entry_ids: list[str], format: str = 'mae')

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.IncludeEntriesTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'include_entries'

DESCRIPTION: str = 'Set which entries to include in the Maestro workspace.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='entry_ids', type='list[string]', description='List of Maestro entry IDs to include'), ToolParam(name='include_only', type='boolean', description='Whether to include only the specified entries and exclude all others from the session. Defaults to true.'))

main(entry_ids: list[str], include_only: bool = True)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.SelectEntriesTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'select_entries'

DESCRIPTION: str = "Select rows in the Maestro project table. This controls which rows are *highlighted* in the project table, not which structures are included in the workspace (use include_entries for that). Supported modes: 'replace' — replace the current selection with the given entry IDs; 'add' — add the given entry IDs to the current selection; 'invert' — invert the current selection (no entry_ids); 'all' — select all rows (no entry_ids); 'none' — deselect all rows (no entry_ids). Default mode is 'replace'."

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='mode', type='string', description="Selection mode: 'replace', 'add', 'invert', 'all', or 'none'. Defaults to 'replace'."), ToolParam(name='entry_ids', type='list[string]', description="Entry IDs to select. Use for 'replace' or 'add'. Must be omitted or empty for 'invert', 'all', and 'none'. Mutually exclusive with positions."), ToolParam(name='positions', type='list[integer]', description="1-based row ordinals to select, e.g. [1, 2, 3] to select the first three rows. Use for 'replace' or 'add'. Mutually exclusive with entry_ids."))

main(mode: str = 'replace', entry_ids: list[str] | None = None, positions: list[int] | None = None)

Select rows in the Maestro project table.

Parameters:

• mode – Selection mode — "replace", "add", "invert", "all", or "none".

• entry_ids – Entry IDs to select. Required for "replace" and "add" unless positions is given; must be absent or empty for "invert", "all", and "none".

• positions – 1-based row ordinals to select, resolved against the current row order. Mutually exclusive with entry_ids.

Raises:

ValueError – If mode is not recognised, or if entry_ids / positions and mode are incompatible.

class schrodinger.application.bunsen.maestro_tools.RemoveEntriesTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'remove_entries'

DESCRIPTION: str = 'Remove entries from the Maestro project table.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='entry_ids', type='list[string]', description='List of Maestro entry IDs to remove'),)

main(entry_ids: list[str])

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.ReplaceStructuresTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'replace_structures'

DESCRIPTION: str = 'Replace structures in the Maestro project table with new ones.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='entry_ids', type='list[string]', description='List of Maestro entry IDs to replace'), ToolParam(name='filename', type='file', description='Structure file with replacement structures'))

main(entry_ids: list[str], filename: str)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.GetSelectedStructuresTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'get_selected_structures'

DESCRIPTION: str = 'Export the currently selected structures from the Maestro project table.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='format', type='string', description="Output format: 'mae', 'maegz', 'sdf', 'csv'. Defaults to 'mae'."),)

RESPONSE_FILES: tuple[str, ...] = ('filename',)

main(format: str = 'mae')

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.SendSequencesTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'send_sequences'

DESCRIPTION: str = 'Import sequences into the Maestro Multiple Sequence Viewer (MSV). Opens the MSV panel if not already open.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='filename', type='file', description='Sequence file to import (e.g. FASTA format)'),)

main(filename: str)

Import sequences from a file into MSV.

Parameters:

filename – Local path to the sequence file.

class schrodinger.application.bunsen.maestro_tools.PickingTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'pick'

DESCRIPTION: str = 'Ask the user to pick an atom or residue from the Maestro workspace. When the user needs to pick multiple items, you can call this repeatedly. If this call returns a timeout error, call cancel_pick to release Maestro from picking mode.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='pick_mode', type='string', description="What to pick: 'atom' or 'residue'"), ToolParam(name='pick_text', type='string', description='Status text displayed in Maestro while picking'))

main(pick_mode: str, pick_text: str = '')

Start a Maestro pick mode and respond when the user picks.

Parameters:

• pick_mode – What to pick: "atom" or "residue".

• pick_text – Status text shown in Maestro while picking.

class schrodinger.application.bunsen.maestro_tools.CancelPickingTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'cancel_pick'

DESCRIPTION: str = 'Cancel an active Maestro picking operation. Call this to release Maestro from picking mode after a pick tool call has timed out.'

main()

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.HighlightTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'highlight'

DESCRIPTION: str = "Draw the user's attention to specific atoms or residues in the Maestro workspace using a silhouette highlight and optionally zoom the camera to fit them."

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='asl', type='string', description='ASL expression selecting atoms to highlight'), ToolParam(name='color', type='string', description="Highlight color: 'yellow', 'red', 'green', 'blue', 'orange', 'cyan', 'magenta', or 'white'"), ToolParam(name='fit', type='boolean', description='Whether to zoom the camera to the highlighted atoms'))

main(asl: str, color: str = 'yellow', fit: bool = True)

Highlight atoms in the Maestro workspace.

Parameters:

• asl – ASL expression selecting atoms to highlight.

• color – Named color for the highlight.

• fit – Whether to zoom the camera to the highlighted atoms.

class schrodinger.application.bunsen.maestro_tools.ClearHighlightTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'clear_highlight'

DESCRIPTION: str = 'Remove a highlight previously created by the highlight tool.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='highlight_name', type='string', description='Name of the highlight to remove, as returned by the highlight tool'),)

main(highlight_name: str)

Remove a named highlight and restore the previous camera view.

Parameters:

highlight_name – The highlight name returned by HighlightTool.

class schrodinger.application.bunsen.maestro_tools.SetRepresentationTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'set_representation'

DESCRIPTION: str = 'Set the atom/bond representation for atoms in the Maestro workspace.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='asl', type='string', description='ASL expression selecting atoms'), ToolParam(name='representation', type='string', description="Atom representation: 'circle', 'cpk', 'ballnstick'"))

main(asl: str, representation: str = 'ballnstick')

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.AtomVisibilityTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'atom_visibility'

DESCRIPTION: str = 'Show or hide atoms in the Maestro workspace.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='asl', type='string', description='ASL expression selecting atoms'), ToolParam(name='visible', type='boolean', description='Whether to show or hide the atoms'))

main(asl: str, visible: bool = True)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.SetColorTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'set_color'

DESCRIPTION: str = "Color atoms in the Maestro workspace by color scheme or explicit color. Provide exactly one of 'scheme' or 'color'."

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='asl', type='string', description='ASL expression selecting atoms. Defaults to all atoms.'), ToolParam(name='scheme', type='string', description="Color scheme name: 'Element', 'Element (Green Carbons)', 'Chain Name', 'Residue Type', 'Residue Position', 'Atom PDB B Factor (Temperature Factor)', 'Secondary Structure', 'Entry'"), ToolParam(name='color', type='string', description="Named color (red, green, blue, yellow, orange, cyan, white, gray, purple) or hex '#RRGGBB'"))

main(asl: str = 'all', scheme: str = '', color: str = '')

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.SetRibbonsTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'set_ribbons'

DESCRIPTION: str = "Set ribbon representation in the Maestro workspace. Use style 'none' to hide ribbons."

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='asl', type='string', description='ASL expression. Defaults to all atoms.'), ToolParam(name='style', type='string', description="Ribbon style: 'none', 'cartoon', 'ribbon', 'tube', 'thintube', 'curvedline', 'calphaline', 'calphatube'"), ToolParam(name='scheme', type='string', description="Ribbon color scheme: 'constant', 'secondarystructure', 'chain', 'calphaatom', 'residuecharge', 'residueproperty', 'residuetype', 'residueposition', 'entry', 'entrychain'"))

main(asl: str = 'all', style: str = 'cartoon', scheme: str = 'calphaatom')

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.ApplyPresetTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'apply_preset'

DESCRIPTION: str = 'Apply a built-in visualization preset to the Maestro workspace.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='preset', type='string', description="Preset name: 'Ligand Sites - Cartoon', 'Ligand Sites - Surface', 'Ligand Sites - Surface (Transparent)', 'Binding Mode Comparison', 'Technical Advanced', 'Protein Surface'"),)

main(preset: str)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.FitWorkspaceTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'fit_workspace'

DESCRIPTION: str = 'Fit the Maestro workspace camera to show specific atoms.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='asl', type='string', description='ASL expression to fit the camera to. Omit to fit all.'),)

main(asl: str = '')

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.CreateSurfaceTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'create_surface'

DESCRIPTION: str = 'Create a molecular surface in the Maestro workspace.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='entry_id', type='string', description='Entry ID the surface belongs to'), ToolParam(name='asl', type='string', description='ASL expression defining atoms for the surface'), ToolParam(name='style', type='string', description="Surface style: 'solid', 'mesh', 'dots'. Defaults to 'solid'."), ToolParam(name='transparency', type='integer', description='Surface transparency 0-100. Defaults to 0.'), ToolParam(name='color_scheme', type='string', description="Surface color scheme. Defaults to 'Atom Color'."))

main(entry_id: str, asl: str, style: str = 'solid', transparency: int = 0, color_scheme: str = 'Atom Color')

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.RemoveSurfaceTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'remove_surface'

DESCRIPTION: str = 'Remove a molecular surface from the Maestro workspace.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='entry_id', type='string', description='Entry ID the surface belongs to'), ToolParam(name='surface_name', type='string', description='Name of the surface to remove'))

main(entry_id: str, surface_name: str)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.LabelsTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'labels'

DESCRIPTION: str = 'Add or remove atom labels in the Maestro workspace. Omit properties to remove labels.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='asl', type='string', description='ASL expression selecting atoms. Defaults to all.'), ToolParam(name='properties', type='list[string]', description="Label properties to display: 'atomname', 'resname', 'resnum', 'element', 'chain', 'formalcharge', 'chirality', 'pdbbfactor', 'pdbname', 'anum', 'atype', 'entryname', 'occupancy', 'oneletter', 'stereochemistry'. Omit or pass empty list to remove labels."))

main(asl: str = 'all', properties: list[str] = ())

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.ShowInteractionsTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'show_interactions'

DESCRIPTION: str = 'Show or hide molecular interactions in the Maestro workspace.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='visible', type='boolean', description='True to show interactions, false to hide'),)

main(visible: bool)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.SendProjectTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'send_project'

DESCRIPTION: str = 'Send a project to Maestro, closing any current project.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='filename', type='file', description='Project archive (.prjzip) to open'),)

main(filename: str)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.GetProjectTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'get_project'

DESCRIPTION: str = 'Get the current Maestro project as a .prjzip archive.'

RESPONSE_FILES: tuple[str, ...] = ('filename',)

main()

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.GetScreenshotTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'get_screenshot'

DESCRIPTION: str = 'Get a PNG screenshot of Maestro. Use this to inspect what the user is currently seeing — particularly useful for diagnosing visual problems.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='capture_target', type='string', description="What to capture: 'workspace' (the 3D view only) or 'maestro_window' (the entire Maestro window). Defaults to 'workspace'."),)

RESPONSE_FILES: tuple[str, ...] = ('filename',)

main(capture_target: str = 'workspace')

Capture a PNG screenshot of the requested target.

Parameters:

capture_target – "workspace" or "maestro_window".

class schrodinger.application.bunsen.maestro_tools.GetStatusTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'get_status'

DESCRIPTION: str = 'Get the current state of the Maestro project.'

main()

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.GetSkillTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'get_skill'

DESCRIPTION: str = 'Get a detailed guide to using the Maestro tools effectively: an overview of the toolset, general usage guidelines, tool-selection advice, and pitfalls to avoid. Call this once after Maestro connects.'

main()

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.CreatePropertyTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'create_property'

DESCRIPTION: str = 'Create a new user property column in the Maestro project table. The new column starts empty; assign values by editing rows or by running calculate_property.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='property_name', type='string', description="Display name of the new property, e.g. 'Notes'."), ToolParam(name='property_type', type='string', description="Property value type: 'string', 'real', 'integer', 'boolean'. Defaults to 'string'."))

main(property_name: str, property_type: str = 'string')

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.DeletePropertyTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'delete_property'

DESCRIPTION: str = "Delete a property column from the Maestro project table. Use the property's display name, not its m2io data name."

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='property_name', type='string', description='Display name of the property to delete.'),)

main(property_name: str)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.RenamePropertyTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'rename_property'

DESCRIPTION: str = "Rename a property column in the Maestro project table. Use the property's display name, not its m2io data name."

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='old_name', type='string', description='Current display name of the property.'), ToolParam(name='new_name', type='string', description='New display name for the property.'))

main(old_name: str, new_name: str)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.CalculatePropertyTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'calculate_property'

DESCRIPTION: str = 'Calculate one or more built-in properties (e.g. molecular weight) for the currently-selected entries in the Maestro project table. Set the selection first with select_entries or select_group.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='property_names', type='list[string]', description="Built-in property names to calculate. Supported values: 'alogp', 'buriedhydrophobicsurfacearea', 'buriedsurfacearea', 'chiralcenter', 'hydrogenbondacceptors', 'hydrogenbonddonors', 'hydrophobicsurfacearea', 'index', 'molarrefractivity', 'molcharge', 'molecularformula', 'molweight', 'numatoms', 'numheavyatoms', 'nummolecules', 'numresidues', 'numrotatablebonds', 'pkaatom', 'polarizability', 'polarsurfacearea', 'propertycalculatesubstructs', 'secstruct', 'spin', 'surfacearea', 'unitcelldensity', 'unitcellformula', 'unitcellvolume'."), ToolParam(name='recalculate', type='boolean', description='Whether to recompute values for entries that already have the property set. Defaults to false.'))

main(property_names: list[str], recalculate: bool = False)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.CollapseGroupTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'collapse_group'

DESCRIPTION: str = "Collapse or expand a group in the Maestro project table. Pass group_path='all' to collapse or expand every group."

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='group_path', type='string', description="Title path of the group, using ' / ' for nesting, e.g. 'Docking Results / Pose 1'. Pass 'all' to operate on every group."), ToolParam(name='collapsed', type='boolean', description='True to collapse the group, false to expand it'))

main(group_path: str, collapsed: bool)

Collapse or expand a project table group.

Parameters:

• group_path – " / "-separated group titles, or the literal string "all" to operate on every group.

• collapsed – Whether to collapse (True) or expand (False).

class schrodinger.application.bunsen.maestro_tools.FindEntriesTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'find_entries'

DESCRIPTION: str = 'Highlight entries in the Maestro project table whose properties contain the given text, so the user can see the matches. This is a visual aid only: it does not return the matching entries. To act on entries programmatically, use select_entries_by_property or read get_status and filter the results yourself.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='query', type='string', description='Text to search for in the project table'), ToolParam(name='match_case', type='boolean', description='Whether to match case. Defaults to false.'), ToolParam(name='match_word', type='boolean', description='Whether to match whole words only. Defaults to false.'))

main(query: str, match_case: bool = False, match_word: bool = False)

Search for entries in the project table.

Parameters:

• query – Text to find.

• match_case – Case-sensitive search.

• match_word – Match whole words only.

class schrodinger.application.bunsen.maestro_tools.SetWorkspaceFeedbackPropertiesTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'set_workspace_feedback_properties'

DESCRIPTION: str = 'Set which entry properties are displayed as feedback in the Maestro workspace. Properties are shown as floating labels near the structure in the 3D view.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='properties', type='list[string]', description="List of property data names to display, e.g. ['r_i_docking_score', 's_m_title']. Pass an empty list to clear feedback properties."),)

main(properties: list[str])

Set workspace feedback properties.

Parameters:

properties – m2io property data names to display.

class schrodinger.application.bunsen.maestro_tools.ColorEntriesByPropertyTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'color_entries_by_property'

DESCRIPTION: str = 'Color entry rows in the Maestro project table by a property value. This sets the entry-row preview coloring (the colored squares next to entry names), which is distinct from atom coloring (use set_color for that).'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='property', type='string', description="Property data name to color by, e.g. 'r_i_docking_score'."),)

main(property: str)

Color entry rows by a property.

Parameters:

property – m2io property data name.

class schrodinger.application.bunsen.maestro_tools.SelectGroupTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'select_group'

DESCRIPTION: str = 'Select only the rows belonging to a group in the Maestro project table, deselecting all other rows.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='group_path', type='string', description="Title path of the group, using ' / ' for nesting, e.g. 'Docking Results / Pose 1'."),)

main(group_path: str)

Select only the rows in the given group.

Parameters:

group_path – " / "-separated group titles.

class schrodinger.application.bunsen.maestro_tools.CreateGroupFromSelectionTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'create_group_from_selection'

DESCRIPTION: str = 'Move the currently-selected entries into a new top-level group with the given title. Set the selection first with select_entries.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='title', type='string', description='Title for the new top-level group.'),)

main(title: str)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.DuplicateSelectionToGroupTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'duplicate_selection_to_group'

DESCRIPTION: str = "Duplicate the currently-selected entries into a group. When existing=false, a new top-level group with the given title is created. When existing=true, group_path must resolve to an existing group (use ' / ' for nesting). Set the selection first with select_entries."

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='group_path', type='string', description="For existing=false: title of the new top-level group. For existing=true: ' / '-separated title path of the target group."), ToolParam(name='existing', type='boolean', description='True to duplicate into an existing group, false to create a new top-level group. Defaults to false.'))

main(group_path: str, existing: bool = False)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.SortEntriesTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'sort_entries'

DESCRIPTION: str = 'Sort rows in the Maestro project table by one or more properties. Later sort fields act as tie-breakers for earlier ones. Set selected_only=true to sort only the currently-selected rows in place.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='sort_fields', type='list[string]', description="Sort fields as 'property:order' strings, e.g. ['Molecular Weight:ascending', 'Stars:descending']. Order must be 'ascending' or 'descending'."), ToolParam(name='selected_only', type='boolean', description='Whether to sort only the currently-selected rows. Defaults to false (sort all rows).'))

main(sort_fields: list[str], selected_only: bool = False)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.MoveEntriesInGroupTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'move_entries_in_group'

DESCRIPTION: str = 'Move the specified entries to the top or bottom of their immediate parent group in the Maestro project table. The prior row selection is preserved.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='entry_ids', type='list[string]', description='Entry IDs to move within their parent group.'), ToolParam(name='position', type='string', description="Where to move: 'top', 'bottom'. Defaults to 'top'."))

main(entry_ids: list[str], position: str = 'top')

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.SelectRandomEntriesTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'select_random_entries'

DESCRIPTION: str = "Randomly sample rows in the Maestro project table and select them. Provide exactly one of 'fraction' (0.0-1.0) or 'count'. When scope='group', sampling is restricted to the given group_path; otherwise all rows are eligible. Replaces the current selection."

SCOPES = ('all', 'group')

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='fraction', type='number', description='Fraction of eligible rows to sample, between 0.0 and 1.0.'), ToolParam(name='count', type='integer', description='Exact number of rows to sample.'), ToolParam(name='scope', type='string', description="Sampling scope: 'all', 'group'. Defaults to 'all'."), ToolParam(name='group_path', type='string', description="For scope='group': ' / '-separated title path of the group, e.g. 'Docking Results / Pose 1'."))

main(fraction: float | None = None, count: int | None = None, scope: str = 'all', group_path: str = '')

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.SelectEntriesByPropertyTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'select_entries_by_property'

DESCRIPTION: str = "Select rows in the Maestro project table whose numeric property value satisfies a range or a single comparison. Provide either min_value/max_value (inclusive numeric range; either bound is optional) or op/value (single comparison). Use the property's m2io data name, which follows the '<type>_<family>_<name>' format where <type> is 'r' (real) or 'i' (integer) and <family> is the creator (e.g. 'i' for Impact); e.g. 'r_i_docking_score' or 'i_i_glide_confnum'. Do not use the property's display name. For text-based selection use create_filter with an ESL expression instead."

MODES = {'add': 0, 'replace': 1}

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='property_name', type='string', description="m2io data name of the property, following the '<type>_<family>_<name>' format. Must be a real ('r_...') or integer ('i_...') property."), ToolParam(name='min_value', type='number', description='Inclusive lower bound for numeric range.'), ToolParam(name='max_value', type='number', description='Inclusive upper bound for numeric range.'), ToolParam(name='op', type='string', description="Comparison operator: '<', '<=', '>', '>=', '==', '!='."), ToolParam(name='value', type='number', description='Numeric value to compare against.'), ToolParam(name='mode', type='string', description="Selection mode: 'replace', 'add'. Defaults to 'replace'."))

main(property_name: str, min_value: float | None = None, max_value: float | None = None, op: str = '', value: float | None = None, mode: str = 'replace')

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.CreateFilterTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'create_filter'

DESCRIPTION: str = 'Create a named, reusable entry filter in Maestro from an ESL (Entry Selection Language) expression. Unlike select_entries_by_property, which selects rows once, a filter is saved and can be re-applied later by the user.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='name', type='string', description="Name for the new filter, e.g. 'volume_filter'."), ToolParam(name='esl', type='string', description='ESL definition of the filter. Reference properties by m2io data name (e.g. \'r_i_glide_gscore < -6.0\', \'i_bioluminate_PIPER_Model_Number < 50\') or by display name wrapped in user() (e.g. \'user("Glide Score") < -6.0\'). Combine with AND / OR / NOT.'))

main(name: str, esl: str)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

class schrodinger.application.bunsen.maestro_tools.ApplyFilterTool(call_id: str, args: dict, parent=None)

Bases: Tool

PROVIDER = <schrodinger.application.bunsen.tool.Provider object>

NAME: str = 'apply_filter'

DESCRIPTION: str = 'Apply a previously-created named entry filter to the Maestro project table, selecting the entries that match and deselecting the rest. Use create_filter first to define the filter.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='name', type='string', description='Name of the filter to apply.'),)

main(name: str)

The main function is responsible for calling self.sendResponse() itself or in a downstream callback or slot. This allows for both synchronous and asynchronous tool implementations.

schrodinger.application.bunsen.maestro_tools.connect_url(full_url)

schrodinger.application.bunsen.maestro_tools.connect(url: str, session_id: str, token: str | None = None)

Connect Maestro to a Bunsen session.

Entry point for pythonrun:

pythonrun schrodinger.application.bunsen.maestro_tools connect <url> <session_id>

Parameters:

• url – Bunsen server URL.

• session_id – Session UUID.

• token – Optional Bunsen PAT. When None, the token is resolved via the usual precedence: BUNSEN_PAT environment variable, then the keyring (where the BMI panel’s PAT field stores it).

schrodinger.application.bunsen.maestro_tools.disconnect()

Disconnect Maestro from the current Bunsen session.

Entry point for pythonrun:

pythonrun schrodinger.application.bunsen.maestro_tools disconnect