Skip to main content

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:

Kernel Provides (Mechanism) Modules Decide (Policy)
Module loading Which modules to load
Event emission What to log, where
Session lifecycle Orchestration strategy
Hook registration Security policies

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):

Specifications (Detailed Design):

Detailed Guides:

Philosophy:

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.

Metadata

Release files for amplifier-core 2.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for amplifier-core 2.0.2
File Actions
amplifier_core-2.0.2-cp311-abi3-win_arm64.whl CPython 3.11 abi3 Windows ARM64 Details for amplifier_core-2.0.2-cp311-abi3-win_arm64.whl
amplifier_core-2.0.2-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for amplifier_core-2.0.2-cp311-abi3-win_amd64.whl
amplifier_core-2.0.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.11 abi3 Linux glibc 2.17+ x86-64 Details for amplifier_core-2.0.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
amplifier_core-2.0.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.11 abi3 Linux glibc 2.17+ ARM64 Details for amplifier_core-2.0.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
amplifier_core-2.0.2-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for amplifier_core-2.0.2-cp311-abi3-macosx_11_0_arm64.whl
amplifier_core-2.0.2-cp311-abi3-macosx_10_12_x86_64.whl CPython 3.11 abi3 macOS 10.12+ x86-64 Details for amplifier_core-2.0.2-cp311-abi3-macosx_10_12_x86_64.whl

Total release size: 49.2 MB

Release files / amplifier_core-2.0.2-cp311-abi3-win_arm64.whl

Download URL amplifier_core-2.0.2-cp311-abi3-win_arm64.whl
Size 7.8 MB
Tags CPython 3.11 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
4546b05fe3270029607f8a75807a4182a57c2390b441102d13fbf54a9e07e5b4
BLAKE2b-256 checksum
How to use checksums
3e0c8623cd4b87368dcfa9a7d446049fecd88af16349eb11045360438b330d29
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

Release files / amplifier_core-2.0.2-cp311-abi3-win_amd64.whl

Download URL amplifier_core-2.0.2-cp311-abi3-win_amd64.whl
Size 9.1 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
a784e9f0382c471794e429818d9e55360625523bc62c54cae56be172364c936c
BLAKE2b-256 checksum
How to use checksums
f66de833011187082f414d78db337dff5aff7b70935058b5dedcd4f2441449b5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

Release files / amplifier_core-2.0.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL amplifier_core-2.0.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 8.8 MB
Tags CPython 3.11 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
50406335d88598d6b4cba90f8598e7774d2b9b189e9d3992a09474b777036f9f
BLAKE2b-256 checksum
How to use checksums
e576b58ae511f00c3ba2774213c2d336a6c2e29c94819280df5e52b136b6dae3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

Release files / amplifier_core-2.0.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL amplifier_core-2.0.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 7.8 MB
Tags CPython 3.11 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
cba63bf80af198819ca648edbac4998735d2656fd19af0a569ef1849547a97ac
BLAKE2b-256 checksum
How to use checksums
927f80c9d27f76a3a1f0168ba4410e289d2eac21b01f5728e61be39df6ed9333
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

Release files / amplifier_core-2.0.2-cp311-abi3-macosx_11_0_arm64.whl

Download URL amplifier_core-2.0.2-cp311-abi3-macosx_11_0_arm64.whl
Size 7.4 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
0328151eff8baaa60004db03b85959dd1faaa15b6117a1b2fb2f18700341097f
BLAKE2b-256 checksum
How to use checksums
43dbcbb1514db368d05cd5812431641a627e721f2900bbdf16854e04befb6406
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

Release files / amplifier_core-2.0.2-cp311-abi3-macosx_10_12_x86_64.whl

Download URL amplifier_core-2.0.2-cp311-abi3-macosx_10_12_x86_64.whl
Size 8.3 MB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
4a4048503bd79b2223f14d319044f619e589fd7e0a1a42623f9b9c3e07e27299
BLAKE2b-256 checksum
How to use checksums
9b5cacf5c32dc9197325a71e96c005c54288ac6ddf2db50f3e9d00e8df12bbb1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

Security for amplifier-core 2.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for amplifier_core-2.0.2-cp311-abi3-win_arm64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.0.2 This release

6 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page