"""AgentMiddleware abstract base class.

Defines the middleware hook interface for LangChain agent pipelines.
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any


@dataclass
class ToolCall:
    """Represents a single tool call from a model response."""

    name: str
    args: dict[str, Any] = field(default_factory=dict)
    id: str = ""


@dataclass
class ModelResponse:
    """Represents a model response that may contain tool calls."""

    content: str = ""
    tool_calls: list[ToolCall] = field(default_factory=list)


class AgentMiddleware(ABC):
    """Abstract base class for agent middleware.

    Subclasses implement hooks that intercept and transform data
    flowing through the agent loop.
    """

    def after_model(self, response: ModelResponse) -> ModelResponse:
        """Called after the model returns a response.

        Can inspect/modify tool calls before execution.
        """
        return response

    def wrap_tool_call(self, tool_call: ToolCall) -> ToolCall | None:
        """Called around each tool call execution.

        Return the tool call to proceed, or None to skip it.
        """
        return tool_call

    def after_agent(self, state: dict[str, Any]) -> dict[str, Any]:
        """Called after the agent loop completes.

        Can attach metadata to the final agent state.
        """
        return state
