Local Execution & Configuration#

To maximize flexibility and testability, this project does not hardcode configuration paths. Instead, it relies on environment variables injected at runtime, falling back to command-line interface (CLI) arguments.

1. The .env File#

For local development, we use a .env file to store paths and secrets. This file should be placed in the root of the repository and must never be committed to version control.

Template (.env.example)#

We provide an .env.example file in the repository. Copy this file to .env and adjust the values as needed:

# ====================================================================
# Environment Configuration Template
# ====================================================================

# The absolute or relative path to your JSON configuration file.
# REQUIRED if not passed via the --config-file CLI flag.
CONFIG_PATH=./config/settings.json

# The directory where generated files and results will be saved.
# REQUIRED if not passed via the --output-dir CLI flag.
OUTPUT_DIR=./results

2. Running Scripts Locally#

This project manages dependencies via pyproject.toml and relies on environment variable injection before script execution. There are two ways to run the code locally.

Setup (First Time Only)#

Ensure your virtual environment is created and your dependencies are synced using uv:

uv sync

Option B: Using standard Virtual Environment Activation#

If you prefer to work within an activated virtual environment, you will need to manually inject the .env file using the dotenv CLI (which is installed via our pyproject.toml dependencies).

1. Activate the environment:

# On Linux/macOS
source .venv/bin/activate

# On Windows
.venv\Scripts\activate

2. Run the script via dotenv:

dotenv run -- python scripts/drafts/hello.py

Note

Both execution methods ensure that hello.py thinks the environment variables were natively provided by the operating system. This makes your local development environment behave exactly like a production Docker container.

3. Using CLI Overrides#

The application is built with argparse handling the fallback logic. If you need to quickly run the script with a different configuration or output directory, you can override the injected .env variables by passing explicit arguments to the script:

Using uv:

uv run python scripts/drafts/hello.py \
    --config-file ./config/experiment_2.json \
    --output-dir ./results/experiment_2

Using activated environment:

dotenv run -- python scripts/drafts/hello.py \
    --config-file ./config/experiment_2.json \
    --output-dir ./results/experiment_2

If neither the environment variables nor the CLI arguments are provided, the script will intentionally fail and raise a clean error to prevent accidental runs with missing configurations.