bots.tools package

Submodules

bots.tools.code_tools module

bots.tools.code_tools.view(file_path: str, max_lines: int = 2500)

Display the contents of a file with line numbers.

Parameters: - file_path (str): The path to the file to be viewed. - max_lines (int, optional): Maximum number of lines to display. Defaults to 2500.

Returns: A string containing the file contents with line numbers.

cost: varies

bots.tools.code_tools.view_dir(start_path: str = '.', output_file=None, target_extensions: str = "['py', 'txt', '.md']")

Creates a summary of the directory structure starting from the given path, writing only files with specified extensions and showing venv directories without their contents.

Parameters: - start_path (str): The root directory to start scanning from. - output_file (str): The name of the file to optionally write the directory structure to. - target_extensions (str): String representation of a list of file extensions (e.g. “[‘py’, ‘txt’]”).

Returns: str: A formatted string containing the directory structure, with each directory and file properly indented.

Example output: my_project/

venv/ module1/

script.py README.md

module2/

utils.py

cost: low

bots.tools.code_tools.diff_edit(file_path: str, diff_spec: str)

Diff spec editing with flexible matching.

Use when you need to make precision changes in text files.

Parameters: - file_path (str): Path to the file to modify - diff_spec (str): Diff-style specification of changes. Input lines beginning with ‘-’ are removed, and input lines beginning with ‘+’ are added at the starting index of the removed lines. All lines must start with + or -, and white space must be matched exactly.

Returns: str: Description of changes made/to be made or error message with context

ex) diff_spec: -import numpy +import scipy

cost: medium

bots.tools.code_tools._find_matching_block(current_lines, remove_lines, ignore_indentation)

Find where a block of lines matches in the current file content.

Parameters:

• current_lines – List of strings representing current file content

• remove_lines – List of strings to find in the file

• ignore_indentation – Whether to ignore leading whitespace when matching

Returns:

bool, line_num: int, indent: str, match_score: float, best_index: int) where: - match_found indicates if an exact match was found - line_num is the line where the match starts (or best partial match) - indent is the indentation to preserve - match_score indicates quality of best partial match (0-1) - best_index is the line number of best partial match

Return type:

tuple (match_found

bots.tools.code_tools._get_indentation(line)

Extract the leading whitespace from a line.

bots.tools.code_tools._adjust_indentation(lines, target_indent)

Adjust indentation of a block of lines to match target_indent.

bots.tools.code_tools._get_context(lines, center_idx, context_size)

Get context lines around an index with line numbers.

bots.tools.code_tools._calculate_block_match_score(current_block, old_lines, ignore_indentation)

Calculate how well two blocks match, returning a score and matching line indices.

bots.tools.code_tools._has_line_number_prefix(line: str) → bool

Check if a string starts with a line number format (e.g., ‘123:’ or ‘ 123:’) :param line: The line to check :type line: str

Returns:

True if the line starts with a number followed by a colon

Return type:

bool

bots.tools.code_tools._strip_line_number(line: str) → str

Remove line number prefix if present (e.g., ‘123:content’ or ‘ 123:content’ becomes ‘content’) Preserves any leading whitespace before the line number. :param line: The line to process :type line: str

Returns:

The line with any line number prefix removed

Return type:

str

bots.tools.meta_tools module

bots.tools.meta_tools.message_bot(bot_path, message)

Loads a bot, sends it a message, and allows it to work.

Use to prepare a bot to do a task and to allow it to work. Returns control when the bot replies with ‘/DONE’.

Parameters: - bot_path (str): File path to the saved bot - message (str): The message to send to the bot

Returns the bot’s first response, a list of tool-uses in order, and final response as a string.

Does NOT save the bot.

cost: varies

bots.tools.meta_tools.initialize_file_bot(file_name: str, system_message: str) → str

Creates and initializes a new file-editing bot, saving it to disk. Creates any necessary directories from the file_name path if they don’t exist.

Use when you need to create a new bot to handle implementation of a specific file. The bot will be initialized with appropriate file-level tools and context.

Parameters: - file_name (str): Name of the file this bot will manage (can include directory path)

Returns success message with bot’s file path or an error message string.

cost: low

bots.tools.meta_tools.generate_project(spec: str) → str

Executes the standard process for project generation using a hierarchical system of specialized AI assistants.

Use when you need to create a complete Python project from a specification. The system will: 1. Analyze project specifications and create module requirements 2. Break down the project into logical modules 3. Create and coordinate specialized bots for implementation 4. Implement and test the code 5. Validate against requirements

Parameters: - spec (str): Project specification text describing the desired system

Returns: str: Success message or error message string

cost: very high

bots.tools.python_editing_tools module

class bots.tools.python_editing_tools.NodeTransformerWithAsyncSupport

Bases: NodeTransformer

Base class for AST transformers that need to handle both sync and async functions.

__init__()

visit_FunctionDef(node)

visit_AsyncFunctionDef(node)

_handle_function(node)

Override this method in subclasses to implement specific transformation logic

class bots.tools.python_editing_tools.FunctionReplacer(new_func_node)

Bases: NodeTransformerWithAsyncSupport

__init__(new_func_node)

class bots.tools.python_editing_tools.MethodAdder(class_name, new_method_node)

Bases: NodeTransformerWithAsyncSupport

__init__(class_name, new_method_node)

visit_ClassDef(node)

bots.tools.python_editing_tools.add_imports(file_path: str, code: str) → str

Adds multiple import statements to a Python file. Creates the file if it doesn’t exist. Avoids adding duplicate imports.

Parameters: - file_path (str): The path to the file where the imports will be added - code (str): Import statements, which can include parenthesized multi-line imports

Returns a confirmation message or an error message.

cost: very low

bots.tools.python_editing_tools.remove_import(file_path: str, import_to_remove: str) → str

Removes an import statement from a Python file.

Parameters: - file_path (str): The path to the file to modify - import_to_remove (str): The import statement to remove (e.g., “import os” or “from typing import List”)

Must match the existing import statement exactly.

Returns a confirmation message or an error message.

cost: very low

bots.tools.python_editing_tools.replace_import(file_path: str, old_import: str, new_import: str) → str

Replaces an existing import statement in a Python file.

Parameters: - file_path (str): The path to the file to modify - old_import (str): The existing import statement to replace - new_import (str): The new import statement

Returns a confirmation message or an error message.

cost: very low

bots.tools.python_editing_tools.add_class(file_path: str, class_def: str) → str

Adds a new class definition to an existing Python file. Creates the file if it doesn’t exist.

Parameters: - file_path (str): The path to the file where the new class will be added - class_def (str): The new class definition as a string

Returns a confirmation message or an error message.

cost: low

bots.tools.python_editing_tools.replace_class(file_path: str, new_class_def: str, old_class_name: str = None) → str

Replaces a class definition in a file with a new class definition. Creates the file if it doesn’t exist.

Parameters: - file_path (str): The path to the file to modify - new_class_def (str): The new class definition - old_class_name (str, optional): The name of the class to replace

Returns a confirmation message or an error message.

cost: low

bots.tools.python_editing_tools.add_function_to_class(file_path: str, class_name: str, new_method_def: str) → str

Adds one or more methods to an existing class in a Python file. Creates the file and class if they don’t exist.

Parameters: - file_path (str): The path to the file to modify - class_name (str): The name of the class to modify - new_method_def (str): One or more method definitions as a string

Returns a confirmation message or an error message.

cost: very low

bots.tools.python_editing_tools.add_function_to_file(file_path: str, new_function_def: str, class_name: str = None) → str

Adds one or more function definitions to an existing Python file. Creates the file if it doesn’t exist.

When adding complex code blocks: - Imports are moved to the top of the file - Functions are added in order of appearance - Non-function code (assignments, if blocks, etc.) is preserved but may be reordered - Comments are not preserved (limitation of AST)

Parameters: - file_path (str): The path to the file to modify - new_function_def (str): One or more function definitions as a string - class_name (str, optional): If provided, add functions to this class

Returns a confirmation message or an error message.

cost: very low

bots.tools.python_editing_tools.replace_function(file_path: str, new_function_def: str, class_name: str = None) → str

Replaces one or more function definitions in a file with new function definitions. Creates the file if it doesn’t exist.

Parameters: - file_path (str): The path to the file to modify - new_function_def (str): One or more function definitions as a string - class_name (str, optional): If provided, only replace functions within this class

Returns a confirmation message or an error message.

cost: very low

bots.tools.python_editing_tools._make_file(file_path: str) → str

Creates a file and its parent directories if they don’t exist. Converts relative paths to absolute paths.

Parameters: - file_path (str): The path to the file to be created

Returns: - str: The absolute path to the file

Raises: - ValueError: If there’s an error creating the file or directories,

or if the file_path is empty

bots.tools.python_editing_tools._add_single_function_to_class(file_path: str, class_name: str, new_method_def: str) → str

Adds a single method to a class.

bots.tools.python_editing_tools._add_single_function_to_file(file_path: str, new_function_def: str) → str

Adds a single function and preserves all code blocks, including any code following the function.

bots.tools.python_editing_tools._replace_single_function(file_path: str, new_function_def: str, class_name: str = None) → str

Replaces a single function in a file, optionally within a specific class.

Parameters:

• file_path – Path to the file to modify

• new_function_def – The new function definition

• class_name – If provided, only replace within this class

bots.tools.python_execution_tool module

bots.tools.python_execution_tool._execute_python_code(code: str, timeout: int = 300) → str

Executes python code in a stateless environment with cross-platform timeout handling.

Parameters: - code (str): Syntactically correct python code - timeout (int): Maximum execution time in seconds (default: 300)

Returns stdout or an error message.

cost: varies

bots.tools.python_execution_tool._process_error(error: Exception) → str

Format error message with traceback.

bots.tools.self_tools module

bots.tools.self_tools._get_calling_bot() → Bot | None

Helper function to get a reference to the calling bot.

Returns:

Reference to the calling bot or None if not found

Return type:

Optional[Bot]

bots.tools.self_tools.get_own_info() → str

Get information about yourself.

Use when you need to inspect your current configuration (not tools).

Returns:

JSON string containing bot information including: - name: Your name - role: Your role - role_description: Your role description - model_engine: Current model engine - temperature: Current temperature setting - max_tokens: Maximum tokens setting - tool_count: Number of available tools

Return type:

str

bots.tools.self_tools._modify_own_settings(temperature: str = None, max_tokens: str = None) → str

Modify your settings.

Use when you need to adjust your configuration parameters.

Parameters:

• temperature (str, optional) – New temperature value as string (0.0 to 1.0)

• max_tokens (str, optional) – New maximum tokens value as string (must be > 0)

Returns:

Description of changes made or error message

Return type:

str

bots.tools.self_tools.branch_self(self_prompts: str, allow_work: str = 'False') → str

Branches your conversation using a list of self-prompts. The prompts will be sent as user messages in response to your message that calls this tool. Also tags the messages with (self-prompt) to distinguish from legitimate user messages.

Use when you need to: - explore multiple conversation paths. - break down a large list of tasks (>~6)

Branches will be traversed sequentially.

Each message will start a new conversation branch from the current message.

Parameters:

• self_prompts (str) – Array formatted as a string, i.e. [‘1’, ‘2’, ‘3’]

• allow_work – ‘True’ or ‘False’ (default). If True, allows each branch to work until it does not respond with any tool calls (i.e. each branch will be a chain).

Returns:

success message or error string.

Return type:

str

bots.tools.self_tools.add_tools(filepath: str) → str

Adds a new set of tools (python functions) to your toolkit

All top-level, non-private functions in filepath will be uploaded to your toolkit. Use when you need to create a new tool or kit for yourself to use in the future. Tool format is strict: string in, string out, with error catching wrapping (typically) all code in the function.

Parameters:

filepath – location of python tool file

Returns:

success or error message

Return type:

str

bots.tools.self_tools._process_string_array(input_str: str) → List[str]

Parse a string representation of an array into a list of strings. Only works with properly formatted Python list literals.

Parameters:

input_str (str) – String representation of a Python list literal

Returns:

List of parsed strings

Return type:

List[str]

Raises:

ValueError – If the input is not a valid Python list literal

bots.tools.terminal_tools module

bots.tools.terminal_tools.execute_powershell(command: str, output_length_limit: str = '120') → str

Executes PowerShell commands in a stateful environment

Use when you need to run PowerShell commands and capture their output. If you have other tools available, you should use this as a fallback when the other tools fail. Coerces to utf-8.

Potential use cases: - git commands - gh cli - other cli (which you may need to install using this tool)

Parameters: - command (str): PowerShell command to execute. - output_length_limit (int, optional): Maximum number of lines in the output.

If set, output exceeding this limit will be truncated. Default 120.

Returns:

The complete output from the command execution

Return type:

str

class bots.tools.terminal_tools.PowerShellSession

Bases: object

Manages a persistent PowerShell process for stateful command execution. Maintains a single PowerShell process that persists between commands, allowing for stateful operations like changing directories, setting environment variables, or activating virtual environments.

__init__()

_start_reader_threads()

Start background threads to read stdout and stderr

execute(code: str, timeout: float = 300) → str

Execute PowerShell code and return its complete output.

Parameters:

• code – The PowerShell code to execute

• timeout – Maximum time in seconds to wait for command completion

Returns:

The complete output from the command(s)

Raises:

• Exception if the process is not running or other execution errors –

• TimeoutError if command execution exceeds timeout –

class bots.tools.terminal_tools.PowerShellManager

Bases: object

Thread-safe PowerShell session manager that maintains separate sessions. Each instance automatically gets its own unique ID and isolated PowerShell session. Includes session recovery logic for lost or failed sessions.

classmethod get_instance(bot_id: str = None) → PowerShellManager

Get or create a PowerShell manager instance for the given bot_id. If no bot_id is provided, uses the current thread name.

Parameters:

bot_id – Optional identifier for the bot instance

Returns:

The PowerShell manager instance for this bot/thread

__init__()

Private initializer - use get_instance() instead.

property session: PowerShellSession

Get the PowerShell session for the current thread. Creates a new session if none exists or if the current session is invalid.

_start_new_session()

Starts a new PowerShell session for the current thread.

_is_session_valid() → bool

Checks if the current session is valid and responsive. :returns: True if session is valid, False otherwise :rtype: bool

execute(code: str, output_length_limit: str = '60') → Generator[str, None, None]

Execute PowerShell code in the session with automatic recovery.

Parameters:

• code – PowerShell code to execute

• output_length_limit – Maximum number of lines in output

Yields:

Command output as strings

cleanup()

Clean up the PowerShell session for the current thread. Should be called when work is done or when a session needs to be reset.

bots.tools.terminal_tools._get_active_sessions() → list

Get information about all active PowerShell sessions.

Returns:

List of dictionaries containing session information

bots.tools.terminal_tools._execute_powershell_stateless(code: str, output_length_limit: str = '120')

Executes PowerShell code in a stateless environment

Use when you need to run PowerShell commands and capture their output. If you have other tools available, you should use this as a fallback when the other tools fail. Coerces to utf-8 encoding.

Potential use cases: - git commands - gh cli - other cli (which you may need to install using this tool)

Parameters: - code (str): PowerShell code to execute. - output_length_limit (int, optional): Maximum number of lines in the output.

If set, output exceeding this limit will be truncated. Default 60.

Returns command output or an error message.

bots.tools.terminal_tools._process_commands(code: str) → str

Process PowerShell commands separated by &&, ensuring each command only runs if the previous succeeded. Uses PowerShell error handling to catch both command failures and non-existent commands.

Parameters:

code (str) – The original command string with && separators

Returns:

PowerShell code with proper error checking between commands

Return type:

str

Module contents