Initial import into Gitea

IntelligenceApi/Engines/ISpendDistributionEngine.cs

@@ -0,0 +1,35 @@
+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);
+}