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

prediction_sdk 0.1.10