sqlite_graphrag/
lib.rs

1//! # sqlite-graphrag
2//!
3//! Local GraphRAG memory for LLMs in a single SQLite file — zero external
4//! services required.
5//!
6//! `sqlite-graphrag` is a CLI-first library that persists memories, entities and
7//! typed relationships inside a single SQLite database. It combines FTS5
8//! full-text search with `sqlite-vec` KNN over locally-generated embeddings to
9//! expose a hybrid retrieval ranker tailored for LLM agents.
10//!
11//! ## CLI usage
12//!
13//! Install and initialize once, then save and recall memories:
14//!
15//! ```bash
16//! cargo install sqlite-graphrag
17//! sqlite-graphrag init
18//! sqlite-graphrag remember \
19//!     --name onboarding-note \
20//!     --type user \
21//!     --description "first memory" \
22//!     --body "hello graphrag"
23//! sqlite-graphrag recall "graphrag" --k 5
24//! ```
25//!
26//! ## Crate layout
27//!
28//! The public modules group the CLI, the SQLite storage layer and the
29//! supporting primitives (embedder, chunking, graph, namespace detection,
30//! output, paths and pragmas). The CLI binary wires them together through the
31//! commands in [`commands`].
32//!
33//! ## Exit codes
34//!
35//! Errors returned from [`errors::AppError`] map to deterministic exit codes
36//! suitable for orchestration by shell scripts and LLM agents. Consult the
37//! README for the full contract.
38
39use std::sync::atomic::{AtomicBool, Ordering};
40
41/// Signals that a shutdown signal (SIGINT / SIGTERM / SIGHUP) has been received.
42///
43/// Set in `main` via `ctrlc::set_handler`. Long-running subcommands can
44/// poll [`shutdown_requested`] to shut down gracefully before timeout.
45pub static SHUTDOWN: AtomicBool = AtomicBool::new(false);
46
47/// Returns `true` if a shutdown signal has been received since the process started.
48///
49/// The value reflects the state of [`SHUTDOWN`]. Without a `ctrlc::set_handler` call,
50/// the initial state is always `false`.
51///
52/// # Examples
53///
54/// ```
55/// use sqlite_graphrag::shutdown_requested;
56///
57/// // Under normal startup conditions the signal has not been received.
58/// assert!(!shutdown_requested());
59/// ```
60///
61/// ```
62/// use std::sync::atomic::Ordering;
63/// use sqlite_graphrag::{SHUTDOWN, shutdown_requested};
64///
65/// // Simulate receiving a signal and verify that the function reflects the state.
66/// SHUTDOWN.store(true, Ordering::SeqCst);
67/// assert!(shutdown_requested());
68/// // Restore to avoid contaminating other tests.
69/// SHUTDOWN.store(false, Ordering::SeqCst);
70/// ```
71pub fn shutdown_requested() -> bool {
72    SHUTDOWN.load(Ordering::SeqCst)
73}
74
75/// Token-aware chunking utilities for bodies that exceed the embedding window.
76pub mod chunking;
77
78/// Hybrid entity extraction: regex pre-filter + candle BERT NER (graceful degradation).
79pub mod extraction;
80
81/// `clap` definitions for the top-level `sqlite-graphrag` binary.
82pub mod cli;
83
84/// Subcommand handlers wired into the `clap` tree from [`cli`].
85pub mod commands;
86
87/// Compile-time constants: embedding dimensions, limits and thresholds.
88pub mod constants;
89
90/// Daemon IPC for persistent embedding model reuse across CLI invocations.
91pub mod daemon;
92
93/// Local embedding generation backed by `fastembed`.
94pub mod embedder;
95
96/// Library-wide error type and the mapping to process exit codes (see [`errors::AppError`]).
97pub mod errors;
98
99/// Graph traversal helpers over the entities and relationships tables.
100pub mod graph;
101
102/// Bilingual message layer for human-facing stderr progress (`--lang en|pt`, `SQLITE_GRAPHRAG_LANG`).
103pub mod i18n;
104
105/// Counting semaphore via lock files to limit parallel invocations (see [`lock::acquire_cli_slot`]).
106pub mod lock;
107
108/// Memory guard: checks RAM availability before loading the ONNX model.
109pub mod memory_guard;
110
111/// Namespace resolution with precedence between flag, environment and markers.
112pub mod namespace;
113
114/// Centralized stdout/stderr emitters for CLI output formatting.
115pub mod output;
116
117/// Dual-format argument parser: accepts Unix epoch and RFC 3339.
118pub mod parsers;
119
120/// Filesystem paths for the project-local database and app support directories.
121pub mod paths;
122
123/// SQLite pragma helpers applied on every connection.
124pub mod pragmas;
125
126/// Persistence layer: memories, entities, chunks and version history.
127pub mod storage;
128
129/// Display time zone for `*_iso` fields (flag `--tz`, env `SQLITE_GRAPHRAG_DISPLAY_TZ`, fallback UTC).
130pub mod tz;
131
132/// Real tokenizer of the embedding model for accurate token counting and chunking.
133pub mod tokenizer;
134
135mod embedded_migrations {
136    use refinery::embed_migrations;
137    embed_migrations!("migrations");
138}
139
140pub use embedded_migrations::migrations;
sqlite_graphrag/lib.rs

sqlite_graphrag/
lib.rs
