Skip to content

amplifier-foundation Library

amplifier-foundation is a Python library that simplifies building applications with Amplifier by providing bundle composition, utilities, and reference content.

What is amplifier-foundation?

While amplifier-core provides the kernel (session lifecycle, module loading, coordination), amplifier-foundation provides the application-layer tooling to make working with Amplifier easier:

  • Bundle System: Load, compose, and validate configuration bundles
  • @Mention System: Parse and resolve @namespace:path references
  • Utilities: YAML I/O, dict merging, path handling, caching
  • Reference Content: Pre-configured providers, agents, behaviors, and context files

Why Use amplifier-foundation?

Without amplifier-foundation (using amplifier-core directly):

from amplifier_core import AmplifierSession

# You manually create mount plans (dicts)
mount_plan = {
    "session": {"orchestrator": "loop-basic", "context": "context-simple"},
    "providers": [{"module": "provider-anthropic", "source": "git+...", "config": {...}}],
    "tools": [{"module": "tool-bash", "source": "git+..."}]
}

session = await AmplifierSession(mount_plan)

With amplifier-foundation:

from amplifier_foundation import load_bundle

# Load and compose human-readable bundles
foundation = await load_bundle("git+https://github.com/microsoft/amplifier-foundation@main")
provider = await load_bundle("./providers/anthropic.yaml")
composed = foundation.compose(provider)

# Prepare handles module downloads automatically
prepared = await composed.prepare()
session = await prepared.create_session()

Quick Start

uv add 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

  • Bundle

    A composable configuration unit containing providers, tools, hooks, orchestrator, context manager, and system instruction.

    Bundles are markdown files with YAML frontmatter.

  • Composition

    Layer bundles to build your desired configuration: 

    foundation.compose(provider).compose(tools)

    Later bundles override earlier ones.

  • Preparation

    Downloads modules from git sources and caches them locally: 

    prepared = await bundle.prepare()

    First run: downloads. Subsequent runs: uses cache.

  • Mount Plan

    The final configuration dict consumed by AmplifierSession: 

    mount_plan = bundle.to_mount_plan()
session = AmplifierSession(mount_plan)

What's Included

Bundle System

Export Purpose
Bundle Core class for bundles
load_bundle(uri) Load from local path or git URL
BundleRegistry Track loaded bundles
validate_bundle() Validate bundle structure

@Mention System

Export Purpose
parse_mentions(text) Extract @namespace:path references
load_mentions(text, resolver) Resolve and load mentioned files
BaseMentionResolver Base class for custom resolvers

Utilities

Module Purpose
io/ YAML/frontmatter I/O, retry logic
dicts/ Deep merge, nested get/set
paths/ URI parsing, path normalization
cache/ SimpleCache, DiskCache with TTL

Reference Content

The amplifier-foundation repository also includes reference content:

Path Content
bundle.md Main foundation bundle (provider-agnostic)
providers/ Provider configurations (Anthropic, OpenAI, Azure, Ollama)
agents/ Reusable agent definitions
behaviors/ Behavioral configurations
context/ Shared context files

Architecture Position

┌─────────────────────────────────────┐
│  Your Application                   │
│  (CLI, Web UI, Script)             │
└──────────────┬──────────────────────┘
               │ uses
               ▼
┌─────────────────────────────────────┐
│  amplifier-foundation               │
│  • Bundle loading & composition     │
│  • @Mention resolution              │
│  • Utilities (I/O, paths, cache)    │
└──────────────┬──────────────────────┘
               │ produces
               ▼
┌─────────────────────────────────────┐
│  Mount Plan (Dict)                  │
└──────────────┬──────────────────────┘
               │ passed to
               ▼
┌─────────────────────────────────────┐
│  amplifier-core (Kernel)           │
│  • Session lifecycle                │
│  • Module loading                   │
│  • Coordination                     │
└─────────────────────────────────────┘

Key Insight: amplifier-foundation sits above amplifier-core, providing convenient APIs for building mount plans. You can use amplifier-core directly (with manual mount plans) or use amplifier-foundation for a higher-level API.

When to Use Each

Use amplifier-foundation when:

  • ✅ Building applications with reusable configurations
  • ✅ You want human-readable YAML + Markdown bundles
  • ✅ You need bundle composition (base + overlays)
  • ✅ You want automatic module downloading
  • ✅ You benefit from built-in utilities

Use amplifier-core directly when:

  • ✅ You have your own configuration system
  • ✅ You generate mount plans programmatically
  • ✅ You want minimal dependencies
  • ✅ You're building a framework on top of Amplifier

Documentation Structure

Repository

GitHub: microsoft/amplifier-foundation

Philosophy

amplifier-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 (compose()).
  • Text-first: YAML/Markdown formats are human-readable, diffable, versionable.
  • Composable: Small bundles compose into larger configurations.

Next Steps