aix.config

Central configuration for AIX (single source of truth for defaults).

This module is the SSOT for *what model (and related parameters) each AIX function uses by default*. Instead of scattering hardcoded DFLT_* constants across modules, every function resolves its defaults from a single, layered configuration.

Resolution layers, highest precedence first:

1. Explicit call argument – e.g. chat(..., model=...) always wins (handled at the call site, not here).

2. Runtime override – configure() swaps the active config; using() scopes an override to a with block.

3. Environment variables – AIX_CHAT_MODEL, AIX_CHAT_TEMPERATURE, AIX_EMBEDDING_MODEL, AIX_IMAGE_MODEL, AIX_TTS_MODEL, AIX_TTS_VOICE, AIX_TRANSCRIPTION_MODEL, …

4. User config file – a TOML file at <app config dir>/config.toml (override the path with the AIX_CONFIG_FILE environment variable).

5. Shipped defaults – the dataclass field defaults below.

The schema is a set of frozen dataclasses (immutable). A module-level *active config* pointer holds the currently resolved AixConfig; configure() and using() swap that pointer rather than mutating in place.

Examples

>>> from aix import config
>>> c = config.get_config()
>>> isinstance(c.chat.model, str)
True

Scoped override (does not leak outside the block):

>>> with config.using(chat_model="some/model"):
...     config.get_config().chat.model
'some/model'
>>> config.get_config().chat.model == c.chat.model
True

TOML config file shape:

[chat]
model = "openai/gpt-4o-mini"
temperature = 1.0

[embeddings]
model = "text-embedding-3-small"

[image]
model = "dall-e-3"
size = "1024x1024"

[audio]
tts_model = "tts-1"
tts_voice = "alloy"
transcription_model = "whisper-1"

[vision]
model = "gpt-4o-mini"

[aliases]
fast = "openai/gpt-4o-mini"
best = "anthropic/claude-sonnet-4"

Functions

load_config([path, environ])	Resolve an AixConfig from shipped defaults, TOML file, and env.
get_config()	Return the current active AixConfig.
set_config(config)	Replace the active config wholesale.
configure(**overrides)	Apply runtime overrides to the active config and return it.
using(**overrides)	Context manager applying scoped overrides, restored on exit.
config_file_path()	Path to the user config file (env AIX_CONFIG_FILE overrides default).
resolve_model(model, *[, config])	Resolve a semantic alias ("fast", "best", ...) to a concrete model id.

Classes

ChatConfig([model, temperature, max_tokens])	Defaults for chat / ask / prompt_func.
EmbeddingConfig([model, batch_size])	Defaults for embeddings / embed.
ImageConfig([model, size, quality, num_images])	Defaults for generate_image / generate_images.
AudioConfig([tts_model, tts_voice, ...])	Defaults for text_to_speech / transcribe / translate_audio.
VideoConfig([provider])	Defaults for generate_video (provider-dependent).
VisionConfig([model])	Defaults for describe_image (image→text).
AixConfig([chat, embeddings, image, audio, ...])	Top-level AIX configuration (single source of truth for defaults).

class aix.config.AixConfig(chat=<factory>, embeddings=<factory>, image=<factory>, audio=<factory>, video=<factory>, vision=<factory>, aliases=<factory>)

Bases: object

Top-level AIX configuration (single source of truth for defaults).

class aix.config.AudioConfig(tts_model='gpt-4o-mini-tts', tts_voice='alloy', tts_speed=1.0, transcription_model='whisper-1')

Bases: object

Defaults for text_to_speech / transcribe / translate_audio.

class aix.config.ChatConfig(model='gpt-4.1-mini', temperature=1.0, max_tokens=None)

Bases: object

Defaults for chat / ask / prompt_func.

class aix.config.EmbeddingConfig(model='text-embedding-3-small', batch_size=512)

Bases: object

Defaults for embeddings / embed.

class aix.config.ImageConfig(model='dall-e-3', size='1024x1024', quality='standard', num_images=1)

Bases: object

Defaults for generate_image / generate_images.

class aix.config.VideoConfig(provider=None)

Bases: object

Defaults for generate_video (provider-dependent).

class aix.config.VisionConfig(model='gpt-4o-mini')

Bases: object

Defaults for describe_image (image→text).

The default is a cheap, vision-capable OpenAI model so it works with the same OPENAI_API_KEY most users already have; override per call (describe_image(..., model=...)), via configure(vision_model=...), or the [vision] TOML section to route to Claude / Gemini / etc.

aix.config.config_file_path()

Path to the user config file (env AIX_CONFIG_FILE overrides default).

Return type:

str

aix.config.configure(**overrides)

Apply runtime overrides to the active config and return it.

Return type:

AixConfig

Examples

>>> from aix import config
>>> _ = config.configure(chat_model="openai/gpt-4o-mini")
>>> config.get_config().chat.model
'openai/gpt-4o-mini'
>>> _ = config.configure(chat={"temperature": 0.2})
>>> config.get_config().chat.temperature
0.2

aix.config.get_config()

Return the current active AixConfig.

Return type:

AixConfig

aix.config.load_config(path=None, *, environ=None)

Resolve an AixConfig from shipped defaults, TOML file, and env.

Precedence (low to high): shipped defaults < TOML file < environment variables. Runtime overrides (configure()/using()) and explicit call arguments sit above this and are applied elsewhere.

Parameters:

• path (Optional[str]) – Optional explicit TOML path. Defaults to config_file_path().

• environ (Optional[Mapping[str, str]]) – Optional environment mapping (defaults to os.environ).

Return type:

AixConfig

Returns:

A fully resolved AixConfig.

aix.config.resolve_model(model, *, config=None)

Resolve a semantic alias ("fast", "best", …) to a concrete model id.

Plain substitution: if model is a key in the active aliases table it is replaced (following chains, with cycle protection). Anything that is not an alias – including every literal model id like "gpt-4o" – is returned unchanged. None passes through (callers apply their own default first).

Note

aliases share a namespace with literal model ids, so an unknown name is treated as a literal id, not an error. Inspect available aliases via aix.get_config().aliases.

Examples

>>> from aix import config
>>> config.resolve_model("fast") in config.DEFAULT_ALIASES.values()
True
>>> config.resolve_model("gpt-4o")  # not an alias -> unchanged
'gpt-4o'
>>> config.resolve_model(None) is None
True

Return type:

Optional[str]

aix.config.set_config(config)

Replace the active config wholesale. Returns the new active config.

Return type:

AixConfig

aix.config.using(**overrides)

Context manager applying scoped overrides, restored on exit.

Return type:

Iterator[AixConfig]

Examples

>>> from aix import config
>>> with config.using(chat_temperature=0.0) as c:
...     c.chat.temperature
0.0