Installation

BanditDB has two components: the Rust engine and a client SDK (Python or TypeScript/JavaScript). Start the engine first, then install the SDK.

1. Start the Engine

Binary (fastest, no Docker required)

curl -fsSL https://raw.githubusercontent.com/dynamicpricing-ai/banditdb/main/scripts/install.sh | sh
banditdb
curl http://localhost:8080/health   # {"status":"ok"}

Docker

docker run -d -p 8080:8080 \
  -e BANDITDB_API_KEYS=admin-key=admin \
  -v banditdb_data:/data \
  simeonlukov/banditdb:latest

Docker Compose (recommended for production)

Includes persistence, RBAC, and auto-checkpointing:

curl -fsSL https://raw.githubusercontent.com/dynamicpricing-ai/banditdb/main/docker-compose.yml -o docker-compose.yml
# Set BANDITDB_API_KEYS=admin-key=admin;app-key=writer in .env
docker compose up -d

Key environment variables:

Kubernetes (Helm)

helm install banditdb ./helm/banditdb \
  --set auth.apiKeys="admin-key=admin;app-key=writer" \
  --set persistence.size=10Gi \
  --set ingress.enabled=true \
  --set ingress.host=banditdb.example.com

Build from source

Requires Rust 1.97 or newer.

git clone https://github.com/dynamicpricing-ai/banditdb
cd banditdb
cargo build --release                        # standard build
# cargo build --release --features neural   # with NeuralLinUCB
./target/release/banditdb

2. Install the SDK

Python

pip install banditdb-python

from banditdb import Client
db = Client("http://localhost:8080", api_key="your-secret-key")

Smallest possible working loop — create a campaign, ask for a decision, report the outcome:

# One campaign: which button color converts best?
db.create_campaign("button-color", arms=["red", "green", "blue"], feature_dim=2)

# Ask for a decision. Context: [is_mobile, is_returning_visitor]
arm, interaction_id = db.predict("button-color", [1.0, 0.0])
print(arm)  # e.g. "green"

# Report what happened: 1.0 = clicked, 0.0 = ignored
db.reward(interaction_id, 1.0)

Normalise your context if the features are on different scales. It matters more than it looks: the exploration term scales with the vector's magnitude, and unnormalised input still converges — just far more slowly, with no error to tell you. On one benchmark this single change cut cumulative regret from 2,026 to 709.

from banditdb import normalize_context

ctx = normalize_context([age, income, sessions])   # unit L2 norm
arm, iid = db.predict("button-color", ctx)

SDK 0.2.0 requires server 2.0.0 or newer. It also validates locally before sending, so a bad context raises ValueError naming the offending index rather than costing a round trip.

That is the whole API surface you need day to day. See Quick Start for a realistic end-to-end example.

TypeScript / JavaScript

npm install banditdb-js

import { BanditDBClient } from "banditdb-js";
const db = new BanditDBClient({ url: "http://localhost:8080", apiKey: "your-secret-key" });

await db.createCampaign("button-color", { arms: ["red", "green", "blue"], feature_dim: 2 });

const { arm_id, interaction_id } = await db.predict("button-color", [1.0, 0.0]);
console.log(arm_id); // e.g. "green"

await db.reward(interaction_id, 1.0);

HTTP (no SDK)

Every SDK call is a plain JSON HTTP request. Use X-Api-Key header when auth is enabled:

curl -s http://localhost:8080/health
# {"status":"ok",...}

curl -s -X POST http://localhost:8080/predict \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-secret-key" \
  -d '{"campaign_id":"my-campaign","context":[1.0,0.5,0.3]}'