Ragex.Embeddings.Persistence (Ragex v0.10.0)

@type cache_metadata() :: %{
  version: integer(),
  model_id: atom(),
  model_repo: String.t(),
  dimensions: pos_integer(),
  timestamp: integer(),
  entity_count: non_neg_integer()
}

Functions

cache_path()

Returns the cache path for the current project.

cache_stats()

@spec cache_stats() :: {:ok, map()} | {:error, term()}

Returns statistics about the cache (alias for stats/0).

Provides information about cache file, size, age, and contents.

Returns

{:ok, stats_map} - Cache statistics including:
- :cache_path - Path to the cache file
- :file_size - Size of the cache file in bytes
- :metadata - Cache metadata (version, model, dimensions, timestamp, entity count)
- :valid? - Whether the cache is valid for the current configuration
{:error, :not_found} - No cache file exists
{:error, reason} - Other error

cache_valid?(project_path \\ nil)

Checks if a valid cache exists for the current configuration.

clear(mode \\ :current)

@spec clear(atom() | {atom(), integer()}) :: :ok | {:error, term()}

Clears cached embeddings from disk.

Modes

:current - Clear current project cache
:all - Clear all caches
{:older_than, days} - Clear caches older than N days

Returns

:ok - Success
{:error, reason} - Failure reason

default_cache_root()

Returns the default cache root directory.

generate_project_hash(project_path \\ nil)

Generates a unique hash for a project directory.

This ensures different projects have separate caches. When project_path is nil, falls back to the current working directory.

Parameters

project_path - Absolute path to the project (optional, defaults to CWD)

load(project_path \\ nil)

@spec load(String.t() | nil) :: {:ok, non_neg_integer()} | {:error, term()}

Loads embeddings from disk if available and valid.

Validates:

Model compatibility (same model ID or compatible dimensions)
Cache version
File integrity

Returns

{:ok, count} - Successfully loaded count embeddings
{:error, :not_found} - No cache file exists
{:error, :incompatible_model} - Model mismatch
{:error, reason} - Other failure

save(table_or_nil \\ nil, project_path \\ nil)

@spec save(atom() | reference() | nil, String.t() | nil) ::
  {:ok, Path.t()} | {:error, term()}

Saves embeddings to disk.

Can be called with:

ETS table reference (for tests/direct use)
No arguments (uses Store.embeddings_table())

Returns

{:ok, path} - Success with cache file path
{:error, reason} - Failure reason

stats(project_path \\ nil)

Gets statistics about the cache.

Returns information about cache file, size, age, and contents.