feat(converters): add base action converter with OAGI implementation

[aoshen524]

Summary

Add action converter framework with base class for third-party extension and OAGI reference implementation.

Key Changes

• BaseActionConverter[T] - Abstract base class with shared functionality:

  • Coordinate scaling via scale_coordinate()
  • Key normalization via normalize_key(), parse_hotkey(), validate_keys()
  • action_string_to_step() for runtime API format conversion

• OagiActionConverter - Reference implementation for OAGI actions (0-1000 coordinate space)

• ConverterConfig - Unified configuration dataclass

• Shared utilities in oagi.handler.utils - Reusable by both handler and converters

Usage

from oagi.converters import OagiActionConverter, ConverterConfig

config = ConverterConfig(sandbox_width=1920, sandbox_height=1080)
converter = OagiActionConverter(config=config)

# Convert OAGI actions to pyautogui strings
result = converter(actions)  # list[tuple[str, bool]]

# Convert to runtime API steps
for cmd, is_last in result:
    step = converter.action_string_to_step(cmd)

Creating Custom Converters

Third parties can create custom converters by inheriting from BaseActionConverter:

from oagi.converters import BaseActionConverter, ConverterConfig

class MyModelConverter(BaseActionConverter[MyAction]):
    @property
    def coord_width(self) -> int:
        return 1024  # Your model's coordinate width

    @property
    def coord_height(self) -> int:
        return 768  # Your model's coordinate height

    def _convert_single_action(self, action: MyAction) -> list[str]:
        # Convert action to pyautogui command strings
        ...

    def serialize_actions(self, actions: list[MyAction]) -> list[dict]:
        # Serialize actions for trajectory logging
        ...

Test plan

• Imports work: from oagi.converters import OagiActionConverter, BaseActionConverter, ConverterConfig
• 18 unit tests for OagiActionConverter (coordinate actions, drag, hotkey, type, scroll, wait, finish, action_string_to_step, multiple actions)
• Base class properly exported for inheritance

🤖 Generated with Claude Code