Class AzureCosmosDBService

Namespace

FoundationaLLM.Common.Services.Azure

Assembly

FoundationaLLM.Common.dll

Service to access Azure Cosmos DB for NoSQL.

public class AzureCosmosDBService : IAzureCosmosDBService

Inheritance

object

AzureCosmosDBService

Implements

IAzureCosmosDBService

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ObjectExtensions.GetPropertyValues(object, List<string>)

Constructors

AzureCosmosDBService(IOptions<AzureCosmosDBSettings>, CosmosClient, ILogger<AzureCosmosDBService>)

Initializes a new instance of the AzureCosmosDBService class.

public AzureCosmosDBService(IOptions<AzureCosmosDBSettings> settings, CosmosClient client, ILogger<AzureCosmosDBService> logger)

Parameters

settings IOptions<AzureCosmosDBSettings>

The AzureCosmosDBSettings settings retrieved by the injected IOptions<TOptions>.

client CosmosClient

The Cosmos DB client.

logger ILogger<AzureCosmosDBService>

The logging interface used to log under the AzureCosmosDBService type name.

Exceptions

ArgumentException

Thrown if any of the required settings are null or empty.

Methods

CreateAgentFile(AgentFileReference, CancellationToken)

Creates an agent file.

public Task CreateAgentFile(AgentFileReference agentFile, CancellationToken cancellationToken = default)

Parameters

agentFile AgentFileReference

The agent file to be added.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task

CreateAttachment(AttachmentReference, CancellationToken)

Creates an attachment.

public Task CreateAttachment(AttachmentReference attachmentReference, CancellationToken cancellationToken = default)

Parameters

attachmentReference AttachmentReference

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task

CreateOrUpdateConversationAsync(Conversation, CancellationToken)

Creates or updates a conversation.

public Task<Conversation> CreateOrUpdateConversationAsync(Conversation session, CancellationToken cancellationToken = default)

Parameters

session Conversation

Conversation item to create or update.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<Conversation>

Newly created or updated conversation item.

CreateVectorSearchContainerAsync(string, string, string, int, CancellationToken)

Creates a new container for vector search.

public Task CreateVectorSearchContainerAsync(string containerName, string partitionKeyPath, string vectorPropertyPath, int vectorDimensions, CancellationToken cancellationToken = default)

Parameters

containerName string

The name of the container to create.

partitionKeyPath string

The property path that contains the partition key.

vectorPropertyPath string

vectorDimensions int

The length of each vector (the number of dimensions used for embedding).

cancellationToken CancellationToken

The cancellation token to signal the need to cancel the operation.

Returns

Task

DeleteAgentFile(AgentFileReference, CancellationToken)

Deletes an agent file.

public Task DeleteAgentFile(AgentFileReference agentFile, CancellationToken cancellationToken = default)

Parameters

agentFile AgentFileReference

The agent file to be deleted.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task

DeleteAttachment(AttachmentReference, CancellationToken)

Deletes an attachment.

public Task DeleteAttachment(AttachmentReference attachmentReference, CancellationToken cancellationToken = default)

Parameters

attachmentReference AttachmentReference

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task

DeleteConversationAsync(string, CancellationToken)

Batch deletes an existing chat session and all related messages.

public Task DeleteConversationAsync(string sessionId, CancellationToken cancellationToken = default)

Parameters

sessionId string

Chat session identifier used to flag messages and sessions for deletion.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task

FilterAttachments(string, ResourceFilter, CancellationToken)

Gets list of filtered attachments.

public Task<List<AttachmentReference>> FilterAttachments(string upn, ResourceFilter resourceFilter, CancellationToken cancellationToken = default)

Parameters

upn string

The user's UPN.

resourceFilter ResourceFilter

The resource filter.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<List<AttachmentReference>>

A list of filtered attachments.

GetAgentFile(string, string, string, CancellationToken)

Gets an agent file.

public Task<AgentFileReference?> GetAgentFile(string instanceId, string agentName, string id, CancellationToken cancellationToken = default)

Parameters

instanceId string

The instance unique identifier

agentName string

The agent name.

id string

The agent file id.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<AgentFileReference>

An agent file.

GetAgentFiles(string, string, CancellationToken)

Gets a list of agent files.

public Task<List<AgentFileReference>> GetAgentFiles(string instanceId, string agentName, CancellationToken cancellationToken = default)

Parameters

instanceId string

The instance unique identifier

agentName string

The agent name.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<List<AgentFileReference>>

A list of agent files.

GetAttachment(string, string, CancellationToken)

Gets an attachment.

public Task<AttachmentReference?> GetAttachment(string upn, string resourceName, CancellationToken cancellationToken = default)

Parameters

upn string

The user's UPN.

resourceName string

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<AttachmentReference>

An attachment.

GetAttachments(string, CancellationToken)

Gets a list of attachments for the signed in user.

public Task<List<AttachmentReference>> GetAttachments(string upn, CancellationToken cancellationToken = default)

Parameters

upn string

The user principal name used for retrieving the attachments for the signed in user.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<List<AttachmentReference>>

A list of attachments for the signed in user.

GetCompletionPromptAsync(string, string)

Returns the completion prompt for a given session and completion prompt id.

public Task<CompletionPrompt> GetCompletionPromptAsync(string sessionId, string completionPromptId)

Parameters

sessionId string

The session id from which to retrieve the completion prompt.

completionPromptId string

The id of the completion prompt to retrieve.

Returns

Task<CompletionPrompt>

GetCompletionResponseAsync(string, ReadOnlyMemory<float>, decimal)

Gets the completion response for a given user prompt embedding using vector search and a minimum threshold for similarity.

public Task<CompletionResponse?> GetCompletionResponseAsync(string containerName, ReadOnlyMemory<float> userPromptEmbedding, decimal minimumSimilarityScore)

Parameters

containerName string

The name of the container holding the vector index.

userPromptEmbedding ReadOnlyMemory<float>

The reference embedding used for the vector search.

minimumSimilarityScore decimal

The threshold used for the similarity score.

Returns

Task<CompletionResponse>

A CompletionResponse that matches the search criteria. If no item in the vector index matches the criteria, returns .

GetConversationAsync(string, CancellationToken)

Performs a point read to retrieve a single conversation item.

public Task<Conversation?> GetConversationAsync(string id, CancellationToken cancellationToken = default)

Parameters

id string

cancellationToken CancellationToken

Returns

Task<Conversation>

The conversation item. Returns null if the conversation does not exist.

GetConversationsAsync(string, string, CancellationToken)

Gets a list of all current conversations.

public Task<List<Conversation>> GetConversationsAsync(string type, string upn, CancellationToken cancellationToken = default)

Parameters

type string

The conversation type to return.

upn string

The user principal name used for retrieving conversations for the signed-in user.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<List<Conversation>>

List of distinct conversation items.

GetItemAsync<T>(string, string, string, CancellationToken)

Gets a single item by its identifier and partition key.

public Task<T?> GetItemAsync<T>(string containerName, string id, string partitionKey, CancellationToken cancellationToken = default)

Parameters

containerName string

The name of the container storing the item.

id string

The identifier of the item.

partitionKey string

The partition key of the item.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<T>

The retrieved object of type T.

Type Parameters

T

The type of the item to retrieve.

GetLongRunningOperationContextAsync(string, CancellationToken)

Get the context for a long running operation.

public Task<LongRunningOperationContext> GetLongRunningOperationContextAsync(string operationId, CancellationToken cancellationToken = default)

Parameters

operationId string

The identifier of the long running operation.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<LongRunningOperationContext>

A LongRunningOperationContext object providing the context for the long running operation.

GetMessageAsync(string, string, CancellationToken)

Gets a single conversation message by its identifier.

public Task<Message> GetMessageAsync(string id, string sessionId, CancellationToken cancellationToken = default)

Parameters

id string

The identifier of the message.

sessionId string

The identifier of the conversation.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<Message>

A Message object containing the message.

GetSessionMessagesAsync(string, string, int?, CancellationToken)

Gets a list of all current chat messages for a specified session identifier. Messages are always sorted by TimeStamp in ascending order.

public Task<List<Message>> GetSessionMessagesAsync(string sessionId, string upn, int? max = null, CancellationToken cancellationToken = default)

Parameters

sessionId string

Chat session identifier used to filter messages.

upn string

The user principal name used for retrieving the messages for the signed in user.

max int?

If provided, limits the number of messages.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<List<Message>>

List of chat message items for the specified session.

GetUserProfileAsync(string, CancellationToken)

Returns the user profile for a given user via their UPN.

public Task<UserProfile> GetUserProfileAsync(string upn, CancellationToken cancellationToken = default)

Parameters

upn string

The user principal name used for retrieving the messages for the signed in user.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<UserProfile>

InsertMessageAsync(Message, CancellationToken)

Creates a new chat message.

public Task<Message> InsertMessageAsync(Message message, CancellationToken cancellationToken = default)

Parameters

message Message

Chat message item to create.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<Message>

Newly created chat message item.

PatchConversationPropertiesAsync(string, string, Dictionary<string, object?>, CancellationToken)

Updates conversation properties through a patch operation.

public Task<Conversation> PatchConversationPropertiesAsync(string id, string upn, Dictionary<string, object?> propertyValues, CancellationToken cancellationToken = default)

Parameters

id string

The conversation id.

upn string

The user principal name used for policy enforcement.

propertyValues Dictionary<string, object>

The dictionary containing property names and updated values.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<Conversation>

Updated conversation item.

PatchItemPropertiesAsync<T>(string, string, string, string, Dictionary<string, object?>, CancellationToken)

Patches an item in the specified container.

public Task<T> PatchItemPropertiesAsync<T>(string containerName, string partitionKey, string id, string upn, Dictionary<string, object?> propertyValues, CancellationToken cancellationToken = default)

Parameters

containerName string

The name of the container storing the item.

partitionKey string

The partition key of the item.

id string

The item ID.

upn string

The user principal name used for matching the UPN of the item.

propertyValues Dictionary<string, object>

Dictionary of the property names and values to patch.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<T>

The patched object of type .

Type Parameters

T

The type of the item to patch.

PatchMultipleSessionsItemsInTransactionAsync(string, List<IPatchOperationItem>, CancellationToken)

Updates a subset of the properties of one or more items of a specified type from the Sessions collection.

public Task<Dictionary<string, object>> PatchMultipleSessionsItemsInTransactionAsync(string partitionKey, List<IPatchOperationItem> patchOperations, CancellationToken cancellationToken = default)

Parameters

partitionKey string

The partition key of the item(s) being updated. Batch operations must occur within the same partition key.

patchOperations List<IPatchOperationItem>

The patch operations to perform on each object, including the object's identifier, dictionary containing the property names and updated values, and the item type.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<Dictionary<string, object>>

PatchOperationsItemPropertiesAsync<T>(string, string, Dictionary<string, object?>, CancellationToken)

Updates a subset of the properties of an item of a specified type from the Operations collection.

public Task<T> PatchOperationsItemPropertiesAsync<T>(string itemId, string partitionKey, Dictionary<string, object?> propertyValues, CancellationToken cancellationToken = default)

Parameters

itemId string

The identifier of the item being updated.

partitionKey string

The partition key of the item being updated.

propertyValues Dictionary<string, object>

The dictionary containing property names and updated values.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<T>

Type Parameters

T

The type of the item to update.

PatchSessionsItemPropertiesAsync<T>(string, string, Dictionary<string, object?>, CancellationToken)

Updates a subset of the properties of an item of a specified type from the Sessions collection.

public Task<T> PatchSessionsItemPropertiesAsync<T>(string itemId, string partitionKey, Dictionary<string, object?> propertyValues, CancellationToken cancellationToken = default)

Parameters

itemId string

The identifier of the item being updated.

partitionKey string

The partition key of the item being updated.

propertyValues Dictionary<string, object>

The dictionary containing property names and updated values.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<T>

Type Parameters

T

The type of the item to update.

UpdateMessageAsync(Message, CancellationToken)

Updates an existing chat message.

public Task<Message> UpdateMessageAsync(Message message, CancellationToken cancellationToken = default)

Parameters

message Message

Chat message item to update.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<Message>

Revised chat message item.

UpsertItemAsync<T>(string, string, T, CancellationToken)

Creates or updates an item in the specified container.

public Task<T?> UpsertItemAsync<T>(string containerName, string partitionKey, T item, CancellationToken cancellationToken = default)

Parameters

containerName string

The name of the container storing the item.

partitionKey string

The partition key of the item.

item T

The item to be created or updated.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task<T>

The created or updated object of type T.

Type Parameters

T

The type of the item to create or update.

UpsertLongRunningOperationContextAsync(LongRunningOperationContext, CancellationToken)

Inserts or updates a long running operation context.

public Task UpsertLongRunningOperationContextAsync(LongRunningOperationContext longRunningOperationContext, CancellationToken cancellationToken = default)

Parameters

longRunningOperationContext LongRunningOperationContext

The LongRunningOperationContext object providing the context for the long running operation.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task

UpsertSessionBatchAsync(params dynamic[])

Batch create or update chat messages and session.

public Task UpsertSessionBatchAsync(params dynamic[] messages)

Parameters

messages dynamic[]

Chat message and session items to create or replace.

Returns

Task

UpsertUserProfileAsync(UserProfile, CancellationToken)

Inserts or updates a user profile.

public Task UpsertUserProfileAsync(UserProfile userProfile, CancellationToken cancellationToken = default)

Parameters

userProfile UserProfile

The user profile to upsert.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task

UpsertUserSessionAsync(Conversation, CancellationToken)

Create or update a user session from the passed in Session object.

public Task UpsertUserSessionAsync(Conversation session, CancellationToken cancellationToken = default)

Parameters

session Conversation

The chat session item to create or replace.

cancellationToken CancellationToken

Cancellation token for async calls.

Returns

Task