bondi 0.1.0__tar.gz

bondi-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python and local environments
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Generated documentation and distributions
+site/
+dist/
+build/
+
+# Local configuration and notebook state
+.env
+.env.*
+!.env.example
+.ipynb_checkpoints/
+.DS_Store
+
+# Locally generated research workloads
+/*workload*.jsonl

bondi-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — initial release (prepared)
+
+- Native MongoDB find/aggregation and Couchbase SQL++ queries with JSONL workloads.
+- Synchronous and asynchronous execution, explain and profile operations.
+- Offline query summaries, schema inspection and optional value retention.
+- MongoDB sampling estimation and pattern-based workload generation.
+- Student notebooks, local Docker environments and documentation.
+
+This is an early research release. Public APIs and persistence formats may change
+in subsequent releases; retain the package version alongside experiment artifacts.

bondi-0.1.0/CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: "If you use BONDI in research, please cite this software."
+title: "BONDI: A Python toolkit for document database research"
+authors:
+  - name: Relaxed Constraints
+version: 0.1.0
+license: MIT
+repository-code: "https://github.com/relaxed-constraints/bondi"
+url: "https://relaxed-constraints.github.io/bondi/"

bondi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Relaxed Constraints
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bondi-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: bondi
+Version: 0.1.0
+Summary: A Python toolkit for document database research
+Project-URL: Homepage, https://github.com/relaxed-constraints/bondi
+Project-URL: Documentation, https://relaxed-constraints.github.io/bondi/
+Project-URL: Repository, https://github.com/relaxed-constraints/bondi
+Project-URL: Issues, https://github.com/relaxed-constraints/bondi/issues
+Project-URL: Changelog, https://github.com/relaxed-constraints/bondi/blob/main/CHANGELOG.md
+Author: Relaxed Constraints
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Requires-Python: >=3.11
+Requires-Dist: pymongo<5,>=4.13
+Provides-Extra: couchbase
+Requires-Dist: couchbase<5,>=4.6.3; extra == 'couchbase'
+Description-Content-Type: text/markdown
+
+# 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](docs/installation.md) and the [quickstart](docs/quickstart.md),
+or browse the [documentation overview](docs/index.md).
+
+## Start developing
+
+Requires [uv](https://docs.astral.sh/uv/) and Python 3.11 or newer. From this directory:
+
+```sh
+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](https://relaxed-constraints.github.io/bondi/) ·
+[Issues](https://github.com/relaxed-constraints/bondi/issues) · [MIT license](LICENSE)
+
+## Read the documentation
+
+Start with [the documentation overview](docs/index.md),
+[architecture decisions](docs/architecture.md), and
+[the implementation roadmap](docs/roadmap.md).
+
+To preview or validate the documentation site:
+
+```sh
+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](docs/schemas.md)
+and `notebooks/schema_demo.ipynb`.
+
+## Repository layout
+
+```text
+src/bondi/     Installable library
+tests/            Offline tests
+docs/             Getting started, guides, tutorials, API reference and development
+```
+
+See [the contributor guide](docs/contributing.md) 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](docs/releases.md) for the publishing process.
+
+## Optional local databases
+
+See [the local database guide](docs/local-databases.md) for MongoDB and Couchbase
+Docker Compose profiles, sample data, startup and cleanup. No database or Docker
+installation is required for the offline test suite.

bondi-0.1.0/README.md

@@ -0,0 +1,74 @@
+# 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](docs/installation.md) and the [quickstart](docs/quickstart.md),
+or browse the [documentation overview](docs/index.md).
+
+## Start developing
+
+Requires [uv](https://docs.astral.sh/uv/) and Python 3.11 or newer. From this directory:
+
+```sh
+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](https://relaxed-constraints.github.io/bondi/) ·
+[Issues](https://github.com/relaxed-constraints/bondi/issues) · [MIT license](LICENSE)
+
+## Read the documentation
+
+Start with [the documentation overview](docs/index.md),
+[architecture decisions](docs/architecture.md), and
+[the implementation roadmap](docs/roadmap.md).
+
+To preview or validate the documentation site:
+
+```sh
+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](docs/schemas.md)
+and `notebooks/schema_demo.ipynb`.
+
+## Repository layout
+
+```text
+src/bondi/     Installable library
+tests/            Offline tests
+docs/             Getting started, guides, tutorials, API reference and development
+```
+
+See [the contributor guide](docs/contributing.md) 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](docs/releases.md) for the publishing process.
+
+## Optional local databases
+
+See [the local database guide](docs/local-databases.md) for MongoDB and Couchbase
+Docker Compose profiles, sample data, startup and cleanup. No database or Docker
+installation is required for the offline test suite.

bondi-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "bondi"
+version = "0.1.0"
+description = "A Python toolkit for document database research"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Relaxed Constraints"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "pymongo>=4.13,<5",
+]
+
+[project.urls]
+Homepage = "https://github.com/relaxed-constraints/bondi"
+Documentation = "https://relaxed-constraints.github.io/bondi/"
+Repository = "https://github.com/relaxed-constraints/bondi"
+Issues = "https://github.com/relaxed-constraints/bondi/issues"
+Changelog = "https://github.com/relaxed-constraints/bondi/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+couchbase = ["couchbase>=4.6.3,<5"]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.9"]
+docs = [
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.6,<10",
+    "mkdocstrings[python]>=0.28",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bondi"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src/bondi"]
+addopts = "--import-mode=importlib --doctest-modules"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/pyproject.toml", "/uv.lock", "/README.md", "/LICENSE", "/CHANGELOG.md", "/CITATION.cff"]

bondi-0.1.0/src/bondi/__init__.py

@@ -0,0 +1 @@
+"""A Python toolkit for document database research."""

bondi-0.1.0/src/bondi/_sync.py

@@ -0,0 +1,122 @@
+"""Private background-loop bridge for synchronous database facades."""
+
+import asyncio
+from concurrent.futures import Future
+from threading import Event, Thread, get_ident
+from typing import Self
+
+
+class _SyncExecutor:
+    """Own an async executor on a background loop; calls stay on the owner thread."""
+
+    def __init__(self):
+        raise TypeError("Use from_uri() to create an owned executor")
+
+    @classmethod
+    def _create(cls, factory):
+        self = object.__new__(cls)
+        self._thread = get_ident()
+        self._closed = False
+        self._executor = None
+        ready = Event()
+
+        def serve():
+            with asyncio.Runner() as runner:
+                self._loop = runner.get_loop()
+                ready.set()
+                self._loop.run_forever()
+
+        self._worker = Thread(target=serve, name=f"bondi-{cls.__name__}", daemon=True)
+        self._worker.start()
+        ready.wait()
+
+        async def connect():
+            self._executor = await factory()
+
+        try:
+            self._submit(connect)
+        except BaseException:
+            try:
+                if self._executor is not None:
+                    self._submit(self._executor.close, cancel_on_interrupt=False)
+            finally:
+                self._shutdown()
+            raise
+        return self
+
+    def _check(self):
+        if get_ident() != self._thread:
+            raise RuntimeError("Use this executor only from its creating thread")
+        if self._closed:
+            raise RuntimeError("Executor is closed")
+
+    def _submit(self, operation, *, cancel_on_interrupt=True):
+        """Wait for an operation, including its cancellation cleanup on interrupt."""
+        self._check()
+        outcome = Future()
+        task = None
+
+        async def invoke():
+            try:
+                value = await operation()
+            except BaseException as error:
+                outcome.set_exception(error)
+            else:
+                outcome.set_result(value)
+
+        def start():
+            nonlocal task
+            task = self._loop.create_task(invoke())
+
+        def cancel():
+            if task is not None and not task.done():
+                # Schedule after the already-queued first task step.
+                self._loop.call_soon(task.cancel)
+
+        self._loop.call_soon_threadsafe(start)
+        try:
+            return outcome.result()
+        except KeyboardInterrupt:
+            if cancel_on_interrupt:
+                self._loop.call_soon_threadsafe(cancel)
+            # Do not return control until the coroutine has finished unwinding.
+            while not outcome.done():
+                try:
+                    outcome.result(timeout=0.1)
+                except (KeyboardInterrupt, TimeoutError):
+                    continue
+                except BaseException:
+                    break
+            raise
+
+    def _call(self, method, *args, **kwargs):
+        async def invoke():
+            return await getattr(self._executor, method)(*args, **kwargs)
+
+        return self._submit(invoke)
+
+    def _shutdown(self):
+        self._closed = True
+        self._loop.call_soon_threadsafe(self._loop.stop)
+        while self._worker.is_alive():
+            try:
+                self._worker.join(timeout=0.1)
+            except KeyboardInterrupt:
+                continue
+
+    def close(self) -> None:
+        """Close the connection, stop its loop and join its thread; idempotent."""
+        if self._closed:
+            return
+        self._check()
+        try:
+            self._submit(self._executor.close, cancel_on_interrupt=False)
+        finally:
+            self._shutdown()
+
+    def __enter__(self) -> Self:
+        self._check()
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> None:
+        self.close()

bondi-0.1.0/src/bondi/couchbase/__init__.py

@@ -0,0 +1,8 @@
+"""Native Couchbase query descriptions without an SDK connection."""
+
+from bondi.couchbase.executor import AsyncCouchbaseExecutor
+from bondi.couchbase.explain import summarize
+from bondi.couchbase.query import CouchbaseQuery
+from bondi.couchbase.sync_executor import CouchbaseExecutor
+
+__all__ = ["CouchbaseExecutor", "CouchbaseQuery", "AsyncCouchbaseExecutor", "summarize"]