move methods onto ChatClient

Add Generate methods

Author: tomlm

README.md

@@ -129,11 +129,35 @@ This operator let's you ask a question for each item in a collection.
 var answers = items.Answer<float>(model, "What is the cost?");
 ```
 
-# Defining new operators
-All of these operators are built up of 2 core operators
-* ***TransformItem()/TransformItemAsync()*** - which allows you to give a transformation goal and instructions for a single item.
-* ***TransformItems()*** - Which allows you a transformation goal and instructions for each element in a enumerable collection.
+# Model Extensions
+All of these extensions are built up using 3 ChatClient extensions as primitives.
+
+| Extension | Description | 
+| ----------| ------------|
+| ***.Generate()/.GenerateAsync()*** | use a model and a goal to return a shaped result. |
+| ***.TransformItem()/.TransformItemAsync()*** | use a model, object and goal to transform object into shaped result. |
+| ***.TransformItems()/.TransformItemsAsync()*** | use a model, collection and goal to transform each object in the collection into a collection of shaped results. |
+
+## model.Generate()/model.GenerateAsync()
+Given a model and a goal return a shaped result.
+```csharp
+var names = model.Generate<string[]>("funny names for people named bob");
+var cities = model.Generate<City>("return the top 5 largest cities in the world.");
+```
 
+## model.TransformItem()/model.TransformItemAsync()
+Given a model and item, transform it into the shaped result using goal to guide the transformation.
+```csharp
+var piglatin = model.TransformItem<string>("cow", "transform to pig latin"); // outputs "owcay"
+```
+
+## model.TransformItem()/model.TransformItemAsync()
+Given a model and item, transform it into the shaped result using goal to guide the transformation.
+```csharp
+var piglatin = model.TransformItems<string>(["cow", "dog", "pig"], "transform to pig latin"); // outputs ["owcay", "ogday", "igpay"]
+```
+
+# Defining new operators
 To create a custom operator you create an static class and define static methods for transforming an object or collection of objects.
 
 For example, here is the implementation of Summarize():
@@ -144,16 +168,16 @@ For example, here is the implementation of Summarize():
 ```csharp
     public static class SummarizeExtension
     {
-        // Object operator
+        // operator to summarize object
         public static string Summarize(this object source, ChatClient model, string? goal, string? instructions = null, CancellationToken cancellationToken = default)
             => source.TransformItem<string>(model, goal ?? "create a summarization", instructions, cancellationToken);
 
-        // Object operator
+        // operator to summarize object
         public static Task<string> SummarizeAsync(this object source, ChatClient model, string? goal, string? instructions = null, CancellationToken cancellationToken = default)
             => source.TransformItemAsync<string>(model, goal ?? "create a summarization", instructions, cancellationToken);
 
-        // collection operator
+        // operator to summarize collection of objects
         public static IList<string> Summarize(this IEnumerable<object> source, ChatClient model, string? goal = null, string? instructions = null, int? maxParallel = null, CancellationToken cancellationToken = default)
-            => source.TransformItem<string>(model, goal ?? "create a summarization", instructions, maxParallel, cancellationToken);
+            => source.TransformItems<string>(model, goal ?? "create a summarization", instructions, maxParallel, cancellationToken);
     }
 ```

source/Linq.AI.OpenAI.Tests/MiscTests.cs

@@ -0,0 +1,62 @@
+using System.ComponentModel;
+
+namespace Linq.AI.OpenAI.Tests
+{
+
+
+    [TestClass]
+    public class MiscTests : UnitTestBase
+    {
+
+        [TestMethod]
+        public async Task Generate_Text()
+        {
+            var results = await Model.GenerateAsync<string>("a haiku about camping");
+            Assert.IsTrue(results.ToLower().Contains("camp"));
+        }
+
+        [TestMethod]
+        public void Generate_Object()
+        {
+            var result = Model.Generate<CityObject>("a city object for Ames, Iowa");
+            Assert.AreEqual("Ames", result.Name);
+        }
+
+        [TestMethod]
+        public async Task Generate_Collection_Text()
+        {
+            var results = await Model.GenerateAsync<string[]>("return the top 5 largest cities in the world");
+            Assert.IsTrue(results.Any(item => item.Contains("Mexico City")));
+            Assert.AreEqual(5, results.Count());
+        }
+
+        [TestMethod]
+        public async Task Generate_Collection_Text2()
+        {
+            var results = await Model.GenerateAsync<string[]>("a list of funny names for people named bob");
+            foreach(var result in results)
+            {
+                Assert.IsTrue(result.ToLower().Contains("bob"));
+            }
+        }
+
+
+
+        [TestMethod]
+        public void Generate_Collections_Object()
+        {
+            var generated = Model.Generate<CityObject[]>("return the top 5 largest cities in the world.");
+            Assert.IsTrue(generated.Any(item => item.Name == "Mexico City" && item.Country == "Mexico" ));
+            Assert.AreEqual(5, generated.Count());
+        }
+    }
+
+    internal class CityObject
+    {
+        [System.ComponentModel.Description("Name of the city")]
+        public string Name { get; set; }
+
+        [System.ComponentModel.Description("Name of the Country")]
+        public string Country { get; set; }
+    }
+}

source/Linq.AI.OpenAI.Tests/TransformTests.cs

@@ -13,22 +13,22 @@ public class TransformationTests : UnitTestBase
         public async Task Transform_String2String()
         {
             var source = "My name is Tom.";
-            var transformation = source.TransformItem<string>(Model, "into spanish");
+            var transformation = Model.TransformItem<string>(source, "into spanish");
             Assert.AreEqual("Me llamo Tom.", transformation!);
 
-            transformation = await source.TransformItemAsync<string>(Model, "into spanish");
+            transformation = await Model.TransformItemAsync<string>(source, "into spanish");
             Assert.AreEqual("Me llamo Tom.", transformation!);
         }
 
         [TestMethod]
         public async Task Transform_String2Object()
         {
             var source = "I have 4 children and my name is Inigo Montoya.";
-            var obj = source.TransformItem<TestObject>(Model);
+            var obj = Model.TransformItem<TestObject>(source);
             Assert.AreEqual("Inigo Montoya", obj.Name);
             Assert.AreEqual(4, obj.Count);
 
-            obj = await source.TransformItemAsync<TestObject>(Model);
+            obj = await Model.TransformItemAsync<TestObject>(source);
             Assert.AreEqual("Inigo Montoya", obj.Name);
             Assert.AreEqual(4, obj.Count);
         }
@@ -37,7 +37,7 @@ public async Task Transform_String2Object()
         public async Task Transform_Object2Object()
         {
             var source = new TestObject2() { FirstName = "Inigo", LastName = "Montoya" };
-            var obj = await source.TransformItemAsync<TestObject>(Model, instructions: "Do not fill in properties that you don't have data for.");
+            var obj = await Model.TransformItemAsync<TestObject>(source, instructions: "Do not fill in properties that you don't have data for.");
             Assert.AreEqual("Inigo Montoya", obj.Name);
             Assert.AreEqual(0, obj.Count);
         }
@@ -46,36 +46,36 @@ public async Task Transform_Object2Object()
         public async Task Transform_Bool()
         {
             var source = new TestObject2() { FirstName = "Inigo", LastName = "Montoya" };
-            Assert.IsTrue(await source.TransformItemAsync<bool>(Model, "return true if the <ITEM> has a character in princess bride"));
-            Assert.IsFalse(await source.TransformItemAsync<bool>(Model, "return true if if the <ITEM> has a character in star wars"));
+            Assert.IsTrue(await Model.TransformItemAsync<bool>(source, "return true if the <ITEM> has a character in princess bride"));
+            Assert.IsFalse(await Model.TransformItemAsync<bool>(source, "return true if if the <ITEM> has a character in star wars"));
         }
 
         [TestMethod]
         public async Task Transform_Classify()
         {
-            Assert.AreEqual(TestCategories.Car, await "Ford".TransformItemAsync<TestCategories>(Model, "classify"));
-            Assert.AreEqual(TestCategories.Plane, await "Cessna".TransformItemAsync<TestCategories>(Model, "classify"));
+            Assert.AreEqual(TestCategories.Car, await Model.TransformItemAsync<TestCategories>("Ford", "classify"));
+            Assert.AreEqual(TestCategories.Plane, await Model.TransformItemAsync<TestCategories>("Cessna", "classify"));
         }
 
         [TestMethod]
         public async Task Transform_Classify_text()
         {
 
             var categories = String.Join(",", Enum.GetNames<TestCategories>());
-            Assert.AreEqual("Car", await "Ford".TransformItemAsync<string>(Model, $"Pick the category from this list: {categories}"));
-            Assert.AreEqual("Plane", await "Cessna".TransformItemAsync<string>(Model, $"Pick the category from this list: {categories}"));
+            Assert.AreEqual("Car", await Model.TransformItemAsync<string>("Ford", $"Pick the category from this list: {categories}"));
+            Assert.AreEqual("Plane", await Model.TransformItemAsync<string>("Cessna", $"Pick the category from this list: {categories}"));
         }
 
         [TestMethod]
         public async Task Transform_Answer()
         {
-            Assert.AreEqual("Honolulu", await Text.TransformItemAsync<string>(Model, "What town was he born in?"));
+            Assert.AreEqual("Honolulu", await Model.TransformItemAsync<string>(Text, "What town was he born in?"));
         }
 
         [TestMethod]
         public async Task Transform_Text2Strings()
         {
-            var results = await Text.TransformItemAsync<string[]>(Model, "return titles that are bolded");
+            var results = await Model.TransformItemAsync<string[]>(Text, "return titles that are bolded");
 
             string[] titles =
             [
@@ -100,7 +100,7 @@ public async Task Transform_Text2Strings()
         [TestMethod]
         public async Task Transform_Text2Objects()
         {
-            var results = await Text.TransformItemAsync<Article[]>(Model);
+            var results = await Model.TransformItemAsync<Article[]>(Text);
 
             Assert.IsTrue(results.Count() > 0);
             foreach(var result in results)
@@ -120,7 +120,7 @@ public void Transform_Collection_String2String()
                 "Which is better? Flossing or brushing or doing nothing? Gert Gooble discusses this important subject." ,
             };
 
-            var results = sources.TransformItems<string>(Model, "Transform to text like this:\n# {{title}}\nBy {{Author}}\n{{Summary}}").ToList();
+            var results = Model.TransformItems<string>(sources, "Transform to text like this:\n# {{title}}\nBy {{Author}}\n{{Summary}}").ToList();
             var result = results[0];
             Assert.IsTrue(result.StartsWith("#"));
             Assert.IsTrue(result.Split('\n').First().Contains("Title 1"));
@@ -138,7 +138,7 @@ public void Transform_Collection_String2Object()
                 "Which is better? Flossing or brushing or doing nothing? Gert Gooble discusses this important subject." ,
             };
 
-            var results = sources.TransformItems<TargetObject>(Model).ToList();
+            var results = Model.TransformItems<TargetObject>(sources).ToList();
             var result = results[0];
             Assert.AreEqual("Joe Blow", result.AuthorFullName);
             Assert.AreEqual("Joe", result.Author!.FirstName);
@@ -166,7 +166,7 @@ public void Transform_Collection_Object2Object()
                 new SourceObject() { Title="Title 3", Description="Which is better? Flossing or brushing or doing nothing?", Writer="Gert Gooble", PubliicationDate = new DateTime(2020, 10, 1) },
             };
 
-            foreach (var result in sources.TransformItems<TargetObject>(Model))
+            foreach (var result in Model.TransformItems<TargetObject>(sources))
             {
                 switch (result.Summary)
                 {

source/Linq.AI.OpenAI/MiscExtensions.cs

@@ -0,0 +1,37 @@
+using Iciclecreek.Async;
+using Newtonsoft.Json;
+using OpenAI.Chat;
+
+namespace Linq.AI.OpenAI
+{
+
+    public static class MiscExtensions
+    {
+        /// <summary>
+        /// Generate an item of shape T based on "goal"
+        /// </summary>
+        /// <typeparam name="ResultT">type of items</typeparam>
+        /// <param name="source">collection of items</param>
+        /// <param name="constraint">The constraint to match to remove an item</param>
+        /// <param name="instructions">(OPTIONAL) additional instructions</param>
+        /// <param name="maxParallel">(OPTIONAL) max parallel operations</param>
+        /// <param name="cancellationToken">(OPTIONAL) cancellation token</param>
+        /// <returns>collection of items which didn't match the goal</returns>
+        public static ResultT Generate<ResultT>(this ChatClient model, string goal, string? instructions = null, int? maxParallel = null, CancellationToken cancellationToken = default)
+            => model.TransformItem<ResultT>(String.Empty, goal, instructions, cancellationToken);
+
+        /// <summary>
+        /// Generate an item of shape T based on "goal"
+        /// </summary>
+        /// <typeparam name="T">type of items</typeparam>
+        /// <param name="source">collection of items</param>
+        /// <param name="constraint">The constraint to match to remove an item</param>
+        /// <param name="instructions">(OPTIONAL) additional instructions</param>
+        /// <param name="maxParallel">(OPTIONAL) max parallel operations</param>
+        /// <param name="cancellationToken">(OPTIONAL) cancellation token</param>
+        /// <returns>collection of items which didn't match the goal</returns>
+        public static Task<ResultT> GenerateAsync<ResultT>(this ChatClient model, string goal, string? instructions = null, int? maxParallel = null, CancellationToken cancellationToken = default)
+            => model.TransformItemAsync<ResultT>(String.Empty, goal, instructions, cancellationToken);
+    }
+}
+