Skip to content

Commit f72bf95

Browse files
Copilotwestey-m
andauthored
.NET: [BREAKING] Decouple Cosmos chat metadata from partition-key strategy (#9214)
* Initial plan * Add Cosmos chat history options and customizable partition keys Co-authored-by: westey-m <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: westey-m <[email protected]>
1 parent c1c288b commit f72bf95

4 files changed

Lines changed: 294 additions & 59 deletions

File tree

‎dotnet/src/Microsoft.Agents.AI.CosmosNoSql/CosmosChatHistoryProvider.cs‎

Lines changed: 35 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
4848
private readonly CosmosClient _cosmosClient;
4949
private readonly Container _container;
5050
private readonly bool _ownsClient;
51+
private readonly Func<State, PartitionKey>? _partitionKeyFactory;
5152
private bool _disposed;
5253

5354
/// <summary>
@@ -112,34 +113,27 @@ public int MaxBatchSize
112113
/// <param name="databaseId">The identifier of the Cosmos DB database.</param>
113114
/// <param name="containerId">The identifier of the Cosmos DB container.</param>
114115
/// <param name="stateInitializer">A delegate that initializes the provider state on the first invocation, providing the conversation routing info (conversationId, tenantId, userId).</param>
115-
/// <param name="ownsClient">Whether this instance owns the CosmosClient and should dispose it.</param>
116-
/// <param name="stateKey">An optional key to use for storing the state in the <see cref="AgentSession.StateBag"/>.</param>
117-
/// <param name="provideOutputMessageFilter">An optional filter function to apply to messages when retrieving them from the chat history.</param>
118-
/// <param name="storeInputRequestMessageFilter">An optional filter function to apply to request messages before storing them in the chat history. If not set, defaults to excluding messages with source type <see cref="AgentRequestMessageSourceType.ChatHistory"/>.</param>
119-
/// <param name="storeInputResponseMessageFilter">An optional filter function to apply to response messages before storing them in the chat history. If not set, defaults to storing all response messages.</param>
116+
/// <param name="options">Optional configuration options.</param>
120117
/// <exception cref="ArgumentNullException">Thrown when <paramref name="cosmosClient"/> or <paramref name="stateInitializer"/> is <see langword="null"/>.</exception>
121118
/// <exception cref="ArgumentException">Thrown when any string parameter is null or whitespace.</exception>
122119
public CosmosChatHistoryProvider(
123120
CosmosClient cosmosClient,
124121
string databaseId,
125122
string containerId,
126123
Func<AgentSession?, State> stateInitializer,
127-
bool ownsClient = false,
128-
string? stateKey = null,
129-
Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideOutputMessageFilter = null,
130-
Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputRequestMessageFilter = null,
131-
Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputResponseMessageFilter = null)
132-
: base(provideOutputMessageFilter, storeInputRequestMessageFilter, storeInputResponseMessageFilter)
124+
CosmosChatHistoryProviderOptions? options = null)
125+
: base(options?.ProvideOutputMessageFilter, options?.StoreInputRequestMessageFilter, options?.StoreInputResponseMessageFilter)
133126
{
134127
this._sessionState = new ProviderSessionState<State>(
135128
Throw.IfNull(stateInitializer),
136-
stateKey ?? this.GetType().Name);
129+
options?.StateKey ?? this.GetType().Name);
137130
this._cosmosClient = Throw.IfNull(cosmosClient);
138131
CosmosOptionsHelper.EnsureApplicationName(this._cosmosClient, nameof(CosmosChatHistoryProvider));
139132
this.DatabaseId = Throw.IfNullOrWhitespace(databaseId);
140133
this.ContainerId = Throw.IfNullOrWhitespace(containerId);
141134
this._container = this._cosmosClient.GetContainer(databaseId, containerId);
142-
this._ownsClient = ownsClient;
135+
this._ownsClient = options?.OwnsClient ?? false;
136+
this._partitionKeyFactory = options?.PartitionKeyFactory;
143137
}
144138

145139
/// <inheritdoc />
@@ -152,23 +146,18 @@ public CosmosChatHistoryProvider(
152146
/// <param name="databaseId">The identifier of the Cosmos DB database.</param>
153147
/// <param name="containerId">The identifier of the Cosmos DB container.</param>
154148
/// <param name="stateInitializer">A delegate that initializes the provider state on the first invocation.</param>
155-
/// <param name="stateKey">An optional key to use for storing the state in the <see cref="AgentSession.StateBag"/>.</param>
156-
/// <param name="provideOutputMessageFilter">An optional filter function to apply to messages when retrieving them from the chat history.</param>
157-
/// <param name="storeInputRequestMessageFilter">An optional filter function to apply to request messages before storing them in the chat history. If not set, defaults to excluding messages with source type <see cref="AgentRequestMessageSourceType.ChatHistory"/>.</param>
158-
/// <param name="storeInputResponseMessageFilter">An optional filter function to apply to response messages before storing them in the chat history. If not set, defaults to storing all response messages.</param>
149+
/// <param name="options">Optional configuration options.</param>
159150
/// <exception cref="ArgumentNullException">Thrown when any required parameter is null.</exception>
160151
/// <exception cref="ArgumentException">Thrown when any string parameter is null or whitespace.</exception>
161152
public CosmosChatHistoryProvider(
162153
string connectionString,
163154
string databaseId,
164155
string containerId,
165156
Func<AgentSession?, State> stateInitializer,
166-
string? stateKey = null,
167-
Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideOutputMessageFilter = null,
168-
Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputRequestMessageFilter = null,
169-
Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputResponseMessageFilter = null)
170-
: this(new CosmosClient(Throw.IfNullOrWhitespace(connectionString), CosmosOptionsHelper.CreateOptions(nameof(CosmosChatHistoryProvider))), databaseId, containerId, stateInitializer, ownsClient: true, stateKey, provideOutputMessageFilter, storeInputRequestMessageFilter, storeInputResponseMessageFilter)
157+
CosmosChatHistoryProviderOptions? options = null)
158+
: this(new CosmosClient(Throw.IfNullOrWhitespace(connectionString), CosmosOptionsHelper.CreateOptions(nameof(CosmosChatHistoryProvider))), databaseId, containerId, stateInitializer, options)
171159
{
160+
this._ownsClient = true;
172161
}
173162

174163
/// <summary>
@@ -179,10 +168,7 @@ public CosmosChatHistoryProvider(
179168
/// <param name="databaseId">The identifier of the Cosmos DB database.</param>
180169
/// <param name="containerId">The identifier of the Cosmos DB container.</param>
181170
/// <param name="stateInitializer">A delegate that initializes the provider state on the first invocation.</param>
182-
/// <param name="stateKey">An optional key to use for storing the state in the <see cref="AgentSession.StateBag"/>.</param>
183-
/// <param name="provideOutputMessageFilter">An optional filter function to apply to messages when retrieving them from the chat history.</param>
184-
/// <param name="storeInputRequestMessageFilter">An optional filter function to apply to request messages before storing them in the chat history. If not set, defaults to excluding messages with source type <see cref="AgentRequestMessageSourceType.ChatHistory"/>.</param>
185-
/// <param name="storeInputResponseMessageFilter">An optional filter function to apply to response messages before storing them in the chat history. If not set, defaults to storing all response messages.</param>
171+
/// <param name="options">Optional configuration options.</param>
186172
/// <exception cref="ArgumentNullException">Thrown when any required parameter is null.</exception>
187173
/// <exception cref="ArgumentException">Thrown when any string parameter is null or whitespace.</exception>
188174
public CosmosChatHistoryProvider(
@@ -191,12 +177,10 @@ public CosmosChatHistoryProvider(
191177
string databaseId,
192178
string containerId,
193179
Func<AgentSession?, State> stateInitializer,
194-
string? stateKey = null,
195-
Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideOutputMessageFilter = null,
196-
Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputRequestMessageFilter = null,
197-
Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputResponseMessageFilter = null)
198-
: this(new CosmosClient(Throw.IfNullOrWhitespace(accountEndpoint), Throw.IfNull(tokenCredential), CosmosOptionsHelper.CreateOptions(nameof(CosmosChatHistoryProvider))), databaseId, containerId, stateInitializer, ownsClient: true, stateKey, provideOutputMessageFilter, storeInputRequestMessageFilter, storeInputResponseMessageFilter)
180+
CosmosChatHistoryProviderOptions? options = null)
181+
: this(new CosmosClient(Throw.IfNullOrWhitespace(accountEndpoint), Throw.IfNull(tokenCredential), CosmosOptionsHelper.CreateOptions(nameof(CosmosChatHistoryProvider))), databaseId, containerId, stateInitializer, options)
199182
{
183+
this._ownsClient = true;
200184
}
201185

202186
/// <summary>
@@ -208,8 +192,13 @@ private static bool UseHierarchicalPartitioning(State state) =>
208192
/// <summary>
209193
/// Builds the partition key from the state.
210194
/// </summary>
211-
private static PartitionKey BuildPartitionKey(State state)
195+
private PartitionKey BuildPartitionKey(State state)
212196
{
197+
if (this._partitionKeyFactory is not null)
198+
{
199+
return this._partitionKeyFactory(state);
200+
}
201+
213202
if (UseHierarchicalPartitioning(state))
214203
{
215204
return new PartitionKeyBuilder()
@@ -253,7 +242,7 @@ public async Task<IEnumerable<ChatMessage>> GetMessagesAsync(AgentSession? sessi
253242

254243
FeatureUsageMarker.MarkUsed();
255244
var state = this._sessionState.GetOrInitializeState(session);
256-
var partitionKey = BuildPartitionKey(state);
245+
var partitionKey = this.BuildPartitionKey(state);
257246

258247
// Fetch most recent messages in descending order when limit is set, then reverse to ascending
259248
var orderDirection = this.MaxMessagesToRetrieve.HasValue ? "DESC" : "ASC";
@@ -323,7 +312,7 @@ protected override async ValueTask StoreChatHistoryAsync(InvokedContext context,
323312
return;
324313
}
325314

326-
var partitionKey = BuildPartitionKey(state);
315+
var partitionKey = this.BuildPartitionKey(state);
327316

328317
// Use transactional batch for atomic operations
329318
if (messageList.Count > 1)
@@ -452,8 +441,6 @@ private async Task AddSingleMessageAsync(PartitionKey partitionKey, State state,
452441
/// </summary>
453442
private CosmosMessageDocument CreateMessageDocument(State state, ChatMessage message, long timestamp)
454443
{
455-
var useHierarchical = UseHierarchicalPartitioning(state);
456-
457444
return new CosmosMessageDocument
458445
{
459446
Id = Guid.NewGuid().ToString(),
@@ -464,10 +451,9 @@ private CosmosMessageDocument CreateMessageDocument(State state, ChatMessage mes
464451
Message = JsonSerializer.Serialize(message, s_defaultJsonOptions),
465452
Type = "ChatMessage", // Type discriminator
466453
Ttl = this.MessageTtlSeconds, // Configurable TTL
467-
// Include hierarchical metadata when using hierarchical partitioning
468-
TenantId = useHierarchical ? state.TenantId : null,
469-
UserId = useHierarchical ? state.UserId : null,
470-
SessionId = useHierarchical ? state.ConversationId : null
454+
TenantId = state.TenantId,
455+
UserId = state.UserId,
456+
SessionId = state.ConversationId
471457
};
472458
}
473459

@@ -489,7 +475,7 @@ public async Task<int> GetMessageCountAsync(AgentSession? session, CancellationT
489475

490476
FeatureUsageMarker.MarkUsed();
491477
var state = this._sessionState.GetOrInitializeState(session);
492-
var partitionKey = BuildPartitionKey(state);
478+
var partitionKey = this.BuildPartitionKey(state);
493479

494480
// Efficient count query
495481
var query = new QueryDefinition("SELECT VALUE COUNT(1) FROM c WHERE c.conversationId = @conversationId AND c.type = @type")
@@ -524,7 +510,7 @@ public async Task<int> ClearMessagesAsync(AgentSession? session, CancellationTok
524510

525511
FeatureUsageMarker.MarkUsed();
526512
var state = this._sessionState.GetOrInitializeState(session);
527-
var partitionKey = BuildPartitionKey(state);
513+
var partitionKey = this.BuildPartitionKey(state);
528514

529515
// Batch delete for efficiency
530516
var query = new QueryDefinition("SELECT VALUE c.id FROM c WHERE c.conversationId = @conversationId AND c.type = @type")
@@ -586,8 +572,8 @@ public sealed class State
586572
/// Initializes a new instance of the <see cref="State"/> class.
587573
/// </summary>
588574
/// <param name="conversationId">The unique identifier for this conversation thread.</param>
589-
/// <param name="tenantId">Optional tenant identifier for hierarchical partitioning.</param>
590-
/// <param name="userId">Optional user identifier for hierarchical partitioning.</param>
575+
/// <param name="tenantId">Optional tenant identifier persisted as document metadata and used by the default hierarchical partitioning strategy.</param>
576+
/// <param name="userId">Optional user identifier persisted as document metadata and used by the default hierarchical partitioning strategy.</param>
591577
public State(string conversationId, string? tenantId = null, string? userId = null)
592578
{
593579
this.ConversationId = Throw.IfNullOrWhitespace(conversationId);
@@ -601,12 +587,12 @@ public State(string conversationId, string? tenantId = null, string? userId = nu
601587
public string ConversationId { get; }
602588

603589
/// <summary>
604-
/// Gets the tenant identifier for hierarchical partitioning, if any.
590+
/// Gets the tenant identifier persisted as document metadata, if any.
605591
/// </summary>
606592
public string? TenantId { get; }
607593

608594
/// <summary>
609-
/// Gets the user identifier for hierarchical partitioning, if any.
595+
/// Gets the user identifier persisted as document metadata, if any.
610596
/// </summary>
611597
public string? UserId { get; }
612598
}
@@ -645,19 +631,19 @@ private sealed class CosmosMessageDocument
645631
public int? Ttl { get; set; }
646632

647633
/// <summary>
648-
/// Tenant ID for hierarchical partitioning scenarios (optional).
634+
/// Tenant ID metadata (optional).
649635
/// </summary>
650636
[Newtonsoft.Json.JsonProperty("tenantId")]
651637
public string? TenantId { get; set; }
652638

653639
/// <summary>
654-
/// User ID for hierarchical partitioning scenarios (optional).
640+
/// User ID metadata (optional).
655641
/// </summary>
656642
[Newtonsoft.Json.JsonProperty("userId")]
657643
public string? UserId { get; set; }
658644

659645
/// <summary>
660-
/// Session ID for hierarchical partitioning scenarios (same as ConversationId for compatibility).
646+
/// Session ID metadata (same as ConversationId for compatibility).
661647
/// </summary>
662648
[Newtonsoft.Json.JsonProperty("sessionId")]
663649
public string? SessionId { get; set; }
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
3+
using System;
4+
using System.Collections.Generic;
5+
using Microsoft.Azure.Cosmos;
6+
using Microsoft.Extensions.AI;
7+
8+
namespace Microsoft.Agents.AI;
9+
10+
/// <summary>
11+
/// Options controlling the behavior of <see cref="CosmosChatHistoryProvider"/>.
12+
/// </summary>
13+
public sealed class CosmosChatHistoryProviderOptions
14+
{
15+
/// <summary>
16+
/// Gets or sets a value indicating whether the provider disposes a caller-supplied <see cref="CosmosClient"/>.
17+
/// </summary>
18+
/// <value>Defaults to <see langword="false"/>. Clients created by the provider are always disposed by it.</value>
19+
public bool OwnsClient { get; set; }
20+
21+
/// <summary>
22+
/// Gets or sets the key used to store provider state in the <see cref="AgentSession.StateBag"/>.
23+
/// </summary>
24+
/// <value>Defaults to the provider's type name.</value>
25+
public string? StateKey { get; set; }
26+
27+
/// <summary>
28+
/// Gets or sets a delegate that builds the partition key for all storage, retrieval, count, and delete operations.
29+
/// </summary>
30+
/// <value>
31+
/// When <see langword="null"/>, the provider uses a hierarchical key of tenant ID, user ID, and conversation ID
32+
/// if both tenant ID and user ID are set; otherwise, it uses the conversation ID.
33+
/// </value>
34+
/// <remarks>
35+
/// The key must match the container's partition key definition and the values persisted on the document.
36+
/// Tenant and user IDs are persisted whenever set, and the session ID is always the conversation ID,
37+
/// regardless of this strategy. To use flat <c>/conversationId</c> partitioning while retaining tenant and user
38+
/// metadata, set this to <c>state => new PartitionKey(state.ConversationId)</c>.
39+
/// Partition keys and metadata do not replace application-level authorization.
40+
/// </remarks>
41+
public Func<CosmosChatHistoryProvider.State, PartitionKey>? PartitionKeyFactory { get; set; }
42+
43+
/// <summary>
44+
/// Gets or sets an optional filter applied to messages retrieved from chat history.
45+
/// </summary>
46+
public Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? ProvideOutputMessageFilter { get; set; }
47+
48+
/// <summary>
49+
/// Gets or sets an optional filter applied to request messages before storing them in chat history.
50+
/// </summary>
51+
/// <value>When <see langword="null"/>, messages with source type <see cref="AgentRequestMessageSourceType.ChatHistory"/> are excluded.</value>
52+
public Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? StoreInputRequestMessageFilter { get; set; }
53+
54+
/// <summary>
55+
/// Gets or sets an optional filter applied to response messages before storing them in chat history.
56+
/// </summary>
57+
/// <value>When <see langword="null"/>, all response messages are stored.</value>
58+
public Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? StoreInputResponseMessageFilter { get; set; }
59+
}

0 commit comments

Comments
 (0)