starcoach-hackathon/zarinpal-analytics-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: rank growth events with grounded evidence

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-22 18:44:59 +08:00
parent 7f9c16be4b
commit 1a8a61cfe7
20 changed files with 2555 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/decisions/0015-deterministic-ai-growth-reports.md
View File

@@ -5,15 +5,30 @@
## Context
Growth forecasting, event uplift, low-period detection, and peer comparisons must be reproducible, testable, privacy-safe, and available when an AI provider is unavailable. AvalAI adds value for semantic prioritization and natural Persian campaign guidance, but must not become the source of financial analytics.
Growth forecasting, event uplift, low-period detection, and peer comparisons must be reproducible, testable, privacy-safe, and available when an AI provider is unavailable. Merchants also need a ranked view of three upcoming occasions and a personalized explanation grounded in their own comparable history when it exists. AvalAI adds value for semantic prioritization and natural Persian campaign guidance, but must not become the source of financial analytics or present general business-profile relevance as prior experience.
## Decision
Use PostgreSQL plus deterministic Go analytics as the sole authority for numbers and evidence. Run a bounded backend-only AvalAI Responses workflow over sanitized aggregates, validate its structured qualitative output, and persist report snapshots by a versioned data fingerprint. Use Redis only for hot caching, coordination, budgets, and rate limits. Defer MCP; keep a narrow internal tool interface that an MCP adapter may wrap only when multiple independent agent clients exist.
For event recommendations, use this evidence precedence:
1. Select the most recent completed catalog occurrence with the exact same stable `occasion_key` and `event_variant` as the upcoming event.
2. Accept its deterministic effect only when the established completeness, observation-count, and baseline-session thresholds pass.
3. Otherwise use current onboarding category, description/niches, and sales-channel matches as visibly labeled business-profile evidence.
Do not substitute an operational holiday window for a demand/campaign window, or a similar-family event for an exact occurrence. Deterministic code owns prior-window dates, counts, money, uplift BPS, material direction, and all other financial/performance metrics.
AvalAI may rank three known candidate evidence ids and return an integer `priorityPercent`, stance, and qualitative Persian reason. The percentages represent relative planning attention only, never probability, predicted growth, uplift, expected revenue, or a guarantee. Validation requires three distinct known ids, positive shares descending with rank, and a sum of exactly 100. AI prose remains prohibited from introducing numeric performance claims and cannot claim profile evidence when eligible historical evidence exists.
On invalid output, provider failure, or budget exhaustion, deterministic ranking prefers eligible historical evidence and then reviewed catalog importance/relevance/confidence plus profile matches. Largest-remainder normalization guarantees a 100-percent collection (`34/33/33` for equal scores); deterministic evidence also supplies stance and Persian fallback reasoning.
## Consequences
- The growth page remains useful with AI disabled, unavailable, rate-limited, or rejected.
- Repeated page visits do not create paid calls while the fingerprint is unchanged.
- Algorithm, catalog, prompt, schema, model, or import changes intentionally invalidate the report.
- The backend owns more deterministic forecasting and validation code, but the result is auditable and tenant-safe.
- A high planning share may represent either an opportunity or a risk requiring preparation; stance carries that distinction.
- Reviewed event catalogs must use year-free canonical occasion keys, distinct variants for campaign and operational windows, and honest per-year coverage so historical matching remains auditable.
- Campaign and operational variants of the same holiday share one canonical occasion key. Product-defined date windows cite a reviewed internal derivation policy rather than attributing the custom range to a source that only documents the occasion, and review-placeholder checksums block approval and activation.