beaver-db 2.0rc2__py3-none-any.whl

beaver/sketches.py

@@ -0,0 +1,307 @@
+import math
+import hashlib
+import struct
+import asyncio
+from typing import (
+    Any,
+    Iterator,
+    Optional,
+    Protocol,
+    runtime_checkable,
+    TYPE_CHECKING,
+    Self,
+)
+
+from pydantic import BaseModel
+
+from .manager import AsyncBeaverBase, atomic, emits
+from .locks import AsyncBeaverLock
+
+if TYPE_CHECKING:
+    from .core import AsyncBeaverDB
+
+
+def _calculate_hll_precision(error_rate: float) -> int:
+    """Derives the HyperLogLog precision 'p' from a desired error rate."""
+    if not (0 < error_rate < 1):
+        raise ValueError("Error rate must be between 0 and 1")
+    p = 2 * math.log2(1.04 / error_rate)
+    return max(4, min(int(math.ceil(p)), 18))
+
+
+def _calculate_bloom_params(capacity: int, error_rate: float) -> tuple[int, int]:
+    """Calculates optimal Bloom Filter size (bits) and hash count (k)."""
+    if capacity <= 0:
+        raise ValueError("Capacity must be positive")
+    if not (0 < error_rate < 1):
+        raise ValueError("Error rate must be between 0 and 1")
+
+    m_bits = -(capacity * math.log(error_rate)) / (math.log(2) ** 2)
+    k = (m_bits / capacity) * math.log(2)
+    return int(math.ceil(m_bits)), int(math.ceil(k))
+
+
+class ApproximateSet:
+    """
+    A unified probabilistic data structure combining HyperLogLog and Bloom Filter.
+    Pure Python implementation (CPU-bound).
+    """
+
+    def __init__(
+        self,
+        capacity: int = 1_000_000,
+        error_rate: float = 0.01,
+        data: bytes | None = None,
+    ):
+        self.capacity = capacity
+        self.error_rate = error_rate
+
+        # 1. Configure HyperLogLog
+        self.p = _calculate_hll_precision(error_rate)
+        self.m = 1 << self.p
+        self.alpha = self._get_alpha(self.m)
+
+        # 2. Configure Bloom Filter
+        self.bloom_bits, self.bloom_k = _calculate_bloom_params(capacity, error_rate)
+        self.bloom_bytes_len = (self.bloom_bits + 7) // 8
+
+        # 3. Initialize or Load Storage
+        expected_size = self.m + self.bloom_bytes_len
+
+        if data:
+            if len(data) != expected_size:
+                raise ValueError(
+                    f"Corrupted sketch data. Expected {expected_size} bytes, got {len(data)}"
+                )
+            self._data = bytearray(data)
+        else:
+            self._data = bytearray(expected_size)
+
+    def _get_alpha(self, m: int) -> float:
+        if m == 16:
+            return 0.673
+        elif m == 32:
+            return 0.697
+        elif m == 64:
+            return 0.709
+        return 0.7213 / (1 + 1.079 / m)
+
+    def add(self, item_bytes: bytes):
+        self._add_hll(item_bytes)
+        self._add_bloom(item_bytes)
+
+    def _add_hll(self, item_bytes: bytes):
+        h = hashlib.sha1(item_bytes).digest()
+        x = struct.unpack("<Q", h[:8])[0]
+        j = x & (self.m - 1)
+        w = x >> self.p
+        rank = 1
+        while w & 1 == 0 and rank <= (64 - self.p):
+            rank += 1
+            w >>= 1
+        if rank > self._data[j]:
+            self._data[j] = rank
+
+    def _add_bloom(self, item_bytes: bytes):
+        h = hashlib.md5(item_bytes).digest()
+        h1, h2 = struct.unpack("<QQ", h)
+        offset = self.m
+        for i in range(self.bloom_k):
+            bit_idx = (h1 + i * h2) % self.bloom_bits
+            byte_idx = offset + (bit_idx // 8)
+            mask = 1 << (bit_idx % 8)
+            self._data[byte_idx] |= mask
+
+    def __contains__(self, item_bytes: bytes) -> bool:
+        h = hashlib.md5(item_bytes).digest()
+        h1, h2 = struct.unpack("<QQ", h)
+        offset = self.m
+        for i in range(self.bloom_k):
+            bit_idx = (h1 + i * h2) % self.bloom_bits
+            byte_idx = offset + (bit_idx // 8)
+            mask = 1 << (bit_idx % 8)
+            if not (self._data[byte_idx] & mask):
+                return False
+        return True
+
+    def __len__(self) -> int:
+        zeros = 0
+        sum_inv = 0.0
+        for i in range(self.m):
+            val = self._data[i]
+            if val == 0:
+                zeros += 1
+            sum_inv += 2.0 ** (-val)
+        E = self.alpha * (self.m**2) / sum_inv
+        if E <= 2.5 * self.m:
+            if zeros > 0:
+                E = self.m * math.log(self.m / zeros)
+        return int(E)
+
+    def to_bytes(self) -> bytes:
+        return bytes(self._data)
+
+
+class AsyncSketchBatch[T: BaseModel]:
+    """Async Context manager for batched updates to an ApproximateSet."""
+
+    def __init__(self, manager: "AsyncBeaverSketch[T]"):
+        self._manager = manager
+        self._pending_items: list[Any] = []
+
+    def add(self, item: Any):
+        """Adds an item to the pending batch buffer."""
+        self._pending_items.append(item)
+
+    async def __aenter__(self):
+        if self._manager._sketch is None:
+            await self._manager._ensure_sketch()
+
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if not self._pending_items:
+            return
+
+        # Atomic Bulk Update: Lock -> Reload -> Modify -> Save
+        async with self._manager._internal_lock:
+            async with self._manager._db.transaction():
+                # 1. Reload latest state from DB
+                await self._manager._reload()
+
+                # 2. Update in-memory (CPU bound, could offload to thread if huge)
+                for item in self._pending_items:
+                    serialized_item = self._manager._serialize(item)
+                    item_bytes = serialized_item.encode("utf-8")
+                    self._manager._sketch.add(item_bytes)
+
+                # 3. Save back to DB
+                await self._manager._save()
+
+        self._pending_items.clear()
+
+
+@runtime_checkable
+class IBeaverSketch[T: BaseModel](Protocol):
+    """Protocol exposed to the user via BeaverBridge."""
+
+    def add(self, item: T) -> None: ...
+    def contains(self, item: T) -> bool: ...
+    def count(self) -> int: ...
+    def clear(self) -> None: ...
+    def batched(self) -> AsyncSketchBatch[T]: ...
+    def __len__(self) -> int: ...
+    def __contains__(self, item: T) -> bool: ...
+
+
+class AsyncBeaverSketch[T: BaseModel](AsyncBeaverBase[T]):
+    """
+    Manages a persistent ApproximateSet (Bloom + HLL).
+    """
+
+    def __init__(
+        self,
+        name: str,
+        db: "AsyncBeaverDB",
+        capacity: int = 1_000_000,
+        error_rate: float = 0.01,
+        model: type[T] | None = None,
+    ):
+        super().__init__(name, db, model=model)
+        self._capacity = capacity
+        self._error_rate = error_rate
+        self._sketch: ApproximateSet | None = None
+
+    async def _ensure_sketch(self):
+        """Loads the sketch from DB or creates it if it doesn't exist."""
+        cursor = await self.connection.execute(
+            "SELECT capacity, error_rate, data FROM __beaver_sketches__ WHERE name = ?",
+            (self._name,),
+        )
+        row = await cursor.fetchone()
+
+        if row:
+            db_cap, db_err, db_data = row["capacity"], row["error_rate"], row["data"]
+            # Allow small float tolerance
+            if db_cap != self._capacity or abs(db_err - self._error_rate) > 1e-9:
+                raise ValueError(
+                    f"Sketch '{self._name}' exists with capacity={db_cap}, error={db_err}. "
+                    f"Cannot load with requested capacity={self._capacity}, error={self._error_rate}."
+                )
+            self._sketch = ApproximateSet(
+                self._capacity, self._error_rate, data=db_data
+            )
+        else:
+            self._sketch = ApproximateSet(self._capacity, self._error_rate)
+            await self._save()
+
+    async def _reload(self):
+        """Reloads the binary data from the database."""
+        cursor = await self.connection.execute(
+            "SELECT data FROM __beaver_sketches__ WHERE name = ?", (self._name,)
+        )
+        row = await cursor.fetchone()
+        if row:
+            self._sketch._data = bytearray(row["data"])
+
+    async def _save(self):
+        """Persists the current in-memory sketch to the database."""
+        if self._sketch:
+            await self.connection.execute(
+                """
+                INSERT OR REPLACE INTO __beaver_sketches__ (name, type, capacity, error_rate, data)
+                VALUES (?, 'approx_set', ?, ?, ?)
+                """,
+                (self._name, self._capacity, self._error_rate, self._sketch.to_bytes()),
+            )
+
+    @atomic
+    async def add(self, item: T):
+        """
+        Adds a single item to the sketch atomically.
+        """
+        if self._sketch is None:
+            await self._ensure_sketch()
+
+        serialized_item = self._serialize(item)
+        item_bytes = serialized_item.encode("utf-8")
+
+        await self._reload()
+        self._sketch.add(item_bytes)
+        await self._save()
+
+    async def contains(self, item: T) -> bool:
+        """
+        Checks membership using the local cached state.
+        Note: Does not strictly reload from DB for performance reasons.
+        """
+        if self._sketch is None:
+            await self._ensure_sketch()
+
+        serialized_item = self._serialize(item)
+        item_bytes = serialized_item.encode("utf-8")
+        return item_bytes in self._sketch
+
+    async def count(self) -> int:
+        """Returns approximate cardinality using local cached state."""
+        if self._sketch is None:
+            await self._ensure_sketch()
+
+        return len(self._sketch)
+
+    def batched(self) -> AsyncSketchBatch[T]:
+        """Returns an async context manager for batched updates."""
+        # Initialize lazily if needed
+        if self._sketch is None:
+            # We can't await here in a sync method, so we rely on _init or first usage
+            pass
+
+        return AsyncSketchBatch(self)
+
+    async def clear(self):
+        """Resets the sketch to empty."""
+        if self._sketch is None:
+            await self._ensure_sketch()
+
+        self._sketch = ApproximateSet(self._capacity, self._error_rate)
+        await self._save()

beaver/types.py

@@ -0,0 +1,32 @@
+import json
+import sqlite3
+from typing import Any, Callable, Optional, Protocol, Type, Self, runtime_checkable
+
+from .cache import ICache
+
+
+class IDatabase(Protocol):
+    @property
+    def connection(self) -> sqlite3.Connection: ...
+    def cache(self, key: str) -> "ICache": ...
+    def singleton[T, M](
+        self, cls: Type[M], name: str, model: Type[T] | None = None, **kwargs
+    ) -> M: ...
+    def emit(self, topic: str, event: str, payload: dict) -> bool: ...
+    def on(
+        self,
+        topic: str,
+        event: str,
+        callback: Callable,
+    ): ...
+    def off(
+        self,
+        topic: str,
+        event: str,
+        callback: Callable,
+    ): ...
+
+
+@runtime_checkable
+class IResourceManager(Protocol):
+    def close(self): ...

beaver/vectors.py

@@ -0,0 +1,198 @@
+import json
+import math
+import struct
+from typing import (
+    List,
+    Tuple,
+    Iterator,
+    AsyncIterator,
+    Protocol,
+    runtime_checkable,
+    TYPE_CHECKING,
+    Any,
+)
+
+from pydantic import BaseModel
+
+from .manager import AsyncBeaverBase, atomic, emits
+
+if TYPE_CHECKING:
+    from .core import AsyncBeaverDB
+
+
+class VectorItem[T](BaseModel):
+    """Represents a stored vector with metadata."""
+
+    id: str
+    vector: List[float]
+    metadata: T | None = None
+    score: float = 0
+
+
+@runtime_checkable
+class IBeaverVectors[T](Protocol):
+    """Protocol exposed to the user via BeaverBridge."""
+
+    def set(self, id: str, vector: List[float], metadata: T | None = None) -> None: ...
+    def get(self, id: str) -> VectorItem[T] | None: ...
+    def delete(self, id: str) -> None: ...
+
+    def search(self, vector: List[float], k: int = 10) -> List[VectorItem[T]]: ...
+
+    def count(self) -> int: ...
+    def clear(self) -> None: ...
+    def __iter__(self) -> Iterator[VectorItem[T]]: ...
+
+
+class AsyncBeaverVectors[T: BaseModel](AsyncBeaverBase[T]):
+    """
+    A simple, persistent vector store.
+
+    Performs exact Nearest Neighbor search by doing a full scan
+    and computing distances in memory.
+
+    Table managed:
+    - __beaver_vectors__ (collection, item_id, vector, metadata)
+    """
+
+    def __init__(self, name: str, db: "AsyncBeaverDB", model: type[T] | None = None):
+        super().__init__(name, db, model)
+        # T is the metadata model
+        self._meta_model = model
+
+    def _serialize_vector(self, vector: List[float]) -> bytes:
+        """Packs a list of floats into binary data."""
+        # Use 'f' for float (4 bytes) or 'd' for double (8 bytes).
+        # 'f' is standard for most embeddings.
+        return struct.pack(f"{len(vector)}f", *vector)
+
+    def _deserialize_vector(self, data: bytes) -> List[float]:
+        """Unpacks binary data into a list of floats."""
+        count = len(data) // 4
+        return list(struct.unpack(f"{count}f", data))
+
+    def _cosine_similarity(self, v1: List[float], v2: List[float]) -> float:
+        """Computes Cosine Similarity between two vectors."""
+        if len(v1) != len(v2):
+            return -1.0  # Dimension mismatch punishment
+
+        dot_product = sum(a * b for a, b in zip(v1, v2))
+        norm_v1 = math.sqrt(sum(a * a for a in v1))
+        norm_v2 = math.sqrt(sum(b * b for b in v2))
+
+        if norm_v1 == 0 or norm_v2 == 0:
+            return 0.0
+
+        return dot_product / (norm_v1 * norm_v2)
+
+    @emits("set", payload=lambda id, *args, **kwargs: dict(id=id))
+    @atomic
+    async def set(self, id: str, vector: List[float], metadata: T | None = None):
+        """
+        Stores a vector and optional metadata.
+        """
+        vec_blob = self._serialize_vector(vector)
+
+        # Serialize metadata using base manager logic
+        meta_json = self._serialize(metadata) if metadata else None
+
+        await self.connection.execute(
+            """
+            INSERT OR REPLACE INTO __beaver_vectors__
+            (collection, item_id, vector, metadata)
+            VALUES (?, ?, ?, ?)
+            """,
+            (self._name, id, vec_blob, meta_json),
+        )
+
+    @atomic
+    async def get(self, id: str) -> VectorItem[T]:
+        """Retrieves a vector item by ID."""
+        cursor = await self.connection.execute(
+            "SELECT vector, metadata FROM __beaver_vectors__ WHERE collection = ? AND item_id = ?",
+            (self._name, id),
+        )
+        row = await cursor.fetchone()
+
+        if not row:
+            raise KeyError(id)
+
+        vector = self._deserialize_vector(row["vector"])
+        meta_val = self._deserialize(row["metadata"]) if row["metadata"] else None
+
+        return VectorItem(id=id, vector=vector, metadata=meta_val)
+
+    @emits("delete", payload=lambda id, *args, **kwargs: dict(id=id))
+    @atomic
+    async def delete(self, id: str):
+        """Deletes a vector item."""
+        await self.connection.execute(
+            "DELETE FROM __beaver_vectors__ WHERE collection = ? AND item_id = ?",
+            (self._name, id),
+        )
+
+    async def search(self, vector: List[float], k: int = 10) -> List[VectorItem[T]]:
+        """
+        Performs exact KNN search using Cosine Similarity.
+        Scans the entire table for this collection.
+        """
+        query_vec = vector
+
+        # 1. Fetch ALL vectors (Full Scan)
+        # Optimization: We could stream this if memory is an issue,
+        # but for a simple store, fetching all is fine.
+        cursor = await self.connection.execute(
+            "SELECT item_id, vector, metadata FROM __beaver_vectors__ WHERE collection = ?",
+            (self._name,),
+        )
+
+        candidates = []
+        async for row in cursor:
+            # CPU Bound work inside the loop
+            row_vec = self._deserialize_vector(row["vector"])
+            score = self._cosine_similarity(query_vec, row_vec)
+
+            candidates.append((score, row))
+
+        # 2. Sort by Score Descending
+        candidates.sort(key=lambda x: x[0], reverse=True)
+
+        # 3. Take Top K and Hydrate
+        top_k = candidates[:k]
+        results = []
+
+        for score, row in top_k:
+            # Reconstruct item
+            vec = self._deserialize_vector(row["vector"])
+            meta_val = self._deserialize(row["metadata"]) if row["metadata"] else None
+
+            item = VectorItem(
+                id=row["item_id"], vector=vec, metadata=meta_val, score=score
+            )
+            results.append(item)
+
+        return results
+
+    async def count(self) -> int:
+        cursor = await self.connection.execute(
+            "SELECT COUNT(*) FROM __beaver_vectors__ WHERE collection = ?",
+            (self._name,),
+        )
+        result = await cursor.fetchone()
+        return result[0] if result else 0
+
+    @atomic
+    async def clear(self):
+        await self.connection.execute(
+            "DELETE FROM __beaver_vectors__ WHERE collection = ?", (self._name,)
+        )
+
+    async def __aiter__(self):
+        cursor = await self.connection.execute(
+            "SELECT item_id, vector, metadata FROM __beaver_vectors__ WHERE collection = ?",
+            (self._name,),
+        )
+        async for row in cursor:
+            vec = self._deserialize_vector(row["vector"])
+            meta = self._deserialize(row["metadata"]) if row["metadata"] else None
+            yield VectorItem(id=row["item_id"], vector=vec, metadata=meta)

beaver_db-2.0rc2.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: beaver-db
+Version: 2.0rc2
+Summary: Fast, async-native, embedded, and multi-modal DB based on SQLite for AI-powered applications.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: numpy>=2.3.4
+Requires-Dist: pydantic>=2.12.3
+Requires-Dist: rich>=14.2.0
+Requires-Dist: typer>=0.20.0
+Provides-Extra: full
+Requires-Dist: cryptography>=46.0.3; extra == 'full'
+Requires-Dist: fastapi[standard]>=0.118.0; extra == 'full'
+Provides-Extra: remote
+Requires-Dist: fastapi[standard]>=0.118.0; extra == 'remote'
+Provides-Extra: security
+Requires-Dist: cryptography>=46.0.3; extra == 'security'
+Description-Content-Type: text/markdown
+
+<div style="text-align: center;">
+  <img src="https://github.com/syalia-srl/beaver/blob/main/logo.png?raw=true" width="256px">
+</div>
+
+---
+
+<!-- Project badges -->
+![PyPI - Version](https://img.shields.io/pypi/v/beaver-db)
+![PyPi - Python Version](https://img.shields.io/pypi/pyversions/beaver-db)
+![Github - Open Issues](https://img.shields.io/github/issues-raw/syalia-srl/beaver)
+![PyPi - Downloads (Monthly)](https://img.shields.io/pypi/dm/beaver-db)
+![Github - Commits](https://img.shields.io/github/commit-activity/m/syalia-srl/beaver)
+
+-----
+
+`beaver` is 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.
+
+  * **Minimal Dependencies**: The core library has minimal dependencies (`numpy`, `pydantic`, `rich`, `typer`). Advanced features (like the REST server) are optional extras.
+  * **Safe Concurrency**: Thread-safe and multi-process-safe by default, with robust inter-process locking.
+  * **Local-First**: A single, portable SQLite file is the default.
+  * **Fast & Performant**: Zero network latency for local operations and an optional, in-memory read cache.
+  * **Standard SQLite**: The database file is 100% compatible with any standard SQLite tool, ensuring data portability.
+  * **Pythonic API**: Designed to feel like a natural extension of your code, using standard Python data structures and Pydantic models.
+
+## Installation
+
+Install the core library:
+
+```bash
+pip install beaver-db
+```
+
+To include optional features, you can install them as extras:
+
+```bash
+# For the REST API server and client
+pip install "beaver-db[remote]"
+
+# To install all optional features at once
+pip install "beaver-db[full]"
+```
+
+### Docker
+
+You can also run the BeaverDB REST API server using Docker.
+
+```bash
+docker pull ghcr.io/syalia-srl/beaver:latest
+docker run -p 8000:8000 -v $(pwd)/data:/app ghcr.io/syalia-srl/beaver
+```
+
+## 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",
+    body="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.body}'")
+
+db.close()
+```
+
+## Features
+
+  * [**Key-Value Dictionaries**](https://syalia.com/beaver/guide-dicts-blobs.html): A Pythonic, dictionary-like interface for storing any JSON-serializable object or Pydantic model within separate namespaces. Includes TTL support for caching.
+  * [**Blob Storage**](https://syalia.com/beaver/guide-dicts-blobs.html): A dictionary-like interface for storing binary data (e.g., images, PDFs) with associated JSON metadata.
+  * [**Persistent Lists**](https://syalia.com/beaver/guide-lists-queues.html): A full-featured, persistent Python list supporting `push`, `pop`, `prepend`, `deque`, slicing, and in-place updates.
+  * [**Persistent Priority Queue**](https://syalia.com/beaver/guide-lists-queues.html): A high-performance, persistent priority queue perfect for task orchestration across multiple processes.
+  * [**Probabilistic Sketches:**]() Track cardinality and membership for millions of items in constant space using HyperLogLog and Bloom Filters.
+  * [**Document Collections**](https://syalia.com/beaver/guide-collections.html): Store rich documents combining a vector embedding and Pydantic-based metadata.
+  * [**Vector Search**](https://syalia.com/beaver/guide-collections.html%23vector-search): Fast, multi-process-safe linear vector search using an in-memory `numpy`-based index.
+  * [**Full-Text & Fuzzy Search**](https://syalia.com/beaver/guide-collections.html%23full-text-fuzzy-search): Automatically index and search through document metadata using SQLite's FTS5 engine, with optional fuzzy search for typo-tolerant matching.
+  * [**Knowledge Graph**](https://syalia.com/beaver/guide-collections.html%23knowledge-graph): Create directed, labeled relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
+  * [**Pub/Sub System**](https://syalia.com/beaver/guide-realtime.html): A powerful, thread and process-safe publish-subscribe system for real-time messaging with a fan-out architecture.
+  * [**Time-Indexed Logs**](https://syalia.com/beaver/guide-realtime.html): A specialized data structure for structured, time-series logs. Query historical data by time range or create a live, aggregated view.
+  * [**Event-Driven Callbacks**](https://syalia.com/beaver/guide-realtime.html): Listen for database changes in real-time. Subscribe to events on specific managers to trigger workflows or update UIs.
+  * [**Inter-Process Locking**](https://syalia.com/beaver/guide-concurrency.html): Robust, deadlock-proof locks. Use `db.lock('task_name')` to coordinate arbitrary scripts, or `with db.list('my_list') as l:` to perform atomic, multi-step operations.
+  * [**Pydantic Support**](https://syalia.com/beaver/dev-architecture.html%23type-safe-models): Optionally associate `pydantic.BaseModel`s with any data structure for automatic, recursive data validation and (de)serialization.
+  * [**Deployment**](https://syalia.com/beaver/guide-deployment.html): Instantly serve your database over a RESTful API with `beaver serve` and interact with it via the `beaver` CLI.
+  * [**Data Export & Backups**](https://syalia.com/beaver/guide-deployment.html): Dump any data structure to a portable JSON file with a single `.dump()` command.
+
+## Documentation
+
+For a complete API reference, in-depth guides, and more examples, please visit the official documentation at:
+
+[**https://syalia.com/beaver**](https://syalia.com/beaver)
+
+## Contributing
+
+Contributions are welcome\! If you think of something that would make `beaver` more useful for your use case, please open an issue or submit a pull request.
+
+## License
+
+This project is licensed under the MIT License.