https://github.com/ummtushar/bunq-hackathon
Multi-Agentic LangGraph Recommender System for sending Notifications for saving money
https://github.com/ummtushar/bunq-hackathon
bunq bunq-api fastapi langchain langgraph llm multi-agent-systems openai
Last synced: 8 months ago
JSON representation
Multi-Agentic LangGraph Recommender System for sending Notifications for saving money
- Host: GitHub
- URL: https://github.com/ummtushar/bunq-hackathon
- Owner: ummtushar
- License: apache-2.0
- Created: 2025-05-02T18:31:44.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-30T08:49:38.000Z (about 1 year ago)
- Last Synced: 2025-06-30T02:39:57.764Z (12 months ago)
- Topics: bunq, bunq-api, fastapi, langchain, langgraph, llm, multi-agent-systems, openai
- Language: Python
- Homepage: https://devpost.com/software/bunqsplit-mila
- Size: 2.95 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# bunq Hackathon 6.0
I built an end to end multi-agent AI implementation for automated notifactions on your phone that give you advice to save money based on your last week's transactions.
## Check out the submission at Devpost
https://devpost.com/software/bunqsplit-mila
# Financial Transaction Analysis System
A multi-agent AI system that analyzes bank transaction data (specifically Bunq format) and provides personalized money-saving recommendations using LangGraph, OpenAI/NVIDIA models, and web search capabilities.
## 🎯 Overview
This system processes multiple bank transaction JSON files and employs a coordinated team of AI agents to:
- **Classify** transactions by brand, category, and subscription type
- **Analyze** spending patterns and identify savings opportunities
- **Research** cheaper alternatives and money-saving strategies
- **Recommend** specific, actionable steps to reduce expenses
## 🏗️ Architecture
The system uses a **supervisor-worker pattern** with specialized agents:
### Agent Responsibilities
1. **Supervisor**: Orchestrates the workflow and routes tasks to appropriate agents
2. **Classifier**: Identifies brands, product categories, subscription status, and transaction frequency
3. **PatternAnalyzer**: Detects spending patterns, outliers, and potential savings opportunities
4. **Researcher**: Uses web search to find cheaper alternatives and money-saving strategies
5. **Recommender**: Generates final, actionable recommendations based on all collected data
## 🚀 Setup and Installation
### Prerequisites
- Python 3.8+
- API keys for:
- NVIDIA AI Endpoints
- Tavily Search
- OpenAI
### Installation
1. **Clone or download the script**
2. **Install dependencies**:
```bash
pip install python-dotenv langchain-community langchain-core langchain-nvidia-ai-endpoints langgraph langchain-tavily langchain-openai typing-extensions
```
3. Set up environment variables: Create a ```.env``` file in the project directory:
```
NVIDIA_API_KEY=your_nvidia_api_key_here
TAVILY_API_KEY=your_tavily_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
```
## 📁 Input Data Format
Bunq Transaction JSON Structure
The system expects JSON files in Bunq bank format:
```
{
"Response": [
{
"Payment": {
"id": 12345,
"created": "2024-01-15 10:30:00",
"amount": {
"value": "-15.50",
"currency": "EUR"
},
"description": "McDonald's Payment",
"counterparty_alias": {
"display_name": "McDonald's"
},
"type": "BUNQ",
"sub_type": "PAYMENT"
}
}
]
}
```
## Directory Structure
Place your transaction JSON files in a data/ directory:
```
project/
├── script.py
├── .env
├── data/
│ ├── transaction_1.json
│ ├── transaction_2.json
│ └── transaction_3.json
└── README.md
```
## 🎮 Usage
Basic Usage
```
python script.py
```
The script will automatically:
- Look for JSON files matching data/*.json
- Process all found transaction files
- Run the multi-agent analysis
- Generate recommendations
- Save results to bunq_multiple_analysis_results.json
## Custom File Pattern
Modify the main execution section to use a different file pattern:
```
if __name__ == "__main__":
# Custom pattern examples:
analyze_multiple_bunq_transactions("transactions/*.json")
analyze_multiple_bunq_transactions("data/january_*.json")
analyze_multiple_bunq_transactions("specific_file.json")
```
## 📊 Output
Console Output
The system provides real-time progress updates:
```
Looking for Bunq payment data matching data/*.json...
Found 5 files to analyze.
Successfully loaded 5 transactions.
Running analysis through multi-agent system...
Calling Classifier
Classifier: [JSON classification results]
Calling PatternAnalyzer
PatternAnalyzer: [JSON pattern analysis]
Calling Researcher
Researcher: [Research findings on alternatives]
Calling Recommender
Recommender: [Final recommendations]
==================================================
ANALYSIS COMPLETE
==================================================
FINAL RECOMMENDATION:
TL;DR: Save money by cooking at home instead of frequent fast food purchases.
Based on your transaction analysis, I recommend...
```
JSON Output File
Results are saved to bunq_multiple_analysis_results.json:
```
{
"transactions": [...],
"merchant_analysis": {
"McDonald's": {
"total_spent": 45.50,
"transaction_count": 3,
"transactions": [...]
}
},
"classification": {...},
"pattern_analysis": {...},
"research": "...",
"recommendation": "..."
}
```
## ⚙️ Configuration
Model Selection
Switch between LLM providers by uncommenting the desired model:
```
# NVIDIA model
# model = ChatNVIDIA(model="meta/llama-3.3-70b-instruct", temperature=0)
# OpenAI model (default)
model = ChatOpenAI(
model="gpt-4.1-2025-04-14",
temperature=0,
max_tokens=None,
timeout=None,
max_retries=2,
)
```
Search Configuration
Modify search parameters:
```
web_search = TavilySearch(max_results=3) # Adjust max_results as needed
```
Agent Prompts
Customize agent behavior by modifying their prompts in the agent creation section.
## 🔧 Key Functions
- extract_transaction_data(bunq_json_data)
Converts Bunq JSON format to simplified transaction format.
- load_multiple_json_files(file_paths)
Loads and processes multiple transaction JSON files.
- analyze_transactions_by_merchant(transactions)
Groups transactions by merchant and calculates spending totals.
- enrich_transactions_with_history(transactions)
Adds transaction history context for each merchant.
- analyze_multiple_bunq_transactions(json_file_pattern)
Main analysis function that orchestrates the entire process.
## 🛠️ Troubleshooting
Common Issues
- Missing API Keys: Ensure all required API keys are set in .env or environment variables
- No Files Found: Check that JSON files exist in the specified directory and match the glob pattern
- JSON Parse Errors: Verify that transaction files are valid JSON in Bunq format
- Network Issues: Ensure internet connectivity for web search functionality
Debug Mode
Add print statements or logging to track agent execution:
```
print(f"Processing {len(transactions)} transactions...")
```
## 📋 Dependencies
- python-dotenv: Environment variable management
- langchain-community: Document loaders and utilities
- langchain-core: Core LangChain functionality
- langchain-nvidia-ai-endpoints: NVIDIA AI model integration
- langgraph: Multi-agent workflow orchestration
- langchain-tavily: Web search capabilities
- langchain-openai: OpenAI model integration
- typing-extensions: Enhanced type hints
## 🔒 Security Notes
- Store API keys securely in environment variables or .env files
- Never commit API keys to version control
- Consider using API key rotation for production use
- Review transaction data privacy before processing
## 🚀 Future Enhancements
- Support for additional bank formats (beyond Bunq)
- Integration with multiple search providers
- Advanced visualization capabilities
- Real-time transaction monitoring
- Machine learning-based pattern recognition
- Export capabilities (PDF, Excel reports)
- Web interface for easier interaction