app/schemas/skill_gap_analysis_schema.py

from pydantic import BaseModel, Field
from typing import List, Optional, Literal

class SkillGap(BaseModel):
    skill_name: str = Field(
        ..., 
        description="The specific  tool missing or requiring an upgrade (e.g., 'Docker')"
    )
    
    gap_type: Literal["missing_foundation", "needs_advanced_upgrade"] = Field(
        ...,
        description=(
            "missing_foundation: Candidate has no recorded experience in this core requirement. "
            "needs_advanced_upgrade: Candidate knows the basics but needs role-specific advanced training."
        )
    )
    
    priority: Literal["high", "medium", "low"] = Field(
        ...,
        description="How critical this skill is for the target job role."
    )
    
    reasoning: str = Field(
        ...,
        description=(
            "Explain exactly WHY this gap was flagged based on the resume vs JD comparison. "
            "Example: 'JD requires FastAPI; candidate has Python experience but no record of using FastAPI framework.'"
        )
    )
    
    target_competency: str = Field(
        ...,
        description="The specific outcome the candidate needs to reach (e.g., 'Build asynchronous database endpoints')"
    )

class SkillGapAnalysis(BaseModel):
    job_title: str = Field(..., description="The target role from the JD")
    candidate_name: Optional[str] = Field(None, description="Extracted name from resume")
    
    analyzed_gaps: List[SkillGap] = Field(
        default_factory=list,
        description="List of specific technical gaps found between Resume and JD"
    )
    
    is_fresher_adaptation_needed: bool = Field(
        default=False,
        description="True if foundational corporate/soft-skill modules should be added to the path."
    )
    
    executive_summary: str = Field(
        ...,
        description="A 2-3 sentence overview of the candidate's readiness and the primary focus of the onboarding."
    )