An intelligent ATM cash management system that combines Machine Learning forecasting with Retrieval-Augmented Generation (RAG) to predict next-day cash demand and provide intelligent query responses for ATM operations.
This system tackles the critical operational challenge of ATM cash optimization by integrating:
Predictive ML Models (Ridge, Lasso, Random Forest, XGBoost, CatBoost) for next-day demand forecasting Azure-Powered RAG Pipeline for natural language analytics over transactional data Real-time Analytics Dashboard built with Streamlit for operational decision-making Multi-Model Architecture enabling model comparison and ensemble strategies
Reduce cash shortage incidents & Optimize cash float and reduce idle capital Enable real-time operational insights through conversational AI Data-driven refill planning and risk management
Machine Learning & Data Science ComponentTechnologyPurposeCore MLscikit-learn 1.3+Ridge, Lasso, Random ForestGradient BoostingXGBoost 2.0+, CatBoost 1.2+Advanced tree-based modelsFeature Engineeringpandas 2.1+, numpy 1.24+Time-series feature extractionSerializationjoblib, pickleModel persistence Backend & API ComponentTechnologyPurposeAPI FrameworkFastAPI 0.109+RESTful API with async supportServerUvicornASGI serverValidationPydantic 2.5+Request/response validationHTTP Clienthttpx, requestsInter-service communication Azure Cloud Services ServiceModel/SKUPurposeAzure OpenAIgpt-4o-miniChat completion & reasoningAzure OpenAItext-embedding-3-largeDocument embeddings (3072-dim)Azure AI SearchStandard tierSemantic + vector hybrid searchSearch Index 1atm-knowledgeOperational knowledge baseSearch Index 2atm-data-v2Transactional data index Frontend & Visualization ComponentTechnologyPurposeDashboardStreamlit 1.31+Interactive web interfacePlottingPlotly 5.18+Interactive visualizationsStylingCustom CSSProfessional UI/UX DevOps & Utilities
Environment: python-dotenv Timezone: zoneinfo (Asia/Kuwait) Data I/O: openpyxl (Excel support)
Prerequisites bashPython 3.11 or higher Azure subscription (for cloud services) Git 8GB RAM minimum (16GB recommended for model training) Step 1: Clone Repository bashgit clone [(https://github.com/Ziad-ghazaly/ATM_cash_mangement_and_demand/)].git cd ATM_CASH_MANAGEMENT_AND_DEMAND-1 Step 2: Create Virtual Environment bash# Windows python -m venv venv venv\Scripts\activate
python3 -m venv venv source venv/bin/activate Step 3: Install Dependencies bash# Install all required packages pip install -r requirements.txt
AZURE_SEARCH_ENDPOINT=https://your-search.search.windows.net AZURE_SEARCH_API_KEY=your_search_key_here AZURE_SEARCH_INDEX=YOUR_Semantic_Search ATM_DATA_INDEX_V2=Data_Indexes
RAG_API_URL=http://localhost:8000 STREAMLIT_ML_URL=http://localhost:8501 ALLOWED_ORIGINS=http://localhost:8501,http://localhost:8000 Step 5: Setup Azure Resources Option A: Automated Setup (Recommended) bash# Run setup script (creates indices if they don't exist) cd services/RAG_API python setup_indices.py Option B: Manual Setup
Create Azure AI Search resource in Azure Portal Create two indices: atm-knowledge, atm-data-v2 Configure semantic ranking for both indices Deploy Azure OpenAI models (gpt-4o-mini, text-embedding-3-large)
ML Pipeline
- Feature Engineering ATMFeatureEngineer Class (feature_engineering.py): python# Temporal Features
- Year, Month, Day, Quarter, DayOfWeek
- Month_Sin, Month_Cos (cyclic encoding)
- Week_Sin, Week_Cos (cyclic encoding)
- IsWeekend, IsHoliday
Lag Features (historical demand)
- Withdrawals_Lag1, Withdrawals_Lag7
- Deposits_Lag1, Deposits_Lag7
Rolling Statistics (7-day window)
- Withdrawals_RollMean7, Withdrawals_RollStd7
- Deposits_RollMean7, Deposits_RollStd7
Categorical Encoding
- Location (Label Encoded)
- Weather (Label Encoded)
- City (Label Encoded)
**Feature Importance (Random Forest)**:
-
Withdrawals_Lag1 → 32.4%
-
Withdrawals_RollMean7 → 24.1%
-
DayOfWeek → 11.2%
-
Month → 8.7%
-
Location → 6.3%
-
Model Architecture Multi-Model Ensemble (model_loader.py):
-
Training Pipeline bash# Example training workflow (pseudo-code) python train_model.py
--data data/atm_transactions_2024.csv
--target Withdrawals
--test_size 0.2
--models ridge,lasso,rf,xgboost,catboost
--output trained_model/atm_rf_model.pkl Cross-Validation Strategy:
Method: Time-Series Split (5 folds) Metric: RMSE (Root Mean Square Error) Validation: Last 30 days held out
- Prediction API Streamlit Integration: python# Internal ML API (localhost:8501/?ml_api_mode=true) GET /?ml_api_mode=true&atm_id=ATM_001&days_ahead=1
Response: { "success": true, "prediction": { "ATM_ID": "ATM_001", "Predicted_Demand_KD": 2500, "Prediction_Date": "2025-11-03", "Model_Used": "RandomForest", "Confidence": "High (ML Model)" } }
---
## RAG System
### **Architecture Overview**
Search Strategy Hybrid Search Pipeline:
-
Semantic Search (Azure AI Search)
- Query understanding via semantic ranking
- Returns top 30 documents
-
Vector Search (Fallback)
- Embedding similarity (3072-dim)
- Cosine similarity scoring
-
Keyword Search (Final Fallback)
- BM25 ranking
- Exact term matching Azure OpenAI Integration System Prompt (from app.py): python""" You are an ATM cash management expert.
CRITICAL RULES:
- For "how many ATMs" → Count UNIQUE ATM_IDs (use nunique())
- For predictions → Use ML prediction results as PRIMARY source
- For risk → Identify ATMs with risk levels (CRITICAL/HIGH/MEDIUM/LOW)
- For refills → Provide specific amounts in KD per ATM_ID
- Always cite ATM_IDs, cities, and amounts
RESPONSE FORMAT: ANSWER: Direct answer with numbers EVIDENCE: Bullet points with ATM_IDs and values ACTION: Next steps with timing """ Token Management:
Max Input: 128K tokens (GPT-4o-mini) Typical Context: 2-5K tokens (search results + prompt) Max Output: 1200 tokens Temperature: 0.1 (deterministic answers)
API Reference FastAPI Endpoints (services/RAG_API/app.py)
- Health Check httpGET /health
Response 200: { "status": "healthy", "aoai_configured": true, "search_configured": true, "data_loaded": true, "chat_deploy": "gpt-4o-mini", "embed_deploy": "text-embedding-3-large", "data_count": 15420 } 2. Upload Data httpPOST /data/upload Content-Type: application/json
Request Body: { "data": [ { "ATM_ID": "ATM_001", "City": "Hawalli", "Date": "2024-11-01", "Withdrawals": 2500, "Deposits": 300, ... } ] }
Response 200: { "status": "success", "rows": 1000, "indexed_to_search": 1000, "index_name": "atm-data-v2" } 3. Query RAG System httpPOST /query Content-Type: application/json
Request Body: { "query": "Which ATMs need urgent refills?", "atm_id": null, "use_tools": true }
Response 200: { "answer": "Based on current analysis, 12 ATMs require urgent refills...", "sources": [ {"id": "ATM_001_2024-11-01", "score": 0.92, "title": "ATM_001 in Hawalli"} ], "tool_results": { "tool": "refill_suggestion", "results": [ { "ATM_ID": "ATM_015", "refill_kd": 5000, "priority": "URGENT" } ] } } 4. Index Knowledge Document httpPOST /index/document Content-Type: application/json
Request Body: { "content": "ATM refill procedures...", "title": "Refill SOP", "category": "Operations" }
Response 200: { "status": "indexed", "doc_id": "Operations_a3f5b2c1" }
---
### **Exploratory Data Analysis (EDA)**
**In Streamlit Dashboard**:
- Upload CSV → Auto-generates:
- Top 5 ATMs by withdrawals (bar chart)
- City/Location distribution (pie charts)
- Temporal patterns (line charts)
- Transaction frequency heatmaps
**Filtering Options**:
- By City (dropdown)
- By Location Type (dropdown)
- By Year (multi-select)
- By Metric (Withdrawals/Deposits)
### **Model Evaluation**
**Performance Metrics** (example from Random Forest):
Metric Train Test ───────────────────────────────── RMSE 245.32 312.18 MAE 198.77 267.94 R² Score 0.92 0.88 MAPE 8.34% 11.21% Feature Importance Analysis: python# View in Streamlit after model load model_info = st.session_state.model.get_model_info()
- Prediction Workflow User Flow:
Select ATM from dropdown or enter manually Choose "Next Day" or "Specific Date" Click "Generate Prediction" View results:
Predicted demand (KD) Confidence level Model used Download CSV report
Auto-Rounding Logic: python# Realistic cash denominations if prediction < 100 KD: round to nearest 5 KD if prediction < 500 KD: round to nearest 10 KD if prediction >= 500 KD: round to nearest 20 KD 4. A/B Testing Models python# Compare models on same ATM results = {} for model_name in ["Ridge", "RandomForest", "XGBoost"]: model.switch_model(model_name) pred = model.predict(features) results[model_name] = pred
Deployment Development bash# Already covered in Quick Start Production (Docker) Dockerfile (example): dockerfileFROM python:3.11-slim
WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000 8501
CMD ["sh", "-c", "uvicorn services.RAG_API.app:app --host 0.0.0.0 --port 8000 & streamlit run streamlit_app/app.py --server.port 8501 --server.address 0.0.0.0"]
Build & Run:
bashdocker build -t atm-forecasting .
docker run -p 8000:8000 -p 8501:8501 --env-file .env atm-forecasting
Azure Deployment
Option 1: Azure Container Instances
bashaz container create
--resource-group atm-rg
--name atm-app
--image your-acr.azurecr.io/atm-forecasting:latest
--cpu 2 --memory 4
--ports 8000 8501
--environment-variables @.env.azure
Option 2: Azure App Service
bashaz webapp up
--name atm-forecasting-app
--runtime "PYTHON:3.11"
--sku B2
--location eastus
Performance Metrics ML Model Performance ModelRMSE (KD)MAE (KD)R²Training TimeInference (ms)Ridge387.2312.50.820.5s2Lasso392.1318.30.810.4s2RandomForest312.2267.90.8845s15XGBoost298.5251.30.90120s8CatBoost305.7259.10.89180s12 Recommendation: Use XGBoost for production (best accuracy), Ridge for interpretability. RAG System Performance MetricValueQuery Latency (P50)1.2sQuery Latency (P95)2.8sSemantic Search Accuracy94.3%Tool Execution Success Rate98.7%Average Context Size2.4K tokensLLM Response Time800ms System Scalability
Concurrent Users: Tested up to 50 simultaneous users Throughput: ~30 predictions/second Data Volume: Handles 1M+ transaction records Index Refresh: <30 seconds for 10K documents
Example Prediction:
ATM: ATM_015 (Hawalli, Shopping Mall)
Date: 2025-11-03 (Sunday)
Predicted Demand: 2,840 KD
Model: XGBoost
Confidence: High (R²=0.90)
Recommendation: MODERATE demand. Ensure buffer > 2× daily mean.
Example RAG Query:
Q: "Which ATMs in Hawalli need urgent refills this weekend?"
A: Based on current analysis, 3 ATMs in Hawalli require urgent refills:
ANSWER: 3 ATMs identified for immediate action
EVIDENCE:
- ATM_015 (Hawalli Mall): refill 5,000 KD (balance 1,200 KD)
- ATM_023 (Hawalli Center): refill 4,500 KD (balance 980 KD)
- ATM_031 (Hawalli Square): refill 3,800 KD (balance 1,450 KD)