xSaherElmAiApi/Interfaces/IXAiServiceBase.cs

using System;
using xModels.Dtos;
using System.Net.Http;
using System.Threading;
using xAiModels.Models;
using xAiModels.Models.Dtos;
using System.Threading.Tasks;
using Microsoft.Extensions.AI;
using Microsoft.AspNetCore.Http;
using System.Collections.Generic;

namespace xAiApi.Interfaces
{
    /// <summary>
    /// Describe a Base Service Actions of any Ai Based Services ...
    /// </summary>
    public interface IXAiServiceBase : IDisposable
    {
        /// <summary>
        /// Chat Options ...
        /// </summary>
        ChatOptions Options { get; }

        /// <summary>
        /// Descriptor of Models which used in Service ...
        /// </summary>
        XAiModelDescriptor Descriptor { get; }

        //
        #region Actions ...
        /// <summary>
        /// Base Method for Communicate with LLM ...
        /// </summary>
        /// <param name="prompt"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<string> AskTextAsync(
            string prompt,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Base Method for Communicate with LLM ...
        /// </summary>
        /// <param name="prompt"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        IAsyncEnumerable<string> AskTextAsEnumerable(
            string prompt,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Get LLM Client instance for Communicating with LLM ...
        /// </summary>
        /// <returns></returns>
        IChatClient GetClient();

        /// <summary>
        /// Create Custom HttpClient for Communicating with LLM API ...
        /// </summary>
        /// <param name="url"></param>
        /// <returns></returns>
        HttpClient GetHttpClient(string url = null);

        /// <summary>
        /// Prepare a Message History List for LLM Communication based on Prompt ...
        /// </summary>
        /// <param name="prompt"></param>
        /// <param name="forcePrompt"></param>
        /// <returns></returns>
        IList<ChatMessage> GetHistory(
            string prompt = null,
            bool forcePrompt = true
        );

        /// <summary>
        /// Prepare a Message History List for LLM Communication based on Prompt ...
        /// </summary>
        /// <param name="message"></param>
        /// <param name="forceMessage"></param>
        /// <returns></returns>
        IList<ChatMessage> GetHistory(
            ChatMessage message = null,
            bool forceMessage = true
        );
        #endregion

        //
        #region Data Provider Based Actions ...
        /// <summary>
        /// Load AI Projects ...
        /// </summary>
        /// <param name="ownerId"></param>
        /// <param name="connectionId"></param>
        /// <param name="includeDefaults"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XAiProjectDto>> LoadProjects(
            string ownerId,
            string connectionId = null,
            bool includeDefaults = false,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Load Conversations of Specified AI Project ...
        /// </summary>
        /// <param name="projectId"></param>
        /// <param name="connectionId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XAiConversationDto>> LoadConversations(
            Guid projectId,
            string connectionId = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Load Messages of Specified Conversation ...
        /// </summary>
        /// <param name="conversationId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XAiMessageDto>> LoadMessages(
            Guid conversationId,
            CancellationToken cancellationToken = default
        );
        
        /// <summary>
        /// Query Projects ...
        /// </summary>
        /// <param name="ownerId"></param>
        /// <param name="query"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XQueryResult<XAiProjectDto>> QueryProjects(
            string ownerId,
            XQuery query,
            CancellationToken cancellationToken = default
        );
        
        /// <summary>
        /// Query Conversations ...
        /// </summary>
        /// <param name="ownerId"></param>
        /// <param name="projectId"></param>
        /// <param name="query"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XQueryResult<XAiConversationDto>> QueryConversations(
            string ownerId,
            Guid projectId,
            XQuery query,
            CancellationToken cancellationToken = default
        );
        
        /// <summary>
        /// Query Messages ...
        /// </summary>
        /// <param name="ownerId"></param>
        /// <param name="conversationId"></param>
        /// <param name="query"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XQueryResult<XAiMessageDto>> QueryMessages(
            string ownerId,
            Guid conversationId,
            XQuery query,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Create an AI Project ...
        /// </summary>
        /// <param name="ownerId"></param>
        /// <param name="item"></param>
        /// <param name="connectionId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XAiProjectDto> CreateProject(
            string ownerId,
            XAiProjectDto item,
            string connectionId = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Create an AI Conversation ...
        /// </summary>
        /// <param name="ownerId"></param>
        /// <param name="projectId"></param>
        /// <param name="item"></param>
        /// <param name="connectionId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XAiConversationDto> CreateConversation(
            string ownerId,
            Guid projectId,
            XAiConversationDto item,
            string connectionId = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Ask a Question as Prompt and Retrieve Response ...
        /// </summary>
        /// <param name="prompt"></param>
        /// <param name="ownerId"></param>
        /// <param name="projectId"></param>
        /// <param name="conversationId"></param>
        /// <param name="connectionId"></param>
        /// <param name="files"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XAiMessageDto> AskAsync(
            string prompt,
            string ownerId,
            Guid projectId,
            Guid conversationId,
            string connectionId = null,
            IFormFileCollection files = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Ask a Question as Prompt and Retrieve Response as Async Enumerable ...
        /// </summary>
        /// <param name="prompt"></param>
        /// <param name="ownerId"></param>
        /// <param name="projectId"></param>
        /// <param name="conversationId"></param>
        /// <param name="connectionId"></param>
        /// <param name="files"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        IAsyncEnumerable<XAiResonseMessage> AskAsEnumerable(
            string prompt,
            string ownerId,
            Guid projectId,
            Guid conversationId,
            string connectionId = null,
            IFormFileCollection files = null,
            CancellationToken cancellationToken = default
        );
        #endregion
    }
}