Added LLM Raw Response Feature. New LLM Handling Setters and Getters. Unified Method Names. Updated User Guides. Etc.

Author: AvantMaker

README.md

@@ -113,9 +113,17 @@ void setup() {
   Serial.println(WiFi.localIP());
 
   // Configure AI client parameters:
-  ai.setTemperature(0.7);       // Set response creativity (0.0-2.0)
-  ai.setMaxTokens(200);         // Limit response length (in tokens)
-  ai.setSystemRole("You are a helpful assistant");  // Set assistant behavior
+  ai.setChatTemperature(0.7);       // Set response creativity (0.0-2.0)
+  ai.setChatMaxTokens(200);         // Limit response length (in tokens)
+  ai.setChatSystemRole("You are a helpful assistant");  // Set assistant behavior
+  
+  // You can retrieve current settings using getter methods:
+  Serial.print("Current temperature: ");
+  Serial.println(ai.getChatTemperature());
+  Serial.print("Maximum tokens: ");
+  Serial.println(ai.getChatMaxTokens());
+  Serial.print("System role: ");
+  Serial.println(ai.getChatSystemRole());
 
   // Send a test message to the AI and get response
   Serial.println("\nSending message to AI...");

doc/User Guides/1 Introduction.md

@@ -1,5 +1,5 @@
 # ESP32_AI_Connect Library User Guide - 1 Introduction
-
+> **Version 0.0.2** • Revised: May 09, 2025 • Author: AvantMaker • [https://www.AvantMaker.com](https://www.AvantMaker.com)
 ## Overview
 
 ESP32_AI_Connect is a powerful, flexible library designed to connect ESP32 microcontrollers to various Large Language Model (LLM) platforms. This library simplifies the process of integrating AI capabilities into your ESP32 projects, allowing you to create intelligent IoT devices, smart assistants, and interactive applications with minimal effort.
@@ -128,4 +128,9 @@ Each guide will include detailed explanations, code examples, and best practices
 
 If you encounter any issues or have suggestions for improvements, please open an issue on the GitHub repository. Contributions are welcome through pull requests.
 
-Happy building with ESP32 and AI!
+Happy building with ESP32 and AI!
+
+---
+>🚀 **Explore our GitHub** for more projects:  
+>- [ESP32_AI_Connect GitHub Repo](https://github.com/AvantMaker/ESP32_AI_Connect)  
+>- [AvantMaker GitHub](https://github.com/AvantMaker/)

doc/User Guides/2 Basic LLM Chat Implementation.md

@@ -1,4 +1,5 @@
 # ESP32_AI_Connect Library User Guide - 2 Basic LLM Chat Implementation
+> **Version 0.0.2** • Revised: May 09, 2025 • Author: AvantMaker • [https://www.AvantMaker.com](https://www.AvantMaker.com)
 
 ## Overview
 
@@ -92,18 +93,38 @@ After establishing the WiFi connection, we configure the AI client with specific
 
 ```cpp:basic_example.ino
   // Configure AI client parameters:
-  ai.setTemperature(0.7);       // Set response creativity (0.0-2.0)
-  ai.setMaxTokens(200);         // Limit response length (in tokens)
-  ai.setSystemRole("You are a helpful assistant");  // Set assistant behavior
+  ai.setChatTemperature(0.7);       // Set response creativity (0.0-2.0)
+  ai.setChatMaxTokens(200);         // Limit response length (in tokens)
+  ai.setChatSystemRole("You are a helpful assistant");  // Set assistant behavior
 ```
 
 These configuration options allow you to customize the behavior of the AI:
 
-- `setTemperature(0.7)`: Controls the randomness/creativity of the responses. Lower values (closer to 0) make responses more deterministic and focused, while higher values (up to 2.0) make them more creative and diverse.
-- `setMaxTokens(200)`: Limits the maximum length of the AI's response in tokens (roughly 4 characters per token). This helps control response size and API costs.
-- `setSystemRole("You are a helpful assistant")`: Sets the system message that defines the AI's behavior and personality.
+- `setChatTemperature(0.7)`: Controls the randomness/creativity of the responses. Lower values (closer to 0) make responses more deterministic and focused, while higher values (up to 2.0) make them more creative and diverse.
+- `setChatMaxTokens(200)`: Limits the maximum length of the AI's response in tokens (roughly 4 characters per token). This helps control response size and API costs.
+- `setChatSystemRole("You are a helpful assistant")`: Sets the system message that defines the AI's behavior and personality.
 
-## Step 6: Send a Message and Get a Response
+## Step 6: Verifying Configuration with Getter Methods
+
+You can verify your configuration settings using the corresponding getter methods:
+
+```cpp:basic_example.ino
+  // Retrieve and display the current configuration
+  Serial.println("\nAI Configuration:");
+  Serial.print("System Role: ");
+  Serial.println(ai.getChatSystemRole());
+  Serial.print("Temperature: ");
+  Serial.println(ai.getChatTemperature());
+  Serial.print("Max Tokens: ");
+  Serial.println(ai.getChatMaxTokens());
+```
+
+These getter methods allow you to:
+- Confirm that your settings were applied correctly
+- Access current configuration values for logging or debugging
+- Use configuration values in other parts of your application logic
+
+## Step 7: Send a Message and Get a Response
 
 Now we're ready to send a message to the AI and receive a response:
 
@@ -130,7 +151,7 @@ The key function here is `ai.chat()`, which:
 
 We also include error checking to display any issues that might have occurred during the API call.
 
-## Step 7: The Loop Function
+## Step 8: The Loop Function
 
 In this basic example, the `loop()` function is empty:
 
@@ -185,6 +206,26 @@ This modified `loop()` function:
 4. Prints the AI's response
 5. Checks for errors
 
+## Resetting Chat Configuration
+
+If you need to reset the chat configuration to default values, you can use the `chatReset()` method:
+
+```cpp
+// Reset chat configuration to defaults
+ai.chatReset();
+
+// Verify reset was successful
+Serial.println("After reset:");
+Serial.print("System Role: ");
+Serial.println(ai.getChatSystemRole());  // Should be empty
+Serial.print("Temperature: ");
+Serial.println(ai.getChatTemperature());  // Should be -1.0 (default)
+Serial.print("Max Tokens: ");
+Serial.println(ai.getChatMaxTokens());    // Should be -1 (default)
+```
+
+This is useful when you want to start a fresh conversation with different settings or return to the default configuration.
+
 ## Switching Between AI Platforms
 
 One of the key features of the ESP32_AI_Connect library is its ability to work with multiple AI platforms. To switch from OpenAI to Google Gemini or DeepSeek, you only need to change the platform identifier and model name:
@@ -219,6 +260,22 @@ ESP32_AI_Connect ai("openai-compatible", apiKey, "model-name", customEndpoint);
 
 This is useful for self-hosted models or alternative API providers that are compatible with the OpenAI API format.
 
+## Accessing Raw API Responses
+
+For advanced usage, you might want to access the complete raw JSON response from the API. The library provides methods to retrieve these:
+
+```cpp
+// Get the raw JSON response from the last chat request
+String rawResponse = ai.getChatRawResponse();
+Serial.println("Raw API Response:");
+Serial.println(rawResponse);
+
+// For tool calling, you can also get the raw response
+String rawToolResponse = ai.getTCRawResponse();
+```
+
+These methods allow you to access the full API response data for custom processing or debugging.
+
 ## Troubleshooting
 
 If you encounter issues with your AI chat application, here are some common problems and solutions:
@@ -243,4 +300,9 @@ You've now learned how to use the ESP32_AI_Connect library to conduct basic chat
 
 In the next guide, we'll explore how to use the library's tool calling capabilities to enable your ESP32 to perform specific functions based on AI instructions.
 
-Happy building with ESP32 and AI!
+Happy building with ESP32 and AI!
+
+---
+>🚀 **Explore our GitHub** for more projects:  
+>- [ESP32_AI_Connect GitHub Repo](https://github.com/AvantMaker/ESP32_AI_Connect)  
+>- [AvantMaker GitHub](https://github.com/AvantMaker/)

doc/User Guides/3 Tool Calls Implementation Basics.md

@@ -1,5 +1,5 @@
 # ESP32_AI_Connect Library User Guide - 3 Tool Calls Implementation Basics
-
+> **Version 0.0.2** • Revised: May 09, 2025 • Author: AvantMaker • [https://www.AvantMaker.com](https://www.AvantMaker.com)
 ## Overview
 
 This guide will walk you through the process of setting up and using tool calls (function calling) with Large Language Models (LLMs) using the ESP32_AI_Connect library. We'll use the `tool_calls_demo.ino` sketch stored in the examples folder as our reference implementation, explaining each component in detail so you can understand how to integrate AI function calling capabilities into your ESP32 projects.
@@ -141,20 +141,20 @@ You can customize the tool calling behavior using optional setter methods:
 
 ```cpp
 // --- Demonstrate Configuration Methods (Optional) ---
-aiClient.setTCSystemRole("You are a weather assistant.");
-aiClient.setTCMaxToken(300);
-aiClient.setTCToolChoice("auto");
+aiClient.setTCChatSystemRole("You are a weather assistant.");
+aiClient.setTCChatMaxTokens(300);
+aiClient.setTCChatToolChoice("auto");
 
 Serial.println("\n--- Tool Call Configuration ---");
-Serial.println("System Role: " + aiClient.getTCSystemRole());
-Serial.println("Max Tokens: " + String(aiClient.getTCMaxToken()));
-Serial.println("Tool Choice: " + aiClient.getTCToolChoice());
+Serial.println("System Role: " + aiClient.getTCChatSystemRole());
+Serial.println("Max Tokens: " + String(aiClient.getTCChatMaxTokens()));
+Serial.println("Tool Choice: " + aiClient.getTCChatToolChoice());
 ```
 
 These optional methods allow you to:
-- Set a system role message that defines the AI's behavior (`setTCSystemRole`)
-- Set the maximum number of tokens for the response (`setTCMaxToken`)
-- Set the tool choice parameter (`setTCToolChoice`) which dictates how the AI selects tools
+- Set a system role message that defines the AI's behavior (`setTCChatSystemRole`)
+- Set the maximum number of tokens for the response (`setTCChatMaxTokens`)
+- Set the tool choice parameter (`setTCChatToolChoice`) which dictates how the AI selects tools
 
 Each setter also has a corresponding getter method to retrieve the current value.
 
@@ -228,7 +228,27 @@ Here's a table that summarizes the different finish reason values used by each p
 
 This distinction is important when checking the `finishReason` in your code to determine if you need to execute tools based on the AI's response.
 
-## Step 10: Parse and Execute Tool Calls
+## Step 10: Accessing the Complete Raw API Response
+
+For debugging or advanced scenarios, you may want to access the complete raw JSON response from the AI server:
+
+```cpp
+// Get the raw server response
+String rawResponse = aiClient.getTCRawResponse();
+Serial.println("\n--- Raw API Response ---");
+Serial.println(rawResponse);
+```
+
+The `getTCRawResponse()` method returns the complete server response JSON for the last tool calling method executed (either `tcChat` or `tcReply`). This can be useful for:
+
+- Debugging API interactions
+- Accessing additional response information not exposed by the library
+- Custom parsing of complex response data
+- Monitoring token usage and other metadata
+
+This raw response includes all fields returned by the AI platform, not just the extracted tool calls or content.
+
+## Step 11: Parse and Execute Tool Calls
 
 When you receive tool calls, you must parse the JSON response and execute the requested functions. A practical example of how to parse and handle tool calls can be found in the tool_calling_demo_2 example code located in the examples folder.
 
@@ -258,7 +278,7 @@ if (error) {
 
 This code parses the tool calls JSON array and extracts the function name, ID, and arguments for each tool call.
 
-## Step 11: Reset Tool Call Settings
+## Step 12: Reset Tool Call Settings
 
 After completing a tool call operation, you can reset the tool call settings to their default values:
 
@@ -268,12 +288,17 @@ Serial.println("\nResetting tool call settings to defaults...");
 aiClient.tcChatReset();
 
 Serial.println("\n--- Tool Call Configuration After Reset ---");
-Serial.println("System Role: " + aiClient.getTCSystemRole());
-Serial.println("Max Tokens: " + String(aiClient.getTCMaxToken()));
-Serial.println("Tool Choice: " + aiClient.getTCToolChoice());
+Serial.println("System Role: " + aiClient.getTCChatSystemRole());
+Serial.println("Max Tokens: " + String(aiClient.getTCChatMaxTokens()));
+Serial.println("Tool Choice: " + aiClient.getTCChatToolChoice());
+
+// Verify raw response was cleared
+if (aiClient.getTCRawResponse().isEmpty()) {
+  Serial.println("Raw response was cleared successfully");
+}
 ```
 
-The `tcChatReset()` method resets all tool call parameters to their default values.
+The `tcChatReset()` method resets all tool call parameters to their default values and clears the stored raw response.
 
 ## Advanced: Using Multiple Tools
 
@@ -367,12 +392,19 @@ If you encounter issues with tool calls, here are some common problems and solut
 
 5. **Tool Definition Too Large**: If your tool definition is too large, you'll get an error. Increase `AI_API_REQ_JSON_DOC_SIZE` in the configuration file.
 
+6. **Debug with Raw Response**: If you're not sure why something isn't working, examine the raw response with `getTCRawResponse()` to see the complete server response.
+
 ## Conclusion
 
 You've now learned how to use the ESP32_AI_Connect library to implement tool calls with LLMs. This powerful feature allows your ESP32 to act as an intelligent agent, executing functions based on natural language instructions and providing the results back to the AI for further processing.
 
-With the new setter/getter methods and the `tcChatReset()` function, you have greater control over the tool calling behavior, allowing you to create more flexible and sophisticated AI-powered IoT applications.
+With the setter/getter methods, the `tcChatReset()` function, and the raw response access methods, you have greater control over the tool calling behavior, allowing you to create more flexible and sophisticated AI-powered IoT applications.
 
 Tool calls open up a world of possibilities for creating smart IoT devices that can interact with their environment based on AI-driven decisions. You can create weather stations, home automation systems, data loggers, and much more, all controlled through natural language.
 
 Happy building with ESP32 and AI!
+
+---
+>🚀 **Explore our GitHub** for more projects:  
+>- [ESP32_AI_Connect GitHub Repo](https://github.com/AvantMaker/ESP32_AI_Connect)  
+>- [AvantMaker GitHub](https://github.com/AvantMaker/)