Installation

This guide walks through setting up BDPD from source.

Prefer a containerized environment? See Installation — Docker for a parallel path that needs only Docker on the host.

---

Prerequisites

Tool	Minimum Version	Why
git	any recent	Clone the repository
Node.js	≥ 20	Platform runtime (Express)
npm	bundled with Node	Node.js dependencies
Python 3	≥ 3.12	Agents, experiments, tools
uv	any recent	Python venv management

The setup.sh script auto-validates all prerequisites.

---

Step 1: Clone

git clone https://gitlab.com/bdpd/bdpd.git
cd bdpd

---

Step 2: Run Setup

./scripts/setup.sh

This script performs four steps automatically:

1. Environment check — validates git, Node.js, npm, Python, and uv are installed
2. Python venv — creates venv_py_bdpd/ with Python 3.12 via uv
3. Python dependencies — installs requirements.txt (openai, flask, numpy, matplotlib, etc.)
4. Node.js dependencies — runs npm install (Express)

---

Step 3: Activate the Environment

source venv_py_bdpd/bin/activate

Or run commands directly with uv:

uv run --python venv_py_bdpd/bin/python <command>

---

Step 4: Verify

Start the platform and confirm it responds:

node main.js &
sleep 2
curl -s http://localhost:3000/api/health

You should see {"ok": true, "ts": "..."}. The static landing page is served at http://localhost:3000/ (open in a browser).

To verify the Python environment, run the shell checker:

./scripts/check_env.sh

Output should end with: All checks passed.

shared/bdpd_check_env.py is a library, not a CLI — it is meant to be imported by entry point scripts (from bdpd_check_env import require_venv; require_venv()). Running it directly produces no output.

---

What Gets Installed

Component	Location	Contents
Python venv	venv_py_bdpd/	Python 3.12 with all dependencies from requirements.txt
Node modules	node_modules/	Express and any other package.json dependencies
Configuration	config/	Game defaults (commons params, agent params, observability)
Card data	cards/	Card definitions (cards_v03.json)

---

Troubleshooting

uv: command not found

curl -LsSf https://astral.sh/uv/install.sh | sh

Python version too old

Install Python ≥ 3.12 via your system package manager, or let uv manage it:

uv python install 3.12

Node.js version too old

On Ubuntu/Debian, use NodeSource:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

requirements.txt not found

Ensure you are in the project root and the file exists. If it's missing, re-clone the repository.

Permission errors on setup.sh

chmod +x scripts/setup.sh scripts/check_env.sh