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.

pip install fenn

Basic Usage Steps

The typical FENN workflow is:

Generate a project skeleton and configuration file.
Implement your training logic using the FENN entrypoint.
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.

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:

# ---------------------------------------
# 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.

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:

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.