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

fix: deliver validated AI insight responses

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-22 15:47:38 +08:00
parent ca55c2fb3d
commit 3fba4261ee
68 changed files with 6870 additions and 493 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/GROWTH-ANALYST-SPEC.md
View File

@@ -21,11 +21,11 @@ Give an authenticated merchant a trustworthy 90-day Persian growth outlook: hist
## AI boundary
- AvalAI is backend-only and receives minimized aggregate evidence, never raw transactions, payer keys, credentials, arbitrary merchant ids, SQL, or peer rows.
- AvalAI is backend-only and receives five sanitized, chronologically upcoming events from the active reviewed calendar plus non-identifying merchant category/niche/channel context. It never receives raw transactions, payer keys, credentials, merchant ids, SQL, or peer rows.
- The consumer-owned `GrowthAnalyticsTools` boundary exposes only `get_growth_context`, `get_event_evidence`, `get_peer_context`, and `get_campaign_playbook`. Scope is injected from the authenticated job, not accepted from model arguments.
- Use `POST /v1/responses`, `store:false`, strict function schemas, strict structured output, `parallel_tool_calls:false`, no more than four tool calls and two model turns, 1,600 output tokens, a 30-second deadline, and one transient retry.
- Treat model output as untrusted. Accept only known evidence ids and qualitative Persian fields. Reject numeric claims, unsafe language, unknown references, refusal/incomplete output, or schema drift and use deterministic Persian fallback copy.
- Skip AvalAI when no material opportunity/risk exists or there are no historical observations. Low-confidence evidence may be interpreted, but the response must preserve its limitation. AI failure produces `PARTIAL`, never an empty report.
- The model selects exactly three distinct candidate evidence ids and returns one short qualitative Persian relevance reason per event; it cannot introduce dates, quantities, or event facts. Invalid output or provider failure produces `PARTIAL` with the first three chronological reviewed events and deterministic reasons.
## Persistence, caching, jobs, and limits
@@ -43,7 +43,7 @@ Give an authenticated merchant a trustworthy 90-day Persian growth outlook: hist
- `GET /api/v1/analytics/growth-reports/latest?terminalId=...` returns the latest authorized scope report.
- `GET /api/v1/analytics/growth-reports/{reportId}` returns an owned report; absent and cross-tenant ids are indistinguishable.
- `GET /api/v1/analytics/growth-reports/{reportId}/events` is authenticated SSE with stable ids, heartbeat, replay/snapshot recovery, and terminal status.
- Responses include deterministic series/ranges/confidence/evidence, opportunities, risks, peer result or suppression reason, validated briefs, cache metadata, and next refresh time.
- Responses include the five deterministic calendar candidates, exactly three validated AI-ranked event recommendations (or deterministic fallback), cache metadata, and next refresh time.
## Boundaries and acceptance