beaver-db 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of beaver-db might be problematic. Click here for more details.
- beaver/collections.py +18 -0
- beaver/core.py +30 -0
- beaver/queues.py +87 -0
- beaver_db-0.8.0.dist-info/METADATA +193 -0
- beaver_db-0.8.0.dist-info/RECORD +12 -0
- beaver_db-0.7.0.dist-info/METADATA +0 -197
- beaver_db-0.7.0.dist-info/RECORD +0 -11
- {beaver_db-0.7.0.dist-info → beaver_db-0.8.0.dist-info}/WHEEL +0 -0
- {beaver_db-0.7.0.dist-info → beaver_db-0.8.0.dist-info}/licenses/LICENSE +0 -0
- {beaver_db-0.7.0.dist-info → beaver_db-0.8.0.dist-info}/top_level.txt +0 -0
beaver/collections.py
CHANGED
|
@@ -151,6 +151,24 @@ class CollectionManager:
|
|
|
151
151
|
(self._name,),
|
|
152
152
|
)
|
|
153
153
|
|
|
154
|
+
def __iter__(self):
|
|
155
|
+
"""Returns an iterator over all documents in the collection."""
|
|
156
|
+
cursor = self._conn.cursor()
|
|
157
|
+
cursor.execute(
|
|
158
|
+
"SELECT item_id, item_vector, metadata FROM beaver_collections WHERE collection = ?",
|
|
159
|
+
(self._name,),
|
|
160
|
+
)
|
|
161
|
+
for row in cursor:
|
|
162
|
+
embedding = (
|
|
163
|
+
np.frombuffer(row["item_vector"], dtype=np.float32).tolist()
|
|
164
|
+
if row["item_vector"]
|
|
165
|
+
else None
|
|
166
|
+
)
|
|
167
|
+
yield Document(
|
|
168
|
+
id=row["item_id"], embedding=embedding, **json.loads(row["metadata"])
|
|
169
|
+
)
|
|
170
|
+
cursor.close()
|
|
171
|
+
|
|
154
172
|
def refresh(self):
|
|
155
173
|
"""Forces a rebuild of the in-memory ANN index from data in SQLite."""
|
|
156
174
|
cursor = self._conn.cursor()
|
beaver/core.py
CHANGED
|
@@ -7,6 +7,7 @@ from .dicts import DictManager
|
|
|
7
7
|
from .lists import ListManager
|
|
8
8
|
from .channels import ChannelManager
|
|
9
9
|
from .collections import CollectionManager
|
|
10
|
+
from .queues import QueueManager
|
|
10
11
|
|
|
11
12
|
|
|
12
13
|
class BeaverDB:
|
|
@@ -38,6 +39,27 @@ class BeaverDB:
|
|
|
38
39
|
self._create_edges_table()
|
|
39
40
|
self._create_versions_table()
|
|
40
41
|
self._create_dict_table()
|
|
42
|
+
self._create_priority_queue_table()
|
|
43
|
+
|
|
44
|
+
def _create_priority_queue_table(self):
|
|
45
|
+
"""Creates the priority queue table and its performance index."""
|
|
46
|
+
with self._conn:
|
|
47
|
+
self._conn.execute(
|
|
48
|
+
"""
|
|
49
|
+
CREATE TABLE IF NOT EXISTS beaver_priority_queues (
|
|
50
|
+
queue_name TEXT NOT NULL,
|
|
51
|
+
priority REAL NOT NULL,
|
|
52
|
+
timestamp REAL NOT NULL,
|
|
53
|
+
data TEXT NOT NULL
|
|
54
|
+
)
|
|
55
|
+
"""
|
|
56
|
+
)
|
|
57
|
+
self._conn.execute(
|
|
58
|
+
"""
|
|
59
|
+
CREATE INDEX IF NOT EXISTS idx_priority_queue_order
|
|
60
|
+
ON beaver_priority_queues (queue_name, priority ASC, timestamp ASC)
|
|
61
|
+
"""
|
|
62
|
+
)
|
|
41
63
|
|
|
42
64
|
def _create_dict_table(self):
|
|
43
65
|
"""Creates the namespaced dictionary table."""
|
|
@@ -164,8 +186,16 @@ class BeaverDB:
|
|
|
164
186
|
raise TypeError("List name must be a non-empty string.")
|
|
165
187
|
return ListManager(name, self._conn)
|
|
166
188
|
|
|
189
|
+
def queue(self, name: str) -> QueueManager:
|
|
190
|
+
"""Returns a wrapper object for interacting with a persistent priority queue."""
|
|
191
|
+
if not isinstance(name, str) or not name:
|
|
192
|
+
raise TypeError("Queue name must be a non-empty string.")
|
|
193
|
+
return QueueManager(name, self._conn)
|
|
194
|
+
|
|
167
195
|
def collection(self, name: str) -> CollectionManager:
|
|
168
196
|
"""Returns a wrapper for interacting with a document collection."""
|
|
197
|
+
if not isinstance(name, str) or not name:
|
|
198
|
+
raise TypeError("Collection name must be a non-empty string.")
|
|
169
199
|
return CollectionManager(name, self._conn)
|
|
170
200
|
|
|
171
201
|
def publish(self, channel_name: str, payload: Any):
|
beaver/queues.py
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import json
|
|
2
|
+
import sqlite3
|
|
3
|
+
import time
|
|
4
|
+
from typing import Any, NamedTuple
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
class QueueItem(NamedTuple):
|
|
8
|
+
"""A data class representing a single item retrieved from the queue."""
|
|
9
|
+
|
|
10
|
+
priority: float
|
|
11
|
+
timestamp: float
|
|
12
|
+
data: Any
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class QueueManager:
|
|
16
|
+
"""A wrapper providing a Pythonic interface to a persistent priority queue."""
|
|
17
|
+
|
|
18
|
+
def __init__(self, name: str, conn: sqlite3.Connection):
|
|
19
|
+
self._name = name
|
|
20
|
+
self._conn = conn
|
|
21
|
+
|
|
22
|
+
def put(self, data: Any, priority: float):
|
|
23
|
+
"""
|
|
24
|
+
Adds an item to the queue with a specific priority.
|
|
25
|
+
|
|
26
|
+
Args:
|
|
27
|
+
data: The JSON-serializable data to store.
|
|
28
|
+
priority: The priority of the item (lower numbers are higher priority).
|
|
29
|
+
"""
|
|
30
|
+
with self._conn:
|
|
31
|
+
self._conn.execute(
|
|
32
|
+
"INSERT INTO beaver_priority_queues (queue_name, priority, timestamp, data) VALUES (?, ?, ?, ?)",
|
|
33
|
+
(self._name, priority, time.time(), json.dumps(data)),
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
def get(self) -> QueueItem:
|
|
37
|
+
"""
|
|
38
|
+
Atomically retrieves and removes the highest-priority item from the queue.
|
|
39
|
+
|
|
40
|
+
Returns:
|
|
41
|
+
A QueueItem containing the data and its metadata.
|
|
42
|
+
|
|
43
|
+
Raises IndexError if queue is empty.
|
|
44
|
+
"""
|
|
45
|
+
with self._conn:
|
|
46
|
+
cursor = self._conn.cursor()
|
|
47
|
+
# The compound index on (queue_name, priority, timestamp) makes this query efficient.
|
|
48
|
+
cursor.execute(
|
|
49
|
+
"""
|
|
50
|
+
SELECT rowid, priority, timestamp, data
|
|
51
|
+
FROM beaver_priority_queues
|
|
52
|
+
WHERE queue_name = ?
|
|
53
|
+
ORDER BY priority ASC, timestamp ASC
|
|
54
|
+
LIMIT 1
|
|
55
|
+
""",
|
|
56
|
+
(self._name,),
|
|
57
|
+
)
|
|
58
|
+
result = cursor.fetchone()
|
|
59
|
+
|
|
60
|
+
if result is None:
|
|
61
|
+
raise IndexError("Queue is empty")
|
|
62
|
+
|
|
63
|
+
rowid, priority, timestamp, data = result
|
|
64
|
+
# Delete the retrieved item to ensure it's processed only once.
|
|
65
|
+
cursor.execute("DELETE FROM beaver_priority_queues WHERE rowid = ?", (rowid,))
|
|
66
|
+
|
|
67
|
+
return QueueItem(
|
|
68
|
+
priority=priority, timestamp=timestamp, data=json.loads(data)
|
|
69
|
+
)
|
|
70
|
+
|
|
71
|
+
def __len__(self) -> int:
|
|
72
|
+
"""Returns the current number of items in the queue."""
|
|
73
|
+
cursor = self._conn.cursor()
|
|
74
|
+
cursor.execute(
|
|
75
|
+
"SELECT COUNT(*) FROM beaver_priority_queues WHERE queue_name = ?",
|
|
76
|
+
(self._name,),
|
|
77
|
+
)
|
|
78
|
+
count = cursor.fetchone()[0]
|
|
79
|
+
cursor.close()
|
|
80
|
+
return count
|
|
81
|
+
|
|
82
|
+
def __nonzero__(self) -> bool:
|
|
83
|
+
"""Returns True if the queue is not empty."""
|
|
84
|
+
return len(self) > 0
|
|
85
|
+
|
|
86
|
+
def __repr__(self) -> str:
|
|
87
|
+
return f"QueueManager(name='{self._name}')"
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: beaver-db
|
|
3
|
+
Version: 0.8.0
|
|
4
|
+
Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
|
|
5
|
+
Requires-Python: >=3.13
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Requires-Dist: numpy>=2.3.3
|
|
9
|
+
Requires-Dist: scipy>=1.16.2
|
|
10
|
+
Dynamic: license-file
|
|
11
|
+
|
|
12
|
+
# beaver 🦫
|
|
13
|
+
|
|
14
|
+
A fast, single-file, multi-modal database for Python, built with the standard `sqlite3` library.
|
|
15
|
+
|
|
16
|
+
`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.
|
|
17
|
+
|
|
18
|
+
## Design Philosophy
|
|
19
|
+
|
|
20
|
+
`beaver` is built with a minimalistic philosophy for small, local use cases where a full-blown database server would be overkill.
|
|
21
|
+
|
|
22
|
+
- **Minimalistic & Zero-Dependency**: Uses only Python's standard libraries (`sqlite3`) and `numpy`/`scipy`.
|
|
23
|
+
- **Synchronous & Thread-Safe**: Designed for simplicity and safety in multi-threaded environments.
|
|
24
|
+
- **Built for Local Applications**: Perfect for local AI tools, RAG prototypes, chatbots, and desktop utilities that need persistent, structured data without network overhead.
|
|
25
|
+
- **Fast by Default**: It's built on SQLite, which is famously fast and reliable for local applications. The vector search is accelerated with an in-memory k-d tree.
|
|
26
|
+
- **Standard Relational Interface**: While `beaver` provides high-level features, you can always use the same SQLite file for normal relational tasks with standard SQL.
|
|
27
|
+
|
|
28
|
+
## Core Features
|
|
29
|
+
|
|
30
|
+
- **Synchronous Pub/Sub**: A simple, thread-safe, Redis-like publish-subscribe system for real-time messaging.
|
|
31
|
+
- **Namespaced Key-Value Dictionaries**: A Pythonic, dictionary-like interface for storing any JSON-serializable object within separate namespaces with optional TTL for cache implementations.
|
|
32
|
+
- **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
|
|
33
|
+
- **Persistent Priority Queue**: A high-performance, persistent queue that always returns the item with the highest priority, perfect for task management.
|
|
34
|
+
- **Efficient Vector Storage & Search**: Store vector embeddings and perform fast approximate nearest neighbor searches using an in-memory k-d tree.
|
|
35
|
+
- **Full-Text Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine.
|
|
36
|
+
- **Graph Traversal**: Create relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
|
|
37
|
+
- **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.
|
|
38
|
+
|
|
39
|
+
## Installation
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
pip install beaver-db
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Quickstart
|
|
46
|
+
|
|
47
|
+
Get up and running in 30 seconds. This example showcases a dictionary, a list, and full-text search in a single script.
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
from beaver import BeaverDB, Document
|
|
51
|
+
|
|
52
|
+
# 1. Initialize the database
|
|
53
|
+
db = BeaverDB("data.db")
|
|
54
|
+
|
|
55
|
+
# 2. Use a namespaced dictionary for app configuration
|
|
56
|
+
config = db.dict("app_config")
|
|
57
|
+
config["theme"] = "dark"
|
|
58
|
+
print(f"Theme set to: {config['theme']}")
|
|
59
|
+
|
|
60
|
+
# 3. Use a persistent list to manage a task queue
|
|
61
|
+
tasks = db.list("daily_tasks")
|
|
62
|
+
tasks.push("Write the project report")
|
|
63
|
+
tasks.push("Deploy the new feature")
|
|
64
|
+
print(f"First task is: {tasks[0]}")
|
|
65
|
+
|
|
66
|
+
# 4. Use a collection for document storage and search
|
|
67
|
+
articles = db.collection("articles")
|
|
68
|
+
doc = Document(
|
|
69
|
+
id="sqlite-001",
|
|
70
|
+
content="SQLite is a powerful embedded database ideal for local apps."
|
|
71
|
+
)
|
|
72
|
+
articles.index(doc)
|
|
73
|
+
|
|
74
|
+
# Perform a full-text search
|
|
75
|
+
results = articles.match(query="database")
|
|
76
|
+
top_doc, rank = results[0]
|
|
77
|
+
print(f"FTS Result: '{top_doc.content}'")
|
|
78
|
+
|
|
79
|
+
db.close()
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Things You Can Build with Beaver
|
|
83
|
+
|
|
84
|
+
Here are a few ideas to inspire your next project, showcasing how to combine Beaver's features to build powerful local applications.
|
|
85
|
+
|
|
86
|
+
### 1. AI Agent Task Management
|
|
87
|
+
|
|
88
|
+
Use a **persistent priority queue** to manage tasks for an AI agent. This ensures the agent always works on the most important task first, even if the application restarts.
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
tasks = db.queue("agent_tasks")
|
|
92
|
+
|
|
93
|
+
# Tasks are added with a priority (lower is higher)
|
|
94
|
+
tasks.put({"action": "summarize_news"}, priority=10)
|
|
95
|
+
tasks.put({"action": "respond_to_user"}, priority=1)
|
|
96
|
+
tasks.put({"action": "run_backup"}, priority=20)
|
|
97
|
+
|
|
98
|
+
# The agent retrieves the highest-priority task
|
|
99
|
+
next_task = tasks.get() # -> Returns the "respond_to_user" task
|
|
100
|
+
print(f"Agent's next task: {next_task.data['action']}")
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### 2. User Authentication and Profile Store
|
|
104
|
+
|
|
105
|
+
Use a **namespaced dictionary** to create a simple and secure user store. The key can be the username, and the value can be a dictionary containing the hashed password and other profile information.
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
users = db.dict("user_profiles")
|
|
109
|
+
|
|
110
|
+
# Create a new user
|
|
111
|
+
users["alice"] = {
|
|
112
|
+
"hashed_password": "...",
|
|
113
|
+
"email": "alice@example.com",
|
|
114
|
+
"permissions": ["read", "write"]
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
# Retrieve a user's profile
|
|
118
|
+
alice_profile = users.get("alice")
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### 3. Chatbot Conversation History
|
|
122
|
+
|
|
123
|
+
A **persistent list** is perfect for storing the history of a conversation. Each time the user or the bot sends a message, just `push` it to the list. This maintains a chronological record of the entire dialogue.
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
chat_history = db.list("conversation_with_user_123")
|
|
127
|
+
|
|
128
|
+
chat_history.push({"role": "user", "content": "Hello, Beaver!"})
|
|
129
|
+
chat_history.push({"role": "assistant", "content": "Hello! How can I help you today?"})
|
|
130
|
+
|
|
131
|
+
# Retrieve the full conversation
|
|
132
|
+
for message in chat_history:
|
|
133
|
+
print(f"{message['role']}: {message['content']}")
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### 4. Build a RAG (Retrieval-Augmented Generation) System
|
|
137
|
+
|
|
138
|
+
Combine **vector search** and **full-text search** to build a powerful RAG pipeline for your local documents.
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
# Get context for a user query like "fast python web frameworks"
|
|
142
|
+
vector_results = [doc for doc, _ in docs.search(vector=query_vector)]
|
|
143
|
+
text_results = [doc for doc, _ in docs.match(query="python web framework")]
|
|
144
|
+
|
|
145
|
+
# Combine and rerank for the best context
|
|
146
|
+
from beaver.collections import rerank
|
|
147
|
+
best_context = rerank(vector_results, text_results, weights=[0.6, 0.4])
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### 5. Caching for Expensive API Calls
|
|
151
|
+
|
|
152
|
+
Leverage a **dictionary with a TTL (Time-To-Live)** to cache the results of slow network requests. This can dramatically speed up your application and reduce your reliance on external services.
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
api_cache = db.dict("external_api_cache")
|
|
156
|
+
|
|
157
|
+
# Check the cache first
|
|
158
|
+
response = api_cache.get("weather_new_york")
|
|
159
|
+
if response is None:
|
|
160
|
+
# If not in cache, make the real API call
|
|
161
|
+
response = make_slow_weather_api_call("New York")
|
|
162
|
+
# Cache the result for 1 hour
|
|
163
|
+
api_cache.set("weather_new_york", response, ttl_seconds=3600)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## More Examples
|
|
167
|
+
|
|
168
|
+
For more in-depth examples, check out the scripts in the `examples/` directory:
|
|
169
|
+
|
|
170
|
+
- [`examples/kvstore.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/kvstore.py%5D\(https://www.google.com/search%3Fq%3Dexamples/kvstore.py\)): A comprehensive demo of the namespaced dictionary feature.
|
|
171
|
+
- [`examples/list.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/list.py%5D\(https://www.google.com/search%3Fq%3Dexamples/list.py\)): Shows the full capabilities of the persistent list, including slicing and in-place updates.
|
|
172
|
+
- [`examples/queue.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/queue.py%5D\(https://www.google.com/search%3Fq%3Dexamples/queue.py\)): A practical example of using the persistent priority queue for task management.
|
|
173
|
+
- [`examples/vector.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/vector.py%5D\(https://www.google.com/search%3Fq%3Dexamples/vector.py\)): Demonstrates how to index and search vector embeddings, including upserts.
|
|
174
|
+
- [`examples/fts.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/fts.py%5D\(https://www.google.com/search%3Fq%3Dexamples/fts.py\)): A detailed look at full-text search, including targeted searches on specific metadata fields.
|
|
175
|
+
- [`examples/graph.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/graph.py%5D\(https://www.google.com/search%3Fq%3Dexamples/graph.py\)): Shows how to create relationships between documents and perform multi-hop graph traversals.
|
|
176
|
+
- [`examples/pubsub.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/pubsub.py%5D\(https://www.google.com/search%3Fq%3Dexamples/pubsub.py\)): A demonstration of the synchronous, thread-safe publish/subscribe system.
|
|
177
|
+
- [`examples/cache.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/cache.py%5D\(https://www.google.com/search%3Fq%3Dexamples/cache.py\)): A practical example of using a dictionary with TTL as a cache for API calls.
|
|
178
|
+
- [`examples/rerank.py`](https://www.google.com/search?q=%5Bhttps://www.google.com/search%3Fq%3Dexamples/rerank.py%5D\(https://www.google.com/search%3Fq%3Dexamples/rerank.py\)): Shows how to combine results from vector and text search for more refined results.
|
|
179
|
+
|
|
180
|
+
## Roadmap
|
|
181
|
+
|
|
182
|
+
These are some of the features and improvements planned for future releases:
|
|
183
|
+
|
|
184
|
+
- **Fuzzy search**: Implement fuzzy matching capabilities for text search.
|
|
185
|
+
- **Faster ANN**: Explore integrating more advanced ANN libraries like `faiss` for improved vector search performance.
|
|
186
|
+
- **Improved Pub/Sub**: Fan-out implementation with a more Pythonic API.
|
|
187
|
+
- **Async API**: Comprehensive async support with on-demand wrappers for all collections.
|
|
188
|
+
|
|
189
|
+
Check out the [roadmap](https://www.google.com/search?q=roadmap.md) for a detailed list of upcoming features and design ideas.
|
|
190
|
+
|
|
191
|
+
## License
|
|
192
|
+
|
|
193
|
+
This project is licensed under the MIT License.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
beaver/__init__.py,sha256=-z5Gj6YKMOswpJOOn5Gej8z5i6k3c0Xs00DIYLA-bMI,75
|
|
2
|
+
beaver/channels.py,sha256=2lem2_yEFMc7cjdSx4FbFZQOaeT-HtbSvon3WYYRYzY,1952
|
|
3
|
+
beaver/collections.py,sha256=R4bVmP37s_ZnCkb3Jdck2H8dRvD3-ihFV4mEsA14YeE,15716
|
|
4
|
+
beaver/core.py,sha256=GpQ5HVJd2yBGq_RGC6TKlhRpGvNdFg88c59oAkltgqY,7904
|
|
5
|
+
beaver/dicts.py,sha256=y4z632XKWU29ekP_vdFSOP-MAG9Z8b79kBEHA88gO7E,4463
|
|
6
|
+
beaver/lists.py,sha256=jFlDWwyaYycG0ZFVm58rMChefUaVZhaP1UeQ-hVo3Sg,9082
|
|
7
|
+
beaver/queues.py,sha256=WKpBzlXr9Hp_rOKEs_Y1Tjyj_hWx6ql1uBRKBV7rw8w,2780
|
|
8
|
+
beaver_db-0.8.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
|
|
9
|
+
beaver_db-0.8.0.dist-info/METADATA,sha256=hB3ZWilwbPhfq64laoxiwxx99KfT-WIFOk1Nj2jK28c,9833
|
|
10
|
+
beaver_db-0.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
|
|
11
|
+
beaver_db-0.8.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
|
|
12
|
+
beaver_db-0.8.0.dist-info/RECORD,,
|
|
@@ -1,197 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: beaver-db
|
|
3
|
-
Version: 0.7.0
|
|
4
|
-
Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
|
|
5
|
-
Requires-Python: >=3.13
|
|
6
|
-
Description-Content-Type: text/markdown
|
|
7
|
-
License-File: LICENSE
|
|
8
|
-
Requires-Dist: numpy>=2.3.3
|
|
9
|
-
Requires-Dist: scipy>=1.16.2
|
|
10
|
-
Dynamic: license-file
|
|
11
|
-
|
|
12
|
-
# beaver 🦫
|
|
13
|
-
|
|
14
|
-

|
|
15
|
-

|
|
16
|
-

|
|
17
|
-
|
|
18
|
-
A fast, single-file, multi-modal database for Python, built with the standard `sqlite3` library.
|
|
19
|
-
|
|
20
|
-
`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.
|
|
21
|
-
|
|
22
|
-
## Design Philosophy
|
|
23
|
-
|
|
24
|
-
`beaver` is built with a minimalistic philosophy for small, local use cases where a full-blown database server would be overkill.
|
|
25
|
-
|
|
26
|
-
- **Minimalistic & Zero-Dependency**: Uses only Python's standard libraries (`sqlite3`) and `numpy`/`scipy`.
|
|
27
|
-
- **Synchronous & Thread-Safe**: Designed for simplicity and safety in multi-threaded environments.
|
|
28
|
-
- **Built for Local Applications**: Perfect for local AI tools, RAG prototypes, chatbots, and desktop utilities that need persistent, structured data without network overhead.
|
|
29
|
-
- **Fast by Default**: It's built on SQLite, which is famously fast and reliable for local applications. The vector search is accelerated with an in-memory k-d tree.
|
|
30
|
-
- **Standard Relational Interface**: While `beaver` provides high-level features, you can always use the same SQLite file for normal relational tasks with standard SQL.
|
|
31
|
-
|
|
32
|
-
## Core Features
|
|
33
|
-
|
|
34
|
-
- **Synchronous Pub/Sub**: A simple, thread-safe, Redis-like publish-subscribe system for real-time messaging.
|
|
35
|
-
- **Namespaced Key-Value Dictionaries**: A Pythonic, dictionary-like interface for storing any JSON-serializable object within separate namespaces with optional TTL for cache implementations.
|
|
36
|
-
- **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists, with all operations in constant time.
|
|
37
|
-
- **Efficient Vector Storage & Search**: Store vector embeddings and perform fast approximate nearest neighbor searches using an in-memory k-d tree.
|
|
38
|
-
- **Full-Text Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine.
|
|
39
|
-
- **Graph Traversal**: Create relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
|
|
40
|
-
- **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.
|
|
41
|
-
|
|
42
|
-
## Installation
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
pip install beaver-db
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
## Quickstart & API Guide
|
|
49
|
-
|
|
50
|
-
### Initialization
|
|
51
|
-
|
|
52
|
-
All you need to do is import and instantiate the `BeaverDB` class with a file path.
|
|
53
|
-
|
|
54
|
-
```python
|
|
55
|
-
from beaver import BeaverDB, Document
|
|
56
|
-
|
|
57
|
-
db = BeaverDB("my_application.db")
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
### Namespaced Dictionaries
|
|
61
|
-
|
|
62
|
-
Use `db.dict()` to get a dictionary-like object for a specific namespace. The value can be any JSON-encodable object.
|
|
63
|
-
|
|
64
|
-
```python
|
|
65
|
-
# Get a handle to the 'app_config' namespace
|
|
66
|
-
config = db.dict("app_config")
|
|
67
|
-
|
|
68
|
-
# Set values using standard dictionary syntax
|
|
69
|
-
config["theme"] = "dark"
|
|
70
|
-
config["user_id"] = 123
|
|
71
|
-
|
|
72
|
-
# Get a value
|
|
73
|
-
theme = config.get("theme")
|
|
74
|
-
print(f"Theme: {theme}") # Output: Theme: dark
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
### List Management
|
|
78
|
-
|
|
79
|
-
Get a list wrapper with `db.list()` and use Pythonic methods to manage it.
|
|
80
|
-
|
|
81
|
-
```python
|
|
82
|
-
tasks = db.list("daily_tasks")
|
|
83
|
-
tasks.push("Write the project report")
|
|
84
|
-
tasks.prepend("Plan the day's agenda")
|
|
85
|
-
print(f"The first task is: {tasks[0]}")
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
### Vector & Text Search
|
|
89
|
-
|
|
90
|
-
Store `Document` objects containing vector embeddings and metadata. When you index a document, its string fields are automatically made available for full-text search.
|
|
91
|
-
|
|
92
|
-
```python
|
|
93
|
-
# Get a handle to a collection
|
|
94
|
-
docs = db.collection("articles")
|
|
95
|
-
|
|
96
|
-
# Create and index a multi-modal document
|
|
97
|
-
doc = Document(
|
|
98
|
-
id="sql-001",
|
|
99
|
-
embedding=[0.8, 0.1, 0.1],
|
|
100
|
-
content="SQLite is a powerful embedded database ideal for local apps.",
|
|
101
|
-
author="John Smith"
|
|
102
|
-
)
|
|
103
|
-
docs.index(doc)
|
|
104
|
-
|
|
105
|
-
# 1. Perform a vector search to find semantically similar documents
|
|
106
|
-
query_vector = [0.7, 0.2, 0.2]
|
|
107
|
-
vector_results = docs.search(vector=query_vector, top_k=3)
|
|
108
|
-
top_doc, distance = vector_results[0]
|
|
109
|
-
print(f"Vector Search Result: {top_doc.content} (distance: {distance:.2f})")
|
|
110
|
-
|
|
111
|
-
# 2. Perform a full-text search to find documents with specific words
|
|
112
|
-
text_results = docs.match(query="database", top_k=3)
|
|
113
|
-
top_doc, rank = text_results[0]
|
|
114
|
-
print(f"Full-Text Search Result: {top_doc.content} (rank: {rank:.2f})")
|
|
115
|
-
|
|
116
|
-
# 3. Combine both vector and text search for refined results
|
|
117
|
-
from beaver.collections import rerank
|
|
118
|
-
combined_results = rerank([d for d,_ in vector_results], [d for d,_ in text_results], weights=[2,1])
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
### Graph Traversal
|
|
122
|
-
|
|
123
|
-
Create relationships between documents and traverse them.
|
|
124
|
-
|
|
125
|
-
```python
|
|
126
|
-
from beaver import WalkDirection
|
|
127
|
-
|
|
128
|
-
# Create documents
|
|
129
|
-
alice = Document(id="alice", name="Alice")
|
|
130
|
-
bob = Document(id="bob", name="Bob")
|
|
131
|
-
charlie = Document(id="charlie", name="Charlie")
|
|
132
|
-
|
|
133
|
-
# Index them
|
|
134
|
-
social_net = db.collection("social")
|
|
135
|
-
social_net.index(alice)
|
|
136
|
-
social_net.index(bob)
|
|
137
|
-
social_net.index(charlie)
|
|
138
|
-
|
|
139
|
-
# Create edges
|
|
140
|
-
social_net.connect(alice, bob, label="FOLLOWS")
|
|
141
|
-
social_net.connect(bob, charlie, label="FOLLOWS")
|
|
142
|
-
|
|
143
|
-
# Find direct neighbors
|
|
144
|
-
following = social_net.neighbors(alice, label="FOLLOWS")
|
|
145
|
-
print(f"Alice follows: {[p.id for p in following]}")
|
|
146
|
-
|
|
147
|
-
# Perform a multi-hop walk to find friends of friends
|
|
148
|
-
foaf = social_net.walk(
|
|
149
|
-
source=alice,
|
|
150
|
-
labels=["FOLLOWS"],
|
|
151
|
-
depth=2,
|
|
152
|
-
direction=WalkDirection.OUTGOING,
|
|
153
|
-
)
|
|
154
|
-
print(f"Alice's extended network: {[p.id for p in foaf]}")
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
### Synchronous Pub/Sub
|
|
158
|
-
|
|
159
|
-
Publish events from one part of your app and listen in another using threads.
|
|
160
|
-
|
|
161
|
-
```python
|
|
162
|
-
import threading
|
|
163
|
-
|
|
164
|
-
def listener():
|
|
165
|
-
for message in db.subscribe("system_events"):
|
|
166
|
-
print(f"LISTENER: Received -> {message}")
|
|
167
|
-
if message.get("event") == "shutdown":
|
|
168
|
-
break
|
|
169
|
-
|
|
170
|
-
def publisher():
|
|
171
|
-
db.publish("system_events", {"event": "user_login", "user": "alice"})
|
|
172
|
-
db.publish("system_events", {"event": "shutdown"})
|
|
173
|
-
|
|
174
|
-
# Run them concurrently
|
|
175
|
-
listener_thread = threading.Thread(target=listener)
|
|
176
|
-
publisher_thread = threading.Thread(target=publisher)
|
|
177
|
-
listener_thread.start()
|
|
178
|
-
publisher_thread.start()
|
|
179
|
-
listener_thread.join()
|
|
180
|
-
publisher_thread.join()
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
## Roadmap
|
|
184
|
-
|
|
185
|
-
These are some of the features and improvements planned for future releases:
|
|
186
|
-
|
|
187
|
-
- **Fuzzy search**: Implement fuzzy matching capabilities for text search.
|
|
188
|
-
- **Faster ANN**: Explore integrating more advanced ANN libraries like `faiss` for improved vector search performance.
|
|
189
|
-
- **Priority Queues**: Introduce a priority queue data structure for task management.
|
|
190
|
-
- **Improved Pub/Sub**: Fan-out implementation with a more Pythonic API.
|
|
191
|
-
- **Async API**: Comprehensive async support with on-demand wrappers for all collections.
|
|
192
|
-
|
|
193
|
-
Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
|
|
194
|
-
|
|
195
|
-
## License
|
|
196
|
-
|
|
197
|
-
This project is licensed under the MIT License.
|
beaver_db-0.7.0.dist-info/RECORD
DELETED
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
beaver/__init__.py,sha256=-z5Gj6YKMOswpJOOn5Gej8z5i6k3c0Xs00DIYLA-bMI,75
|
|
2
|
-
beaver/channels.py,sha256=2lem2_yEFMc7cjdSx4FbFZQOaeT-HtbSvon3WYYRYzY,1952
|
|
3
|
-
beaver/collections.py,sha256=htlOnjQl8YwjNKkDsK74c805PQQO9Zq2kIhnKxekLds,15064
|
|
4
|
-
beaver/core.py,sha256=K_abD1RiAMT1jYv6T11fpckNljjqcotu3lkLkCz0bHg,6670
|
|
5
|
-
beaver/dicts.py,sha256=y4z632XKWU29ekP_vdFSOP-MAG9Z8b79kBEHA88gO7E,4463
|
|
6
|
-
beaver/lists.py,sha256=jFlDWwyaYycG0ZFVm58rMChefUaVZhaP1UeQ-hVo3Sg,9082
|
|
7
|
-
beaver_db-0.7.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
|
|
8
|
-
beaver_db-0.7.0.dist-info/METADATA,sha256=MmlUva8ILoEMDdXyoujG1N-iGwMSScFuEx3qqF_vGyU,7196
|
|
9
|
-
beaver_db-0.7.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
|
|
10
|
-
beaver_db-0.7.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
|
|
11
|
-
beaver_db-0.7.0.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|
|
File without changes
|