Crate arama_cache 

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

use arama_cache::{
    CacheConfig, DbLocation, ImageCacheConfig, ImageCacheWriter, LookupResult,
    UpsertImageRequest,
};

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"),
}

onetime — single-shot calls

use arama_cache::{DbLocation, ImageCacheWriter};

let result = ImageCacheWriter::onetime(DbLocation::WorkDir(None))?
    .lookup(std::path::Path::new("/data/photo.jpg"))?;

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.

Re-exports

pub use types::CacheRead;

pub use types::DirCacheSummary;

pub use types::ImageCacheEntry;

pub use types::ImageFeatures;

pub use types::LookupResult;

pub use types::UpsertImageRequest;

pub use types::UpsertVideoRequest;

pub use types::VideoCacheEntry;

pub use types::VideoFeatures;

Modules

types

Public types of the arama-cache facade.

Structs

CacheConfig

Session-level configuration shared by image and video handles.

ImageCacheConfig

ImageCacheReader

Read-only handle for image files. Clone only bumps Arc counters; clones share the same read pool and may be used from many threads.

ImageCacheWriter

Update handle for image files.

MigrationReport

Outcome of a migration run.

VideoCacheConfig

VideoCacheReader

Read-only handle for video files. Clone only bumps Arc counters; clones share the same read pool and may be used from many threads.

VideoCacheWriter

Update handle for video files.

Enums

CacheError

Errors produced by the arama-cache facade.

DbLocation

Where the cache database file lives.

Functions

migrate_v1_if_present

Import v1_db into v2_db when, and only when, the former exists and the latter does not. Returns Ok(None) when there is nothing to do.

Type Aliases

Result

Convenience alias used across the crate and by consumers.