# `Pixir.Provider.Cache`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/provider/cache.ex#L1)

Prompt-cache key helpers for the OpenAI Responses dialect.

A cache key is a routing hint for a stable prefix family. It must be short and safe:
no raw workspace paths, user text, request ids, timestamps, emails, or secrets. The
Provider still combines this hint with its own prompt-prefix hash; Pixir treats the key
as optimization metadata, never as durable state.

# `metadata`

```elixir
@spec metadata(map()) :: {:ok, map()} | {:error, :invalid_args}
```

Build safe prompt-cache metadata for one Provider call.

Expected fields are `:session_id`, `:model`, `:mode`, `:tools`, and `:skill_index`;
`:fork_root_session_id` is optional and defaults to `:session_id` (a fork passes its
fork-tree ROOT so the whole tree shares one cache family — ADR 0020).
Returns a string-keyed map so it can be copied into a `provider_usage` Event.

# `prompt_contract_version`

```elixir
@spec prompt_contract_version() :: String.t()
```

The current Prompt Contract version segment (leads every cache key).

# `stable_hash`

```elixir
@spec stable_hash(term()) :: {:ok, String.t()} | {:error, term()}
```

Return a stable short hash for maps, lists, and scalar values.

---

*Consult [api-reference.md](api-reference.md) for complete listing*