Tools

Core

Base classes for tools.

class folderbot.tools.base.ToolResult

Bases: BaseModel

Result of a tool execution.

content: str

is_error: bool

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class folderbot.tools.base.ToolDefinition

Bases: object

A tool definition with its input model.

name: str

description: str

input_model: type

requires_confirmation: bool = False

to_api_format()

Convert to Anthropic API tool format.

Return type:

dict[str, Any]

__init__(name, description, input_model, requires_confirmation=False)

Parameters:

• name (str)

• description (str)

• input_model (type)

• requires_confirmation (bool)

Return type:

None

Central tool registry for folder tools.

class folderbot.tools.registry.FolderServicesProtocol

Bases: Protocol

Protocol for folder tool services/dependencies.

property root: Path

Root folder path.

property config: Any

Configuration object.

property activity_logger: Any

Activity logger instance.

property session_manager: Any | None

Session manager for user preferences.

validate_path(relative_path)

Validate and resolve a path within root folder.

Return type:

Path | None

Parameters:

relative_path (str)

is_file_allowed(rel_path)

Check if file matches include/exclude patterns.

Return type:

bool

Parameters:

rel_path (str)

is_append_allowed(rel_path)

Check if file matches append_allowed patterns.

Return type:

bool

Parameters:

rel_path (str)

__init__(*args, **kwargs)

class folderbot.tools.registry.FolderServices

Bases: object

Concrete implementation of folder services.

root: Path

config: Any

activity_logger: Any

session_manager: Any | None = None

validate_path(relative_path)

Validate a relative path, ensuring it stays within root folder.

Returns the logical (un-resolved) path so that symlinks inside the root folder work transparently. Python’s pathlib follows symlinks automatically for I/O operations (read, write, exists, rglob, etc.). Security is enforced by rejecting .. components and absolute paths.

Return type:

Path | None

Parameters:

relative_path (str)

is_file_allowed(rel_path)

Check if file matches include patterns and not exclude patterns.

Return type:

bool

Parameters:

rel_path (str)

is_append_allowed(rel_path)

Check if file matches append_allowed patterns.

Return type:

bool

Parameters:

rel_path (str)

get_tool_config(tool_name)

Get configuration for a specific tool from [tools.<name>] section.

Return type:

dict[str, Any]

Parameters:

tool_name (str)

__init__(root, config, activity_logger, session_manager=None, _include_spec=None, _exclude_spec=None, _append_spec=None)

Parameters:

• root (Path)

• config (Any)

• activity_logger (Any)

• session_manager (Any | None)

• _include_spec (Any)

• _exclude_spec (Any)

• _append_spec (Any)

Return type:

None

folderbot.tools.registry.get_service(context, key)

Extract a named service from context.

Return type:

Any

Parameters:

• context (BotContext | None)

• key (str)

folderbot.tools.registry.get_services(context)

Extract FolderServices from context.

Return type:

FolderServices | None

Parameters:

context (BotContext | None)

folderbot.tools.registry.get_tool_config(context, tool_name)

Get configuration for a specific tool from context.

Return type:

dict[str, Any]

Parameters:

• context (BotContext | None)

• tool_name (str)

folderbot.tools.registry.get_root(context)

Get root folder from context services.

Return type:

Path | None

Parameters:

context (BotContext | None)

folderbot.tools.registry.validate_path(context, relative_path)

Validate path using context services.

Return type:

Path | None

Parameters:

• context (BotContext | None)

• relative_path (str)

folderbot.tools.registry.is_file_allowed(context, rel_path)

Check if file is allowed using context services.

Return type:

bool

Parameters:

• context (BotContext | None)

• rel_path (str)

folderbot.tools.registry.is_append_allowed(context, rel_path)

Check if append is allowed using context services.

Return type:

bool

Parameters:

• context (BotContext | None)

• rel_path (str)

async folderbot.tools.registry.execute_with_logging(tool_name, tool_input, context=None)

Execute a tool with activity logging.

Return type:

ToolResult

Parameters:

• tool_name (str)

• tool_input (dict[str, Any])

• context (BotContext | None)

FolderTools class for interacting with the configured folder.

class folderbot.tools.folder_tools.FolderTools

Bases: object

Tools for interacting with the configured folder.

This class serves as the main coordinator for tool execution. All tools (file tools, utility tools, web tools, scheduler tools) are registered on the single folder_bot instance and executed through this class.

__init__(config)

Parameters:

config (Config)

set_scheduler(scheduler)

Set the scheduler reference for tool execution.

Return type:

None

Parameters:

scheduler (TaskScheduler)

set_session_manager(session_manager)

Set the session manager reference for user preferences.

Return type:

None

Parameters:

session_manager (SessionManager)

set_upload_services(upload_services)

Set the upload services for upload tools.

Return type:

None

Parameters:

upload_services (UploadServices)

create_context(user_id=0, chat_id=0)

Create a BotContext with services configured.

This is the preferred way to create a context for tool execution. The context includes FolderServices and SchedulerServices which provide access to folder operations and task scheduling.

Return type:

BotContext

Parameters:

• user_id (int)

• chat_id (int)

get_tool_definitions()

Return tool definitions for the Claude API.

Return type:

list[dict[str, Any]]

get_tools_requiring_confirmation()

Return names of tools that require user confirmation before use.

Return type:

list[str]

execute(tool_name, tool_input, user_id=0)

Execute a tool synchronously (wraps async execute for compatibility).

Return type:

ToolResult

Parameters:

• tool_name (str)

• tool_input (dict[str, Any])

• user_id (int)

execute_direct(tool_name, tool_input, user_id=0)

Execute a tool directly (alias for execute).

Return type:

ToolResult

Parameters:

• tool_name (str)

• tool_input (dict[str, Any])

• user_id (int)

async execute_async(tool_name, tool_input, context, chat_id=0)

Execute a tool asynchronously with the given context.

Parameters:

• tool_name (str) – Name of the tool to execute

• tool_input (dict[str, Any]) – Input parameters for the tool

• context (BotContext) – BotContext with user info and services

• chat_id (int) – Telegram chat ID (for scheduler tools)

Return type:

ToolResult

Returns:

ToolResult with the execution result

property activity_logger: ActivityLogger

Expose activity logger for external use.

File Tools

List files tool.

class folderbot.tools.list_files.ListFilesRequest

Bases: BaseModel

Request for listing files in a directory.

path: str

pattern: str

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.list_files.list_files(request, _context=None)

List files in the folder or a subfolder.

Returns file paths relative to the root folder. Use this to discover what files are available before reading them.

Return type:

ToolResult

Parameters:

• request (ListFilesRequest)

• _context (BotContext | None)

Read file tool.

class folderbot.tools.read_file.ReadFileRequest

Bases: BaseModel

Request for reading a file.

path: str

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.read_file.read_file(request, _context=None)

Read the contents of a specific file.

The path must be relative to the root folder. Use list_files first to discover available files.

Return type:

ToolResult

Parameters:

• request (ReadFileRequest)

• _context (BotContext | None)

Write file tool.

class folderbot.tools.write_file.WriteMode

Bases: str, Enum

Write mode for file operations.

overwrite = 'overwrite'

append = 'append'

__new__(value)

class folderbot.tools.write_file.WriteFileRequest

Bases: BaseModel

Request for writing a file.

path: str

content: str

mode: WriteMode

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.write_file.write_file(request, _context=None)

Create or update a file in the folder.

The file path must satisfy the configured include rules. Use this to help the user manage their notes, todos, and documentation.

Return type:

ToolResult

Parameters:

• request (WriteFileRequest)

• _context (BotContext | None)

Search files tool.

class folderbot.tools.search_files.SearchFilesRequest

Bases: BaseModel

Request for searching files.

query: str

max_results: int

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.search_files.search_files(request, _context=None)

Search for text content across all files in the folder.

Returns matching file paths and relevant excerpts. Useful for finding files containing specific keywords.

Return type:

ToolResult

Parameters:

• request (SearchFilesRequest)

• _context (BotContext | None)

Web Tools

Web search tool using Google Custom Search API.

class folderbot.tools.web_search.WebSearchRequest

Bases: BaseModel

Request for searching the web.

query: str

max_results: int

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.web_search.web_search(request, _context=None)

Search the web using Google.

Returns titles, URLs, and snippets for the top results. Use this to find information online.

Return type:

ToolResult

Parameters:

• request (WebSearchRequest)

• _context (BotContext | None)

folderbot.tools.web_search.is_available()

Check if web search is available (always True — uses httpx which is a core dep).

Return type:

bool

Web fetch tool.

class folderbot.tools.web_fetch.WebFetchRequest

Bases: BaseModel

Request for fetching content from a URL.

url: str

max_chars: int

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.web_fetch.web_fetch(request, _context=None)

Fetch and extract text content from a URL.

Returns the main text content of the page, stripping HTML. Use this to read articles, documentation, or other web pages.

Return type:

ToolResult

Parameters:

• request (WebFetchRequest)

• _context (BotContext | None)

folderbot.tools.web_fetch.is_available()

Check if web fetch is available.

Return type:

bool

Weather forecast tool via Open-Meteo (free, no API key).

class folderbot.tools.weather.GetWeatherRequest

Bases: BaseModel

Request for getting weather forecast.

latitude: float

longitude: float

forecast_days: int

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.weather.get_weather(request, _context=None)

Get current weather and forecast for a location.

Requires latitude and longitude — use ask_user with input_type ‘location’ to get the user’s coordinates if not known.

Return type:

ToolResult

Parameters:

• request (GetWeatherRequest)

• _context (BotContext | None)

Scheduler Tools

Scheduler tools for scheduling and managing background tasks.

These tools are registered on the central folder_bot instance and executed asynchronously through SchedulerServices.

class folderbot.tools.scheduler_tools.TaskStepInput

Bases: BaseModel

A single tool call within a task.

tool_name: str

tool_input: dict[str, Any]

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class folderbot.tools.scheduler_tools.ScheduleTaskRequest

Bases: BaseModel

Request for scheduling a new task.

description: str

steps: list[TaskStepInput]

schedule_type: str

delay_seconds: int

interval_seconds: int

cron_expression: str

duration_seconds: int

max_iterations: int

summarize_on_complete: bool

progress_interval: int

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class folderbot.tools.scheduler_tools.ListTasksRequest

Bases: BaseModel

Request for listing scheduled tasks.

status_filter: str

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class folderbot.tools.scheduler_tools.CancelTaskRequest

Bases: BaseModel

Request for cancelling a scheduled task.

task_id: str

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class folderbot.tools.scheduler_tools.GetTaskResultsRequest

Bases: BaseModel

Request for getting results of a task.

task_id: str

last_n: int

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class folderbot.tools.scheduler_tools.SchedulerServices

Bases: object

Services for scheduler tool execution.

This class wraps the TaskScheduler and provides async handlers for scheduler tools. It’s stored in BotContext.services[“scheduler”].

scheduler: TaskScheduler

chat_id: int = 0

async schedule_task(request, context)

Schedule a new task.

Return type:

ToolResult

Parameters:

• request (ScheduleTaskRequest)

• context (BotContext | None)

async list_tasks(request, context)

List scheduled tasks.

Return type:

ToolResult

Parameters:

• request (ListTasksRequest)

• context (BotContext | None)

async cancel_task(request, context)

Cancel a scheduled task.

Return type:

ToolResult

Parameters:

• request (CancelTaskRequest)

• context (BotContext | None)

async get_task_results(request, context)

Get results of a scheduled task.

Return type:

ToolResult

Parameters:

• request (GetTaskResultsRequest)

• context (BotContext | None)

__init__(scheduler, chat_id=0)

Parameters:

• scheduler (TaskScheduler)

• chat_id (int)

Return type:

None

async folderbot.tools.scheduler_tools.schedule_task(request, _context=None)

Schedule a task to be executed later or repeatedly.

Return type:

ToolResult

Parameters:

• request (ScheduleTaskRequest)

• _context (BotContext | None)

async folderbot.tools.scheduler_tools.list_tasks(request, _context=None)

List all scheduled tasks.

Return type:

ToolResult

Parameters:

• request (ListTasksRequest)

• _context (BotContext | None)

async folderbot.tools.scheduler_tools.cancel_task(request, _context=None)

Cancel a scheduled task.

Return type:

ToolResult

Parameters:

• request (CancelTaskRequest)

• _context (BotContext | None)

async folderbot.tools.scheduler_tools.get_task_results(request, _context=None)

Get results of a scheduled task.

Return type:

ToolResult

Parameters:

• request (GetTaskResultsRequest)

• _context (BotContext | None)

Upload Tools

Upload management tools for listing, deleting, and resending uploaded files.

class folderbot.tools.upload_tools.UploadServices

Bases: object

Services for upload tools.

session_manager: SessionManager

uploads_dir: Path

send_document: Callable[[int, Path, str], Awaitable[None]]

chat_id: int = 0

__init__(session_manager, uploads_dir, send_document, chat_id=0)

Parameters:

• session_manager (SessionManager)

• uploads_dir (Path)

• send_document (Callable[[int, Path, str], Awaitable[None]])

• chat_id (int)

Return type:

None

class folderbot.tools.upload_tools.ListUploadsRequest

Bases: BaseModel

Request for listing uploaded files.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.upload_tools.list_uploads(request, _context=None)

List all files the user has uploaded.

Returns a list of uploaded files with their ID, original filename, size, and upload date.

Return type:

ToolResult

Parameters:

• request (ListUploadsRequest)

• _context (BotContext | None)

class folderbot.tools.upload_tools.DeleteUploadRequest

Bases: BaseModel

Request for deleting an uploaded file.

upload_id: int

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.upload_tools.delete_upload(request, _context=None)

Delete an uploaded file by its ID.

Removes the file from disk and the database record. Use list_uploads first to find the upload ID.

Return type:

ToolResult

Parameters:

• request (DeleteUploadRequest)

• _context (BotContext | None)

class folderbot.tools.upload_tools.SendUploadRequest

Bases: BaseModel

Request for sending an uploaded file back to the user.

upload_id: int

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.upload_tools.send_upload(request, _context=None)

Send an uploaded file back to the user in the chat.

Use list_uploads first to find the upload ID.

Return type:

ToolResult

Parameters:

• request (SendUploadRequest)

• _context (BotContext | None)

Topic Tools

Topic reorganization tools.

class folderbot.tools.topic_tools.TopicAssignment

Bases: BaseModel

A single message-to-topic assignment.

message_index: int

topic: str

classmethod normalize_topic(v)

Return type:

str

Parameters:

v (str)

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class folderbot.tools.topic_tools.GetFullHistoryRequest

Bases: BaseModel

Request to get the full conversation history with message indices.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.topic_tools.get_full_history(request, _context=None)

Get the full conversation history with message indices and current topics.

Returns all messages numbered by index. Use this before calling reorganize_topics to see what needs to be reassigned.

Return type:

ToolResult

Parameters:

• request (GetFullHistoryRequest)

• _context (BotContext | None)

class folderbot.tools.topic_tools.ReorganizeTopicsRequest

Bases: BaseModel

Request to reassign topic labels on conversation messages.

assignments: list[TopicAssignment]

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.topic_tools.reorganize_topics(request, _context=None)

Reassign topic labels on conversation messages.

Use this when the user asks to re-split, reorganize, or rename their conversation topics. First use get_full_history to see all messages with their indices, then call this tool with the new assignments.

Return type:

ToolResult

Parameters:

• request (ReorganizeTopicsRequest)

• _context (BotContext | None)

Utility Tools

Utility tools for common operations.

class folderbot.tools.utils.GetTimeRequest

Bases: BaseModel

Request for getting current time.

timezone: str

format: str

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.utils.get_time(request, _context=None)

Get the current date and time. Useful for knowing what day/time it is.

Return type:

ToolResult

Parameters:

• request (GetTimeRequest)

• _context (BotContext | None)

class folderbot.tools.utils.CompareNumbersRequest

Bases: BaseModel

Request for comparing two numbers.

a: float

b: float

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.utils.compare_numbers(request, _context=None)

Compare two numbers. Returns which is greater, lesser, or if equal.

Return type:

ToolResult

Parameters:

• request (CompareNumbersRequest)

• _context (BotContext | None)

class folderbot.tools.utils.ShuffleListRequest

Bases: BaseModel

Request for shuffling a list.

items: list[str]

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.utils.shuffle_list(request, _context=None)

Randomly shuffle a list of items.

Return type:

ToolResult

Parameters:

• request (ShuffleListRequest)

• _context (BotContext | None)

class folderbot.tools.utils.SortListRequest

Bases: BaseModel

Request for sorting a list.

items: list[str | float]

reverse: bool

numeric: bool

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.utils.sort_list(request, _context=None)

Sort a list of items alphabetically or numerically.

Return type:

ToolResult

Parameters:

• request (SortListRequest)

• _context (BotContext | None)

class folderbot.tools.utils.RandomChoiceRequest

Bases: BaseModel

Request for picking random items.

items: list[str]

count: int

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.utils.random_choice(request, _context=None)

Pick random item(s) from a list.

Return type:

ToolResult

Parameters:

• request (RandomChoiceRequest)

• _context (BotContext | None)

class folderbot.tools.utils.RandomNumberRequest

Bases: BaseModel

Request for generating a random number.

min: float

max: float

integer: bool

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.utils.random_number(request, _context=None)

Generate a random number within a range.

Return type:

ToolResult

Parameters:

• request (RandomNumberRequest)

• _context (BotContext | None)

class folderbot.tools.utils.SendMessageRequest

Bases: BaseModel

Request for sending a message to the user.

message: str

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.utils.send_message(request, _context=None)

Send a message directly to the user via Telegram.

Use this in scheduled tasks to send notifications, greetings, reminders, or any other message to the user. The message is sent exactly as provided — no template interpolation.

Return type:

ToolResult

Parameters:

• request (SendMessageRequest)

• _context (BotContext | None)

class folderbot.tools.utils.ListTopicsRequest

Bases: BaseModel

Request for listing conversation topics.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.utils.list_topics(request, _context=None)

List active conversation topics for the current user.

Shows all topics with message counts and last activity. Use this when the user asks about their active conversations or threads.

Return type:

ToolResult

Parameters:

• request (ListTopicsRequest)

• _context (BotContext | None)

Activity Log

Activity logging with structured entries and rotation.

class folderbot.tools.activity_log.ReadActivityLogRequest

Bases: BaseModel

Request for reading the activity log.

last_n: int

tool_filter: str

date: str

search: str

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async folderbot.tools.activity_log.read_activity_log(request, _context=None)

Read the bot’s activity log to see what tools were actually used.

Shows when tasks were scheduled, and message history. Use this to verify whether actions were actually performed or to debug issues.

Return type:

ToolResult

Parameters:

• request (ReadActivityLogRequest)

• _context (BotContext | None)

class folderbot.tools.activity_log.ActivityLogger

Bases: object

Logs tool activity to structured JSON files with rotation.

MAX_DAYS_TO_KEEP = 30

__init__(root_folder)

Parameters:

root_folder (Path)

log_tool_call(tool_name, tool_input, result, is_error, user_id, duration_ms=0)

Log a tool call with structured data.

Return type:

None

Parameters:

• tool_name (str)

• tool_input (dict[str, Any])

• result (str)

• is_error (bool)

• user_id (int)

• duration_ms (int)

log_message(direction, content, user_id, tools_used=None)

Log a message exchange.

Return type:

None

Parameters:

• direction (str)

• content (str)

• user_id (int)

• tools_used (list[str] | None)

log_task_event(event, task_id, description, user_id, details=None)

Log a scheduler task event.

Return type:

None

Parameters:

• event (str)

• task_id (str)

• description (str)

• user_id (int)

• details (dict[str, Any] | None)

read_log(last_n=20, tool_filter='', date='', search='')

Read and filter log entries, returning human-readable format.

Return type:

str

Parameters:

• last_n (int)

• tool_filter (str)

• date (str)

• search (str)

get_available_dates()

Return list of dates that have log files.

Return type:

list[str]