beaver-db 0.7.1__py3-none-any.whl → 0.8.0__py3-none-any.whl

beaver/core.py

@@ -7,6 +7,7 @@ from .dicts import DictManager
 from .lists import ListManager
 from .channels import ChannelManager
 from .collections import CollectionManager
+from .queues import QueueManager
 
 
 class BeaverDB:
@@ -38,6 +39,27 @@ class BeaverDB:
         self._create_edges_table()
         self._create_versions_table()
         self._create_dict_table()
+        self._create_priority_queue_table()
+
+    def _create_priority_queue_table(self):
+        """Creates the priority queue table and its performance index."""
+        with self._conn:
+            self._conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS beaver_priority_queues (
+                    queue_name TEXT NOT NULL,
+                    priority REAL NOT NULL,
+                    timestamp REAL NOT NULL,
+                    data TEXT NOT NULL
+                )
+                """
+            )
+            self._conn.execute(
+                """
+                CREATE INDEX IF NOT EXISTS idx_priority_queue_order
+                ON beaver_priority_queues (queue_name, priority ASC, timestamp ASC)
+                """
+            )
 
     def _create_dict_table(self):
         """Creates the namespaced dictionary table."""
@@ -164,8 +186,16 @@ class BeaverDB:
             raise TypeError("List name must be a non-empty string.")
         return ListManager(name, self._conn)
 
+    def queue(self, name: str) -> QueueManager:
+        """Returns a wrapper object for interacting with a persistent priority queue."""
+        if not isinstance(name, str) or not name:
+            raise TypeError("Queue name must be a non-empty string.")
+        return QueueManager(name, self._conn)
+
     def collection(self, name: str) -> CollectionManager:
         """Returns a wrapper for interacting with a document collection."""
+        if not isinstance(name, str) or not name:
+            raise TypeError("Collection name must be a non-empty string.")
         return CollectionManager(name, self._conn)
 
     def publish(self, channel_name: str, payload: Any):

beaver/queues.py

@@ -0,0 +1,87 @@
+import json
+import sqlite3
+import time
+from typing import Any, NamedTuple
+
+
+class QueueItem(NamedTuple):
+    """A data class representing a single item retrieved from the queue."""
+
+    priority: float
+    timestamp: float
+    data: Any
+
+
+class QueueManager:
+    """A wrapper providing a Pythonic interface to a persistent priority queue."""
+
+    def __init__(self, name: str, conn: sqlite3.Connection):
+        self._name = name
+        self._conn = conn
+
+    def put(self, data: Any, priority: float):
+        """
+        Adds an item to the queue with a specific priority.
+
+        Args:
+            data: The JSON-serializable data to store.
+            priority: The priority of the item (lower numbers are higher priority).
+        """
+        with self._conn:
+            self._conn.execute(
+                "INSERT INTO beaver_priority_queues (queue_name, priority, timestamp, data) VALUES (?, ?, ?, ?)",
+                (self._name, priority, time.time(), json.dumps(data)),
+            )
+
+    def get(self) -> QueueItem:
+        """
+        Atomically retrieves and removes the highest-priority item from the queue.
+
+        Returns:
+            A QueueItem containing the data and its metadata.
+
+        Raises IndexError if queue is empty.
+        """
+        with self._conn:
+            cursor = self._conn.cursor()
+            # The compound index on (queue_name, priority, timestamp) makes this query efficient.
+            cursor.execute(
+                """
+                SELECT rowid, priority, timestamp, data
+                FROM beaver_priority_queues
+                WHERE queue_name = ?
+                ORDER BY priority ASC, timestamp ASC
+                LIMIT 1
+                """,
+                (self._name,),
+            )
+            result = cursor.fetchone()
+
+            if result is None:
+                raise IndexError("Queue is empty")
+
+            rowid, priority, timestamp, data = result
+            # Delete the retrieved item to ensure it's processed only once.
+            cursor.execute("DELETE FROM beaver_priority_queues WHERE rowid = ?", (rowid,))
+
+            return QueueItem(
+                priority=priority, timestamp=timestamp, data=json.loads(data)
+            )
+
+    def __len__(self) -> int:
+        """Returns the current number of items in the queue."""
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT COUNT(*) FROM beaver_priority_queues WHERE queue_name = ?",
+            (self._name,),
+        )
+        count = cursor.fetchone()[0]
+        cursor.close()
+        return count
+
+    def __nonzero__(self) -> bool:
+        """Returns True if the queue is not empty."""
+        return len(self) > 0
+
+    def __repr__(self) -> str:
+        return f"QueueManager(name='{self._name}')"

{beaver_db-0.7.1.dist-info → beaver_db-0.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.7.1
+Version: 0.8.0
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -11,10 +11,6 @@ Dynamic: license-file
 
 # beaver 🦫
 
-![PyPI - Downloads](https://img.shields.io/pypi/dm/beaver-db)
-![PyPI](https://img.shields.io/pypi/v/beaver-db)
-![License](https://img.shields.io/github/license/apiad/beaver)
-
 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.
@@ -34,6 +30,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
   - **Synchronous Pub/Sub**: A simple, thread-safe, Redis-like publish-subscribe system for real-time messaging.
   - **Namespaced Key-Value Dictionaries**: A Pythonic, dictionary-like interface for storing any JSON-serializable object within separate namespaces with optional TTL for cache implementations.
   - **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
+  - **Persistent Priority Queue**: A high-performance, persistent queue that always returns the item with the highest priority, perfect for task management.
   - **Efficient Vector Storage & Search**: Store vector embeddings and perform fast approximate nearest neighbor searches using an in-memory k-d tree.
   - **Full-Text Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine.
   - **Graph Traversal**: Create relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
@@ -86,7 +83,24 @@ db.close()
 
 Here are a few ideas to inspire your next project, showcasing how to combine Beaver's features to build powerful local applications.
 
-### 1. User Authentication and Profile Store
+### 1. AI Agent Task Management
+
+Use a **persistent priority queue** to manage tasks for an AI agent. This ensures the agent always works on the most important task first, even if the application restarts.
+
+```python
+tasks = db.queue("agent_tasks")
+
+# Tasks are added with a priority (lower is higher)
+tasks.put({"action": "summarize_news"}, priority=10)
+tasks.put({"action": "respond_to_user"}, priority=1)
+tasks.put({"action": "run_backup"}, priority=20)
+
+# The agent retrieves the highest-priority task
+next_task = tasks.get() # -> Returns the "respond_to_user" task
+print(f"Agent's next task: {next_task.data['action']}")
+```
+
+### 2. User Authentication and Profile Store
 
 Use a **namespaced dictionary** to create a simple and secure user store. The key can be the username, and the value can be a dictionary containing the hashed password and other profile information.
 
@@ -104,7 +118,7 @@ users["alice"] = {
 alice_profile = users.get("alice")
 ```
 
-### 2. Chatbot Conversation History
+### 3. Chatbot Conversation History
 
 A **persistent list** is perfect for storing the history of a conversation. Each time the user or the bot sends a message, just `push` it to the list. This maintains a chronological record of the entire dialogue.
 
@@ -119,7 +133,7 @@ for message in chat_history:
     print(f"{message['role']}: {message['content']}")
 ```
 
-### 3. Build a RAG (Retrieval-Augmented Generation) System
+### 4. Build a RAG (Retrieval-Augmented Generation) System
 
 Combine **vector search** and **full-text search** to build a powerful RAG pipeline for your local documents.
 
@@ -133,7 +147,7 @@ from beaver.collections import rerank
 best_context = rerank(vector_results, text_results, weights=[0.6, 0.4])
 ```
 
-### 4. Caching for Expensive API Calls
+### 5. Caching for Expensive API Calls
 
 Leverage a **dictionary with a TTL (Time-To-Live)** to cache the results of slow network requests. This can dramatically speed up your application and reduce your reliance on external services.
 
@@ -153,14 +167,15 @@ if response is None:
 
 For more in-depth examples, check out the scripts in the `examples/` directory:
 
-  - [`examples/kvstore.py`](https://www.google.com/search?q=examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
-  - [`examples/list.py`](https://www.google.com/search?q=examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
-  - [`examples/vector.py`](https://www.google.com/search?q=examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
-  - [`examples/fts.py`](https://www.google.com/search?q=examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
-  - [`examples/graph.py`](https://www.google.com/search?q=examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
-  - [`examples/pubsub.py`](https://www.google.com/search?q=examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system.
-  - [`examples/cache.py`](https://www.google.com/search?q=examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
-  - [`examples/rerank.py`](https://www.google.com/search?q=examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
+  - [`examples/kvstore.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/kvstore.py%5D\(https://www.google.com/search%3Fq%3Dexamples/kvstore.py\)): A comprehensive demo of the namespaced dictionary feature.
+  - [`examples/list.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/list.py%5D\(https://www.google.com/search%3Fq%3Dexamples/list.py\)): Shows the full capabilities of the persistent list, including slicing and in-place updates.
+  - [`examples/queue.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/queue.py%5D\(https://www.google.com/search%3Fq%3Dexamples/queue.py\)): A practical example of using the persistent priority queue for task management.
+  - [`examples/vector.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/vector.py%5D\(https://www.google.com/search%3Fq%3Dexamples/vector.py\)): Demonstrates how to index and search vector embeddings, including upserts.
+  - [`examples/fts.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/fts.py%5D\(https://www.google.com/search%3Fq%3Dexamples/fts.py\)): A detailed look at full-text search, including targeted searches on specific metadata fields.
+  - [`examples/graph.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/graph.py%5D\(https://www.google.com/search%3Fq%3Dexamples/graph.py\)): Shows how to create relationships between documents and perform multi-hop graph traversals.
+  - [`examples/pubsub.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/pubsub.py%5D\(https://www.google.com/search%3Fq%3Dexamples/pubsub.py\)): A demonstration of the synchronous, thread-safe publish/subscribe system.
+  - [`examples/cache.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/cache.py%5D\(https://www.google.com/search%3Fq%3Dexamples/cache.py\)): A practical example of using a dictionary with TTL as a cache for API calls.
+  - [`examples/rerank.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/rerank.py%5D\(https://www.google.com/search%3Fq%3Dexamples/rerank.py\)): Shows how to combine results from vector and text search for more refined results.
 
 ## Roadmap
 
@@ -168,7 +183,6 @@ These are some of the features and improvements planned for future releases:
 
   - **Fuzzy search**: Implement fuzzy matching capabilities for text search.
   - **Faster ANN**: Explore integrating more advanced ANN libraries like `faiss` for improved vector search performance.
-  - **Priority Queues**: Introduce a priority queue data structure for task management.
   - **Improved Pub/Sub**: Fan-out implementation with a more Pythonic API.
   - **Async API**: Comprehensive async support with on-demand wrappers for all collections.
 

beaver_db-0.8.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+beaver/__init__.py,sha256=-z5Gj6YKMOswpJOOn5Gej8z5i6k3c0Xs00DIYLA-bMI,75
+beaver/channels.py,sha256=2lem2_yEFMc7cjdSx4FbFZQOaeT-HtbSvon3WYYRYzY,1952
+beaver/collections.py,sha256=R4bVmP37s_ZnCkb3Jdck2H8dRvD3-ihFV4mEsA14YeE,15716
+beaver/core.py,sha256=GpQ5HVJd2yBGq_RGC6TKlhRpGvNdFg88c59oAkltgqY,7904
+beaver/dicts.py,sha256=y4z632XKWU29ekP_vdFSOP-MAG9Z8b79kBEHA88gO7E,4463
+beaver/lists.py,sha256=jFlDWwyaYycG0ZFVm58rMChefUaVZhaP1UeQ-hVo3Sg,9082
+beaver/queues.py,sha256=WKpBzlXr9Hp_rOKEs_Y1Tjyj_hWx6ql1uBRKBV7rw8w,2780
+beaver_db-0.8.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
+beaver_db-0.8.0.dist-info/METADATA,sha256=hB3ZWilwbPhfq64laoxiwxx99KfT-WIFOk1Nj2jK28c,9833
+beaver_db-0.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+beaver_db-0.8.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
+beaver_db-0.8.0.dist-info/RECORD,,

beaver_db-0.7.1.dist-info/RECORD

@@ -1,11 +0,0 @@
-beaver/__init__.py,sha256=-z5Gj6YKMOswpJOOn5Gej8z5i6k3c0Xs00DIYLA-bMI,75
-beaver/channels.py,sha256=2lem2_yEFMc7cjdSx4FbFZQOaeT-HtbSvon3WYYRYzY,1952
-beaver/collections.py,sha256=R4bVmP37s_ZnCkb3Jdck2H8dRvD3-ihFV4mEsA14YeE,15716
-beaver/core.py,sha256=K_abD1RiAMT1jYv6T11fpckNljjqcotu3lkLkCz0bHg,6670
-beaver/dicts.py,sha256=y4z632XKWU29ekP_vdFSOP-MAG9Z8b79kBEHA88gO7E,4463
-beaver/lists.py,sha256=jFlDWwyaYycG0ZFVm58rMChefUaVZhaP1UeQ-hVo3Sg,9082
-beaver_db-0.7.1.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
-beaver_db-0.7.1.dist-info/METADATA,sha256=hRyym_sgGSdGTsIp55w7FpnXQF0-HczAzxZio02pFIs,8257
-beaver_db-0.7.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-beaver_db-0.7.1.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
-beaver_db-0.7.1.dist-info/RECORD,,