Fix OpenAPI doc and remove "Citation" class duplication

microsoft · Aug 16, 2023 · e7b465f · e7b465f
1 parent 75330f9
commit e7b465f
Show file tree

Hide file tree

Showing 5 changed files with 73 additions and 119 deletions.
diff --git a/README.md b/README.md
@@ -244,6 +244,11 @@ var pipeline = orchestrator
 await orchestrator.RunPipelineAsync(pipeline);
 ```
 
+# Web API specs
+
+The API schema is available at http://127.0.0.1:9001/swagger/index.html when
+running the service locally with OpenAPI enabled.
+
 # Examples and Tools
 
 1. [Using the web service](samples/dotnet-WebClient)

diff --git a/dotnet/ClientLib/Models/Citation.cs b/dotnet/ClientLib/Models/Citation.cs
@@ -0,0 +1,63 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.SemanticMemory.Client.Models;
+
+public class Citation
+{
+    /// <summary>
+    /// Link to the source, if available.
+    /// </summary>
+    [JsonPropertyName("link")]
+    [JsonPropertyOrder(1)]
+    public string Link { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Type of source, e.g. PDF, Word, Chat, etc.
+    /// </summary>
+    [JsonPropertyName("sourceContentType")]
+    [JsonPropertyOrder(2)]
+    public string SourceContentType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Name of the source, e.g. file name.
+    /// </summary>
+    [JsonPropertyName("sourceName")]
+    [JsonPropertyOrder(3)]
+    public string SourceName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// List of chunks/blocks of text used.
+    /// </summary>
+    [JsonPropertyName("partitions")]
+    [JsonPropertyOrder(4)]
+    public List<Partition> Partitions { get; set; } = new();
+
+    public class Partition
+    {
+        /// <summary>
+        /// Content of the document partition, aka chunk/block of text.
+        /// </summary>
+        [JsonPropertyName("text")]
+        [JsonPropertyOrder(1)]
+        public string Text { get; set; } = string.Empty;
+
+        /// <summary>
+        /// Relevance of this partition against the given query.
+        /// Value usually is between 0 and 1, when using cosine similarity.
+        /// </summary>
+        [JsonPropertyName("relevance")]
+        [JsonPropertyOrder(2)]
+        public float Relevance { get; set; } = 0;
+
+        /// <summary>
+        /// Timestamp about the file/text partition.
+        /// </summary>
+        [JsonPropertyName("lastUpdate")]
+        [JsonPropertyOrder(4)]
+        public DateTimeOffset LastUpdate { get; set; } = DateTimeOffset.MinValue;
+    }
+}
diff --git a/dotnet/ClientLib/Models/MemoryAnswer.cs b/dotnet/ClientLib/Models/MemoryAnswer.cs
@@ -1,6 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using System;
 using System.Collections.Generic;
 using System.Text.Json;
 using System.Text.Json.Serialization;
@@ -32,62 +31,6 @@ public class MemoryAnswer
     [JsonPropertyOrder(3)]
     public List<Citation> RelevantSources { get; set; } = new();
 
-    public class Citation
-    {
-        /// <summary>
-        /// Link to the source, if available.
-        /// </summary>
-        [JsonPropertyName("link")]
-        [JsonPropertyOrder(1)]
-        public string Link { get; set; } = string.Empty;
-
-        /// <summary>
-        /// Type of source, e.g. PDF, Word, Chat, etc.
-        /// </summary>
-        [JsonPropertyName("sourceContentType")]
-        [JsonPropertyOrder(2)]
-        public string SourceContentType { get; set; } = string.Empty;
-
-        /// <summary>
-        /// Name of the source, e.g. file name.
-        /// </summary>
-        [JsonPropertyName("sourceName")]
-        [JsonPropertyOrder(3)]
-        public string SourceName { get; set; } = string.Empty;
-
-        /// <summary>
-        /// List of chunks/blocks of text used.
-        /// </summary>
-        [JsonPropertyName("partitions")]
-        [JsonPropertyOrder(4)]
-        public List<Partition> Partitions { get; set; } = new();
-
-        public class Partition
-        {
-            /// <summary>
-            /// Content of the document partition, aka chunk/block of text.
-            /// </summary>
-            [JsonPropertyName("text")]
-            [JsonPropertyOrder(1)]
-            public string Text { get; set; } = string.Empty;
-
-            /// <summary>
-            /// Relevance of this partition against the given query.
-            /// Value usually is between 0 and 1, when using cosine similarity.
-            /// </summary>
-            [JsonPropertyName("relevance")]
-            [JsonPropertyOrder(2)]
-            public float Relevance { get; set; } = 0;
-
-            /// <summary>
-            /// Timestamp about the file/text partition.
-            /// </summary>
-            [JsonPropertyName("lastUpdate")]
-            [JsonPropertyOrder(4)]
-            public DateTimeOffset LastUpdate { get; set; } = DateTimeOffset.MinValue;
-        }
-    }
-
     /// <summary>
     /// Serialize using .NET JSON serializer, e.g. to avoid ambiguity
     /// with other serializers and other options

diff --git a/dotnet/ClientLib/Models/SearchResult.cs b/dotnet/ClientLib/Models/SearchResult.cs
@@ -1,6 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using System;
 using System.Collections.Generic;
 using System.Text.Json;
 using System.Text.Json.Serialization;
@@ -25,62 +24,6 @@ public class SearchResult
     [JsonPropertyOrder(3)]
     public List<Citation> Results { get; set; } = new();
 
-    public class Citation
-    {
-        /// <summary>
-        /// Link to the source, if available.
-        /// </summary>
-        [JsonPropertyName("link")]
-        [JsonPropertyOrder(1)]
-        public string Link { get; set; } = string.Empty;
-
-        /// <summary>
-        /// Type of source, e.g. PDF, Word, Chat, etc.
-        /// </summary>
-        [JsonPropertyName("sourceContentType")]
-        [JsonPropertyOrder(2)]
-        public string SourceContentType { get; set; } = string.Empty;
-
-        /// <summary>
-        /// Name of the source, e.g. file name.
-        /// </summary>
-        [JsonPropertyName("sourceName")]
-        [JsonPropertyOrder(3)]
-        public string SourceName { get; set; } = string.Empty;
-
-        /// <summary>
-        /// List of chunks/blocks of text used.
-        /// </summary>
-        [JsonPropertyName("partitions")]
-        [JsonPropertyOrder(4)]
-        public List<Partition> Partitions { get; set; } = new();
-
-        public class Partition
-        {
-            /// <summary>
-            /// Content of the document partition, aka chunk/block of text.
-            /// </summary>
-            [JsonPropertyName("text")]
-            [JsonPropertyOrder(1)]
-            public string Text { get; set; } = string.Empty;
-
-            /// <summary>
-            /// Relevance of this partition against the given query.
-            /// Value usually is between 0 and 1, when using cosine similarity.
-            /// </summary>
-            [JsonPropertyName("relevance")]
-            [JsonPropertyOrder(2)]
-            public float Relevance { get; set; } = 0;
-
-            /// <summary>
-            /// Timestamp about the file/text partition.
-            /// </summary>
-            [JsonPropertyName("lastUpdate")]
-            [JsonPropertyOrder(4)]
-            public DateTimeOffset LastUpdate { get; set; } = DateTimeOffset.MinValue;
-        }
-    }
-
     /// <summary>
     /// Serialize using .NET JSON serializer, e.g. to avoid ambiguity
     /// with other serializers and other options

diff --git a/dotnet/CoreLib/Search/SearchClient.cs b/dotnet/CoreLib/Search/SearchClient.cs
@@ -60,7 +60,7 @@ public async Task<SearchResult> SearchAsync(string index, string query, MemoryFi
         var result = new SearchResult
         {
             Query = query,
-            Results = new List<SearchResult.Citation>()
+            Results = new List<Citation>()
         };
 
         if (string.IsNullOrEmpty(query))
@@ -123,7 +123,7 @@ public async Task<SearchResult> SearchAsync(string index, string query, MemoryFi
             var citation = result.Results.FirstOrDefault(x => x.Link == linkToFile);
             if (citation == null)
             {
-                citation = new SearchResult.Citation();
+                citation = new Citation();
                 result.Results.Add(citation);
             }
 
@@ -136,7 +136,7 @@ public async Task<SearchResult> SearchAsync(string index, string query, MemoryFi
             DateTimeOffset.TryParse(memory.Payload["last_update"].ToString(), out var lastUpdate);
 #pragma warning restore CA1806
 
-            citation.Partitions.Add(new SearchResult.Citation.Partition
+            citation.Partitions.Add(new Citation.Partition
             {
                 Text = partitionText,
                 Relevance = (float)relevance,
@@ -247,7 +247,7 @@ public async Task<MemoryAnswer> AskAsync(string index, string question, MemoryFi
                 var citation = answer.RelevantSources.FirstOrDefault(x => x.Link == linkToFile);
                 if (citation == null)
                 {
-                    citation = new MemoryAnswer.Citation();
+                    citation = new Citation();
                     answer.RelevantSources.Add(citation);
                 }
 
@@ -260,7 +260,7 @@ public async Task<MemoryAnswer> AskAsync(string index, string question, MemoryFi
                 DateTimeOffset.TryParse(memory.Payload["last_update"].ToString(), out var lastUpdate);
 #pragma warning restore CA1806
 
-                citation.Partitions.Add(new MemoryAnswer.Citation.Partition
+                citation.Partitions.Add(new Citation.Partition
                 {
                     Text = partitionText,
                     Relevance = (float)relevance,