Riskify Machine Learning (ML)

Welcome to the Machine Learning (ML) module of Riskify! This repository powers advanced risk assessment, optimization, and automation for the Riskify platform, blending AI with decentralized finance to transform how insurance risk is managed and traded.

Purpose

Riskify ML enables smarter, faster, and more transparent risk management by leveraging machine learning to analyze data, predict risk, and optimize capital allocation across insurance pools and portfolios.

How ML Powers Riskify

Machine learning is central to:

• Evaluating risk at both pool and network levels
• Optimizing capital allocation and risk sharing
• Monitoring performance and adapting to market changes
• Enabling real-time, data-driven decisions for all platform participants

System Architecture & Pipeline

Riskify's ML system is built on a robust, modular pipeline:

1. Data Collection: Aggregates on-chain, market, and external data relevant to risk and performance.
2. Feature Engineering: Transforms raw data into actionable features for modeling.
3. Model Training: Builds and trains models for risk assessment and pool optimization.
4. Validation: Tests models for accuracy, reliability, and fairness.
5. Deployment: Integrates models into the Riskify platform, including on-chain smart contracts.
6. Monitoring: Continuously tracks model performance and triggers alerts for anomalies or drift.

Key Components:

• Data collectors (on-chain, market)
• Feature engineering and selection modules
• Risk assessment and optimization models
• Model validation and cross-validation tools
• Model deployment/export (including ONNX for on-chain use)
• On-chain integration (Solidity smart contracts)
• Performance monitoring and alerting

For detailed class structures and code, see integration.md.

System Overview & Architecture Diagram

The following diagram illustrates the flow of data and models within the Riskify ML system:

graph TB
    style A fill:#2ecc71,stroke:#27ae60,color:white
    style B fill:#3498db,stroke:#2980b9,color:white
    style C fill:#e74c3c,stroke:#c0392b,color:white
    
    A[ML Components] --> B[Models]
    A --> C[Training]
    A --> D[Inference]
    
    B --> B1[GNN Model]
    B --> B2[PPO Model]
    B --> B3[Energy Model]
    
    C --> C1[Data Pipeline]
    C --> C2[Training Loop]
    C --> C3[Validation]
    
    D --> D1[API]
    D --> D2[Oracles]
    D --> D3[Monitoring]

Diagram Explanation:

• ML Components: The core infrastructure for data handling, model orchestration, and integration.
• Models:
  • GNN Model: Graph Neural Network for modeling relationships and dependencies in risk networks (e.g., insurer connections, correlated exposures).
  • PPO Model: Proximal Policy Optimization, a reinforcement learning agent for optimizing capital allocation and pool balancing.
  • Energy Model: Energy-based models for scenario scoring, tail risk estimation, and rare event simulation.
• Training:
  • Data Pipeline: Ingests and preprocesses raw data from on-chain and external sources.
  • Training Loop: Iteratively fits models to data, tunes hyperparameters, and tracks metrics.
  • Validation: Evaluates model performance, robustness, and fairness before deployment.
• Inference:
  • API: Exposes model predictions to the Riskify platform and external consumers.
  • Oracles: Bridges on-chain smart contracts with off-chain ML predictions for automated execution.
  • Monitoring: Continuously tracks model health, performance, and triggers retraining as needed.

Platform Integration:

• Model predictions (e.g., risk scores, optimal allocations) are delivered to smart contracts via oracles, enabling automated, transparent execution of risk management logic.
• Monitoring and performance data feed back into the ML pipeline, supporting continuous improvement and retraining.
• The modular design allows for rapid extension with new models, data sources, or risk products as the platform evolves.

Key Features & Capabilities

• Risk Assessment: Predicts risk levels for pools and the overall network
• Optimization: Recommends optimal allocation of capital and risk
• On-Chain Integration: Deploys models to smart contracts for automated, transparent execution
• Performance Monitoring: Tracks and alerts on model health and outcomes
• Modular Design: Easily extendable for new data sources, models, or risk products

Technologies Used:

• Python (PyTorch, NumPy, scikit-learn)
• ONNX (for model export)
• Solidity (for smart contract integration)
• Modern data engineering and monitoring tools

Getting Started

• General Users: Learn how ML enhances transparency, efficiency, and security in risk management.
• Developers & Data Scientists: Dive into technical details, code, and integration guides in integration.md.
• Contributors: See best practices below and open a pull request or issue to get involved.

Best Practices & Contribution

• Data Quality: Validate, clean, and normalize all data for reliable results
• Model Management: Version, retrain, and test models regularly
• Security: Protect data and model outputs with strict controls and audit logging
• Continuous Monitoring: Track performance and set up alerts for anomalies
• Contribution: Follow our guidelines, document your changes, and help us improve the platform!

Learn More & Documentation

• ML Integration Guide — Technical deep-dives and code
• Technical Reference
• API Usage
• Risk Management Concepts