tokmor 1.2.9__py3-none-any.whl

tokmor/morphology/advanced_base.py

@@ -0,0 +1,472 @@
+"""
+Advanced Morphological Analyzer Base
+=====================================
+
+5가지 고급 기능을 지원하는 형태소 분석기 베이스 클래스
+
+Features:
+1. NER Gazetteer Integration - 개체명 경계 보존
+2. Real-time Dictionary Extension - 런타임 사전 확장
+3. Domain Adaptation - 도메인별 분석 최적화
+4. Code-switching - 다국어 혼용 텍스트 처리
+5. N-best Analysis - 다중 후보 + 신뢰도 점수
+"""
+
+import re
+from abc import ABC, abstractmethod
+from typing import List, Dict, Tuple, Optional, Set, Any
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class Domain(Enum):
+    """분석 도메인"""
+    GENERAL = "general"
+    TECH = "tech"
+    FOOD = "food"
+    SPORTS = "sports"
+    MEDICAL = "medical"
+    LEGAL = "legal"
+    FINANCE = "finance"
+    ENTERTAINMENT = "entertainment"
+    NEWS = "news"
+    SNS = "sns"
+
+
+@dataclass
+class Morpheme:
+    """형태소"""
+    surface: str           # 표층형
+    lemma: str             # 기본형
+    pos: str               # 품사
+    start: int             # 시작 위치
+    end: int               # 끝 위치
+    score: float = 1.0     # 신뢰도 점수
+    features: Dict[str, Any] = field(default_factory=dict)
+
+    def __repr__(self):
+        return f"{self.surface}/{self.pos}"
+
+
+@dataclass
+class AnalysisResult:
+    """분석 결과"""
+    morphemes: List[Morpheme]
+    score: float = 1.0
+    domain: Domain = Domain.GENERAL
+    detected_languages: Set[str] = field(default_factory=set)
+
+    def __repr__(self):
+        return " + ".join(str(m) for m in self.morphemes)
+
+
+@dataclass
+class NBestResult:
+    """N-best 분석 결과"""
+    results: List[AnalysisResult]
+
+    @property
+    def best(self) -> AnalysisResult:
+        return self.results[0] if self.results else AnalysisResult([])
+
+    def __iter__(self):
+        return iter(self.results)
+
+
+class AdvancedMorphologicalAnalyzer(ABC):
+    """
+    고급 형태소 분석기 베이스 클래스
+
+    모든 언어별 분석기가 상속받아 구현
+    """
+
+    # 서브클래스에서 오버라이드
+    LANG_CODE: str = ""
+    LANG_NAME: str = ""
+
+    def __init__(self):
+        # 기본 사전
+        self._dictionary: Dict[str, Tuple[str, str]] = {}  # word -> (lemma, pos)
+
+        # 런타임 추가 사전
+        self._user_dictionary: Dict[str, Tuple[str, str, Optional[str]]] = {}  # word -> (lemma, pos, domain)
+
+        # 개체명 가제티어 (외부 연동)
+        self._gazetteer: Set[str] = set()
+        self._gazetteer_entities: Dict[str, str] = {}  # entity -> type (PER, ORG, LOC, etc.)
+
+        # 도메인별 사전
+        self._domain_dictionaries: Dict[Domain, Dict[str, Tuple[str, str]]] = {
+            domain: {} for domain in Domain
+        }
+
+        # 초기화
+        self._build_base_dictionary()
+        self._build_domain_dictionaries()
+
+    @abstractmethod
+    def _build_base_dictionary(self):
+        """기본 사전 구축 - 서브클래스 구현"""
+        pass
+
+    def _build_domain_dictionaries(self):
+        """도메인 사전 구축 - 서브클래스에서 오버라이드 가능"""
+        pass
+
+    # =========================================================================
+    # Feature 1: NER Gazetteer Integration
+    # =========================================================================
+
+    def load_gazetteer(self, gazetteer: Set[str], entity_types: Optional[Dict[str, str]] = None):
+        """
+        개체명 가제티어 로드
+
+        Args:
+            gazetteer: 개체명 집합
+            entity_types: 개체명 -> 타입 매핑 (PER, ORG, LOC 등)
+        """
+        self._gazetteer = gazetteer
+        if entity_types:
+            self._gazetteer_entities = entity_types
+
+    def add_entity(self, entity: str, entity_type: str = "NNP"):
+        """단일 개체명 추가"""
+        self._gazetteer.add(entity)
+        self._gazetteer_entities[entity] = entity_type
+
+    def _find_entities_in_text(self, text: str) -> List[Tuple[int, int, str, str]]:
+        """
+        텍스트에서 개체명 위치 찾기
+
+        Returns:
+            List of (start, end, entity, entity_type)
+        """
+        entities = []
+
+        # 긴 개체명부터 매칭 (greedy)
+        sorted_gazetteer = sorted(self._gazetteer, key=len, reverse=True)
+
+        used_positions = set()
+
+        for entity in sorted_gazetteer:
+            start = 0
+            while True:
+                idx = text.find(entity, start)
+                if idx == -1:
+                    break
+
+                # 이미 사용된 위치인지 확인
+                positions = set(range(idx, idx + len(entity)))
+                if not positions & used_positions:
+                    entity_type = self._gazetteer_entities.get(entity, "NNP")
+                    entities.append((idx, idx + len(entity), entity, entity_type))
+                    used_positions |= positions
+
+                start = idx + 1
+
+        # 위치순 정렬
+        entities.sort(key=lambda x: x[0])
+        return entities
+
+    # =========================================================================
+    # Feature 2: Real-time Dictionary Extension
+    # =========================================================================
+
+    def add_word(self, word: str, pos: str, lemma: Optional[str] = None,
+                 domain: Optional[str] = None):
+        """
+        런타임 사전 확장
+
+        Args:
+            word: 단어
+            pos: 품사
+            lemma: 기본형 (생략시 word와 동일)
+            domain: 도메인 (생략시 전체 도메인)
+        """
+        lemma = lemma or word
+        self._user_dictionary[word] = (lemma, pos, domain)
+
+        # 도메인 사전에도 추가
+        if domain:
+            try:
+                dom = Domain(domain)
+                self._domain_dictionaries[dom][word] = (lemma, pos)
+            except ValueError:
+                pass
+
+    def add_words(self, words: List[Dict[str, str]]):
+        """
+        복수 단어 추가
+
+        Args:
+            words: [{"word": "뉴진스", "pos": "NNP", "domain": "entertainment"}, ...]
+        """
+        for w in words:
+            self.add_word(
+                word=w["word"],
+                pos=w["pos"],
+                lemma=w.get("lemma"),
+                domain=w.get("domain")
+            )
+
+    def remove_word(self, word: str):
+        """사전에서 단어 제거"""
+        self._user_dictionary.pop(word, None)
+        for dom_dict in self._domain_dictionaries.values():
+            dom_dict.pop(word, None)
+
+    # =========================================================================
+    # Feature 3: Domain Adaptation
+    # =========================================================================
+
+    def set_domain_words(self, domain: Domain, words: Dict[str, Tuple[str, str]]):
+        """
+        도메인 사전 설정
+
+        Args:
+            domain: 도메인
+            words: {word: (lemma, pos), ...}
+        """
+        self._domain_dictionaries[domain] = words
+
+    def _get_domain_sense(self, word: str, domain: Domain) -> Optional[Tuple[str, str]]:
+        """도메인별 단어 의미 조회"""
+        if domain in self._domain_dictionaries:
+            return self._domain_dictionaries[domain].get(word)
+        return None
+
+    # =========================================================================
+    # Feature 4: Code-switching Detection
+    # =========================================================================
+
+    # 언어별 문자 패턴 (Unicode ranges)
+    SCRIPT_PATTERNS = {
+        'ko': re.compile(r'[\uac00-\ud7af\u1100-\u11ff\u3130-\u318f]+'),  # 한글
+        'ja': re.compile(r'[\u3040-\u309f\u30a0-\u30ff]+'),  # 히라가나/가타카나
+        'zh': re.compile(r'[\u4e00-\u9fff]+'),  # 한자
+        'ar': re.compile(r'[\u0600-\u06ff\u0750-\u077f]+'),  # 아랍어
+        'hi': re.compile(r'[\u0900-\u097f]+'),  # 데바나가리
+        'ru': re.compile(r'[\u0400-\u04ff]+'),  # 키릴
+        'th': re.compile(r'[\u0e00-\u0e7f]+'),  # 태국어
+        'he': re.compile(r'[\u0590-\u05ff]+'),  # 히브리어
+        'latin': re.compile(r'[a-zA-ZÀ-ÿ]+'),  # 라틴 문자
+    }
+
+    def detect_languages(self, text: str) -> Set[str]:
+        """
+        텍스트에서 사용된 언어(스크립트) 감지
+
+        Returns:
+            감지된 언어 코드 집합
+        """
+        detected = set()
+
+        for lang, pattern in self.SCRIPT_PATTERNS.items():
+            if pattern.search(text):
+                detected.add(lang)
+
+        return detected
+
+    def _split_by_language(self, text: str) -> List[Tuple[str, str, int, int]]:
+        """
+        텍스트를 언어별로 분리
+
+        Returns:
+            List of (segment, language, start, end)
+        """
+        segments = []
+
+        # 모든 패턴으로 매칭
+        all_matches = []
+        for lang, pattern in self.SCRIPT_PATTERNS.items():
+            for match in pattern.finditer(text):
+                all_matches.append((match.start(), match.end(), match.group(), lang))
+
+        # 숫자/기호
+        for match in re.finditer(r'[0-9]+', text):
+            all_matches.append((match.start(), match.end(), match.group(), 'num'))
+
+        # 위치순 정렬
+        all_matches.sort(key=lambda x: x[0])
+
+        # 겹치지 않는 세그먼트 선택
+        used = set()
+        for start, end, segment, lang in all_matches:
+            positions = set(range(start, end))
+            if not positions & used:
+                segments.append((segment, lang, start, end))
+                used |= positions
+
+        segments.sort(key=lambda x: x[2])
+        return segments
+
+    # =========================================================================
+    # Feature 5: N-best Analysis
+    # =========================================================================
+
+    @abstractmethod
+    def _generate_candidates(self, text: str, domain: Domain) -> List[AnalysisResult]:
+        """
+        분석 후보 생성 - 서브클래스 구현
+
+        Returns:
+            점수순 정렬된 분석 결과 리스트
+        """
+        pass
+
+    def _score_analysis(self, result: AnalysisResult) -> float:
+        """
+        분석 결과 점수 계산
+
+        기본 휴리스틱:
+        - 형태소 수가 적을수록 좋음
+        - 알려진 단어가 많을수록 좋음
+        - 도메인 일치 보너스
+        """
+        if not result.morphemes:
+            return 0.0
+
+        # 기본 점수
+        score = 1.0
+
+        # 형태소 수 패널티 (적을수록 좋음)
+        score -= len(result.morphemes) * 0.01
+
+        # 알려진 단어 보너스
+        known_count = sum(
+            1 for m in result.morphemes
+            if m.surface in self._dictionary or m.surface in self._user_dictionary
+        )
+        score += known_count * 0.05
+
+        return max(0.0, min(1.0, score))
+
+    # =========================================================================
+    # Main Analysis Methods
+    # =========================================================================
+
+    def analyze(self, text: str,
+                preserve_entities: bool = True,
+                domain: Optional[str] = None,
+                n_best: int = 1) -> NBestResult:
+        """
+        형태소 분석 (고급 기능 통합)
+
+        Args:
+            text: 입력 텍스트
+            preserve_entities: 개체명 경계 보존 여부
+            domain: 분석 도메인
+            n_best: 반환할 후보 수
+
+        Returns:
+            NBestResult: n-best 분석 결과
+        """
+        if not text or not text.strip():
+            return NBestResult([AnalysisResult([])])
+
+        # 도메인 결정
+        dom = Domain(domain) if domain else Domain.GENERAL
+
+        # 언어 감지 (code-switching)
+        detected_langs = self.detect_languages(text)
+
+        # 개체명 위치 찾기
+        entity_spans = []
+        if preserve_entities and self._gazetteer:
+            entity_spans = self._find_entities_in_text(text)
+
+        # 텍스트 분할 (개체명 보존)
+        segments = self._segment_text(text, entity_spans)
+
+        # 세그먼트별 분석
+        all_morphemes = []
+        for seg_text, seg_start, is_entity, entity_type in segments:
+            if is_entity:
+                # 개체명은 그대로 유지
+                all_morphemes.append(Morpheme(
+                    surface=seg_text,
+                    lemma=seg_text,
+                    pos=entity_type,
+                    start=seg_start,
+                    end=seg_start + len(seg_text),
+                    score=1.0,
+                    features={"is_entity": True}
+                ))
+            else:
+                # 일반 텍스트 분석
+                segment_results = self._generate_candidates(seg_text, dom)
+                if segment_results:
+                    # 오프셋 조정
+                    for m in segment_results[0].morphemes:
+                        m.start += seg_start
+                        m.end += seg_start
+                    all_morphemes.extend(segment_results[0].morphemes)
+
+        # 최종 결과
+        main_result = AnalysisResult(
+            morphemes=all_morphemes,
+            score=self._score_analysis(AnalysisResult(all_morphemes)),
+            domain=dom,
+            detected_languages=detected_langs
+        )
+
+        # N-best 생성 (현재는 단일 결과)
+        results = [main_result]
+
+        # 추가 후보 생성 (n_best > 1인 경우)
+        if n_best > 1:
+            additional = self._generate_alternatives(text, dom, n_best - 1)
+            results.extend(additional)
+
+        return NBestResult(results[:n_best])
+
+    def _segment_text(self, text: str, entity_spans: List[Tuple[int, int, str, str]]) -> List[Tuple[str, int, bool, str]]:
+        """
+        텍스트를 개체명 기준으로 분할
+
+        Returns:
+            List of (segment_text, start_offset, is_entity, entity_type)
+        """
+        if not entity_spans:
+            return [(text, 0, False, "")]
+
+        segments = []
+        prev_end = 0
+
+        for start, end, entity, entity_type in entity_spans:
+            # 개체명 이전 텍스트
+            if start > prev_end:
+                segments.append((text[prev_end:start], prev_end, False, ""))
+
+            # 개체명
+            segments.append((entity, start, True, entity_type))
+            prev_end = end
+
+        # 마지막 개체명 이후 텍스트
+        if prev_end < len(text):
+            segments.append((text[prev_end:], prev_end, False, ""))
+
+        return segments
+
+    def _generate_alternatives(self, text: str, domain: Domain, count: int) -> List[AnalysisResult]:
+        """대안 분석 결과 생성 - 서브클래스에서 오버라이드 가능"""
+        return []
+
+    # =========================================================================
+    # Convenience Methods
+    # =========================================================================
+
+    def tokenize(self, text: str) -> List[str]:
+        """간편 토크나이징"""
+        result = self.analyze(text, preserve_entities=False, n_best=1)
+        return [m.surface for m in result.best.morphemes]
+
+    def pos_tag(self, text: str) -> List[Tuple[str, str]]:
+        """품사 태깅"""
+        result = self.analyze(text, preserve_entities=False, n_best=1)
+        return [(m.surface, m.pos) for m in result.best.morphemes]
+
+    def lemmatize(self, text: str) -> List[str]:
+        """기본형 추출"""
+        result = self.analyze(text, preserve_entities=False, n_best=1)
+        return [m.lemma for m in result.best.morphemes]