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    /// Map common Chroma concepts onto the git-vdb API.
83    #[doc = include_str!("../docs/chroma-migration.md")]
84    pub mod chroma_migration {}
85
86    /// Connect document and vector frameworks through the public API or CLI.
87    #[doc = include_str!("../docs/integrations.md")]
88    pub mod integrations {}
89}
90
91pub use adapter::{Collection, Database};
92pub use model::{
93    CollectionConfig, CollectionInfo, Condition, CountResult, DeleteSelector, DiffResult, Distance,
94    Filter, GetRequest, GetResult, HistoryEntry, IndexConfig, JsonObject, MatchValue,
95    MutationResult, ObjectId, ObjectStats, Point, PointId, Query, QueryMode, QueryParams,
96    QueryResult, QueryStats, Range, Record, ScoredPoint, SnapshotInfo, SnapshotMutation,
97    ValidationReport, WriteResult,
98};
99pub use snapshot::{Snapshot, SnapshotEngine};
100pub use store::{open, CollectionHandle, Store};
101pub use text::{Document, DocumentHit, Embedder, TextCollection, TextQuery};
102#[cfg(feature = "fastembed")]
103pub use text::{FastEmbedInitOptions, FastEmbedModel, FastEmbedder};
104
105use thiserror::Error;
106
107#[derive(Debug, Error)]
108#[non_exhaustive]
109/// An error returned by a `git-vdb` operation.
110pub enum Error {
111    /// The underlying Git object database returned an error.
112    #[error("Git error: {0}")]
113    Git(#[from] git2::Error),
114    /// JSON serialization or deserialization failed.
115    #[error("JSON error: {0}")]
116    Json(#[from] serde_json::Error),
117    /// A filesystem operation failed.
118    #[error("I/O error: {0}")]
119    Io(#[from] std::io::Error),
120    /// An embedding provider could not initialize or generate vectors.
121    #[error("embedding error: {0}")]
122    Embedding(String),
123    /// The request or persisted value violated a declared invariant.
124    #[error("invalid request: {0}")]
125    Invalid(String),
126    /// A requested named collection does not exist.
127    #[error("collection not found: {0}")]
128    CollectionNotFound(String),
129    /// A collection could not be created because its name already exists.
130    #[error("collection already exists: {0}")]
131    CollectionExists(String),
132    /// A named write expected a different current collection root.
133    #[error("stale collection root: expected {expected}, actual {actual}")]
134    StaleRoot {
135        /// Root supplied by the writer as its compare-and-swap precondition.
136        expected: ObjectId,
137        /// Root resolved from the collection ref when the write was attempted.
138        actual: ObjectId,
139    },
140    /// A write was attempted through an immutable historical collection view.
141    #[error("read-only historical collection")]
142    ReadOnly,
143    /// Stored Git objects do not form a valid canonical collection root.
144    #[error("corrupt collection: {0}")]
145    Corrupt(String),
146}
147
148/// The result type returned by `git-vdb` operations.
149pub type Result<T> = std::result::Result<T, Error>;
git_vdb/lib.rs

git_vdb/
lib.rs
