Inferenco Predictions SDK

A Rust library for cryptocurrency price forecasting that combines statistical methods, technical analysis, and machine learning.

Projects using this SDK

• DeFiCalc integrates the SDK for price-aware DeFi calculations.
• Inferenco Nova uses the SDK to power AI-driven blockchain conversations and tooling.

Features

• Hybrid Forecasting Engine: Ensemble of statistical models, ML (SVR), and technical indicators

• Multi-Horizon Forecasts: From 15 minutes to 4 years

• Two-Tier Caching: Smart TTL-based caching for API responses and forecasts

• Rate Limiting: Built-in token bucket + exponential backoff for CoinGecko API

• Technical Analysis: RSI, MACD, Bollinger Bands

• Local AI: On-the-fly Mixture of Linear Experts (MixLinear) training

Installation

Add to your Cargo.toml:

[dependencies]
prediction_sdk = "0.1.9"
tokio = { version = "1", features = ["full"] }

Quick Start

cd prediction_sdk
cargo build
cargo test

Usage

use prediction_sdk::{PredictionSdk, ForecastHorizon, ShortForecastHorizon, SentimentSnapshot};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let sdk = PredictionSdk::new()?;
    
    let sentiment = SentimentSnapshot {
        news_score: 0.65,
        social_score: 0.80,
    };
    
    let result = sdk.forecast_with_fetch(
        "bitcoin",
        "usd",
        ForecastHorizon::Short(ShortForecastHorizon::OneHour),
        Some(sentiment),
    ).await?;
    
    println!("Forecast: {:?}", result);
    Ok(())
}

Fetching Charts

To retrieve historical candles and (for long horizons) projection bands, set the chart flag to true in your request. This is best handled via the run_prediction_handler helper or by manually calling fetch_chart_candles.

use prediction_sdk::{ForecastRequest, ForecastHorizon, ShortForecastHorizon, run_prediction_handler};

// ... inside async fn
let request = ForecastRequest {
    asset_id: "bitcoin".to_string(),
    vs_currency: "usd".to_string(),
    horizon: ForecastHorizon::Short(ShortForecastHorizon::OneHour),
    sentiment: None,
    chart: true, // <--- Enable chart data
};

// Returns a JSON string containing both "forecast" and "chart" fields
let json_response = run_prediction_handler(request).await?;
println!("{}", json_response);

Response Structure:

{
  "forecast": {
    "type": "short",
    "value": {
      "expected_price": 42350.0,
      "confidence": 0.85,
      // ... other forecast fields
      "ml_interval_calibration": {
        "target_coverage": 0.9,
        "observed_coverage": 0.88,
        "interval_width": 0.031,
        "price_interval_width": 1320.0,
        "pinball_loss": 0.004,
        "calibration_score": 0.74
      }
    }
  },
  "chart": {
    "history": [
      {
        "timestamp": "2024-01-01T00:00:00Z",
        "open": 42000.0,
        "high": 42500.0,
        "low": 41800.0,
        "close": 42350.0,
        "volume": 1823.4
      }
      // ... more candles
    ],
    "projection": [
      // Only present for Long horizons
      {
        "timestamp": "2024-01-02T00:00:00Z", 
        "percentile_10": 40000.0, 
        "mean": 43000.0, 
        "percentile_90": 46000.0
      }
    ]
  }
}

ML-backed short forecasts expose ml_interval_calibration, reflecting a 90% target conformal interval built from rolling, out-of-fold residuals. The calibration_score replaces the previous heuristic reliability metric and is derived from pinball loss against the observed coverage.

Run the Example

cargo run --example real_world_test

MCP Integration

This SDK is designed to be easily integrated into Model Context Protocol (MCP) servers as a tool.

• Tool Name: get_crypto_forecast
• Functionality: Provides short/long term price forecasts and optional chart data.
• Integration: Use run_prediction_handler to process tool arguments and return the JSON result directly.

See the MCP Integration Guide in the documentation for the full JSON schema and Rust implementation details.

See DOCUMENTATION.md for detailed architecture, API reference, and integration guides.

CI/CD

GitHub Actions runs:

• cargo fmt --check
• cargo clippy
• cargo build
• cargo test (unit + integration + doc tests)

License

MIT