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 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
- ![PyPI - Downloads](https://img.shields.io/pypi/dm/beaver-db)
15
- ![PyPI](https://img.shields.io/pypi/v/beaver-db)
16
- ![License](https://img.shields.io/github/license/apiad/beaver)
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.
@@ -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,,