kglite 0.11.13

Pure-Rust knowledge graph engine — Cypher pipeline, snapshot/working CoW transactions, columnar/mmap/disk storage backends, optional dataset loaders (SEC EDGAR, Sodir, Wikidata). PyO3 wrappers live in the sibling kglite-py crate (the Python wheel); embeddable directly from any Rust binary without PyO3 in the dep tree.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

//! Filesystem layout for the Sodir workdir.
//!
//! ```text
//! path/
//!   sodir_index.json           per-dataset row counts + fetch timestamps
//!   blueprint_complement.json  (optional) persisted complement blueprint
//!   csv/{stem}.csv             cached dataset CSVs (flat directory)
//!   graph/                     built knowledge graph (disk mode only)
//! ```
//!
//! Sodir has only two storage modes — `memory` (rebuilt each open,
//! discarded) and `disk` (persisted under `graph/`).

use std::path::{Path, PathBuf};

/// Resolved paths for one Sodir workdir. Cheap to clone — wraps a
/// single `PathBuf`.
#[derive(Debug, Clone)]
pub struct Workdir {
    root: PathBuf,
}

impl Workdir {
    /// Wrap an existing or to-be-created workdir path. Does not touch
    /// the filesystem.
    pub fn new(root: impl Into<PathBuf>) -> Self {
        Self { root: root.into() }
    }

    pub fn root(&self) -> &Path {
        &self.root
    }

    /// `csv/` — the flat cache of dataset CSVs.
    pub fn csv_dir(&self) -> PathBuf {
        self.root.join("csv")
    }

    /// `csv/{stem}.csv`.
    pub fn csv_path(&self, stem: &str) -> PathBuf {
        self.csv_dir().join(format!("{stem}.csv"))
    }

    /// `sodir_index.json` — the per-dataset fetch manifest.
    pub fn index_file(&self) -> PathBuf {
        self.root.join("sodir_index.json")
    }

    /// `blueprint_complement.json` — persisted complement blueprint.
    pub fn complement_file(&self) -> PathBuf {
        self.root.join("blueprint_complement.json")
    }

    /// `_compiled_blueprint.json` — scratch file holding the merged
    /// blueprint passed to `from_blueprint`.
    pub fn compiled_blueprint(&self) -> PathBuf {
        self.root.join("_compiled_blueprint.json")
    }

    /// `graph/` — the built graph (disk mode).
    pub fn graph_dir(&self) -> PathBuf {
        self.root.join("graph")
    }

    /// `graph/disk_graph_meta.json` — its mtime drives the disk-mode
    /// "reopen → load, don't rebuild" cooldown short-circuit.
    pub fn disk_graph_meta(&self) -> PathBuf {
        self.graph_dir().join("disk_graph_meta.json")
    }

    /// `graph/sodir_source.json` — build-time dataset snapshot.
    pub fn source_meta(&self) -> PathBuf {
        self.graph_dir().join("sodir_source.json")
    }

    /// True if a disk-mode graph already exists.
    pub fn graph_exists(&self) -> bool {
        self.disk_graph_meta().is_file()
    }

    /// Age in days of the disk-mode graph metadata, or `None` if no
    /// graph has been built. Drives the disk-mode cooldown short-circuit
    /// in `Workdir`-managed dataset fetchers. Lifted from kglite-py in
    /// 0.10.1.
    pub fn disk_graph_age_days(&self) -> Option<f64> {
        crate::datasets::sodir::index::file_mtime_age_days(&self.disk_graph_meta())
    }

    /// Create the `csv/` and `graph/` directories (idempotent).
    pub fn ensure_dirs(&self) -> std::io::Result<()> {
        std::fs::create_dir_all(self.csv_dir())?;
        std::fs::create_dir_all(self.graph_dir())?;
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn paths_are_well_formed() {
        let w = Workdir::new("/tmp/sodir");
        assert_eq!(w.csv_dir(), Path::new("/tmp/sodir/csv"));
        assert_eq!(w.csv_path("field"), Path::new("/tmp/sodir/csv/field.csv"));
        assert_eq!(w.index_file(), Path::new("/tmp/sodir/sodir_index.json"));
        assert_eq!(w.graph_dir(), Path::new("/tmp/sodir/graph"));
        assert_eq!(
            w.disk_graph_meta(),
            Path::new("/tmp/sodir/graph/disk_graph_meta.json")
        );
    }

    #[test]
    fn ensure_dirs_idempotent_and_graph_probe() {
        let tmp = tempfile::tempdir().unwrap();
        let w = Workdir::new(tmp.path());
        assert!(!w.graph_exists());
        w.ensure_dirs().unwrap();
        w.ensure_dirs().unwrap(); // idempotent
        assert!(w.csv_dir().is_dir());
        assert!(w.graph_dir().is_dir());
        assert!(!w.graph_exists()); // dirs exist, but no disk_graph_meta.json
    }
}