Readme updates

README.md

@@ -2,14 +2,15 @@
 
 TypeChat.NET is an **experimental project** from the [Microsoft Semantic Kernel](https://github.com/microsoft/semantic-kernel) team. TypeChat.NET brings the ideas of [TypeChat](https://github.com/microsoft/TypeChat) to .NET. 
 
-TypeChat.NET helps you build natural language interfaces with language models using strong types, type validation and type safe programs (plans). Strong typing may help make software that uses language models more deterministic and reliable.    
+TypeChat.NET provides **cross platform** libraries that help you build natural language interfaces with language models using strong types, type validation and simple type safe programs (plans). Strong typing may help make software that uses language models more deterministic and reliable.    
+```
+// Translates user intent into strongly typed Calendar Actions
+var translator = new JsonTranslator<CalendarActions>(
+    new LanguageModel(Config.LoadOpenAI())
+);
+```
 
-        // Translates user intent into strongly typed Calendar Actions
-        var translator = new JsonTranslator<CalendarActions>(
-            new LanguageModel(Config.LoadOpenAI())
-        );
-
-TypeChat.NET is in **active development** with frequent updates. The framework and programming model will evolve as the team explores the space and incorporates feedback. Supported scenarios are shown in the examples. Documentation will also continue to improve. When in doubt, please look at the code.  
+TypeChat.NET is in **active development** with frequent updates. The framework and programming model will evolve as the team explores the space and incorporates feedback. Supported scenarios are shown in the included [Examples](./examples). Documentation will also continue to improve. When in doubt, please look at the code.  
 
 # Assemblies
 TypeChat.NET consists of the following assemblies:
@@ -24,20 +25,17 @@ TypeChat.NET consists of the following assemblies:
 
 * **TypeChat.App**: Support classes and extensions used by Typechat examples. These classes may be useful for other apps built using Typechat.
 
-
 ## TypeChat ##
-TypeChat uses language models to translate user intent into JSON that adheres to a schema. This JSON is then validated and deserialized into a typed object, with additional constraint checking applied as needed.
-
-TypeChat includes:
-* Json Translators (JsonTranslator<T>)
-* Json Validators
-* Schema Exporters. Generate schema for .NET Types using the concise syntax of Typescript. Includes support for:
-  * Dynamic export at runtime. This is especially needed for scenarios where the schema must include dynamic lists and vocabularies: e.g. available product names, lists of players in a team.
-  * Vocabularies: easy unions of string tables, like in Typescript, along with support for dynamic loading. 
-  * Auomated schema export supports common scenarios, as shown in the examples. Additional scenarios may be supported in the future. 
-* Extensibility interfaces let you use custom hand (such as hand-authored written) schemas, validators and even prompts.
-* Classifiers used to route requests to child or hierarchical schemas and handlers
+TypeChat uses language models to translate user intent into JSON that conforms to a schema. This JSON is then validated and deserialized into a typed object. Additional constraint checking is applied as needed.
 
+TypeChat provides:
+* Json Translation and validation.
+* Schema export: generate schema for .NET Types using **Typescript**, a language designed to express the schema of JSON objects concisely. Schema export supports common scenarios (as shown in the examples) and provides:
+  * Runtime export: This is needed for scenarios where the schema may vary for each request, may have to be selected from sub-schemas or include dynamic lists and vocabularies (such as product names, or lists of players in a team).
+  * Vocabularies: easy specification of string tables along with support for dynamic loading. 
+
+* Classification: lightweight text classifiers used to route requests to child or hierarchical schemas and handlers.
+* Extensibility: interfaces let you customize schemas (including hand-written), validators and even language model prompts.
 
 ## TypeChat.Program ##
 TypeChat.Program translates natural language requests into simple programs (***Plans***), represented as JSON. 
@@ -49,21 +47,23 @@ TypeChat.Program includes:
 * Program Interpreter: runs programs generated by ProgramTranslator using an interpreter.
 * Program Compiler: demonstrates how to use the dynamic language runtime (DLR) to compile programs/plans into verifiable typesafe code that can be checked for errors... and ***repaired***. 
 * Program C# Transpiler/Compiler (experimental): demonsrates how to transpile programs into C# and compile them with Roslyn. The compiler does type checking and compilation diagnostics can be used to repair programs.  
+```
+// Translates user intent into typed Programs that call
+// methods on a Math API
+_api = new MathAPI();
+_translator = new ProgramTranslator<IMathAPI>(
+    new LanguageModel(Config.LoadOpenAI()),
+    _api
+);
+ ```
 
-        // Translates user intent into typed Programs that call
-        // methods on a Math API
-        _api = new MathAPI();
-        _translator = new ProgramTranslator<IMathAPI>(
-            new LanguageModel(Config.LoadOpenAI()),
-            _api
-        );
-
 ## TypeChat.SemanticKernel ##
-TypeChat.SemanticKernel provides bindings for Language Models, Plugins and Embeddings for components in Typechat.NET.
+TypeChat.SemanticKernel provides out-of-the-box bindings for language models, plugins and embeddings to Typechat.NET and TypeChat.Net examples.
 
-TypeChat.SemanticKernel includes classes that demonstrate:
-* **Json Programs for Plugins**: turns registered plugins into a Plugin **API** and then generate Json programs that call these APIs. [Plugins Example](examples/Plugins/Program.cs)
-* Language model and embeddings access. All TypeChat examples use the Semantic Kernel to call models and generate embeddings. 
+TypeChat.SemanticKernel include classes for:
+* **Json Programs for Plugins**: turn registered plugins into **APIs** that Json programs can target See the [Plugins Example](examples/Plugins/Program.cs).
+* Language model and embeddings access: all TypeChat examples use the Semantic Kernel to call models and generate embeddings. 
+* Embeddings classes: Easy to use in-memory tables with nearest neighbor matching support. These make it easy to build lightweight classifiers and routers. See the [SchemaHierarchy example](examples/SchemaHierarchy/Program.cs) for details.
 
 ## TypeChat.Dialog
 (Early)
@@ -72,61 +72,85 @@ TypeChat.Dialog demonstrates how TypeChat.NET may be used for strongly typed int
 TypeChat.Dialog includes support for:
 * Agents, Agents with History
 * Messages, Message Streams
-
-      // Create an agent with history
-      _agent = new AgentWithHistory<HealthDataResponse>(new LanguageModel(Config.LoadOpenAI()));
+```
+// Create an agent with history
+_agent = new AgentWithHistory<HealthDataResponse>(new LanguageModel(Config.LoadOpenAI()));
+```
 
 ## TypeChat.App
-A utility library with classes used by Typechat examples. These classes may be generally useful for apps built on top of Typechat. Helper classes include:
+A utility library with classes used by TypeChat examples. These classes may be generally useful for apps built on top of TypeChat. Helper classes include:
 * Program synthesis of programs that call Plugins
 * Console Apps
 
 # Getting Started 
+
+## Prequisite: Open AI
+* **Open AI Language Models**: TypeChat.NET and its examples currently require familiarity with and access to language models from Open AI. 
+* TypeChat.NET has been tested with and supports the following models: 
+    * gpt-35-turbo
+    * gpt-4
+    * ada-002
+* Some examples and scenarios will work best with gpt-4
+* Since TypeChat.NET uses the Semantic Kernel, models from other providers ***may*** be used for experimentation.
+
 ## Building
 
 * Visual Studio 2022. 
   * Load **typechat.sln** from the root directory. 
   * Restore packages
   * Build
 
-* Command Line
-  * Launch a command prompt
+* dotnet build
+  * Launch a command prompt / terminal
   * Go to the root directory of the project
   * dotnet build Typechat.sln
 
 ## Nuget Packages
 
+(Coming)
+
 ## Examples
 
-To see TypeChat in action, explore the [TypeChat example projects](./examples). The list below describes which examples will best introduc which concept
+To see TypeChat in action, explore the [TypeChat example projects](./examples). The list below describes which examples will best introduc which concept. Some examples or scenarios may work best with gpt-4.
 
-* Typechat, JsonTranslator and Schemas: 
+* JsonTranslator and Schemas: 
   * Sentiment: the simplest example that demonstrates JsonTranslator and other core features 
-  * CoffeeShop: Natural language ordering at a coffee shop
+  * CoffeeShop1: Natural language ordering at a coffee shop
   * Calendar: Transform language into calendar actions
   * Restaurant: Order at a pizza restaurant
 
 * Hierarchical schemas and routing:
   * MultiSchema: dynamically route user intent to other 'sub-apps'
   * SchemaHierarchy: A Json Translator than uses multiple child JsonTranslators
 
-* TypeChat.Program and program synthesis from these examples:
+* TypeChat.Program:
   * Math: Turn user requests into calculator programs
   * Plugins (program synthesis that target Semantic Kernel Plugins)
 
-* Typed conversations with Agents:
+* TypeChat.Dialog:
   * Healthdata
 
 ### Api Key
-To run the examples, you will need an **API key** for an Open AI service. Both Azure Open AI and the Open AI service are supported. 
-- Go to the ***examples*** folder in the solution
-- Make a copy of the appSettings.json file. Name it **appSettings.Development.json**. This file contains a local override of the settings in appSettings.json
-- Add your Api Key to **appSettings.Development.json**. 
-
+To run the examples, you will need an **API key** for an Open AI service. Both Azure Open AI and the Open AI service are supported.
+
+* Go to the ***examples*** folder in the solution
+* Make a copy of the appSettings.json file. Name it **appSettings.Development.json**. Ensure it is in the same folder as the appSettings.json
+* appSettings.Development.json is a local override of the settings in appSettings.json
+* Add your Api Key to **appSettings.Development.json**. 
+
+A typical appSettings.Development.json will look like this:
+```
+{
+  "OpenAI": {
+    "ApiKey": "YOUR API KEY",
+    "Endpoint": "API ENDPOINT - Open AI or Azure",
+    "Model": "gpt-35-turbo"
+  }
+}
+```
 ### Inputs
 - Each example includes an **input.txt** with sample input. 
 - Pass the input file as an argument to run the example in **batch mode**. 
-
 # License
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).

examples/Calendar/ReadMe.md

@@ -2,6 +2,9 @@
 
 The Calendar example shows how you can capture user intent as a sequence of actions, such as adding event to a calendar or searching for an event as defined by the [`CalendarActions`](CalendarActionsSchema.cs) type.
 
+## Target models
+Works with gpt-35-turbo and gpt-4.
+
 # Usage
 
 Example prompts can be found in [`input.txt`](input.txt).

examples/CoffeeShop/ReadMe.md

@@ -1,7 +1,7 @@
 # CoffeeShop
 Demonstrates **JsonTranslator** with a [complex schema](CoffeeShopSchema.cs) for a coffee shop. It shows how GPT 3.5 and 4.0 can effectively be used to translate a broad range of user intent into strongly typed objects that can then be processed with conventional software.
 
-CoffeeShop Emulates natural language ordering at a Coffee Shop that serves:
+CoffeeShop emulates natural language ordering at a Coffee Shop serving:
 - Coffee
 - Espresso
 - Lattes
@@ -14,6 +14,9 @@ Also demonstrates how to use the ***[JsonVocab]*** attribute to:
   ```[JsonVocab(whole milk | two percent milk | nonfat milk | soy milk | almond milk | oat milk)]```
 * Automatic validation and repair of strings using these vocabularies
 
+## Target models
+Works with gpt-35-turbo and gpt-4.
+
 # Usage
 
 Example prompts can be found in [`input.txt`](input.txt).

examples/CoffeeShop2/Readme.md

@@ -6,6 +6,9 @@ CoffeeShop2 implements the same features as [CoffeeShop](../CoffeeShop/Readme.md
 - Each request could use a different translator and associated vocabulary (with associated schema generated on the fly). 
 -- e.g. Premium Coffee Shop users could be offered more complex Syrups or Toppings. Vegan users would only see non-dairy milks. Etc.
 
+## Target models
+Works with gpt-35-turbo and gpt-4.
+
 # Usage
 
 Example prompts can be found in [`input.txt`](input.txt).

examples/HealthData/Readme.md

@@ -5,6 +5,9 @@ Demonstrates a ***strongly typed*** Chat. Here, you work with an Agent to intera
 
 Shows how to use **Agents (Chat) with history** to ***interactively*** acquire information needed for one or more Types from the user: **form filling**. 
 
+## Target models
+For best and consistent results, use **gpt-4**. 
+
 # Usage
 
 Example prompts can be found in [`input.txt`](input.txt).

examples/Math/Readme.md

@@ -2,6 +2,9 @@
 
 The Math example shows how to use **TypeChat.Program** for program generation based on an API schema. This example translates calculations into simple programs given an [`API`](MathAPI.cs) type that can perform the four basic mathematical operations.
 
+## Target models
+Works with gpt-35-turbo and gpt-4.
+
 # Usage
 
 Example prompts can be found in [`input.txt`](input.txt).

examples/MultiSchema/Readme.md

@@ -9,6 +9,12 @@ In this example, the child apps are existng Typechat chat examples:
 * Sentiment
 * Math
 * Plugins
+* HealthData
+* 
+## Target models
+Works with gpt-35-turbo and gpt-4.
+
+Sub-apps like HealthData and Plugins work best with gpt-4
 
 # Usage
 Example prompts can be found in [`input.txt`](input.txt).

examples/Plugins/Readme.md

@@ -6,9 +6,12 @@ For best and consistent results, use **GPT-4**.
 
 Sample plugins:
 * ShellPlugin (file system operations)
-* StringPlugin (Simple string manipulation)
+* StringPlugin (String manipulation)
 * TimePlugin (Time operations)
 
+## Target models
+For best and consistent results, use **gpt-4**. 
+
 # Usage
 
 Example prompts can be found in [`input.txt`](input.txt).

examples/Restaurant/ReadMe.md

@@ -5,6 +5,9 @@ This example can act as a "stress test" for language models, illustrating the li
 This example also shows how we can create a "user intent summary" to display to a user.
 It uses a natural language experience for placing an order with the [`Order`](RestaurantSchema.cs) type.
 
+## Target models
+Works with gpt-35-turbo and gpt-4.
+
 # Usage
 
 Example prompts can be found in [`input.txt`](input.txt).

examples/SchemaHierarchy/Readme.md

@@ -9,5 +9,8 @@ The HierarchicalJsonTranslator automatically picks the best child schema for a r
 * Sentiment
 * HealthDataResponse
 
+## Target models
+Works with gpt-35-turbo and gpt-4.
+
 # Usage
 Example prompts can be found in [`input.txt`](input.txt).

examples/Sentiment/Readme.md

@@ -2,6 +2,9 @@
 
 The Sentiment example shows how to match user intent to a set of nouns, in this case categorizing user sentiment of the input as negative, neutral, or positive with the [`SentimentResponse`](SentimentSchema.cs) type.
 
+## Target models
+Works with gpt-35-turbo and gpt-4.
+
 # Usage
 Example prompts can be found in [`input.txt`](input.txt).
 

examples/appSettings.json

@@ -4,7 +4,13 @@
     "Azure": true,
     "Endpoint": "?",
     "ApiKey": "?",
-    "Model": "gpt-35-turbo"
+    "Model": "gpt-35-turbo",
+    //
+    // Http Retry and timeout settings
+    //
+    "MaxRetries": 2,
+    // 30 seconds
+    "TimeoutMs": "30000"
   },
   // Custom. Load Open AI Config using this name
   "OpenAI_GPT4": {