Pixir.Config (pixir v0.1.8)

Copy Markdown View Source

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:

  1. config :pixir, :key (programmatic override)
  2. ~/.pixir/config.json
  3. 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.

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_tail_events(opts \\ [])
file_context_windows(opts \\ [])

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

file_model(opts \\ [])

Model slug from config.json only (no env/app precedence).

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.

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.

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 config, or nil when disabled/absent.

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_tail_events(opts \\ [])

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

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

Model slug from config.json only (no env/app precedence).

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.

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.

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

Resolved hosted web search config, or nil when disabled/absent.