beaver-db 0.17.4__tar.gz → 0.17.6__tar.gz

{beaver_db-0.17.4 → beaver_db-0.17.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.17.4
+Version: 0.17.6
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
@@ -42,7 +42,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 
 `beaver` is built with a minimalistic philosophy for small, local use cases where a full-blown database server would be overkill.
 
-- **Minimalistic**: The core library has zero external dependencies. Vector search capabilities, which require `numpy` and `faiss-cpu`, are available as an optional feature.
+- **Minimalistic**: The core library has zero external dependencies. Vector search, the REST server, and the CLI, which require external libraries, are available as optional features.
 - **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.
@@ -61,6 +61,8 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 - **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.
+- **Built-in REST API Server (Optional)**: Instantly serve your database over a RESTful API with automatic OpenAPI documentation using FastAPI.
+- **Full-Featured CLI Client (Optional)**: Interact with your database directly from the command line for administrative tasks and data exploration.
 - **Optional Type-Safety:** Although the database is schemaless, you can use a minimalistic typing system for automatic serialization and deserialization that is Pydantic-compatible out of the box.
 
 ## How Beaver is Implemented
@@ -79,7 +81,6 @@ The vector store in BeaverDB is designed for high performance and reliability, u
 
 This hybrid approach allows BeaverDB to provide a vector search experience that is both fast and durable, without sacrificing the single-file, embedded philosophy of the library.
 
-
 ## Installation
 
 Install the core, dependency-free library:
@@ -88,10 +89,17 @@ Install the core, dependency-free library:
 pip install beaver-db
 ```
 
-If you want vector search capabilities, install the `faiss` extra:
+To include optional features, you can install them as extras:
 
 ```bash
+# For vector search capabilities
 pip install "beaver-db[faiss]"
+
+# For the REST API server and CLI
+pip install "beaver-db[server,cli]"
+
+# To install all optional features at once
+pip install "beaver-db[full]"
 ```
 
 ## Quickstart
@@ -131,6 +139,53 @@ print(f"FTS Result: '{top_doc.content}'")
 db.close()
 ```
 
+## Built-in Server and CLI
+
+Beaver comes with a built-in REST API server and a full-featured command-line client, allowing you to interact with your database without writing any code.
+
+### REST API Server
+
+You can instantly expose all of your database's functionality over a RESTful API. This is perfect for building quick prototypes, microservices, or for interacting with your data from other languages.
+
+**1. Start the server**
+
+```bash
+# Start the server for your database file
+beaver serve --database data.db --port 8000
+```
+
+This starts a `FastAPI` server. You can now access the interactive API documentation at `http://127.0.0.1:8000/docs`.
+
+**2. Interact with the API**
+
+Here are a couple of examples using `curl`:
+
+```bash
+# Set a value in the 'app_config' dictionary
+curl -X PUT http://127.0.0.1:8000/dicts/app_config/api_key
+     -H "Content-Type: application/json"
+     -d '"your-secret-api-key"'
+
+# Get the value back
+curl http://127.0.0.1:8000/dicts/app_config/api_key
+# Output: "your-secret-api-key"
+```
+
+### Command-Line Client
+
+The CLI client allows you to call any BeaverDB method directly from your terminal.
+
+```bash
+# Set a value in a dictionary
+beaver client --database data.db dict app_config set theme light
+
+# Get the value back
+beaver client --database data.db dict app_config get theme
+
+# Push an item to a list
+beaver client --database data.db list daily_tasks push "Review PRs"
+```
+
 ## 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.
@@ -282,8 +337,10 @@ For enhanced data integrity and a better developer experience, BeaverDB supports
 
 This feature is designed to be flexible and works seamlessly with two kinds of models:
 
-  * **Pydantic Models**: If you're already using Pydantic, your `BaseModel` classes will work out of the box.
-  * **Lightweight `beaver.Model`**: For a zero-dependency solution, you can inherit from the built-in `beaver.Model` class, which is a standard Python class with serialization methods automatically included.
+- **Pydantic Models**: If you're already using Pydantic, your `BaseModel` classes will work out of the box.
+
+- **Lightweight `beaver.Model`**: For a zero-dependency solution, you can inherit from the built-in `beaver.Model` class, which is a standard Python class with serialization methods automatically included.
+
 
 Here’s a quick example of how to use it:
 
@@ -305,7 +362,8 @@ users["alice"] = User(name="Alice", email="alice@example.com")
 
 # The retrieved object is a proper instance of the User class
 retrieved_user = users["alice"]
-print(f"Retrieved: {retrieved_user.name}") # Your editor will provide autocompletion here
+# Your editor will provide autocompletion here
+print(f"Retrieved: {retrieved_user.name}")
 ```
 
 In the same way you can have typed message payloads in `db.channel`, typed metadata in `db.blobs`, and custom document types in `db.collection`, as well as custom types in lists and queues.
@@ -316,25 +374,25 @@ Basically everywhere you can store or get some object in BeaverDB, you can use a
 
 For more in-depth examples, check out the scripts in the `examples/` directory:
 
-  - [`async_pubsub.py`](examples/async_pubsub.py): A demonstration of the asynchronous wrapper for the publish/subscribe system.
-  - [`blobs.py`](examples/blobs.py): Demonstrates how to store and retrieve binary data in the database.
-  - [`cache.py`](examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
-  - [`fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
-  - [`fuzzy.py`](examples/fuzzy.py): Demonstrates fuzzy search capabilities for text search.
-  - [`general_test.py`](examples/general_test.py): A general-purpose test to run all operations randomly which allows testing long-running processes and synchronicity issues.
-  - [`graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
-  - [`kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
-  - [`list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
-  - [`logs.py`](examples/logs.py): A short example showing how to build a realtime dashboard with the logging feature.
-  - [`pqueue.py`](examples/pqueue.py): A practical example of using the persistent priority queue for task management.
-  - [`producer_consumer.py`](examples/producer_consumer.py): A demonstration of the distributed task queue system in a multi-process environment.
-  - [`publisher.py`](examples/publisher.py) and [`subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
-  - [`pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
-  - [`rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
-  - [`stress_vectors.py`](examples/stress_vectors.py): A stress test for the vector search functionality.
-  - [`textual_chat.py`](examples/textual_chat.py): A chat application built with `textual` and `beaver` to illustrate the use of several primitives (lists, dicts, and channels) at the same time.
-  - [`type_hints.py`](examples/type_hints.py): Shows how to use type hints with `beaver` to get better IDE support and type safety.
-  - [`vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
+- [`async_pubsub.py`](examples/async_pubsub.py): A demonstration of the asynchronous wrapper for the publish/subscribe system.
+- [`blobs.py`](examples/blobs.py): Demonstrates how to store and retrieve binary data in the database.
+- [`cache.py`](examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
+- [`fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
+- [`fuzzy.py`](examples/fuzzy.py): Demonstrates fuzzy search capabilities for text search.
+- [`general_test.py`](examples/general_test.py): A general-purpose test to run all operations randomly which allows testing long-running processes and synchronicity issues.
+- [`graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
+- [`kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
+- [`list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
+- [`logs.py`](examples/logs.py): A short example showing how to build a realtime dashboard with the logging feature.
+- [`pqueue.py`](examples/pqueue.py): A practical example of using the persistent priority queue for task management.
+- [`producer_consumer.py`](examples/producer_consumer.py): A demonstration of the distributed task queue system in a multi-process environment.
+- [`publisher.py`](examples/publisher.p) and [`subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+- [`pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
+- [`rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
+- [`stress_vectors.py`](examples/stress_vectors.py): A stress test for the vector search functionality.
+- [`textual_chat.py`](examples/textual_chat.py): A chat application built with `textual` and `beaver` to illustrate the use of several primitives (lists, dicts, and channels) at the same time.
+- [`type_hints.py`](examples/type_hints.py): Shows how to use type hints with `beaver` to get better IDE support and type safety.
+- [`vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
 
 ## Roadmap
 
@@ -342,7 +400,7 @@ For more in-depth examples, check out the scripts in the `examples/` directory:
 
 These are some of the features and improvements planned for future releases:
 
-  - **Async API**: Extend the async support with on-demand wrappers for all features besides channels.
+- **Async API**: Extend the async support with on-demand wrappers for all features besides channels.
 
 Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
 
@@ -350,4 +408,4 @@ If you think of something that would make `beaver` more useful for your use case
 
 ## License
 
-This project is licensed under the MIT License.
+This project is licensed under the MIT License.

{beaver_db-0.17.4 → beaver_db-0.17.6}/README.md

@@ -17,7 +17,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 
 `beaver` is built with a minimalistic philosophy for small, local use cases where a full-blown database server would be overkill.
 
-- **Minimalistic**: The core library has zero external dependencies. Vector search capabilities, which require `numpy` and `faiss-cpu`, are available as an optional feature.
+- **Minimalistic**: The core library has zero external dependencies. Vector search, the REST server, and the CLI, which require external libraries, are available as optional features.
 - **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.
@@ -36,6 +36,8 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 - **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.
+- **Built-in REST API Server (Optional)**: Instantly serve your database over a RESTful API with automatic OpenAPI documentation using FastAPI.
+- **Full-Featured CLI Client (Optional)**: Interact with your database directly from the command line for administrative tasks and data exploration.
 - **Optional Type-Safety:** Although the database is schemaless, you can use a minimalistic typing system for automatic serialization and deserialization that is Pydantic-compatible out of the box.
 
 ## How Beaver is Implemented
@@ -54,7 +56,6 @@ The vector store in BeaverDB is designed for high performance and reliability, u
 
 This hybrid approach allows BeaverDB to provide a vector search experience that is both fast and durable, without sacrificing the single-file, embedded philosophy of the library.
 
-
 ## Installation
 
 Install the core, dependency-free library:
@@ -63,10 +64,17 @@ Install the core, dependency-free library:
 pip install beaver-db
 ```
 
-If you want vector search capabilities, install the `faiss` extra:
+To include optional features, you can install them as extras:
 
 ```bash
+# For vector search capabilities
 pip install "beaver-db[faiss]"
+
+# For the REST API server and CLI
+pip install "beaver-db[server,cli]"
+
+# To install all optional features at once
+pip install "beaver-db[full]"
 ```
 
 ## Quickstart
@@ -106,6 +114,53 @@ print(f"FTS Result: '{top_doc.content}'")
 db.close()
 ```
 
+## Built-in Server and CLI
+
+Beaver comes with a built-in REST API server and a full-featured command-line client, allowing you to interact with your database without writing any code.
+
+### REST API Server
+
+You can instantly expose all of your database's functionality over a RESTful API. This is perfect for building quick prototypes, microservices, or for interacting with your data from other languages.
+
+**1. Start the server**
+
+```bash
+# Start the server for your database file
+beaver serve --database data.db --port 8000
+```
+
+This starts a `FastAPI` server. You can now access the interactive API documentation at `http://127.0.0.1:8000/docs`.
+
+**2. Interact with the API**
+
+Here are a couple of examples using `curl`:
+
+```bash
+# Set a value in the 'app_config' dictionary
+curl -X PUT http://127.0.0.1:8000/dicts/app_config/api_key
+     -H "Content-Type: application/json"
+     -d '"your-secret-api-key"'
+
+# Get the value back
+curl http://127.0.0.1:8000/dicts/app_config/api_key
+# Output: "your-secret-api-key"
+```
+
+### Command-Line Client
+
+The CLI client allows you to call any BeaverDB method directly from your terminal.
+
+```bash
+# Set a value in a dictionary
+beaver client --database data.db dict app_config set theme light
+
+# Get the value back
+beaver client --database data.db dict app_config get theme
+
+# Push an item to a list
+beaver client --database data.db list daily_tasks push "Review PRs"
+```
+
 ## 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.
@@ -257,8 +312,10 @@ For enhanced data integrity and a better developer experience, BeaverDB supports
 
 This feature is designed to be flexible and works seamlessly with two kinds of models:
 
-  * **Pydantic Models**: If you're already using Pydantic, your `BaseModel` classes will work out of the box.
-  * **Lightweight `beaver.Model`**: For a zero-dependency solution, you can inherit from the built-in `beaver.Model` class, which is a standard Python class with serialization methods automatically included.
+- **Pydantic Models**: If you're already using Pydantic, your `BaseModel` classes will work out of the box.
+
+- **Lightweight `beaver.Model`**: For a zero-dependency solution, you can inherit from the built-in `beaver.Model` class, which is a standard Python class with serialization methods automatically included.
+
 
 Here’s a quick example of how to use it:
 
@@ -280,7 +337,8 @@ users["alice"] = User(name="Alice", email="alice@example.com")
 
 # The retrieved object is a proper instance of the User class
 retrieved_user = users["alice"]
-print(f"Retrieved: {retrieved_user.name}") # Your editor will provide autocompletion here
+# Your editor will provide autocompletion here
+print(f"Retrieved: {retrieved_user.name}")
 ```
 
 In the same way you can have typed message payloads in `db.channel`, typed metadata in `db.blobs`, and custom document types in `db.collection`, as well as custom types in lists and queues.
@@ -291,25 +349,25 @@ Basically everywhere you can store or get some object in BeaverDB, you can use a
 
 For more in-depth examples, check out the scripts in the `examples/` directory:
 
-  - [`async_pubsub.py`](examples/async_pubsub.py): A demonstration of the asynchronous wrapper for the publish/subscribe system.
-  - [`blobs.py`](examples/blobs.py): Demonstrates how to store and retrieve binary data in the database.
-  - [`cache.py`](examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
-  - [`fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
-  - [`fuzzy.py`](examples/fuzzy.py): Demonstrates fuzzy search capabilities for text search.
-  - [`general_test.py`](examples/general_test.py): A general-purpose test to run all operations randomly which allows testing long-running processes and synchronicity issues.
-  - [`graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
-  - [`kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
-  - [`list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
-  - [`logs.py`](examples/logs.py): A short example showing how to build a realtime dashboard with the logging feature.
-  - [`pqueue.py`](examples/pqueue.py): A practical example of using the persistent priority queue for task management.
-  - [`producer_consumer.py`](examples/producer_consumer.py): A demonstration of the distributed task queue system in a multi-process environment.
-  - [`publisher.py`](examples/publisher.py) and [`subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
-  - [`pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
-  - [`rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
-  - [`stress_vectors.py`](examples/stress_vectors.py): A stress test for the vector search functionality.
-  - [`textual_chat.py`](examples/textual_chat.py): A chat application built with `textual` and `beaver` to illustrate the use of several primitives (lists, dicts, and channels) at the same time.
-  - [`type_hints.py`](examples/type_hints.py): Shows how to use type hints with `beaver` to get better IDE support and type safety.
-  - [`vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
+- [`async_pubsub.py`](examples/async_pubsub.py): A demonstration of the asynchronous wrapper for the publish/subscribe system.
+- [`blobs.py`](examples/blobs.py): Demonstrates how to store and retrieve binary data in the database.
+- [`cache.py`](examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
+- [`fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
+- [`fuzzy.py`](examples/fuzzy.py): Demonstrates fuzzy search capabilities for text search.
+- [`general_test.py`](examples/general_test.py): A general-purpose test to run all operations randomly which allows testing long-running processes and synchronicity issues.
+- [`graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
+- [`kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
+- [`list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
+- [`logs.py`](examples/logs.py): A short example showing how to build a realtime dashboard with the logging feature.
+- [`pqueue.py`](examples/pqueue.py): A practical example of using the persistent priority queue for task management.
+- [`producer_consumer.py`](examples/producer_consumer.py): A demonstration of the distributed task queue system in a multi-process environment.
+- [`publisher.py`](examples/publisher.p) and [`subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+- [`pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
+- [`rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
+- [`stress_vectors.py`](examples/stress_vectors.py): A stress test for the vector search functionality.
+- [`textual_chat.py`](examples/textual_chat.py): A chat application built with `textual` and `beaver` to illustrate the use of several primitives (lists, dicts, and channels) at the same time.
+- [`type_hints.py`](examples/type_hints.py): Shows how to use type hints with `beaver` to get better IDE support and type safety.
+- [`vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
 
 ## Roadmap
 
@@ -317,7 +375,7 @@ For more in-depth examples, check out the scripts in the `examples/` directory:
 
 These are some of the features and improvements planned for future releases:
 
-  - **Async API**: Extend the async support with on-demand wrappers for all features besides channels.
+- **Async API**: Extend the async support with on-demand wrappers for all features besides channels.
 
 Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
 
@@ -325,4 +383,4 @@ If you think of something that would make `beaver` more useful for your use case
 
 ## License
 
-This project is licensed under the MIT License.
+This project is licensed under the MIT License.

beaver_db-0.17.6/beaver/server.py

@@ -0,0 +1,339 @@
+try:
+    from typing import Any, Optional, List
+    import json
+    from datetime import datetime, timedelta, timezone
+    from fastapi import FastAPI, HTTPException, Body, UploadFile, File, Form, Response, WebSocket, WebSocketDisconnect
+    import uvicorn
+    from pydantic import BaseModel, Field
+except ImportError:
+    raise ImportError("Please install server dependencies with: pip install \"beaver-db[server]\"")
+
+from .core import BeaverDB
+from .collections import Document, WalkDirection
+
+
+# --- Pydantic Models for Collections ---
+
+class IndexRequest(BaseModel):
+    id: Optional[str] = None
+    embedding: Optional[List[float]] = None
+    metadata: dict = Field(default_factory=dict)
+    fts: bool = True
+    fuzzy: bool = False
+
+class SearchRequest(BaseModel):
+    vector: List[float]
+    top_k: int = 10
+
+class MatchRequest(BaseModel):
+    query: str
+    on: Optional[List[str]] = None
+    top_k: int = 10
+    fuzziness: int = 0
+
+class ConnectRequest(BaseModel):
+    source_id: str
+    target_id: str
+    label: str
+    metadata: Optional[dict] = None
+
+class WalkRequest(BaseModel):
+    labels: List[str]
+    depth: int
+    direction: WalkDirection = WalkDirection.OUTGOING
+
+
+def build(db: BeaverDB) -> FastAPI:
+    """Constructs a FastAPI instance for a given BeaverDB."""
+    app = FastAPI(title="BeaverDB Server")
+
+    # --- Dicts Endpoints ---
+
+    @app.get("/dicts/{name}/{key}", tags=["Dicts"])
+    def get_dict_item(name: str, key: str) -> Any:
+        """Retrieves the value for a specific key."""
+        d = db.dict(name)
+        value = d.get(key)
+        if value is None:
+            raise HTTPException(status_code=404, detail=f"Key '{key}' not found in dictionary '{name}'")
+        return value
+
+    @app.put("/dicts/{name}/{key}", tags=["Dicts"])
+    def set_dict_item(name: str, key: str, value: Any = Body(...)):
+        """Sets or updates the value for a specific key."""
+        d = db.dict(name)
+        d[key] = value
+        return {"status": "ok"}
+
+    @app.delete("/dicts/{name}/{key}", tags=["Dicts"])
+    def delete_dict_item(name: str, key: str):
+        """Deletes a key-value pair."""
+        d = db.dict(name)
+        try:
+            del d[key]
+            return {"status": "ok"}
+        except KeyError:
+            raise HTTPException(status_code=404, detail=f"Key '{key}' not found in dictionary '{name}'")
+
+
+    # --- Lists Endpoints ---
+
+    @app.get("/lists/{name}", tags=["Lists"])
+    def get_list(name: str) -> list:
+        """Retrieves all items in the list."""
+        l = db.list(name)
+        return l[:]
+
+    @app.get("/lists/{name}/{index}", tags=["Lists"])
+    def get_list_item(name: str, index: int) -> Any:
+        """Retrieves the item at a specific index."""
+        l = db.list(name)
+        try:
+            return l[index]
+        except IndexError:
+            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
+
+    @app.post("/lists/{name}", tags=["Lists"])
+    def push_list_item(name: str, value: Any = Body(...)):
+        """Adds an item to the end of the list."""
+        l = db.list(name)
+        l.push(value)
+        return {"status": "ok"}
+
+    @app.put("/lists/{name}/{index}", tags=["Lists"])
+    def update_list_item(name: str, index: int, value: Any = Body(...)):
+        """Updates the item at a specific index."""
+        l = db.list(name)
+        try:
+            l[index] = value
+            return {"status": "ok"}
+        except IndexError:
+            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
+
+    @app.delete("/lists/{name}/{index}", tags=["Lists"])
+    def delete_list_item(name: str, index: int):
+        """Deletes the item at a specific index."""
+        l = db.list(name)
+        try:
+            del l[index]
+            return {"status": "ok"}
+        except IndexError:
+            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
+
+    # --- Queues Endpoints ---
+
+    @app.get("/queues/{name}/peek", tags=["Queues"])
+    def peek_queue_item(name: str) -> Any:
+        """Retrieves the highest-priority item from the queue without removing it."""
+        q = db.queue(name)
+        item = q.peek()
+        if item is None:
+            raise HTTPException(status_code=404, detail=f"Queue '{name}' is empty")
+        return item
+
+    @app.post("/queues/{name}/put", tags=["Queues"])
+    def put_queue_item(name: str, data: Any = Body(...), priority: float = Body(...)):
+        """Adds an item to the queue with a specific priority."""
+        q = db.queue(name)
+        q.put(data=data, priority=priority)
+        return {"status": "ok"}
+
+    @app.delete("/queues/{name}/get", tags=["Queues"])
+    def get_queue_item(name: str, timeout: float = 5.0) -> Any:
+        """
+        Atomically retrieves and removes the highest-priority item from the queue,
+        blocking until an item is available or the timeout is reached.
+        """
+        q = db.queue(name)
+        try:
+            item = q.get(block=True, timeout=timeout)
+            return item
+        except TimeoutError:
+            raise HTTPException(status_code=408, detail=f"Request timed out after {timeout}s waiting for an item in queue '{name}'")
+        except IndexError:
+            # This case is less likely with block=True but good to handle
+            raise HTTPException(status_code=404, detail=f"Queue '{name}' is empty")
+
+
+    # --- Blobs Endpoints ---
+
+    @app.get("/blobs/{name}/{key}", response_class=Response, tags=["Blobs"])
+    def get_blob(name: str, key: str):
+        """Retrieves a blob as a binary file."""
+        blobs = db.blobs(name)
+        blob = blobs.get(key)
+        if blob is None:
+            raise HTTPException(status_code=404, detail=f"Blob with key '{key}' not found in store '{name}'")
+        # Return the raw bytes with a generic binary content type
+        return Response(content=blob.data, media_type="application/octet-stream")
+
+    @app.put("/blobs/{name}/{key}", tags=["Blobs"])
+    async def put_blob(name: str, key: str, data: UploadFile = File(...), metadata: Optional[str] = Form(None)):
+        """Stores a blob (binary file) with optional JSON metadata."""
+        blobs = db.blobs(name)
+        file_bytes = await data.read()
+
+        meta_dict = None
+        if metadata:
+            try:
+                meta_dict = json.loads(metadata)
+            except json.JSONDecodeError:
+                raise HTTPException(status_code=400, detail="Invalid JSON format for metadata.")
+
+        blobs.put(key=key, data=file_bytes, metadata=meta_dict)
+        return {"status": "ok"}
+
+    @app.delete("/blobs/{name}/{key}", tags=["Blobs"])
+    def delete_blob(name: str, key: str):
+        """Deletes a blob from the store."""
+        blobs = db.blobs(name)
+        try:
+            blobs.delete(key)
+            return {"status": "ok"}
+        except KeyError:
+            raise HTTPException(status_code=404, detail=f"Blob with key '{key}' not found in store '{name}'")
+
+
+    # --- Logs Endpoints ---
+
+    @app.post("/logs/{name}", tags=["Logs"])
+    def create_log_entry(name: str, data: Any = Body(...)):
+        """Adds a new entry to the log."""
+        log = db.log(name)
+        log.log(data)
+        return {"status": "ok"}
+
+    @app.get("/logs/{name}/range", tags=["Logs"])
+    def get_log_range(name: str, start: datetime, end: datetime) -> list:
+        """Retrieves log entries within a specific time window."""
+        log = db.log(name)
+        # Ensure datetimes are timezone-aware (UTC) for correct comparison
+        start_utc = start.astimezone(timezone.utc) if start.tzinfo else start.replace(tzinfo=timezone.utc)
+        end_utc = end.astimezone(timezone.utc) if end.tzinfo else end.replace(tzinfo=timezone.utc)
+        return log.range(start=start_utc, end=end_utc)
+
+    @app.websocket("/logs/{name}/live", name="Logs")
+    async def live_log_feed(websocket: WebSocket, name: str, window_seconds: int = 5, period_seconds: int = 1):
+        """Streams live, aggregated log data over a WebSocket."""
+        await websocket.accept()
+
+        async_logs = db.log(name).as_async()
+
+        # This simple aggregator function runs in the background and returns a
+        # JSON-serializable summary of the data in the current window.
+        def simple_aggregator(window):
+            return {"count": len(window), "latest_timestamp": window[-1]["timestamp"] if window else None}
+
+        live_stream = async_logs.live(
+            window=timedelta(seconds=window_seconds),
+            period=timedelta(seconds=period_seconds),
+            aggregator=simple_aggregator,
+        )
+
+        try:
+            async for summary in live_stream:
+                await websocket.send_json(summary)
+        except WebSocketDisconnect:
+            print(f"Client disconnected from log '{name}' live feed.")
+        finally:
+            # Cleanly close the underlying iterator and its background thread.
+            live_stream.close()
+
+
+    # --- Channels Endpoints ---
+
+    @app.post("/channels/{name}/publish", tags=["Channels"])
+    def publish_to_channel(name: str, payload: Any = Body(...)):
+        """Publishes a message to the specified channel."""
+        channel = db.channel(name)
+        channel.publish(payload)
+        return {"status": "ok"}
+
+    @app.websocket("/channels/{name}/subscribe", name="Channels")
+    async def subscribe_to_channel(websocket: WebSocket, name: str):
+        """Subscribes to a channel and streams messages over a WebSocket."""
+        await websocket.accept()
+
+        async_channel = db.channel(name).as_async()
+
+        try:
+            async with async_channel.subscribe() as listener:
+                async for message in listener.listen():
+                    await websocket.send_json(message)
+        except WebSocketDisconnect:
+            print(f"Client disconnected from channel '{name}' subscription.")
+
+
+    # --- Collections Endpoints ---
+
+    @app.get("/collections/{name}", tags=["Collections"])
+    def get_all_documents(name: str) -> List[dict]:
+        """Retrieves all documents in the collection."""
+        collection = db.collection(name)
+        return [doc.model_dump() for doc in collection]
+
+    @app.post("/collections/{name}/index", tags=["Collections"])
+    def index_document(name: str, req: IndexRequest):
+        """Indexes a document in the specified collection."""
+        collection = db.collection(name)
+        doc = Document(id=req.id, embedding=req.embedding, **req.metadata)
+        try:
+            collection.index(doc, fts=req.fts, fuzzy=req.fuzzy)
+            return {"status": "ok", "id": doc.id}
+        except TypeError as e:
+            if "faiss" in str(e):
+                raise HTTPException(status_code=501, detail="Vector indexing requires the '[faiss]' extra. Install with: pip install \"beaver-db[faiss]\"")
+            raise e
+
+    @app.post("/collections/{name}/search", tags=["Collections"])
+    def search_collection(name: str, req: SearchRequest) -> List[dict]:
+        """Performs a vector search on the collection."""
+        collection = db.collection(name)
+        try:
+            results = collection.search(vector=req.vector, top_k=req.top_k)
+            return [{"document": doc.model_dump(), "distance": dist} for doc, dist in results]
+        except TypeError as e:
+            if "faiss" in str(e):
+                raise HTTPException(status_code=501, detail="Vector search requires the '[faiss]' extra. Install with: pip install \"beaver-db[faiss]\"")
+            raise e
+
+    @app.post("/collections/{name}/match", tags=["Collections"])
+    def match_collection(name: str, req: MatchRequest) -> List[dict]:
+        """Performs a full-text or fuzzy search on the collection."""
+        collection = db.collection(name)
+        results = collection.match(query=req.query, on=req.on, top_k=req.top_k, fuzziness=req.fuzziness)
+        return [{"document": doc.model_dump(), "score": score} for doc, score in results]
+
+    @app.post("/collections/{name}/connect", tags=["Collections"])
+    def connect_documents(name: str, req: ConnectRequest):
+        """Creates a directed edge between two documents."""
+        collection = db.collection(name)
+        source_doc = Document(id=req.source_id)
+        target_doc = Document(id=req.target_id)
+        collection.connect(source=source_doc, target=target_doc, label=req.label, metadata=req.metadata)
+        return {"status": "ok"}
+
+    @app.get("/collections/{name}/{doc_id}/neighbors", tags=["Collections"])
+    def get_neighbors(name: str, doc_id: str, label: Optional[str] = None) -> List[dict]:
+        """Retrieves the neighboring documents for a given document."""
+        collection = db.collection(name)
+        doc = Document(id=doc_id)
+        neighbors = collection.neighbors(doc, label=label)
+        return [n.model_dump() for n in neighbors]
+
+    @app.post("/collections/{name}/{doc_id}/walk", tags=["Collections"])
+    def walk_graph(name: str, doc_id: str, req: WalkRequest) -> List[dict]:
+        """Performs a graph traversal (BFS) from a starting document."""
+        collection = db.collection(name)
+        source_doc = Document(id=doc_id)
+        results = collection.walk(source=source_doc, labels=req.labels, depth=req.depth, direction=req.direction)
+        return [doc.model_dump() for doc in results]
+
+    return app
+
+
+def serve(db_path: str, host: str, port: int):
+    """Initializes and runs the Uvicorn server."""
+    db = BeaverDB(db_path)
+    app = build(db)
+    uvicorn.run(app, host=host, port=port)

{beaver_db-0.17.4 → beaver_db-0.17.6}/pyproject.toml

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

beaver_db-0.17.4/beaver/server.py

@@ -1,132 +0,0 @@
-try:
-    from fastapi import FastAPI, HTTPException, Body
-    import uvicorn
-except ImportError:
-    raise ImportError(
-        "FastAPI and Uvicorn are required to serve the database. "
-        'Please install them with `pip install "beaver-db[server]"`'
-    )
-from typing import Any
-from .core import BeaverDB
-
-
-def build(db: BeaverDB) -> FastAPI:
-    """
-    Constructs a FastAPI application instance for a given BeaverDB instance.
-
-    Args:
-        db: An active BeaverDB instance.
-
-    Returns:
-        A FastAPI application with all endpoints configured.
-    """
-    app = FastAPI(
-        title="BeaverDB",
-        description="A RESTful API for a BeaverDB instance.",
-        version="0.1.0",
-    )
-
-    # --- Dicts Endpoints ---
-
-    @app.get("/dicts/{name}")
-    def get_all_dict_items(name: str) -> dict:
-        """Retrieves all key-value pairs in a dictionary."""
-        d = db.dict(name)
-        return {k: v for k, v in d.items()}
-
-    @app.get("/dicts/{name}/{key}")
-    def get_dict_item(name: str, key: str) -> Any:
-        """Retrieves the value for a specific key."""
-        d = db.dict(name)
-        try:
-            return d[key]
-        except KeyError:
-            raise HTTPException(status_code=404, detail=f"Key '{key}' not found in dictionary '{name}'")
-
-    @app.post("/dicts/{name}/{key}")
-    def set_dict_item(name: str, key: str, value: Any = Body(...)):
-        """Sets the value for a specific key."""
-        d = db.dict(name)
-        d[key] = value
-        return {"status": "ok"}
-
-    @app.delete("/dicts/{name}/{key}")
-    def delete_dict_item(name: str, key: str):
-        """Deletes a key-value pair."""
-        d = db.dict(name)
-        try:
-            del d[key]
-            return {"status": "ok"}
-        except KeyError:
-            raise HTTPException(status_code=404, detail=f"Key '{key}' not found in dictionary '{name}'")
-
-    # --- Lists Endpoints ---
-
-    @app.get("/lists/{name}")
-    def get_list(name: str) -> list:
-        """Retrieves all items in the list."""
-        l = db.list(name)
-        return l[:]
-
-    @app.get("/lists/{name}/{index}")
-    def get_list_item(name: str, index: int) -> Any:
-        """Retrieves the item at a specific index."""
-        l = db.list(name)
-        try:
-            return l[index]
-        except IndexError:
-            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
-
-    @app.post("/lists/{name}")
-    def push_list_item(name: str, value: Any = Body(...)):
-        """Adds an item to the end of the list."""
-        l = db.list(name)
-        l.push(value)
-        return {"status": "ok"}
-
-    @app.put("/lists/{name}/{index}")
-    def update_list_item(name: str, index: int, value: Any = Body(...)):
-        """Updates the item at a specific index."""
-        l = db.list(name)
-        try:
-            l[index] = value
-            return {"status": "ok"}
-        except IndexError:
-            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
-
-    @app.delete("/lists/{name}/{index}")
-    def delete_list_item(name: str, index: int):
-        """Deletes the item at a specific index."""
-        l = db.list(name)
-        try:
-            del l[index]
-            return {"status": "ok"}
-        except IndexError:
-            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
-
-    # TODO: Add endpoints for all BeaverDB modalities
-    # - Queues
-    # - Collections
-    # - Channels
-    # - Logs
-    # - Blobs
-
-    @app.get("/")
-    def read_root():
-        return {"message": "Welcome to the BeaverDB API"}
-
-    return app
-
-
-def serve(db_path: str, host: str, port: int):
-    """
-    Initializes a BeaverDB instance and runs a Uvicorn server for it.
-
-    Args:
-        db_path: The path to the SQLite database file.
-        host: The host to bind the server to.
-        port: The port to run the server on.
-    """
-    db = BeaverDB(db_path)
-    app = build(db)
-    uvicorn.run(app, host=host, port=port)