ss-tools/backend/src/schemas/dataset_review_pkg/_composites.py

# [DEF:DatasetReviewSchemaComposites:Module]
# @COMPLEXITY: 2
# @PURPOSE: Composite Pydantic DTOs for clarification, preview, run context, and session summary/detail responses.
# @LAYER: API
# @RELATION: DEPENDS_ON -> [DatasetReviewSchemaDtos]

from datetime import datetime
from typing import Any, List, Optional

from pydantic import BaseModel

from src.models.dataset_review import (
    ClarificationStatus,
    QuestionState,
    AnswerKind,
    PreviewStatus,
    LaunchStatus,
    SessionStatus,
    SessionPhase,
    ReadinessState,
    RecommendedAction,
)
from src.schemas.dataset_review_pkg._dtos import (
    SessionCollaboratorDto,
    DatasetProfileDto,
    ValidationFindingDto,
    SemanticSourceDto,
    SemanticFieldEntryDto,
    ImportedFilterDto,
    TemplateVariableDto,
    ExecutionMappingDto,
)


# [DEF:ClarificationOptionDto:Class]
# @COMPLEXITY: 1
# @PURPOSE: Clarification option DTO.
class ClarificationOptionDto(BaseModel):
    option_id: str
    question_id: str
    label: str
    value: str
    is_recommended: bool
    display_order: int

    class Config:
        from_attributes = True


# [/DEF:ClarificationOptionDto:Class]


# [DEF:ClarificationAnswerDto:Class]
# @COMPLEXITY: 1
# @PURPOSE: Clarification answer DTO with feedback.
class ClarificationAnswerDto(BaseModel):
    answer_id: str
    question_id: str
    answer_kind: AnswerKind
    answer_value: Optional[str] = None
    answered_by_user_id: str
    impact_summary: Optional[str] = None
    user_feedback: Optional[str] = None
    created_at: datetime

    class Config:
        from_attributes = True


# [/DEF:ClarificationAnswerDto:Class]


# [DEF:ClarificationQuestionDto:Class]
# @COMPLEXITY: 2
# @PURPOSE: Clarification question DTO with nested options and answer.
class ClarificationQuestionDto(BaseModel):
    question_id: str
    clarification_session_id: str
    topic_ref: str
    question_text: str
    why_it_matters: str
    current_guess: Optional[str] = None
    priority: int
    state: QuestionState
    created_at: datetime
    updated_at: datetime
    options: List[ClarificationOptionDto] = []
    answer: Optional[ClarificationAnswerDto] = None

    class Config:
        from_attributes = True


# [/DEF:ClarificationQuestionDto:Class]


# [DEF:ClarificationSessionDto:Class]
# @COMPLEXITY: 2
# @PURPOSE: Clarification session DTO with nested questions.
class ClarificationSessionDto(BaseModel):
    clarification_session_id: str
    session_id: str
    status: ClarificationStatus
    current_question_id: Optional[str] = None
    resolved_count: int
    remaining_count: int
    summary_delta: Optional[str] = None
    started_at: datetime
    updated_at: datetime
    completed_at: Optional[datetime] = None
    questions: List[ClarificationQuestionDto] = []

    class Config:
        from_attributes = True


# [/DEF:ClarificationSessionDto:Class]


# [DEF:CompiledPreviewDto:Class]
# @COMPLEXITY: 1
# @PURPOSE: Compiled preview DTO with fingerprint and session version.
class CompiledPreviewDto(BaseModel):
    preview_id: str
    session_id: str
    session_version: Optional[int] = None
    preview_status: PreviewStatus
    compiled_sql: Optional[str] = None
    preview_fingerprint: str
    compiled_by: str
    error_code: Optional[str] = None
    error_details: Optional[str] = None
    compiled_at: Optional[datetime] = None
    created_at: datetime

    class Config:
        from_attributes = True


# [/DEF:CompiledPreviewDto:Class]


# [DEF:DatasetRunContextDto:Class]
# @COMPLEXITY: 1
# @PURPOSE: Run context DTO with launch audit data and session version.
class DatasetRunContextDto(BaseModel):
    run_context_id: str
    session_id: str
    session_version: Optional[int] = None
    dataset_ref: str
    environment_id: str
    preview_id: str
    sql_lab_session_ref: str
    effective_filters: Any
    template_params: Any
    approved_mapping_ids: List[str]
    semantic_decision_refs: List[str]
    open_warning_refs: List[str]
    launch_status: LaunchStatus
    launch_error: Optional[str] = None
    created_at: datetime

    class Config:
        from_attributes = True


# [/DEF:DatasetRunContextDto:Class]


# [DEF:SessionSummary:Class]
# @COMPLEXITY: 2
# @PURPOSE: Lightweight session summary DTO for list responses.
class SessionSummary(BaseModel):
    session_id: str
    user_id: str
    environment_id: str
    source_kind: str
    source_input: str
    dataset_ref: str
    dataset_id: Optional[int] = None
    version: int = 0
    session_version: int = 0
    readiness_state: ReadinessState
    recommended_action: RecommendedAction
    status: SessionStatus
    current_phase: SessionPhase
    created_at: datetime
    updated_at: datetime
    last_activity_at: datetime

    class Config:
        from_attributes = True


# [/DEF:SessionSummary:Class]


# [DEF:SessionDetail:Class]
# @COMPLEXITY: 2
# @PURPOSE: Full session detail DTO with all nested aggregates for detail views.
# @RELATION: INHERITS -> [SessionSummary]
class SessionDetail(SessionSummary):
    collaborators: List[SessionCollaboratorDto] = []
    profile: Optional[DatasetProfileDto] = None
    findings: List[ValidationFindingDto] = []
    semantic_sources: List[SemanticSourceDto] = []
    semantic_fields: List[SemanticFieldEntryDto] = []
    imported_filters: List[ImportedFilterDto] = []
    template_variables: List[TemplateVariableDto] = []
    execution_mappings: List[ExecutionMappingDto] = []
    clarification_sessions: List[ClarificationSessionDto] = []
    previews: List[CompiledPreviewDto] = []
    run_contexts: List[DatasetRunContextDto] = []


# [/DEF:SessionDetail:Class]


# [/DEF:DatasetReviewSchemaComposites:Module]