Der offizielle Python-Client und Model-Context-Protocol-Server (MCP) für BanditDB — die ultraschnelle, lock-freie Contextual-Bandit-Datenbank, geschrieben in Rust.
BanditDB abstrahiert die komplexe lineare Algebra des Reinforcement Learnings (LinUCB, Thompson Sampling) hinter einer denkbar einfachen API. Bauen Sie Echtzeit-Personalisierer, dynamische A/B-Tests und geben Sie LLM-Agenten mathematisch fundiertes, persistentes Gedächtnis.
pip install banditdb-pythonErfordert den laufenden BanditDB-Rust-Server (Standard: http://localhost:8080).
Related MCP server: Copilot Memory Store
Der Client bietet automatisches Connection Pooling, exponentielle Backoff-Retries und strikte 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"],
feature_dim=3,
)
# or: db.create_campaign(..., algorithm="thompson_sampling")
# 2. A user arrives — ask the database what to show them
# Context: [is_mobile, cart_value_normalized, is_returning_user]
arm_id, interaction_id = db.predict("checkout_upsell", [1.0, 0.8, 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}")Health
Methode | Beschreibung |
| Gibt |
| Gibt das vollständige Health-Dict zurück, einschließlich |
Kampagnen
Methode | Beschreibung |
| Registriert eine neue Kampagne. |
| Gibt eine Liste aller Kampagnen (aktiv und archiviert) mit |
| Gibt den vollständigen Zustand pro Arm zurück: |
| Konvergenzbericht auf Geschäftsebene. |
| Operator-Diagnose: Theta-Normen pro Arm, A_inv-Unsicherheitsgrenzen, Entropie-Health ( |
| Soft-Delete: pausiert Vorhersagen/Belohnungen, bewahrt aber alle gelernten Gewichte. Wiederherstellbar mit |
| Stellt eine archivierte Kampagne mit allen Gewichten wieder auf aktiv. |
| Löscht eine Kampagne dauerhaft. Gibt |
Vorhersage & Belohnung
Methode | Beschreibung |
| Gibt |
| Sagt bis zu 100 Kampagnen-/Kontext-Paare in einem einzigen Round-Trip voraus. Jedes Element: |
| Zeichnet das Ergebnis auf. |
Daten & Export
Methode | Beschreibung |
| Leert WAL, erstellt Snapshots der Modelle, schreibt Parquet-Shards, führt neuronales Retraining + Turnier-Evaluierung durch, rotiert WAL. Gibt eine Zusammenfassung zurück. |
| Listet Parquet-Export-Shards gruppiert nach Kampagne auf. Gibt |
Standard-LLM-Agenten sind zustandslos — wenn sie eine Aufgabe an das falsche Modell weiterleiten und scheitern, wiederholen sie denselben Fehler morgen. Der integrierte MCP-Server von BanditDB gibt dem gesamten Agentenschwarm ein gemeinsames, persistentes Gedächtnis.
# 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-mcpFügen Sie Folgendes zu Ihrer Claude-Konfigurationsdatei hinzu:
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"
}
}
}
}Der Agentenschwarm verfügt nun über neun Tools:
Tool | Was es tut |
| Erstellt eine neue Entscheidungskampagne. Akzeptiert |
| Listet alle aktiven Kampagnen auf (zeigt |
| Untersucht den Lernzustand pro Arm: |
| Konvergenzbericht auf Geschäftsebene. Sagt Ihnen, ob die Kampagne statistisch konvergiert ist und welcher Arm mit Konfidenzintervallen gewinnt. |
| Fragt BanditDB, welchen Arm es für einen gegebenen Kontext wählen soll. Gibt den Arm und eine |
| Holt Entscheidungen für mehrere Kampagnen in einem einzigen Round-Trip. Übergeben Sie eine Liste von |
| Meldet, ob die gewählte Aktion erfolgreich war (1.0) oder fehlgeschlagen ist (0.0). Aktualisiert das gemeinsame Modell. |
| Soft-Delete einer Kampagne. Pausiert Vorhersagen/Belohnungen, bewahrt aber alle gelernten Gewichte. |
| Stellt eine archivierte Kampagne mit allen Gewichten wieder auf aktiv. |
Jede Entscheidung, die ein Agent im Netzwerk trifft, verbessert das Routing für alle zukünftigen Agenten.
BanditDB protokolliert jede Vorhersage und Belohnung ereignisbasiert in einem Write-Ahead-Log (WAL). Ein Aufruf von checkpoint() kompiliert abgeschlossene Vorhersage→Belohnungs-Paare in Snappy-komprimierte Parquet-Dateien — eine pro Kampagne — für Offline-Analysen mit Polars oder Pandas.
Jede Vorhersage erscheint garantiert in der Parquet-Datei, selbst wenn ihre Belohnung Stunden später eintrifft: BanditDB gibt laufende Interaktionen bei jedem Checkpoint erneut aus, sodass verzögerte Belohnungen immer in einem zukünftigen Zyklus erfasst werden.
# 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 = pl.read_parquet("/data/exports/llm_routing.parquet")
print(df.head())
print(df.columns)Das SDK enthält drei OPE-Schätzer in banditdb.eval. Sie beantworten die Frage: „Wie hoch wäre meine durchschnittliche Belohnung unter einer anderen Policy gewesen — ohne ein Live-Experiment durchzuführen?"
Installieren Sie die Evaluierungs-Abhängigkeiten:
pip install "banditdb-python[eval]"Schätzer | Funktion | So funktioniert es | Wann verwenden |
Replay |
| Akzeptiert jede Interaktion mit Wahrscheinlichkeit | Baseline-Sanity-Check. Geringe Abdeckung ist zu erwarten — ~1/K der Interaktionen werden verwendet. |
IPS / SNIPS |
| Verwendet jede Interaktion mit Importance-Gewicht | Primärer Schätzer. Verwenden Sie ihn, wenn Sie genügend Daten haben, aber volle Abdeckung wünschen. |
Doubly Robust |
| Passt ein lineares Belohnungsmodell an und wendet dann eine IPS-Korrektur auf die Residuen an. Konsistent, wenn entweder das Belohnungsmodell oder die Propensitäten korrekt sind. | Beste statistische Effizienz. Verwenden Sie ihn beim Vergleich mehrerer Policies oder beim Durchsuchen von |
Alle drei Schätzer:
Akzeptieren Sie einen Polars- oder pandas-DataFrame, der aus einem BanditDB-Parquet-Export geladen wurde
Bewerten Sie die uniforme Zufallspolitik als Ziel (die unverzerrte Baseline, die es zu schlagen gilt)
Lösen Sie ValueError für Thompson-Sampling-Kampagnen aus (Propensity-Spalte ist null – TS protokolliert keine Propensities)
Geben Sie ein OPEResult mit estimate, std_error, n_used, n_total und method zurück
import polars as pl
from banditdb.eval import replay, ips, doubly_robust
df = pl.read_parquet("/data/exports/llm_routing.parquet")
# How much reward would a uniform random policy have earned?
print(replay(df))
# OPEResult(method='replay', estimate=0.4821, std_error=0.0312, coverage=22.1% [33/149])
print(ips(df))
# OPEResult(method='ips', estimate=0.5103, std_error=0.0187, coverage=100.0% [149/149])
print(doubly_robust(df))
# OPEResult(method='doubly_robust', estimate=0.5219, std_error=0.0141, coverage=100.0% [149/149])
# Compare against the observed reward of the logging policy:
print("Observed (logging policy):", df["reward"].mean())
# If observed >> estimate, the campaign has learned something real — it outperforms random.Praktische Anwendung: alpha offline durchsuchen, bevor Sie bereitstellen. Trainieren Sie eine Kampagne auf echtem Traffic, speichern Sie Checkpoints in Parquet, und spielen Sie dann verschiedene Alpha-Werte über doubly_robust() durch, um das beste Explorationsniveau zu finden – kein Live-Experiment erforderlich.
Hinweis: OPE erfordert die
propensity-Spalte, die nur für LinUCB-Kampagnen geschrieben wird. Thompson-Sampling-Kampagnen protokollierennull-Propensities, da die TS-Armauswahl stochastisch ist und die Propensity-Bewertung eine deterministische Protokollierungsrichtlinie erfordert.
BanditDB unterstützt vier Algorithmen, die bei der Kampagnenerstellung ausgewählt werden.
Algorithmus |
| Explorationsstil | Verwendung |
LinUCB |
| Deterministischer UCB-Bonus: | Vorhersehbar, einstellbar. |
Lineares Thompson-Sampling |
| Stichproben θ̃ ~ N(θ, α²·A⁻¹), bewertet durch θ̃·x | Bayesianische Posteriori – kein Alpha-Sweep erforderlich. Gleichzeitige Benutzer diversifizieren die Auswahl automatisch. |
NeuralLinUCB |
| Deep-MLP-Einbettung + LinUCB im Einbettungsraum | Nichtlineare Belohnungsfunktionen. Trainiert das MLP alle N Belohnungen neu. |
Progressiv |
| Selbstjustierendes Turnier: führt Basis + Herausforderer parallel aus, verlagert Traffic auf den Gewinner | Modellauswahl ohne Konfiguration. Wählt automatisch den besten Algorithmus. |
from banditdb import Client, NeuralLinUCBConfig, ProgressiveConfig
db = Client("http://localhost:8080")
# LinUCB (default)
db.create_campaign("routing", ["fast", "cheap"], feature_dim=4, alpha=1.5)
# Thompson Sampling — natural Bayesian exploration, alpha=1.0 is ideal
db.create_campaign("routing_ts", ["fast", "cheap"], feature_dim=4,
algorithm="thompson_sampling")
# NeuralLinUCB — learns a deep embedding of the context, then applies LinUCB
cfg = NeuralLinUCBConfig(
context_dim=4, # must match feature_dim
embed_dim=32, # arm matrix dimension (default 32)
hidden_dim=128, # MLP hidden layer width (default 128)
retrain_every=200, # retrain the MLP every N cumulative rewards
)
db.create_campaign("routing_neural", ["fast", "cheap"], feature_dim=4, algorithm=cfg)
# Progressive — runs LinUCB vs NeuralLinUCB, shifts traffic to whoever wins SNIPS checkpoints
cfg = ProgressiveConfig(
base="linucb",
challenger=NeuralLinUCBConfig(context_dim=4, embed_dim=32),
min_obs=100, # minimum buffer entries per arm before any traffic shift
required_wins=3, # consecutive checkpoint wins to earn one traffic step
step_bps=1000, # traffic delta per win run, in basis points (1000 = 10%)
)
db.create_campaign("routing_prog", ["fast", "cheap"], feature_dim=4, algorithm=cfg)Alle vier Algorithmen teilen sich dieselbe predict → reward-Schleife.
Ausnahme | Wann ausgelöst |
| Basisausnahme – fangen Sie diese ab, um alle SDK-Fehler zu behandeln. |
| Server ist offline oder nicht erreichbar. |
| Anfrage hat das konfigurierte Timeout überschritten. |
| Server hat einen Fehler zurückgegeben (z. B. Kampagne nicht gefunden, nicht autorisiert). |
Apache-2.0 – Copyright (C) 2026 Simeon Lukov und Dynamic Pricing Ltd. Weitere Informationen finden Sie im Haupt-Repository.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
No tool schema history has been recorded yet.
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Shared, governed long-term memory for AI agents across tools and sessions via MCP and REST.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/dynamicpricing-ai/banditdb-python'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
