Chat endpoint improvements, tests, readme updates, and an alternate C…

…onversation class

OpenAI_API/Chat/ChatEndpoint.cs

@@ -1,6 +1,7 @@
 using OpenAI_API.Models;
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Net.Http;
 using System.Text;
 using System.Threading.Tasks;
@@ -10,8 +11,8 @@ namespace OpenAI_API.Chat
  /// <summary>
  /// ChatGPT API endpoint. Use this endpoint to send multiple messages and carry on a conversation.
  /// </summary>
- public class ChatEndpoint : EndpointBase
- {
+ public class ChatEndpoint : EndpointBase
+ {
  /// <summary>
  /// This allows you to set default parameters for every request, for example to set a default temperature or max tokens. For every request, if you do not have a parameter set on the request but do have it set here as a default, the request will automatically pick up the default value.
  /// </summary>
@@ -28,14 +29,23 @@ public class ChatEndpoint : EndpointBase
  /// <param name="api"></param>
  internal ChatEndpoint(OpenAIAPI api) : base(api) { }
 
+ /// <summary>
+ /// Creates an ongoing chat which can easily encapsulate the conversation. This is the simplest way to use the Chat endpoint.
+ /// </summary>
+ /// <returns></returns>
+ public Conversation CreateConversation()
+ {
+ return new Conversation(this, defaultChatRequestArgs: DefaultChatRequestArgs);
+ }
+
  #region Non-streaming
 
  /// <summary>
  /// Ask the API to complete the request using the specified parameters. This is non-streaming, so it will wait until the API returns the full result. Any non-specified parameters will fall back to default values specified in <see cref="DefaultChatRequestArgs"/> if present.
  /// </summary>
  /// <param name="request">The request to send to the API.</param>
  /// <returns>Asynchronously returns the completion result. Look in its <see cref="ChatResult.Choices"/> property for the results.</returns>
- public async Task<ChatResult> CreateChatAsync(ChatRequest request)
+ public async Task<ChatResult> CreateChatCompletionAsync(ChatRequest request)
  {
  return await HttpPost<ChatResult>(postData: request);
  }
@@ -46,10 +56,10 @@ public async Task<ChatResult> CreateChatAsync(ChatRequest request)
  /// <param name="request">The request to send to the API.</param>
  /// <param name="numOutputs">Overrides <see cref="ChatRequest.NumChoicesPerMessage"/> as a convenience.</param>
  /// <returns>Asynchronously returns the completion result. Look in its <see cref="ChatResult.Choices"/> property for the results.</returns>
- public Task<ChatResult> CreateChatAsync(ChatRequest request, int numOutputs = 5)
+ public Task<ChatResult> CreateChatCompletionAsync(ChatRequest request, int numOutputs = 5)
  {
  request.NumChoicesPerMessage = numOutputs;
- return CreateChatAsync(request);
+ return CreateChatCompletionAsync(request);
  }
 
  /// <summary>
@@ -66,15 +76,15 @@ public Task<ChatResult> CreateChatAsync(ChatRequest request, int numOutputs = 5)
  /// <param name="logitBias">Maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.</param>
  /// <param name="stopSequences">One or more sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.</param>
  /// <returns>Asynchronously returns the completion result. Look in its <see cref="ChatResult.Choices"/> property for the results.</returns>
- public Task<ChatResult> CreateChatAsync(IEnumerable<ChatMessage> messages,
+ public Task<ChatResult> CreateChatCompletionAsync(IList<ChatMessage> messages,
  Model model = null,
  double? temperature = null,
  double? top_p = null,
  int? numOutputs = null,
  int? max_tokens = null,
  double? frequencyPenalty = null,
  double? presencePenalty = null,
- IReadOnlyDictionary<string, float> logitBias = null,
+ IReadOnlyDictionary<string, float> logitBias = null,
  params string[] stopSequences)
  {
  ChatRequest request = new ChatRequest(DefaultChatRequestArgs)
@@ -90,23 +100,30 @@ public Task<ChatResult> CreateChatAsync(ChatRequest request, int numOutputs = 5)
  PresencePenalty = presencePenalty ?? DefaultChatRequestArgs.PresencePenalty,
  LogitBias = logitBias ?? DefaultChatRequestArgs.LogitBias
  };
- return CreateChatAsync(request);
+ return CreateChatCompletionAsync(request);
  }
 
  /// <summary>
- /// Ask the API to complete the request using the specified parameters. This is non-streaming, so it will wait until the API returns the full result. Any non-specified parameters will fall back to default values specified in <see cref="DefaultChatRequestArgs"/> if present.
+ /// Ask the API to complete the request using the specified message(s). Any parameters will fall back to default values specified in <see cref="DefaultChatRequestArgs"/> if present.
  /// </summary>
  /// <param name="messages">The messages to use in the generation.</param>
- /// <returns></returns>
- public Task<ChatResult> CreateChatAsync(IEnumerable<ChatMessage> messages)
+ /// <returns>The <see cref="ChatResult"/> with the API response.</returns>
+ public Task<ChatResult> CreateChatCompletionAsync(params ChatMessage[] messages)
  {
  ChatRequest request = new ChatRequest(DefaultChatRequestArgs)
  {
  Messages = messages
  };
- return CreateChatAsync(request);
+ return CreateChatCompletionAsync(request);
  }
 
+ /// <summary>
+ /// Ask the API to complete the request using the specified message(s). Any parameters will fall back to default values specified in <see cref="DefaultChatRequestArgs"/> if present.
+ /// </summary>
+ /// <param name="userMessages">The user message or messages to use in the generation. All strings are assumed to be of Role <see cref="ChatMessageRole.User"/></param>
+ /// <returns>The <see cref="ChatResult"/> with the API response.</returns>
+ public Task<ChatResult> CreateChatCompletionAsync(params string[] userMessages) => CreateChatCompletionAsync(userMessages.Select(m => new ChatMessage(ChatMessageRole.User, m)).ToArray());
+
  #endregion
 
  #region Streaming
@@ -168,15 +185,15 @@ public IAsyncEnumerable<ChatResult> StreamChatEnumerableAsync(ChatRequest reques
  /// <param name="logitBias">Maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.</param>
  /// <param name="stopSequences">One or more sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.</param>
  /// <returns>An async enumerable with each of the results as they come in. See <see href="https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-8#asynchronous-streams">the C# docs</see> for more details on how to consume an async enumerable.</returns>
- public IAsyncEnumerable<ChatResult> StreamChatEnumerableAsync(IEnumerable<ChatMessage> messages,
+ public IAsyncEnumerable<ChatResult> StreamChatEnumerableAsync(IList<ChatMessage> messages,
  Model model = null,
  double? temperature = null,
  double? top_p = null,
  int? numOutputs = null,
  int? max_tokens = null,
  double? frequencyPenalty = null,
  double? presencePenalty = null,
- IReadOnlyDictionary<string, float> logitBias = null,
+ IReadOnlyDictionary<string, float> logitBias = null,
  params string[] stopSequences)
  {
  ChatRequest request = new ChatRequest(DefaultChatRequestArgs)

OpenAI_API/Chat/ChatMessageRole.cs

@@ -0,0 +1,119 @@
+using Newtonsoft.Json;
+using System;
+using System.Collections.Generic;
+using System.ComponentModel.Design;
+using System.Text;
+
+namespace OpenAI_API.Chat
+{
+ /// <summary>
+ /// Represents the Role of a <see cref="ChatMessage"/>. Typically, a conversation is formatted with a system message first, followed by alternating user and assistant messages. See <see href="https://platform.openai.com/docs/guides/chat/introduction">the OpenAI docs</see> for more details about usage.
+ /// </summary>
+ public class ChatMessageRole : IEquatable<ChatMessageRole>
+ {
+ /// <summary>
+ /// Contructor is prvate to force usage of strongly typed values
+ /// </summary>
+ /// <param name="value"></param>
+ private ChatMessageRole(string value) { Value = value; }
+
+ /// <summary>
+ /// Gets the singleton instance of <see cref="ChatMessageRole"/> based on the string value.
+ /// </summary>
+ /// <param name="roleName">Muse be one of "system", "user", or "assistant"</param>
+ /// <returns></returns>
+ public static ChatMessageRole FromString(string roleName)
+ {
+ switch (roleName)
+ {
+ case "system":
+ return ChatMessageRole.System;
+ case "user":
+ return ChatMessageRole.User;
+ case "assistant":
+ return ChatMessageRole.Assistant;
+ default:
+ return null;
+ }
+ }
+
+ private string Value { get; set; }
+
+ /// <summary>
+ /// The system message helps set the behavior of the assistant. 
+ /// </summary>
+ public static ChatMessageRole System { get { return new ChatMessageRole("system"); } }
+ /// <summary>
+ /// The user messages help instruct the assistant. They can be generated by the end users of an application, or set by a developer as an instruction.
+ /// </summary>
+ public static ChatMessageRole User { get { return new ChatMessageRole("user"); } }
+ /// <summary>
+ /// The assistant messages help store prior responses. They can also be written by a developer to help give examples of desired behavior.
+ /// </summary>
+ public static ChatMessageRole Assistant { get { return new ChatMessageRole("assistant"); } }
+
+ /// <summary>
+ /// Gets the string value for this role to pass to the API
+ /// </summary>
+ /// <returns>The size as a string</returns>
+ public override string ToString()
+ {
+ return Value;
+ }
+
+ /// <summary>
+ /// Determines whether this instance and a specified object have the same value.
+ /// </summary>
+ /// <param name="obj">The ChatMessageRole to compare to this instance</param>
+ /// <returns>true if obj is a ChatMessageRole and its value is the same as this instance; otherwise, false. If obj is null, the method returns false</returns>
+ public override bool Equals(object obj)
+ {
+ return Value.Equals((obj as ChatMessageRole).Value);
+ }
+
+ /// <summary>
+ /// Returns the hash code for this object
+ /// </summary>
+ /// <returns>A 32-bit signed integer hash code</returns>
+ public override int GetHashCode()
+ {
+ return Value.GetHashCode(); 
+ }
+
+ /// <summary>
+ /// Determines whether this instance and a specified object have the same value.
+ /// </summary>
+ /// <param name="other">The ChatMessageRole to compare to this instance</param>
+ /// <returns>true if other's value is the same as this instance; otherwise, false. If other is null, the method returns false</returns>
+ public bool Equals(ChatMessageRole other)
+ {
+ return Value.Equals(other.Value);
+ }
+
+ /// <summary>
+ /// Gets the string value for this role to pass to the API
+ /// </summary>
+ /// <param name="value">The ChatMessageRole to convert</param>
+ public static implicit operator String(ChatMessageRole value) { return value; }
+
+ ///// <summary>
+ ///// Used during the Json serialization process
+ ///// </summary>
+ //internal class ChatMessageRoleJsonConverter : JsonConverter<ChatMessageRole>
+ //{
+ // public override void WriteJson(JsonWriter writer, ChatMessageRole value, JsonSerializer serializer)
+ // {
+ // writer.WriteValue(value.ToString());
+ // }
+
+ // public override ChatMessageRole ReadJson(JsonReader reader, Type objectType, ChatMessageRole existingValue, bool hasExistingValue, JsonSerializer serializer)
+ // {
+ // if (reader.TokenType != JsonToken.String)
+ // {
+ // throw new JsonSerializationException();
+ // }
+ // return new ChatMessageRole(reader.ReadAsString());
+ // }
+ //}
+ }
+}

OpenAI_API/Chat/ChatRequest.cs

@@ -22,7 +22,7 @@ public class ChatRequest
  /// The messages to send with this Chat Request
  /// </summary>
  [JsonProperty("messages")]
- public IEnumerable<ChatMessage> Messages { get; set; }
+ public IList<ChatMessage> Messages { get; set; }
 
  /// <summary>
  /// What sampling temperature to use. Higher values means the model will take more risks. Try 0.9 for more creative applications, and 0 (argmax sampling) for ones with a well-defined answer. It is generally recommend to use this or <see cref="TopP"/> but not both.
@@ -52,7 +52,7 @@ public class ChatRequest
  /// This is only used for serializing the request into JSON, do not use it directly.
  /// </summary>
  [JsonProperty("stop")]
- public object CompiledStop
+ internal object CompiledStop
  {
  get
  {
@@ -109,9 +109,9 @@ public string StopSequence
  /// Accepts a json object that maps tokens(specified by their token ID in the tokenizer) to an associated bias value from -100 to 100.
  /// Mathematically, the bias is added to the logits generated by the model prior to sampling.
  /// The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
-  /// </summary>
+  /// </summary>
  [JsonProperty("logit_bias")]
- public IReadOnlyDictionary<string, float> LogitBias { get; set; } 
+ public IReadOnlyDictionary<string, float> LogitBias { get; set; }
 
  /// <summary>
  /// A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.
@@ -123,16 +123,17 @@ public string StopSequence
  /// Creates a new, empty <see cref="ChatRequest"/>
  /// </summary>
  public ChatRequest()
- {
- this.Model = OpenAI_API.Models.Model.ChatGPTTurbo;
- }
+ { }
 
  /// <summary>
  /// Create a new chat request using the data from the input chat request.
  /// </summary>
  /// <param name="basedOn"></param>
  public ChatRequest(ChatRequest basedOn)
- {
+ {
+ if (basedOn == null)
+ return;
+
  this.Model = basedOn.Model;
  this.Messages = basedOn.Messages;
  this.Temperature = basedOn.Temperature;