.. _quick_start:

Quick Start Guide
=================

This guide provides a streamlined path to setting up the Backtest Engine and executing your first portfolio simulation. The engine uses a high-performance PyArrow-based architecture to handle data processing and backtesting.

Environment Configuration
-------------------------

The Backtest Engine requires **Python 3.12 or 3.13**. It is recommended to use a virtual environment to manage dependencies and avoid conflicts.

1. **Create and Activate Environment**:

   Using Conda:

   .. code-block:: console

      conda create --name backtest_engine python=3.12
      conda activate backtest_engine

   Using venv:

   .. code-block:: console

      python -m venv .venv

   .. code-block:: console

      # Windows
      .venv\Scripts\activate

   .. code-block:: console

      # Linux / macOS
      source .venv/bin/activate

2. **Install the Backtest Engine**:

   Run the pip install command from your license welcome email:

   .. code-block:: console

      pip install kaxanuk-backtest-engine --extra-index-url https://license:{YOUR_LICENSE_KEY}@{SERVER}/simple/

   .. note::

      The full command with your license key is included ready to copy in the welcome email you receive after purchase.

3. **Initialize Project Folders**:

   Generate the required directory structure and the Excel configuration template.

   .. code-block:: console

      kaxanuk.backtest_engine init excel

4. **Set your license key**:

   Open ``Config/.env`` and replace the placeholder with your actual license key:

   .. code-block:: text

      KNPC_API_KEY_KAXANUK=LIC-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

   This is loaded automatically by the entry script — no terminal environment variables needed.

Environment Structure
---------------------

The initialization process creates the following essential folders:

* **Config/**: Contains ``backtest_engine_parameters.xlsx`` for defining simulation parameters and column mappings.
* **Input/Data/**: Directory for market data files (CSV or Parquet).
* **Input/Portfolios/**: Directory for portfolio weight files (CSV or Excel).
* **Output/**: Directory where generated backtest results are stored.

Data Preparation
----------------

Portfolio Files
~~~~~~~~~~~~~~~

The engine supports both horizontal and vertical layouts. The ``PortfolioConfigurationService`` automatically detects the format based on the first column name.

* **Horizontal**: First column must be named **"Ticker"**. Subsequent columns represent rebalancing dates.
* **Vertical**: First column must be named **"date"**. Subsequent columns represent ticker symbols.

Market Data
~~~~~~~~~~~

Market data files must include a date column and at least three price columns. Column names are fully configurable — you map them to their roles (commission price, trade execution price, mark-to-market price) in the configuration file. One file per ticker, named ``{TICKER}.csv`` or ``{TICKER}.parquet``.

Execution
---------

Once your data is placed in the ``Input`` folders and parameters are configured in the ``Config`` Excel file, you can run the backtest using one of the following methods.

Command Line Interface
~~~~~~~~~~~~~~~~~~~~~~

The most direct way to execute the engine is through the CLI:

.. code-block:: console

   python -m kaxanuk.backtest_engine.services.cli autorun

Python Script
~~~~~~~~~~~~~

You can also run the engine programmatically using the main entry point:

.. code-block:: python

   import kaxanuk.backtest_engine.backtest_engine
   from kaxanuk.backtest_engine.config_handlers.excel_configurator import ExcelConfigurator
   from kaxanuk.backtest_engine.input_handlers.csv_input import CsvInput
   from kaxanuk.backtest_engine.input_handlers.csv_portfolio_input_handler import CsvPortfolioInputHandler
   from kaxanuk.backtest_engine.services.env_loader import load_config_env

   # Load Config/.env (license key)
   load_config_env()

   # 1. Load configuration from the Excel template
   configurator = ExcelConfigurator(file_path='Config/backtest_engine_parameters.xlsx')
   configuration = configurator.get_configuration()

   # 2. Set up data handlers
   market_data_handler = CsvInput(input_dir=configuration.input_market_data_directory)
   portfolio_handler = CsvPortfolioInputHandler(base_dir=configuration.input_portfolio_directory)

   # 3. Run the backtest
   results = kaxanuk.backtest_engine.backtest_engine.main(
       configuration=configuration,
       input_handlers=[market_data_handler],
       portfolio_handlers=[portfolio_handler],
   )

Pre-Execution Checklist
-----------------------

Before running the backtest, ensure:

* Portfolio files are correctly formatted and placed in ``Input/Portfolios``.
* Market data files are available in ``Input/Data`` with the proper column structure.
* The configuration file ``backtest_engine_parameters.xlsx`` is completed.
* All rebalancing dates in portfolio files exist within the market data date range.
* No null values are present in any input files.