Metadata-Version: 2.4
Name: jsf-core
Version: 0.7.0
Summary: JBAC Strategy Foundry - A production-grade quantitative research engine
Author-email: JBAC EdTech <contact@jbac.edu>
Maintainer-email: JBAC EdTech <contact@jbac.edu>
License: MIT
Project-URL: Homepage, https://github.com/JaiAnshSB26/JBAC-Strategy-Foundry
Project-URL: Documentation, https://jbac-strategy-foundry.readthedocs.io
Project-URL: Repository, https://github.com/JaiAnshSB26/JBAC-Strategy-Foundry
Project-URL: Bug Tracker, https://github.com/JaiAnshSB26/JBAC-Strategy-Foundry/issues
Keywords: quantitative-finance,backtesting,algorithmic-trading,strategy-research,portfolio-optimization,quant
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0.0,>=1.24.0
Requires-Dist: pandas<3.0.0,>=2.0.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: scipy<2.0.0,>=1.10.0
Requires-Dist: matplotlib<4.0.0,>=3.7.0
Requires-Dist: seaborn<1.0.0,>=0.12.0
Requires-Dist: plotly<6.0.0,>=5.14.0
Requires-Dist: pyarrow>=12.0.0
Requires-Dist: typing-extensions>=4.5.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: xgboost>=1.7.0
Requires-Dist: lightgbm>=4.0.0
Requires-Dist: joblib>=1.3.0
Provides-Extra: ml
Requires-Dist: tensorflow>=2.13.0; extra == "ml"
Requires-Dist: torch>=2.6.0; extra == "ml"
Requires-Dist: transformers>=4.30.0; extra == "ml"
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.28.0; extra == "dashboard"
Requires-Dist: python-dotenv>=1.0.0; extra == "dashboard"
Provides-Extra: trading
Requires-Dist: alpaca-trade-api>=3.0.0; extra == "trading"
Provides-Extra: alerts
Requires-Dist: python-telegram-bot<21.0,>=20.0; extra == "alerts"
Provides-Extra: optimization
Requires-Dist: optuna>=3.2.0; extra == "optimization"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.3.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: ruff>=0.0.280; extra == "dev"
Requires-Dist: mypy>=1.4.0; extra == "dev"
Requires-Dist: pre-commit>=3.3.0; extra == "dev"
Requires-Dist: ipython>=8.14.0; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: jsf-core[alerts,dashboard,ml,optimization,trading]; extra == "all"
Dynamic: license-file

# JSF-Core: JBAC Strategy Foundry

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Tests](https://img.shields.io/badge/tests-635%20passing-brightgreen.svg)](tests/)
[![Progress](https://img.shields.io/badge/progress-Phase%2019%20Complete-brightgreen.svg)](#development-roadmap)
[![Version](https://img.shields.io/badge/version-0.7.0--dev-blue.svg)](src/jsf/__init__.py)

> ⚠️ **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](#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)

```bash
# 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)

```bash
pip install jsf-core
```

## 🚀 Quick Start

### Setup Telegram Alerts (Optional, 2 minutes)

Get real-time paper trading alerts on your phone:

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

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

### Your First Strategy

```python
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

```bash
# 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**](HANDOFF_STATUS.md) - Current status, test results, and immediate next steps
- [**HANDOFF_DOCUMENTATION.md**](HANDOFF_DOCUMENTATION.md) - Complete technical guide (500+ lines)
- [**Test Suite**](tests/test_integration_phases_7_11.py) - 18 integration tests (all passing)

**Quick Validation**:
```bash
# 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](CONTRIBUTING.md) for details.

### Development Setup

```bash
# 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](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](https://github.com/JaiAnshSB26)

---

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