Skip to main content

graphrt_rag/
node.rs

1//! The `knowledge-retrieval` node.
2
3use std::sync::Arc;
4
5use futures::future::BoxFuture;
6use graphrt_core::catalog::{NodeCategory, NodeDescriptor, OutputDescriptor};
7use graphrt_core::dsl::NodeDoc;
8use graphrt_core::node::{ConfigError, Node, NodeContext, NodeError, NodeOutput, NodeResult, Registry, parse_config};
9use graphrt_core::template::Template;
10use graphrt_core::{Selector, Value, ValueType};
11use serde::Deserialize;
12
13use crate::filter::MetadataFilter;
14use crate::kb::KnowledgeBase;
15use crate::types::{Hit, HybridWeights, RetrievalRequest};
16
17/// Node kind.
18pub const KIND: &str = "knowledge-retrieval";
19
20#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize)]
21#[serde(rename_all = "snake_case")]
22enum Mode {
23    /// Use only the dataset whose best hit scores highest.
24    Single,
25    /// Merge hits from all datasets.
26    #[default]
27    Multiple,
28}
29
30#[derive(Clone, Debug, Deserialize)]
31struct VectorSetting {
32    #[serde(default)]
33    vector_weight: f32,
34}
35
36#[derive(Clone, Debug, Deserialize)]
37struct KeywordSetting {
38    #[serde(default)]
39    keyword_weight: f32,
40}
41
42/// Accepts `{vector, keyword}` or `{vector_setting: {vector_weight}, keyword_setting: {keyword_weight}}`.
43#[derive(Clone, Debug, Deserialize)]
44#[serde(untagged)]
45enum WeightsConfig {
46    Flat { vector: f32, keyword: f32 },
47    Nested { vector_setting: VectorSetting, keyword_setting: KeywordSetting },
48}
49
50impl WeightsConfig {
51    fn to_weights(&self) -> HybridWeights {
52        match self {
53            WeightsConfig::Flat { vector, keyword } => HybridWeights { vector: *vector, keyword: *keyword },
54            WeightsConfig::Nested { vector_setting, keyword_setting } => {
55                HybridWeights { vector: vector_setting.vector_weight, keyword: keyword_setting.keyword_weight }
56            }
57        }
58    }
59}
60
61#[derive(Clone, Debug, Deserialize)]
62struct MultipleConfig {
63    #[serde(default = "default_top_k")]
64    top_k: usize,
65    #[serde(default)]
66    score_threshold: Option<f32>,
67    #[serde(default)]
68    reranking_enable: bool,
69    /// `reranking_model` (use the dataset reranker) or `weighted_score` (hybrid weights only).
70    #[serde(default)]
71    reranking_mode: Option<String>,
72    #[serde(default)]
73    weights: Option<WeightsConfig>,
74}
75
76fn default_top_k() -> usize {
77    4
78}
79
80impl Default for MultipleConfig {
81    fn default() -> Self {
82        Self {
83            top_k: default_top_k(),
84            score_threshold: None,
85            reranking_enable: false,
86            reranking_mode: None,
87            weights: None,
88        }
89    }
90}
91
92#[derive(Clone, Debug, Deserialize)]
93struct Config {
94    query_variable_selector: Selector,
95    #[serde(default)]
96    dataset_ids: Vec<String>,
97    #[serde(default)]
98    retrieval_mode: Mode,
99    #[serde(default)]
100    multiple_retrieval_config: Option<MultipleConfig>,
101    /// `disabled`, `manual` (use the conditions) or `automatic` (not supported; ignored).
102    #[serde(default)]
103    metadata_filtering_mode: Option<String>,
104    #[serde(default)]
105    metadata_filtering_conditions: Option<MetadataFilter>,
106}
107
108/// Retrieves chunks from a [`KnowledgeBase`] service.
109///
110/// Output `result` is an array of `{content, title, score, dataset_id,
111/// document_id, id, metadata}` objects, ready for an LLM node's context.
112#[derive(Debug)]
113pub struct KnowledgeRetrievalNode {
114    query: Selector,
115    datasets: Vec<String>,
116    mode: Mode,
117    top_k: usize,
118    threshold: Option<f32>,
119    rerank: bool,
120    weights: HybridWeights,
121    filter: Option<MetadataFilter>,
122}
123
124impl KnowledgeRetrievalNode {
125    /// Build from a node document.
126    pub fn from_doc(doc: &NodeDoc) -> Result<Self, ConfigError> {
127        let config: Config = parse_config(doc)?;
128        if config.dataset_ids.is_empty() {
129            return Err(ConfigError::new(doc, "`dataset_ids` must list at least one dataset"));
130        }
131        let multi = config.multiple_retrieval_config.unwrap_or_default();
132        if multi.top_k == 0 {
133            return Err(ConfigError::new(doc, "`top_k` must be at least 1"));
134        }
135        let weighted_only = multi.reranking_mode.as_deref() == Some("weighted_score");
136        let weights = multi.weights.as_ref().map(WeightsConfig::to_weights).unwrap_or_default();
137        if weights.vector < 0.0 || weights.keyword < 0.0 || weights.vector + weights.keyword <= 0.0 {
138            return Err(ConfigError::new(doc, "hybrid weights must be non-negative and not both zero"));
139        }
140        let filter = match config.metadata_filtering_mode.as_deref() {
141            Some("disabled") => None,
142            None | Some("manual") => config.metadata_filtering_conditions.filter(|f| !f.is_empty()),
143            Some("automatic") => {
144                return Err(ConfigError::new(
145                    doc,
146                    "`metadata_filtering_mode: automatic` is not supported; use `manual`",
147                ));
148            }
149            Some(other) => {
150                return Err(ConfigError::new(
151                    doc,
152                    format!("unknown `metadata_filtering_mode` `{other}` (expected disabled or manual)"),
153                ));
154            }
155        };
156        if let Some(f) = &filter {
157            f.validate().map_err(|e| ConfigError::new(doc, e.to_string()))?;
158        }
159        Ok(Self {
160            query: config.query_variable_selector,
161            datasets: config.dataset_ids,
162            mode: config.retrieval_mode,
163            top_k: multi.top_k.min(100),
164            threshold: multi.score_threshold,
165            rerank: multi.reranking_enable && !weighted_only,
166            weights,
167            filter,
168        })
169    }
170
171    /// Resolve `{{#...#}}` templates in string condition values.
172    fn resolved_filter(&self, ctx: &NodeContext) -> Option<MetadataFilter> {
173        let mut filter = self.filter.clone()?;
174        for c in &mut filter.conditions {
175            if let serde_json::Value::String(s) = &c.value {
176                let template = Template::parse(s);
177                if !template.is_static() {
178                    c.value = serde_json::Value::String(template.render(&ctx.pool));
179                }
180            }
181        }
182        Some(filter)
183    }
184
185    async fn execute(&self, ctx: NodeContext) -> NodeResult {
186        // A missing variable is a wiring mistake; an empty value is a legitimate empty query.
187        let query = ctx
188            .get(&self.query)
189            .ok_or_else(|| NodeError::invalid_input(format!("query variable `{}` is not set", self.query)))?
190            .to_text();
191        if query.trim().is_empty() {
192            return Ok(NodeOutput::new().with("result", Value::array([])).meta("skipped", "empty query").into());
193        }
194        let kb = ctx.require_service::<KnowledgeBase>("knowledge base")?;
195        for id in &self.datasets {
196            if !kb.contains(id) {
197                return Err(NodeError::fatal("invalid_input", format!("unknown dataset `{id}`")));
198            }
199        }
200        let request = RetrievalRequest::new(query, self.datasets.clone())
201            .top_k(self.top_k)
202            .threshold(self.threshold)
203            .filter(self.resolved_filter(&ctx))
204            .weights(self.weights)
205            .rerank(self.rerank);
206        let hits = match self.mode {
207            Mode::Multiple => kb.retrieve(&request).await,
208            Mode::Single => kb.retrieve_single(&request).await,
209        }
210        .map_err(NodeError::from)?;
211
212        let count = hits.len();
213        let result = Value::array(hits.into_iter().map(hit_value));
214        Ok(NodeOutput::new()
215            .with("result", result)
216            .meta("datasets", Value::array(self.datasets.iter().map(|d| Value::from(d.as_str()))))
217            .meta("hits", i64::try_from(count).unwrap_or(i64::MAX))
218            .into())
219    }
220}
221
222fn hit_value(hit: Hit) -> Value {
223    Value::object([
224        ("content", Value::from(hit.content)),
225        ("title", Value::from(hit.title)),
226        ("score", Value::Float(f64::from(hit.score))),
227        ("dataset_id", Value::from(hit.dataset_id)),
228        ("document_id", Value::from(hit.document_id)),
229        ("id", Value::from(hit.id)),
230        // Metadata comes from external stores: never let it forge file values.
231        ("metadata", Value::from_json(serde_json::Value::Object(hit.metadata))),
232    ])
233}
234
235impl Node for KnowledgeRetrievalNode {
236    fn run(&self, ctx: NodeContext) -> BoxFuture<'_, NodeResult> {
237        Box::pin(self.execute(ctx))
238    }
239
240    fn inputs(&self) -> Vec<Selector> {
241        let mut out = vec![self.query.clone()];
242        if let Some(filter) = &self.filter {
243            for c in &filter.conditions {
244                if let serde_json::Value::String(s) = &c.value {
245                    out.extend(Template::parse(s).selectors().cloned());
246                }
247            }
248        }
249        out
250    }
251}
252
253/// Catalog entry for the node.
254pub fn descriptor() -> NodeDescriptor {
255    NodeDescriptor::new(KIND, "Knowledge Retrieval", NodeCategory::Knowledge)
256        .describe("Search knowledge datasets (vector, keyword or hybrid, with optional reranking) and return matching chunks.")
257        .icon("database")
258        .source("graphrt-rag")
259        .schema(serde_json::json!({
260            "type": "object",
261            "required": ["query_variable_selector", "dataset_ids"],
262            "properties": {
263                "query_variable_selector": {
264                    "description": "Variable holding the search query, e.g. [\"sys\", \"query\"].",
265                    "oneOf": [{"type": "array", "items": {"type": "string"}, "minItems": 2}, {"type": "string"}]
266                },
267                "dataset_ids": {"type": "array", "items": {"type": "string"}, "minItems": 1},
268                "retrieval_mode": {"type": "string", "enum": ["single", "multiple"], "default": "multiple"},
269                "multiple_retrieval_config": {
270                    "type": "object",
271                    "properties": {
272                        "top_k": {"type": "integer", "minimum": 1, "maximum": 100, "default": 4},
273                        "score_threshold": {"type": ["number", "null"]},
274                        "reranking_enable": {"type": "boolean", "default": false},
275                        "reranking_mode": {"type": "string", "enum": ["reranking_model", "weighted_score"]},
276                        "weights": {
277                            "type": "object",
278                            "description": "Hybrid weights: {vector, keyword} or {vector_setting: {vector_weight}, keyword_setting: {keyword_weight}}."
279                        }
280                    }
281                },
282                "metadata_filtering_mode": {"type": "string", "enum": ["disabled", "manual"]},
283                "metadata_filtering_conditions": {
284                    "type": "object",
285                    "properties": {
286                        "logical_operator": {"type": "string", "enum": ["and", "or"]},
287                        "conditions": {
288                            "type": "array",
289                            "items": {
290                                "type": "object",
291                                "required": ["name", "comparison_operator"],
292                                "properties": {
293                                    "name": {"type": "string"},
294                                    "comparison_operator": {"type": "string"},
295                                    "value": {}
296                                }
297                            }
298                        }
299                    }
300                }
301            }
302        }))
303        .output(
304            OutputDescriptor::new("result", ValueType::ArrayObject)
305                .describe("Matching chunks: {content, title, score, dataset_id, document_id, id, metadata}."),
306        )
307}
308
309/// Register the `knowledge-retrieval` node.
310pub fn register(registry: &mut Registry) {
311    registry.register_described(descriptor(), |doc| {
312        let node: Arc<dyn Node> = Arc::new(KnowledgeRetrievalNode::from_doc(doc)?);
313        Ok(node)
314    });
315}