Amplifier Core

The ultra-thin kernel of the Amplifier modular AI agent system -- now implemented in Rust with Python bindings via PyO3.

Purpose

Amplifier Core provides the mechanisms for building modular AI agent systems. Following the Linux kernel model, it's a tiny, stable center that rarely changes, with all policies and features implemented as replaceable modules at the edges.

The kernel is implemented in Rust for performance and type safety. Python bindings via PyO3 provide the same API that existing consumers already use -- existing Python code requires zero changes. Same imports, same API, same behavior.

Core responsibilities:

• Module discovery and loading
• Lifecycle coordination
• Hook system and events
• Session management
• Stable contracts and APIs

Architecture

+---------------------------------------------------------------+
| RUST KERNEL (crates/amplifier-core/)                          |
| * Session lifecycle       * Event system                      |
| * Coordinator             * Hook registry                     |
| * Type-safe contracts     * Cancellation tokens               |
+----------------------------+----------------------------------+
                             | PyO3 bridge (bindings/python/)
                             v
+---------------------------------------------------------------+
| PYTHON BINDINGS (python/amplifier_core/)                      |
| * Same public API          * Pydantic models                  |
| * Module loader (Python)   * Backward-compatible imports      |
+----------------------------+----------------------------------+
                             | protocols (Tool, Provider, etc.)
                             v
+---------------------------------------------------------------+
| MODULES (Userspace - Swappable)                               |
| * Providers: LLM backends (Anthropic, OpenAI, Azure, Ollama) |
| * Tools: Capabilities (filesystem, bash, web, search)        |
| * Orchestrators: Execution loops (basic, streaming, events)  |
| * Contexts: Memory management (simple, persistent)           |
| * Hooks: Observability (logging, redaction, approval)        |
+---------------------------------------------------------------+

Rust Kernel

The kernel is implemented in Rust for performance and type safety. Key details:

• Rust crate: crates/amplifier-core/ -- pure Rust kernel with all core types, traits, and engine logic
• PyO3 bridge: bindings/python/ -- thin Python bindings that expose Rust types to Python
• Python source: python/amplifier_core/ -- Pydantic models, module loader, and backward-compatible API surface

The RUST_AVAILABLE flag (on amplifier_core._engine) indicates whether the Rust engine loaded successfully. When available:

• Top-level imports (from amplifier_core import AmplifierSession) return Rust-backed types
• Submodule imports (from amplifier_core.session import AmplifierSession) return Python types for backward compatibility
• HookRegistry uses the Rust implementation for all hook dispatch
• CancellationToken uses the Rust implementation

For consumers, this is transparent -- the API is identical regardless of which implementation is active.

Design Philosophy

Mechanisms, Not Policies

The kernel provides capabilities without decisions:

Litmus test: "Could two teams want different behavior?" -> If yes, it's policy -> Module, not kernel.

Stability Guarantees

• Backward compatible: Existing modules continue working across kernel updates
• Minimal runtime dependencies: Only pydantic, pyyaml, typing-extensions (unchanged for consumers)
• Single maintainer scope: Can be understood by one person
• Additive evolution: Changes extend, don't break

Installation

For consumers

Core 2.0.1 combines the patched PyO3 dependency family, lifecycle contract work, and updated Actions pins. It is available only when the exact version is on PyPI, a non-draft GitHub release is published, and that release includes the matching qualification receipt. Branch and pull-request artifacts are not published release artifacts.

Install an available, qualified version as a binary-only dependency:

python -m pip install --only-binary=:all: amplifier-core==<qualified-release>

Verify the official release's automated evidence archive and SHA256SUMS before adoption. Follow Native artifact qualification to match the installed extension and wheel to its build receipt. Do not rebuild native Core as part of every application release when a qualified wheel exists.

For complete Amplifier installation and usage: -> https://github.com/microsoft/amplifier

For developers

Building from source requires the Rust toolchain:

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build and install in development mode
pip install maturin
maturin develop

# Or with uv
uv run maturin develop

To regenerate the committed Python gRPC stubs, install the pinned generator and run the canonical command:

python -m pip install grpcio-tools==1.78.0
python scripts/generate_grpc_stubs.py

See docs/RUST_CORE_TESTING.md for the full development setup guide.

Build dependencies: current stable Rust and maturin, using the locked dependencies. The resolved graph currently has a Wasmtime-driven Rust floor of at least 1.92 (PyO3 alone has a 1.83 floor); the project's actual MSRV has not been independently validated. This is guidance, not a new minimum-Rust CI requirement.

Core 2.0.1 native-artifact and lifecycle release

Version 2.0.1 updates PyO3 to 0.29.2, pyo3-async-runtimes to 0.29.0, and pyo3-log to 0.13.4, outside the affected ranges for GHSA-36hh-v3qg-5jq4, GHSA-chgr-c6px-7xpp, RustSec-2026-0176, and RustSec-2026-0177.

The binding keeps abi3-py311, multiple-pymethods, and the deprecated generate-import-lib feature for compatibility; Windows qualification is required before any future linkage migration to raw-dylib. The lifecycle work from PR #114 and the PyO3 remediation from PR #115 retain their separate attribution while shipping together in 2.0.1.

The Rust-backed Python session attempts session:end at most once per initialized lifetime; cancellation can interrupt delivery, and the host owns cleanup completion. See CONTRACTS.md for the authoritative lifecycle and registration-ownership contracts. See Native Artifact Qualification for evidence and adoption requirements.

Core Concepts

Session

Execution context with mounted modules and conversation state. Lifespan: initialize() -> execute() -> cleanup().

Mount Plan

Configuration dictionary specifying which modules to load and their configuration. Apps/bundles compile to Mount Plans.

Coordinator

Infrastructure context providing session_id, config access, hooks, and mount points. Injected into all modules.

Module Types

All modules use Python Protocol (structural typing, no inheritance required):

• Provider - LLM backends (name, complete(), parse_tool_calls(), get_info(), list_models())
• Tool - Agent capabilities (name, description, execute())
• Orchestrator - Execution loops (execute())
• ContextManager - Memory (add_message(), get_messages(), compact())
• Hook - Observability (call(event, data) -> HookResult)

API Example

from amplifier_core import AmplifierSession

# Define mount plan (modules must be installed or discoverable)
config = {
    "session": {
        "orchestrator": "loop-basic",
        "context": "context-simple"
    },
    "providers": [
        {"module": "provider-anthropic"}
    ],
    "tools": [
        {"module": "tool-filesystem"},
        {"module": "tool-bash"}
    ]
}

# Create and use session
async with AmplifierSession(config) as session:
    response = await session.execute("List files in current directory")

Module Development

Modules implement protocols via structural typing (duck typing):

from amplifier_core.interfaces import Tool
from amplifier_core.models import ToolResult

class MyTool:
    """Implements Tool protocol without inheritance."""

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

    @property
    def description(self) -> str:
        return "Does something useful"

    async def execute(self, input: dict) -> ToolResult:
        """Execute tool with input dict."""
        return ToolResult(
            output=f"Processed: {input.get('param')}",
            error=None
        )

# Mount function (entry point)
async def mount(coordinator, config):
    tool = MyTool()
    await coordinator.mount("tools", tool, name="my_tool")

    async def cleanup():
        pass  # Cleanup resources

    return cleanup

Entry point (pyproject.toml):

[project.entry-points."amplifier.modules"]
my-tool = "amplifier_module_my_tool:mount"

For complete module development guide: -> https://github.com/microsoft/amplifier

Documentation

Rust/Python Type Mapping:

• CONTRACTS.md - Authoritative Rust/Python type mapping for the PyO3 boundary

Module Contracts (Entry Point for Developers):

• Contracts Index - Start here for module development
• Provider Contract - LLM backend protocol
• Tool Contract - Agent capability protocol
• Hook Contract - Observability protocol
• Orchestrator Contract - Execution loop protocol
• Context Contract - Memory manager protocol

Specifications (Detailed Design):

• Mount Plan Specification - Configuration format
• Provider Specification - LLM provider details
• Contribution Channels - Module contribution protocol

Detailed Guides:

• Hooks API - Complete hook system reference
• Session Forking - Child sessions for delegation
• Module Source Protocol - Custom module loading
• Rust Core Testing - Development setup and testing guide
• Rust Core Limitations - Known limitations
• Native Artifact Qualification - release evidence and consumer verification

Philosophy:

• Design Philosophy - Kernel principles and patterns

Testing

# Rust kernel tests
cargo test -p amplifier-core

# Python tests (includes binding tests)
uv run pytest tests/ bindings/python/tests/ -q --tb=short

# Full coverage
uv run pytest tests/ bindings/python/tests/ --cov

# Validate Rust kernel integration
uv run python tests/validate_rust_kernel.py

Contributing

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.