app_types.py

"""
Type definitions for the GradeM8 application (renamed to avoid stdlib conflict).
"""

from typing import TypedDict, NotRequired, Callable, Protocol


class RubricBreakdown(TypedDict, total=False):
    """Score breakdown by criterion.

    Keys are criterion names, values are scores (0-100).
    This is a flexible type - criteria vary by rubric.
    """
    # Example criteria (not required):
    clarity: int
    grammar: int
    accuracy: int
    # Additional criteria can be added dynamically


class GradingResult(TypedDict):
    """Complete result from grading a single submission."""
    score: int
    rubric_breakdown: dict[str, int]
    summary: str
    strengths: list[str]
    improvements: list[str]
    feedback: str
    details: str


class GradingResultWithStatus(TypedDict):
    """Grading result including processing status."""
    index: int
    score: int | None
    feedback: str
    summary: str
    rubric_breakdown: dict[str, int]
    strengths: list[str]
    improvements: list[str]
    details: str
    status: str  # "success" or "error"
    filename: NotRequired[str]  # Optional filename injection


class BatchSummary(TypedDict):
    """Summary statistics for a batch grading operation."""
    total: int
    successful: int
    failed: int
    avg_score: float


class ProgressCallback(Protocol):
    """Protocol for progress callback functions.
    
    Used for asynchronous progress updates during batch operations.
    """
    def __call__(self, current: int, total: int, message: str) -> None:
        """Update progress state.
        
        Args:
            current: Current item number (1-indexed)
            total: Total number of items to process
            message: Human-readable status message
        """
        pass


class BatchResultDisplay(TypedDict):
    """Formatted result for display in the UI."""
    filename: str
    score: int | None
    feedback: str
    summary: str
    rubric_breakdown: dict[str, int]
    strengths: list[str]
    improvements: list[str]
    details: str
    status: str


class BatchResult(TypedDict):
    """Complete result from a batch grading operation."""
    batch_summary: BatchSummary
    results: list[BatchResultDisplay]  # Changed from dict[str, object] to proper type


class ExtractedDocument(TypedDict):
    """Result of document text extraction."""
    filename: str
    content: str
    status: str  # "success" or error message


class PDFMetadata(TypedDict):
    """Metadata extracted from a PDF document."""
    text: str
    page_count: int
    title: str
    author: str
    error: str | None


ProgressCallback = Callable[[int, int, str], None]
"""Callback for progress updates: (current, total, message) -> None"""


class DeepInfraChoice(TypedDict):
    """Choice object from DeepInfra API response."""
    message: dict[str, str]
    index: int
    finish_reason: str


class DeepInfraResponse(TypedDict):
    """Complete response from DeepInfra API."""
    id: str
    object: str
    created: int
    model: str
    choices: list[DeepInfraChoice]