Pixir.Config (pixir v0.1.14)

Loader for ~/.pixir/config.json (ADR 0005 ergonomics).

Parses user-global knobs, ignores invalid values with warnings (never hard-fails on a bad field), and resolves effective values with this precedence for each key:

config :pixir, :key (programmatic override)
~/.pixir/config.json
built-in default

Model id keeps the Provider chain: config :pixir, :model → PIXIR_MODEL → "model" in config.json → built-in default.

Legacy keys (model, models, context_windows) remain supported alongside the expanded surface (permission_default, reasoning.effort, text.verbosity, bash_timeout_ms, bash_timeout_max_ms, host_commands, max_retries, stream_idle_timeout_ms, compaction.tail_events).

bash_timeout_max_ms is an override cap, not a way to shorten the configured default. The effective cap is never lower than bash_timeout_ms; when config asks for a lower cap, load/1 reports a warning and raises the effective cap so the default bash command remains executable.

compaction.native is a late-bound overlay preference (nil = no preference, false = off, true = request on). Invalid values warn and stay nil so they cannot force the overlay off.

Summary

Types

load_result()

warning()

Functions

bash_timeout_max_ms(opts \\ [])

bash_timeout_ms(opts \\ [])

compaction_model_assisted(opts \\ [])

Whether model-assisted compaction is enabled (default false).

compaction_native(opts \\ [])

Native OpenAI compaction overlay preference.

compaction_tail_events(opts \\ [])

file_anthropic_models(opts \\ [])

Anthropic models list from config.json only, or nil when absent/invalid.

file_context_windows(opts \\ [])

Context-window overrides from config.json (model => positive integer).

file_model(opts \\ [])

Effective model when config.json is present; application and env precedence still applies.

file_models(opts \\ [])

Models list from config.json only, or nil when absent/invalid.

host_commands(opts \\ [])

Resolved host-command boundary limits.

load(opts \\ [])

Load and resolve config.json.

max_retries(opts \\ [])

merge_provider_opts(provider_opts, config_opts \\ [])

Merge config defaults into Provider opts without clobbering explicit values.

models_refreshed_at(opts \\ [])

UTC timestamp written by the last explicit model-catalog refresh, if present.

permission_default(opts \\ [])

Resolved permission default (:auto, :ask, or :read_only).

reasoning_effort(opts \\ [])

Resolved reasoning effort, or nil to omit and let the model default.

request_snapshot(opts \\ [])

Resolve one immutable model/backend snapshot from exactly one source-document read.

responses_backend(opts \\ [])

Resolve only the explicit Responses backend descriptor from one request snapshot.

stream_idle_timeout_ms(opts \\ [])

text_verbosity(opts \\ [])

Resolved text verbosity, or nil to omit and let the model default.

valid_reasoning_efforts()

Accepted reasoning effort ids.

web_search(opts \\ [])

Resolved hosted web search preference.

Types

load_result()

@type load_result() :: %{required(String.t()) => term()}

warning()

@type warning() :: %{required(String.t()) => String.t()}

Functions

bash_timeout_max_ms(opts \\ [])

@spec bash_timeout_max_ms(keyword()) :: pos_integer()

bash_timeout_ms(opts \\ [])

@spec bash_timeout_ms(keyword()) :: pos_integer()

compaction_model_assisted(opts \\ [])

@spec compaction_model_assisted(keyword()) :: boolean()

Whether model-assisted compaction is enabled (default false).

compaction_native(opts \\ [])

@spec compaction_native(keyword()) :: boolean() | nil

Native OpenAI compaction overlay preference.

Absence (nil) means no preference; after Provider/backend resolve the overlay defaults on for chatgpt_codex / API-key OpenAI. Explicit false always wins. Explicit true still refuses open_responses and Anthropic. Invalid values are ignored with a warning and stored as nil.

compaction_tail_events(opts \\ [])

@spec compaction_tail_events(keyword()) :: pos_integer()

file_anthropic_models(opts \\ [])

@spec file_anthropic_models(keyword()) :: [String.t()] | nil

Anthropic models list from config.json only, or nil when absent/invalid.

file_context_windows(opts \\ [])

@spec file_context_windows(keyword()) :: %{required(String.t()) => pos_integer()}

Context-window overrides from config.json (model => positive integer).

file_model(opts \\ [])

@spec file_model(keyword()) :: String.t() | nil

Effective model when config.json is present; application and env precedence still applies.

file_models(opts \\ [])

@spec file_models(keyword()) :: [String.t()] | nil

Models list from config.json only, or nil when absent/invalid.

host_commands(opts \\ [])

@spec host_commands(keyword()) ::
  {:ok, %{required(String.t()) => non_neg_integer() | pos_integer()}}

Resolved host-command boundary limits.

load(opts \\ [])

@spec load(keyword()) :: load_result()

Load and resolve config.json.

Returns a JSON-serializable map with "path", "present", "effective", and "warnings". Missing files yield defaults and an empty warning list.

max_retries(opts \\ [])

@spec max_retries(keyword()) :: non_neg_integer()

merge_provider_opts(provider_opts, config_opts \\ [])

@spec merge_provider_opts(keyword(), keyword()) :: keyword()

Merge config defaults into Provider opts without clobbering explicit values.

models_refreshed_at(opts \\ [])

@spec models_refreshed_at(keyword()) :: String.t() | nil

UTC timestamp written by the last explicit model-catalog refresh, if present.

permission_default(opts \\ [])

@spec permission_default(keyword()) :: Permissions.mode()

Resolved permission default (:auto, :ask, or :read_only).

reasoning_effort(opts \\ [])

@spec reasoning_effort(keyword()) :: String.t() | nil

Resolved reasoning effort, or nil to omit and let the model default.

request_snapshot(opts \\ [])

@spec request_snapshot(keyword()) :: {:ok, map()} | {:error, map()}

Resolve one immutable model/backend snapshot from exactly one source-document read.

responses_backend(opts \\ [])

@spec responses_backend(keyword()) ::
  {:ok, :absent | Pixir.Providers.ResponsesBackend.t()} | {:error, map()}

Resolve only the explicit Responses backend descriptor from one request snapshot.

stream_idle_timeout_ms(opts \\ [])

@spec stream_idle_timeout_ms(keyword()) :: non_neg_integer()

text_verbosity(opts \\ [])

@spec text_verbosity(keyword()) :: String.t() | nil

Resolved text verbosity, or nil to omit and let the model default.

valid_reasoning_efforts()

@spec valid_reasoning_efforts() :: [String.t()]

Accepted reasoning effort ids.

web_search(opts \\ [])

@spec web_search(keyword()) :: map() | false | nil

Resolved hosted web search preference.

This is not the runtime default. Absence (nil) means no preference; the Provider/backend seam decides later. An explicit disable is false. A map is an explicit enable (and may carry search policy fields). Invalid values are ignored with a warning and stored as false so they cannot default-on.