Search documentation of Ragex

# Ragex.AI.Features.Cache (Ragex v0.4.0)

View Source

Feature-aware wrapper around Ragex.AI.Cache.

Provides convenience functions that automatically use feature-specific cache TTLs and configuration from Features.Config.

## Usage

    alias Ragex.AI.Features.Cache

    # Get cached response for validation errors
    case Cache.get(:validation_error_explanation, error, context) do
      {:ok, response} -> response
      {:error, :not_found} ->
        # Generate and cache
        response = generate_ai_response(...)
        Cache.put(:validation_error_explanation, error, context, response)
        response
    end

    # Or use fetch! helper
    response = Cache.fetch!(:refactor_preview_commentary, params, context, fn ->
      generate_ai_response(...)
    end)

## Summary

### Types

cache_result()
feature()

### Functions

clear(feature)

Clear cache for a specific feature.

enabled?(feature, opts \\ [])

Check if caching is enabled for a specific feature.

fetch(feature, query, context, generator_fn, opts \\ [])

Fetch from cache or generate if not found (with error handling).

fetch!(feature, query, context, generator_fn, opts \\ [])

Fetch from cache or generate if not found.

get(feature, query, context, opts \\ [])

Get a cached AI response for a specific feature.

put(feature, query, context, response, opts \\ [])

Store an AI response in the cache for a specific feature.

stats()

Get cache statistics for all features.

warm_up(entries)

Warm up the cache with pre-computed responses.

## Types

# cache_result()

    @type cache_result() :: {:ok, any()} | {:error, :not_found}

# feature()

    @type feature() :: Ragex.AI.Features.Config.feature()

## Functions

# clear(feature)

    @spec clear(feature()) :: :ok

Clear cache for a specific feature.

Note: Currently clears the entire AI cache. Future versions may implement per-feature cache partitioning.

## Parameters

- `feature` - Feature identifier atom

## Returns

- `:ok`

# enabled?(feature, opts \\ [])

    @spec enabled?(
      feature(),
      keyword()
    ) :: boolean()

Check if caching is enabled for a specific feature.

Takes into account:

1. Global AI cache enabled flag
2. Feature-specific enabled flag
3. Per-call overrides

## Parameters

- `feature` - Feature identifier atom
- `opts` - Options with potential overrides

## Returns

- `true` if caching should be used
- `false` otherwise

# fetch(feature, query, context, generator_fn, opts \\ [])

    @spec fetch(feature(), any(), any(), function(), keyword()) ::
      {:ok, any()} | {:error, term()}

Fetch from cache or generate if not found (with error handling).

Like `fetch!/4` but propagates errors from the generator function.

## Returns

- `{:ok, response}` on success (cached or generated)
- `{:error, reason}` if generation fails

# fetch!(feature, query, context, generator_fn, opts \\ [])

    @spec fetch!(feature(), any(), any(), function(), keyword()) :: any()

Fetch from cache or generate if not found.

This is the recommended way to use the cache - it handles both retrieval and storage in one call.

## Parameters

- `feature` - Feature identifier atom
- `query` - Query or input data
- `context` - Context map
- `generator_fn` - Function to call if cache miss (arity 0)
- `opts` - Additional options

## Returns

- Cached or freshly generated response

## Examples

    response = Cache.fetch!(
      :validation_error_explanation,
      error,
      context,
      fn -> ValidationAI.generate_explanation(error, context) end
    )

# get(feature, query, context, opts \\ [])

    @spec get(feature(), any(), any(), keyword()) :: cache_result()

Get a cached AI response for a specific feature.

Automatically uses feature-specific TTL and configuration.

## Parameters

- `feature` - Feature identifier atom
- `query` - Query or input data
- `context` - Context map
- `opts` - Additional options (merged with feature config)

## Returns

- `{:ok, response}` if cached
- `{:error, :not_found}` if not cached or expired

# put(feature, query, context, response, opts \\ [])

    @spec put(feature(), any(), any(), any(), keyword()) :: :ok

Store an AI response in the cache for a specific feature.

Automatically uses feature-specific TTL and configuration.

## Parameters

- `feature` - Feature identifier atom
- `query` - Query or input data
- `context` - Context map
- `response` - Response to cache
- `opts` - Additional options

## Returns

- `:ok`

# stats()

    @spec stats() :: map()

Get cache statistics for all features.

Returns general cache stats plus per-feature breakdown if available.

## Returns

- Map of statistics

# warm_up(entries)

    @spec warm_up([{feature(), any(), any(), any()}]) :: :ok

Warm up the cache with pre-computed responses.

Useful for seeding the cache with known common patterns.

## Parameters

- `entries` - List of {feature, query, context, response} tuples

## Returns

- `:ok`

## Examples

    Cache.warm_up([
      {:validation_error_explanation, error1, context1, response1},
      {:refactor_preview_commentary, params1, context1, response1}
    ])