Documentation and cleanup

examples/appSettings.json

@@ -6,7 +6,7 @@
     "ApiKey": "?",
     "Model": "gpt-35-turbo"
   },
-  // Custom. Load Config by this name
+  // Custom. Load Open AI Config using this name
   "OpenAI_GPT4": {
     "Azure": true,
     "Endpoint": "?",

src/typechat.dialog/Agent.cs

@@ -5,7 +5,9 @@
 namespace Microsoft.TypeChat.Dialog;
 
 /// <summary>
-/// A multi-turn message passing Agent
+/// Experimental:
+/// A multi-turn message passing Agent that returns strongly typed responses
+/// Message
 /// </summary>
 public class Agent<T>
 {

src/typechat.dialog/Message.cs

@@ -1,18 +1,20 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using Microsoft.VisualBasic;
+
 namespace Microsoft.TypeChat.Dialog;
 
-public class Message<T> : IPromptSection
+public class Message : IPromptSection
 {
     string _source;
-    T _body;
+    object _body;
 
-    public Message(T body)
+    public Message(object body)
         : this(null, body)
     {
     }
 
-    public Message(string from, T body)
+    public Message(string from, object body)
     {
         if (string.IsNullOrEmpty(from))
         {
@@ -23,10 +25,12 @@ public Message(string from, T body)
     }
 
     public string Source => _source;
-
-    public T Body => _body;
-
+    public object Body => _body;
     public Type BodyType => _body.GetType();
+    public MessageHeaders? Headers { get; set; }
+    public object Attachment { get; set; }
+
+    public T GetBody<T>() => (T) _body;
 
     public virtual string GetText()
     {
@@ -36,6 +40,11 @@ public virtual string GetText()
         }
         return _body.Stringify();
     }
+
+    public static implicit operator Message(string text) => new Message(text);
+    public static Message FromUser(object body) => new Message(body);
+    public static Message FromAssistant(object body) => new Message(PromptSection.Sources.Assistant, body);
+
 }
 
 public class MessageHeaders : Dictionary<string, string>
@@ -45,29 +54,3 @@ public MessageHeaders()
     {
     }
 }
-
-/// <summary>
-/// General message
-/// </summary>
-public class Message : Message<object>
-{
-    public Message(object body)
-        : base(body)
-    {
-    }
-
-    public Message(string source, object body)
-        : base(source, body)
-    {
-    }
-
-
-    public MessageHeaders? Headers { get; set; }
-
-    public object Attachment { get; set; }
-
-    public static implicit operator Message(string text) => new Message(text);
-
-    public static Message FromUser(object body) => new Message(body);
-    public static Message FromAssistant(object body) => new Message(PromptSection.Sources.Assistant, body);
-}

src/typechat.program/ProgramSchema.cs

@@ -4,6 +4,8 @@ namespace Microsoft.TypeChat;
 
 /// <summary>
 /// A Json Program. See ProgramSchema.ts for the grammar for Programs
+/// A Program is a set of steps, where each step is a function call.
+/// Function calls can nest and take arguments that are Json values, arrays and objects
 /// This class is the root is a simple AST for programs
 /// </summary>
 [JsonConverter(typeof(JsonProgramConvertor))]
@@ -20,6 +22,7 @@ public Steps? Steps
 
     /// <summary>
     /// Part or all of the user request that could not be translated into program steps
+    /// This is especially handy where the user asks has intent that cannot be mapped to existing APIs
     /// </summary>
     public string[] NotTranslated { get; set; }
 }
@@ -36,6 +39,9 @@ public abstract partial class Expression
 /// </summary>
 public partial class Steps : Expression
 {
+    /// <summary>
+    /// Currently, program steps are a collection of function calls
+    /// </summary>
     public FunctionCall[] Calls
     {
         get;
@@ -45,6 +51,7 @@ public FunctionCall[] Calls
 
 /// <summary>
 /// A Function Call to a named function with zero or more arguments
+/// This call is bound to the API targeted by this program.
 /// </summary>
 public partial class FunctionCall : Expression
 {
@@ -79,6 +86,10 @@ public partial class ResultReference : Expression
 
 /// <summary>
 /// An expression representing a Json value
+/// Supported Json types:
+/// - string
+/// - number
+/// - boolean
 /// </summary>
 public partial class ValueExpr : Expression
 {
@@ -90,10 +101,13 @@ public JsonElement Value
 }
 
 /// <summary>
-/// An array expression - can contain any expression including function calls
+/// An array expression - can contain any expression including Json objects and function calls
 /// </summary>
 public partial class ArrayExpr : Expression
 {
+    /// <summary>
+    /// Any array can be a collection of any expression
+    /// </summary>
     public Expression[] Value
     {
         get;
@@ -102,7 +116,8 @@ public Expression[] Value
 }
 
 /// <summary>
-/// A Json Object. 
+/// A Json Object where the value can be any expression, including values returned
+/// dynamically at runtime by function calls
 /// </summary>
 public partial class ObjectExpr : Expression
 {

src/typechat/JsonTranslatorPrompts.cs

@@ -11,33 +11,40 @@ public class JsonTranslatorPrompts : IJsonTranslatorPrompts
 
     public virtual Prompt CreateRequestPrompt(TypeSchema schema, Prompt request, IList<IPromptSection> preamble = null)
     {
-        return RequestPrompt(schema.TypeFullName, schema.Schema, request, preamble);
+        return RequestPrompt(schema, request, preamble);
     }
 
     public virtual string CreateRepairPrompt(TypeSchema schema, string json, string validationError)
     {
         return RepairPrompt(validationError);
     }
 
-    public static Prompt RequestPrompt(string typeName, string schema, Prompt request, IList<IPromptSection>? context = null)
+    public static Prompt RequestPrompt(TypeSchema typeSchema, Prompt request, IList<IPromptSection>? context = null)
     {
         if (request == null)
         {
             throw new ArgumentNullException(nameof(request));
         }
         Prompt prompt = new Prompt();
 
-        prompt += IntroSection(typeName, schema);
+        prompt += IntroSection(typeSchema.TypeFullName, typeSchema.Schema);
         AddContextAndRequest(prompt, request, context);
 
         return prompt;
     }
 
-    public static Prompt AddContextAndRequest(Prompt prompt, Prompt request, IList<IPromptSection> preamble)
+    /// <summary>
+    /// Add the given user request and any context to the prompt we are sending to the model
+    /// </summary>
+    /// <param name="prompt">prompt being constructed</param>
+    /// <param name="request">user request</param>
+    /// <param name="context">any RAG context</param>
+    /// <returns>prompt to send to the model</returns>
+    public static Prompt AddContextAndRequest(Prompt prompt, Prompt request, IList<IPromptSection> context)
     {
-        if (!preamble.IsNullOrEmpty())
+        if (!context.IsNullOrEmpty())
         {
-            prompt.Append(preamble);
+            prompt.Append(context);
         }
 
         if (request.Count == 1)
@@ -52,15 +59,22 @@ public static Prompt AddContextAndRequest(Prompt prompt, Prompt request, IList<I
         return prompt;
     }
 
-    static PromptSection IntroSection(string typeName, string schema)
+    /// <summary>
+    /// Adds a section that tells the model that its task to is translate requests into JSON matching the
+    /// given schema
+    /// </summary>
+    /// <param name="typeName"></param>
+    /// <param name="schema"></param>
+    /// <returns></returns>
+    public static PromptSection IntroSection(string typeName, string schema)
     {
         PromptSection introSection = new PromptSection();
         introSection += $"You are a service that translates user requests into JSON objects of type \"{typeName}\" according to the following TypeScript definitions:\n";
         introSection += $"###\n{schema}###\n";
         return introSection;
     }
 
-    public static PromptSection RequestSection(string request)
+    static PromptSection RequestSection(string request)
     {
         PromptSection requestSection = new PromptSection();
         requestSection += "The following is a user request:\n";