feat: initial dataset review orchestration flow implementation

backend/src/schemas/dataset_review.py

@@ -0,0 +1,362 @@
+# [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 -> pydantic
+
+# [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]