from __future__ import annotations

from typing import Any, Protocol

from app.core.ai.domain.models import (
    AiResponse,
    AiStructuredRequest,
    AiTextRequest,
    AiVisionRequest,
)


class AiGatewayPort(Protocol):
    """Hexagonal Architecture Port for Enterprise AI interactions."""

    async def generate_text(self, request: AiTextRequest) -> AiResponse:
        """Execute text or multi-turn conversational inference."""
        ...

    async def analyze_vision(self, request: AiVisionRequest) -> AiResponse:
        """Execute multimodal vision analysis on images, drawings or document scans."""
        ...

    async def generate_structured(
        self, request: AiStructuredRequest
    ) -> dict[str, Any]:
        """Execute inference and return guaranteed parsed JSON object matching schema."""
        ...