Tool Execution Framework

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• tests/function-calling.test.js
• INSIGHTS_TOOL_EXECUTION_ENHANCEMENT.md
• REACT_LOOP_README.md
• GITHUB_INTEGRATION_COMPLETE.md
• 12-2-todo.md
• FINAL_REPORT_TASK_COMPLETION.md

The Tool Execution Framework is an agentic insights system that empowers the Gemini AI to dynamically request and use data during analysis. It is the core of the "Ultimate AI Battery Guru" feature, transforming the AI from a passive analyzer into an active partner that can orchestrate tool calls to gather the necessary context for answering complex user queries. This is achieved through a ReAct (Reasoning and Acting) loop, where the AI can reason about a problem and decide to act by calling a predefined tool.

The framework is designed to be robust, with features like automatic format validation, response correction, and explicit instructions to ensure the AI executes tools itself rather than recommending them to the user. It also includes security measures for tools that interact with external systems like the GitHub API.

Sources: README.md, REACT_LOOP_README.md, INSIGHTS_TOOL_EXECUTION_ENHANCEMENT.md

Architecture

The framework is built around a ReAct Loop, which orchestrates the conversation between the user, the Gemini AI, and the available tools. When a user submits a query, the AI, aware of the tools it can use, may decide that it needs more information. It then issues a function call, which the system intercepts and executes. The result is then fed back to the AI, allowing it to continue its reasoning process and formulate a final answer.

Sources: REACT_LOOP_README.md, INSIGHTS_TOOL_EXECUTION_ENHANCEMENT.md

High-Level Data Flow

The following diagram illustrates the agentic workflow managed by the ReAct loop.

ReAct Loop Sequence

The react-loop.cjs module manages the multi-turn conversation. It detects tool call requests from Gemini, executes them via tool-executor.cjs, and appends the results to the conversation history for the AI to use in the next turn. This process repeats until the AI has enough information to generate a final answer or hits a predefined limit on turns or time.

The diagram below shows the detailed interaction sequence.

Tool Definitions

Tools are defined in netlify/functions/utils/gemini-tools.cjs and made available to the Gemini model. Each definition includes a name, a description of what it does, and a schema for its parameters. This allows the AI to understand when and how to use each tool.

Sources: tests/function-calling.test.js, GITHUB_INTEGRATION_COMPLETE.md:41-51

The following table summarizes the available tools. Note that several tools are currently stubs and return placeholder data.

Tool Name	Description	Status	Key Parameters
getSystemHistory	Retrieves historical data for a specific BMS system.	Working	systemId, limit, startDate, endDate
getWeatherData	Fetches current or historical weather data for a given location.	Stub	latitude, longitude, timestamp, type
getSolarEstimate	Gets solar generation estimates based on location and panel specs.	Stub	location, panelWatts, startDate, endDate
getSystemAnalytics	Retrieves pre-computed analytics for a BMS system.	Stub	systemId
predict_battery_trends	Predicts future battery performance trends.	Stub	N/A
analyze_usage_patterns	Analyzes charge and discharge usage patterns.	Stub	N/A
calculate_energy_budget	Calculates a daily energy budget based on generation and consumption.	Stub	N/A
searchGitHubIssues	Searches the repository for existing GitHub issues to prevent duplicates.	Working	query, state, labels
getCodebaseFile	Fetches the contents of a file from the codebase for verification.	Working	path
listDirectory	Lists files in an approved directory to discover repository structure.	Working	path

Sources: tests/function-calling.test.js:10-33, 12-2-todo.md:49-59, GITHUB_INTEGRATION_COMPLETE.md:41-51

Tool Orchestration and Execution

A critical aspect of the framework is ensuring the AI executes tools rather than suggesting them to the user. This is enforced through explicit, multi-layered instructions embedded within the system prompts.

Sources: INSIGHTS_TOOL_EXECUTION_ENHANCEMENT.md:11-59

Prompt Engineering

The netlify/functions/utils/insights-guru.cjs module contains several rules to guide the AI's behavior:

• Absolute Rule: A top-level directive explicitly states that only the AI can execute tools and that it must never instruct the user to do so.
• Data Gathering Instructions: When analysis requires data from a tool, the AI is instructed to call the tool immediately, wait for the result, and present the findings.
• Actionability Requirements: Recommendations to the user must be physical actions (e.g., "reduce load"), not tool executions.

Sources: INSIGHTS_TOOL_EXECUTION_ENHANCEMENT.md:14-43

Execution and Security

When Gemini requests a tool call, the executeToolCall function in gemini-tools.cjs handles the request. For tools that interact with sensitive systems, such as the GitHub API, a robust security model is in place.

The flow for accessing a file via the getCodebaseFile tool is shown below:

This security model includes:

• Path Allowlist & Blocklist: Only approved directories are accessible, while sensitive paths like .git or node_modules are blocked.
• Directory Traversal Protection: Prevents access to files outside the intended directories.
• File Size Limits: A 15KB limit is enforced on file fetches to prevent abuse.

Sources: tests/function-calling.test.js:70-85, GITHUB_INTEGRATION_COMPLETE.md:21-36, 105-110

Resilience and Error Handling

The framework includes mechanisms to handle failures and ensure the quality of the AI's final output.

Timeout, Retry, and Resume

For potentially long-running insights generation, the system has a checkpoint and resume capability.

• Frontend: The clientService.ts contains logic to automatically retry a request if it times out (HTTP 408). It can perform up to 5 resume attempts, parsing the jobId from the timeout response to continue the analysis.
• Backend: The generate-insights-with-tools.cjs function can save its state as a "resumable job" and return a 408 status with a jobId if it's about to time out. Subsequent requests can include this jobId to resume from the last checkpoint.

Sources: FINAL_REPORT_TASK_COMPLETION.md:50-68

Response Validation and Auto-Correction

To prevent malformed AI responses from breaking the UI, a validation and correction loop is integrated into the react-loop.cjs module.

This system works as follows:

1. Format Detection: The system detects if the user requested a specific format (e.g., CSV, JSON, Markdown table).
2. Validation: The AI's response is checked against the rules for the requested format (e.g., consistent column counts for CSV).
3. Auto-Correction: If the format is invalid and retry turns are available, a detailed correction prompt is sent back to the AI, including the error, the malformed snippet, and examples of the correct format.
4. Fallback: If correction fails after multiple attempts, the malformed response is displayed as a last resort.

Sources: INSIGHTS_TOOL_EXECUTION_ENHANCEMENT.md:65-121

Conclusion

The Tool Execution Framework is a sophisticated system that significantly enhances the capabilities of the BMSview application. By enabling the AI to act as an agent within a ReAct loop, it can dynamically gather and process information from a variety of sources to provide deep, context-aware, and actionable insights. The framework's robust design, which includes strong prompt engineering, security controls, and resilient error handling, makes it a cornerstone of the "Ultimate AI Battery Guru" and a powerful engine for continuous application improvement.

Sources: REACT_LOOP_README.md, INSIGHTS_TOOL_EXECUTION_ENHANCEMENT.md