Run from source

Clone and install#

install.sh runs installer/engine.py setup, the same installer the desktop app runs with buttons. It describes your computer's processors, asks where models should run, then installs into ./.venv:

Running it again is safe. To move models to a different processor, run it again with another --device; it replaces the PyTorch build and keeps everything else.

git clone https://github.com/BudEcosystem/Bud-Decision-Engine.gitcd Bud-Decision-Engine# asks where models should run./install.sh# or choose up front: cuda, mps, xpu, rocm or cpu./install.sh --device cpu

git clone https://github.com/BudEcosystem/Bud-Decision-Engine.gitcd Bud-Decision-Engine# asks where models should runpowershell -ExecutionPolicy Bypass -File install.ps1# or choose up front: cuda, xpu or cpupowershell -ExecutionPolicy Bypass -File install.ps1 --device cpu

Run the studio#

run.sh starts the server from .venv and passes its options through. Open http://127.0.0.1:8420 in a browser; the interface is the same one the desktop app shows. Stop the server with Ctrl+C, which ejects every loaded model first.

On Linux, scripts/open.sh starts the studio in the background if it is not running and opens it in your browser, and scripts/install-desktop-launcher.sh adds it to your applications menu.

On its first start the studio creates its database and the starter templates, as the output shows.

python -m basal.doctor checks the environment: that PyTorch can use the GPU and that every model library imports. It prints one line per library and All good when nothing is missing. Each GPU failure is named for what it is: no GPU, the GPU out of memory at that moment, or a test calculation that failed.

# http://127.0.0.1:8420./run.sh# another port; or reachable from your network, with a key./run.sh --port 8500BASAL_API_KEY=change-me ./run.sh --host 0.0.0.0# check the environment.venv/bin/python -m basal.doctor

# http://127.0.0.1:8420.venv\Scripts\python -m basal.server# another port; or reachable from your network, with a key.venv\Scripts\python -m basal.server --port 8500$env:BASAL_API_KEY = "change-me".venv\Scripts\python -m basal.server --host 0.0.0.0# check the environment.venv\Scripts\python -m basal.doctor

  Bud Decision Studio 0.3.0  at  http://localhost:8420[history] database ready (migrations [1, 2, 3] applied)[templates] 30 starter template(s) added or updated

Environment variables#

The server reads these when it starts. A checkout keeps its data in ./data; the desktop app sets BASAL_DATA to its own folder.

Two more are read by the tests: BASAL_TEST_URL, the studio to test (default http://127.0.0.1:8420), and BASAL_TEST_MODEL (default laya).

The studio sets a few variables itself for the processes it starts. Workers run with HF_HUB_OFFLINE=1, so loading a model never reaches the network, and downloads run with HF_HUB_OFFLINE=0. You do not need to set these.

# A second studio beside the app: its own history,# the same models, no downloads of its ownBASAL_DATA=~/studio-b BASAL_PORT=8421 BASAL_NO_DOWNLOADS=1 ./run.sh# Serve your network with a key, and allow one web app# to call it from the browserBASAL_API_KEY=change-me \BASAL_CORS_ORIGINS=http://localhost:3000 \./run.sh --host 0.0.0.0# Models on another diskHF_HOME=/data/huggingface ./run.sh

Work without a GPU or models#

BASAL_FAKE_MODEL=1 adds Fake Decider (fake-decider) to the model list. It loads instantly, reads every kind of media, needs no download, and computes its probabilities from a hash of the situation, the question and each option, so the same request always gets the same answer. The test suites and CI use it to exercise the whole API, history included, without PyTorch.

Run it with a throwaway data folder so its decisions stay out of your real history.

BASAL_FAKE_MODEL=1 BASAL_DATA=/tmp/studio-dev ./run.sh --port 8479 &curl -s http://127.0.0.1:8479/v1/systemone -H 'content-type: application/json' -d '{  "model": "fake-decider",  "state": "The package arrived crushed.",  "questions": {    "damaged": {"type": "noul", "instructions": "Was the item damaged?"},    "team": {"type": "choice", "instructions": "Who should handle this?",             "criteria": {"returns": "refunds and replacements",                          "shipping": "carriers and delivery"}}  }}'

{  "model": "fake-decider",  "answers": {    "damaged": {"type": "noul", "noul": 0.467},    "team": {      "type": "choice",      "choice": "returns",      "probabilities": {"returns": 0.8975, "shipping": 0.1025},      "confidence": 0.7949    }  },  "usage": {"input_tokens": 7, "output_tokens": 0}}

Change the interface#

The interface has no build step. Edit the files in ui/, then reload the page: the server sends them with cache-control: no-cache, so the browser always checks for the newer version. DESIGN.md describes its design system.

The 30 starter templates (builtin/<scenario>) are generated from the Playground's examples. After changing ui/js/examples.js or ui/js/model-guides.js, regenerate basal/builtin_templates.json; the template tests fail when the two are out of sync.

node scripts/export-builtins.mjs

node scripts/export-builtins.mjs --check

builtin_templates.json is in sync

Development dependencies#

The test tools are not part of the engine install. Add them to .venv from requirements-dev.txt: pytest, jsonschema, PyYAML and the official TypeSafe Python SDK (typesafe-sdk 0.7.2) for the conformance test. The JavaScript SDK test needs npm install in tests/js, and the end-to-end check needs Playwright with Chromium.

What each suite covers and how to run it: Testing.

uv pip install --python .venv/bin/python -r requirements-dev.txt(cd tests/js && npm install)uv pip install --python .venv/bin/python playwright.venv/bin/python -m playwright install chromium