feat: Add date and time awareness tool (#20)

pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
     "pydantic>=2.13.4",
     "httpx>=0.28.1",
     "beautifulsoup4>=4.13.4",
+    "tzdata>=2026.2",
 ]
 
 [project.scripts]

tapio/tools/__init__.py

@@ -0,0 +1,5 @@
+"""Tool registry package for Tapio's agent tools."""
+from tapio.tools.datetime_tool import get_current_datetime
+
+ALL_TOOLS = [get_current_datetime]
+__all__ = ["ALL_TOOLS", "get_current_datetime"]

tapio/tools/datetime_tool.py

@@ -0,0 +1,29 @@
+"""Date and time awareness tool."""
+
+from datetime import UTC, datetime, tzinfo
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from langchain_core.tools import tool
+
+
+def _get_helsinki_tz() -> tzinfo:
+    try:
+        return ZoneInfo("Europe/Helsinki")
+    except ZoneInfoNotFoundError:
+        return UTC
+
+
+@tool
+def get_current_datetime() -> str:
+    """Return the current date and time in Helsinki (Finnish) local time.
+
+    Use this tool whenever the user's question involves today's date, current
+    deadlines, permit processing windows, office opening hours, or any other
+    context that requires knowing what day or time it is right now.
+
+    Returns:
+        A human-readable string with the current weekday, date, and time in
+        Helsinki local time, e.g. "Tuesday, 27 June 2026, 14:32 EEST".
+    """
+    now = datetime.now(UTC).astimezone(_get_helsinki_tz())
+    return now.strftime("%A, %d %B %Y, %H:%M %Z")

tests/tools/test_datetime_tool.py

@@ -0,0 +1,31 @@
+from zoneinfo import ZoneInfoNotFoundError
+
+from tapio.tools import datetime_tool
+from tapio.tools.datetime_tool import get_current_datetime
+
+
+def test_returns_string():
+    result = get_current_datetime.invoke({})
+    assert isinstance(result, str)
+    assert len(result) > 0
+
+
+def test_includes_timezone():
+    result = get_current_datetime.invoke({})
+    # Helsinki is EET (UTC+2) or EEST (UTC+3) depending on DST
+    assert "EET" in result or "EEST" in result
+
+
+def test_when_tzdata_missing(monkeypatch):
+    """If the IANA timezone database isn't available, the tool should
+    fall back to UTC."""
+
+    def raise_zone_info_not_found(name):
+        raise ZoneInfoNotFoundError(name)
+
+    monkeypatch.setattr(datetime_tool, "ZoneInfo", raise_zone_info_not_found)
+
+    result = get_current_datetime.invoke({})
+    assert isinstance(result, str)
+    assert len(result) > 0
+    assert "UTC" in result