Quickstart
==========

This section provides a guided overview of setting up FENN in a new environment, defining a minimal project structure, and executing an initial experiment through a configuration-driven entrypoint. By the end of this section, you will have a functioning Python script that relies on ``fenn.yaml`` for configuration rather than hardcoded parameters.

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

FENN is distributed as a standard Python package and can be installed from PyPI.
It is recommended to use a virtual environment (``venv`` or ``conda``) to keep your project dependencies isolated.

.. code-block:: bash

    pip install fenn

Basic Usage Steps
-----------------

The typical FENN workflow is:

1. Generate a project skeleton and configuration file.
2. Implement your training logic using the FENN entrypoint.
3. Run the script as a normal Python module while FENN takes care of configuration
   parsing, logging, and integration with external tools.

1. Initialize a Project
^^^^^^^^^^^^^^^^^^^^^^^

Run the CLI tool to generate a template and config file in the current directory.
This will usually create a basic ``main.py`` script and a default ``fenn.yaml`` file.

.. code-block:: bash

    fenn init

After running this command, you can immediately open the generated files and adapt them to your model, dataset, and training loop.
You can configure the ``fenn.yaml`` file with the hyperparameters and options for your project. The structure of the ``fenn.yaml`` file is:

.. code-block:: yaml

    # ---------------------------------------
    # FENN Configuration (Modify Carefully)
    # ---------------------------------------

    project: project_name

    logger:
        dir: logger

    wandb:
        entity: your_wandb_account

    seed: seed
    device: 'cpu'/'cuda'

    training:
        epochs: n_epochs
        lr: lr
        weight_decay: wd
        batch: batch_size

    testing:
        batch: batch_size

.. tip::
    You can add new sections as needed (for example, ``model``, ``optimizer``, ``scheduler``) and access them via the same keys in ``args``. This makes it easy to manage multiple experiments by maintaining different YAML files.

Set your WANDB API key in the ``.env`` file.

2. Write Your Code
^^^^^^^^^^^^^^^^^^

You can work on the ``main.py`` script to create your project. Use the ``@app.entrypoint`` decorator. Your configuration variables are automatically passed via ``args`` as a nested dictionary that mirrors the structure of ``fenn.yaml``.
Inside ``main``, you never hardcode hyperparameters; instead, you read them from ``args`` so that experiments can be reproduced or changed just by editing YAML.

.. code-block:: python

    from fenn import FENN

    app = FENN()

    @app.entrypoint
    def main(args):
        # 'args' contains your fenn.yaml configurations
        print(f"Training with learning rate: {args['training']['lr']}")

        # Your logic here...

    if __name__ == "__main__":
        app.run()

4. Run It
^^^^^^^^^

Once the code and configuration are in place, you can start an experiment by
running your entrypoint script as a normal Python program:

.. code-block:: bash

    python main.py

During execution, FENN will:

- Parse ``fenn.yaml`` and inject its contents into ``args``.
- Initialize logging so that standard output and configuration are captured.
- Optionally connect to remote trackers (for example, WandB) if enabled in the config.