Merge pull request #519 from coding-kitties/dev

Docs: metrics reference + CLI scaffold + Azure deploy fixes + dependabot patches

Author: MDUYN

README.md

@@ -70,23 +70,23 @@ This framework is built around the full loop: **create strategies → vector bac
  Features
 </summary> <br>
 
-- 📊 **30+ Metrics** — CAGR, Sharpe, Sortino, Calmar, VaR, CVaR, Max DD, Recovery & more
+- 📊 **[30+ Metrics](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/metrics)** — CAGR, Sharpe, Sortino, Calmar, VaR, CVaR, Max DD, Recovery & more
 - 🧮 **[Cross-Sectional Pipelines](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/pipelines)** — Rank, filter and score entire universes of symbols every iteration with a tidy factor table
-- ⚡ **Vector Backtesting for Signal Analysis** — Quickly test your strategy logic on historical data to see how signals would have behaved before committing to full event-driven backtests
-- 🏃 **Event-Driven Backtesting** — Once promising strategies are identified via vector backtests, run full event-driven backtests to simulate realistic execution and portfolio management
-- 🔀 **Permutation Testing / Monte Carlo Simulations** — Assess the statistical robustness of your strategies by running them across randomized market scenarios to see how often your results could occur by chance
-- 🚀 **Deployment** — Once the best strategy is identified through backtesting and comparison, deploy it to production locally or in the cloud (AWS Lambda / Azure Functions) to start live trading
-- ⚔️ **Multi-Strategy Comparison** — Rank, filter & compare strategies in a single interactive report
-- 🪟 **Multi-Window Robustness** — Test across different time periods with window coverage analysis
-- 📈 **Equity & Drawdown Charts** — Overlay equity curves, rolling Sharpe, drawdown & return distributions
-- 🗓️ **Monthly Heatmaps & Yearly Returns** — Calendar heatmap per strategy with return/growth toggles
-- 🎯 **Return Scenario Projections** — Good, average, bad & very bad year projections from backtest data
-- 📉 **Benchmark Comparison** — Beat-rate analysis vs Buy & Hold, DCA, risk-free & custom benchmarks
-- 📄 **One-Click HTML Report** — Self-contained file, no server, dark & light theme, shareable
-- 📦 **Custom `.iafbt` Backtest Bundle Format** — An explicit, versioned, compressed, language-portable container (zstd + msgpack with magic-byte header) plus a separate parquet index for fast filtering without loading. ~21× smaller and ~27× fewer files than standard filebased directory layouts, with parallel I/O for fast load/save of large amounts of backtests.
-- 🌐 **Load External Data** — Fetch CSV, JSON, or Parquet from any URL with caching and auto-refresh
-- � **[Record Custom Variables](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/recording-variables)** — Track any indicator or metric during backtests with `context.record()`
-- �🚀 **Build → Backtest → Deploy** — Local dev, cloud deploy (AWS / Azure), or monetize on Finterion
+- ⚡ **[Vector Backtesting for Signal Analysis](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/vector-backtesting)** — Quickly test your strategy logic on historical data to see how signals would have behaved before committing to full event-driven backtests
+- 🏃 **[Event-Driven Backtesting](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/event-backtesting)** — Once promising strategies are identified via vector backtests, run full event-driven backtests to simulate realistic execution and portfolio management
+- 🔀 **[Permutation Testing / Monte Carlo Simulations](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Assess the statistical robustness of your strategies by running them across randomized market scenarios to see how often your results could occur by chance
+- 🚀 **[Deployment](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/deployment)** — Once the best strategy is identified through backtesting and comparison, deploy it to production locally or in the cloud (AWS Lambda / Azure Functions) to start live trading
+- ⚔️ **[Multi-Strategy Comparison](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Rank, filter & compare strategies in a single interactive report
+- 🪟 **[Multi-Window Robustness](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Test across different time periods with window coverage analysis
+- 📈 **[Equity & Drawdown Charts](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Overlay equity curves, rolling Sharpe, drawdown & return distributions
+- 🗓️ **[Monthly Heatmaps & Yearly Returns](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Calendar heatmap per strategy with return/growth toggles
+- 🎯 **[Return Scenario Projections](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Good, average, bad & very bad year projections from backtest data
+- 📉 **[Benchmark Comparison](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Beat-rate analysis vs Buy & Hold, DCA, risk-free & custom benchmarks
+- 📄 **[One-Click HTML Report](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Self-contained file, no server, dark & light theme, shareable
+- 📦 **[Custom `.iafbt` Backtest Bundle Format](https://coding-kitties.github.io/investing-algorithm-framework/Data/backtest_data)** — An explicit, versioned, compressed, language-portable container (zstd + msgpack with magic-byte header) plus a separate parquet index for fast filtering without loading. ~21× smaller and ~27× fewer files than standard filebased directory layouts, with parallel I/O for fast load/save of large amounts of backtests.
+- 🌐 **[Load External Data](https://coding-kitties.github.io/investing-algorithm-framework/Data/external-data)** — Fetch CSV, JSON, or Parquet from any URL with caching and auto-refresh
+- 📝 **[Record Custom Variables](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/recording-variables)** — Track any indicator or metric during backtests with `context.record()`
+- 🚀 **[Build → Backtest → Deploy](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/application-setup)** — Local dev, cloud deploy (AWS / Azure), or monetize on Finterion
 
 </details>
 

docusaurus/docs/Getting Started/application-setup.md

@@ -4,125 +4,256 @@ sidebar_position: 2
 
 # Application Setup
 
-Learn how to set up your first trading application using the Investing Algorithm Framework.
-
-## Creating Your First App
+A real trading project usually has three concerns that pull in different
+directions:
+
+1. **Research**: exploring data, designing strategies and tuning parameters
+   in Jupyter notebooks.
+2. **Backtesting**: running reproducible historical simulations from a
+   script.
+3. **Production**: running the strategy live, deployed somewhere stable, with
+   secrets, logging and a single entry point.
+
+The Investing Algorithm Framework is designed to support all three from the
+**same** strategy code. To make that work, we recommend the following
+project layout for any non-trivial bot.
+
+## Recommended Project Structure
+
+```text
+my_trading_bot/
+├── app.py                  # Production entry point (live trading)
+├── strategies/             # Strategy implementations (importable package)
+│   ├── __init__.py
+│   └── my_strategy.py
+├── data_providers.py       # Custom data providers for your dataSource definitions in your strategies (OPTIONAL)
+├── notebooks/              # Research notebooks and backtest analyses
+│   ├── 01_data_exploration.ipynb
+│   ├── 02_backtest_baseline.ipynb
+│   ├── 03_in_sample_param_grid_search.ipynb
+│   ├── 04_out_of_sample_param_grid_search.ipynb
+│   ├── 05_overfitting_analysis.ipynb
+│   └── 06_event_backtests.ipynb
+├── data/                   # Downloaded market data (OHLCV, etc.)
+├── backtest_results/       # Saved backtest bundles (.iafbt)
+├── reports/                # Generated reports (HTML, CSV, etc.)
+├── resources/              # Misc assets (databases, configs)
+├── requirements.txt
+├── .env.example
+└── README.md
+```
 
-The framework provides a simple `create_app()` function to initialize your trading application:
+A working example of this layout lives in
+[`examples/tutorial`](https://github.com/coding-kitties/investing-algorithm-framework/tree/main/examples/tutorial).
 
-```python
-from investing_algorithm_framework import create_app
+You can scaffold this structure with the framework's CLI:
 
-app = create_app()
+```bash
+investing-algorithm-framework init --path ./my_trading_bot
 ```
 
-## Adding a Market
+This creates the above files and folders, with `app.py` and a sample strategy
+that you can modify. The `notebooks/` folder is left empty for you to fill with your research work.
 
-Before you can trade, you need to add a market configuration:
+### Why this layout?
 
-```python
-app.add_market(
-    market="bitvavo",
-    trading_symbol="EUR",
-)
-```
+- **`strategies/` is a package, not a script.** Both `app.py` (production)
+  and `notebooks` import the same strategy class, so
+  what you backtest is *exactly* what you deploy.
+- **`notebooks/` is for exploration and backtesting only.** Notebooks should `import`
+  from `strategies/` and `data_providers.py` — never copy-paste strategy
+  code into a cell. This keeps research and production in sync.
+- **`data/` and `backtest_results/` are caches.** They should usually
+  be in `.gitignore`. The framework writes data downloads to `data/`
+  and backtest bundles to `backtest_results/`.
+- **`app.py` does only what production needs** — load config, register
+  the market and strategy, call `app.run()`. Nothing else.
+
+## The Strategy (`strategies/my_strategy.py`)
 
-## Adding a Strategy
+This is the only file that contains your trading logic. It is imported
+by `app.py`, `run_backtest.py` and your notebooks alike.
 
-Register your trading strategy with the application:
+A strategy is **declarative**: you describe *what data you need* and *when
+to buy or sell*, and the framework takes care of order routing, position
+sizing, stop-losses and take-profits. The two functions you implement are
+`generate_buy_signals` and `generate_sell_signals` — both return a
+boolean `pd.Series` per symbol.
 
 ```python
-from investing_algorithm_framework import TradingStrategy, TimeUnit
+from typing import Any, Dict
+
+import pandas as pd
+from pyindicators import sma, crossover, crossunder
+
+from investing_algorithm_framework import (
+    TradingStrategy,
+    DataSource,
+    DataType,
+    TimeUnit,
+)
+
 
 class MyStrategy(TradingStrategy):
     time_unit = TimeUnit.HOUR
     interval = 2
     symbols = ["BTC"]
-    
-    def run(self, algorithm):
-        # Your trading logic here
-        pass
 
-app.add_strategy(MyStrategy())
+    data_sources = [
+        DataSource(
+            identifier="btc_ohlcv_1h",
+            data_type=DataType.OHLCV,
+            symbol="BTC/EUR",
+            time_frame="1h",
+            market="BITVAVO",
+            window_size=200,
+            pandas=True,
+        ),
+    ]
+
+    def generate_buy_signals(
+        self, data: Dict[str, Any]
+    ) -> Dict[str, pd.Series]:
+        df = data["btc_ohlcv_1h"]
+        df = sma(df, period=20, source_column="Close", result_column="sma_fast")
+        df = sma(df, period=50, source_column="Close", result_column="sma_slow")
+        df = crossover(df, "sma_fast", "sma_slow", result_column="cross_up")
+
+        return {"BTC": df["cross_up"].fillna(False).astype(bool)}
+
+    def generate_sell_signals(
+        self, data: Dict[str, Any]
+    ) -> Dict[str, pd.Series]:
+        df = data["btc_ohlcv_1h"]
+        df = sma(df, period=20, source_column="Close", result_column="sma_fast")
+        df = sma(df, period=50, source_column="Close", result_column="sma_slow")
+        df = crossunder(df, "sma_fast", "sma_slow", result_column="cross_down")
+
+        return {"BTC": df["cross_down"].fillna(False).astype(bool)}
 ```
 
-## Running the Application
+> The framework instantiates the class for you, so pass the **class**
+> (not an instance) to `app.add_strategy(...)`.
 
-### Live Trading
+The same `generate_buy_signals` / `generate_sell_signals` functions are
+used by **both** the vector backtest engine and the event-driven engine,
+which is what guarantees that what you backtest is what you deploy. For
+custom entry/exit logic that doesn't fit signals (e.g. rebalancing across
+symbols), override `run_strategy` instead see [Strategies](./strategies)
+for advanced patterns including position sizing, stop-loss, take-profit
+and scale-in rules.
 
-To start live trading:
+## The Production Entry Point (`app.py`)
+
+`app.py` is the file you run in production (locally, in a container, or as
+a serverless function). It should be small, declarative, and free of any
+research code.
 
 ```python
-app.run()
-```
+import logging.config
 
-### Backtesting
+from dotenv import load_dotenv
 
-To run a backtest:
+from investing_algorithm_framework import create_app, DEFAULT_LOGGING_CONFIG
 
-```python
-from datetime import datetime, timezone
-from investing_algorithm_framework import BacktestDateRange
+from strategies.my_strategy import MyStrategy
 
-backtest_range = BacktestDateRange(
-    start_date=datetime(2023, 1, 1, tzinfo=timezone.utc),
-    end_date=datetime(2024, 1, 1, tzinfo=timezone.utc)
-)
+load_dotenv()
+logging.config.dictConfig(DEFAULT_LOGGING_CONFIG)
 
-backtest = app.run_backtest(
-    backtest_date_range=backtest_range,
-    initial_amount=1000
+app = create_app()
+app.add_market(
+    market="bitvavo",
+    trading_symbol="EUR",
+    initial_balance=1000,
 )
+app.add_strategy(MyStrategy)
+
+
+if __name__ == "__main__":
+    app.run()
 ```
 
-## Complete Example
+API keys belong in environment variables (`.env`), not in source. Use
+`.env.example` to document which variables are required.
 
-Here's a complete example bringing it all together:
+## The Backtest Entry Point (`run_backtest.py`)
+
+`run_backtest.py` mirrors `app.py` but calls `run_backtest(...)` instead
+of `run()`. Because both files import the same `MyStrategy`, the strategy
+under test is identical to the one that will run live.
 
 ```python
-from investing_algorithm_framework import (
-    create_app, 
-    TradingStrategy, 
-    TimeUnit,
-    BacktestDateRange
-)
 from datetime import datetime, timezone
 
-# Create the application
-app = create_app()
+from investing_algorithm_framework import create_app, BacktestDateRange
 
-# Define your strategy
-class SimpleStrategy(TradingStrategy):
-    time_unit = TimeUnit.HOUR
-    interval = 4
-    symbols = ["BTC", "ETH"]
-    
-    def run(self, algorithm):
-        for symbol in self.symbols:
-            # Your trading logic
-            pass
-
-# Add market and strategy
+from strategies.my_strategy import MyStrategy
+
+app = create_app()
 app.add_market(market="bitvavo", trading_symbol="EUR")
-app.add_strategy(SimpleStrategy())
+app.add_strategy(MyStrategy)
 
-# Run backtest
-backtest_range = BacktestDateRange(
-    start_date=datetime(2023, 1, 1, tzinfo=timezone.utc),
-    end_date=datetime(2024, 1, 1, tzinfo=timezone.utc)
-)
 
-backtest = app.run_backtest(
-    backtest_date_range=backtest_range,
-    initial_amount=1000
-)
+if __name__ == "__main__":
+    backtest_date_range = BacktestDateRange(
+        start_date=datetime(2023, 1, 1, tzinfo=timezone.utc),
+        end_date=datetime(2024, 1, 1, tzinfo=timezone.utc),
+    )
+
+    backtest = app.run_backtest(
+        backtest_date_range=backtest_date_range,
+        initial_amount=1000,
+    )
 
-print(f"Total return: {backtest.get_total_return()}%")
+    summary = backtest.backtest_summary
+    print(f"Total return: {summary.total_growth_percentage:.2f}%")
+    print(f"Sharpe ratio: {summary.sharpe_ratio:.2f}")
 ```
 
-## Next Steps
+## The Notebooks (`notebooks/`)
 
-- Learn about [Portfolio Configuration](./portfolio-configuration) to manage your assets
-- Explore [Strategies](./strategies) for advanced strategy development
-- Check out [Backtesting](./backtesting) for comprehensive testing
+Notebooks are for research, backtesting, data exploration, signal visualisation,
+parameter sweeps, robustness checks, final reporting. They should
+**import** strategies from your `strategies/` package rather than
+redefining them.
+
+A typical progression (mirroring `examples/tutorial/notebooks/`):
+
+| Notebook | Purpose |
+| --- | --- |
+| `01_data_exploration.ipynb` | Download OHLCV, inspect coverage, detect and fill gaps |
+| `02_backtest_baseline.ipynb` | Single vector backtest of the strategy with default parameters + HTML report |
+| `03_in_sample_param_grid_search.ipynb` | Grid search across thousands of parameter combinations on the in-sample window |
+| `04_out_of_sample_param_grid_search.ipynb` | Re-run top in-sample candidates on the held-out out-of-sample window |
+| `05_overfitting_analysis.ipynb` | Compare in-sample vs out-of-sample performance, walk-forward / permutation checks |
+| `06_event_backtests.ipynb` | Validate the final picks with the event-driven engine (fees, slippage, fills) |
+
+See the [tutorial README](https://github.com/coding-kitties/investing-algorithm-framework/tree/main/examples/tutorial)
+for fully worked-out versions.
+
+## Running the Application
+
+### Live trading
+
+```bash
+python app.py
+```
+
+### Research and backtesting
+
+```bash
+jupyter lab notebooks/
+```
+
+## Next Steps
 
+- [Strategies](./strategies) — designing the `run_strategy` body, declaring
+  data sources, position sizing, stop-losses and take-profits.
+- [Portfolio Configuration](./portfolio-configuration) — fees, slippage,
+  multi-market portfolios.
+- [Event Backtesting](./event-backtesting) and
+  [Vector Backtesting](./vector-backtesting) — the two backtest engines
+  and when to use which.
+- [Deployment](./deployment) — packaging `app.py` for AWS Lambda, Azure
+  Functions or a long-running container.