README.md

---
title: RewardPilot API
emoji: 💳
colorFrom: green
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# RewardPilot API

FastAPI backend for the RewardPilot mobile app — the deterministic credit-card
scoring engine plus an OpenAI-powered, no-hallucination "why this card" narration.

## Endpoints
- `GET /health` — status + whether the LLM key is configured
- `GET /cards` — card catalogue
- `POST /recommend` — optimal card for a text/structured query (+ LLM narration)
- `POST /voice` — audio → transcript → recommendation (needs OpenAI key)
- `POST /statements/parse` — upload PDF/CSV → normalized transactions
- `POST /transactions/analyze` — were optimal cards used? how much lost?
- `GET /discover/{card_id}` — apply-for details + extra benefits

## Configuration
Set **`OPENAI_API_KEY`** as a Space **secret** (Settings → Variables and secrets).
The key is used only for the natural-language reasoning; the engine computes all
numbers and the ranking deterministically. Without the key the API still works
and returns the deterministic explanation.

The numbers and ranking are never produced by the LLM — the model is constrained
to rephrase the engine's facts, forbidden from stating figures or naming cards
not in the input, and any violating output is discarded server-side.