quant-torch 0.0.1

ML Forecasting and Backtesting Framework

Quant-Torch

A modular, extensible Python framework for financial time-series forecasting and trading strategy evaluation.

---

Overview

Quant-Torch unifies data ingestion, feature engineering, ML forecasting models, signal generation, and backtesting into a clean, research-friendly and production-lean architecture.

Target Users:

• Quantitative ML beginners and intermediate learners
• Students building portfolio projects
• Researchers needing reproducible pipelines
• Developers exploring systematic trading architectures

---

Installation

# Clone repository
git clone https://github.com/yourusername/quant-torch.git
cd quant-torch

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install in development mode
pip install -e ".[dev]"

---

Quick Start

# Example workflow (implement as you build modules)
from quantml.data import CSVLoader
from quantml.features import FeaturePipeline
from quantml.models import get_model
from quantml.training import Trainer
from quantml.signals import ThresholdGenerator
from quantml.backtesting import BacktestEngine
from quantml.evaluation import sharpe_ratio

# 1. Load data
data = CSVLoader().load("data/btc_daily.csv")

# 2. Create features
pipeline = FeaturePipeline(config)
features = pipeline.fit_transform(data)

# 3. Train model
model = get_model("lstm", model_config)
trainer = Trainer(model, ...)
trainer.fit(train_loader, val_loader)

# 4. Generate signals
predictions = model.predict(test_features)
signals = ThresholdGenerator(thresholds).generate(predictions)

# 5. Backtest
engine = BacktestEngine(config)
result = engine.run(signals, prices)

# 6. Evaluate
print(f"Sharpe Ratio: {result.metrics['sharpe']:.2f}")

---

Architecture

┌──────────┐    ┌───────────┐    ┌────────┐    ┌─────────┐
│   Data   │───▶│  Features │───▶│ Models │───▶│ Signals │
└──────────┘    └───────────┘    └────────┘    └─────────┘
                                                    │
                    ┌───────────────────────────────┘
                    ▼
            ┌──────────────┐    ┌────────────┐
            │ Backtesting  │───▶│ Evaluation │
            └──────────────┘    └────────────┘

---

Module Overview

Module	Purpose
core/	Protocols, schemas, exceptions — foundation layer
data/	Data loading, transforms, PyTorch datasets
features/	Technical indicators, statistical features
models/	ML model definitions (LSTM, TCN, Transformer)
training/	Training loop, callbacks, time-series CV
signals/	Convert predictions to trading signals
backtesting/	Backtest engine with cost models
evaluation/	Performance metrics (Sharpe, drawdown, etc.)
visualization/	Equity curves, forecast plots
cli/	Command-line interface
utils/	Config, logging, reproducibility

Each module contains a .instructions.md file with detailed implementation guidance.

---

Configuration

Experiments are driven by YAML configuration:

# configs/experiment.yaml
data:
  source: csv
  path: data/btc_daily.csv
  
features:
  sequence_length: 60
  indicators:
    - name: sma
      params: { period: 20 }

model:
  type: lstm
  params:
    hidden_size: 128
    num_layers: 2

training:
  epochs: 100
  early_stopping:
    patience: 10

signals:
  type: threshold
  params:
    buy_threshold: 0.01
    sell_threshold: -0.01

---

CLI Usage

# Train a model
quantml train --config configs/experiment.yaml

# Run backtest
quantml backtest --config configs/experiment.yaml

# Full pipeline
quantml run --config configs/experiment.yaml

---

Development

Running Tests

pytest
pytest --cov=quantml  # with coverage

Project Structure

quant-torch/
├── quantml/           # Main package
├── tests/             # Test suite
├── configs/           # YAML configurations
├── docs/              # Documentation
├── examples/          # Example scripts
└── scripts/           # Utility scripts

---

Version Roadmap

v0.1 (Current)

• Basic data loaders and transforms
• LSTM model with base forecaster abstraction
• Simple backtest engine
• Core metrics (Sharpe, drawdown)
• CLI for training and backtesting

v0.2

• TCN and Transformer models
• Realistic backtesting (slippage, fees)
• More indicators
• Visualization module

v0.3

• Full documentation
• Config-driven experiments
• Clean extensibility patterns

---

License

MIT License — see LICENSE file for details.

---

Contributing

See CONTRIBUTING.md for guidelines.