Spectre.Router.SemanticCache behaviour (Spectre v0.3.0)

Adapter boundary for semantic cache lookups.

Configure one of:

semantic_lookup: &MyCache.lookup/2
semantic_cache: MyCache
semantic_cache: {MyCache, :lookup}

The adapter should return {:ok, map} for accepted route-like results or {:error, reason} for misses.

Summary

Callbacks

clear(module, keyword)

delete(module, t, keyword)

examples(module, keyword)

get_example(module, t, keyword)

load_snapshot(module, term, keyword)

lookup(t, keyword)

put(t, map, keyword)

relabel(module, t, atom, keyword)

snapshot(module, keyword)

update_example(module, t, map, keyword)

verify(module, t, keyword)

Functions

clear(agent, opts \\ [])

Clears semantic-cache state for an agent.

delete(agent, id, opts \\ [])

Deletes an online learned example.

examples(agent, opts \\ [])

Lists semantic-cache examples for an agent.

get_example(agent, id, opts \\ [])

Fetches one semantic-cache example by id.

learn_eligibility(agent, route)

Explains whether a resolved route should be learned into the semantic cache.

learnable?(agent, route)

Convenience boolean form of learn_eligibility/2.

load_snapshot(agent, snapshot_or_opts, opts \\ [])

Loads online learned examples and their stored embeddings from a snapshot.

lookup(text, opts)

Looks up a message in the configured semantic cache.

put(text, result, opts)

Stores a semantic-cache example.

relabel(agent, id, new_label, opts \\ [])

Relabels an online learned example and marks it verified.

snapshot(agent, opts \\ [])

Snapshots semantic-cache examples and their stored embeddings.

update_example(agent, id, attrs, opts \\ [])

Edits an online learned example in place.

verify(agent, id, opts \\ [])

Marks an online learned example as verified.

Callbacks

clear(module, keyword)

(optional)

@callback clear(
  module(),
  keyword()
) :: :ok | {:ok, term()} | {:error, term()}

delete(module, t, keyword)

(optional)

@callback delete(module(), String.t(), keyword()) ::
  :ok | {:ok, term()} | {:error, term()}

examples(module, keyword)

(optional)

@callback examples(
  module(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

get_example(module, t, keyword)

(optional)

@callback get_example(module(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

load_snapshot(module, term, keyword)

(optional)

@callback load_snapshot(module(), term(), keyword()) ::
  :ok | {:ok, term()} | {:error, term()}

lookup(t, keyword)

@callback lookup(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}

put(t, map, keyword)

(optional)

@callback put(String.t(), map(), keyword()) :: :ok | {:ok, term()} | {:error, term()}

relabel(module, t, atom, keyword)

(optional)

@callback relabel(module(), String.t(), atom(), keyword()) ::
  {:ok, map()} | {:error, term()}

snapshot(module, keyword)

(optional)

@callback snapshot(
  module(),
  keyword()
) :: {:ok, term()} | {:error, term()}

update_example(module, t, map, keyword)

(optional)

@callback update_example(module(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, term()}

verify(module, t, keyword)

(optional)

@callback verify(module(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Functions

clear(agent, opts \\ [])

@spec clear(
  module(),
  keyword()
) :: :ok | {:error, term()}

Clears semantic-cache state for an agent.

Spectre's built-in learned cache is always cleared. When a custom semantic_cache: module is configured, that adapter must also implement clear/2.

delete(agent, id, opts \\ [])

@spec delete(module(), String.t(), keyword()) ::
  :ok | {:ok, term()} | {:error, term()}

Deletes an online learned example.

examples(agent, opts \\ [])

@spec examples(
  module(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Lists semantic-cache examples for an agent.

get_example(agent, id, opts \\ [])

@spec get_example(module(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Fetches one semantic-cache example by id.

learn_eligibility(agent, route)

@spec learn_eligibility(module(), Spectre.Route.t() | map() | nil) ::
  :ok | {:skip, atom()}

Explains whether a resolved route should be learned into the semantic cache.

Returns :ok when learning is safe, or {:skip, reason} with one of :missing_route, :route_not_accepted, :semantic_cache_route (the route was served from the cache itself), :route_not_found, :route_not_learnable (the matched rule is not learn: true), or :protected_action (the route stages a policy-protected action — learning it would let the cache bypass future consent classification).

case SemanticCache.learn_eligibility(MyApp.Agent, result.route) do
  :ok -> SemanticCache.put(text, result.route, opts)
  {:skip, _reason} -> :ok
end

learnable?(agent, route)

@spec learnable?(module(), Spectre.Route.t() | map() | nil) :: boolean()

Convenience boolean form of learn_eligibility/2.

load_snapshot(agent, snapshot_or_opts, opts \\ [])

@spec load_snapshot(module(), term(), keyword()) ::
  :ok | {:ok, term()} | {:error, term()}

Loads online learned examples and their stored embeddings from a snapshot.

lookup(text, opts)

@spec lookup(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Looks up a message in the configured semantic cache.

put(text, result, opts)

@spec put(String.t(), map(), keyword()) :: :ok | {:ok, term()} | {:error, term()}

Stores a semantic-cache example.

relabel(agent, id, new_label, opts \\ [])

@spec relabel(module(), String.t(), atom(), keyword()) ::
  {:ok, map()} | {:error, term()}

Relabels an online learned example and marks it verified.

snapshot(agent, opts \\ [])

@spec snapshot(
  module(),
  keyword()
) :: {:ok, term()} | {:error, term()}

Snapshots semantic-cache examples and their stored embeddings.

update_example(agent, id, attrs, opts \\ [])

@spec update_example(module(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, term()}

Edits an online learned example in place.

Supported attrs: :text (re-embedded through the configured embedding adapter), :label (must name a cacheable route), and :verified.

{:ok, updated} =
  Spectre.Router.SemanticCache.update_example(MyApp.Agent, id, %{label: :PRICING})

verify(agent, id, opts \\ [])

@spec verify(module(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Marks an online learned example as verified.