Sequence Modeling (LSTM)

The Sequence Modeling component is the core predictive engine of Signal.Engine. Unlike traditional models that analyze a single data point, our LSTM (Long Short-Term Memory) architecture processes a sliding window of historical market data to identify temporal patterns, momentum, and trend reversals.

The 50-Candle Logic

The model is designed to "read" the market as a sequence. It ingests the last 50 candles (time-steps) to output a single directional prediction. This allows the agent to distinguish between a temporary price spike and a sustained structural trend.

Input Features

For every time-step in the sequence, the model processes:

Close Price: Normalized price action.
RSI (14): Momentum indicator to detect overbought/oversold conditions.
MACD: Trend-following momentum indicator.
Log Returns: To capture stationary volatility patterns.

Model Architecture: `LSTMPredictor`

The system utilizes LSTMPredictor, built on PyTorch Lightning for high-performance training and reproducibility.

Key Specifications:

Architecture: Multi-layer LSTM followed by Batch Normalization and Dropout.
Hidden Layers: 64 units (configurable).
Output: A 3-class Softmax distribution.
Stability: Includes a BatchNorm1d layer after the sequence processing to stabilize training against market volatility.

Class Mapping (Directional Bias)

The model outputs one of three states: | Index | Label | Market Sentiment | | :--- | :--- | :--- | | 0 | DOWN | Bearish / Sell Signal | | 1 | NEUTRAL | Sideways / No Trade | | 2 | UP | Bullish / Buy Signal |

The Training Pipeline

The LSTM undergoes a two-stage evolution process:

Supervised Fine-Tuning (SFT): The model is first trained using src/train_sft.py on a "Golden Dataset." This dataset uses a ZigZag Hindsight Labeler to identify perfect historical entries and exits. The goal of SFT is to give the model "Common Sense" (targeting ~77% directional accuracy).
Reinforcement Learning (PPO): Once pre-trained, the LSTM weights are used as the policy backbone for the Proximal Policy Optimization (PPO) agent, which learns to maximize profit and minimize drawdown in a live-simulated environment.

Usage & Implementation

1. Training the Sequence Model

To start the Supervised Fine-Tuning phase:

python -m src.train_sft --epochs 50 --batch_size 32

2. Inference via API

The model is served via a FastAPI endpoint. It automatically fetches the latest sequence, scales the features, and returns the prediction.

Endpoint: GET /prediction

Example Response:

{
  "date": "2023-10-27",
  "ticker": "RELIANCE.NS",
  "prediction": "UP",
  "confidence": 88.42,
  "features": {
    "Close": 2450.10,
    "RSI": 62.5
  }
}

3. Manual Model Loading (Internal)

If you are developing custom logic, you can load the trained weights directly:

from src.lstm_model import LSTMPredictor
import torch

# Initialize with same dims used in training
model = LSTMPredictor(input_dim=4, hidden_dim=64, output_dim=3)
model.load_state_dict(torch.load("checkpoints_sft/final_sft_model.pth"))
model.eval()

# Input shape: (Batch, Sequence_Length, Features)
dummy_input = torch.randn(1, 50, 4)
logits = model(dummy_input)
prediction = torch.argmax(logits, dim=1)

Configuration Parameters

The model behavior can be tuned in the LSTMPredictor constructor:

dropout: (Default: 0.2) Controls regularization to prevent overfitting on specific stock tickers.
lr: (Default: 0.001) Learning rate for the Adam optimizer.
loss_fn: Uses CrossEntropyLoss with custom weights [1.2, 0.8, 1.2] to penalize missing major moves (UP/DOWN) more heavily than misidentifying NEUTRAL states.

Sequence Modeling (LSTM)