beaver-db 0.15.0__py3-none-any.whl → 0.16.0__py3-none-any.whl

beaver/core.py

@@ -8,6 +8,7 @@ from .channels import ChannelManager
 from .collections import CollectionManager, Document
 from .dicts import DictManager
 from .lists import ListManager
+from .logs import LogManager
 from .queues import QueueManager
 
 
@@ -51,11 +52,31 @@ class BeaverDB:
             self._create_edges_table()
             self._create_fts_table()
             self._create_list_table()
+            self._create_logs_table()
             self._create_priority_queue_table()
             self._create_pubsub_table()
             self._create_trigrams_table()
             self._create_versions_table()
 
+    def _create_logs_table(self):
+        """Creates the table for time-indexed logs."""
+        self._conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS beaver_logs (
+                log_name TEXT NOT NULL,
+                timestamp REAL NOT NULL,
+                data TEXT NOT NULL,
+                PRIMARY KEY (log_name, timestamp)
+            )
+            """
+        )
+        self._conn.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_logs_timestamp
+            ON beaver_logs (log_name, timestamp)
+            """
+        )
+
     def _create_blobs_table(self):
         """Creates the table for storing named blobs."""
         self._conn.execute(
@@ -343,3 +364,16 @@ class BeaverDB:
             raise TypeError("Blob store name must be a non-empty string.")
 
         return BlobManager(name, self._conn, model)
+
+    def log[T](self, name: str, model: type[T] | None = None) -> LogManager[T]:
+        """
+        Returns a wrapper for interacting with a named, time-indexed log.
+        If model is defined, it should be a type used for automatic (de)serialization.
+        """
+        if not isinstance(name, str) or not name:
+            raise TypeError("Log name must be a non-empty string.")
+
+        if model and not isinstance(model, JsonSerializable):
+            raise TypeError("The model parameter must be a JsonSerializable class.")
+
+        return LogManager(name, self._conn, self._db_path, model)

beaver/logs.py

@@ -0,0 +1,278 @@
+import asyncio
+import collections
+import json
+import sqlite3
+import threading
+import time
+from datetime import datetime, timedelta, timezone
+from queue import Empty, Queue
+from typing import Any, AsyncIterator, Callable, Iterator, Type, TypeVar
+
+from .types import JsonSerializable
+
+
+# A special message object used to signal the iterator to gracefully shut down.
+_SHUTDOWN_SENTINEL = object()
+
+
+class LiveIterator[T,R]:
+    """
+    A thread-safe, blocking iterator that yields aggregated results from a
+    rolling window of log data.
+    """
+
+    def __init__(
+        self,
+        db_path: str,
+        log_name: str,
+        window: timedelta,
+        period: timedelta,
+        aggregator: Callable[[list[T]], R],
+        deserializer: Callable[[str], T],
+    ):
+        self._db_path = db_path
+        self._log_name = log_name
+        self._window_duration_seconds = window.total_seconds()
+        self._sampling_period_seconds = period.total_seconds()
+        self._aggregator = aggregator
+        self._deserializer = deserializer
+        self._queue: Queue = Queue()
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def _polling_loop(self):
+        """The main loop for the background thread that queries and aggregates data."""
+        # Each thread needs its own database connection.
+        thread_conn = sqlite3.connect(self._db_path, check_same_thread=False)
+        thread_conn.row_factory = sqlite3.Row
+
+        window_deque: collections.deque[tuple[float, T]] = collections.deque()
+        last_seen_timestamp = 0.0
+
+        # --- Initial window population ---
+        now = datetime.now(timezone.utc).timestamp()
+        start_time = now - self._window_duration_seconds
+        cursor = thread_conn.cursor()
+        cursor.execute(
+            "SELECT timestamp, data FROM beaver_logs WHERE log_name = ? AND timestamp >= ? ORDER BY timestamp ASC",
+            (self._log_name, start_time),
+        )
+        for row in cursor:
+            ts, data_str = row
+            window_deque.append((ts, self._deserializer(data_str)))
+            last_seen_timestamp = max(last_seen_timestamp, ts)
+
+        # Yield the first result
+        try:
+            initial_result = self._aggregator([item[1] for item in window_deque])
+            self._queue.put(initial_result)
+        except Exception as e:
+            # Propagate aggregator errors to the main thread
+            self._queue.put(e)
+
+        # --- Continuous polling loop ---
+        while not self._stop_event.is_set():
+            time.sleep(self._sampling_period_seconds)
+
+            # Fetch only new data since the last check
+            cursor.execute(
+                "SELECT timestamp, data FROM beaver_logs WHERE log_name = ? AND timestamp > ? ORDER BY timestamp ASC",
+                (self._log_name, last_seen_timestamp),
+            )
+            for row in cursor:
+                ts, data_str = row
+                window_deque.append((ts, self._deserializer(data_str)))
+                last_seen_timestamp = max(last_seen_timestamp, ts)
+
+            # Evict old data from the left of the deque
+            now = datetime.now(timezone.utc).timestamp()
+            eviction_time = now - self._window_duration_seconds
+            while window_deque and window_deque[0][0] < eviction_time:
+                window_deque.popleft()
+
+            # Run aggregator and yield the new result
+            try:
+                new_result = self._aggregator([item[1] for item in window_deque])
+                self._queue.put(new_result)
+            except Exception as e:
+                self._queue.put(e)
+
+        thread_conn.close()
+
+    def __iter__(self) -> "LiveIterator[T,R]":
+        self._thread = threading.Thread(target=self._polling_loop, daemon=True)
+        self._thread.start()
+        return self
+
+    def __next__(self) -> R:
+        result = self._queue.get()
+        if result is _SHUTDOWN_SENTINEL:
+            raise StopIteration
+        if isinstance(result, Exception):
+            # If the background thread put an exception in the queue, re-raise it
+            raise result
+        return result
+
+    def close(self):
+        """Stops the background polling thread."""
+        self._stop_event.set()
+        self._queue.put(_SHUTDOWN_SENTINEL)
+        if self._thread:
+            self._thread.join()
+
+
+class AsyncLiveIterator[T,R]:
+    """An async wrapper for the LiveIterator."""
+
+    def __init__(self, sync_iterator: LiveIterator[T,R]):
+        self._sync_iterator = sync_iterator
+
+    async def __anext__(self) -> R:
+        try:
+            return await asyncio.to_thread(self._sync_iterator.__next__)
+        except StopIteration:
+            raise StopAsyncIteration
+
+    def __aiter__(self) -> "AsyncLiveIterator[T,R]":
+        # The synchronous iterator's __iter__ method starts the thread.
+        # This is non-blocking, so it's safe to call directly.
+        self._sync_iterator.__iter__()
+        return self
+
+    def close(self):
+        self._sync_iterator.close()
+
+
+class AsyncLogManager[T]:
+    """An async-compatible wrapper for the LogManager."""
+
+    def __init__(self, sync_manager: "LogManager[T]"):
+        self._sync_manager = sync_manager
+
+    async def log(self, data: T, timestamp: datetime | None = None) -> None:
+        """Asynchronously adds a new entry to the log."""
+        await asyncio.to_thread(self._sync_manager.log, data, timestamp)
+
+    async def range(self, start: datetime, end: datetime) -> list[T]:
+        """Asynchronously retrieves all log entries within a specific time window."""
+        return await asyncio.to_thread(self._sync_manager.range, start, end)
+
+    def live[R](
+        self,
+        window: timedelta,
+        period: timedelta,
+        aggregator: Callable[[list[T]], R],
+    ) -> AsyncIterator[R]:
+        """Returns an async, infinite iterator for real-time log analysis."""
+        sync_iterator = self._sync_manager.live(
+            window, period, aggregator
+        )
+        return AsyncLiveIterator(sync_iterator)
+
+
+class LogManager[T]:
+    """
+    A wrapper for interacting with a named, time-indexed log, providing
+    type-safe and async-compatible methods.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        conn: sqlite3.Connection,
+        db_path: str,
+        model: Type[T] | None = None,
+    ):
+        self._name = name
+        self._conn = conn
+        self._db_path = db_path
+        self._model = model
+
+    def _serialize(self, value: T) -> str:
+        """Serializes the given value to a JSON string."""
+        if isinstance(value, JsonSerializable):
+            return value.model_dump_json()
+
+        return json.dumps(value)
+
+    def _deserialize(self, value: str) -> T:
+        """Deserializes a JSON string into the specified model or a generic object."""
+        if self._model:
+            return self._model.model_validate_json(value)
+
+        return json.loads(value)
+
+    def log(self, data: T, timestamp: datetime | None = None) -> None:
+        """
+        Adds a new entry to the log.
+
+        Args:
+            data: The JSON-serializable data to store. If a model is used, this
+                  should be an instance of that model.
+            timestamp: A timezone-naive datetime object. If not provided,
+                       `datetime.now()` is used.
+        """
+        ts = timestamp or datetime.now(timezone.utc)
+        ts_float = ts.timestamp()
+
+        with self._conn:
+            self._conn.execute(
+                "INSERT INTO beaver_logs (log_name, timestamp, data) VALUES (?, ?, ?)",
+                (self._name, ts_float, self._serialize(data)),
+            )
+
+    def range(self, start: datetime, end: datetime) -> list[T]:
+        """
+        Retrieves all log entries within a specific time window.
+
+        Args:
+            start: The start of the time range (inclusive).
+            end: The end of the time range (inclusive).
+
+        Returns:
+            A list of log entries, deserialized into the specified model if provided.
+        """
+        start_ts = start.timestamp()
+        end_ts = end.timestamp()
+
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT data FROM beaver_logs WHERE log_name = ? AND timestamp BETWEEN ? AND ? ORDER BY timestamp ASC",
+            (self._name, start_ts, end_ts),
+        )
+        return [self._deserialize(row["data"]) for row in cursor.fetchall()]
+
+    def live[R](
+        self,
+        window: timedelta,
+        period: timedelta,
+        aggregator: Callable[[list[T]], R],
+    ) -> Iterator[R]:
+        """
+        Returns a blocking, infinite iterator for real-time log analysis.
+
+        This maintains a sliding window of log entries and yields the result
+        of an aggregator function at specified intervals.
+
+        Args:
+            window: The duration of the sliding window (e.g., `timedelta(minutes=5)`).
+            period: The interval at which to update and yield a new result
+                             (e.g., `timedelta(seconds=10)`).
+            aggregator: A function that takes a list of log entries (the window) and
+                        returns a single, aggregated result.
+
+        Returns:
+            An iterator that yields the results of the aggregator.
+        """
+        return LiveIterator(
+            db_path=self._db_path,
+            log_name=self._name,
+            window=window,
+            period=period,
+            aggregator=aggregator,
+            deserializer=self._deserialize,
+        )
+
+    def as_async(self) -> AsyncLogManager[T]:
+        """Returns an async-compatible version of the log manager."""
+        return AsyncLogManager(self)

{beaver_db-0.15.0.dist-info → beaver_db-0.16.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.15.0
+Version: 0.16.0
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -19,25 +19,26 @@ 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**: Uses only Python's standard libraries (`sqlite3`) and `numpy`/`faiss-cpu`.
-  - **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.
-  - **Fast by Default**: It's built on SQLite, which is famously fast and reliable for local applications. Vector search is accelerated with a high-performance, persistent `faiss` index.
-  - **Standard Relational Interface**: While `beaver` provides high-level features, you can always use the same SQLite file for normal relational tasks with standard SQL.
+- **Minimalistic**: Uses only Python's standard libraries (`sqlite3`) and `numpy`/`faiss-cpu`.
+- **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.
+- **Fast by Default**: It's built on SQLite, which is famously fast and reliable for local applications. Vector search is accelerated with a high-performance, persistent `faiss` index.
+- **Standard Relational Interface**: While `beaver` provides high-level features, you can always use the same SQLite file for normal relational tasks with standard SQL.
 
 ## Core Features
 
-  - **Sync/Async High-Efficiency Pub/Sub**: A powerful, thread and process-safe publish-subscribe system for real-time messaging with a fan-out architecture. Sync by default, but with an `as_async` wrapper for async applications.
-  - **Namespaced Key-Value Dictionaries**: A Pythonic, dictionary-like interface for storing any JSON-serializable object within separate namespaces with optional TTL for cache implementations.
-  - **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
-  - **Persistent Priority Queue**: A high-performance, persistent priority queue perfect for task orchestration across multiple processes. Also with optional async support.
-  - **Simple Blob Storage**: A dictionary-like interface for storing medium-sized binary files (like PDFs or images) directly in the database, ensuring transactional integrity with your other data.
-  - **High-Performance Vector Storage & Search**: Store vector embeddings and perform fast, crash-safe approximate nearest neighbor searches using a `faiss`-based hybrid index.
-  - **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.
-  - **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.
+- **Sync/Async High-Efficiency Pub/Sub**: A powerful, thread and process-safe publish-subscribe system for real-time messaging with a fan-out architecture. Sync by default, but with an `as_async` wrapper for async applications.
+- **Namespaced Key-Value Dictionaries**: A Pythonic, dictionary-like interface for storing any JSON-serializable object within separate namespaces with optional TTL for cache implementations.
+- **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
+- **Persistent Priority Queue**: A high-performance, persistent priority queue perfect for task orchestration across multiple processes. Also with optional async support.
+- **Time-Indexed Log for Monitoring**: A specialized data structure for structured, time-series logs. Query historical data by time range or create a live, aggregated view of the most recent events for real-time dashboards.
+- **Simple Blob Storage**: A dictionary-like interface for storing medium-sized binary files (like PDFs or images) directly in the database, ensuring transactional integrity with your other data.
+- **High-Performance Vector Storage & Search**: Store vector embeddings and perform fast, crash-safe approximate nearest neighbor searches using a `faiss`-based hybrid index.
+- **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.
+- **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
 
@@ -220,6 +221,29 @@ attachments.put(
 avatar = attachments.get("user_123_avatar.png")
 ```
 
+### 8. Real-time Application Monitoring
+
+Use the **time-indexed log** to monitor your application's health in real-time. The `live()` method provides a continuously updating, aggregated view of your log data, perfect for building simple dashboards directly in your terminal.
+
+```python
+from datetime import timedelta
+import statistics
+
+logs = db.log("system_metrics")
+
+def summarize(window):
+    values = [log.get("value", 0) for log in window]
+    return {"mean": statistics.mean(values), "count": len(values)}
+
+live_summary = logs.live(
+    window_duration=timedelta(seconds=10),
+    sampling_period=timedelta(seconds=1),
+    aggregator=summarize
+)
+
+for summary in live_summary:
+    print(f"Live Stats (10s window): Count={summary['count']}, Mean={summary['mean']:.2f}")
+```
 
 ## Type-Safe Data Models
 

{beaver_db-0.15.0.dist-info → beaver_db-0.16.0.dist-info}/RECORD

@@ -2,14 +2,15 @@ beaver/__init__.py,sha256=qyEzF1Os7w4b4Hijgz0Y0R4zTrRBrHIGT1mEkZFl2YM,101
 beaver/blobs.py,sha256=5cmcvlJLY9jaftIRuNbdEryZxI47sw_pYpysYli23NY,3996
 beaver/channels.py,sha256=pCO8wFJAHdMzBLKvinI32L_XfU2B91H2qfsj1Tej-bc,9322
 beaver/collections.py,sha256=Uz241TSs0xRABPYeKenDYmkbaM0PKfvcBX5j0lMzMMA,24306
-beaver/core.py,sha256=zAPlym786_sOpRkP6LfKkd5BH2DXPwdOPTdAkSYojvQ,12469
+beaver/core.py,sha256=t_UzpqcbF2U8BjmQ9aIWTvUzPuVuOLcPzTrZQ2htjn4,13706
 beaver/dicts.py,sha256=1BQ9A_cMkJ7l5ayWbDG-4Wi3WtQ-9BKd7Wj_CB7dGlU,5410
 beaver/lists.py,sha256=0LT2XjuHs8pDgvW48kk_lfVc-Y-Ulmym0gcVWRESPtA,9708
+beaver/logs.py,sha256=mlJizZU0emlqLwuNeBJSPlict35Vyi35L4eIl5orv-M,9673
 beaver/queues.py,sha256=IQoeNhcYrVZTuH_4bWhtiEa-EYbFx_2iVKkR254XPnE,5953
 beaver/types.py,sha256=65rDdj97EegghEkKCNjI67bPYtTTI_jyB-leHdIypx4,1249
 beaver/vectors.py,sha256=j7RL2Y_xMAF2tPTi6E2LdJqZerSQXlnEQJOGZkefTsA,18358
-beaver_db-0.15.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
-beaver_db-0.15.0.dist-info/METADATA,sha256=bbeIcJMu28cG3KLBiraaGHEypZJ0h52JIMGBj0u85_U,16101
-beaver_db-0.15.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-beaver_db-0.15.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
-beaver_db-0.15.0.dist-info/RECORD,,
+beaver_db-0.16.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
+beaver_db-0.16.0.dist-info/METADATA,sha256=hNq6GOos295d5QeaUfTqSiLw4MDty9vyzNXpVYV7JzI,17070
+beaver_db-0.16.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+beaver_db-0.16.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
+beaver_db-0.16.0.dist-info/RECORD,,