Development Setup

How to set up a full development environment with linting, CI, and verification.

---

Prerequisites

Same as user setup — see Installation. Additional tools for development:

Tool	Purpose
ruff	Python linting and formatting
ESLint	JavaScript linting (via npx, no global install needed)
uv	Python package and venv management

---

Full Dev Environment

# 1. Clone and run setup
git clone https://gitlab.com/bdpd/bdpd.git
cd bdpd
./scripts/setup.sh
source venv_py_bdpd/bin/activate

# 2. Install dev tools
uv pip install --python venv_py_bdpd/bin/python ruff

# 3. Verify
./scripts/check_env.sh
python shared/bdpd_check_env.py

---

Linting

Python (ruff)

# Check all Python source directories
ruff check shared/ agents/ experiments/ tools/

# Auto-fix
ruff check --fix shared/ agents/ experiments/ tools/

Configuration in pyproject.toml (rules: E, F, I, W, UP; ignores E501).

JavaScript (ESLint)

# Run on platform source
npx eslint platform/

Configuration is embedded in .gitlab-ci.yml (default rules, sourceType: module).

---

Running Locally

Platform

node main.js
# → listening on http://localhost:3000

LLM Middleman (standalone)

python agents/bdpd_agent.py
# → listening on http://localhost:5001

Card Game (heuristic demo)

python agents/cards_ai_play.py \
  --deck1 warrior --deck2 temple \
  --cards cards/cards_v03.json --demo --games 1

---

CI Pipeline

Defined in .gitlab-ci.yml (runs on every push):

Stage	Job	Command
lint	lint:python	ruff check shared/ agents/ experiments/
lint	lint:node	npx eslint platform/*.js
deploy	pages	mkdocs build --strict --site-dir public (main branch only)

The deploy job installs mkdocs-material and builds the documentation site to GitLab Pages. It only runs on the main branch.

Running CI Locally

# Python lint
ruff check shared/ agents/ experiments/

# Node.js lint
npx eslint platform/*.js

# Docs build
mkdocs build --strict

---

Testing

Currently no automated test suite exists. Smoke tests:

# Platform responds
curl -s http://localhost:3000/api/health && echo "OK"

# Card game simulates
python agents/cards_ai_play.py \
  --deck1 warrior --deck2 temple \
  --cards cards/cards_v03.json --demo --games 1

# Card generator runs
python tools/card_generator/generate_cards.py \
  --cards-json cards/cards_v03.json --dpi 72

---

Adding New Code

New Built-in Agent Strategy

1. Add a class in agents/built-in.js extending BaseAgent
2. Register it in STRATEGY_REGISTRY
3. Add documentation in docs/platform/agents.md

New Experiment Sweep

1. Create a JSON definition in experiments/definitions/
2. Add the sweep name to experiments/experiment.js (if using the Node.js runner) or run with python experiments/sweep.py --definition

New Card Archetype

1. Add 20 card entries to cards/cards_v03.json
2. Add faction colours to tools/card_generator/templates/faction_config.json
3. Run generate_cards.py to produce print-ready images

New Perturbation Type

1. Add to PERTURBATION_TYPES constant in platform/perturbation.js
2. Add a case in applyPerturbation()
3. Document in docs/platform/perturbations.md