Search documentation of Ragex

# Ragex.Embeddings.Persistence (Ragex v0.4.0)

View Source

Persistence layer for embedding vectors.

Saves and loads embeddings to/from disk to avoid regeneration on restart. Uses ETS serialization for fast I/O and includes metadata for validation.

## Summary

### Types

cache_metadata()

### Functions

cache_path()

Returns the cache path for the current project.

cache_stats()

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

cache_valid?()

Checks if a valid cache exists for the current configuration.

clear(mode \\ :current)

Clears cached embeddings from disk.

default_cache_root()

Returns the default cache root directory.

generate_project_hash()

Generates a unique hash for the current project directory.

load()

Loads embeddings from disk if available and valid.

save(table_or_opts \\ nil)

Saves embeddings to disk.

stats()

Gets statistics about the cache.

## Types

# cache_metadata()

    @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?()

    @spec cache_valid?() :: boolean()

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()

Generates a unique hash for the current project directory.

This ensures different projects have separate caches. Uses the absolute path of the current working directory.

# load()

    @spec load() :: {: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_opts \\ nil)

    @spec save(atom() | reference()) :: {: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()

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

Gets statistics about the cache.

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