Steering & Error Recovery

from marsys.coordination.validation import ValidationErrorCategory

class ValidationErrorCategory(Enum):
    """Categories of validation errors for targeted steering."""
    FORMAT_ERROR = "format_error"           # JSON structure, parsing errors
    PERMISSION_ERROR = "permission_error"   # Agent permission denied
    ACTION_ERROR = "action_error"           # Invalid action type
    API_TRANSIENT = "api_transient"         # Rate limit, timeout, network
    API_TERMINAL = "api_terminal"           # Auth failure, invalid model
    TOOL_ERROR = "tool_error"               # Tool execution failure
    UNKNOWN = "unknown"

from marsys.coordination.steering import SteeringManager, SteeringContext, ErrorContext

# Initialize (automatically done by StepExecutor)
steering_manager = SteeringManager()

# Get steering prompt
prompt = steering_manager.get_steering_prompt(context)

# Get statistics
stats = steering_manager.get_stats()
# {
#     "total_injections": 15,
#     "by_mode": {"error": 10, "auto": 3, "always": 2},
#     "by_category": {
#         "format_error": 8,
#         "permission_error": 3,
#         "action_error": 2
#     }
# }

from marsys.coordination import Orchestra
from marsys.coordination.config import ExecutionConfig

# Mode 1: "error" - Only inject when error occurred (DEFAULT, minimum interference)
result = await Orchestra.run(
    task="Your task",
    topology=topology,
    execution_config=ExecutionConfig(
        steering_mode="error"  # Only on validation/API errors
    )
)

# Mode 2: "auto" - Inject on any retry (balanced)
result = await Orchestra.run(
    task="Your task",
    topology=topology,
    execution_config=ExecutionConfig(
        steering_mode="auto"  # On all retries, error-specific when available
    )
)

# Mode 3: "always" - Inject on every step (maximum guidance)
result = await Orchestra.run(
    task="Your task",
    topology=topology,
    execution_config=ExecutionConfig(
        steering_mode="always"  # Every step, even without errors
    )
)

# Access steering statistics
stats = step_executor.steering_manager.get_stats()

print(f"Total injections: {stats['total_injections']}")
print(f"By mode: {stats['by_mode']}")
print(f"By category: {stats['by_category']}")

# Example output:
# Total injections: 15
# By mode: {'error': 10, 'auto': 3, 'always': 2}
# By category: {'format_error': 8, 'permission_error': 3, 'action_error': 2}

from marsys.coordination.steering import SteeringManager

class CustomSteeringManager(SteeringManager):
    """Custom steering with domain-specific logic."""

    def _build_error_prompt(self, context):
        """Override to add custom error handling."""
        error = context.error_context

        # Custom logic for your domain
        if error.category == ValidationErrorCategory.FORMAT_ERROR:
            if "medical" in context.agent_name.lower():
                return self._medical_format_prompt(context)

        # Fallback to default
        return super()._build_error_prompt(context)

    def _medical_format_prompt(self, context):
        """Domain-specific prompt for medical agents."""
        return """
Your previous response had an incorrect medical report format.

Please use this structure:
\`\`\`json
{
  "diagnosis": "...",
  "treatment": "...",
  "confidence": 0.95
}
\`\`\`
"""

# Apply different steering modes based on agent type
if agent.name.startswith("Experimental_"):
    steering_mode = "always"  # More guidance for experimental agents
elif agent.name in critical_agents:
    steering_mode = "error"  # Minimal interference for critical path
else:
    steering_mode = "auto"  # Balanced for others

config = ExecutionConfig(steering_mode=steering_mode)

@dataclass
class SteeringContext:
    agent_name: str
    available_actions: List[str]
    error_context: Optional[ErrorContext] = None
    is_retry: bool = False
    steering_mode: str = "error"

@dataclass
class ErrorContext:
    category: ValidationErrorCategory
    error_message: str
    retry_suggestion: Optional[str] = None
    retry_count: int = 0
    classification: Optional[str] = None  # For API errors
    failed_action: Optional[str] = None

class SteeringManager:
    def get_steering_prompt(self, context: SteeringContext) -> Optional[str]:
        """Get steering prompt for given context."""

    def get_stats(self) -> dict:
        """Get steering injection statistics."""

    def _build_error_prompt(self, context: SteeringContext) -> str:
        """Build error-category-specific prompt."""

    def _build_generic_prompt(self, context: SteeringContext) -> str:
        """Build generic steering prompt."""