axm 0.9.0

AXM — Shared SDK and unified command launcher

AXM provides the shared Python contracts for AXM tools and the axm command launcher. Install provider packages to add commands; the SDK itself does not ship domain tools or run an MCP server.

Features

• Shared SDK — AXMTool, ToolResult, discovery metadata, witness contracts, and the tool_node adapter.
• Lazy CLI discovery — list installed entry points without importing every provider; load the requested command when dispatched.
• One tool declaration — axm.tools connects a provider to the generic CLI, MCP discovery and tool-node resolution.
• Small runtime — only Cyclopts is required; ecosystem providers are optional.

Installation

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

uv add axm                  # SDK and launcher; no domain tools
uv add 'axm[init]'           # scaffolding and project checks
uv add 'axm[audit]'          # code quality
uv add 'axm[bib]'            # bibliography provider
uv add 'axm[mcp]'            # MCP server package
uv add 'axm[all]'            # the four optional providers above

With an activated virtual environment, pip install 'axm[init]' is an alternative. Quote extras in shells such as zsh. all does not install every package in the AXM ecosystem.

Quick Start

After uv add axm, create a structured result without installing a provider:

uv run python - <<'PY'
from axm import ToolResult

result = ToolResult(success=True, data={"count": 3}, text="3 items")
print(result.text)
print(result.data["count"])
PY

This prints 3 items followed by 3. Tools return the same contract to expose structured data alongside readable output.

Usage

Unified CLI

With the init extra installed, run from the project environment:

uv run axm --help
uv run axm --version
uv run axm init_check --help
uv run axm init_check --path . --json-output

The catalog depends on installed providers. Use a command's help for its actual options. Generated commands normally print ToolResult.text or fall back to data; the shared --json-output emits the data mapping. Failures remain nonzero. A provider with its own json_output parameter owns that flag's behavior. See the CLI reference.

Shared Python contracts

from axm import AXMTool, ToolResult, tool_node

result = ToolResult(success=True, data={"count": 3}, text="3 items")
assert result.data["count"] == 3

The root also exports ToolMetadata, tool_metadata, ToolNodeError, WitnessRule, WitnessResult, ValidationFeedback and __version__. See the SDK reference and witnesses for their contracts.

How It Works

A provider registers an implementation in its pyproject.toml:

[project.entry-points."axm.tools"]
demo_count = "demo_tools.count:CountTool"

This is an illustrative provider, implemented in the write-a-tool guide. The CLI derives arguments from its execute signature. Only axm.tools extends the unified launcher.

Documentation

• Getting started
• Write a tool
• Compose a tool node
• Architecture
• Published documentation

The MkDocs home page is docs/index.md; it is separate from this README. The package has a standalone MkDocs configuration and also participates in the workspace site.

Development

This package belongs to the axm-forge workspace.

git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-packages --all-groups
uv run --package axm --directory packages/axm pytest

From packages/axm, build the package documentation with mkdocs build --strict in an environment containing the package's docs dependencies.

Package Structure

src/axm/
  __init__.py          # root SDK exports and version
  cli.py               # command discovery and rendering
  tools/base.py        # tool protocol, result and metadata
  tools/node.py        # tool-node adapter and scoped substitutes
  tools/write_scope.py # internal write-scope decisions
  witnesses.py         # validation contracts
tests_axm/             # package tests
docs/                  # tutorials, guides, reference and explanations

License

Licensed under Apache-2.0. See LICENSE.