serena.tools.tools_base

serena.tools.tools_base#

Source code: serena/tools/tools_base.py

class Component(agent)[source]#

Bases: ABC

Parameters:

agent (SerenaAgent)

get_project_root()[source]#
Returns:

the root directory of the active project, raises a ValueError if no active project configuration is set

Return type:

str

class ToolMarker[source]#

Bases: object

Base class for tool markers.

class ToolMarkerCanEdit[source]#

Bases: ToolMarker

Marker class for all tools that can perform editing operations on files.

class ToolMarkerDoesNotRequireActiveProject[source]#

Bases: ToolMarker

class ToolMarkerOptional[source]#

Bases: ToolMarker

Marker class for optional tools that are disabled by default.

class ToolMarkerSymbolicRead[source]#

Bases: ToolMarker

Marker class for tools that perform symbol read operations.

class ToolMarkerSymbolicEdit[source]#

Bases: ToolMarkerCanEdit

Marker class for tools that perform symbolic edit operations.

class ToolMarkerBeta[source]#

Bases: ToolMarker

Marker for tools that are considered beta features (may not be fully robust)

class ApplyMethodProtocol(*args, **kwargs)[source]#

Bases: Protocol

Callable protocol for the apply method of a tool.

exception ToolCallError(error_message)[source]#

Bases: Exception

Represents an error raised during a tool call execution

Parameters:

error_message (str)

class Tool(agent)[source]#

Bases: Component

Parameters:

agent (SerenaAgent)

SESSION_ID_PARAM_NAME = 'session_id'#

parameter name to use in apply method for the client session ID. This parameter will be ignored by the MCP interface but will be populated with the session ID of the current client session when the tool is called, allowing tools to be session-aware if needed.

classmethod can_edit()[source]#

Returns whether this tool can perform editing operations on code.

Returns:

True if the tool can edit code, False otherwise

Return type:

bool

classmethod get_apply_docstring_from_cls()[source]#

Get the docstring for the apply method from the class (static metadata). Needed for creating MCP tools in a separate process without running into serialization issues.

Return type:

str

get_apply_docstring()[source]#

Gets the docstring for the tool application, used by the MCP server.

Return type:

str

get_apply_fn_metadata(structured_output=None)[source]#

Gets the metadata for the tool application function, used by the MCP server.

Parameters:

structured_output (bool | None)

Return type:

FuncMetadata

classmethod get_apply_fn_metadata_from_cls(structured_output=None)[source]#

Get the metadata for the apply method from the class (static metadata). Needed for creating MCP tools in a separate process without running into serialization issues.

Parameters:

structured_output (bool | None)

Return type:

FuncMetadata

classmethod get_param_aliases()[source]#
Returns:

a mapping of parameter aliases for the apply method, where the key is the alias and the value is the actual parameter name. This can be used to define alternative parameter names for the same parameter.

Return type:

dict[str, str]

apply_ex(log_call=True, catch_exceptions=True, mcp_ctx=None, **kwargs)[source]#

Applies the tool with logging and exception handling, using the given keyword arguments. This method either returns a string result or raises a ToolCallError in case of an error during tool application (but if catch_exceptions is enabled, it will return the error message as a string instead of raising the exception).

Parameters:

  • log_call (bool) – whether to log the tool call and its result

  • catch_exceptions (bool) – whether to catch exceptions and return their messages as strings, instead of raising a ToolCallError

  • mcp_ctx (Context | None)

Return type:

str

class EditingToolWithDiagnostics(agent)[source]#

Bases: Tool, ToolMarkerCanEdit

Base class for editing tools that want to capture and report changes in LSP diagnostics before and after the edit.

Parameters:

agent (SerenaAgent)

ENABLE_DIAGNOSTICS: bool = False#

Global flag to enable/disable diagnostics for LSP-based editing tools derived from this class. The feature is currently disabled, because per-edit diagnostics are a questionable feature, since individual edits often intentionally introduce diagnostics (e.g. function signature mismatches or even syntax errors) that are then resolved in subsequent edits.

class EditedFileContext(relative_path, code_editor)[source]#

Bases: object

Context manager for file editing.

Create the context, then use set_updated_content to set the new content, the original content being provided in original_content. When exiting the context without an exception, the updated content will be written back to the file.

Parameters:

  • relative_path (str)

  • code_editor (CodeEditor)

get_original_content()[source]#
Returns:

the original content of the file before any modifications.

Return type:

str

set_updated_content(content)[source]#

Sets the updated content of the file, which will be written back to the file when the context is exited without an exception.

Parameters:

content (str) – the updated content of the file

Return type:

None

class RegisteredTool(
*,
tool_class: type[Tool],
is_optional: bool,
is_beta: bool,
tool_name: str,
)[source]#

Bases: object

Parameters:

  • tool_class (type[Tool])

  • is_optional (bool)

  • is_beta (bool)

  • tool_name (str)

property class_docstring: str#
Returns:

the tool description (high-level class docstring)