Python SDK reference

Stable root imports

from axm import ... supports the following contracts:

Export	Purpose
`AXMTool`	Structural tool protocol: `name` and `execute`
`ToolResult`	Tool success, data, error, hint and text
`ToolMetadata`, `tool_metadata`	Optional discovery settings and their defaults
`tool_node`, `ToolNodeError`	Tool-to-node adapter and its contract errors
`WitnessRule`, `WitnessResult`, `ValidationFeedback`	Validation contracts
`__version__`	Installed distribution version; `"0.0.0"` if metadata is missing

Definitions remain in their submodules. Prefer root imports for these contracts. load_tool and override_tools are additionally re-exported by axm.tools. CLI helpers and axm.tools.write_scope are implementation modules, not root SDK exports.

Tool results

ToolResult is a frozen dataclass, not a Pydantic model. It requires success; data defaults to a fresh empty dict, and error, hint, text default to None. Frozen fields do not make nested data immutable.

data is for machine consumers; text is an optional prepared rendering. Neither automatically derives from the other. hint is available to consumers but the generic CLI does not print it as a separate field. Use dataclasses.asdict when you explicitly need the whole dataclass; the CLI's shared --json-output emits only data.

`ToolResult` `dataclass`

Immutable result of a tool execution.

Attributes:

Name	Type	Description
`success`	`bool`	Whether the tool execution succeeded.
`data`	`dict[str, Any]`	Structured output data (backend-specific).
`error`	`str \| None`	Human-readable error message, if any.
`hint`	`str \| None`	Optional next-step suggestion for the agent.
`text`	`str \| None`	Optional pre-rendered text representation (e.g. Markdown).

Source code in packages/axm/src/axm/tools/base.py

Python
@dataclass(frozen=True)
class ToolResult:
    """Immutable result of a tool execution.

    Attributes:
        success: Whether the tool execution succeeded.
        data: Structured output data (backend-specific).
        error: Human-readable error message, if any.
        hint: Optional next-step suggestion for the agent.
        text: Optional pre-rendered text representation (e.g. Markdown).
    """

    success: bool
    data: dict[str, Any] = field(default_factory=dict)
    error: str | None = None
    hint: str | None = None
    text: str | None = None

`AXMTool`

Bases: Protocol

Structural protocol for AXM deterministic tools.

Implementors must provide: - name (property): unique tool identifier - execute(...) : deterministic execution with explicit params

Optionally provide: - agent_hint (class attribute): optional, free-form one-liner optimized for LLM consumption: what the tool does, key params, and what it replaces. Like the other discovery attributes below, it is not a protocol member and carries no guaranteed fallback — some discovery tooling reads it best-effort via getattr / :func:tool_metadata; absent, nothing is substituted. - expose_directly (class attribute, default False): when True, the MCP server registers this tool directly in tools/list (the hot path). When False (default), the tool is reachable only through the MCP facade (axm_search -> axm_describe -> axm_call), keeping the tools/list payload small. - domain (class attribute, default None): coarse capability group used by the facade for axm_capabilities and to scope axm_search (e.g. "ast", "git", "ticket"). - tags (class attribute, default frozenset()): free-form keywords feeding facade discovery (axm_search).

Uses structural typing (PEP 544) — no inheritance required. @runtime_checkable enables isinstance() checks. The discovery attributes (expose_directly / domain / tags) are not protocol members on purpose: adding data attributes to a runtime_checkable protocol would make them required for isinstance() and break the check for the many tools that satisfy AXMTool structurally without subclassing it. Read them through :func:tool_metadata (or getattr(tool, name, default)) instead, which works for subclasses and structural tools alike.

Example::

Text Only

class MyTool(AXMTool):
    agent_hint = "Frobnicate widgets — use width param."
    expose_directly = True          # hot path (read via tool_metadata)
    domain = "widget"
    tags = frozenset({"frobnicate"})

    @property
    def name(self) -> str:
        return "my-tool"

    def execute(self, *, value: int = 0) -> ToolResult:
        return ToolResult(success=True, data={"result": value})

Source code in packages/axm/src/axm/tools/base.py

Python
@runtime_checkable
class AXMTool(Protocol):
    """Structural protocol for AXM deterministic tools.

    Implementors must provide:
    - ``name`` (property): unique tool identifier
    - ``execute(...)`` : deterministic execution with explicit params

    Optionally provide:
    - ``agent_hint`` (class attribute): optional, free-form one-liner
      optimized for LLM consumption: what the tool does, key params, and
      what it replaces.  Like the other discovery attributes below, it is
      *not* a protocol member and carries no guaranteed fallback — some
      discovery tooling reads it best-effort via ``getattr`` /
      :func:`tool_metadata`; absent, nothing is substituted.
    - ``expose_directly`` (class attribute, default ``False``): when
      ``True``, the MCP server registers this tool directly in
      ``tools/list`` (the *hot path*).  When ``False`` (default), the
      tool is reachable only through the MCP facade
      (``axm_search`` -> ``axm_describe`` -> ``axm_call``), keeping the
      ``tools/list`` payload small.
    - ``domain`` (class attribute, default ``None``): coarse capability
      group used by the facade for ``axm_capabilities`` and to scope
      ``axm_search`` (e.g. ``"ast"``, ``"git"``, ``"ticket"``).
    - ``tags`` (class attribute, default ``frozenset()``): free-form
      keywords feeding facade discovery (``axm_search``).

    Uses structural typing (PEP 544) — no inheritance required.
    ``@runtime_checkable`` enables ``isinstance()`` checks.  The discovery
    attributes (``expose_directly`` / ``domain`` / ``tags``) are *not*
    protocol members on purpose: adding data attributes to a
    ``runtime_checkable`` protocol would make them required for
    ``isinstance()`` and break the check for the many tools that satisfy
    ``AXMTool`` structurally without subclassing it.  Read them through
    :func:`tool_metadata` (or ``getattr(tool, name, default)``) instead,
    which works for subclasses and structural tools alike.

    Example::

        class MyTool(AXMTool):
            agent_hint = "Frobnicate widgets — use width param."
            expose_directly = True          # hot path (read via tool_metadata)
            domain = "widget"
            tags = frozenset({"frobnicate"})

            @property
            def name(self) -> str:
                return "my-tool"

            def execute(self, *, value: int = 0) -> ToolResult:
                return ToolResult(success=True, data={"result": value})
    """

    @property
    def name(self) -> str:
        """Unique tool identifier (e.g., 'esbmc', 'dafny', 'pytest')."""
        ...

    def execute(self, **kwargs: Any) -> ToolResult:
        """Execute the tool with given arguments.

        Subclasses should override with explicit, typed parameters::

            def execute(self, *, title: str = "", body: str = "") -> ToolResult:
                ...

        The ``**kwargs`` signature here is the *structural minimum* —
        any callable accepting keyword arguments satisfies it.

        Returns:
            ToolResult with success status and structured data.
        """
        ...

`name` `property`

Unique tool identifier (e.g., 'esbmc', 'dafny', 'pytest').

`execute(**kwargs)`

Execute the tool with given arguments.

Subclasses should override with explicit, typed parameters::

Text Only

def execute(self, *, title: str = "", body: str = "") -> ToolResult:
    ...

The **kwargs signature here is the structural minimum — any callable accepting keyword arguments satisfies it.

Returns:

Type	Description
`ToolResult`	ToolResult with success status and structured data.

Source code in packages/axm/src/axm/tools/base.py

Python
def execute(self, **kwargs: Any) -> ToolResult:
    """Execute the tool with given arguments.

    Subclasses should override with explicit, typed parameters::

        def execute(self, *, title: str = "", body: str = "") -> ToolResult:
            ...

    The ``**kwargs`` signature here is the *structural minimum* —
    any callable accepting keyword arguments satisfies it.

    Returns:
        ToolResult with success status and structured data.
    """
    ...

Discovery metadata

tool_metadata(tool) returns ToolMetadata with defaults expose_directly=False, domain=None, tags=frozenset(). It uses attributes rather than requiring inheritance. Tags are coerced to a frozenset; expose_directly is converted with bool.

agent_hint is a separate optional attribute, absent from ToolMetadata. The helper does not invent an agent hint or guarantee a docstring fallback.

`ToolMetadata` `dataclass`

Facade/CLI discovery metadata for a tool, with safe defaults.

Built by :func:tool_metadata from the optional expose_directly / domain / tags attributes a tool may declare. Centralising the defaults here keeps the MCP facade and the CLI reading the same contract.

Attributes:

Name	Type	Description
`expose_directly`	`bool`	Whether the tool is on the MCP hot path (registered directly in `tools/list`). Default `False`.
`domain`	`str \| None`	Coarse capability group, or `None` if ungrouped.
`tags`	`frozenset[str]`	Discovery keywords (possibly empty).

Source code in packages/axm/src/axm/tools/base.py

Python
@dataclass(frozen=True)
class ToolMetadata:
    """Facade/CLI discovery metadata for a tool, with safe defaults.

    Built by :func:`tool_metadata` from the optional ``expose_directly`` /
    ``domain`` / ``tags`` attributes a tool may declare.  Centralising the
    defaults here keeps the MCP facade and the CLI reading the same contract.

    Attributes:
        expose_directly: Whether the tool is on the MCP hot path
            (registered directly in ``tools/list``).  Default ``False``.
        domain: Coarse capability group, or ``None`` if ungrouped.
        tags: Discovery keywords (possibly empty).
    """

    expose_directly: bool = False
    domain: str | None = None
    tags: frozenset[str] = frozenset()

`tool_metadata(tool)`

Read a tool's optional discovery attributes into a :class:ToolMetadata.

Works for tools that subclass :class:AXMTool, tools that satisfy it structurally, and plain callables — anything missing an attribute falls back to the default. tags is coerced to a frozenset so callers can rely on set semantics regardless of how the tool declared it.

Parameters:

Name	Type	Description	Default
`tool`	`object`	The tool instance (or plain callable) to introspect.	required

Returns:

Name	Type	Description
`A`	`ToolMetadata`	class:`ToolMetadata` with resolved values.

Source code in packages/axm/src/axm/tools/base.py

Python
def tool_metadata(tool: object) -> ToolMetadata:
    """Read a tool's optional discovery attributes into a :class:`ToolMetadata`.

    Works for tools that subclass :class:`AXMTool`, tools that satisfy it
    structurally, and plain callables — anything missing an attribute falls
    back to the default.  ``tags`` is coerced to a ``frozenset`` so callers
    can rely on set semantics regardless of how the tool declared it.

    Args:
        tool: The tool instance (or plain callable) to introspect.

    Returns:
        A :class:`ToolMetadata` with resolved values.
    """
    raw_tags = getattr(tool, "tags", None) or ()
    return ToolMetadata(
        expose_directly=bool(getattr(tool, "expose_directly", False)),
        domain=getattr(tool, "domain", None),
        tags=frozenset(raw_tags),
    )

Tool nodes

Read the composition guide before choosing mappings and failure handling. ToolNodeError is a RuntimeError subclass.

`tool_node(name, *, args=None, returns=None, allow_failure_data=False)`

Build a DAG python-node fn(payload) -> dict around an axm.tools tool.

Parameters:

Name	Type	Description	Default
`name`	`str`	The tool's `axm.tools` entry-point name (e.g. `"ast_impact"`).	required
`args`	`Mapping[str, str] \| None`	Optional `{param_name: mem_key}` rename map for params whose mem key differs from the `execute` parameter name. Params absent from args are read from `payload` by their own name when present.	`None`
`returns`	`Mapping[str, str] \| None`	`{write_key: source}` where source is `"text"` (the `ToolResult.text`) or a key inside `ToolResult.data`. Defaults to `{name: "text"}` is not assumed — supply it so the node's writes are explicit (decision: writes nommés par clé). Precedence / collision: the literal `"text"` is a sentinel that always routes to `ToolResult.text`, checked before any lookup in `ToolResult.data`. A tool whose `data` carries its own `"text"` key therefore cannot surface that field through this shortcut — `source="text"` yields `ToolResult.text`, never `data["text"]` (which is unreachable via returns). Route such a field under a different write source, or rename the data key upstream.	`None`
`allow_failure_data`	`bool`	Opt-in for observation tools whose `success=False` is itself measured domain data (for example `audit_test` returning exact failed cases). When true, shape `ToolResult.data` through returns instead of raising solely on the success flag. Missing declared data still raises, so an empty/tool failure cannot become evidence. Defaults to the existing fail-fast behaviour.	`False`

Returns:

Type	Description
`Callable[[Mapping[str, object]], dict[str, object]]`	A callable mapping the node's `payload` to a dict keyed by returns.

Raises:

Type	Description
`ToolNodeError`	At call time, if the tool is unknown, returns `success=False` without the explicit observation opt-in, or omits one of the declared return fields.

Source code in packages/axm/src/axm/tools/node.py

Python
def tool_node(
    name: str,
    *,
    args: Mapping[str, str] | None = None,
    returns: Mapping[str, str] | None = None,
    allow_failure_data: bool = False,
) -> Callable[[Mapping[str, object]], dict[str, object]]:
    """Build a DAG python-node ``fn(payload) -> dict`` around an ``axm.tools`` tool.

    Args:
        name: The tool's ``axm.tools`` entry-point name (e.g. ``"ast_impact"``).
        args: Optional ``{param_name: mem_key}`` rename map for params whose mem
            key differs from the ``execute`` parameter name. Params absent from
            *args* are read from ``payload`` by their own name when present.
        returns: ``{write_key: source}`` where *source* is ``"text"`` (the
            ``ToolResult.text``) or a key inside ``ToolResult.data``. Defaults to
            ``{name: "text"}`` is **not** assumed — supply it so the node's writes
            are explicit (decision: writes nommés par clé).

            Precedence / collision: the literal ``"text"`` is a sentinel that
            **always** routes to ``ToolResult.text``, checked *before* any lookup
            in ``ToolResult.data``. A tool whose ``data`` carries its own
            ``"text"`` key therefore cannot surface that field through this
            shortcut — ``source="text"`` yields ``ToolResult.text``, never
            ``data["text"]`` (which is unreachable via *returns*). Route such a
            field under a different write source, or rename the data key upstream.
        allow_failure_data: Opt-in for observation tools whose ``success=False``
            is itself measured domain data (for example ``audit_test`` returning
            exact failed cases).  When true, shape ``ToolResult.data`` through
            *returns* instead of raising solely on the success flag. Missing
            declared data still raises, so an empty/tool failure cannot become
            evidence. Defaults to the existing fail-fast behaviour.

    Returns:
        A callable mapping the node's ``payload`` to a dict keyed by *returns*.

    Raises:
        ToolNodeError: At call time, if the tool is unknown, returns
            ``success=False`` without the explicit observation opt-in, or omits
            one of the declared return fields.
    """
    rename = dict(args or {})
    out_spec = dict(returns or {})
    cache: dict[str, AXMTool] = {}

    def _run(payload: Mapping[str, object]) -> dict[str, object]:
        overrides = _OVERRIDES.get()
        if overrides and name in overrides:
            # A substitute shadows even a memoized real tool and never enters
            # the cache: it lives exactly as long as its block.
            tool: AXMTool = overrides[name]
        else:
            cached = cache.get(name)
            if cached is None:
                # Resolve entry points + instantiate once, lazily on first call
                # (late-binding): building the node scans nothing.
                cached = _load_tool(name)
                cache[name] = cached
            tool = cached
        kwargs = _kwargs_from_payload(payload, rename)
        try:
            result = tool.execute(**kwargs)
        except TypeError as exc:
            # A payload key with no matching ``execute`` parameter (strict
            # signature, no ``**kwargs``) must surface as the documented
            # ToolNodeError, not a raw TypeError.
            msg = f"tool {name!r}: bad payload for execute(): {exc}"
            raise ToolNodeError(msg) from exc
        if not result.success and not allow_failure_data:
            msg = f"tool {name!r} failed: {result.error or '<no error message>'}"
            raise ToolNodeError(msg)
        try:
            return _shape_output(name, result.data, result.text, out_spec)
        except ToolNodeError as exc:
            if not result.success and result.error:
                msg = f"tool {name!r} failed: {result.error}; {exc}"
                raise ToolNodeError(msg) from exc
            raise

    return _run

`ToolNodeError`

Bases: RuntimeError

A tool invoked as a DAG node failed (ToolResult.success was False).

Source code in packages/axm/src/axm/tools/node.py

Python
class ToolNodeError(RuntimeError):
    """A tool invoked as a DAG node failed (``ToolResult.success`` was ``False``)."""

`load_tool(name)`

Resolve and instantiate the axm.tools entry point named name.

Source code in packages/axm/src/axm/tools/node.py

Python
def load_tool(name: str) -> AXMTool:
    """Resolve and instantiate the ``axm.tools`` entry point named *name*."""
    # An active ``override_tools`` substitute wins over discovery, for direct
    # callers as well as for ``tool_node`` (which consults it before its cache).
    overrides = _OVERRIDES.get()
    if overrides and name in overrides:
        return overrides[name]
    eps = entry_points_for(TOOLS_ENTRY_POINT_GROUP)
    ep = eps.get(name)
    if ep is not None:
        obj = ep.load()
        tool: AXMTool = obj() if isinstance(obj, type) else obj
        return tool
    known = ", ".join(sorted(eps))
    msg = f"No tool registered under {name!r}. Registered: {known or '<none>'}"
    raise ToolNodeError(msg)

`override_tools(tools)`

Substitute tools ({entry_point_name: tool}) for the duration of a block.

Inside the block, a :func:tool_node built for one of the named tools calls the substitute instead of resolving the axm.tools entry point — whether the node was built before or after entering the block, and whether or not the real tool had already been resolved and memoized. Blocks nest: an inner block adds to (or shadows, per name) the enclosing one, and leaving it restores exactly what was active before.

The substitution applies to every resolution by name — :func:tool_node nodes and direct :func:_load_tool callers alike — so a graph node that resolves a tool itself (_load_tool("echo_check") in a python node) is covered too, not only tool_node wrappers.

The scope is a :mod:contextvars context, not a global: it propagates to asyncio tasks and :func:asyncio.to_thread calls started inside the block (how axm_dag executes python nodes) and is invisible to concurrent work started outside it. Substitutes are never memoized, so the real tool resolves again as soon as the block exits.

Parameters:

Name	Type	Description	Default
`tools`	`Mapping[str, AXMTool]`	Entry-point name → substitute implementing `execute(**kwargs) -> ToolResult`.	required

Source code in packages/axm/src/axm/tools/node.py

Python
@contextmanager
def override_tools(tools: Mapping[str, AXMTool]) -> Iterator[None]:
    """Substitute *tools* (``{entry_point_name: tool}``) for the duration of a block.

    Inside the block, a :func:`tool_node` built for one of the named tools calls
    the substitute instead of resolving the ``axm.tools`` entry point — whether
    the node was built before or after entering the block, and whether or not
    the real tool had already been resolved and memoized. Blocks nest: an inner
    block adds to (or shadows, per name) the enclosing one, and leaving it
    restores exactly what was active before.

    The substitution applies to every resolution *by name* — :func:`tool_node`
    nodes and direct :func:`_load_tool` callers alike — so a graph node that
    resolves a tool itself (``_load_tool("echo_check")`` in a python node) is
    covered too, not only ``tool_node`` wrappers.

    The scope is a :mod:`contextvars` context, not a global: it propagates to
    ``asyncio`` tasks and :func:`asyncio.to_thread` calls started inside the
    block (how ``axm_dag`` executes python nodes) and is invisible to concurrent
    work started outside it. Substitutes are never memoized, so the real tool
    resolves again as soon as the block exits.

    Args:
        tools: Entry-point name → substitute implementing ``execute(**kwargs)
            -> ToolResult``.
    """
    active = _OVERRIDES.get() or {}
    token = _OVERRIDES.set({**active, **tools})
    try:
        yield
    finally:
        _OVERRIDES.reset(token)

Other contracts

Witnesses covers the remaining root protocols and result types. CLI reference documents launcher helpers.

The workspace build also generates module reference pages from docs/gen_ref_pages.py. This curated reference renders directly from the same source, so it works in both package-only and monorepo builds.

Python SDK reference

Stable root imports

Tool results

ToolResult dataclass

AXMTool

name property

execute(**kwargs)

Discovery metadata

ToolMetadata dataclass

tool_metadata(tool)

Tool nodes

tool_node(name, *, args=None, returns=None, allow_failure_data=False)

ToolNodeError

load_tool(name)

override_tools(tools)

Other contracts

`ToolResult` `dataclass`

`AXMTool`

`name` `property`

`execute(**kwargs)`

`ToolMetadata` `dataclass`

`tool_metadata(tool)`

`tool_node(name, *, args=None, returns=None, allow_failure_data=False)`

`ToolNodeError`

`load_tool(name)`

`override_tools(tools)`