graph_r/
lib.rs

1// Author: support@lituus.io
2// Copyright: lituus-io, all rights reserved
3//
4//! # graph-r
5//!
6//! An embedded, persistent knowledge graph that acts as the durable backend
7//! for `link-r`: link-r acquires and ranks (crawl, extract, hybrid search);
8//! graph-r remembers and serves (historical graph, adaptive freshness,
9//! token-budgeted local lookups). The two share one foreign key — the 64-bit
10//! xxh3 of a canonical URL — so a link-r index can be absorbed and then
11//! discarded while every lookup keeps resolving.
12//!
13//! ## Design tenets
14//!
15//! - **Zero-copy reads.** The base snapshot is an mmapped, checksummed,
16//!   sectioned file; lookups binary-search fixed-width records in place.
17//! - **Readers never block.** Snapshots pin a generation lock-free; a single
18//!   writer appends to a WAL and publishes into an append-only overlay;
19//!   compaction swaps generations under readers without pausing them.
20//! - **Lifetimes over `Arc`.** [`Snapshot`], [`NodeRef`], hits, and iterators
21//!   are borrow guards tied to the [`Store`]; nothing is reference-counted.
22//! - **Determinism.** Compaction is byte-reproducible; ranking, communities,
23//!   and query output are fully ordered with explicit tie-breaks.
24//! - **References, never bodies.** Nodes hold compact lookup metadata (title,
25//!   snippet, anchors, freshness); document bodies and dense vectors stay in
26//!   link-r or at the source URL. Lookups answer with URLs + anchors, which
27//!   is what keeps repeat token spend near zero.
28//!
29//! ## Quick start
30//!
31//! The link-r ingest path is link-r's `graph` feature (`link_r::bridge`),
32//! and object-store mirroring is objstore-r's `mirror` feature; both build
33//! on this crate's core, so none of them is a dependency here:
34//!
35//! ```toml
36//! uu-graph-r = "0.4"
37//! uu-link-r = { version = "0.4", features = ["graph"] }
38//! ```
39#![deny(unsafe_code)]
40#![deny(missing_docs)]
41#![deny(missing_debug_implementations)]
42#![deny(rust_2018_idioms)]
43#![deny(unreachable_pub)]
44#![warn(clippy::all, clippy::pedantic, clippy::cargo)]
45#![allow(
46    clippy::module_name_repetitions,
47    clippy::missing_errors_doc,
48    clippy::missing_panics_doc,
49    clippy::multiple_crate_versions,
50    clippy::cast_possible_truncation,
51    clippy::cast_precision_loss,
52    clippy::cast_sign_loss,
53    clippy::cast_possible_wrap
54)]
55
56// Core (always built; xxh3 is the only dependency): hashing, keys, byte
57// codecs, the checksummed container, errors and file primitives.
58pub mod bytesio;
59pub mod container;
60pub mod error;
61pub mod fsio;
62pub mod hash;
63pub mod key;
64pub mod text;
65
66/// Zero-copy read-only images (feature `mmap`).
67#[cfg(feature = "mmap")]
68pub mod mmap;
69
70// The embedded graph store (feature `store`, on by default).
71#[cfg(feature = "store")]
72mod compact;
73#[cfg(feature = "store")]
74pub mod format;
75#[cfg(feature = "store")]
76mod overlay;
77#[cfg(feature = "store")]
78pub mod query;
79#[cfg(feature = "store")]
80pub mod rank;
81#[cfg(feature = "store")]
82pub mod snapshot;
83#[cfg(feature = "store")]
84pub mod store;
85#[cfg(feature = "store")]
86pub mod traverse;
87#[cfg(feature = "store")]
88pub mod ttl;
89#[cfg(feature = "store")]
90pub mod writer;
91
92pub use error::{Error, Result};
93pub use key::{EdgeType, NodeId, SegKey, UrlKey};
94#[cfg(feature = "store")]
95pub use query::{Anchor, Hit, QueryOpts, TokenBudget};
96#[cfg(feature = "store")]
97pub use snapshot::{DueItem, NodeRef, SegRef, Snapshot};
98#[cfg(feature = "store")]
99pub use store::{Config, Durability, Store};
100#[cfg(feature = "store")]
101pub use traverse::{Direction, EdgeRef, Hop, LendingIterator, Neighbors, Walk};
102#[cfg(feature = "store")]
103pub use ttl::{Outcome, TtlConfig};
104#[cfg(feature = "store")]
105pub use writer::{DocRecord, SegmentRecord, Touch, Writer};
106
107/// Convenient single-line import of the working set.
108#[cfg(feature = "store")]
109pub mod prelude {
110    pub use crate::{
111        Config, DocRecord, Durability, EdgeType, Error, Hit, LendingIterator, NodeId, NodeRef,
112        Outcome, QueryOpts, Result, SegmentRecord, Snapshot, Store, TokenBudget, Touch, TtlConfig,
113        UrlKey, Writer,
114    };
115}
graph_r/lib.rs

graph_r/
lib.rs
