beaver-db 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

beaver/lists.py

@@ -0,0 +1,166 @@
+import json
+import sqlite3
+from typing import Any, Union
+
+
+class ListWrapper:
+    """A wrapper providing a Pythonic interface to a list in the database."""
+
+    def __init__(self, name: str, conn: sqlite3.Connection):
+        self._name = name
+        self._conn = conn
+
+    def __len__(self) -> int:
+        """Returns the number of items in the list (e.g., `len(my_list)`)."""
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT COUNT(*) FROM beaver_lists WHERE list_name = ?", (self._name,)
+        )
+        count = cursor.fetchone()[0]
+        cursor.close()
+        return count
+
+    def __getitem__(self, key: Union[int, slice]) -> Any:
+        """
+        Retrieves an item or slice from the list (e.g., `my_list[0]`, `my_list[1:3]`).
+        """
+        if isinstance(key, slice):
+            start, stop, step = key.indices(len(self))
+            if step != 1:
+                raise ValueError("Slicing with a step is not supported.")
+
+            limit = stop - start
+            if limit <= 0:
+                return []
+
+            cursor = self._conn.cursor()
+            cursor.execute(
+                "SELECT item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT ? OFFSET ?",
+                (self._name, limit, start),
+            )
+            results = [json.loads(row["item_value"]) for row in cursor.fetchall()]
+            cursor.close()
+            return results
+
+        elif isinstance(key, int):
+            list_len = len(self)
+            if key < -list_len or key >= list_len:
+                raise IndexError("List index out of range.")
+
+            offset = key if key >= 0 else list_len + key
+
+            cursor = self._conn.cursor()
+            cursor.execute(
+                "SELECT item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT 1 OFFSET ?",
+                (self._name, offset),
+            )
+            result = cursor.fetchone()
+            cursor.close()
+            return json.loads(result["item_value"]) if result else None
+
+        else:
+            raise TypeError("List indices must be integers or slices.")
+
+    def _get_order_at_index(self, index: int) -> float:
+        """Helper to get the float `item_order` at a specific index."""
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT item_order FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT 1 OFFSET ?",
+            (self._name, index),
+        )
+        result = cursor.fetchone()
+        cursor.close()
+
+        if result:
+            return result[0]
+
+        raise IndexError(f"{index} out of range.")
+
+    def push(self, value: Any):
+        """Pushes an item to the end of the list."""
+        with self._conn:
+            cursor = self._conn.cursor()
+            cursor.execute(
+                "SELECT MAX(item_order) FROM beaver_lists WHERE list_name = ?",
+                (self._name,),
+            )
+            max_order = cursor.fetchone()[0] or 0.0
+            new_order = max_order + 1.0
+
+            cursor.execute(
+                "INSERT INTO beaver_lists (list_name, item_order, item_value) VALUES (?, ?, ?)",
+                (self._name, new_order, json.dumps(value)),
+            )
+
+    def prepend(self, value: Any):
+        """Prepends an item to the beginning of the list."""
+        with self._conn:
+            cursor = self._conn.cursor()
+            cursor.execute(
+                "SELECT MIN(item_order) FROM beaver_lists WHERE list_name = ?",
+                (self._name,),
+            )
+            min_order = cursor.fetchone()[0] or 0.0
+            new_order = min_order - 1.0
+
+            cursor.execute(
+                "INSERT INTO beaver_lists (list_name, item_order, item_value) VALUES (?, ?, ?)",
+                (self._name, new_order, json.dumps(value)),
+            )
+
+    def insert(self, index: int, value: Any):
+        """Inserts an item at a specific index."""
+        list_len = len(self)
+        if index <= 0:
+            self.prepend(value)
+            return
+        if index >= list_len:
+            self.push(value)
+            return
+
+        # Midpoint insertion for O(1) inserts
+        order_before = self._get_order_at_index(index - 1)
+        order_after = self._get_order_at_index(index)
+        new_order = order_before + (order_after - order_before) / 2.0
+
+        with self._conn:
+            self._conn.execute(
+                "INSERT INTO beaver_lists (list_name, item_order, item_value) VALUES (?, ?, ?)",
+                (self._name, new_order, json.dumps(value)),
+            )
+
+    def pop(self) -> Any:
+        """Removes and returns the last item from the list."""
+        with self._conn:
+            cursor = self._conn.cursor()
+            cursor.execute(
+                "SELECT rowid, item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order DESC LIMIT 1",
+                (self._name,),
+            )
+            result = cursor.fetchone()
+            if not result:
+                return None
+
+            rowid_to_delete, value_to_return = result
+            cursor.execute(
+                "DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,)
+            )
+            return json.loads(value_to_return)
+
+    def deque(self) -> Any:
+        """Removes and returns the first item from the list."""
+        with self._conn:
+            cursor = self._conn.cursor()
+            cursor.execute(
+                "SELECT rowid, item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT 1",
+                (self._name,),
+            )
+            result = cursor.fetchone()
+            if not result:
+                return None
+
+            rowid_to_delete, value_to_return = result
+            cursor.execute(
+                "DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,)
+            )
+            return json.loads(value_to_return)

beaver/subscribers.py

@@ -0,0 +1,54 @@
+import json
+import sqlite3
+import time
+from typing import Any, Iterator
+
+
+class SubWrapper(Iterator):
+    """
+    A synchronous, blocking iterator that polls a channel for new messages.
+    """
+
+    def __init__(
+        self, conn: sqlite3.Connection, channel_name: str, poll_interval: float = 0.1
+    ):
+        """
+        Initializes the synchronous subscriber.
+
+        Args:
+            conn: The SQLite database connection.
+            channel_name: The name of the channel to subscribe to.
+            poll_interval: The time in seconds to wait between polling for new messages.
+        """
+        self._conn = conn
+        self._channel = channel_name
+        self._poll_interval = poll_interval
+        self._last_seen_timestamp = time.time()
+
+    def __iter__(self) -> "SubWrapper":
+        """Returns the iterator object itself."""
+        return self
+
+    def __next__(self) -> Any:
+        """
+        Blocks until a new message is available on the channel and returns it.
+        This polling mechanism is simple but can introduce a slight latency
+        equivalent to the poll_interval.
+        """
+        while True:
+            # Fetch the next available message from the database
+            cursor = self._conn.cursor()
+            cursor.execute(
+                "SELECT timestamp, message_payload FROM beaver_pubsub_log WHERE channel_name = ? AND timestamp > ? ORDER BY timestamp ASC LIMIT 1",
+                (self._channel, self._last_seen_timestamp),
+            )
+            result = cursor.fetchone()
+            cursor.close()
+
+            if result:
+                # If a message is found, update the timestamp and return the payload
+                self._last_seen_timestamp = result["timestamp"]
+                return json.loads(result["message_payload"])
+            else:
+                # If no new messages, wait for the poll interval before trying again
+                time.sleep(self._poll_interval)

beaver_db-0.5.1.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: beaver-db
+Version: 0.5.1
+Summary: Asynchronous, embedded, modern DB based on SQLite.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: scipy>=1.16.2
+
+# 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.
+
+## Design Philosophy
+
+`beaver` is built with a minimalistic philosophy for small, local use cases where a full-blown database server would be overkill.
+
+  - **Minimalistic & Zero-Dependency**: Uses only Python's standard libraries (`sqlite3`) and `numpy`/`scipy`.
+  - **Synchronous & Thread-Safe**: Designed for simplicity and safety in multi-threaded environments.
+  - **Built for Local Applications**: Perfect for local AI tools, RAG prototypes, chatbots, and desktop utilities that need persistent, structured data without network overhead.
+  - **Fast by Default**: It's built on SQLite, which is famously fast and reliable for local applications. The vector search is accelerated with an in-memory k-d tree.
+  - **Standard Relational Interface**: While `beaver` provides high-level features, you can always use the same SQLite file for normal relational tasks with standard SQL.
+
+## Core Features
+
+  - **Synchronous Pub/Sub**: A simple, thread-safe, Redis-like publish-subscribe system for real-time messaging.
+  - **Persistent Key-Value Store**: A simple `set`/`get` interface for storing any JSON-serializable object.
+  - **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
+  - **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.
+  - **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.
+
+## Installation
+
+```bash
+pip install beaver-db
+```
+
+## Quickstart & API Guide
+
+### Initialization
+
+All you need to do is import and instantiate the `BeaverDB` class with a file path.
+
+```python
+from beaver import BeaverDB, Document
+
+db = BeaverDB("my_application.db")
+```
+
+### Key-Value Store
+
+Use `set()` and `get()` for simple data storage. The value can be any JSON-encodable object.
+
+```python
+# Set a value
+db.set("app_config", {"theme": "dark", "user_id": 123})
+
+# Get a value
+config = db.get("app_config")
+print(f"Theme: {config.get('theme')}") # Output: Theme: dark
+```
+
+### List Management
+
+Get a list wrapper with `db.list()` and use Pythonic methods to manage it.
+
+```python
+tasks = db.list("daily_tasks")
+tasks.push("Write the project report")
+tasks.prepend("Plan the day's agenda")
+print(f"The first task is: {tasks[0]}")
+```
+
+### Vector & Text Search
+
+Store `Document` objects containing vector embeddings and metadata. When you index a document, its string fields are automatically made available for full-text search.
+
+```python
+# Get a handle to a collection
+docs = db.collection("articles")
+
+# Create and index a multi-modal document
+doc = Document(
+    id="sql-001",
+    embedding=[0.8, 0.1, 0.1],
+    content="SQLite is a powerful embedded database ideal for local apps.",
+    author="John Smith"
+)
+docs.index(doc)
+
+# 1. Perform a vector search to find semantically similar documents
+query_vector = [0.7, 0.2, 0.2]
+vector_results = docs.search(vector=query_vector, top_k=1)
+top_doc, distance = vector_results[0]
+print(f"Vector Search Result: {top_doc.content} (distance: {distance:.2f})")
+
+# 2. Perform a full-text search to find documents with specific words
+text_results = docs.match(query="database", top_k=1)
+top_doc, rank = text_results[0]
+print(f"Full-Text Search Result: {top_doc.content} (rank: {rank:.2f})")
+```
+
+### Graph Traversal
+
+Create relationships between documents and traverse them.
+
+```python
+from beaver import WalkDirection
+
+# Create documents
+alice = Document(id="alice", name="Alice")
+bob = Document(id="bob", name="Bob")
+charlie = Document(id="charlie", name="Charlie")
+
+# Index them
+social_net = db.collection("social")
+social_net.index(alice)
+social_net.index(bob)
+social_net.index(charlie)
+
+# Create edges
+social_net.connect(alice, bob, label="FOLLOWS")
+social_net.connect(bob, charlie, label="FOLLOWS")
+
+# Find direct neighbors
+following = social_net.neighbors(alice, label="FOLLOWS")
+print(f"Alice follows: {[p.id for p in following]}")
+
+# Perform a multi-hop walk to find friends of friends
+foaf = social_net.walk(
+    source=alice,
+    labels=["FOLLOWS"],
+    depth=2,
+    direction=WalkDirection.OUTGOING,
+)
+print(f"Alice's extended network: {[p.id for p in foaf]}")
+```
+
+### Synchronous Pub/Sub
+
+Publish events from one part of your app and listen in another using threads.
+
+```python
+import threading
+
+def listener():
+    for message in db.subscribe("system_events"):
+        print(f"LISTENER: Received -> {message}")
+        if message.get("event") == "shutdown":
+            break
+
+def publisher():
+    db.publish("system_events", {"event": "user_login", "user": "alice"})
+    db.publish("system_events", {"event": "shutdown"})
+
+# Run them concurrently
+listener_thread = threading.Thread(target=listener)
+publisher_thread = threading.Thread(target=publisher)
+listener_thread.start()
+publisher_thread.start()
+listener_thread.join()
+publisher_thread.join()
+```
+
+## License
+
+This project is licensed under the MIT License.

beaver_db-0.5.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+beaver/__init__.py,sha256=-z5Gj6YKMOswpJOOn5Gej8z5i6k3c0Xs00DIYLA-bMI,75
+beaver/collections.py,sha256=fP1xkmo-XXlk3H_lPRiqFhtizINQn8192wOtXFlkTK4,12811
+beaver/core.py,sha256=sk0Z_k7EcORe6bN8CfPukGX7eAfmCGSX_B37KpJmQJ4,7279
+beaver/lists.py,sha256=JG1JOkaYCUldADUzPJhaNi93w-k3S8mUzcCw574uht4,5915
+beaver/subscribers.py,sha256=tCty2iDbeE9IXcPicbxj2CB5gqfLufMB9-nLQwqNBUU,1944
+beaver_db-0.5.1.dist-info/METADATA,sha256=GSFmx4PdrZSOMOJg1RVV9ni59hjtvyOCosAeaUxFJuU,5875
+beaver_db-0.5.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+beaver_db-0.5.1.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
+beaver_db-0.5.1.dist-info/RECORD,,

beaver_db-0.4.0.dist-info/METADATA

@@ -1,129 +0,0 @@
-Metadata-Version: 2.4
-Name: beaver-db
-Version: 0.4.0
-Summary: Asynchronous, embedded, modern DB based on SQLite.
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-Requires-Dist: numpy>=2.3.3
-
-# 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**synchronous **V**ector & **E**vent Retrieval. It's an industrious, all-in-one database designed to manage complex, modern data types without requiring a database server.
-
-## Design Philosophy
-
-`beaver` is built with a minimalistic philosophy for small, local use cases where a full-blown database server would be overkill.
-
-  - **Minimalistic & Zero-Dependency**: Uses only Python's standard libraries (`sqlite3`, `asyncio`) and `numpy`.
-  - **Async-First (When It Matters)**: The pub/sub system is fully asynchronous for high-performance, real-time messaging. Other features like key-value, list, and vector operations are synchronous for ease of use.
-  - **Built for Local Applications**: Perfect for local AI tools, RAG prototypes, chatbots, and desktop utilities that need persistent, structured data without network overhead.
-  - **Fast by Default**: It's built on SQLite, which is famously fast and reliable for local applications.
-
-## Core Features
-
-  - **Asynchronous Pub/Sub**: A fully asynchronous, Redis-like publish-subscribe system for real-time messaging.
-  - **Persistent Key-Value Store**: A simple `set`/`get` interface for storing any JSON-serializable object.
-  - **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
-  - **Vector Storage & Search**: Store vector embeddings and perform simple, brute-force k-nearest neighbor searches, ideal for small-scale RAG.
-  - **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.
-
-## Installation
-
-```bash
-pip install beaver-db
-```
-
-## Quickstart & API Guide
-
-### Initialization
-
-All you need to do is import and instantiate the `BeaverDB` class with a file path.
-
-```python
-from beaver import BeaverDB, Document
-
-db = BeaverDB("my_application.db")
-```
-
-### Key-Value Store
-
-Use `set()` and `get()` for simple data storage. The value can be any JSON-encodable object.
-
-```python
-# Set a value
-db.set("app_config", {"theme": "dark", "user_id": 123})
-
-# Get a value
-config = db.get("app_config")
-print(f"Theme: {config['theme']}") # Output: Theme: dark
-```
-
-### List Management
-
-Get a list wrapper with `db.list()` and use Pythonic methods to manage it.
-
-```python
-tasks = db.list("daily_tasks")
-tasks.push("Write the project report")
-tasks.prepend("Plan the day's agenda")
-print(f"The first task is: {tasks[0]}")
-```
-
-### Vector Storage & Search
-
-Store `Document` objects containing vector embeddings and metadata. The search is a linear scan, which is sufficient for small-to-medium collections.
-
-```python
-# Get a handle to a collection
-docs = db.collection("my_documents")
-
-# Create and index a document (ID will be a UUID)
-doc1 = Document(embedding=[0.1, 0.2, 0.7], text="A cat sat on the mat.")
-docs.index(doc1)
-
-# Create and index a document with a specific ID (for upserting)
-doc2 = Document(id="article-42", embedding=[0.9, 0.1, 0.1], text="A dog chased a ball.")
-docs.index(doc2)
-
-# Search for the 2 most similar documents
-query_vector = [0.15, 0.25, 0.65]
-results = docs.search(vector=query_vector, top_k=2)
-
-# Results are a list of (Document, distance) tuples
-top_document, distance = results[0]
-print(f"Closest document: {top_document.text} (distance: {distance:.4f})")
-```
-
-### Asynchronous Pub/Sub
-
-Publish events from one part of your app and listen in another using `asyncio`.
-
-```python
-import asyncio
-
-async def listener():
-    async with db.subscribe("system_events") as sub:
-        async for message in sub:
-            print(f"LISTENER: Received event -> {message['event']}")
-
-async def publisher():
-    await asyncio.sleep(1)
-    await db.publish("system_events", {"event": "user_login", "user": "alice"})
-
-# To run them concurrently:
-# asyncio.run(asyncio.gather(listener(), publisher()))
-```
-
-## Roadmap
-
-`beaver` aims to be a complete, self-contained data toolkit. The following features are planned:
-
-  - **More Efficient Vector Search**: Integrate an approximate nearest neighbor (ANN) index like `scipy.spatial.cKDTree` to improve search speed on larger datasets.
-  - **JSON Document Store with Full-Text Search**: Store flexible JSON documents and get powerful full-text search across all text fields, powered by SQLite's FTS5 extension.
-  - **Standard Relational Interface**: While `beaver` provides high-level features, you can always use the same SQLite file for normal relational tasks with standard SQL.
-
-## License
-
-This project is licensed under the MIT License.

beaver_db-0.4.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-beaver/__init__.py,sha256=uTPhMNDjw41YTWQN8NTLbovudfp8RIwcqbZ5XtYIuJA,36
-beaver/core.py,sha256=i2rBoUM1rq_j1xM3w4xW4c9e2eI8Ce6BeJ8rE8jQ-fI,21928
-beaver_db-0.4.0.dist-info/METADATA,sha256=7VzqxHKU-Ft1QVAfVvywt4e50C3QWxS7FUpKIaQEJKk,4865
-beaver_db-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-beaver_db-0.4.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
-beaver_db-0.4.0.dist-info/RECORD,,