beaver-db 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

beaver/__init__.py

@@ -1 +1 @@
-from .core import BeaverDB, Subscriber
+from .core import BeaverDB, Document

beaver/core.py

@@ -1,35 +1,357 @@
 import asyncio
+import uuid
+import numpy as np
 import json
 import sqlite3
 import time
-from typing import Any, AsyncIterator
+from typing import Any, AsyncIterator, Union
 
-# --- SQL Schema ---
-# These statements are executed once to set up the database.
 
-PUBSUB_TABLE_SQL = """
-CREATE TABLE IF NOT EXISTS _beaver_pubsub_log (
-    timestamp REAL PRIMARY KEY,
-    channel_name TEXT NOT NULL,
-    message_payload TEXT NOT NULL
-);
-"""
+class BeaverDB:
+    """
+    An embedded, multi-modal database in a single SQLite file.
+    Currently supports async pub/sub and a synchronous key-value store.
+    """
+
+    def __init__(self, db_path: str):
+        """
+        Initializes the database connection and creates necessary tables.
+
+        Args:
+            db_path: The path to the SQLite database file.
+        """
+        self._db_path = db_path
+        # Enable WAL mode for better concurrency between readers and writers
+        self._conn = sqlite3.connect(self._db_path, check_same_thread=False)
+        self._conn.execute("PRAGMA journal_mode=WAL;")
+        self._conn.row_factory = sqlite3.Row
+        self._create_pubsub_table()
+        self._create_kv_table()
+        self._create_list_table()
+        self._create_collections_table()
+
+    def _create_pubsub_table(self):
+        """Creates the pub/sub log table if it doesn't exist."""
+        with self._conn:
+            self._conn.execute("""
+                CREATE TABLE IF NOT EXISTS beaver_pubsub_log (
+                    timestamp REAL PRIMARY KEY,
+                    channel_name TEXT NOT NULL,
+                    message_payload TEXT NOT NULL
+                )
+            """)
+            self._conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_pubsub_channel_timestamp
+                ON beaver_pubsub_log (channel_name, timestamp)
+            """)
+
+    def _create_kv_table(self):
+        """Creates the key-value store table if it doesn't exist."""
+        with self._conn:
+            self._conn.execute("""
+                CREATE TABLE IF NOT EXISTS _beaver_kv_store (
+                    key TEXT PRIMARY KEY,
+                    value TEXT NOT NULL
+                )
+            """)
+
+    def _create_list_table(self):
+        """Creates the lists table if it doesn't exist."""
+        with self._conn:
+            self._conn.execute("""
+                CREATE TABLE IF NOT EXISTS beaver_lists (
+                    list_name TEXT NOT NULL,
+                    item_order REAL NOT NULL,
+                    item_value TEXT NOT NULL,
+                    PRIMARY KEY (list_name, item_order)
+                )
+            """)
+
+    def _create_collections_table(self):
+        """Creates the collections table if it doesn't exist."""
+        with self._conn:
+            self._conn.execute("""
+                CREATE TABLE IF NOT EXISTS beaver_collections (
+                    collection TEXT NOT NULL,
+                    item_id TEXT NOT NULL,
+                    item_vector BLOB NOT NULL,
+                    metadata TEXT,
+                    PRIMARY KEY (collection, item_id)
+                )
+            """)
+
+    def close(self):
+        """Closes the database connection."""
+        if self._conn:
+            self._conn.close()
+
+    # --- Key-Value Store Methods ---
+
+    def set(self, key: str, value: Any):
+        """
+        Stores a JSON-serializable value for a given key.
+        This operation is synchronous.
+
+        Args:
+            key: The unique string identifier for the value.
+            value: A JSON-serializable Python object (dict, list, str, int, etc.).
+
+        Raises:
+            TypeError: If the key is not a string or the value is not JSON-serializable.
+        """
+        if not isinstance(key, str):
+            raise TypeError("Key must be a string.")
+
+        try:
+            json_value = json.dumps(value)
+        except TypeError as e:
+            raise TypeError("Value must be JSON-serializable.") from e
+
+        with self._conn:
+            self._conn.execute(
+                "INSERT OR REPLACE INTO _beaver_kv_store (key, value) VALUES (?, ?)",
+                (key, json_value)
+            )
+
+    def get(self, key: str) -> Any:
+        """
+        Retrieves a value for a given key.
+        This operation is synchronous.
+
+        Args:
+            key: The string identifier for the value.
+
+        Returns:
+            The deserialized Python object, or None if the key is not found.
+
+        Raises:
+            TypeError: If the key is not a string.
+        """
+        if not isinstance(key, str):
+            raise TypeError("Key must be a string.")
+
+        cursor = self._conn.cursor()
+        cursor.execute("SELECT value FROM _beaver_kv_store WHERE key = ?", (key,))
+        result = cursor.fetchone()
+        cursor.close()
+
+        if result:
+            return json.loads(result['value'])
+        return None
+
+    # --- List Methods ---
+
+    def list(self, name: str) -> "ListWrapper":
+        """
+        Returns a wrapper object for interacting with a specific list.
+
+        Args:
+            name: The name of the list.
+
+        Returns:
+            A ListWrapper instance bound to the given list name.
+        """
+        if not isinstance(name, str) or not name:
+            raise TypeError("List name must be a non-empty string.")
+        return ListWrapper(name, self._conn)
+
+    def collection(self, name: str) -> "CollectionWrapper":
+        """Returns a wrapper for interacting with a vector collection."""
+        return CollectionWrapper(name, self._conn)
+
+    # --- Asynchronous Pub/Sub Methods ---
+
+    async def publish(self, channel_name: str, payload: Any):
+        """
+        Publishes a JSON-serializable message to a channel.
+        This operation is asynchronous.
+        """
+        if not isinstance(channel_name, str) or not channel_name:
+            raise ValueError("Channel name must be a non-empty string.")
+        try:
+            json_payload = json.dumps(payload)
+        except TypeError as e:
+            raise TypeError("Message payload must be JSON-serializable.") from e
+
+        await asyncio.to_thread(
+            self._write_publish_to_db, channel_name, json_payload
+        )
+
+    def _write_publish_to_db(self, channel_name, json_payload):
+        """The synchronous part of the publish operation."""
+        with self._conn:
+            self._conn.execute(
+                "INSERT INTO beaver_pubsub_log (timestamp, channel_name, message_payload) VALUES (?, ?, ?)",
+                (time.time(), channel_name, json_payload)
+            )
+
+    def subscribe(self, channel_name: str) -> "Subscriber":
+        """
+        Subscribes to a channel, returning an async iterator.
+        """
+        return Subscriber(self._conn, channel_name)
+
+
+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))
+            )
 
-PUBSUB_INDEX_SQL = """
-CREATE INDEX IF NOT EXISTS _beaver_idx_pubsub_channel_timestamp
-ON _beaver_pubsub_log (channel_name, timestamp);
-"""
+    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
+        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)
 
 
 class Subscriber(AsyncIterator):
     """
-    A stateful, async context manager for receiving messages from a channel.
-
-    This object is returned by `BeaverDB.subscribe()` and is designed to
-    be used with `async with` and `async for`.
+    An async iterator that polls a channel for new messages.
+    Designed to be used with 'async with'.
     """
-    def __init__(self, db_path: str, channel_name: str, poll_interval: float = 0.1):
-        self._db_path = db_path
+
+    def __init__(self, conn: sqlite3.Connection, channel_name: str, poll_interval: float = 0.1):
+        self._conn = conn
         self._channel = channel_name
         self._poll_interval = poll_interval
         self._queue = asyncio.Queue()
@@ -37,50 +359,42 @@ class Subscriber(AsyncIterator):
         self._polling_task = None
 
     async def _poll_for_messages(self):
-        """A background task that polls SQLite for new messages."""
+        """Background task that polls the database for new messages."""
         while True:
             try:
-                # Run the synchronous DB query in a thread to avoid blocking asyncio
                 new_messages = await asyncio.to_thread(
                     self._fetch_new_messages_from_db
                 )
-
                 if new_messages:
-                    for timestamp, payload_str in new_messages:
-                        payload = json.loads(payload_str)
+                    for msg in new_messages:
+                        payload = json.loads(msg["message_payload"])
                         await self._queue.put(payload)
-                        self._last_seen_timestamp = timestamp
-
+                        self._last_seen_timestamp = msg["timestamp"]
                 await asyncio.sleep(self._poll_interval)
             except asyncio.CancelledError:
-                # Gracefully exit when the task is cancelled
                 break
-            except Exception as e:
-                # In a real app, you'd add more robust logging/error handling
-                print(f"ERROR: Pub/sub polling task failed: {e}")
-                await asyncio.sleep(self._poll_interval * 5) # Back off on error
-
-    def _fetch_new_messages_from_db(self) -> list[tuple[float, str]]:
-        """The actual synchronous database query using sqlite3."""
-        # Each call in a separate thread gets its own connection object.
-        with sqlite3.connect(self._db_path) as conn:
-            cursor = conn.cursor()
-            cursor.execute(
-                "SELECT timestamp, message_payload FROM _beaver_pubsub_log "
-                "WHERE channel_name = ? AND timestamp > ? "
-                "ORDER BY timestamp ASC",
-                (self._channel, self._last_seen_timestamp)
-            )
-            return cursor.fetchall()
+            except Exception:
+                # In a real app, add more robust error logging
+                await asyncio.sleep(self._poll_interval * 5)
+
+    def _fetch_new_messages_from_db(self) -> list:
+        """The actual synchronous database query."""
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT timestamp, message_payload FROM beaver_pubsub_log WHERE channel_name = ? AND timestamp > ? ORDER BY timestamp ASC",
+            (self._channel, self._last_seen_timestamp)
+        )
+        results = cursor.fetchall()
+        cursor.close()
+        return results
 
     async def __aenter__(self):
-        """Starts the background task when entering an 'async with' block."""
-        if not self._polling_task:
-            self._polling_task = asyncio.create_task(self._poll_for_messages())
+        """Starts the background task."""
+        self._polling_task = asyncio.create_task(self._poll_for_messages())
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
-        """Stops the background task when exiting the 'async with' block."""
+        """Stops the background task."""
         if self._polling_task:
             self._polling_task.cancel()
             await asyncio.gather(self._polling_task, return_exceptions=True)
@@ -93,71 +407,86 @@ class Subscriber(AsyncIterator):
         return await self._queue.get()
 
 
-class BeaverDB:
-    """
-    A single-file, multi-modal database for Python.
+class Document:
+    """A data class for a vector and its metadata, with a unique ID."""
+    def __init__(self, embedding: list[float], id: str|None = None, **metadata):
+        if not isinstance(embedding, list) or not all(isinstance(x, (int, float)) for x in embedding):
+            raise TypeError("Embedding must be a list of numbers.")
 
-    Currently provides asynchronous pub/sub functionality using the standard
-    sqlite3 library.
-    """
-    def __init__(self, db_path: str = "beaver.db"):
-        """
-        Initializes the database.
+        self.id = id or str(uuid.uuid4())
+        self.embedding = np.array(embedding, dtype=np.float32)
 
-        Args:
-            db_path: The path to the SQLite database file.
-        """
-        self.db_path = db_path
-        self._setup_database()
+        for key, value in metadata.items():
+            setattr(self, key, value)
 
-    def _setup_database(self):
-        """Creates the necessary tables and indices if they don't exist."""
-        with sqlite3.connect(self.db_path) as conn:
-            cursor = conn.cursor()
-            cursor.execute(PUBSUB_TABLE_SQL)
-            cursor.execute(PUBSUB_INDEX_SQL)
-            conn.commit()
+    def to_dict(self) -> dict[str, Any]:
+        """Serializes metadata to a dictionary."""
+        metadata = self.__dict__.copy()
+        # Exclude internal attributes from the metadata payload
+        metadata.pop('embedding', None)
+        metadata.pop('id', None)
+        return metadata
 
-    async def publish(self, channel_name: str, payload: Any):
+    def __repr__(self):
+        metadata_str = ', '.join(f"{k}={v!r}" for k, v in self.to_dict().items())
+        return f"Document(id='{self.id}', {metadata_str})"
+
+
+class CollectionWrapper:
+    """A wrapper for vector collection operations with upsert logic."""
+    def __init__(self, name: str, conn: sqlite3.Connection):
+        self._name = name
+        self._conn = conn
+
+    def index(self, document: Document):
         """
-        Publishes a JSON-serializable message to a channel.
+        Indexes a Document, performing an upsert based on the document's ID.
+        If the ID exists, the record is replaced.
+        If the ID is new (or auto-generated), a new record is inserted.
 
         Args:
-            channel_name: The name of the channel.
-            payload: A JSON-serializable Python object (e.g., dict, list).
+            document: The Document object to index.
         """
-        if not isinstance(channel_name, str) or not channel_name:
-            raise ValueError("Channel name must be a non-empty string.")
+        with self._conn:
+            self._conn.execute(
+                "INSERT OR REPLACE INTO beaver_collections (collection, item_id, item_vector, metadata) VALUES (?, ?, ?, ?)",
+                (
+                    self._name,
+                    document.id,
+                    document.embedding.tobytes(),
+                    json.dumps(document.to_dict())
+                )
+            )
 
-        try:
-            json_payload = json.dumps(payload)
-        except TypeError as e:
-            raise TypeError("Message payload must be JSON-serializable.") from e
+    def search(self, vector: list[float], top_k: int = 10) -> list[tuple[Document, float]]:
+        """
+        Performs a vector search and returns Document objects.
+        """
+        query_vector = np.array(vector, dtype=np.float32)
 
-        # Run the blocking DB write in a thread to keep this method non-blocking
-        await asyncio.to_thread(
-            self._write_publish_to_db, channel_name, json_payload
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT item_id, item_vector, metadata FROM beaver_collections WHERE collection = ?",
+            (self._name,)
         )
 
-    def _write_publish_to_db(self, channel_name: str, json_payload: str):
-        """The synchronous part of the publish operation using sqlite3."""
-        with sqlite3.connect(self.db_path) as conn:
-            cursor = conn.cursor()
-            cursor.execute(
-                "INSERT INTO _beaver_pubsub_log (timestamp, channel_name, message_payload) "
-                "VALUES (?, ?, ?)",
-                (time.time(), channel_name, json_payload)
-            )
-            conn.commit()
+        all_docs_data = cursor.fetchall()
+        cursor.close()
 
-    def subscribe(self, channel_name: str) -> Subscriber:
-        """
-        Subscribes to a channel.
+        if not all_docs_data:
+            return []
 
-        Returns a 'Subscriber' object that can be used in an 'async with'
-        block and `async for` loop to receive messages.
+        results = []
+        for row in all_docs_data:
+            doc_id = row['item_id']
+            embedding = np.frombuffer(row['item_vector'], dtype=np.float32).tolist()
+            metadata = json.loads(row['metadata'])
 
-        Args:
-            channel_name: The name of the channel to subscribe to.
-        """
-        return Subscriber(self.db_path, channel_name)
+            distance = np.linalg.norm(embedding - query_vector)
+
+            # Reconstruct the Document object with its original ID
+            doc = Document(id=doc_id, embedding=list(embedding), **metadata)
+            results.append((doc, float(distance)))
+
+        results.sort(key=lambda x: x[1])
+        return results[:top_k]

beaver_db-0.3.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: beaver-db
+Version: 0.3.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.3.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+beaver/__init__.py,sha256=uTPhMNDjw41YTWQN8NTLbovudfp8RIwcqbZ5XtYIuJA,36
+beaver/core.py,sha256=I-_i8AshcNor1OZxoEtNjzLXCy1Byuxvo84y9K4AV_Q,17518
+beaver_db-0.3.0.dist-info/METADATA,sha256=_Hy3Fq64IDahqm3K0vuPvvZRTmtO0sU-tEGlmEjLNpE,4865
+beaver_db-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+beaver_db-0.3.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
+beaver_db-0.3.0.dist-info/RECORD,,

beaver_db-0.1.0.dist-info/METADATA

@@ -1,117 +0,0 @@
-Metadata-Version: 2.4
-Name: beaver-db
-Version: 0.1.0
-Summary: Asynchronous, embedded, modern DB based on SQLite.
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-
-# beaver 🦫
-
-A 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 **R**etrieval. It's an industrious, all-in-one database designed to manage complex, modern data types without leaving the comfort of a single file.
-
-This project is currently in its initial phase, with the core asynchronous pub/sub functionality fully implemented.
-
-## Core Features (Current)
-
-- **Zero Dependencies:** Built using only the standard Python `sqlite3` and `asyncio` libraries. No external packages to install.
-- **Async Pub/Sub:** A fully asynchronous, Redis-like publish-subscribe system for real-time messaging between components of your application.
-- **Single-File & Persistent:** All data is stored in a single SQLite file, making it incredibly portable and easy to back up. Your event log persists across application restarts.
-- **Works with Existing Databases:** `beaver` can be pointed at an existing SQLite file and will create its tables without disturbing other data.
-
-## Use Cases
-
-I built `beaver` to have a local, embedded database for building small AI-powered projects without having to pay for a server-based database.
-
-Examples include:
-
-- Streaming messages and tokens from a local FastAPI to a local Streamlit app.
-- Storing user files for Retrieval Augmented Generation in single-user applications.
-
-## Installation
-
-To use `beaver`, just run `pip install beaver-db` and import the main class.
-
-```python
-import asyncio
-from beaver import BeaverDB
-
-
-# --- Example Usage ---
-async def listener(db: BeaverDB):
-    """A sample task that listens for messages."""
-    print("LISTENER: Waiting for messages on the 'system_events' channel...")
-    try:
-        async with db.subscribe("system_events") as subscriber:
-            async for message in subscriber:
-                print(f"LISTENER: Received -> {message}")
-    except asyncio.CancelledError:
-        print("LISTENER: Shutting down.")
-
-
-async def publisher(db: BeaverDB):
-    """A sample task that publishes messages."""
-    print("PUBLISHER: Ready to send events.")
-    await asyncio.sleep(1) # Give the listener a moment to start
-
-    print("PUBLISHER: Sending user login event.")
-    await db.publish(
-        "system_events",
-        {"event": "user_login", "username": "alice", "status": "success"}
-    )
-
-    await asyncio.sleep(2)
-
-    print("PUBLISHER: Sending system alert.")
-    await db.publish(
-        "system_events",
-        {"event": "system_alert", "level": "warning", "detail": "CPU usage at 85%"}
-    )
-    await asyncio.sleep(1)
-
-
-async def main():
-    """Runs the listener and publisher concurrently."""
-    db = BeaverDB("demo.db")
-
-    # Run both tasks and wait for them to complete
-    listener_task = asyncio.create_task(listener(db))
-    publisher_task = asyncio.create_task(publisher(db))
-
-    await asyncio.sleep(5) # Let them run for a bit
-    listener_task.cancel() # Cleanly shut down the listener
-    await asyncio.gather(listener_task, publisher_task, return_exceptions=True)
-    print("\nDemo finished.")
-
-
-if __name__ == "__main__":
-    # To run this demo, save the file as beaver.py and run `python beaver.py`
-    print("--- BeaverDB Pub/Sub Demo ---")
-    asyncio.run(main())
-```
-
-## Roadmap
-
-`beaver` aims to be a complete, self-contained data toolkit for modern Python applications. The following features are planned for future releases, all accessible through a high-level API while still allowing direct SQL access:
-
-- **Vector Storage & Search:** Store numpy vector embeddings alongside your data and perform efficient k-nearest neighbor (k-NN) searches.
-- **Persistent Key-Value Store:** A simple get/set interface for storing configuration, session data, or any other JSON-serializable object.
-- **JSON Document Store with Full-Text Search:** Store flexible JSON documents and get powerful full-text search across all text fields by default, powered by SQLite's FTS5 extension.
-- **Standard Relational Interface:** While beaver provides high-level features, you will always be able to use the underlying SQLite connection for normal relational tasks, such as creating and managing users or products tables with standard SQL.
-
-## Performance
-
-Despite its local, embedded nature, `beaver` is highly performant by small use cases. Here are some metrics, measured on a single laptop, Intel Core i7, 7th generation.
-
-- Process 100,000 messages (1000 messages times 100 asynchronous clients) in less than 30 seconds, giving over 3K messages per second with an average latency of only 100 ms (time elapsed between message generation and client processing).
-
-## Why Beaver?
-
-Beavers are nature's engineers. They build a single, robust, and complex home—the lodge—from many different materials.
-
-Similarly, beaver builds a powerful, multi-modal database but contains it all within a single, self-contained file. It's an industrious, no-nonsense tool for building modern applications.
-
-## License
-
-This project is licensed under the MIT License.

beaver_db-0.1.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-beaver/__init__.py,sha256=pE1JdpHVni2Hv6igs5VrKPlHkkKMik3ZiwhR23KRBkk,38
-beaver/core.py,sha256=gWuuPwpT7yWgOulv_uwhOvJniltFO8K5-dfqjfA0jNk,5888
-beaver_db-0.1.0.dist-info/METADATA,sha256=b0gaV6IuXw2F_B4NOjKAP6Wj7dzHi7DjIYYg-0R_Q1Q,5243
-beaver_db-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-beaver_db-0.1.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
-beaver_db-0.1.0.dist-info/RECORD,,