ss-tools/backend/src/schemas/dataset_review.py

# [DEF:DatasetReviewSchemas:Module]
#
# @COMPLEXITY: 3
# @SEMANTICS: dataset_review, schemas, pydantic, session, profile, findings
# @PURPOSE:   Defines API schemas for the dataset review orchestration flow.
# @LAYER:     API
# @RELATION:  DEPENDS_ON -> [DatasetReviewModels]

# [SECTION: IMPORTS]
from datetime import datetime
from typing import List, Optional, Any
from pydantic import BaseModel, Field
from src.models.dataset_review import (
    SessionStatus,
    SessionPhase,
    ReadinessState,
    RecommendedAction,
    SessionCollaboratorRole,
    BusinessSummarySource,
    ConfidenceState,
    FindingArea,
    FindingSeverity,
    ResolutionState,
    SemanticSourceType,
    TrustLevel,
    SemanticSourceStatus,
    FieldKind,
    FieldProvenance,
    CandidateMatchType,
    CandidateStatus,
    FilterSource,
    FilterConfidenceState,
    FilterRecoveryStatus,
    VariableKind,
    MappingStatus,
    MappingMethod,
    MappingWarningLevel,
    ApprovalState,
    ClarificationStatus,
    QuestionState,
    AnswerKind,
    PreviewStatus,
    LaunchStatus,
    ArtifactType,
    ArtifactFormat
)
# [/SECTION]

# [DEF:SessionCollaboratorDto:Class]
class SessionCollaboratorDto(BaseModel):
    user_id: str
    role: SessionCollaboratorRole
    added_at: datetime

    class Config:
        from_attributes = True
# [/DEF:SessionCollaboratorDto:Class]

# [DEF:DatasetProfileDto:Class]
class DatasetProfileDto(BaseModel):
    profile_id: str
    session_id: str
    dataset_name: str
    schema_name: Optional[str] = None
    database_name: Optional[str] = None
    business_summary: str
    business_summary_source: BusinessSummarySource
    description: Optional[str] = None
    dataset_type: Optional[str] = None
    is_sqllab_view: bool
    completeness_score: Optional[float] = None
    confidence_state: ConfidenceState
    has_blocking_findings: bool
    has_warning_findings: bool
    manual_summary_locked: bool
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True
# [/DEF:DatasetProfileDto:Class]

# [DEF:ValidationFindingDto:Class]
class ValidationFindingDto(BaseModel):
    finding_id: str
    session_id: str
    area: FindingArea
    severity: FindingSeverity
    code: str
    title: str
    message: str
    resolution_state: ResolutionState
    resolution_note: Optional[str] = None
    caused_by_ref: Optional[str] = None
    created_at: datetime
    resolved_at: Optional[datetime] = None

    class Config:
        from_attributes = True
# [/DEF:ValidationFindingDto:Class]

# [DEF:SemanticSourceDto:Class]
class SemanticSourceDto(BaseModel):
    source_id: str
    session_id: str
    source_type: SemanticSourceType
    source_ref: str
    source_version: str
    display_name: str
    trust_level: TrustLevel
    schema_overlap_score: Optional[float] = None
    status: SemanticSourceStatus
    created_at: datetime

    class Config:
        from_attributes = True
# [/DEF:SemanticSourceDto:Class]

# [DEF:SemanticCandidateDto:Class]
class SemanticCandidateDto(BaseModel):
    candidate_id: str
    field_id: str
    source_id: Optional[str] = None
    candidate_rank: int
    match_type: CandidateMatchType
    confidence_score: float
    proposed_verbose_name: Optional[str] = None
    proposed_description: Optional[str] = None
    proposed_display_format: Optional[str] = None
    status: CandidateStatus
    created_at: datetime

    class Config:
        from_attributes = True
# [/DEF:SemanticCandidateDto:Class]

# [DEF:SemanticFieldEntryDto:Class]
class SemanticFieldEntryDto(BaseModel):
    field_id: str
    session_id: str
    field_name: str
    field_kind: FieldKind
    verbose_name: Optional[str] = None
    description: Optional[str] = None
    display_format: Optional[str] = None
    provenance: FieldProvenance
    source_id: Optional[str] = None
    confidence_rank: Optional[int] = None
    is_locked: bool
    has_conflict: bool
    needs_review: bool
    last_changed_by: str
    user_feedback: Optional[str] = None
    created_at: datetime
    updated_at: datetime
    candidates: List[SemanticCandidateDto] = []

    class Config:
        from_attributes = True
# [/DEF:SemanticFieldEntryDto:Class]

# [DEF:ImportedFilterDto:Class]
class ImportedFilterDto(BaseModel):
    filter_id: str
    session_id: str
    filter_name: str
    display_name: Optional[str] = None
    raw_value: Any
    normalized_value: Optional[Any] = None
    source: FilterSource
    confidence_state: FilterConfidenceState
    requires_confirmation: bool
    recovery_status: FilterRecoveryStatus
    notes: Optional[str] = None
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True
# [/DEF:ImportedFilterDto:Class]

# [DEF:TemplateVariableDto:Class]
class TemplateVariableDto(BaseModel):
    variable_id: str
    session_id: str
    variable_name: str
    expression_source: str
    variable_kind: VariableKind
    is_required: bool
    default_value: Optional[Any] = None
    mapping_status: MappingStatus
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True
# [/DEF:TemplateVariableDto:Class]

# [DEF:ExecutionMappingDto:Class]
class ExecutionMappingDto(BaseModel):
    mapping_id: str
    session_id: str
    filter_id: str
    variable_id: str
    mapping_method: MappingMethod
    raw_input_value: Any
    effective_value: Optional[Any] = None
    transformation_note: Optional[str] = None
    warning_level: Optional[MappingWarningLevel] = None
    requires_explicit_approval: bool
    approval_state: ApprovalState
    approved_by_user_id: Optional[str] = None
    approved_at: Optional[datetime] = None
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True
# [/DEF:ExecutionMappingDto:Class]

# [DEF:ClarificationOptionDto:Class]
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]
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
    created_at: datetime

    class Config:
        from_attributes = True
# [/DEF:ClarificationAnswerDto:Class]

# [DEF:ClarificationQuestionDto:Class]
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]
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]
class CompiledPreviewDto(BaseModel):
    preview_id: str
    session_id: str
    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]
class DatasetRunContextDto(BaseModel):
    run_context_id: str
    session_id: str
    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]
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
    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]
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] = []

    class Config:
        from_attributes = True
# [/DEF:SessionDetail:Class]

# [/DEF:DatasetReviewSchemas:Module]