extended documentation

Assets/Virtual Agents Framework/Runtime/Scripts/LLMIntegration/IQueryAPI.cs

@@ -1,6 +1,6 @@
 using System.Threading.Tasks;
 
-namespace i5.VirtualAgents
+namespace i5.VirtualAgents.LLM
 {
     /// <summary>
     /// Interface that should be used to implement more query APIs, these could be offline or online

Assets/Virtual Agents Framework/Runtime/Scripts/LLMIntegration/OpenAIAPIController.CS

@@ -17,11 +17,11 @@ using System.Threading;
 using OpenAI;
 #endif
 
-namespace i5.VirtualAgents
+namespace i5.VirtualAgents.LLM
 {
 
     /// <summary>
-    /// This script should be attached to an agent or any controller object to integrate chat GPT. If attached to an agent the chat bot can command animations.
+    /// This script should be attached to an agent or any controller object to integrate chatGPT. If attached to an agent the chat bot can command animations.
     /// Uses Text Field, Imput Field and Ok Button for Text message interaction.
     /// </summary>
     public class OpenAIController : MonoBehaviour
@@ -31,29 +31,58 @@ namespace i5.VirtualAgents
         public Button okButton;
 
         [Space(10)]
-
+        /// <summary>
+        /// How the chat agent should behave and what it has know.
+        /// </summary>
         [Tooltip("How the chat agent should behave and what it has know.")]
         public string systemMessage = "You are an honorable, friendly guide of the RWTH Aachen University.You will teach students about the processes of the RWTH if they ask.";
+        /// <summary>
+        /// How the chat bot should start the conservation.
+        /// </summary>
         [Tooltip("How the chat bot should start the conservation.")]
         public string startString = "Hello! I am here to help you with any questions about the RWTH Aachen.";
+        /// <summary>
+        /// Chat bot is told to keep responeses short and simple for cost saving.
+        /// </summary>
         [Tooltip("Chat bot is told to keep responeses short and simple for cost saving.")]
         public bool costSaving = true;
-
+        /// <summary>
+        /// Chat bot is told to generate a query that retrives relevant infromation.
+        /// </summary>
         [Tooltip("Chat bot is told to generate a query that retrives relevant infromation.")]
         public bool useQuery = true;
+        /// <summary>
+        /// Interface that is used to get information about the query language and evaluate the query.
+        /// </summary>
+        [Tooltip("Interface that is used to get information about the query language and evaluate the query.")]
         public IQueryAPI queryAPI;
+        /// <summary>
+        /// Chat bot is told to animate when appropriate
+        /// </summary>
 
         [Tooltip("Chat bot is told to animate when appropriate")]
         public bool doAnimation = true;
+        /// <summary>
+        /// The agent and its taskSystem that the animations are called on. Is automatically set to the agent on the game object if no agent is provided.
+        /// </summary>
         [Tooltip("The agent and its taskSystem that the animations are called on. Is automatically set to the agent on the game object if no agent is provided.")]
         public Agent agent = null;
         protected ScheduleBasedTaskSystem taskSystem;
         [Space(10)]
-        [Tooltip("Response will always be the dummyMessage instead of actually contacting the OpenAPI")]
+        /// <summary>
+        /// If true the response will always be the dummyMessage instead of actually contacting the OpenAPI
+        /// </summary>
+        [Tooltip("If true response will always be the dummyMessage instead of actually contacting the OpenAPI")]
         public bool useDummyMessage = true;
         public string dummyMessage = "The RWTH Aachen has approximately 45,000 students. doWave() \r\n\r\n SPARQL-Query:\r\n SELECT ?studentCount WHERE {\r\n  wd:Q273263 wdt:P2196 ?studentCount .\r\n}";
+        /// <summary>
+        /// Model of the ChatGPT AI that is uses, see OpenAI documentation for model names
+        /// </summary>
         [Tooltip("Model of the ChatGPT AI that is uses, see OpenAI documentation for model names")]
         public string model = "gpt-3.5-turbo-1106";
+        /// <summary>
+        /// If true the response will be streamed, one word after another.
+        /// </summary>
         [Tooltip("If true the response will be streamed, one word after another.")]
         public bool streamResponse = false;
         private CancellationTokenSource token = new CancellationTokenSource();
@@ -345,7 +374,7 @@ namespace i5.VirtualAgents
             string query = message.Substring(splitIndex + startingString.Length);
 
             // Remove any whitespace from the query.
-            query = query.Trim().Replace("\n", null).Replace("\r", null).Replace("```", "").Replace("´´´", ""); ;
+            query = query.Trim().Replace("\n", null).Replace("\r", null).Replace("```", "").Replace("���", ""); ;
             Debug.Log("Extracted Query: " + query);
 
 

Assets/Virtual Agents Framework/Runtime/Scripts/LLMIntegration/WikiDataAPI.cs

@@ -4,17 +4,29 @@
 using System.Threading.Tasks;
 using UnityEngine;
 
-namespace i5.VirtualAgents
+namespace i5.VirtualAgents.LLM
 {
     public class WikiDataAPI : MonoBehaviour, IQueryAPI
     {
+        /// <summary>
+        /// The query type name that will be provided to the LLM to build the a query with the correct syntax.
+        /// </summary>
         [Tooltip("Query type name that will be provided to the LLM to build the a query with the correct syntax.")]
         public string QueryTypeName { get; set; }
+        /// <summary>
+        /// Service name that will be provided to the LLM so that it could use datapoints known by the LLM.
+        /// </summary>
         [Tooltip("Service name that will be provided to the LLM so that it could use datapoints known by the LLM.")]
         public string ServiceName { get; set; }
+        /// <summary>
+        /// This example data can provided further examples for the LLM of how a query should look like, what the specifed service name offers or include additional ids of datapoints.
+        /// </summary>
         [Tooltip("This example data can provided further examples for the LLM of how a query should look like, what the specifed service name offers or include additional ids of datapoints.")]
         public string ExampleData { get; set; }
 
+        /// <summary>
+        /// Please enter your email address here. This is required by the WikiData API to idetify spam, see Wikidata Query Service User Manuel SPARQL Endpoint.
+        /// </summary>
         [SerializeField]
         [Tooltip("Please enter your email address here. This is required by the WikiData API to idetify spam, see Wikidata Query Service User Manuel SPARQL Endpoint.")]
         private string email = "";
@@ -24,7 +36,7 @@ public WikiDataAPI()
         {
             QueryTypeName = "SPARQL";
             ServiceName = "WikiData";
-            ExampleData = "The RWTH Aachen is Q273263 in wikidata.";
+            ExampleData = "The RWTH Aachen is Q273263 in WikiData.";
         }
         public async Task<string> SendQueryToAPI(string sparqlQuery)
         {

Documentation/manual/open-ai-integration.md

@@ -0,0 +1,22 @@
+# OpenAI Integration
+The Virtual Agents Framework provides a script to easily utilize the ChatGPT models provided by OpenAI. 
+
+
+## Explanation of External Package
+To keep the Virtual Agents Framework lightweight an external package needed for the OpenAI integration needs to be added on-demand when the feature is used. 
+In the top menu of Unity click ``Virtual Agents Framework`` > ``OpenAI`` > ``Add unofficial OpenAI Helper Package`` to automatically add the needed package to the Unity Package Manager. Click ``Remove unofficial OpenAI Helper Package`` when the feature is no longer in use. The package that is added can be found [here](https://github.com/srcnalt/OpenAI-Unity).
+
+# OpenAI Script
+As the OpenAI API is a paid service you need to set up your own account, paying method and credentials. Follow the steps [here](https://github.com/srcnalt/OpenAI-Unity?tab=readme-ov-file#setting-up-your-openai-account) to create your own OpenAI Account with an API Key. Save your credentials locally like explained [here](https://github.com/srcnalt/OpenAI-Unity?tab=readme-ov-file#setting-up-your-openai-account).
+
+After that you can use the <xref:i5.VirtualAgents.OpenAIController> script, which can be added to any object or an agent. See the tooltips in the inspector or documentation of the script for further explanations of its options.
+
+# Data Query APIs
+
+The OpenAIController has the option to extend the knowledge of the ChatGPT by taking queries from a separate database. The chatbot will be asked to create relevant queries that ask for more or updated information. The result of that query will be given to the agent to enhance its answer to the user. The user will only see the message with the updated information. Information about the query language, database and API needs to be provided in a script that inherited from <xref:i5.VirtualAgents.IQueryAPI>. The Virtual Agents Framework provides one implementation that uses the public knowledge base [WikiData](https://www.wikidata.org/wiki/Wikidata:Main_Page). <xref:i5.VirtualAgents.WikiDataAPI> specifies that the used query language is SPARQL, that the service name is WikiData and as example data what the data point of the RWTH Aachen is, so that the agent can use that as a starting point.
+
+
+
+
+
+

Documentation/manual/toc.yml

@@ -14,6 +14,8 @@
       href: adaptive-gaze.md
     - name: Aiming and Pointing
       href: aiming.md
+    - name: OpenAI Integration
+      href: open-ai-integration.md
 - name: Customization
   items:
     - name: Adding Own Agent Models and Animations

Documentation/readme.txt

@@ -1 +1,2 @@
-Documentation was generated using DocFx 2.61.0
+Documentation was generated using DocFx 2.61.0
+Generate with: docfx docfx.json --serve