[GH-ISSUE #50] [Implementation] Implement Amp Adapter #18

New issue

Closed

opened 2026-02-27 10:21:47 +03:00 by kerem · 0 comments

kerem commented

2026-02-27 10:21:47 +03:00

Owner

Originally created by @mikeyobrien on GitHub (Jan 12, 2026).
Original GitHub issue: https://github.com/mikeyobrien/ralph-orchestrator/issues/50

Ref: #48

Task: Implement Amp Adapter

Description

Implement a new adapter class AmpAdapter in src/ralph_orchestrator/adapters/amp.py to enable the Ralph Orchestrator to use the Amp AI CLI tool (amp) as an execution backend. This allows users to leverage Amp's models and capabilities within the Ralph workflow.

Background

Ralph Orchestrator supports multiple AI backends via a plugin/adapter architecture. Issue #48 requests support for Amp. The Amp CLI (amp) is available for terminal-based AI interaction. We need to wrap this CLI in a python class adhering to the ToolAdapter interface.

Reference Documentation

Required:

Design: src/ralph_orchestrator/adapters/base.py (ToolAdapter interface)
Existing Implementation: src/ralph_orchestrator/adapters/kiro.py (Example of CLI wrapper)

Additional References:

Amp CLI documentation (external)

Note: You MUST read the detailed design document (base adapter) before beginning implementation.

Technical Requirements

Create src/ralph_orchestrator/adapters/amp.py.
Define AmpAdapter class inheriting from ToolAdapter.
Implement __init__ to configure the command (default amp).
Implement aexecute(self, prompt: str, prompt_file: str = None, verbose: bool = False) method.
Construct the shell command to invoke amp. Note: Check if amp supports non-interactive input/output or requires specific flags (e.g. reading from stdin or file).
Handle subprocess execution asynchronously (use asyncio.create_subprocess_exec).
Capture stdout and stderr.
Process the output to determine success/failure and token usage (if reported).
Implement unit tests in tests/test_amp_adapter.py.

Dependencies

src/ralph_orchestrator/adapters/base.py
asyncio

Implementation Approach

Analyze src/ralph_orchestrator/adapters/base.py to understand the contract.
Create src/ralph_orchestrator/adapters/amp.py.
Implement the class structure.
Implement the command execution logic, ensuring arguments are passed correctly to amp to accept the prompt.
- Assumption: amp accepts a prompt as an argument or via stdin. The adapter should handle this.
Add error handling for command not found or execution errors.
Create tests/test_amp_adapter.py mocking the subprocess to verify command construction and parsing.

Acceptance Criteria

Adapter Initialization
- Given the AmpAdapter class
- When initialized
- Then it sets valid defaults for command and timeout
Command Execution
- Given a prompt string "Hello World"
- When aexecute is called
- Then it calls the amp CLI with the prompt
- And captures the output
Error Handling
- Given amp is not installed
- When aexecute is called
- Then it handles FileNotFoundError gracefully and returns a failure response
Unit Tests
- Given the test suite
- When running pytest tests/test_amp_adapter.py
- Then all tests pass

Metadata

Complexity: Low
Labels: Adapter, Amp, CLI, Integration
Required Skills: Python, AsyncIO, Subprocess management

Originally created by @mikeyobrien on GitHub (Jan 12, 2026). Original GitHub issue: https://github.com/mikeyobrien/ralph-orchestrator/issues/50 # Ref: #48 # Task: Implement Amp Adapter ## Description Implement a new adapter class `AmpAdapter` in `src/ralph_orchestrator/adapters/amp.py` to enable the Ralph Orchestrator to use the Amp AI CLI tool (`amp`) as an execution backend. This allows users to leverage Amp's models and capabilities within the Ralph workflow. ## Background Ralph Orchestrator supports multiple AI backends via a plugin/adapter architecture. Issue #48 requests support for Amp. The Amp CLI (`amp`) is available for terminal-based AI interaction. We need to wrap this CLI in a python class adhering to the `ToolAdapter` interface. ## Reference Documentation **Required:** - Design: `src/ralph_orchestrator/adapters/base.py` (ToolAdapter interface) - Existing Implementation: `src/ralph_orchestrator/adapters/kiro.py` (Example of CLI wrapper) **Additional References:** - Amp CLI documentation (external) **Note:** You MUST read the detailed design document (base adapter) before beginning implementation. ## Technical Requirements 1. Create `src/ralph_orchestrator/adapters/amp.py`. 2. Define `AmpAdapter` class inheriting from `ToolAdapter`. 3. Implement `__init__` to configure the command (default `amp`). 4. Implement `aexecute(self, prompt: str, prompt_file: str = None, verbose: bool = False)` method. 5. Construct the shell command to invoke `amp`. Note: Check if `amp` supports non-interactive input/output or requires specific flags (e.g. reading from stdin or file). 6. Handle subprocess execution asynchronously (use `asyncio.create_subprocess_exec`). 7. Capture `stdout` and `stderr`. 8. Process the output to determine success/failure and token usage (if reported). 9. Implement unit tests in `tests/test_amp_adapter.py`. ## Dependencies - `src/ralph_orchestrator/adapters/base.py` - `asyncio` ## Implementation Approach 1. Analyze `src/ralph_orchestrator/adapters/base.py` to understand the contract. 2. Create `src/ralph_orchestrator/adapters/amp.py`. 3. Implement the class structure. 4. Implement the command execution logic, ensuring arguments are passed correctly to `amp` to accept the prompt. * *Assumption*: `amp` accepts a prompt as an argument or via stdin. The adapter should handle this. 5. Add error handling for command not found or execution errors. 6. Create `tests/test_amp_adapter.py` mocking the subprocess to verify command construction and parsing. ## Acceptance Criteria 1. **Adapter Initialization** - Given the AmpAdapter class - When initialized - Then it sets valid defaults for command and timeout 2. **Command Execution** - Given a prompt string "Hello World" - When `aexecute` is called - Then it calls the `amp` CLI with the prompt - And captures the output 3. **Error Handling** - Given `amp` is not installed - When `aexecute` is called - Then it handles `FileNotFoundError` gracefully and returns a failure response 4. **Unit Tests** - Given the test suite - When running `pytest tests/test_amp_adapter.py` - Then all tests pass ## Metadata - **Complexity**: Low - **Labels**: Adapter, Amp, CLI, Integration - **Required Skills**: Python, AsyncIO, Subprocess management