|Y||N||P1|Y|N|
+|Failure reasons when batch partially fails|Y|Y|Y|N||N|||||
+|Is Key separate from data|N|Y|Y|Y||Y||N|Y|N|
+|Can Generate Ids|N|Y|N|N||Y||Y|N|Y|
+|Can Generate Embedding|Not Available Via API yet|Y|N|Client Side Abstraction|||||N||
+
+Footnotes:
+- P = Partial Support
+- 1 Only if you have the schema, to select the appropriate fields.
+- 2 Supports broad categories of fields only.
+- 3 Id is required in request, so can be returned if needed.
+- 4 No strong typed support when specifying field list.
+
+### Vector Store Cross Store support - Fields, types and indexing
+
+|Feature|Azure AI Search|Weaviate|Redis|Chroma|FAISS|Pinecone|LLamaIndex|PostgreSql|Qdrant|Milvus|
+|-|-|-|-|-|-|-|-|-|-|-|
+|Field Differentiation|Fields|Key, Props, Vectors|Key, Fields|Key, Document, Metadata, Vector||Key, Metadata, SparseValues, Vector||Fields|Key, Props(Payload), Vectors|Fields|
+|Multiple Vector per record support|Y|Y|Y|N||[N](https://docs.pinecone.io/guides/data/upsert-data#upsert-records-with-metadata)||Y|Y|Y|
+|Index to Collection|1 to 1|1 to 1|1 to many|1 to 1|-|1 to 1|-|1 to 1|1 to 1|1 to 1|
+|Id Type|String|UUID|string with collection name prefix|string||string|UUID|64Bit Int / UUID / ULID|64Bit Unsigned Int / UUID|Int64 / varchar|
+|Supported Vector Types|[Collection(Edm.Byte) / Collection(Edm.Single) / Collection(Edm.Half) / Collection(Edm.Int16) / Collection(Edm.SByte)](https://learn.microsoft.com/en-us/rest/api/searchservice/supported-data-types)|float32|FLOAT32 and FLOAT64|||[Rust f32](https://docs.pinecone.io/troubleshooting/embedding-values-changed-when-upserted)||[single-precision (4 byte float) / half-precision (2 byte float) / binary (1bit) / sparse vectors (4 bytes)](https://github.com/pgvector/pgvector?tab=readme-ov-file#pgvector)|UInt8 / Float32|Binary / Float32 / Float16 / BFloat16 / SparseFloat|
+|Supported Distance Functions|[Cosine / dot prod / euclidean dist (l2 norm)](https://learn.microsoft.com/en-us/azure/search/vector-search-ranking#similarity-metrics-used-to-measure-nearness)|[Cosine dist / dot prod / Squared L2 dist / hamming (num of diffs) / manhattan dist](https://weaviate.io/developers/weaviate/config-refs/distances#available-distance-metrics)|[Euclidean dist (L2) / Inner prod (IP) / Cosine dist](https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/vectors/)|[Squared L2 / Inner prod / Cosine similarity](https://docs.trychroma.com/guides#changing-the-distance-function)||[cosine sim / euclidean dist / dot prod](https://docs.pinecone.io/reference/api/control-plane/create_index)||[L2 dist / inner prod / cosine dist / L1 dist / Hamming dist / Jaccard dist (NB: Specified at query time, not index creation time)](https://github.com/pgvector/pgvector?tab=readme-ov-file#pgvector)|[Dot prod / Cosine sim / Euclidean dist (L2) / Manhattan dist](https://qdrant.tech/documentation/concepts/search/)|[Cosine sim / Euclidean dist / Inner Prod](https://milvus.io/docs/index-vector-fields.md)|
+|Supported index types|[Exhaustive KNN (FLAT) / HNSW](https://learn.microsoft.com/en-us/azure/search/vector-search-ranking#algorithms-used-in-vector-search)|[HNSW / Flat / Dynamic](https://weaviate.io/developers/weaviate/config-refs/schema/vector-index)|[HNSW / FLAT](https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/vectors/#create-a-vector-field)|[HNSW not configurable](https://cookbook.chromadb.dev/core/concepts/#vector-index-hnsw-index)||[PGA](https://www.pinecone.io/blog/hnsw-not-enough/)||[HNSW / IVFFlat](https://github.com/pgvector/pgvector?tab=readme-ov-file#indexing)|[HNSW for dense](https://qdrant.tech/documentation/concepts/indexing/#vector-index)|[In Memory: FLAT / IVF_FLAT / IVF_SQ8 / IVF_PQ / HNSW / SCANN](https://milvus.io/docs/index.md)
[On Disk: DiskANN](https://milvus.io/docs/disk_index.md)
[GPU: GPU_CAGRA / GPU_IVF_FLAT / GPU_IVF_PQ / GPU_BRUTE_FORCE](https://milvus.io/docs/gpu_index.md)
|
+
+Footnotes:
+- HNSW = Hierarchical Navigable Small World (HNSW performs an [approximate nearest neighbor (ANN)](https://learn.microsoft.com/en-us/azure/search/vector-search-overview#approximate-nearest-neighbors) search)
+- KNN = k-nearest neighbors (performs a brute-force search that scans the entire vector space)
+- IVFFlat = Inverted File with Flat Compression (This index type uses approximate nearest neighbor search (ANNS) to provide fast searches)
+- Weaviate Dynamic = Starts as flat and switches to HNSW if the number of objects exceed a limit
+- PGA = [Pinecone Graph Algorithm](https://www.pinecone.io/blog/hnsw-not-enough/)
+
+### Vector Store Cross Store support - Search and filtering
+
+|Feature|Azure AI Search|Weaviate|Redis|Chroma|FAISS|Pinecone|LLamaIndex|PostgreSql|Qdrant|Milvus|
+|-|-|-|-|-|-|-|-|-|-|-|
+|Index allows text search|Y|Y|Y|Y (On Metadata by default)||[Only in combination with Vector](https://docs.pinecone.io/guides/data/understanding-hybrid-search)||Y (with TSVECTOR field)|Y|Y|
+|Text search query format|[Simple or Full Lucene](https://learn.microsoft.com/en-us/azure/search/search-query-create?tabs=portal-text-query#choose-a-query-type-simple--full)|[wildcard](https://weaviate.io/developers/weaviate/search/filters#filter-text-on-partial-matches)|wildcard & fuzzy|[contains & not contains](https://docs.trychroma.com/guides#filtering-by-document-contents)||Text only||[wildcard & binary operators](https://www.postgresql.org/docs/16/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES)|[Text only](https://qdrant.tech/documentation/concepts/filtering/#full-text-match)|[wildcard](https://milvus.io/docs/single-vector-search.md#Filtered-search)|
+|Multi Field Vector Search Support|Y|[N](https://weaviate.io/developers/weaviate/search/similarity)||N (no multi vector support)||N||[Unclear due to order by syntax](https://github.com/pgvector/pgvector?tab=readme-ov-file#querying)|[N](https://qdrant.tech/documentation/concepts/search/)|[Y](https://milvus.io/api-reference/restful/v2.4.x/v2/Vector%20(v2)/Hybrid%20Search.md)|
+|Targeted Multi Field Text Search Support|Y|[Y](https://weaviate.io/developers/weaviate/search/hybrid#set-weights-on-property-values)|[Y](https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/query_syntax/#field-modifiers)|N (only on document)||N||Y|Y|Y|
+|Vector per Vector Field for Search|Y|N/A||N/A|||N/A||N/A|N/A|[Y](https://milvus.io/docs/multi-vector-search.md#Step-1-Create-Multiple-AnnSearchRequest-Instances)|
+|Separate text search query from vectors|Y|[Y](https://weaviate.io/developers/weaviate/search/hybrid#specify-a-search-vector)|Y|Y||Y||Y|Y|[Y](https://milvus.io/api-reference/restful/v2.4.x/v2/Vector%20(v2)/Hybrid%20Search.md)|
+|Allows filtering|Y|Y|Y (on TAG)|Y (On Metadata by default)||[Y](https://docs.pinecone.io/guides/indexes/configure-pod-based-indexes#selective-metadata-indexing)||Y|Y|Y|
+|Allows filter grouping|Y (Odata)|[Y](https://weaviate.io/developers/weaviate/search/filters#nested-filters)||[Y](https://docs.trychroma.com/guides#using-logical-operators)||Y||Y|[Y](https://qdrant.tech/documentation/concepts/filtering/#clauses-combination)|[Y](https://milvus.io/docs/get-and-scalar-query.md#Use-Basic-Operators)|
+|Allows scalar index field setup|Y|Y|Y|N||Y||Y|Y|Y|
+|Requires scalar index field setup to filter|Y|Y|Y|N||N (on by default for all)||N|N|N (can filter without index)|
+
+### Support for different mappers
+
+Mapping between data models and the storage models can also require custom logic depending on the type of data model and storage model involved.
+
+I'm therefore proposing that we allow mappers to be injectable for each `VectorStoreCollection` instance. The interfaces for these would vary depending
+on the storage models used by each vector store and any unique capabilities that each vector store may have, e.g. qdrant can operate in `single` or
+`multiple named vector` modes, which means the mapper needs to know whether to set a single vector or fill a vector map.
+
+In addition to this, we should build first party mappers for each of the vector stores, which will cater for built in, generic models or use metadata to perform the mapping.
+
+### Support for different storage schemas
+
+The different stores vary in many ways around how data is organized.
+- Some just store a record with fields on it, where fields can be a key or a data field or a vector and their type is determined at collection creation time.
+- Others separate fields by type when interacting with the api, e.g. you have to specify a key explicitly, put metadata into a metadata dictionary and put vectors into a vector array.
+
+I'm proposing that we allow two ways in which to provide the information required to map data between the consumer data model and storage data model.
+First is a set of configuration objects that capture the types of each field. Second would be a set of attributes that can be used to decorate the model itself
+and can be converted to the configuration objects, allowing a single execution path.
+Additional configuration properties can easily be added for each type of field as required, e.g. IsFilterable or IsFullTextSearchable, allowing us to also create an index from the provided configuration.
+
+I'm also proposing that even though similar attributes already exist in other systems, e.g. System.ComponentModel.DataAnnotations.KeyAttribute, we create our own.
+We will likely require additional properties on all these attributes that are not currently supported on the existing attributes, e.g. whether a field is or
+should be filterable. Requiring users to switch to new attributes later will be disruptive.
+
+Here is what the attributes would look like, plus a sample use case.
+
+```cs
+sealed class VectorStoreRecordKeyAttribute : Attribute
+{
+}
+sealed class VectorStoreRecordDataAttribute : Attribute
+{
+ public bool HasEmbedding { get; set; }
+ public string EmbeddingPropertyName { get; set; }
+}
+sealed class VectorStoreRecordVectorAttribute : Attribute
+{
+}
+
+public record HotelInfo(
+ [property: VectorStoreRecordKey, JsonPropertyName("hotel-id")] string HotelId,
+ [property: VectorStoreRecordData, JsonPropertyName("hotel-name")] string HotelName,
+ [property: VectorStoreRecordData(HasEmbedding = true, EmbeddingPropertyName = "DescriptionEmbeddings"), JsonPropertyName("description")] string Description,
+ [property: VectorStoreRecordVector, JsonPropertyName("description-embeddings")] ReadOnlyMemory? DescriptionEmbeddings);
+```
+
+Here is what the configuration objects would look like.
+
+```cs
+abstract class VectorStoreRecordProperty(string propertyName);
+
+sealed class VectorStoreRecordKeyProperty(string propertyName): Field(propertyName)
+{
+}
+sealed class VectorStoreRecordDataProperty(string propertyName): Field(propertyName)
+{
+ bool HasEmbedding;
+ string EmbeddingPropertyName;
+}
+sealed class VectorStoreRecordVectorProperty(string propertyName): Field(propertyName)
+{
+}
+
+sealed class VectorStoreRecordDefinition
+{
+ IReadOnlyList Properties;
+}
+```
+
+### Notable method signature changes from existing interface
+
+All methods currently existing on IMemoryStore will be ported to new interfaces, but in places I am proposing that we make changes to improve
+consistency and scalability.
+
+1. `RemoveAsync` and `RemoveBatchAsync` renamed to `DeleteAsync` and `DeleteBatchAsync`, since record are actually deleted, and this also matches the verb used for collections.
+2. `GetCollectionsAsync` renamed to `GetCollectionNamesAsync`, since we are only retrieving names and no other information about collections.
+3. `DoesCollectionExistAsync` renamed to `CollectionExistsAsync` since this is shorter and is more commonly used in other apis.
+
+### Comparison with other AI frameworks
+
+|Criteria|Current SK Implementation|Proposed SK Implementation|Spring AI|LlamaIndex|Langchain|
+|-|-|-|-|-|-|
+|Support for Custom Schemas|N|Y|N|N|N|
+|Naming of store|MemoryStore|VectorStore, VectorStoreCollection|VectorStore|VectorStore|VectorStore|
+|MultiVector support|N|Y|N|N|N|
+|Support Multiple Collections via SDK params|Y|Y|N (via app config)|Y|Y|
+
+## Decision Drivers
+
+From GitHub Issue:
+- API surface must be easy to use and intuitive
+- Alignment with other patterns in the SK
+- - Design must allow Memory Plugins to be easily instantiated with any connector
+- Design must support all Kernel content types
+- Design must allow for database specific configuration
+- All NFR's to be production ready are implemented (see Roadmap for more detail)
+- Basic CRUD operations must be supported so that connectors can be used in a polymorphic manner
+- Official Database Clients must be used where available
+- Dynamic database schema must be supported
+- Dependency injection must be supported
+- Azure-ML YAML format must be supported
+- Breaking glass scenarios must be supported
+
+## Considered Questions
+
+1. Combined collection and record management vs separated.
+2. Collection name and key value normalization in decorator or main class.
+3. Collection name as method param or constructor param.
+4. How to normalize ids across different vector stores where different types are supported.
+5. Store Interface/Class Naming
+
+### Question 1: Combined collection and record management vs separated.
+
+#### Option 1 - Combined collection and record management
+
+```cs
+interface IVectorRecordStore
+{
+ Task CreateCollectionAsync(CollectionCreateConfig collectionConfig, CancellationToken cancellationToken = default);
+ IAsyncEnumerable ListCollectionNamesAsync(CancellationToken cancellationToken = default);
+ Task CollectionExistsAsync(string name, CancellationToken cancellationToken = default);
+ Task DeleteCollectionAsync(string name, CancellationToken cancellationToken = default);
+
+ Task UpsertAsync(TRecord data, CancellationToken cancellationToken = default);
+ IAsyncEnumerable UpsertBatchAsync(IEnumerable dataSet, CancellationToken cancellationToken = default);
+ Task GetAsync(string key, bool withEmbedding = false, CancellationToken cancellationToken = default);
+ IAsyncEnumerable GetBatchAsync(IEnumerable keys, bool withVectors = false, CancellationToken cancellationToken = default);
+ Task DeleteAsync(string key, CancellationToken cancellationToken = default);
+ Task DeleteBatchAsync(IEnumerable keys, CancellationToken cancellationToken = default);
+}
+
+class AzureAISearchVectorRecordStore(
+ Azure.Search.Documents.Indexes.SearchIndexClient client,
+ Schema schema): IVectorRecordStore;
+
+class WeaviateVectorRecordStore(
+ WeaviateClient client,
+ Schema schema): IVectorRecordStore;
+
+class RedisVectorRecordStore(
+ StackExchange.Redis.IDatabase database,
+ Schema schema): IVectorRecordStore;
+```
+
+#### Option 2 - Separated collection and record management with opinionated create implementations
+
+```cs
+
+interface IVectorCollectionStore
+{
+ virtual Task CreateChatHistoryCollectionAsync(string name, CancellationToken cancellationToken = default);
+ virtual Task CreateSemanticCacheCollectionAsync(string name, CancellationToken cancellationToken = default);
+
+ IAsyncEnumerable ListCollectionNamesAsync(CancellationToken cancellationToken = default);
+ Task CollectionExistsAsync(string name, CancellationToken cancellationToken = default);
+ Task DeleteCollectionAsync(string name, CancellationToken cancellationToken = default);
+}
+
+class AzureAISearchVectorCollectionStore: IVectorCollectionStore;
+class RedisVectorCollectionStore: IVectorCollectionStore;
+class WeaviateVectorCollectionStore: IVectorCollectionStore;
+
+// Customers can inherit from our implementations and replace just the creation scenarios to match their schemas.
+class CustomerCollectionStore: AzureAISearchVectorCollectionStore, IVectorCollectionStore;
+
+// We can also create implementations that create indices based on an MLIndex specification.
+class MLIndexAzureAISearchVectorCollectionStore(MLIndex mlIndexSpec): AzureAISearchVectorCollectionStore, IVectorCollectionStore;
+
+interface IVectorRecordStore
+{
+ Task GetAsync(string key, GetRecordOptions? options = default, CancellationToken cancellationToken = default);
+ Task DeleteAsync(string key, DeleteRecordOptions? options = default, CancellationToken cancellationToken = default);
+ Task UpsertAsync(TRecord record, UpsertRecordOptions? options = default, CancellationToken cancellationToken = default);
+}
+
+class AzureAISearchVectorRecordStore(): IVectorRecordStore;
+```
+
+#### Option 3 - Separated collection and record management with collection create separate from other operations.
+
+Vector store same as option 2 so not repeated for brevity.
+
+```cs
+
+interface IVectorCollectionCreate
+{
+ virtual Task CreateCollectionAsync(string name, CancellationToken cancellationToken = default);
+}
+
+// Implement a generic version of create that takes a configuration that should work for 80% of cases.
+class AzureAISearchConfiguredVectorCollectionCreate(CollectionCreateConfig collectionConfig): IVectorCollectionCreate;
+
+// Allow custom implementations of create for break glass scenarios for outside the 80% case.
+class AzureAISearchChatHistoryVectorCollectionCreate: IVectorCollectionCreate;
+class AzureAISearchSemanticCacheVectorCollectionCreate: IVectorCollectionCreate;
+
+// Customers can create their own creation scenarios to match their schemas, but can continue to use our get, does exist and delete class.
+class CustomerChatHistoryVectorCollectionCreate: IVectorCollectionCreate;
+
+interface IVectorCollectionNonSchema
+{
+ IAsyncEnumerable ListCollectionNamesAsync(CancellationToken cancellationToken = default);
+ Task CollectionExistsAsync(string name, CancellationToken cancellationToken = default);
+ Task DeleteCollectionAsync(string name, CancellationToken cancellationToken = default);
+}
+
+class AzureAISearchVectorCollectionNonSchema: IVectorCollectionNonSchema;
+class RedisVectorCollectionNonSchema: IVectorCollectionNonSchema;
+class WeaviateVectorCollectionNonSchema: IVectorCollectionNonSchema;
+
+```
+
+#### Option 4 - Separated collection and record management with collection create separate from other operations, with collection management aggregation class on top.
+
+Variation on option 3.
+
+```cs
+
+interface IVectorCollectionCreate
+{
+ virtual Task CreateCollectionAsync(string name, CancellationToken cancellationToken = default);
+}
+
+interface IVectorCollectionNonSchema
+{
+ IAsyncEnumerable ListCollectionNamesAsync(CancellationToken cancellationToken = default);
+ Task CollectionExistsAsync(string name, CancellationToken cancellationToken = default);
+ Task DeleteCollectionAsync(string name, CancellationToken cancellationToken = default);
+}
+
+// DB Specific NonSchema implementations
+class AzureAISearchVectorCollectionNonSchema: IVectorCollectionNonSchema;
+class RedisVectorCollectionNonSchema: IVectorCollectionNonSchema;
+
+// Combined Create + NonSchema Interface
+interface IVectorCollectionStore: IVectorCollectionCreate, IVectorCollectionNonSchema {}
+
+// Base abstract class that forwards non-create operations to provided implementation.
+abstract class VectorCollectionStore(IVectorCollectionNonSchema collectionNonSchema): IVectorCollectionStore
+{
+ public abstract Task CreateCollectionAsync(string name, CancellationToken cancellationToken = default);
+ public IAsyncEnumerable ListCollectionNamesAsync(CancellationToken cancellationToken = default) { return collectionNonSchema.ListCollectionNamesAsync(cancellationToken); }
+ public Task CollectionExistsAsync(string name, CancellationToken cancellationToken = default) { return collectionNonSchema.CollectionExistsAsync(name, cancellationToken); }
+ public Task DeleteCollectionAsync(string name, CancellationToken cancellationToken = default) { return collectionNonSchema.DeleteCollectionAsync(name, cancellationToken); }
+}
+
+// Collections store implementations, that inherit from base class, and just adds the different creation implementations.
+class AzureAISearchChatHistoryVectorCollectionStore(AzureAISearchVectorCollectionNonSchema nonSchema): VectorCollectionStore(nonSchema);
+class AzureAISearchSemanticCacheVectorCollectionStore(AzureAISearchVectorCollectionNonSchema nonSchema): VectorCollectionStore(nonSchema);
+class AzureAISearchMLIndexVectorCollectionStore(AzureAISearchVectorCollectionNonSchema nonSchema): VectorCollectionStore(nonSchema);
+
+// Customer collections store implementation, that uses the base Azure AI Search implementation for get, doesExist and delete, but adds its own creation.
+class ContosoProductsVectorCollectionStore(AzureAISearchVectorCollectionNonSchema nonSchema): VectorCollectionStore(nonSchema);
+
+```
+
+#### Option 5 - Separated collection and record management with collection create separate from other operations, with overall aggregation class on top.
+
+Same as option 3 / 4, plus:
+
+```cs
+
+interface IVectorStore : IVectorCollectionStore, IVectorRecordStore
+{
+}
+
+// Create a static factory that produces one of these, so only the interface is public, not the class.
+internal class VectorStore(IVectorCollectionCreate create, IVectorCollectionNonSchema nonSchema, IVectorRecordStore records): IVectorStore
+{
+}
+
+```
+
+#### Option 6 - Collection store acts as factory for record store.
+
+`IVectorStore` acts as a factory for `IVectorStoreCollection`, and any schema agnostic multi-collection operations are kept on `IVectorStore`.
+
+
+```cs
+public interface IVectorStore
+{
+ IVectorStoreCollection GetCollection(string name, VectorStoreRecordDefinition? vectorStoreRecordDefinition = null);
+ IAsyncEnumerable ListCollectionNamesAsync(CancellationToken cancellationToken = default));
+}
+
+public interface IVectorStoreCollection
+{
+ public string Name { get; }
+
+ // Collection Operations
+ Task CreateCollectionAsync();
+ Task CreateCollectionIfNotExistsAsync();
+ Task CollectionExistsAsync();
+ Task DeleteCollectionAsync();
+
+ // Data manipulation
+ Task GetAsync(TKey key, GetRecordOptions? options = default, CancellationToken cancellationToken = default);
+ IAsyncEnumerable GetBatchAsync(IEnumerable keys, GetRecordOptions? options = default, CancellationToken cancellationToken = default);
+ Task DeleteAsync(TKey key, DeleteRecordOptions? options = default, CancellationToken cancellationToken = default);
+ Task DeleteBatchAsync(IEnumerable keys, DeleteRecordOptions? options = default, CancellationToken cancellationToken = default);
+ Task UpsertAsync(TRecord record, UpsertRecordOptions? options = default, CancellationToken cancellationToken = default);
+ IAsyncEnumerable UpsertBatchAsync(IEnumerable records, UpsertRecordOptions? options = default, CancellationToken cancellationToken = default);
+}
+```
+
+
+#### Decision Outcome
+
+Option 1 is problematic on its own, since we have to allow consumers to create custom implementations of collection create for break glass scenarios. With
+a single interface like this, it will require them to implement many methods that they do not want to change. Options 4 & 5, gives us more flexibility while
+still preserving the ease of use of an aggregated interface as described in Option 1.
+
+Option 2 doesn't give us the flexbility we need for break glass scenarios, since it only allows certain types of collections to be created. It also means
+that each time a new collection type is required it introduces a breaking change, so it is not a viable option.
+
+Since collection create and configuration and the possible options vary considerable across different database types, we will need to support an easy
+to use break glass scenario for collection creation. While we would be able to develop a basic configurable create option, for complex create scenarios
+users will need to implement their own. We will also need to support multiple create implementations out of the box, e.g. a configuration based option using
+our own configuration, create implementations that re-create the current model for backward compatibility, create implementations that use other configuration
+as input, e.g. Azure-ML YAML. Therefore separating create, which may have many implementations, from exists, list and delete, which requires only a single implementation per database type is useful.
+Option 3 provides us this separation, but Option 4 + 5 builds on top of this, and allows us to combine different implementations together for simpler
+consumption.
+
+Chosen option: 6
+
+- Easy to use, and similar to many SDk implementations.
+- Can pass a single object around for both collection and record access.
+
+### Question 2: Collection name and key value normalization in store, decorator or via injection.
+
+#### Option 1 - Normalization in main record store
+
+- Pros: Simple
+- Cons: The normalization needs to vary separately from the record store, so this will not work
+
+```cs
+ public class AzureAISearchVectorStoreCollection : IVectorStoreCollection
+ {
+ ...
+
+ // On input.
+ var normalizedCollectionName = this.NormalizeCollectionName(collectionName);
+ var encodedId = AzureAISearchMemoryRecord.EncodeId(key);
+
+ ...
+
+ // On output.
+ DecodeId(this.Id)
+
+ ...
+ }
+```
+
+#### Option 2 - Normalization in decorator
+
+- Pros: Allows normalization to vary separately from the record store.
+- Pros: No code executed when no normalization required.
+- Pros: Easy to package matching encoders/decoders together.
+- Pros: Easier to obsolete encoding/normalization as a concept.
+- Cons: Not a major con, but need to implement the full VectorStoreCollection interface, instead of e.g. just providing the two translation functions, if we go with option 3.
+- Cons: Hard to have a generic implementation that can work with any model, without either changing the data in the provided object on upsert or doing cloning in an expensive way.
+
+```cs
+ new KeyNormalizingAISearchVectorStoreCollection(
+ "keyField",
+ new AzureAISearchVectorStoreCollection(...));
+```
+
+#### Option 3 - Normalization via optional function parameters to record store constructor
+
+- Pros: Allows normalization to vary separately from the record store.
+- Pros: No need to implement the full VectorStoreCollection interface.
+- Pros: Can modify values on serialization without changing the incoming record, if supported by DB SDK.
+- Cons: Harder to package matching encoders/decoders together.
+
+```cs
+public class AzureAISearchVectorStoreCollection(StoreOptions options);
+
+public class StoreOptions
+{
+ public Func? EncodeKey { get; init; }
+ public Func? DecodeKey { get; init; }
+ public Func? SanitizeCollectionName { get; init; }
+}
+```
+
+#### Option 4 - Normalization via custom mapper
+
+If developer wants to change any values they can do so by creating a custom mapper.
+
+- Cons: Developer needs to implement a mapper if they want to do normalization.
+- Cons: Developer cannot change collection name as part of the mapping.
+- Pros: No new extension points required to support normalization.
+- Pros: Developer can change any field in the record.
+
+#### Decision Outcome
+
+Chosen option 3, since it is similar to how we are doing mapper injection and would also work well in python.
+
+Option 1 won't work because if e.g. the data was written using another tool, it may be unlikely that it was encoded using the same mechanism as supported here
+and therefore this functionality may not be appropriate. The developer should have the ability to not use this functionality or
+provide their own encoding / decoding behavior.
+
+### Question 3: Collection name as method param or via constructor or either
+
+#### Option 1 - Collection name as method param
+
+```cs
+public class MyVectorStoreCollection()
+{
+ public async Task GetAsync(string collectionName, string key, GetRecordOptions? options = default, CancellationToken cancellationToken = default);
+}
+```
+
+#### Option 2 - Collection name via constructor
+
+```cs
+public class MyVectorStoreCollection(string defaultCollectionName)
+{
+ public async Task GetAsync(string key, GetRecordOptions? options = default, CancellationToken cancellationToken = default);
+}
+```
+
+#### Option 3 - Collection name via either
+
+```cs
+public class MyVectorStoreCollection(string defaultCollectionName)
+{
+ public async Task GetAsync(string key, GetRecordOptions? options = default, CancellationToken cancellationToken = default);
+}
+
+public class GetRecordOptions
+{
+ public string CollectionName { get; init; };
+}
+```
+
+#### Decision Outcome
+
+Chosen option 2. None of the other options work with the decision outcome of Question 1, since that design requires the `VectorStoreCollection` to be tied to a single collection instance.
+
+### Question 4: How to normalize ids across different vector stores where different types are supported.
+
+#### Option 1 - Take a string and convert to a type that was specified on the constructor
+
+```cs
+public async Task GetAsync(string key, GetRecordOptions? options = default, CancellationToken cancellationToken = default)
+{
+ var convertedKey = this.keyType switch
+ {
+ KeyType.Int => int.parse(key),
+ KeyType.GUID => Guid.parse(key)
+ }
+
+ ...
+}
+```
+
+- No additional overloads are required over time so no breaking changes.
+- Most data types can easily be represented in string form and converted to/from it.
+
+#### Option 2 - Take an object and cast to a type that was specified on the constructor.
+
+```cs
+public async Task GetAsync(object key, GetRecordOptions? options = default, CancellationToken cancellationToken = default)
+{
+ var convertedKey = this.keyType switch
+ {
+ KeyType.Int => key as int,
+ KeyType.GUID => key as Guid
+ }
+
+ if (convertedKey is null)
+ {
+ throw new InvalidOperationException($"The provided key must be of type {this.keyType}")
+ }
+
+ ...
+}
+
+```
+
+- No additional overloads are required over time so no breaking changes.
+- Any data types can be represented as object.
+
+#### Option 3 - Multiple overloads where we convert where possible, throw when not possible.
+
+```cs
+public async Task GetAsync(string key, GetRecordOptions? options = default, CancellationToken cancellationToken = default)
+{
+ var convertedKey = this.keyType switch
+ {
+ KeyType.Int => int.Parse(key),
+ KeyType.String => key,
+ KeyType.GUID => Guid.Parse(key)
+ }
+}
+public async Task GetAsync(int key, GetRecordOptions? options = default, CancellationToken cancellationToken = default)
+{
+ var convertedKey = this.keyType switch
+ {
+ KeyType.Int => key,
+ KeyType.String => key.ToString(),
+ KeyType.GUID => throw new InvalidOperationException($"The provided key must be convertible to a GUID.")
+ }
+}
+public async Task GetAsync(GUID key, GetRecordOptions? options = default, CancellationToken cancellationToken = default)
+{
+ var convertedKey = this.keyType switch
+ {
+ KeyType.Int => throw new InvalidOperationException($"The provided key must be convertible to an int.")
+ KeyType.String => key.ToString(),
+ KeyType.GUID => key
+ }
+}
+```
+
+- Additional overloads are required over time if new key types are found on new connectors, causing breaking changes.
+- You can still call a method that causes a runtime error, when the type isn't supported.
+
+#### Option 4 - Add key type as generic to interface
+
+```cs
+interface IVectorRecordStore
+{
+ Task GetAsync(TKey key, GetRecordOptions? options = default, CancellationToken cancellationToken = default);
+}
+
+class AzureAISearchVectorRecordStore: IVectorRecordStore
+{
+ public AzureAISearchVectorRecordStore()
+ {
+ // Check if TKey matches the type of the field marked as a key on TRecord and throw if they don't match.
+ // Also check if keytype is one of the allowed types for Azure AI Search and throw if it isn't.
+ }
+}
+
+```
+
+- No runtime issues after construction.
+- More cumbersome interface.
+
+#### Decision Outcome
+
+Chosen option 4, since it is forwards compatible with any complex key types we may need to support but still allows
+each implementation to hardcode allowed key types if the vector db only supports certain key types.
+
+### Question 5: Store Interface/Class Naming.
+
+#### Option 1 - VectorDB
+
+```cs
+interface IVectorDBRecordService {}
+interface IVectorDBCollectionUpdateService {}
+interface IVectorDBCollectionCreateService {}
+```
+
+#### Option 2 - Memory
+
+```cs
+interface IMemoryRecordService {}
+interface IMemoryCollectionUpdateService {}
+interface IMemoryCollectionCreateService {}
+```
+
+### Option 3 - VectorStore
+
+```cs
+interface IVectorRecordStore {}
+interface IVectorCollectionNonSchema {}
+interface IVectorCollectionCreate {}
+interface IVectorCollectionStore {}: IVectorCollectionCreate, IVectorCollectionNonSchema
+interface IVectorStore {}: IVectorCollectionStore, IVectorRecordStore
+```
+
+### Option 4 - VectorStore + VectorStoreCollection
+
+```cs
+interface IVectorStore
+{
+ IVectorStoreCollection GetCollection()
+}
+interface IVectorStoreCollection
+{
+ Get()
+ Delete()
+ Upsert()
+}
+```
+
+#### Decision Outcome
+
+Chosen option 4. The word memory is broad enough to encompass any data, so using it seems arbitrary. All competitors are using the term vector store, so using something similar is good for recognition.
+Option 4 also matches our design as chosen in question 1.
+
+## Usage Examples
+
+### DI Framework: .net 8 Keyed Services
+
+```cs
+class CacheEntryModel(string prompt, string result, ReadOnlyMemory promptEmbedding);
+
+class SemanticTextMemory(IVectorStore configuredVectorStore, VectorStoreRecordDefinition? vectorStoreRecordDefinition): ISemanticTextMemory
+{
+ public async Task SaveInformation(string collectionName, TDataType record)
+ {
+ var collection = vectorStore.GetCollection(collectionName, vectorStoreRecordDefinition);
+ if (!await collection.CollectionExists())
+ {
+ await collection.CreateCollection();
+ }
+ await collection.UpsertAsync(record);
+ }
+}
+
+class CacheSetFunctionFilter(ISemanticTextMemory memory); // Saves results to cache.
+class CacheGetPromptFilter(ISemanticTextMemory memory); // Check cache for entries.
+
+var builder = Kernel.CreateBuilder();
+
+builder
+ // Existing registration:
+ .AddAzureOpenAITextEmbeddingGeneration(textEmbeddingDeploymentName, azureAIEndpoint, apiKey, serviceId: "AzureOpenAI:text-embedding-ada-002")
+
+ // Register an IVectorStore implementation under the given key.
+ .AddAzureAISearch("Cache", azureAISearchEndpoint, apiKey, new Options() { withEmbeddingGeneration = true });
+
+// Add Semantic Cache Memory for the cache entry model.
+builder.Services.AddTransient(sp => {
+ return new SemanticTextMemory(
+ sp.GetKeyedService("Cache"),
+ cacheRecordDefinition);
+});
+
+// Add filter to retrieve items from cache and one to add items to cache.
+// Since these filters depend on ISemanticTextMemory and that is already registered, it should get matched automatically.
+builder.Services.AddTransient();
+builder.Services.AddTransient();
+```
+
+## Roadmap
+
+### Record Management
+
+1. Release VectorStoreCollection public interface and implementations for Azure AI Search, Qdrant and Redis.
+2. Add support for registering record stores with SK container to allow automatic dependency injection.
+3. Add VectorStoreCollection implementations for remaining stores.
+
+### Collection Management
+
+4. Release Collection Management public interface and implementations for Azure AI Search, Qdrant and Redis.
+5. Add support for registering collection management with SK container to allow automatic dependency injection.
+6. Add Collection Management implementations for remaining stores.
+
+### Collection Creation
+
+7. Release Collection Creation public interface.
+8. Create cross db collection creation config that supports common functionality, and per daatabase implementation that supports this configuration.
+9. Add support for registering collection creation with SK container to allow automatic dependency injection.
+
+### First Party Memory Features and well known model support
+
+10. Add model and mappers for legacy SK MemoryStore interface, so that consumers using this has an upgrade path to the new memory storage stack.
+11. Add model and mappers for popular loader systems, like Kernel Memory or LlamaIndex.
+11. Explore adding first party implementations for common scenarios, e.g. semantic caching. Specfics TBD.
+
+### Cross Cutting Requirements
+
+Need the following for all features:
+
+- Unit tests
+- Integration tests
+- Logging / Telemetry
+- Common Exception Handling
+- Samples, including:
+ - Usage scenario for collection and record management using custom model and configured collection creation.
+ - A simple consumption example like semantic caching, specfics TBD.
+ - Adding your own collection creation implementation.
+ - Adding your own custom model mapper.
+- Documentation, including:
+ - How to create models and annotate/describe them to use with the storage system.
+ - How to define configuration for creating collections using common create implementation.
+ - How to use record and collection management apis.
+ - How to implement your own collection create implementation for break glass scenario.
+ - How to implement your own mapper.
+ - How to upgrade from the current storage system to the new one.
diff --git a/dotnet/Directory.Packages.props b/dotnet/Directory.Packages.props
index 645c8a249d2a..b1c7dc58eddc 100644
--- a/dotnet/Directory.Packages.props
+++ b/dotnet/Directory.Packages.props
@@ -10,7 +10,7 @@
-
+
@@ -18,7 +18,7 @@
-
+
@@ -27,9 +27,10 @@
-
+
+
@@ -38,12 +39,12 @@
-
+
-
+
@@ -68,23 +69,24 @@
+
-
+
-
+
-
-
+
+
-
+
@@ -92,6 +94,7 @@
+
diff --git a/dotnet/SK-dotnet.sln b/dotnet/SK-dotnet.sln
index 6574700e6ce6..b6cd87d2040b 100644
--- a/dotnet/SK-dotnet.sln
+++ b/dotnet/SK-dotnet.sln
@@ -318,7 +318,9 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Connectors.Redis.UnitTests"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Connectors.Qdrant.UnitTests", "src\Connectors\Connectors.Qdrant.UnitTests\Connectors.Qdrant.UnitTests.csproj", "{E92AE954-8F3A-4A6F-A4F9-DC12017E5AAF}"
EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StepwisePlannerMigration", "samples\Demos\StepwisePlannerMigration\StepwisePlannerMigration.csproj", "{38374C62-0263-4FE8-A18C-70FC8132912B}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "StepwisePlannerMigration", "samples\Demos\StepwisePlannerMigration\StepwisePlannerMigration.csproj", "{38374C62-0263-4FE8-A18C-70FC8132912B}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AIModelRouter", "samples\Demos\AIModelRouter\AIModelRouter.csproj", "{E06818E3-00A5-41AC-97ED-9491070CDEA1}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -795,6 +797,12 @@ Global
{38374C62-0263-4FE8-A18C-70FC8132912B}.Publish|Any CPU.Build.0 = Debug|Any CPU
{38374C62-0263-4FE8-A18C-70FC8132912B}.Release|Any CPU.ActiveCfg = Release|Any CPU
{38374C62-0263-4FE8-A18C-70FC8132912B}.Release|Any CPU.Build.0 = Release|Any CPU
+ {E06818E3-00A5-41AC-97ED-9491070CDEA1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+ {E06818E3-00A5-41AC-97ED-9491070CDEA1}.Debug|Any CPU.Build.0 = Debug|Any CPU
+ {E06818E3-00A5-41AC-97ED-9491070CDEA1}.Publish|Any CPU.ActiveCfg = Debug|Any CPU
+ {E06818E3-00A5-41AC-97ED-9491070CDEA1}.Publish|Any CPU.Build.0 = Debug|Any CPU
+ {E06818E3-00A5-41AC-97ED-9491070CDEA1}.Release|Any CPU.ActiveCfg = Release|Any CPU
+ {E06818E3-00A5-41AC-97ED-9491070CDEA1}.Release|Any CPU.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
@@ -904,6 +912,7 @@ Global
{1D4667B9-9381-4E32-895F-123B94253EE8} = {0247C2C9-86C3-45BA-8873-28B0948EDC0C}
{E92AE954-8F3A-4A6F-A4F9-DC12017E5AAF} = {0247C2C9-86C3-45BA-8873-28B0948EDC0C}
{38374C62-0263-4FE8-A18C-70FC8132912B} = {5D4C0700-BBB5-418F-A7B2-F392B9A18263}
+ {E06818E3-00A5-41AC-97ED-9491070CDEA1} = {5D4C0700-BBB5-418F-A7B2-F392B9A18263}
EndGlobalSection
GlobalSection(ExtensibilityGlobals) = postSolution
SolutionGuid = {FBDC56A3-86AD-4323-AA0F-201E59123B83}
diff --git a/dotnet/nuget/nuget-package.props b/dotnet/nuget/nuget-package.props
index 3e173111cdd3..00837d71f910 100644
--- a/dotnet/nuget/nuget-package.props
+++ b/dotnet/nuget/nuget-package.props
@@ -1,7 +1,7 @@
- 1.16.1
+ 1.17.1
$(VersionPrefix)-$(VersionSuffix)
$(VersionPrefix)
@@ -10,7 +10,7 @@
true
- 1.16.1
+ 1.17.0
$(NoWarn);CP0003
diff --git a/dotnet/samples/Concepts/Agents/ChatCompletion_FunctionTermination.cs b/dotnet/samples/Concepts/Agents/ChatCompletion_FunctionTermination.cs
index f344dae432b9..16c019aebbfd 100644
--- a/dotnet/samples/Concepts/Agents/ChatCompletion_FunctionTermination.cs
+++ b/dotnet/samples/Concepts/Agents/ChatCompletion_FunctionTermination.cs
@@ -1,5 +1,6 @@
// Copyright (c) Microsoft. All rights reserved.
using System.ComponentModel;
+using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;
@@ -21,8 +22,8 @@ public async Task UseAutoFunctionInvocationFilterWithAgentInvocationAsync()
new()
{
Instructions = "Answer questions about the menu.",
- Kernel = CreateKernelWithChatCompletion(),
- ExecutionSettings = new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions },
+ Kernel = CreateKernelWithFilter(),
+ Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions }),
};
KernelPlugin plugin = KernelPluginFactory.CreateFromType();
@@ -74,8 +75,8 @@ public async Task UseAutoFunctionInvocationFilterWithAgentChatAsync()
new()
{
Instructions = "Answer questions about the menu.",
- Kernel = CreateKernelWithChatCompletion(),
- ExecutionSettings = new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions },
+ Kernel = CreateKernelWithFilter(),
+ Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions }),
};
KernelPlugin plugin = KernelPluginFactory.CreateFromType();
@@ -119,17 +120,41 @@ private void WriteContent(ChatMessageContent content)
Console.WriteLine($"[{content.Items.LastOrDefault()?.GetType().Name ?? "(empty)"}] {content.Role} : '{content.Content}'");
}
+ private Kernel CreateKernelWithFilter()
+ {
+ IKernelBuilder builder = Kernel.CreateBuilder();
+
+ if (this.UseOpenAIConfig)
+ {
+ builder.AddOpenAIChatCompletion(
+ TestConfiguration.OpenAI.ChatModelId,
+ TestConfiguration.OpenAI.ApiKey);
+ }
+ else
+ {
+ builder.AddAzureOpenAIChatCompletion(
+ TestConfiguration.AzureOpenAI.ChatDeploymentName,
+ TestConfiguration.AzureOpenAI.Endpoint,
+ TestConfiguration.AzureOpenAI.ApiKey);
+ }
+
+ builder.Services.AddSingleton(new AutoInvocationFilter());
+
+ return builder.Build();
+ }
+
private sealed class MenuPlugin
{
[KernelFunction, Description("Provides a list of specials from the menu.")]
[System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1024:Use properties where appropriate", Justification = "Too smart")]
public string GetSpecials()
{
- return @"
-Special Soup: Clam Chowder
-Special Salad: Cobb Salad
-Special Drink: Chai Tea
-";
+ return
+ """
+ Special Soup: Clam Chowder
+ Special Salad: Cobb Salad
+ Special Drink: Chai Tea
+ """;
}
[KernelFunction, Description("Provides the price of the requested menu item.")]
diff --git a/dotnet/samples/Concepts/Agents/ChatCompletion_HistoryReducer.cs b/dotnet/samples/Concepts/Agents/ChatCompletion_HistoryReducer.cs
new file mode 100644
index 000000000000..6e0816bc8470
--- /dev/null
+++ b/dotnet/samples/Concepts/Agents/ChatCompletion_HistoryReducer.cs
@@ -0,0 +1,173 @@
+// Copyright (c) Microsoft. All rights reserved.
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.Agents.History;
+using Microsoft.SemanticKernel.ChatCompletion;
+
+namespace Agents;
+
+///
+/// Demonstrate creation of and
+/// eliciting its response to three explicit user messages.
+///
+public class ChatCompletion_HistoryReducer(ITestOutputHelper output) : BaseTest(output)
+{
+ private const string TranslatorName = "NumeroTranslator";
+ private const string TranslatorInstructions = "Add one to latest user number and spell it in spanish without explanation.";
+
+ ///
+ /// Demonstrate the use of when directly
+ /// invoking a .
+ ///
+ [Fact]
+ public async Task TruncatedAgentReductionAsync()
+ {
+ // Define the agent
+ ChatCompletionAgent agent = CreateTruncatingAgent(10, 10);
+
+ await InvokeAgentAsync(agent, 50);
+ }
+
+ ///
+ /// Demonstrate the use of when directly
+ /// invoking a .
+ ///
+ [Fact]
+ public async Task SummarizedAgentReductionAsync()
+ {
+ // Define the agent
+ ChatCompletionAgent agent = CreateSummarizingAgent(10, 10);
+
+ await InvokeAgentAsync(agent, 50);
+ }
+
+ ///
+ /// Demonstrate the use of when using
+ /// to invoke a .
+ ///
+ [Fact]
+ public async Task TruncatedChatReductionAsync()
+ {
+ // Define the agent
+ ChatCompletionAgent agent = CreateTruncatingAgent(10, 10);
+
+ await InvokeChatAsync(agent, 50);
+ }
+
+ ///
+ /// Demonstrate the use of when using
+ /// to invoke a .
+ ///
+ [Fact]
+ public async Task SummarizedChatReductionAsync()
+ {
+ // Define the agent
+ ChatCompletionAgent agent = CreateSummarizingAgent(10, 10);
+
+ await InvokeChatAsync(agent, 50);
+ }
+
+ // Proceed with dialog by directly invoking the agent and explicitly managing the history.
+ private async Task InvokeAgentAsync(ChatCompletionAgent agent, int messageCount)
+ {
+ ChatHistory chat = [];
+
+ int index = 1;
+ while (index <= messageCount)
+ {
+ // Provide user input
+ chat.Add(new ChatMessageContent(AuthorRole.User, $"{index}"));
+ Console.WriteLine($"# {AuthorRole.User}: '{index}'");
+
+ // Reduce prior to invoking the agent
+ bool isReduced = await agent.ReduceAsync(chat);
+
+ // Invoke and display assistant response
+ await foreach (ChatMessageContent message in agent.InvokeAsync(chat))
+ {
+ chat.Add(message);
+ Console.WriteLine($"# {message.Role} - {message.AuthorName ?? "*"}: '{message.Content}'");
+ }
+
+ index += 2;
+
+ // Display the message count of the chat-history for visibility into reduction
+ Console.WriteLine($"@ Message Count: {chat.Count}\n");
+
+ // Display summary messages (if present) if reduction has occurred
+ if (isReduced)
+ {
+ int summaryIndex = 0;
+ while (chat[summaryIndex].Metadata?.ContainsKey(ChatHistorySummarizationReducer.SummaryMetadataKey) ?? false)
+ {
+ Console.WriteLine($"\tSummary: {chat[summaryIndex].Content}");
+ ++summaryIndex;
+ }
+ }
+ }
+ }
+
+ // Proceed with dialog with AgentGroupChat.
+ private async Task InvokeChatAsync(ChatCompletionAgent agent, int messageCount)
+ {
+ AgentGroupChat chat = new();
+
+ int lastHistoryCount = 0;
+
+ int index = 1;
+ while (index <= messageCount)
+ {
+ // Provide user input
+ chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, $"{index}"));
+ Console.WriteLine($"# {AuthorRole.User}: '{index}'");
+
+ // Invoke and display assistant response
+ await foreach (ChatMessageContent message in chat.InvokeAsync(agent))
+ {
+ Console.WriteLine($"# {message.Role} - {message.AuthorName ?? "*"}: '{message.Content}'");
+ }
+
+ index += 2;
+
+ // Display the message count of the chat-history for visibility into reduction
+ // Note: Messages provided in descending order (newest first)
+ ChatMessageContent[] history = await chat.GetChatMessagesAsync(agent).ToArrayAsync();
+ Console.WriteLine($"@ Message Count: {history.Length}\n");
+
+ // Display summary messages (if present) if reduction has occurred
+ if (history.Length < lastHistoryCount)
+ {
+ int summaryIndex = history.Length - 1;
+ while (history[summaryIndex].Metadata?.ContainsKey(ChatHistorySummarizationReducer.SummaryMetadataKey) ?? false)
+ {
+ Console.WriteLine($"\tSummary: {history[summaryIndex].Content}");
+ --summaryIndex;
+ }
+ }
+
+ lastHistoryCount = history.Length;
+ }
+ }
+
+ private ChatCompletionAgent CreateSummarizingAgent(int reducerMessageCount, int reducerThresholdCount)
+ {
+ Kernel kernel = this.CreateKernelWithChatCompletion();
+ return
+ new()
+ {
+ Name = TranslatorName,
+ Instructions = TranslatorInstructions,
+ Kernel = kernel,
+ HistoryReducer = new ChatHistorySummarizationReducer(kernel.GetRequiredService(), reducerMessageCount, reducerThresholdCount),
+ };
+ }
+
+ private ChatCompletionAgent CreateTruncatingAgent(int reducerMessageCount, int reducerThresholdCount) =>
+ new()
+ {
+ Name = TranslatorName,
+ Instructions = TranslatorInstructions,
+ Kernel = this.CreateKernelWithChatCompletion(),
+ HistoryReducer = new ChatHistoryTruncationReducer(reducerMessageCount, reducerThresholdCount),
+ };
+}
diff --git a/dotnet/samples/Concepts/Agents/ChatCompletion_ServiceSelection.cs b/dotnet/samples/Concepts/Agents/ChatCompletion_ServiceSelection.cs
new file mode 100644
index 000000000000..82b2ca28bce0
--- /dev/null
+++ b/dotnet/samples/Concepts/Agents/ChatCompletion_ServiceSelection.cs
@@ -0,0 +1,128 @@
+// Copyright (c) Microsoft. All rights reserved.
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.ChatCompletion;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+
+namespace Agents;
+
+///
+/// Demonstrate service selection for through setting service-id
+/// on and also providing override
+/// when calling
+///
+public class ChatCompletion_ServiceSelection(ITestOutputHelper output) : BaseTest(output)
+{
+ private const string ServiceKeyGood = "chat-good";
+ private const string ServiceKeyBad = "chat-bad";
+
+ [Fact]
+ public async Task UseServiceSelectionWithChatCompletionAgentAsync()
+ {
+ // Create kernel with two instances of IChatCompletionService
+ // One service is configured with a valid API key and the other with an
+ // invalid key that will result in a 401 Unauthorized error.
+ Kernel kernel = CreateKernelWithTwoServices();
+
+ // Define the agent targeting ServiceId = ServiceKeyGood
+ ChatCompletionAgent agentGood =
+ new()
+ {
+ Kernel = kernel,
+ Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ServiceId = ServiceKeyGood }),
+ };
+
+ // Define the agent targeting ServiceId = ServiceKeyBad
+ ChatCompletionAgent agentBad =
+ new()
+ {
+ Kernel = kernel,
+ Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ServiceId = ServiceKeyBad }),
+ };
+
+ // Define the agent with no explicit ServiceId defined
+ ChatCompletionAgent agentDefault = new() { Kernel = kernel };
+
+ // Invoke agent as initialized with ServiceId = ServiceKeyGood: Expect agent response
+ Console.WriteLine("\n[Agent With Good ServiceId]");
+ await InvokeAgentAsync(agentGood);
+
+ // Invoke agent as initialized with ServiceId = ServiceKeyBad: Expect failure due to invalid service key
+ Console.WriteLine("\n[Agent With Bad ServiceId]");
+ await InvokeAgentAsync(agentBad);
+
+ // Invoke agent as initialized with no explicit ServiceId: Expect agent response
+ Console.WriteLine("\n[Agent With No ServiceId]");
+ await InvokeAgentAsync(agentDefault);
+
+ // Invoke agent with override arguments where ServiceId = ServiceKeyGood: Expect agent response
+ Console.WriteLine("\n[Bad Agent: Good ServiceId Override]");
+ await InvokeAgentAsync(agentBad, new(new OpenAIPromptExecutionSettings() { ServiceId = ServiceKeyGood }));
+
+ // Invoke agent with override arguments where ServiceId = ServiceKeyBad: Expect failure due to invalid service key
+ Console.WriteLine("\n[Good Agent: Bad ServiceId Override]");
+ await InvokeAgentAsync(agentGood, new(new OpenAIPromptExecutionSettings() { ServiceId = ServiceKeyBad }));
+ Console.WriteLine("\n[Default Agent: Bad ServiceId Override]");
+ await InvokeAgentAsync(agentDefault, new(new OpenAIPromptExecutionSettings() { ServiceId = ServiceKeyBad }));
+
+ // Invoke agent with override arguments with no explicit ServiceId: Expect agent response
+ Console.WriteLine("\n[Good Agent: No ServiceId Override]");
+ await InvokeAgentAsync(agentGood, new(new OpenAIPromptExecutionSettings()));
+ Console.WriteLine("\n[Bad Agent: No ServiceId Override]");
+ await InvokeAgentAsync(agentBad, new(new OpenAIPromptExecutionSettings()));
+ Console.WriteLine("\n[Default Agent: No ServiceId Override]");
+ await InvokeAgentAsync(agentDefault, new(new OpenAIPromptExecutionSettings()));
+
+ // Local function to invoke agent and display the conversation messages.
+ async Task InvokeAgentAsync(ChatCompletionAgent agent, KernelArguments? arguments = null)
+ {
+ ChatHistory chat = [new(AuthorRole.User, "Hello")];
+
+ try
+ {
+ await foreach (ChatMessageContent response in agent.InvokeAsync(chat, arguments))
+ {
+ Console.WriteLine(response.Content);
+ }
+ }
+ catch (HttpOperationException exception)
+ {
+ Console.WriteLine($"Status: {exception.StatusCode}");
+ }
+ }
+ }
+
+ private Kernel CreateKernelWithTwoServices()
+ {
+ IKernelBuilder builder = Kernel.CreateBuilder();
+
+ if (this.UseOpenAIConfig)
+ {
+ builder.AddOpenAIChatCompletion(
+ TestConfiguration.OpenAI.ChatModelId,
+ "bad-key",
+ serviceId: ServiceKeyBad);
+
+ builder.AddOpenAIChatCompletion(
+ TestConfiguration.OpenAI.ChatModelId,
+ TestConfiguration.OpenAI.ApiKey,
+ serviceId: ServiceKeyGood);
+ }
+ else
+ {
+ builder.AddAzureOpenAIChatCompletion(
+ TestConfiguration.AzureOpenAI.ChatDeploymentName,
+ TestConfiguration.AzureOpenAI.Endpoint,
+ "bad-key",
+ serviceId: ServiceKeyBad);
+
+ builder.AddAzureOpenAIChatCompletion(
+ TestConfiguration.AzureOpenAI.ChatDeploymentName,
+ TestConfiguration.AzureOpenAI.Endpoint,
+ TestConfiguration.AzureOpenAI.ApiKey,
+ serviceId: ServiceKeyGood);
+ }
+
+ return builder.Build();
+ }
+}
diff --git a/dotnet/samples/Concepts/Agents/ChatCompletion_Streaming.cs b/dotnet/samples/Concepts/Agents/ChatCompletion_Streaming.cs
index 258e12166a6b..d3e94386af96 100644
--- a/dotnet/samples/Concepts/Agents/ChatCompletion_Streaming.cs
+++ b/dotnet/samples/Concepts/Agents/ChatCompletion_Streaming.cs
@@ -49,7 +49,7 @@ public async Task UseStreamingChatCompletionAgentWithPluginAsync()
Name = "Host",
Instructions = MenuInstructions,
Kernel = this.CreateKernelWithChatCompletion(),
- ExecutionSettings = new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions },
+ Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions }),
};
// Initialize plugin and add to the agent's Kernel (same as direct Kernel usage).
diff --git a/dotnet/samples/Concepts/Agents/MixedChat_Reset.cs b/dotnet/samples/Concepts/Agents/MixedChat_Reset.cs
new file mode 100644
index 000000000000..92aa8a9ce9d4
--- /dev/null
+++ b/dotnet/samples/Concepts/Agents/MixedChat_Reset.cs
@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft. All rights reserved.
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.Agents.OpenAI;
+using Microsoft.SemanticKernel.ChatCompletion;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+
+namespace Agents;
+
+///
+/// Demonstrate the use of .
+///
+public class MixedChat_Reset(ITestOutputHelper output) : BaseTest(output)
+{
+ private const string AgentInstructions =
+ """
+ The user may either provide information or query on information previously provided.
+ If the query does not correspond with information provided, inform the user that their query cannot be answered.
+ """;
+
+ [Fact]
+ public async Task ResetChatAsync()
+ {
+ OpenAIFileService fileService = new(TestConfiguration.OpenAI.ApiKey);
+
+ // Define the agents
+ OpenAIAssistantAgent assistantAgent =
+ await OpenAIAssistantAgent.CreateAsync(
+ kernel: new(),
+ config: new(this.ApiKey, this.Endpoint),
+ new()
+ {
+ Name = nameof(OpenAIAssistantAgent),
+ Instructions = AgentInstructions,
+ ModelId = this.Model,
+ });
+
+ ChatCompletionAgent chatAgent =
+ new()
+ {
+ Name = nameof(ChatCompletionAgent),
+ Instructions = AgentInstructions,
+ Kernel = this.CreateKernelWithChatCompletion(),
+ };
+
+ // Create a chat for agent interaction.
+ AgentGroupChat chat = new();
+
+ // Respond to user input
+ try
+ {
+ await InvokeAgentAsync(assistantAgent, "What is my favorite color?");
+ await InvokeAgentAsync(chatAgent);
+
+ await InvokeAgentAsync(assistantAgent, "I like green.");
+ await InvokeAgentAsync(chatAgent);
+
+ await InvokeAgentAsync(assistantAgent, "What is my favorite color?");
+ await InvokeAgentAsync(chatAgent);
+
+ await chat.ResetAsync();
+
+ await InvokeAgentAsync(assistantAgent, "What is my favorite color?");
+ await InvokeAgentAsync(chatAgent);
+ }
+ finally
+ {
+ await chat.ResetAsync();
+ await assistantAgent.DeleteAsync();
+ }
+
+ // Local function to invoke agent and display the conversation messages.
+ async Task InvokeAgentAsync(Agent agent, string? input = null)
+ {
+ if (!string.IsNullOrWhiteSpace(input))
+ {
+ chat.AddChatMessage(new(AuthorRole.User, input));
+ Console.WriteLine($"\n# {AuthorRole.User}: '{input}'");
+ }
+
+ await foreach (ChatMessageContent message in chat.InvokeAsync(agent))
+ {
+ if (!string.IsNullOrWhiteSpace(message.Content))
+ {
+ Console.WriteLine($"\n# {message.Role} - {message.AuthorName ?? "*"}: '{message.Content}'");
+ }
+ }
+ }
+ }
+}
diff --git a/dotnet/samples/Concepts/ChatCompletion/OpenAI_ChatCompletion.cs b/dotnet/samples/Concepts/ChatCompletion/OpenAI_ChatCompletion.cs
index 22b6eec9baaf..46aadfc243b0 100644
--- a/dotnet/samples/Concepts/ChatCompletion/OpenAI_ChatCompletion.cs
+++ b/dotnet/samples/Concepts/ChatCompletion/OpenAI_ChatCompletion.cs
@@ -1,5 +1,6 @@
// Copyright (c) Microsoft. All rights reserved.
+using Azure.Identity;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.OpenAI;
@@ -11,7 +12,7 @@ public class OpenAI_ChatCompletion(ITestOutputHelper output) : BaseTest(output)
[Fact]
public async Task OpenAIChatSampleAsync()
{
- Console.WriteLine("======== Open AI - ChatGPT ========");
+ Console.WriteLine("======== Open AI - Chat Completion ========");
OpenAIChatCompletionService chatCompletionService = new(TestConfiguration.OpenAI.ChatModelId, TestConfiguration.OpenAI.ApiKey);
@@ -49,7 +50,7 @@ I hope these suggestions are helpful!
[Fact]
public async Task AzureOpenAIChatSampleAsync()
{
- Console.WriteLine("======== Azure Open AI - ChatGPT ========");
+ Console.WriteLine("======== Azure Open AI - Chat Completion ========");
AzureOpenAIChatCompletionService chatCompletionService = new(
deploymentName: TestConfiguration.AzureOpenAI.ChatDeploymentName,
@@ -60,6 +61,24 @@ public async Task AzureOpenAIChatSampleAsync()
await StartChatAsync(chatCompletionService);
}
+ ///
+ /// Sample showing how to use Azure Open AI Chat Completion with Azure Default Credential.
+ /// If local auth is disabled in the Azure Open AI deployment, you can use Azure Default Credential to authenticate.
+ ///
+ [Fact]
+ public async Task AzureOpenAIWithDefaultAzureCredentialSampleAsync()
+ {
+ Console.WriteLine("======== Azure Open AI - Chat Completion with Azure Default Credential ========");
+
+ AzureOpenAIChatCompletionService chatCompletionService = new(
+ deploymentName: TestConfiguration.AzureOpenAI.ChatDeploymentName,
+ endpoint: TestConfiguration.AzureOpenAI.Endpoint,
+ credentials: new DefaultAzureCredential(),
+ modelId: TestConfiguration.AzureOpenAI.ChatModelId);
+
+ await StartChatAsync(chatCompletionService);
+ }
+
private async Task StartChatAsync(IChatCompletionService chatGPT)
{
Console.WriteLine("Chat content:");
diff --git a/dotnet/samples/Concepts/Concepts.csproj b/dotnet/samples/Concepts/Concepts.csproj
index dd43184b6612..89cc2c897d61 100644
--- a/dotnet/samples/Concepts/Concepts.csproj
+++ b/dotnet/samples/Concepts/Concepts.csproj
@@ -14,6 +14,7 @@
+
diff --git a/dotnet/samples/Concepts/Memory/TextChunkerUsage.cs b/dotnet/samples/Concepts/Memory/TextChunkerUsage.cs
index a42e769ae916..51d50c619903 100644
--- a/dotnet/samples/Concepts/Memory/TextChunkerUsage.cs
+++ b/dotnet/samples/Concepts/Memory/TextChunkerUsage.cs
@@ -8,7 +8,7 @@ namespace Memory;
public class TextChunkerUsage(ITestOutputHelper output) : BaseTest(output)
{
- private static readonly Tokenizer s_tokenizer = Tokenizer.CreateTiktokenForModel("gpt-4");
+ private static readonly Tokenizer s_tokenizer = TiktokenTokenizer.CreateForModel("gpt-4");
[Fact]
public void RunExample()
diff --git a/dotnet/samples/Concepts/Memory/TextChunkingAndEmbedding.cs b/dotnet/samples/Concepts/Memory/TextChunkingAndEmbedding.cs
index 013bb4961621..04a74656e948 100644
--- a/dotnet/samples/Concepts/Memory/TextChunkingAndEmbedding.cs
+++ b/dotnet/samples/Concepts/Memory/TextChunkingAndEmbedding.cs
@@ -9,7 +9,7 @@ namespace Memory;
public class TextChunkingAndEmbedding(ITestOutputHelper output) : BaseTest(output)
{
private const string EmbeddingModelName = "text-embedding-ada-002";
- private static readonly Tokenizer s_tokenizer = Tokenizer.CreateTiktokenForModel(EmbeddingModelName);
+ private static readonly Tokenizer s_tokenizer = TiktokenTokenizer.CreateForModel(EmbeddingModelName);
[Fact]
public async Task RunAsync()
diff --git a/dotnet/samples/Concepts/Memory/VectorStoreFixtures/VectorStoreInfra.cs b/dotnet/samples/Concepts/Memory/VectorStoreFixtures/VectorStoreInfra.cs
new file mode 100644
index 000000000000..ea498f20c5ab
--- /dev/null
+++ b/dotnet/samples/Concepts/Memory/VectorStoreFixtures/VectorStoreInfra.cs
@@ -0,0 +1,108 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Docker.DotNet;
+using Docker.DotNet.Models;
+
+namespace Memory.VectorStoreFixtures;
+
+///
+/// Helper class that creates and deletes containers for the vector store examples.
+///
+internal static class VectorStoreInfra
+{
+ ///
+ /// Setup the qdrant container by pulling the image and running it.
+ ///
+ /// The docker client to create the container with.
+ /// The id of the container.
+ public static async Task SetupQdrantContainerAsync(DockerClient client)
+ {
+ await client.Images.CreateImageAsync(
+ new ImagesCreateParameters
+ {
+ FromImage = "qdrant/qdrant",
+ Tag = "latest",
+ },
+ null,
+ new Progress());
+
+ var container = await client.Containers.CreateContainerAsync(new CreateContainerParameters()
+ {
+ Image = "qdrant/qdrant",
+ HostConfig = new HostConfig()
+ {
+ PortBindings = new Dictionary>
+ {
+ {"6333", new List {new() {HostPort = "6333" } }},
+ {"6334", new List {new() {HostPort = "6334" } }}
+ },
+ PublishAllPorts = true
+ },
+ ExposedPorts = new Dictionary
+ {
+ { "6333", default },
+ { "6334", default }
+ },
+ });
+
+ await client.Containers.StartContainerAsync(
+ container.ID,
+ new ContainerStartParameters());
+
+ return container.ID;
+ }
+
+ ///
+ /// Setup the redis container by pulling the image and running it.
+ ///
+ /// The docker client to create the container with.
+ /// The id of the container.
+ public static async Task SetupRedisContainerAsync(DockerClient client)
+ {
+ await client.Images.CreateImageAsync(
+ new ImagesCreateParameters
+ {
+ FromImage = "redis/redis-stack",
+ Tag = "latest",
+ },
+ null,
+ new Progress());
+
+ var container = await client.Containers.CreateContainerAsync(new CreateContainerParameters()
+ {
+ Image = "redis/redis-stack",
+ HostConfig = new HostConfig()
+ {
+ PortBindings = new Dictionary>
+ {
+ {"6379", new List {new() {HostPort = "6379"}}},
+ {"8001", new List {new() {HostPort = "8001"}}}
+ },
+ PublishAllPorts = true
+ },
+ ExposedPorts = new Dictionary
+ {
+ { "6379", default },
+ { "8001", default }
+ },
+ });
+
+ await client.Containers.StartContainerAsync(
+ container.ID,
+ new ContainerStartParameters());
+
+ return container.ID;
+ }
+
+ ///
+ /// Stop and delete the container with the specified id.
+ ///
+ /// The docker client to delete the container in.
+ /// The id of the container to delete.
+ /// An async task.
+ public static async Task DeleteContainerAsync(DockerClient client, string containerId)
+ {
+ await client.Containers.StopContainerAsync(containerId, new ContainerStopParameters());
+ await client.Containers.RemoveContainerAsync(containerId, new ContainerRemoveParameters());
+ }
+}
diff --git a/dotnet/samples/Concepts/Memory/VectorStoreFixtures/VectorStoreQdrantContainerFixture.cs b/dotnet/samples/Concepts/Memory/VectorStoreFixtures/VectorStoreQdrantContainerFixture.cs
new file mode 100644
index 000000000000..820b5d3bf172
--- /dev/null
+++ b/dotnet/samples/Concepts/Memory/VectorStoreFixtures/VectorStoreQdrantContainerFixture.cs
@@ -0,0 +1,56 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Docker.DotNet;
+using Qdrant.Client;
+
+namespace Memory.VectorStoreFixtures;
+
+///
+/// Fixture to use for creating a Qdrant container before tests and delete it after tests.
+///
+public class VectorStoreQdrantContainerFixture : IAsyncLifetime
+{
+ private DockerClient? _dockerClient;
+ private string? _qdrantContainerId;
+
+ public async Task InitializeAsync()
+ {
+ }
+
+ public async Task ManualInitializeAsync()
+ {
+ if (this._qdrantContainerId == null)
+ {
+ // Connect to docker and start the docker container.
+ using var dockerClientConfiguration = new DockerClientConfiguration();
+ this._dockerClient = dockerClientConfiguration.CreateClient();
+ this._qdrantContainerId = await VectorStoreInfra.SetupQdrantContainerAsync(this._dockerClient);
+
+ // Delay until the Qdrant server is ready.
+ var qdrantClient = new QdrantClient("localhost");
+ var succeeded = false;
+ var attemptCount = 0;
+ while (!succeeded && attemptCount++ < 10)
+ {
+ try
+ {
+ await qdrantClient.ListCollectionsAsync();
+ succeeded = true;
+ }
+ catch (Exception)
+ {
+ await Task.Delay(1000);
+ }
+ }
+ }
+ }
+
+ public async Task DisposeAsync()
+ {
+ if (this._dockerClient != null && this._qdrantContainerId != null)
+ {
+ // Delete docker container.
+ await VectorStoreInfra.DeleteContainerAsync(this._dockerClient, this._qdrantContainerId);
+ }
+ }
+}
diff --git a/dotnet/samples/Concepts/Memory/VectorStoreFixtures/VectorStoreRedisContainerFixture.cs b/dotnet/samples/Concepts/Memory/VectorStoreFixtures/VectorStoreRedisContainerFixture.cs
new file mode 100644
index 000000000000..eb35b7ff555f
--- /dev/null
+++ b/dotnet/samples/Concepts/Memory/VectorStoreFixtures/VectorStoreRedisContainerFixture.cs
@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Docker.DotNet;
+
+namespace Memory.VectorStoreFixtures;
+
+///
+/// Fixture to use for creating a Redis container before tests and delete it after tests.
+///
+public class VectorStoreRedisContainerFixture : IAsyncLifetime
+{
+ private DockerClient? _dockerClient;
+ private string? _redisContainerId;
+
+ public async Task InitializeAsync()
+ {
+ }
+
+ public async Task ManualInitializeAsync()
+ {
+ if (this._redisContainerId == null)
+ {
+ // Connect to docker and start the docker container.
+ using var dockerClientConfiguration = new DockerClientConfiguration();
+ this._dockerClient = dockerClientConfiguration.CreateClient();
+ this._redisContainerId = await VectorStoreInfra.SetupRedisContainerAsync(this._dockerClient);
+ }
+ }
+
+ public async Task DisposeAsync()
+ {
+ if (this._dockerClient != null && this._redisContainerId != null)
+ {
+ // Delete docker container.
+ await VectorStoreInfra.DeleteContainerAsync(this._dockerClient, this._redisContainerId);
+ }
+ }
+}
diff --git a/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_CustomMapper.cs b/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_CustomMapper.cs
new file mode 100644
index 000000000000..db8e259f4e7a
--- /dev/null
+++ b/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_CustomMapper.cs
@@ -0,0 +1,204 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using Memory.VectorStoreFixtures;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+using Microsoft.SemanticKernel.Connectors.Redis;
+using Microsoft.SemanticKernel.Data;
+using Microsoft.SemanticKernel.Embeddings;
+using StackExchange.Redis;
+
+namespace Memory;
+
+///
+/// An example showing how to ingest data into a vector store using with a custom mapper.
+/// In this example, the storage model differs significantly from the data model, so a custom mapper is used to map between the two.
+/// A is used to define the schema of the storage model, and this means that the connector
+/// will not try and infer the schema from the data model.
+/// In storage the data is stored as a JSON object that looks similar to this:
+///
+/// {
+/// "Term": "API",
+/// "Definition": "Application Programming Interface. A set of rules and specifications that allow software components to communicate and exchange data.",
+/// "DefinitionEmbedding": [ ... ]
+/// }
+///
+/// However, the data model is a class with a property for key and two dictionaries for the data (Term and Definition) and vector (DefinitionEmbedding).
+///
+/// The example shows the following steps:
+/// 1. Create an embedding generator.
+/// 2. Create a Redis Vector Store using a custom factory for creating collections.
+/// When constructing a collection, the factory injects a custom mapper that maps between the data model and the storage model if required.
+/// 3. Ingest some data into the vector store.
+/// 4. Read the data back from the vector store.
+///
+/// You need a local instance of Docker running, since the associated fixture will try and start a Redis container in the local docker instance to run against.
+///
+public class VectorStore_DataIngestion_CustomMapper(ITestOutputHelper output, VectorStoreRedisContainerFixture redisFixture) : BaseTest(output), IClassFixture
+{
+ ///
+ /// A record definition for the glossary entries that defines the storage schema of the record.
+ ///
+ private static readonly VectorStoreRecordDefinition s_glossaryDefinition = new()
+ {
+ Properties = new List
+ {
+ new VectorStoreRecordKeyProperty("Key", typeof(string)),
+ new VectorStoreRecordDataProperty("Term", typeof(string)),
+ new VectorStoreRecordDataProperty("Definition", typeof(string)),
+ new VectorStoreRecordVectorProperty("DefinitionEmbedding", typeof(ReadOnlyMemory)) { Dimensions = 1536, DistanceFunction = DistanceFunction.DotProductSimilarity }
+ }
+ };
+
+ [Fact]
+ public async Task ExampleAsync()
+ {
+ // Create an embedding generation service.
+ var textEmbeddingGenerationService = new AzureOpenAITextEmbeddingGenerationService(
+ TestConfiguration.AzureOpenAIEmbeddings.DeploymentName,
+ TestConfiguration.AzureOpenAIEmbeddings.Endpoint,
+ TestConfiguration.AzureOpenAIEmbeddings.ApiKey);
+
+ // Initiate the docker container and construct the vector store using the custom factory for creating collections.
+ await redisFixture.ManualInitializeAsync();
+ ConnectionMultiplexer redis = ConnectionMultiplexer.Connect("localhost:6379");
+ var vectorStore = new RedisVectorStore(redis.GetDatabase(), new() { VectorStoreCollectionFactory = new Factory() });
+
+ // Get and create collection if it doesn't exist, using the record definition containing the storage model.
+ var collection = vectorStore.GetCollection("skglossary", s_glossaryDefinition);
+ await collection.CreateCollectionIfNotExistsAsync();
+
+ // Create glossary entries and generate embeddings for them.
+ var glossaryEntries = CreateGlossaryEntries().ToList();
+ var tasks = glossaryEntries.Select(entry => Task.Run(async () =>
+ {
+ entry.Vectors["DefinitionEmbedding"] = await textEmbeddingGenerationService.GenerateEmbeddingAsync((string)entry.Data["Definition"]);
+ }));
+ await Task.WhenAll(tasks);
+
+ // Upsert the glossary entries into the collection and return their keys.
+ var upsertedKeysTasks = glossaryEntries.Select(x => collection.UpsertAsync(x));
+ var upsertedKeys = await Task.WhenAll(upsertedKeysTasks);
+
+ // Retrieve one of the upserted records from the collection.
+ var upsertedRecord = await collection.GetAsync(upsertedKeys.First(), new() { IncludeVectors = true });
+
+ // Write upserted keys and one of the upserted records to the console.
+ Console.WriteLine($"Upserted keys: {string.Join(", ", upsertedKeys)}");
+ Console.WriteLine($"Upserted record: {JsonSerializer.Serialize(upsertedRecord)}");
+ }
+
+ ///
+ /// A custom mapper that maps between the data model and the storage model.
+ ///
+ private sealed class Mapper : IVectorStoreRecordMapper
+ {
+ public (string Key, JsonNode Node) MapFromDataToStorageModel(GenericDataModel dataModel)
+ {
+ var jsonObject = new JsonObject();
+
+ jsonObject.Add("Term", dataModel.Data["Term"].ToString());
+ jsonObject.Add("Definition", dataModel.Data["Definition"].ToString());
+
+ var vector = (ReadOnlyMemory)dataModel.Vectors["DefinitionEmbedding"];
+ var jsonArray = new JsonArray(vector.ToArray().Select(x => JsonValue.Create(x)).ToArray());
+ jsonObject.Add("DefinitionEmbedding", jsonArray);
+
+ return (dataModel.Key, jsonObject);
+ }
+
+ public GenericDataModel MapFromStorageToDataModel((string Key, JsonNode Node) storageModel, StorageToDataModelMapperOptions options)
+ {
+ var dataModel = new GenericDataModel
+ {
+ Key = storageModel.Key,
+ Data = new Dictionary
+ {
+ { "Term", (string)storageModel.Node["Term"]! },
+ { "Definition", (string)storageModel.Node["Definition"]! }
+ },
+ Vectors = new Dictionary
+ {
+ { "DefinitionEmbedding", new ReadOnlyMemory(storageModel.Node["DefinitionEmbedding"]!.AsArray().Select(x => (float)x!).ToArray()) }
+ }
+ };
+
+ return dataModel;
+ }
+ }
+
+ ///
+ /// A factory for creating collections in the vector store
+ ///
+ private sealed class Factory : IRedisVectorStoreRecordCollectionFactory
+ {
+ public IVectorStoreRecordCollection CreateVectorStoreRecordCollection(IDatabase database, string name, VectorStoreRecordDefinition? vectorStoreRecordDefinition)
+ where TKey : notnull
+ where TRecord : class
+ {
+ // If the record definition is the glossary definition and the record type is the generic data model, inject the custom mapper into the collection options.
+ if (vectorStoreRecordDefinition == s_glossaryDefinition && typeof(TRecord) == typeof(GenericDataModel))
+ {
+ var customCollection = new RedisJsonVectorStoreRecordCollection(database, name, new() { VectorStoreRecordDefinition = vectorStoreRecordDefinition, JsonNodeCustomMapper = new Mapper() }) as IVectorStoreRecordCollection;
+ return customCollection!;
+ }
+
+ // Otherwise, just create a standard collection with the default mapper.
+ var collection = new RedisJsonVectorStoreRecordCollection(database, name, new() { VectorStoreRecordDefinition = vectorStoreRecordDefinition }) as IVectorStoreRecordCollection;
+ return collection!;
+ }
+ }
+
+ ///
+ /// Sample generic data model class that can store any data.
+ ///
+ private sealed class GenericDataModel
+ {
+ public string Key { get; set; }
+
+ public Dictionary Data { get; set; }
+
+ public Dictionary Vectors { get; set; }
+ }
+
+ ///
+ /// Create some sample glossary entries using the generic data model.
+ ///
+ /// A list of sample glossary entries.
+ private static IEnumerable CreateGlossaryEntries()
+ {
+ yield return new GenericDataModel
+ {
+ Key = "1",
+ Data = new()
+ {
+ { "Term", "API" },
+ { "Definition", "Application Programming Interface. A set of rules and specifications that allow software components to communicate and exchange data." }
+ },
+ Vectors = new()
+ };
+
+ yield return new GenericDataModel
+ {
+ Key = "2",
+ Data = new()
+ {
+ { "Term", "Connectors" },
+ { "Definition", "Connectors allow you to integrate with various services provide AI capabilities, including LLM, AudioToText, TextToAudio, Embedding generation, etc." }
+ },
+ Vectors = new()
+ };
+
+ yield return new GenericDataModel
+ {
+ Key = "3",
+ Data = new()
+ {
+ { "Term", "RAG" },
+ { "Definition", "Retrieval Augmented Generation - a term that refers to the process of retrieving additional data to provide as context to an LLM to use when generating a response (completion) to a user’s question (prompt)." }
+ },
+ Vectors = new()
+ };
+ }
+}
diff --git a/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_MultiStore.cs b/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_MultiStore.cs
new file mode 100644
index 000000000000..18f0e5b476ca
--- /dev/null
+++ b/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_MultiStore.cs
@@ -0,0 +1,256 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Memory.VectorStoreFixtures;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+using Microsoft.SemanticKernel.Connectors.Qdrant;
+using Microsoft.SemanticKernel.Connectors.Redis;
+using Microsoft.SemanticKernel.Data;
+using Microsoft.SemanticKernel.Embeddings;
+using Qdrant.Client;
+using StackExchange.Redis;
+
+namespace Memory;
+
+///
+/// An example showing how to ingest data into a vector store using , or .
+/// Since Redis and Volatile supports string keys and Qdrant supports ulong or Guid keys, this example also shows how you can have common code
+/// that works with both types of keys by using a generic key generator function.
+///
+/// The example shows the following steps:
+/// 1. Register a vector store and embedding generator with the DI container.
+/// 2. Register a class (DataIngestor) with the DI container that uses the vector store and embedding generator to ingest data.
+/// 3. Ingest some data into the vector store.
+/// 4. Read the data back from the vector store.
+///
+/// For some databases in this sample (Redis & Qdrant), you need a local instance of Docker running, since the associated fixtures will try and start containers in the local docker instance to run against.
+///
+[Collection("Sequential")]
+public class VectorStore_DataIngestion_MultiStore(ITestOutputHelper output, VectorStoreRedisContainerFixture redisFixture, VectorStoreQdrantContainerFixture qdrantFixture) : BaseTest(output), IClassFixture, IClassFixture
+{
+ ///
+ /// Example with dependency injection.
+ ///
+ /// The type of database to run the example for.
+ [Theory]
+ [InlineData("Redis")]
+ [InlineData("Qdrant")]
+ [InlineData("Volatile")]
+ public async Task ExampleWithDIAsync(string databaseType)
+ {
+ // Use the kernel for DI purposes.
+ var kernelBuilder = Kernel
+ .CreateBuilder();
+
+ // Register an embedding generation service with the DI container.
+ kernelBuilder.AddAzureOpenAITextEmbeddingGeneration(
+ deploymentName: TestConfiguration.AzureOpenAIEmbeddings.DeploymentName,
+ endpoint: TestConfiguration.AzureOpenAIEmbeddings.Endpoint,
+ apiKey: TestConfiguration.AzureOpenAIEmbeddings.ApiKey);
+
+ // Register the chosen vector store with the DI container and initialize docker containers via the fixtures where needed.
+ if (databaseType == "Redis")
+ {
+ await redisFixture.ManualInitializeAsync();
+ kernelBuilder.AddRedisVectorStore("localhost:6379");
+ }
+ else if (databaseType == "Qdrant")
+ {
+ await qdrantFixture.ManualInitializeAsync();
+ kernelBuilder.AddQdrantVectorStore("localhost");
+ }
+ else if (databaseType == "Volatile")
+ {
+ kernelBuilder.AddVolatileVectorStore();
+ }
+
+ // Register the DataIngestor with the DI container.
+ kernelBuilder.Services.AddTransient();
+
+ // Build the kernel.
+ var kernel = kernelBuilder.Build();
+
+ // Build a DataIngestor object using the DI container.
+ var dataIngestor = kernel.GetRequiredService();
+
+ // Invoke the data ingestor using an appropriate key generator function for each database type.
+ // Redis and Volatile supports string keys, while Qdrant supports ulong or Guid keys, so we use a different key generator for each key type.
+ if (databaseType == "Redis" || databaseType == "Volatile")
+ {
+ await this.UpsertDataAndReadFromVectorStoreAsync(dataIngestor, () => Guid.NewGuid().ToString());
+ }
+ else if (databaseType == "Qdrant")
+ {
+ await this.UpsertDataAndReadFromVectorStoreAsync(dataIngestor, () => Guid.NewGuid());
+ }
+ }
+
+ ///
+ /// Example without dependency injection.
+ ///
+ /// The type of database to run the example for.
+ [Theory]
+ [InlineData("Redis")]
+ [InlineData("Qdrant")]
+ [InlineData("Volatile")]
+ public async Task ExampleWithoutDIAsync(string databaseType)
+ {
+ // Create an embedding generation service.
+ var textEmbeddingGenerationService = new AzureOpenAITextEmbeddingGenerationService(
+ TestConfiguration.AzureOpenAIEmbeddings.DeploymentName,
+ TestConfiguration.AzureOpenAIEmbeddings.Endpoint,
+ TestConfiguration.AzureOpenAIEmbeddings.ApiKey);
+
+ // Construct the chosen vector store and initialize docker containers via the fixtures where needed.
+ IVectorStore vectorStore;
+ if (databaseType == "Redis")
+ {
+ await redisFixture.ManualInitializeAsync();
+ var database = ConnectionMultiplexer.Connect("localhost:6379").GetDatabase();
+ vectorStore = new RedisVectorStore(database);
+ }
+ else if (databaseType == "Qdrant")
+ {
+ await qdrantFixture.ManualInitializeAsync();
+ var qdrantClient = new QdrantClient("localhost");
+ vectorStore = new QdrantVectorStore(qdrantClient);
+ }
+ else if (databaseType == "Volatile")
+ {
+ vectorStore = new VolatileVectorStore();
+ }
+ else
+ {
+ throw new ArgumentException("Invalid database type.");
+ }
+
+ // Create the DataIngestor.
+ var dataIngestor = new DataIngestor(vectorStore, textEmbeddingGenerationService);
+
+ // Invoke the data ingestor using an appropriate key generator function for each database type.
+ // Redis and Volatile supports string keys, while Qdrant supports ulong or Guid keys, so we use a different key generator for each key type.
+ if (databaseType == "Redis" || databaseType == "Volatile")
+ {
+ await this.UpsertDataAndReadFromVectorStoreAsync(dataIngestor, () => Guid.NewGuid().ToString());
+ }
+ else if (databaseType == "Qdrant")
+ {
+ await this.UpsertDataAndReadFromVectorStoreAsync(dataIngestor, () => Guid.NewGuid());
+ }
+ }
+
+ private async Task UpsertDataAndReadFromVectorStoreAsync(DataIngestor dataIngestor, Func uniqueKeyGenerator)
+ where TKey : notnull
+ {
+ // Ingest some data into the vector store.
+ var upsertedKeys = await dataIngestor.ImportDataAsync(uniqueKeyGenerator);
+
+ // Get one of the upserted records.
+ var upsertedRecord = await dataIngestor.GetGlossaryAsync(upsertedKeys.First());
+
+ // Write upserted keys and one of the upserted records to the console.
+ Console.WriteLine($"Upserted keys: {string.Join(", ", upsertedKeys)}");
+ Console.WriteLine($"Upserted record: {JsonSerializer.Serialize(upsertedRecord)}");
+ }
+
+ ///
+ /// Sample class that does ingestion of sample data into a vector store and allows retrieval of data from the vector store.
+ ///
+ /// The vector store to ingest data into.
+ /// Used to generate embeddings for the data being ingested.
+ private sealed class DataIngestor(IVectorStore vectorStore, ITextEmbeddingGenerationService textEmbeddingGenerationService)
+ {
+ ///
+ /// Create some glossary entries and upsert them into the vector store.
+ ///
+ /// The keys of the upserted glossary entries.
+ /// The type of the keys in the vector store.
+ public async Task> ImportDataAsync(Func uniqueKeyGenerator)
+ where TKey : notnull
+ {
+ // Get and create collection if it doesn't exist.
+ var collection = vectorStore.GetCollection>("skglossary");
+ await collection.CreateCollectionIfNotExistsAsync();
+
+ // Create glossary entries and generate embeddings for them.
+ var glossaryEntries = CreateGlossaryEntries(uniqueKeyGenerator).ToList();
+ var tasks = glossaryEntries.Select(entry => Task.Run(async () =>
+ {
+ entry.DefinitionEmbedding = await textEmbeddingGenerationService.GenerateEmbeddingAsync(entry.Definition);
+ }));
+ await Task.WhenAll(tasks);
+
+ // Upsert the glossary entries into the collection and return their keys.
+ var upsertedKeys = glossaryEntries.Select(x => collection.UpsertAsync(x));
+ return await Task.WhenAll(upsertedKeys);
+ }
+
+ ///
+ /// Get a glossary entry from the vector store.
+ ///
+ /// The key of the glossary entry to retrieve.
+ /// The glossary entry.
+ /// The type of the keys in the vector store.
+ public Task?> GetGlossaryAsync(TKey key)
+ where TKey : notnull
+ {
+ var collection = vectorStore.GetCollection>("skglossary");
+ return collection.GetAsync(key, new() { IncludeVectors = true });
+ }
+ }
+
+ ///
+ /// Create some sample glossary entries.
+ ///
+ /// The type of the model key.
+ /// A function that can be used to generate unique keys for the model in the type that the model requires.
+ /// A list of sample glossary entries.
+ private static IEnumerable> CreateGlossaryEntries(Func uniqueKeyGenerator)
+ {
+ yield return new Glossary
+ {
+ Key = uniqueKeyGenerator(),
+ Term = "API",
+ Definition = "Application Programming Interface. A set of rules and specifications that allow software components to communicate and exchange data."
+ };
+
+ yield return new Glossary
+ {
+ Key = uniqueKeyGenerator(),
+ Term = "Connectors",
+ Definition = "Connectors allow you to integrate with various services provide AI capabilities, including LLM, AudioToText, TextToAudio, Embedding generation, etc."
+ };
+
+ yield return new Glossary
+ {
+ Key = uniqueKeyGenerator(),
+ Term = "RAG",
+ Definition = "Retrieval Augmented Generation - a term that refers to the process of retrieving additional data to provide as context to an LLM to use when generating a response (completion) to a user’s question (prompt)."
+ };
+ }
+
+ ///
+ /// Sample model class that represents a glossary entry.
+ ///
+ ///
+ /// Note that each property is decorated with an attribute that specifies how the property should be treated by the vector store.
+ /// This allows us to create a collection in the vector store and upsert and retrieve instances of this class without any further configuration.
+ ///
+ /// The type of the model key.
+ private sealed class Glossary
+ {
+ [VectorStoreRecordKey]
+ public TKey Key { get; set; }
+
+ [VectorStoreRecordData]
+ public string Term { get; set; }
+
+ [VectorStoreRecordData]
+ public string Definition { get; set; }
+
+ [VectorStoreRecordVector(1536)]
+ public ReadOnlyMemory DefinitionEmbedding { get; set; }
+ }
+}
diff --git a/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_Simple.cs b/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_Simple.cs
new file mode 100644
index 000000000000..341e5c2bbda2
--- /dev/null
+++ b/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_Simple.cs
@@ -0,0 +1,113 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Memory.VectorStoreFixtures;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+using Microsoft.SemanticKernel.Connectors.Qdrant;
+using Microsoft.SemanticKernel.Data;
+using Microsoft.SemanticKernel.Embeddings;
+using Qdrant.Client;
+
+namespace Memory;
+
+///
+/// A simple example showing how to ingest data into a vector store using .
+///
+/// The example shows the following steps:
+/// 1. Create an embedding generator.
+/// 2. Create a Qdrant Vector Store.
+/// 3. Ingest some data into the vector store.
+/// 4. Read the data back from the vector store.
+///
+/// You need a local instance of Docker running, since the associated fixture will try and start a Qdrant container in the local docker instance to run against.
+///
+[Collection("Sequential")]
+public class VectorStore_DataIngestion_Simple(ITestOutputHelper output, VectorStoreQdrantContainerFixture qdrantFixture) : BaseTest(output), IClassFixture
+{
+ [Fact]
+ public async Task ExampleAsync()
+ {
+ // Create an embedding generation service.
+ var textEmbeddingGenerationService = new AzureOpenAITextEmbeddingGenerationService(
+ TestConfiguration.AzureOpenAIEmbeddings.DeploymentName,
+ TestConfiguration.AzureOpenAIEmbeddings.Endpoint,
+ TestConfiguration.AzureOpenAIEmbeddings.ApiKey);
+
+ // Initiate the docker container and construct the vector store.
+ await qdrantFixture.ManualInitializeAsync();
+ var vectorStore = new QdrantVectorStore(new QdrantClient("localhost"));
+
+ // Get and create collection if it doesn't exist.
+ var collection = vectorStore.GetCollection("skglossary");
+ await collection.CreateCollectionIfNotExistsAsync();
+
+ // Create glossary entries and generate embeddings for them.
+ var glossaryEntries = CreateGlossaryEntries().ToList();
+ var tasks = glossaryEntries.Select(entry => Task.Run(async () =>
+ {
+ entry.DefinitionEmbedding = await textEmbeddingGenerationService.GenerateEmbeddingAsync(entry.Definition);
+ }));
+ await Task.WhenAll(tasks);
+
+ // Upsert the glossary entries into the collection and return their keys.
+ var upsertedKeysTasks = glossaryEntries.Select(x => collection.UpsertAsync(x));
+ var upsertedKeys = await Task.WhenAll(upsertedKeysTasks);
+
+ // Retrieve one of the upserted records from the collection.
+ var upsertedRecord = await collection.GetAsync(upsertedKeys.First(), new() { IncludeVectors = true });
+
+ // Write upserted keys and one of the upserted records to the console.
+ Console.WriteLine($"Upserted keys: {string.Join(", ", upsertedKeys)}");
+ Console.WriteLine($"Upserted record: {JsonSerializer.Serialize(upsertedRecord)}");
+ }
+
+ ///
+ /// Sample model class that represents a glossary entry.
+ ///
+ ///
+ /// Note that each property is decorated with an attribute that specifies how the property should be treated by the vector store.
+ /// This allows us to create a collection in the vector store and upsert and retrieve instances of this class without any further configuration.
+ ///
+ private sealed class Glossary
+ {
+ [VectorStoreRecordKey]
+ public ulong Key { get; set; }
+
+ [VectorStoreRecordData]
+ public string Term { get; set; }
+
+ [VectorStoreRecordData]
+ public string Definition { get; set; }
+
+ [VectorStoreRecordVector(1536)]
+ public ReadOnlyMemory DefinitionEmbedding { get; set; }
+ }
+
+ ///
+ /// Create some sample glossary entries.
+ ///
+ /// A list of sample glossary entries.
+ private static IEnumerable CreateGlossaryEntries()
+ {
+ yield return new Glossary
+ {
+ Key = 1,
+ Term = "API",
+ Definition = "Application Programming Interface. A set of rules and specifications that allow software components to communicate and exchange data."
+ };
+
+ yield return new Glossary
+ {
+ Key = 2,
+ Term = "Connectors",
+ Definition = "Connectors allow you to integrate with various services provide AI capabilities, including LLM, AudioToText, TextToAudio, Embedding generation, etc."
+ };
+
+ yield return new Glossary
+ {
+ Key = 3,
+ Term = "RAG",
+ Definition = "Retrieval Augmented Generation - a term that refers to the process of retrieving additional data to provide as context to an LLM to use when generating a response (completion) to a user’s question (prompt)."
+ };
+ }
+}
diff --git a/dotnet/samples/Concepts/Plugins/OpenApiPlugin_CustomHttpContentReader.cs b/dotnet/samples/Concepts/Plugins/OpenApiPlugin_CustomHttpContentReader.cs
new file mode 100644
index 000000000000..829e5a42abb3
--- /dev/null
+++ b/dotnet/samples/Concepts/Plugins/OpenApiPlugin_CustomHttpContentReader.cs
@@ -0,0 +1,101 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Plugins.OpenApi;
+
+namespace Plugins;
+
+///
+/// Sample shows how to register a custom HTTP content reader for an Open API plugin.
+///
+public sealed class CustomHttpContentReaderForOpenApiPlugin(ITestOutputHelper output) : BaseTest(output)
+{
+ [Fact]
+ public async Task ShowReadingJsonAsStreamAsync()
+ {
+ var kernel = new Kernel();
+
+ // Register the custom HTTP content reader
+ var executionParameters = new OpenApiFunctionExecutionParameters() { HttpResponseContentReader = ReadHttpResponseContentAsync };
+
+ // Create OpenAPI plugin
+ var plugin = await OpenApiKernelPluginFactory.CreateFromOpenApiAsync("RepairService", "Resources/Plugins/RepairServicePlugin/repair-service.json", executionParameters);
+
+ // Create a repair so it can be read as a stream in the following step
+ var arguments = new KernelArguments
+ {
+ ["title"] = "The Case of the Broken Gizmo",
+ ["description"] = "It's broken. Send help!",
+ ["assignedTo"] = "Tech Magician"
+ };
+ var createResult = await plugin["createRepair"].InvokeAsync(kernel, arguments);
+ Console.WriteLine(createResult.ToString());
+
+ // List relevant repairs
+ arguments = new KernelArguments
+ {
+ ["assignedTo"] = "Tech Magician"
+ };
+ var listResult = await plugin["listRepairs"].InvokeAsync(kernel, arguments);
+ using var reader = new StreamReader((Stream)listResult.GetValue()!.Content!);
+ var content = await reader.ReadToEndAsync();
+ var repairs = JsonSerializer.Deserialize(content);
+ Console.WriteLine(content);
+
+ // Delete the repair
+ arguments = new KernelArguments
+ {
+ ["id"] = repairs!.Where(r => r.AssignedTo == "Tech Magician").First().Id.ToString()
+ };
+ var deleteResult = await plugin["deleteRepair"].InvokeAsync(kernel, arguments);
+ Console.WriteLine(deleteResult.ToString());
+ }
+
+ ///
+ /// A custom HTTP content reader to change the default behavior of reading HTTP content.
+ ///
+ /// The HTTP response content reader context.
+ /// The cancellation token.
+ /// The HTTP response content.
+ private static async Task ReadHttpResponseContentAsync(HttpResponseContentReaderContext context, CancellationToken cancellationToken)
+ {
+ // Read JSON content as a stream rather than as a string, which is the default behavior
+ if (context.Response.Content.Headers.ContentType?.MediaType == "application/json")
+ {
+ return await context.Response.Content.ReadAsStreamAsync(cancellationToken);
+ }
+
+ // HTTP request and response properties can be used to decide how to read the content.
+ // The 'if' operator below is not relevant to the current example and is just for demonstration purposes.
+ if (context.Request.Headers.Contains("x-stream"))
+ {
+ return await context.Response.Content.ReadAsStreamAsync(cancellationToken);
+ }
+
+ // Return null to indicate that any other HTTP content not handled above should be read by the default reader.
+ return null;
+ }
+
+ private sealed class Repair
+ {
+ [JsonPropertyName("id")]
+ public int? Id { get; set; }
+
+ [JsonPropertyName("title")]
+ public string? Title { get; set; }
+
+ [JsonPropertyName("description")]
+ public string? Description { get; set; }
+
+ [JsonPropertyName("assignedTo")]
+ public string? AssignedTo { get; set; }
+
+ [JsonPropertyName("date")]
+ public string? Date { get; set; }
+
+ [JsonPropertyName("image")]
+ public string? Image { get; set; }
+ }
+}
diff --git a/dotnet/samples/Concepts/README.md b/dotnet/samples/Concepts/README.md
index 77427c605193..26eef28982a7 100644
--- a/dotnet/samples/Concepts/README.md
+++ b/dotnet/samples/Concepts/README.md
@@ -104,6 +104,9 @@ Down below you can find the code snippets that demonstrate the usage of many Sem
- [TextMemoryPlugin_GeminiEmbeddingGeneration](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Memory/TextMemoryPlugin_GeminiEmbeddingGeneration.cs)
- [TextMemoryPlugin_MultipleMemoryStore](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Memory/TextMemoryPlugin_MultipleMemoryStore.cs)
- [TextMemoryPlugin_RecallJsonSerializationWithOptions](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Memory/TextMemoryPlugin_RecallJsonSerializationWithOptions.cs)
+- [VectorStore_DataIngestion_Simple: A simple example of how to do data ingestion into a vector store when getting started.](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_Simple.cs)
+- [VectorStore_DataIngestion_MultiStore: An example of data ingestion that uses the same code to ingest into multiple vector stores types.](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_MultiStore.cs)
+- [VectorStore_DataIngestion_CustomMapper: An example that shows how to use a custom mapper for when your data model and storage model doesn't match.](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Memory/VectorStore_DataIngestion_CustomMapper.cs)
## Optimization - Examples of different cost and performance optimization techniques
diff --git a/dotnet/samples/Demos/AIModelRouter/AIModelRouter.csproj b/dotnet/samples/Demos/AIModelRouter/AIModelRouter.csproj
new file mode 100644
index 000000000000..fb5862e3270a
--- /dev/null
+++ b/dotnet/samples/Demos/AIModelRouter/AIModelRouter.csproj
@@ -0,0 +1,20 @@
+
+
+
+ Exe
+ net8.0;netstandard2.0
+ enable
+ enable
+ 5ee045b0-aea3-4f08-8d31-32d1a6f8fed0
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/dotnet/samples/Demos/AIModelRouter/CustomRouter.cs b/dotnet/samples/Demos/AIModelRouter/CustomRouter.cs
new file mode 100644
index 000000000000..ff2767a289c8
--- /dev/null
+++ b/dotnet/samples/Demos/AIModelRouter/CustomRouter.cs
@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+#pragma warning disable SKEXP0001
+#pragma warning disable SKEXP0010
+#pragma warning disable CA2249 // Consider using 'string.Contains' instead of 'string.IndexOf'
+
+namespace AIModelRouter;
+
+///
+/// This class is for demonstration purposes only.
+/// In a real-world scenario, you would use a more sophisticated routing mechanism, such as another local model for
+/// deciding which service to use based on the user's input or any other criteria.
+///
+public class CustomRouter()
+{
+ ///
+ /// Returns the best service id to use based on the user's input.
+ /// This demonstration uses a simple logic where your input is checked for specific keywords as a deciding factor,
+ /// if no keyword is found it defaults to the first service in the list.
+ ///
+ /// User's input prompt
+ /// List of service ids to choose from in order of importance, defaulting to the first
+ /// Service id.
+ public string FindService(string lookupPrompt, IReadOnlyList serviceIds)
+ {
+ // The order matters, if the keyword is not found, the first one is used.
+ foreach (var serviceId in serviceIds)
+ {
+ if (Contains(lookupPrompt, serviceId)) { return serviceId; }
+ }
+
+ return serviceIds[0];
+ }
+
+ // Ensure compatibility with both netstandard2.0 and net8.0 by using IndexOf instead of Contains
+ private static bool Contains(string prompt, string pattern)
+ => prompt.IndexOf(pattern, StringComparison.CurrentCultureIgnoreCase) >= 0;
+}
diff --git a/dotnet/samples/Demos/AIModelRouter/Program.cs b/dotnet/samples/Demos/AIModelRouter/Program.cs
new file mode 100644
index 000000000000..5bafa4934883
--- /dev/null
+++ b/dotnet/samples/Demos/AIModelRouter/Program.cs
@@ -0,0 +1,56 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.SemanticKernel;
+
+#pragma warning disable SKEXP0001
+#pragma warning disable SKEXP0010
+#pragma warning disable CA2249 // Consider using 'string.Contains' instead of 'string.IndexOf'
+
+namespace AIModelRouter;
+
+internal sealed partial class Program
+{
+ private static async Task Main(string[] args)
+ {
+ Console.ForegroundColor = ConsoleColor.White;
+
+ var config = new ConfigurationBuilder().AddUserSecrets().Build();
+
+ ServiceCollection services = new();
+
+ // Adding multiple connectors targeting different providers / models.
+ services.AddKernel() /* LMStudio model is selected in server side. */
+ .AddOpenAIChatCompletion(serviceId: "lmstudio", modelId: "N/A", endpoint: new Uri("http://localhost:1234"), apiKey: null)
+ .AddOpenAIChatCompletion(serviceId: "ollama", modelId: "phi3", endpoint: new Uri("http://localhost:11434"), apiKey: null)
+ .AddOpenAIChatCompletion(serviceId: "openai", modelId: "gpt-4o", apiKey: config["OpenAI:ApiKey"]!)
+
+ // Adding a custom filter to capture router selected service id
+ .Services.AddSingleton(new SelectedServiceFilter());
+
+ var kernel = services.BuildServiceProvider().GetRequiredService();
+ var router = new CustomRouter();
+
+ while (true)
+ {
+ Console.Write("\n\nUser > ");
+ var userMessage = Console.ReadLine();
+
+ // Exit application if the user enters an empty message
+ if (string.IsNullOrWhiteSpace(userMessage)) { return; }
+
+ // Find the best service to use based on the user's input
+ KernelArguments arguments = new(new PromptExecutionSettings()
+ {
+ ServiceId = router.FindService(userMessage, ["lmstudio", "ollama", "openai"])
+ });
+
+ // Invoke the prompt and print the response
+ await foreach (var chatChunk in kernel.InvokePromptStreamingAsync(userMessage, arguments).ConfigureAwait(false))
+ {
+ Console.Write(chatChunk);
+ }
+ }
+ }
+}
diff --git a/dotnet/samples/Demos/AIModelRouter/README.md b/dotnet/samples/Demos/AIModelRouter/README.md
new file mode 100644
index 000000000000..92ac37e7c81e
--- /dev/null
+++ b/dotnet/samples/Demos/AIModelRouter/README.md
@@ -0,0 +1,51 @@
+# AI Model Router
+
+This sample demonstrates how to implement an AI Model Router using Semantic Kernel connectors to direct requests to various AI models based on user input. As part of this example we integrate LMStudio, Ollama, and OpenAI, utilizing the OpenAI Connector for LMStudio and Ollama due to their compatibility with the OpenAI API.
+
+> [!IMPORTANT]
+> You can modify to use any other combination of connector or OpenAI compatible API model provider.
+
+## Semantic Kernel Features Used
+
+- [Chat Completion Service](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/src/SemanticKernel.Abstractions/AI/ChatCompletion/IChatCompletionService.cs) - Using the Chat Completion Service [OpenAI Connector implementation](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/src/Connectors/Connectors.OpenAI/ChatCompletion/OpenAIChatCompletionService.cs) to generate responses from the LLM.
+- [Filters](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/src/SemanticKernel.Abstractions/AI/ChatCompletion/IChatCompletionService.cs), using to capture selected service and log in the console.
+
+## Prerequisites
+
+- [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0).
+
+## Configuring the sample
+
+The sample can be configured by using the command line with .NET [Secret Manager](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) to avoid the risk of leaking secrets into the repository, branches and pull requests.
+
+### Using .NET [Secret Manager](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets)
+
+```powershell
+# OpenAI (Not required if using Azure OpenAI)
+dotnet user-secrets set "OpenAI:ApiKey" "... your api key ... "
+```
+
+## Running the sample
+
+After configuring the sample, to build and run the console application just hit `F5`.
+
+To build and run the console application from the terminal use the following commands:
+
+```powershell
+dotnet build
+dotnet run
+```
+
+### Example of a conversation
+
+> **User** > OpenAI, what is Jupiter? Keep it simple.
+
+> **Assistant** > Sure! Jupiter is the largest planet in our solar system. It's a gas giant, mostly made of hydrogen and helium, and it has a lot of storms, including the famous Great Red Spot. Jupiter also has at least 79 moons.
+
+> **User** > Ollama, what is Jupiter? Keep it simple.
+
+> **Assistant** > Jupiter is a giant planet in our solar system known for being the largest and most massive, famous for its spectacled clouds and dozens of moons including Ganymede which is bigger than Earth!
+
+> **User** > LMStudio, what is Jupiter? Keep it simple.
+
+> **Assistant** > Jupiter is the fifth planet from the Sun in our Solar System and one of its gas giants alongside Saturn, Uranus, and Neptune. It's famous for having a massive storm called the Great Red Spot that has been raging for hundreds of years.
\ No newline at end of file
diff --git a/dotnet/samples/Demos/AIModelRouter/SelectedServiceFilter.cs b/dotnet/samples/Demos/AIModelRouter/SelectedServiceFilter.cs
new file mode 100644
index 000000000000..9824d57ebd55
--- /dev/null
+++ b/dotnet/samples/Demos/AIModelRouter/SelectedServiceFilter.cs
@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel;
+
+#pragma warning disable SKEXP0001
+#pragma warning disable SKEXP0010
+#pragma warning disable CA2249 // Consider using 'string.Contains' instead of 'string.IndexOf'
+
+namespace AIModelRouter;
+
+///
+/// Using a filter to log the service being used for the prompt.
+///
+public class SelectedServiceFilter : IPromptRenderFilter
+{
+ ///
+ public Task OnPromptRenderAsync(PromptRenderContext context, Func next)
+ {
+ Console.ForegroundColor = ConsoleColor.Yellow;
+ Console.WriteLine($"Selected service id: '{context.Arguments.ExecutionSettings?.FirstOrDefault().Key}'");
+
+ Console.ForegroundColor = ConsoleColor.White;
+ Console.Write("Assistant > ");
+ return next(context);
+ }
+}
diff --git a/dotnet/samples/GettingStartedWithAgents/Step2_Plugins.cs b/dotnet/samples/GettingStartedWithAgents/Step2_Plugins.cs
index 38741bbb2e7c..7946adc7f687 100644
--- a/dotnet/samples/GettingStartedWithAgents/Step2_Plugins.cs
+++ b/dotnet/samples/GettingStartedWithAgents/Step2_Plugins.cs
@@ -26,7 +26,7 @@ public async Task UseChatCompletionWithPluginAgentAsync()
Instructions = HostInstructions,
Name = HostName,
Kernel = this.CreateKernelWithChatCompletion(),
- ExecutionSettings = new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions },
+ Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions }),
};
// Initialize plugin and add to the agent's Kernel (same as direct Kernel usage).
diff --git a/dotnet/samples/GettingStartedWithAgents/Step4_KernelFunctionStrategies.cs b/dotnet/samples/GettingStartedWithAgents/Step4_KernelFunctionStrategies.cs
index 9cabe0193d3e..d71b6ae26767 100644
--- a/dotnet/samples/GettingStartedWithAgents/Step4_KernelFunctionStrategies.cs
+++ b/dotnet/samples/GettingStartedWithAgents/Step4_KernelFunctionStrategies.cs
@@ -72,7 +72,6 @@ State only the name of the participant to take the next turn.
- {{{CopyWriterName}}}
Always follow these rules when selecting the next participant:
- - After user input, it is {{{CopyWriterName}}}'a turn.
- After {{{CopyWriterName}}} replies, it is {{{ReviewerName}}}'s turn.
- After {{{ReviewerName}}} provides feedback, it is {{{CopyWriterName}}}'s turn.
@@ -105,6 +104,8 @@ State only the name of the participant to take the next turn.
SelectionStrategy =
new KernelFunctionSelectionStrategy(selectionFunction, CreateKernelWithChatCompletion())
{
+ // Always start with the writer agent.
+ InitialAgent = agentWriter,
// Returns the entire result value as a string.
ResultParser = (result) => result.GetValue() ?? CopyWriterName,
// The prompt variable name for the agents argument.
diff --git a/dotnet/src/Agents/Abstractions/AgentChannel.cs b/dotnet/src/Agents/Abstractions/AgentChannel.cs
index 9788464a2adb..34f7a8030896 100644
--- a/dotnet/src/Agents/Abstractions/AgentChannel.cs
+++ b/dotnet/src/Agents/Abstractions/AgentChannel.cs
@@ -25,6 +25,15 @@ public abstract class AgentChannel
/// The to monitor for cancellation requests. The default is .
protected internal abstract Task ReceiveAsync(IEnumerable history, CancellationToken cancellationToken = default);
+ ///
+ /// Reset any persistent state associated with the channel.
+ ///
+ /// The to monitor for cancellation requests. The default is .
+ ///
+ /// The channel wont' be reused; rather, it will be discarded and a new one created.
+ ///
+ protected internal abstract Task ResetAsync(CancellationToken cancellationToken = default);
+
///
/// Perform a discrete incremental interaction between a single and .
///
diff --git a/dotnet/src/Agents/Abstractions/AgentChat.cs b/dotnet/src/Agents/Abstractions/AgentChat.cs
index f4654963444e..cdc46024ece7 100644
--- a/dotnet/src/Agents/Abstractions/AgentChat.cs
+++ b/dotnet/src/Agents/Abstractions/AgentChat.cs
@@ -266,6 +266,29 @@ async Task GetOrCreateChannelAsync()
}
}
+ ///
+ /// Reset the chat, clearing all history and persisted state.
+ /// All agents will remain present.
+ ///
+ /// The to monitor for cancellation requests. The default is .
+ public async Task ResetAsync(CancellationToken cancellationToken = default)
+ {
+ this.SetActivityOrThrow(); // Disallow concurrent access to chat
+
+ try
+ {
+ Task[] resetTasks = this._agentChannels.Values.Select(c => c.ResetAsync(cancellationToken)).ToArray();
+ await Task.WhenAll(resetTasks).ConfigureAwait(false);
+ this._agentChannels.Clear();
+ this._channelMap.Clear();
+ this.History.Clear();
+ }
+ finally
+ {
+ this.ClearActivitySignal();
+ }
+ }
+
///
/// Clear activity signal to indicate that activity has ceased.
///
diff --git a/dotnet/src/Agents/Abstractions/AggregatorChannel.cs b/dotnet/src/Agents/Abstractions/AggregatorChannel.cs
index 73561a4eba8b..c7123abf9b71 100644
--- a/dotnet/src/Agents/Abstractions/AggregatorChannel.cs
+++ b/dotnet/src/Agents/Abstractions/AggregatorChannel.cs
@@ -47,6 +47,7 @@ protected internal override IAsyncEnumerable GetHistoryAsync
}
}
+ ///
protected internal override Task ReceiveAsync(IEnumerable history, CancellationToken cancellationToken = default)
{
// Always receive the initial history from the owning chat.
@@ -54,4 +55,8 @@ protected internal override Task ReceiveAsync(IEnumerable hi
return Task.CompletedTask;
}
+
+ ///
+ protected internal override Task ResetAsync(CancellationToken cancellationToken = default) =>
+ this._chat.ResetAsync(cancellationToken);
}
diff --git a/dotnet/src/Agents/Abstractions/ChatHistoryKernelAgent.cs b/dotnet/src/Agents/Abstractions/ChatHistoryKernelAgent.cs
deleted file mode 100644
index 3de87da3de06..000000000000
--- a/dotnet/src/Agents/Abstractions/ChatHistoryKernelAgent.cs
+++ /dev/null
@@ -1,42 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-using System.Collections.Generic;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Extensions.Logging;
-using Microsoft.SemanticKernel.ChatCompletion;
-
-namespace Microsoft.SemanticKernel.Agents;
-
-///
-/// A specialization bound to a .
-///
-public abstract class ChatHistoryKernelAgent : KernelAgent, IChatHistoryHandler
-{
- ///
- protected internal sealed override IEnumerable GetChannelKeys()
- {
- yield return typeof(ChatHistoryChannel).FullName!;
- }
-
- ///
- protected internal sealed override Task CreateChannelAsync(CancellationToken cancellationToken)
- {
- ChatHistoryChannel channel =
- new()
- {
- Logger = this.LoggerFactory.CreateLogger()
- };
-
- return Task.FromResult(channel);
- }
-
- ///
- public abstract IAsyncEnumerable InvokeAsync(
- ChatHistory history,
- CancellationToken cancellationToken = default);
-
- ///
- public abstract IAsyncEnumerable InvokeStreamingAsync(
- ChatHistory history,
- CancellationToken cancellationToken = default);
-}
diff --git a/dotnet/src/Agents/Abstractions/Extensions/ChatHistoryExtensions.cs b/dotnet/src/Agents/Abstractions/Extensions/ChatHistoryExtensions.cs
index a7b2273ece9e..d8ef44a416a1 100644
--- a/dotnet/src/Agents/Abstractions/Extensions/ChatHistoryExtensions.cs
+++ b/dotnet/src/Agents/Abstractions/Extensions/ChatHistoryExtensions.cs
@@ -8,7 +8,7 @@ namespace Microsoft.SemanticKernel.Agents.Extensions;
///
/// Extension methods for
///
-internal static class ChatHistoryExtensions
+public static class ChatHistoryExtensions
{
///
/// Enumeration of chat-history in descending order.
diff --git a/dotnet/src/Agents/Abstractions/IChatHistoryHandler.cs b/dotnet/src/Agents/Abstractions/IChatHistoryHandler.cs
deleted file mode 100644
index 8b7dab748c81..000000000000
--- a/dotnet/src/Agents/Abstractions/IChatHistoryHandler.cs
+++ /dev/null
@@ -1,32 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-using System.Collections.Generic;
-using System.Threading;
-using Microsoft.SemanticKernel.ChatCompletion;
-
-namespace Microsoft.SemanticKernel.Agents;
-
-///
-/// Contract for an agent that utilizes a .
-///
-public interface IChatHistoryHandler
-{
- ///
- /// Entry point for calling into an agent from a .
- ///
- /// The chat history at the point the channel is created.
- /// The to monitor for cancellation requests. The default is .
- /// Asynchronous enumeration of messages.
- IAsyncEnumerable InvokeAsync(
- ChatHistory history,
- CancellationToken cancellationToken = default);
-
- ///
- /// Entry point for calling into an agent from a for streaming content.
- ///
- /// The chat history at the point the channel is created.
- /// The to monitor for cancellation requests. The default is .
- /// Asynchronous enumeration of streaming content.
- public abstract IAsyncEnumerable InvokeStreamingAsync(
- ChatHistory history,
- CancellationToken cancellationToken = default);
-}
diff --git a/dotnet/src/Agents/Abstractions/KernelAgent.cs b/dotnet/src/Agents/Abstractions/KernelAgent.cs
index 061705670a2a..1df425972495 100644
--- a/dotnet/src/Agents/Abstractions/KernelAgent.cs
+++ b/dotnet/src/Agents/Abstractions/KernelAgent.cs
@@ -17,5 +17,5 @@ public abstract class KernelAgent : Agent
///
/// Defaults to empty Kernel, but may be overridden.
///
- public Kernel Kernel { get; init; } = new Kernel();
+ public Kernel Kernel { get; init; } = new();
}
diff --git a/dotnet/src/Agents/Core/AgentGroupChat.cs b/dotnet/src/Agents/Core/AgentGroupChat.cs
index 928326745b97..bff8f90f34b3 100644
--- a/dotnet/src/Agents/Core/AgentGroupChat.cs
+++ b/dotnet/src/Agents/Core/AgentGroupChat.cs
@@ -8,7 +8,6 @@
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.SemanticKernel.Agents.Chat;
-using Microsoft.SemanticKernel.ChatCompletion;
namespace Microsoft.SemanticKernel.Agents;
@@ -53,7 +52,7 @@ public void AddAgent(Agent agent)
/// The interactions will proceed according to the and the
/// defined via .
/// In the absence of an , this method will not invoke any agents.
- /// Any agent may be explicitly selected by calling .
+ /// Any agent may be explicitly selected by calling .
///
/// The to monitor for cancellation requests. The default is .
/// Asynchronous enumeration of messages.
@@ -77,30 +76,11 @@ public override async IAsyncEnumerable InvokeAsync([Enumerat
for (int index = 0; index < this.ExecutionSettings.TerminationStrategy.MaximumIterations; index++)
{
// Identify next agent using strategy
- this.Logger.LogAgentGroupChatSelectingAgent(nameof(InvokeAsync), this.ExecutionSettings.SelectionStrategy.GetType());
-
- Agent agent;
- try
- {
- agent = await this.ExecutionSettings.SelectionStrategy.NextAsync(this.Agents, this.History, cancellationToken).ConfigureAwait(false);
- }
- catch (Exception exception)
- {
- this.Logger.LogAgentGroupChatNoAgentSelected(nameof(InvokeAsync), exception);
- throw;
- }
-
- this.Logger.LogAgentGroupChatSelectedAgent(nameof(InvokeAsync), agent.GetType(), agent.Id, this.ExecutionSettings.SelectionStrategy.GetType());
+ Agent agent = await this.SelectAgentAsync(cancellationToken).ConfigureAwait(false);
// Invoke agent and process messages along with termination
- await foreach (var message in base.InvokeAgentAsync(agent, cancellationToken).ConfigureAwait(false))
+ await foreach (var message in this.InvokeAsync(agent, cancellationToken).ConfigureAwait(false))
{
- if (message.Role == AuthorRole.Assistant)
- {
- var task = this.ExecutionSettings.TerminationStrategy.ShouldTerminateAsync(agent, this.History, cancellationToken);
- this.IsComplete = await task.ConfigureAwait(false);
- }
-
yield return message;
}
@@ -122,45 +102,23 @@ public override async IAsyncEnumerable InvokeAsync([Enumerat
///
/// Specified agent joins the chat.
/// >
- public IAsyncEnumerable InvokeAsync(
- Agent agent,
- CancellationToken cancellationToken = default) =>
- this.InvokeAsync(agent, isJoining: true, cancellationToken);
-
- ///
- /// Process a single interaction between a given an a irregardless of
- /// the defined via . Likewise, this does
- /// not regard as it only takes a single turn for the specified agent.
- ///
- /// The agent actively interacting with the chat.
- /// Optional flag to control if agent is joining the chat.
- /// The to monitor for cancellation requests. The default is .
- /// Asynchronous enumeration of messages.
public async IAsyncEnumerable InvokeAsync(
Agent agent,
- bool isJoining,
[EnumeratorCancellation] CancellationToken cancellationToken = default)
{
this.EnsureStrategyLoggerAssignment();
this.Logger.LogAgentGroupChatInvokingAgent(nameof(InvokeAsync), agent.GetType(), agent.Id);
- if (isJoining)
- {
- this.AddAgent(agent);
- }
+ this.AddAgent(agent);
await foreach (var message in base.InvokeAgentAsync(agent, cancellationToken).ConfigureAwait(false))
{
- if (message.Role == AuthorRole.Assistant)
- {
- var task = this.ExecutionSettings.TerminationStrategy.ShouldTerminateAsync(agent, this.History, cancellationToken);
- this.IsComplete = await task.ConfigureAwait(false);
- }
-
yield return message;
}
+ this.IsComplete = await this.ExecutionSettings.TerminationStrategy.ShouldTerminateAsync(agent, this.History, cancellationToken).ConfigureAwait(false);
+
this.Logger.LogAgentGroupChatYield(nameof(InvokeAsync), this.IsComplete);
}
@@ -187,4 +145,25 @@ private void EnsureStrategyLoggerAssignment()
this.ExecutionSettings.TerminationStrategy.Logger = this.LoggerFactory.CreateLogger(this.ExecutionSettings.TerminationStrategy.GetType());
}
}
+
+ private async Task SelectAgentAsync(CancellationToken cancellationToken)
+ {
+ this.Logger.LogAgentGroupChatSelectingAgent(nameof(InvokeAsync), this.ExecutionSettings.SelectionStrategy.GetType());
+
+ Agent agent;
+
+ try
+ {
+ agent = await this.ExecutionSettings.SelectionStrategy.NextAsync(this.Agents, this.History, cancellationToken).ConfigureAwait(false);
+ }
+ catch (Exception exception)
+ {
+ this.Logger.LogAgentGroupChatNoAgentSelected(nameof(InvokeAsync), exception);
+ throw;
+ }
+
+ this.Logger.LogAgentGroupChatSelectedAgent(nameof(InvokeAsync), agent.GetType(), agent.Id, this.ExecutionSettings.SelectionStrategy.GetType());
+
+ return agent;
+ }
}
diff --git a/dotnet/src/Agents/Core/Chat/KernelFunctionSelectionStrategy.cs b/dotnet/src/Agents/Core/Chat/KernelFunctionSelectionStrategy.cs
index d912ed147eb6..00ea8c1e2965 100644
--- a/dotnet/src/Agents/Core/Chat/KernelFunctionSelectionStrategy.cs
+++ b/dotnet/src/Agents/Core/Chat/KernelFunctionSelectionStrategy.cs
@@ -47,6 +47,11 @@ public class KernelFunctionSelectionStrategy(KernelFunction function, Kernel ker
///
public KernelFunction Function { get; } = function;
+ ///
+ /// When set, will use in the event of a failure to select an agent.
+ ///
+ public bool UseInitialAgentAsFallback { get; init; }
+
///
/// The used when invoking .
///
@@ -59,7 +64,7 @@ public class KernelFunctionSelectionStrategy(KernelFunction function, Kernel ker
public Func ResultParser { get; init; } = (result) => result.GetValue() ?? string.Empty;
///
- public sealed override async Task NextAsync(IReadOnlyList agents, IReadOnlyList history, CancellationToken cancellationToken = default)
+ protected sealed override async Task SelectAgentAsync(IReadOnlyList agents, IReadOnlyList history, CancellationToken cancellationToken = default)
{
KernelArguments originalArguments = this.Arguments ?? [];
KernelArguments arguments =
@@ -76,13 +81,17 @@ public sealed override async Task NextAsync(IReadOnlyList agents,
this.Logger.LogKernelFunctionSelectionStrategyInvokedFunction(nameof(NextAsync), this.Function.PluginName, this.Function.Name, result.ValueType);
string? agentName = this.ResultParser.Invoke(result);
- if (string.IsNullOrEmpty(agentName))
+ if (string.IsNullOrEmpty(agentName) && (!this.UseInitialAgentAsFallback || this.InitialAgent == null))
{
throw new KernelException("Agent Failure - Strategy unable to determine next agent.");
}
- return
- agents.FirstOrDefault(a => (a.Name ?? a.Id) == agentName) ??
- throw new KernelException($"Agent Failure - Strategy unable to select next agent: {agentName}");
+ Agent? agent = agents.FirstOrDefault(a => (a.Name ?? a.Id) == agentName);
+ if (agent == null && this.UseInitialAgentAsFallback)
+ {
+ agent = this.InitialAgent;
+ }
+
+ return agent ?? throw new KernelException($"Agent Failure - Strategy unable to select next agent: {agentName}");
}
}
diff --git a/dotnet/src/Agents/Core/Chat/SelectionStrategy.cs b/dotnet/src/Agents/Core/Chat/SelectionStrategy.cs
index 5aa58b99e194..1ba5fb502649 100644
--- a/dotnet/src/Agents/Core/Chat/SelectionStrategy.cs
+++ b/dotnet/src/Agents/Core/Chat/SelectionStrategy.cs
@@ -12,6 +12,19 @@ namespace Microsoft.SemanticKernel.Agents.Chat;
///
public abstract class SelectionStrategy
{
+ ///
+ /// Flag indicating if an agent has been selected (first time).
+ ///
+ protected bool HasSelected { get; private set; }
+
+ ///
+ /// An optional agent for initial selection.
+ ///
+ ///
+ /// Useful to avoid latency in initial agent selection.
+ ///
+ public Agent? InitialAgent { get; set; }
+
///
/// The associated with the .
///
@@ -24,5 +37,29 @@ public abstract class SelectionStrategy
/// The chat history.
/// The to monitor for cancellation requests. The default is .
/// The agent who shall take the next turn.
- public abstract Task NextAsync(IReadOnlyList agents, IReadOnlyList history, CancellationToken cancellationToken = default);
+ public async Task NextAsync(IReadOnlyList agents, IReadOnlyList history, CancellationToken cancellationToken = default)
+ {
+ if (agents.Count == 0 && this.InitialAgent == null)
+ {
+ throw new KernelException("Agent Failure - No agents present to select.");
+ }
+
+ Agent agent =
+ (!this.HasSelected && this.InitialAgent != null) ?
+ this.InitialAgent :
+ await this.SelectAgentAsync(agents, history, cancellationToken).ConfigureAwait(false);
+
+ this.HasSelected = true;
+
+ return agent;
+ }
+
+ ///
+ /// Determine which agent goes next.
+ ///
+ /// The agents participating in chat.
+ /// The chat history.
+ /// The to monitor for cancellation requests. The default is .
+ /// The agent who shall take the next turn.
+ protected abstract Task SelectAgentAsync(IReadOnlyList agents, IReadOnlyList history, CancellationToken cancellationToken = default);
}
diff --git a/dotnet/src/Agents/Core/Chat/SequentialSelectionStrategy.cs b/dotnet/src/Agents/Core/Chat/SequentialSelectionStrategy.cs
index 878cd7530eed..4707a5724f28 100644
--- a/dotnet/src/Agents/Core/Chat/SequentialSelectionStrategy.cs
+++ b/dotnet/src/Agents/Core/Chat/SequentialSelectionStrategy.cs
@@ -20,11 +20,15 @@ public sealed class SequentialSelectionStrategy : SelectionStrategy
public void Reset() => this._index = 0;
///
- public override Task NextAsync(IReadOnlyList agents, IReadOnlyList history, CancellationToken cancellationToken = default)
+ protected override Task SelectAgentAsync(IReadOnlyList agents, IReadOnlyList history, CancellationToken cancellationToken = default)
{
- if (agents.Count == 0)
+ if (this.HasSelected &&
+ this.InitialAgent != null &&
+ agents.Count > 0 &&
+ agents[0] == this.InitialAgent)
{
- throw new KernelException("Agent Failure - No agents present to select.");
+ // Avoid selecting first agent twice
+ IncrementIndex();
}
// Set of agents array may not align with previous execution, constrain index to valid range.
@@ -33,12 +37,17 @@ public override Task NextAsync(IReadOnlyList agents, IReadOnlyList
this._index = 0;
}
- var agent = agents[this._index];
+ Agent agent = agents[this._index];
this.Logger.LogSequentialSelectionStrategySelectedAgent(nameof(NextAsync), this._index, agents.Count, agent.Id);
- this._index = (this._index + 1) % agents.Count;
+ IncrementIndex();
return Task.FromResult(agent);
+
+ void IncrementIndex()
+ {
+ this._index = (this._index + 1) % agents.Count;
+ }
}
}
diff --git a/dotnet/src/Agents/Core/ChatCompletionAgent.cs b/dotnet/src/Agents/Core/ChatCompletionAgent.cs
index 1e9ea3d3208e..212c56038484 100644
--- a/dotnet/src/Agents/Core/ChatCompletionAgent.cs
+++ b/dotnet/src/Agents/Core/ChatCompletionAgent.cs
@@ -4,6 +4,7 @@
using System.Threading;
using System.Threading.Tasks;
using Microsoft.SemanticKernel.ChatCompletion;
+using Microsoft.SemanticKernel.Services;
namespace Microsoft.SemanticKernel.Agents;
@@ -12,21 +13,21 @@ namespace Microsoft.SemanticKernel.Agents;
///
///
/// NOTE: Enable OpenAIPromptExecutionSettings.ToolCallBehavior for agent plugins.
-/// ()
+/// ()
///
public sealed class ChatCompletionAgent : ChatHistoryKernelAgent
{
- ///
- /// Optional execution settings for the agent.
- ///
- public PromptExecutionSettings? ExecutionSettings { get; set; }
-
///
public override async IAsyncEnumerable InvokeAsync(
ChatHistory history,
+ KernelArguments? arguments = null,
+ Kernel? kernel = null,
[EnumeratorCancellation] CancellationToken cancellationToken = default)
{
- IChatCompletionService chatCompletionService = this.Kernel.GetRequiredService();
+ kernel ??= this.Kernel;
+ arguments ??= this.Arguments;
+
+ (IChatCompletionService chatCompletionService, PromptExecutionSettings? executionSettings) = this.GetChatCompletionService(kernel, arguments);
ChatHistory chat = this.SetupAgentChatHistory(history);
@@ -37,8 +38,8 @@ public override async IAsyncEnumerable InvokeAsync(
IReadOnlyList messages =
await chatCompletionService.GetChatMessageContentsAsync(
chat,
- this.ExecutionSettings,
- this.Kernel,
+ executionSettings,
+ kernel,
cancellationToken).ConfigureAwait(false);
this.Logger.LogAgentChatServiceInvokedAgent(nameof(InvokeAsync), this.Id, chatCompletionService.GetType(), messages.Count);
@@ -55,7 +56,6 @@ await chatCompletionService.GetChatMessageContentsAsync(
foreach (ChatMessageContent message in messages ?? [])
{
- // TODO: MESSAGE SOURCE - ISSUE #5731
message.AuthorName = this.Name;
yield return message;
@@ -65,9 +65,14 @@ await chatCompletionService.GetChatMessageContentsAsync(
///
public override async IAsyncEnumerable InvokeStreamingAsync(
ChatHistory history,
+ KernelArguments? arguments = null,
+ Kernel? kernel = null,
[EnumeratorCancellation] CancellationToken cancellationToken = default)
{
- IChatCompletionService chatCompletionService = this.Kernel.GetRequiredService();
+ kernel ??= this.Kernel;
+ arguments ??= this.Arguments;
+
+ (IChatCompletionService chatCompletionService, PromptExecutionSettings? executionSettings) = this.GetChatCompletionService(kernel, arguments);
ChatHistory chat = this.SetupAgentChatHistory(history);
@@ -78,15 +83,14 @@ public override async IAsyncEnumerable InvokeStream
IAsyncEnumerable messages =
chatCompletionService.GetStreamingChatMessageContentsAsync(
chat,
- this.ExecutionSettings,
- this.Kernel,
+ executionSettings,
+ kernel,
cancellationToken);
this.Logger.LogAgentChatServiceInvokedStreamingAgent(nameof(InvokeAsync), this.Id, chatCompletionService.GetType());
await foreach (StreamingChatMessageContent message in messages.ConfigureAwait(false))
{
- // TODO: MESSAGE SOURCE - ISSUE #5731
message.AuthorName = this.Name;
yield return message;
@@ -103,6 +107,19 @@ public override async IAsyncEnumerable InvokeStream
}
}
+ private (IChatCompletionService service, PromptExecutionSettings? executionSettings) GetChatCompletionService(Kernel kernel, KernelArguments? arguments)
+ {
+ // Need to provide a KernelFunction to the service selector as a container for the execution-settings.
+ KernelFunction nullPrompt = KernelFunctionFactory.CreateFromPrompt("placeholder", arguments?.ExecutionSettings?.Values);
+ (IChatCompletionService chatCompletionService, PromptExecutionSettings? executionSettings) =
+ kernel.ServiceSelector.SelectAIService(
+ kernel,
+ nullPrompt,
+ arguments ?? []);
+
+ return (chatCompletionService, executionSettings);
+ }
+
private ChatHistory SetupAgentChatHistory(IReadOnlyList history)
{
ChatHistory chat = [];
diff --git a/dotnet/src/Agents/Abstractions/ChatHistoryChannel.cs b/dotnet/src/Agents/Core/ChatHistoryChannel.cs
similarity index 77%
rename from dotnet/src/Agents/Abstractions/ChatHistoryChannel.cs
rename to dotnet/src/Agents/Core/ChatHistoryChannel.cs
index 5dcb6b9b0204..0ff06a39b222 100644
--- a/dotnet/src/Agents/Abstractions/ChatHistoryChannel.cs
+++ b/dotnet/src/Agents/Core/ChatHistoryChannel.cs
@@ -10,22 +10,25 @@
namespace Microsoft.SemanticKernel.Agents;
///
-/// A specialization for that acts upon a .
+/// A specialization for that acts upon a .
///
-public class ChatHistoryChannel : AgentChannel
+public sealed class ChatHistoryChannel : AgentChannel
{
private readonly ChatHistory _history;
///
- protected internal sealed override async IAsyncEnumerable<(bool IsVisible, ChatMessageContent Message)> InvokeAsync(
+ protected override async IAsyncEnumerable<(bool IsVisible, ChatMessageContent Message)> InvokeAsync(
Agent agent,
[EnumeratorCancellation] CancellationToken cancellationToken = default)
{
- if (agent is not IChatHistoryHandler historyHandler)
+ if (agent is not ChatHistoryKernelAgent historyAgent)
{
throw new KernelException($"Invalid channel binding for agent: {agent.Id} ({agent.GetType().FullName})");
}
+ // Pre-process history reduction.
+ await historyAgent.ReduceAsync(this._history, cancellationToken).ConfigureAwait(false);
+
// Capture the current message count to evaluate history mutation.
int messageCount = this._history.Count;
HashSet mutatedHistory = [];
@@ -34,7 +37,7 @@ public class ChatHistoryChannel : AgentChannel
Queue messageQueue = [];
ChatMessageContent? yieldMessage = null;
- await foreach (ChatMessageContent responseMessage in historyHandler.InvokeAsync(this._history, cancellationToken).ConfigureAwait(false))
+ await foreach (ChatMessageContent responseMessage in historyAgent.InvokeAsync(this._history, null, null, cancellationToken).ConfigureAwait(false))
{
// Capture all messages that have been included in the mutated the history.
for (int messageIndex = messageCount; messageIndex < this._history.Count; messageIndex++)
@@ -74,7 +77,7 @@ bool IsMessageVisible(ChatMessageContent message) =>
}
///
- protected internal sealed override Task ReceiveAsync(IEnumerable history, CancellationToken cancellationToken)
+ protected override Task ReceiveAsync(IEnumerable history, CancellationToken cancellationToken)
{
this._history.AddRange(history);
@@ -82,11 +85,19 @@ protected internal sealed override Task ReceiveAsync(IEnumerable
- protected internal sealed override IAsyncEnumerable GetHistoryAsync(CancellationToken cancellationToken)
+ protected override IAsyncEnumerable GetHistoryAsync(CancellationToken cancellationToken)
{
return this._history.ToDescendingAsync();
}
+ ///
+ protected override Task ResetAsync(CancellationToken cancellationToken = default)
+ {
+ this._history.Clear();
+
+ return Task.CompletedTask;
+ }
+
///
/// Initializes a new instance of the class.
///
diff --git a/dotnet/src/Agents/Core/ChatHistoryKernelAgent.cs b/dotnet/src/Agents/Core/ChatHistoryKernelAgent.cs
new file mode 100644
index 000000000000..b14363c4bb44
--- /dev/null
+++ b/dotnet/src/Agents/Core/ChatHistoryKernelAgent.cs
@@ -0,0 +1,80 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System.Collections.Generic;
+using System.Globalization;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+using Microsoft.SemanticKernel.Agents.History;
+using Microsoft.SemanticKernel.ChatCompletion;
+
+namespace Microsoft.SemanticKernel.Agents;
+
+///
+/// A specialization bound to a .
+///
+///
+/// NOTE: Enable OpenAIPromptExecutionSettings.ToolCallBehavior for agent plugins.
+/// ()
+///
+public abstract class ChatHistoryKernelAgent : KernelAgent
+{
+ ///
+ /// Optional arguments for the agent.
+ ///
+ public KernelArguments? Arguments { get; init; }
+
+ ///
+ public IChatHistoryReducer? HistoryReducer { get; init; }
+
+ ///
+ public abstract IAsyncEnumerable InvokeAsync(
+ ChatHistory history,
+ KernelArguments? arguments = null,
+ Kernel? kernel = null,
+ CancellationToken cancellationToken = default);
+
+ ///
+ public abstract IAsyncEnumerable InvokeStreamingAsync(
+ ChatHistory history,
+ KernelArguments? arguments = null,
+ Kernel? kernel = null,
+ CancellationToken cancellationToken = default);
+
+ ///
+ /// Reduce the provided history
+ ///
+ /// The source history
+ /// The to monitor for cancellation requests. The default is .
+ ///
+ public Task ReduceAsync(ChatHistory history, CancellationToken cancellationToken = default) =>
+ history.ReduceAsync(this.HistoryReducer, cancellationToken);
+
+ ///
+ protected sealed override IEnumerable GetChannelKeys()
+ {
+ yield return typeof(ChatHistoryChannel).FullName!;
+
+ // Agents with different reducers shall not share the same channel.
+ // Agents with the same or equivalent reducer shall share the same channel.
+ if (this.HistoryReducer != null)
+ {
+ // Explicitly include the reducer type to eliminate the possibility of hash collisions
+ // with custom implementations of IChatHistoryReducer.
+ yield return this.HistoryReducer.GetType().FullName!;
+
+ yield return this.HistoryReducer.GetHashCode().ToString(CultureInfo.InvariantCulture);
+ }
+ }
+
+ ///
+ protected sealed override Task CreateChannelAsync(CancellationToken cancellationToken)
+ {
+ ChatHistoryChannel channel =
+ new()
+ {
+ Logger = this.LoggerFactory.CreateLogger()
+ };
+
+ return Task.FromResult(channel);
+ }
+}
diff --git a/dotnet/src/Agents/Core/History/ChatHistoryReducerExtensions.cs b/dotnet/src/Agents/Core/History/ChatHistoryReducerExtensions.cs
new file mode 100644
index 000000000000..c884846baafa
--- /dev/null
+++ b/dotnet/src/Agents/Core/History/ChatHistoryReducerExtensions.cs
@@ -0,0 +1,166 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.SemanticKernel.ChatCompletion;
+
+namespace Microsoft.SemanticKernel.Agents.History;
+
+///
+/// Discrete operations used when reducing chat history.
+///
+///
+/// Allows for improved testability.
+///
+internal static class ChatHistoryReducerExtensions
+{
+ ///
+ /// Extract a range of messages from the source history.
+ ///
+ /// The source history
+ /// The index of the first message to extract
+ /// The index of the last message to extract
+ /// The optional filter to apply to each message
+ public static IEnumerable Extract(this IReadOnlyList history, int startIndex, int? finalIndex = null, Func? filter = null)
+ {
+ int maxIndex = history.Count - 1;
+ if (startIndex > maxIndex)
+ {
+ yield break;
+ }
+
+ finalIndex ??= maxIndex;
+
+ finalIndex = Math.Min(finalIndex.Value, maxIndex);
+
+ for (int index = startIndex; index <= finalIndex; ++index)
+ {
+ if (filter?.Invoke(history[index]) ?? false)
+ {
+ continue;
+ }
+
+ yield return history[index];
+ }
+ }
+
+ ///
+ /// Identify the index of the first message that is not a summary message, as indicated by
+ /// the presence of the specified metadata key.
+ ///
+ /// The source history
+ /// The metadata key that identifies a summary message.
+ public static int LocateSummarizationBoundary(this IReadOnlyList history, string summaryKey)
+ {
+ for (int index = 0; index < history.Count; ++index)
+ {
+ ChatMessageContent message = history[index];
+
+ if (!message.Metadata?.ContainsKey(summaryKey) ?? true)
+ {
+ return index;
+ }
+ }
+
+ return history.Count;
+ }
+
+ ///
+ /// Identify the index of the first message at or beyond the specified targetCount that
+ /// does not orphan sensitive content.
+ /// Specifically: function calls and results shall not be separated since chat-completion requires that
+ /// a function-call always be followed by a function-result.
+ /// In addition, the first user message (if present) within the threshold window will be included
+ /// in order to maintain context with the subsequent assistant responses.
+ ///
+ /// The source history
+ /// The desired message count, should reduction occur.
+ ///
+ /// The threshold, beyond targetCount, required to trigger reduction.
+ /// History is not reduces it the message count is less than targetCount + thresholdCount.
+ ///
+ ///
+ /// Optionally ignore an offset from the start of the history.
+ /// This is useful when messages have been injected that are not part of the raw dialog
+ /// (such as summarization).
+ ///
+ /// An index that identifies the starting point for a reduced history that does not orphan sensitive content.
+ public static int LocateSafeReductionIndex(this IReadOnlyList history, int targetCount, int? thresholdCount = null, int offsetCount = 0)
+ {
+ // Compute the index of the truncation threshold
+ int thresholdIndex = history.Count - (thresholdCount ?? 0) - targetCount;
+
+ if (thresholdIndex <= offsetCount)
+ {
+ // History is too short to truncate
+ return 0;
+ }
+
+ // Compute the index of truncation target
+ int messageIndex = history.Count - targetCount;
+
+ // Skip function related content
+ while (messageIndex >= 0)
+ {
+ if (!history[messageIndex].Items.Any(i => i is FunctionCallContent || i is FunctionResultContent))
+ {
+ break;
+ }
+
+ --messageIndex;
+ }
+
+ // Capture the earliest non-function related message
+ int targetIndex = messageIndex;
+
+ // Scan for user message within truncation range to maximize chat cohesion
+ while (messageIndex >= thresholdIndex)
+ {
+ // A user message provides a superb truncation point
+ if (history[messageIndex].Role == AuthorRole.User)
+ {
+ return messageIndex;
+ }
+
+ --messageIndex;
+ }
+
+ // No user message found, fallback to the earliest non-function related message
+ return targetIndex;
+ }
+
+ ///
+ /// Process history reduction and mutate the provided history.
+ ///
+ /// The source history
+ /// The target reducer
+ /// The to monitor for cancellation requests. The default is .
+ /// True if reduction has occurred.
+ ///
+ /// Using the existing for a reduction in collection size eliminates the need
+ /// for re-allocation (of memory).
+ ///
+ public static async Task ReduceAsync(this ChatHistory history, IChatHistoryReducer? reducer, CancellationToken cancellationToken)
+ {
+ if (reducer == null)
+ {
+ return false;
+ }
+
+ IEnumerable? reducedHistory = await reducer.ReduceAsync(history, cancellationToken).ConfigureAwait(false);
+
+ if (reducedHistory == null)
+ {
+ return false;
+ }
+
+ // Mutate the history in place
+ ChatMessageContent[] reduced = reducedHistory.ToArray();
+ history.Clear();
+ history.AddRange(reduced);
+
+ return true;
+ }
+}
diff --git a/dotnet/src/Agents/Core/History/ChatHistorySummarizationReducer.cs b/dotnet/src/Agents/Core/History/ChatHistorySummarizationReducer.cs
new file mode 100644
index 000000000000..a45bfa57011d
--- /dev/null
+++ b/dotnet/src/Agents/Core/History/ChatHistorySummarizationReducer.cs
@@ -0,0 +1,166 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.SemanticKernel.ChatCompletion;
+
+namespace Microsoft.SemanticKernel.Agents.History;
+
+///
+/// Reduce the chat history by summarizing message past the target message count.
+///
+///
+/// Summarization will always avoid orphaning function-content as the presence of
+/// a function-call _must_ be followed by a function-result. When a threshold count is
+/// is provided (recommended), reduction will scan within the threshold window in an attempt to
+/// avoid orphaning a user message from an assistant response.
+///
+public class ChatHistorySummarizationReducer : IChatHistoryReducer
+{
+ ///
+ /// Metadata key to indicate a summary message.
+ ///
+ public const string SummaryMetadataKey = "__summary__";
+
+ ///
+ /// The default summarization system instructions.
+ ///
+ public const string DefaultSummarizationPrompt =
+ """
+ Provide a concise and complete summarizion of the entire dialog that does not exceed 5 sentences
+
+ This summary must always:
+ - Consider both user and assistant interactions
+ - Maintain continuity for the purpose of further dialog
+ - Include details from any existing summary
+ - Focus on the most significant aspects of the dialog
+
+ This summary must never:
+ - Critique, correct, interpret, presume, or assume
+ - Identify faults, mistakes, misunderstanding, or correctness
+ - Analyze what has not occurred
+ - Exclude details from any existing summary
+ """;
+
+ ///
+ /// System instructions for summarization. Defaults to .
+ ///
+ public string SummarizationInstructions { get; init; } = DefaultSummarizationPrompt;
+
+ ///
+ /// Flag to indicate if an exception should be thrown if summarization fails.
+ ///
+ public bool FailOnError { get; init; } = true;
+
+ ///
+ /// Flag to indicate summarization is maintained in a single message, or if a series of
+ /// summations are generated over time.
+ ///
+ ///
+ /// Not using a single summary may ultimately result in a chat history that exceeds the token limit.
+ ///
+ public bool UseSingleSummary { get; init; } = true;
+
+ ///
+ public async Task?> ReduceAsync(IReadOnlyList history, CancellationToken cancellationToken = default)
+ {
+ // Identify where summary messages end and regular history begins
+ int insertionPoint = history.LocateSummarizationBoundary(SummaryMetadataKey);
+
+ // First pass to determine the truncation index
+ int truncationIndex = history.LocateSafeReductionIndex(this._targetCount, this._thresholdCount, insertionPoint);
+
+ IEnumerable? truncatedHistory = null;
+
+ if (truncationIndex > 0)
+ {
+ // Second pass to extract history for summarization
+ IEnumerable summarizedHistory =
+ history.Extract(
+ this.UseSingleSummary ? 0 : insertionPoint,
+ truncationIndex,
+ (m) => m.Items.Any(i => i is FunctionCallContent || i is FunctionResultContent));
+
+ try
+ {
+ // Summarize
+ ChatHistory summarizationRequest = [.. summarizedHistory, new ChatMessageContent(AuthorRole.System, this.SummarizationInstructions)];
+ ChatMessageContent summary = await this._service.GetChatMessageContentAsync(summarizationRequest, cancellationToken: cancellationToken).ConfigureAwait(false);
+ summary.Metadata = new Dictionary { { SummaryMetadataKey, true } };
+
+ // Assembly the summarized history
+ truncatedHistory = AssemblySummarizedHistory(summary);
+ }
+ catch
+ {
+ if (this.FailOnError)
+ {
+ throw;
+ }
+ }
+ }
+
+ return truncatedHistory;
+
+ // Inner function to assemble the summarized history
+ IEnumerable AssemblySummarizedHistory(ChatMessageContent? summary)
+ {
+ if (insertionPoint > 0 && !this.UseSingleSummary)
+ {
+ for (int index = 0; index <= insertionPoint - 1; ++index)
+ {
+ yield return history[index];
+ }
+ }
+
+ if (summary != null)
+ {
+ yield return summary;
+ }
+
+ for (int index = truncationIndex; index < history.Count; ++index)
+ {
+ yield return history[index];
+ }
+ }
+ }
+
+ ///
+ /// Initializes a new instance of the class.
+ ///
+ /// A instance to be used for summarization.
+ /// The desired number of target messages after reduction.
+ /// An optional number of messages beyond the 'targetCount' that must be present in order to trigger reduction/
+ ///
+ /// While the 'thresholdCount' is optional, it is recommended to provided so that reduction is not triggered
+ /// for every incremental addition to the chat history beyond the 'targetCount'.
+ /// >
+ public ChatHistorySummarizationReducer(IChatCompletionService service, int targetCount, int? thresholdCount = null)
+ {
+ Verify.NotNull(service, nameof(service));
+ Verify.True(targetCount > 0, "Target message count must be greater than zero.");
+ Verify.True(!thresholdCount.HasValue || thresholdCount > 0, "The reduction threshold length must be greater than zero.");
+
+ this._service = service;
+ this._targetCount = targetCount;
+ this._thresholdCount = thresholdCount ?? 0;
+ }
+
+ ///
+ public override bool Equals(object? obj)
+ {
+ ChatHistorySummarizationReducer? other = obj as ChatHistorySummarizationReducer;
+ return other != null &&
+ this._thresholdCount == other._thresholdCount &&
+ this._targetCount == other._targetCount;
+ }
+
+ ///
+ public override int GetHashCode() => HashCode.Combine(nameof(ChatHistorySummarizationReducer), this._thresholdCount, this._targetCount, this.SummarizationInstructions, this.UseSingleSummary);
+
+ private readonly IChatCompletionService _service;
+ private readonly int _thresholdCount;
+ private readonly int _targetCount;
+}
diff --git a/dotnet/src/Agents/Core/History/ChatHistoryTruncationReducer.cs b/dotnet/src/Agents/Core/History/ChatHistoryTruncationReducer.cs
new file mode 100644
index 000000000000..be9ca7868f87
--- /dev/null
+++ b/dotnet/src/Agents/Core/History/ChatHistoryTruncationReducer.cs
@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.SemanticKernel.Agents.History;
+
+///
+/// Truncate the chat history to the target message count.
+///
+///
+/// Truncation will always avoid orphaning function-content as the presence of
+/// a function-call _must_ be followed by a function-result. When a threshold count is
+/// is provided (recommended), reduction will scan within the threshold window in an attempt to
+/// avoid orphaning a user message from an assistant response.
+///
+public class ChatHistoryTruncationReducer : IChatHistoryReducer
+{
+ ///
+ public Task?> ReduceAsync(IReadOnlyList history, CancellationToken cancellationToken = default)
+ {
+ // First pass to determine the truncation index
+ int truncationIndex = history.LocateSafeReductionIndex(this._targetCount, this._thresholdCount);
+
+ IEnumerable? truncatedHistory = null;
+
+ if (truncationIndex > 0)
+ {
+ // Second pass to truncate the history
+ truncatedHistory = history.Extract(truncationIndex);
+ }
+
+ return Task.FromResult(truncatedHistory);
+ }
+
+ ///
+ /// Initializes a new instance of the class.
+ ///
+ /// The desired number of target messages after reduction.
+ /// An optional number of messages beyond the 'targetCount' that must be present in order to trigger reduction/
+ ///
+ /// While the 'thresholdCount' is optional, it is recommended to provided so that reduction is not triggered
+ /// for every incremental addition to the chat history beyond the 'targetCount'.
+ /// >
+ public ChatHistoryTruncationReducer(int targetCount, int? thresholdCount = null)
+ {
+ Verify.True(targetCount > 0, "Target message count must be greater than zero.");
+ Verify.True(!thresholdCount.HasValue || thresholdCount > 0, "The reduction threshold length must be greater than zero.");
+
+ this._targetCount = targetCount;
+
+ this._thresholdCount = thresholdCount ?? 0;
+ }
+
+ ///
+ public override bool Equals(object? obj)
+ {
+ ChatHistoryTruncationReducer? other = obj as ChatHistoryTruncationReducer;
+ return other != null &&
+ this._thresholdCount == other._thresholdCount &&
+ this._targetCount == other._targetCount;
+ }
+
+ ///
+ public override int GetHashCode() => HashCode.Combine(nameof(ChatHistoryTruncationReducer), this._thresholdCount, this._targetCount);
+
+ private readonly int _thresholdCount;
+ private readonly int _targetCount;
+}
diff --git a/dotnet/src/Agents/Core/History/IChatHistoryReducer.cs b/dotnet/src/Agents/Core/History/IChatHistoryReducer.cs
new file mode 100644
index 000000000000..884fbcf42bc1
--- /dev/null
+++ b/dotnet/src/Agents/Core/History/IChatHistoryReducer.cs
@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.SemanticKernel.Agents.History;
+
+///
+/// Defines a contract for a reducing chat history.
+///
+public interface IChatHistoryReducer
+{
+ ///
+ /// Each reducer shall override equality evaluation so that different reducers
+ /// of the same configuration can be evaluated for equivalency.
+ ///
+ bool Equals(object? obj);
+
+ ///
+ /// Each reducer shall implement custom hash-code generation so that different reducers
+ /// of the same configuration can be evaluated for equivalency.
+ ///
+ int GetHashCode();
+
+ ///
+ /// Optionally reduces the chat history.
+ ///
+ /// The source history (which may have been previously reduced)
+ /// The to monitor for cancellation requests. The default is .
+ /// The reduced history, or 'null' if no reduction has occurred
+ Task?> ReduceAsync(IReadOnlyList history, CancellationToken cancellationToken = default);
+}
diff --git a/dotnet/src/Agents/OpenAI/AssistantThreadActions.cs b/dotnet/src/Agents/OpenAI/AssistantThreadActions.cs
index cdb5ae3faea7..cfc7a905cfc7 100644
--- a/dotnet/src/Agents/OpenAI/AssistantThreadActions.cs
+++ b/dotnet/src/Agents/OpenAI/AssistantThreadActions.cs
@@ -109,14 +109,21 @@ public static async IAsyncEnumerable GetMessagesAsync(Assist
/// The thread identifier
/// Config to utilize when polling for run state.
/// The logger to utilize (might be agent or channel scoped)
+ /// The plugins and other state.
+ /// Optional arguments to pass to the agents's invocation, including any .
/// The to monitor for cancellation requests. The default is .
/// Asynchronous enumeration of messages.
+ ///
+ /// The `arguments` parameter is not currently used by the agent, but is provided for future extensibility.
+ ///
public static async IAsyncEnumerable<(bool IsVisible, ChatMessageContent Message)> InvokeAsync(
OpenAIAssistantAgent agent,
AssistantsClient client,
string threadId,
OpenAIAssistantConfiguration.PollingConfiguration pollingConfiguration,
ILogger logger,
+ Kernel kernel,
+ KernelArguments? arguments,
[EnumeratorCancellation] CancellationToken cancellationToken)
{
if (agent.IsDeleted)
@@ -124,7 +131,7 @@ public static async IAsyncEnumerable GetMessagesAsync(Assist
throw new KernelException($"Agent Failure - {nameof(OpenAIAssistantAgent)} agent is deleted: {agent.Id}.");
}
- ToolDefinition[]? tools = [.. agent.Tools, .. agent.Kernel.Plugins.SelectMany(p => p.Select(f => f.ToToolDefinition(p.Name, FunctionDelimiter)))];
+ ToolDefinition[]? tools = [.. agent.Tools, .. kernel.Plugins.SelectMany(p => p.Select(f => f.ToToolDefinition(p.Name, FunctionDelimiter)))];
logger.LogOpenAIAssistantCreatingRun(nameof(InvokeAsync), threadId);
@@ -408,6 +415,7 @@ private static ChatMessageContent GenerateCodeInterpreterContent(string agentNam
])
{
AuthorName = agentName,
+ Metadata = new Dictionary { { OpenAIAssistantAgent.CodeInterpreterMetadataKey, true } },
};
}
diff --git a/dotnet/src/Agents/OpenAI/OpenAIAssistantAgent.cs b/dotnet/src/Agents/OpenAI/OpenAIAssistantAgent.cs
index 8e8797fa8885..6746c6c50d9a 100644
--- a/dotnet/src/Agents/OpenAI/OpenAIAssistantAgent.cs
+++ b/dotnet/src/Agents/OpenAI/OpenAIAssistantAgent.cs
@@ -18,12 +18,25 @@ namespace Microsoft.SemanticKernel.Agents.OpenAI;
///
/// A