Pixir.Provider.Cache (pixir v0.1.17)

Copy Markdown View Source

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.

px8 versions the virtual-overlay lifetime/delivery Tool contract (Anthropic: pa5). This intentionally restarts cache warming even though Layer 0 bytes are unchanged. Keep this prompt-contract change in a separate PR and observability window from independent WebSocket fixes; one release may include both verified changes. Do not attribute that cold start to transport.

Summary

Functions

metadata(input)

Build safe prompt-cache metadata for one Provider call.

prompt_contract_version()

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

stable_hash(term)

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

Functions

metadata(input)

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

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

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

stable_hash(term)

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

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