Getting Started with bonsai-io#

This guide walks through preparing a development environment, obtaining the required datasets, and validating your installation.

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 will contain the _bonsai/ data bundle.

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

Clone the repository#

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

Editable install for development#

pip install -e .[testing]

Install a specific version#

git checkout tags/<version>
pip install .

Upgrade an existing clone#

git pull origin main
pip install .

To pin bonsai-io as a dependency of another project, reference the Git repository directly:

# pyproject.toml
bonsai-io = { git = "ssh://git@gitlab.com/bonsamurais/bonsai/build/hybrid_sut.git" }

Verify the Setup#

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

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

  3. Open docs/_build/html/index.html to view the generated site locally

CI expects pytest, flake8, and tox -e docs to pass before a merge request is accepted.

Working with the Docs#

  • Documentation is written in Markdown (MyST) and rendered with pydata_sphinx_theme

  • Each page exposes an “Edit on GitLab” button; use it to raise quick documentation merge requests

  • A floating “How can we improve this page?” widget links directly to pre-filled GitLab issue forms

  • Remember to record doc-facing changes in docs/CHANGELOG.md

Helpful Commands#

Task

Command

Run all tests

pytest

Lint source + tests

flake8 src tests

Build docs

tox -e docs

Clean build artefacts

tox -e clean

Next Steps#

  • Read docs/methodology.md for an overview of the supply–use methodology

  • Explore workflow entry points in workflow_manager.py

  • Consult tests/ for examples of prepared fixtures and task-level tests