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>

exception schrodinger.application.bunsen.maestro_tools.InvalidMaestroCommandError(command: str, reason: str)

Bases: ValueError

A Bunsen tool produced malformed Maestro command text.

__init__(command: str, reason: str)

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

Bases: Tool

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

NAME: str = 'send_fep_map'

DESCRIPTION: str = "Import an FEP map (.fmp) into the Maestro project table, preserving its FEP workflow metadata, and stage the original map for Maestro-side workflows. This does not open any panel. To open the complete map afterward, use WAM > 'Associated FMP File...' rather than 'Grouped Structures...', which omits edge data. Provide the matching .fmpdb file when available."

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='filename', type='file', description='FEP map (.fmp) to import into the Maestro project table'), ToolParam(name='fmpdb', type='file', description='Optional companion .fmpdb file to stage with the map'))

main(filename: str, fmpdb: str | None = None)

Stage and import an FEP map into the project table.

Responds with the imported entry_ids, the staged fmp_path, and, when available, the staged fmpdb_path.

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: 'maegz', 'mae', 'sdf', 'csv'. Defaults to 'maegz'."))

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

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

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 are included in the Maestro workspace. The given entries become the entire workspace; every other entry is excluded. To add to what is already shown, read included_entry_ids from get_status and pass those IDs along with the new ones.'

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

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.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, or clear it entirely when entry_ids is empty; 'add' — add the given entry IDs to the current selection. Default mode is 'replace'. Read get_status to work out which entry IDs to pass, e.g. to select every entry or to invert the current selection."

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='mode', type='string', description="Selection mode: 'replace' or 'add'. Defaults to 'replace'."), ToolParam(name='entry_ids', type='list[string]', description="Entry IDs to select. Pass an empty list with mode 'replace' to deselect everything."))

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

Select rows in the Maestro project table.

Parameters:

• mode – Selection mode — "replace" or "add".

• entry_ids – Entry IDs to select. An empty list is only meaningful with "replace", which clears the selection.

Raises:

ValueError – If mode is not recognised, or if "add" is given no entry IDs.

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'), ToolParam(name='keep_surfaces', type='boolean', description='Whether to keep any molecular surfaces associated with the replaced entries. Surfaces are geometric meshes tied to the original atom positions, so they become stale when the structure changes. Defaults to True (surfaces are kept). Set to False to delete them when replacing with a structure that has different coordinates or a different atom count/ordering.'))

main(entry_ids: list[str], filename: str, keep_surfaces: 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.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 or bond representation for atoms selected by an ASL expression in the Maestro workspace. Use an entry.id clause to target specific included entries. Atom representations are 'none', 'circle', 'cpk', 'ballnstick'; bond representations are 'wire', 'tube', 'thin_tube'. The 'none' atom representation resets both atom and bond representations to Maestro defaults: no atom spheres and wire bonds."

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

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. Use an entry.id clause to target specific included entries.'

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'. Use an entry.id clause to target specific included entries."

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="Maestro palette color name ('red', 'green', 'blue', 'yellow', 'orange', 'white', 'gray', or '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 and an entry.id clause to target specific included entries."

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.ListSurfacesTool(call_id: str, args: dict, parent=None)

Bases: Tool

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

NAME: str = 'list_surfaces'

DESCRIPTION: str = 'List surfaces in the Maestro project, including surfaces created by visualization presets. Returns entry IDs and surface names that can be passed to remove_surface.'

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.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, and use an entry.id clause to target specific included entries.'

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 archive to Maestro. If the current project has scratch work that needs attention, Maestro may prompt user to save, discard, or cancel before importing; otherwise it proceeds without waiting for input. Canceling leaves the current project open.'

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',)

RESPONSE_FILE_DIR: str | None = 'maestro_files/screenshots'

main(capture_target: str = 'workspace')

Capture a PNG screenshot of the requested target.

Camera moves such as fit animate, so a single capture can catch a mid-animation frame. We recapture until two consecutive images compare equal (the view has settled), or until _MAX_SCREENSHOT_CAPTURES is reached, pumping events between captures so the animation can advance.

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 full current state of the Maestro project table. This response includes section hashes for use as a baseline. Before relying on this state later, use get_status_hashes and only call get_status again when a hash has changed or more information about the table state is needed.'

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.GetStatusHashesTool(call_id: str, args: dict, parent=None)

Bases: GetStatusTool

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

NAME: str = 'get_status_hashes'

DESCRIPTION: str = 'Check whether previously fetched Maestro project-table state is still current. Before acting on state from get_status, call this tool and compare its section hashes with the hashes from that response. Call get_status again if any hash has changed.'

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 specified entries in the Maestro project table.'

PARAMS: tuple[ToolParam, ...] = (ToolParam(name='entry_ids', type='list[string]', description='Entry IDs for which to calculate the properties.'), 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(entry_ids: list[str], 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 one group in the Maestro project table. To operate on every group, read the group paths from get_status and call this tool for each one.'

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

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

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.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.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