beaver-db 0.17.5__py3-none-any.whl → 0.18.0__py3-none-any.whl

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/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/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/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.17.5.dist-info → beaver_db-0.18.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.17.5
+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
@@ -42,7 +42,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 
 `beaver` is built with a minimalistic philosophy for small, local use cases where a full-blown database server would be overkill.
 
-- **Minimalistic**: The core library has zero external dependencies. Vector search capabilities, which require `numpy` and `faiss-cpu`, are available as an optional feature.
+- **Minimalistic**: The core library has zero external dependencies. Vector search, the REST server, and the CLI, which require external libraries, are available as optional features.
 - **Schemaless**: Flexible data storage without rigid schemas across all modalities.
 - **Synchronous, Multi-Process, and Thread-Safe**: Designed for simplicity and safety in multi-threaded and multi-process environments.
 - **Built for Local Applications**: Perfect for local AI tools, RAG prototypes, chatbots, and desktop utilities that need persistent, structured data without network overhead.
@@ -61,6 +61,8 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 - **Full-Text and Fuzzy Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine, enhanced with optional fuzzy search for typo-tolerant matching.
 - **Knowledge Graph**: Create relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
 - **Single-File & Portable**: All data is stored in a single SQLite file, making it incredibly easy to move, back up, or embed in your application.
+- **Built-in REST API Server (Optional)**: Instantly serve your database over a RESTful API with automatic OpenAPI documentation using FastAPI.
+- **Full-Featured CLI Client (Optional)**: Interact with your database directly from the command line for administrative tasks and data exploration.
 - **Optional Type-Safety:** Although the database is schemaless, you can use a minimalistic typing system for automatic serialization and deserialization that is Pydantic-compatible out of the box.
 
 ## How Beaver is Implemented
@@ -79,7 +81,6 @@ The vector store in BeaverDB is designed for high performance and reliability, u
 
 This hybrid approach allows BeaverDB to provide a vector search experience that is both fast and durable, without sacrificing the single-file, embedded philosophy of the library.
 
-
 ## Installation
 
 Install the core, dependency-free library:
@@ -88,12 +89,29 @@ Install the core, dependency-free library:
 pip install beaver-db
 ```
 
-If you want vector search capabilities, install the `faiss` extra:
+To include optional features, you can install them as extras:
+
+```bash
+# For vector search capabilities
+pip install "beaver-db[vector]"
+
+# For the REST API server and CLI
+pip install "beaver-db[server,cli]"
+
+# To install all optional features at once
+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
-pip install "beaver-db[faiss]"
+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.
@@ -131,6 +149,53 @@ print(f"FTS Result: '{top_doc.content}'")
 db.close()
 ```
 
+## Built-in Server and CLI
+
+Beaver comes with a built-in REST API server and a full-featured command-line client, allowing you to interact with your database without writing any code.
+
+### REST API Server
+
+You can instantly expose all of your database's functionality over a RESTful API. This is perfect for building quick prototypes, microservices, or for interacting with your data from other languages.
+
+**1. Start the server**
+
+```bash
+# Start the server for your database file
+beaver serve --database data.db --port 8000
+```
+
+This starts a `FastAPI` server. You can now access the interactive API documentation at `http://127.0.0.1:8000/docs`.
+
+**2. Interact with the API**
+
+Here are a couple of examples using `curl`:
+
+```bash
+# Set a value in the 'app_config' dictionary
+curl -X PUT http://127.0.0.1:8000/dicts/app_config/api_key
+     -H "Content-Type: application/json"
+     -d '"your-secret-api-key"'
+
+# Get the value back
+curl http://127.0.0.1:8000/dicts/app_config/api_key
+# Output: "your-secret-api-key"
+```
+
+### Command-Line Client
+
+The CLI client allows you to call any BeaverDB method directly from your terminal.
+
+```bash
+# Set a value in a dictionary
+beaver client --database data.db dict app_config set theme light
+
+# Get the value back
+beaver client --database data.db dict app_config get theme
+
+# Push an item to a list
+beaver client --database data.db list daily_tasks push "Review PRs"
+```
+
 ## Things You Can Build with Beaver
 
 Here are a few ideas to inspire your next project, showcasing how to combine Beaver's features to build powerful local applications.
@@ -282,8 +347,10 @@ For enhanced data integrity and a better developer experience, BeaverDB supports
 
 This feature is designed to be flexible and works seamlessly with two kinds of models:
 
-  * **Pydantic Models**: If you're already using Pydantic, your `BaseModel` classes will work out of the box.
-  * **Lightweight `beaver.Model`**: For a zero-dependency solution, you can inherit from the built-in `beaver.Model` class, which is a standard Python class with serialization methods automatically included.
+- **Pydantic Models**: If you're already using Pydantic, your `BaseModel` classes will work out of the box.
+
+- **Lightweight `beaver.Model`**: For a zero-dependency solution, you can inherit from the built-in `beaver.Model` class, which is a standard Python class with serialization methods automatically included.
+
 
 Here’s a quick example of how to use it:
 
@@ -305,7 +372,8 @@ users["alice"] = User(name="Alice", email="alice@example.com")
 
 # The retrieved object is a proper instance of the User class
 retrieved_user = users["alice"]
-print(f"Retrieved: {retrieved_user.name}") # Your editor will provide autocompletion here
+# Your editor will provide autocompletion here
+print(f"Retrieved: {retrieved_user.name}")
 ```
 
 In the same way you can have typed message payloads in `db.channel`, typed metadata in `db.blobs`, and custom document types in `db.collection`, as well as custom types in lists and queues.
@@ -316,25 +384,25 @@ Basically everywhere you can store or get some object in BeaverDB, you can use a
 
 For more in-depth examples, check out the scripts in the `examples/` directory:
 
-  - [`async_pubsub.py`](examples/async_pubsub.py): A demonstration of the asynchronous wrapper for the publish/subscribe system.
-  - [`blobs.py`](examples/blobs.py): Demonstrates how to store and retrieve binary data in the database.
-  - [`cache.py`](examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
-  - [`fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
-  - [`fuzzy.py`](examples/fuzzy.py): Demonstrates fuzzy search capabilities for text search.
-  - [`general_test.py`](examples/general_test.py): A general-purpose test to run all operations randomly which allows testing long-running processes and synchronicity issues.
-  - [`graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
-  - [`kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
-  - [`list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
-  - [`logs.py`](examples/logs.py): A short example showing how to build a realtime dashboard with the logging feature.
-  - [`pqueue.py`](examples/pqueue.py): A practical example of using the persistent priority queue for task management.
-  - [`producer_consumer.py`](examples/producer_consumer.py): A demonstration of the distributed task queue system in a multi-process environment.
-  - [`publisher.py`](examples/publisher.py) and [`subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
-  - [`pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
-  - [`rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
-  - [`stress_vectors.py`](examples/stress_vectors.py): A stress test for the vector search functionality.
-  - [`textual_chat.py`](examples/textual_chat.py): A chat application built with `textual` and `beaver` to illustrate the use of several primitives (lists, dicts, and channels) at the same time.
-  - [`type_hints.py`](examples/type_hints.py): Shows how to use type hints with `beaver` to get better IDE support and type safety.
-  - [`vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
+- [`async_pubsub.py`](examples/async_pubsub.py): A demonstration of the asynchronous wrapper for the publish/subscribe system.
+- [`blobs.py`](examples/blobs.py): Demonstrates how to store and retrieve binary data in the database.
+- [`cache.py`](examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
+- [`fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
+- [`fuzzy.py`](examples/fuzzy.py): Demonstrates fuzzy search capabilities for text search.
+- [`general_test.py`](examples/general_test.py): A general-purpose test to run all operations randomly which allows testing long-running processes and synchronicity issues.
+- [`graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
+- [`kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
+- [`list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
+- [`logs.py`](examples/logs.py): A short example showing how to build a realtime dashboard with the logging feature.
+- [`pqueue.py`](examples/pqueue.py): A practical example of using the persistent priority queue for task management.
+- [`producer_consumer.py`](examples/producer_consumer.py): A demonstration of the distributed task queue system in a multi-process environment.
+- [`publisher.py`](examples/publisher.p) and [`subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+- [`pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
+- [`rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
+- [`stress_vectors.py`](examples/stress_vectors.py): A stress test for the vector search functionality.
+- [`textual_chat.py`](examples/textual_chat.py): A chat application built with `textual` and `beaver` to illustrate the use of several primitives (lists, dicts, and channels) at the same time.
+- [`type_hints.py`](examples/type_hints.py): Shows how to use type hints with `beaver` to get better IDE support and type safety.
+- [`vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
 
 ## Roadmap
 
@@ -342,7 +410,9 @@ 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.
+- **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.
 

{beaver_db-0.17.5.dist-info → beaver_db-0.18.0.dist-info}/RECORD

@@ -1,18 +1,18 @@
-beaver/__init__.py,sha256=qyEzF1Os7w4b4Hijgz0Y0R4zTrRBrHIGT1mEkZFl2YM,101
+beaver/__init__.py,sha256=QkP3H8ah0QpWqaryT3yjNFX07zjGHMoWgu4dWDHH9eQ,125
 beaver/blobs.py,sha256=YkIEskHD6oHRaJTF0P25HrTT8LqM-REyV_UBPVQxeqQ,4055
 beaver/channels.py,sha256=kIuwKMDBdDQObaKT23znsMXzfpKfE7pXSxvf-u4LlpY,9554
-beaver/cli.py,sha256=Q61OYGrsWzERKy69NbttlSLUh1JunPlDSAd__LeKxhM,1789
-beaver/collections.py,sha256=Wm684pGp-E89PCq9gcbbmRC9VMtTxolRVXnrxKlw2m8,24615
+beaver/cli.py,sha256=Sxm-mYU3LGd4tIqw-5LHb0ektWebjV9vn51hm-CMJD0,2232
+beaver/collections.py,sha256=NVBq4W23I4WcMH-PBdvABBx2B0TR19AHpav6SktlQVk,24818
 beaver/core.py,sha256=68vjuEbkJTHv4SltCLCrgs34BpLCeL602oJZ6CJ34Zo,14560
 beaver/dicts.py,sha256=Xp8lPfQt08O8zCbptQLWQLO79OxG6uAVER6ryj3SScQ,5495
 beaver/lists.py,sha256=rfJ8uTNLkMREYc0uGx0z1VKt2m3eR9hvbdvDD58EbmQ,10140
 beaver/logs.py,sha256=a5xenwl5NZeegIU0dWVEs67lvaHzzw-JRAZtEzNNO3E,9529
 beaver/queues.py,sha256=Fr3oie63EtceSoiC8EOEDSLu1tDI8q2MYLXd8MEeC3g,6476
-beaver/server.py,sha256=OixUvPTIbSYN3anPc98UiF2mM289yjJBQGla1S_HmIY,13556
+beaver/server.py,sha256=sf2cGUt6aTvegUzhssHOaFiAFaJCP65EMSDX3cvhf0s,13541
 beaver/types.py,sha256=WZLINf7hy6zdKdAFQK0EVMSl5vnY_KnrHXNdXgAKuPg,1582
 beaver/vectors.py,sha256=qvI6RwUOGrhVH5d6PUmI3jKDaoDotMy0iy-bHyvmXks,18496
-beaver_db-0.17.5.dist-info/METADATA,sha256=gMM4Ul7WQ7lrtTPJKss-59g1Swxkek4FiioWjfPNvk4,18664
-beaver_db-0.17.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-beaver_db-0.17.5.dist-info/entry_points.txt,sha256=bd5E2s45PoBdtdR9-ToKSdLNhmHp8naV1lWP5mOzlrc,42
-beaver_db-0.17.5.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
-beaver_db-0.17.5.dist-info/RECORD,,
+beaver_db-0.18.0.dist-info/METADATA,sha256=T9Uqog7NP-Ts7-2tgWNytgBaeNkLV7nPDJbnlfUHrGY,21232
+beaver_db-0.18.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+beaver_db-0.18.0.dist-info/entry_points.txt,sha256=bd5E2s45PoBdtdR9-ToKSdLNhmHp8naV1lWP5mOzlrc,42
+beaver_db-0.18.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
+beaver_db-0.18.0.dist-info/RECORD,,