sqlite_graphrag/output.rs
1//! Single point of terminal I/O for the CLI (stdout JSON, stderr human).
2//!
3//! All user-visible output must go through this module; direct `println!` in
4//! other modules is forbidden.
5
6use crate::errors::AppError;
7use serde::Serialize;
8
9/// Output format variants accepted by `--format` CLI flags.
10#[derive(Debug, Clone, Copy, clap::ValueEnum, Default)]
11pub enum OutputFormat {
12 #[default]
13 Json,
14 Text,
15 Markdown,
16}
17
18/// Restricted JSON-only format for commands that always emit JSON.
19#[derive(Debug, Clone, Copy, clap::ValueEnum, Default)]
20pub enum JsonOutputFormat {
21 #[default]
22 Json,
23}
24
25/// Serializes `value` as pretty-printed JSON and writes it to stdout with a trailing newline.
26///
27/// Flushes stdout after writing. A `BrokenPipe` error is silenced so that
28/// piping to consumers that close early (e.g. `head`) does not surface an error.
29///
30/// # Errors
31/// Returns `Err` when serialization fails or when a non-`BrokenPipe` I/O error occurs.
32#[inline]
33pub fn emit_json<T: Serialize>(value: &T) -> Result<(), AppError> {
34 let json = serde_json::to_string_pretty(value)?;
35 let mut out = std::io::stdout().lock();
36 if let Err(e) = std::io::Write::write_all(&mut out, json.as_bytes())
37 .and_then(|()| std::io::Write::write_all(&mut out, b"\n"))
38 .and_then(|()| std::io::Write::flush(&mut out))
39 {
40 if e.kind() == std::io::ErrorKind::BrokenPipe {
41 return Ok(());
42 }
43 return Err(AppError::Io(e));
44 }
45 Ok(())
46}
47
48/// Serializes `value` as compact (single-line) JSON and writes it to stdout with a trailing newline.
49///
50/// Flushes stdout after writing. A `BrokenPipe` error is silenced.
51///
52/// # Errors
53/// Returns `Err` when serialization fails or when a non-`BrokenPipe` I/O error occurs.
54#[inline]
55pub fn emit_json_compact<T: Serialize>(value: &T) -> Result<(), AppError> {
56 let json = serde_json::to_string(value)?;
57 let mut out = std::io::stdout().lock();
58 if let Err(e) = std::io::Write::write_all(&mut out, json.as_bytes())
59 .and_then(|()| std::io::Write::write_all(&mut out, b"\n"))
60 .and_then(|()| std::io::Write::flush(&mut out))
61 {
62 if e.kind() == std::io::ErrorKind::BrokenPipe {
63 return Ok(());
64 }
65 return Err(AppError::Io(e));
66 }
67 Ok(())
68}
69
70/// Writes compact JSON to stdout, silently ignoring serialization and I/O errors.
71/// Designed for NDJSON streaming where partial output is acceptable.
72#[inline]
73pub fn emit_json_line<T: Serialize>(value: &T) {
74 if let Ok(json) = serde_json::to_string(value) {
75 let mut out = std::io::stdout().lock();
76 let _ = std::io::Write::write_all(&mut out, json.as_bytes());
77 let _ = std::io::Write::write_all(&mut out, b"\n");
78 let _ = std::io::Write::flush(&mut out);
79 }
80}
81
82/// Writes `msg` followed by a newline to stdout and flushes.
83///
84/// A `BrokenPipe` error is silenced gracefully.
85#[inline]
86pub fn emit_text(msg: &str) {
87 let mut out = std::io::stdout().lock();
88 let _ = std::io::Write::write_all(&mut out, msg.as_bytes())
89 .and_then(|()| std::io::Write::write_all(&mut out, b"\n"))
90 .and_then(|()| std::io::Write::flush(&mut out));
91}
92
93/// Logs `msg` as a structured `tracing::info!` event (does not write to stdout).
94#[inline]
95pub fn emit_progress(msg: &str) {
96 tracing::info!(target: "output", message = msg);
97}
98
99/// Emits a bilingual progress message honouring `--lang` or `SQLITE_GRAPHRAG_LANG`.
100/// Usage: `output::emit_progress_i18n("Computing embedding...", "Calculando embedding...")`.
101pub fn emit_progress_i18n(en: &str, pt: &str) {
102 use crate::i18n::{current, Language};
103 match current() {
104 Language::English => tracing::info!(target: "output", message = en),
105 Language::Portuguese => tracing::info!(target: "output", message = pt),
106 }
107}
108
109/// Emits a JSON error envelope to stdout for machine consumers.
110///
111/// Ensures the stdout JSON contract is honoured even on error paths:
112/// `{"error": true, "code": <exit_code>, "message": "<localized_msg>"}`.
113/// A `BrokenPipe` error is silenced so piping to early-closing consumers
114/// does not surface a secondary error.
115#[cold]
116#[inline(never)]
117pub fn emit_error_json(code: i32, message: &str) {
118 #[derive(serde::Serialize)]
119 struct ErrorEnvelope<'a> {
120 error: bool,
121 code: i32,
122 message: &'a str,
123 }
124 let envelope = ErrorEnvelope {
125 error: true,
126 code,
127 message,
128 };
129 if emit_json(&envelope).is_err() {
130 use std::io::Write;
131 let escaped = message.replace('\\', "\\\\").replace('"', "\\\"");
132 let _ = writeln!(
133 std::io::stdout().lock(),
134 r#"{{"error":true,"code":{code},"message":"{escaped}"}}"#
135 );
136 }
137}
138
139/// Emits a localised error message to stderr with the `Error:`/`Erro:` prefix.
140///
141/// Centralises human-readable error output following Pattern 5 (`output.rs` is the
142/// SOLE I/O point of the CLI). Does not log via `tracing` — call `tracing::error!`
143/// explicitly before this function when structured observability is desired.
144#[cold]
145#[inline(never)]
146pub fn emit_error(localized_msg: &str) {
147 tracing::error!(target: "output", message = localized_msg);
148 eprintln!("{}: {}", crate::i18n::error_prefix(), localized_msg);
149}
150
151/// Emits a bilingual error to stderr honouring `--lang` or `SQLITE_GRAPHRAG_LANG`.
152/// Usage: `output::emit_error_i18n("invariant violated", "invariante violado")`.
153#[cold]
154#[inline(never)]
155pub fn emit_error_i18n(en: &str, pt: &str) {
156 use crate::i18n::{current, Language};
157 let msg = match current() {
158 Language::English => en,
159 Language::Portuguese => pt,
160 };
161 emit_error(msg);
162}
163
164/// JSON payload emitted by the `remember` subcommand.
165///
166/// All fields are required by the JSON contract (see `docs/schemas/remember.schema.json`).
167/// `operation` is an alias of `action` for compatibility with clients using the old field name.
168///
169/// # Examples
170///
171/// ```
172/// use sqlite_graphrag::output::RememberResponse;
173///
174/// let resp = RememberResponse {
175/// memory_id: 1,
176/// name: "nota-inicial".into(),
177/// namespace: "global".into(),
178/// action: "created".into(),
179/// operation: "created".into(),
180/// version: 1,
181/// entities_persisted: 0,
182/// relationships_persisted: 0,
183/// relationships_truncated: false,
184/// chunks_created: 1,
185/// chunks_persisted: 0,
186/// urls_persisted: 0,
187/// extraction_method: None,
188/// merged_into_memory_id: None,
189/// warnings: vec![],
190/// created_at: 1_700_000_000,
191/// created_at_iso: "2023-11-14T22:13:20Z".into(),
192/// elapsed_ms: 42,
193/// name_was_normalized: false,
194/// original_name: None,
195/// };
196///
197/// let json = serde_json::to_string(&resp).unwrap();
198/// assert!(json.contains("\"memory_id\":1"));
199/// assert!(json.contains("\"elapsed_ms\":42"));
200/// assert!(json.contains("\"merged_into_memory_id\":null"));
201/// assert!(json.contains("\"urls_persisted\":0"));
202/// assert!(json.contains("\"relationships_truncated\":false"));
203/// ```
204#[derive(Serialize)]
205pub struct RememberResponse {
206 pub memory_id: i64,
207 pub name: String,
208 pub namespace: String,
209 pub action: String,
210 /// Semantic alias of `action` for compatibility with the contract documented in SKILL.md.
211 pub operation: String,
212 pub version: i64,
213 pub entities_persisted: usize,
214 pub relationships_persisted: usize,
215 /// True when the relationship builder hit the cap before covering all entity pairs.
216 /// Callers can use this to decide whether to increase GRAPHRAG_MAX_RELATIONSHIPS_PER_MEMORY.
217 pub relationships_truncated: bool,
218 /// Total number of chunks the body was split into BEFORE dedup.
219 ///
220 /// For single-chunk bodies this equals 1 even though no row is added to
221 /// the `memory_chunks` table — the memory row itself acts as the chunk.
222 /// Use `chunks_persisted` to know how many rows were actually written.
223 pub chunks_created: usize,
224 /// Number of chunks actually written to chunks/embeddings tables. Always <= chunks_created.
225 ///
226 /// Equal when no chunk had identical normalized text already in DB; less when dedup skipped
227 /// some. Equals zero for single-chunk bodies (the memory row is the chunk) and equals
228 /// `chunks_created` for multi-chunk bodies. Added in v1.0.23 to disambiguate from
229 /// `chunks_created` and reflect database state precisely.
230 pub chunks_persisted: usize,
231 /// Number of unique URLs inserted into `memory_urls` for this memory.
232 /// Added in v1.0.24 — split URLs out of the entity graph (P0-2 fix).
233 #[serde(default)]
234 pub urls_persisted: usize,
235 /// Extraction method used: "gliner-{variant}+regex" or "regex-only". None when NER is not enabled.
236 #[serde(skip_serializing_if = "Option::is_none")]
237 pub extraction_method: Option<String>,
238 pub merged_into_memory_id: Option<i64>,
239 pub warnings: Vec<String>,
240 /// Timestamp Unix epoch seconds.
241 pub created_at: i64,
242 /// RFC 3339 UTC timestamp string parallel to `created_at` for ISO 8601 parsers.
243 pub created_at_iso: String,
244 /// Total execution time in milliseconds from handler start to serialisation.
245 pub elapsed_ms: u64,
246 /// True when the user-supplied `--name` differed from the persisted slug
247 /// (i.e. kebab-case normalization changed the value). Added in v1.0.32 so
248 /// callers can detect normalization without parsing stderr WARN logs.
249 #[serde(default)]
250 pub name_was_normalized: bool,
251 /// Original user-supplied `--name` value before normalization.
252 /// Present only when `name_was_normalized == true`; omitted otherwise to
253 /// keep the common (already-kebab) payload small.
254 #[serde(skip_serializing_if = "Option::is_none")]
255 pub original_name: Option<String>,
256}
257
258/// Individual item returned by the `recall` query.
259///
260/// The `memory_type` field is serialised as `"type"` in JSON to maintain
261/// compatibility with external clients — the Rust name uses `memory_type`
262/// to avoid conflict with the reserved keyword.
263///
264/// # Examples
265///
266/// ```
267/// use sqlite_graphrag::output::RecallItem;
268///
269/// let item = RecallItem {
270/// memory_id: 7,
271/// name: "nota-rust".into(),
272/// namespace: "global".into(),
273/// memory_type: "user".into(),
274/// description: "aprendizado de Rust".into(),
275/// snippet: "ownership e borrowing".into(),
276/// distance: 0.12,
277/// score: 0.88,
278/// source: "direct".into(),
279/// graph_depth: None,
280/// };
281///
282/// let json = serde_json::to_string(&item).unwrap();
283/// // Rust field `memory_type` appears as `"type"` in JSON.
284/// assert!(json.contains("\"type\":\"user\""));
285/// assert!(!json.contains("memory_type"));
286/// assert!(json.contains("\"distance\":0.12"));
287/// ```
288#[derive(Serialize, Clone)]
289pub struct RecallItem {
290 pub memory_id: i64,
291 pub name: String,
292 pub namespace: String,
293 #[serde(rename = "type")]
294 pub memory_type: String,
295 pub description: String,
296 pub snippet: String,
297 pub distance: f32,
298 /// Cosine similarity in `[0.0, 1.0]` derived as `1.0 - distance` and clamped
299 /// to that interval. Always populated to satisfy the documented contract
300 /// (M-A5 in v1.0.40); higher means more similar. For graph hits the value
301 /// reflects the hop-derived distance proxy and should be interpreted
302 /// alongside `graph_depth` rather than as a true cosine score.
303 pub score: f32,
304 pub source: String,
305 /// Number of graph hops between this match and the seed memories.
306 ///
307 /// Set to `None` for direct vector matches (where `distance` is meaningful)
308 /// and to `Some(N)` for traversal results, with `N=0` when the depth could
309 /// not be tracked precisely. Added in v1.0.23 to disambiguate graph results
310 /// from the `distance: 0.0` placeholder previously used for graph entries.
311 /// Field is omitted from JSON output when `None`.
312 #[serde(skip_serializing_if = "Option::is_none")]
313 pub graph_depth: Option<u32>,
314}
315
316impl RecallItem {
317 /// Computes the similarity score from a vector distance, clamped to
318 /// `[0.0, 1.0]`. Cosine distance returned by sqlite-vec lives in `[0, 2]`
319 /// in theory but the embedder produces unit-norm vectors so the practical
320 /// range is `[0, 1]`. Centralized so every constructor keeps the contract.
321 #[inline]
322 pub fn score_from_distance(distance: f32) -> f32 {
323 let raw = 1.0 - distance;
324 if raw.is_nan() {
325 0.0
326 } else {
327 raw.clamp(0.0, 1.0)
328 }
329 }
330}
331
332/// Full response envelope returned by the `recall` subcommand.
333///
334/// Contains both direct vector matches and graph-traversal matches, plus the
335/// aggregated `results` list that merges both for callers that do not need
336/// to distinguish the source.
337#[derive(Serialize)]
338pub struct RecallResponse {
339 pub query: String,
340 pub k: usize,
341 pub direct_matches: Vec<RecallItem>,
342 pub graph_matches: Vec<RecallItem>,
343 /// Aggregated alias of `direct_matches` + `graph_matches` for the contract documented in SKILL.md.
344 pub results: Vec<RecallItem>,
345 /// Total execution time in milliseconds from handler start to serialisation.
346 pub elapsed_ms: u64,
347 /// G58 (v1.0.80): `true` when the live query embedding failed and the
348 /// handler fell back to FTS5 BM25 + LIKE prefix. Symmetric to
349 /// `fts_degraded` in `hybrid-search`. Absent on the wire when false.
350 #[serde(skip_serializing_if = "std::ops::Not::not", default)]
351 pub vec_degraded: bool,
352 /// G58 (v1.0.80): human-readable description of the embedding failure
353 /// that triggered the fallback. Absent on the wire when `vec_degraded`
354 /// is false or the failure had no message.
355 #[serde(skip_serializing_if = "std::option::Option::is_none")]
356 pub vec_error: Option<String>,
357 /// G58 (v1.0.80): advisory warning echoed for callers that branch on
358 /// top-level status. Distinguishes a FTS5-only fallback from a clean
359 /// hybrid response so downstream pipelines can lower their confidence.
360 #[serde(skip_serializing_if = "std::option::Option::is_none")]
361 pub warning: Option<String>,
362}
363
364#[cfg(test)]
365mod tests {
366 use super::*;
367 use serde::Serialize;
368
369 #[derive(Serialize)]
370 struct Dummy {
371 val: u32,
372 }
373
374 // Non-serializable type to force a JSON serialization error
375 struct NotSerializable;
376 impl Serialize for NotSerializable {
377 fn serialize<S: serde::Serializer>(&self, _: S) -> Result<S::Ok, S::Error> {
378 Err(serde::ser::Error::custom(
379 "intentional serialization failure",
380 ))
381 }
382 }
383
384 #[test]
385 fn emit_json_returns_ok_for_valid_value() {
386 let v = Dummy { val: 42 };
387 assert!(emit_json(&v).is_ok());
388 }
389
390 #[test]
391 fn emit_json_returns_err_for_non_serializable_value() {
392 let v = NotSerializable;
393 assert!(emit_json(&v).is_err());
394 }
395
396 #[test]
397 fn emit_json_compact_returns_ok_for_valid_value() {
398 let v = Dummy { val: 7 };
399 assert!(emit_json_compact(&v).is_ok());
400 }
401
402 #[test]
403 fn emit_json_compact_returns_err_for_non_serializable_value() {
404 let v = NotSerializable;
405 assert!(emit_json_compact(&v).is_err());
406 }
407
408 #[test]
409 fn emit_text_does_not_panic() {
410 emit_text("mensagem de teste");
411 }
412
413 #[test]
414 fn emit_progress_does_not_panic() {
415 emit_progress("progresso de teste");
416 }
417
418 #[test]
419 fn remember_response_serializes_correctly() {
420 let r = RememberResponse {
421 memory_id: 1,
422 name: "teste".to_string(),
423 namespace: "ns".to_string(),
424 action: "created".to_string(),
425 operation: "created".to_string(),
426 version: 1,
427 entities_persisted: 2,
428 relationships_persisted: 3,
429 relationships_truncated: false,
430 chunks_created: 4,
431 chunks_persisted: 4,
432 urls_persisted: 2,
433 extraction_method: None,
434 merged_into_memory_id: None,
435 warnings: vec!["aviso".to_string()],
436 created_at: 1776569715,
437 created_at_iso: "2026-04-19T03:34:15Z".to_string(),
438 elapsed_ms: 123,
439 name_was_normalized: false,
440 original_name: None,
441 };
442 let json = serde_json::to_string(&r).unwrap();
443 assert!(json.contains("memory_id"));
444 assert!(json.contains("aviso"));
445 assert!(json.contains("\"namespace\""));
446 assert!(json.contains("\"merged_into_memory_id\""));
447 assert!(json.contains("\"operation\""));
448 assert!(json.contains("\"created_at\""));
449 assert!(json.contains("\"created_at_iso\""));
450 assert!(json.contains("\"elapsed_ms\""));
451 assert!(json.contains("\"urls_persisted\""));
452 assert!(json.contains("\"relationships_truncated\":false"));
453 }
454
455 #[test]
456 fn recall_item_serializes_renamed_type_field() {
457 let item = RecallItem {
458 memory_id: 10,
459 name: "entidade".to_string(),
460 namespace: "ns".to_string(),
461 memory_type: "entity".to_string(),
462 description: "desc".to_string(),
463 snippet: "trecho".to_string(),
464 distance: 0.5,
465 score: RecallItem::score_from_distance(0.5),
466 source: "db".to_string(),
467 graph_depth: None,
468 };
469 let json = serde_json::to_string(&item).unwrap();
470 assert!(json.contains("\"type\""));
471 assert!(!json.contains("memory_type"));
472 // Field is omitted from JSON when None.
473 assert!(!json.contains("graph_depth"));
474 assert!(json.contains("\"score\":0.5"));
475 }
476
477 #[test]
478 fn recall_response_serializes_with_lists() {
479 let resp = RecallResponse {
480 query: "busca".to_string(),
481 k: 10,
482 direct_matches: vec![],
483 graph_matches: vec![],
484 results: vec![],
485 elapsed_ms: 42,
486 vec_degraded: false,
487 vec_error: None,
488 warning: None,
489 };
490 let json = serde_json::to_string(&resp).unwrap();
491 assert!(json.contains("direct_matches"));
492 assert!(json.contains("graph_matches"));
493 assert!(json.contains("\"k\":"));
494 assert!(json.contains("\"results\""));
495 assert!(json.contains("\"elapsed_ms\""));
496 // G58: clean response must NOT carry the degradation fields.
497 assert!(!json.contains("vec_degraded"));
498 assert!(!json.contains("vec_error"));
499 assert!(!json.contains("warning"));
500 }
501
502 #[test]
503 fn recall_response_serializes_vec_degraded_when_fallback_fired() {
504 let resp = RecallResponse {
505 query: "busca".to_string(),
506 k: 10,
507 direct_matches: vec![],
508 graph_matches: vec![],
509 results: vec![],
510 elapsed_ms: 42,
511 vec_degraded: true,
512 vec_error: Some("embedding cancelled by external signal".to_string()),
513 warning: Some("live query embedding unavailable; results are FTS5 BM25 only (semantic relevance reduced)".to_string()),
514 };
515 let json = serde_json::to_string(&resp).unwrap();
516 assert!(json.contains("\"vec_degraded\":true"));
517 assert!(json.contains("\"vec_error\":\"embedding cancelled by external signal\""));
518 assert!(json.contains("\"warning\":\"live query embedding unavailable"));
519 }
520
521 #[test]
522 fn error_envelope_serializes_correctly() {
523 #[derive(serde::Serialize)]
524 struct ErrorEnvelope<'a> {
525 error: bool,
526 code: i32,
527 message: &'a str,
528 }
529 let envelope = ErrorEnvelope {
530 error: true,
531 code: 10,
532 message: "database disk image is malformed",
533 };
534 let json = serde_json::to_value(&envelope).unwrap();
535 assert_eq!(json["error"], true);
536 assert_eq!(json["code"], 10);
537 assert_eq!(json["message"], "database disk image is malformed");
538 }
539
540 #[test]
541 fn output_format_default_is_json() {
542 let fmt = OutputFormat::default();
543 assert!(matches!(fmt, OutputFormat::Json));
544 }
545
546 #[test]
547 fn output_format_variants_exist() {
548 let _text = OutputFormat::Text;
549 let _md = OutputFormat::Markdown;
550 let _json = OutputFormat::Json;
551 }
552
553 #[test]
554 fn recall_item_clone_produces_equal_value() {
555 let item = RecallItem {
556 memory_id: 99,
557 name: "clone".to_string(),
558 namespace: "ns".to_string(),
559 memory_type: "relation".to_string(),
560 description: "d".to_string(),
561 snippet: "s".to_string(),
562 distance: 0.1,
563 score: RecallItem::score_from_distance(0.1),
564 source: "src".to_string(),
565 graph_depth: Some(2),
566 };
567 let cloned = item.clone();
568 assert_eq!(cloned.memory_id, item.memory_id);
569 assert_eq!(cloned.name, item.name);
570 assert_eq!(cloned.graph_depth, Some(2));
571 }
572}