{"id":28421729,"url":"https://github.com/ummtushar/bunq-hackathon","last_synced_at":"2025-10-13T05:13:26.252Z","repository":{"id":296364915,"uuid":"976781260","full_name":"ummtushar/bunq-hackathon","owner":"ummtushar","description":"Multi-Agentic LangGraph Recommender System for sending Notifications for saving money","archived":false,"fork":false,"pushed_at":"2025-05-30T08:49:38.000Z","size":3089,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-30T02:39:57.764Z","etag":null,"topics":["bunq","bunq-api","fastapi","langchain","langgraph","llm","multi-agent-systems","openai"],"latest_commit_sha":null,"homepage":"https://devpost.com/software/bunqsplit-mila","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ummtushar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-02T18:31:44.000Z","updated_at":"2025-06-14T23:16:59.000Z","dependencies_parsed_at":"2025-05-30T11:20:09.512Z","dependency_job_id":"4ba8b534-4bee-489a-b0d0-2f232eee3344","html_url":"https://github.com/ummtushar/bunq-hackathon","commit_stats":null,"previous_names":["ummtushar/bunq-hackathon"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ummtushar/bunq-hackathon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ummtushar%2Fbunq-hackathon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ummtushar%2Fbunq-hackathon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ummtushar%2Fbunq-hackathon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ummtushar%2Fbunq-hackathon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ummtushar","download_url":"https://codeload.github.com/ummtushar/bunq-hackathon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ummtushar%2Fbunq-hackathon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013695,"owners_count":26085390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bunq","bunq-api","fastapi","langchain","langgraph","llm","multi-agent-systems","openai"],"created_at":"2025-06-05T06:10:25.518Z","updated_at":"2025-10-13T05:13:26.245Z","avatar_url":"https://github.com/ummtushar.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bunq Hackathon 6.0\nI 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.\n\n## Check out the submission at Devpost\nhttps://devpost.com/software/bunqsplit-mila\n\n# Financial Transaction Analysis System\n\nA 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.\n\n## 🎯 Overview\n\nThis system processes multiple bank transaction JSON files and employs a coordinated team of AI agents to:\n- **Classify** transactions by brand, category, and subscription type\n- **Analyze** spending patterns and identify savings opportunities\n- **Research** cheaper alternatives and money-saving strategies\n- **Recommend** specific, actionable steps to reduce expenses\n\n## 🏗️ Architecture\n\nThe system uses a **supervisor-worker pattern** with specialized agents:\n\n\u003cimg width=\"607\" alt=\"image\" src=\"https://github.com/user-attachments/assets/7ba49f40-d58e-44b9-87d6-95dadba4dc41\" /\u003e\n\n### Agent Responsibilities\n\n1. **Supervisor**: Orchestrates the workflow and routes tasks to appropriate agents\n2. **Classifier**: Identifies brands, product categories, subscription status, and transaction frequency\n3. **PatternAnalyzer**: Detects spending patterns, outliers, and potential savings opportunities\n4. **Researcher**: Uses web search to find cheaper alternatives and money-saving strategies\n5. **Recommender**: Generates final, actionable recommendations based on all collected data\n\n## 🚀 Setup and Installation\n\n### Prerequisites\n\n- Python 3.8+\n- API keys for:\n  - NVIDIA AI Endpoints\n  - Tavily Search\n  - OpenAI\n\n### Installation\n\n1. **Clone or download the script**\n\n2. **Install dependencies**:\n```bash\npip install python-dotenv langchain-community langchain-core langchain-nvidia-ai-endpoints langgraph langchain-tavily langchain-openai typing-extensions\n```\n3. Set up environment variables: Create a ```.env``` file in the project directory:\n```\nNVIDIA_API_KEY=your_nvidia_api_key_here\nTAVILY_API_KEY=your_tavily_api_key_here\nOPENAI_API_KEY=your_openai_api_key_here\n```\n\n## 📁 Input Data Format\nBunq Transaction JSON Structure\nThe system expects JSON files in Bunq bank format:\n\n```\n{\n  \"Response\": [\n    {\n      \"Payment\": {\n        \"id\": 12345,\n        \"created\": \"2024-01-15 10:30:00\",\n        \"amount\": {\n          \"value\": \"-15.50\",\n          \"currency\": \"EUR\"\n        },\n        \"description\": \"McDonald's Payment\",\n        \"counterparty_alias\": {\n          \"display_name\": \"McDonald's\"\n        },\n        \"type\": \"BUNQ\",\n        \"sub_type\": \"PAYMENT\"\n      }\n    }\n  ]\n}\n```\n## Directory Structure\nPlace your transaction JSON files in a data/ directory:\n```\nproject/\n├── script.py\n├── .env\n├── data/\n│   ├── transaction_1.json\n│   ├── transaction_2.json\n│   └── transaction_3.json\n└── README.md\n```\n\n## 🎮 Usage\nBasic Usage\n```\npython script.py\n```\nThe script will automatically:\n\n- Look for JSON files matching data/*.json\n\n- Process all found transaction files\n\n- Run the multi-agent analysis\n\n- Generate recommendations\n\n- Save results to bunq_multiple_analysis_results.json\n\n## Custom File Pattern\n\nModify the main execution section to use a different file pattern:\n```\nif __name__ == \"__main__\":\n    # Custom pattern examples:\n    analyze_multiple_bunq_transactions(\"transactions/*.json\")\n    analyze_multiple_bunq_transactions(\"data/january_*.json\")\n    analyze_multiple_bunq_transactions(\"specific_file.json\")\n```\n\n## 📊 Output\nConsole Output\nThe system provides real-time progress updates:\n\n```\nLooking for Bunq payment data matching data/*.json...\nFound 5 files to analyze.\nSuccessfully loaded 5 transactions.\nRunning analysis through multi-agent system...\n\nCalling Classifier\nClassifier: [JSON classification results]\n\nCalling PatternAnalyzer\nPatternAnalyzer: [JSON pattern analysis]\n\nCalling Researcher\nResearcher: [Research findings on alternatives]\n\nCalling Recommender\nRecommender: [Final recommendations]\n\n==================================================\nANALYSIS COMPLETE\n==================================================\n\nFINAL RECOMMENDATION:\nTL;DR: Save money by cooking at home instead of frequent fast food purchases.\n\nBased on your transaction analysis, I recommend...\n```\n\nJSON Output File\nResults are saved to bunq_multiple_analysis_results.json:\n```\n{\n  \"transactions\": [...],\n  \"merchant_analysis\": {\n    \"McDonald's\": {\n      \"total_spent\": 45.50,\n      \"transaction_count\": 3,\n      \"transactions\": [...]\n    }\n  },\n  \"classification\": {...},\n  \"pattern_analysis\": {...},\n  \"research\": \"...\",\n  \"recommendation\": \"...\"\n}\n```\n\n## ⚙️ Configuration\nModel Selection\nSwitch between LLM providers by uncommenting the desired model:\n```\n# NVIDIA model\n# model = ChatNVIDIA(model=\"meta/llama-3.3-70b-instruct\", temperature=0)\n\n# OpenAI model (default)\nmodel = ChatOpenAI(\n    model=\"gpt-4.1-2025-04-14\",\n    temperature=0,\n    max_tokens=None,\n    timeout=None,\n    max_retries=2,\n)\n```\n\nSearch Configuration\nModify search parameters:\n\n```\nweb_search = TavilySearch(max_results=3)  # Adjust max_results as needed\n```\n\nAgent Prompts\nCustomize agent behavior by modifying their prompts in the agent creation section.\n\n## 🔧 Key Functions\n- extract_transaction_data(bunq_json_data)\nConverts Bunq JSON format to simplified transaction format.\n\n- load_multiple_json_files(file_paths)\nLoads and processes multiple transaction JSON files.\n\n- analyze_transactions_by_merchant(transactions)\nGroups transactions by merchant and calculates spending totals.\n\n- enrich_transactions_with_history(transactions)\nAdds transaction history context for each merchant.\n\n- analyze_multiple_bunq_transactions(json_file_pattern)\nMain analysis function that orchestrates the entire process.\n\n\n## 🛠️ Troubleshooting\nCommon Issues\n- Missing API Keys: Ensure all required API keys are set in .env or environment variables\n\n- No Files Found: Check that JSON files exist in the specified directory and match the glob pattern\n\n- JSON Parse Errors: Verify that transaction files are valid JSON in Bunq format\n\n- Network Issues: Ensure internet connectivity for web search functionality\n\nDebug Mode\nAdd print statements or logging to track agent execution:\n```\nprint(f\"Processing {len(transactions)} transactions...\")\n```\n\n## 📋 Dependencies\n- python-dotenv: Environment variable management\n\n- langchain-community: Document loaders and utilities\n\n- langchain-core: Core LangChain functionality\n\n- langchain-nvidia-ai-endpoints: NVIDIA AI model integration\n\n- langgraph: Multi-agent workflow orchestration\n\n- langchain-tavily: Web search capabilities\n\n- langchain-openai: OpenAI model integration\n\n- typing-extensions: Enhanced type hints\n\n## 🔒 Security Notes\n- Store API keys securely in environment variables or .env files\n\n- Never commit API keys to version control\n\n- Consider using API key rotation for production use\n\n- Review transaction data privacy before processing\n\n## 🚀 Future Enhancements\n- Support for additional bank formats (beyond Bunq)\n\n- Integration with multiple search providers\n\n- Advanced visualization capabilities\n\n- Real-time transaction monitoring\n\n- Machine learning-based pattern recognition\n\n- Export capabilities (PDF, Excel reports)\n\n- Web interface for easier interaction\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fummtushar%2Fbunq-hackathon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fummtushar%2Fbunq-hackathon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fummtushar%2Fbunq-hackathon/lists"}