axm-config 0.2.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 computes candidate state paths.

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 calculates candidate paths; it does not audit the actual configuration of every consumer. 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. 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.