Graph visualization and end nodes

- Add graph visualization using GraphViz
- Make tool to add end nodes when deem a logical end

Co-authored-by: Sarmisuper <stharm20@student.aau.dk>

Author: KarmaKamikaze

ChatRPG/API/Tools/AddEdgeTool.cs

@@ -32,7 +32,7 @@ public class AddEdgeTool(
             return addEdgeErrorMessage ?? "Failed to add edge.";
         }
 
-        return $"The graph has been updated. From now on, use the updated graph::\n{graph.Serialize()}";
+        return $"The graph has been updated. From now on, use the updated graph:\n{graph.Serialize()}";
     }
 
     private static bool IsValidJson(AddEdgeInput jsonEdge, out string? errorMessage)
@@ -55,27 +55,7 @@ private static bool TryAddEdge(NarrativeGraph graph, AddEdgeInput newEdge, out s
         existingNodes.TryGetValue(newEdge.SourceNodeName!, out var sourceNode);
         existingNodes.TryGetValue(newEdge.TargetNodeName!, out var targetNode);
 
-        var errorMessages = new List<string>();
-
-        if (targetNode is null)
-        {
-            errorMessages.Add($"Target node with name {newEdge.TargetNodeName} not found.");
-        }
-
-        if (sourceNode is null)
-        {
-            errorMessages.Add($"Source node with name {newEdge.SourceNodeName} not found.");
-        }
-        else if (sourceNode == targetNode)
-        {
-            errorMessages.Add($"Node {sourceNode.Name} cannot have an edge to itself.");
-        }
-        else if (targetNode is not null && sourceNode.Edges.Any(e => e.TargetNode == targetNode))
-        {
-            errorMessages.Add($"An edge already exists between {newEdge.SourceNodeName} and {newEdge.TargetNodeName}.");
-        }
-
-        if (!ToolUtilities.NodesValidForNewEdge(sourceNode, targetNode, newEdge, out errorMessages))
+        if (!ToolUtilities.NodesValidForNewEdge(sourceNode, targetNode, newEdge, out var errorMessages))
         {
             errorMessage =
                 $"Invalid input provided for the edge. " +

ChatRPG/API/Tools/AddEndNodeInput.cs

@@ -0,0 +1,35 @@
+namespace ChatRPG.API.Tools;
+
+public class AddEndNodeInput
+{
+    public string? SourceNodeName { get; set; }
+
+    public List<string>? Conditions { get; set; }
+
+    public bool IsValid(out List<string> validationErrors)
+    {
+        validationErrors = [];
+
+        if (string.IsNullOrWhiteSpace(SourceNodeName))
+        {
+            validationErrors.Add("SourceNodeName is required");
+        }
+
+        if (Conditions is null || Conditions.Count == 0)
+        {
+            validationErrors.Add("Conditions list is required.");
+        }
+        else
+        {
+            foreach (var condition in Conditions)
+            {
+                if (string.IsNullOrWhiteSpace(condition))
+                {
+                    validationErrors.Add("Condition is required.");
+                }
+            }
+        }
+
+        return validationErrors.Count == 0;
+    }
+}

ChatRPG/API/Tools/AddEndNodeTool.cs

@@ -0,0 +1,73 @@
+using System.Text.Json;
+using ChatRPG.Data.Models;
+using LangChain.Chains.StackableChains.Agents.Tools;
+
+namespace ChatRPG.API.Tools;
+
+public class AddEndNodeTool(
+    NarrativeGraph graph,
+    string name,
+    string? description = null) : AgentTool(name, description)
+{
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        PropertyNameCaseInsensitive = true
+    };
+
+    public override async Task<string> ToolTask(string input, CancellationToken token = new CancellationToken())
+    {
+        await Task.Yield();
+
+        var addEndNodeInput =
+            JsonSerializer.Deserialize<AddEndNodeInput>(ToolUtilities.RemoveMarkdown(input), JsonOptions) ??
+            throw new JsonException("Failed to deserialize");
+
+        if (!IsValidJson(addEndNodeInput, out var jsonValidationError))
+        {
+            return jsonValidationError ?? "Invalid JSON input.";
+        }
+
+        if (!TryAddEndNode(graph, addEndNodeInput, out var addEndNodeErrorMessage))
+        {
+            return addEndNodeErrorMessage ?? "Failed to add edge to end node.";
+        }
+
+        return $"The graph has been updated. From now on, use the updated graph:\n{graph.Serialize()}";
+    }
+
+    private static bool IsValidJson(AddEndNodeInput jsonNode, out string? errorMessage)
+    {
+        if (jsonNode.IsValid(out var errors))
+        {
+            errorMessage = null;
+            return true;
+        }
+
+        errorMessage =
+            $"Invalid input provided for the edge to the end node. Please correct the following errors:\n{string.Join("\n", errors)}";
+        return false;
+    }
+
+    private static bool TryAddEndNode(NarrativeGraph graph, AddEndNodeInput newEndNode, out string? errorMessage)
+    {
+        var sourceNode = graph.Nodes.FirstOrDefault(n => n.Name == newEndNode.SourceNodeName);
+
+        if (sourceNode is null)
+        {
+            errorMessage = $"Source node with name {newEndNode.SourceNodeName} not found.";
+            return false;
+        }
+
+        var endNode = graph.Nodes.FirstOrDefault(n => n.Name == "End");
+
+        if (endNode is null)
+        {
+            endNode = new NarrativeNode("End", "", graph);
+            graph.AddNode(endNode);
+        }
+
+        sourceNode.Edges.Add(new NarrativeEdge(newEndNode.Conditions!, sourceNode, endNode));
+        errorMessage = null;
+        return true;
+    }
+}

ChatRPG/ChatRPG.csproj

@@ -33,10 +33,15 @@
     <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="9.0.4" />
     <PackageReference Include="Radzen.Blazor" Version="6.2.4" />
     <PackageReference Include="RichardSzalay.MockHttp" Version="7.0.0" />
+    <PackageReference Include="Rubjerg.Graphviz" Version="2.0.2" />
   </ItemGroup>
 
   <ItemGroup>
     <InternalsVisibleTo Include="ChatRPGTests" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Folder Include="Visualization\" />
+  </ItemGroup>
+
 </Project>

ChatRPG/Data/Models/NarrativeGraph.cs

@@ -36,6 +36,11 @@ public List<NarrativeNode> GetIncomingNodes(NarrativeNode targetNode)
         return Nodes.FirstOrDefault(node => GetIncomingNodes(node).Count == 0);
     }
 
+    public List<NarrativeNode> GetNodesWithStatus(NarrativeNode.Status status)
+    {
+        return Nodes.Where(n => n.NodeStatus == status).ToList();
+    }
+
     public void InitializeStartNode()
     {
         Nodes.Add(new NarrativeNode("Start", "", this));

ChatRPG/Pages/CampaignPage.razor.cs

@@ -2,6 +2,7 @@
 using ChatRPG.Services;
 using ChatRPG.Data.Models;
 using ChatRPG.Services.Events;
+using ChatRPG.Visualization;
 using Microsoft.AspNetCore.Components;
 using Microsoft.AspNetCore.Components.Authorization;
 using Microsoft.AspNetCore.Components.Web;
@@ -88,6 +89,8 @@ protected override async Task OnInitializedAsync()
         GameInputHandler!.ChatCompletionChunkReceived += OnChatCompletionChunkReceived;
         GameInputHandler!.CampaignUpdated += OnCampaignUpdated;
         _pageInitialized = true;
+
+        GraphVisualization.SaveToPngFile(_campaign!.NarrativeGraph!);
     }
 
     /// <summary>

ChatRPG/Services/ReActScribeAgent.cs

@@ -95,23 +95,35 @@ private static List<AgentTool> CreateTools(NarrativeGraph graph)
             "\"targetnodename\": \"the name of the target node that should be connected using this edge. " +
             "This node can already exist in the graph or it can be this node, if this node is the target \" } ] } " +
             "Each edge must include a list of conditions (which may be empty if no prerequisites exist) and " +
-            "connect either from or to an existing node to maintain coherence in the narrative structure.\n\n " +
+            "connect either from or to an existing node to maintain coherence in the narrative structure. " +
+            "These conditions must be formulated as short easy-to-answer questions.\n\n " +
             "Example Usage:\n " +
+            "Example 1: Gaining Information on The Abandoned Ruins\n " +
             "Scenario Context:\n " +
             "The player is currently at \"The Village of Eldermere\". A new story point is being introduced: " +
             "\"The Abandoned Ruins\", which contains an ancient shrine with hidden inscriptions. The player can " +
-            "only proceed if they have spoken to the village elder.\n " +
+            "only proceed if they have spoken to the village elder and removed a large boulder in the way.\n " +
             "Tool Call Example:\n " +
             "{ \"name\": \"The Abandoned Ruins\", \"storycontent\": \"A crumbling stone structure overgrown " +
             "with vines, hiding an ancient shrine with faded inscriptions. The air is thick with mystery, and a " +
             "sense of forgotten history lingers. Possible discoveries include ancient artifacts and hidden passages.\", " +
-            "\"edges\": [ { \"conditions\": [ \"Has the player spoken to the Village Elder?\" ], " +
+            "\"edges\": [ { \"conditions\": [ \"Has the player spoken to the Village Elder?\", \"Has the player removed the large boulder?\" ], " +
             "\"sourcenodename\": \"The Village of Eldermere\", \"targetnodename\": \"The Abandoned Ruins\" } ] } " +
             "Expected Outcome:\n " +
             "The tool returns an updated string representation of the graph, now including \"The Abandoned Ruins\" " +
-            "as a new node, connected to \"The Village of Eldermere\" via an edge with the condition " +
-            "\"Has the player spoken to the Village Elder?\" You can now verify the structure and ensure " +
-            "that traversal logic remains consistent with the scenario documents.");
+            "as a new node, connected to \"The Village of Eldermere\" via an edge with the conditions " +
+            "\"Has the player spoken to the Village Elder?\" and \"Has the player removed the large boulder?\" You can now verify the structure and ensure " +
+            "that traversal logic remains consistent with the scenario documents.\n " +
+            "Example 2: Entering the Forbidden Archives (No Conditions Required)\n " +
+            "A new node is added when the player discovers the Forbidden Archives, an ancient library containing lost knowledge. \n" +
+            "{ \"name\": \"Forbidden Archives\", \"storycontent\": \"A vast underground library filled with " +
+            "crumbling tomes, forbidden knowledge, and the echoes of long-forgotten scholars. " +
+            "Strange symbols glow faintly on the walls, hinting at secrets waiting to be uncovered.\", " +
+            "\"edges\": [ { \"conditions\": [], \"sourcenodename\": \"Grand Library\", \"targetnodename\": \"Forbidden Archives\" } ] } " +
+            "Outcome:\n " +
+            "- The Forbidden Archives is introduced as a new story node.\n " +
+            "- The Grand Library is directly connected to it without conditions, meaning the player can freely enter the archives.\n " +
+            "- The archives can now serve as a new exploration point with potential clues, puzzles, or hidden dangers.");
         tools.Add(addNodeTool);
 
         var addEdgeTool = new AddEdgeTool(graph, "addedgetool",
@@ -150,14 +162,58 @@ private static List<AgentTool> CreateTools(NarrativeGraph graph)
             "To enter the Royal Chamber, the player must have:\n " +
             "1. Met Sir Ivan, the Wizard, who provides the key to the chamber.\n " +
             "2. Defeated the Elite Guards stationed outside.\n " +
+            "3. Dispelled the magical barrier on the Royal Chamber doors." +
             "Input to AddEdgeTool:\n " +
             "{ \"sourcenodename\": \"Castle Courtyard\", \"targetnodename\": \"Royal Chamber\", \"conditions\": " +
-            "[ \"Has the player met Sir Ivan, the Wizard?\", \"Has the player defeated the Elite Guards?\" ] } " +
+            "[ \"Has the player been granted the key by Sir Ivan, the Wizard?\", \"Has the player defeated the Elite Guards?\", \"Has the player dispelled the magical barrier?\" ] } " +
             "Outcome:\n " +
             "- The Castle Courtyard is now connected to the Royal Chamber.\n " +
-            "- The player cannot enter until both conditions are fulfilled.");
+            "- The player cannot enter until all conditions are fulfilled.");
         tools.Add(addEdgeTool);
 
+        var addEndNodeTool = new AddEndNodeTool(graph, "addendnodetool",
+            "This tool must be used to add a new end node to the narrative graph. An end node represents " +
+            "a definitive conclusion to a story branch, meaning that once the player reaches this point, the " +
+            "story will end. This tool must be used whenever a branch of the story does not loop back to another " +
+            "plot point but instead results in a final outcome.\n " +
+            "There can be multiple possible endings in an adventure scenario, so this tool must be invoked " +
+            "whenever a narrative path leads to a conclusion instead of continuing forward. End nodes should be " +
+            "used to signify significant story resolutions, such as:\n " +
+            "- The player meeting their demise.\n " +
+            "- The player achieving victory.\n " +
+            "- The player failing or being trapped indefinitely.\n " +
+            "- Any other scenario where the player's journey logically concludes.\n" +
+            "Usage Format:\n " +
+            "The tool requires valid JSON input structured as follows:\n " +
+            "{ \"sourcenodename\": \"the name of the source node which already exists in the graph\", " +
+            "\"conditions\": [ \"condition that define if the ending is reached based on the player’s choices\" ] } " +
+            "The conditions list may be empty if the edge does not require prerequisites for traversal.\n" +
+            "Example Usage:\n " +
+            "Example 1: A Hero’s Victory\n " +
+            "If the player successfully defeats the Dark Lord and restores peace, the ending is triggered:\n " +
+            "{ \"sourcenodename\": \"Victory Over the Dark Lord\", " +
+            "\"conditions\": [ \"Has the player defeated the Dark Lord?\" ] } " +
+            "Outcome:\n " +
+            "- This ending is reached only if the player defeats the Dark Lord.\n " +
+            "Example 2: The Player’s Demise\n " +
+            "If the player fails to escape a collapsing dungeon:\n " +
+            "{ \"sourcenodename\": \"Buried Beneath the Ruins\", " +
+            "\"conditions\": [ \"Has the player failed to escape the ruins before time ran out?\" ] } " +
+            "Outcome:\n " +
+            "- The story ends when the player fails to escape the ruins.\n " +
+            "Example 3: The Ascension of the New King\n " +
+            "If the player successfully claims the throne by fulfilling multiple prerequisites:\n " +
+            "{ \"sourcenodename\": \"Ascension to the Throne\", " +
+            "\"conditions\": [ \"Has the player retrieved the Royal Crown?\", " +
+            "\"Has the player gained the support of the High Council?\", " +
+            "\"Has the player defeated the False Heir in battle?\" ] } " +
+            "Outcome:\n " +
+            "- This ending is only reached if the player has:\n " +
+            "\t - Retrieved the Royal Crown, signifying their right to rule.\n " +
+            "\t - Secured the High Council’s approval, ensuring political stability.\n " +
+            "\t - Defeated the False Heir, eliminating rival claims to the throne.");
+        tools.Add(addEndNodeTool);
+
         return tools;
     }
 }

ChatRPG/Services/ScenarioDocumentService.cs

@@ -5,7 +5,6 @@
 using LangChain.Providers.OpenAI.Predefined;
 using LangChain.DocumentLoaders;
 using LangChain.Extensions;
-using LangChain.Providers;
 using LangChain.Splitters.Text;
 using static LangChain.Chains.Chain;
 
@@ -64,7 +63,7 @@ public async Task<string> GenerateStartingScenario(Campaign campaign)
         var prompt = new StringBuilder();
         prompt.Append(_startingScenarioPrompt);
 
-        var chain = Set("Introduce the adventure that the player will embark on", outputKey: "instruction")
+        var chain = Set(CreateRagQuery(campaign), outputKey: "instruction")
                     | RetrieveSimilarDocuments(vectorCollection, embeddingModel, inputKey: "instruction", amount: 20)
                     | CombineDocuments(outputKey: "context")
                     | Template(prompt.ToString())
@@ -74,4 +73,21 @@ public async Task<string> GenerateStartingScenario(Campaign campaign)
 
         return response ?? "System: I'm sorry, I couldn't find any relevant scenarios.";
     }
+
+    private static string CreateRagQuery(Campaign campaign)
+    {
+        var ragQuery = new StringBuilder();
+        ragQuery.AppendLine("Introduce the adventure that the player will embark on.");
+
+        var startNode = campaign.NarrativeGraph!.GetStartNode();
+
+        foreach (var edge in startNode!.Edges)
+        {
+            ragQuery.AppendLine(string.Join(", ", edge.Conditions));
+            ragQuery.AppendLine(edge.TargetNodeName);
+            ragQuery.AppendLine(edge.TargetNode.StoryContent);
+        }
+
+        return ragQuery.ToString();
+    }
 }