Creating Amplifier Modules

Creating Amplifier Modules

Overview

Amplifier modules are Python packages that extend the runtime with tools, hooks, providers, and other capabilities. Every module has a mount() function that runs at session startup.

Core principle: mount() must register something with the coordinator. A mount() that logs and returns None WILL fail validation.

This matters immediately. Module validation runs every time a session loads. A broken mount() prevents any agent using the behavior from spawning — not just future agents, not "when Phase 2 is done" — right now, on every invocation.

The Iron Law

mount() MUST call coordinator.mount() or return a Tool instance.
A mount() that returns None and calls nothing WILL FAIL with:
"protocol_compliance: No tool was mounted and mount() did not return a Tool instance"

"Stub" means placeholder that satisfies the protocol — not empty function that does nothing.

Module Directory Structure

modules/tool-{name}/
├── pyproject.toml                        # name = "amplifier-module-tool-{name}", hatchling
└── amplifier_module_tool_{name}/
    └── __init__.py                       # async mount(coordinator, config)

The pyproject.toml entry point wires the module name to mount():

[project]
name = "amplifier-module-tool-{name}"
version = "0.1.0"
description = "Description of what this tool does"
requires-python = ">=3.11"
license = { text = "MIT" }
dependencies = []   # amplifier-core is a peer dependency — do NOT declare it here

[project.entry-points."amplifier.modules"]
tool-{name} = "amplifier_module_tool_{name}:mount"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["amplifier_module_tool_{name}"]

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"

The mount() Contract

Every mount() must:

1. Instantiate a tool class
2. Call await coordinator.mount("tools", tool, name=tool.name)
3. Return a metadata dict (not None)

Complete working example:

"""Amplifier tool module for {name}."""

import logging
from typing import Any

from amplifier_core import ToolResult

logger = logging.getLogger(__name__)


class MyTool:
    """Tool class — the actual capability being registered."""

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

    @property
    def description(self) -> str:
        # A tool description IS a description surface: it is rendered into the
        # tool block on EVERY request of every session that mounts the tool,
        # used or not. Write it to
        # foundation:context/shared/description-authoring-principles.md --
        # trigger first, then USE WHEN, then DO NOT USE WHEN naming what
        # should handle the rejected case; zero <example> blocks. One measured
        # tool description ran 15,271 chars -- 56% of that session's entire
        # tool-description budget -- and drove 7-8x over-delegation (V5).
        return "What this tool does. USE WHEN <condition>. DO NOT USE WHEN <condition> -- use <alternative>."

    @property
    def input_schema(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "param": {
                    "type": "string",
                    "description": "What this parameter does",
                },
            },
            "required": ["param"],
        }

    async def execute(self, input_data: dict[str, Any]) -> ToolResult:
        """Execute the tool operation."""
        result = do_the_work(input_data["param"])
        return ToolResult(success=True, output=result)


async def mount(coordinator: Any, config: dict[str, Any] | None = None) -> dict[str, Any]:
    """Mount the tool into the coordinator."""
    tool = MyTool()
    await coordinator.mount("tools", tool, name=tool.name)
    logger.info("tool-my-tool mounted: registered 'my_tool'")
    return {
        "name": "tool-my-tool",
        "version": "0.1.0",
        "provides": ["my_tool"],
    }

The Placeholder Pattern

When Phase 1 needs a module skeleton before full implementation, create a real tool class that returns a "not yet implemented" message. The tool still has all required properties and registers with the coordinator.

"""Amplifier tool module for {name} — Phase 1 placeholder."""

import logging
from typing import Any

from amplifier_core import ToolResult

logger = logging.getLogger(__name__)


class MyToolPlaceholder:
    """Placeholder tool — registers to satisfy protocol compliance (Phase 1).

    Phase 2 will replace this with full implementation.
    """

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

    @property
    def description(self) -> str:
        return "Description of what this tool will do. Phase 2 implementation pending."

    @property
    def input_schema(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "operation": {
                    "type": "string",
                    "description": "Operation to perform",
                },
            },
            "required": ["operation"],
        }

    async def execute(self, input_data: dict[str, Any]) -> ToolResult:
        """Return not-yet-implemented message."""
        return ToolResult(
            success=False,
            output=(
                "Tool not yet implemented. Phase 2 will add full functionality. "
                "Use the shell scripts in the bundle for now."
            ),
        )


async def mount(coordinator: Any, config: dict[str, Any] | None = None) -> dict[str, Any]:
    """Mount placeholder tool — satisfies protocol compliance during Phase 1."""
    tool = MyToolPlaceholder()
    await coordinator.mount("tools", tool, name=tool.name)
    logger.info("tool-my-tool mounted: registered placeholder 'my_tool' (Phase 2 pending)")
    return {
        "name": "tool-my-tool",
        "version": "0.1.0",
        "provides": ["my_tool"],
    }

A placeholder tool IS a real tool. It has name, description, input_schema, and execute(). It registers with coordinator.mount(). It just tells callers it's not implemented yet.

Behavior YAML Reference

How the module is referenced in a behavior YAML:

tools:
  - module: tool-{name}
    source: git+https://github.com/org/repo@main#subdirectory=modules/tool-{name}

Use this self-referential git URL form even for modules that live in the bundle's own repo — it resolves the same way no matter which file declares it. A bare relative path (source: ./modules/tool-{name}) resolves relative to whichever bundle file is active at activation time, not the file that declares it, so it only works from a root bundle.md/bundle.yaml and breaks silently when the same line is used in a behaviors/*.yaml or other included file.

Writing Tests

Test that mount() registers the tool — not that it returns None:

import pytest
from unittest.mock import AsyncMock, MagicMock
from amplifier_module_tool_my_tool import mount


@pytest.mark.asyncio
async def test_mount_registers_tool():
    """mount() must register a tool via coordinator.mount()."""
    coordinator = MagicMock()
    coordinator.mount = AsyncMock()

    result = await mount(coordinator)

    # Verify coordinator.mount was called (the Iron Law)
    coordinator.mount.assert_called_once()
    call_args = coordinator.mount.call_args
    assert call_args[0][0] == "tools"  # first positional arg is "tools"

    # Verify return value is metadata dict, not None
    assert result is not None
    assert "name" in result
    assert "provides" in result


@pytest.mark.asyncio
async def test_tool_has_required_properties():
    """Tool class must have name, description, input_schema, execute."""
    coordinator = MagicMock()
    coordinator.mount = AsyncMock()

    await mount(coordinator)

    # Get the tool that was registered
    tool = coordinator.mount.call_args[0][1]
    assert isinstance(tool.name, str) and tool.name
    assert isinstance(tool.description, str) and tool.description
    assert isinstance(tool.input_schema, dict)
    assert callable(tool.execute)

Anti-Rationalization Table

Red Flags — STOP and Use the Placeholder Pattern

If you find yourself thinking any of these, STOP:

• "mount() can just log and return None" → NO. It must register a tool.
• "I'll skip the tool class since there's nothing to implement yet" → NO. Create a placeholder class.
• "The test should assert result is None" → NO. The test should verify coordinator.mount() was called.
• "It's a stub so it should be empty" → NO. Use the placeholder pattern above.
• "Phase 2 will make it real, for now I'll just return None" → NO. Phase 2 doesn't exist yet. The module loads today.

Validation Checklist

After creating a module, verify it will pass protocol compliance:

• Does mount() call await coordinator.mount("tools", tool, name=tool.name)?
• Does the tool class have a name property (string)?
• Does the tool class have a description property (string)?
• Does that description lead with the TRIGGER, carry a DO NOT USE WHEN clause naming the alternative, and contain zero <example> blocks? (foundation:context/shared/description-authoring-principles.md -- a tool description is paid on every request whether or not the tool is called)
• Does the tool class have an input_schema property (dict)?
• Does the tool class have a callable execute() method?
• Does mount() return a metadata dict (not None)?
• Does pyproject.toml declare the amplifier.modules entry point?
• Do tests verify coordinator.mount() was called (not that result is None)?

All nine boxes must be checked before committing.

Quick Reference

Minimum viable module __init__.py:

from amplifier_core import ToolResult

class MyTool:
    name = "my_tool"
    description = "What this tool does"
    input_schema = {"type": "object", "properties": {}}

    async def execute(self, input_data):
        return ToolResult(success=False, output="Not yet implemented")

async def mount(coordinator, config=None):
    tool = MyTool()
    await coordinator.mount("tools", tool, name=tool.name)
    return {"name": "tool-my-tool", "version": "0.1.0", "provides": ["my_tool"]}

This is the minimum. Every line is required. Nothing can be removed.