Profile loading (verified)

This chapter explains how profiles are discovered and loaded in Amplifier, based on the actual implementation in amplifier-profiles and how the CLI wires it up.

The pieces

amplifier-profiles (library): implements ProfileLoader and compile_profile_to_mount_plan.
amplifier-collections (library): helps resolve collection names to paths.
amplifier-app-cli (application): decides where to search (policy) and injects resolvers and mention handling.

Discovery and name formats

ProfileLoader supports both “simple” profile names and “collection:” forms. In particular, it supports:

base (simple name)
foundation:base (collection + simple name)
foundation:profiles/base.md (collection + full path)

Source: microsoft/amplifier-profiles/src/amplifier_profiles/loader.py

Inheritance

Profiles can extend other profiles (via profile.extends). The loader resolves inheritance by loading the parent first and deep-merging parent and child before validating the resulting schema.

Source: ProfileLoader.load_profile()

Mount plan compilation

A loaded profile is compiled into a “mount plan” dictionary (the thing a session can consume) by compile_profile_to_mount_plan. The code-level merge strategy is explicit:

Start with base profile
Apply overlays in precedence order
Merge module lists by module id (later wins)
Session fields are overridden (not deep-merged)
Agents are only loaded if the application injects an agent loader

Source: microsoft/amplifier-profiles/src/amplifier_profiles/compiler.py

Mentions: what the loader does not do

The profile loader intentionally does not fully process @mentions in the instruction text; that’s handled in the application layer. This is a deliberate boundary: profiles library loads config and leaves policy/IO to apps.

Concrete example (Python)

A minimal “profile service” that loads a profile and compiles it to a mount plan:

from pathlib import Path
from amplifier_profiles import ProfileLoader, compile_profile_to_mount_plan

loader = ProfileLoader(search_paths=[Path("profiles")])
profile = loader.load_profile("dev")

mount_plan = compile_profile_to_mount_plan(profile)

Source (example usage): microsoft/amplifier-profiles/README.md

How the CLI wires it up

The CLI chooses search paths and injects the collection resolver and mention loader when constructing the profile loader:

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

Flow diagram

flowchart TB sel["Select profile name"] --> load["ProfileLoader.find/load (inheritance)"] load --> compile["compile_profile_to_mount_plan()"] compile --> plan["Mount plan"] plan --> resolve["Module resolution (sources → paths)"] resolve --> session["Session runs orchestrator loop"]