beaver-db 0.19.1__py3-none-any.whl → 0.19.3__py3-none-any.whl

beaver/__init__.py

@@ -2,4 +2,4 @@ from .core import BeaverDB
 from .types import Model
 from .collections import Document, WalkDirection
 
-__version__ = "0.19.1"
+__version__ = "0.19.3"

beaver/blobs.py

@@ -1,8 +1,8 @@
 import json
 import sqlite3
 from typing import Any, Dict, Iterator, NamedTuple, Optional, Type, TypeVar
-
 from .types import JsonSerializable, IDatabase
+from .locks import LockManager
 
 
 class Blob[M](NamedTuple):
@@ -16,10 +16,13 @@ class Blob[M](NamedTuple):
 class BlobManager[M]:
     """A wrapper providing a Pythonic interface to a blob store in the database."""
 
+# In beaver/blobs.py, inside class BlobManager[M]:
     def __init__(self, name: str, db: IDatabase, model: Type[M] | None = None):
         self._name = name
         self._db = db
         self._model = model
+        lock_name = f"__lock__blob__{name}"
+        self._lock = LockManager(db, lock_name)
 
     def _serialize(self, value: M) -> str | None:
         """Serializes the given value to a JSON string."""
@@ -122,5 +125,48 @@ class BlobManager[M]:
             yield row["key"]
         cursor.close()
 
+    def __len__(self) -> int:
+        """Returns the number of blobs in the store."""
+        cursor = self._db.connection.cursor()
+        cursor.execute(
+            "SELECT COUNT(*) FROM beaver_blobs WHERE store_name = ?",
+            (self._name,)
+        )
+        count = cursor.fetchone()[0]
+        cursor.close()
+        return count
+
     def __repr__(self) -> str:
         return f"BlobManager(name='{self._name}')"
+
+    def acquire(
+        self,
+        timeout: Optional[float] = None,
+        lock_ttl: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+    ) -> "BlobManager[M]":
+        """
+        Acquires an inter-process lock on this blob store, blocking until acquired.
+
+        Parameters override the default settings of the underlying LockManager.
+        """
+        self._lock.acquire(
+            timeout=timeout,
+            lock_ttl=lock_ttl,
+            poll_interval=poll_interval
+        )
+        return self
+
+    def release(self):
+        """
+        Releases the inter-process lock on this blob store.
+        """
+        self._lock.release()
+
+    def __enter__(self) -> "BlobManager[M]":
+        """Acquires the lock upon entering a 'with' statement."""
+        return self.acquire()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Releases the lock when exiting a 'with' statement."""
+        self.release()

beaver/collections.py

@@ -3,15 +3,16 @@ import sqlite3
 import threading
 import uuid
 from enum import Enum
-from typing import Any, Iterator, List, Literal, Tuple, Type, TypeVar
+from typing import Any, Iterator, List, Literal, Tuple, Type, TypeVar, Optional
 from .types import Model, stub, IDatabase
+from .locks import LockManager
 
 try:
     import numpy as np
     from .vectors import VectorIndex
 except ImportError:
-    np = stub("This feature requires to install beaver-db[faiss]")()
-    VectorIndex = stub("This feature requires to install beaver-db[faiss]")
+    np = stub("This feature requires to install beaver-db[vector]")()
+    VectorIndex = stub("This feature requires to install beaver-db[vector]")
 
 # --- Fuzzy Search Helper Functions ---
 
@@ -135,6 +136,9 @@ class CollectionManager[D: Document]:
         self._compaction_lock = threading.Lock()
         self._compaction_thread: threading.Thread | None = None
 
+        lock_name = f"__lock__collection__{name}"
+        self._lock = LockManager(db, lock_name)
+
     def _flatten_metadata(self, metadata: dict, prefix: str = "") -> dict[str, Any]:
         """Flattens a nested dictionary for indexing."""
         flat_dict = {}
@@ -643,6 +647,38 @@ class CollectionManager[D: Document]:
         cursor.close()
         return count
 
+    def acquire(
+        self,
+        timeout: Optional[float] = None,
+        lock_ttl: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+    ) -> "CollectionManager[D]":
+        """
+        Acquires an inter-process lock on this collection, blocking until acquired.
+        This guarantees exclusive access for multi-step atomic operations
+        (e.g., index + connect).
+
+        Parameters override the default settings of the underlying LockManager.
+        """
+        self._lock.acquire(
+            timeout=timeout, lock_ttl=lock_ttl, poll_interval=poll_interval
+        )
+        return self
+
+    def release(self):
+        """
+        Releases the inter-process lock on this collection.
+        """
+        self._lock.release()
+
+    def __enter__(self) -> "CollectionManager[D]":
+        """Acquires the lock upon entering a 'with' statement."""
+        return self.acquire()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Releases the lock when exiting a 'with' statement."""
+        self.release()
+
 
 def rerank[D: Document](
     *results: list[D], weights: list[float] | None = None, k: int = 60

beaver/dicts.py

@@ -1,9 +1,9 @@
 import json
 import sqlite3
 import time
-from typing import Any, Iterator, Tuple, Type
-
+from typing import Any, Iterator, Tuple, Type, Optional
 from .types import JsonSerializable, IDatabase
+from .locks import LockManager
 
 class DictManager[T]:
     """A wrapper providing a Pythonic interface to a dictionary in the database."""
@@ -12,6 +12,8 @@ class DictManager[T]:
         self._name = name
         self._db = db
         self._model = model
+        lock_name = f"__lock__dict__{name}"
+        self._lock = LockManager(db, lock_name)
 
     def _serialize(self, value: T) -> str:
         """Serializes the given value to a JSON string."""
@@ -147,4 +149,35 @@ class DictManager[T]:
         cursor.close()
 
     def __repr__(self) -> str:
-        return f"DictManager(name='{self._name}')"
+        return f"DictManager(name='{self._name}')"
+
+    def acquire(
+        self,
+        timeout: Optional[float] = None,
+        lock_ttl: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+    ) -> "DictManager[T]":
+        """
+        Acquires an inter-process lock on this dictionary, blocking until acquired.
+        Parameters override the default settings of the underlying LockManager.
+        """
+        self._lock.acquire(
+            timeout=timeout,
+            lock_ttl=lock_ttl,
+            poll_interval=poll_interval
+        )
+        return self
+
+    def release(self):
+        """
+        Releases the inter-process lock on this dictionary.
+        """
+        self._lock.release()
+
+    def __enter__(self) -> "DictManager[T]":
+        """Acquires the lock upon entering a 'with' statement."""
+        return self.acquire()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Releases the lock when exiting a 'with' statement."""
+        self.release()

beaver/lists.py

@@ -1,8 +1,8 @@
 import json
 import sqlite3
-from typing import Any, Iterator, Type, Union
-
+from typing import Any, Iterator, Type, Union, Optional
 from .types import JsonSerializable, IDatabase
+from .locks import LockManager
 
 
 class ListManager[T]:
@@ -12,6 +12,8 @@ class ListManager[T]:
         self._name = name
         self._db = db
         self._model = model
+        lock_name = f"__lock__list__{name}"
+        self._lock = LockManager(db, lock_name)
 
     def _serialize(self, value: T) -> str:
         """Serializes the given value to a JSON string."""
@@ -261,4 +263,36 @@ class ListManager[T]:
             cursor.execute(
                 "DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,)
             )
-            return self._deserialize(value_to_return)
+            return self._deserialize(value_to_return)
+
+    def acquire(
+        self,
+        timeout: Optional[float] = None,
+        lock_ttl: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+    ) -> "ListManager[T]":
+        """
+        Acquires an inter-process lock on this list, blocking until acquired.
+
+        Parameters override the default settings of the underlying LockManager.
+        """
+        self._lock.acquire(
+            timeout=timeout,
+            lock_ttl=lock_ttl,
+            poll_interval=poll_interval
+        )
+        return self
+
+    def release(self):
+        """
+        Releases the inter-process lock on this list, allowing the next waiting process access.
+        """
+        self._lock.release()
+
+    def __enter__(self) -> "ListManager[T]":
+        """Acquires the lock upon entering a 'with' statement."""
+        return self.acquire()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Releases the lock when exiting a 'with' statement."""
+        self.release()

beaver/locks.py

@@ -55,7 +55,11 @@ class LockManager:
         self._waiter_id = f"pid:{os.getpid()}:id:{uuid.uuid4()}"
         self._acquired = False  # State to track if this instance holds the lock
 
-    def acquire(self) -> "LockManager":
+    def acquire(self,
+                timeout: float|None = None,
+        lock_ttl: float |None = None,
+        poll_interval: float |None = None,
+        ) -> "LockManager":
         """
         Blocks until the lock is acquired or the timeout expires.
 
@@ -66,9 +70,18 @@ class LockManager:
             # This instance already holds the lock
             return self
 
+        if timeout is None:
+            timeout = self._timeout
+
+        if lock_ttl is None:
+            lock_ttl = self._lock_ttl
+
+        if poll_interval is None:
+            poll_interval = self._poll_interval
+
         start_time = time.time()
         requested_at = time.time()
-        expires_at = requested_at + self._lock_ttl
+        expires_at = requested_at + lock_ttl
 
         conn = self._db.connection
 
@@ -113,19 +126,19 @@ class LockManager:
                         return self
 
                 # 5. Check for timeout
-                if self._timeout is not None:
-                    if (time.time() - start_time) > self._timeout:
+                if timeout is not None:
+                    if (time.time() - start_time) > timeout:
                         # We timed out. Remove ourselves from the queue and raise.
                         self._release_from_queue()
                         raise TimeoutError(
-                            f"Failed to acquire lock '{self._lock_name}' within {self._timeout}s."
+                            f"Failed to acquire lock '{self._lock_name}' within {timeout}s."
                         )
 
                 # 6. Wait politely before polling again
                 # Add +/- 10% jitter to the poll interval to avoid thundering herd
-                jitter = self._poll_interval * 0.1
+                jitter = poll_interval * 0.1
                 sleep_time = random.uniform(
-                    self._poll_interval - jitter, self._poll_interval + jitter
+                    poll_interval - jitter, poll_interval + jitter
                 )
                 time.sleep(sleep_time)
 

beaver/queues.py

@@ -2,10 +2,9 @@ import asyncio
 import json
 import sqlite3
 import time
-from typing import Any, Literal, NamedTuple, Type, overload
-
+from typing import Any, Literal, NamedTuple, Type, overload, Optional
 from .types import JsonSerializable, IDatabase
-
+from .locks import LockManager
 
 class QueueItem[T](NamedTuple):
     """A data class representing a single item retrieved from the queue."""
@@ -54,6 +53,8 @@ class QueueManager[T]:
         self._name = name
         self._db = db
         self._model = model
+        lock_name = f"__lock__queue__{name}"
+        self._lock = LockManager(db, lock_name)
 
     def _serialize(self, value: T) -> str:
         """Serializes the given value to a JSON string."""
@@ -184,3 +185,37 @@ class QueueManager[T]:
 
     def __repr__(self) -> str:
         return f"QueueManager(name='{self._name}')"
+
+    def acquire(
+        self,
+        timeout: Optional[float] = None,
+        lock_ttl: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+    ) -> "QueueManager[T]":
+        """
+        Acquires an inter-process lock on this queue, blocking until acquired.
+        This ensures that a sequence of operations (e.g., batch-getting tasks)
+        is performed atomically without interruption from other processes.
+
+        Parameters override the default settings of the underlying LockManager.
+        """
+        self._lock.acquire(
+            timeout=timeout,
+            lock_ttl=lock_ttl,
+            poll_interval=poll_interval
+        )
+        return self
+
+    def release(self):
+        """
+        Releases the inter-process lock on this queue.
+        """
+        self._lock.release()
+
+    def __enter__(self) -> "QueueManager[T]":
+        """Acquires the lock upon entering a 'with' statement."""
+        return self.acquire()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Releases the lock when exiting a 'with' statement."""
+        self.release()

beaver/server.py

@@ -2,11 +2,23 @@ try:
     from typing import Any, Optional, List
     import json
     from datetime import datetime, timedelta, timezone
-    from fastapi import FastAPI, HTTPException, Body, UploadFile, File, Form, Response, WebSocket, WebSocketDisconnect
+    from fastapi import (
+        FastAPI,
+        HTTPException,
+        Body,
+        UploadFile,
+        File,
+        Form,
+        Response,
+        WebSocket,
+        WebSocketDisconnect,
+    )
     import uvicorn
     from pydantic import BaseModel, Field
 except ImportError:
-    raise ImportError("Please install server dependencies with: pip install \"beaver-db[server]\"")
+    raise ImportError(
+        'Please install server dependencies with: pip install "beaver-db[server]"'
+    )
 
 from .core import BeaverDB
 from .collections import Document, WalkDirection
@@ -14,6 +26,7 @@ from .collections import Document, WalkDirection
 
 # --- Pydantic Models for Collections ---
 
+
 class IndexRequest(BaseModel):
     id: Optional[str] = None
     embedding: Optional[List[float]] = None
@@ -21,28 +34,36 @@ class IndexRequest(BaseModel):
     fts: bool = True
     fuzzy: bool = False
 
+
 class SearchRequest(BaseModel):
     vector: List[float]
     top_k: int = 10
 
+
 class MatchRequest(BaseModel):
     query: str
     on: Optional[List[str]] = None
     top_k: int = 10
     fuzziness: int = 0
 
+
 class ConnectRequest(BaseModel):
     source_id: str
     target_id: str
     label: str
     metadata: Optional[dict] = None
 
+
 class WalkRequest(BaseModel):
     labels: List[str]
     depth: int
     direction: WalkDirection = WalkDirection.OUTGOING
 
 
+class CountResponse(BaseModel):
+    count: int
+
+
 def build(db: BeaverDB) -> FastAPI:
     """Constructs a FastAPI instance for a given BeaverDB."""
     app = FastAPI(title="BeaverDB Server")
@@ -55,7 +76,9 @@ def build(db: BeaverDB) -> FastAPI:
         d = db.dict(name)
         value = d.get(key)
         if value is None:
-            raise HTTPException(status_code=404, detail=f"Key '{key}' not found in dictionary '{name}'")
+            raise HTTPException(
+                status_code=404, detail=f"Key '{key}' not found in dictionary '{name}'"
+            )
         return value
 
     @app.put("/dicts/{name}/{key}", tags=["Dicts"])
@@ -73,8 +96,15 @@ def build(db: BeaverDB) -> FastAPI:
             del d[key]
             return {"status": "ok"}
         except KeyError:
-            raise HTTPException(status_code=404, detail=f"Key '{key}' not found in dictionary '{name}'")
+            raise HTTPException(
+                status_code=404, detail=f"Key '{key}' not found in dictionary '{name}'"
+            )
 
+    @app.get("/dicts/{name}/count", tags=["Dicts"], response_model=CountResponse)
+    def get_dict_count(name: str) -> dict:
+        """Retrieves the number of key-value pairs in the dictionary."""
+        d = db.dict(name)
+        return {"count": len(d)}
 
     # --- Lists Endpoints ---
 
@@ -91,7 +121,9 @@ def build(db: BeaverDB) -> FastAPI:
         try:
             return l[index]
         except IndexError:
-            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
+            raise HTTPException(
+                status_code=404, detail=f"Index {index} out of bounds for list '{name}'"
+            )
 
     @app.post("/lists/{name}", tags=["Lists"])
     def push_list_item(name: str, value: Any = Body(...)):
@@ -108,7 +140,9 @@ def build(db: BeaverDB) -> FastAPI:
             l[index] = value
             return {"status": "ok"}
         except IndexError:
-            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
+            raise HTTPException(
+                status_code=404, detail=f"Index {index} out of bounds for list '{name}'"
+            )
 
     @app.delete("/lists/{name}/{index}", tags=["Lists"])
     def delete_list_item(name: str, index: int):
@@ -118,7 +152,15 @@ def build(db: BeaverDB) -> FastAPI:
             del l[index]
             return {"status": "ok"}
         except IndexError:
-            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
+            raise HTTPException(
+                status_code=404, detail=f"Index {index} out of bounds for list '{name}'"
+            )
+
+    @app.get("/lists/{name}/count", tags=["Lists"], response_model=CountResponse)
+    def get_list_count(name: str) -> dict:
+        """Retrieves the number of items in the list."""
+        l = db.list(name)
+        return {"count": len(l)}
 
     # --- Queues Endpoints ---
 
@@ -149,11 +191,19 @@ def build(db: BeaverDB) -> FastAPI:
             item = q.get(block=True, timeout=timeout)
             return item
         except TimeoutError:
-            raise HTTPException(status_code=408, detail=f"Request timed out after {timeout}s waiting for an item in queue '{name}'")
+            raise HTTPException(
+                status_code=408,
+                detail=f"Request timed out after {timeout}s waiting for an item in queue '{name}'",
+            )
         except IndexError:
             # This case is less likely with block=True but good to handle
             raise HTTPException(status_code=404, detail=f"Queue '{name}' is empty")
 
+    @app.get("/queues/{name}/count", tags=["Queues"], response_model=CountResponse)
+    def get_queue_count(name: str) -> dict:
+        """RetrieVIes the number of items currently in the queue."""
+        q = db.queue(name)
+        return {"count": len(q)}
 
     # --- Blobs Endpoints ---
 
@@ -163,12 +213,20 @@ def build(db: BeaverDB) -> FastAPI:
         blobs = db.blobs(name)
         blob = blobs.get(key)
         if blob is None:
-            raise HTTPException(status_code=404, detail=f"Blob with key '{key}' not found in store '{name}'")
+            raise HTTPException(
+                status_code=404,
+                detail=f"Blob with key '{key}' not found in store '{name}'",
+            )
         # Return the raw bytes with a generic binary content type
         return Response(content=blob.data, media_type="application/octet-stream")
 
     @app.put("/blobs/{name}/{key}", tags=["Blobs"])
-    async def put_blob(name: str, key: str, data: UploadFile = File(...), metadata: Optional[str] = Form(None)):
+    async def put_blob(
+        name: str,
+        key: str,
+        data: UploadFile = File(...),
+        metadata: Optional[str] = Form(None),
+    ):
         """Stores a blob (binary file) with optional JSON metadata."""
         blobs = db.blobs(name)
         file_bytes = await data.read()
@@ -178,7 +236,9 @@ def build(db: BeaverDB) -> FastAPI:
             try:
                 meta_dict = json.loads(metadata)
             except json.JSONDecodeError:
-                raise HTTPException(status_code=400, detail="Invalid JSON format for metadata.")
+                raise HTTPException(
+                    status_code=400, detail="Invalid JSON format for metadata."
+                )
 
         blobs.put(key=key, data=file_bytes, metadata=meta_dict)
         return {"status": "ok"}
@@ -191,8 +251,16 @@ def build(db: BeaverDB) -> FastAPI:
             blobs.delete(key)
             return {"status": "ok"}
         except KeyError:
-            raise HTTPException(status_code=404, detail=f"Blob with key '{key}' not found in store '{name}'")
+            raise HTTPException(
+                status_code=404,
+                detail=f"Blob with key '{key}' not found in store '{name}'",
+            )
 
+    @app.get("/blobs/{name}/count", tags=["Blobs"], response_model=CountResponse)
+    def get_blob_count(name: str) -> dict:
+        """Retrieves the number of blobs in the store."""
+        b = db.blobs(name)
+        return {"count": len(b)}
 
     # --- Logs Endpoints ---
 
@@ -208,12 +276,25 @@ def build(db: BeaverDB) -> FastAPI:
         """Retrieves log entries within a specific time window."""
         log = db.log(name)
         # Ensure datetimes are timezone-aware (UTC) for correct comparison
-        start_utc = start.astimezone(timezone.utc) if start.tzinfo else start.replace(tzinfo=timezone.utc)
-        end_utc = end.astimezone(timezone.utc) if end.tzinfo else end.replace(tzinfo=timezone.utc)
+        start_utc = (
+            start.astimezone(timezone.utc)
+            if start.tzinfo
+            else start.replace(tzinfo=timezone.utc)
+        )
+        end_utc = (
+            end.astimezone(timezone.utc)
+            if end.tzinfo
+            else end.replace(tzinfo=timezone.utc)
+        )
         return log.range(start=start_utc, end=end_utc)
 
     @app.websocket("/logs/{name}/live", name="Logs")
-    async def live_log_feed(websocket: WebSocket, name: str, window_seconds: int = 5, period_seconds: int = 1):
+    async def live_log_feed(
+        websocket: WebSocket,
+        name: str,
+        window_seconds: int = 5,
+        period_seconds: int = 1,
+    ):
         """Streams live, aggregated log data over a WebSocket."""
         await websocket.accept()
 
@@ -222,7 +303,10 @@ def build(db: BeaverDB) -> FastAPI:
         # This simple aggregator function runs in the background and returns a
         # JSON-serializable summary of the data in the current window.
         def simple_aggregator(window):
-            return {"count": len(window), "latest_timestamp": window[-1]["timestamp"] if window else None}
+            return {
+                "count": len(window),
+                "latest_timestamp": window[-1]["timestamp"] if window else None,
+            }
 
         live_stream = async_logs.live(
             window=timedelta(seconds=window_seconds),
@@ -239,7 +323,6 @@ def build(db: BeaverDB) -> FastAPI:
             # Cleanly close the underlying iterator and its background thread.
             live_stream.close()
 
-
     # --- Channels Endpoints ---
 
     @app.post("/channels/{name}/publish", tags=["Channels"])
@@ -263,7 +346,6 @@ def build(db: BeaverDB) -> FastAPI:
         except WebSocketDisconnect:
             print(f"Client disconnected from channel '{name}' subscription.")
 
-
     # --- Collections Endpoints ---
 
     @app.get("/collections/{name}", tags=["Collections"])
@@ -282,7 +364,10 @@ def build(db: BeaverDB) -> FastAPI:
             return {"status": "ok", "id": doc.id}
         except TypeError as e:
             if "vector" in str(e):
-                raise HTTPException(status_code=501, detail="Vector indexing requires the '[vector]' extra. Install with: pip install \"beaver-db[vector]\"")
+                raise HTTPException(
+                    status_code=501,
+                    detail="Vector indexing requires the '[vector]' extra. Install with: pip install \"beaver-db[vector]\"",
+                )
             raise e
 
     @app.post("/collections/{name}/search", tags=["Collections"])
@@ -291,18 +376,29 @@ def build(db: BeaverDB) -> FastAPI:
         collection = db.collection(name)
         try:
             results = collection.search(vector=req.vector, top_k=req.top_k)
-            return [{"document": doc.to_dict(metadata_only=False), "distance": dist} for doc, dist in results]
+            return [
+                {"document": doc.to_dict(metadata_only=False), "distance": dist}
+                for doc, dist in results
+            ]
         except TypeError as e:
             if "vector" in str(e):
-                raise HTTPException(status_code=501, detail="Vector search requires the '[vector]' extra. Install with: pip install \"beaver-db[vector]\"")
+                raise HTTPException(
+                    status_code=501,
+                    detail="Vector search requires the '[vector]' extra. Install with: pip install \"beaver-db[vector]\"",
+                )
             raise e
 
     @app.post("/collections/{name}/match", tags=["Collections"])
     def match_collection(name: str, req: MatchRequest) -> List[dict]:
         """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.to_dict(metadata_only=False), "score": score} for doc, score in results]
+        results = collection.match(
+            query=req.query, on=req.on, top_k=req.top_k, fuzziness=req.fuzziness
+        )
+        return [
+            {"document": doc.to_dict(metadata_only=False), "score": score}
+            for doc, score in results
+        ]
 
     @app.post("/collections/{name}/connect", tags=["Collections"])
     def connect_documents(name: str, req: ConnectRequest):
@@ -310,11 +406,15 @@ def build(db: BeaverDB) -> FastAPI:
         collection = db.collection(name)
         source_doc = Document(id=req.source_id)
         target_doc = Document(id=req.target_id)
-        collection.connect(source=source_doc, target=target_doc, label=req.label, metadata=req.metadata)
+        collection.connect(
+            source=source_doc, target=target_doc, label=req.label, metadata=req.metadata
+        )
         return {"status": "ok"}
 
     @app.get("/collections/{name}/{doc_id}/neighbors", tags=["Collections"])
-    def get_neighbors(name: str, doc_id: str, label: Optional[str] = None) -> List[dict]:
+    def get_neighbors(
+        name: str, doc_id: str, label: Optional[str] = None
+    ) -> List[dict]:
         """Retrieves the neighboring documents for a given document."""
         collection = db.collection(name)
         doc = Document(id=doc_id)
@@ -326,9 +426,22 @@ def build(db: BeaverDB) -> FastAPI:
         """Performs a graph traversal (BFS) from a starting document."""
         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)
+        results = collection.walk(
+            source=source_doc,
+            labels=req.labels,
+            depth=req.depth,
+            direction=req.direction,
+        )
         return [doc.to_dict(metadata_only=False) for doc in results]
 
+    @app.get(
+        "/collections/{name}/count", tags=["Collections"], response_model=CountResponse
+    )
+    def get_collection_count(name: str) -> dict:
+        """RetrieRetrieves the number of documents in the collection."""
+        c = db.collection(name)
+        return {"count": len(c)}
+
     return app
 
 

{beaver_db-0.19.1.dist-info → beaver_db-0.19.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.19.1
+Version: 0.19.3
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
@@ -23,7 +23,11 @@ Provides-Extra: vector
 Requires-Dist: faiss-cpu>=1.12.0; extra == 'vector'
 Description-Content-Type: text/markdown
 
-# beaver 🦫
+<div style="text-align: center;">
+  <img src="https://github.com/syalia-srl/beaver/blob/main/logo.png?raw=true" width="256px">
+</div>
+
+---
 
 <!-- Project badges -->
 ![PyPI - Version](https://img.shields.io/pypi/v/beaver-db)
@@ -32,7 +36,9 @@ Description-Content-Type: text/markdown
 ![PyPi - Downloads (Monthly)](https://img.shields.io/pypi/dm/beaver-db)
 ![Github - Commits](https://img.shields.io/github/commit-activity/m/apiad/beaver)
 
-A fast, single-file, multi-modal database for Python, built with the standard `sqlite3` library.
+> A fast, single-file, multi-modal database for Python, built with the standard `sqlite3` library.
+
+---
 
 `beaver` is the **B**ackend for **E**mbedded, **A**ll-in-one **V**ector, **E**ntity, and **R**elationship storage. It's a simple, local, and embedded database designed to manage complex, modern data types without requiring a database server, built on top of SQLite.
 

beaver_db-0.19.3.dist-info/RECORD

@@ -0,0 +1,19 @@
+beaver/__init__.py,sha256=DBnqxMZ-ZIvX14_FoC_ZGmYqcqhQtpLG1VXjNVCcPdc,125
+beaver/blobs.py,sha256=gauxfWOCMoP6mq61JRj-TVqqkXMAcVI2taBGYnJXsxg,5527
+beaver/channels.py,sha256=kIuwKMDBdDQObaKT23znsMXzfpKfE7pXSxvf-u4LlpY,9554
+beaver/cli.py,sha256=Sxm-mYU3LGd4tIqw-5LHb0ektWebjV9vn51hm-CMJD0,2232
+beaver/collections.py,sha256=Vc5ZF5gVIACx2XeL25PxgOcW7iF6lBInO-cnfyBBUeo,27299
+beaver/core.py,sha256=JRkRvc0Sb3FT9KlR3YbmiPcqCQ686dFKmHSNZ_UJ_aE,17100
+beaver/dicts.py,sha256=0csA1fvQb3rB2yQvwuq_kzgJ0YPp-wifBLkNcuiUltI,6582
+beaver/lists.py,sha256=vKZPVRiw0BRSx4JKaboGnWXfwNGkHX8cBFH59qQX1yY,11258
+beaver/locks.py,sha256=b6cHgAI1YQxKmVdLLzNw9fcGvk4V3SQS_wUaQTHSsUk,6630
+beaver/logs.py,sha256=a5xenwl5NZeegIU0dWVEs67lvaHzzw-JRAZtEzNNO3E,9529
+beaver/queues.py,sha256=wTlxsu12grcIPbosA1S0_23Tot4Wv3BWXeKyq4dRPKk,7709
+beaver/server.py,sha256=At3BoEV7JfpYjNtyHMdPUF8shj4V4D5nStXWb6Bv53A,15947
+beaver/types.py,sha256=m0ohT7A8r0Y1a7bJEx4VanLaOUWU2VYxaLHPsVPjrIw,1651
+beaver/vectors.py,sha256=EGZf1s364-rMubxkYoTcjBl72lRRxM1cUwypjsoC6ec,18499
+beaver_db-0.19.3.dist-info/METADATA,sha256=gRJetTcWICFhi0kQUFeNt773vTZkZYF-iRFqCtUXqjE,23431
+beaver_db-0.19.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+beaver_db-0.19.3.dist-info/entry_points.txt,sha256=bd5E2s45PoBdtdR9-ToKSdLNhmHp8naV1lWP5mOzlrc,42
+beaver_db-0.19.3.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
+beaver_db-0.19.3.dist-info/RECORD,,

beaver_db-0.19.1.dist-info/RECORD

@@ -1,19 +0,0 @@
-beaver/__init__.py,sha256=dMWanhrt58thAIt9Qj4jzxy5Dg5KzvNQenZ_cNcz_Tk,125
-beaver/blobs.py,sha256=YkIEskHD6oHRaJTF0P25HrTT8LqM-REyV_UBPVQxeqQ,4055
-beaver/channels.py,sha256=kIuwKMDBdDQObaKT23znsMXzfpKfE7pXSxvf-u4LlpY,9554
-beaver/cli.py,sha256=Sxm-mYU3LGd4tIqw-5LHb0ektWebjV9vn51hm-CMJD0,2232
-beaver/collections.py,sha256=UAQAuRxJRCqY5PHfxJNm3CdKqMNuyY8DOLdodvY6jpk,26107
-beaver/core.py,sha256=JRkRvc0Sb3FT9KlR3YbmiPcqCQ686dFKmHSNZ_UJ_aE,17100
-beaver/dicts.py,sha256=Xp8lPfQt08O8zCbptQLWQLO79OxG6uAVER6ryj3SScQ,5495
-beaver/lists.py,sha256=rfJ8uTNLkMREYc0uGx0z1VKt2m3eR9hvbdvDD58EbmQ,10140
-beaver/locks.py,sha256=GWDSRkPw2lrAQfXIRqvkc5PK9zZ2eLYWKTuzHTs9j_A,6321
-beaver/logs.py,sha256=a5xenwl5NZeegIU0dWVEs67lvaHzzw-JRAZtEzNNO3E,9529
-beaver/queues.py,sha256=Fr3oie63EtceSoiC8EOEDSLu1tDI8q2MYLXd8MEeC3g,6476
-beaver/server.py,sha256=WoNcPXU9oh6hcHtb60IbEk5DfZT5J4Fb-yubJE3YLIc,13642
-beaver/types.py,sha256=m0ohT7A8r0Y1a7bJEx4VanLaOUWU2VYxaLHPsVPjrIw,1651
-beaver/vectors.py,sha256=EGZf1s364-rMubxkYoTcjBl72lRRxM1cUwypjsoC6ec,18499
-beaver_db-0.19.1.dist-info/METADATA,sha256=Nt_3RlU4UraPp-zJusitwvwE2yza_zUyhRvecRcEvrI,23299
-beaver_db-0.19.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-beaver_db-0.19.1.dist-info/entry_points.txt,sha256=bd5E2s45PoBdtdR9-ToKSdLNhmHp8naV1lWP5mOzlrc,42
-beaver_db-0.19.1.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
-beaver_db-0.19.1.dist-info/RECORD,,