Module resolution (verified)

“Module resolution” is how an app turns a module id like tool-bash into an actual Python module directory (from git, a local path, a collection, or an installed package).

Reference implementation: StandardModuleSourceResolver

The reference resolver is implemented in amplifier-module-resolution as StandardModuleSourceResolver.

Source: microsoft/amplifier-module-resolution/src/amplifier_module_resolution/resolvers.py

Resolution order (what the code actually does)

The resolver implements a 6-layer “first match wins” strategy:

Environment variable: AMPLIFIER_MODULE_<ID>
Workspace convention directory
Settings provider (merged project + user settings)
Collection-provided modules
Profile hint (source declared by the profile)
Installed package fallback

Readme vs reality

Some docs summarize this as “5 layers” (env → workspace → settings → profile → package). The code adds an explicit collection modules layer in between settings and profile hint. When in doubt, trust resolve_with_layer().

Concrete example: force a module to a local checkout

# force tool-bash to load from a local path (highest precedence)
export AMPLIFIER_MODULE_TOOL_BASH=./amplifier-module-tool-bash

How the CLI uses it

The CLI creates the resolver and injects two providers:

A settings provider that merges explicit overrides with sources registered in settings (modules.providers, modules.tools, modules.hooks, etc.).
A collection-module provider that discovers module directories inside installed collections and registers them as candidates in the resolver’s layer 4.

Source: microsoft/amplifier-app-cli/amplifier_app_cli/paths.py (create_module_resolver)

Flow diagram

flowchart TB id["module id (e.g. tool-bash)"] --> r["StandardModuleSourceResolver.resolve_with_layer()"] r --> env["Layer 1: env var"] r --> ws["Layer 2: workspace dir"] r --> settings["Layer 3: settings"] r --> col["Layer 4: collections"] r --> prof["Layer 5: profile hint"] r --> pkg["Layer 6: installed package"]