jsf-core 0.7.0

JBAC Strategy Foundry - A production-grade quantitative research engine

JSF-Core: JBAC Strategy Foundry

⚠️ EDUCATIONAL PURPOSE ONLY: This software is designed for learning and research purposes only. It is NOT intended for real trading with real money. Past performance in backtests does NOT guarantee future results. Trading involves substantial risk of loss. The authors and contributors are NOT liable for any financial losses. See DISCLAIMER for full details.

JSF-Core is a production-grade, open-source quantitative research engine for building, backtesting, and optimizing trading strategies. Built by JBAC EdTech, it provides a modular, type-safe, and extensible framework for systematic trading research.

Status Update (Feb 4, 2026): Phases 1-19 complete (95%)! ML Integration added with feature extraction, ensemble models, and walk-forward validation.

Features

• Modular Architecture: Clean separation between data, signals, strategies, simulation, and evaluation
• Type-Safe: Full Pydantic validation and Python type hints throughout
• Extensible: Easy to add custom signals, strategies, and evaluation metrics
• Production-Ready: Comprehensive logging, error handling, and testing
• Reproducible: Deterministic backtests with seed control
• Fast: Vectorized operations and optional parallel processing
• Live Trading: Real broker integration with paper & live trading modes
• Monitoring: Real-time dashboard with performance tracking and risk metrics
• Alerts: Multi-channel notifications with centralized Telegram bot (Console, Telegram, Email)
• Multi-Asset: Support for Futures, Options, Crypto, and Forex beyond equities
• Machine Learning: ML-based strategies with ensemble models and walk-forward validation
• Centralized Config: Secure environment-based configuration with .env support
• Well-Documented: Detailed docstrings and usage examples

Installation

From Source (Development)

# Clone the repository
git clone https://github.com/JaiAnshSB26/JBAC-Strategy-Foundry.git
cd JBAC-Strategy-Foundry

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

# Install pre-commit hooks
pre-commit install

From PyPI (Coming Soon)

pip install jsf-core

🚀 Quick Start

Setup Telegram Alerts (Optional, 2 minutes)

Get real-time paper trading alerts on your phone:

# Interactive setup wizard
python -m jsf.cli.setup_telegram

# Or follow the guide
# See: docs/QUICKSTART_TELEGRAM.md

Your First Strategy

from jsf.data import load_data
from jsf.strategies import MomentumStrategy
from jsf.simulation import BacktestEngine, BacktestConfig

# Load data
data = load_data(
    source='synthetic',
    symbols=['AAPL', 'GOOGL', 'MSFT', 'AMZN'],
    start_date='2020-01-01',
    end_date='2023-12-31'
)

# Create strategy
strategy = MomentumStrategy(
    name="momentum_60d",
    lookback=60,
    long_only=True
)

# Configure backtest
config = BacktestConfig(
    initial_capital=100000,
    transaction_cost=0.001,  # 10 bps
    slippage=0.0005,  # 5 bps
)

# Run backtest
engine = BacktestEngine(config)
result = engine.run_strategy(strategy, data)

# Display results
print(f"Total Return: {result.total_return:.2%}")
print(f"Sharpe Ratio: {result.sharpe_ratio:.2f}")
print(f"Max Drawdown: {result.max_drawdown:.2%}")
print(f"Total Trades: {len(result.trades)}")

# Full metrics
from jsf.simulation import calculate_all_metrics
metrics = calculate_all_metrics(result.returns)
print(f"\nCAGR: {metrics['cagr']:.2%}")
print(f"Sortino Ratio: {metrics['sortino_ratio']:.2f}")
print(f"Win Rate: {metrics['win_rate']:.2%}")

See examples/complete_backtest_example.py for comprehensive examples including:

• Basic backtesting
• Multi-strategy comparison
• Detailed performance metrics
• Transaction cost analysis

Documentation

Core Modules

• jsf.config: Configuration schemas and validation
• jsf.data: Data loading and preprocessing (synthetic & real data)
• jsf.signals: Signal generation (momentum, mean-reversion, trend, volatility, etc.)
• jsf.portfolio: Portfolio construction (position sizing, optimization, rebalancing)
• jsf.strategies: Strategy templates (momentum, mean-reversion, trend-following)
• jsf.simulation: Backtesting engine with transaction costs and performance metrics
• jsf.optimization: Parameter optimization (grid search, walk-forward)
• jsf.ml: Machine learning integration (feature extraction, ensemble models, validation)
• jsf.broker: Live trading broker integration (paper & live trading)
• jsf.monitoring: Real-time monitoring dashboard with performance tracking
• jsf.alerts: Multi-channel alert system (Console, Telegram, Email, SMS, Webhook)

Available Components

Signals (10+ types):

• Momentum, Mean Reversion, Trend Following
• Volatility, Volume, Moving Average Cross
• Breakout, Support/Resistance, Seasonality

Portfolio Construction (24 components):

• Position Sizing: Equal weight, signal-weighted, volatility-scaled, risk parity, Kelly
• Optimization: Min variance, max Sharpe, mean-variance, risk parity, max diversification
• Rebalancing: Periodic, threshold-based, signal-triggered, volatility-adjusted, cost-aware
• Constraints: Long-only, leverage, position limits, sector, turnover, exposure

Strategies (3 templates):

• Momentum Strategy (trend following)
• Mean Reversion Strategy (counter-trend)
• Trend Following Strategy (MA cross + trend strength)

Performance Metrics (20+ metrics):

• Returns: Total, CAGR, mean daily
• Risk: Volatility, downside deviation, max drawdown, VaR, CVaR
• Risk-adjusted: Sharpe, Sortino, Calmar
• Trading: Win rate, profit factor, avg win/loss
• Distribution: Skewness, kurtosis

🧪 Testing

# Run all tests
make test

# Run fast tests (no coverage)
make test-fast

# Run linting
make lint

# Format code
make format

Development

Project Structure

jsf-core/
├── src/jsf/              # Main package
│   ├── config/           # Configuration schemas
│   ├── data/             # Data loading & preprocessing
│   ├── signals/          # Signal generation
│   ├── strategies/       # Strategy templates
│   ├── simulation/       # Backtest engine
│   ├── optimization/     # Parameter optimization
│   ├── evaluation/       # Performance metrics
│   ├── reporting/        # Report generation
│   └── utils/            # Utilities
├── tests/                # Test suite
├── docs/                 # Documentation
└── examples/             # Usage examples

Development Roadmap

Phase 1: Foundation & Project Structure [Complete]
Phase 2: Core Configuration System [Complete]
Phase 3: Data Loading Infrastructure [Complete]
Phase 4-6: Signal Framework [Complete]
Phase 7: Portfolio Construction [Complete]
Phase 8: Strategy Templates [Complete]
Phase 9: Backtesting & Simulation Engine [Complete]
Phase 10: Visualization & Reporting [Complete]
Phase 11: Parameter Optimization [Complete]
Phase 12: Walk-Forward Analysis (Next)
Phase 13: Real Data Integration
Phase 14: Advanced Strategies
Phase 15: Risk Management Enhancements
Phase 16: Multi-Asset Support
Phase 17: High-Level API
Phase 18: CLI Tool
Phase 19: SDK Documentation
Phase 20: Release Preparation

Current Status (Phase 11 Complete)

Production-Ready Quantitative Trading System:

• Data loading (synthetic + real data support)
• Signal generation (10+ signal types)
• Portfolio construction (24 components)
• Strategy templates (3 pre-built strategies)
• Backtesting engine (transaction costs, slippage, tracking)
• Performance metrics (20+ metrics)
• Professional visualizations (6 plot types)
• Parameter optimization (grid search)

Latest Achievements:

• Validation Complete: 18/18 integration tests passing (100% success rate)
• Phases 7-11: All functionality tested and validated
• Optimization: Grid search finding optimal parameters (tested 95.65% return, 2.00 Sharpe)
• End-to-End: Complete workflow validated from data → signals → portfolio → backtest → metrics → plots

Real Results from Optimization:

• Momentum 120d optimized: 95.65% return, 2.00 Sharpe, -8.12% max drawdown
• Parameter search: Tested 6 combinations, found best in 2.5 seconds
• Multi-metric optimization: Different metrics favor different parameters

Next Steps (Phases 12-20):

1. Phase 12: Walk-forward analysis for out-of-sample testing
2. Phase 13: Real market data integration (Yahoo Finance, Alpha Vantage)
3. Phase 14: Advanced strategy templates (ML, multi-signal)
4. Phases 15-17: Risk management, multi-asset support, high-level API
5. Phases 18-20: CLI tool, documentation, PyPI release

Handoff Documentation

For Anubhav (Co-Developer):

This project is ready for collaborative development! All foundational components (Phases 1-11) are complete, tested, and documented.

Key Documents:

• HANDOFF_STATUS.md - Current status, test results, and immediate next steps
• HANDOFF_DOCUMENTATION.md - Complete technical guide (500+ lines)
• Test Suite - 18 integration tests (all passing)

Quick Validation:

# Run all integration tests
pytest tests/test_integration_phases_7_11.py --override-ini="addopts=" -v

# Expected: 18 passed in ~30 seconds

Development Status:

• Phases 1-11: Complete & Tested (55%)
• Phases 12-20: Ready for development (45%)
• Next: Phase 12 (Walk-Forward Analysis)

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Install with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run checks before committing
make check

⚠️ Disclaimer

EDUCATIONAL PURPOSE ONLY

This software is provided for educational and research purposes only. It is designed to help students, researchers, and developers learn about quantitative trading concepts, backtesting methodologies, and algorithmic strategy development.

IMPORTANT NOTICES:

1. NOT FINANCIAL ADVICE: Nothing in this software or documentation constitutes financial, investment, tax, or legal advice. Always consult with qualified professionals before making investment decisions.

2. NO REAL TRADING: This software is NOT intended for trading with real money. While it includes broker integration capabilities for educational demonstrations, using it for live trading is at your own risk.

3. PAST PERFORMANCE: Backtested results do NOT guarantee future performance. Simulated trading programs are designed with the benefit of hindsight and do not account for real-world market conditions, liquidity, or execution issues.

4. SUBSTANTIAL RISK: Trading financial instruments involves substantial risk of loss. You could lose some or all of your invested capital. Only trade with money you can afford to lose.

5. NO WARRANTY: This software is provided "AS IS" without warranty of any kind, express or implied. The authors and contributors disclaim all liability for any losses or damages.

6. YOUR RESPONSIBILITY: You are solely responsible for any trading decisions and their outcomes. The authors and JBAC EdTech are NOT responsible for any financial losses.

By using this software, you acknowledge that you understand and accept these risks.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with modern Python best practices
• Inspired by leading quantitative research frameworks
• Powered by NumPy, Pandas, and Pydantic

Contact

JBAC EdTech
GitHub: @JaiAnshSB26

---

Status: Active Development (v0.7.0-dev)
Phase: 19/20 - ML Integration & NLP Sentiment Complete
Next: Phase 20 - PyPI Publication & Documentation