using IntelligenceApi.Models;

namespace IntelligenceApi.Engines;

/// <summary>
/// Contract for all spend distribution engines.
///
/// Each engine encapsulates the logic for recommending how a client should
/// distribute their ad budget across providers. Engines vary by client category:
///
///   General      — rules-based scoring (default, free tier)
///   Franchisee   — location-aware, franchise-specific signals (premium)
///   Franchisor   — network-wide co-op budget management (premium)
///   FoodFranchisee — geo density, competitor proximity, demographics (AI-driven)
///
/// The contract is intentionally narrow: one method in, one model out.
/// Each engine can call external APIs, ML models, or run local logic —
/// the caller doesn't need to know which.
/// </summary>
public interface ISpendDistributionEngine
{
    /// <summary>
    /// Human-readable name for logging, metadata, and billing attribution.
    /// e.g. "General", "Franchisee", "FoodFranchisee"
    /// </summary>
    string EngineName { get; }

    /// <summary>
    /// Generate a spend distribution recommendation for the given request.
    /// Must never throw — return a valid response with reduced confidence on errors.
    /// </summary>
    Task<SpendDistributionResponse> RecommendAsync(
        SpendDistributionRequest request,
        CancellationToken ct);
}