BONDI — A Python toolkit for document database research

bondi provides A Python toolkit for document database research.

Use native MongoDB and Couchbase queries, execute and profile workloads, inspect schemas, estimate MongoDB selectivity, and generate pattern-based workloads. Synchronous APIs work in scripts and notebooks; async APIs remain available. Research algorithms and experiment tracking stay in separate projects.

Start with installation and the quickstart, or browse the documentation overview.

Start developing

Requires uv and Python 3.11 or newer. From this directory:

uv sync --locked
uv run python -c "import bondi; print(bondi.__file__)"
uv run pytest
uv run ruff check .
uv run ruff format --check .

uv sync installs the package in editable mode and includes the development group. PyMongo is a required dependency for BSON support; no database service is needed. The committed uv.lock records the development dependency resolution.

Documentation · Issues · MIT license

Read the documentation

Start with the documentation overview, architecture decisions, and the implementation roadmap.

To preview or validate the documentation site:

uv sync --locked --group docs
uv run --group docs mkdocs serve
# Or build without starting a server:
uv run --group docs mkdocs build --strict

API reference pages are generated from Python docstrings using mkdocstrings. Tutorials are available in notebooks/workload_demo.ipynb (MongoDB) and notebooks/couchbase_demo.ipynb (Couchbase). For database-independent inference and inspection, see the schema guide and notebooks/schema_demo.ipynb.

Repository layout

src/bondi/     Installable library
tests/            Offline tests
docs/             Getting started, guides, tutorials, API reference and development

See the contributor guide for the development workflow. A distribution can be built with uv build.

Publication

BONDI is MIT licensed, copyright Relaxed Constraints. Version 0.1.0 is being prepared for PyPI; use the source installation instructions until it is published. See release preparation for the publishing process.

Optional local databases

See the local database guide for MongoDB and Couchbase Docker Compose profiles, sample data, startup and cleanup. No database or Docker installation is required for the offline test suite.