beaver-db 0.16.5__tar.gz → 0.16.7__tar.gz

beaver_db-0.16.7/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+*.db*
+.env

beaver_db-0.16.7/.python-version

@@ -0,0 +1 @@
+3.13

{beaver_db-0.16.5 → beaver_db-0.16.7}/PKG-INFO

@@ -1,18 +1,17 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.16.5
+Version: 0.16.7
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
-Classifier: Programming Language :: Python :: 3.13
+License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-License-File: LICENSE
 Provides-Extra: faiss
-Requires-Dist: faiss-cpu>=1.12.0; extra == "faiss"
-Dynamic: license-file
+Requires-Dist: faiss-cpu>=1.12.0; extra == 'faiss'
+Description-Content-Type: text/markdown
 
 # beaver 🦫
 
@@ -27,15 +26,17 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 
 `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.
 
+> If you like beaver's minimalist, no-bullshit philosophy, check out [castor](https://github.com/apiad/castor) for an equally minimalistic approach to task orchestration.
+
 ## Design Philosophy
 
 `beaver` is built with a minimalistic philosophy for small, local use cases where a full-blown database server would be overkill.
 
-- **Minimalistic**: Uses only Python's standard libraries (`sqlite3`) and `numpy`/`faiss-cpu`.
+- **Minimalistic**: The core library has zero external dependencies. Vector search capabilities, which require `numpy` and `faiss-cpu`, are available as an optional feature.
 - **Schemaless**: Flexible data storage without rigid schemas across all modalities.
 - **Synchronous, Multi-Process, and Thread-Safe**: Designed for simplicity and safety in multi-threaded and multi-process 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. Vector search is accelerated with a high-performance, persistent `faiss` index.
+- **Fast by Default**: It's built on SQLite, which is famously fast and reliable for local applications. Vector search is an optional feature accelerated with a high-performance, persistent `faiss` index.
 - **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
@@ -46,7 +47,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 - **Persistent Priority Queue**: A high-performance, persistent priority queue perfect for task orchestration across multiple processes. Also with optional async support.
 - **Time-Indexed Log for Monitoring**: A specialized data structure for structured, time-series logs. Query historical data by time range or create a live, aggregated view of the most recent events for real-time dashboards.
 - **Simple Blob Storage**: A dictionary-like interface for storing medium-sized binary files (like PDFs or images) directly in the database, ensuring transactional integrity with your other data.
-- **High-Performance Vector Storage & Search**: Store vector embeddings and perform fast, crash-safe approximate nearest neighbor searches using a `faiss`-based hybrid index.
+- **High-Performance Vector Storage & Search (Optional)**: Store vector embeddings and perform fast approximate nearest neighbor searches using a `faiss`-based hybrid index.
 - **Full-Text and Fuzzy Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine, enhanced with optional fuzzy search for typo-tolerant matching.
 - **Knowledge Graph**: 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.
@@ -71,10 +72,18 @@ This hybrid approach allows BeaverDB to provide a vector search experience that
 
 ## Installation
 
+Install the core, dependency-free library:
+
 ```bash
 pip install beaver-db
 ```
 
+If you want vector search capabilities, install the `faiss` extra:
+
+```bash
+pip install "beaver-db[faiss]"
+```
+
 ## Quickstart
 
 Get up and running in 30 seconds. This example showcases a dictionary, a list, and full-text search in a single script.

{beaver_db-0.16.5 → beaver_db-0.16.7}/README.md

@@ -11,15 +11,17 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 
 `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.
 
+> If you like beaver's minimalist, no-bullshit philosophy, check out [castor](https://github.com/apiad/castor) for an equally minimalistic approach to task orchestration.
+
 ## Design Philosophy
 
 `beaver` is built with a minimalistic philosophy for small, local use cases where a full-blown database server would be overkill.
 
-- **Minimalistic**: Uses only Python's standard libraries (`sqlite3`) and `numpy`/`faiss-cpu`.
+- **Minimalistic**: The core library has zero external dependencies. Vector search capabilities, which require `numpy` and `faiss-cpu`, are available as an optional feature.
 - **Schemaless**: Flexible data storage without rigid schemas across all modalities.
 - **Synchronous, Multi-Process, and Thread-Safe**: Designed for simplicity and safety in multi-threaded and multi-process 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. Vector search is accelerated with a high-performance, persistent `faiss` index.
+- **Fast by Default**: It's built on SQLite, which is famously fast and reliable for local applications. Vector search is an optional feature accelerated with a high-performance, persistent `faiss` index.
 - **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
@@ -30,7 +32,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 - **Persistent Priority Queue**: A high-performance, persistent priority queue perfect for task orchestration across multiple processes. Also with optional async support.
 - **Time-Indexed Log for Monitoring**: A specialized data structure for structured, time-series logs. Query historical data by time range or create a live, aggregated view of the most recent events for real-time dashboards.
 - **Simple Blob Storage**: A dictionary-like interface for storing medium-sized binary files (like PDFs or images) directly in the database, ensuring transactional integrity with your other data.
-- **High-Performance Vector Storage & Search**: Store vector embeddings and perform fast, crash-safe approximate nearest neighbor searches using a `faiss`-based hybrid index.
+- **High-Performance Vector Storage & Search (Optional)**: Store vector embeddings and perform fast approximate nearest neighbor searches using a `faiss`-based hybrid index.
 - **Full-Text and Fuzzy Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine, enhanced with optional fuzzy search for typo-tolerant matching.
 - **Knowledge Graph**: 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.
@@ -55,10 +57,18 @@ This hybrid approach allows BeaverDB to provide a vector search experience that
 
 ## Installation
 
+Install the core, dependency-free library:
+
 ```bash
 pip install beaver-db
 ```
 
+If you want vector search capabilities, install the `faiss` extra:
+
+```bash
+pip install "beaver-db[faiss]"
+```
+
 ## Quickstart
 
 Get up and running in 30 seconds. This example showcases a dictionary, a list, and full-text search in a single script.

{beaver_db-0.16.5 → beaver_db-0.16.7}/beaver/channels.py

@@ -190,6 +190,16 @@ class ChannelManager[T]:
 
         self._listeners.clear()
 
+    def prune(self):
+        """
+        Cleans the log history for the channel effectively
+        deleting all previous logs.
+
+        Useful for reducing the database once logs are not needed.
+        """
+        with self._conn:
+            self._conn.execute("DELETE FROM beaver_pubsub_log WHERE channel_name = ?", (self._name,))
+
     def _polling_loop(self):
         """
         The main loop for the background thread.

{beaver_db-0.16.5 → beaver_db-0.16.7}/beaver/queues.py

@@ -25,6 +25,12 @@ class AsyncQueueManager[T]:
         """Asynchronously adds an item to the queue with a specific priority."""
         await asyncio.to_thread(self._queue.put, data, priority)
 
+    async def peek(self) -> QueueItem[T] | None:
+        """
+        Asynchronously returns the first item without removing it, if any, otherwise returns None.
+        """
+        return await asyncio.to_thread(self._queue.peek)
+
     @overload
     async def get(self, block: Literal[True] = True, timeout: float | None = None) -> QueueItem[T]: ...
     @overload
@@ -77,7 +83,7 @@ class QueueManager[T]:
                 (self._name, priority, time.time(), self._serialize(data)),
             )
 
-    def _get_item_atomically(self) -> QueueItem[T] | None:
+    def _get_item_atomically(self, pop:bool=True) -> QueueItem[T] | None:
         """
         Performs a single, atomic attempt to retrieve and remove the
         highest-priority item from the queue. Returns None if the queue is empty.
@@ -100,12 +106,21 @@ class QueueManager[T]:
                 return None
 
             rowid, priority, timestamp, data = result
-            cursor.execute("DELETE FROM beaver_priority_queues WHERE rowid = ?", (rowid,))
+
+            if pop:
+                cursor.execute("DELETE FROM beaver_priority_queues WHERE rowid = ?", (rowid,))
 
             return QueueItem(
                 priority=priority, timestamp=timestamp, data=self._deserialize(data)
             )
 
+    def peek(self) -> QueueItem[T] | None:
+        """
+        Retrieves the first item of the queue.
+        If the queue is empy, returns None.
+        """
+        return self._get_item_atomically(pop=False)
+
     @overload
     def get(self, block: Literal[True] = True, timeout: float | None = None) -> QueueItem[T]: ...
     @overload

beaver_db-0.16.7/design.md

@@ -0,0 +1,118 @@
+# BeaverDB Design Document
+
+Version: 1.1
+Status: In Progress
+Last Updated: September 18, 2025
+
+## 1. Introduction & Vision
+
+`beaver-db` is a local-first, embedded, multi-modal database for Python. Its primary motivation is to provide a simple, single-file solution for modern applications that need to handle complex data types like vectors, documents, and graphs without the overhead of a database server.
+
+The vision for `beaver-db` is to be the go-to "good enough" database for prototypes, desktop utilities, and small-scale applications. It empowers developers to start quickly with a simple API but provides sufficient power and performance so that they do not need to immediately upgrade to a more complex database system as their application's features grow.
+
+## 2. Guiding Principles
+
+These principleembeddings guide all development and design decisions for beaver-db.
+
+* **Local-First & Embedded:** The database will always be a single SQLite file. This is the non-negotiable source of truth. Temporary files for journaling or syncing are acceptable, but the core architecture is serverless. Any feature that requires a client-server model is out of scope.
+* **Standard SQLite Compatibility:** The .db file generated by beaver-db must always be a valid SQLite file that can be opened and queried by any standard SQLite tool. This ensures data portability and interoperability.
+* **Minimal & Cross-Platform Dependencies:** New dependencies beyond numpy and scipy will only be considered if they provide a monumental performance improvement and are fully cross-platform, with a guarantee of easy installation for all users. The core library should strive to use Python's standard library wherever possible.
+* **Simplicity and Pythonic API:** The library must present a simple, intuitive, and "Pythonic" interface. We will always prefer simple function calls with clear parameters over custom Domain Specific Languages (DSLs) or expression parsing. The user should not have to learn a new query language.
+* **Developer Experience & Minimal API Surface:** The primary user experience goal is to provide a clean and minimal public API.
+  * **User-facing Classes:** The user should only ever need to instantiate BeaverDB and Document directly.
+  * **Fluent Interface:** All other functionalities (like list or collection operations) are exposed through methods on the BeaverDB object (e.g., `db.list("my_list")`, `db.collection("my_docs")`). These methods return internal wrapper objects (`ListWrapper`, `CollectionWrapper`) that provide a rich, fluent interface, preventing the need for the user to learn and manage a large number of classes.
+  * **API Design:** Public functions will have short, descriptive names and well-documented parameters, adhering to Python's conventions.
+* **Synchronousembedding Core with Async Potential:** The core library is built on a synchronous foundation, reflecting the synchronous nature of the underlying `sqlite3` driver. This ensures thread safety and simplicity. An async-compatible API may be introduced in the future, but it will likely be a wrapper around the synchronous core (e.g., using a thread pool).
+* **Convention over Configuration:** Features should work well out-of-the-box with sensible defaults. While configuration options can be provided, the user should not be required to tweak many parameters to get good performance and functionality.
+
+## 3. Architecture & Core Components
+
+`beaver-db` is architected as a set of targeted wrappers around a standard SQLite database, with an in-memory component for performance-critical tasks like vector search.
+
+### 3.1. Core Engine (BeaverDB)
+
+* **Connection Management:** The BeaverDB class manages a single connection to the SQLite database file.
+* **Concurrency:** It enables `PRAGMA journal_mode=WAL;` (Write-Ahead Logging) by default. This provides a good level of concurrency between one writer and multiple readers, which is a common pattern for the target applications.
+* **Schema Management:** All tables created and managed by the library are prefixed with `beaver_` (or `_beaver_` for internal helpers). This avoids conflicts with user-defined tables within the same database file. The schema is evolved by adding new `beaver_*` tables as new features are introduced.
+
+### 3.2. Data Models & Features
+
+### Key-Value Dictionaries (DictWrapper)
+
+* **Implementation**: A single table (`beaver_dicts`) stores key-value pairs partitioned by a `dict_name` (TEXT). The primary key is a composite of `(dict_name, key)`.
+* **Design**: The `db.dict("namespace")` method returns a `DictWrapper` that provides a complete and standard Pythonic dictionary-like interface. This includes subscripting (`__getitem__`, `__setitem__`), explicit `get()`/`set()` methods, and iterators (`keys()`, `values()`, `items()`). This feature is ideal for managing structured configurations or namespaced key-value data while adhering to the principle of a Simple and Pythonic API.
+
+#### Lists (ListWrapper)
+
+* **Implementation:** A table (`beaver_lists`) storing list_name, item_order (REAL), and item_value (TEXT).
+* **Design:** The item_order is a floating-point number. This allows for O(1) insertions in the middle of the list by calculating the midpoint between two existing order values. This avoids re-indexing all subsequent items. The ListWrapper provides a rich, Pythonic API (`_len_`, `_getitem_`, `push`, `pop`, etc.).
+
+#### Pub/Sub System
+
+* **Implementation:** A log table (`beaver_pubsub_log`) that stores messages with a timestamp, channel name, and payload.
+* **Design:** The current SubWrapper is a synchronous iterator that polls the table for new messages since the last seen timestamp. This design is simple and robust. A more performant, event-driven mechanism could be explored in the future, but only if it does not violate the principles of simplicity and minimal dependencies.
+
+#### Collections (CollectionWrapper)
+
+This is the most complex component, supporting documents, vectors, text, and graphs.
+
+* **Document Storage:** Documents are stored in the beaver_collections table. Each document has a collection, item_id, optional item_vector (BLOB), and metadata (TEXT, as JSON). The Document class is a flexible container with no enforced schema.
+* **Vector Search (ANN):**
+  * **Indexing:** Vector embeddings are stored as raw bytes (BLOBs) in the beaver_collections table.
+  * **Search Algorithm:** For performance, an in-memory k-d tree (`scipy.spatial.cKDTree`) is used for Approximate Nearest Neighbor (ANN) search.
+  * **Stale Index Handling:** The database maintains a version number for each collection in beaver_collection_versions. This version is incremented on every index or drop operation. The CollectionWrapper caches the version of its in-memory index and automatically triggers a `refresh()` if it detects its version is older than the database version.
+  * **Design Trade-offs:** This in-memory approach is extremely fast for datasets that fit in RAM. The library will not have hard-coded scalability limits, but performance testing will establish practical boundaries which will be published in the documentation.
+* **Full-Text Search (FTS):**
+  * **Implementation:** Uses a virtual table (`beaver_fts_index`) powered by SQLite's FTS5 extension.
+  * **Indexing:** When a Document is indexed, its metadata is flattened into key-value pairs (e.g., author.name becomes author_name). All string values are automatically inserted into the FTS index.
+  * **Querying:** The `match()` method provides a simple interface for searching. It supports FTS5 syntax (like "OR", "AND") passed directly in the query string. The goal is to provide powerful search out-of-the-box without requiring complex configuration.
+* **Graph Engine:**
+  * **Implementation:** Relationships are stored as directed edges in the beaver_edges table, linking a source_item_id to a target_item_id with a label.
+  * **Design:** The API is purely functional and Pythonic. It does not use a custom graph query language.
+    * `connect()`: Creates a directed edge.
+    * `neighbors()`: Retrieves immediate (1-hop) neighbors.
+    * `walk()`: Uses a recursive Common Table Expression (CTE) in SQL to perform efficient multi-hop graph traversals (BFS). This is powerful yet keeps the implementation clean and contained within SQL.
+
+### 3.3. Reliability and Data Handling
+
+* **Atomicity and Transactions:** Correctness is paramount. Any public method that performs multiple database modifications (e.g., collection.index, which writes to the documents, FTS, and version tables) **must** be wrapped in a single, atomic database transaction. If any step of the operation fails, the entire transaction will be rolled back, ensuring the database is never left in an inconsistent state.
+* **Error Handling:** The library will use standard Python exceptions whenever possible (e.g., TypeError, ValueError, sqlite3.Error). Custom exceptions will be avoided to ensure the API feels native and predictable to Python developers.
+* **Data Serialization:**
+  * The default serialization format is JSON.
+  * The library will provide built-in, standardized converters for common Python types not native to JSON, such as `datetime` (to ISO 8601 strings) and `bytes` (to a standard encoding like base64).
+  * For custom user-defined objects, it is the user's responsibility to serialize them into a JSON-compatible format (e.g., a string or a dictionary) before storing them.
+
+## 4. Roadmap & Future Development
+
+### 4.1. Immediate Priorities
+
+The primary focus for the near future is on stability and usability.
+
+1. **Comprehensive Unit Testing:** Increase test coverage to ensure all features are robust and reliable.
+2. **Elaborate Examples:** Create more examples that demonstrate how to combine features (e.g., a hybrid search that uses FTS, graph traversal, and vector search together).
+3. **Performance Benchmarking:** Develop a standardized suite of performance tests to track regressions and identify optimization opportunities. The results will be used to document the practical scalability limits of the library for various use cases.
+
+### 4.2. Long-Term Vision
+
+The library is approaching feature-completeness for its core domain. The long-term vision is to make it a stable, trusted, and well-documented tool for its niche.
+
+* **Stability:** The API will soon be stabilized, with a commitment to backward compatibility as defined in the versioning policy.
+* **New Modalities:** In the distant future, other data modalities could be considered if they fit the embedded, single-file philosophy.
+
+### 4.3. Explicitly Out of Scope
+
+To maintain focus and simplicity, the following features will **not** be implemented:
+
+* Client-server architecture.
+* Replication or distributed operation.
+* Multi-file database formats.
+* Any feature that makes the database file incompatible with standard SQLite tools.
+* Custom query languages or DSLs.
+
+### 4.4. Versioning and Backward Compatibility
+
+The project will adhere to **Semantic Versioning (Major.Minor.Patch)**.
+
+* **Patch Releases (x.y.Z):** For bug fixes and non-breaking changes. No API or schema changes are permitted.
+* **Minor Releases (x.Y.z):** For adding new, backward-compatible features. Schema additions (e.g., new `beaver_*` tables) are allowed, but schema modifications that break older code are not. Code written for version x.z will be able to open and read a database file from version x.y where z > y.
+* **Major Releases (X.y.z):** For introducing breaking changes to the API or the database schema. There is no guarantee of backward compatibility between major versions, and a migration path will not be provided automatically.

beaver_db-0.16.7/examples/async_pubsub.py

@@ -0,0 +1,48 @@
+import asyncio
+from beaver import BeaverDB
+
+async def listener_task(name: str, db: BeaverDB):
+    """An async task that listens for messages on a channel."""
+    print(f"[{name}] Starting and subscribing to 'async_events'.")
+    async_channel = db.channel("async_events").as_async()
+
+    async with async_channel.subscribe() as listener:
+        async for message in listener.listen():
+            print(f"[{name}] Received -> {message}")
+
+async def publisher_task(db: BeaverDB):
+    """An async task that publishes several messages."""
+    print("[Publisher] Starting.")
+    async_channel = db.channel("async_events").as_async()
+
+    await asyncio.sleep(1)
+    print("[Publisher] Publishing message 1: User Login")
+    await async_channel.publish({"event": "user_login", "user": "alice"})
+
+    await asyncio.sleep(0.5)
+    print("[Publisher] Publishing message 2: System Alert")
+    await async_channel.publish({"event": "alert", "level": "high"})
+
+    print("[Publisher] Finished publishing.")
+
+async def main():
+    """Sets up and runs the concurrent async publisher and listeners."""
+    db = BeaverDB("async_demo.db")
+
+    # Create and run the listener and publisher tasks concurrently
+    listener_a = asyncio.create_task(listener_task("Listener-A", db))
+    listener_b = asyncio.create_task(listener_task("Listener-B", db))
+    publisher = asyncio.create_task(publisher_task(db))
+
+    await publisher
+    await asyncio.sleep(2) # Wait for messages to be processed
+
+    # In a real app, you might cancel the listeners or have a shutdown event
+    listener_a.cancel()
+    listener_b.cancel()
+    db.close()
+
+if __name__ == "__main__":
+    print("--- BeaverDB Async Pub/Sub Demo ---")
+    asyncio.run(main())
+    print("\nDemo finished successfully.")

beaver_db-0.16.7/examples/blobs.py

@@ -0,0 +1,51 @@
+from beaver import BeaverDB
+
+
+def blob_store_demo():
+    """Demonstrates the basic functionality of the blob store."""
+    print("--- Running Blob Store Demo ---")
+    db = BeaverDB("demo.db")
+
+    # 1. Get a handle to a named blob store
+    attachments = db.blobs("email_attachments")
+
+    # 2. Create some sample binary data
+    file_content = "This is the content of a virtual text file."
+    file_bytes = file_content.encode("utf-8")
+    file_key = "emails/user123/attachment_01.txt"
+
+    # 3. Store the blob with some metadata
+    print(f"Storing blob with key: '{file_key}'")
+    attachments.put(
+        key=file_key,
+        data=file_bytes,
+        metadata={"mimetype": "text/plain", "sender": "alice@example.com"},
+    )
+
+    # 4. Check for the blob's existence
+    if file_key in attachments:
+        print(f"Verified that key '{file_key}' exists in the store.")
+
+    # 5. Retrieve the blob
+    blob = attachments.get(file_key)
+    if blob:
+        print("\n--- Retrieved Blob ---")
+        print(f"  Key: {blob.key}")
+        print(f"  Metadata: {blob.metadata}")
+        print(f"  Data (decoded): '{blob.data.decode('utf-8')}'")
+        assert blob.data == file_bytes
+
+    # 6. Delete the blob
+    print("\nDeleting blob...")
+    attachments.delete(file_key)
+
+    # 7. Verify deletion
+    if file_key not in attachments:
+        print(f"Verified that key '{file_key}' has been deleted.")
+
+    db.close()
+    print("\n--- Demo Finished Successfully ---")
+
+
+if __name__ == "__main__":
+    blob_store_demo()

beaver_db-0.16.7/examples/cache.py

@@ -0,0 +1,64 @@
+import time
+from beaver import BeaverDB
+
+def expensive_api_call(prompt: str):
+    """A mock function that simulates a slow API call."""
+    print(f"--- Making expensive API call for: '{prompt}' ---")
+    time.sleep(2) # Simulate network latency
+    if prompt == "capital of Ecuador":
+        return "Quito"
+    return "Data not found"
+
+def cache_demo():
+    """Demonstrates using a namespaced dictionary as a persistent cache with TTL."""
+    print("--- Running Cache Demo ---")
+    db = BeaverDB("demo.db")
+
+    # Use a dictionary as a cache. Items will expire after 10 seconds.
+    api_cache = db.dict("api_cache")
+
+    prompt = "capital of Ecuador"
+
+    # --- 1. First Call (Cache Miss) ---
+    print("\nAttempt 1: Key is not in cache.")
+    response = api_cache.get(prompt)
+    if response is None:
+        print("Cache miss.")
+        response = expensive_api_call(prompt)
+        # Set the value in the cache with a 10-second TTL
+        api_cache.set(prompt, response, ttl_seconds=10)
+
+    print(f"Response: {response}")
+
+    # --- 2. Second Call (Cache Hit) ---
+    print("\nAttempt 2: Making the same request within 5 seconds.")
+    time.sleep(5)
+    response = api_cache.get(prompt)
+    if response is None:
+        print("Cache miss.")
+        response = expensive_api_call(prompt)
+        api_cache.set(prompt, response, ttl_seconds=10)
+    else:
+        print("Cache hit!")
+
+    print(f"Response: {response}")
+
+    # --- 3. Third Call (Cache Expired) ---
+    print("\nAttempt 3: Waiting for 12 seconds for the cache to expire.")
+    time.sleep(12)
+    response = api_cache.get(prompt)
+    if response is None:
+        print("Cache miss (key expired).")
+        response = expensive_api_call(prompt)
+        api_cache.set(prompt, response, ttl_seconds=10)
+    else:
+        print("Cache hit!")
+
+    print(f"Response: {response}")
+
+    db.close()
+    print("\n--- Demo Finished ---")
+
+
+if __name__ == "__main__":
+    cache_demo()

beaver_db-0.16.7/examples/fts.py

@@ -0,0 +1,92 @@
+from beaver import BeaverDB, Document
+
+def full_text_search_demo():
+    """
+    Demonstrates the full-text search (FTS) functionality in BeaverDB.
+    """
+    print("--- Running Full-Text Search Demo ---")
+
+    # We use a separate database file for this demo
+    db = BeaverDB("demo.db")
+    articles = db.collection("tech_articles")
+
+    # --- 1. Create and Index Documents with Nested Metadata ---
+
+    # By calling articles.index(), the text fields will be automatically indexed for FTS.
+    print("Indexing documents...")
+
+    doc1 = Document(
+        id="py-001",
+        content="Python is a versatile programming language. Its use in data science is notable.",
+        author={
+            "name": "Jane Doe",
+            "email": "jane.doe@example.com"
+        },
+        category="Programming Languages"
+    )
+    articles.index(doc1)
+
+    doc2 = Document(
+        id="sql-002",
+        content="SQLite is a powerful embedded database. It is ideal for local applications.",
+        author={
+            "name": "John Smith",
+            "handle": "@john_smith_sql"
+        },
+        category="Databases"
+    )
+    articles.index(doc2)
+
+    doc3 = Document(
+        id="py-dev-003",
+        content="Web application development with Python is made easier with frameworks like Django.",
+        author={
+            "name": "Jane Doe", # Same author as doc1
+            "email": "jane.doe@example.com"
+        },
+        category="Web Development"
+    )
+    articles.index(doc3)
+
+    print("Documents indexed.\n")
+
+    # --- 2. Perform a General Full-Text Search ---
+
+    # We search for the word "data" across ALL text fields in all documents.
+    # It should find both doc1 ("data science") and doc2 ("Databases").
+    print("--- General Search for 'data' ---")
+    general_results = articles.match("data", top_k=5)
+
+    for doc, rank in general_results:
+        print(f"  - Document ID: {doc.id}, Relevance (Rank): {rank:.4f}")
+        print(f"    Content: '{doc.content[:40]}...'")
+        print(f"    Author: {doc.author['name']}")
+
+    # --- 3. Perform a Targeted Full-Text Search on a Specific Field ---
+
+    # Now, we search for "Jane" but ONLY in the flattened 'author__name' field.
+    # This should return only the documents by Jane Doe (doc1 and doc3).
+    print("\n--- Specific Search for 'Jane' in the 'author__name' field ---")
+    specific_results = articles.match("Jane", on="author.name", top_k=5)
+
+    for doc, rank in specific_results:
+        print(f"  - Document ID: {doc.id}, Relevance (Rank): {rank:.4f}")
+        print(f"    Author Found: {doc.author['name']}")
+        print(f"    Category: {doc.category}")
+
+    # --- 4. Use FTS5 Operators ---
+
+    # FTS5 allows for operators like OR. We search for documents containing "SQLite" OR "Django".
+    print("\n--- Search with 'OR' Operator: 'SQLite OR Django' ---")
+    or_results = articles.match("SQLite OR Django", top_k=5)
+
+    for doc, rank in or_results:
+        print(f"  - Document ID: {doc.id}, Relevance (Rank): {rank:.4f}")
+        print(f"    Content: '{doc.content}'")
+
+    db.close()
+    print("\n--- Demo Finished ---")
+
+
+if __name__ == "__main__":
+    full_text_search_demo()

beaver_db-0.16.7/examples/fuzzy.py

@@ -0,0 +1,69 @@
+from beaver import BeaverDB, Document
+
+
+def fuzzy_search_demo():
+    """Demonstrates the unified FTS and fuzzy search functionality."""
+    print("--- Running Fuzzy Search Demo ---")
+    db = BeaverDB("fuzzy_demo.db")
+    articles = db.collection("tech_articles")
+
+    # Clean up from previous runs
+    for doc in articles:
+        articles.drop(doc)
+
+    # --- 1. Index Documents with Fuzzy Indexing Enabled ---
+    print("Indexing documents with fuzzy=True...")
+    docs_to_index = [
+        Document(
+            id="py-001",
+            content="Python is a versatile programming language.",
+            author={"name": "Jane Doe", "handle": "janedoe_py"},
+        ),
+        Document(
+            id="sql-002",
+            content="SQLite is a powerful embedded database.",
+            author={"name": "Jon Smith", "handle": "jonsmith_sql"},
+        ),
+        Document(
+            id="py-dev-003",
+            content="Web development with python is easier with frameworks.",
+            author={"name": "Jane Doe", "handle": "janedoe_py"},
+        ),
+    ]
+
+    for doc in docs_to_index:
+        # Index all string fields for FTS and also create a fuzzy index for them
+        articles.index(doc, fts=True, fuzzy=True)
+
+    # --- 2. Standard FTS Search (fuzziness=0) ---
+    print("\n--- Standard FTS for 'python' ---")
+    exact_results = articles.match("python", fuzziness=0)
+    for doc, rank in exact_results:
+        print(f"  - Found ID: {doc.id} (Rank: {rank:.2f})")
+
+    # --- 3. Fuzzy Search on a Specific Field ---
+    # Search for "Jhn Smith" with a typo. It should find "Jon Smith".
+    print("\n--- Fuzzy Search for 'Jhn Smith' on 'author.name' ---")
+    fuzzy_results = articles.match(
+        "Jhn Smith",
+        on=["author.name"],
+        fuzziness=2
+    )
+    for doc, distance in fuzzy_results:
+        print(f"  - Found: '{doc.author['name']}' (Distance: {distance})")
+        assert doc.id == "sql-002"
+
+    # --- 4. Fuzzy Search Across All Fields ---
+    # Search for "prgramming" with a typo. It should find the doc with "programming".
+    print("\n--- Fuzzy Search for 'prgramming' across all fields ---")
+    fuzzy_all_fields = articles.match("prgramming", fuzziness=2)
+    for doc, distance in fuzzy_all_fields:
+        print(f"  - Found in content: '{doc.content}' (Distance: {distance})")
+        assert doc.id == "py-001"
+
+    db.close()
+    print("\n--- Demo Finished ---")
+
+
+if __name__ == "__main__":
+    fuzzy_search_demo()