Adapter API

概述

Adapter 層是 PETsARD 架構中的關鍵組件，負責將各個模組包裝成統一的執行介面，供 Executor 調用。每個 Adapter 為其對應的模組提供標準化的生命週期方法和資料流管理。

Adapter 整體架構

classDiagram

    class BaseAdapter {
        <<抽象類別>>
        +config: dict
        +name: str
        +run()
    }

    class LoaderAdapter {
        +loader: Loader
        +benchmarker: Benchmarker
        +run() tuple[DataFrame, Schema]
    }

    class MetadaterAdapter {
        +metadater: SchemaMetadater
        +run() Schema
    }

    class DperAdapter {
        +dper: Dper
        +run() DataFrame
    }

    class SynthesizerAdapter {
        +synthesizer: Synthesizer
        +run() DataFrame
    }

    class EvaluatorAdapter {
        +evaluator: Evaluator
        +run() dict
    }

    class VisualizerAdapter {
        +visualizer: Visualizer
        +run() None
    }

    class DatalabAdapter {
        +datalab: Datalab
        +run() dict
    }

    BaseAdapter <|-- LoaderAdapter
    BaseAdapter <|-- MetadaterAdapter
    BaseAdapter <|-- DperAdapter
    BaseAdapter <|-- SynthesizerAdapter
    BaseAdapter <|-- EvaluatorAdapter
    BaseAdapter <|-- VisualizerAdapter
    BaseAdapter <|-- DatalabAdapter

    %% 樣式定義
    style BaseAdapter fill:#F0F0F0
    style LoaderAdapter fill:#E6E6FA
    style MetadaterAdapter fill:#E6E6FA
    style DperAdapter fill:#E6E6FA
    style SynthesizerAdapter fill:#E6E6FA
    style EvaluatorAdapter fill:#E6E6FA
    style VisualizerAdapter fill:#E6E6FA
    style DatalabAdapter fill:#E6E6FA

圖例說明：
灰色框：抽象基底類別
淺紫框：具體 Adapter 實作類別
<|--：繼承關係 (inheritance)

架構

所有 Adapter 類別都繼承自 BaseAdapter，並實作以下核心介面：

核心方法

__init__(config: dict) - 使用配置初始化 adapter
run(input: dict) - 執行模組功能並計時
set_input(status) - 從 Status 物件準備輸入資料
get_result() - 取得執行結果
get_metadata() - 取得詮釋資料（Schema）（如適用）

工具方法

BaseAdapter 提供多個工具方法用於常見操作：

_apply_precision_rounding() - 根據 schema 對數值欄位套用精度四捨五入
_update_schema_stats() - 重新計算統計資訊並更新 schema
_handle_benchmark_download() - 處理 benchmark:// 協議下載
_resolve_data_source() - 統一的資料來源解析，支援 “Module.key” 格式
_get_metadata_with_priority() - 按優先順序取得 metadata
_safe_copy() - 根據資料類型的統一拷貝策略

Adapter 類別

Adapter	對應模組	主要特色
`LoaderAdapter`	`Loader`	資料載入，支援 benchmark:// 協議
`SplitterAdapter`	`Splitter`	資料分割，支援 custom_data 方法
`PreprocessorAdapter`	`Processor`	前處理，支援全域離群值配置展開
`SynthesizerAdapter`	`Synthesizer`	資料合成，支援 custom_data 方法
`PostprocessorAdapter`	`Processor`	後處理，支援資料型別復原
`ConstrainerAdapter`	`Constrainer`	約束應用，支援 resample/validate 模式
`EvaluatorAdapter`	`Evaluator`	評估，支援自動資料型別對齊
`DescriberAdapter`	`Describer`	描述統計，支援 describe/compare 模式
`ReporterAdapter`	`Reporter`	報告產生，支援計時和驗證結果

基本使用模式

from petsard.adapter import LoaderAdapter

# 創建 adapter
adapter = LoaderAdapter(config)

# 從 Status 設定輸入
input_data = adapter.set_input(status)

# 執行並計時
adapter.run(input_data)

# 取得結果
result = adapter.get_result()
metadata = adapter.get_metadata()  # 如適用

錯誤處理

所有 Adapter 都使用裝飾器模式處理錯誤：

@log_and_raise_config_error - 配置錯誤處理，包含詳細日誌記錄
@log_and_raise_not_implemented - 未實作方法處理

資料流

Adapter 透過 Status 物件管理模組間的資料流：

輸入階段：set_input() 透過 Status 從前置模組取得資料
執行階段：run() 執行包裝的模組並計時
輸出階段：get_result() 和 get_metadata() 將結果提供給 Status

注意事項

Adapter 層是內部架構 - 不建議直接使用
優先使用 YAML 配置檔搭配 Executor
所有資料修改都遵守 Schema 的精度和統計設定
Benchmark 下載透過 benchmark:// 協議自動處理
各 Adapter 的詳細配置選項請參考個別頁面