investing-algorithm-framework 1.3.1__py3-none-any.whl → 7.25.6__py3-none-any.whl

investing_algorithm_framework/cli/templates/readme.md.template

@@ -0,0 +1,135 @@
+# README created by investing_algorithm_framework
+
+You can find the documentation for the investing_algorithm_framework
+[here](https://coding-kitties.github.io/investing-algorithm-framework).
+
+
+## Getting Started
+
+This project was created using the investing_algorithm_framework CLI. It provides a template for building a trading algorithm using the investing_algorithm_framework.
+
+This repository contains a simple trading algorithm that uses the
+`investing_algorithm_framework` to fetch data from [bitvavo](https://www.bitvavo.com/en/) and execute trades on the [bitvavo exchange](https://www.bitvavo.com/en/).
+
+The trading strategy is a simple moving average crossover strategy that uses the 50 and 100 day moving averages and the 200 day moving average as a trend filter. The strategy is implemented in the `strategy.py` file. The data provider is implemented in the `data_providers.py` file.
+
+All indicators are implemented with the [pyindicators](https://github.com/coding-kitties/PyIndicators) library.
+
+
+#### 1. Install the requirements
+
+You can install the requirements using the following command:
+```bash
+pip install -r requirements.txt
+```
+
+This will install the `investing_algorithm_framework`, `pyindicators`, and
+`python-dotenv` libraries. If you use the azure functions type option, it will also install the `azure-functions` library.
+
+
+#### 2. Create a `.env` file
+You need to create a `.env` file in the root of the project. You can use the `.env.example` file as a template. The `.env` file should contain the following environment variables:
+
+```bash
+BITVAVO_API_KEY=your_api_key
+BITVAVO_API_SECRET=your_api_secret
+```
+
+##### 2.1 Changing the exchange
+You can change the exchange in the `app.py` file. The default is set to `bitvavo`, but you can change it to any exchange you want. You can find the list of supported exchanges [here](https://investing-algorithm-framework.com/Getting%20Started/markets).
+
+##### 2.2 Azure Functions `.env` file
+If you are using the azure functions type option, you also need to add the following environment variables:
+
+```
+AZURE_STORAGE_CONNECTION_STRING=your_azure_storage_connection_string
+AZURE_STORAGE_CONTAINER_NAME=your_azure_storage_container_name
+```
+
+If you would like to have guidance on how to create the azure storage connection string, you can find it [here](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal).
+
+#### 3. Run the app (Skip this step if you have not backtested your strategy)
+> This will run the app as if it was run in production. It will execute live
+> trades on your connected exchange. Please only run this if you are
+> comfortable with this and have backtested your strategy.
+
+You can run the app using the following command:
+```bash
+python app.py
+```
+
+This will start the app and run the trading algorithm. The app will fetch data from the bitvavo exchange and execute trades based on the trading strategy.
+
+#### 3.1 Run the app with azure functions locally
+> Make sure to have the azure functions core tools installed. You can find the
+> installation instructions [here](https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local).
+
+If you are using the azure functions type option, you can run the app locally using the following command:
+```bash
+func start
+```
+
+#### 4. Run the backtest
+You can run the backtest using the following command:
+
+```bash
+python run_backtest.py
+```
+
+#### 5. Deployment
+You can deploy your trading bot in varous ways.
+
+##### 5.1 Azure Functions
+You can deploy your trading bot to azure functions using the following command:
+
+```bash
+investing-algorithm-framework deploy --type function --cloud azure
+```
+This will deploy your trading bot to azure functions. You can find the deployment instructions [here](https://investing-algorithm-framework.com/Getting%20Started/deployment).
+
+## Project Structure
+
+> We highly recommend to keep the file structure as is, as it is
+> designed to work with the investing_algorithm_framework CLI.
+> You can add your own files and folders as needed, however, we
+> recommend to keep the `strategies` folder for your strategies
+> and the `app.py` file for your app entry point.
+
+```yaml
+.
+├── app.py
+├── requirements.txt
+├── strategies
+│   ├── data_providers.py
+│   └── strategy.py
+├── .gitignore
+├── .env.example
+└── README.md
+```
+
+If you're using the azure functions type option, you will also have an `function_app.py`, `local.settings.json`, and `function.json` file. The `function_app.py` file is the entry point for the azure function, and the `local.settings.json` file is used to configure the local environment for the azure function. The `function.json` file is used to configure the function itself.
+
+> You can change the time trigger in the `function_app.py` when
+> using the azure functions type option. The default is set to
+> every 30 seconds. You can change it to any time you want,
+> but make sure to use the correct format for the time trigger.
+
+## Requirements
+
+The project requires Python 3.10 or higher. You can create a virtual environment and install the requirements using the following commands:
+
+```bash
+virtualenv venv
+source venv/bin/activate  # On Windows use `venv\Scripts\activate`
+pip install -r requirements.txt
+```
+
+By default pyindicators is installed as its specified in the requirements.txt file. This is a requirement for the example strategy in the `strategy.py` file. You can always remove it from the requirements.txt file if you don't need it.
+
+## Deployment
+
+You can deploy your trading bot to azure functions using the following cli command:
+
+```bash
+investing-algorithm-framework deploy --type function --cloud azure
+```

investing_algorithm_framework/cli/templates/requirements.txt.template

@@ -0,0 +1,2 @@
+investing-algorithm-framework>=6.8.2
+pyindicators>=0.5.4

investing_algorithm_framework/cli/templates/run_backtest.py.template

@@ -0,0 +1,20 @@
+from datetime import datetime
+
+from investing_algorithm_framework import BacktestDateRange
+from investing_algorithm_framework import create_app
+from strategies.strategy import MyTradingStrategy
+
+app = create_app()
+app.add_strategy(MyTradingStrategy)
+app.add_market(market="BITVAVO", trading_symbol="EUR")
+
+
+if __name__ == "__main__":
+    backtest_date_range = BacktestDateRange(
+        start_date=datetime(2023, 1, 1),
+        end_date=datetime(2023, 12, 31),
+    )
+    report = app.run_backtest(
+        backtest_date_range=backtest_date_range, initial_amount=1000
+    )
+    report.show()

investing_algorithm_framework/cli/templates/strategy.py.template

@@ -0,0 +1,124 @@
+from investing_algorithm_framework import TimeUnit, TradingStrategy, Context, \
+    OrderSide
+from .data_providers import btc_eur_ohlcv_2h, btc_eur_ticker
+from pyindicators import ema, is_crossover, is_above, is_below, is_crossunder
+
+
+class MyTradingStrategy(TradingStrategy):
+    """
+    A simple trading strategy that uses EMA crossovers to generate buy and
+    sell signals. The strategy uses a 50-period EMA and a 100-period EMA
+    to detect golden and death crosses. It also uses a 200-period EMA to
+    determine the overall trend direction. The strategy trades BTC/EUR
+    on a 2-hour timeframe. The strategy is designed to be used with the
+    Investing Algorithm Framework and uses the PyIndicators library
+    to calculate the EMAs and crossover signals.
+
+    The strategy uses a trailing stop loss and take profit to manage
+    risk. The stop loss is set to 5% below the entry price and the
+    take profit is set to 10% above the entry price. The stop loss and
+    take profit are both trailing, meaning that they will move up
+    with the price when the price goes up.
+    """
+    time_unit = TimeUnit.HOUR
+    interval = 2
+    symbol_pairs = ["BTC/EUR"]
+    market_data_sources = [btc_eur_ohlcv_2h, btc_eur_ticker]
+    fast = 50
+    slow = 100
+    trend = 200
+    stop_loss_percentage = 2
+    stop_loss_sell_size = 50
+    take_profit_percentage = 8
+    take_profit_sell_size = 50
+
+    def apply_strategy(self, context: Context, market_data):
+
+        for pair in self.symbol_pairs:
+            symbol = pair.split('/')[0]
+
+            # Don't trade if there are open orders for the symbol
+            # This is important to avoid placing new orders while there are
+            # existing orders that are not yet filled
+            if context.has_open_orders(symbol):
+                continue
+
+            ohlvc_data = market_data[f"{pair}-ohlcv-2h"]
+            # ticker_data = market_data[f"{symbol}-ticker"]
+            # Add fast, slow, and trend EMAs to the data
+            ohlvc_data = ema(
+                ohlvc_data,
+                source_column="Close",
+                period=self.fast,
+                result_column=f"ema_{self.fast}"
+            )
+            ohlvc_data = ema(
+                ohlvc_data,
+                source_column="Close",
+                period=self.slow,
+                result_column=f"ema_{self.slow}"
+            )
+            ohlvc_data = ema(
+                ohlvc_data,
+                source_column="Close",
+                period=self.trend,
+                result_column=f"ema_{self.trend}"
+            )
+
+            price = ohlvc_data["Close"][-1]
+
+            if not context.has_position(symbol) \
+                    and self._is_buy_signal(ohlvc_data):
+                order = context.create_limit_order(
+                    target_symbol=symbol,
+                    order_side=OrderSide.BUY,
+                    price=price,
+                    percentage_of_portfolio=25,
+                    precision=4,
+                )
+                trade = context.get_trade(order_id=order.id)
+                context.add_stop_loss(
+                    trade=trade,
+                    trade_risk_type="trailing",
+                    percentage=self.stop_loss_percentage,
+                    sell_percentage=self.stop_loss_sell_size
+                )
+                context.add_take_profit(
+                    trade=trade,
+                    percentage=self.take_profit_percentage,
+                    trade_risk_type="trailing",
+                    sell_percentage=self.take_profit_sell_size
+                )
+
+            if context.has_position(symbol) \
+                    and self._is_sell_signal(ohlvc_data):
+                open_trades = context.get_open_trades(
+                    target_symbol=symbol
+                )
+
+                for trade in open_trades:
+                    context.close_trade(trade)
+
+    def _is_sell_signal(self, data):
+        return is_crossunder(
+            data,
+            first_column=f"ema_{self.fast}",
+            second_column=f"ema_{self.slow}",
+            number_of_data_points=2
+        ) and is_below(
+            data,
+            first_column=f"ema_{self.fast}",
+            second_column=f"ema_{self.trend}",
+        )
+
+    def _is_buy_signal(self, data):
+        return is_crossover(
+            data=data,
+            first_column=f"ema_{self.fast}",
+            second_column=f"ema_{self.slow}",
+            number_of_data_points=2
+        ) and is_above(
+            data=data,
+            first_column=f"ema_{self.fast}",
+            second_column=f"ema_{self.trend}",
+        )

investing_algorithm_framework/cli/validate_backtest_checkpoints.py

@@ -0,0 +1,197 @@
+"""
+CLI command to validate backtest checkpoints from a directory.
+
+This command scans a directory for backtest results and creates or updates
+a checkpoints.json file with all found backtests organized by date ranges.
+"""
+import json
+import os
+from typing import Dict, List
+
+import click
+
+from investing_algorithm_framework.domain import Backtest
+
+
+def validate_and_create_checkpoints(
+    directory_path: str,
+    output_file: str = None,
+    verbose: bool = False
+) -> Dict[str, List[str]]:
+    """
+    Validate a directory for backtest checkpoints and create a checkpoint file.
+
+    Args:
+        directory_path (str): Path to the directory containing
+            backtest results.
+        output_file (str, optional): Custom path for the output
+            checkpoint file. If None, will create 'checkpoints.json'
+            in the directory_path.
+        verbose (bool): Whether to print detailed information.
+
+    Returns:
+        Dict[str, List[str]]: Dictionary mapping date range
+        keys to algorithm IDs.
+    """
+    if not os.path.exists(directory_path):
+        raise click.ClickException(
+            f"Directory {directory_path} does not exist."
+        )
+
+    # Determine output file path
+    if output_file is None:
+        output_file = os.path.join(directory_path, "checkpoints.json")
+
+    checkpoints = {}
+    valid_backtests = 0
+    invalid_dirs = 0
+
+    if verbose:
+        click.echo(f"Scanning directory: {directory_path}")
+        click.echo("-" * 60)
+
+    # Scan all subdirectories in the target directory
+    for item in os.listdir(directory_path):
+        item_path = os.path.join(directory_path, item)
+
+        # Skip files, only process directories
+        if not os.path.isdir(item_path):
+            continue
+
+        # Skip the checkpoints.json file itself
+        if item == "checkpoints.json":
+            continue
+
+        try:
+            # Try to load the backtest
+            backtest = Backtest.open(item_path)
+
+            if backtest.algorithm_id is None:
+                if verbose:
+                    click.echo(
+                        f"⚠️  Warning: {item} - No "
+                        f"algorithm_id found, skipping"
+                    )
+                invalid_dirs += 1
+                continue
+
+            # Process each backtest run to extract date ranges
+            if backtest.backtest_runs:
+                for run in backtest.get_all_backtest_runs():
+                    # Create date range key in the format used by the framework
+                    start_date = run.backtest_start_date.isoformat()
+                    end_date = run.backtest_end_date.isoformat()
+                    date_range_key = f"{start_date}_{end_date}"
+
+                    # Add algorithm_id to the checkpoint for this date range
+                    if date_range_key not in checkpoints:
+                        checkpoints[date_range_key] = []
+
+                    if backtest.algorithm_id \
+                            not in checkpoints[date_range_key]:
+                        checkpoints[date_range_key].append(
+                            backtest.algorithm_id
+                        )
+
+                        if verbose:
+                            click.echo(
+                                f"✓ {item} - Algorithm: "
+                                f"{backtest.algorithm_id}, "
+                                f"Range: {start_date} to {end_date}"
+                            )
+
+                valid_backtests += 1
+            else:
+                if verbose:
+                    click.echo(
+                        f"⚠️  Warning: {item} - No backtest runs found"
+                    )
+                invalid_dirs += 1
+
+        except Exception as e:
+            if verbose:
+                click.echo(f"✗ {item} - Not a valid backtest: {str(e)}")
+            invalid_dirs += 1
+            continue
+
+    # Sort algorithm IDs in each checkpoint for consistency
+    for date_range_key in checkpoints:
+        checkpoints[date_range_key].sort()
+
+    # Write checkpoint file
+    with open(output_file, 'w') as f:
+        json.dump(checkpoints, f, indent=4)
+
+    # Print summary
+    if verbose:
+        click.echo("-" * 60)
+
+    click.echo("\n✓ Checkpoint validation complete!")
+    click.echo(f"  Valid backtests found: {valid_backtests}")
+    click.echo(f"  Invalid/skipped directories: {invalid_dirs}")
+    click.echo(f"  Total date ranges: {len(checkpoints)}")
+    click.echo(f"  Checkpoint file saved to: {output_file}\n")
+
+    if verbose and checkpoints:
+        click.echo("Date ranges found:")
+        for date_range_key, algorithm_ids in sorted(checkpoints.items()):
+            click.echo(
+                f"  {date_range_key}: {len(algorithm_ids)} algorithm(s)"
+            )
+
+    return checkpoints
+
+
+@click.command()
+@click.argument(
+    'directory',
+    type=click.Path(exists=True, file_okay=False, dir_okay=True),
+    required=True
+)
+@click.option(
+    '--output',
+    '-o',
+    type=click.Path(),
+    default=None,
+    help='Output path for the checkpoint file. '
+         'Defaults to checkpoints.json in the target directory.'
+)
+@click.option(
+    '--verbose',
+    '-v',
+    is_flag=True,
+    default=False,
+    help='Print detailed information about each backtest found.'
+)
+def command(directory, output, verbose):
+    """
+    Validate a directory for backtest checkpoints and create/update
+    checkpoints.json.
+
+    This command scans DIRECTORY for backtest results, validates
+    each subdirectory to check if it contains a valid backtest, and
+    creates a checkpoints.json file mapping date ranges to algorithm IDs.
+
+    Example usage:
+
+    \b
+        # Validate backtests in a directory
+        iaf validate-checkpoints /path/to/backtest/results
+
+    \b
+        # With verbose output
+        iaf validate-checkpoints /path/to/backtest/results --verbose
+
+    \b
+        # Save to a custom location
+        iaf validate-checkpoints /path/to/backtest/results -o
+        /path/to/checkpoints.json
+    """
+    try:
+        validate_and_create_checkpoints(
+            directory_path=directory,
+            output_file=output,
+            verbose=verbose
+        )
+    except Exception as e:
+        raise click.ClickException(f"Error validating checkpoints: {str(e)}")

investing_algorithm_framework/create_app.py

@@ -1,20 +1,54 @@
-from investing_algorithm_framework.app import App
+import os
+import logging
+import inspect
+from dotenv import load_dotenv
+
+from .app import App
 from .dependency_container import setup_dependency_container
+from .domain import AppMode, APPLICATION_DIRECTORY, APP_MODE
+
+logger = logging.getLogger("investing_algorithm_framework")
 
 
 def create_app(
-    config={},
-    stateless=False,
-    web=False,
-    initialize=True
-):
-    app = App(config=config, web=web, stateless=stateless)
+    config: dict = None,
+    state_handler=None,
+    web: bool = False,
+    name=None
+) -> App:
+    """
+    Factory method to create an app instance.
+
+    Args:
+        config (dict): Configuration dictionary
+        web (bool): Whether to create a web app
+        state_handler (StateHandler): State handler for the app
+        name (str): Name of the app
+
+    Returns:
+        App: App instance
+    """
+    # Load the environment variables
+    load_dotenv()
+
+    app = App(state_handler=state_handler)
     app = setup_dependency_container(
         app,
         ["investing_algorithm_framework"],
         ["investing_algorithm_framework"]
     )
+    app.name = name
+
+    if config is not None:
+        app.set_config_with_dict(config)
+
+    if web:
+        app.set_config(APP_MODE, AppMode.WEB.value)
+
+    # Add the application directory to the config
+    caller_frame = inspect.stack()[1]
+    caller_path = os.path.abspath(caller_frame.filename)
+    app.set_config(APPLICATION_DIRECTORY, caller_path)
 
-    if initialize:
-        app.initialize()
+    logger.info("Investing algorithm framework app created")
     return app