PayPilot AI — Intelligent Payment & Finance Assistant

An AI-powered payment intelligence workspace that helps small businesses understand payment health, identify anomalies, diagnose failed payments, forecast cash flow, and get explainable next-best actions from their transaction data.

Why PayPilot AI?

Small merchants often have payment data but not enough time or analytical support to answer questions such as:

• Why did payment success rate drop today?
• Which failed payments should I investigate first?
• Are there suspicious or unusual transactions?
• What is my expected cash inflow over the next few days?
• Which payment method is causing the most failures?
• What action should I take next, and why?

PayPilot AI turns raw payment records into explainable, bounded and auditable recommendations instead of just charts.

Core Features

• Payment Health Dashboard — volume, success rate, failure rate, total processed value and method-level breakdown.
• AI Anomaly Detection — Isolation Forest identifies unusual payments using amount, time, method and status features.
• Failure Diagnosis — ranks failure reasons and produces practical recovery suggestions.
• Cash-Flow Forecasting — simple ML-based forecast from historical successful payments.
• Natural-Language Finance Assistant — asks questions such as “Why are payments failing?” or “What should I investigate first?”.
• Razorpay Test-Mode Connector — optionally fetches payment records from GET /v1/payments using test API keys.
• Explainability & Audit Trail — every assistant response records the data context, source and timestamp.
• Graceful Fallbacks — the product runs fully on bundled demo data even without Razorpay or LLM credentials.

Architecture

flowchart LR
    A[Razorpay Test Mode\nor Demo CSV] --> B[Ingestion Layer]
    B --> C[FastAPI Backend]
    C --> D[Analytics Engine]
    C --> E[Anomaly Detection]
    C --> F[Forecast Engine]
    D --> G[AI Assistant]
    E --> G
    F --> G
    G --> H[Streamlit Dashboard]
    C --> I[(Audit Log)]

Loading

See docs/architecture.md for the detailed architecture and design decisions.

Tech Stack

Layer	Technology
Frontend	Streamlit
API	FastAPI + Uvicorn
Data	Pandas + CSV
ML	scikit-learn
AI narration	Optional OpenAI-compatible chat-completions endpoint
Payment integration	Razorpay Test Mode REST API
Testing	Pytest
CI	GitHub Actions
Containerization	Docker / Docker Compose

Repository Structure

paypilot-ai/
├── app/
│   ├── main.py
│   └── services/
│       ├── analytics.py
│       ├── assistant.py
│       ├── audit.py
│       ├── data.py
│       ├── ml.py
│       └── razorpay.py
├── frontend/
│   └── dashboard.py
├── data/
│   └── sample_transactions.csv
├── docs/
│   ├── architecture.md
│   ├── ai-design.md
│   ├── evaluation.md
│   ├── failure-handling.md
│   └── pitch-script.md
├── scripts/
│   └── seed_data.py
├── tests/
│   ├── test_analytics.py
│   └── test_api.py
├── .github/workflows/ci.yml
├── .env.example
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── SECURITY.md
├── CONTRIBUTING.md
└── LICENSE

Quick Start

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/paypilot-ai.git
cd paypilot-ai

2. Create a virtual environment

Windows PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1

macOS / Linux

python -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Create environment file

cp .env.example .env

On Windows, you can simply copy .env.example to .env.

5. Generate demo data

python scripts/seed_data.py

6. Run the API

uvicorn app.main:app --reload --port 8000

Open API docs at: http://localhost:8000/docs

7. Run the dashboard

In a second terminal:

streamlit run frontend/dashboard.py

The Streamlit URL will be printed in your terminal, usually http://localhost:8501.

Optional: Connect Razorpay Test Mode

PayPilot supports Razorpay test-mode payment data. Create Test Mode API keys in the Razorpay Dashboard and put them only in your local .env file:

RAZORPAY_KEY_ID=rzp_test_xxxxxxxxxx
RAZORPAY_KEY_SECRET=your_test_secret

Then call:

curl -X POST http://localhost:8000/api/razorpay/sync

Never commit API secrets. .env is excluded by .gitignore.

Optional: Enable LLM Narration

PayPilot's core analytics works without any external AI API. If you want richer natural-language responses, configure any OpenAI-compatible provider:

LLM_API_KEY=your_key
LLM_BASE_URL=https://your-provider.example/v1
LLM_MODEL=your-model-name

If these variables are absent or the provider fails, PayPilot automatically falls back to deterministic explainable responses.

API Endpoints

Method	Endpoint	Purpose
GET	/health	Health check
GET	/api/transactions	List transaction data
GET	/api/analytics/summary	Payment KPIs and failure breakdown
GET	/api/analytics/anomalies	Detect unusual transactions
GET	/api/analytics/forecast	Forecast successful payment value
POST	/api/assistant/query	Ask finance/payment questions
POST	/api/razorpay/sync	Fetch Razorpay test-mode payments
GET	/api/audit	View assistant audit history

Demo Questions

Try these in the AI Assistant page:

• Why are payments failing?
• Which payment method has the lowest success rate?
• Show me suspicious transactions.
• What is the expected payment value for the next 7 days?
• What should the merchant investigate first?

Reliability and Safety Design

PayPilot intentionally separates analysis from money movement:

• The assistant is read-only and never initiates a debit, refund, capture or payout.
• Recommendations include the reason/data behind the suggestion.
• Missing API keys fall back to demo data instead of crashing.
• Failed LLM calls fall back to deterministic analytics.
• API secrets are loaded from environment variables only.
• Audit records make assistant behavior reviewable.

See docs/failure-handling.md.

Evaluation

The project includes measurable checks for:

• Success/failure aggregation correctness
• Anomaly detection coverage
• Forecast availability
• API health and response format
• Failure-mode behavior

Run tests:

pytest -q

See docs/evaluation.md for suggested demo metrics and how to report them honestly.

What Broke and How I Fixed It

A strong project should document iteration, not pretend everything worked first time. This repository includes a ready-to-customize breakdown in docs/failure-handling.md, covering examples such as:

1. Sparse transaction history produced unstable forecasts → added minimum-data checks and fallback estimates.
2. Anomaly models over-flagged very large legitimate payments → included method/status/time features and exposed anomaly score instead of auto-blocking.
3. External LLM/API outages made the assistant unreliable → added deterministic fallback responses.
4. Payment API credentials may be missing/invalid → app continues in demo mode and returns a clear integration error.

Replace these notes with the exact issues you personally encounter while testing.

5-Minute Pitch

A complete pitch outline is included in docs/pitch-script.md:

1. Problem
2. Product
3. Architecture
4. Live demo
5. AI/ML decisions
6. Failure handling
7. Results and next steps

Screenshots to Add Before Submission

Create docs/screenshots/ and add real screenshots of:

1. Dashboard overview
2. Payment failure analysis
3. Anomaly detection result
4. Cash-flow forecast
5. AI assistant response
6. FastAPI Swagger page
7. Successful Razorpay test-mode sync (if configured)
8. Passing pytest output

Future Improvements

• Webhook-driven real-time payment updates
• Merchant-specific learned baselines
• Failed-payment recovery prioritization model
• Settlement/reconciliation assistant
• Role-based access control
• Persistent database (PostgreSQL)
• Evaluation dashboard with precision/recall and forecast error
• Human approval workflow before any future financial action

License

MIT License. See LICENSE.