ragleap-tools 0.1.0__tar.gz

ragleap_tools-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Environment
+.env
+*.env.local
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+venv/
+.venv/
+
+# Node
+node_modules/
+
+# Docker
+docker-compose.override.yml
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+.env
+
+# Package build artifacts
+dist/
+build/

ragleap_tools-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to `ragleap-tools` are documented here. Format
+loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-16
+
+### Added
+
+- Initial release. `Tool`/`ToolResult` base abstraction with OpenAI
+  and Gemini function-calling schema generation. Deliberately does not
+  own a tool-calling execution loop - that's `ragleap-agents`' scope,
+  per the project roadmap's own split.
+- 12 stateless tools: calculator (safe AST-based expression
+  evaluation, never `eval()`/`exec()`), `get_current_datetime`,
+  `add_to_date`, `date_difference`, `convert_length`,
+  `convert_weight`, `convert_temperature`, `parse_json`, `parse_csv`,
+  `regex_extract`, `word_count`, `text_case_transform`.
+- 3 sandboxed file-op tools (`read_file`, `write_file`, `list_files`)
+  via `FileOpsConfig(root_dir=...)` - confined entirely to a
+  caller-specified root directory. Path resolution follows symlinks
+  before checking containment, so symlink-based sandbox escapes are
+  rejected, not just naive `../` string checking.
+- 1 optional ingestion tool (`make_ingest_tool`, needs the `ingest`
+  extra: `pip install ragleap-tools[ingest]`) wrapping `ragleap-rag`'s
+  already-tested `ingest_text()` - no new ingestion logic.
+- Explicitly out of scope for this release: code execution, web
+  search, HTTP fetch, and database/business-system connectors - each
+  documented in the README as needing its own security-focused design
+  pass rather than a rushed inclusion.
+
+### Verified
+
+- 51 tests, all passing. Includes real security verification, not
+  just documentation: the calculator's AST whitelist is tested against
+  real code-injection attempts (`__import__`, attribute access, list
+  comprehensions, multi-statement injection - all correctly rejected),
+  and file ops' sandboxing is tested against real path-traversal
+  attempts AND a real symlink-escape attempt (a file outside the
+  sandbox, symlinked from inside it - correctly rejected).

ragleap_tools-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: ragleap-tools
+Version: 0.1.0
+Summary: Standalone, dependency-light tool implementations (calculator, file ops, datetime, unit conversion, JSON/CSV, text utilities) exposing OpenAI/Gemini-style function-calling schemas. No tool-calling execution loop - wire these into your own LLM tool-calling code, or into ragleap-agents when that ships. BYOK, no vendor lock-in.
+Project-URL: Homepage, https://github.com/antonyrag/ragleap-core
+Project-URL: Repository, https://github.com/antonyrag/ragleap-core
+Project-URL: Documentation, https://packages.ragleap.com/docs/ragleap-tools.html
+Project-URL: Issues, https://github.com/antonyrag/ragleap-core/issues
+Author-email: Antony <antony@ragleap.com>
+License-Expression: MIT
+Keywords: agents,byok,calculator,file-ops,function-calling,llm,self-hosted,tool-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: ingest
+Requires-Dist: ragleap-rag>=0.12.0; extra == 'ingest'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# ragleap-tools
+
+Standalone, dependency-light tool implementations for LLM tool-calling.
+Exposes OpenAI/Gemini-style function-calling schemas.
+
+```bash
+pip install ragleap-tools
+```
+
+## What this is (and isn't)
+
+`ragleap-tools` provides `Tool` objects - a name, a description, a JSON
+Schema for parameters, and a safe handler function. It does **not** own
+a tool-calling execution loop (deciding when to call a tool, running
+it, feeding the result back to the model) - that's `ragleap-agents`'
+job, per the project roadmap's own split. Wire these tools into your
+own tool-calling code, or into `ragleap-agents` once that ships.
+
+## Quickstart
+
+```python
+from ragleap_tools import STATELESS_TOOLS, CALCULATOR_TOOL
+
+# Give these to your LLM provider's tools= parameter:
+openai_tools = [t.to_openai_schema() for t in STATELESS_TOOLS]
+gemini_tools = [t.to_gemini_schema() for t in STATELESS_TOOLS]
+
+# When the model calls one, invoke the handler yourself:
+result = CALCULATOR_TOOL.call(expression="2 + 2 * sqrt(16)")
+print(result.success, result.result)  # True 10.0
+```
+
+## The 12 stateless tools
+
+No configuration needed - import and use directly.
+
+- `CALCULATOR_TOOL` - safe arithmetic (AST-based whitelist, never `eval()`)
+- `CURRENT_DATETIME_TOOL`, `ADD_TO_DATE_TOOL`, `DATE_DIFFERENCE_TOOL` - date/time math
+- `CONVERT_LENGTH_TOOL`, `CONVERT_WEIGHT_TOOL`, `CONVERT_TEMPERATURE_TOOL` - unit conversion
+- `PARSE_JSON_TOOL`, `PARSE_CSV_TOOL` - structured data parsing
+- `REGEX_EXTRACT_TOOL`, `WORD_COUNT_TOOL`, `TEXT_CASE_TRANSFORM_TOOL` - text utilities
+
+## File operations (sandboxed, needs configuration)
+
+```python
+from ragleap_tools import FileOpsConfig, make_file_tools
+
+config = FileOpsConfig(root_dir="/path/to/a/safe/directory")
+read_tool, write_tool, list_tool = make_file_tools(config)
+```
+
+Every operation is confined to `root_dir` - both `../` path traversal
+and symlink-based escapes are rejected (verified via real security
+tests, not just documented), not just naive string-prefix checking.
+There is no unsandboxed mode.
+
+## Document ingestion (optional, needs ragleap-rag)
+
+```bash
+pip install ragleap-tools[ingest]
+```
+
+```python
+from ragleap import RagLeap, ProviderConfig, EmbeddingConfig
+from ragleap_tools import IngestConfig, make_ingest_tool
+
+rag = RagLeap(database_url="...", primary=ProviderConfig(...), embedder=EmbeddingConfig(...))
+ingest_tool = make_ingest_tool(IngestConfig(rag=rag))
+```
+
+Wraps `ragleap-rag`'s already-tested `ingest_text()` - no new ingestion
+logic, just a tool schema on top of the real 28-format-capable
+pipeline. `ragleap-rag` owns the actual ingestion; this is a thin
+adapter, same pattern `ragleap-graph` uses for its own optional
+`ragleap-rag` dependency.
+
+## Deliberately out of scope for v0.1.0
+
+Each of these needs its own security-focused design pass, not a
+rushed inclusion here:
+
+- **Code execution** - a real sandboxing/resource-limit design
+  decision, not something to bolt on alongside a calculator.
+- **Web search** - needs a pluggable-provider decision (this
+  ecosystem's BYOK philosophy applies here too), not a single
+  hardcoded provider.
+- **HTTP fetch** - letting an LLM request arbitrary URLs carries real
+  SSRF risk, same care level as code execution.
+- **Database/business-system connectors** (SQL, CRM, payment
+  processors, etc.) - some of what this ecosystem already has
+  elsewhere (e.g. a live payment processor) would be a materially
+  different risk if exposed to LLM tool-calling without deliberate
+  guardrails (dry-run modes, confirmation steps, scoped permissions).
+
+## Status
+
+v0.1.0. 51 tests, all passing, including real security verification
+for the two risk-sensitive tools (calculator's code-injection
+rejection, file ops' path-traversal and symlink-escape rejection) -
+not just documented as safe, actually tested against real attack
+vectors.
+
+## License
+
+MIT

ragleap_tools-0.1.0/README.md

@@ -0,0 +1,105 @@
+# ragleap-tools
+
+Standalone, dependency-light tool implementations for LLM tool-calling.
+Exposes OpenAI/Gemini-style function-calling schemas.
+
+```bash
+pip install ragleap-tools
+```
+
+## What this is (and isn't)
+
+`ragleap-tools` provides `Tool` objects - a name, a description, a JSON
+Schema for parameters, and a safe handler function. It does **not** own
+a tool-calling execution loop (deciding when to call a tool, running
+it, feeding the result back to the model) - that's `ragleap-agents`'
+job, per the project roadmap's own split. Wire these tools into your
+own tool-calling code, or into `ragleap-agents` once that ships.
+
+## Quickstart
+
+```python
+from ragleap_tools import STATELESS_TOOLS, CALCULATOR_TOOL
+
+# Give these to your LLM provider's tools= parameter:
+openai_tools = [t.to_openai_schema() for t in STATELESS_TOOLS]
+gemini_tools = [t.to_gemini_schema() for t in STATELESS_TOOLS]
+
+# When the model calls one, invoke the handler yourself:
+result = CALCULATOR_TOOL.call(expression="2 + 2 * sqrt(16)")
+print(result.success, result.result)  # True 10.0
+```
+
+## The 12 stateless tools
+
+No configuration needed - import and use directly.
+
+- `CALCULATOR_TOOL` - safe arithmetic (AST-based whitelist, never `eval()`)
+- `CURRENT_DATETIME_TOOL`, `ADD_TO_DATE_TOOL`, `DATE_DIFFERENCE_TOOL` - date/time math
+- `CONVERT_LENGTH_TOOL`, `CONVERT_WEIGHT_TOOL`, `CONVERT_TEMPERATURE_TOOL` - unit conversion
+- `PARSE_JSON_TOOL`, `PARSE_CSV_TOOL` - structured data parsing
+- `REGEX_EXTRACT_TOOL`, `WORD_COUNT_TOOL`, `TEXT_CASE_TRANSFORM_TOOL` - text utilities
+
+## File operations (sandboxed, needs configuration)
+
+```python
+from ragleap_tools import FileOpsConfig, make_file_tools
+
+config = FileOpsConfig(root_dir="/path/to/a/safe/directory")
+read_tool, write_tool, list_tool = make_file_tools(config)
+```
+
+Every operation is confined to `root_dir` - both `../` path traversal
+and symlink-based escapes are rejected (verified via real security
+tests, not just documented), not just naive string-prefix checking.
+There is no unsandboxed mode.
+
+## Document ingestion (optional, needs ragleap-rag)
+
+```bash
+pip install ragleap-tools[ingest]
+```
+
+```python
+from ragleap import RagLeap, ProviderConfig, EmbeddingConfig
+from ragleap_tools import IngestConfig, make_ingest_tool
+
+rag = RagLeap(database_url="...", primary=ProviderConfig(...), embedder=EmbeddingConfig(...))
+ingest_tool = make_ingest_tool(IngestConfig(rag=rag))
+```
+
+Wraps `ragleap-rag`'s already-tested `ingest_text()` - no new ingestion
+logic, just a tool schema on top of the real 28-format-capable
+pipeline. `ragleap-rag` owns the actual ingestion; this is a thin
+adapter, same pattern `ragleap-graph` uses for its own optional
+`ragleap-rag` dependency.
+
+## Deliberately out of scope for v0.1.0
+
+Each of these needs its own security-focused design pass, not a
+rushed inclusion here:
+
+- **Code execution** - a real sandboxing/resource-limit design
+  decision, not something to bolt on alongside a calculator.
+- **Web search** - needs a pluggable-provider decision (this
+  ecosystem's BYOK philosophy applies here too), not a single
+  hardcoded provider.
+- **HTTP fetch** - letting an LLM request arbitrary URLs carries real
+  SSRF risk, same care level as code execution.
+- **Database/business-system connectors** (SQL, CRM, payment
+  processors, etc.) - some of what this ecosystem already has
+  elsewhere (e.g. a live payment processor) would be a materially
+  different risk if exposed to LLM tool-calling without deliberate
+  guardrails (dry-run modes, confirmation steps, scoped permissions).
+
+## Status
+
+v0.1.0. 51 tests, all passing, including real security verification
+for the two risk-sensitive tools (calculator's code-injection
+rejection, file ops' path-traversal and symlink-escape rejection) -
+not just documented as safe, actually tested against real attack
+vectors.
+
+## License
+
+MIT

ragleap_tools-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ragleap-tools"
+version = "0.1.0"
+description = "Standalone, dependency-light tool implementations (calculator, file ops, datetime, unit conversion, JSON/CSV, text utilities) exposing OpenAI/Gemini-style function-calling schemas. No tool-calling execution loop - wire these into your own LLM tool-calling code, or into ragleap-agents when that ships. BYOK, no vendor lock-in."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Antony", email = "antony@ragleap.com" }
+]
+keywords = ["llm", "tool-calling", "function-calling", "agents", "calculator", "file-ops", "self-hosted", "byok"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8.0.0"]
+ingest = ["ragleap-rag>=0.12.0"]
+
+[project.urls]
+Homepage = "https://github.com/antonyrag/ragleap-core"
+Repository = "https://github.com/antonyrag/ragleap-core"
+Documentation = "https://packages.ragleap.com/docs/ragleap-tools.html"
+Issues = "https://github.com/antonyrag/ragleap-core/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ragleap_tools"]

ragleap_tools-0.1.0/src/ragleap_tools/__init__.py

@@ -0,0 +1,74 @@
+"""
+ragleap_tools - standalone, dependency-light tool implementations for
+LLM tool-calling. Exposes OpenAI/Gemini-style function-calling schemas.
+
+Deliberately does NOT own a tool-calling execution loop - that's
+ragleap-agents' job (per the project roadmap's own split). This package
+is just the tools: name, description, JSON Schema parameters, and a
+safe handler function you invoke yourself once your LLM picks a tool.
+
+v0.1.0 - 7 tools:
+  calculator, file ops (read/write/list), get_current_datetime,
+  add_to_date, date_difference, convert_length, convert_weight,
+  convert_temperature, parse_json, parse_csv, regex_extract,
+  word_count, text_case_transform, ingest_document (needs the
+  optional ragleap-rag dependency: pip install ragleap-tools[ingest])
+
+Deliberately out of scope for now (each needs its own security-focused
+design pass, not a rushed inclusion here): code execution, web search,
+HTTP fetch, and database/business-system connectors (SQL, CRM,
+payment processors, etc.) - the last of those specifically because
+some of the connectors this ecosystem already has elsewhere (e.g. a
+live payment processor) would be a materially different risk if
+exposed to LLM tool-calling without deliberate guardrails.
+"""
+
+from ragleap_tools.base import Tool, ToolResult
+from ragleap_tools.calculator import CALCULATOR_TOOL
+from ragleap_tools.datetime_tools import ADD_TO_DATE_TOOL, CURRENT_DATETIME_TOOL, DATE_DIFFERENCE_TOOL
+from ragleap_tools.file_ops import FileOpsConfig, make_file_tools
+from ragleap_tools.ingest import IngestConfig, make_ingest_tool
+from ragleap_tools.json_csv import PARSE_CSV_TOOL, PARSE_JSON_TOOL
+from ragleap_tools.text_utils import REGEX_EXTRACT_TOOL, TEXT_CASE_TRANSFORM_TOOL, WORD_COUNT_TOOL
+from ragleap_tools.unit_conversion import CONVERT_LENGTH_TOOL, CONVERT_TEMPERATURE_TOOL, CONVERT_WEIGHT_TOOL
+
+__version__ = "0.1.0"
+
+# Tools with no config/state needed - usable directly.
+STATELESS_TOOLS = [
+    CALCULATOR_TOOL,
+    CURRENT_DATETIME_TOOL,
+    ADD_TO_DATE_TOOL,
+    DATE_DIFFERENCE_TOOL,
+    CONVERT_LENGTH_TOOL,
+    CONVERT_WEIGHT_TOOL,
+    CONVERT_TEMPERATURE_TOOL,
+    PARSE_JSON_TOOL,
+    PARSE_CSV_TOOL,
+    REGEX_EXTRACT_TOOL,
+    WORD_COUNT_TOOL,
+    TEXT_CASE_TRANSFORM_TOOL,
+]
+
+__all__ = [
+    "Tool",
+    "ToolResult",
+    "STATELESS_TOOLS",
+    "CALCULATOR_TOOL",
+    "CURRENT_DATETIME_TOOL",
+    "ADD_TO_DATE_TOOL",
+    "DATE_DIFFERENCE_TOOL",
+    "CONVERT_LENGTH_TOOL",
+    "CONVERT_WEIGHT_TOOL",
+    "CONVERT_TEMPERATURE_TOOL",
+    "PARSE_JSON_TOOL",
+    "PARSE_CSV_TOOL",
+    "REGEX_EXTRACT_TOOL",
+    "WORD_COUNT_TOOL",
+    "TEXT_CASE_TRANSFORM_TOOL",
+    "FileOpsConfig",
+    "make_file_tools",
+    "IngestConfig",
+    "make_ingest_tool",
+    "__version__",
+]

ragleap_tools-0.1.0/src/ragleap_tools/base.py

@@ -0,0 +1,79 @@
+"""
+ragleap_tools.base
+
+Core Tool/ToolResult abstraction every tool implementation in this
+package uses. Deliberately minimal - a name, a description, a JSON
+Schema for parameters (the OpenAI/Gemini function-calling convention,
+so no adapter layer is needed for either provider), and a handler
+callable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Optional
+
+
+@dataclass
+class ToolResult:
+    """Result of calling a tool's handler.
+
+    success=False + error=<message> on any failure - handlers should
+    never raise for expected failure modes (bad input, file not found,
+    etc.); they should catch and return a ToolResult so a caller's
+    tool-calling loop can feed a clean error back to the LLM instead of
+    crashing. Handlers MAY still raise for genuinely unexpected
+    programming errors - that's a real bug, not user input to explain
+    to the model.
+    """
+
+    success: bool
+    result: Any = None
+    error: Optional[str] = None
+
+
+@dataclass
+class Tool:
+    """A single callable tool with an OpenAI/Gemini-compatible schema.
+
+    parameters: a JSON Schema object (the same shape both OpenAI's
+    `tools=[{"type": "function", "function": {...}}]` and Gemini's
+    `FunctionDeclaration` expect for their own `parameters` field) -
+    e.g. {"type": "object", "properties": {...}, "required": [...]}.
+
+    handler: called with the tool call's arguments as keyword
+    arguments (already parsed from whatever JSON the model returned -
+    parsing that JSON is the caller's responsibility, not this
+    package's). Must return a ToolResult, never raise for expected
+    failure modes (see ToolResult's docstring).
+    """
+
+    name: str
+    description: str
+    parameters: Dict[str, Any]
+    handler: Callable[..., ToolResult]
+
+    def to_openai_schema(self) -> Dict[str, Any]:
+        """Returns the {"type": "function", "function": {...}} shape
+        OpenAI's `tools=` parameter expects."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def to_gemini_schema(self) -> Dict[str, Any]:
+        """Returns the shape google-genai's FunctionDeclaration expects
+        (name/description/parameters, same JSON Schema convention)."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.parameters,
+        }
+
+    def call(self, **kwargs: Any) -> ToolResult:
+        """Invokes the handler with the given keyword arguments."""
+        return self.handler(**kwargs)

ragleap_tools-0.1.0/src/ragleap_tools/calculator.py

@@ -0,0 +1,139 @@
+"""
+ragleap_tools.calculator
+
+Safe arithmetic expression evaluation - deliberately NOT using eval()
+or exec(). Parses the expression into a real Python AST, then walks it
+recursively, rejecting anything that isn't an explicitly whitelisted
+node type (numbers, basic binary/unary math operators, and a small
+fixed set of math functions/constants). No name lookups beyond that
+fixed set, no attribute access, no function calls beyond the
+whitelist, no comprehensions, no imports - none of eval()'s real
+attack surface exists here at all.
+"""
+
+from __future__ import annotations
+
+import ast
+import math
+import operator
+from typing import Any, Dict
+
+from ragleap_tools.base import Tool, ToolResult
+
+_ALLOWED_BINOPS = {
+    ast.Add: operator.add,
+    ast.Sub: operator.sub,
+    ast.Mult: operator.mul,
+    ast.Div: operator.truediv,
+    ast.FloorDiv: operator.floordiv,
+    ast.Mod: operator.mod,
+    ast.Pow: operator.pow,
+}
+
+_ALLOWED_UNARYOPS = {
+    ast.UAdd: operator.pos,
+    ast.USub: operator.neg,
+}
+
+_ALLOWED_FUNCTIONS = {
+    "abs": abs,
+    "round": round,
+    "min": min,
+    "max": max,
+    "sqrt": math.sqrt,
+    "sin": math.sin,
+    "cos": math.cos,
+    "tan": math.tan,
+    "log": math.log,
+    "log10": math.log10,
+    "log2": math.log2,
+    "exp": math.exp,
+    "floor": math.floor,
+    "ceil": math.ceil,
+}
+
+_ALLOWED_CONSTANTS = {
+    "pi": math.pi,
+    "e": math.e,
+}
+
+
+class UnsafeExpressionError(ValueError):
+    """Raised when the expression contains anything outside the
+    explicit whitelist - not a math error, a rejected-input error."""
+
+
+def _eval_node(node: ast.AST) -> Any:
+    if isinstance(node, ast.Expression):
+        return _eval_node(node.body)
+    if isinstance(node, ast.Constant):
+        if isinstance(node.value, (int, float)):
+            return node.value
+        raise UnsafeExpressionError(f"Constant type not allowed: {type(node.value).__name__}")
+    if isinstance(node, ast.BinOp):
+        op_type = type(node.op)
+        if op_type not in _ALLOWED_BINOPS:
+            raise UnsafeExpressionError(f"Operator not allowed: {op_type.__name__}")
+        return _ALLOWED_BINOPS[op_type](_eval_node(node.left), _eval_node(node.right))
+    if isinstance(node, ast.UnaryOp):
+        op_type = type(node.op)
+        if op_type not in _ALLOWED_UNARYOPS:
+            raise UnsafeExpressionError(f"Unary operator not allowed: {op_type.__name__}")
+        return _ALLOWED_UNARYOPS[op_type](_eval_node(node.operand))
+    if isinstance(node, ast.Name):
+        if node.id in _ALLOWED_CONSTANTS:
+            return _ALLOWED_CONSTANTS[node.id]
+        raise UnsafeExpressionError(f"Name not allowed: {node.id!r}")
+    if isinstance(node, ast.Call):
+        if not isinstance(node.func, ast.Name) or node.func.id not in _ALLOWED_FUNCTIONS:
+            raise UnsafeExpressionError("Only whitelisted functions may be called")
+        if node.keywords:
+            raise UnsafeExpressionError("Keyword arguments are not allowed")
+        args = [_eval_node(a) for a in node.args]
+        return _ALLOWED_FUNCTIONS[node.func.id](*args)
+    raise UnsafeExpressionError(f"Expression node type not allowed: {type(node).__name__}")
+
+
+def safe_eval_expression(expression: str) -> float:
+    """Parses and evaluates a math expression using only the
+    whitelisted grammar above. Raises UnsafeExpressionError for
+    anything outside that whitelist, SyntaxError for invalid syntax,
+    ZeroDivisionError/ValueError/OverflowError for real math errors -
+    the caller (calculate()) catches all of these and returns a
+    ToolResult rather than letting them propagate."""
+    if not expression or not expression.strip():
+        raise ValueError("Expression is empty")
+    if len(expression) > 200:
+        raise UnsafeExpressionError("Expression too long (max 200 characters)")
+    parsed = ast.parse(expression, mode="eval")
+    return _eval_node(parsed)
+
+
+def calculate(expression: str) -> ToolResult:
+    try:
+        result = safe_eval_expression(expression)
+        return ToolResult(success=True, result=result)
+    except (UnsafeExpressionError, SyntaxError, ValueError, ZeroDivisionError, OverflowError, TypeError) as e:
+        return ToolResult(success=False, error=f"{type(e).__name__}: {e}")
+
+
+CALCULATOR_TOOL = Tool(
+    name="calculator",
+    description=(
+        "Evaluate a mathematical expression. Supports +, -, *, /, //, %, ** "
+        "and the functions abs, round, min, max, sqrt, sin, cos, tan, log, "
+        "log10, log2, exp, floor, ceil, plus the constants pi and e. "
+        "No variables, no string operations, no other Python syntax."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "expression": {
+                "type": "string",
+                "description": "A math expression, e.g. '2 + 2 * sqrt(16)'",
+            },
+        },
+        "required": ["expression"],
+    },
+    handler=calculate,
+)