Grammar refactored to support multiple formats (#94)

Madzionator · web-flow · commit f6388b016b17 · 2025-10-08T14:17:56.000+02:00
diff --git a/Examples/Examples/Chat/ChatCustomGrammarExample.cs b/Examples/Examples/Chat/ChatCustomGrammarExample.cs
@@ -1,26 +1,27 @@
-using LLama.Sampling;
 using MaIN.Core.Hub;
 using MaIN.Domain.Entities;
+using MaIN.Domain.Models;
+using Grammar = MaIN.Domain.Models.Grammar;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatCustomGrammarExample : IExample
 {
     public async Task Start()
     {
         Console.WriteLine("ChatExample with grammar is running!");
 
-        var personGrammar = """
-                            root ::= person
-                            person ::= "{" ws "\"name\":" ws name "," ws "\"age\":" ws age "," ws "\"city\":" ws city ws "}"
-                            name ::= "\"" [A-Za-z ]+ "\""
-                            age ::= [1-9] | [1-9][0-9]
-                            city ::= "\"" [A-Za-z ]+ "\""
-                            ws ::= [ \t]*
-                            """;
+        var personGrammar = new Grammar("""
+                                        root ::= person
+                                        person ::= "{" ws "\"name\":" ws name "," ws "\"age\":" ws age "," ws "\"city\":" ws city ws "}"
+                                        name ::= "\"" [A-Za-z ]+ "\""
+                                        age ::= [1-9] | [1-9][0-9]
+                                        city ::= "\"" [A-Za-z ]+ "\""
+                                        ws ::= [ \t]*
+                                        """, GrammarFormat.GBNF);
 
         await AIHub.Chat()
-            .WithInferenceParams(new InferenceParams()
+            .WithInferenceParams(new InferenceParams
             {
                 Grammar = personGrammar
             })
diff --git a/Examples/Examples/Chat/ChatExample.cs b/Examples/Examples/Chat/ChatExample.cs
@@ -1,6 +1,6 @@
 using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatExample : IExample
 {
diff --git a/Examples/Examples/Chat/ChatExampleAnthropic.cs b/Examples/Examples/Chat/ChatExampleAnthropic.cs
@@ -1,7 +1,7 @@
 using Examples.Utils;
 using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatExampleAnthropic : IExample
 {
diff --git a/Examples/Examples/Chat/ChatExampleGemini.cs b/Examples/Examples/Chat/ChatExampleGemini.cs
@@ -1,7 +1,7 @@
 using Examples.Utils;
 using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatExampleGemini : IExample
 {
diff --git a/Examples/Examples/Chat/ChatExampleGroqCloud.cs b/Examples/Examples/Chat/ChatExampleGroqCloud.cs
@@ -1,8 +1,7 @@
 using Examples.Utils;
 using MaIN.Core.Hub;
-using MaIN.Domain.Configuration;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatExampleGroqCloud : IExample
 {
diff --git a/Examples/Examples/Chat/ChatExampleOpenAi.cs b/Examples/Examples/Chat/ChatExampleOpenAi.cs
@@ -1,8 +1,7 @@
 using Examples.Utils;
 using MaIN.Core.Hub;
-using MaIN.Domain.Configuration;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatExampleOpenAi : IExample
 {
diff --git a/Examples/Examples/Chat/ChatFromExistingExample.cs b/Examples/Examples/Chat/ChatFromExistingExample.cs
@@ -1,7 +1,7 @@
 using System.Text.Json;
 using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatFromExistingExample : IExample
 {
diff --git a/Examples/Examples/Chat/ChatGrammarExampleGemini.cs b/Examples/Examples/Chat/ChatGrammarExampleGemini.cs
@@ -0,0 +1,49 @@
+using Examples.Utils;
+using MaIN.Core.Hub;
+using MaIN.Domain.Entities;
+using MaIN.Domain.Models;
+
+namespace Examples.Chat;
+
+public class ChatGrammarExampleGemini : IExample
+{
+    public async Task Start()
+    {
+        GeminiExample.Setup(); //We need to provide Gemini API key
+        Console.WriteLine("(Gemini) ChatExample is running!");
+
+        var grammarValue = """
+                           {
+                             "$schema": "https://json-schema.org/draft/2020-12/schema",
+                             "title": "User",
+                             "type": "object",
+                             "properties": {
+                               "name": {
+                                 "type": "string",
+                                 "description": "Full name of the user."
+                               },
+                               "age": {
+                                 "type": "integer",
+                                 "minimum": 0,
+                                 "description": "User's age in years."
+                               },
+                               "email": {
+                                 "type": "string",
+                                 "format": "email",
+                                 "description": "User's email address."
+                               }
+                             },
+                             "required": ["name", "email"]
+                           }
+                           """;
+
+        await AIHub.Chat()
+            .WithInferenceParams(new InferenceParams
+            {
+                Grammar = new Grammar(grammarValue, GrammarFormat.JSONSchema)
+            })
+            .WithModel("gemini-2.5-flash")
+            .WithMessage("Generate random person")
+            .CompleteAsync(interactive: true);
+    }
+}
diff --git a/Examples/Examples/Chat/ChatWithFilesExample.cs b/Examples/Examples/Chat/ChatWithFilesExample.cs
@@ -1,6 +1,6 @@
 using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatWithFilesExample : IExample
 {
diff --git a/Examples/Examples/Chat/ChatWithFilesExampleGemini.cs b/Examples/Examples/Chat/ChatWithFilesExampleGemini.cs
@@ -1,7 +1,7 @@
 using Examples.Utils;
 using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatWithFilesExampleGemini : IExample
 {
diff --git a/Examples/Examples/Chat/ChatWithFilesFromStreamExample.cs b/Examples/Examples/Chat/ChatWithFilesFromStreamExample.cs
@@ -1,6 +1,6 @@
 ﻿using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 //TODO: this will be moved to test cases. It's same as normal files but I want to test streams
 public class ChatWithFilesFromStreamExample : IExample
diff --git a/Examples/Examples/Chat/ChatWithImageGenExample.cs b/Examples/Examples/Chat/ChatWithImageGenExample.cs
@@ -1,7 +1,7 @@
 using Examples.Utils;
 using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatWithImageGenExample : IExample
 {
diff --git a/Examples/Examples/Chat/ChatWithImageGenGeminiExample.cs b/Examples/Examples/Chat/ChatWithImageGenGeminiExample.cs
@@ -1,7 +1,7 @@
 using Examples.Utils;
 using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatWithImageGenGeminiExample : IExample
 {
diff --git a/Examples/Examples/Chat/ChatWithImageGenOpenAiExample.cs b/Examples/Examples/Chat/ChatWithImageGenOpenAiExample.cs
@@ -1,8 +1,7 @@
 using Examples.Utils;
 using MaIN.Core.Hub;
-using MaIN.Domain.Models;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatWithImageGenOpenAiExample : IExample
 {
diff --git a/Examples/Examples/Chat/ChatWithReasoningDeepSeekExample.cs b/Examples/Examples/Chat/ChatWithReasoningDeepSeekExample.cs
@@ -1,7 +1,7 @@
 using Examples.Utils;
 using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatWithReasoningDeepSeekExample : IExample
 {
diff --git a/Examples/Examples/Chat/ChatWithReasoningExample.cs b/Examples/Examples/Chat/ChatWithReasoningExample.cs
@@ -1,6 +1,6 @@
 using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatWithReasoningExample : IExample
 {
diff --git a/Examples/Examples/Chat/ChatWithTextToSpeechExample.cs b/Examples/Examples/Chat/ChatWithTextToSpeechExample.cs
@@ -2,7 +2,7 @@
 using MaIN.Domain.Entities;
 using MaIN.Services.Services.TTSService;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatWithTextToSpeechExample : IExample
 {
diff --git a/Examples/Examples/Chat/ChatWithVisionExample.cs b/Examples/Examples/Chat/ChatWithVisionExample.cs
@@ -1,6 +1,6 @@
 using MaIN.Core.Hub;
 
-namespace Examples;
+namespace Examples.Chat;
 
 public class ChatWithVisionExample : IExample
 {
diff --git a/Examples/Examples/Program.cs b/Examples/Examples/Program.cs
@@ -1,6 +1,7 @@
 ﻿using Examples;
 using Examples.Agents;
 using Examples.Agents.Flows;
+using Examples.Chat;
 using Examples.Mcp;
 using MaIN.Core;
 using Microsoft.Extensions.Configuration;
@@ -68,6 +69,7 @@ static void RegisterExamples(IServiceCollection services)
     services.AddTransient<AgentWithWebDataSourceOpenAiExample>();
     services.AddTransient<ChatWithImageGenOpenAiExample>();
     services.AddTransient<ChatExampleGemini>();
+    services.AddTransient<ChatGrammarExampleGemini>();
     services.AddTransient<ChatWithImageGenGeminiExample>();
     services.AddTransient<ChatWithFilesExampleGemini>();
     services.AddTransient<ChatWithReasoningDeepSeekExample>();
@@ -160,6 +162,7 @@ public class ExampleRegistry(IServiceProvider serviceProvider)
             ("\u25a0 OpenAi Chat with image", serviceProvider.GetRequiredService<ChatWithImageGenOpenAiExample>()),
             ("\u25a0 OpenAi Agent with Web Data Source", serviceProvider.GetRequiredService<AgentWithWebDataSourceOpenAiExample>()),
             ("\u25a0 Gemini Chat", serviceProvider.GetRequiredService<ChatExampleGemini>()),
+            ("\u25a0 Gemini Chat with grammar", serviceProvider.GetRequiredService<ChatGrammarExampleGemini>()),
             ("\u25a0 Gemini Chat with image", serviceProvider.GetRequiredService<ChatWithImageGenGeminiExample>()),
             ("\u25a0 Gemini Chat with files", serviceProvider.GetRequiredService<ChatWithFilesExampleGemini>()),
             ("\u25a0 DeepSeek Chat with reasoning", serviceProvider.GetRequiredService<ChatWithReasoningDeepSeekExample>()),
diff --git a/Releases/0.6.4.md b/Releases/0.6.4.md
@@ -0,0 +1,15 @@
+# 0.6.4 release
+
+Grammar handling has been refactored to support multiple grammar formats. Definitions must now be wrapped in a Grammar object with an explicit format selection. Currently supported formats: GBNF, JSONSchema.
+
+// before:
+.WithInferenceParams(new InferenceParams
+{
+    Grammar = grammarText;
+})
+
+// after:
+.WithInferenceParams(new InferenceParams
+{
+    Grammar = new Grammar(grammarText, GrammarFormat.GBNF)
+})
diff --git a/src/MaIN.Core/.nuspec b/src/MaIN.Core/.nuspec
@@ -2,7 +2,7 @@
 <package>
   <metadata>
     <id>MaIN.NET</id>
-    <version>0.6.3</version>
+    <version>0.6.4</version>
     <authors>Wisedev</authors>
     <owners>Wisedev</owners>
     <icon>favicon.png</icon>
diff --git a/src/MaIN.Domain/Entities/InferenceParams.cs b/src/MaIN.Domain/Entities/InferenceParams.cs
@@ -1,4 +1,4 @@
-using LLama.Sampling;
+using Grammar = MaIN.Domain.Models.Grammar;
 
 namespace MaIN.Domain.Entities;
 
@@ -19,5 +19,5 @@ public class InferenceParams
     
     public int TopK { get; init; } = 40;
     public float TopP { get; init; } = 0.9f;
-    public string? Grammar { get; set; }
+    public Grammar? Grammar { get; set; }
 }
diff --git a/src/MaIN.Domain/Entities/MemoryParams.cs b/src/MaIN.Domain/Entities/MemoryParams.cs
@@ -1,4 +1,6 @@
-﻿namespace MaIN.Domain.Entities;
+﻿using MaIN.Domain.Models;
+
+namespace MaIN.Domain.Entities;
 
 public class MemoryParams
 {
@@ -17,6 +19,6 @@ public class MemoryParams
 
     public bool MultiModalMode { get; set; } = false;
     
-    public string? Grammar { get; set; }
+    public Grammar? Grammar { get; set; }
     public bool IncludeQuestionSource { get; set; } = false;
 }
diff --git a/src/MaIN.Domain/Models/Grammar.cs b/src/MaIN.Domain/Models/Grammar.cs
@@ -0,0 +1,3 @@
+﻿namespace MaIN.Domain.Models;
+
+public record Grammar(string Value, GrammarFormat Format);
diff --git a/src/MaIN.Domain/Models/GrammarFormat.cs b/src/MaIN.Domain/Models/GrammarFormat.cs
@@ -0,0 +1,7 @@
+﻿namespace MaIN.Domain.Models;
+
+public enum GrammarFormat
+{
+    GBNF = 0,
+    JSONSchema = 1
+}
diff --git a/src/MaIN.Infrastructure/Models/InterferenceParamsDocument.cs b/src/MaIN.Infrastructure/Models/InterferenceParamsDocument.cs
@@ -1,4 +1,4 @@
-using LLama.Sampling;
+using Grammar = MaIN.Domain.Models.Grammar;
 
 namespace MaIN.Infrastructure.Models;
 
@@ -17,5 +17,5 @@ public class InferenceParamsDocument
     public int MaxTokens { get; set; }
     public int TopK { get; init; }
     public float TopP { get; init; }
-    public string? Grammar { get; set; }
+    public Grammar? Grammar { get; set; }
 }
diff --git a/src/MaIN.Infrastructure/Models/MemoryParamsDocument.cs b/src/MaIN.Infrastructure/Models/MemoryParamsDocument.cs
@@ -1,3 +1,5 @@
+using MaIN.Domain.Models;
+
 namespace MaIN.Infrastructure.Models;
 
 public class MemoryParamsDocument
@@ -9,5 +11,5 @@ public class MemoryParamsDocument
     public float Temperature { get; set; } 
     public int AnswerTokens { get; set; }
     public bool MultiModalMode { get; set; }
-    public string? Grammar { get; set; }
+    public Grammar? Grammar { get; set; }
 }
diff --git a/src/MaIN.Infrastructure/Models/MessageDocument.cs b/src/MaIN.Infrastructure/Models/MessageDocument.cs
@@ -1,5 +1,3 @@
-using MaIN.Domain.Models;
-
 namespace MaIN.Infrastructure.Models;
 
 public class MessageDocument
diff --git a/src/MaIN.Services/Services/LLMService/AnthropicService.cs b/src/MaIN.Services/Services/LLMService/AnthropicService.cs
@@ -186,7 +186,7 @@ private async Task ProcessStreamingChatAsync(
             model = chat.Model,
             max_tokens = chat.InterferenceParams.MaxTokens < 0 ? 4096 : chat.InterferenceParams.MaxTokens,
             stream = true,
-            system = chat.InterferenceParams.Grammar is not null ? $"Respond only using the following grammar format: \n{chat.InterferenceParams.Grammar}\n. Do not add explanations, code tags, or any extra content." : "",
+            system = chat.InterferenceParams.Grammar is not null ? $"Respond only using the following grammar format: \n{chat.InterferenceParams.Grammar.Value}\n. Do not add explanations, code tags, or any extra content." : "",
             messages = await OpenAiCompatibleService.BuildMessagesArray(conversation, chat, ImageType.AsBase64)
             //todo: Add thinking support
         };
@@ -283,7 +283,7 @@ private async Task ProcessNonStreamingChatAsync(
             model = chat.Model,
             max_tokens = chat.InterferenceParams.MaxTokens < 0 ? 4096 : chat.InterferenceParams.MaxTokens,
             stream = false,
-            system = chat.InterferenceParams.Grammar is not null ? $"Respond only using the following grammar format: \n{chat.InterferenceParams.Grammar}\n. Do not add explanations, code tags, or any extra content." : "",
+            system = chat.InterferenceParams.Grammar is not null ? $"Respond only using the following grammar format: \n{chat.InterferenceParams.Grammar.Value}\n. Do not add explanations, code tags, or any extra content." : "",
             messages = await OpenAiCompatibleService.BuildMessagesArray(conversation, chat, ImageType.AsBase64)
         };
 
diff --git a/src/MaIN.Services/Services/LLMService/GeminiService.cs b/src/MaIN.Services/Services/LLMService/GeminiService.cs
@@ -82,7 +82,7 @@ protected override void ValidateApiKey()
         var userQuery = chat.Messages.Last().Content;
         if (chat.MemoryParams.Grammar != null)
         {
-            var jsonGrammarConverter = new GBNFToJsonConverter();
+            var jsonGrammarConverter = new GrammarToJsonConverter();
             var jsonGrammar = jsonGrammarConverter.ConvertToJson(chat.MemoryParams.Grammar);
             userQuery =
                 $"{userQuery} | For your next response only, please respond using exactly the following JSON format: \n{jsonGrammar}\n. Do not include any explanations, code blocks, or additional content. After this single JSON response, resume your normal conversational style.";
diff --git a/src/MaIN.Services/Services/LLMService/LLMService.cs b/src/MaIN.Services/Services/LLMService/LLMService.cs
diff --git a/src/MaIN.Services/Services/LLMService/Memory/KernelMemoryLlamaExtensions.cs b/src/MaIN.Services/Services/LLMService/Memory/KernelMemoryLlamaExtensions.cs
diff --git a/src/MaIN.Services/Services/LLMService/OpenAiCompatibleService.cs b/src/MaIN.Services/Services/LLMService/OpenAiCompatibleService.cs
diff --git a/src/MaIN.Services/Services/Steps/Commands/AnswerCommandHandler.cs b/src/MaIN.Services/Services/Steps/Commands/AnswerCommandHandler.cs
diff --git a/src/MaIN.Services/Utils/GNNFJsonConverter.cs b/src/MaIN.Services/Utils/GNNFJsonConverter.cs
diff --git a/src/MaIN.Services/Utils/GrammarToJsonConverter.cs b/src/MaIN.Services/Utils/GrammarToJsonConverter.cs

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`using MaIN.Core.Hub;`
`2`	`2`
`3`		`-namespace Examples;`
	`3`	`+namespace Examples.Chat;`
`4`	`4`
`5`	`5`	`public class ChatExample : IExample`
`6`	`6`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`using Examples.Utils;`
`2`	`2`	`using MaIN.Core.Hub;`
`3`	`3`
`4`		`-namespace Examples;`
	`4`	`+namespace Examples.Chat;`
`5`	`5`
`6`	`6`	`public class ChatExampleAnthropic : IExample`
`7`	`7`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,7 @@`
`1`	`1`	`using Examples.Utils;`
`2`	`2`	`using MaIN.Core.Hub;`
`3`		`-using MaIN.Domain.Configuration;`
`4`	`3`
`5`		`-namespace Examples;`
	`4`	`+namespace Examples.Chat;`
`6`	`5`
`7`	`6`	`public class ChatExampleGroqCloud : IExample`
`8`	`7`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`using System.Text.Json;`
`2`	`2`	`using MaIN.Core.Hub;`
`3`	`3`
`4`		`-namespace Examples;`
	`4`	`+namespace Examples.Chat;`
`5`	`5`
`6`	`6`	`public class ChatFromExistingExample : IExample`
`7`	`7`	`{`