axm-config 0.3.0

axm-config — Non-sensitive runtime configuration for AXM

axm-config provides non-sensitive runtime configuration for AXM: environment overrides, TOML persistence, typed settings and named profiles. Resolution follows environment > file > default.

Features

• get, get_file, set_, delete and load provide resolution and model binding.
• Typed accessors share runtime paths, warden settings and inference defaults.
• Execution-policy helpers persist complete backend/model pairs and analysis overrides.
• config_doctor reports provenance; profile_isolation reports the resolved state paths.
• A pytest11 plugin sandboxes the AXM state paths of every pytest session under a temporary root; see Isolate test sessions.

Installation

Requires Python 3.12 or newer. In a Python project managed by uv:

uv add axm-config
uv run axm-config --help

Quick Start

Choose an unused profile name for this example:

AXM_PROFILE=docs-demo uv run axm-config set research.demo timeout 30
AXM_PROFILE=docs-demo uv run axm-config get research.demo timeout
AXM_PROFILE=docs-demo AXM_RESEARCH__DEMO_TIMEOUT=10 uv run axm-config get research.demo timeout
AXM_PROFILE=docs-demo uv run axm-config delete research.demo timeout

The two reads print 30, then 10: the environment overrides the stored value. The final command deletes the example key. These commands write to ~/.axm/profiles/docs-demo/config.toml; the profile file can remain afterward. The CLI stores strings; use the Python API for TOML integers and booleans.

Usage

CLI and tools

The axm-config command exposes get, set, delete, path and doctor. Installed AXMTool entry points also expose diagnostics through the generic CLI:

uv run axm config_doctor --namespace research.demo
uv run axm profile_isolation --profile scratch

config_doctor reports where settings come from without returning their values. profile_isolation reports the state paths the resolver would use for a profile, honouring configured overrides and creating nothing. See the CLI and tool contracts.

Python configuration

Import the public helpers from axm_config. Use get for raw resolution, get_file to omit environment overrides, and load(namespace, model) to bind settings to a Pydantic model. Use get_file_namespace(namespace) when validating the complete persisted tree, including unknown keys and nested tables, rather than selecting only declared fields. See typed consumer configuration and the Python contracts.

Profiles and persistence limits

An unset or empty AXM_PROFILE selects production at ~/.axm/config.toml. Each file replacement is atomic; concurrent read-modify-write operations are not serialized. See the persistence limits before automating writes.

Passwords, tokens and API keys belong in axm-vault, not this plaintext store. AXM_HOME is not a general store override; see the profile guide.

Documentation

The documentation home is the MkDocs landing page; this README is the repository/package introduction.

• Published documentation
• Tutorial
• Typed consumer configuration
• Profiles and isolation limits
• Execution policies
• CLI and tools
• Python contracts
• Persistence and architecture

Development

Part of the axm-forge workspace. From the workspace root:

uv sync --all-packages --all-groups
uv run --package axm-config --directory packages/axm-config pytest

The package test directory is packages/axm-config/tests_axm_config.

Build this package's documentation from its directory with mkdocs build --strict, using an environment containing its local installation, MkDocs Material and mkdocstrings with the Python handler. The package configuration also works when included by the workspace site.

License

Licensed under Apache-2.0. See LICENSE.