Merge pull request #33 from kookmin-sw/feature/#32-ai-schemas

[#32][AI] Pydantic 스키마 정의

Author: jys705

ai/schemas/__init__.py

@@ -1 +1,40 @@
-# ai/schemas — Pydantic 입출력 스키마
+"""ai/schemas — Pydantic 입출력 스키마 (AI Dataset Spec v3 기반)."""
+
+from ai.schemas.accept import AcceptInput, AcceptOutput
+from ai.schemas.common import (
+    CommonMistake,
+    DecisionHistoryItem,
+    GeneratedStep,
+    ProjectInfo,
+    RecommendedMethod,
+    RequiredStepInfo,
+    RequiredStepStatus,
+    RetrievedChunk,
+    StageInfo,
+    StepInfo,
+)
+from ai.schemas.generate import GenerateInput, GenerateOutput
+from ai.schemas.side_panel import SidePanelInput, SidePanelOutput
+
+__all__ = [
+    # common
+    "ProjectInfo",
+    "StageInfo",
+    "StepInfo",
+    "DecisionHistoryItem",
+    "RequiredStepInfo",
+    "RequiredStepStatus",
+    "GeneratedStep",
+    "RecommendedMethod",
+    "CommonMistake",
+    "RetrievedChunk",
+    # generate
+    "GenerateInput",
+    "GenerateOutput",
+    # accept
+    "AcceptInput",
+    "AcceptOutput",
+    # side_panel
+    "SidePanelInput",
+    "SidePanelOutput",
+]

ai/schemas/accept.py

@@ -1 +1,34 @@
-# ai/schemas/accept.py — AcceptInput, AcceptOutput (Phase 1에서 구현)
+"""accept 시나리오 입출력 스키마 — AI Dataset Spec v3 기반.
+
+필수 Step 충족 판단: is_current_required_step_completed를 반환.
+"""
+
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+from ai.schemas.common import (
+    ProjectInfo,
+    RequiredStepInfo,
+    RequiredStepStatus,
+    StageInfo,
+    StepInfo,
+)
+
+
+class AcceptInput(BaseModel):
+    """accept 시나리오 입력."""
+
+    project_info: ProjectInfo
+    current_stage: StageInfo
+    required_steps_status: list[RequiredStepStatus]
+    current_required_step: Optional[RequiredStepInfo] = None
+    accepted_steps_in_required: list[StepInfo]
+    accepted_step: StepInfo
+    rag_context: Optional[dict[str, Any]] = None
+
+
+class AcceptOutput(BaseModel):
+    """accept 시나리오 출력."""
+
+    is_current_required_step_completed: bool

ai/schemas/common.py

@@ -1 +1,93 @@
-# ai/schemas/common.py — 공통 Pydantic 모델 (Phase 1에서 구현)
+"""공통 Pydantic 모델 — AI Dataset Spec v3 기반.
+
+모든 AI 시나리오(generate, accept, side_panel)에서 공유하는 데이터 모델.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class ProjectInfo(BaseModel):
+    """프로젝트 기본 정보."""
+
+    project_id: str
+    name: Optional[str] = None
+    duration_months: int
+    member_count: int
+    description: Optional[str] = None
+    constraints: Optional[str] = None
+    initial_prompt: str
+
+
+class StageInfo(BaseModel):
+    """현재 Stage 정보."""
+
+    stage_id: str
+    stage_number: int
+    name: str
+
+
+class StepInfo(BaseModel):
+    """Step 기본 정보 (current_step, target_step, accepted_step 등)."""
+
+    step_id: str
+    name: str
+
+
+class DecisionHistoryItem(BaseModel):
+    """사용자 의사결정 히스토리 항목."""
+
+    step_id: str
+    name: str
+    status: str
+    stage_number: Optional[int] = None
+
+
+class RequiredStepInfo(BaseModel):
+    """현재 진행 중인 필수 Step 상세 정보."""
+
+    step_id: str
+    name: str
+    is_completed: bool
+    goal: str
+    entry_criteria: str
+    fulfillment_aspects: list[str]
+    fulfillment_threshold: int
+
+
+class RequiredStepStatus(BaseModel):
+    """Stage 내 필수 Step 완료 상태."""
+
+    name: str
+    order: int
+    is_completed: bool
+
+
+class GeneratedStep(BaseModel):
+    """AI가 생성한 일반 Step."""
+
+    name: str
+    description: str
+
+
+class RecommendedMethod(BaseModel):
+    """사이드패널 추천 방법."""
+
+    title: str
+    content: str
+
+
+class CommonMistake(BaseModel):
+    """사이드패널 흔한 실수."""
+
+    mistake: str
+    bad_example: str
+    good_example: str
+
+
+class RetrievedChunk(BaseModel):
+    """KB에서 검색된 청크."""
+
+    text: str
+    relevance_score: float

ai/schemas/generate.py

@@ -1 +1,41 @@
-# ai/schemas/generate.py — GenerateInput, GenerateOutput (Phase 1에서 구현)
+"""generate 시나리오 입출력 스키마 — AI Dataset Spec v3 기반.
+
+Step 동적 생성: 일반 Step 3개를 생성하여 반환.
+"""
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, field_validator
+
+from ai.schemas.common import (
+    DecisionHistoryItem,
+    GeneratedStep,
+    ProjectInfo,
+    RequiredStepInfo,
+    StageInfo,
+    StepInfo,
+)
+
+
+class GenerateInput(BaseModel):
+    """generate 시나리오 입력."""
+
+    project_info: ProjectInfo
+    current_stage: StageInfo
+    decision_history: list[DecisionHistoryItem]
+    current_step: StepInfo
+    current_required_step: Optional[RequiredStepInfo] = None
+    rag_context: Optional[dict[str, Any]] = None
+
+
+class GenerateOutput(BaseModel):
+    """generate 시나리오 출력 — 정확히 3개의 GeneratedStep."""
+
+    generated_steps: list[GeneratedStep]
+
+    @field_validator("generated_steps")
+    @classmethod
+    def exactly_three(cls, v: list[GeneratedStep]) -> list[GeneratedStep]:
+        if len(v) != 3:
+            raise ValueError("generated_steps must contain exactly 3 items")
+        return v

ai/schemas/side_panel.py

@@ -1 +1,39 @@
-# ai/schemas/side_panel.py — SidePanelInput, SidePanelOutput (Phase 1에서 구현)
+"""side_panel 시나리오 입출력 스키마 — AI Dataset Spec v3.1 기반.
+
+일반 Step 사이드패널 콘텐츠 동적 생성:
+description + recommended_methods + common_mistakes + one_line_tip.
+"""
+
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+from ai.schemas.common import (
+    CommonMistake,
+    DecisionHistoryItem,
+    ProjectInfo,
+    RecommendedMethod,
+    RequiredStepInfo,
+    StageInfo,
+    StepInfo,
+)
+
+
+class SidePanelInput(BaseModel):
+    """side_panel 시나리오 입력."""
+
+    project_info: ProjectInfo
+    current_stage: StageInfo
+    target_step: StepInfo
+    decision_history: list[DecisionHistoryItem]
+    current_required_step: Optional[RequiredStepInfo] = None
+    rag_context: Optional[dict[str, Any]] = None
+
+
+class SidePanelOutput(BaseModel):
+    """side_panel 시나리오 출력 — 일반 Step용."""
+
+    description: str
+    recommended_methods: list[RecommendedMethod]
+    common_mistakes: list[CommonMistake]
+    one_line_tip: str