Getting Started#

See online documentation here.

Package Layout#

The repository provides two installable packages:

  • bonsai-io: core workflow orchestration, including export tasks

  • bonsai-export: converter library (SimaPro/Brightway) consumed by bonsai-io

Prerequisites#

  • Python: 3.9-3.12 (project CI currently targets 3.10-3.11). Check with python --version.

  • Git: ensure git --version succeeds.

  • Build tooling: pip >= 22 and a C/C++ compiler for optional native dependencies.

  • BONSAI account: request an API token via the bonsai.io portal. First create a user if you do not yet have one.

Configure Environment#

Set the BONSAI_HOME environment variable to the directory that contains the _bonsai/ data bundle parent.

# Windows PowerShell
$env:BONSAI_HOME = "C:\\bonsai_data"

# macOS / Linux (shell profile)
export BONSAI_HOME="$HOME/bonsai_data"

BONSAI_HOME must be the parent directory of _bonsai/. For example, if your data resides in /data/bonsai/_bonsai/, set BONSAI_HOME=/data/bonsai.

Store long-lived secrets (such as BONSAI_TOKEN) in your shell profile or a password manager; never commit them to the repository.

Accessing Data#

For questions about dataset availability or onboarding:

Install bonsai-io and bonsai-export#

Clone the repository#

git clone git@gitlab.com:bonsamurais/bonsai/build/hybrid_sut.git
cd hybrid_sut

Editable install for development#

pip install -e "packages/bonsai-io[testing]"

Install exporter package#

pip install -e packages/bonsai-export

Optional: Brightway2 exporter dependency#

The Brightway2 exporter dependency (bw2io) is intentionally optional:

pip install -e "packages/bonsai-export[bw2]"

Install a specific version#

git checkout tags/<version>
pip install packages/bonsai-io
pip install packages/bonsai-export

Upgrade an existing clone#

git pull origin main
pip install -e "packages/bonsai-io[testing]"
pip install -e packages/bonsai-export

Verify the Setup#

  1. Run a smoke test: pytest -k versions -q

  2. Build docs to confirm Sphinx/requirements: make -C docs html

  3. Open docs/_build/html/index.html locally

CI expects pytest, flake8, and tox -e docs to pass before merge.

Release Tags#

Use package-specific tags for independent versions:

  • bonsai-io-vX.Y.Z releases packages/bonsai-io

  • bonsai-export-vX.Y.Z releases packages/bonsai-export