serena.tools.file_tools

serena.tools.file_tools#

Source code: serena/tools/file_tools.py

File and file system-related tools, specifically for

  • listing directory contents

  • reading files

  • creating files

  • editing at the file level

class ReadFileTool(agent)[source]#

Bases: Tool

Reads a file within the project directory.

Parameters:

agent (SerenaAgent)

apply(relative_path, start_line=0, end_line=None, max_answer_chars=-1)[source]#

Reads the given file or a chunk of it.

Parameters:

  • relative_path (str) – the relative path to the file to read

  • start_line (int) – the 0-based index of the first line to be retrieved, negative values count from the end of the file.

  • end_line (int | None) – the 0-based index of the last line to be retrieved (inclusive). If None, read until the end of the file.

  • max_answer_chars (int) – if the file (chunk) is longer than this number of characters, no content will be returned. Don’t adjust unless there is really no other way to get the content required for the task.

Returns:

the full text of the file at the given relative path

Return type:

str

class CreateTextFileTool(agent)[source]#

Bases: EditingToolWithDiagnostics

Creates/overwrites a file in the project directory.

Parameters:

agent (SerenaAgent)

apply(relative_path, content)[source]#

Write a new file or overwrite an existing file with the given content.

Parameters:

  • relative_path (str) – the relative path to the file to create

  • content (str) – the (appropriately encoded) content to write to the file

Returns:

a message indicating success or failure

Return type:

str

class ListDirTool(agent)[source]#

Bases: Tool

Lists files and directories in the given directory (optionally with recursion).

Parameters:

agent (SerenaAgent)

apply(
relative_path,
recursive,
skip_ignored_files=False,
max_answer_chars=-1,
)[source]#

Lists files and directories in the given directory (optionally with recursion).

Parameters:

  • relative_path (str) – the relative path to the directory to list; pass “.” to scan the project root

  • recursive (bool) – whether to scan subdirectories recursively

  • skip_ignored_files (bool) – whether to skip files and directories that are ignored

  • max_answer_chars (int) – if the output is longer than this number of characters, no content will be returned. -1 means the default value from the config will be used. Don’t adjust unless there is really no other way to get the content required for the task.

Returns:

a JSON object with the names of directories and files within the given directory

Return type:

str

class FindFileTool(agent)[source]#

Bases: Tool

Finds files in the given relative paths

Parameters:

agent (SerenaAgent)

apply(file_mask, relative_path)[source]#

Finds files matching the given file mask within the given relative path

Parameters:

  • file_mask (str) – the filename or file mask (using the wildcards * or ?) to search for

  • relative_path (str) – the relative path to the directory to search in; pass “.” to scan the project root

  • skip_ignored_files – whether to skip ignored files/directories

Returns:

a JSON object with the list of matching files

Return type:

str

class ReplaceContentTool(agent)[source]#

Bases: EditingToolWithDiagnostics

Replaces content in a file (optionally using regular expressions).

Parameters:

agent (SerenaAgent)

apply(
relative_path,
needle,
repl,
mode,
allow_multiple_occurrences=False,
)[source]#

Replaces one or more occurrences of a given pattern in a file with new content.

VERY IMPORTANT: The “regex” mode allows very large sections of code to be replaced WITHOUT quoting them fully: use a needle of the form “beginning.*?end-of-text-to-be-replaced” with wildcards instead of pasting the exact original text — shorter, cheaper, and you cannot make mistakes, because an ambiguous match returns an error you can refine, so wildcards are safe. Prefer regex mode with suitable wildcards for long multi-line replacements; use the symbol-level editors when replacing a whole method/class.

Parameters:

  • relative_path (str) – the relative path to the file

  • needle (str) – the string or regex pattern to search for. If mode is “literal”, this string will be matched exactly. If mode is “regex”, this string will be treated as a regular expression (syntax of Python’s re module, with flags DOTALL and MULTILINE enabled).

  • repl (str) – the replacement string (verbatim). If mode is “regex”, the string can contain backreferences to matched groups in the needle regex, specified using the syntax $!1, $!2, etc. for groups 1, 2, etc.

  • mode (Literal['literal', 'regex']) – either “literal” or “regex”, specifying how the needle parameter is to be interpreted.

  • allow_multiple_occurrences (bool) – whether to allow matching and replacing multiple occurrences. If false and multiple occurrences are found, an error will be returned

Return type:

str

class ReplaceInFilesTool(agent)[source]#

Bases: EditingToolWithDiagnostics

Replaces occurrences of a pattern across multiple files, with dry-run preview and per-occurrence selection.

Parameters:

agent (SerenaAgent)

apply(
needle,
repl,
mode,
relative_path='',
paths_include_glob='',
paths_exclude_glob='',
dry_run=False,
occurrence_ids=None,
expected_count=-1,
max_answer_chars=-1,
)[source]#

Replaces occurrences of a pattern across multiple files in ONE call.

This is the preferred tool for repeated small edits (renames, import swaps, annotation changes, path prefixes) spanning several files or many places in one file: one call with a SHORT pattern replaces many single-file replacements with long disambiguating needles.

Recommended protocol whenever there is ANY risk of unintended replacements:

  1. Call with dry_run=True: every prospective change is returned as a minimal line diff with an occurrence id; nothing is modified.

  2. Call again with dry_run=False, passing the ids you want in occurrence_ids (omit it to apply all). You pick the desired replacements from the list - no counting, no needle-crafting.

For clearly unambiguous bulk replacements you may skip the dry run; pass expected_count as a guard. If the actual number of matches differs, NOTHING is changed and the diff list is returned, so a failed guard costs one call and gives you the dry-run output to select from.

Parameters:

  • needle (str) – the string (mode “literal”) or regular expression (mode “regex”; Python re syntax with DOTALL and MULTILINE) to search for

  • repl (str) – the replacement string. In regex mode, backreferences to matched groups can be specified as $!1, $!2, etc.

  • mode (Literal['literal', 'regex']) – either “literal” or “regex”, specifying how needle is to be interpreted

  • relative_path (str) – only consider this file or directory (default: the whole project)

  • paths_include_glob (str) – optional glob (relative to the project root, e.g. "src/**/*.java") restricting which files are considered

  • paths_exclude_glob (str) – optional glob of files to exclude; takes precedence over the include glob

  • dry_run (bool) – if True, do not modify anything; return the prospective changes as a list of diffs with occurrence ids

  • occurrence_ids (list[str] | None) – optional list of occurrence ids (obtained from a dry run) to which the replacement is restricted; if any id is unknown or stale, NOTHING is changed. If omitted, all occurrences are replaced.

  • expected_count (int) – optional guard for calls without occurrence_ids: the number of occurrences you expect to be replaced. If the actual count differs, nothing is changed and the list of prospective changes is returned. -1 disables the guard.

  • max_answer_chars (int) – if the output exceeds this many characters, a shortened version is returned. -1 uses the configured default.

Returns:

in a dry run, the prospective changes; otherwise a summary of the applied replacements

Return type:

str

class DeleteLinesTool(agent)[source]#

Bases: EditingToolWithDiagnostics, ToolMarkerOptional

Deletes a range of lines within a file.

Parameters:

agent (SerenaAgent)

apply(relative_path, start_line, end_line)[source]#

Deletes the given lines in the file. Requires that the same range of lines was previously read using the read_file tool to verify correctness of the operation.

Parameters:

  • relative_path (str) – the relative path to the file

  • start_line (int) – the 0-based index of the first line to be deleted

  • end_line (int) – the 0-based index of the last line to be deleted

Return type:

str

class ReplaceLinesTool(agent)[source]#

Bases: EditingToolWithDiagnostics, ToolMarkerOptional

Replaces a range of lines within a file with new content.

Parameters:

agent (SerenaAgent)

apply(relative_path, start_line, end_line, content)[source]#

Replaces the given range of lines in the given file. Requires that the same range of lines was previously read using the read_file tool to verify correctness of the operation.

Parameters:

  • relative_path (str) – the relative path to the file

  • start_line (int) – the 0-based index of the first line to be deleted

  • end_line (int) – the 0-based index of the last line to be deleted

  • content (str) – the content to insert

Return type:

str

class InsertAtLineTool(agent)[source]#

Bases: EditingToolWithDiagnostics, ToolMarkerOptional

Inserts content at a given line in a file.

Parameters:

agent (SerenaAgent)

apply(relative_path, line, content)[source]#

Inserts the given content at the given line in the file, pushing existing content of the line down. In general, symbolic insert operations like insert_after_symbol or insert_before_symbol should be preferred if you know which symbol you are looking for. However, this can also be useful for small targeted edits of the body of a longer symbol (without replacing the entire body).

Parameters:

  • relative_path (str) – the relative path to the file

  • line (int) – the 0-based index of the line to insert content at

  • content (str) – the content to be inserted

Return type:

str

class SearchForPatternTool(agent)[source]#

Bases: Tool

Parameters:

agent (SerenaAgent)

apply(
substring_pattern,
context_lines_before=0,
context_lines_after=0,
paths_include_glob='',
paths_exclude_glob='',
relative_path='',
restrict_search_to_code_files=False,
skip_ignored_files=True,
multiline=True,
max_answer_chars=-1,
)[source]#

Searches for a regex pattern across project files, returning whole matched lines (plus optional context). Prefer symbolic operations if you know which symbols you are looking for!

Parameters:

  • substring_pattern (str) – regular expression to search for.

  • context_lines_before (int) – number of context lines to include before each match.

  • context_lines_after (int) – number of context lines to include after each match.

  • paths_include_glob (str) – optional glob (relative to project root, e.g. "src/**/*.ts") restricting which files are searched.

  • paths_exclude_glob (str) – optional glob to exclude files; takes precedence over paths_include_glob.

  • relative_path (str) – restricts the search to this file or subdirectory of the project root

  • restrict_search_to_code_files (bool) – whether to search only (non-ignored) files containing analyzable code symbols (useful when looking for class/method definitions); otherwise also search non-code files.

  • skip_ignored_files (bool) – whether to skip ignored sub-paths (default: True)

  • multiline (bool) – whether to apply multi-line matching (default: True), enabling the flags re.DOTALL and re.MULTILINE

  • max_answer_chars (int) – if the output exceeds this many characters, a progressively shortened summary is returned instead. -1 uses the configured default.

Returns:

A mapping from file paths to matched consecutive lines (0-based line numbers).

Return type:

str