AI Agent Tools Integration

This module provides a comprehensive integration layer for autonomous AI agents (such as AIyaru) to natively use Sandalwood for Differential Algebra (DA) and Truncated Power Series Algebra (TPSA) operations.

Architecture

The agent_tools module is designed with a decoupled architecture that conforms to standard agentic best practices:

Stateful Session Registry: Differential algebra objects (like MultivariateTaylorFunction and TaylorMap) can contain thousands of coefficients. To prevent LLM context window bloat, all tools return lightweight JSON references (e.g., {"ref": "mtf_0"}) inside a standardized response envelope. Agents pass these reference strings in subsequent tool calls instead of large serialized coefficient datasets.
Core Logic: Contains the raw Python functions, type hints, robust error handling, and docstrings.
LangChain Tools: Exposes the core functions wrapped with LangChain’s @tool decorator in langchain_tools.py.
MCP Server: Exposes the core functions as Model Context Protocol (MCP) tools and provides the @mcp.prompt("sandalwood-da-expert") instruction prompt in mcp_server.py.

Response Envelope Structure

All tools in the agent_tools module return a standardized response structure to ensure reliable parsing by LLMs and client applications.

Success Response

When an operation succeeds, the tool returns a JSON object matching ToolSuccessResponse:

{
  "status": "success",
  "data": {
    "result": {
      "ref": "mtf_0",
      "message": "Successfully parsed expression. Saved as 'mtf_0'."
    },
    "metadata": {
      "operation": "parse_expression_to_mtf"
    }
  }
}

(Note: Some diagnostic/evaluation tools return concrete data arrays or metrics in the result block instead of reference names, e.g., evaluations returning numerical values/coordinates.)

Error Response

When an operation fails (due to invalid inputs, parser syntax errors, registry mismatches, or calculation errors), the tool catches the exception internally and returns a JSON object matching ToolErrorResponse:

{
  "status": "error",
  "error_code": "INVALID_INPUT",
  "message": "Variables in expression exceed max_dimension 2."
}

This structured error-handling prevents the execution thread from crashing, allowing the AI agent to observe the issue and dynamically self-correct.

Usage

LangChain / LangGraph

from sandalwood.agent_tools.langchain_tools import evaluate_taylor_map, invert_taylor_map

# Add tools to your LangGraph nodes
tools = [evaluate_taylor_map, invert_taylor_map]
# llm.bind_tools(tools)

Model Context Protocol (MCP)

To run the server and expose the tools and prompts to compatible MCP clients (like Claude Desktop or an AI IDE):

uv run python -m sandalwood.agent_tools.mcp_server

You can instruct your MCP client to load the expert instructions by invoking the prompt:

{
  "method": "prompts/get",
  "params": {
    "name": "sandalwood-da-expert"
  }
}

Or configure it directly in your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "sandalwood": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "sandalwood.agent_tools.mcp_server"
      ]
    }
  }
}

API Reference

The following sections provide the auto-generated documentation for the core agent tools and the stateful registry.