Turn every dollar into opportunity!

BuckBounty is an AI-powered personal finance assistant that maximizes savings through intelligent credit card reward optimization, automated deal discovery, and personalized wealth-building strategies.

The average American leaves over $3,000 on the table every year through:

• Suboptimal credit card usage (wrong cards for wrong categories)
• Missed promotional deals and coupons
• Lack of financial awareness and poor spending decisions
• Not investing saved money for wealth building

Traditional budgeting apps just show you numbers—they don't actively help you make money.

BuckBounty solves this by combining AI-powered transaction analysis, multi-agent orchestration, and advanced retrieval techniques to turn your spending into savings and wealth.

• MARK (Main Agent): Orchestrates user queries, provides financial advice, budget analysis
• BountyHunter1: Automated coupon scraping from Gmail, Honey, Rakuten (cron-based)
• BountyHunter2: Personalized financial news aggregation from Yahoo Finance (24-hour cycles)

• Analyzes spending patterns across 10+ categories
• Recommends optimal credit cards for maximum rewards
• Calculates annual savings potential (up to $2,400/year)

• @ Mentions: @Starbucks instantly analyzes merchant-specific spending and finds coupons
• Voice Interface: Speech-to-text input + ElevenLabs TTS output for hands-free control
• Bill Splitting: Gemini Vision scans receipts and auto-splits via Stripe
• Investment Advisor: Converts savings into personalized portfolios with 10-year projections
• PolyMarket Integration: Prediction market analysis with risk assessment

• Radar charts comparing current vs previous month spending
• Pie charts for category breakdown
• Real-time budget tracking with overspending alerts
• Transaction search with semantic understanding

BuckBounty uses a novel dual-index architecture with FAISS for optimal retrieval speed:

┌─────────────────────────────────────────────┐
│         Transaction Ingestion               │
│    (Plaid API → Embedding → Vector DB)      │
└──────────────┬──────────────────────────────┘
               │
               ▼
       ┌───────────────┐
       │  Current Month │ → FLAT Index (Exact Search, <50ms)
       └───────┬────────┘
               │ Auto-migration after 30 days
               ▼
       ┌───────────────┐
       │  Historical    │ → HNSW Index (Approximate NN, scales to millions)
       └────────────────┘

Why This Matters:

• 2x faster than traditional single-index systems
• FLAT index: Perfect accuracy for recent transactions (most queries)
• HNSW index: Memory-efficient for historical data (infrequent queries)
• Automatic migration keeps both indices optimized

User Query → Hash with Embeddings → Check Redis Cache
                                          ↓
                                    Cache Hit? (50ms)
                                          │
                                          ├─ Yes → Return cached response
                                          │
                                          └─ No → Call Gemini API (2.5s)
                                                  ↓
                                            Store in Redis with TTL
                                                  ↓
                                            Return response

Performance Gains:

• 50x speedup on repeated queries (<50ms vs 2.5s)
• 70% reduction in API costs
• Semantic cache matching (similar questions hit same cache)
• UI indicators show time saved from cache hits

BuckBounty processes multiple data modalities:

1. Text: Natural language queries via Gemini
2. Voice: Web Speech API (input) + ElevenLabs (output)
3. Vision: Gemini Vision for receipt scanning
4. Structured Data: Transaction JSON, budget data, coupon databases
5. Time-Series: Historical spending patterns for trend analysis

Cron Jobs (Backend Scheduling)
    │
    ├─ BountyHunter1: Every 6 hours
    │     ↓
    │  Gmail API + Web Scraping (Honey, Rakuten)
    │     ↓
    │  Extract coupons → Generate embeddings
    │     ↓
    │  Store in JSON + Vector DB
    │
    └─ BountyHunter2: Every 24 hours
          ↓
       Yahoo Finance API (personalized by spending categories)
          ↓
       Fetch market news + trends
          ↓
       Store in JSON with metadata

Benefits:

• No blocking on main user queries
• Always-fresh data without user intervention
• Pre-processed embeddings for instant RAG retrieval

• Framework: Next.js 14 with App Router, React 18, TypeScript
• UI Components: ShadCN UI (Radix primitives), Tailwind CSS
• Visualizations: Recharts (Radar, Pie charts)
• 3D Graphics: Vanta.js for animated backgrounds
• State Management: Zustand
• Banking: Plaid Link (react-plaid-link)
• Voice: Web Speech API (STT), ElevenLabs API (TTS)

• Framework: FastAPI + Uvicorn (Python 3.11)
• LLM/AI:
  • Google Gemini (text generation, embeddings, vision)
  • OpenAI (fallback LLM support)
  • Sentence Transformers (local embeddings: all-MiniLM-L6-v2)
• Vector Database: FAISS (FLAT + HNSW dual indexing)
• Caching: Redis (response cache, conversation history)
• Payment: Stripe API (bill splitting)
• Banking: Plaid API (transaction syncing)
• Web Scraping: BeautifulSoup, Selenium (coupon aggregation)

• Transactions: FAISS vector DB with metadata
• Coupons: Versioned JSON files with embeddings
• Finance News: JSON with category tagging
• Cache: Redis with TTL expiration
• Budgets: Embedded in vector DB

• Node.js 18+ and npm
• Python 3.11+
• Redis server (local or cloud)
• Git

git clone https://github.com/yourusername/buckbounty.git
cd buckbounty

Copy the example environment file and fill in your API keys:

cp .env.example .env

Edit .env with your credentials:

# LLM APIs
GEMINI_API_KEY=your_gemini_api_key_here

# Financial APIs
PLAID_CLIENT_ID=your_plaid_client_id
PLAID_SECRET=your_plaid_sandbox_secret
STRIPE_API_KEY=your_stripe_test_key

# Application
NEXT_PUBLIC_API_URL=http://localhost:8000
PORT=8000

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Mac/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start Redis (in a separate terminal)
redis-server

# Run the FastAPI server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Backend will be available at http://localhost:8000

# From project root
npm install

# Run development server
npm run dev

Frontend will be available at http://localhost:3000

1. Navigate to http://localhost:3000
2. Click "Connect Your Bank Account"
3. Follow Plaid Link flow (use Plaid Sandbox credentials for testing)
4. Start chatting with MARK!

We provide a complete Docker setup with frontend, backend, and Redis:

# Build and start all services
docker-compose up --build

# Run in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

Services:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• Redis: localhost:6379 (internal)

Backend:

cd backend
docker build -t buckbounty-backend .
docker run -p 8000:8000 --env-file ../.env buckbounty-backend

Frontend:

docker build -t buckbounty-frontend .
docker run -p 3000:3000 --env-file .env buckbounty-frontend

For production (AWS, GCP, Azure):

1. Update environment variables with production API keys
2. Set up Redis (AWS ElastiCache, Redis Cloud, etc.)
3. Configure CORS in backend/main.py
4. Enable HTTPS (use nginx reverse proxy or cloud load balancer)
5. Scale horizontally using Kubernetes or ECS

Example production URLs:

NEXT_PUBLIC_API_URL=https://api.buckbounty.com
REDIS_URL=redis://production-redis:6379

1. Google Gemini (Free tier available)

   • Get key: https://makersuite.google.com/app/apikey
   • Used for: LLM reasoning, embeddings, vision

2. Plaid (Free sandbox)

   • Sign up: https://dashboard.plaid.com/signup
   • Get sandbox credentials
   • Used for: Bank connections, transactions

3. Stripe (Free test mode)

   • Sign up: https://dashboard.stripe.com/register
   • Get test API key
   • Used for: Bill splitting payments

4. ElevenLabs (Free tier: 10k characters/month)

   • Sign up: https://elevenlabs.io
   • Used for: High-quality text-to-speech

5. Gmail API (Free)

   • Enable in Google Cloud Console
   • Used for: Coupon email extraction

User: "Maximize my savings"
MARK: Analyzes spending across categories
      → Recommends best credit cards
      → Shows annual savings: $2,400
      → Generates investment portfolio from savings

User: "@Starbucks"
MARK: Total spent: $347.82 (23 transactions)
      Average: $15.12 per visit
      Available coupons: 2 promo codes
      Suggestion: Try local coffee shop (save 40%)

User: "Can I afford AirPods Pro 2 ($249)?"
MARK: Current month spending: $1,847
      Remaining budget: $653
      Recommendation: YES (within 10% safe purchase rule)
      Alternative: Klarna 4 payments of $62.25

User: [Speaks] "What did I spend on food last month?"
MARK: [Voice response] "You spent $487 on food delivery
       and $312 on groceries. I found 3 active DoorDash
       coupons that could save you 20% on your next order."

cd backend
pytest

# Test MARK agent
python -m agents.mark_agent

# Test mention handler
python test_mention_handler.py

npm run lint
npm run build

buckbounty/
├── app/                          # Next.js app directory
│   ├── page.tsx                 # Main landing page
│   ├── layout.tsx               # Root layout
│   └── globals.css              # Global styles
├── components/                   # React components
│   ├── ChatInterface.tsx        # AI chat UI
│   ├── Dashboard.tsx            # Financial dashboard
│   ├── TransactionList.tsx      # Transaction table
│   ├── PlaidLink.tsx           # Bank connection
│   └── ui/                      # ShadCN components
├── backend/                      # FastAPI backend
│   ├── main.py                  # API server entry
│   ├── agents/
│   │   ├── mark_agent.py       # Main orchestrator
│   │   ├── bounty_hunter_1.py  # Coupon scraper
│   │   └── bounty_hunter_2.py  # Finance news
│   ├── vector_db.py            # FAISS wrapper
│   ├── rag_service.py          # Dual-index RAG
│   ├── redis_cache.py          # Caching layer
│   ├── credit_card_optimizer.py
│   ├── investment_advisor.py
│   ├── mention_handler.py      # @ mention processing
│   └── data/
│       ├── coupons/            # Scraped coupon JSON
│       └── finance_news/       # News JSON
├── docker-compose.yml           # Multi-service orchestration
├── Dockerfile                   # Frontend container
├── backend/Dockerfile           # Backend container
├── .env.example                 # Environment template
└── README.md                    # This file

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Plaid for making bank integration accessible
• Google Gemini for powerful multimodal AI
• ElevenLabs for natural voice synthesis
• Vercel for Next.js and deployment platform
• ShadCN for beautiful UI components

Project Maintainer: [Your Name]

• Email: your.email@example.com
• Twitter: @yourusername
• LinkedIn: [Your Profile]

Project Link: https://github.com/yourusername/buckbounty

Check out our roadmap:

• Machine learning budget predictions
• Tax optimization agent
• Automated bill negotiation
• Mobile app (React Native)
• Cryptocurrency portfolio tracking
• International banking support
• Social spending leaderboards

Turn every dollar into opportunity with BuckBounty! 💰