toollm 0.1.0

Tools for LLM

Essential tools for LLMs to interact with the real world.

toollm provides command execution, file operations, web scraping, process management, and system monitoring capabilities. Works seamlessly with LLMs.

---

⚠️ Important Warnings

For Development/Testing Only - NOT for Production Use

toollm provides system interaction capabilities, which come with inherent risks:

• CommandRunner: Executes shell commands with basic sandboxing. Assumes LLM-generated commands are trusted. Only defends against accidents, not malicious attacks. Do not use in untrusted environments.

• Fetch: No rate limiting or anti-spider protection. Use responsibly.

• File: Only supports text files. All operations restricted to workdir, but path traversal risks exist.

• Process: Can affect system stability. Use kill operations with extreme caution.

• System: May expose sensitive system information.

These tools are designed for development and testing scenarios where you control the LLM's behavior. Use in production at your own risk.

---

Core Features

🌻 Dual API Design

Use whichever fits your workflow:

# Class API - when you need state and reusability
runner = CommandRunner(workdir="./workspace")
result = runner.execute("ls -la")

# Function API - for stateless calls and AI framework integration
from toollm import execute_command
result = execute_command("ls -la", workdir="./workspace")

• Class API: Perfect for maintaining state and reusing instances
• Function API: Drop-in tools

🌱 Five Essential Tools

CommandRunner - Cross-platform sandboxed command execution

with CommandRunner() as runner:
    result = runner.execute("echo 'Hello!'")
    print(result['stdout'])

Fetch - HTTP requests and web content extraction

fetch = Fetch(workdir="./downloads")
result = fetch.get("https://example.com", format='content')  # Clean text
result = fetch.download("https://example.com/file.pdf")      # Download files

File - Structured file operations with safety boundaries

file_ops = File(workdir="./workspace")
result = file_ops.create_file("test.py", "print('Hello')")
result = file_ops.search_replace("test.py", [{
    'original_text': "Hello",
    'new_text': "Hi there"
}])

Process - Process monitoring and management

proc = Process()
result = proc.list(filter='python', sort_by='cpu')
result = proc.info(pid=1234)

System - System resource information

sys = System()
result = sys.info()      # CPU, memory, uptime
result = sys.disk()      # Disk usage
result = sys.network()   # Network stats

🪴 Structured Returns

Every operation returns a consistent dictionary format:

{
    'success': bool,
    'content': ...,      # Operation result
    'error': str         # Error message (on failure)
}

LLMs can easily parse and handle these responses.

---

Quick Start

Installation

pip install toollm

Execute Commands

from toollm import CommandRunner

# Auto-managed temp directory
with CommandRunner() as runner:
    result = runner.execute("echo 'Hello LLM!'")
    if result['success']:
        print(result['stdout'])

Function style:

from toollm import execute_command

result = execute_command("ls -la", workdir="./workspace")

Fetch Web Content

from toollm import Fetch

fetch = Fetch(workdir="./downloads")

# Get clean text content
result = fetch.get("https://example.com", format='content')

# Get raw HTML
result = fetch.get("https://example.com", format='raw')

# Parse JSON API
result = fetch.get("https://api.example.com/data", format='json')

# Download files
result = fetch.download("https://example.com/file.pdf")

Function style:

from toollm import fetch_url, download_file

result = fetch_url("https://example.com", format='content')
result = download_file("https://example.com/file.pdf", workdir="./downloads")

File Operations

from toollm import File

file_ops = File(workdir="./workspace")

# Create file
file_ops.create_file("test.py", "print('Hello')")

# Read file (with optional line range)
result = file_ops.read_file("test.py")
result = file_ops.read_file("test.py", start_line=1, end_line=5)

# Precise search and replace
file_ops.search_replace("test.py", [
    {
        'original_text': "print('Hello')",
        'new_text': "print('Hello LLM!')",
        'replace_all': False
    }
])

# List files
result = file_ops.list_files(recursive=True)

# Delete file
file_ops.delete_file("test.py")

Function style:

from toollm import read_file, create_file, replace_in_file

read_file("test.py", workdir="./workspace")
create_file("test.py", "print('Hello')", workdir="./workspace")
replace_in_file("test.py", [{'original_text': "Hello", 'new_text': "Hi"}], workdir="./workspace")

Process Management

from toollm import Process

proc = Process()

# List processes (sorted by CPU usage)
result = proc.list(sort_by='cpu')
for p in result['processes'][:10]:
    print(f"{p['name']}: {p['cpu_percent']}%")

# Filter by name
result = proc.list(filter='python', sort_by='memory')

# Get detailed info
result = proc.info(pid=1234)

# Terminate process (use with caution)
result = proc.kill(pid=1234)

Function style:

from toollm import list_processes, get_process_info, kill_process

list_processes(filter='python', sort_by='cpu')
get_process_info(pid=1234)
kill_process(pid=1234)

System Monitoring

from toollm import System

sys = System()

# System information
result = sys.info()
print(f"CPU: {result['cpu_percent']}%")
print(f"Memory: {result['memory_used_gb']}GB / {result['memory_total_gb']}GB")

# Disk usage
result = sys.disk(path="/")
print(f"Disk: {result['used_gb']}GB / {result['total_gb']}GB")

# Network status
result = sys.network()
print(f"Connections: {result['connections']}")
print(f"Sent: {result['bytes_sent_mb']}MB")

# Environment variables
result = sys.env(key='PATH')

Function style:

from toollm import get_system_info, get_disk_usage, get_network_status, get_env_var

get_system_info()
get_disk_usage(path="/")
get_network_status()
get_env_var(key='PATH')

---

Design Principles

• Structured Returns: All operations return consistent dict format with success and error fields
• Safety Boundaries: File operations restricted to workdir, command execution has basic protections
• Cross-Platform: Works on Windows, Linux, and macOS
• Development Focus: Designed for development/testing, not production use

---

Examples

Each module includes a standalone demo:

python -m toollm.cmd       # Command execution examples
python -m toollm.fetch     # Web fetching examples
python -m toollm.file      # File operation examples
python -m toollm.process   # Process management examples
python -m toollm.system    # System monitoring examples

---

Is toollm for You?

If you:

• Need to give LLMs real-world interaction capabilities
• Want simple, structured tool responses
• Are building with LangChain, OpenAI, or other AI frameworks
• Need both class-based and function-based APIs

Then toollm is made for you.

---

License

MIT License - see LICENSE file

Contributing

Issues and Pull Requests are welcome!