git_vdb/
lib.rs

1#![deny(missing_docs)]
2#![deny(rustdoc::broken_intra_doc_links)]
3
4//! A local vector database stored entirely in Git.
5//!
6//! The common path opens one directory, selects a collection, writes points,
7//! and searches. A missing database and collection are created on first write,
8//! and vector dimensions are inferred from that write.
9//!
10//! ```
11//! use git_vdb::{open, Point};
12//!
13//! # fn main() -> git_vdb::Result<()> {
14//! # let temporary = tempfile::TempDir::new()?;
15//! let db = open(temporary.path().join("vectors.git"))?;
16//! let docs = db.collection("docs");
17//! docs.upsert([
18//!     Point::new("east", [1.0, 0.0]),
19//!     Point::new("north", [0.0, 1.0]),
20//! ])?;
21//! let hits = docs.search([0.9, 0.1], 1)?;
22//! assert_eq!(hits[0].id.to_string(), "east");
23//! # Ok(())
24//! # }
25//! ```
26//!
27//! Use [`Store`] and [`CollectionHandle`] for ordinary embedded use. Use
28//! [`Database`] and [`Collection`] for explicitly configured collections,
29//! filters, detailed query statistics, history, and compare-and-swap writes.
30//! Use [`SnapshotEngine`] when another system owns naming and persistence.
31//!
32//! Equivalent configuration and points produce the same canonical Git root,
33//! independent of insertion order, repository path, history, or timestamps.
34//! The crate's semantic version and persisted [`mod@format`] version are
35//! separate compatibility boundaries; new roots use format version 2 and
36//! format-version-1 roots remain readable and mutable.
37
38pub mod adapter;
39mod codec;
40mod filter;
41pub mod model;
42mod root;
43mod root_v2;
44pub mod snapshot;
45mod store;
46pub mod text;
47
48/// The normative persisted format-version-2 specification.
49#[doc = include_str!("../docs/format-v2.md")]
50pub mod format {}
51
52/// The legacy persisted format-version-1 specification.
53#[doc = include_str!("../docs/format.md")]
54pub mod format_v1 {}
55
56/// Design notes for immutable root snapshots and named collection history.
57#[doc = include_str!("../docs/snapshots.md")]
58pub mod snapshots {}
59
60/// Task-oriented guides whose Rust examples are checked as doctests.
61pub mod guides {
62    /// Create and query a persistent database.
63    #[doc = include_str!("../docs/quickstart.md")]
64    pub mod quickstart {}
65
66    /// Safely create, reopen, and reuse a database.
67    #[doc = include_str!("../docs/persistence.md")]
68    pub mod persistence {}
69
70    /// Filter metadata through the detailed query API.
71    #[doc = include_str!("../docs/filtering.md")]
72    pub mod filtering {}
73
74    /// Read collection history and transport refs with Git.
75    #[doc = include_str!("../docs/history.md")]
76    pub mod history {}
77
78    /// Keep embedding-model identities consistent.
79    #[doc = include_str!("../docs/embeddings.md")]
80    pub mod embeddings {}
81}
82
83pub use adapter::{Collection, Database};
84pub use model::{
85    CollectionConfig, CollectionInfo, Condition, CountResult, DeleteSelector, DiffResult, Distance,
86    Filter, GetRequest, GetResult, HistoryEntry, IndexConfig, JsonObject, MatchValue, ObjectId,
87    ObjectStats, Point, PointId, Query, QueryMode, QueryParams, QueryResult, QueryStats, Range,
88    Record, ScoredPoint, SnapshotInfo, SnapshotMutation, ValidationReport, WriteResult,
89};
90pub use snapshot::{Snapshot, SnapshotEngine};
91pub use store::{open, CollectionHandle, Store};
92pub use text::{Document, Embedder, TextCollection};
93#[cfg(feature = "fastembed")]
94pub use text::{FastEmbedInitOptions, FastEmbedModel, FastEmbedder};
95
96use thiserror::Error;
97
98#[derive(Debug, Error)]
99#[non_exhaustive]
100/// An error returned by a `git-vdb` operation.
101pub enum Error {
102    /// The underlying Git object database returned an error.
103    #[error("Git error: {0}")]
104    Git(#[from] git2::Error),
105    /// JSON serialization or deserialization failed.
106    #[error("JSON error: {0}")]
107    Json(#[from] serde_json::Error),
108    /// A filesystem operation failed.
109    #[error("I/O error: {0}")]
110    Io(#[from] std::io::Error),
111    /// An embedding provider could not initialize or generate vectors.
112    #[error("embedding error: {0}")]
113    Embedding(String),
114    /// The request or persisted value violated a declared invariant.
115    #[error("invalid request: {0}")]
116    Invalid(String),
117    /// A requested named collection does not exist.
118    #[error("collection not found: {0}")]
119    CollectionNotFound(String),
120    /// A collection could not be created because its name already exists.
121    #[error("collection already exists: {0}")]
122    CollectionExists(String),
123    /// A named write expected a different current collection root.
124    #[error("stale collection root: expected {expected}, actual {actual}")]
125    StaleRoot {
126        /// Root supplied by the writer as its compare-and-swap precondition.
127        expected: ObjectId,
128        /// Root resolved from the collection ref when the write was attempted.
129        actual: ObjectId,
130    },
131    /// A write was attempted through an immutable historical collection view.
132    #[error("read-only historical collection")]
133    ReadOnly,
134    /// Stored Git objects do not form a valid canonical collection root.
135    #[error("corrupt collection: {0}")]
136    Corrupt(String),
137}
138
139/// The result type returned by `git-vdb` operations.
140pub type Result<T> = std::result::Result<T, Error>;
git_vdb/lib.rs

git_vdb/
lib.rs
