.. _quick_start:

Quick Start
===========

.. GET_STARTED_SUMMARY_BEGIN

Installation
------------

**Requirements**

- Python 3.12 or 3.13

**Installing**

.. code-block:: bash

   pip install kaxanuk-attribution_analysis  --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.

The same command installs ``kaxanuk-license-client``, the license check KaxaNuk's libraries share, from the same index.

You can acquire your license `here <https://www.kaxanuk.mx/lab>`_.

Interested in collaborating on a custom project? Get in touch at **software@kaxanuk.mx**.

**Initialize project structure**

1. Open a terminal in your project directory and run:

   .. code-block:: bash

      kaxanuk.attribution_analysis init excel

   This creates the following structure:

   .. code-block:: text

      project-root/
      ├── __main__.py                                   # Entry script
      ├── Config/
      │   ├── .env                                      # Environment variables (e.g. FRED_API_KEY)
      │   └── attribution_analysis_parameters.xlsx      # Configuration template
      ├── Input/
      │   ├── Data/                                     # Market data files (one per ticker)
      │   ├── Portfolios/                                # Portfolio weight files
      │   ├── Benchmark_Portfolios/                      # Benchmark weights + benchmark returns
      │   └── Factor_Models/                             # Per-factor return files
      └── Output/                                        # Analysis results

.. GET_STARTED_SUMMARY_END

**Set your license key**

Running the analysis requires a valid KaxaNuk license key. Open ``Config/.env`` and replace the
placeholder with your actual key:

.. code-block:: text

   KNAA_API_KEY_KAXANUK=LIC-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

``Config/.env`` is loaded automatically by the entry script, so you don't need to set environment
variables in your terminal. Alternatively, export ``KNAA_API_KEY_KAXANUK`` in your environment, or
keep the key in a ``.kaxanuk_license`` file in your home folder or in the working folder, on a line
of its own: ``KNAA_API_KEY_KAXANUK=<your license key>``.

Each run checks your license with the KaxaNuk license server, the one that serves every KaxaNuk
library, **for Attribution Analysis**: the key has to belong to a license that includes it, and a
license the server rejects (unknown, expired, revoked, or out of devices) stops the analysis at
once. A successful check is saved on your machine: for **24 hours** the analysis does not contact
the server at all, and when the server cannot be reached (no connection, a timeout, or an outage on
our side) it keeps working for **3 days** from the last successful check, never past the license's
own expiry date, with a warning each run saying how much of that window is left. The first run
after upgrading from version 0.2 or earlier needs the network: the check those versions saved is not
carried over.

Advanced: ``KNAA_LICENSE_SERVER_URL`` points Attribution Analysis at another license server, and
``KAXANUK_LICENSE_SERVER_URL`` does the same for every KaxaNuk library, read after it. When neither
is set, the unified KaxaNuk license server is used; a value that is not an ``http`` or ``https`` URL
stops the analysis with a ``LicenseConfigurationError`` before anything is sent.

After initialization, populate the ``Input/`` subfolders with your data (see
:ref:`data_formats`) and edit ``Config/attribution_analysis_parameters.xlsx`` (see
:ref:`configuration`).

**Usage**

Run the analysis using:

.. code-block:: bash

   kaxanuk.attribution_analysis run

The system will read the configured inputs, run the enabled attribution methodologies, and save
results in the ``Output`` folder (and launch the dashboard if configured to do so).