beaver-db 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

beaver/core.py

@@ -29,56 +29,82 @@ class BeaverDB:
         self._create_kv_table()
         self._create_list_table()
         self._create_collections_table()
+        self._create_fts_table()  # <-- Nueva llamada
+
+    def _create_fts_table(self):
+        """Creates the virtual FTS table for full text search."""
+        with self._conn:
+            self._conn.execute(
+                """
+                CREATE VIRTUAL TABLE IF NOT EXISTS beaver_fts_index USING fts5(
+                    collection,
+                    item_id,
+                    field_path,
+                    field_content,
+                    tokenize = 'porter'
+                )
+            """
+            )
 
     def _create_pubsub_table(self):
         """Creates the pub/sub log table if it doesn't exist."""
         with self._conn:
-            self._conn.execute("""
+            self._conn.execute(
+                """
                 CREATE TABLE IF NOT EXISTS beaver_pubsub_log (
                     timestamp REAL PRIMARY KEY,
                     channel_name TEXT NOT NULL,
                     message_payload TEXT NOT NULL
                 )
-            """)
-            self._conn.execute("""
+            """
+            )
+            self._conn.execute(
+                """
                 CREATE INDEX IF NOT EXISTS idx_pubsub_channel_timestamp
                 ON beaver_pubsub_log (channel_name, timestamp)
-            """)
+            """
+            )
 
     def _create_kv_table(self):
         """Creates the key-value store table if it doesn't exist."""
         with self._conn:
-            self._conn.execute("""
+            self._conn.execute(
+                """
                 CREATE TABLE IF NOT EXISTS _beaver_kv_store (
                     key TEXT PRIMARY KEY,
                     value TEXT NOT NULL
                 )
-            """)
+            """
+            )
 
     def _create_list_table(self):
         """Creates the lists table if it doesn't exist."""
         with self._conn:
-            self._conn.execute("""
+            self._conn.execute(
+                """
                 CREATE TABLE IF NOT EXISTS beaver_lists (
                     list_name TEXT NOT NULL,
                     item_order REAL NOT NULL,
                     item_value TEXT NOT NULL,
                     PRIMARY KEY (list_name, item_order)
                 )
-            """)
+            """
+            )
 
     def _create_collections_table(self):
         """Creates the collections table if it doesn't exist."""
         with self._conn:
-            self._conn.execute("""
+            self._conn.execute(
+                """
                 CREATE TABLE IF NOT EXISTS beaver_collections (
                     collection TEXT NOT NULL,
                     item_id TEXT NOT NULL,
-                    item_vector BLOB NOT NULL,
+                    item_vector BLOB,
                     metadata TEXT,
                     PRIMARY KEY (collection, item_id)
                 )
-            """)
+            """
+            )
 
     def close(self):
         """Closes the database connection."""
@@ -110,7 +136,7 @@ class BeaverDB:
         with self._conn:
             self._conn.execute(
                 "INSERT OR REPLACE INTO _beaver_kv_store (key, value) VALUES (?, ?)",
-                (key, json_value)
+                (key, json_value),
             )
 
     def get(self, key: str) -> Any:
@@ -136,7 +162,7 @@ class BeaverDB:
         cursor.close()
 
         if result:
-            return json.loads(result['value'])
+            return json.loads(result["value"])
         return None
 
     # --- List Methods ---
@@ -173,16 +199,14 @@ class BeaverDB:
         except TypeError as e:
             raise TypeError("Message payload must be JSON-serializable.") from e
 
-        await asyncio.to_thread(
-            self._write_publish_to_db, channel_name, json_payload
-        )
+        await asyncio.to_thread(self._write_publish_to_db, channel_name, json_payload)
 
     def _write_publish_to_db(self, channel_name, json_payload):
         """The synchronous part of the publish operation."""
         with self._conn:
             self._conn.execute(
                 "INSERT INTO beaver_pubsub_log (timestamp, channel_name, message_payload) VALUES (?, ?, ?)",
-                (time.time(), channel_name, json_payload)
+                (time.time(), channel_name, json_payload),
             )
 
     def subscribe(self, channel_name: str) -> "Subscriber":
@@ -202,7 +226,9 @@ class ListWrapper:
     def __len__(self) -> int:
         """Returns the number of items in the list (e.g., `len(my_list)`)."""
         cursor = self._conn.cursor()
-        cursor.execute("SELECT COUNT(*) FROM beaver_lists WHERE list_name = ?", (self._name,))
+        cursor.execute(
+            "SELECT COUNT(*) FROM beaver_lists WHERE list_name = ?", (self._name,)
+        )
         count = cursor.fetchone()[0]
         cursor.close()
         return count
@@ -223,9 +249,9 @@ class ListWrapper:
             cursor = self._conn.cursor()
             cursor.execute(
                 "SELECT item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT ? OFFSET ?",
-                (self._name, limit, start)
+                (self._name, limit, start),
             )
-            results = [json.loads(row['item_value']) for row in cursor.fetchall()]
+            results = [json.loads(row["item_value"]) for row in cursor.fetchall()]
             cursor.close()
             return results
 
@@ -239,11 +265,11 @@ class ListWrapper:
             cursor = self._conn.cursor()
             cursor.execute(
                 "SELECT item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT 1 OFFSET ?",
-                (self._name, offset)
+                (self._name, offset),
             )
             result = cursor.fetchone()
             cursor.close()
-            return json.loads(result['item_value']) if result else None
+            return json.loads(result["item_value"]) if result else None
 
         else:
             raise TypeError("List indices must be integers or slices.")
@@ -253,7 +279,7 @@ class ListWrapper:
         cursor = self._conn.cursor()
         cursor.execute(
             "SELECT item_order FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT 1 OFFSET ?",
-            (self._name, index)
+            (self._name, index),
         )
         result = cursor.fetchone()
         cursor.close()
@@ -267,26 +293,32 @@ class ListWrapper:
         """Pushes an item to the end of the list."""
         with self._conn:
             cursor = self._conn.cursor()
-            cursor.execute("SELECT MAX(item_order) FROM beaver_lists WHERE list_name = ?", (self._name,))
+            cursor.execute(
+                "SELECT MAX(item_order) FROM beaver_lists WHERE list_name = ?",
+                (self._name,),
+            )
             max_order = cursor.fetchone()[0] or 0.0
             new_order = max_order + 1.0
 
             cursor.execute(
                 "INSERT INTO beaver_lists (list_name, item_order, item_value) VALUES (?, ?, ?)",
-                (self._name, new_order, json.dumps(value))
+                (self._name, new_order, json.dumps(value)),
             )
 
     def prepend(self, value: Any):
         """Prepends an item to the beginning of the list."""
         with self._conn:
             cursor = self._conn.cursor()
-            cursor.execute("SELECT MIN(item_order) FROM beaver_lists WHERE list_name = ?", (self._name,))
+            cursor.execute(
+                "SELECT MIN(item_order) FROM beaver_lists WHERE list_name = ?",
+                (self._name,),
+            )
             min_order = cursor.fetchone()[0] or 0.0
             new_order = min_order - 1.0
 
             cursor.execute(
                 "INSERT INTO beaver_lists (list_name, item_order, item_value) VALUES (?, ?, ?)",
-                (self._name, new_order, json.dumps(value))
+                (self._name, new_order, json.dumps(value)),
             )
 
     def insert(self, index: int, value: Any):
@@ -308,7 +340,7 @@ class ListWrapper:
         with self._conn:
             self._conn.execute(
                 "INSERT INTO beaver_lists (list_name, item_order, item_value) VALUES (?, ?, ?)",
-                (self._name, new_order, json.dumps(value))
+                (self._name, new_order, json.dumps(value)),
             )
 
     def pop(self) -> Any:
@@ -317,14 +349,16 @@ class ListWrapper:
             cursor = self._conn.cursor()
             cursor.execute(
                 "SELECT rowid, item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order DESC LIMIT 1",
-                (self._name,)
+                (self._name,),
             )
             result = cursor.fetchone()
             if not result:
                 return None
 
             rowid_to_delete, value_to_return = result
-            cursor.execute("DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,))
+            cursor.execute(
+                "DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,)
+            )
             return json.loads(value_to_return)
 
     def deque(self) -> Any:
@@ -333,14 +367,16 @@ class ListWrapper:
             cursor = self._conn.cursor()
             cursor.execute(
                 "SELECT rowid, item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT 1",
-                (self._name,)
+                (self._name,),
             )
             result = cursor.fetchone()
             if not result:
                 return None
 
             rowid_to_delete, value_to_return = result
-            cursor.execute("DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,))
+            cursor.execute(
+                "DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,)
+            )
             return json.loads(value_to_return)
 
 
@@ -350,7 +386,9 @@ class Subscriber(AsyncIterator):
     Designed to be used with 'async with'.
     """
 
-    def __init__(self, conn: sqlite3.Connection, channel_name: str, poll_interval: float = 0.1):
+    def __init__(
+        self, conn: sqlite3.Connection, channel_name: str, poll_interval: float = 0.1
+    ):
         self._conn = conn
         self._channel = channel_name
         self._poll_interval = poll_interval
@@ -362,9 +400,7 @@ class Subscriber(AsyncIterator):
         """Background task that polls the database for new messages."""
         while True:
             try:
-                new_messages = await asyncio.to_thread(
-                    self._fetch_new_messages_from_db
-                )
+                new_messages = await asyncio.to_thread(self._fetch_new_messages_from_db)
                 if new_messages:
                     for msg in new_messages:
                         payload = json.loads(msg["message_payload"])
@@ -382,7 +418,7 @@ class Subscriber(AsyncIterator):
         cursor = self._conn.cursor()
         cursor.execute(
             "SELECT timestamp, message_payload FROM beaver_pubsub_log WHERE channel_name = ? AND timestamp > ? ORDER BY timestamp ASC",
-            (self._channel, self._last_seen_timestamp)
+            (self._channel, self._last_seen_timestamp),
         )
         results = cursor.fetchall()
         cursor.close()
@@ -409,12 +445,21 @@ class Subscriber(AsyncIterator):
 
 class Document:
     """A data class for a vector and its metadata, with a unique ID."""
-    def __init__(self, embedding: list[float], id: str|None = None, **metadata):
-        if not isinstance(embedding, list) or not all(isinstance(x, (int, float)) for x in embedding):
-            raise TypeError("Embedding must be a list of numbers.")
 
+    def __init__(
+        self, embedding: list[float] | None = None, id: str | None = None, **metadata
+    ):
         self.id = id or str(uuid.uuid4())
-        self.embedding = np.array(embedding, dtype=np.float32)
+
+        if embedding is None:
+            self.embedding = None
+        else:
+            if not isinstance(embedding, list) or not all(
+                isinstance(x, (int, float)) for x in embedding
+            ):
+                raise TypeError("Embedding must be a list of numbers.")
+
+            self.embedding = np.array(embedding, dtype=np.float32)
 
         for key, value in metadata.items():
             setattr(self, key, value)
@@ -423,42 +468,74 @@ class Document:
         """Serializes metadata to a dictionary."""
         metadata = self.__dict__.copy()
         # Exclude internal attributes from the metadata payload
-        metadata.pop('embedding', None)
-        metadata.pop('id', None)
+        metadata.pop("embedding", None)
+        metadata.pop("id", None)
         return metadata
 
     def __repr__(self):
-        metadata_str = ', '.join(f"{k}={v!r}" for k, v in self.to_dict().items())
+        metadata_str = ", ".join(f"{k}={v!r}" for k, v in self.to_dict().items())
         return f"Document(id='{self.id}', {metadata_str})"
 
 
 class CollectionWrapper:
     """A wrapper for vector collection operations with upsert logic."""
+
     def __init__(self, name: str, conn: sqlite3.Connection):
         self._name = name
         self._conn = conn
 
-    def index(self, document: Document):
-        """
-        Indexes a Document, performing an upsert based on the document's ID.
-        If the ID exists, the record is replaced.
-        If the ID is new (or auto-generated), a new record is inserted.
+    # Dentro de la clase CollectionWrapper en beaver/core.py
 
-        Args:
-            document: The Document object to index.
+    def _flatten_metadata(self, metadata: dict, prefix: str = "") -> dict[str, str]:
+        """
+        Aplana un diccionario anidado y filtra solo los valores de tipo string.
+        Ejemplo: {'a': {'b': 'c'}} -> {'a__b': 'c'}
+        """
+        flat_dict = {}
+        for key, value in metadata.items():
+            new_key = f"{prefix}__{key}" if prefix else key
+            if isinstance(value, dict):
+                flat_dict.update(self._flatten_metadata(value, new_key))
+            elif isinstance(value, str):
+                flat_dict[new_key] = value
+        return flat_dict
+
+    def index(self, document: Document, *, fts: bool = True):
+        """
+        Indexa un Document, realizando un upsert y actualizando el índice FTS.
         """
         with self._conn:
+            if fts:
+                self._conn.execute(
+                    "DELETE FROM beaver_fts_index WHERE collection = ? AND item_id = ?",
+                    (self._name, document.id),
+                )
+
+                string_fields = self._flatten_metadata(document.to_dict())
+
+                if string_fields:
+                    fts_data = [
+                        (self._name, document.id, path, content)
+                        for path, content in string_fields.items()
+                    ]
+                    self._conn.executemany(
+                        "INSERT INTO beaver_fts_index (collection, item_id, field_path, field_content) VALUES (?, ?, ?, ?)",
+                        fts_data,
+                    )
+
             self._conn.execute(
                 "INSERT OR REPLACE INTO beaver_collections (collection, item_id, item_vector, metadata) VALUES (?, ?, ?, ?)",
                 (
                     self._name,
                     document.id,
-                    document.embedding.tobytes(),
-                    json.dumps(document.to_dict())
-                )
+                    document.embedding.tobytes() if document.embedding is not None else None,
+                    json.dumps(document.to_dict()),
+                ),
             )
 
-    def search(self, vector: list[float], top_k: int = 10) -> list[tuple[Document, float]]:
+    def search(
+        self, vector: list[float], top_k: int = 10
+    ) -> list[tuple[Document, float]]:
         """
         Performs a vector search and returns Document objects.
         """
@@ -467,7 +544,7 @@ class CollectionWrapper:
         cursor = self._conn.cursor()
         cursor.execute(
             "SELECT item_id, item_vector, metadata FROM beaver_collections WHERE collection = ?",
-            (self._name,)
+            (self._name,),
         )
 
         all_docs_data = cursor.fetchall()
@@ -478,9 +555,12 @@ class CollectionWrapper:
 
         results = []
         for row in all_docs_data:
-            doc_id = row['item_id']
-            embedding = np.frombuffer(row['item_vector'], dtype=np.float32).tolist()
-            metadata = json.loads(row['metadata'])
+            if row["item_vector"] is None:
+                continue  # Skip documents without embeddings
+
+            doc_id = row["item_id"]
+            embedding = np.frombuffer(row["item_vector"], dtype=np.float32).tolist()
+            metadata = json.loads(row["metadata"])
 
             distance = np.linalg.norm(embedding - query_vector)
 
@@ -490,3 +570,69 @@ class CollectionWrapper:
 
         results.sort(key=lambda x: x[1])
         return results[:top_k]
+
+    def match(
+        self, query: str, on_field: str | None = None, top_k: int = 10
+    ) -> list[tuple[Document, float]]:
+        """
+        Realiza una búsqueda de texto completo en los campos de metadatos indexados.
+
+        Args:
+            query: La expresión de búsqueda (ej. "gato", "perro OR conejo").
+            on_field: Opcional, el campo específico donde buscar (ej. "details__title").
+            top_k: El número máximo de resultados a devolver.
+
+        Returns:
+            Una lista de tuplas (Documento, puntuación_de_relevancia).
+        """
+        cursor = self._conn.cursor()
+
+        sql_query = """
+            SELECT
+                t1.item_id, t1.item_vector, t1.metadata, fts.rank
+            FROM beaver_collections AS t1
+            JOIN (
+                SELECT DISTINCT item_id, rank
+                FROM beaver_fts_index
+                WHERE beaver_fts_index MATCH ?
+                ORDER BY rank
+                LIMIT ?
+            ) AS fts ON t1.item_id = fts.item_id
+            WHERE t1.collection = ?
+            ORDER BY fts.rank
+        """
+
+        params = []
+        field_filter_sql = ""
+
+        if on_field:
+            field_filter_sql = "AND field_path = ?"
+            params.append(on_field)
+        else:
+            # Búsqueda en todos los campos
+            params.append(query)
+
+        sql_query = sql_query.format(field_filter_sql)
+        params.extend([top_k, self._name])
+
+        cursor.execute(sql_query, tuple(params))
+
+        results = []
+        for row in cursor.fetchall():
+            doc_id = row["item_id"]
+
+            if row["item_vector"] is None:
+                embedding = None
+            else:
+                embedding = np.frombuffer(row["item_vector"], dtype=np.float32).tolist()
+
+            metadata = json.loads(row["metadata"])
+            rank = row["rank"]
+
+            doc = Document(id=doc_id, embedding=embedding, **metadata)
+            results.append((doc, rank))
+
+        results.sort(key=lambda x: x[1])
+        cursor.close()
+
+        return results

{beaver_db-0.3.0.dist-info → beaver_db-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.3.0
+Version: 0.4.0
 Summary: Asynchronous, embedded, modern DB based on SQLite.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown

beaver_db-0.4.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+beaver/__init__.py,sha256=uTPhMNDjw41YTWQN8NTLbovudfp8RIwcqbZ5XtYIuJA,36
+beaver/core.py,sha256=i2rBoUM1rq_j1xM3w4xW4c9e2eI8Ce6BeJ8rE8jQ-fI,21928
+beaver_db-0.4.0.dist-info/METADATA,sha256=7VzqxHKU-Ft1QVAfVvywt4e50C3QWxS7FUpKIaQEJKk,4865
+beaver_db-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+beaver_db-0.4.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
+beaver_db-0.4.0.dist-info/RECORD,,

beaver_db-0.3.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-beaver/__init__.py,sha256=uTPhMNDjw41YTWQN8NTLbovudfp8RIwcqbZ5XtYIuJA,36
-beaver/core.py,sha256=I-_i8AshcNor1OZxoEtNjzLXCy1Byuxvo84y9K4AV_Q,17518
-beaver_db-0.3.0.dist-info/METADATA,sha256=_Hy3Fq64IDahqm3K0vuPvvZRTmtO0sU-tEGlmEjLNpE,4865
-beaver_db-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-beaver_db-0.3.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
-beaver_db-0.3.0.dist-info/RECORD,,