36 lines
1.3 KiB
C#
36 lines
1.3 KiB
C#
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);
|
|
}
|