Skip to content

Latest commit

 

History

History
89 lines (62 loc) · 2.97 KB

README.md

File metadata and controls

89 lines (62 loc) · 2.97 KB

Module Contracts

Start here for building Amplifier modules.

This directory contains the authoritative guidance for building each type of Amplifier module. Each contract document explains:

  1. What it is - Purpose and responsibilities
  2. Protocol reference - Link to interfaces.py with exact line numbers
  3. Entry point pattern - How modules are discovered and loaded
  4. Configuration - Mount Plan integration
  5. Canonical example - Reference implementation
  6. Validation - How to verify your module works

Module Types

Module Type Contract Purpose
Provider PROVIDER_CONTRACT.md LLM backend integration
Tool TOOL_CONTRACT.md Agent capabilities
Hook HOOK_CONTRACT.md Lifecycle observation and control
Orchestrator ORCHESTRATOR_CONTRACT.md Agent loop execution strategy
Context CONTEXT_CONTRACT.md Conversation memory management

Quick Start Pattern

All modules follow this pattern:

# 1. Implement the Protocol from interfaces.py
class MyModule:
    # ... implement required methods
    pass

# 2. Provide mount() function
async def mount(coordinator, config):
    """Initialize and register module."""
    instance = MyModule(config)
    await coordinator.mount("category", instance, name="my-module")
    return instance  # or cleanup function

# 3. Register entry point in pyproject.toml
# [project.entry-points."amplifier.modules"]
# my-module = "my_package:mount"

Source of Truth

Protocols are in code, not docs:

  • Protocol definitions: python/amplifier_core/interfaces.py
  • Data models: python/amplifier_core/models.py
  • Message models: python/amplifier_core/message_models.py (Pydantic models for request/response envelopes)
  • Content models: python/amplifier_core/content_models.py (dataclass types for events and streaming)
  • Rust traits: crates/amplifier-core/src/traits.rs (Rust-side trait definitions)
  • Rust/Python type mapping: CONTRACTS.md (authoritative cross-boundary reference)

These contract documents provide guidance that code cannot express. Always read the code docstrings first.

Related Documentation

Validation

Verify your module before release:

# Structural validation
amplifier module validate ./my-module

See individual contract documents for type-specific validation requirements.

For ecosystem overview: amplifier