sqlite_graphrag/
cli.rs

1use crate::commands::*;
2use crate::i18n::{current, Language};
3use clap::{Parser, Subcommand};
4
5/// Retorna o número máximo de invocações simultâneas permitidas pela heurística de CPU.
6fn max_concurrency_ceiling() -> usize {
7    std::thread::available_parallelism()
8        .map(|n| n.get() * 2)
9        .unwrap_or(8)
10}
11
12#[derive(Copy, Clone, Debug, clap::ValueEnum)]
13pub enum RelationKind {
14    AppliesTo,
15    Uses,
16    DependsOn,
17    Causes,
18    Fixes,
19    Contradicts,
20    Supports,
21    Follows,
22    Related,
23    Mentions,
24    Replaces,
25    TrackedIn,
26}
27
28impl RelationKind {
29    pub fn as_str(&self) -> &'static str {
30        match self {
31            Self::AppliesTo => "applies_to",
32            Self::Uses => "uses",
33            Self::DependsOn => "depends_on",
34            Self::Causes => "causes",
35            Self::Fixes => "fixes",
36            Self::Contradicts => "contradicts",
37            Self::Supports => "supports",
38            Self::Follows => "follows",
39            Self::Related => "related",
40            Self::Mentions => "mentions",
41            Self::Replaces => "replaces",
42            Self::TrackedIn => "tracked_in",
43        }
44    }
45}
46
47#[derive(Copy, Clone, Debug, clap::ValueEnum)]
48pub enum GraphExportFormat {
49    Json,
50    Dot,
51    Mermaid,
52}
53
54#[derive(Parser)]
55#[command(name = "sqlite-graphrag")]
56#[command(version)]
57#[command(about = "Local GraphRAG memory for LLMs in a single SQLite file")]
58#[command(arg_required_else_help = true)]
59pub struct Cli {
60    /// Número máximo de invocações CLI simultâneas permitidas (default: 4).
61    ///
62    /// Limita o semáforo de contagem de slots de concorrência. O valor é restrito
63    /// ao intervalo [1, 2×nCPUs]. Valores acima do teto são rejeitados com exit 2.
64    #[arg(long, global = true, value_name = "N")]
65    pub max_concurrency: Option<usize>,
66
67    /// Aguardar até SECONDS por um slot livre antes de desistir (exit 75).
68    ///
69    /// Útil em pipelines de agentes que fazem retry: a instância faz polling a
70    /// cada 500 ms até o timeout ou um slot abrir. Default: 300s (5 minutos).
71    #[arg(long, global = true, value_name = "SECONDS")]
72    pub wait_lock: Option<u64>,
73
74    /// Pular a verificação de memória disponível antes de carregar o modelo.
75    ///
76    /// Uso exclusivo em testes automatizados onde a alocação real não ocorre.
77    #[arg(long, global = true, hide = true, default_value_t = false)]
78    pub skip_memory_guard: bool,
79
80    /// Idioma das mensagens humanas (stderr). Aceita `en` ou `pt`.
81    ///
82    /// Sem a flag, detecta via env `SQLITE_GRAPHRAG_LANG` e depois `LC_ALL`/`LANG`.
83    /// JSON de stdout é determinístico e idêntico entre idiomas — apenas
84    /// strings destinadas a humanos são afetadas.
85    #[arg(long, global = true, value_enum, value_name = "LANG")]
86    pub lang: Option<crate::i18n::Language>,
87
88    /// Fuso horário para campos `*_iso` no JSON de saída (ex: `America/Sao_Paulo`).
89    ///
90    /// Aceita qualquer nome IANA da IANA Time Zone Database. Sem a flag, usa
91    /// `SQLITE_GRAPHRAG_DISPLAY_TZ`; se ausente, usa UTC. Não afeta campos epoch inteiros.
92    #[arg(long, global = true, value_name = "IANA")]
93    pub tz: Option<chrono_tz::Tz>,
94
95    #[command(subcommand)]
96    pub command: Commands,
97}
98
99#[cfg(test)]
100mod testes_formato_json_only {
101    use super::Cli;
102    use clap::Parser;
103
104    #[test]
105    fn restore_aceita_apenas_format_json() {
106        assert!(Cli::try_parse_from([
107            "sqlite-graphrag",
108            "restore",
109            "--name",
110            "mem",
111            "--version",
112            "1",
113            "--format",
114            "json",
115        ])
116        .is_ok());
117
118        assert!(Cli::try_parse_from([
119            "sqlite-graphrag",
120            "restore",
121            "--name",
122            "mem",
123            "--version",
124            "1",
125            "--format",
126            "text",
127        ])
128        .is_err());
129    }
130
131    #[test]
132    fn hybrid_search_aceita_apenas_format_json() {
133        assert!(Cli::try_parse_from([
134            "sqlite-graphrag",
135            "hybrid-search",
136            "query",
137            "--format",
138            "json",
139        ])
140        .is_ok());
141
142        assert!(Cli::try_parse_from([
143            "sqlite-graphrag",
144            "hybrid-search",
145            "query",
146            "--format",
147            "markdown",
148        ])
149        .is_err());
150    }
151
152    #[test]
153    fn remember_recall_rename_vacuum_json_only() {
154        assert!(Cli::try_parse_from([
155            "sqlite-graphrag",
156            "remember",
157            "--name",
158            "mem",
159            "--type",
160            "project",
161            "--description",
162            "desc",
163            "--format",
164            "json",
165        ])
166        .is_ok());
167        assert!(Cli::try_parse_from([
168            "sqlite-graphrag",
169            "remember",
170            "--name",
171            "mem",
172            "--type",
173            "project",
174            "--description",
175            "desc",
176            "--format",
177            "text",
178        ])
179        .is_err());
180
181        assert!(
182            Cli::try_parse_from(["sqlite-graphrag", "recall", "query", "--format", "json",])
183                .is_ok()
184        );
185        assert!(
186            Cli::try_parse_from(["sqlite-graphrag", "recall", "query", "--format", "text",])
187                .is_err()
188        );
189
190        assert!(Cli::try_parse_from([
191            "sqlite-graphrag",
192            "rename",
193            "--name",
194            "old",
195            "--new-name",
196            "new",
197            "--format",
198            "json",
199        ])
200        .is_ok());
201        assert!(Cli::try_parse_from([
202            "sqlite-graphrag",
203            "rename",
204            "--name",
205            "old",
206            "--new-name",
207            "new",
208            "--format",
209            "markdown",
210        ])
211        .is_err());
212
213        assert!(Cli::try_parse_from(["sqlite-graphrag", "vacuum", "--format", "json",]).is_ok());
214        assert!(Cli::try_parse_from(["sqlite-graphrag", "vacuum", "--format", "text",]).is_err());
215    }
216}
217
218impl Cli {
219    /// Valida flags de concorrência e retorna erro descritivo localizado se inválidas.
220    ///
221    /// Requer que `crate::i18n::init()` já tenha sido chamado (ocorre antes desta função
222    /// no fluxo de `main`). Em inglês emite mensagens EN; em português emite PT.
223    pub fn validate_flags(&self) -> Result<(), String> {
224        if let Some(n) = self.max_concurrency {
225            if n == 0 {
226                return Err(match current() {
227                    Language::English => "--max-concurrency must be >= 1".to_string(),
228                    Language::Portugues => "--max-concurrency deve ser >= 1".to_string(),
229                });
230            }
231            let teto = max_concurrency_ceiling();
232            if n > teto {
233                return Err(match current() {
234                    Language::English => format!(
235                        "--max-concurrency {n} exceeds the ceiling of {teto} (2×nCPUs) on this system"
236                    ),
237                    Language::Portugues => format!(
238                        "--max-concurrency {n} excede o teto de {teto} (2×nCPUs) neste sistema"
239                    ),
240                });
241            }
242        }
243        Ok(())
244    }
245}
246
247#[derive(Subcommand)]
248pub enum Commands {
249    /// Initialize database and download embedding model
250    Init(init::InitArgs),
251    /// Save a memory with optional entity graph
252    Remember(remember::RememberArgs),
253    /// Search memories semantically
254    Recall(recall::RecallArgs),
255    /// Read a memory by exact name
256    Read(read::ReadArgs),
257    /// List memories with filters
258    List(list::ListArgs),
259    /// Soft-delete a memory
260    Forget(forget::ForgetArgs),
261    /// Permanently delete soft-deleted memories
262    Purge(purge::PurgeArgs),
263    /// Rename a memory preserving history
264    Rename(rename::RenameArgs),
265    /// Edit a memory's body or description
266    Edit(edit::EditArgs),
267    /// List all versions of a memory
268    History(history::HistoryArgs),
269    /// Restore a memory to a previous version
270    Restore(restore::RestoreArgs),
271    /// Search using hybrid vector + full-text search
272    HybridSearch(hybrid_search::HybridSearchArgs),
273    /// Show database health
274    Health(health::HealthArgs),
275    /// Apply pending schema migrations
276    Migrate(migrate::MigrateArgs),
277    /// Resolve namespace precedence for the current invocation
278    NamespaceDetect(namespace_detect::NamespaceDetectArgs),
279    /// Run PRAGMA optimize on the database
280    Optimize(optimize::OptimizeArgs),
281    /// Show database statistics
282    Stats(stats::StatsArgs),
283    /// Create a checkpointed copy safe for file sync
284    SyncSafeCopy(sync_safe_copy::SyncSafeCopyArgs),
285    /// Run VACUUM after checkpointing the WAL
286    Vacuum(vacuum::VacuumArgs),
287    /// Create an explicit relationship between two entities
288    Link(link::LinkArgs),
289    /// Remove a specific relationship between two entities
290    Unlink(unlink::UnlinkArgs),
291    /// List memories connected via the entity graph
292    Related(related::RelatedArgs),
293    /// Export a graph snapshot in json, dot or mermaid
294    Graph(graph_export::GraphArgs),
295    /// Remove entities that have no memories and no relationships
296    CleanupOrphans(cleanup_orphans::CleanupOrphansArgs),
297    #[command(name = "__debug_schema", hide = true)]
298    DebugSchema(debug_schema::DebugSchemaArgs),
299}
300
301#[derive(Copy, Clone, Debug, clap::ValueEnum)]
302pub enum MemoryType {
303    User,
304    Feedback,
305    Project,
306    Reference,
307    Decision,
308    Incident,
309    Skill,
310}
311
312impl MemoryType {
313    pub fn as_str(&self) -> &'static str {
314        match self {
315            Self::User => "user",
316            Self::Feedback => "feedback",
317            Self::Project => "project",
318            Self::Reference => "reference",
319            Self::Decision => "decision",
320            Self::Incident => "incident",
321            Self::Skill => "skill",
322        }
323    }
324}
sqlite_graphrag/cli.rs

sqlite_graphrag/
cli.rs
