arama-cache 0.36.2

Embedding and thumbnail cache facade over localcache for arama
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

//! # arama-cache
//!
//! Caches AI inference results (thumbnails + feature vectors) for image
//! and video files in SQLite, backed by the [`localcache`] engine
//! (RFC 002). The cache database holds two namespaces — `image` and
//! `video` — in a single file, with per-file freshness tracked by
//! metadata-first change detection.
//!
//! ## Choosing a handle
//!
//! | Type | Purpose |
//! |---|---|
//! | [`ImageCacheWriter`] | Register, look up, and delete image entries |
//! | [`ImageCacheReader`] | Look up image entries (parallel-friendly) |
//! | [`VideoCacheWriter`] | Register, look up, and delete video entries |
//! | [`VideoCacheReader`] | Look up video entries (parallel-friendly) |
//!
//! Writers serialize database writes through a single connection; both
//! writers and readers serve lookups from a pool of `read_conns`
//! read-only connections, so cloned readers can fan lookups out across
//! threads.
//!
//! ## Basic usage
//!
//! ```rust,no_run
//! use arama_cache::{
//!     CacheConfig, DbLocation, ImageCacheConfig, ImageCacheWriter, LookupResult,
//!     UpsertImageRequest,
//! };
//!
//! # fn main() -> anyhow::Result<()> {
//! let writer = ImageCacheWriter::as_session(ImageCacheConfig {
//!     cache_config: CacheConfig {
//!         db_location: DbLocation::AppCache(None),
//!         read_conns: 4,
//!         thumbnail_dir: Some("/var/cache/myapp/thumbs".into()),
//!     },
//! })?;
//!
//! writer.upsert(UpsertImageRequest {
//!     path: "/data/photo.jpg".into(),
//!     clip_vector: Some(vec![0.1, 0.2, 0.3]),
//! })?;
//!
//! match writer.lookup(std::path::Path::new("/data/photo.jpg"))? {
//!     LookupResult::Hit(entry) => {
//!         println!("thumbnail: {:?}", entry.thumbnail_path);
//!         println!("features:  {:?}", entry.features);
//!     }
//!     LookupResult::Invalidated => println!("file changed; will be recomputed"),
//!     LookupResult::Miss => println!("not cached"),
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ## `onetime` — single-shot calls
//!
//! ```rust,no_run
//! use arama_cache::{DbLocation, ImageCacheWriter};
//!
//! # fn main() -> anyhow::Result<()> {
//! let result = ImageCacheWriter::onetime(DbLocation::WorkDir(None))?
//!     .lookup(std::path::Path::new("/data/photo.jpg"))?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Migrating from the v1 cache
//!
//! Applications upgrading from the `file-feature-cache`-backed v1
//! database run [`migrate_v1_if_present`] once at startup; it is a no-op
//! when there is nothing to migrate.

mod core;
pub mod types;

pub use core::engine::{CacheConfig, CacheError, DbLocation, Result};
pub use core::image::{ImageCacheConfig, ImageCacheReader, ImageCacheWriter};
pub use core::migrate::{MigrationReport, migrate_v1_if_present};
pub use core::video::{VideoCacheConfig, VideoCacheReader, VideoCacheWriter};
pub use types::{
    CacheRead, DirCacheSummary, ImageCacheEntry, ImageFeatures, LookupResult, UpsertImageRequest,
    UpsertVideoRequest, VideoCacheEntry, VideoFeatures,
};