beaver-db 0.17.6__tar.gz → 0.18.0__tar.gz

beaver_db-0.18.0/.dockerignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+*.db*
+.env
+examples/

{beaver_db-0.17.6 → beaver_db-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.17.6
+Version: 0.18.0
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
@@ -93,7 +93,7 @@ To include optional features, you can install them as extras:
 
 ```bash
 # For vector search capabilities
-pip install "beaver-db[faiss]"
+pip install "beaver-db[vector]"
 
 # For the REST API server and CLI
 pip install "beaver-db[server,cli]"
@@ -102,6 +102,16 @@ pip install "beaver-db[server,cli]"
 pip install "beaver-db[full]"
 ```
 
+### Running with Docker
+For a fully embedded and lightweight solution, you can run the BeaverDB REST API server using Docker. This is the easiest way to get a self-hosted instance up and running.
+
+```bash
+docker run -p 8000:8000 -v $(pwd)/data:/app apiad/beaverdb
+```
+
+This command will start the BeaverDB server, and your database file will be stored in the data directory on your host machine. You can access the API at <http://localhost:8000>.
+
+
 ## Quickstart
 
 Get up and running in 30 seconds. This example showcases a dictionary, a list, and full-text search in a single script.
@@ -401,6 +411,8 @@ For more in-depth examples, check out the scripts in the `examples/` directory:
 These are some of the features and improvements planned for future releases:
 
 - **Async API**: Extend the async support with on-demand wrappers for all features besides channels.
+- **Type-Safe Models**: Enhance built-in `Model` to handle recursive and embedded types.
+- **Drop-in REST Client**: Implement a `BeaverClient` class that acts as a drop-in replacement for `BeaverDB` but instead of a local database file, it works against a REST API server.
 
 Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
 
@@ -408,4 +420,4 @@ If you think of something that would make `beaver` more useful for your use case
 
 ## License
 
-This project is licensed under the MIT License.
+This project is licensed under the MIT License.

{beaver_db-0.17.6 → beaver_db-0.18.0}/README.md

@@ -68,7 +68,7 @@ To include optional features, you can install them as extras:
 
 ```bash
 # For vector search capabilities
-pip install "beaver-db[faiss]"
+pip install "beaver-db[vector]"
 
 # For the REST API server and CLI
 pip install "beaver-db[server,cli]"
@@ -77,6 +77,16 @@ pip install "beaver-db[server,cli]"
 pip install "beaver-db[full]"
 ```
 
+### Running with Docker
+For a fully embedded and lightweight solution, you can run the BeaverDB REST API server using Docker. This is the easiest way to get a self-hosted instance up and running.
+
+```bash
+docker run -p 8000:8000 -v $(pwd)/data:/app apiad/beaverdb
+```
+
+This command will start the BeaverDB server, and your database file will be stored in the data directory on your host machine. You can access the API at <http://localhost:8000>.
+
+
 ## Quickstart
 
 Get up and running in 30 seconds. This example showcases a dictionary, a list, and full-text search in a single script.
@@ -376,6 +386,8 @@ For more in-depth examples, check out the scripts in the `examples/` directory:
 These are some of the features and improvements planned for future releases:
 
 - **Async API**: Extend the async support with on-demand wrappers for all features besides channels.
+- **Type-Safe Models**: Enhance built-in `Model` to handle recursive and embedded types.
+- **Drop-in REST Client**: Implement a `BeaverClient` class that acts as a drop-in replacement for `BeaverDB` but instead of a local database file, it works against a REST API server.
 
 Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
 
@@ -383,4 +395,4 @@ If you think of something that would make `beaver` more useful for your use case
 
 ## License
 
-This project is licensed under the MIT License.
+This project is licensed under the MIT License.

{beaver_db-0.17.6 → beaver_db-0.18.0}/beaver/__init__.py

@@ -1,3 +1,5 @@
 from .core import BeaverDB
 from .types import Model
 from .collections import Document, WalkDirection
+
+__version__ = "0.17.6"

{beaver_db-0.17.6 → beaver_db-0.18.0}/beaver/cli.py

@@ -1,10 +1,35 @@
 import typer
 import rich
 from typing_extensions import Annotated
+import beaver
 
 app = typer.Typer()
 
 
+def version_callback(value: bool):
+    if value:
+        print(beaver.__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=version_callback,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = False,
+):
+    """
+    BeaverDB command-line interface.
+    """
+    pass
+
+
 @app.command()
 def serve(
     database: Annotated[

{beaver_db-0.17.6 → beaver_db-0.18.0}/beaver/collections.py

@@ -96,13 +96,20 @@ class Document(Model):
     def to_dict(self) -> dict[str, Any]:
         """Serializes the document's metadata to a dictionary."""
         metadata = self.__dict__.copy()
-        metadata.pop("embedding", None)
-        metadata.pop("id", None)
+        metadata["embedding"] = self.embedding.tolist() if self.embedding is not None else None
         return metadata
 
     def __repr__(self):
+        d = self.to_dict()
+        d.pop("embedding")
         metadata_str = ", ".join(f"{k}={v!r}" for k, v in self.to_dict().items())
-        return f"Document(id='{self.id}', {metadata_str})"
+        return f"Document({metadata_str})"
+
+    def model_dump_json(self) -> str:
+        d = self.to_dict()
+        d.pop("embedding")
+        d.pop("id")
+        return json.dumps(d)
 
 
 class CollectionManager[D: Document]:

{beaver_db-0.17.6 → beaver_db-0.18.0}/beaver/server.py

@@ -270,7 +270,7 @@ def build(db: BeaverDB) -> FastAPI:
     def get_all_documents(name: str) -> List[dict]:
         """Retrieves all documents in the collection."""
         collection = db.collection(name)
-        return [doc.model_dump() for doc in collection]
+        return [doc.to_dict() for doc in collection]
 
     @app.post("/collections/{name}/index", tags=["Collections"])
     def index_document(name: str, req: IndexRequest):
@@ -291,7 +291,7 @@ def build(db: BeaverDB) -> FastAPI:
         collection = db.collection(name)
         try:
             results = collection.search(vector=req.vector, top_k=req.top_k)
-            return [{"document": doc.model_dump(), "distance": dist} for doc, dist in results]
+            return [{"document": doc.to_dict(), "distance": dist} for doc, dist in results]
         except TypeError as e:
             if "faiss" in str(e):
                 raise HTTPException(status_code=501, detail="Vector search requires the '[faiss]' extra. Install with: pip install \"beaver-db[faiss]\"")
@@ -302,7 +302,7 @@ def build(db: BeaverDB) -> FastAPI:
         """Performs a full-text or fuzzy search on the collection."""
         collection = db.collection(name)
         results = collection.match(query=req.query, on=req.on, top_k=req.top_k, fuzziness=req.fuzziness)
-        return [{"document": doc.model_dump(), "score": score} for doc, score in results]
+        return [{"document": doc.to_dict(), "score": score} for doc, score in results]
 
     @app.post("/collections/{name}/connect", tags=["Collections"])
     def connect_documents(name: str, req: ConnectRequest):
@@ -319,7 +319,7 @@ def build(db: BeaverDB) -> FastAPI:
         collection = db.collection(name)
         doc = Document(id=doc_id)
         neighbors = collection.neighbors(doc, label=label)
-        return [n.model_dump() for n in neighbors]
+        return [n.to_dict() for n in neighbors]
 
     @app.post("/collections/{name}/{doc_id}/walk", tags=["Collections"])
     def walk_graph(name: str, doc_id: str, req: WalkRequest) -> List[dict]:
@@ -327,7 +327,7 @@ def build(db: BeaverDB) -> FastAPI:
         collection = db.collection(name)
         source_doc = Document(id=doc_id)
         results = collection.walk(source=source_doc, labels=req.labels, depth=req.depth, direction=req.direction)
-        return [doc.model_dump() for doc in results]
+        return [doc.to_dict() for doc in results]
 
     return app
 

beaver_db-0.18.0/design.md

@@ -0,0 +1,91 @@
+# BeaverDB Design Document
+
+- **Version**: 1.2
+- **Status**: Active
+- **Last Updated**: October 4, 2025
+
+## 1. Introduction & Vision
+
+`beaver-db` is a local-first, embedded, multi-modal database for Python. Its primary motivation is to provide a simple, single-file solution for modern applications that need to handle complex data types like vectors, documents, and graphs without the overhead of a database server.
+
+The vision for `beaver-db` is to be the go-to "good enough" database for prototypes, desktop utilities, and small-scale applications. It empowers developers to start quickly with a simple API but provides a seamless path to scale from a local, embedded model to a networked client-server architecture without changing their application code.
+
+## 2. Guiding Principles
+
+These principles guide all development and design decisions for beaver-db.
+
+* **Local-First & Embedded:** The default mode of operation is a single SQLite file. This is the non-negotiable source of truth for local use. While a client-server model is supported via the REST API, the core engine remains fundamentally embedded.
+* **Standard SQLite Compatibility:** The .db file generated by beaver-db must always be a valid SQLite file that can be opened and queried by any standard SQLite tool. This ensures data portability and interoperability.
+* **Minimal & Optional Dependencies:** The core library has zero external dependencies. Features like vector search, the REST server, and the API client are available as optional extras, allowing users to install only what they need.
+* **Simplicity and Pythonic API:** The library must present a simple, intuitive, and "Pythonic" interface. We will always prefer simple method calls with clear parameters over custom Domain Specific Languages (DSLs).
+* **Developer Experience & API Parity**: The primary user experience goal is to provide a clean and minimal public API. This includes ensuring that the remote `BeaverClient` is a drop-in replacement for the local `BeaverDB`, maintaining perfect API parity.
+* **Synchronous Core with Async Potential:** The core library is built on a synchronous foundation for thread safety and simplicity. An async-compatible API is provided via on-demand wrappers that run blocking calls in a background thread pool.
+* **Convention over Configuration:** Features should work well out-of-the-box with sensible defaults.
+
+## 3. Architecture & Core Components
+
+`beaver-db` is architected as a set of targeted wrappers around a standard SQLite database. It supports two primary modes of operation: **Embedded** and **Client-Server**.
+
+### 3.1. Core Engine (Embedded Mode)
+
+* **`BeaverDB` Class**: Manages a thread-safe connection to a local SQLite database file.
+* **Concurrency**: Enables `PRAGMA journal_mode=WAL;` (Write-Ahead Logging) by default to provide good concurrency between one writer and multiple readers.
+* **Schema Management**: All tables are prefixed with `beaver_` to avoid conflicts with user-defined tables.
+
+### 3.2. Client-Server Mode
+
+* **REST API Server**: An optional feature that exposes the full functionality of a `BeaverDB` instance over a RESTful API, including WebSocket endpoints for real-time features.
+* **`BeaverClient`**: A drop-in replacement for the `BeaverDB` class that interacts with the REST API. Instead of a database connection, it manages an HTTP client session, allowing applications to switch from local to remote operation without code changes.
+
+### 3.3. Data Models & Features
+
+#### Key-Value Dictionaries (DictManager)
+
+* **Implementation**: A single table (`beaver_dicts`) stores key-value pairs partitioned by a `dict_name`.
+* **Design**: The `db.dict("namespace")` method returns a `DictManager` (or `RemoteDictManager`) that provides a complete Pythonic dictionary-like interface.
+
+#### Lists (ListManager)
+
+* **Implementation:** A table (`beaver_lists`) storing `list_name`, `item_order` (REAL), and `item_value` (TEXT). The use of a floating-point `item_order` allows for O(1) insertions.
+* **Design:** The `ListManager` provides a rich, Pythonic API (`__len__`, `__getitem__`, `push`, `pop`, etc.).
+
+#### Pub/Sub System
+
+* **Implementation:** A log table (`beaver_pubsub_log`) stores messages with a timestamp and channel name.
+* **Design:** In embedded mode, a background thread polls the table for new messages. In client-server mode, the client subscribes to a WebSocket endpoint for real-time updates.
+
+#### Collections (CollectionManager)
+
+This is the most complex component, supporting documents, vectors, text, and graphs.
+
+* **Document Storage:** Documents are stored in the `beaver_collections` table.
+* **Vector Search (ANN):**
+    * **Implementation**: Uses a hybrid index system with a large, on-disk `faiss` base index and a small, in-memory delta index for fast writes. All changes are crash-safe, logged in SQLite tables before being applied.
+    * **Compaction**: An automatic background process compacts the delta index into the base index to maintain search performance over time.
+* **Full-Text Search (FTS):**
+    * **Implementation:** Uses a virtual table (`beaver_fts_index`) powered by SQLite's FTS5 extension. String values from indexed documents are automatically added to the FTS index.
+* **Graph Engine:**
+    * **Implementation:** Relationships are stored as directed edges in the `beaver_edges` table.
+    * **Design:** The API is purely functional and Pythonic, using recursive Common Table Expressions (CTEs) for efficient multi-hop graph traversals (`walk()`).
+
+### 3.4. Developer Experience Features
+
+* **Async API**: A `.as_async()` method is available on all synchronous manager objects. It returns a parallel `Async` version of the object where all methods are `async def`. This is achieved by running the blocking database calls in a background thread pool via `asyncio.to_thread`.
+* **Type-Safe Models**: All data-handling methods (`db.dict`, `db.list`, etc.) accept an optional `model` argument. When a Pydantic model or the built-in `beaver.Model` is provided, the library handles automatic data validation, serialization, and deserialization, enabling static analysis and autocompletion.
+
+## 4. Roadmap & Future Development
+
+With the design of the REST API client and async wrappers, the library is approaching feature-completeness for its core domain. The primary focus for the near future is on stability and usability.
+
+1.  **Comprehensive Unit Testing:** Increase test coverage for all features, including the new `BeaverClient` and async wrappers.
+2.  **Elaborate Examples:** Create more examples that demonstrate how to combine features, particularly in a client-server context.
+3.  **Performance Benchmarking:** Develop a standardized suite of performance tests for both embedded and client-server modes to document practical scalability limits.
+
+### Explicitly Out of Scope
+
+To maintain focus and simplicity, the following features will **not** be implemented:
+
+* Replication or distributed operation beyond the single-server model.
+* Multi-file database formats.
+* Any feature that makes the database file incompatible with standard SQLite tools.
+* Custom query languages or DSLs.

beaver_db-0.18.0/dockerfile

@@ -0,0 +1,28 @@
+# Use a lightweight Python base image
+FROM python:3.13-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Add a build argument for the version, defaulting to the latest
+ARG VERSION=latest
+
+# Install the specified version of beaver-db from PyPI
+# If VERSION is "latest", it installs the most recent version.
+# Otherwise, it installs the specified version (e.g., beaver-db==0.17.6)
+RUN if [ "${VERSION}" = "latest" ]; then \
+        pip install --no-cache-dir "beaver-db[full]"; \
+    else \
+        pip install --no-cache-dir "beaver-db[full]==${VERSION}"; \
+    fi
+
+# Set default environment variables for configuration
+ENV DATABASE=beaver.db
+ENV HOST=0.0.0.0
+ENV PORT=8000
+
+# Expose the port the server will run on
+EXPOSE 8000
+
+# The command to run when the container starts
+CMD ["beaver", "serve", "--database", "${DATABASE}", "--host", "${HOST}", "--port", "${PORT}"]

beaver_db-0.18.0/makefile

@@ -0,0 +1,23 @@
+.PHONY: publish
+publish: clean build
+	uv publish --token `dotenv -f .env get PYPI_TOKEN`
+
+.PHONY: build
+build:
+	uv build
+	uv pip install -e .[full]
+
+.PHONY: clean
+clean:
+	rm -rf dist
+	rm -rf beaver_db.egg-info
+	find . -name '*.pyc' -exec rm -f {} +
+	find . -name '__pycache__' -exec rm -rf {} +
+
+.PHONY: push-docker
+push-docker:
+	$(eval VERSION := $(shell beaver --version))
+	docker build --build-arg VERSION=$(VERSION) -t apiad/beaverdb:$(VERSION) .
+	docker tag apiad/beaverdb:$(VERSION) apiad/beaverdb:latest
+	docker push apiad/beaverdb:$(VERSION)
+	docker push apiad/beaverdb:latest

{beaver_db-0.17.6 → beaver_db-0.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "beaver-db"
-version = "0.17.6"
+version = "0.18.0"
 description = "Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications."
 readme = "README.md"
 requires-python = ">=3.13"

{beaver_db-0.17.6 → beaver_db-0.18.0}/roadmap.md

@@ -43,8 +43,6 @@ This feature perfectly aligns with the library's guiding principles:
   * **Simplicity and Pythonic API**: The `.as_async()` method is an intuitive and Pythonic way to opt into asynchronous behavior, and the chained-call syntax is elegant and clean.
   * **Developer Experience**: By ensuring the `async` wrappers are explicitly typed, the design prioritizes compatibility with modern developer tools, preventing bugs and improving productivity.
 
------
-
 ## Feature: Pydantic Model Integration for Type-Safe Operations
 
 ### 1. Concept
@@ -103,3 +101,52 @@ This feature aligns with `beaver-db`'s guiding principles:
   * **Simplicity and Pythonic API**: The `model` parameter is a simple and intuitive way to enable type safety.
   * **Developer Experience**: This feature directly addresses the developer experience by providing type safety and editor support.
   * **Minimal & Cross-Platform Dependencies**: By making `pydantic` an optional dependency, the core library remains minimalistic.
+
+## Feature: Drop-in REST API Client (`BeaverClient`)
+
+### 1. Concept
+
+This feature introduces a new `BeaverClient` class that acts as a **drop-in replacement** for the core `BeaverDB` class. Instead of interacting directly with a local SQLite file, this client will execute all operations by making requests to a remote BeaverDB REST API server. This allows users to seamlessly switch from a local, embedded database to a client-server architecture without changing their application code.
+
+### 2. Use Cases
+
+  * **Seamless Scaling**: Effortlessly transition a project from a local prototype to a networked service without a code rewrite.
+  * **Multi-Process/Multi-Machine Access**: Allow multiple processes or machines to share and interact with a single, centralized BeaverDB instance.
+  * **Language Interoperability**: While the client itself is Python, it provides a blueprint for creating clients in other languages to interact with the BeaverDB server.
+
+### 3. Proposed API
+
+The API is designed for maximum compatibility. A user only needs to change how the database object is instantiated.
+
+**Local Implementation:**
+
+```python
+from beaver import BeaverDB
+db = BeaverDB("my_local_data.db")
+```
+
+**Remote Implementation:**
+
+```python
+from beaver.client import BeaverClient
+db = BeaverClient(base_url="http://127.0.0.1:8000")
+```
+
+All subsequent code, such as `db.dict("config")["theme"] = "dark"` or `db.collection("docs").search(...)`, remains identical.
+
+### 4. Implementation Design: Remote Managers and HTTP Client
+
+The implementation will live in a new `beaver/client.py` file and will not depend on any SQLite logic.
+
+1.  **Core Component**: The `BeaverClient` class will manage a persistent HTTP session using the **`httpx`** library, which provides connection pooling and supports both synchronous and asynchronous operations.
+2.  **Remote Managers**: For each existing manager (e.g., `DictManager`, `CollectionManager`), a corresponding `RemoteDictManager` or `RemoteCollectionManager` will be created. These classes will contain no database logic; their methods will simply construct and send the appropriate HTTP requests to the server endpoints.
+3.  **WebSocket Handling**: For real-time features like `db.channel("my_channel").subscribe()` and `db.log("metrics").live()`, the remote managers will establish WebSocket connections to the server's streaming endpoints. This will require new `WebSocketSubscriber` and `WebSocketLiveIterator` classes that read from the network stream instead of a local queue.
+4.  **Optional Dependency**: `httpx` and any necessary WebSocket libraries will be included as a new optional dependency, such as `pip install "beaver-db[client]"`.
+
+### 5. Alignment with Philosophy
+
+This feature strongly aligns with the library's guiding principles:
+
+  * **Simplicity and Pythonic API**: By maintaining perfect API parity, it ensures the remote client is just as intuitive and simple to use as the local database.
+  * **Developer Experience**: It provides a frictionless path for scaling applications, which is a major enhancement to the developer experience.
+  * **Minimal Dependencies**: By keeping the client and its dependencies optional, the core library remains lightweight and dependency-free.

beaver_db-0.17.6/design.md

@@ -1,118 +0,0 @@
-# BeaverDB Design Document
-
-Version: 1.1
-Status: In Progress
-Last Updated: September 18, 2025
-
-## 1. Introduction & Vision
-
-`beaver-db` is a local-first, embedded, multi-modal database for Python. Its primary motivation is to provide a simple, single-file solution for modern applications that need to handle complex data types like vectors, documents, and graphs without the overhead of a database server.
-
-The vision for `beaver-db` is to be the go-to "good enough" database for prototypes, desktop utilities, and small-scale applications. It empowers developers to start quickly with a simple API but provides sufficient power and performance so that they do not need to immediately upgrade to a more complex database system as their application's features grow.
-
-## 2. Guiding Principles
-
-These principleembeddings guide all development and design decisions for beaver-db.
-
-* **Local-First & Embedded:** The database will always be a single SQLite file. This is the non-negotiable source of truth. Temporary files for journaling or syncing are acceptable, but the core architecture is serverless. Any feature that requires a client-server model is out of scope.
-* **Standard SQLite Compatibility:** The .db file generated by beaver-db must always be a valid SQLite file that can be opened and queried by any standard SQLite tool. This ensures data portability and interoperability.
-* **Minimal & Cross-Platform Dependencies:** New dependencies beyond numpy and scipy will only be considered if they provide a monumental performance improvement and are fully cross-platform, with a guarantee of easy installation for all users. The core library should strive to use Python's standard library wherever possible.
-* **Simplicity and Pythonic API:** The library must present a simple, intuitive, and "Pythonic" interface. We will always prefer simple function calls with clear parameters over custom Domain Specific Languages (DSLs) or expression parsing. The user should not have to learn a new query language.
-* **Developer Experience & Minimal API Surface:** The primary user experience goal is to provide a clean and minimal public API.
-  * **User-facing Classes:** The user should only ever need to instantiate BeaverDB and Document directly.
-  * **Fluent Interface:** All other functionalities (like list or collection operations) are exposed through methods on the BeaverDB object (e.g., `db.list("my_list")`, `db.collection("my_docs")`). These methods return internal wrapper objects (`ListWrapper`, `CollectionWrapper`) that provide a rich, fluent interface, preventing the need for the user to learn and manage a large number of classes.
-  * **API Design:** Public functions will have short, descriptive names and well-documented parameters, adhering to Python's conventions.
-* **Synchronousembedding Core with Async Potential:** The core library is built on a synchronous foundation, reflecting the synchronous nature of the underlying `sqlite3` driver. This ensures thread safety and simplicity. An async-compatible API may be introduced in the future, but it will likely be a wrapper around the synchronous core (e.g., using a thread pool).
-* **Convention over Configuration:** Features should work well out-of-the-box with sensible defaults. While configuration options can be provided, the user should not be required to tweak many parameters to get good performance and functionality.
-
-## 3. Architecture & Core Components
-
-`beaver-db` is architected as a set of targeted wrappers around a standard SQLite database, with an in-memory component for performance-critical tasks like vector search.
-
-### 3.1. Core Engine (BeaverDB)
-
-* **Connection Management:** The BeaverDB class manages a single connection to the SQLite database file.
-* **Concurrency:** It enables `PRAGMA journal_mode=WAL;` (Write-Ahead Logging) by default. This provides a good level of concurrency between one writer and multiple readers, which is a common pattern for the target applications.
-* **Schema Management:** All tables created and managed by the library are prefixed with `beaver_` (or `_beaver_` for internal helpers). This avoids conflicts with user-defined tables within the same database file. The schema is evolved by adding new `beaver_*` tables as new features are introduced.
-
-### 3.2. Data Models & Features
-
-### Key-Value Dictionaries (DictWrapper)
-
-* **Implementation**: A single table (`beaver_dicts`) stores key-value pairs partitioned by a `dict_name` (TEXT). The primary key is a composite of `(dict_name, key)`.
-* **Design**: The `db.dict("namespace")` method returns a `DictWrapper` that provides a complete and standard Pythonic dictionary-like interface. This includes subscripting (`__getitem__`, `__setitem__`), explicit `get()`/`set()` methods, and iterators (`keys()`, `values()`, `items()`). This feature is ideal for managing structured configurations or namespaced key-value data while adhering to the principle of a Simple and Pythonic API.
-
-#### Lists (ListWrapper)
-
-* **Implementation:** A table (`beaver_lists`) storing list_name, item_order (REAL), and item_value (TEXT).
-* **Design:** The item_order is a floating-point number. This allows for O(1) insertions in the middle of the list by calculating the midpoint between two existing order values. This avoids re-indexing all subsequent items. The ListWrapper provides a rich, Pythonic API (`_len_`, `_getitem_`, `push`, `pop`, etc.).
-
-#### Pub/Sub System
-
-* **Implementation:** A log table (`beaver_pubsub_log`) that stores messages with a timestamp, channel name, and payload.
-* **Design:** The current SubWrapper is a synchronous iterator that polls the table for new messages since the last seen timestamp. This design is simple and robust. A more performant, event-driven mechanism could be explored in the future, but only if it does not violate the principles of simplicity and minimal dependencies.
-
-#### Collections (CollectionWrapper)
-
-This is the most complex component, supporting documents, vectors, text, and graphs.
-
-* **Document Storage:** Documents are stored in the beaver_collections table. Each document has a collection, item_id, optional item_vector (BLOB), and metadata (TEXT, as JSON). The Document class is a flexible container with no enforced schema.
-* **Vector Search (ANN):**
-  * **Indexing:** Vector embeddings are stored as raw bytes (BLOBs) in the beaver_collections table.
-  * **Search Algorithm:** For performance, an in-memory k-d tree (`scipy.spatial.cKDTree`) is used for Approximate Nearest Neighbor (ANN) search.
-  * **Stale Index Handling:** The database maintains a version number for each collection in beaver_collection_versions. This version is incremented on every index or drop operation. The CollectionWrapper caches the version of its in-memory index and automatically triggers a `refresh()` if it detects its version is older than the database version.
-  * **Design Trade-offs:** This in-memory approach is extremely fast for datasets that fit in RAM. The library will not have hard-coded scalability limits, but performance testing will establish practical boundaries which will be published in the documentation.
-* **Full-Text Search (FTS):**
-  * **Implementation:** Uses a virtual table (`beaver_fts_index`) powered by SQLite's FTS5 extension.
-  * **Indexing:** When a Document is indexed, its metadata is flattened into key-value pairs (e.g., author.name becomes author_name). All string values are automatically inserted into the FTS index.
-  * **Querying:** The `match()` method provides a simple interface for searching. It supports FTS5 syntax (like "OR", "AND") passed directly in the query string. The goal is to provide powerful search out-of-the-box without requiring complex configuration.
-* **Graph Engine:**
-  * **Implementation:** Relationships are stored as directed edges in the beaver_edges table, linking a source_item_id to a target_item_id with a label.
-  * **Design:** The API is purely functional and Pythonic. It does not use a custom graph query language.
-    * `connect()`: Creates a directed edge.
-    * `neighbors()`: Retrieves immediate (1-hop) neighbors.
-    * `walk()`: Uses a recursive Common Table Expression (CTE) in SQL to perform efficient multi-hop graph traversals (BFS). This is powerful yet keeps the implementation clean and contained within SQL.
-
-### 3.3. Reliability and Data Handling
-
-* **Atomicity and Transactions:** Correctness is paramount. Any public method that performs multiple database modifications (e.g., collection.index, which writes to the documents, FTS, and version tables) **must** be wrapped in a single, atomic database transaction. If any step of the operation fails, the entire transaction will be rolled back, ensuring the database is never left in an inconsistent state.
-* **Error Handling:** The library will use standard Python exceptions whenever possible (e.g., TypeError, ValueError, sqlite3.Error). Custom exceptions will be avoided to ensure the API feels native and predictable to Python developers.
-* **Data Serialization:**
-  * The default serialization format is JSON.
-  * The library will provide built-in, standardized converters for common Python types not native to JSON, such as `datetime` (to ISO 8601 strings) and `bytes` (to a standard encoding like base64).
-  * For custom user-defined objects, it is the user's responsibility to serialize them into a JSON-compatible format (e.g., a string or a dictionary) before storing them.
-
-## 4. Roadmap & Future Development
-
-### 4.1. Immediate Priorities
-
-The primary focus for the near future is on stability and usability.
-
-1. **Comprehensive Unit Testing:** Increase test coverage to ensure all features are robust and reliable.
-2. **Elaborate Examples:** Create more examples that demonstrate how to combine features (e.g., a hybrid search that uses FTS, graph traversal, and vector search together).
-3. **Performance Benchmarking:** Develop a standardized suite of performance tests to track regressions and identify optimization opportunities. The results will be used to document the practical scalability limits of the library for various use cases.
-
-### 4.2. Long-Term Vision
-
-The library is approaching feature-completeness for its core domain. The long-term vision is to make it a stable, trusted, and well-documented tool for its niche.
-
-* **Stability:** The API will soon be stabilized, with a commitment to backward compatibility as defined in the versioning policy.
-* **New Modalities:** In the distant future, other data modalities could be considered if they fit the embedded, single-file philosophy.
-
-### 4.3. Explicitly Out of Scope
-
-To maintain focus and simplicity, the following features will **not** be implemented:
-
-* Client-server architecture.
-* Replication or distributed operation.
-* Multi-file database formats.
-* Any feature that makes the database file incompatible with standard SQLite tools.
-* Custom query languages or DSLs.
-
-### 4.4. Versioning and Backward Compatibility
-
-The project will adhere to **Semantic Versioning (Major.Minor.Patch)**.
-
-* **Patch Releases (x.y.Z):** For bug fixes and non-breaking changes. No API or schema changes are permitted.
-* **Minor Releases (x.Y.z):** For adding new, backward-compatible features. Schema additions (e.g., new `beaver_*` tables) are allowed, but schema modifications that break older code are not. Code written for version x.z will be able to open and read a database file from version x.y where z > y.
-* **Major Releases (X.y.z):** For introducing breaking changes to the API or the database schema. There is no guarantee of backward compatibility between major versions, and a migration path will not be provided automatically.

beaver_db-0.17.6/makefile

@@ -1,15 +0,0 @@
-.PHONY: publish
-publish: clean build
-	uv publish --token `dotenv -f .env get PYPI_TOKEN`
-
-.PHONY: build
-build:
-	uv build
-	uv pip install -e .[full]
-
-.PHONY: clean
-clean:
-	rm -rf dist
-	rm -rf beaver_db.egg-info
-	find . -name '*.pyc' -exec rm -f {} +
-	find . -name '__pycache__' -exec rm -rf {} +