using GB5Shared.DTO.Framework.Login;
using System.Threading;
using System.Threading.Tasks;

namespace KmsBLL.Sync
{
    /// <summary>
    /// KMS's outbound calls into gbEAI's kms_discovery agent route, built on top of the shared
    /// GB5Shared.ExternalAI.IAIEngineSyncClient transport (same low-level contract EAIAdmin's
    /// EAISyncClient uses — see that class's doc comment for why the two don't share a DI-resolved
    /// instance, only the interface shape). Replaces the three bare "// TODO: Publish Dapr event"
    /// comments in KmDiscoveryBLL.TriggerExtractionJob / KmGovernanceBLL.Publish / .Retire — no
    /// Dapr pub/sub is used anywhere for calling gbEAI, and gbEAI has no Dapr subscriber either.
    ///
    /// Every call is synchronous HTTP, not fire-and-forget — callers decide how to handle a
    /// failure (KmGovernanceBLL treats embed/retire failures as non-fatal to the governance
    /// transition that already committed; see that class for the exact partial-failure handling).
    /// </summary>
    public interface IKmsAISyncClient
    {
        /// <summary>KMS_EXTRACT — kicks off gbEAI's extraction pipeline. Synchronous; gbEAI's
        /// pipeline has no background job runner (confirmed: no Celery import anywhere in
        /// kms_discovery_adapter.py despite TKMJOB.CELERYTASKID existing as a column), so this can
        /// legitimately take minutes for a real document — give it a long timeout
        /// (KMS:AIExtract:TimeoutSeconds, ~600s), not GOP's 120s default.</summary>
        Task<KmsSyncResult> TriggerExtractionAsync(
            int jobId, int domainId, string? sourceText, LoginDTO login, CancellationToken ct = default);

        /// <summary>KMS_EMBED_ARTIFACT — synchronous, response carries gbEAI's Qdrant point_id on
        /// success.</summary>
        Task<KmsSyncResult> EmbedArtifactAsync(
            int artifactId, int domainId, byte artifactType, string content,
            LoginDTO login, CancellationToken ct = default);

        /// <summary>KMS_RETIRE_ARTIFACT — synchronous.</summary>
        Task<KmsSyncResult> RetireArtifactAsync(
            int artifactId, string? qdrantPointId, LoginDTO login, CancellationToken ct = default);
    }
}