beaver-db 0.2.0__tar.gz → 0.3.0__tar.gz

beaver_db-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,121 @@
+# 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/beaver/__init__.py

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

{beaver_db-0.2.0 → beaver_db-0.3.0}/beaver/core.py

@@ -1,4 +1,6 @@
 import asyncio
+import uuid
+import numpy as np
 import json
 import sqlite3
 import time
@@ -26,6 +28,7 @@ class BeaverDB:
         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."""
@@ -64,6 +67,19 @@ class BeaverDB:
                 )
             """)
 
+    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:
@@ -139,6 +155,10 @@ class BeaverDB:
             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):
@@ -385,3 +405,88 @@ class Subscriber(AsyncIterator):
     async def __anext__(self) -> Any:
         """Allows 'async for' to pull messages from the internal queue."""
         return await self._queue.get()
+
+
+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.")
+
+        self.id = id or str(uuid.uuid4())
+        self.embedding = np.array(embedding, dtype=np.float32)
+
+        for key, value in metadata.items():
+            setattr(self, key, value)
+
+    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
+
+    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):
+        """
+        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:
+            document: The Document object to index.
+        """
+        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())
+                )
+            )
+
+    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)
+
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT item_id, item_vector, metadata FROM beaver_collections WHERE collection = ?",
+            (self._name,)
+        )
+
+        all_docs_data = cursor.fetchall()
+        cursor.close()
+
+        if not all_docs_data:
+            return []
+
+        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'])
+
+            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/beaver_db.egg-info/PKG-INFO

@@ -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.2.0 → beaver_db-0.3.0}/beaver_db.egg-info/SOURCES.txt

@@ -5,4 +5,5 @@ beaver/core.py
 beaver_db.egg-info/PKG-INFO
 beaver_db.egg-info/SOURCES.txt
 beaver_db.egg-info/dependency_links.txt
+beaver_db.egg-info/requires.txt
 beaver_db.egg-info/top_level.txt

beaver_db-0.3.0/beaver_db.egg-info/requires.txt

@@ -0,0 +1 @@
+numpy>=2.3.3

{beaver_db-0.2.0 → beaver_db-0.3.0}/pyproject.toml

@@ -1,10 +1,12 @@
 [project]
 name = "beaver-db"
-version = "0.2.0"
+version = "0.3.0"
 description = "Asynchronous, embedded, modern DB based on SQLite."
 readme = "README.md"
 requires-python = ">=3.13"
-dependencies = []
+dependencies = [
+    "numpy>=2.3.3",
+]
 
 [tool.hatch.build.targets.wheel]
 packages = ["beaver"]

beaver_db-0.2.0/PKG-INFO

@@ -1,109 +0,0 @@
-Metadata-Version: 2.4
-Name: beaver-db
-Version: 0.2.0
-Summary: Asynchronous, embedded, modern DB based on SQLite.
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-
-# beaver 🦫
-
-A fast, single-file, multi-modal database for Python, built with the standard sqlite3 library.
-
-`beaver` is the Backend for Embedded Asynchronous Vector & Event 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). No external packages are required, making it incredibly lightweight and portable.
-- **Async-First (When It Matters)**: The pub/sub system is fully asynchronous for high-performance, real-time messaging. Simpler features like key-value and list operations remain synchronous for ease of use.
-- **Built for Local Applications**: Perfect for local AI tools, chatbots (streaming tokens), task management apps, desktop utilities, and prototypes that need persistent, structured data without network overhead.
-- **Fast by Default**: It's built on SQLite, which is famously fast, reliable, and will likely serve your needs for a long way before you need a "professional" database.
-
-## 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 configuration, session data, or any other JSON-serializable object.
-- **Pythonic List Management**: A fluent, Redis-like interface (db.list("name").push()) for managing persistent, ordered lists with support for indexing and slicing.
-- **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
-
-### 1. Initialization
-
-All you need to do is import and instantiate the BeaverDB class with a file path.
-
-```python
-from beaver import BeaverDB
-
-db = BeaverDB("my_application.db")
-```
-
-### 2. 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
-```
-
-### 3. List Management
-
-Get a list wrapper with `db.list()` and use Pythonic methods to manage it.
-
-```python
-# Get a wrapper for the 'tasks' list
-tasks = db.list("daily_tasks")
-
-# Push items to the list
-tasks.push("Write the project report")
-tasks.push("Send follow-up emails")
-tasks.prepend("Plan the day's agenda") # Push to the front
-
-# Use len() and indexing (including slices!)
-print(f"There are {len(tasks)} tasks.")
-print(f"The first task is: {tasks[0]}")
-print(f"The rest is: {tasks[1:]}")
-```
-
-### 4. 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:
-
-- **Vector Storage & Search**: Store NumPy vector embeddings and perform efficient k-nearest neighbor (k-NN) searches using `scipy.spatial.cKDTree`.
-- **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 (e.g., managing users, products) with standard SQL.
-
-## License
-
-This project is licensed under the MIT License.

beaver_db-0.2.0/README.md

@@ -1,102 +0,0 @@
-# beaver 🦫
-
-A fast, single-file, multi-modal database for Python, built with the standard sqlite3 library.
-
-`beaver` is the Backend for Embedded Asynchronous Vector & Event 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). No external packages are required, making it incredibly lightweight and portable.
-- **Async-First (When It Matters)**: The pub/sub system is fully asynchronous for high-performance, real-time messaging. Simpler features like key-value and list operations remain synchronous for ease of use.
-- **Built for Local Applications**: Perfect for local AI tools, chatbots (streaming tokens), task management apps, desktop utilities, and prototypes that need persistent, structured data without network overhead.
-- **Fast by Default**: It's built on SQLite, which is famously fast, reliable, and will likely serve your needs for a long way before you need a "professional" database.
-
-## 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 configuration, session data, or any other JSON-serializable object.
-- **Pythonic List Management**: A fluent, Redis-like interface (db.list("name").push()) for managing persistent, ordered lists with support for indexing and slicing.
-- **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
-
-### 1. Initialization
-
-All you need to do is import and instantiate the BeaverDB class with a file path.
-
-```python
-from beaver import BeaverDB
-
-db = BeaverDB("my_application.db")
-```
-
-### 2. 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
-```
-
-### 3. List Management
-
-Get a list wrapper with `db.list()` and use Pythonic methods to manage it.
-
-```python
-# Get a wrapper for the 'tasks' list
-tasks = db.list("daily_tasks")
-
-# Push items to the list
-tasks.push("Write the project report")
-tasks.push("Send follow-up emails")
-tasks.prepend("Plan the day's agenda") # Push to the front
-
-# Use len() and indexing (including slices!)
-print(f"There are {len(tasks)} tasks.")
-print(f"The first task is: {tasks[0]}")
-print(f"The rest is: {tasks[1:]}")
-```
-
-### 4. 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:
-
-- **Vector Storage & Search**: Store NumPy vector embeddings and perform efficient k-nearest neighbor (k-NN) searches using `scipy.spatial.cKDTree`.
-- **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 (e.g., managing users, products) with standard SQL.
-
-## License
-
-This project is licensed under the MIT License.

beaver_db-0.2.0/beaver/__init__.py

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

beaver_db-0.2.0/beaver_db.egg-info/PKG-INFO

@@ -1,109 +0,0 @@
-Metadata-Version: 2.4
-Name: beaver-db
-Version: 0.2.0
-Summary: Asynchronous, embedded, modern DB based on SQLite.
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-
-# beaver 🦫
-
-A fast, single-file, multi-modal database for Python, built with the standard sqlite3 library.
-
-`beaver` is the Backend for Embedded Asynchronous Vector & Event 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). No external packages are required, making it incredibly lightweight and portable.
-- **Async-First (When It Matters)**: The pub/sub system is fully asynchronous for high-performance, real-time messaging. Simpler features like key-value and list operations remain synchronous for ease of use.
-- **Built for Local Applications**: Perfect for local AI tools, chatbots (streaming tokens), task management apps, desktop utilities, and prototypes that need persistent, structured data without network overhead.
-- **Fast by Default**: It's built on SQLite, which is famously fast, reliable, and will likely serve your needs for a long way before you need a "professional" database.
-
-## 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 configuration, session data, or any other JSON-serializable object.
-- **Pythonic List Management**: A fluent, Redis-like interface (db.list("name").push()) for managing persistent, ordered lists with support for indexing and slicing.
-- **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
-
-### 1. Initialization
-
-All you need to do is import and instantiate the BeaverDB class with a file path.
-
-```python
-from beaver import BeaverDB
-
-db = BeaverDB("my_application.db")
-```
-
-### 2. 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
-```
-
-### 3. List Management
-
-Get a list wrapper with `db.list()` and use Pythonic methods to manage it.
-
-```python
-# Get a wrapper for the 'tasks' list
-tasks = db.list("daily_tasks")
-
-# Push items to the list
-tasks.push("Write the project report")
-tasks.push("Send follow-up emails")
-tasks.prepend("Plan the day's agenda") # Push to the front
-
-# Use len() and indexing (including slices!)
-print(f"There are {len(tasks)} tasks.")
-print(f"The first task is: {tasks[0]}")
-print(f"The rest is: {tasks[1:]}")
-```
-
-### 4. 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:
-
-- **Vector Storage & Search**: Store NumPy vector embeddings and perform efficient k-nearest neighbor (k-NN) searches using `scipy.spatial.cKDTree`.
-- **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 (e.g., managing users, products) with standard SQL.
-
-## License
-
-This project is licensed under the MIT License.