Vybe Change

<!, Tech Stack Shields, >

🚀 Deployment

• Data Analytics: API & Admin Dashboard
• Mobile App Demo: Vybe Change on Mobile

---

A smart donation layer embedded into BPI's Vybe online banking app. It detects when users are most likely to give, nudges them with localized, hyper-relevant causes, and delivers verified proof when their change creates real-world impact. No spam, no guesswork. Just sense.

This demo showcases:

• Automatic round-up: Every purchase in the Vybe online banking app is rounded up to the nearest tens (e.g., ₱127 → ₱130, donate ₱3). Donation suggestions are agentically determined based on user context, not random or fixed.
• Agentic AI: Likelihood scores and suggested donation amounts are generated by autonomous agents using behavioral, contextual, and historical data—not static values. The system adapts to each user and transaction.
• Explainable AI decisions: Powered by Google Gemini via LangChain, every prompt and recommendation is transparent and human-readable.
• Real-time impact tracking

For technical details, see the agent architecture and code in src/agents/core_agents.py.

🚩 THE CORE IDEA

A smart donation layer embedded into BPI's VIBE payment ecosystem. It detects when users are most likely to give, nudges them with localized, hyper-relevant causes, and delivers verified proof when their change creates real-world impact.

✅ WHAT WE'VE RESOLVED

• 🎯 Integrate via BPI's VIBE, not individual e-commerce stores
• 💸 Donation prompts scale with transaction amount
• 📍 Recommend hyperlocal causes using user region & preferences
• 🧾 Users can opt-in to impact updates, to avoid spamming
• 💯 100% of donations go directly to NGOs, no BPI/partner fees
• 🏆 Year-end impact storytelling is core to user delight
• 📈 Behavioral data (order frequency, timing, confirmation time, etc.) guides donation logic
• 🔗 Must partner directly with NGOs; web scraping is out

📁 Project Structure

vybe-change/
├── README.md # This file - Product Reality Sheet
├── api_server.py # API server for backend integration
├── dashboard.py # Main dashboard logic
├── generate_demo_data.py # Demo data generation
├── model.py # Core ML model for donation likelihood
├── constants/
│ └── ngos.py # NGO database and categories
├── docs/
│ ├── user-journey.md # Detailed user journey mapping
│ ├── agents/ # AI agent specifications
│ └── compliance.md # Legal and regulatory considerations
├── src/
│ ├── agents/ # Core AI agents implementation
│ ├── api/ # API endpoints
│ └── analytics/ # Impact tracking and reporting
├── tests/ # Test suites for all components
└── streamlit_demo.py # Streamlit deployment entrypoint

Tech Stack

• Python for backend and orchestration
• Streamlit for interactive dashboards
• LangChain for agentic AI logic
• Gemini (Google Generative AI) for LLM-powered reasoning and explanations
• Plotly & Pandas for data visualization and analytics
• FastAPI for API endpoints and integration

📡 API Endpoints

Donation & Recommendation

Method	Endpoint	Description
POST	/likelihood/analyze	Analyze donation likelihood
POST	/causes/recommend	Recommend causes for donation
POST	/amounts/optimize	Suggest optimal donation amount
POST	/submit-donation	Submit a donation
GET	/donations	List user donations

User & Profile

Method	Endpoint	Description
POST	/register	Register a new user
GET	/profile	Get user profile
PUT	/profile	Update user profile
DELETE	/profile	Delete user profile
GET	/user/{user_id}/impact-summary	Get user's impact summary

NGO & Causes

Method	Endpoint	Description
GET	/ngos	List NGOs
GET	/ngos/{ngo_id}	Get NGO details
POST	/ngo/{ngo_id}/submit-proof	NGO submits proof of impact
GET	/causes	List available causes

Analytics & Insights

Method	Endpoint	Description
GET	/analytics/dashboard	Analytics dashboard
GET	/metrics/dashboard	Metrics dashboard
GET	/platform/insights	Platform insights
GET	/impact-report	Get impact report

System

Method	Endpoint	Description
GET	/health	Health check

---

🛠️ Developer Quickstart

Prerequisites

• Python 3.10+
• Node.js (if working with frontend or integration)
• pip
• Streamlit (for dashboard)

1. Clone the Repository

git clone https://github.com/smmariquit/vybe-change.git
cd vybe-change

2. Install Python Dependencies

pip install -r requirements.txt

3. Set Up Environment Variables

Create a .env file in the root directory:

GOOGLE_GEMINI_API_KEY=your_api_key_here

4. Run the Streamlit Dashboard

streamlit run streamlit_demo.py

5. Run the API Server (FastAPI)

uvicorn src.api.main:app --reload

6. Run Tests

pytest tests/

---

🧩 Environment & Configuration

• All sensitive keys (e.g., Gemini API) should be stored in .env (never commit secrets).
• See pyproject.toml and requirements.txt for dependencies.
• For custom agent logic, see src/agents/.

📊 Current State of the Code

• Tech Stack: Python
• Repository Size: 38 tracked files
• Latest Update: 044c4c4 chore: add stale issue and PR validators

---

☕ If you found this project useful, you can support my work at kape.stimmie.dev!