Amplifier Foundation¶

Repository: amplifier-foundation

Foundational library for the Amplifier ecosystem: bundle composition, utilities, and reference content.

Foundation provides: - Bundle System — Load, compose, validate, and resolve bundles from local and remote sources - @Mention System — Parse and resolve @namespace:path references in instructions - Utilities — YAML/frontmatter I/O, dict merging, path handling, caching - Reference Content — Reusable providers, agents, behaviors, and context files

Quick Start¶

pip install git+https://github.com/microsoft/amplifier-foundation

import asyncio
from amplifier_foundation import load_bundle

async def main():
    # Load foundation bundle and a provider
    foundation = await load_bundle("git+https://github.com/microsoft/amplifier-foundation@main")
    provider = await load_bundle("./providers/anthropic.yaml")

    # Compose bundles (later overrides earlier)
    composed = foundation.compose(provider)

    # Prepare: resolves module sources, downloads if needed
    prepared = await composed.prepare()

    # Create session and execute
    async with await prepared.create_session() as session:
        response = await session.execute("Hello! What can you help me with?")
        print(response)

asyncio.run(main())

Core Concepts¶

Bundles¶

A bundle is the fundamental unit of composition in Amplifier. A bundle is a YAML/Markdown file that specifies:

• Which modules to mount (orchestrator, providers, tools, hooks, context manager)
• System instructions and agent behavior
• References to other bundles via includes:

---
bundle:
  name: my-assistant
  version: 1.0.0

session:
  orchestrator: {module: loop-streaming}
  context: {module: context-simple}

providers:
  - module: provider-anthropic
    source: git+https://github.com/microsoft/amplifier-module-provider-anthropic@main
    config:
      default_model: claude-sonnet-4-5

tools:
  - module: tool-filesystem
    source: git+https://github.com/microsoft/amplifier-module-tool-filesystem@main
---

You are a helpful assistant with file system access.

Composition¶

Bundles compose via the compose() method. Later bundles override earlier ones using deep-merge rules:

base = await load_bundle("./base.md")
overlay = await load_bundle("./dev-overlay.md")
composed = base.compose(overlay)

The includes: key provides declarative composition directly in YAML:

includes:
  - ./base.md
  - ./dev-overlay.md

Mount Plans¶

After composition, a bundle is converted to a mount plan — a resolved configuration that AmplifierSession consumes to load modules. prepare() resolves all source URIs and installs module packages.

prepared = await composed.prepare()
mount_plan = composed.to_mount_plan()  # Inspect before preparing

What's Included¶

Bundle System¶

@Mention System¶

Utilities¶

Session Capabilities¶

Spawn Utilities¶

Utilities for spawning sub-sessions with provider/model preferences.

Cost Bridge Utilities¶

Utilities for propagating child-session costs to parent coordinators in app-layer spawn wrappers.

Exceptions¶

Reference Content¶

The repository co-locates reusable bundle content:

Examples¶

See examples/README.md for the full catalog of 20+ examples.

Documentation¶

Philosophy¶

Foundation follows Amplifier's core principles:

• Mechanism, not policy: Provides loading/composition mechanisms. Apps decide which bundles to use.
• Ruthless simplicity: One concept (bundle), one mechanism (includes: + compose()).
• Text-first: YAML/Markdown formats are human-readable, diffable, versionable.
• Composable: Small bundles compose into larger configurations.

This library is pure mechanism. It doesn't know about specific bundles. The co-located reference content is just content — discovered and loaded like any other bundle.