xSaherElmAiApi/AI/Interfaces/IXAiProvider.cs

using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using xAiApi.AI.Configuration;
using xAiApi.AI.Models.Entities;
using xAiModels.Models;
using xIdentityModels.Models;
using xModels.Dtos;

namespace xAiApi.AI.Interfaces
{
    /// <summary>
    /// Provide Ai Capabilities Using AI Service ...
    /// using User Data Info ...
    /// </summary>
    public interface IXAiProvider
    {
        /// <summary>
        /// Configuration ...
        /// </summary>
        /// <value></value>
        public XAiApiConfiguration Configuration { get; }

        //
        #region Helpers ...
        /// <summary>
        /// Converts Entity to Dto ...
        /// <see cref="XAiProjectDto"/>
        /// </summary>
        /// <param name="entity"><see cref="XAiProject"/></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XAiProjectDto> ToDto(
            XAiProject entity,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Converts Entity to Dto ...
        /// <see cref="XAiMessageDto"/>
        /// </summary>
        /// <param name="entity"><see cref="XAiMessage"/></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XAiMessageDto> ToDto(
            XAiMessage entity,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Converts Entity to Dto ...
        /// <see cref="XAiConversationDto"/>
        /// </summary>
        /// <param name="entity"><see cref="XAiConversation"/></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XAiConversationDto> ToDto(
            XAiConversation entity,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Converts a List of Entities to Dtos ...
        /// <see cref="XAiProjectDto"/>
        /// </summary>
        /// <param name="entities"><see cref="XAiProject"/></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XAiProjectDto>> ToDtos(
            IEnumerable<XAiProject> entities,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Converts a List of Entities to Dtos ...
        /// <see cref="XAiMessageDto"/>
        /// </summary>
        /// <param name="entities"><see cref="XAiMessage"/></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XAiMessageDto>> ToDtos(
            IEnumerable<XAiMessage> entities,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Converts a List of Entities to Dtos ...
        /// <see cref="XAiConversationDto"/>
        /// </summary>
        /// <param name="entities"><see cref="XAiConversation"/></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XAiConversationDto>> ToDtos(
            IEnumerable<XAiConversation> entities,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Converts a QueryResult of Entities to Dtos ...
        /// <see cref="XAiProjectDto"/>
        /// </summary>
        /// <param name="queryResult"><see cref="XAiProject"/></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XQueryResult<XAiProjectDto>> ToDtoQueryResult(
            XQueryResult<XAiProject> queryResult,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Converts a QueryResult of Entities to Dtos ...
        /// <see cref="XAiMessageDto"/>
        /// </summary>
        /// <param name="queryResult"><see cref="XAiMessage"/></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XQueryResult<XAiMessageDto>> ToDtoQueryResult(
            XQueryResult<XAiMessage> queryResult,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Converts a QueryResult of Entities to Dtos ...
        /// <see cref="XAiConversationDto"/>
        /// </summary>
        /// <param name="queryResult"><see cref="XAiConversation"/></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XQueryResult<XAiConversationDto>> ToDtoQueryResult(
            XQueryResult<XAiConversation> queryResult,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Check Permission for Ai Actions ...
        /// </summary>
        /// <param name="projectId"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<bool> HasPermission(
            string projectId = null,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Prepare Prompt ...
        /// </summary>
        /// <param name="prompt"></param>
        /// <param name="projectId"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<string> PreparePrompt(
            string prompt,
            string projectId = null,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region Actions ...
        /// <summary>
        /// Ask a Question ...
        /// </summary>
        /// <param name="prompt"></param>
        /// <param name="projectId"></param>
        /// <param name="conversationId"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XAiMessageDto> Ask(
            string prompt,
            string projectId = null,
            string conversationId = null,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Ask a Question in Streaming ...
        /// </summary>
        /// <param name="prompt"></param>
        /// <param name="projectId"></param>
        /// <param name="conversationId"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        IAsyncEnumerable<XAiMessageUpdateDto> AskStream(
            string prompt,
            string projectId = null,
            string conversationId = null,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );
        #endregion
    }
}