Apppublic

MCP-1st-Birthday/rewardpilot-orchestrator

sourceHugging Faceupdated 9mo agoView on Hugging Face

0likes

App README

Unified API that orchestrates all RewardPilot MCP services to provide intelligent credit card recommendations.

Overview

The Orchestrator calls multiple backend services in parallel to deliver a single, context-aware recommendation:

—Smart Wallet: rewards optimization and alternative card options
—Rewards-RAG: detailed, human-readable card benefits and usage tips
—Spend-Forecast: cap risk analysis and spend projections

Architecture

User → Orchestrator → Smart Wallet (rewards optimization) → Rewards-RAG (card benefits) → Spend-Forecast (cap risk analysis)

Features

—🎯 Smart Recommendations: Optimal card selection based on rewards
—📚 Enhanced Context: Detailed card benefits from RAG
—⚠️ Risk Awareness: Spending cap warnings
—⚡ Fast: Parallel service calls for low latency
—🔄 Resilient: Graceful degradation if any service fails

API

POST /recommend

Get a comprehensive, orchestrated card recommendation for a single transaction.

Request:

json

{
  "user_id": "u_alice",
  "merchant": "Whole Foods",
  "mcc": "5411",
  "amount_usd": 125.50,
  "transaction_date": "2025-01-15"
}

Response:

json

{
  "user_id": "u_alice",
  "merchant": "Whole Foods",
  "amount_usd": 125.5,
  "transaction_date": "2025-01-15",
  "recommended_card": {
    "card_id": "c_chase_sapphire_reserve",
    "card_name": "Chase Sapphire Reserve",
    "reward_rate": 3.0,
    "reward_amount": 376.5,
    "category": "Groceries",
    "reasoning": "Best rewards for this purchase"
  },
  "alternative_cards": ["..."],
  "rag_insights": {
    "card_id": "c_chase_sapphire_reserve",
    "benefits": "3x points on dining and travel...",
    "tips": "Use for grocery purchases to maximize rewards"
  },
  "forecast_warning": {
    "card_id": "c_chase_sapphire_reserve",
    "current_spend": 933.75,
    "cap": 3000.0,
    "projected_spend": 1920.63,
    "cap_risk": false,
    "risk_level": "low",
    "message": "✅ LOW RISK: You're on track..."
  },
  "orchestration_time_ms": 1250.5,
  "services_used": ["smart_wallet", "rewards_rag", "spend_forecast"],
  "final_recommendation": "💳 Recommended Card: Chase Sapphire Reserve..."
}

Other Endpoints

—GET / — Health check
—GET /docs — Interactive API documentation (if enabled)

Configuration

Edit config.py to point to your dependent services:

python

# config.py
SMART_WALLET_URL = "https://your-wallet-space.hf.space"
REWARDS_RAG_URL = "https://your-rag-space.hf.space"
SPEND_FORECAST_URL = "https://your-forecast-space.hf.space"

# Optional timeouts/retries
REQUEST_TIMEOUT_SEC = 10
RETRY_ATTEMPTS = 1

You can also use environment variables (recommended for Spaces):

bash

# In your Space “Secrets” or local env
export SMART_WALLET_URL="https://your-wallet-space.hf.space"
export REWARDS_RAG_URL="https://your-rag-space.hf.space"
export SPEND_FORECAST_URL="https://your-forecast-space.hf.space"

Local Development

Prerequisites:

—Python 3.10+
—pip

Install and run:

bash

pip install -r requirements.txt
uvicorn app:app --reload --port 7860

Test the endpoint:

bash

curl -X POST http://localhost:7860/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "u_alice",
    "merchant": "Whole Foods",
    "mcc": "5411",
    "amount_usd": 125.50,
    "transaction_date": "2025-01-15"
  }'

Deployment

—Hugging Face Spaces:
—This README includes the required front matter (top block) for Spaces.
—Ensure app.py exposes the interface expected by your chosen SDK (here: gradio).
—Set your service URLs as Secrets in the Space settings.

—Docker (alternative):
—If you prefer Docker, provide a Dockerfile and switch the SDK in the front matter to:

    sdk: docker

—Then build and run with your preferred container runtime.

Error Handling & Resilience

—Parallel calls to dependent services with timeouts
—Partial failures degrade gracefully:
—If Rewards-RAG fails, you still get Smart Wallet + Forecast results
—If Forecast fails, you still get Smart Wallet + RAG results
—Responses include servicesused and orchestrationtime_ms for observability

Notes

—MCC category mappings and reward logic live in the Smart Wallet service
—RAG insights summarize benefits and provide usage tips for human readability
—Spend Forecast estimates risk based on current and projected spend relative to caps

License

MIT (or your chosen license)# Force rebuild Thu Jan 8 20:33:16 IST 2026