beaver-db 0.6.2__tar.gz → 0.7.1__tar.gz

beaver_db-0.7.1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: beaver-db
+Version: 0.7.1
+Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: scipy>=1.16.2
+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.
+
+## 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.
+  - **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.
+  - **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
+
+Get up and running in 30 seconds. This example showcases a dictionary, a list, and full-text search in a single script.
+
+```python
+from beaver import BeaverDB, Document
+
+# 1. Initialize the database
+db = BeaverDB("data.db")
+
+# 2. Use a namespaced dictionary for app configuration
+config = db.dict("app_config")
+config["theme"] = "dark"
+print(f"Theme set to: {config['theme']}")
+
+# 3. Use a persistent list to manage a task queue
+tasks = db.list("daily_tasks")
+tasks.push("Write the project report")
+tasks.push("Deploy the new feature")
+print(f"First task is: {tasks[0]}")
+
+# 4. Use a collection for document storage and search
+articles = db.collection("articles")
+doc = Document(
+    id="sqlite-001",
+    content="SQLite is a powerful embedded database ideal for local apps."
+)
+articles.index(doc)
+
+# Perform a full-text search
+results = articles.match(query="database")
+top_doc, rank = results[0]
+print(f"FTS Result: '{top_doc.content}'")
+
+db.close()
+```
+
+## Things You Can Build with Beaver
+
+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
+
+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.
+
+```python
+users = db.dict("user_profiles")
+
+# Create a new user
+users["alice"] = {
+    "hashed_password": "...",
+    "email": "alice@example.com",
+    "permissions": ["read", "write"]
+}
+
+# Retrieve a user's profile
+alice_profile = users.get("alice")
+```
+
+### 2. 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.
+
+```python
+chat_history = db.list("conversation_with_user_123")
+
+chat_history.push({"role": "user", "content": "Hello, Beaver!"})
+chat_history.push({"role": "assistant", "content": "Hello! How can I help you today?"})
+
+# Retrieve the full conversation
+for message in chat_history:
+    print(f"{message['role']}: {message['content']}")
+```
+
+### 3. Build a RAG (Retrieval-Augmented Generation) System
+
+Combine **vector search** and **full-text search** to build a powerful RAG pipeline for your local documents.
+
+```python
+# Get context for a user query like "fast python web frameworks"
+vector_results = [doc for doc, _ in docs.search(vector=query_vector)]
+text_results = [doc for doc, _ in docs.match(query="python web framework")]
+
+# Combine and rerank for the best context
+from beaver.collections import rerank
+best_context = rerank(vector_results, text_results, weights=[0.6, 0.4])
+```
+
+### 4. 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.
+
+```python
+api_cache = db.dict("external_api_cache")
+
+# Check the cache first
+response = api_cache.get("weather_new_york")
+if response is None:
+    # If not in cache, make the real API call
+    response = make_slow_weather_api_call("New York")
+    # Cache the result for 1 hour
+    api_cache.set("weather_new_york", response, ttl_seconds=3600)
+```
+
+## More Examples
+
+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.
+
+## Roadmap
+
+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.
+
+Check out the [roadmap](https://www.google.com/search?q=roadmap.md) for a detailed list of upcoming features and design ideas.
+
+## License
+
+This project is licensed under the MIT License.

beaver_db-0.7.1/README.md

@@ -0,0 +1,168 @@
+# 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.
+
+## 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.
+  - **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.
+  - **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
+
+Get up and running in 30 seconds. This example showcases a dictionary, a list, and full-text search in a single script.
+
+```python
+from beaver import BeaverDB, Document
+
+# 1. Initialize the database
+db = BeaverDB("data.db")
+
+# 2. Use a namespaced dictionary for app configuration
+config = db.dict("app_config")
+config["theme"] = "dark"
+print(f"Theme set to: {config['theme']}")
+
+# 3. Use a persistent list to manage a task queue
+tasks = db.list("daily_tasks")
+tasks.push("Write the project report")
+tasks.push("Deploy the new feature")
+print(f"First task is: {tasks[0]}")
+
+# 4. Use a collection for document storage and search
+articles = db.collection("articles")
+doc = Document(
+    id="sqlite-001",
+    content="SQLite is a powerful embedded database ideal for local apps."
+)
+articles.index(doc)
+
+# Perform a full-text search
+results = articles.match(query="database")
+top_doc, rank = results[0]
+print(f"FTS Result: '{top_doc.content}'")
+
+db.close()
+```
+
+## Things You Can Build with Beaver
+
+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
+
+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.
+
+```python
+users = db.dict("user_profiles")
+
+# Create a new user
+users["alice"] = {
+    "hashed_password": "...",
+    "email": "alice@example.com",
+    "permissions": ["read", "write"]
+}
+
+# Retrieve a user's profile
+alice_profile = users.get("alice")
+```
+
+### 2. 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.
+
+```python
+chat_history = db.list("conversation_with_user_123")
+
+chat_history.push({"role": "user", "content": "Hello, Beaver!"})
+chat_history.push({"role": "assistant", "content": "Hello! How can I help you today?"})
+
+# Retrieve the full conversation
+for message in chat_history:
+    print(f"{message['role']}: {message['content']}")
+```
+
+### 3. Build a RAG (Retrieval-Augmented Generation) System
+
+Combine **vector search** and **full-text search** to build a powerful RAG pipeline for your local documents.
+
+```python
+# Get context for a user query like "fast python web frameworks"
+vector_results = [doc for doc, _ in docs.search(vector=query_vector)]
+text_results = [doc for doc, _ in docs.match(query="python web framework")]
+
+# Combine and rerank for the best context
+from beaver.collections import rerank
+best_context = rerank(vector_results, text_results, weights=[0.6, 0.4])
+```
+
+### 4. 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.
+
+```python
+api_cache = db.dict("external_api_cache")
+
+# Check the cache first
+response = api_cache.get("weather_new_york")
+if response is None:
+    # If not in cache, make the real API call
+    response = make_slow_weather_api_call("New York")
+    # Cache the result for 1 hour
+    api_cache.set("weather_new_york", response, ttl_seconds=3600)
+```
+
+## More Examples
+
+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.
+
+## Roadmap
+
+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.
+
+Check out the [roadmap](https://www.google.com/search?q=roadmap.md) for a detailed list of upcoming features and design ideas.
+
+## License
+
+This project is licensed under the MIT License.

beaver_db-0.6.2/beaver/subscribers.py → beaver_db-0.7.1/beaver/channels.py

@@ -4,7 +4,7 @@ import time
 from typing import Any, Iterator
 
 
-class SubWrapper(Iterator):
+class ChannelManager(Iterator):
     """
     A synchronous, blocking iterator that polls a channel for new messages.
     """
@@ -25,7 +25,7 @@ class SubWrapper(Iterator):
         self._poll_interval = poll_interval
         self._last_seen_timestamp = time.time()
 
-    def __iter__(self) -> "SubWrapper":
+    def __iter__(self) -> "ChannelManager":
         """Returns the iterator object itself."""
         return self
 

{beaver_db-0.6.2 → beaver_db-0.7.1}/beaver/collections.py

@@ -45,7 +45,7 @@ class Document:
         return f"Document(id='{self.id}', {metadata_str})"
 
 
-class CollectionWrapper:
+class CollectionManager:
     """
     A wrapper for multi-modal collection operations with an in-memory ANN index,
     FTS, and graph capabilities.
@@ -151,6 +151,24 @@ class CollectionWrapper:
                 (self._name,),
             )
 
+    def __iter__(self):
+        """Returns an iterator over all documents in the collection."""
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT item_id, item_vector, metadata FROM beaver_collections WHERE collection = ?",
+            (self._name,),
+        )
+        for row in cursor:
+            embedding = (
+                np.frombuffer(row["item_vector"], dtype=np.float32).tolist()
+                if row["item_vector"]
+                else None
+            )
+            yield Document(
+                id=row["item_id"], embedding=embedding, **json.loads(row["metadata"])
+            )
+        cursor.close()
+
     def refresh(self):
         """Forces a rebuild of the in-memory ANN index from data in SQLite."""
         cursor = self._conn.cursor()

{beaver_db-0.6.2 → beaver_db-0.7.1}/beaver/core.py

@@ -3,10 +3,10 @@ import sqlite3
 import time
 from typing import Any
 
-from .dicts import DictWrapper
-from .lists import ListWrapper
-from .subscribers import SubWrapper
-from .collections import CollectionWrapper
+from .dicts import DictManager
+from .lists import ListManager
+from .channels import ChannelManager
+from .collections import CollectionManager
 
 
 class BeaverDB:
@@ -152,21 +152,21 @@ class BeaverDB:
 
     # --- Factory and Passthrough Methods ---
 
-    def dict(self, name: str) -> DictWrapper:
+    def dict(self, name: str) -> DictManager:
         """Returns a wrapper object for interacting with a named dictionary."""
         if not isinstance(name, str) or not name:
             raise TypeError("Dictionary name must be a non-empty string.")
-        return DictWrapper(name, self._conn)
+        return DictManager(name, self._conn)
 
-    def list(self, name: str) -> ListWrapper:
+    def list(self, name: str) -> ListManager:
         """Returns a wrapper object for interacting with a named list."""
         if not isinstance(name, str) or not name:
             raise TypeError("List name must be a non-empty string.")
-        return ListWrapper(name, self._conn)
+        return ListManager(name, self._conn)
 
-    def collection(self, name: str) -> CollectionWrapper:
+    def collection(self, name: str) -> CollectionManager:
         """Returns a wrapper for interacting with a document collection."""
-        return CollectionWrapper(name, self._conn)
+        return CollectionManager(name, self._conn)
 
     def publish(self, channel_name: str, payload: Any):
         """Publishes a JSON-serializable message to a channel. This is synchronous."""
@@ -183,6 +183,6 @@ class BeaverDB:
                 (time.time(), channel_name, json_payload),
             )
 
-    def subscribe(self, channel_name: str) -> SubWrapper:
+    def subscribe(self, channel_name: str) -> ChannelManager:
         """Subscribes to a channel, returning a synchronous iterator."""
-        return SubWrapper(self._conn, channel_name)
+        return ChannelManager(self._conn, channel_name)

{beaver_db-0.6.2 → beaver_db-0.7.1}/beaver/dicts.py

@@ -3,7 +3,7 @@ import sqlite3
 import time # Add this import
 from typing import Any, Iterator, Tuple
 
-class DictWrapper:
+class DictManager:
     """A wrapper providing a Pythonic interface to a dictionary in the database."""
 
     def __init__(self, name: str, conn: sqlite3.Connection):

{beaver_db-0.6.2 → beaver_db-0.7.1}/beaver/lists.py

@@ -2,7 +2,7 @@ import json
 import sqlite3
 from typing import Any, Union, Iterator
 
-class ListWrapper:
+class ListManager:
     """A wrapper providing a Pythonic, full-featured interface to a list in the database."""
 
     def __init__(self, name: str, conn: sqlite3.Connection):

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

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: beaver-db
+Version: 0.7.1
+Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: scipy>=1.16.2
+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.
+
+## 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.
+  - **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.
+  - **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
+
+Get up and running in 30 seconds. This example showcases a dictionary, a list, and full-text search in a single script.
+
+```python
+from beaver import BeaverDB, Document
+
+# 1. Initialize the database
+db = BeaverDB("data.db")
+
+# 2. Use a namespaced dictionary for app configuration
+config = db.dict("app_config")
+config["theme"] = "dark"
+print(f"Theme set to: {config['theme']}")
+
+# 3. Use a persistent list to manage a task queue
+tasks = db.list("daily_tasks")
+tasks.push("Write the project report")
+tasks.push("Deploy the new feature")
+print(f"First task is: {tasks[0]}")
+
+# 4. Use a collection for document storage and search
+articles = db.collection("articles")
+doc = Document(
+    id="sqlite-001",
+    content="SQLite is a powerful embedded database ideal for local apps."
+)
+articles.index(doc)
+
+# Perform a full-text search
+results = articles.match(query="database")
+top_doc, rank = results[0]
+print(f"FTS Result: '{top_doc.content}'")
+
+db.close()
+```
+
+## Things You Can Build with Beaver
+
+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
+
+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.
+
+```python
+users = db.dict("user_profiles")
+
+# Create a new user
+users["alice"] = {
+    "hashed_password": "...",
+    "email": "alice@example.com",
+    "permissions": ["read", "write"]
+}
+
+# Retrieve a user's profile
+alice_profile = users.get("alice")
+```
+
+### 2. 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.
+
+```python
+chat_history = db.list("conversation_with_user_123")
+
+chat_history.push({"role": "user", "content": "Hello, Beaver!"})
+chat_history.push({"role": "assistant", "content": "Hello! How can I help you today?"})
+
+# Retrieve the full conversation
+for message in chat_history:
+    print(f"{message['role']}: {message['content']}")
+```
+
+### 3. Build a RAG (Retrieval-Augmented Generation) System
+
+Combine **vector search** and **full-text search** to build a powerful RAG pipeline for your local documents.
+
+```python
+# Get context for a user query like "fast python web frameworks"
+vector_results = [doc for doc, _ in docs.search(vector=query_vector)]
+text_results = [doc for doc, _ in docs.match(query="python web framework")]
+
+# Combine and rerank for the best context
+from beaver.collections import rerank
+best_context = rerank(vector_results, text_results, weights=[0.6, 0.4])
+```
+
+### 4. 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.
+
+```python
+api_cache = db.dict("external_api_cache")
+
+# Check the cache first
+response = api_cache.get("weather_new_york")
+if response is None:
+    # If not in cache, make the real API call
+    response = make_slow_weather_api_call("New York")
+    # Cache the result for 1 hour
+    api_cache.set("weather_new_york", response, ttl_seconds=3600)
+```
+
+## More Examples
+
+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.
+
+## Roadmap
+
+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.
+
+Check out the [roadmap](https://www.google.com/search?q=roadmap.md) for a detailed list of upcoming features and design ideas.
+
+## License
+
+This project is licensed under the MIT License.

{beaver_db-0.6.2 → beaver_db-0.7.1}/beaver_db.egg-info/SOURCES.txt

@@ -2,11 +2,11 @@ LICENSE
 README.md
 pyproject.toml
 beaver/__init__.py
+beaver/channels.py
 beaver/collections.py
 beaver/core.py
 beaver/dicts.py
 beaver/lists.py
-beaver/subscribers.py
 beaver_db.egg-info/PKG-INFO
 beaver_db.egg-info/SOURCES.txt
 beaver_db.egg-info/dependency_links.txt

{beaver_db-0.6.2 → beaver_db-0.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "beaver-db"
-version = "0.6.2"
+version = "0.7.1"
 description = "Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications."
 readme = "README.md"
 requires-python = ">=3.13"

beaver_db-0.6.2/PKG-INFO

@@ -1,185 +0,0 @@
-Metadata-Version: 2.4
-Name: beaver-db
-Version: 0.6.2
-Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy>=2.3.3
-Requires-Dist: scipy>=1.16.2
-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.
-
-## 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.
-  - **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, with all operations in constant time.
-  - **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")
-```
-
-### Namespaced Dictionaries
-
-Use `db.dict()` to get a dictionary-like object for a specific namespace. The value can be any JSON-encodable object.
-
-```python
-# Get a handle to the 'app_config' namespace
-config = db.dict("app_config")
-
-# Set values using standard dictionary syntax
-config["theme"] = "dark"
-config["user_id"] = 123
-
-# Get a value
-theme = config.get("theme")
-print(f"Theme: {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=3)
-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=3)
-top_doc, rank = text_results[0]
-print(f"Full-Text Search Result: {top_doc.content} (rank: {rank:.2f})")
-
-# 3. Combine both vector and text search for refined results
-from beaver.collections import rerank
-combined_results = rerank([d for d,_ in vector_results], [d for d,_ in text_results], weights=[2,1])
-```
-
-### 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.6.2/README.md

@@ -1,174 +0,0 @@
-# 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.
-
-## 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.
-  - **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, with all operations in constant time.
-  - **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")
-```
-
-### Namespaced Dictionaries
-
-Use `db.dict()` to get a dictionary-like object for a specific namespace. The value can be any JSON-encodable object.
-
-```python
-# Get a handle to the 'app_config' namespace
-config = db.dict("app_config")
-
-# Set values using standard dictionary syntax
-config["theme"] = "dark"
-config["user_id"] = 123
-
-# Get a value
-theme = config.get("theme")
-print(f"Theme: {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=3)
-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=3)
-top_doc, rank = text_results[0]
-print(f"Full-Text Search Result: {top_doc.content} (rank: {rank:.2f})")
-
-# 3. Combine both vector and text search for refined results
-from beaver.collections import rerank
-combined_results = rerank([d for d,_ in vector_results], [d for d,_ in text_results], weights=[2,1])
-```
-
-### 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.6.2/beaver_db.egg-info/PKG-INFO

@@ -1,185 +0,0 @@
-Metadata-Version: 2.4
-Name: beaver-db
-Version: 0.6.2
-Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy>=2.3.3
-Requires-Dist: scipy>=1.16.2
-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.
-
-## 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.
-  - **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, with all operations in constant time.
-  - **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")
-```
-
-### Namespaced Dictionaries
-
-Use `db.dict()` to get a dictionary-like object for a specific namespace. The value can be any JSON-encodable object.
-
-```python
-# Get a handle to the 'app_config' namespace
-config = db.dict("app_config")
-
-# Set values using standard dictionary syntax
-config["theme"] = "dark"
-config["user_id"] = 123
-
-# Get a value
-theme = config.get("theme")
-print(f"Theme: {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=3)
-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=3)
-top_doc, rank = text_results[0]
-print(f"Full-Text Search Result: {top_doc.content} (rank: {rank:.2f})")
-
-# 3. Combine both vector and text search for refined results
-from beaver.collections import rerank
-combined_results = rerank([d for d,_ in vector_results], [d for d,_ in text_results], weights=[2,1])
-```
-
-### 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.