"""Response schemas for the Adapter-to-Core contract.

These models define the structure of data that tenant adapters send back
to ENTR Core after processing a document.
"""

from __future__ import annotations

from enum import Enum
from typing import Any, Dict, List

from pydantic import BaseModel, Field


class StatusEnum(str, Enum):
    """Adapter processing outcome status.

    Indicates the result of adapter processing for a document.
    """

    SUCCESS = "success"
    FAILED = "failed"
    REVIEW_REQUIRED = "review_required"


class ProposedValue(BaseModel):
    """A single proposed value with a description, part of a list of suggestions."""

    value: Any = Field(
        ..., description="The suggested value to be used"
    )
    description: str = Field(
        ..., description="A human-readable description for this value (e.g., product name, confidence score)"
    )


class ReviewSuggestion(BaseModel):
    """A single suggested change for a document under review."""

    field_path: str = Field(
        ..., description="JSON path to the field requiring a change (e.g., 'line_items.0.product_id')"
    )
    original_value: Any = Field(
        ..., description="The original value extracted from the document"
    )
    proposed_values: list[ProposedValue] = Field(
        ..., description="A list of possible values suggested by the adapter"
    )
    reason: str | None = Field(
        None, description="Explanation for why this change is suggested (e.g., 'Fuzzy match on product code')"
    )


class AdapterResponse(BaseModel):
    """Response sent back to ENTR Core after adapter processing.

    Contains the processing outcome, optional error details, review suggestions,
    user-facing notifications, and execution logs from the flight recorder.
    """

    document_id: int = Field(
        ..., description="ID of the document in the ENTR-CORE platform"
    )
    status: StatusEnum = Field(
        ..., description="Status of the adapter processing"
    )
    failure_type: str | None = Field(
        None, description="Type of failure if processing failed"
    )
    failure_reason: str | None = Field(
        None, description="Reason for failure if processing failed"
    )
    details: Dict[str, Any] | None = Field(
        None, description="Additional details about the processing result"
    )
    review_reason: str | None = Field(
        None, description="A high-level, human-readable reason why the document needs review"
    )
    review_suggestions: list[ReviewSuggestion] | None = Field(
        None, description="A structured list of proposed changes for review"
    )
    notifications: list[str] | None = Field(
        None, description="User-facing notifications to display after processing"
    )
    execution_logs: list[dict[str, Any]] | None = Field(
        None, description="Flight recorder execution logs from adapter processing"
    )
