__init__.py

"""
医镜 (MediLens) - 基于 GLM-5.1 的中文医疗 NLP 工具包

MediLens 是一个专注于中文医疗领域的自然语言处理工具包，
利用智谱 GLM-5.1 大语言模型提供医疗实体识别、PHI 检测、
文本分类等核心功能。

典型用法::

    from medilens import MediLens

    lens = MediLens(api_key="your-api-key")
    result = lens.analyze("患者三天前出现发热、咳嗽，体温最高38.5℃")
    print(result.entities)
"""

from __future__ import annotations

from importlib.metadata import PackageNotFoundError
from importlib.metadata import version as _version
from typing import Any, Dict, List, Optional

from medilens.config import Settings, settings as default_settings

try:
    __version__ = _version("medilens")
except PackageNotFoundError:  # pragma: no cover
    __version__ = "0.1.0"

__version__ = "0.1.0"
"""MediLens 包版本号"""

__author__ = "MediLens Team"
__license__ = "MIT"

# 公开的模块成员
__all__ = [
    "MediLens",
    "Settings",
    "__version__",
]


class MediLens:
    """MediLens 主入口类，提供一站式医疗 NLP 分析能力。

    封装了分析引擎、实体识别、PHI 检测、文本分类等核心功能，
    通过统一的接口对外暴露。

    Args:
        api_key: GLM API 密钥
        model: 模型名称，默认为 GLM-5.1
        temperature: 生成温度 (0.0 ~ 1.0)
        max_tokens: 最大输出 Token 数
        settings: 自定义配置对象（与前面参数二选一）

    Examples:
        >>> lens = MediLens(api_key="your-key")
        >>> result = lens.analyze("患者发热38.5℃三天")
    """

    def __init__(
        self,
        api_key: Optional[str] = None,
        model: Optional[str] = None,
        temperature: Optional[float] = None,
        max_tokens: Optional[int] = None,
        settings: Optional[Settings] = None,
    ) -> None:
        if settings is not None:
            self._settings = settings
        else:
            self._settings = Settings(
                api_key=api_key or default_settings.api_key,
                model=model or default_settings.model,
                temperature=temperature if temperature is not None else default_settings.temperature,
                max_tokens=max_tokens if max_tokens is not None else default_settings.max_tokens,
            )
        self._settings.validate()

        # 延迟导入以避免循环依赖
        from medilens.core.analyzer import GLMClient
        from medilens.core.classifier import MedicalTextClassifier

        self._client = GLMClient(self._settings)
        self._classifier = MedicalTextClassifier(self._client)

    @property
    def client(self):
        """底层 GLM API 客户端实例。"""
        return self._client

    @property
    def settings(self) -> Settings:
        """当前配置。"""
        return self._settings

    # ---- 一站式分析 ----

    def analyze(self, text: str, **kwargs) -> "EntityExtractionResult":
        """分析医疗文本，提取其中的医疗实体。

        Args:
            text: 输入的中文医疗文本
            **kwargs: 传递给分析引擎的额外参数

        Returns:
            实体提取结果
        """
        from medilens.core.entity import EntityExtractionResult

        result = self._client.extract_entities(text, **kwargs)
        return EntityExtractionResult.from_dict(result) if isinstance(result, dict) else result

    def detect_phi(self, text: str, **kwargs) -> "PHIDetectionResult":
        """检测医疗文本中的受保护健康信息 (PHI)。

        Args:
            text: 输入的中文医疗文本
            **kwargs: 额外参数

        Returns:
            PHI 检测结果
        """
        result = self._client.detect_phi(text, **kwargs)
        return result

    def classify(self, text: str, **kwargs) -> "ClassificationResult":
        """对医疗文本进行分类。

        Args:
            text: 输入的中文医疗文本
            **kwargs: 额外参数

        Returns:
            分类结果
        """
        result = self._classifier.classify(text, **kwargs)
        return result

    def classify_text(self, text: str, **kwargs) -> dict:
        """分类医疗文本（兼容 analyzer 接口）。

        Args:
            text: 输入的中文医疗文本
            **kwargs: 额外参数

        Returns:
            分类结果的字典表示
        """
        result = self.classify(text, **kwargs)
        return result.to_dict()

    # ---- 批量处理 ----

    def batch_analyze(
        self,
        inputs: List[str],
        format: str = "json",
        output_path: Optional[str] = None,
        **kwargs,
    ) -> List[dict]:
        """批量分析医疗文本。

        Args:
            inputs: 文本列表或文件路径
            format: 输出格式 (json/csv)
            output_path: 输出文件路径
            **kwargs: 额外参数

        Returns:
            分析结果列表
        """
        from medilens.core.batch import BatchProcessor

        processor = BatchProcessor(client=self._client)
        return processor.process_texts(inputs, output_format=format, output_path=output_path, **kwargs)

    # ---- 去标识化 ----

    def deidentify(self, text: str, method: str = "MASK", **kwargs) -> str:
        """对医疗文本进行去标识化处理。

        Args:
            text: 输入文本
            method: 去标识方法 (MASK / REPLACE / HASH / REDACT)
            **kwargs: 额外参数

        Returns:
            去标识化后的文本
        """
        result = self._client.detect_phi(text, **kwargs)
        return result.apply(text, method=method)


# 便捷工厂
def create_medilens(**kwargs) -> MediLens:
    """创建 MediLens 实例的便捷函数。

    Args:
        **kwargs: 传给 MediLens 构造函数的参数

    Returns:
        MediLens 实例
    """
    return MediLens(**kwargs)