Ronin-Ecosystem-Tracker---ML-Backend

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

Ronin-Ecosystem-Tracker---ML-Backend

★ 10 Open GitHub ↗

This ML backend is one component of the complete Ronhub Analytics Platform. Check this out: https://github.com/joshuatochinwachi/ronin-ecosystem-tracker

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🎮 Ronin Gaming ML Analytics API

[![FastAPI](https://img.shields.io/badge/FastAPI-0.104.1-009688?style=flat&logo=fastapi)](https://fastapi.tiangolo.com/)
[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=flat&logo=python&logoColor=white)](https://www.python.org/)
[![ML](https://img.shields.io/badge/ML-XGBoost%20%7C%20LightGBM-orange?style=flat)](https://xgboost.readthedocs.io/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://raw.githubusercontent.com/joshuatochinwachi/Ronin-Ecosystem-Tracker---ML-Backend/main/LICENSE)
[![Live](https://img.shields.io/badge/Live-Production-success)](https://web-production-f90ba.up.railway.app)

> **AI-powered game health prediction and analytics for the Ronin gaming ecosystem**

Predict which games are declining or thriving using machine learning models trained on real-time blockchain data from 13+ Ronin Analytics endpoints.

---

## 🌐 **Part of the RonHub Ecosystem**

This ML backend is one component of the complete **RonHub Analytics Platform**:

| Component | Description | Link |
|-----------|-------------|------|
| 🎨 **Frontend** | Production web application (what users see) | [ronhub.io/analytics](https://www.ronhub.io/analytics) |
| 🔧 **Main Backend** | Core analytics API with 13 Ronin data endpoints | [Railway API](https://web-production-4fae.up.railway.app) \| [GitHub](https://github.com/joshuatochinwachi/Ronin-Ecosystem-Tracker) |
| 🤖 **ML Backend** | This repo - AI predictions & game health analysis | [Railway API](https://web-production-f90ba.up.railway.app) \| [GitHub](https://github.com/joshuatochinwachi/Ronin-Ecosystem-Tracker---ML-Backend) |

**👉 Visit [ronhub.io/analytics](https://www.ronhub.io/analytics) to see this ML backend in action!**

---

## 🌟 Features

### 🤖 **Multi-Model ML Ensemble**
- **5 ML Models**: XGBoost, LightGBM, Random Forest, Gradient Boosting, Logistic Regression
- **Auto-Selection**: Champion model selected via composite scoring (ROC-AUC + Accuracy + Precision + Recall)
- **Ensemble Predictions**: Weighted average of top 3 models for robust predictions

### 📊 **Game Health Prediction**
- Predict if games will decline in the next 7 days
- Risk levels: High (>65% decline probability), Medium (35-65%), Low (<35%)
- 10+ engineered features: player trends, volatility, days since peak, growth momentum, etc.

### 🔄 **Smart Auto-Retraining**
- **Background Polling**: Checks for data changes every 15 minutes
- **Change Detection**: MD5 hash comparison across 13 endpoints
- **Auto-Retrain**: Triggers only when data actually changes (no wasted compute)
- **Temporal Validation**: Proper time-series train/test split (no data leakage)

### 💾 **Intelligent Caching**
- **Parquet Storage**: Fast, compressed data storage
- **Prediction Cache**: Champion and ensemble predictions cached separately
- **Metadata Tracking**: Timestamps, row counts, data hashes for all endpoints

### 🚀 **Production-Ready**
- RESTful API with 13+ endpoints
- Background task with exponential backoff error recovery
- Health checks and monitoring endpoints
- CORS enabled for web applications
- Comprehensive logging

---

## 📈 Use Cases

- **Game Developers**: Monitor your game's health and predict player churn
- **Investors**: Identify trending games for investment opportunities
- **Analytics Teams**: Track Ronin ecosystem performance
- **Community Managers**: Get early warnings for declining games

---

## 🏗️ Architecture

### **System Overview - RonHub Ecosystem**

```
┌─────────────────────────────────────────────────────────────────┐
│                    RonHub Analytics Platform                     │
│                   https://www.ronhub.io/analytics                │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │                   │
         ┌──────────▼──────────┐ ┌─────▼──────────────┐
         │   Main Backend      │ │   ML Backend       │
         │   (Core Analytics)  │ │   (This Repo)      │
         │                     │ │                    │
         │ 13 Ronin Endpoints  │ │ Game Health AI     │
         │ Data Aggregation    │ │ Risk Predictions   │
         │ whale_tracking      │ │ Trending Detection │
         └──────────┬──────────┘ └─────┬──────────────┘
                    │                   │
                    └─────────┬─────────┘
                              │
                    ┌─────────▼──────────┐
                    │   Ronin Blockchain  │
                    │   (Data Source)     │
                    └─────────────────────┘
```

### **ML Backend Architecture (This Repository)**

```
┌─────────────────────────────────────────────────────────────┐
│                   Ronin Gaming ML API                        │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐     ┌──────────────┐    ┌──────────────┐ │
│  │   Data Sync  │────▶│ Feature Eng. │───▶│  ML Training │ │
│  │  (15 min)    │     │  (10 metrics)│    │  (5 models)  │ │
│  └──────────────┘     └──────────────┘    └──────────────┘ │
│         │                     │                     │        │
│         ▼                     ▼                     ▼        │
│  ┌──────────────┐     ┌──────────────┐    ┌──────────────┐ │
│  │   Cache      │     │  Predictions │    │   Champion   │ │
│  │  (Parquet)   │     │  (Ensemble)  │    │  Selection   │ │
│  └──────────────┘     └──────────────┘    └──────────────┘ │
│                                                               │
├─────────────────────────────────────────────────────────────┤
│                      REST API (FastAPI)                      │
└─────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
  Game Health          Games at Risk        Trending Games
  Predictions           Detection            Discovery
```

---

## 🚀 Quick Start

### **Production Deployment**

This ML backend is **live in production** and powers the RonHub Analytics platform!

| Environment | URL | Purpose |
|------------|-----|---------|
| 🌐 **User-Facing App** | [ronhub.io/analytics](https://www.ronhub.io/analytics) | Main analytics dashboard (uses this ML backend) |
| 🔧 **Main Backend API** | [web-production-4fae.up.railway.app](https://web-production-4fae.up.railway.app) | Core data aggregation (13 Ronin endpoints) |
| 🤖 **ML Backend API** | [web-production-f90ba.up.railway.app](https://web-production-f90ba.up.railway.app) | This repo - AI predictions |

### **Try the ML API Now**

```bash
# Health Check
curl https://web-production-f90ba.up.railway.app/api/health

# Get AI Predictions for All Games
curl https://web-production-f90ba.up.railway.app/api/bulk/predictions

# Interactive API Docs
# Visit: https://web-production-f90ba.up.railway.app/docs
```

---

### **Local Development**

### **Prerequisites**

- Python 3.11+
- pip or conda
- 2GB+ RAM (4GB recommended for ML training)

### **Installation**

```bash
# Clone the repository
git clone https://github.com/YOUR_USERNAME/ronin-ml-backend.git
cd ronin-ml-backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### **Configuration**

Create a `.env` file in the root directory:

```env
PORT=8000
CHECK_INTERVAL_SECONDS=900  # 15 minutes
MIN_TRAINING_SAMPLES=15
MAX_STALE_HOURS=24
```

### **Run Locally**

```bash
python main.py
```

API will be available at: `http://localhost:8000`

---

## 📚 API Documentation

### **Base URLs**

| Environment | URL | Use Case |
|-------------|-----|----------|
| 🌐 **Production (ML)** | `https://web-production-f90ba.up.railway.app` | Use this for integrations |
| 🔧 **Main Backend** | `https://web-production-4fae.up.railway.app` | Raw Ronin data endpoints |
| 💻 **Local Development** | `http://localhost:8000` | Testing & development |

### **Interactive API Documentation**

- **Production Swagger UI**: [web-production-f90ba.up.railway.app/docs](https://web-production-f90ba.up.railway.app/docs)
- **Production ReDoc**: [web-production-f90ba.up.railway.app/redoc](https://web-production-f90ba.up.railway.app/redoc)
- **Local Swagger UI**: `http://localhost:8000/docs`
- **Local ReDoc**: `http://localhost:8000/redoc`

---

## 🔌 Core Endpoints

### **1. System Health**

```bash
GET /api/health
```

**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2026-01-08T18:00:00",
  "ml_models_trained": true,
  "champion_model": "xgboost",
  "background_polling": true
}
```

---

### **2. Game Health Predictions**

```bash
GET /api/predictions/game-health?method=ensemble
```

**Parameters:**
- `method`: `champion` or `ensemble` (default: `champion`)

**Response:**
```json
{
  "method": "ensemble",
  "timestamp": "2026-01-08T18:00:00",
  "predictions": [
    {
      "game_project": "Fableborne",
      "latest_players": 63742,
      "decline_probability": 0.168,
      "risk_level": "Low",
      "player_trend_7d": 5.48,
      "growth_momentum": 64.96
    }
  ],
  "summary": {
    "total_games": 21,
    "high_risk": 5,
    "medium_risk": 5,
    "low_risk": 11
  }
}
```

---

### **3. Games at Risk**

```bash
GET /api/predictions/games-at-risk?limit=10&method=champion
```

**Parameters:**
- `limit`: Number of games to return (1-50, default: 10)
- `method`: `champion` or `ensemble`

**Response:**
```json
{
  "method": "champion",
  "at_risk_games": [
    {
      "game_project": "Cambria",
      "decline_probability": 0.982,
      "risk_level": "High",
      "latest_players": 1,
      "days_since_peak": 264
    }
  ],
  "count": 6
}
```

---

### **4. Trending Games**

```bash
GET /api/predictions/trending-games?limit=10&method=champion
```

**Parameters:**
- `limit`: Number of games to return (1-50, default: 10)
- `method`: `champion` or `ensemble`

**Response:**
```json
{
  "method": "champion",
  "trending_games": [
    {
      "game_project": "Fableborne",
      "decline_probability": 0.029,
      "risk_level": "Low",
      "player_trend_7d": 5.48,
      "growth_momentum": 64.96
    }
  ],
  "count": 10
}
```

---

### **5. Bulk Predictions**

```bash
GET /api/bulk/predictions
```

Returns all predictions in one request (game health, at-risk, trending, model info).

---

### **6. Model Information**

```bash
GET /api/models/info
```

**Response:**
```json
{
  "champion": {
    "name": "xgboost",
    "roc_auc": 0.50,
    "accuracy": 0.60,
    "precision": 0.33,
    "recall": 1.0
  },
  "top_3_ensemble": [
    {"name": "xgboost", "roc_auc": 0.50, "accuracy": 0.60},
    {"name": "lightgbm", "roc_auc": 0.50, "accuracy": 0.80},
    {"name": "logistic_regression", "roc_auc": 0.25, "accuracy": 0.40}
  ]
}
```

---

### **7. Force Refresh & Retrain**

```bash
POST /api/refresh?force=true
```

**Parameters:**
- `force`: If `true`, retrain even if no data changed

**Response:**
```json
{
  "status": "success",
  "message": "Data refreshed and ML models trained successfully",
  "models_trained": 5,
  "champion_model": "xgboost",
  "training_samples": 20,
  "predictions_generated": 21
}
```

---

### **8. Polling Status**

```bash
GET /api/polling/status
```

**Response:**
```json
{
  "polling_enabled": true,
  "check_interval_minutes": 15,
  "seconds_until_next_check": 432,
  "predictions_available": true
}
```

---

## 🧠 Machine Learning Details

### **Features Engineered (10 Total)**

| Feature | Description |
|---------|-------------|
| `avg_players_7d` | Average unique players in last 7 days |
| `avg_transactions_7d` | Average transactions in last 7 days |
| `avg_volume_7d` | Average RON volume in last 7 days |
| `player_trend_7d` | % change in players (recent 7d vs previous 7d) |
| `transaction_trend_7d` | % change in transactions |
| `player_volatility` | Standard deviation of player count |
| `days_since_peak` | Days since peak player count |
| `peak_to_current_ratio` | Current players / Peak players |
| `consistency_score` | Inverse coefficient of variation |
| `growth_momentum` | (Last week - First week) / First week |

### **Models Trained**

1. **XGBoost** - Gradient boosting with tree ensembles
2. **LightGBM** - Fast gradient boosting framework
3. **Random Forest** - Ensemble of decision trees
4. **Gradient Boosting** - Sklearn's gradient boosting
5. **Logistic Regression** - Linear classification baseline

### **Model Selection**

Champion selected via **composite score**:

```
Composite Score = 0.35×ROC-AUC + 0.35×Accuracy + 0.15×Precision + 0.15×Recall
```

### **Training Strategy**

- **Temporal Split**: 75% train, 25% test (chronological)
- **Class Weighting**: Handle imbalanced data (typically 25% declining, 75% growing)
- **No SMOTE**: Avoid synthetic data for time series
- **Auto-Retraining**: Every 15 minutes if data changes

### **Target Definition**

Game is "declining" if:
```
avg_players_next_7_days < 0.9 × avg_players_last_7_days
```
(i.e., >10% drop in player count)

---

## 📊 Data Sources

### **Data Flow**

This ML backend consumes data from the **Main Backend API**:

```
Main Backend API → ML Backend → AI Predictions → Frontend
(13 endpoints)      (Training)    (Real-time)     (ronhub.io)
```

### **13 Ronin Analytics Endpoints** (via Main Backend)

All data is fetched from: `https://web-production-4fae.up.railway.app/api/raw/`

1. `games_daily_activity` - Daily game metrics (primary ML data source)
2. `games_overall_activity` - Aggregated game stats
3. `ronin_daily_activity` - Network-wide activity
4. `user_activation_retention` - User cohort analysis
5. `ron_current_holders` - RON token holders
6. `ron_segmented_holders` - Holder segments
7. `wron_active_trade_pairs` - DEX trading pairs
8. `wron_whale_tracking` - Large holder tracking
9. `wron_volume_liquidity` - DEX liquidity metrics
10. `wron_trading_hourly` - Hourly trading data
11. `wron_weekly_segmentation` - Weekly user segments
12. `nft_collections` - NFT collection metrics
13. `coingecko_ron` - RON price data

**Source Code**: [Ronin-Ecosystem-Tracker](https://github.com/joshuatochinwachi/Ronin-Ecosystem-Tracker)

---

## 🚀 Deployment

### **Current Status: ✅ Live in Production**

This ML backend is **already deployed** and powers [ronhub.io/analytics](https://www.ronhub.io/analytics)!

- **ML API**: [web-production-f90ba.up.railway.app](https://web-production-f90ba.up.railway.app)
- **Main Backend**: [web-production-4fae.up.railway.app](https://web-production-4fae.up.railway.app)
- **Frontend**: [ronhub.io/analytics](https://www.ronhub.io/analytics)

### **Deploy Your Own Instance**

Want to deploy your own version? Here's how:

#### **1. Fork & Clone**

```bash
git clone https://github.com/joshuatochinwachi/Ronin-Ecosystem-Tracker---ML-Backend.git
cd Ronin-Ecosystem-Tracker---ML-Backend
```

#### **2. Deploy to Railway**

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new)

```bash
# Push to GitHub
git add .
git commit -m "Ready for deployment"
git push origin main

# Deploy on Railway:
# 1. Connect your GitHub repo
# 2. Railway auto-detects Python
# 3. Add environment variables (see below)
# 4. Add persistent volumes (see below)
```

#### **3. Environment Variables**

Add these in Railway dashboard under **"Variables"**:

```env
PORT=8000
CHECK_INTERVAL_SECONDS=900
MIN_TRAINING_SAMPLES=15
MAX_STALE_HOURS=24
RAILWAY_ENVIRONMENT=production
```

#### **4. Persistent Volumes (Critical!)**

Railway containers restart frequently. Add volumes in **"Settings"** → **"Volumes"**:

| Mount Path | Size | Purpose |
|------------|------|---------|
| `/app/ml_models` | 500MB | Stores trained ML models |
| `/app/raw_data_cache` | 1GB | Caches Ronin data |

Without volumes, your models get wiped on restart!

---

## 🧪 Testing

```bash
# Run tests
pytest

# Test specific endpoint
pytest tests/test_predictions.py -v

# Test with coverage
pytest --cov=main --cov-report=html
```

---

## 📊 Performance

### **API Response Times**
- Health check: ~10ms
- Predictions (cached): ~50-100ms
- Refresh & retrain: ~30-60s (only when data changes)

### **Resource Usage**
- Memory: 300-500MB (idle), 800MB-1.2GB (training)
- CPU: <5% (idle), 60-80% (training)
- Storage: ~50MB (cache + models)

### **Accuracy Metrics** (With Limited Data)
- ROC-AUC: 0.50 (baseline: 0.50)
- Accuracy: 0.60-0.80
- Recall: 1.0 (catches all declining games)

*Note: Performance improves with more data (currently 20 samples)*

---

## 🛠️ Development

### **Project Structure**

```
ronin-ml-backend/
├── main.py                 # FastAPI application
├── requirements.txt        # Python dependencies
├── Procfile               # Railway deployment config
├── railway.json           # Railway settings
├── .env                   # Environment variables (not committed)
├── .gitignore            # Git ignore rules
├── README.md             # This file
├── ml_models/            # Trained models (generated)
│   ├── scaler.joblib
│   ├── xgboost.joblib
│   └── metadata.json
└── raw_data_cache/       # Cached data (generated)
    ├── games_daily_activity.parquet
    └── cache_metadata.json
```

### **Adding New Features**

1. Edit `FeatureService.create_game_features()` in `main.py`
2. Add feature name to `feature_columns` list
3. Retrain models via `/api/refresh?force=true`

### **Adding New Models**

```python
# In MLModelManager.__init__()
self.model_configs['your_model'] = {
    'model': YourModelClass(),
    'priority': 1
}
```

---

## 🤝 Contributing

Contributions are welcome! Please:

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

---

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 👨‍💻 Author

**Joshua Tochinwachi**
- 🌐 Production App: [ronhub.io/analytics](https://www.ronhub.io/analytics)
- 📦 Main Repo: [Ronin-Ecosystem-Tracker](https://github.com/joshuatochinwachi/Ronin-Ecosystem-Tracker)
- 🤖 ML Repo: This repository
- GitHub: [@joshuatochinwachi](https://github.com/joshuatochinwachi)

---

## 🔗 Related Repositories

This ML backend is part of a larger ecosystem:

1. **Main Backend** - [Ronin-Ecosystem-Tracker](https://github.com/joshuatochinwachi/Ronin-Ecosystem-Tracker)
   - Core data aggregation
   - 13 Ronin blockchain endpoints
   - RESTful API for analytics

2. **ML Backend** - [Ronin-Ecosystem-Tracker---ML-Backend](https://github.com/joshuatochinwachi/Ronin-Ecosystem-Tracker---ML-Backend)
   - AI-powered game health predictions
   - 5 machine learning models
   - Auto-retraining system
   - **You are here!**

3. **Frontend** - (Coming soon to GitHub)
   - React-based dashboard
   - Live at [ronhub.io/analytics](https://www.ronhub.io/analytics)
   - Interactive charts & visualizations

---

## 🙏 Acknowledgments

- [FastAPI](https://fastapi.tiangolo.com/) - Modern Python web framework
- [XGBoost](https://xgboost.readthedocs.io/) & [LightGBM](https://lightgbm.readthedocs.io/) - ML libraries
- [Ronin Network](https://roninchain.com/) - Blockchain data source
- [Railway](https://railway.app/) - Deployment platform
- [Sky Mavis](https://skymavis.com/) - For building the Ronin ecosystem

---

## 📧 Support & Contact

### **For Issues or Questions:**

- 🐛 **Bug Reports**: Open an [issue](https://github.com/joshuatochinwachi/Ronin-Ecosystem-Tracker---ML-Backend/issues)
- 💬 **Feature Requests**: Open a [discussion](https://github.com/joshuatochinwachi/Ronin-Ecosystem-Tracker---ML-Backend/discussions)
- 📧 **Email**: contact@ronhub.io
- 🌐 **Production App**: [ronhub.io/analytics](https://www.ronhub.io/analytics)

### **API Status**

Check real-time API status:
- ML Backend: [web-production-f90ba.up.railway.app/api/health](https://web-production-f90ba.up.railway.app/api/health)
- Main Backend: [web-production-4fae.up.railway.app/api/health](https://web-production-4fae.up.railway.app/api/health)

---

## 🗺️ Roadmap

### **v1.1 (Next Release)**
- [ ] Add SHAP values for prediction explanations
- [ ] Historical prediction tracking
- [ ] Alerts via webhook/email for high-risk games
- [ ] Dashboard UI (React + Recharts)

### **v1.2 (Future)**
- [ ] Multi-timeframe predictions (7d, 14d, 30d)
- [ ] Game clustering and segmentation
- [ ] Revenue prediction models
- [ ] A/B testing framework for models

### **v2.0 (Long-term)**
- [ ] Real-time streaming predictions
- [ ] Custom model training via API
- [ ] Multi-chain support (not just Ronin)

---

**⭐ If this project helped you, please star it on GitHub! ⭐**

### 🌐 **Live Production App**
# [ronhub.io/analytics](https://www.ronhub.io/analytics)

Built with ❤️ for the Ronin Gaming Community

---

**Part of the RonHub Ecosystem** | [Main Backend](https://github.com/joshuatochinwachi/Ronin-Ecosystem-Tracker) | [ML Backend](https://github.com/joshuatochinwachi/Ronin-Ecosystem-Tracker---ML-Backend) | [Frontend](https://www.ronhub.io/analytics)

</div>

Ronin-Ecosystem-Tracker---ML-Backend

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README