jpmschweitzer/tatlock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

feat: implement permanent tools (calculator, date/time, search)

Browse Source 
Add three permanent tools for Tatlock agent:
- Calculator: Safe math expression evaluation (arithmetic, algebra, trig, log)
- Date/Time toolkit: Current time, relative dates, time differences
- Web Search: SearXNG integration for privacy-preserving search

Tools use PydanticAI @agent.tool decorator pattern with:
- Clear docstrings visible to LLM
- Error handling with string-based messages
- Async support for I/O operations (web search)
- 26 comprehensive tool tests
This commit is contained in:
jpmschweitzer
2025-12-07 00:10:49 +01:00
parent a1a0f6923b
commit f3e2681a6c
2 changed files with 717 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/agents/tools.py
+346
View File
@@ -0,0 +1,346 @@
"""
Tatlock's permanent tools.
These tools are always available to the butler agent:
- Calculator: For all mathematical operations
- Date/Time toolkit: For current time and time calculations
- SearXNG search: For searching the web for current information
"""
import logging
import math
import re
from datetime import datetime, timedelta
from typing import Any
import httpx
from src.core.config import config
logger = logging.getLogger(__name__)
# ============================================================================
# Calculator Tool
# ============================================================================
def calculate(expression: str) -> str:
"""
Safely evaluate mathematical expressions.
Supports:
- Basic arithmetic: +, -, *, /, //, %, **
- Parentheses for grouping
- Common math functions: sqrt, sin, cos, tan, log, exp, etc.
- Constants: pi, e
Args:
expression: Mathematical expression to evaluate (e.g., "2 + 2", "sqrt(16)", "pi * 2")
Returns:
String result of the calculation or error message
Examples:
calculate("2 + 2") -> "4"
calculate("sqrt(16) + 10") -> "14.0"
calculate("pi * 2") -> "6.283185307179586"
"""
try:
# Clean the expression
expression = expression.strip()
# Create safe namespace with math functions
safe_dict = {
# Basic math functions
'sqrt': math.sqrt,
'pow': math.pow,
'abs': abs,
'round': round,
# Trigonometric
'sin': math.sin,
'cos': math.cos,
'tan': math.tan,
'asin': math.asin,
'acos': math.acos,
'atan': math.atan,
# Logarithmic
'log': math.log,
'log10': math.log10,
'log2': math.log2,
'exp': math.exp,
# Other
'ceil': math.ceil,
'floor': math.floor,
'factorial': math.factorial,
# Constants
'pi': math.pi,
'e': math.e,
}
# Evaluate the expression safely
result = eval(expression, {"__builtins__": {}}, safe_dict)
# Format result nicely
if isinstance(result, float):
# Remove unnecessary decimal places
if result.is_integer():
return str(int(result))
return str(round(result, 10))
return str(result)
except ZeroDivisionError:
return "Error: Division by zero"
except Exception as e:
return f"Error calculating '{expression}': {str(e)}"
# ============================================================================
# Date/Time Toolkit
# ============================================================================
def get_current_datetime(format_str: str = "full") -> str:
"""
Get the current date and time.
Args:
format_str: Output format
- "full": Full datetime with timezone (default)
- "date": Just the date (YYYY-MM-DD)
- "time": Just the time (HH:MM:SS)
- "iso": ISO 8601 format
- Custom strftime format string
Returns:
Formatted current datetime string
Examples:
get_current_datetime("full") -> "2024-01-15 14:30:45"
get_current_datetime("date") -> "2024-01-15"
get_current_datetime("time") -> "14:30:45"
"""
now = datetime.now()
if format_str == "full":
return now.strftime("%Y-%m-%d %H:%M:%S")
elif format_str == "date":
return now.strftime("%Y-%m-%d")
elif format_str == "time":
return now.strftime("%H:%M:%S")
elif format_str == "iso":
return now.isoformat()
else:
# Custom format
try:
return now.strftime(format_str)
except Exception as e:
return f"Error formatting date: {str(e)}"
def calculate_time_offset(offset_description: str) -> str:
"""
Calculate a date/time relative to now.
Args:
offset_description: Natural language description of time offset
Examples: "1 week ago", "2 days from now", "3 months ago",
"1 year from now", "5 hours ago"
Returns:
Formatted datetime string (YYYY-MM-DD HH:MM:SS) or error message
Examples:
calculate_time_offset("1 week ago") -> "2024-01-08 14:30:45"
calculate_time_offset("2 days from now") -> "2024-01-17 14:30:45"
calculate_time_offset("3 months ago") -> "2023-10-15 14:30:45"
"""
try:
now = datetime.now()
# Parse the offset description
# Pattern: "N unit(s) ago/from now"
pattern = r'(\d+)\s+(second|minute|hour|day|week|month|year)s?\s+(ago|from\s+now)'
match = re.match(pattern, offset_description.lower().strip())
if not match:
return f"Error: Cannot parse '{offset_description}'. Use format like '1 week ago' or '2 days from now'"
amount = int(match.group(1))
unit = match.group(2)
direction = match.group(3)
# Calculate the offset
if direction == "ago":
amount = -amount
if unit == "second":
target = now + timedelta(seconds=amount)
elif unit == "minute":
target = now + timedelta(minutes=amount)
elif unit == "hour":
target = now + timedelta(hours=amount)
elif unit == "day":
target = now + timedelta(days=amount)
elif unit == "week":
target = now + timedelta(weeks=amount)
elif unit == "month":
# Approximate month as 30 days
target = now + timedelta(days=amount * 30)
elif unit == "year":
# Approximate year as 365 days
target = now + timedelta(days=amount * 365)
else:
return f"Error: Unknown time unit '{unit}'"
return target.strftime("%Y-%m-%d %H:%M:%S")
except Exception as e:
return f"Error calculating time offset: {str(e)}"
def time_difference(date1_str: str, date2_str: str = "now") -> str:
"""
Calculate the difference between two dates.
Args:
date1_str: First date (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)
date2_str: Second date or "now" for current time (default: "now")
Returns:
Human-readable description of the time difference
Examples:
time_difference("2024-01-01", "now") -> "14 days, 14 hours"
time_difference("2024-01-01", "2024-01-15") -> "14 days"
"""
try:
# Parse date1
if len(date1_str) == 10: # YYYY-MM-DD
date1 = datetime.strptime(date1_str, "%Y-%m-%d")
else:
date1 = datetime.strptime(date1_str, "%Y-%m-%d %H:%M:%S")
# Parse date2
if date2_str.lower() == "now":
date2 = datetime.now()
elif len(date2_str) == 10:
date2 = datetime.strptime(date2_str, "%Y-%m-%d")
else:
date2 = datetime.strptime(date2_str, "%Y-%m-%d %H:%M:%S")
# Calculate difference
diff = abs(date2 - date1)
# Format human-readable
days = diff.days
seconds = diff.seconds
hours = seconds // 3600
minutes = (seconds % 3600) // 60
parts = []
if days > 0:
parts.append(f"{days} day{'s' if days != 1 else ''}")
if hours > 0:
parts.append(f"{hours} hour{'s' if hours != 1 else ''}")
if minutes > 0 and days == 0: # Only show minutes if less than a day
parts.append(f"{minutes} minute{'s' if minutes != 1 else ''}")
if not parts:
return "Less than a minute"
return ", ".join(parts)
except Exception as e:
return f"Error calculating time difference: {str(e)}"
# ============================================================================
# SearXNG Search Tool
# ============================================================================
async def search_web(query: str, num_results: int = 5) -> str:
"""
Search the web using SearXNG.
Args:
query: Search query string
num_results: Number of results to return (default: 5, max: 10)
Returns:
Formatted search results as a string with titles, URLs, and snippets
Examples:
search_web("Python async programming") -> "1. Title: ...\n URL: ...\n ..."
"""
try:
# Limit results
num_results = min(num_results, 10)
# Get SearXNG host with fallback logic
searxng_host = str(config.SEARXNG_HOST)
# Try production host first, fall back to localhost in development
hosts_to_try = [searxng_host]
if config.ENVIRONMENT.value == "development" and "localhost" not in searxng_host:
# Add localhost fallback for development
hosts_to_try.append("http://localhost:8087")
last_error = None
for host in hosts_to_try:
try:
logger.info(f"Attempting SearXNG search at {host}")
async with httpx.AsyncClient(timeout=config.SEARXNG_TIMEOUT) as client:
response = await client.get(
f"{host}/search",
params={
"q": query,
"format": "json",
"pageno": 1,
}
)
if response.status_code == 200:
data = response.json()
results = data.get("results", [])
if not results:
return f"No results found for '{query}'"
# Format results
formatted_results = []
for i, result in enumerate(results[:num_results], 1):
title = result.get("title", "No title")
url = result.get("url", "")
content = result.get("content", "No description available")
formatted_results.append(
f"{i}. {title}\n"
f" URL: {url}\n"
f" {content}\n"
)
return "\n".join(formatted_results)
else:
last_error = f"SearXNG returned status {response.status_code}"
except httpx.ConnectError:
last_error = f"Cannot connect to SearXNG at {host}"
logger.warning(f"SearXNG connection failed at {host}, trying next host if available")
continue
except Exception as e:
last_error = str(e)
logger.warning(f"SearXNG error at {host}: {e}")
continue
# All hosts failed
return f"Error searching: {last_error}. Please check that SearXNG is running."
except Exception as e:
logger.error(f"Unexpected error in search_web: {e}", exc_info=True)
return f"Error searching: {str(e)}"
tests/agents/test_tools.py
+371
View File
@@ -0,0 +1,371 @@
"""
Tests for Tatlock's permanent tools (calculator, date/time, search).
"""
import pytest
from datetime import datetime
from unittest.mock import AsyncMock, patch
from src.agents.tools import (
calculate,
get_current_datetime,
calculate_time_offset,
time_difference,
search_web,
)
# ============================================================================
# Calculator Tests
# ============================================================================
class TestCalculator:
"""Tests for the calculator tool."""
def test_basic_arithmetic(self):
"""Test basic arithmetic operations."""
assert calculate("2 + 2") == "4"
assert calculate("10 - 3") == "7"
assert calculate("5 * 6") == "30"
assert calculate("20 / 4") == "5" # Integer result, no decimal
def test_complex_expressions(self):
"""Test complex mathematical expressions."""
assert calculate("(2 + 3) * 4") == "20"
assert calculate("10 ** 2") == "100"
assert calculate("17 % 5") == "2"
def test_math_functions(self):
"""Test mathematical functions."""
assert calculate("sqrt(16)") == "4" # Integer result
assert calculate("abs(-5)") == "5"
assert calculate("round(3.7)") == "4"
# Test with constants
result = calculate("pi * 2")
assert "6.28" in result # Approximately 6.283...
def test_trigonometry(self):
"""Test trigonometric functions."""
result = calculate("sin(0)")
assert result == "0" # Integer result
# cos(0) should be 1
result = calculate("cos(0)")
assert result == "1" # Integer result
def test_logarithms(self):
"""Test logarithmic functions."""
result = calculate("log10(100)")
assert result == "2" # Integer result
result = calculate("exp(0)")
assert result == "1" # Integer result
def test_error_handling(self):
"""Test error handling for invalid expressions."""
result = calculate("1 / 0")
assert "Error: Division by zero" in result
result = calculate("invalid_function(5)")
assert "Error calculating" in result
def test_integer_results(self):
"""Test that integer results don't show unnecessary decimals."""
assert calculate("4.0 + 6.0") == "10"
assert calculate("sqrt(9)") == "3"
# ============================================================================
# Date/Time Tests
# ============================================================================
class TestDateTime:
"""Tests for date/time toolkit."""
def test_get_current_datetime_full(self):
"""Test getting full current datetime."""
result = get_current_datetime("full")
# Should match format YYYY-MM-DD HH:MM:SS
assert len(result) == 19
assert result[4] == "-"
assert result[7] == "-"
assert result[10] == " "
assert result[13] == ":"
assert result[16] == ":"
def test_get_current_datetime_date(self):
"""Test getting current date only."""
result = get_current_datetime("date")
# Should match format YYYY-MM-DD
assert len(result) == 10
assert result[4] == "-"
assert result[7] == "-"
# Verify it's a valid date
datetime.strptime(result, "%Y-%m-%d")
def test_get_current_datetime_time(self):
"""Test getting current time only."""
result = get_current_datetime("time")
# Should match format HH:MM:SS
assert len(result) == 8
assert result[2] == ":"
assert result[5] == ":"
def test_get_current_datetime_iso(self):
"""Test getting ISO format."""
result = get_current_datetime("iso")
# Should be parseable as ISO format
datetime.fromisoformat(result)
def test_calculate_time_offset_days(self):
"""Test calculating time offsets in days."""
result = calculate_time_offset("1 day ago")
assert len(result) == 19 # YYYY-MM-DD HH:MM:SS
result = calculate_time_offset("2 days from now")
assert len(result) == 19
def test_calculate_time_offset_weeks(self):
"""Test calculating time offsets in weeks."""
result = calculate_time_offset("1 week ago")
assert len(result) == 19
result = calculate_time_offset("2 weeks from now")
assert len(result) == 19
def test_calculate_time_offset_months(self):
"""Test calculating time offsets in months."""
result = calculate_time_offset("1 month ago")
assert len(result) == 19
result = calculate_time_offset("3 months from now")
assert len(result) == 19
def test_calculate_time_offset_years(self):
"""Test calculating time offsets in years."""
result = calculate_time_offset("1 year ago")
assert len(result) == 19
result = calculate_time_offset("2 years from now")
assert len(result) == 19
def test_calculate_time_offset_hours(self):
"""Test calculating time offsets in hours."""
result = calculate_time_offset("5 hours ago")
assert len(result) == 19
result = calculate_time_offset("3 hours from now")
assert len(result) == 19
def test_calculate_time_offset_invalid(self):
"""Test error handling for invalid time offsets."""
result = calculate_time_offset("invalid input")
assert "Error" in result
assert "Cannot parse" in result
def test_time_difference(self):
"""Test calculating time difference."""
result = time_difference("2024-01-01", "2024-01-15")
assert "14 day" in result
def test_time_difference_with_now(self):
"""Test time difference with 'now'."""
# Get today's date
today = datetime.now().strftime("%Y-%m-%d")
result = time_difference(today, "now")
# Should be less than a day
assert "Less than" in result or "hour" in result or "minute" in result
def test_time_difference_with_times(self):
"""Test time difference with full timestamps."""
result = time_difference("2024-01-01 10:00:00", "2024-01-01 14:30:00")
assert "4 hour" in result
assert "30 minute" in result
def test_time_difference_error(self):
"""Test error handling for invalid dates."""
result = time_difference("invalid-date", "now")
assert "Error" in result
# ============================================================================
# Search Tests
# ============================================================================
class TestSearch:
"""Tests for web search tool."""
@pytest.mark.asyncio
async def test_search_web_success(self):
"""Test successful web search."""
mock_response = {
"results": [
{
"title": "Test Result 1",
"url": "https://example.com/1",
"content": "This is a test result"
},
{
"title": "Test Result 2",
"url": "https://example.com/2",
"content": "Another test result"
}
]
}
with patch("src.agents.tools.httpx.AsyncClient") as mock_client_class:
# Create mock response
mock_response_obj = type('MockResponse', (), {
'status_code': 200,
'json': lambda *args, **kwargs: mock_response
})()
# Create mock client with async get method
async def mock_get(*args, **kwargs):
return mock_response_obj
mock_client_instance = type('MockClient', (), {
'get': mock_get
})()
# Setup async context manager
async def mock_aenter(*args, **kwargs):
return mock_client_instance
async def mock_aexit(*args, **kwargs):
return None
mock_client_class.return_value.__aenter__ = mock_aenter
mock_client_class.return_value.__aexit__ = mock_aexit
result = await search_web("test query", num_results=2)
assert "Test Result 1" in result
assert "https://example.com/1" in result
assert "Test Result 2" in result
assert "https://example.com/2" in result
@pytest.mark.asyncio
async def test_search_web_no_results(self):
"""Test web search with no results."""
mock_response_data = {"results": []}
with patch("src.agents.tools.httpx.AsyncClient") as mock_client_class:
mock_response_obj = type('MockResponse', (), {
'status_code': 200,
'json': lambda *args, **kwargs: mock_response_data
})()
async def mock_get(*args, **kwargs):
return mock_response_obj
mock_client_instance = type('MockClient', (), {
'get': mock_get
})()
async def mock_aenter(*args, **kwargs):
return mock_client_instance
async def mock_aexit(*args, **kwargs):
return None
mock_client_class.return_value.__aenter__ = mock_aenter
mock_client_class.return_value.__aexit__ = mock_aexit
result = await search_web("test query")
assert "No results found" in result
@pytest.mark.asyncio
async def test_search_web_connection_error(self):
"""Test web search with connection error."""
with patch("httpx.AsyncClient") as mock_client:
mock_client_instance = AsyncMock()
mock_client_instance.get.side_effect = Exception("Connection failed")
mock_client.return_value.__aenter__.return_value = mock_client_instance
result = await search_web("test query")
assert "Error searching" in result
@pytest.mark.asyncio
async def test_search_web_limits_results(self):
"""Test that search limits results to max 10."""
mock_response_data = {
"results": [
{"title": f"Result {i}", "url": f"https://example.com/{i}", "content": "Test"}
for i in range(20)
]
}
with patch("src.agents.tools.httpx.AsyncClient") as mock_client_class:
mock_response_obj = type('MockResponse', (), {
'status_code': 200,
'json': lambda *args, **kwargs: mock_response_data
})()
async def mock_get(*args, **kwargs):
return mock_response_obj
mock_client_instance = type('MockClient', (), {
'get': mock_get
})()
async def mock_aenter(*args, **kwargs):
return mock_client_instance
async def mock_aexit(*args, **kwargs):
return None
mock_client_class.return_value.__aenter__ = mock_aenter
mock_client_class.return_value.__aexit__ = mock_aexit
result = await search_web("test query", num_results=15)
# Should only return 10 results (max limit)
result_count = result.count("URL:")
assert result_count == 10
@pytest.mark.asyncio
async def test_search_web_formats_results(self):
"""Test that search results are properly formatted."""
mock_response_data = {
"results": [
{
"title": "Test Title",
"url": "https://example.com",
"content": "Test content description"
}
]
}
with patch("src.agents.tools.httpx.AsyncClient") as mock_client_class:
mock_response_obj = type('MockResponse', (), {
'status_code': 200,
'json': lambda *args, **kwargs: mock_response_data
})()
async def mock_get(*args, **kwargs):
return mock_response_obj
mock_client_instance = type('MockClient', (), {
'get': mock_get
})()
async def mock_aenter(*args, **kwargs):
return mock_client_instance
async def mock_aexit(*args, **kwargs):
return None
mock_client_class.return_value.__aenter__ = mock_aenter
mock_client_class.return_value.__aexit__ = mock_aexit
result = await search_web("test query")
# Check formatting
assert "1. Test Title" in result
assert "URL: https://example.com" in result
assert "Test content description" in result