1use 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
17pub const KIND: &str = "knowledge-retrieval";
19
20#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize)]
21#[serde(rename_all = "snake_case")]
22enum Mode {
23 Single,
25 #[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#[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 #[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 #[serde(default)]
103 metadata_filtering_mode: Option<String>,
104 #[serde(default)]
105 metadata_filtering_conditions: Option<MetadataFilter>,
106}
107
108#[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 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 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 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", 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
253pub 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 "additionalProperties": false,
262 "required": ["query_variable_selector", "dataset_ids"],
263 "properties": {
264 "query_variable_selector": {
265 "description": "Variable holding the search query, e.g. [\"sys\", \"query\"].",
266 "oneOf": [{"type": "array", "items": {"type": "string"}, "minItems": 2}, {"type": "string"}]
267 },
268 "dataset_ids": {"type": "array", "items": {"type": "string"}, "minItems": 1},
269 "retrieval_mode": {"type": "string", "enum": ["single", "multiple"], "default": "multiple"},
270 "multiple_retrieval_config": {
271 "type": "object",
272 "properties": {
273 "top_k": {"type": "integer", "minimum": 1, "maximum": 100, "default": 4},
274 "score_threshold": {"type": ["number", "null"]},
275 "reranking_enable": {"type": "boolean", "default": false},
276 "reranking_mode": {"type": "string", "enum": ["reranking_model", "weighted_score"]},
277 "weights": {
278 "type": "object",
279 "description": "Hybrid weights: {vector, keyword} or {vector_setting: {vector_weight}, keyword_setting: {keyword_weight}}."
280 }
281 }
282 },
283 "metadata_filtering_mode": {"type": "string", "enum": ["disabled", "manual"]},
284 "metadata_filtering_conditions": {
285 "type": "object",
286 "properties": {
287 "logical_operator": {"type": "string", "enum": ["and", "or"]},
288 "conditions": {
289 "type": "array",
290 "items": {
291 "type": "object",
292 "required": ["name", "comparison_operator"],
293 "properties": {
294 "name": {"type": "string"},
295 "comparison_operator": {"type": "string"},
296 "value": {}
297 }
298 }
299 }
300 }
301 }
302 }
303 }))
304 .output(
305 OutputDescriptor::new("result", ValueType::ArrayObject)
306 .describe("Matching chunks: {content, title, score, dataset_id, document_id, id, metadata}."),
307 )
308}
309
310pub fn register(registry: &mut Registry) {
312 registry.register_lazily_described(KIND, descriptor, |doc| {
313 let node: Arc<dyn Node> = Arc::new(KnowledgeRetrievalNode::from_doc(doc)?);
314 Ok(node)
315 });
316}