README.md

---
tags:
- time-series
- forecasting
- temporal
- trading
- ensemble
- consensus
- btc-usd
library_name: temporal-forecasting
---

# BTC-USD Consensus Ensemble (1d)

This repository contains a **consensus ensemble** of 5 temporal transformer models for BTC-USD price forecasting.

## Overview

Instead of relying on a single model, this ensemble combines multiple models with different characteristics to produce robust, diverse forecasts. Each model specializes in different market patterns:

- **Momentum models**: Capture trending behavior with shorter lookback windows
- **Balanced models**: General-purpose forecasting with medium lookback windows
- **Mean reversion models**: Detect overbought/oversold conditions with longer windows

## Ensemble Members

- [momentum (lookback=30)](./tree/main/momentum_lookback30)
- [balanced (lookback=60)](./tree/main/balanced_lookback60)
- [balanced (lookback=90)](./tree/main/balanced_lookback90)
- [mean_reversion (lookback=60)](./tree/main/mean_reversion_lookback60)
- [momentum (lookback=45)](./tree/main/momentum_lookback45)

## How It Works

### 1. Independent Forecasting
Each model generates independent 7-period forecasts using its specific lookback window and focus strategy.

### 2. Consensus Analysis
Eight different consensus strategies analyze the ensemble's forecasts:

- **Gradient Strategy**: Analyzes forecast momentum and direction changes
- **Confidence Strategy**: Weighs predictions by model confidence scores
- **Timeframe Strategy**: Balances short-term vs long-term predictions
- **Volatility Strategy**: Adjusts for market volatility conditions
- **Mean Reversion Strategy**: Identifies reversal opportunities
- **Acceleration Strategy**: Detects accelerating price movements
- **Swing Strategy**: Targets swing trading opportunities
- **Risk-Adjusted Strategy**: Optimizes risk-reward ratios

### 3. Unified Signal
All strategy recommendations are aggregated into a final consensus signal with:
- **Action**: BUY, SELL, or HOLD
- **Confidence Score**: 0.0 to 1.0
- **Expected Return**: Basis points (bps)

## Usage

### Import Individual Models

```python
from strategies.model_cache import get_model_cache

cache = get_model_cache()

# Import a specific ensemble member
model_path, scaler_path, metadata = cache.import_from_huggingface(
    repo_id="maverick90024/btc-usd-consensus-1d",
    symbol="BTC-USD",
    interval="1d",
    lookback=30,  # Choose appropriate lookback
    focus="momentum",  # Choose appropriate focus
    forecast_horizon=7,
    path_in_repo="momentum_lookback30"  # Specify subdirectory
)
```

### Run Consensus Analysis

```python
from backend.main import run_consensus_analysis_worker
from backend.database import Database

async def run_analysis():
    db = Database()
    await db.connect()

    result = await run_consensus_analysis_worker(
        symbol="BTC-USD",
        horizons=[7],
        interval="1d",
        analysis_id="my-analysis",
        db=db
    )

    print(f"Consensus: {result['consensus']}")
    print(f"Action: {result['action']}")
    print(f"Confidence: {result['confidence']}")
```

## Model Details

- **Symbol**: BTC-USD
- **Interval**: 1d
- **Forecast Horizon**: 7 periods
- **Ensemble Size**: 5 models
- **Architecture**: Temporal Transformer
- **Training Framework**: PyTorch
- **Export Date**: 2025-11-09

## License

GPL-3.0-or-later

## Citation

```
@software{temporal_trading_ensemble,
  title = {BTC-USD Consensus Ensemble},
  author = {Unidatum Integrated Products LLC},
  year = {2025},
  url = {https://github.com/OptimalMatch/temporal-trading-agents}
}
```

## Links

- [GitHub Repository](https://github.com/OptimalMatch/temporal-trading-agents)
- [Documentation](https://github.com/OptimalMatch/temporal-trading-agents/blob/main/README.md)