⚡ ULTRON: Sync README.md

README.md

@@ -0,0 +1,164 @@
+---
+language:
+- en
+license: mit
+library_name: pytorch
+tags:
+- time-series
+- financial-forecasting
+- ohlcv
+- conformer
+- transformer
+- convolution
+- market-prediction
+- finance
+datasets:
+- mito0o852/OHLCV-1m
+pipeline_tag: time-series-forecasting
+---
+
+# ⚡ ULTRON // Advanced OHLCV Convolutional Transformer
+
+Autonomous high-performance deep learning pipeline designed to train on the **90 GB `mito0o852/OHLCV-1m`** minute-level stock market dataset on Google Colab GPU instances without hitting storage quotas, RAM OOM, or session timeout limits.
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Ultron09/ohlcv-transformer/blob/main/OHLCV_Transformer_Colab.ipynb)
+
+---
+
+## 🏛️ Architectural Overview
+
+```
+Raw Minute Candlesticks (90GB Parquet Shards on HF Hub)
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 1. Zero-Disk-Overflow Streaming Shard Manager               │
+│    • Streams 1 monthly shard (~300MB) at a time             │
+│    • In-memory feature computation + overlapping windowing  │
+│    • Immediate shard disk cache eviction (O(1) disk footprint)│
+└─────────────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 2. Stationary Feature Extraction Engine                     │
+│    • Log Returns: ln(C_t / C_{t-1})                         │
+│    • Relative Bar Range: (H_t - L_t) / C_t                  │
+│    • Normalized Candle Body: (C_t - O_t) / (Range + eps)    │
+│    • Upper & Lower Wick Absorption Dynamics                 │
+│    • Parkinson Continuous Micro-Volatility Estimator        │
+│    • Rolling Normalized Volume Z-Score                      │
+└─────────────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 3. Reversible Instance Normalization (RevIN)                │
+│    • Dynamically strips non-stationary market regime drift  │
+└─────────────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 4. Multi-Scale Overlapping 1D Convolutional Tokenizer       │
+│    • Inception kernels: [3m, 7m, 15m, 31m]                  │
+│    • Stride S=4 creates continuous overlapping patches      │
+│    • Compresses 512-min sequence to 128 tokens (16x speedup)│
+└─────────────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 5. Conformer Backbone (FlashAttention + Depthwise Conv)     │
+│    • Rotary Position Embeddings (RoPE)                      │
+│    • Causal Scaled Dot-Product Self-Attention (FlashAttn-2) │
+│    • Depthwise Separable 1D Conv (local momentum dynamics)  │
+│    • Pre-LN SwiGLU Feed-Forward Networks                    │
+└─────────────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 6. Multi-Horizon Dual Forecasting Head                      │
+│    • Expected Return Vector: [1m, 3m, 5m, 10m, 15m]         │
+│    • Directional Probability: P(Return > 0)                 │
+│    �� Loss: Huber Loss + λ * Directional BCE                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+![Architecture Schematic](assets/architecture_schematic.png)
+
+---
+
+## 📊 Empirical Training Telemetry (Tesla T4 GPU)
+
+Trained across all 12 monthly shards of the 2024 trading year (**26,000,000+ raw minute bars**, ~151,000 overlapping sliding windows across top US liquid equities).
+
+![Training Telemetry](assets/training_telemetry.png)
+
+### 📈 Multi-Horizon Forecast Curves & Confidence
+
+The model forecasts both continuous return curves and upward movement probabilities across multiple discrete temporal horizons (1m, 3m, 5m, 10m, and 15m):
+
+![Multi-Horizon Forecast Curves](assets/multi_horizon_forecast.png)
+
+| Horizon | Sample A (Tech Breakout) | Sample B (Mean Reversion) | Sample C (Momentum Spike) | Signal Confidence |
+| :--- | :--- | :--- | :--- | :--- |
+| **1-Minute** | `+0.5032%` | `+0.2899%` | `+1.0101%` | `50.9%` P(Up) |
+| **3-Minute** | `+0.8202%` | `+0.0537%` | `+0.6119%` | `52.5%` P(Up) |
+| **5-Minute** | `+0.5146%` | `-1.0078%` | `-0.8469%` | `49.3%` P(Up) |
+| **10-Minute**| `-1.2062%` | `-0.5882%` | `+0.1730%` | `48.7%` P(Up) |
+| **15-Minute**| `-0.3365%` | `+0.4570%` | `-0.3456%` | `49.0%` P(Up) |
+
+---
+
+## 📂 Repository Structure
+
+- `config.py`: Central hyperparameter matrix (date ranges, tickers, model dimensions, training parameters).
+- `features.py`: Stationary feature engineering engine (candle morphology, Parkinson volatility, returns).
+- `dataset.py`: Streaming Shard Manager that downloads, windows, and cleans up Parquet files on-the-fly.
+- `model.py`: Complete PyTorch Conformer model with overlapping 1D convolutions and RoPE.
+- `loss.py`: Multi-task financial loss function (Huber + BCE + Directional Accuracy tracking).
+- `train.py`: Autonomous Colab training loop with AMP FP16, gradient accumulation, and auto-resume.
+- `colab_runner.sh`: Turnkey bash script for headless Colab CLI execution.
+- `OHLCV_Transformer_Colab.ipynb`: Jupyter notebook ready to open in Google Colab.
+
+---
+
+## 🚀 How to Execute on Google Colab
+
+### Method 1: Turnkey Colab CLI / Terminal Execution
+
+In your Google Colab bash terminal (or via Colab CLI / SSH session):
+
+```bash
+# 1. Clone or copy this repository into Colab
+git clone <your-repo> /content/ohlcv-transformer
+cd /content/ohlcv-transformer
+
+# 2. Execute the autonomous runner script
+bash colab_runner.sh
+```
+
+Or run directly with customized parameters:
+```bash
+python3 train.py \
+    --start_year 2021 \
+    --end_year 2025 \
+    --batch_size 64 \
+    --grad_accum 4 \
+    --lr 0.0003 \
+    --epochs 5
+```
+
+### Method 2: Google Colab Web Interface
+
+1. Upload `OHLCV_Transformer_Colab.ipynb` to Google Colab.
+2. Select **Runtime** > **Change runtime type** > **T4 GPU** (or A100/L4).
+3. Click **Runtime** > **Run all**.
+
+---
+
+## 🛡️ Colab Quota & Limit Protection Protocol
+
+| Quota / Constraint | Default Risk | ULTRON Architectural Mitigation |
+| :--- | :--- | :--- |
+| **Disk Space (~78 GB)** | 90 GB dataset causes immediate `Disk Full` crash | Shard Manager downloads 1 month (~300MB), processes, and immediately deletes it ($O(1)$ disk usage < 1 GB). |
+| **System RAM (12.7 GB)** | DataFrames cause `Out of Memory` killer | Filters top liquid tickers and runs garbage collection (`gc.collect()`) after every shard. |
+| **GPU VRAM (15 GB)** | Transformer self-attention $O(T^2)$ VRAM spike | Overlapping 1D conv tokenizes $512 \to 128$ tokens; Mixed Precision (FP16) + Gradient Accumulation (`effective_batch_size = 256`). |
+| **Runtime Disconnects** | 12-hour timeout loses all trained weights | Checkpoints sync automatically to Google Drive (`/content/drive/MyDrive/ohlcv_checkpoints/`) every 200 steps and auto-resume seamlessly. |