diff --git a/CONTRACTS.md b/CONTRACTS.md index 63a472b..e94c331 100644 --- a/CONTRACTS.md +++ b/CONTRACTS.md @@ -186,20 +186,21 @@ These types stay as Python by design — they are app-layer concerns, not kernel ## Event Constants -Rust defines event names in `crates/amplifier-core/src/events.rs`. Python defines -them as class-level constants on `HookRegistry` in `hooks.py`. They must be -identical strings: +Canonical event names are defined in `crates/amplifier-core/src/events.rs` (Rust) +and re-exported in `amplifier_core.events` (Python). The full set contains 41+ +events; the table below lists the most commonly referenced ones. Always use the +constants from the events module rather than hard-coding strings. | Event | Value | |-------|-------| +| Execution start | `"execution:start"` | +| Execution end | `"execution:end"` | | Session start | `"session:start"` | | Session end | `"session:end"` | -| Turn start | `"turn:start"` | -| Turn end | `"turn:end"` | +| LLM request | `"llm:request"` | +| LLM response | `"llm:response"` | | Tool pre | `"tool:pre"` | | Tool post | `"tool:post"` | -| LLM pre | `"llm:pre"` | -| LLM post | `"llm:post"` | | Context compaction | `"context:compaction"` | --- diff --git a/docs/HOOKS_API.md b/docs/HOOKS_API.md index dbad5f7..f0afe83 100644 --- a/docs/HOOKS_API.md +++ b/docs/HOOKS_API.md @@ -5,7 +5,7 @@ last_modified: 2025-01-29 related_contracts: - path: contracts/HOOK_CONTRACT.md relationship: contract_hub - - path: ../amplifier_core/interfaces.py#HookHandler + - path: ../python/amplifier_core/interfaces.py#HookHandler relationship: protocol_definition lines: 205-220 --- diff --git a/docs/contracts/CONTEXT_CONTRACT.md b/docs/contracts/CONTEXT_CONTRACT.md index b3fe704..6643cc1 100644 --- a/docs/contracts/CONTEXT_CONTRACT.md +++ b/docs/contracts/CONTEXT_CONTRACT.md @@ -4,14 +4,13 @@ module_type: context contract_version: 2.1.0 last_modified: 2026-01-01 related_files: - - path: amplifier_core/interfaces.py#ContextManager + - path: ../../python/amplifier_core/interfaces.py#ContextManager relationship: protocol_definition - lines: 148-180 - path: ../specs/MOUNT_PLAN_SPECIFICATION.md relationship: configuration - path: ../specs/CONTRIBUTION_CHANNELS.md relationship: observability - - path: amplifier_core/testing.py#MockContextManager + - path: ../../python/amplifier_core/testing.py#MockContextManager relationship: test_utilities canonical_example: https://github.com/microsoft/amplifier-module-context-simple --- @@ -38,7 +37,7 @@ Context managers control **what the agent remembers**: ## Protocol Definition -**Source**: `amplifier_core/interfaces.py` lines 148-180 +**Source**: `amplifier_core/interfaces.py` → `class ContextManager(Protocol)` ```python @runtime_checkable diff --git a/docs/contracts/HOOK_CONTRACT.md b/docs/contracts/HOOK_CONTRACT.md index c1f7c86..6a38925 100644 --- a/docs/contracts/HOOK_CONTRACT.md +++ b/docs/contracts/HOOK_CONTRACT.md @@ -4,10 +4,9 @@ module_type: hook contract_version: 1.0.0 last_modified: 2025-01-29 related_files: - - path: amplifier_core/interfaces.py#HookHandler + - path: ../../python/amplifier_core/interfaces.py#HookHandler relationship: protocol_definition - lines: 205-220 - - path: amplifier_core/models.py#HookResult + - path: ../../python/amplifier_core/models.py#HookResult relationship: result_model - path: ../HOOKS_API.md relationship: detailed_api @@ -15,7 +14,7 @@ related_files: relationship: configuration - path: ../specs/CONTRIBUTION_CHANNELS.md relationship: observability - - path: amplifier_core/testing.py#EventRecorder + - path: ../../python/amplifier_core/testing.py#EventRecorder relationship: test_utilities canonical_example: https://github.com/microsoft/amplifier-module-hooks-logging --- @@ -52,7 +51,7 @@ This contract provides the essentials. The API reference contains full details. ## Protocol Definition -**Source**: `amplifier_core/interfaces.py` lines 205-220 +**Source**: `amplifier_core/interfaces.py` → `class HookHandler(Protocol)` ```python @runtime_checkable diff --git a/docs/contracts/ORCHESTRATOR_CONTRACT.md b/docs/contracts/ORCHESTRATOR_CONTRACT.md index 44c5db2..c7e8d30 100644 --- a/docs/contracts/ORCHESTRATOR_CONTRACT.md +++ b/docs/contracts/ORCHESTRATOR_CONTRACT.md @@ -4,16 +4,15 @@ module_type: orchestrator contract_version: 1.0.0 last_modified: 2026-03-05 related_files: - - path: amplifier_core/interfaces.py#Orchestrator + - path: ../../python/amplifier_core/interfaces.py#Orchestrator relationship: protocol_definition - lines: 26-55 - - path: amplifier_core/content_models.py + - path: ../../python/amplifier_core/content_models.py relationship: event_content_types - path: ../specs/MOUNT_PLAN_SPECIFICATION.md relationship: configuration - path: ../specs/CONTRIBUTION_CHANNELS.md relationship: observability - - path: amplifier_core/testing.py#ScriptedOrchestrator + - path: ../../python/amplifier_core/testing.py#ScriptedOrchestrator relationship: test_utilities canonical_example: https://github.com/microsoft/amplifier-module-loop-basic --- @@ -38,7 +37,7 @@ Orchestrators control **how** agents execute: ## Protocol Definition -**Source**: `amplifier_core/interfaces.py` lines 26-52 +**Source**: `amplifier_core/interfaces.py` → `class Orchestrator(Protocol)` ```python @runtime_checkable @@ -50,7 +49,7 @@ class Orchestrator(Protocol): providers: dict[str, Provider], tools: dict[str, Tool], hooks: HookRegistry, - coordinator: ModuleCoordinator | None = None, + **kwargs: Any, ) -> str: """ Execute the agent loop with given prompt. @@ -61,8 +60,7 @@ class Orchestrator(Protocol): providers: Available LLM providers (keyed by name) tools: Available tools (keyed by name) hooks: Hook registry for lifecycle events - coordinator: Module coordinator for accessing shared services - (optional; passed by session.py in production) + **kwargs: Additional kernel-injected arguments (see note below) Returns: Final response string @@ -70,6 +68,12 @@ class Orchestrator(Protocol): ... ``` +> **`coordinator` injection**: The kernel (`session.py`) passes +> `coordinator=` via kwargs at runtime so orchestrators can +> process hook results and coordinate module interactions. Implementations may +> accept `coordinator` as an explicit keyword argument or simply absorb it +> through `**kwargs`. + --- ## Execution Flow @@ -200,7 +204,7 @@ async def execute(self, prompt, context, providers, tools, hooks): - `execution:end` MUST be emitted on **ALL exit paths** — normal completion, error, and cancellation ```python -async def execute(self, prompt, context, providers, tools, hooks, coordinator=None): +async def execute(self, prompt, context, providers, tools, hooks, **kwargs): # REQUIRED: Emit at the very start of execute() await hooks.emit("execution:start", {"prompt": prompt}) @@ -369,7 +373,7 @@ Additional examples: ### Required -- [ ] Implements `execute(prompt, context, providers, tools, hooks, coordinator=None) -> str` +- [ ] Implements `execute(prompt, context, providers, tools, hooks, **kwargs) -> str` - [ ] `mount()` function with entry point in pyproject.toml - [ ] **Emits `execution:start` with `{prompt}` at the very beginning of `execute()`** - [ ] **Emits `execution:end` with `{response, status}` on ALL exit paths (success, error, cancellation)** diff --git a/docs/contracts/PROVIDER_CONTRACT.md b/docs/contracts/PROVIDER_CONTRACT.md index da05e2a..2adf86c 100644 --- a/docs/contracts/PROVIDER_CONTRACT.md +++ b/docs/contracts/PROVIDER_CONTRACT.md @@ -4,14 +4,13 @@ module_type: provider contract_version: 1.0.0 last_modified: 2025-01-29 related_files: - - path: amplifier_core/interfaces.py#Provider + - path: ../../python/amplifier_core/interfaces.py#Provider relationship: protocol_definition - lines: 54-119 - - path: amplifier_core/message_models.py + - path: ../../python/amplifier_core/message_models.py relationship: request_response_models - - path: amplifier_core/content_models.py + - path: ../../python/amplifier_core/content_models.py relationship: event_content_types - - path: amplifier_core/models.py#ProviderInfo + - path: ../../python/amplifier_core/models.py#ProviderInfo relationship: metadata_models - path: ../specs/PROVIDER_SPECIFICATION.md relationship: detailed_spec @@ -19,7 +18,7 @@ related_files: relationship: configuration - path: ../specs/CONTRIBUTION_CHANNELS.md relationship: observability - - path: amplifier_core/testing.py + - path: ../../python/amplifier_core/testing.py relationship: test_utilities canonical_example: https://github.com/microsoft/amplifier-module-provider-anthropic --- @@ -46,7 +45,7 @@ This contract document provides the quick-reference essentials. The specificatio ## Protocol Definition -**Source**: `amplifier_core/interfaces.py` lines 54-119 +**Source**: `amplifier_core/interfaces.py` → `class Provider(Protocol)` ```python @runtime_checkable diff --git a/docs/contracts/TOOL_CONTRACT.md b/docs/contracts/TOOL_CONTRACT.md index 628eb51..df234c9 100644 --- a/docs/contracts/TOOL_CONTRACT.md +++ b/docs/contracts/TOOL_CONTRACT.md @@ -4,16 +4,15 @@ module_type: tool contract_version: 1.0.0 last_modified: 2025-01-29 related_files: - - path: amplifier_core/interfaces.py#Tool + - path: ../../python/amplifier_core/interfaces.py#Tool relationship: protocol_definition - lines: 121-146 - - path: amplifier_core/models.py#ToolResult + - path: ../../python/amplifier_core/models.py#ToolResult relationship: result_model - - path: amplifier_core/message_models.py#ToolCall + - path: ../../python/amplifier_core/message_models.py#ToolCall relationship: invocation_model - path: ../specs/MOUNT_PLAN_SPECIFICATION.md relationship: configuration - - path: amplifier_core/testing.py#MockTool + - path: ../../python/amplifier_core/testing.py#MockTool relationship: test_utilities canonical_example: https://github.com/microsoft/amplifier-module-tool-filesystem --- @@ -37,7 +36,7 @@ Tools extend agent capabilities beyond pure conversation: ## Protocol Definition -**Source**: `amplifier_core/interfaces.py` lines 121-146 +**Source**: `amplifier_core/interfaces.py` → `class Tool(Protocol)` ```python @runtime_checkable diff --git a/python/amplifier_core/interfaces.py b/python/amplifier_core/interfaces.py index ef989bc..03b6e62 100644 --- a/python/amplifier_core/interfaces.py +++ b/python/amplifier_core/interfaces.py @@ -3,11 +3,11 @@ Uses Protocol classes for structural subtyping (no inheritance required). Related contracts (for module developers): - - docs/contracts/PROVIDER_CONTRACT.md (Provider, lines 54-119) - - docs/contracts/TOOL_CONTRACT.md (Tool, lines 121-146) - - docs/contracts/HOOK_CONTRACT.md (HookHandler, lines 173-189) - - docs/contracts/ORCHESTRATOR_CONTRACT.md (Orchestrator, lines 26-52) - - docs/contracts/CONTEXT_CONTRACT.md (ContextManager, lines 148-180) + - docs/contracts/ORCHESTRATOR_CONTRACT.md (Orchestrator) + - docs/contracts/PROVIDER_CONTRACT.md (Provider) + - docs/contracts/TOOL_CONTRACT.md (Tool) + - docs/contracts/CONTEXT_CONTRACT.md (ContextManager) + - docs/contracts/HOOK_CONTRACT.md (HookHandler) """ from typing import TYPE_CHECKING