calute.tools.system_tools

calute.tools.system_tools#

System and environment tools for interacting with the operating system.

This module provides a collection of system tools for agents to interact with the operating system and environment. It includes: - System information retrieval (OS, CPU, memory, disk, network) - Process management and monitoring - File system operations (copy, move, delete, search) - Environment variable management - Temporary file and directory handling

All tools provide comprehensive error handling and return structured dictionaries with operation results and error information.

Example

>>> info = SystemInfo.static_call(info_type="cpu")
>>> print(f"CPU cores: {info['cpu']['logical_cores']}")

class calute.tools.system_tools.EnvironmentManager(name, bases, namespace, /, **kwargs)[source]#

Bases: AgentBaseFn

Manage environment variables and settings.

Provides operations for getting, setting, listing, and removing environment variables. Includes filtering capabilities and automatic listing of commonly important environment variables.

Changes to environment variables affect only the current process and its child processes.

Inherits from AgentBaseFn for agent integration.

Example

>>> result = EnvironmentManager.static_call(
...     operation="get",
...     key="PATH"
... )
>>> print(result["value"])

static static_call(operation: str, key: str | None = None, value: str | None = None, **context_variables) → dict[str, Any][source]#

Manage environment variables.

Performs operations on environment variables within the current process scope.

Parameters

operation – Operation to perform: - “get”: Get value of specific variable - “set”: Set a variable to a value - “list”: List environment variables (filtered or common) - “remove”: Remove an environment variable
key – Environment variable name (required for get/set/remove). For list, used as prefix filter.
value – Value to set (required for set operation).
**context_variables – Additional context passed from the agent.

Returns

get: key, value, exists
set: success, key, value
list: environment dict, count
remove: success, removed key
error: Error message if operation failed

Return type

Dictionary containing operation-specific results

Note

Environment changes are process-scoped and do not persist after the program exits.

class calute.tools.system_tools.FileSystemTools(name, bases, namespace, /, **kwargs)[source]#

Bases: AgentBaseFn

Advanced file system operations.

Provides comprehensive file system operations including copying, moving, deleting files and directories, searching with patterns, getting detailed file information, and generating directory trees.

Supports recursive operations and pattern-based file searching using glob patterns.

Inherits from AgentBaseFn for agent integration.

Example

>>> result = FileSystemTools.static_call(
...     operation="search",
...     path="./src",
...     pattern="*.py",
...     recursive=True
... )
>>> print(f"Found {result['count']} Python files")

static static_call(operation: str, path: str | None = None, destination: str | None = None, pattern: str | None = None, recursive: bool = False, **context_variables) → dict[str, Any][source]#

Perform file system operations.

Executes various file system operations with support for recursive operations and pattern matching.

Parameters

operation – Operation to perform: - “copy”: Copy file or directory - “move”: Move file or directory - “delete”: Delete file or directory - “search”: Search for files matching pattern - “info”: Get detailed file/directory information - “tree”: Generate directory tree structure
path – Source path (required for most operations).
destination – Destination path (for copy/move operations).
pattern – Glob pattern for search (e.g., “.py”, “*/*.txt”).
recursive – Whether to operate recursively (default: False).
**context_variables – Additional context passed from the agent.

Returns

copy/move: success, source, destination
delete: success, deleted path
search: matches list, count
info: path, exists, is_file, is_dir, size, timestamps
tree: nested directory tree structure
error: Error message if operation failed

Return type

Dictionary containing operation-specific results

class calute.tools.system_tools.ProcessManager(name, bases, namespace, /, **kwargs)[source]#

Bases: AgentBaseFn

Manage and monitor system processes.

Provides process management capabilities including listing, finding, inspecting, running commands, and terminating processes. Uses psutil for cross-platform process management.

Supports graceful termination with fallback to force kill, and provides detailed process information including resource usage.

Inherits from AgentBaseFn for agent integration.

Example

>>> result = ProcessManager.static_call(
...     operation="find",
...     process_name="python"
... )
>>> print(f"Found {result['count']} Python processes")

static static_call(operation: str, process_name: str | None = None, pid: int | None = None, command: str | None = None, limit: int = 20, **context_variables) → dict[str, Any][source]#

Manage system processes.

Performs various process management operations including listing, finding, getting detailed info, killing, and running processes.

Parameters

operation – Operation to perform: - “list”: List top processes by CPU usage - “find”: Find processes by name - “info”: Get detailed process information by PID - “kill”: Terminate a process by PID - “run”: Execute a shell command
process_name – Name of process to find (for find operation).
pid – Process ID (for info and kill operations).
command – Shell command to run (for run operation).
limit – Maximum number of processes to return (default: 20).
**context_variables – Additional context passed from the agent.

Returns

list: processes list with pid, name, cpu_percent, memory_percent
find: found list with matching processes
info: detailed process info including memory, threads, cmdline
kill: status, pid, name, message
run: completed, returncode, stdout, stderr
error: Error message if operation failed

Return type

Dictionary containing operation-specific results

class calute.tools.system_tools.SystemInfo(name, bases, namespace, /, **kwargs)[source]#

Bases: AgentBaseFn

Get system and environment information.

Provides comprehensive system information retrieval capabilities including operating system details, CPU metrics, memory usage, disk space, and network interface information.

Uses the psutil library for cross-platform system monitoring and the platform module for OS-level information.

Inherits from AgentBaseFn for agent integration.

Example

>>> result = SystemInfo.static_call(info_type="memory")
>>> print(f"Available: {result['memory']['available_gb']} GB")

static static_call(info_type: str = 'all', **context_variables) → dict[str, Any][source]#

Get system information.

Retrieves various types of system information based on the requested info_type. Can retrieve all categories or specific subsets for efficiency.

Parameters

info_type – Type of information to retrieve. Options: - “all”: All available system information - “os”: Operating system and Python version - “cpu”: CPU cores, usage, and frequency - “memory”: RAM usage and availability - “disk”: Disk usage and partitions - “network”: Network interfaces and addresses
**context_variables – Additional context passed from the agent.

Returns

os: System, release, version, machine, processor, python_version
cpu: Physical/logical cores, usage_percent, frequency
memory: Total, available, used, percent (in bytes and GB)
disk: Total, used, free, percent, partitions list
network: Hostname, interfaces with addresses

Return type

Dictionary containing requested system information

class calute.tools.system_tools.TempFileManager(name, bases, namespace, /, **kwargs)[source]#

Bases: AgentBaseFn

Create and manage temporary files and directories.

Provides functionality for creating temporary files and directories with optional content, custom prefixes/suffixes, and cleanup operations for Calute-created temporary files.

Uses the system’s default temporary directory and provides options for automatic or manual cleanup.

Inherits from AgentBaseFn for agent integration.

Example

>>> result = TempFileManager.static_call(
...     operation="create_file",
...     content="temporary data",
...     suffix=".txt"
... )
>>> print(result["path"])

static static_call(operation: str, content: str | None = None, suffix: str | None = None, prefix: str | None = None, cleanup: bool = True, **context_variables) → dict[str, Any][source]#

Manage temporary files and directories.

Creates temporary files or directories in the system temp directory, or cleans up previously created Calute temp files.

Parameters

operation – Operation to perform: - “create_file”: Create a temporary file - “create_dir”: Create a temporary directory - “cleanup”: Remove all Calute temp files/directories
content – Content to write to temporary file (optional).
suffix – File extension/suffix (e.g., “.txt”, “.json”).
prefix – Filename prefix (default: “calute_”).
cleanup – Whether to mark for automatic cleanup (default: True).
**context_variables – Additional context passed from the agent.

Returns

create_file: path, exists, size
create_dir: path, exists
cleanup: temp_dir, found, deleted, failed, deleted_count
error: Error message if operation failed

Return type

Dictionary containing operation-specific results

Note

Files created with cleanup=False will persist after program exit. The cleanup operation only removes files with “calute_” prefix.

calute.tools.system_tools

Contents

calute.tools.system_tools#