기술적 문서화

# EU AI Act 부속서 IV 기반 기술 문서 생성기
from dataclasses import dataclass, field
from typing import List, Dict, Optional
from datetime import datetime
import json

@dataclass
class GeneralDescription:
    """1. 일반 정보 (Annex IV, Section 1)"""
    system_name: str
    version: str
    provider_name: str
    provider_address: str
    provider_contact: str
    authorized_representative: Optional[str] = None
    trade_names: List[str] = field(default_factory=list)

@dataclass
class IntendedPurpose:
    """2. 의도된 용도 (Annex IV, Section 2)"""
    intended_purpose: str
    intended_users: List[str]
    deployment_context: str
    geographic_scope: List[str]
    prohibited_uses: List[str] = field(default_factory=list)
    foreseeable_misuse: List[str] = field(default_factory=list)

@dataclass
class RiskManagementDoc:
    """3. 위험관리시스템 (Annex IV, Section 2(b))"""
    risk_management_process: str
    identified_risks: List[Dict]
    mitigation_measures: List[Dict]
    residual_risks: List[Dict]
    testing_procedures: List[str]

@dataclass
class DataGovernanceDoc:
    """4. 데이터 거버넌스 (Annex IV, Section 2(d))"""
    training_data: Dict
    validation_data: Dict
    test_data: Dict
    data_preparation: str
    bias_detection: str
    data_gaps: List[str] = field(default_factory=list)

@dataclass
class SystemArchitecture:
    """5. 시스템 아키텍처 (Annex IV, Section 2(e))"""
    architecture_description: str
    main_components: List[Dict]
    computational_resources: Dict
    model_type: str
    training_methodology: str
    key_design_choices: List[str]

@dataclass
class PerformanceMetrics:
    """6. 성능 지표 (Annex IV, Section 2(f))"""
    accuracy_metrics: Dict
    robustness_metrics: Dict
    fairness_metrics: Dict
    test_results: List[Dict]
    known_limitations: List[str]
    performance_thresholds: Dict

@dataclass
class HumanOversight:
    """7. 인간감독 조치 (Annex IV, Section 2(g))"""
    oversight_measures: List[str]
    interpretability_tools: List[str]
    intervention_mechanisms: List[str]
    user_instructions: str

@dataclass
class TechnicalDocumentation:
    """EU AI Act 부속서 IV 기술 문서"""
    document_id: str
    created_at: datetime = field(default_factory=datetime.now)
    last_updated: datetime = field(default_factory=datetime.now)

    # 부속서 IV 섹션별 내용
    general: Optional[GeneralDescription] = None
    intended_purpose: Optional[IntendedPurpose] = None
    risk_management: Optional[RiskManagementDoc] = None
    data_governance: Optional[DataGovernanceDoc] = None
    architecture: Optional[SystemArchitecture] = None
    performance: Optional[PerformanceMetrics] = None
    human_oversight: Optional[HumanOversight] = None

    # 추가 문서
    model_card: Optional[Dict] = None
    change_log: List[Dict] = field(default_factory=list)

    def validate_completeness(self) -> Dict:
        """문서 완성도 검증"""
        sections = {
            "general_description": self.general is not None,
            "intended_purpose": self.intended_purpose is not None,
            "risk_management": self.risk_management is not None,
            "data_governance": self.data_governance is not None,
            "architecture": self.architecture is not None,
            "performance_metrics": self.performance is not None,
            "human_oversight": self.human_oversight is not None,
        }

        completed = sum(1 for v in sections.values() if v)
        total = len(sections)

        return {
            "document_id": self.document_id,
            "sections": sections,
            "completeness": completed / total * 100,
            "missing_sections": [k for k, v in sections.items() if not v],
            "compliant": completed == total,
            "ce_marking_ready": completed == total
        }

    def generate_model_card(self) -> Dict:
        """모델 카드 생성"""
        if not self.general or not self.performance:
            raise ValueError("일반 정보와 성능 지표 필요")

        return {
            "model_details": {
                "name": self.general.system_name,
                "version": self.general.version,
                "type": self.architecture.model_type if self.architecture else "N/A",
                "developer": self.general.provider_name
            },
            "intended_use": {
                "primary_use": self.intended_purpose.intended_purpose if self.intended_purpose else "N/A",
                "users": self.intended_purpose.intended_users if self.intended_purpose else [],
                "out_of_scope": self.intended_purpose.prohibited_uses if self.intended_purpose else []
            },
            "metrics": self.performance.accuracy_metrics,
            "limitations": self.performance.known_limitations,
            "ethical_considerations": {
                "fairness_evaluation": self.performance.fairness_metrics,
                "bias_mitigation": self.data_governance.bias_detection if self.data_governance else "N/A"
            },
            "generated_at": datetime.now().isoformat()
        }

    def log_change(self, change_type: str, description: str, author: str):
        """변경 이력 기록"""
        self.change_log.append({
            "timestamp": datetime.now().isoformat(),
            "change_type": change_type,
            "description": description,
            "author": author,
            "version_before": self.general.version if self.general else "N/A"
        })
        self.last_updated = datetime.now()

    def export_for_authority(self, format: str = "json") -> str:
        """감독기관 제출용 내보내기"""
        export_data = {
            "document_id": self.document_id,
            "export_date": datetime.now().isoformat(),
            "eu_ai_act_compliance": "Annex IV",
            "sections": {
                "1_general_description": self.general.__dict__ if self.general else None,
                "2_intended_purpose": self.intended_purpose.__dict__ if self.intended_purpose else None,
                "3_risk_management": self.risk_management.__dict__ if self.risk_management else None,
                "4_data_governance": self.data_governance.__dict__ if self.data_governance else None,
                "5_architecture": self.architecture.__dict__ if self.architecture else None,
                "6_performance": self.performance.__dict__ if self.performance else None,
                "7_human_oversight": self.human_oversight.__dict__ if self.human_oversight else None,
            },
            "change_log": self.change_log,
            "retention_period": "10 years from market placement"
        }

        if format == "json":
            return json.dumps(export_data, ensure_ascii=False, indent=2, default=str)
        return export_data

# 사용 예시
doc = TechnicalDocumentation(document_id="TD-2024-001")

# 일반 정보 작성
doc.general = GeneralDescription(
    system_name="AI 신용평가 시스템",
    version="2.0.0",
    provider_name="KAITRUST Corp",
    provider_address="서울특별시 강남구...",
    provider_contact="compliance@kaitrust.ai"
)

# 의도된 용도 작성
doc.intended_purpose = IntendedPurpose(
    intended_purpose="개인 신용도 평가 및 대출 심사 보조",
    intended_users=["금융기관 심사담당자", "대출 상담사"],
    deployment_context="금융기관 내부 시스템",
    geographic_scope=["EU", "대한민국"],
    prohibited_uses=["자동 거절 결정", "취약계층 차별적 사용"],
    foreseeable_misuse=["심사 근거 없이 결과만 사용"]
)

# 성능 지표 작성
doc.performance = PerformanceMetrics(
    accuracy_metrics={"AUC": 0.85, "accuracy": 0.82, "F1": 0.79},
    robustness_metrics={"adversarial_accuracy": 0.78},
    fairness_metrics={"demographic_parity": 0.95, "equalized_odds": 0.92},
    test_results=[{"test_name": "validation_set", "date": "2024-01-15", "passed": True}],
    known_limitations=["신규 고객 예측 정확도 저하", "특정 직업군 데이터 부족"],
    performance_thresholds={"minimum_AUC": 0.80}
)

# 완성도 검증
validation = doc.validate_completeness()
print(f"문서 완성도: {validation['completeness']}%")
print(f"누락 섹션: {validation['missing_sections']}")