context_forge/
traits.rs

1use async_trait::async_trait;
2
3use crate::entry::{ContextEntry, ScoredEntry};
4use crate::error::Error;
5
6/// Result type alias for crate operations.
7pub type Result<T> = std::result::Result<T, Error>;
8
9/// Trait for persisting and retrieving context entries.
10///
11/// Implementations must be thread-safe (`Send + Sync`) to support
12/// concurrent access from multiple worker threads.
13#[async_trait]
14pub trait ContextStorage: Send + Sync {
15    /// Persist a single entry.
16    ///
17    /// # Security
18    ///
19    /// Implementations persist `entry.content` verbatim — secret scrubbing
20    /// happens only in [`ContextForge::save`](crate::ContextForge::save).
21    /// Callers writing through this trait directly are responsible for
22    /// scrubbing first (see [`scrub_secrets`](crate::scrub_secrets)).
23    ///
24    /// # Errors
25    ///
26    /// Returns an error if the underlying storage write fails.
27    async fn save(&self, entry: &ContextEntry) -> Result<()>;
28
29    /// Return the top-k entries (most recent or highest priority).
30    ///
31    /// # Errors
32    ///
33    /// Returns an error if the underlying storage read fails.
34    async fn get_top_k(&self, k: usize) -> Result<Vec<ContextEntry>>;
35
36    /// Return every stored entry.
37    ///
38    /// # Errors
39    ///
40    /// Returns an error if the underlying storage read fails.
41    async fn get_all(&self) -> Result<Vec<ContextEntry>>;
42
43    /// Delete an entry by id. Returns `true` if an entry was removed.
44    ///
45    /// # Errors
46    ///
47    /// Returns an error if the underlying storage delete fails.
48    async fn delete(&self, id: &str) -> Result<bool>;
49
50    /// Remove all entries. Returns the number of entries removed.
51    ///
52    /// # Errors
53    ///
54    /// Returns an error if the underlying storage delete fails.
55    async fn clear(&self) -> Result<usize>;
56
57    /// Remove all entries within a given scope. Returns the number of entries removed.
58    ///
59    /// # Errors
60    ///
61    /// Returns an error if the underlying storage delete fails.
62    async fn clear_scope(&self, scope: &str) -> Result<usize>;
63
64    /// Return the total number of stored entries.
65    ///
66    /// # Errors
67    ///
68    /// Returns an error if the underlying storage read fails.
69    async fn count(&self) -> Result<usize>;
70}
71
72/// Trait for searching context entries by relevance.
73///
74/// Implementations must be thread-safe (`Send + Sync`) to support
75/// concurrent access from multiple worker threads.
76#[async_trait]
77pub trait Searcher: Send + Sync {
78    /// Search for entries matching `query`, optionally restricted to `scope`,
79    /// returning at most `limit` results ordered by descending relevance score.
80    ///
81    /// `scope = None` searches every entry regardless of scope (global recall).
82    /// `scope = Some(s)` restricts results to entries whose `scope` equals `s`.
83    ///
84    /// `query` is treated as natural-language text: implementations should
85    /// split it into terms and OR-match them (e.g. via FTS5 bm25 ranking)
86    /// rather than requiring every term to match. Query-language operator
87    /// syntax (`AND`, `OR`, `NEAR`, prefix `*`, quoted phrases, column
88    /// filters, etc.) must **not** be interpreted from `query` — operator
89    /// characters are treated as term separators, so arbitrary text never
90    /// produces a syntax error. A query with no usable terms (empty or
91    /// punctuation-only) returns an empty result set, not an error. The
92    /// special value [`crate::engine::MATCH_ALL_QUERY`] (`"*"`) matches every
93    /// entry.
94    ///
95    /// # Errors
96    ///
97    /// Returns an error if the underlying search fails.
98    async fn search(
99        &self,
100        query: &str,
101        scope: Option<&str>,
102        limit: usize,
103    ) -> Result<Vec<ScoredEntry>>;
104}
context_forge/traits.rs

context_forge/
traits.rs
