BanditDB

BanditDB Python SDK

The official Python client and Model Context Protocol (MCP) server for BanditDB — the ultra-fast, lock-free Contextual Bandit database written in Rust.

BanditDB abstracts away the complex linear algebra of Reinforcement Learning (LinUCB, Thompson Sampling) behind a dead-simple API. Build real-time personalizers, dynamic A/B tests, and give LLM agents mathematically rigorous persistent memory.

mcp-name: com.banditdb/mcp

Installation

pip install banditdb-python

Requires the BanditDB Rust server running (default: http://localhost:8080).

1. Standard SDK Usage

The client features automatic connection pooling, exponential backoff retries, and strict timeouts.

from banditdb import Client, BanditDBError

Connect to the BanditDB server.

Pass api_key if BANDITDB_API_KEY is set on the server.

db = Client( url="http://localhost:8080", timeout=2.0, api_key="your-secret-key", # omit if server runs without auth )

try:

1. Create a campaign (run once at startup)

algorithm defaults to "linucb"; use "thompson_sampling" for Bayesian exploration

db.create_campaign( campaign_id="checkout_upsell", arms=["offer_discount", "offer_free_shipping"], features=["is_mobile", "cart_value", "is_returning_user"], )

or: db.create_campaign(..., algorithm="thompson_sampling")

2. A user arrives — ask the database what to show them.

Scale each value to 0–1; the SDK puts them in order, adds a constant 1

and normalises the vector.

arm_id, interaction_id = db.predict("checkout_upsell", { "is_mobile": 1.0, "cart_value": min(cart_total / 200, 1.0), "is_returning_user": 0.0, }) print(f"Showing: {arm_id}") # e.g., "offer_free_shipping"

3. The user clicked — send the reward

db.reward(interaction_id, reward=1.0)

except BanditDBError as e: print(f"Database error: {e}")

Named features or a vector. With features=[...] the campaign stores the feature order in its metadata, and predict, batch_predict and interact accept a dict keyed by name. A missing or misspelt name raises ValueError before any request is sent. Campaigns created in the BanditDB console accept dicts too. The order is read once per campaign with campaign_info() and cached on the client. To manage the vector yourself, pass feature_dim instead and send lists — normalize_context() scales one to unit length.

All Client methods

Health

Campaigns

Predict & Reward

Data & Export

Budget constraints

Server 2.3.0+. Give a campaign one or more budgeted resources and per-arm costs; the server learns a shadow price per resource and steers spend to last the horizon, choosing costly arms only where their uplift is worth it.

from banditdb import Client, PacingConfig, ResourceConstraint

db.create_campaign( "promos", ["none", "discount_10", "discount_20"], feature_dim=4, pacing=PacingConfig(resources=[ ResourceConstraint( name="promo_budget", budget=5_000.0, # units available over the horizon horizon=100_000, # decisions the budget should last arm_costs={"discount_10": 1.0, "discount_20": 2.0}, # "none" costs 0 ), ]), )

Arms added later declare their own costs

db.add_arm("promos", "discount_30", costs={"promo_budget": 3.0})

for r in db.pacing("promos")["resources"]: print(f"{r['name']}: {r['utilization']:.0%} spent, lambda={r['lambda']:.3f}")

Worth knowing:

• Budget is spent at `predict`, not `reward`. A recommendation you never act on still consumes budget.
• Budget never resets and pacing is immutable. Once spent, costly arms stay unselectable until the campaign is recreated.
• arm_costs keys must be campaign arms. The server would silently treat a misspelt arm as free; the SDK raises ValueError instead.
• Predicts on a pacing campaign can return 503 if the server's WAL is saturated.
• Downgrading the server below 2.3.0 silently drops pacing.

2. The AI "Hive Mind" (Model Context Protocol)

Standard LLM agents are stateless — if they route a task to the wrong model and fail, they repeat the same mistake tomorrow. BanditDB's built-in MCP server gives the entire agent swarm shared persistent memory.

Starting the MCP server

# Set environment variables before starting

export BANDITDB_URL=http://localhost:8080 export BANDITDB_API_KEY=your-secret-key # omit if server runs without auth

banditdb-mcp

Connecting to Claude Desktop

Add to your Claude configuration file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{

"mcpServers": { "banditdb": { "command": "banditdb-mcp", "args": [], "env": { "BANDITDB_URL": "http://localhost:8080", "BANDITDB_API_KEY": "your-secret-key" } } } }

The agent swarm now has twelve tools:

Every decision made by any agent in the network improves the routing for all future agents.

3. Data Science & Offline Evaluation

BanditDB event-sources every prediction and reward to a Write-Ahead Log (WAL). Calling checkpoint() compiles completed prediction→reward pairs into Snappy-compressed Parquet files — one per campaign — for offline analysis with Polars or Pandas.

Every prediction is guaranteed to appear in the Parquet file even if its reward arrives hours later: BanditDB re-emits in-flight interactions at each checkpoint so delayed rewards are always captured in a future cycle.

# Checkpoint: snapshot models, write Parquet, rotate the WAL.

Call this on a schedule or after significant traffic.

summary = db.checkpoint() print(summary)

"Checkpoint written and WAL rotated: 2 campaigns, offset 4821 bytes,

150 interactions exported, 3 in-flight re-emitted"

List which Parquet files are available

print(db.export())

'Parquet files in /data/exports: ["llm_routing.parquet"]'

Load directly from the mounted volume into Polars.

Flat schema: interaction_id | arm_id | reward | predicted_at | rewarded_at | propensity | feature_0 | ...

import polars as pl df = p