backend/src/agents/autonomy.py

"""autonomy — schema for a future per-minute LLM "deviate from plan" decision.

Defines AutonomyDecision (deviate / deviation_type / reason / duration)
as the structured contract for a behavior switch the brain may request.

Architecture: prepared for brain.py and the engine; currently no call
site exists (the decision is gated off until enabled).
Design: kept as a standalone schema so enabling autonomy later requires
no changes to existing callers.
"""

from __future__ import annotations

from pydantic import BaseModel
from typing import Optional


class AutonomyDecision(BaseModel):
    """Structured output from the autonomy LLM call."""
    deviate: bool
    deviation_type: Optional[str] = None
    reason: Optional[str] = None
    duration_minutes: int = 0